@jasy/pdf 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/renderer/text-renderer.js

@@ -1,4 +1,7 @@
+import { Color } from "../common/color.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
+import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
+import { emojiImageNode } from "./emoji-image.js";
 import { wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.js";
 // Distance from the top of a line down to its baseline, as a fraction of the font
 // size. ~0.683 is the standard-14 ascent ratio used to seat the first baseline.
@@ -17,17 +20,200 @@ export class TextRenderer {
         return lines.reduce((total, line) => total + line.maxFontSize * lineHeight, 0);
     }
     static async render(textElement, objectManager) {
-        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, } = textElement.getProps();
+        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, role, } = textElement.getProps();
         // Component -> display list. Wrapping and positioning stay here; the backend
         // turns each run into BT/Tf/Td/Tj/ET. The wrapping algorithm is unchanged from
         // the original renderer - unifying it into the engine is Phase 3.
-        return TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight);
+        const { runs, links } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight);
+        // Accessible tagging: this whole text block is one structure element (a paragraph P, or a heading
+        // from `role`); each run's text lands under it. Emoji sub-nodes produced below stay untagged (drawn
+        // as artifacts). Keyed by structId so a block split across pages stays one element.
+        if (objectManager.struct.enabled) {
+            const pdfRole = role ? role.toUpperCase() : "P"; // "h1" -> "H1"; default paragraph
+            const key = objectManager.struct.openElement(textElement.structId, pdfRole);
+            for (const run of runs)
+                run.tag = { role: pdfRole, key };
+        }
+        // Color fonts (COLR/CPAL): expand each run's emoji into filled vector layers (or fetched images
+        // for an image emoji source); plain runs and monochrome fonts pass straight through unchanged.
+        const drawn = (await Promise.all(runs.map((run) => TextRenderer._expandColorGlyphs(run, objectManager)))).flat();
+        // Inline hyperlinks (href spans) ride along as /Link annotations - they draw nothing, so order
+        // vs the drawn runs does not matter; the page renderer peels them off into /Annots.
+        return links.length > 0 ? [...drawn, ...links] : drawn;
+    }
+    // Splits a text run into normal text sub-runs + filled `Path` layers for any COLR color glyphs,
+    // walking code point by code point and advancing the pen by each glyph's width. Returns `[run]`
+    // untouched when the font has no color glyphs (the common case).
+    static async _expandColorGlyphs(run, om) {
+        // The run's own font (if it's a color font) draws emoji directly; otherwise a document-level
+        // emoji source (`Document({ emoji })`) supplies them - a fallback FONT (color glyphs, native
+        // vector) or an IMAGE source (fetched emoji images) - for code points the run's font lacks, so
+        // `Text("Hallo 😅")` works in one string. No emoji source at all -> pass the run through.
+        const own = om.getColorFont(run.fontFamily, run.fontStyle);
+        const emojiName = om.getEmojiFont();
+        const fallback = emojiName && emojiName !== run.fontFamily
+            ? om.getColorFont(emojiName, run.fontStyle)
+            : undefined;
+        const imageSource = om.getEmojiImageSource();
+        if (!own && !fallback && !imageSource)
+            return [run];
+        const nodes = [];
+        let cursorX = run.x; // absolute x of the next glyph
+        let pending = ""; // run of consecutive non-color characters
+        let pendingX = run.x; // where that run started
+        const flushPending = () => {
+            if (pending) {
+                nodes.push({ ...run, x: pendingX, text: pending });
+                pending = "";
+            }
+        };
+        for (const ch of run.text) {
+            const cp = ch.codePointAt(0);
+            // Which color font renders this code point: the run's own font first, then the emoji fallback.
+            let source;
+            let layers = null;
+            if (own) {
+                const l = own.getColorGlyph(own.getGlyphIndex(cp));
+                if (l)
+                    [source, layers] = [own, l];
+            }
+            if (!layers && fallback) {
+                const l = fallback.getColorGlyph(fallback.getGlyphIndex(cp));
+                if (l)
+                    [source, layers] = [fallback, l];
+            }
+            // The advance matches measuring (getCharWidth applies the same emoji fallback).
+            const advance = om.getCharWidth(ch, run.fontSize, undefined, run.fontFamily, run.fontStyle);
+            if (source && layers) {
+                flushPending();
+                const scale = run.fontSize / source.unitsPerEm;
+                for (const layer of layers) {
+                    const commands = TextRenderer._glyphToPath(source.getGlyphPath(layer.glyphId), cursorX, run.y, scale, layer.transform);
+                    if (commands.length === 0)
+                        continue; // an empty layer outline draws nothing
+                    const paint = layer.paint;
+                    let fill;
+                    if (paint.type === "solid") {
+                        const c = paint.color;
+                        fill = c ? new Color(c.r, c.g, c.b, c.a / 255) : run.color; // null -> foreground
+                    }
+                    else {
+                        fill = TextRenderer._toGradient(paint, cursorX, run.y, scale, run.color, layer.transform);
+                    }
+                    nodes.push({ type: "path", commands, fill });
+                }
+            }
+            else if (imageSource && isEmojiCodePoint(cp)) {
+                // Image emoji source: fetch + embed a 1em square. The emoji breaks the text run either way;
+                // a failed fetch (offline/404) leaves a blank em gap (advance already applied) rather than
+                // drawing a broken glyph.
+                flushPending();
+                const node = await emojiImageNode(cp, imageSource, cursorX, run.y, run.fontSize);
+                if (node)
+                    nodes.push(node);
+            }
+            else {
+                if (!pending)
+                    pendingX = cursorX;
+                pending += ch;
+            }
+            cursorX += advance;
+        }
+        flushPending();
+        return nodes;
+    }
+    // Maps a glyph outline (font units, y-up) to absolute IR path commands at the pen origin, scaling
+    // by `scale` and flipping the axis into the engine's top-left space (the seam flips it once more
+    // to PDF space). TrueType quadratics become cubics: C1 = P0 + 2/3(C-P0), C2 = P1 + 2/3(C-P1).
+    static _glyphToPath(cmds, originX, baselineY, scale, transform) {
+        // Apply the layer's affine (font units) first, then scale to points, position at the pen origin
+        // and flip into engine space. `mapX`/`mapY` take BOTH glyph coords because an affine mixes them.
+        const [a, b, c, d, e, f] = transform ?? [1, 0, 0, 1, 0, 0];
+        const mapX = (gx, gy) => originX + (a * gx + c * gy + e) * scale;
+        const mapY = (gx, gy) => baselineY - (b * gx + d * gy + f) * scale;
+        const out = [];
+        let curX = 0;
+        let curY = 0;
+        for (const cmd of cmds) {
+            if (cmd.type === "M") {
+                curX = mapX(cmd.x, cmd.y);
+                curY = mapY(cmd.x, cmd.y);
+                out.push({ op: "m", x: curX, y: curY });
+            }
+            else if (cmd.type === "L") {
+                curX = mapX(cmd.x, cmd.y);
+                curY = mapY(cmd.x, cmd.y);
+                out.push({ op: "l", x: curX, y: curY });
+            }
+            else if (cmd.type === "Q") {
+                const ctrlX = mapX(cmd.cx, cmd.cy);
+                const ctrlY = mapY(cmd.cx, cmd.cy);
+                const endX = mapX(cmd.x, cmd.y);
+                const endY = mapY(cmd.x, cmd.y);
+                out.push({
+                    op: "c",
+                    x1: curX + (2 / 3) * (ctrlX - curX),
+                    y1: curY + (2 / 3) * (ctrlY - curY),
+                    x2: endX + (2 / 3) * (ctrlX - endX),
+                    y2: endY + (2 / 3) * (ctrlY - endY),
+                    x: endX,
+                    y: endY,
+                });
+                curX = endX;
+                curY = endY;
+            }
+            else {
+                out.push({ op: "z" });
+            }
+        }
+        return out;
+    }
+    // Maps a COLR v1 gradient paint (font-unit coordinates) into an IR `Gradient` positioned at the
+    // pen origin, using the SAME scale + baseline flip as the glyph outline so the gradient axis lines
+    // up with the shape. Radii scale uniformly (the em scale is uniform). A null stop color (the COLR
+    // "use foreground" sentinel) becomes the text color.
+    static _toGradient(paint, originX, baselineY, scale, foreground, transform) {
+        const [a, b, c, d, e, f] = transform ?? [1, 0, 0, 1, 0, 0];
+        const mapX = (gx, gy) => originX + (a * gx + c * gy + e) * scale;
+        const mapY = (gx, gy) => baselineY - (b * gx + d * gy + f) * scale;
+        // A radius has no single value under a general affine (a circle can shear into an ellipse); use
+        // the affine's geometric-mean scale sqrt(|det|) times the em scale - exact for uniform scaling.
+        const radiusScale = scale * Math.sqrt(Math.abs(a * d - b * c));
+        const stops = paint.stops.map((s) => ({
+            offset: s.offset,
+            color: s.color ? new Color(s.color.r, s.color.g, s.color.b, s.color.a / 255) : foreground,
+        }));
+        if (paint.type === "linearGradient") {
+            return {
+                type: "linear",
+                x0: mapX(paint.p0[0], paint.p0[1]),
+                y0: mapY(paint.p0[0], paint.p0[1]),
+                x1: mapX(paint.p1[0], paint.p1[1]),
+                y1: mapY(paint.p1[0], paint.p1[1]),
+                stops,
+                extend: paint.extend,
+            };
+        }
+        return {
+            type: "radial",
+            x0: mapX(paint.c0[0], paint.c0[1]),
+            y0: mapY(paint.c0[0], paint.c0[1]),
+            r0: paint.c0[2] * radiusScale,
+            x1: mapX(paint.c1[0], paint.c1[1]),
+            y1: mapY(paint.c1[0], paint.c1[1]),
+            r1: paint.c1[2] * radiusScale,
+            stops,
+            extend: paint.extend,
+        };
     }
     // Lay the content out into absolutely-positioned text runs. Glyph positions match
     // the previous hand-written operators exactly (verified by pixel-identical render);
     // only the output form changed from PDF strings to `TextRun`s.
     static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight = 1) {
         const runs = [];
+        // /Link annotation rects for any `href` spans, collected as we place segments. Empty for the
+        // common (no-href) case, so plain text keeps producing exactly the runs it did before.
+        const links = [];
         // Horizontal offset of a line of the given width under the current alignment.
         const alignmentOffset = (lineWidth) => {
             if (textAlignment === HorizontalAlignment.center)
@@ -68,7 +254,7 @@ export class TextRenderer {
                     color,
                 });
             });
-            return runs;
+            return { runs, links };
         }
         // --- Segments: break into lines (shared breaker), then emit one run per segment.
         // Segment 0 starts at the aligned line origin; each following segment is offset by
@@ -81,6 +267,7 @@ export class TextRenderer {
                 const family = segment.fontFamily || fontFamily;
                 const size = segment.fontSize || fontSize;
                 const style = segment.fontStyle || fontStyle;
+                const advance = advanceNoKerning(segment.content, family, size, style);
                 runs.push({
                     type: "text",
                     x,
@@ -91,7 +278,21 @@ export class TextRenderer {
                     fontSize: size,
                     color: segment.fontColor || color,
                 });
-                x += advanceNoKerning(segment.content, family, size, style);
+                // An href/to span becomes a /Link annotation over exactly this run's glyph box. `lineY` is the
+                // baseline; the box spans from the ascent (BASELINE_RATIO above it) down by the full size, so
+                // ascent + descent are covered. A span wrapped across lines yields one rect per line.
+                if (segment.href !== undefined || segment.dest !== undefined) {
+                    links.push({
+                        type: "link",
+                        x,
+                        y: lineY - size * BASELINE_RATIO,
+                        width: advance,
+                        height: size,
+                        href: segment.href,
+                        dest: segment.dest,
+                    });
+                }
+                x += advance;
             });
         };
         // The overall tallest font seats the first baseline; each line then steps DOWN by
@@ -111,6 +312,6 @@ export class TextRenderer {
             pushLine(line, lineY + halfLeading);
             lineY += line.maxFontSize * lineHeight;
         }
-        return runs;
+        return { runs, links };
     }
 }

package/dist/text/emoji-codepoints.d.ts

@@ -0,0 +1 @@
+export declare function isEmojiCodePoint(codePoint: number): boolean;

package/dist/text/emoji-codepoints.js

@@ -0,0 +1,29 @@
+// Whether a code point is (very likely) an emoji, used ONLY by the image/CDN emoji source: unlike a
+// font source, there is no font to ask "do you have a color glyph for this?", so we decide from the
+// well-known emoji blocks. This is a curated, dependency-free subset - it covers the emoji people
+// actually type, not the full Unicode Emoji property list, and intentionally errs toward the common
+// blocks. A font source does NOT use this (it asks the font).
+// [lo, hi] inclusive ranges of the main emoji / pictograph blocks.
+const RANGES = [
+    [0x1f000, 0x1faff], // Mahjong/Dominoes/Cards, Misc Symbols & Pictographs, Emoticons, Transport,
+    //                     Supplemental Symbols & Pictographs, Symbols & Pictographs Extended-A (incl. flags)
+    [0x2190, 0x21ff], // Arrows
+    [0x2300, 0x23ff], // Misc Technical (⌚ ⏰ ⏳, media controls)
+    [0x2460, 0x24ff], // Enclosed Alphanumerics (Ⓜ)
+    [0x25a0, 0x25ff], // Geometric Shapes (▪ ◼ ⬛)
+    [0x2600, 0x27bf], // Misc Symbols + Dingbats (☀ ★ ✂ ✅ ✈ ✉ ✊ ✋)
+    [0x2900, 0x297f], // Supplemental Arrows-B (⤴ ⤵)
+    [0x2b00, 0x2bff], // Misc Symbols and Arrows (⭐ ⬅ ⬛)
+    [0x3000, 0x303f], // CJK Symbols and Punctuation (〰 〽)
+    [0x3200, 0x32ff], // Enclosed CJK Letters and Months (㊗ ㊙)
+];
+// Emoji-presentation singletons outside the ranges above.
+const SINGLES = new Set([0x00a9, 0x00ae, 0x203c, 0x2049, 0x2122, 0x2139, 0xfe0f]);
+export function isEmojiCodePoint(codePoint) {
+    if (SINGLES.has(codePoint))
+        return true;
+    for (const [lo, hi] of RANGES)
+        if (codePoint >= lo && codePoint <= hi)
+            return true;
+    return false;
+}

package/dist/text/line-breaker.js

@@ -133,9 +133,12 @@ function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics) {
         if (fits(words.join(" ")))
             return words.join(" ") + ELLIPSIS;
     }
-    let single = words[0] ?? "";
-    while (single.length > 1) {
-        single = single.slice(0, -1);
+    // Drop one code point at a time (not one UTF-16 unit) so an astral char is never split into a
+    // lone surrogate. `chars` is the code-point view; rebuild the string from its shrinking prefix.
+    const chars = [...(words[0] ?? "")];
+    while (chars.length > 1) {
+        chars.pop();
+        const single = chars.join("");
         if (fits(single))
             return single + ELLIPSIS;
     }

package/dist/utils/afm-parser.js

@@ -25,6 +25,7 @@ export class AFMParser {
         return this.glyphMap[char] || char;
     }
     parseAFMData(afmData) {
+        var _a;
         const lines = afmData.split("\n");
         let inCharMetrics = false;
         for (let line of lines) {
@@ -49,8 +50,10 @@ export class AFMParser {
                 const firstChar = parts[1];
                 const secondChar = parts[2];
                 const kerning = parseFloat(parts[3]);
-                const pair = `${firstChar}-${secondChar}`;
-                this.kerningPairs[pair] = kerning;
+                // Nested by first glyph, then second. A flat `${a}-${b}` key would have to be BUILT on every
+                // lookup, and getKerning runs once per adjacent character pair - that string allocation was a
+                // quarter of a standard-font render.
+                ((_a = this.kerningPairs)[firstChar] ?? (_a[firstChar] = {}))[secondChar] = kerning;
             }
         }
     }
@@ -75,7 +78,6 @@ export class AFMParser {
         return this.advanceWidths[this.getGlyphName(charName)] || 0;
     }
     getKerning(firstChar, secondChar) {
-        const pair = `${firstChar}-${secondChar}`;
-        return this.kerningPairs[pair] || 0;
+        return this.kerningPairs[firstChar]?.[secondChar] ?? 0;
     }
 }

package/dist/utils/dest-registry.d.ts

@@ -0,0 +1,19 @@
+interface Dest {
+    pageObjNum: number;
+    top: number;
+}
+/**
+ * Collects named destinations - the jump targets an internal `Link({ to })` points at, declared with
+ * `Anchor({ name })`. `finalize` emits the `/Dests` name-tree fragment for the catalog `/Names` dict, or
+ * "" when no anchor was placed. Names are strings the viewer resolves at click time, so a link can point
+ * at an anchor on a later (not-yet-rendered) page without any forward-reference bookkeeping.
+ */
+export declare class DestRegistry {
+    private dests;
+    add(name: string, dest: Dest): void;
+    get isEmpty(): boolean;
+    /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it. */
+    finalize(): string;
+}
+export {};

package/dist/utils/dest-registry.js

@@ -0,0 +1,32 @@
+// A PDF literal string escape (backslash first, then the string delimiters).
+const esc = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+const num = (n) => (Number.isFinite(n) ? Number(n.toFixed(2)) : 0);
+/**
+ * Collects named destinations - the jump targets an internal `Link({ to })` points at, declared with
+ * `Anchor({ name })`. `finalize` emits the `/Dests` name-tree fragment for the catalog `/Names` dict, or
+ * "" when no anchor was placed. Names are strings the viewer resolves at click time, so a link can point
+ * at an anchor on a later (not-yet-rendered) page without any forward-reference bookkeeping.
+ */
+export class DestRegistry {
+    constructor() {
+        // Keyed by name so a duplicate name resolves to its last definition (last anchor wins).
+        this.dests = new Map();
+    }
+    add(name, dest) {
+        this.dests.set(name, dest);
+    }
+    get isEmpty() {
+        return this.dests.size === 0;
+    }
+    /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it. */
+    finalize() {
+        if (this.dests.size === 0)
+            return "";
+        const entries = [...this.dests.keys()].sort().map((name) => {
+            const d = this.dests.get(name);
+            return `(${esc(name)}) [${d.pageObjNum} 0 R /XYZ null ${num(d.top)} null]`;
+        });
+        return `/Dests << /Names [ ${entries.join(" ")} ] >>`;
+    }
+}

package/dist/utils/flex-layout.d.ts

@@ -12,18 +12,25 @@ export type CrossAlign = "start" | "center" | "end" | "stretch";
  * (main = width). "main" is the stacking direction; "cross" is perpendicular.
  */
 export interface FlexAxis {
+    /** Whether the MAIN (stacking) axis is horizontal - i.e. this is a Row. Used to ask a child for the
+     *  right relative-size factor (width vs height) when resolving a percentage child. */
+    mainHorizontal: boolean;
     mainOf(size: Size): number;
     crossOf(size: Size): number;
     /**
-     * Constraints for a fixed child: the main extent is unbounded (it takes its natural
-     * size); the cross extent is ALWAYS capped to what the line offers. The cap is a hard
+     * Constraints for a fixed child: the main extent is unbounded by default (the child takes its
+     * natural size); the cross extent is ALWAYS capped to what the line offers. The cap is a hard
      * ceiling regardless of `cross` alignment - it is what guarantees nothing ever overflows
      * (a paragraph wraps at the column width instead of running one line off the page). A
      * child smaller than the cap keeps its size and is positioned by `crossOffset`; a child
      * that wants to fill (Container, Text) fills the cap. So `stretch` vs `start/center/end`
      * differ only in where a smaller child sits, never in the ceiling.
+     *
+     * `mainMax` bounds the main axis too (default unbounded): passed only for a PERCENTAGE child, so its
+     * `width: "50%"` can resolve against the space the line offers its items. A plain child keeps the
+     * unbounded main axis and shrink-wraps as before.
      */
-    measureConstraints(crossAvail: number): BoxConstraints;
+    measureConstraints(crossAvail: number, mainMax?: number): BoxConstraints;
     /** Constraints for a flex child (fills the cross axis like a stretched child). */
     flexConstraints(mainExtent: number, crossAvail: number): BoxConstraints;
     /** Absolute offset for a child at main position `mainPos`, cross position `crossPos`. */

package/dist/utils/flex-layout.js

@@ -1,16 +1,18 @@
 import { FlexiblePDFElement } from "../elements/pdf-element.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
 export const VERTICAL_AXIS = {
+    mainHorizontal: false,
     mainOf: (s) => s.height,
     crossOf: (s) => s.width,
-    measureConstraints: (crossAvail) => BoxConstraints.loose(crossAvail, Infinity),
+    measureConstraints: (crossAvail, mainMax = Infinity) => BoxConstraints.loose(crossAvail, mainMax),
     flexConstraints: (mainExtent, crossAvail) => BoxConstraints.loose(crossAvail, mainExtent),
     offsetAt: (mainPos, crossPos) => ({ x: crossPos, y: mainPos }),
 };
 export const HORIZONTAL_AXIS = {
+    mainHorizontal: true,
     mainOf: (s) => s.width,
     crossOf: (s) => s.height,
-    measureConstraints: (crossAvail) => BoxConstraints.loose(Infinity, crossAvail),
+    measureConstraints: (crossAvail, mainMax = Infinity) => BoxConstraints.loose(mainMax, crossAvail),
     flexConstraints: (mainExtent, crossAvail) => BoxConstraints.loose(mainExtent, crossAvail),
     offsetAt: (mainPos, crossPos) => ({ x: mainPos, y: crossPos }),
 };
@@ -37,6 +39,22 @@ export class FlexLayoutHelper {
         const main = options.main ?? "start";
         const cross = options.cross ?? "stretch";
         const count = children.length;
+        const totalGap = Math.max(0, count - 1) * gap;
+        // The main extent a percentage child resolves against: the line's own extent minus the gaps
+        // between the items. So N children at (100/N)% + gaps fit exactly, instead of overflowing by the
+        // gaps (the flexbox `width: 33%` + gap trap). Only finite when the line's main axis is bounded -
+        // a fraction of an unbounded main axis has no meaning, so `%` children fall back to shrink-wrap.
+        const percentBase = mainAvail !== Infinity ? Math.max(0, mainAvail - totalGap) : Infinity;
+        // The main cap to hand a child: `percentBase` for a percentage child (so its fraction resolves) and
+        // for a child that cannot lay itself out without a bound (a nested stack holding an `Expanded`/
+        // `Spacer`); unbounded for everyone else, who keep their natural size and never fill the line.
+        const mainCapFor = (child) => {
+            if (percentBase === Infinity)
+                return Infinity;
+            const needsBound = child.relativeSizeFactor(axis.mainHorizontal) !== undefined ||
+                child.needsBoundedMain(axis.mainHorizontal);
+            return needsBound ? percentBase : Infinity;
+        };
         // Pass 1: measure the fixed children (main extent + cross size) and total the flex.
         let fixedMain = 0;
         let totalFlex = 0;
@@ -47,15 +65,17 @@ export class FlexLayoutHelper {
                 totalFlex += child.getFlex();
             }
             else {
-                const size = child.calculateLayout(axis.measureConstraints(crossAvail), axis.offsetAt(mainStart, crossOrigin), ctx);
+                const size = child.calculateLayout(axis.measureConstraints(crossAvail, mainCapFor(child)), axis.offsetAt(mainStart, crossOrigin), ctx);
                 fixedMain += axis.mainOf(size);
                 crossUsed = Math.max(crossUsed, axis.crossOf(size));
                 fixedSize.set(child, size);
             }
         }
-        const totalGap = Math.max(0, count - 1) * gap;
         const leftover = mainAvail - fixedMain - totalGap;
-        const remaining = Math.max(leftover, 0); // for flex children
+        // A flex child on an UNBOUNDED main axis has no leftover space to claim. It must collapse to zero,
+        // never to `Infinity`: an infinite extent would become the offset of every following sibling and get
+        // written into the content stream verbatim, silently corrupting the page from that point on.
+        const remaining = Number.isFinite(leftover) ? Math.max(leftover, 0) : 0;
         // Main-axis distribution only kicks in with no flex child and bounded, positive space.
         let leadingSpace = 0;
         let betweenSpace = gap;
@@ -101,7 +121,7 @@ export class FlexLayoutHelper {
             }
             else {
                 const childCross = axis.crossOf(fixedSize.get(child));
-                const size = child.calculateLayout(axis.measureConstraints(stretch ? crossExtent : crossAvail), axis.offsetAt(mainPos, crossOrigin + crossOffset(cross, crossExtent, childCross)), ctx);
+                const size = child.calculateLayout(axis.measureConstraints(stretch ? crossExtent : crossAvail, mainCapFor(child)), axis.offsetAt(mainPos, crossOrigin + crossOffset(cross, crossExtent, childCross)), ctx);
                 mainExtent = axis.mainOf(size);
                 placedCross = Math.max(placedCross, axis.crossOf(size));
             }

package/dist/utils/outline.d.ts

@@ -0,0 +1,21 @@
+import type { PDFObjectManager } from "./pdf-object-manager.js";
+interface Entry {
+    title: string;
+    level: number;
+    pageObjNum: number;
+    top: number;
+}
+/**
+ * Builds the PDF document outline (`/Outlines`) - the viewer's bookmark panel. Entries are collected
+ * flat in reading order with a 1-based `level`; `finalize` nests each entry under the nearest preceding
+ * entry of a smaller level (so level 2s hang under the last level 1), emits the outline objects and
+ * returns the catalog addition `/Outlines N 0 R`. A no-op returning "" when nothing was added, so a
+ * document without bookmarks stays byte-identical.
+ */
+export declare class OutlineBuilder {
+    private entries;
+    add(entry: Entry): void;
+    get isEmpty(): boolean;
+    finalize(om: PDFObjectManager): string;
+}
+export {};

package/dist/utils/outline.js

@@ -0,0 +1,80 @@
+// A PDF literal string escape (same rule as elsewhere): backslash first, then the string delimiters.
+const esc = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+const num = (n) => Number(n.toFixed(2));
+/**
+ * Builds the PDF document outline (`/Outlines`) - the viewer's bookmark panel. Entries are collected
+ * flat in reading order with a 1-based `level`; `finalize` nests each entry under the nearest preceding
+ * entry of a smaller level (so level 2s hang under the last level 1), emits the outline objects and
+ * returns the catalog addition `/Outlines N 0 R`. A no-op returning "" when nothing was added, so a
+ * document without bookmarks stays byte-identical.
+ */
+export class OutlineBuilder {
+    constructor() {
+        this.entries = [];
+    }
+    add(entry) {
+        this.entries.push(entry);
+    }
+    get isEmpty() {
+        return this.entries.length === 0;
+    }
+    finalize(om) {
+        if (this.entries.length === 0)
+            return "";
+        // Nest by level: a stack where stack[i] is the last open node at level i+1. An entry at level L
+        // becomes a child of stack[L-2] (the enclosing smaller level), or a root when L is 1. Levels that
+        // skip a step (1 -> 3) are clamped to one deeper than the current stack so nothing is orphaned.
+        const roots = [];
+        const stack = [];
+        for (const e of this.entries) {
+            const level = Math.max(1, Math.min(e.level, stack.length + 1));
+            stack.length = level - 1; // pop back to this entry's parent depth
+            const node = { ...e, children: [] };
+            if (level === 1)
+                roots.push(node);
+            else
+                stack[level - 2].children.push(node);
+            stack[level - 1] = node;
+        }
+        // Reserve an object number for every node up front - parent/child/prev/next all cross-reference.
+        const objOf = new Map();
+        const walk = (nodes) => {
+            for (const n of nodes) {
+                objOf.set(n, om.addObject(""));
+                walk(n.children);
+            }
+        };
+        walk(roots);
+        const rootNum = om.addObject(""); // the /Outlines dictionary itself
+        // Count of all descendants of a node (used for the /Count of an open item, which shows them all).
+        const descendantCount = (n) => n.children.reduce((sum, c) => sum + 1 + descendantCount(c), 0);
+        const totalCount = roots.reduce((sum, r) => sum + 1 + descendantCount(r), 0);
+        // Emit each item dict, wired to its parent, siblings (prev/next) and first/last child.
+        const emit = (nodes, parentNum) => {
+            nodes.forEach((n, i) => {
+                const parts = [`/Title (${esc(n.title)})`, `/Parent ${parentNum} 0 R`];
+                if (i > 0)
+                    parts.push(`/Prev ${objOf.get(nodes[i - 1])} 0 R`);
+                if (i < nodes.length - 1)
+                    parts.push(`/Next ${objOf.get(nodes[i + 1])} 0 R`);
+                if (n.children.length > 0) {
+                    parts.push(`/First ${objOf.get(n.children[0])} 0 R`);
+                    parts.push(`/Last ${objOf.get(n.children[n.children.length - 1])} 0 R`);
+                    parts.push(`/Count ${descendantCount(n)}`); // positive = shown open
+                }
+                // /Dest: jump to this page, scrolling the target's top into view; null left/zoom keep the
+                // viewer's current horizontal position and magnification. Guard the top: a non-finite value
+                // (e.g. a bookmark under a Spacer in an unbounded column) would emit invalid PDF, so fall back
+                // to the page top (0 flips to the page top edge).
+                const top = Number.isFinite(n.top) ? num(n.top) : 0;
+                parts.push(`/Dest [${n.pageObjNum} 0 R /XYZ null ${top} null]`);
+                om.replaceObject(objOf.get(n), `<< ${parts.join(" ")} >>`);
+                emit(n.children, objOf.get(n));
+            });
+        };
+        emit(roots, rootNum);
+        om.replaceObject(rootNum, `<< /Type /Outlines /First ${objOf.get(roots[0])} 0 R ` +
+            `/Last ${objOf.get(roots[roots.length - 1])} 0 R /Count ${totalCount} >>`);
+        return `/Outlines ${rootNum} 0 R`;
+    }
+}