@jasy/pdf 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/layout/box-constraints.js

@@ -62,6 +62,16 @@ export 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)));
@@ -81,3 +91,65 @@ export function resolveExtent(fixed, factor, boundedMax, 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/insets.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolved and unresolved edge insets, on the LAYOUT side of the seam.
+ *
+ * The public `Insets` input (points, percentages, four shapes) lives in `api/insets.ts` and normalizes
+ * into the specs below - the same split `dimension.ts` and `box-constraints.ts` already use for sizes,
+ * so an element never sees a percentage string and the api layer never sees layout geometry.
+ */
+/** One side: an absolute point size, or a fraction of the available width. */
+export interface EdgeSpec {
+    points?: number;
+    factor?: number;
+}
+/**
+ * `[top, right, bottom, left]`, each still unresolved.
+ *
+ * A plain number is accepted as shorthand for `{ points: n }`: the engine elements are exported for
+ * power users and used to take four numbers, so requiring `{ points: 5 }` would break them for a
+ * feature they are not using.
+ */
+export type EdgeSpecs = [EdgeInput, EdgeInput, EdgeInput, EdgeInput];
+/** A side as given: points for short, or a spec when it may be a percentage. */
+export type EdgeInput = number | EdgeSpec;
+/**
+ * Turn the specs into points. `available` is the WIDTH the element was offered - a percentage resolves
+ * against the width on ALL FOUR sides, top and bottom included, which is the CSS rule (and Yoga's, so
+ * react-pdf agrees). An unbounded width leaves a percentage at 0, the no-op a percentage size gives.
+ */
+export declare function resolveEdges(specs: EdgeSpecs, available: number): [number, number, number, number];

package/dist/layout/insets.js

@@ -0,0 +1,20 @@
+/**
+ * Resolved and unresolved edge insets, on the LAYOUT side of the seam.
+ *
+ * The public `Insets` input (points, percentages, four shapes) lives in `api/insets.ts` and normalizes
+ * into the specs below - the same split `dimension.ts` and `box-constraints.ts` already use for sizes,
+ * so an element never sees a percentage string and the api layer never sees layout geometry.
+ */
+/**
+ * Turn the specs into points. `available` is the WIDTH the element was offered - a percentage resolves
+ * against the width on ALL FOUR sides, top and bottom included, which is the CSS rule (and Yoga's, so
+ * react-pdf agrees). An unbounded width leaves a percentage at 0, the no-op a percentage size gives.
+ */
+export function resolveEdges(specs, available) {
+    const one = (e) => {
+        if (typeof e === "number")
+            return e;
+        return (e.points ?? (e.factor !== undefined && Number.isFinite(available) ? available * e.factor : 0));
+    };
+    return [one(specs[0]), one(specs[1]), one(specs[2]), one(specs[3])];
+}

package/dist/renderer/form-field-renderer.d.ts

@@ -0,0 +1,20 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { TextFieldElement } from "../elements/forms/text-field-element.js";
+import { CheckboxElement } from "../elements/forms/checkbox-element.js";
+import { RadioElement } from "../elements/forms/radio-element.js";
+import { ChoiceElement } from "../elements/forms/choice-element.js";
+import { PushButtonElement } from "../elements/forms/push-button-element.js";
+import { SignatureFieldElement } from "../elements/forms/signature-element.js";
+import { IRNode } from "../ir/display-list.js";
+/** Any form-field element exposes its box + shared spec + style through `getProps()`. */
+type FormFieldElement = TextFieldElement | CheckboxElement | RadioElement | ChoiceElement | PushButtonElement | SignatureFieldElement;
+/**
+ * Renders a form-field element to a single `formfield` IR node - the field's box + its shared
+ * `FormFieldSpec` + style. It draws nothing; the PageRenderer peels it into a Widget /Annot and the
+ * /AcroForm (via forms/acroform.ts). One renderer serves every field element (the spec's `kind`
+ * discriminates downstream).
+ */
+export declare class FormFieldRenderer {
+    static render(element: FormFieldElement, _objectManager: PDFObjectManager): Promise<IRNode[]>;
+}
+export {};

package/dist/renderer/form-field-renderer.js

@@ -0,0 +1,12 @@
+/**
+ * Renders a form-field element to a single `formfield` IR node - the field's box + its shared
+ * `FormFieldSpec` + style. It draws nothing; the PageRenderer peels it into a Widget /Annot and the
+ * /AcroForm (via forms/acroform.ts). One renderer serves every field element (the spec's `kind`
+ * discriminates downstream).
+ */
+export class FormFieldRenderer {
+    static async render(element, _objectManager) {
+        const { x, y, width, height, spec, style } = element.getProps();
+        return [{ type: "formfield", x, y, width, height, field: spec, style }];
+    }
+}

package/dist/renderer/image-renderer.js

@@ -1,6 +1,7 @@
 import { BoxFit } from "../elements/image-element.js";
 import { bytesFromLatin1 } from "../utils/bytes.js";
 import { applyContainFit, applyCoverFit, applyFillFit, applyFitNone, decodePngToRgbFlate, } from "../utils/image-helper.js";
+import { isRounded } from "../ir/display-list.js";
 export class ImageRenderer {
     static async render(imageElement, objectManager) {
         // Load the image and convert it in a binary string
@@ -56,7 +57,7 @@ export class ImageRenderer {
         }
         // A radius rounds the image BOX (the element frame), so it clips to that frame too -
         // independent of the cover/contain overflow clip.
-        const wantsClip = mustCreateOverflowContainer || (radius ?? 0) > 0;
+        const wantsClip = mustCreateOverflowContainer || isRounded(radius);
         // The fitted geometry becomes a display-list primitive; the backend registers
         // the XObject and emits the placement (+ clip, rounded when a radius is set).
         const node = {

package/dist/renderer/page-renderer.js

@@ -74,14 +74,20 @@ export class PageRenderer {
         const num = (n) => Number(n.toFixed(2));
         const annotRefs = [];
         for (const node of flipped) {
+            // A form field: build its Widget annotation + register it as an /AcroForm field (the logic lives in
+            // forms/acroform.ts), then reference it here in the page /Annots - the same side channel as a link.
+            if (node.type === "formfield") {
+                annotRefs.push(`${objectManager.acroform.addField(node, objectManager)} 0 R`);
+                continue;
+            }
             if (node.type !== "link")
                 continue;
             const rect = `[${num(node.x)} ${num(node.y)} ${num(node.x + node.width)} ${num(node.y + node.height)}]`;
             // Either an external URL (/URI) or an internal named destination (/GoTo, resolved via /Names /Dests).
             // The Link IR guarantees exactly one is set; prefer `dest` when present.
             const action = node.dest !== undefined
-                ? `/A << /S /GoTo /D (${PdfBackend.escapePdfString(node.dest)}) >>`
-                : `/A << /S /URI /URI (${PdfBackend.escapePdfString(node.href ?? "")}) >>`;
+                ? `/A << /S /GoTo /D ${objectManager.pdfString(node.dest)} >>`
+                : `/A << /S /URI /URI ${objectManager.pdfString(node.href ?? "")} >>`;
             const annot = objectManager.addObject(`<< /Type /Annot /Subtype /Link /Rect ${rect} /Border [0 0 0] ${action} >>`);
             annotRefs.push(`${annot} 0 R`);
         }

package/dist/renderer/pdf-backend.d.ts

@@ -58,6 +58,12 @@ export declare class PdfBackend {
      * (kappa ≈ 0.5523). Returns m/l/c/h ops WITHOUT the paint operator.
      */
     private static roundedRectPath;
+    /**
+     * Clamp the four radii into the box. Each is capped at half the box, and two radii sharing an edge
+     * are scaled down together when they would overlap - the CSS rule, and what keeps the path from
+     * folding back on itself.
+     */
+    private static clampRadii;
     /**
      * Serialize a single display-list node to its content-stream operators.
      * `om` is used only by primitives that allocate PDF resources (images, fonts).

package/dist/renderer/pdf-backend.js

@@ -1,3 +1,4 @@
+import { isRounded } from "../ir/display-list.js";
 import { Color } from "../common/color.js";
 /**
  * PDF backend - turns display-list primitives into content-stream operators.
@@ -18,8 +19,13 @@ export class PdfBackend {
     static flipY(nodes, pageHeight) {
         return nodes.map((node) => {
             switch (node.type) {
-                case "rect":
-                    return { ...node, y: pageHeight - node.y - node.height };
+                case "rect": {
+                    // A gradient fill carries its own page-space anchors; flip them with the box (see "path").
+                    const fill = node.fill === undefined || node.fill instanceof Color
+                        ? node.fill
+                        : { ...node.fill, y0: pageHeight - node.fill.y0, y1: pageHeight - node.fill.y1 };
+                    return { ...node, y: pageHeight - node.y - node.height, fill };
+                }
                 case "line":
                     return {
                         ...node,
@@ -65,6 +71,9 @@ export class PdfBackend {
                 case "link":
                     // A link's clickable rect flips around its bottom edge, exactly like a rect.
                     return { ...node, y: pageHeight - node.y - node.height };
+                case "formfield":
+                    // A form field's box flips around its bottom edge, exactly like a link rect.
+                    return { ...node, y: pageHeight - node.y - node.height };
                 case "outline":
                     // An outline anchor is a single point (the target's top); flip it like a text baseline.
                     return { ...node, y: pageHeight - node.y };
@@ -137,6 +146,7 @@ export class PdfBackend {
                 node.type === "link" ||
                 node.type === "outline" ||
                 node.type === "anchor" ||
+                node.type === "formfield" ||
                 ops === "")
                 return ops;
             const { open, close } = struct.mark(node.tag);
@@ -189,26 +199,45 @@ export class PdfBackend {
      * (kappa ≈ 0.5523). Returns m/l/c/h ops WITHOUT the paint operator.
      */
     static roundedRectPath(x, y, w, h, radius) {
-        const r = Math.min(radius, w / 2, h / 2);
-        const c = r * 0.5523; // control-point offset that approximates a quarter circle
+        // Per corner, in PDF coordinates (y up). With all four equal this emits exactly the operators the
+        // single-radius version did - the byte-identity guard for every document that never asks for one.
+        const r = PdfBackend.clampRadii(radius, w, h);
+        const k = 0.5523; // control-point offset that approximates a quarter circle
         const f = (n) => n.toFixed(3);
-        const xr = x + r;
-        const xwr = x + w - r;
         const xw = x + w;
-        const yr = y + r;
-        const yhr = y + h - r;
         const yh = y + h;
-        return (`${f(xr)} ${f(y)} m\n` +
-            `${f(xwr)} ${f(y)} l\n` +
-            `${f(xwr + c)} ${f(y)} ${f(xw)} ${f(yr - c)} ${f(xw)} ${f(yr)} c\n` +
-            `${f(xw)} ${f(yhr)} l\n` +
-            `${f(xw)} ${f(yhr + c)} ${f(xwr + c)} ${f(yh)} ${f(xwr)} ${f(yh)} c\n` +
-            `${f(xr)} ${f(yh)} l\n` +
-            `${f(xr - c)} ${f(yh)} ${f(x)} ${f(yhr + c)} ${f(x)} ${f(yhr)} c\n` +
-            `${f(x)} ${f(yr)} l\n` +
-            `${f(x)} ${f(yr - c)} ${f(xr - c)} ${f(y)} ${f(xr)} ${f(y)} c\n` +
+        return (`${f(x + r.bl)} ${f(y)} m\n` +
+            `${f(xw - r.br)} ${f(y)} l\n` +
+            `${f(xw - r.br + r.br * k)} ${f(y)} ${f(xw)} ${f(y + r.br - r.br * k)} ${f(xw)} ${f(y + r.br)} c\n` +
+            `${f(xw)} ${f(yh - r.tr)} l\n` +
+            `${f(xw)} ${f(yh - r.tr + r.tr * k)} ${f(xw - r.tr + r.tr * k)} ${f(yh)} ${f(xw - r.tr)} ${f(yh)} c\n` +
+            `${f(x + r.tl)} ${f(yh)} l\n` +
+            `${f(x + r.tl - r.tl * k)} ${f(yh)} ${f(x)} ${f(yh - r.tl + r.tl * k)} ${f(x)} ${f(yh - r.tl)} c\n` +
+            `${f(x)} ${f(y + r.bl)} l\n` +
+            `${f(x)} ${f(y + r.bl - r.bl * k)} ${f(x + r.bl - r.bl * k)} ${f(y)} ${f(x + r.bl)} ${f(y)} c\n` +
             `h`);
     }
+    /**
+     * Clamp the four radii into the box. Each is capped at half the box, and two radii sharing an edge
+     * are scaled down together when they would overlap - the CSS rule, and what keeps the path from
+     * folding back on itself.
+     */
+    static clampRadii(radius, w, h) {
+        const n = typeof radius === "number" ? radius : 0;
+        const cap = Math.max(0, Math.min(w, h) / 2);
+        const at = (v) => Math.max(0, Math.min(v ?? n, cap));
+        const r = typeof radius === "number"
+            ? { tl: at(radius), tr: at(radius), br: at(radius), bl: at(radius) }
+            : { tl: at(radius.tl), tr: at(radius.tr), br: at(radius.br), bl: at(radius.bl) };
+        // Per-edge overlap: scale the whole set by the tightest edge, so the corners stay proportional.
+        // An edge whose two corners are both 0 constrains NOTHING - it must not contribute a ratio of 0,
+        // which would scale every other corner away with it.
+        const ratio = (extent, a, b) => a + b > 0 ? extent / (a + b) : Infinity;
+        const scale = Math.min(1, ratio(w, r.tl, r.tr), ratio(w, r.bl, r.br), ratio(h, r.tl, r.bl), ratio(h, r.tr, r.br));
+        if (scale >= 1)
+            return r;
+        return { tl: r.tl * scale, tr: r.tr * scale, br: r.br * scale, bl: r.bl * scale };
+    }
     /**
      * Serialize a single display-list node to its content-stream operators.
      * `om` is used only by primitives that allocate PDF resources (images, fonts).
@@ -233,22 +262,37 @@ export class PdfBackend {
                 const doStroke = !!node.stroke && (node.strokeWidth ?? 0) > 0;
                 if (!node.fill && !doStroke)
                     return "";
-                let ops = "";
-                if (doStroke) {
-                    ops += `${node.strokeWidth} w\n${node.stroke.toPDFColorString()} RG\n`;
-                }
-                if (node.fill)
-                    ops += `${node.fill.toPDFColorString()} rg\n`;
-                const paint = node.fill ? (doStroke ? "B" : "f") : "S";
                 // Rounded corners emit a Bézier path; sharp corners keep the plain `re`
                 // (byte-identical when no radius is set).
-                const path = (node.radius ?? 0) > 0
+                const path = isRounded(node.radius)
                     ? PdfBackend.roundedRectPath(node.x, node.y, node.width, node.height, node.radius)
                     : `${node.x} ${node.y} ${node.width} ${node.height} re`;
+                // A gradient cannot be a fill COLOUR - PDF paints one with `sh`, which floods the current
+                // clip. So the box becomes the clip, the shading is painted inside it, and a border is
+                // stroked afterwards on its own. Solid fills keep the plain operators, byte for byte.
+                const gradient = node.fill !== undefined && !(node.fill instanceof Color) ? node.fill : undefined;
+                if (gradient) {
+                    const shading = om.registerShading(gradient);
+                    let out = `q\n${path} W n\n/${shading} sh\nQ\n`;
+                    if (doStroke) {
+                        const gsStroke = PdfBackend.alphaPrefix(om, 1, node.stroke.getAlpha());
+                        const stroke = `${node.strokeWidth} w\n${node.stroke.toPDFColorString()} RG\n` + `${path} S\n`;
+                        out += gsStroke ? `q\n${gsStroke}${stroke}Q\n` : stroke;
+                    }
+                    return out;
+                }
+                const fill = node.fill;
+                let ops = "";
+                if (doStroke) {
+                    ops += `${node.strokeWidth} w\n${node.stroke.toPDFColorString()} RG\n`;
+                }
+                if (fill)
+                    ops += `${fill.toPDFColorString()} rg\n`;
+                const paint = fill ? (doStroke ? "B" : "f") : "S";
                 const body = ops + `${path} ${paint}\n`;
                 // Transparency needs an isolating q/Q so the state does not leak; opaque rects
                 // keep their bare operators (byte-identical).
-                const gs = PdfBackend.alphaPrefix(om, node.fill?.getAlpha() ?? 1, doStroke ? node.stroke.getAlpha() : 1);
+                const gs = PdfBackend.alphaPrefix(om, fill?.getAlpha() ?? 1, doStroke ? node.stroke.getAlpha() : 1);
                 return gs ? `q\n${gs}${body}Q\n` : body;
             }
             case "text": {
@@ -266,15 +310,22 @@ export class PdfBackend {
                 const encode = (t) => isCustom
                     ? `<${om.encodeCustomText(node.fontFamily, t, node.fontStyle)}>`
                     : `(${PdfBackend.escapePdfString(t)})`;
+                // A shaped run brings its own glyphs, already in drawing order - they cannot be derived from
+                // the text here.
+                const shapedHex = node.glyphs && isCustom
+                    ? om.registerGlyphs(node.fontFamily, node.glyphs, node.fontStyle)
+                    : undefined;
                 // Kerning (if the document has it on): a `TJ` array with the font's per-pair adjustments
                 // between glyph chunks, measured into the layout by the SAME numbers (runAdvance). A plain
                 // `Tj` when the run has no kerning, byte-identical.
                 const kerns = om.kerningEnabled
                     ? om.getKernPairs(node.text, node.fontFamily, node.fontStyle)
                     : [];
-                const showOp = kerns.some((k) => k !== 0)
-                    ? `${PdfBackend.kernedArray(node.text, kerns, encode)} TJ`
-                    : `${encode(node.text)} Tj`;
+                const showOp = shapedHex
+                    ? `<${shapedHex}> Tj`
+                    : kerns.some((k) => k !== 0)
+                        ? `${PdfBackend.kernedArray(node.text, kerns, encode)} TJ`
+                        : `${encode(node.text)} Tj`;
                 // letterSpacing is the `Tc` operator: extra advance after EVERY glyph (an embedded
                 // Identity-H font too - that is `Tw`, word spacing, which only touches single-byte code 32).
                 const spacing = node.letterSpacing ? `${node.letterSpacing.toFixed(3)} Tc\n` : "";
@@ -299,7 +350,7 @@ export class PdfBackend {
                 // Clip to the frame (re … W n); rounded when a radius is set. The rectangular
                 // path is byte-identical to before.
                 const c = node.clip;
-                const clipPath = (node.radius ?? 0) > 0
+                const clipPath = isRounded(node.radius)
                     ? PdfBackend.roundedRectPath(c.x, c.y, c.width, c.height, node.radius)
                     : `${c.x} ${c.y} ${c.width} ${c.height} re `;
                 return `q\n${clipPath}\nW n \n` + draw + `Q\n`;
@@ -307,7 +358,7 @@ export class PdfBackend {
             case "clip-push": {
                 // Save the graphics state and intersect the clip with this (rounded) rect. Everything
                 // drawn until the matching clip-pop is cropped to it.
-                const path = (node.radius ?? 0) > 0
+                const path = isRounded(node.radius)
                     ? PdfBackend.roundedRectPath(node.x, node.y, node.width, node.height, node.radius)
                     : `${node.x} ${node.y} ${node.width} ${node.height} re`;
                 return `q\n${path}\nW n\n`;
@@ -357,6 +408,10 @@ export class PdfBackend {
             case "anchor":
                 // A named destination draws nothing - it becomes a /Names /Dests entry (built in PageRenderer/PDFRenderer).
                 return "";
+            case "formfield":
+                // A form field draws nothing in the content stream - it becomes a Widget /Annot + /AcroForm field
+                // (built in PageRenderer via forms/acroform.ts).
+                return "";
             default: {
                 // Exhaustiveness guard: if a new IRNode variant is added, this fails to compile.
                 const unknown = node;

package/dist/renderer/pdf-document-renderer.js

@@ -14,8 +14,13 @@ export class PDFDocumentRenderer {
         // pure (`{ fitted, remainder }`), so the full list of physical pages can be settled up front. Only
         // then is the total page count known, which is what page numbers in a header/footer need.
         const physicalPages = [];
+        // Where each sheet sits WITHIN the logical page it came from. Pass A already knows: one logical
+        // `Page` element produces one run of sheets, so the run's length is that section's total.
+        const section = [];
         for (const page of document.getProps().children) {
-            physicalPages.push(...PDFDocumentRenderer.paginateLogicalPage(page, ctx));
+            const sheets = PDFDocumentRenderer.paginateLogicalPage(page, ctx);
+            sheets.forEach((_, i) => section.push({ number: i + 1, total: sheets.length }));
+            physicalPages.push(...sheets);
         }
         // Pass B - draw them, in order, so the emitted page objects keep their previous numbering. Each page
         // is laid out again with its own PageInfo, which is how a `PageBuilder` anywhere in the tree (header,
@@ -25,6 +30,8 @@ export class PDFDocumentRenderer {
             const pageInfo = {
                 pageNumber: index + 1,
                 pageCount: physicalPages.length,
+                subPageNumber: section[index].number,
+                subPageTotalPages: section[index].total,
                 pageSize: resolvePageSize(PDFDocumentRenderer.configOf(physical, ctx)),
             };
             pageNumbers.push(await PDFDocumentRenderer.renderPhysicalPage(physical, objectManager, {

package/dist/renderer/pdf-renderer.js

@@ -31,6 +31,13 @@ import { AnchorRenderer } from "./anchor-renderer.js";
 import { PageBreakRenderer } from "./page-break-renderer.js";
 import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
 import { KeepTogetherRenderer } from "./keep-together-renderer.js";
+import { TextFieldElement } from "../elements/forms/text-field-element.js";
+import { CheckboxElement } from "../elements/forms/checkbox-element.js";
+import { RadioElement } from "../elements/forms/radio-element.js";
+import { ChoiceElement } from "../elements/forms/choice-element.js";
+import { PushButtonElement } from "../elements/forms/push-button-element.js";
+import { SignatureFieldElement } from "../elements/forms/signature-element.js";
+import { FormFieldRenderer } from "./form-field-renderer.js";
 import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
 import { PageBuilderRenderer } from "./page-builder-renderer.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
@@ -51,6 +58,12 @@ export class PDFRenderer {
         RendererRegistry.register(PaddingElement, PaddingRenderer.render);
         RendererRegistry.register(PageBreakElement, PageBreakRenderer.render);
         RendererRegistry.register(KeepTogetherElement, KeepTogetherRenderer.render);
+        RendererRegistry.register(TextFieldElement, FormFieldRenderer.render);
+        RendererRegistry.register(CheckboxElement, FormFieldRenderer.render);
+        RendererRegistry.register(RadioElement, FormFieldRenderer.render);
+        RendererRegistry.register(ChoiceElement, FormFieldRenderer.render);
+        RendererRegistry.register(PushButtonElement, FormFieldRenderer.render);
+        RendererRegistry.register(SignatureFieldElement, FormFieldRenderer.render);
         RendererRegistry.register(DefaultTextStyleElement, DefaultTextStyleRenderer.render);
         RendererRegistry.register(ImageElement, ImageRenderer.render);
         RendererRegistry.register(LineElement, LineRenderer.render);
@@ -124,8 +137,13 @@ export class PDFRenderer {
         const outlineCatalog = objectManager.outline.finalize(objectManager);
         if (outlineCatalog)
             catalogParts.push(outlineCatalog);
+        // Interactive form fields: emit the catalog /AcroForm dict collected as pages rendered. Returns ""
+        // (no-op) when no field was placed, so a plain document's catalog is unchanged.
+        const acroformCatalog = objectManager.acroform.finalize(objectManager);
+        if (acroformCatalog)
+            catalogParts.push(acroformCatalog);
         // Named destinations (internal-link targets): a /Dests entry in the shared /Names dict.
-        const destsNames = objectManager.dests.finalize();
+        const destsNames = objectManager.dests.finalize(objectManager);
         if (destsNames)
             namesParts.push(destsNames);
         // Emit the single /Names dict if either embedded files or destinations contributed to it.

package/dist/renderer/rectangle-renderer.js

@@ -1,14 +1,20 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
+import { isGradientInput, resolveGradient } from "../api/gradient.js";
 export class RectangleRenderer {
     static async render(rectangleElement, objectManager) {
         const { x, y, width, height, children, color, backgroundColor, borderWidth, radius, sideBorders, overflow, } = rectangleElement.getProps();
         const h = height;
         const nodes = [];
+        // A gradient is written box-relative (an angle and stops); this is the first place the box is
+        // known, so it is resolved into the absolute page coordinates the IR wants.
+        const fill = backgroundColor !== undefined && isGradientInput(backgroundColor)
+            ? resolveGradient(backgroundColor, x, y, width, h)
+            : backgroundColor;
         if (sideBorders) {
             // Per-side borders: a fill-only box (no stroke), then a line per present side
             // (sharp corners). This is what lets cells draw grid lines.
             if (backgroundColor) {
-                nodes.push({ type: "rect", x, y, width, height: h, strokeWidth: 0, fill: backgroundColor });
+                nodes.push({ type: "rect", x, y, width, height: h, strokeWidth: 0, fill });
             }
             nodes.push(...RectangleRenderer.sideLines(x, y, width, h, borderWidth, sideBorders));
         }
@@ -23,7 +29,7 @@ export class RectangleRenderer {
                 height: h,
                 stroke: color,
                 strokeWidth: borderWidth,
-                ...(backgroundColor ? { fill: backgroundColor } : {}),
+                ...(fill ? { fill } : {}),
                 ...(radius ? { radius } : {}),
             };
             nodes.push(node);

package/dist/renderer/text-renderer.d.ts

@@ -2,9 +2,9 @@ import { TextElement, TextSegment } from "../elements/text-element.js";
 import { FontStyle, PDFObjectManager } from "../utils/pdf-object-manager.js";
 import type { FontMetrics } from "../utils/font-metrics.js";
 import { IRNode } from "../ir/display-list.js";
-import { TextOverflow } from "../text/line-breaker.js";
+import { type LineOptions, TextOverflow } from "../text/line-breaker.js";
 export declare class TextRenderer {
-    static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number, letterSpacing?: number): number;
+    static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number, letterSpacing?: number, lineOptions?: LineOptions): number;
     static render(textElement: TextElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
     private static _expandColorGlyphs;
     private static _glyphToPath;