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

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

@@ -0,0 +1,50 @@
+/**
+ * Where an underline and a strikethrough sit, and how thick they are.
+ *
+ * These are GLYPH metrics, and they are deliberately NOT part of `FontVerticals` in
+ * `line-metrics.ts`, which holds LINE metrics. Confusing the two is exactly what produced ISSUE-5:
+ * the AFM's `Ascender` (the height of a `b`) was used to seat a baseline, a job that belongs to the
+ * `FontBBox`. Keep the two kinds of number in two places so they cannot be mixed up again.
+ *
+ * Every number here comes out of the font: the standard-14 AFM header, or a TrueType `post` +
+ * `OS/2` table. Nothing is invented. Verified against `google-chrome --headless --print-to-pdf` on
+ * the same font: Chrome's strikethrough centre lands on `xHeight / 2` (measured 0.260 em vs the
+ * font's 0.262), and its underline stroke with `text-decoration-thickness: from-font` is the font's
+ * `underlineThickness` (0.048 em vs 0.050). Chrome does NOT use the font's underline POSITION - it
+ * has its own offset - so we follow the font there and land within 0.02 em of it.
+ */
+/** A font's decoration metrics, as fractions of the em. */
+export interface FontDecoration {
+    /** Distance BELOW the baseline to the CENTRE of the underline stroke. Positive.
+     *  (The AFM defines it as "the distance from the baseline for centering underlining strokes";
+     *  FreeType reads TrueType's `post.underlinePosition` the same way.) */
+    underlinePosition: number;
+    /** Stroke thickness, used by both the underline and the strikethrough. */
+    underlineThickness: number;
+    /** Height of a lowercase `x` above the baseline. Sets where a strikethrough crosses. */
+    xHeight: number;
+    /** Height of a capital above the baseline. */
+    capHeight: number;
+}
+/** A decoration stroke: the y of its centre line, and how thick it is. Points, engine coords. */
+export interface DecorationStroke {
+    y: number;
+    thickness: number;
+}
+/** The underline for a run whose baseline sits at `baselineY` (engine coords, y grows down). */
+export declare function underlineStroke(decoration: FontDecoration, fontSize: number, baselineY: number): DecorationStroke;
+/**
+ * The strikethrough for a run whose baseline sits at `baselineY`. It crosses at half the x-height,
+ * which is what a browser does and what looks right: through the middle of the lowercase letters,
+ * not through the middle of the capitals.
+ */
+export declare function strikethroughStroke(decoration: FontDecoration, fontSize: number, baselineY: number): DecorationStroke;
+/**
+ * Cuts `[0, runWidth]` at every place the glyphs put ink, leaving the segments an underline should
+ * actually draw. `inkSpans` are x-intervals in points from the start of the run.
+ *
+ * This is CSS `text-decoration-skip-ink`, and it needs the real glyph outlines - so it only works
+ * for an embedded font. Segments narrower than the padding are dropped: a sliver of a line between
+ * two descenders reads as dirt, not as an underline.
+ */
+export declare function skipInkSegments(runWidth: number, inkSpans: Array<[number, number]>, thickness: number): Array<[number, number]>;

package/dist/text/text-decoration.js

@@ -0,0 +1,62 @@
+/**
+ * Where an underline and a strikethrough sit, and how thick they are.
+ *
+ * These are GLYPH metrics, and they are deliberately NOT part of `FontVerticals` in
+ * `line-metrics.ts`, which holds LINE metrics. Confusing the two is exactly what produced ISSUE-5:
+ * the AFM's `Ascender` (the height of a `b`) was used to seat a baseline, a job that belongs to the
+ * `FontBBox`. Keep the two kinds of number in two places so they cannot be mixed up again.
+ *
+ * Every number here comes out of the font: the standard-14 AFM header, or a TrueType `post` +
+ * `OS/2` table. Nothing is invented. Verified against `google-chrome --headless --print-to-pdf` on
+ * the same font: Chrome's strikethrough centre lands on `xHeight / 2` (measured 0.260 em vs the
+ * font's 0.262), and its underline stroke with `text-decoration-thickness: from-font` is the font's
+ * `underlineThickness` (0.048 em vs 0.050). Chrome does NOT use the font's underline POSITION - it
+ * has its own offset - so we follow the font there and land within 0.02 em of it.
+ */
+/** The underline for a run whose baseline sits at `baselineY` (engine coords, y grows down). */
+export function underlineStroke(decoration, fontSize, baselineY) {
+    return {
+        y: baselineY + decoration.underlinePosition * fontSize,
+        thickness: decoration.underlineThickness * fontSize,
+    };
+}
+/**
+ * The strikethrough for a run whose baseline sits at `baselineY`. It crosses at half the x-height,
+ * which is what a browser does and what looks right: through the middle of the lowercase letters,
+ * not through the middle of the capitals.
+ */
+export function strikethroughStroke(decoration, fontSize, baselineY) {
+    return {
+        y: baselineY - (decoration.xHeight / 2) * fontSize,
+        thickness: decoration.underlineThickness * fontSize,
+    };
+}
+/**
+ * Horizontal breathing room left on each side of a descender that interrupts an underline. Unlike
+ * everything else in this file this is a DESIGN choice, not a number read from the font - so it is
+ * expressed in the one quantity the font does give us, the stroke thickness.
+ */
+const SKIP_INK_PADDING = 1.0;
+/**
+ * Cuts `[0, runWidth]` at every place the glyphs put ink, leaving the segments an underline should
+ * actually draw. `inkSpans` are x-intervals in points from the start of the run.
+ *
+ * This is CSS `text-decoration-skip-ink`, and it needs the real glyph outlines - so it only works
+ * for an embedded font. Segments narrower than the padding are dropped: a sliver of a line between
+ * two descenders reads as dirt, not as an underline.
+ */
+export function skipInkSegments(runWidth, inkSpans, thickness) {
+    const pad = SKIP_INK_PADDING * thickness;
+    const segments = [];
+    let cursor = 0;
+    for (const [start, end] of inkSpans) {
+        const gapStart = Math.max(0, start - pad);
+        const gapEnd = Math.min(runWidth, end + pad);
+        if (gapStart > cursor + pad)
+            segments.push([cursor, gapStart]);
+        cursor = Math.max(cursor, gapEnd);
+    }
+    if (runWidth > cursor + pad)
+        segments.push([cursor, runWidth]);
+    return segments;
+}

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

@@ -13,12 +13,22 @@ export interface ResolvedTextStyle {
     fontStyle: FontStyle;
     color: Color;
     textAlignment: HorizontalAlignment;
-    lineHeight: number;
+    /** Multiplier of the font size. `undefined` means the font's natural line height
+     *  (`ascent + descent + lineGap`), i.e. CSS `line-height: normal`. */
+    lineHeight?: number;
+    /** Draw a line under the text, at the position and thickness the font declares. */
+    underline: boolean;
+    /** Draw a line through the text, at half its x-height. */
+    strikethrough: boolean;
+    /** Let the underline step around descenders (CSS `text-decoration-skip-ink`). Needs an EMBEDDED
+     *  font: the standard-14 outlines live in the viewer, not in the AFM. */
+    skipInk: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Default 0. */
+    letterSpacing: number;
 }
 /**
  * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
- * property. These MUST match the historical `Text` defaults so a document that sets nothing renders
- * byte-for-byte as before.
+ * property.
  */
 export declare const DEFAULT_TEXT_STYLE: ResolvedTextStyle;
 /** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */

package/dist/text/text-style.js

@@ -3,8 +3,7 @@ import { FontStyle } from "../utils/pdf-object-manager.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
 /**
  * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
- * property. These MUST match the historical `Text` defaults so a document that sets nothing renders
- * byte-for-byte as before.
+ * property.
  */
 export const DEFAULT_TEXT_STYLE = {
     fontSize: 12,
@@ -12,7 +11,11 @@ export const DEFAULT_TEXT_STYLE = {
     fontStyle: FontStyle.Normal,
     color: new Color(0, 0, 0),
     textAlignment: HorizontalAlignment.left,
-    lineHeight: 1,
+    lineHeight: undefined,
+    underline: false,
+    strikethrough: false,
+    skipInk: false,
+    letterSpacing: 0,
 };
 /** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */
 export function mergeTextStyle(base, override) {
@@ -25,5 +28,9 @@ export function mergeTextStyle(base, override) {
         color: override.color ?? base.color,
         textAlignment: override.textAlignment ?? base.textAlignment,
         lineHeight: override.lineHeight ?? base.lineHeight,
+        underline: override.underline ?? base.underline,
+        strikethrough: override.strikethrough ?? base.strikethrough,
+        skipInk: override.skipInk ?? base.skipInk,
+        letterSpacing: override.letterSpacing ?? base.letterSpacing,
     };
 }

package/dist/utils/afm-parser.d.ts

@@ -1,12 +1,46 @@
+import type { FontVerticals } from "../text/line-metrics.js";
+import type { FontDecoration } from "../text/text-decoration.js";
 export declare class AFMParser {
     private advanceWidths;
     private kerningPairs;
     private glyphMap;
+    private bbox;
+    private cachedVerticals?;
+    private underlinePosition;
+    private underlineThickness;
+    private capHeight;
+    private xHeight;
+    private cachedDecoration?;
     constructor(afmData: string);
     private loadGlyphList;
     private getGlyphName;
     private parseAFMData;
     private parseCharMetrics;
+    /**
+     * The font's LINE metrics, as fractions of the em: how far a line box must reach above and below
+     * the baseline. Taken from the `FontBBox`.
+     *
+     * Not from the AFM's `Ascender` / `Descender` lines, and that distinction is the whole point.
+     * `Ascender 718` is a GLYPH metric - the height of `b`, `d`, `h` - and for Helvetica it happens to
+     * equal the cap height. The line-metric equivalent is TrueType's `hhea.ascent`, which is much
+     * taller because it has to clear the accented capitals: Arial declares 0.905 where its caps reach
+     * 0.716. That surplus above the caps (0.189) is about as large as the descent below the baseline
+     * (0.212), which is exactly why capitals look vertically centred in a browser.
+     *
+     * Helvetica's `FontBBox` is `-166 -225 1000 931`: 0.931 up, 0.225 down - within a hair of Arial's
+     * hhea numbers. So the bbox IS the standard-14 line metric, and there is no leftover slack to
+     * call a lineGap. (Seating the baseline at `Ascender` instead put every capital too high; see
+     * ISSUE-5.)
+     */
+    verticals(): FontVerticals;
+    /**
+     * The font's decoration metrics (underline / strikethrough), as fractions of the em.
+     *
+     * Symbol and ZapfDingbats declare no `CapHeight`/`XHeight` - they have no lowercase letters. For
+     * those the bbox top is the only height the font gives us, so the capitals reach it and a
+     * strikethrough crosses at half of that. Still read from the font, not guessed.
+     */
+    decoration(): FontDecoration;
     getAdvanceWidth(charName: string): number;
     getKerning(firstChar: string, secondChar: string): number;
 }

package/dist/utils/afm-parser.js

@@ -4,6 +4,15 @@ export class AFMParser {
         this.advanceWidths = {};
         this.kerningPairs = {};
         this.glyphMap = {};
+        // The font's bounding box in glyph space (1000 units / em), from the AFM header. This - not the
+        // `Ascender` line - is what a line box is built from; see `verticals()`.
+        this.bbox = [0, 0, 0, 0];
+        // Glyph metrics from the AFM header, for underline / strikethrough. All 14 standard fonts carry
+        // the underline pair; Symbol and ZapfDingbats have no CapHeight/XHeight (they have no lowercase).
+        this.underlinePosition = 0; // negative, as the AFM writes it: below the baseline
+        this.underlineThickness = 0;
+        this.capHeight = 0;
+        this.xHeight = 0;
         this.parseAFMData(afmData);
         this.loadGlyphList();
     }
@@ -25,6 +34,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) {
@@ -44,13 +54,31 @@ export class AFMParser {
                     this.advanceWidths[charName] = wx;
                 }
             }
+            if (line.startsWith("UnderlinePosition ")) {
+                this.underlinePosition = parseFloat(line.slice(18));
+            }
+            if (line.startsWith("UnderlineThickness ")) {
+                this.underlineThickness = parseFloat(line.slice(19));
+            }
+            if (line.startsWith("CapHeight ")) {
+                this.capHeight = parseFloat(line.slice(10));
+            }
+            if (line.startsWith("XHeight ")) {
+                this.xHeight = parseFloat(line.slice(8));
+            }
+            if (line.startsWith("FontBBox ")) {
+                const [x0, y0, x1, y1] = line.slice(9).trim().split(/\s+/).map(parseFloat);
+                this.bbox = [x0, y0, x1, y1];
+            }
             if (line.startsWith("KPX")) {
                 const parts = line.split(/\s+/);
                 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;
             }
         }
     }
@@ -71,11 +99,52 @@ export class AFMParser {
         }
         return null;
     }
+    /**
+     * The font's LINE metrics, as fractions of the em: how far a line box must reach above and below
+     * the baseline. Taken from the `FontBBox`.
+     *
+     * Not from the AFM's `Ascender` / `Descender` lines, and that distinction is the whole point.
+     * `Ascender 718` is a GLYPH metric - the height of `b`, `d`, `h` - and for Helvetica it happens to
+     * equal the cap height. The line-metric equivalent is TrueType's `hhea.ascent`, which is much
+     * taller because it has to clear the accented capitals: Arial declares 0.905 where its caps reach
+     * 0.716. That surplus above the caps (0.189) is about as large as the descent below the baseline
+     * (0.212), which is exactly why capitals look vertically centred in a browser.
+     *
+     * Helvetica's `FontBBox` is `-166 -225 1000 931`: 0.931 up, 0.225 down - within a hair of Arial's
+     * hhea numbers. So the bbox IS the standard-14 line metric, and there is no leftover slack to
+     * call a lineGap. (Seating the baseline at `Ascender` instead put every capital too high; see
+     * ISSUE-5.)
+     */
+    verticals() {
+        if (this.cachedVerticals)
+            return this.cachedVerticals;
+        const [, yMin, , yMax] = this.bbox;
+        this.cachedVerticals = { ascent: yMax / 1000, descent: -yMin / 1000, lineGap: 0 };
+        return this.cachedVerticals;
+    }
+    /**
+     * The font's decoration metrics (underline / strikethrough), as fractions of the em.
+     *
+     * Symbol and ZapfDingbats declare no `CapHeight`/`XHeight` - they have no lowercase letters. For
+     * those the bbox top is the only height the font gives us, so the capitals reach it and a
+     * strikethrough crosses at half of that. Still read from the font, not guessed.
+     */
+    decoration() {
+        if (this.cachedDecoration)
+            return this.cachedDecoration;
+        const capHeight = this.capHeight || this.bbox[3];
+        this.cachedDecoration = {
+            underlinePosition: -this.underlinePosition / 1000, // AFM writes it negative (below the baseline)
+            underlineThickness: this.underlineThickness / 1000,
+            capHeight: capHeight / 1000,
+            xHeight: (this.xHeight || capHeight / 2) / 1000,
+        };
+        return this.cachedDecoration;
+    }
     getAdvanceWidth(charName) {
         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/font-metrics.d.ts

@@ -1,4 +1,6 @@
 import type { FontStyle } from "./pdf-object-manager.js";
+import type { FontVerticals } from "../text/line-metrics.js";
+import type { FontDecoration } from "../text/text-decoration.js";
 /**
  * Read-only font measurement - the slice of the object manager that the layout pass
  * needs. Keeping layout (and, later, fragmentation) behind this interface means those
@@ -9,4 +11,16 @@ import type { FontStyle } from "./pdf-object-manager.js";
 export interface FontMetrics {
     getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle): number;
     getCharWidth(char: string, fontSize: number, fullFontName?: string, fontName?: string, fontStyle?: FontStyle): number;
+    /** Ascent / descent / lineGap of a face, in em fractions - the vertical counterpart of the widths
+     *  above. Drives the line box and the baseline (see `text/line-metrics.ts`). */
+    getFontVerticals(fontFamily: string, fontStyle: FontStyle): FontVerticals;
+    /** Underline / strikethrough geometry of a face, in em fractions. GLYPH metrics, deliberately kept
+     *  apart from the LINE metrics above (see `text/text-decoration.ts`). */
+    getFontDecoration(fontFamily: string, fontStyle: FontStyle): FontDecoration;
+    /** Whether kerning is on for this document. `runAdvance` reads it so a measured advance matches the
+     *  drawn one (the backend emits a `TJ` under the same flag). */
+    readonly kerningEnabled: boolean;
+    /** Per-adjacent-pair kerning of `text`, in em/1000 (negative tightens); length `codePoints - 1`,
+     *  zero next to a space. Only meaningful when `kerningEnabled`. */
+    getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle): number[];
 }

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`;
+    }
+}