@jasy/pdf 1.0.0-alpha.8 → 1.0.0-beta.1

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

@@ -41,11 +41,22 @@ export declare class PdfBackend {
     static escapePdfString(text: string): string;
     /**
      * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
-     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
-     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
-     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     * sign the font declares). Generic over the UNIT so the same chunking serves both paths: characters
+     * for a WinAnsi run, glyph ids for a shaped one - a shaped run cannot be expressed as text.
+     * A `TJ` number moves the pen LEFT, so it is the NEGATED kern. Consecutive un-kerned glyphs stay in
+     * one encoded chunk, so `[(T) 40 (otal)]` rather than one chunk per glyph. `kerns[i]` is the
+     * adjustment AFTER code point `i`.
      */
-    static kernedArray(text: string, kerns: number[], encode: (chunk: string) => string): string;
+    static kernedArray<T>(units: readonly T[], kerns: number[], encode: (chunk: T[]) => string): string;
+    /** The path-construction operators for a command list. Shared by a filled path and by a clip. */
+    private static pathOps;
+    /**
+     * The graphics-state operators for a stroke, in the order a content stream wants them. Only what
+     * differs from the PDF default is emitted, EXCEPT the miter limit: SVG's initial value is 4 and
+     * PDF's is 10, so a mitered join has to say so or a sharp corner grows a spike the source never had.
+     * The caller isolates these in a q/Q - `d` in particular would otherwise dash every later stroke.
+     */
+    private static strokeState;
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays
@@ -58,6 +69,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,
@@ -40,6 +46,19 @@ export class PdfBackend {
                     }
                     return flipped;
                 }
+                case "clip-path-push":
+                    // Its commands live in the same space as a Path's, so they flip the same way.
+                    return {
+                        ...node,
+                        commands: node.commands.map((c) => {
+                            if (c.op === "z")
+                                return c;
+                            if (c.op === "c") {
+                                return { ...c, y1: pageHeight - c.y1, y2: pageHeight - c.y2, y: pageHeight - c.y };
+                            }
+                            return { ...c, y: pageHeight - c.y };
+                        }),
+                    };
                 case "clip-push":
                     // Flip the clip rect around its bottom edge, like a rect.
                     return { ...node, y: pageHeight - node.y - node.height };
@@ -57,7 +76,7 @@ export class PdfBackend {
                     });
                     // A gradient fill carries its own page-space anchor points; flip their y too (radii and
                     // x stay). A solid Color fill has no geometry.
-                    const fill = node.fill instanceof Color
+                    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, commands, fill };
@@ -134,6 +153,7 @@ export class PdfBackend {
             // catalog entries instead of content-stream operators.
             if (!struct ||
                 node.type === "clip-push" ||
+                node.type === "clip-path-push" ||
                 node.type === "clip-pop" ||
                 node.type === "transform-push" ||
                 node.type === "transform-pop" ||
@@ -158,25 +178,72 @@ export class PdfBackend {
     }
     /**
      * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
-     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
-     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
-     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     * sign the font declares). Generic over the UNIT so the same chunking serves both paths: characters
+     * for a WinAnsi run, glyph ids for a shaped one - a shaped run cannot be expressed as text.
+     * A `TJ` number moves the pen LEFT, so it is the NEGATED kern. Consecutive un-kerned glyphs stay in
+     * one encoded chunk, so `[(T) 40 (otal)]` rather than one chunk per glyph. `kerns[i]` is the
+     * adjustment AFTER code point `i`.
      */
-    static kernedArray(text, kerns, encode) {
-        const chars = [...text];
+    static kernedArray(units, kerns, encode) {
+        const gaps = Math.max(0, units.length - 1);
+        if (kerns.length !== gaps) {
+            // The loop walks the GAPS, so a short list would drop the units past it - silently, and only the
+            // last glyph, which is exactly the kind of thing nobody notices until a word reads wrong. An
+            // empty run has no gaps at all, so any adjustment for one is a disagreement too.
+            throw new Error(`@jasy/pdf: ${kerns.length} kern adjustments for ${units.length} units - expected ${gaps}.`);
+        }
         let out = "";
-        let chunk = chars[0] ?? "";
+        let chunk = units.length > 0 ? [units[0]] : [];
         for (let i = 0; i < kerns.length; i++) {
             if (kerns[i] === 0) {
-                chunk += chars[i + 1];
+                chunk.push(units[i + 1]);
             }
             else {
                 out += encode(chunk) + ` ${-kerns[i]} `;
-                chunk = chars[i + 1];
+                chunk = [units[i + 1]];
             }
         }
         return `[${out}${encode(chunk)}]`;
     }
+    /** The path-construction operators for a command list. Shared by a filled path and by a clip. */
+    static pathOps(commands) {
+        const f = (n) => n.toFixed(3);
+        let out = "";
+        for (const c of commands) {
+            if (c.op === "m")
+                out += `${f(c.x)} ${f(c.y)} m\n`;
+            else if (c.op === "l")
+                out += `${f(c.x)} ${f(c.y)} l\n`;
+            else if (c.op === "c")
+                out += `${f(c.x1)} ${f(c.y1)} ${f(c.x2)} ${f(c.y2)} ${f(c.x)} ${f(c.y)} c\n`;
+            else
+                out += `h\n`;
+        }
+        return out;
+    }
+    /**
+     * The graphics-state operators for a stroke, in the order a content stream wants them. Only what
+     * differs from the PDF default is emitted, EXCEPT the miter limit: SVG's initial value is 4 and
+     * PDF's is 10, so a mitered join has to say so or a sharp corner grows a spike the source never had.
+     * The caller isolates these in a q/Q - `d` in particular would otherwise dash every later stroke.
+     */
+    static strokeState(stroke) {
+        const CAPS = { butt: 0, round: 1, square: 2 };
+        const JOINS = { miter: 0, round: 1, bevel: 2 };
+        let ops = `${stroke.width} w\n${stroke.color.toPDFColorString()} RG\n`;
+        if (stroke.cap && stroke.cap !== "butt")
+            ops += `${CAPS[stroke.cap]} J\n`;
+        const join = stroke.join ?? "miter";
+        if (join !== "miter")
+            ops += `${JOINS[join]} j\n`;
+        else
+            ops += `${stroke.miterLimit ?? 4} M\n`;
+        // A dash array of all zeros means "solid" in SVG but is an error in PDF, so it is dropped.
+        if (stroke.dash && stroke.dash.length > 0 && stroke.dash.some((n) => n > 0)) {
+            ops += `[${stroke.dash.join(" ")}] ${stroke.dashOffset ?? 0} d\n`;
+        }
+        return ops;
+    }
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays
@@ -193,26 +260,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).
@@ -237,22 +323,38 @@ 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);
+                    const gsFill = PdfBackend.alphaPrefix(om, gradient.alpha ?? 1, 1);
+                    let out = `q\n${gsFill}${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": {
@@ -268,17 +370,35 @@ export class PdfBackend {
                     ? om.getCustomFontResource(node.fontFamily, node.fontStyle)
                     : om.registerFont(node.fontFamily, node.fontStyle);
                 const encode = (t) => isCustom
-                    ? `<${om.encodeCustomText(node.fontFamily, t, node.fontStyle)}>`
+                    ? `<${om.encodeCustomText(node.fontFamily, t, node.fontStyle, false)}>`
                     : `(${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`;
+                // A shaped run brings its glyphs along, so kern those directly rather than re-deriving them
+                // from the text - which would also have to guess the run's ligature setting.
+                const kerns = !om.kerningEnabled
+                    ? []
+                    : node.glyphs && isCustom
+                        ? om.getGlyphKernPairs(node.glyphs, node.fontFamily, node.fontStyle)
+                        : // No glyph list means the run was NOT shaped, whatever the document asks for - so take the
+                            // character path explicitly. Letting it default would shape here, and a pair count that
+                            // does not match the character count silently drops the last one.
+                            om.getKernPairs(node.text, node.fontFamily, node.fontStyle, false);
+                // A shaped run kerns too, over its SHAPED glyphs - `getKernPairs` returns one adjustment per
+                // adjacent drawn pair either way, so both paths use the same numbers `runAdvance` measured.
+                const showOp = node.glyphs && isCustom
+                    ? kerns.some((k) => k !== 0)
+                        ? `${PdfBackend.kernedArray(node.glyphs, kerns, (chunk) => `<${om.registerGlyphs(node.fontFamily, chunk, node.fontStyle)}>`)} TJ`
+                        : `<${shapedHex}> Tj`
+                    : kerns.some((k) => k !== 0)
+                        ? `${PdfBackend.kernedArray([...node.text], kerns, (chunk) => encode(chunk.join("")))} 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` : "";
@@ -303,7 +423,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`;
@@ -311,38 +431,55 @@ 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`;
             }
             case "path": {
-                // A filled vector path (one color-glyph layer). Emit the subpath ops, then either a solid
-                // nonzero fill (a Color) or, for a gradient, clip to the path and paint a shading inside it.
-                const f = (n) => n.toFixed(3);
-                let path = "";
-                for (const c of node.commands) {
-                    if (c.op === "m")
-                        path += `${f(c.x)} ${f(c.y)} m\n`;
-                    else if (c.op === "l")
-                        path += `${f(c.x)} ${f(c.y)} l\n`;
-                    else if (c.op === "c")
-                        path += `${f(c.x1)} ${f(c.y1)} ${f(c.x2)} ${f(c.y2)} ${f(c.x)} ${f(c.y)} c\n`;
-                    else
-                        path += `h\n`;
-                }
-                if (!(node.fill instanceof Color)) {
+                // A vector path: a color-glyph layer (fill only) or an SVG shape (fill and/or stroke). Emit
+                // the subpath ops once, then pick the painting operator from what the node actually carries.
+                const path = PdfBackend.pathOps(node.commands);
+                // The even-odd variants of the fill and clip operators are the same letter plus a star.
+                const star = node.fillRule === "evenodd" ? "*" : "";
+                const stroke = node.stroke;
+                if (node.fill !== undefined && !(node.fill instanceof Color)) {
                     // Gradient: clip to the path (W n keeps it as the clip without painting it), then paint
                     // the registered shading across that clip. The q/Q isolates the clip. Note: per-stop alpha
                     // is not represented (a DeviceRGB shading has no alpha channel - that would need a soft-mask
                     // group); COLR gradient stops are opaque in real fonts, so they render correctly.
+                    // A stroke cannot share that q/Q: the clip would cut the outline in half, because a stroke
+                    // straddles the edge. So it is drawn afterwards, over the same path.
                     const shading = om.registerShading(node.fill);
-                    return `q\n${path}W n\n/${shading} sh\nQ\n`;
+                    const gsFill = PdfBackend.alphaPrefix(om, node.fill.alpha ?? 1, 1);
+                    const filled = `q\n${gsFill}${path}W${star} n\n/${shading} sh\nQ\n`;
+                    if (!stroke)
+                        return filled;
+                    const gsStroke = PdfBackend.alphaPrefix(om, 1, stroke.color.getAlpha());
+                    return `${filled}q\n${gsStroke}${PdfBackend.strokeState(stroke)}${path}S\nQ\n`;
+                }
+                // No fill and no stroke: a shape that paints nothing. Emitting the path without an operator
+                // would leave it pending in the content stream and swallow whatever is drawn next.
+                if (node.fill === undefined && !stroke)
+                    return "";
+                if (stroke) {
+                    // A stroked path always gets its own q/Q. Unlike a rect it can set `J`, `j`, `M` and `d`,
+                    // and those would otherwise stay on for every later stroke on the page - a dash pattern
+                    // leaking into the next table rule. Existing IR carries no stroke, so nothing moves.
+                    const paint = node.fill !== undefined ? `B${star}` : "S";
+                    const color = node.fill !== undefined ? `${node.fill.toPDFColorString()} rg\n` : "";
+                    const gs = PdfBackend.alphaPrefix(om, node.fill !== undefined ? node.fill.getAlpha() : 1, stroke.color.getAlpha());
+                    return `q\n${gs}${color}${PdfBackend.strokeState(stroke)}${path}${paint}\nQ\n`;
                 }
-                const body = `${node.fill.toPDFColorString()} rg\n${path}f\n`;
+                const body = `${node.fill.toPDFColorString()} rg\n${path}f${star}\n`;
                 const gs = PdfBackend.alphaPrefix(om, node.fill.getAlpha(), 1);
                 return gs ? `q\n${gs}${body}Q\n` : body;
             }
+            case "clip-path-push": {
+                // `W n` sets the clip from the current path without painting it; the q is closed by clip-pop.
+                const star = node.fillRule === "evenodd" ? "*" : "";
+                return `q\n${PdfBackend.pathOps(node.commands)}W${star} n\n`;
+            }
             case "clip-pop":
                 return `Q\n`;
             case "transform-push": {

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

@@ -1,6 +1,6 @@
 import { PDFDocumentRenderer } from "./pdf-document-renderer.js";
 import { RendererRegistry } from "../utils/renderer-registry.js";
-import { DefaultTextStyleElement, ExpandedElement, ImageElement, LineElement, PaddingElement, TextElement, } from "../elements/index.js";
+import { DefaultTextStyleElement, ExpandedElement, ImageElement, LineElement, CanvasElement, PaddingElement, SvgElement, TextElement, } from "../elements/index.js";
 import { TextRenderer } from "./text-renderer.js";
 import { ContainerElement } from "../elements/container-element.js";
 import { RectangleElement } from "../elements/rectangle-element.js";
@@ -13,6 +13,8 @@ import { PaddingRenderer } from "./padding-renderer.js";
 import { DefaultTextStyleRenderer } from "./default-text-style-renderer.js";
 import { ImageRenderer } from "./image-renderer.js";
 import { LineRenderer } from "./line-renderer.js";
+import { SvgRenderer } from "./svg-renderer.js";
+import { CanvasRenderer } from "./canvas-renderer.js";
 import { RepeatingHeaderElement } from "../elements/layout/repeating-header-element.js";
 import { RepeatingHeaderRenderer } from "./repeating-header-renderer.js";
 import { DeferredElement } from "../elements/layout/deferred-element.js";
@@ -67,6 +69,8 @@ export class PDFRenderer {
         RendererRegistry.register(DefaultTextStyleElement, DefaultTextStyleRenderer.render);
         RendererRegistry.register(ImageElement, ImageRenderer.render);
         RendererRegistry.register(LineElement, LineRenderer.render);
+        RendererRegistry.register(SvgElement, SvgRenderer.render);
+        RendererRegistry.register(CanvasElement, CanvasRenderer.render);
         RendererRegistry.register(RepeatingHeaderElement, RepeatingHeaderRenderer.render);
         RendererRegistry.register(DeferredElement, DeferredRenderer.render);
         RendererRegistry.register(PositionedElement, PositionedRenderer.render);

package/dist/renderer/positioned-renderer.js

@@ -5,6 +5,6 @@ export class PositionedRenderer {
         // after the frame's flow content, so it paints on top.
         const { child } = positionedElement.getProps();
         const renderer = RendererRegistry.getRenderer(child);
-        return renderer ? renderer(child, objectManager) : [];
+        return renderer(child, objectManager);
     }
 }

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);
@@ -38,9 +44,7 @@ export class RectangleRenderer {
         if (children)
             for (const child of children) {
                 const renderer = RendererRegistry.getRenderer(child);
-                if (renderer) {
-                    nodes.push(...(await renderer(child, objectManager)));
-                }
+                nodes.push(...(await renderer(child, objectManager)));
             }
         if (clip)
             nodes.push({ type: "clip-pop" });

package/dist/renderer/repeating-header-renderer.js

@@ -5,8 +5,7 @@ export class RepeatingHeaderRenderer {
         const nodes = [];
         for (const child of [header, body]) {
             const renderer = RendererRegistry.getRenderer(child);
-            if (renderer)
-                nodes.push(...(await renderer(child, objectManager)));
+            nodes.push(...(await renderer(child, objectManager)));
         }
         return nodes;
     }

package/dist/renderer/rotated-renderer.js

@@ -22,7 +22,7 @@ export class RotatedRenderer {
             cy - sin * cx - cos * cy,
         ];
         const renderer = RendererRegistry.getRenderer(child);
-        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        const childNodes = await renderer(child, objectManager);
         // Wrap the child's drawing between a push (apply the matrix) and a pop (restore).
         return [{ type: "transform-push", matrix }, ...childNodes, { type: "transform-pop" }];
     }

package/dist/renderer/row-renderer.js

@@ -6,9 +6,7 @@ export class RowRenderer {
         if (children)
             for (const child of children) {
                 const renderer = RendererRegistry.getRenderer(child);
-                if (renderer) {
-                    nodes.push(...(await renderer(child, objectManager)));
-                }
+                nodes.push(...(await renderer(child, objectManager)));
             }
         return nodes;
     }

package/dist/renderer/struct-group-renderer.js

@@ -8,7 +8,7 @@ export class StructGroupRenderer {
         const { role, child } = group.getProps();
         const renderChild = async () => {
             const renderer = RendererRegistry.getRenderer(child);
-            return renderer ? await renderer(child, objectManager) : [];
+            return renderer(child, objectManager);
         };
         if (!objectManager.struct.enabled)
             return renderChild();

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

@@ -0,0 +1,11 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { SvgElement } from "../elements/svg-element.js";
+import type { IRNode } from "../ir/display-list.js";
+/**
+ * Turns the drawing into display-list nodes inside the box layout gave it. All the work is in
+ * `svg/`; this is only the seam, which is why an SVG needs no new IR primitive - the vector layer
+ * that colour emoji already draw through carries it.
+ */
+export declare class SvgRenderer {
+    static render(element: SvgElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/svg-renderer.js

@@ -0,0 +1,27 @@
+import { svgToIr } from "../svg/index.js";
+/**
+ * Turns the drawing into display-list nodes inside the box layout gave it. All the work is in
+ * `svg/`; this is only the seam, which is why an SVG needs no new IR primitive - the vector layer
+ * that colour emoji already draw through carries it.
+ */
+export class SvgRenderer {
+    static async render(element, objectManager) {
+        const { x, y, width, height, source, alt } = element.getProps();
+        const nodes = svgToIr(source, {
+            x: x ?? 0,
+            y: y ?? 0,
+            width: width ?? 0,
+            height: height ?? 0,
+        });
+        // Accessible tagging: a drawing WITH alt text is one Figure - every path of it belongs to the
+        // same struct element, which is what `openElement` keyed on `structId` gives us. Without alt it
+        // stays untagged and the backend treats it as decoration (an Artifact).
+        if (!alt || !objectManager.struct.enabled)
+            return nodes;
+        const tag = {
+            role: "Figure",
+            key: objectManager.struct.openElement(element.structId, "Figure", { alt }),
+        };
+        return nodes.map((node) => (node.type === "path" ? { ...node, tag } : 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;