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

package/dist/text/whitespace.js

@@ -0,0 +1,43 @@
+/**
+ * A character with no glyph is still ENCODED and DRAWN: it comes out as the font's .notdef box, and
+ * veraPDF rejects the file for referencing .notdef (ISO 19005-3, 6.2.11.8). A `\n` in an invoice
+ * description was the first case we hit; zero-width characters are the same fault and arrive far more
+ * quietly - a paste out of Word or a web page carries them routinely.
+ *
+ * So nothing invisible survives into the breaker except `\n`, and that only because the breaker treats
+ * it as a hard break. The mapping follows a browser's `white-space: normal` apart from `\n`: CSS
+ * collapses that to a space, while a text COMPONENT breaks on it - Flutter's `Text` and react-pdf both
+ * do, and it is what anyone writing `"a\nb"` expects.
+ */
+/**
+ * Everything that MEANS a line break, matched as a WHOLE so a two-character ending never becomes two
+ * breaks. `\n\r` is in here beside `\r\n` because it is what a mistyped CRLF looks like, and a stray
+ * blank line is a worse answer than reading it as the one break it was meant to be. U+2028/U+2029 are
+ * Unicode's own line and paragraph separators.
+ */
+const LINE_BREAKS = /\r\n|\n\r|\r|\u2028|\u2029/g;
+/**
+ * Invisible and inert: a zero-width space and a byte-order mark carry no meaning we act on, so they are
+ * dropped rather than drawn. C0, C1 and DEL likewise.
+ *
+ * Deliberately NOT here: U+200C/U+200D (zero-width non-joiner and joiner) drive Arabic shaping and
+ * emoji sequences, and U+200E/U+200F (the bidi marks) drive `text/bidi.ts`. Dropping those would
+ * silently change how correct text is laid out - worse than the box they can still leave behind in a
+ * run that neither shapes nor reorders.
+ */
+// oxlint-disable-next-line no-control-regex -- matching control characters is the whole point here.
+const UNPRINTABLE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u200B\uFEFF]/g;
+export function normalizeWhitespace(text) {
+    return (text
+        // Every spelling of a break becomes `\n` first, so the breaker only ever sees one form.
+        .replace(LINE_BREAKS, "\n")
+        // A tab is collapsible whitespace; a PDF text operator has no tab stops to advance to.
+        .replace(/\t/g, " ")
+        .replace(UNPRINTABLE, ""));
+}
+/** The same, for content that may already be split into styled spans. */
+export function normalizeContent(content) {
+    if (typeof content === "string")
+        return normalizeWhitespace(content);
+    return content.map((seg) => ({ ...seg, content: normalizeWhitespace(seg.content) }));
+}

package/dist/text/word-splitting.d.ts

@@ -0,0 +1,42 @@
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+/**
+ * What to do with a word that is wider than the box it has to fit in.
+ *
+ * Until now: nothing. It stayed on its line and drew straight over whatever was beside it - which on an
+ * invoice means a mandatory field (§14 UStG) painted across its own label. CSS overflows too, so this
+ * was never a bug; it was a missing feature, and it is the one that bites in German.
+ *
+ * Two layers, and they are NOT alternatives - CSS stacks them the same way:
+ *
+ *   1. HYPHENATION splits a word at a linguistically valid point and marks it with a hyphen:
+ *      `Rechtsschutzver-` / `sicherungsgesellschaften`. It needs language knowledge, which is why it is
+ *      PLUGGABLE rather than bundled - no pattern data in this package, no licence question, nothing
+ *      added to a bundle that never asks for it.
+ *   2. BREAK-WORD is the floor: split wherever the box ends, no hyphen. It is what handles the things
+ *      hyphenation cannot touch - an e-mail address, an IBAN, an invoice number. Those are single
+ *      "words" with no valid point anywhere, and they are exactly what an invoice is full of.
+ *
+ * With both on, hyphenation is tried first and break-word catches what it cannot split.
+ */
+/** Splits one word into its hyphenation points, e.g. `["Rechts", "schutz", "ver", "siche", ...]`. */
+export type Hyphenator = (word: string) => string[];
+export interface WordSplitting {
+    /** Language-aware splitting, with a hyphen at the break. Supply `hyphen`, `hyphenopoly`, your own. */
+    hyphenate?: Hyphenator;
+    /** Split anywhere as a last resort, without a hyphen. CSS `overflow-wrap: break-word`. */
+    breakWord?: boolean;
+}
+/**
+ * Splits `word` into pieces that each fit within `room`. Returns null when nothing applies - no
+ * splitting configured, or the word fits anyway - and the caller keeps its current behaviour, so a
+ * document that asks for neither is untouched.
+ *
+ * Every piece but the last is a finished line. The last is what carries on, so the caller keeps
+ * filling it as usual.
+ */
+export declare function splitLongWord(word: string, room: number, font: {
+    fontFamily: string;
+    fontSize: number;
+    fontStyle: FontStyle;
+}, metrics: FontMetrics, letterSpacing: number, options: WordSplitting): string[] | null;

package/dist/text/word-splitting.js

@@ -0,0 +1,72 @@
+import { runAdvance } from "./advance.js";
+/** The hyphen actually drawn at a hyphenation break. U+002D, in every font we can encode. */
+const HYPHEN = "-";
+/**
+ * Splits `word` into pieces that each fit within `room`. Returns null when nothing applies - no
+ * splitting configured, or the word fits anyway - and the caller keeps its current behaviour, so a
+ * document that asks for neither is untouched.
+ *
+ * Every piece but the last is a finished line. The last is what carries on, so the caller keeps
+ * filling it as usual.
+ */
+export function splitLongWord(word, room, font, metrics, letterSpacing, options) {
+    const { hyphenate, breakWord } = options;
+    if (!hyphenate && !breakWord)
+        return null;
+    if (room <= 0)
+        return null;
+    if (runAdvance(metrics, word, font, letterSpacing) <= room)
+        return null;
+    const width = (s) => runAdvance(metrics, s, font, letterSpacing);
+    const pieces = [];
+    let rest = word;
+    // Bounded by construction: every pass either emits a piece and shortens `rest`, or gives up.
+    while (width(rest) > room) {
+        // The layering: a linguistically valid split if one is offered and reaches far enough, otherwise
+        // the blunt one - which is what an e-mail address or an IBAN needs, having no valid point at all.
+        const head = (hyphenate ? longestHyphenatedPrefix(rest, room, width, hyphenate) : null) ??
+            (breakWord ? longestPrefix(rest, room, width) : null);
+        // Nothing fits - not even one character, or hyphenation found nothing and break-word is off.
+        // Leave the remainder whole and let it overflow, exactly as before.
+        if (head === null)
+            break;
+        pieces.push(head.text);
+        rest = head.rest;
+    }
+    if (pieces.length === 0)
+        return null;
+    return [...pieces, rest];
+}
+/** The longest prefix that fits, plus a hyphen - split only where the hyphenator allows. */
+function longestHyphenatedPrefix(word, room, width, hyphenate) {
+    const parts = hyphenate(word);
+    if (parts.length < 2)
+        return null;
+    let taken = "";
+    let best = null;
+    for (let i = 0; i < parts.length - 1; i++) {
+        taken += parts[i];
+        // The hyphen has to fit too, or the line it lands on overflows by exactly that hyphen.
+        if (width(taken + HYPHEN) > room)
+            break;
+        best = { text: taken + HYPHEN, rest: parts.slice(i + 1).join("") };
+    }
+    return best;
+}
+/** The longest prefix that fits, split anywhere. Code points, so an astral character stays whole. */
+function longestPrefix(word, room, width) {
+    const chars = [...word];
+    let taken = "";
+    let count = 0;
+    for (const char of chars) {
+        if (width(taken + char) > room)
+            break;
+        taken += char;
+        count += 1;
+    }
+    // Not even one character fits: the box is narrower than a single glyph. Splitting cannot help, and
+    // looping on it would never terminate.
+    if (count === 0 || count === chars.length)
+        return null;
+    return { text: taken, rest: chars.slice(count).join("") };
+}

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

@@ -2,10 +2,8 @@ import { PDFElement, LayoutContext } from "../elements/pdf-element.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 /** Distribution of the children ALONG the stacking (main) axis when there is leftover
  *  space and no flex child to absorb it. */
-export type MainAlign = "start" | "center" | "end" | "between" | "around";
-/** Position/size of each child ACROSS the cross axis. `stretch` fills the cross extent;
- *  the others place the child at its natural cross size. */
-export type CrossAlign = "start" | "center" | "end" | "stretch";
+export type { MainAlign, CrossAlign } from "../layout/alignment.js";
+import type { CrossAlign, MainAlign } from "../layout/alignment.js";
 /**
  * Maps the abstract MAIN/CROSS axes onto concrete width/height + x/y, so one flex
  * algorithm drives both a vertical Column (main = height) and a horizontal Row
@@ -42,6 +40,12 @@ export interface FlexOptions {
     gap?: number;
     main?: MainAlign;
     cross?: CrossAlign;
+    /** Lay the children out along the main axis backwards (CSS `row-reverse` / `column-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap: wrap`). */
+    wrap?: boolean;
+    /** How the BLOCK of wrapped lines sits across the axis (CSS `align-content`). Default `start`. */
+    alignContent?: MainAlign;
 }
 export declare class FlexLayoutHelper {
     /**
@@ -53,8 +57,24 @@ export declare class FlexLayoutHelper {
      * extent occupied. Vertical with `gap 0`, `main start`, `cross stretch` reproduces the
      * previous Column layout exactly.
      */
+    /**
+     * Lays out the children along `axis`, on one line or several.
+     *
+     * Without `wrap` this is the single-line engine and nothing about it changed - the call goes
+     * straight through, which is what keeps every existing document byte-identical. With `wrap` the
+     * children are split into lines first and the SAME engine runs once per line.
+     */
     static layout(children: PDFElement[], axis: FlexAxis, mainAvail: number, crossAvail: number, mainStart: number, crossOrigin: number, options: FlexOptions, ctx: LayoutContext): {
         mainUsed: number;
         crossUsed: number;
     };
+    /**
+     * The wrapping path: split into lines, lay each one out, then place the lines across the axis.
+     *
+     * Lines are laid out TWICE - once to learn how tall each is, once at its final cross position. That
+     * is the same measure-then-place shape the single-line engine already uses, and it is what
+     * `alignContent` needs: the block of lines can only be centred once its total is known.
+     */
+    private static layoutWrapped;
+    private static layoutLine;
 }

package/dist/utils/flex-layout.js

@@ -24,6 +24,20 @@ function crossOffset(align, crossExtent, childCross) {
         return Math.max(0, crossExtent - childCross);
     return 0; // start, stretch (stretch fills, so no offset)
 }
+/**
+ * The order children are LAID OUT in: by `order` (lowest first, ties keeping source order), then
+ * reversed if the container asks for it. The element tree itself is never touched, so the reading order
+ * a tagged PDF exposes stays the source order - which is what CSS says too.
+ *
+ * `sort` is stable in every engine we target, so equal `order` values keep their source positions and a
+ * container where nobody sets one comes back with the identical array.
+ */
+function inLayoutOrder(children, reverse) {
+    const ordered = children.some((c) => c.order !== 0)
+        ? [...children].sort((a, b) => a.order - b.order)
+        : children;
+    return reverse ? [...ordered].reverse() : ordered;
+}
 export class FlexLayoutHelper {
     /**
      * Lays out a flex line along `axis`, IN SOURCE ORDER, and places every child.
@@ -34,10 +48,113 @@ export class FlexLayoutHelper {
      * extent occupied. Vertical with `gap 0`, `main start`, `cross stretch` reproduces the
      * previous Column layout exactly.
      */
+    /**
+     * Lays out the children along `axis`, on one line or several.
+     *
+     * Without `wrap` this is the single-line engine and nothing about it changed - the call goes
+     * straight through, which is what keeps every existing document byte-identical. With `wrap` the
+     * children are split into lines first and the SAME engine runs once per line.
+     */
     static layout(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
+        if (!options.wrap || children.length === 0 || !Number.isFinite(mainAvail)) {
+            // An unbounded main axis has no edge to wrap at, so wrapping there is meaningless, not an error.
+            return FlexLayoutHelper.layoutLine(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx);
+        }
+        return FlexLayoutHelper.layoutWrapped(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx);
+    }
+    /**
+     * The wrapping path: split into lines, lay each one out, then place the lines across the axis.
+     *
+     * Lines are laid out TWICE - once to learn how tall each is, once at its final cross position. That
+     * is the same measure-then-place shape the single-line engine already uses, and it is what
+     * `alignContent` needs: the block of lines can only be centred once its total is known.
+     */
+    static layoutWrapped(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
+        const gap = options.gap ?? 0;
+        const ordered = inLayoutOrder(children, options.reverse ?? false);
+        // Which children share a line. A child is measured at its natural main extent; a flex child
+        // contributes its BASIS, which is 0 unless it asked for one - so it never forces a break by itself.
+        // A child's natural main extent. A PERCENTAGE child has no fixed answer: its size depends on how
+        // many gaps the line ends up with, which depends on who is on it. So it is asked again for every
+        // candidate membership below rather than measured once.
+        // A plain child's extent does not depend on the line, so it is laid out ONCE and remembered.
+        // Without this each membership probe re-lays every child already on the line - O(n^2) subtree
+        // layouts, which is expensive the moment those children hold a Table or a wrapping paragraph.
+        const measured = new Map();
+        const naturalMain = (child, base) => {
+            if (child instanceof FlexiblePDFElement)
+                return child.getBasis(base);
+            const factor = child.relativeSizeFactor(axis.mainHorizontal);
+            if (factor !== undefined)
+                return base * factor;
+            const cached = measured.get(child);
+            if (cached !== undefined)
+                return cached;
+            // Measured UNCAPPED, the same way the single-line engine measures a plain child. Handing the
+            // line width in as a cap would silently squash a child wider than the line - CSS lets such a
+            // child overflow, and so does our own non-wrapping path.
+            const needsBound = child.needsBoundedMain(axis.mainHorizontal);
+            const main = axis.mainOf(child.calculateLayout(axis.measureConstraints(crossAvail, needsBound ? mainAvail : Infinity), axis.offsetAt(mainStart, crossOrigin), ctx));
+            measured.set(child, main);
+            return main;
+        };
+        /** What a line of these children would occupy, resolving every `%` against ITS gap count. */
+        const lineExtent = (members) => {
+            const gaps = Math.max(0, members.length - 1) * gap;
+            const base = Math.max(0, mainAvail - gaps);
+            return members.reduce((n, c) => n + naturalMain(c, base), 0) + gaps;
+        };
+        const lines = [[]];
+        for (const child of ordered) {
+            const current = lines[lines.length - 1];
+            // A child wider than a whole line still gets one of its own rather than an empty line before it.
+            if (current.length > 0 && lineExtent([...current, child]) > mainAvail) {
+                lines.push([child]);
+            }
+            else {
+                current.push(child);
+            }
+        }
+        // Each line keeps SOURCE order internally: the ordering was applied above, and applying it again
+        // per line would reverse twice.
+        const lineOptions = { ...options, wrap: false, reverse: false };
+        const measure = lines.map((line) => FlexLayoutHelper.layoutLine(line, axis, mainAvail, Infinity, // let each line report the cross extent it actually needs
+        mainStart, crossOrigin, lineOptions, ctx));
+        const heights = measure.map((m) => m.crossUsed);
+        const totalCross = heights.reduce((n, h) => n + h, 0) + Math.max(0, lines.length - 1) * gap;
+        // `alignContent` distributes the BLOCK of lines across the axis, using the same vocabulary the main
+        // axis uses. Only meaningful in a bounded cross axis with room left over.
+        const slack = Number.isFinite(crossAvail) ? crossAvail - totalCross : 0;
+        const align = options.alignContent ?? "start";
+        let cursor = crossOrigin;
+        let between = gap;
+        if (slack > 0) {
+            if (align === "center")
+                cursor += slack / 2;
+            else if (align === "end")
+                cursor += slack;
+            else if (align === "between" && lines.length > 1)
+                between = gap + slack / (lines.length - 1);
+            else if (align === "around") {
+                const unit = slack / lines.length;
+                cursor += unit / 2;
+                between = gap + unit;
+            }
+        }
+        lines.forEach((line, i) => {
+            FlexLayoutHelper.layoutLine(line, axis, mainAvail, heights[i], // the line's own extent, so `stretch` fills the line and not the container
+            mainStart, cursor, lineOptions, ctx);
+            cursor += heights[i];
+            if (i < lines.length - 1)
+                cursor += between;
+        });
+        return { mainUsed: mainAvail, crossUsed: Math.max(totalCross, cursor - crossOrigin) };
+    }
+    static layoutLine(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
         const gap = options.gap ?? 0;
         const main = options.main ?? "start";
         const cross = options.cross ?? "stretch";
+        children = inLayoutOrder(children, options.reverse ?? false);
         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
@@ -48,7 +165,13 @@ export class FlexLayoutHelper {
         // 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.
+        // Filled by the shrink pass below; read by `mainCapFor` in pass 2. Declared here so the closure
+        // can see it - it is empty for every document that does not ask for shrinking.
+        const shrunkCap = new Map();
         const mainCapFor = (child) => {
+            const target = shrunkCap.get(child);
+            if (target !== undefined)
+                return target;
             if (percentBase === Infinity)
                 return Infinity;
             const needsBound = child.relativeSizeFactor(axis.mainHorizontal) !== undefined ||
@@ -56,13 +179,17 @@ export class FlexLayoutHelper {
             return needsBound ? percentBase : Infinity;
         };
         // Pass 1: measure the fixed children (main extent + cross size) and total the flex.
+        // A flex child's BASIS is reserved here too: it is main extent the leftover no longer contains,
+        // exactly like a fixed child's size. With the default basis of 0 this line adds nothing.
         let fixedMain = 0;
         let totalFlex = 0;
+        let totalBasis = 0;
         let crossUsed = 0;
         const fixedSize = new Map();
         for (const child of children) {
             if (child instanceof FlexiblePDFElement) {
                 totalFlex += child.getFlex();
+                totalBasis += child.getBasis(percentBase);
             }
             else {
                 const size = child.calculateLayout(axis.measureConstraints(crossAvail, mainCapFor(child)), axis.offsetAt(mainStart, crossOrigin), ctx);
@@ -71,7 +198,79 @@ export class FlexLayoutHelper {
                 fixedSize.set(child, size);
             }
         }
-        const leftover = mainAvail - fixedMain - totalGap;
+        // Shrinking: the line overflows and some children said they would give space back. CSS weights a
+        // shrinker's share by `shrink x its own size`, so a big item yields more than a small one - which is
+        // why this cannot reuse the grow maths above. Nobody shrinks by default, so a document that never
+        // asks for it never enters this block.
+        const shrinkers = children.filter((c) => c.flexShrink > 0 && !(c instanceof FlexiblePDFElement));
+        const overflow = fixedMain + totalBasis + totalGap - mainAvail;
+        if (shrinkers.length > 0 && Number.isFinite(mainAvail) && overflow > 0) {
+            // Every child is floored at what it can actually hold - its `min-content` extent, which is CSS's
+            // automatic `min-width` on a flex item. Without it a badly overflowing line would grind a
+            // paragraph down to one word per line: the box gets narrow, the text gets tall, and nothing is
+            // gained. Past that floor a child overflows again, which is what a browser does too.
+            const naturalOf = (c) => axis.mainOf(fixedSize.get(c));
+            const floorOf = new Map(shrinkers.map((c) => [
+                c,
+                // Never above its natural size: the shrink pass may only take space away, never hand it out.
+                // Never below zero either - when the GAPS alone outgrow the line a proportional share asks
+                // for more than a child has, and a negative constraint is nonsense even though
+                // `constrainWidth` would floor it further down anyway.
+                Math.min(naturalOf(c), Math.max(0, c.minIntrinsicMain(axis.mainHorizontal, ctx))),
+            ]));
+            // CSS resolves this iteratively (Flexbox 9.7): a child that lands on its floor is FROZEN there
+            // and the share it could not absorb is handed to the rest. A single pass would leave that share
+            // unspent, so one unsqueezable child would keep the whole line overflowing while its neighbours
+            // still had room to give.
+            const target = new Map(shrinkers.map((c) => [c, naturalOf(c)]));
+            const frozen = new Set();
+            let flexible = [...shrinkers];
+            // What the frozen ones took off the overflow; the rest is always shared out from scratch, never
+            // from what a previous round already assigned.
+            let absorbedByFrozen = 0;
+            while (flexible.length > 0) {
+                const toAbsorb = overflow - absorbedByFrozen;
+                if (toAbsorb <= 1e-9)
+                    break;
+                const weight = (c) => c.flexShrink * naturalOf(c);
+                const totalWeight = flexible.reduce((n, c) => n + weight(c), 0);
+                if (totalWeight <= 0)
+                    break;
+                const froze = [];
+                for (const child of flexible) {
+                    const natural = naturalOf(child);
+                    const floor = floorOf.get(child);
+                    const wanted = natural - (weight(child) / totalWeight) * toAbsorb;
+                    if (wanted < floor) {
+                        target.set(child, floor);
+                        froze.push(child);
+                        absorbedByFrozen += natural - floor;
+                    }
+                    else {
+                        target.set(child, wanted);
+                    }
+                }
+                if (froze.length === 0)
+                    break;
+                for (const c of froze)
+                    frozen.add(c);
+                flexible = flexible.filter((c) => !frozen.has(c));
+            }
+            for (const child of shrinkers) {
+                const natural = naturalOf(child);
+                const capped = target.get(child);
+                if (capped >= natural)
+                    continue;
+                shrunkCap.set(child, capped);
+                // Re-measure NOW, not in pass 2: a narrower child may wrap to more lines, and the line's
+                // cross extent is settled just below.
+                const size = child.calculateLayout(axis.measureConstraints(crossAvail, capped), axis.offsetAt(mainStart, crossOrigin), ctx);
+                fixedMain += axis.mainOf(size) - natural;
+                crossUsed = Math.max(crossUsed, axis.crossOf(size));
+                fixedSize.set(child, size);
+            }
+        }
+        const leftover = mainAvail - fixedMain - totalBasis - totalGap;
         // 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.
@@ -97,7 +296,7 @@ export class FlexLayoutHelper {
         if (totalFlex > 0) {
             for (const child of children) {
                 if (child instanceof FlexiblePDFElement) {
-                    const mainExtent = (child.getFlex() / totalFlex) * remaining;
+                    const mainExtent = child.getBasis(percentBase) + (child.getFlex() / totalFlex) * remaining;
                     const size = child.calculateLayout(axis.flexConstraints(mainExtent, crossAvail), axis.offsetAt(mainStart, crossOrigin), ctx);
                     crossUsed = Math.max(crossUsed, axis.crossOf(size));
                 }
@@ -108,20 +307,32 @@ export class FlexLayoutHelper {
         // `stretch` caps a child's cross to `crossExtent` (not `crossAvail`) so siblings end up
         // equal across the axis. Bounded lines have crossExtent == crossAvail (byte-identical);
         // only an unbounded line (a shrink-wrap Row) now equalises instead of staying natural.
-        const stretch = cross === "stretch";
-        // Pass 2: place each child at the running main position, offset across by `cross`.
+        // A child may override the container with its own `alignSelf` (CSS), so the decision is per child.
+        const alignFor = (child) => child.alignSelf ?? cross;
+        // Pass 2: place each child at the running main position, offset across by its alignment.
         let mainPos = mainStart + leadingSpace;
         let placedCross = 0;
         children.forEach((child, index) => {
+            const align = alignFor(child);
+            const stretch = align === "stretch";
             let mainExtent;
             if (child instanceof FlexiblePDFElement) {
-                mainExtent = (child.getFlex() / totalFlex) * remaining;
-                const size = child.calculateLayout(axis.flexConstraints(mainExtent, stretch ? crossExtent : crossAvail), axis.offsetAt(mainPos, crossOrigin), ctx);
+                // `totalFlex` is 0 when every flex child asked for `flex: 0` (a pure `flexBasis` slot). The
+                // share is then 0/0 - a NaN that becomes the offset of every later sibling, which is the
+                // shape of the old Spacer bug. Such a child simply takes its basis.
+                const share = totalFlex > 0 ? (child.getFlex() / totalFlex) * remaining : 0;
+                mainExtent = child.getBasis(percentBase) + share;
+                // A flex child fills the MAIN axis, and its cross size is only known after layout - there is
+                // nothing to align against. So alignSelf is a no-op here, and that has to hold for the CROSS
+                // CONSTRAINT too: reading the per-child alignment would hand an `alignSelf: "start"` flex child
+                // an unbounded cross axis on a shrink-wrapping line, where the container's own rule gives it
+                // the line's extent. A no-op that changes the constraints is not a no-op.
+                const size = child.calculateLayout(axis.flexConstraints(mainExtent, cross === "stretch" ? crossExtent : crossAvail), axis.offsetAt(mainPos, crossOrigin), ctx);
                 placedCross = Math.max(placedCross, axis.crossOf(size));
             }
             else {
                 const childCross = axis.crossOf(fixedSize.get(child));
-                const size = child.calculateLayout(axis.measureConstraints(stretch ? crossExtent : crossAvail, mainCapFor(child)), 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(align, crossExtent, childCross)), ctx);
                 mainExtent = axis.mainOf(size);
                 placedCross = Math.max(placedCross, axis.crossOf(size));
             }

package/dist/utils/font-metrics.d.ts

@@ -9,7 +9,7 @@ import type { FontDecoration } from "../text/text-decoration.js";
  * touching layout code.
  */
 export interface FontMetrics {
-    getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle): number;
+    getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, ligatures?: boolean): 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`). */
@@ -22,5 +22,16 @@ export interface FontMetrics {
     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[];
+    getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle, ligatures?: boolean): number[];
+    /** Whether this family can draw the code point at all - what picks a face out of a fallback stack. */
+    hasGlyph(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
+    /** Whether the document draws this code point as colour emoji rather than from the text font - it
+     *  is missing from that font on purpose, so glyph coverage must not touch it. */
+    rendersAsEmoji?(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
+    /** Told when a code point had to be removed because no font could draw it. Optional: a metrics
+     *  object used only for measuring (a test double) has nothing to report to. */
+    reportMissingGlyph?(codePoints: number[]): void;
+    /** How many glyphs the run will DRAW, when a ligature made that differ from its code-point count.
+     *  Absent or `undefined` means "the same", which is every Latin run. */
+    shapedGlyphCount?(text: string, fontFamily?: string, fontStyle?: FontStyle, ligatures?: boolean): number | undefined;
 }

package/dist/utils/gsub.d.ts

@@ -0,0 +1,36 @@
+export declare class GsubTable {
+    private data;
+    private base;
+    private scriptList;
+    private featureList;
+    private lookupList;
+    private lookupCache;
+    private coverageCache;
+    constructor(data: Uint8Array, base: number);
+    /** Whether the font carries this script at all - `arab` is the question the shaper asks. */
+    hasScript(script: string): boolean;
+    /** A feature's lookup indices, under the script's DEFAULT language system - Arabic shaping features
+     *  are script-wide, so a language-specific override would only add typographic niceties. */
+    lookups(script: string, feature: string): number[];
+    /** Type 1: substitute one glyph. `null` when no subtable covers it - the feature does not apply. */
+    substituteSingle(lookupIndex: number, glyph: number): number | null;
+    /**
+     * Type 4: collapse a run of glyphs into one, starting at `at`. Longest match wins, as the spec
+     * requires - a three-glyph ligature beats the two-glyph one that starts the same way.
+     */
+    substituteLigature(lookupIndex: number, glyphs: readonly number[], at: number): {
+        glyph: number;
+        consumed: number;
+    } | null;
+    /** The type of a lookup, for reporting what a font needs that we do not do. */
+    lookupType(lookupIndex: number): number | undefined;
+    private scriptOffset;
+    /**
+     * Resolve a lookup, unwrapping type 7 (extension) - which exists only because the 16-bit offsets
+     * elsewhere cannot reach far enough in a big font. Callers never learn it was wrapped.
+     */
+    private lookup;
+    /** Coverage table -> glyph id to its INDEX in the table, which is how subtables address glyphs. */
+    private coverage;
+    private cacheCoverage;
+}