@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/ir/display-list.d.ts

@@ -1,5 +1,6 @@
-import { Color } from "../common/color";
-import { FontStyle } from "../utils/pdf-object-manager";
+import { Color } from "../common/color.js";
+import { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
 /**
  * Display list - the seam between layout and the PDF backend.
  *
@@ -11,6 +12,16 @@ import { FontStyle } from "../utils/pdf-object-manager";
  * Coordinates are in PDF points (1/72"). Which origin they use is still the
  * producer's concern for now; centralizing the Y-flip at this seam is Phase 3.
  */
+/**
+ * Structure tag for accessible (PDF/UA) tagging. `role` is the PDF structure type the content maps to
+ * (`P`, `H1`..`H6`, `Figure`, `TD`, …); `key` groups the IR nodes of one logical element (e.g. every line
+ * of a paragraph) into a single structure element; `alt` is the alternate text for a figure. A drawable
+ * node WITHOUT a tag is emitted as an Artifact (decoration, skipped by screen readers).
+ */
+export interface StructTag {
+    role: string;
+    key: number;
+}
 /**
  * A single positioned run of text in one font / size / color. Line wrapping has
  * already happened upstream: the producer emits one `TextRun` per laid-out line or
@@ -21,23 +32,43 @@ export interface TextRun {
     x: number;
     y: number;
     text: string;
+    /** The glyphs to draw, when the run was SHAPED. The backend emits these instead of encoding `text`,
+     *  which stays logical for `ToUnicode` and the accessible tree. */
+    glyphs?: number[];
     fontFamily: string;
     fontStyle: FontStyle;
     fontSize: number;
     color: Color;
+    letterSpacing?: number;
+    tag?: StructTag;
 }
 /** An axis-aligned rectangle. An absent `fill` or `stroke` means that part is not drawn. */
+/**
+ * Corner radii in points (CSS `border-radius`). Any corner left out falls back to 0. A single number
+ * everywhere is the common case and stays a plain `number` on the nodes, so nothing changed for a
+ * document that never asks for different corners.
+ */
+export interface Radii {
+    tl?: number;
+    tr?: number;
+    br?: number;
+    bl?: number;
+}
+/** True when any corner asks for a radius - the gate between a plain rect and a curved path. */
+export declare function isRounded(radius: number | Radii | undefined): boolean;
 export interface Rect {
     type: "rect";
     x: number;
     y: number;
     width: number;
     height: number;
-    fill?: Color;
+    /** Solid colour, or a gradient whose anchor points are in absolute page coordinates. */
+    fill?: Color | Gradient;
     stroke?: Color;
     strokeWidth: number;
-    /** Corner radius in points; absent/0 = sharp corners (plain `re`). */
-    radius?: number;
+    /** Corner radius in points - one number for all four, or per corner. Absent/0 = sharp (plain `re`). */
+    radius?: number | Radii;
+    tag?: StructTag;
 }
 /** A straight line segment between two points. */
 export interface Line {
@@ -48,6 +79,7 @@ export interface Line {
     y2: number;
     stroke: Color;
     strokeWidth: number;
+    tag?: StructTag;
 }
 /** A raster image, already resolved to bytes by the producer (no `CustomImage` here). */
 export interface Image {
@@ -60,6 +92,8 @@ export interface Image {
     intrinsicHeight: number;
     data: string;
     imageType: string;
+    /** Flate-compressed DeviceGray alpha channel for a transparent PNG, embedded as the XObject's /SMask. */
+    smask?: string;
     /** cover/contain fits clip the placement to the element's original frame. */
     clip?: {
         x: number;
@@ -67,8 +101,163 @@ export interface Image {
         width: number;
         height: number;
     };
-    /** Corner radius in points for the image box; absent/0 = sharp corners. */
-    radius?: number;
+    /** Corner radius in points for the image box - one number or per corner; absent/0 = sharp. */
+    radius?: number | Radii;
+    tag?: StructTag;
+}
+/**
+ * Pushes a clipping region (a rectangle, rounded when `radius` is set). Everything between this and
+ * the matching `ClipPop` is clipped to it - what a Box with `overflow: "hidden"` wraps its children
+ * in, so a `Positioned` child gets cropped at the box edge instead of spilling over.
+ */
+export interface ClipPush {
+    type: "clip-push";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius?: number | Radii;
+}
+/** Closes the most recent `ClipPush` (restores the graphics state). */
+export interface ClipPop {
+    type: "clip-pop";
+}
+/**
+ * A hyperlink over a rectangle. Unlike every other IR node this draws NOTHING into the content stream -
+ * it becomes a PDF Link ANNOTATION on the page (`/Annots`), a side channel next to the drawing. Exactly
+ * one target is set: `href` is an external URL (a `/URI` action); `dest` is a named destination inside
+ * this document (a `/GoTo` action, resolved via the catalog `/Names /Dests` tree - see `Anchor`). The
+ * rect is the clickable region in top-left engine coords; the Y-flip converts it to PDF page space.
+ *
+ * NOTE: a Link inside a `TransformPush` is NOT yet rotated with it - the annotation rect lives in page
+ * space and ignores the content-stream matrix. Completing that is a planned follow-up (see todo.md).
+ */
+export interface Link {
+    type: "link";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    href?: string;
+    dest?: string;
+}
+/**
+ * A named destination anchor - a jump TARGET for an internal `Link({ to })`. Like `Link` it draws
+ * NOTHING; it registers `name` -> (this page, `y`) in the catalog `/Names /Dests` name tree. `y` is the
+ * top of the target in top-left engine coords (the Y-flip turns it into the page-space scroll target).
+ */
+export interface Anchor {
+    type: "anchor";
+    y: number;
+    name: string;
+}
+/**
+ * A document-outline (bookmark) anchor. Like `Link` it draws NOTHING - it becomes an entry in the PDF
+ * outline tree (`/Outlines`), a side channel the viewer shows in its bookmark panel. `y` is the top of
+ * the target in top-left engine coords (the Y-flip turns it into the page-space scroll target); `level`
+ * (1-based) nests the entry under the nearest preceding entry of a smaller level.
+ */
+export interface Outline {
+    type: "outline";
+    y: number;
+    title: string;
+    level: number;
+}
+/**
+ * An interactive form field (AcroForm). Like `Link` it draws NOTHING into the content stream - it becomes
+ * a Widget ANNOTATION on the page (`/Annots`) and a field in the catalog `/AcroForm`, both built from the
+ * shared `FormFieldSpec`. The rect is the field box in top-left engine coords; the Y-flip converts it to
+ * page space. See `forms/acroform.ts` for the widget/field assembly.
+ */
+export interface FormFieldNode {
+    type: "formfield";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    field: FormFieldSpec;
+    style: FieldStyle;
+}
+/**
+ * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the
+ * matching `TransformPop` is painted through `matrix`. This is what `Rotated` wraps its child's nodes
+ * in, so a subtree draws rotated (or scaled/translated) around a pivot without touching its layout.
+ *
+ * `matrix` is `[a, b, c, d, e, f]` in the engine's TOP-LEFT coordinates - the same space every other IR
+ * node uses. The Y-flip at the IR -> backend seam converts it to PDF's bottom-left once per page, so
+ * producers stay coordinate-system-blind (they never see a flipped matrix).
+ */
+export interface TransformPush {
+    type: "transform-push";
+    matrix: [number, number, number, number, number, number];
+}
+/** Closes the most recent `TransformPush` (restores the graphics state). */
+export interface TransformPop {
+    type: "transform-pop";
+}
+/**
+ * One drawing command of a `Path`, in absolute page coordinates. Curves are CUBIC because PDF
+ * content streams have no quadratic operator - a producer converts TrueType quads to cubics before
+ * emitting. `z` closes the current subpath (a glyph contour).
+ */
+export type PathCommand = {
+    op: "m";
+    x: number;
+    y: number;
+} | {
+    op: "l";
+    x: number;
+    y: number;
+} | {
+    op: "c";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    op: "z";
+};
+/** One color stop of a gradient: a position 0..1 along the axis and its color. */
+export interface GradientStop {
+    offset: number;
+    color: Color;
+}
+/** An axial (linear) gradient between two points, in absolute page coordinates. */
+export interface LinearGradient {
+    type: "linear";
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    stops: GradientStop[];
+    extend: "pad" | "repeat" | "reflect";
+}
+/** A radial gradient between two circles, in absolute page coordinates. */
+export interface RadialGradient {
+    type: "radial";
+    x0: number;
+    y0: number;
+    r0: number;
+    x1: number;
+    y1: number;
+    r1: number;
+    stops: GradientStop[];
+    extend: "pad" | "repeat" | "reflect";
+}
+export type Gradient = LinearGradient | RadialGradient;
+/**
+ * A filled vector path - one or more closed subpaths sharing a single fill, using the nonzero
+ * winding rule (so a glyph's inner contour cuts a hole). This is what a color glyph's layers draw
+ * onto: each COLR layer is one `Path` filled with a solid `Color` (v0) or a `Gradient` (v1).
+ */
+export interface Path {
+    type: "path";
+    commands: PathCommand[];
+    fill: Color | Gradient;
+    /** Accessibility structure tag (absent = drawn as an artifact); color-emoji layers stay untagged. */
+    tag?: StructTag;
 }
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | FormFieldNode | TransformPush | TransformPop;

package/dist/ir/display-list.js

@@ -1,2 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+/** True when any corner asks for a radius - the gate between a plain rect and a curved path. */
+export function isRounded(radius) {
+    if (radius === undefined)
+        return false;
+    if (typeof radius === "number")
+        return radius > 0;
+    return ((radius.tl ?? 0) > 0 || (radius.tr ?? 0) > 0 || (radius.br ?? 0) > 0 || (radius.bl ?? 0) > 0);
+}

package/dist/layout/alignment.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Flex alignment vocabulary. It lives here rather than in `utils/flex-layout.ts` because the base
+ * `PDFElement` needs `CrossAlign` for `alignSelf`, and flex-layout imports the elements - defining it
+ * there would close a cycle.
+ */
+/** Distribution along the MAIN axis (CSS `justify-content`). */
+export type MainAlign = "start" | "center" | "end" | "between" | "around";
+/** Position/size ACROSS the axis (CSS `align-items` / `align-self`). `stretch` fills the cross extent;
+ *  the others place the child at its natural cross size. */
+export type CrossAlign = "start" | "center" | "end" | "stretch";

package/dist/layout/alignment.js

@@ -0,0 +1,6 @@
+/**
+ * Flex alignment vocabulary. It lives here rather than in `utils/flex-layout.ts` because the base
+ * `PDFElement` needs `CrossAlign` for `alignSelf`, and flex-layout imports the elements - defining it
+ * there would close a cycle.
+ */
+export {};

package/dist/layout/box-constraints.d.ts

@@ -41,9 +41,70 @@ export declare class BoxConstraints {
      * what a padding/border element hands its child after reserving its own insets.
      */
     deflate(horizontal: number, vertical: number): BoxConstraints;
+    /**
+     * Tightens this box by an element's own `min`/`max` on either axis. A max never widens the offered
+     * room, and a min may push past it - `minHeight: 500` in a 300pt region means 500, and pagination
+     * deals with the overflow, the same answer CSS gives.
+     */
+    narrow(minWidth?: number, maxWidth?: number, minHeight?: number, maxHeight?: number): BoxConstraints;
     /** Returns the constraints clamped to lie within `parent` (Flutter's enforce). */
     enforce(parent: BoxConstraints): BoxConstraints;
 }
+/**
+ * Resolves a sized element's extent on one axis (relative sizing). An explicit point size (`fixed`)
+ * always wins; otherwise a `factor` (0..1) of the offered extent, but ONLY when that axis is bounded -
+ * a fraction of an unbounded axis has no meaning (Flutter's FractionallySizedBox under unbounded
+ * constraints). Returns `undefined` to mean "no explicit extent", i.e. fill the box or shrink-wrap.
+ * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
+ */
+export declare function resolveExtent(fixed: number | undefined, factor: number | undefined, boundedMax: number, hasBounded: boolean): number | undefined;
+/** What one axis of a sized element was asked for: a size, plus the bounds it must stay inside. */
+export interface ExtentSpec {
+    fixed?: number;
+    factor?: number;
+    min?: number;
+    minFactor?: number;
+    max?: number;
+    maxFactor?: number;
+}
+/** The sizing options every sized element accepts. Each `*Factor` is the percentage form of its pair. */
+export interface SizingParams {
+    width?: number;
+    height?: number;
+    widthFactor?: number;
+    heightFactor?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height. Derives whichever axis is left open; see `resolveSize`. */
+    aspectRatio?: number;
+}
+/** Split `SizingParams` into the per-axis form `resolveSize` takes. */
+export declare function extentSpecs(p: SizingParams): {
+    width: ExtentSpec;
+    height: ExtentSpec;
+};
+/**
+ * Resolve both axes of a sized element: relative sizing, then `aspectRatio`, then `min`/`max`.
+ *
+ * The order follows CSS: a ratio fills in the axis you left open, and min/max clamp afterwards - so an
+ * explicit bound wins over the ratio, exactly as `min-height` beats `aspect-ratio` in a browser.
+ *
+ * `min`/`max` also come back as NARROWED constraints, because an axis with no explicit size still has
+ * to obey them. `maxWidth` alone means "fill, but no wider than this", and the caller's own fill and
+ * shrink-wrap paths get that for free by using the returned constraints instead of the ones passed in.
+ * A `width` of `undefined` keeps its usual meaning: fill or shrink-wrap.
+ */
+export declare function resolveSize(width: ExtentSpec, height: ExtentSpec, aspectRatio: number | undefined, constraints: BoxConstraints): {
+    width?: number;
+    height?: number;
+    constraints: BoxConstraints;
+};
 /** The size an element resolves to and returns UP the tree. */
 export interface Size {
     width: number;

package/dist/layout/box-constraints.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BoxConstraints = void 0;
 /**
  * The size constraints handed DOWN the tree during layout (Flutter's BoxConstraints
  * model). Pure geometry: a min/max range per axis, no position. An element receives a
@@ -15,7 +12,7 @@ exports.BoxConstraints = void 0;
  * remaining vertical space becomes a `maxHeight`, and "does this fit?" is a constraint
  * check, not a special case.
  */
-class BoxConstraints {
+export class BoxConstraints {
     constructor(minWidth = 0, maxWidth = Infinity, minHeight = 0, maxHeight = Infinity) {
         this.minWidth = minWidth;
         this.maxWidth = maxWidth;
@@ -28,7 +25,7 @@ class BoxConstraints {
     }
     /** Tight only on the axes given; the others stay unbounded (0..Infinity). */
     static tightFor({ width, height }) {
-        return new BoxConstraints(width !== null && width !== void 0 ? width : 0, width !== null && width !== void 0 ? width : Infinity, height !== null && height !== void 0 ? height : 0, height !== null && height !== void 0 ? height : Infinity);
+        return new BoxConstraints(width ?? 0, width ?? Infinity, height ?? 0, height ?? Infinity);
     }
     /** Caps each axis at `max` but allows anything down to zero (shrink-wrap). */
     static loose(maxWidth, maxHeight) {
@@ -65,9 +62,94 @@ class BoxConstraints {
     deflate(horizontal, vertical) {
         return new BoxConstraints(Math.max(0, this.minWidth - horizontal), Math.max(0, this.maxWidth - horizontal), Math.max(0, this.minHeight - vertical), Math.max(0, this.maxHeight - vertical));
     }
+    /**
+     * Tightens this box by an element's own `min`/`max` on either axis. A max never widens the offered
+     * room, and a min may push past it - `minHeight: 500` in a 300pt region means 500, and pagination
+     * deals with the overflow, the same answer CSS gives.
+     */
+    narrow(minWidth, maxWidth, minHeight, maxHeight) {
+        const lo = (own, current) => Math.max(current, own ?? 0);
+        const hi = (own, current) => own === undefined ? current : Math.min(current, own);
+        return new BoxConstraints(lo(minWidth, this.minWidth), Math.max(hi(maxWidth, this.maxWidth), lo(minWidth, this.minWidth)), lo(minHeight, this.minHeight), Math.max(hi(maxHeight, this.maxHeight), lo(minHeight, this.minHeight)));
+    }
     /** Returns the constraints clamped to lie within `parent` (Flutter's enforce). */
     enforce(parent) {
         return new BoxConstraints(Math.max(parent.minWidth, Math.min(this.minWidth, parent.maxWidth)), Math.max(parent.minWidth, Math.min(this.maxWidth, parent.maxWidth)), Math.max(parent.minHeight, Math.min(this.minHeight, parent.maxHeight)), Math.max(parent.minHeight, Math.min(this.maxHeight, parent.maxHeight)));
     }
 }
-exports.BoxConstraints = BoxConstraints;
+/**
+ * Resolves a sized element's extent on one axis (relative sizing). An explicit point size (`fixed`)
+ * always wins; otherwise a `factor` (0..1) of the offered extent, but ONLY when that axis is bounded -
+ * a fraction of an unbounded axis has no meaning (Flutter's FractionallySizedBox under unbounded
+ * constraints). Returns `undefined` to mean "no explicit extent", i.e. fill the box or shrink-wrap.
+ * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
+ */
+export function resolveExtent(fixed, factor, boundedMax, hasBounded) {
+    if (fixed !== undefined)
+        return fixed;
+    if (factor !== undefined && hasBounded)
+        return boundedMax * factor;
+    return undefined;
+}
+/** Split `SizingParams` into the per-axis form `resolveSize` takes. */
+export function extentSpecs(p) {
+    return {
+        width: {
+            fixed: p.width,
+            factor: p.widthFactor,
+            min: p.minWidth,
+            minFactor: p.minWidthFactor,
+            max: p.maxWidth,
+            maxFactor: p.maxWidthFactor,
+        },
+        height: {
+            fixed: p.height,
+            factor: p.heightFactor,
+            min: p.minHeight,
+            minFactor: p.minHeightFactor,
+            max: p.maxHeight,
+            maxFactor: p.maxHeightFactor,
+        },
+    };
+}
+/**
+ * Resolve both axes of a sized element: relative sizing, then `aspectRatio`, then `min`/`max`.
+ *
+ * The order follows CSS: a ratio fills in the axis you left open, and min/max clamp afterwards - so an
+ * explicit bound wins over the ratio, exactly as `min-height` beats `aspect-ratio` in a browser.
+ *
+ * `min`/`max` also come back as NARROWED constraints, because an axis with no explicit size still has
+ * to obey them. `maxWidth` alone means "fill, but no wider than this", and the caller's own fill and
+ * shrink-wrap paths get that for free by using the returned constraints instead of the ones passed in.
+ * A `width` of `undefined` keeps its usual meaning: fill or shrink-wrap.
+ */
+export function resolveSize(width, height, aspectRatio, constraints) {
+    const bounds = constraints.narrow(resolveExtent(width.min, width.minFactor, constraints.maxWidth, constraints.hasBoundedWidth), resolveExtent(width.max, width.maxFactor, constraints.maxWidth, constraints.hasBoundedWidth), resolveExtent(height.min, height.minFactor, constraints.maxHeight, constraints.hasBoundedHeight), resolveExtent(height.max, height.maxFactor, constraints.maxHeight, constraints.hasBoundedHeight));
+    // Against the OFFERED box, not the narrowed one: `width: "50%"` with `maxWidth: 100` in a 400pt
+    // region is 200 capped to 100, not 50% of 100. The clamp below applies the bound.
+    let w = resolveExtent(width.fixed, width.factor, constraints.maxWidth, constraints.hasBoundedWidth);
+    let h = resolveExtent(height.fixed, height.factor, constraints.maxHeight, constraints.hasBoundedHeight);
+    if (aspectRatio !== undefined && aspectRatio > 0) {
+        if (w !== undefined && h === undefined)
+            h = w / aspectRatio;
+        else if (h !== undefined && w === undefined)
+            w = h * aspectRatio;
+        else if (w === undefined && h === undefined) {
+            // Neither axis pinned: take the offered width and let the ratio give the height (CSS block
+            // behaviour). Falls back to the height when only that axis is bounded.
+            if (bounds.hasBoundedWidth) {
+                w = bounds.maxWidth;
+                h = w / aspectRatio;
+            }
+            else if (bounds.hasBoundedHeight) {
+                h = bounds.maxHeight;
+                w = h * aspectRatio;
+            }
+        }
+    }
+    return {
+        width: w === undefined ? undefined : bounds.constrainWidth(w),
+        height: h === undefined ? undefined : bounds.constrainHeight(h),
+        constraints: bounds,
+    };
+}

package/dist/layout/collect-images.d.ts

@@ -0,0 +1,9 @@
+import { PDFElement } from "../elements/pdf-element.js";
+import { ImageElement } from "../elements/image-element.js";
+/**
+ * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
+ * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
+ * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
+ * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ */
+export declare function collectImageElements(root: PDFElement): ImageElement[];

package/dist/layout/collect-images.js

@@ -0,0 +1,34 @@
+import { PDFElement, hasChildrenProp, hasChildProp } from "../elements/pdf-element.js";
+import { ImageElement } from "../elements/image-element.js";
+/**
+ * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
+ * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
+ * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
+ * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ */
+export function collectImageElements(root) {
+    const out = [];
+    const visit = (el) => {
+        if (el instanceof ImageElement)
+            out.push(el);
+        const props = el.getProps();
+        if (hasChildrenProp(props))
+            for (const c of props.children)
+                visit(c);
+        else if (hasChildProp(props))
+            visit(props.child);
+        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer and a
+        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there). A
+        // DeferredElement's `composed` is null until layout runs, so it cannot be reached from this
+        // pre-layout pass; an image inside a deferred subtree just skips aspect pre-resolution.
+        const w = props;
+        if (w.header instanceof PDFElement)
+            visit(w.header);
+        if (w.footer instanceof PDFElement)
+            visit(w.footer);
+        if (w.body instanceof PDFElement)
+            visit(w.body);
+    };
+    visit(root);
+    return out;
+}

package/dist/layout/fragmentation.d.ts

@@ -1,4 +1,4 @@
-import { LayoutContext, PDFElement } from "../elements/pdf-element";
+import { LayoutContext, PDFElement } from "../elements/pdf-element.js";
 /**
  * The result of splitting an element against a fragmentation region (a page, later a
  * column). `fitted` is the part that fits in the region; `remainder` describes what did
@@ -12,6 +12,10 @@ import { LayoutContext, PDFElement } from "../elements/pdf-element";
 export interface FragmentResult {
     fitted: PDFElement | null;
     remainder: PDFElement | null;
+    /** The split ended at a FORCED page break (a `PageBreak`), not because the region filled up. The
+     *  remainder must start a fresh page, and an enclosing flow must stop packing too - so this bubbles
+     *  up through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
+    forceBreak?: boolean;
 }
 /**
  * An element that knows how to split itself across regions. Width is already finalized
@@ -22,6 +26,20 @@ export interface Fragmentable {
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
 }
 export declare function isFragmentable(element: PDFElement): element is PDFElement & Fragmentable;
+/**
+ * What to do when an element is taller than the whole page region and cannot be broken. We always
+ * still place it (clipped) so pagination terminates - this only controls how loud we are about it:
+ * `"error"` throws (the default; an unbreakable overflow is almost always a layout bug), `"warn"`
+ * logs and clips, `"ignore"` clips silently.
+ */
+export type OverflowPolicy = "error" | "warn" | "ignore";
+export declare function reportOverflow(child: PDFElement, childHeight: number, maxHeight: number, policy: OverflowPolicy): void;
+/**
+ * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
+ * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
+ * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ */
+export declare function childrenForceBreak(children: PDFElement[]): boolean;
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -39,4 +57,5 @@ export declare function isFragmentable(element: PDFElement): element is PDFEleme
 export declare function packChildren(children: PDFElement[], maxHeight: number, width: number, ctx: LayoutContext, gap?: number): {
     fitted: PDFElement[];
     remainder: PDFElement[];
+    forceBreak: boolean;
 };