@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/utils/flex-layout.js

@@ -1,5 +1,9 @@
-import { FlexiblePDFElement } from "../elements/pdf-element.js";
+import { alignSelfOf, flexibleOf, flexShrinkOf, orderOf } from "../layout/flex-item.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
+const sameConstraints = (a, b) => a.minWidth === b.minWidth &&
+    a.maxWidth === b.maxWidth &&
+    a.minHeight === b.minHeight &&
+    a.maxHeight === b.maxHeight;
 export const VERTICAL_AXIS = {
     mainHorizontal: false,
     mainOf: (s) => s.height,
@@ -33,21 +37,24 @@ function crossOffset(align, crossExtent, childCross) {
  * 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)
+    const ordered = children.some((c) => orderOf(c) !== 0)
+        ? [...children].sort((a, b) => orderOf(a) - orderOf(b))
         : children;
     return reverse ? [...ordered].reverse() : ordered;
 }
+/**
+ * The main-axis alignment as the container means it. Reversed, the axis runs from the other end: `start`
+ * is where the first child of the REVERSED order sits - the right of a Row, the bottom of a Column (CSS
+ * `row-reverse` with `flex-start`, Flutter's `MainAxisAlignment.start` on a reversed axis). `center`,
+ * `between` and `around` are symmetric and stay.
+ */
+function mainAlignOf(options) {
+    const main = options.main ?? "start";
+    if (!options.reverse)
+        return main;
+    return main === "start" ? "end" : main === "end" ? "start" : main;
+}
 export class FlexLayoutHelper {
-    /**
-     * Lays out a flex line along `axis`, IN SOURCE ORDER, and places every child.
-     * Fixed children take their natural main extent; flex (`ExpandedElement`) children
-     * split the leftover main space by their `flex`. `gap` is inserted between children.
-     * `main` distributes any leftover when there is no flex child; `cross` positions/sizes
-     * each child across the line. Returns the total main extent consumed and the cross
-     * 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.
      *
@@ -55,12 +62,12 @@ export class FlexLayoutHelper {
      * 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) {
+    static layout(children, axis, mainAvail, crossAvail, options, ctx, mode = "layout") {
         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.layoutLine(children, axis, mainAvail, crossAvail, 0, options, ctx, mode);
         }
-        return FlexLayoutHelper.layoutWrapped(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx);
+        return FlexLayoutHelper.layoutWrapped(children, axis, mainAvail, crossAvail, options, ctx, mode);
     }
     /**
      * The wrapping path: split into lines, lay each one out, then place the lines across the axis.
@@ -69,21 +76,19 @@ export class FlexLayoutHelper {
      * 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) {
+    static layoutWrapped(children, axis, mainAvail, crossAvail, options, ctx, mode) {
         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.
+        // Which children share a line. A child counts with its natural main extent; a flex child with its
+        // BASIS, which is 0 unless it asked for one - so it never forces a break by itself. A PERCENTAGE
+        // child's size depends on how many gaps the line ends up with, so it is asked again for every
+        // candidate membership. A plain child's extent does not, so it is measured ONCE and remembered -
+        // otherwise each membership probe re-lays every child already on the line (O(n^2) subtree layouts).
         const measured = new Map();
         const naturalMain = (child, base) => {
-            if (child instanceof FlexiblePDFElement)
-                return child.getBasis(base);
+            const flexible = flexibleOf(child);
+            if (flexible)
+                return flexible.getBasis(base);
             const factor = child.relativeSizeFactor(axis.mainHorizontal);
             if (factor !== undefined)
                 return base * factor;
@@ -92,9 +97,9 @@ export class FlexLayoutHelper {
                 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));
+            // child overflow, and so does our own non-wrapping path. A stack holding a Spacer counts with its
+            // content too: its Spacer only grows into what is left once the line is laid out.
+            const main = axis.mainOf(child.measure(axis.measureConstraints(crossAvail, Infinity), ctx));
             measured.set(child, main);
             return main;
         };
@@ -117,16 +122,19 @@ export class FlexLayoutHelper {
         }
         // 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 lineOptions = { ...options, wrap: false, reverse: false, main: mainAlignOf(options) };
+        const measure = lines.map((line) => FlexLayoutHelper.layoutLine(line, axis, mainAvail, 
+        // Across a Column a child gets the column's width, as a block does in CSS (a paragraph wraps
+        // inside it); across a Row it is as tall as its content. Either way the line is only as big as
+        // what is on it, so `stretch` fills the line and not the container.
+        axis.mainHorizontal ? Infinity : crossAvail, 0, lineOptions, ctx, "measure", true));
         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 cursor = 0;
         let between = gap;
         if (slack > 0) {
             if (align === "center")
@@ -143,203 +151,297 @@ export class FlexLayoutHelper {
         }
         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, lineOptions, ctx, mode);
             cursor += heights[i];
             if (i < lines.length - 1)
                 cursor += between;
         });
-        return { mainUsed: mainAvail, crossUsed: Math.max(totalCross, cursor - crossOrigin) };
+        return { mainUsed: mainAvail, crossUsed: Math.max(totalCross, cursor) };
     }
-    static layoutLine(children, axis, mainAvail, crossAvail, mainStart, crossOrigin, options, ctx) {
+    /**
+     * Lays out ONE flex line along `axis` and places every child. Fixed children take their natural main
+     * extent; flex children split the leftover by their `flex`; `gap` goes between children. `main`
+     * distributes leftover when nothing flexes; `cross` positions or stretches each child across the line.
+     * Returns the main extent consumed and the cross extent occupied.
+     *
+     * The steps run in this order, and the order is part of the result: `leftover` is taken after the
+     * shrink and before the share, and the main-axis spacing reads exactly that value.
+     */
+    static layoutLine(children, axis, mainAvail, crossAvail, crossOrigin, options, ctx, mode, 
+    // The line's cross extent is its content, not `crossAvail`: one line of a wrapping container.
+    crossFromContent = false) {
         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
-        // 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.
-        // 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 ||
-                child.needsBoundedMain(axis.mainHorizontal);
-            return needsBound ? percentBase : Infinity;
+        const ordered = inLayoutOrder(children, options.reverse ?? false);
+        const totalGap = Math.max(0, ordered.length - 1) * gap;
+        const line = {
+            children: ordered,
+            axis,
+            mainAvail,
+            crossAvail,
+            ctx,
+            totalGap,
+            // The main extent a percentage child resolves against: the line minus the gaps between its items,
+            // so N children at (100/N)% + gaps fit exactly (the flexbox `width: 33%` + gap trap). Only finite
+            // on a bounded main axis - a fraction of an unbounded one has no meaning, so `%` shrink-wraps.
+            percentBase: mainAvail !== Infinity ? Math.max(0, mainAvail - totalGap) : Infinity,
+            fixedMain: 0,
+            crossUsed: 0,
+            totalFlex: 0,
+            totalBasis: 0,
+            sizes: new Map(),
+            under: new Map(),
+            shrunkCap: new Map(),
+            sharedCap: new Map(),
+            shrunkBasis: new Map(),
         };
-        // 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);
-                fixedMain += axis.mainOf(size);
-                crossUsed = Math.max(crossUsed, axis.crossOf(size));
-                fixedSize.set(child, size);
-            }
-        }
-        // 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;
+        measureLine(line);
+        shrinkLine(line);
+        const leftover = mainAvail - line.fixedMain - line.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.
         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;
-        if (totalFlex === 0 && mainAvail !== Infinity && leftover > 0) {
-            if (main === "center")
-                leadingSpace = leftover / 2;
-            else if (main === "end")
-                leadingSpace = leftover;
-            else if (main === "between" && count > 1)
-                betweenSpace = gap + leftover / (count - 1);
-            else if (main === "around") {
-                const unit = leftover / count;
-                leadingSpace = unit / 2;
-                betweenSpace = gap + unit;
-            }
-        }
-        // Measure flex children too (at their main share) so a tall/wrapping flex cell counts
-        // toward the line's cross extent - they're placed in pass 2, but crossExtent needs them now.
-        if (totalFlex > 0) {
-            for (const child of children) {
-                if (child instanceof FlexiblePDFElement) {
-                    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));
-                }
-            }
-        }
+        const weight = shareLeftover(line, remaining);
+        const spacing = mainSpacing(mainAlignOf(options), gap, ordered.length, mainAvail, leftover, weight);
+        measureFlex(line, weight, remaining);
         // The cross extent children align within: the bounded line size, else the tallest child.
-        const crossExtent = crossAvail !== Infinity ? crossAvail : crossUsed;
-        // `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.
-        // 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) {
-                // `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));
+        const crossExtent = crossAvail !== Infinity && !crossFromContent ? crossAvail : line.crossUsed;
+        return placeLine(line, options.cross ?? "stretch", crossExtent, crossOrigin, spacing, weight, remaining, mode);
+    }
+}
+/** A flex child's basis on this line: what it asked for, or less once the line has shrunk it. */
+function basisOf(line, child, flexible) {
+    return line.shrunkBasis.get(child) ?? flexible.getBasis(line.percentBase);
+}
+/**
+ * The main cap to hand a child: its shrunk or shared cap once the line is settled; `percentBase` for a
+ * percentage child, so its fraction resolves; unbounded for everyone else, who keep their natural size.
+ */
+function mainCapFor(line, child) {
+    const target = line.shrunkCap.get(child) ?? line.sharedCap.get(child);
+    if (target !== undefined)
+        return target;
+    if (line.percentBase === Infinity)
+        return Infinity;
+    return child.relativeSizeFactor(line.axis.mainHorizontal) !== undefined
+        ? line.percentBase
+        : Infinity;
+}
+/** Measures `child` and remembers the size with the constraints it answers. */
+function measureInto(line, child, constraints) {
+    const size = child.measure(constraints, line.ctx);
+    line.sizes.set(child, size);
+    line.under.set(child, constraints);
+    return size;
+}
+/** Measures a fixed child again at a new main cap, moving the line's totals with it. */
+function remeasure(line, child, cap) {
+    const before = line.axis.mainOf(line.sizes.get(child));
+    const size = measureInto(line, child, line.axis.measureConstraints(line.crossAvail, cap));
+    line.fixedMain += line.axis.mainOf(size) - before;
+    line.crossUsed = Math.max(line.crossUsed, line.axis.crossOf(size));
+}
+/**
+ * Step 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 it adds nothing.
+ */
+function measureLine(line) {
+    const { axis } = line;
+    for (const child of line.children) {
+        const flexible = flexibleOf(child);
+        if (flexible) {
+            line.totalFlex += flexible.getFlex();
+            line.totalBasis += flexible.getBasis(line.percentBase);
+            continue;
+        }
+        const size = measureInto(line, child, axis.measureConstraints(line.crossAvail, mainCapFor(line, child)));
+        line.fixedMain += axis.mainOf(size);
+        line.crossUsed = Math.max(line.crossUsed, axis.crossOf(size));
+    }
+}
+/**
+ * Step 2: 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 - for a flex child that
+ * size is its basis, so a Spacer (basis 0) gives nothing. A document that never overflows never gets past
+ * the first test.
+ */
+function shrinkLine(line) {
+    const { axis } = line;
+    const overflow = line.fixedMain + line.totalBasis + line.totalGap - line.mainAvail;
+    if (!Number.isFinite(line.mainAvail) || !(overflow > 0))
+        return;
+    const shrinkers = line.children.filter((c) => {
+        if (!(flexShrinkOf(c) > 0))
+            return false;
+        const flexible = flexibleOf(c);
+        return !flexible || flexible.getBasis(line.percentBase) > 0;
+    });
+    if (shrinkers.length === 0)
+        return;
+    // 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. Past that floor a child overflows again, as in a browser.
+    const naturalOf = (c) => {
+        const flexible = flexibleOf(c);
+        return flexible ? flexible.getBasis(line.percentBase) : axis.mainOf(line.sizes.get(c));
+    };
+    const floorOf = new Map(shrinkers.map((c) => [
+        c,
+        // Never above its natural size (the shrink only takes space away) and never below zero (when the
+        // GAPS alone outgrow the line, a proportional share asks for more than a child has).
+        Math.min(naturalOf(c), Math.max(0, c.minIntrinsicMain(axis.mainHorizontal, line.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.
+    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.
+    let absorbedByFrozen = 0;
+    while (flexible.length > 0) {
+        const toAbsorb = overflow - absorbedByFrozen;
+        if (toAbsorb <= 1e-9)
+            break;
+        const weight = (c) => flexShrinkOf(c) * 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 {
-                const childCross = axis.crossOf(fixedSize.get(child));
-                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));
+                target.set(child, wanted);
             }
-            mainPos += mainExtent;
-            if (index < count - 1)
-                mainPos += betweenSpace;
-        });
-        return { mainUsed: mainPos - mainStart, crossUsed: placedCross };
+        }
+        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 capped = target.get(child);
+        if (capped >= naturalOf(child))
+            continue;
+        if (flexibleOf(child)) {
+            // A flex child is measured later, at its basis plus its share; it starts from less.
+            line.totalBasis -= naturalOf(child) - capped;
+            line.shrunkBasis.set(child, capped);
+            continue;
+        }
+        line.shrunkCap.set(child, capped);
+        // Re-measured NOW: a narrower child may wrap to more lines, and the line's cross extent is
+        // settled before anything is placed.
+        remeasure(line, child, capped);
+    }
+}
+/**
+ * Step 3: a stack holding a Spacer grows like an `Expanded` of flex 1 whose basis is its content - it
+ * shares what is left with the flex children. Handing it the whole line squeezed its siblings; handing
+ * it a share before the line was settled could leave it less than its own content. Returns the total
+ * weight the leftover is shared by.
+ */
+function shareLeftover(line, remaining) {
+    const { axis } = line;
+    const sharing = line.children.filter((child) => line.percentBase !== Infinity &&
+        !flexibleOf(child) &&
+        child.relativeSizeFactor(axis.mainHorizontal) === undefined &&
+        child.needsBoundedMain(axis.mainHorizontal));
+    const weight = line.totalFlex + sharing.length;
+    if (remaining > 0) {
+        for (const child of sharing) {
+            const grown = axis.mainOf(line.sizes.get(child)) + remaining / weight;
+            line.sharedCap.set(child, grown);
+            remeasure(line, child, grown);
+        }
+    }
+    return weight;
+}
+/** Step 4: the main-axis distribution - only with nothing to flex and bounded, positive space. */
+function mainSpacing(main, gap, count, mainAvail, leftover, weight) {
+    if (weight !== 0 || mainAvail === Infinity || !(leftover > 0))
+        return { leading: 0, between: gap };
+    if (main === "center")
+        return { leading: leftover / 2, between: gap };
+    if (main === "end")
+        return { leading: leftover, between: gap };
+    if (main === "between" && count > 1)
+        return { leading: 0, between: gap + leftover / (count - 1) };
+    if (main === "around") {
+        const unit = leftover / count;
+        return { leading: unit / 2, between: gap + unit };
+    }
+    return { leading: 0, between: gap };
+}
+/**
+ * Step 5: measure the flex children at their share, so a tall or wrapping flex cell counts toward the
+ * line's cross extent before anything is placed.
+ */
+function measureFlex(line, weight, remaining) {
+    for (const child of line.children) {
+        const flexible = flexibleOf(child);
+        if (!flexible)
+            continue;
+        // A pure `flexBasis` slot (`flex: 0`) has no share but still has a size across the line.
+        const share = weight > 0 ? (flexible.getFlex() / weight) * remaining : 0;
+        const mainExtent = basisOf(line, child, flexible) + share;
+        const size = measureInto(line, child, line.axis.flexConstraints(mainExtent, line.crossAvail));
+        line.crossUsed = Math.max(line.crossUsed, line.axis.crossOf(size));
     }
 }
+/**
+ * Step 6: place each child at the running main position, offset across by its alignment. This is the
+ * ONE layout a child gets. Measuring, it only sizes - and reuses a size already measured under the same
+ * constraints, or the measuring itself would double at every level.
+ *
+ * `stretch` caps a child's cross to `crossExtent`, not `crossAvail`, so siblings end up equal across the
+ * axis. A child may override the container with its own `alignSelf` (CSS).
+ */
+function placeLine(line, cross, crossExtent, crossOrigin, spacing, weight, remaining, mode) {
+    const { axis, ctx } = line;
+    const place = (child, constraints, offset) => {
+        if (mode === "layout")
+            return child.calculateLayout(constraints, offset, ctx);
+        const known = line.under.get(child);
+        return known && sameConstraints(known, constraints)
+            ? line.sizes.get(child)
+            : child.measure(constraints, ctx);
+    };
+    const last = line.children.length - 1;
+    let mainPos = spacing.leading;
+    let placedCross = 0;
+    line.children.forEach((child, index) => {
+        let mainExtent;
+        const flexible = flexibleOf(child);
+        if (flexible) {
+            // `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. Such a child takes its basis.
+            const share = weight > 0 ? (flexible.getFlex() / weight) * remaining : 0;
+            mainExtent = basisOf(line, child, flexible) + share;
+            // A flex child fills the MAIN axis and its cross size is only known after layout, so `alignSelf`
+            // is a no-op here - and that has to hold for the CROSS CONSTRAINT too, or an `alignSelf: "start"`
+            // flex child would get an unbounded cross axis on a shrink-wrapping line.
+            const size = place(child, axis.flexConstraints(mainExtent, cross === "stretch" ? crossExtent : line.crossAvail), axis.offsetAt(mainPos, crossOrigin));
+            placedCross = Math.max(placedCross, axis.crossOf(size));
+        }
+        else {
+            const align = alignSelfOf(child) ?? cross;
+            const childCross = axis.crossOf(line.sizes.get(child));
+            const size = place(child, axis.measureConstraints(align === "stretch" ? crossExtent : line.crossAvail, mainCapFor(line, child)), axis.offsetAt(mainPos, crossOrigin + crossOffset(align, crossExtent, childCross)));
+            mainExtent = axis.mainOf(size);
+            placedCross = Math.max(placedCross, axis.crossOf(size));
+        }
+        mainPos += mainExtent;
+        if (index < last)
+            mainPos += spacing.between;
+    });
+    return { mainUsed: mainPos, crossUsed: placedCross };
+}

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

@@ -31,9 +31,10 @@ export interface FontMetrics {
     /** 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;
+    /** Told when a code point had to be removed because no font could draw it - `about` is the element
+     *  it was removed from. Optional: a metrics object used only for measuring (a test double) has
+     *  nothing to report to. */
+    reportMissingGlyph?(codePoints: number[], about?: object, page?: 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/image-helper.js

@@ -9,7 +9,8 @@ DataView.prototype.getUint24 = function (byteOffset, littleEndian = false) {
     return littleEndian ? (b3 << 16) | (b2 << 8) | b1 : (b1 << 16) | (b2 << 8) | b3;
 };
 export async function getImageDimensions(buffer) {
-    const dataView = new DataView(buffer.buffer);
+    // The view's own window: a `Uint8Array` may be a slice of a larger buffer (a Node `Buffer` usually is).
+    const dataView = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
     // Check for JPEG (0xFFD8 is the start of JPEG file)
     if (dataView.getUint16(0) === 0xffd8) {
         let offset = 2;