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

package/dist/elements/row-element.d.ts

@@ -35,18 +35,6 @@ interface RowElementParams extends WithChildren {
     /** Start everything after this row on a fresh page (CSS `break-after: page`). */
     breakAfter?: boolean;
 }
-/**
- * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
- * left-to-right via the shared `FlexLayoutHelper` on the horizontal axis; fixed children
- * take their natural width, `ExpandedElement`/Spacer children split the leftover width by
- * `flex`, and `gap` is inserted between them. The row fills the width it is offered and
- * shrink-wraps its height to the tallest child (unless a height is forced on it).
- *
- * Cross/main alignment is the next foundation slice; today children sit at the top-left
- * (cross start, main start). The row is atomic w.r.t. pagination - it reflows whole if it
- * does not fit (handled by the parent's `packChildren`); synchronized cell splitting is a
- * Grid/Table concern.
- */
 export declare class RowElement extends SizedPDFElement {
     private children;
     private gap;
@@ -62,6 +50,7 @@ export declare class RowElement extends SizedPDFElement {
     breaksBefore(): boolean;
     breaksAfter(): boolean;
     relativeSizeFactor(horizontal: boolean): number | undefined;
+    maxExtent(horizontal: boolean): number;
     /** The mirror of `ContainerElement`: a Row's OWN flex child needs a bounded width, and the need of any
      *  descendant propagates on both axes (see the Column for the reasoning). */
     needsBoundedMain(horizontal: boolean): boolean;
@@ -78,6 +67,11 @@ export declare class RowElement extends SizedPDFElement {
     private reportIgnoredBreak;
     /** The one sizing path: `layout` places the children (relative to this box), `measure` only sizes them. */
     private sizeWith;
+    private percentPaddingChild?;
+    /** A child's `%` padding resolves against this Row's width (CSS: the containing block), which the Row
+     *  never offers - its children get their natural size - so it is told. Only when a child uses it,
+     *  since every key below would otherwise change with the Row's width. */
+    private childContext;
     layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;

package/dist/elements/row-element.js

@@ -1,9 +1,9 @@
-import { flexibleOf } from "../layout/flex-item.js";
+import { flexibleOf, hasPercentPaddingItem } from "../layout/flex-item.js";
 import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
 import { FlexLayoutHelper, HORIZONTAL_AXIS, } from "../utils/flex-layout.js";
 import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
 import { diagnose, pageOf } from "../common/diagnostics.js";
-import { SizedPDFElement } from "./pdf-element.js";
+import { SizedPDFElement, withPaddingBase, } from "./pdf-element.js";
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
  * left-to-right via the shared `FlexLayoutHelper` on the horizontal axis; fixed children
@@ -16,6 +16,8 @@ import { SizedPDFElement } from "./pdf-element.js";
  * does not fit (handled by the parent's `packChildren`); synchronized cell splitting is a
  * Grid/Table concern.
  */
+/** How far a line may run past its box before it is reported, in points (floating-point slack). */
+const WIDE_EPSILON = 0.01;
 export class RowElement extends SizedPDFElement {
     constructor({ children, gap, main, cross, reverse, wrap, alignContent, width, height, breakBefore, breakAfter, ...sizing }) {
         super({ x: 0, y: 0 });
@@ -39,6 +41,9 @@ export class RowElement extends SizedPDFElement {
     relativeSizeFactor(horizontal) {
         return horizontal ? this.requested.widthFactor : this.requested.heightFactor;
     }
+    maxExtent(horizontal) {
+        return (horizontal ? this.requested.maxWidth : this.requested.maxHeight) ?? Infinity;
+    }
     /** The mirror of `ContainerElement`: a Row's OWN flex child needs a bounded width, and the need of any
      *  descendant propagates on both axes (see the Column for the reasoning). */
     needsBoundedMain(horizontal) {
@@ -124,7 +129,10 @@ export class RowElement extends SizedPDFElement {
         // Horizontal stack: main = width (children fill it), cross = height (children can stretch to it).
         const mainAvail = boundedWidth ?? Infinity;
         const crossAvail = boundedHeight ?? Infinity;
-        let result = { mainUsed: 0, crossUsed: 0 };
+        let result = {
+            mainUsed: 0,
+            crossUsed: 0,
+        };
         if (this.children.length > 0) {
             result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, {
                 gap: this.gap,
@@ -133,10 +141,32 @@ export class RowElement extends SizedPDFElement {
                 reverse: this.reverse,
                 wrap: this.wrap,
                 alignContent: this.alignContent,
-            }, ctx, mode);
+            }, this.childContext(ctx, mainAvail), mode);
+        }
+        const used = result.widestLine ?? result.mainUsed;
+        if (mode === "layout" && used > mainAvail + WIDE_EPSILON) {
+            diagnose(ctx.diagnostics, {
+                code: "overflow-wide",
+                severity: "warning",
+                message: `A Row's children need ${Math.round(used)}pt but it is ` +
+                    `${Math.round(mainAvail)}pt wide; they are drawn past its edge. Let them wrap ` +
+                    '(`breakWord`, `wrap`), make room, or clip with a Box\'s `overflow: "hidden"`.',
+                about: this,
+                page: pageOf(ctx),
+                fallback: "silent",
+            });
         }
         return { width: boundedWidth ?? result.mainUsed, height: boundedHeight ?? result.crossUsed };
     }
+    /** A child's `%` padding resolves against this Row's width (CSS: the containing block), which the Row
+     *  never offers - its children get their natural size - so it is told. Only when a child uses it,
+     *  since every key below would otherwise change with the Row's width. */
+    childContext(ctx, mainAvail) {
+        this.percentPaddingChild ?? (this.percentPaddingChild = this.children.some(hasPercentPaddingItem));
+        if (!this.percentPaddingChild)
+            return ctx;
+        return withPaddingBase(ctx, Number.isFinite(mainAvail) ? mainAvail : undefined);
+    }
     layoutChildren() {
         return this.children;
     }

package/dist/elements/svg-element.js

@@ -1,6 +1,6 @@
 import { readFileBytes } from "../platform/node-fs.js";
 import { SvgParseError, svgSize, svgToIr } from "../svg/index.js";
-import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, sizeAtOwnRatio, } from "../layout/box-constraints.js";
 import { SizedPDFElement } from "./pdf-element.js";
 import { IMAGE_FETCH_LIMITS, ImageUrlError, isImageUrl } from "./image-element.js";
 import { fetchBytes } from "../utils/fetch-bytes.js";
@@ -144,18 +144,12 @@ export class SvgElement extends SizedPDFElement {
                 `column), where its size cannot be read before it is placed - give it both a width and a ` +
                 `height, or an aspectRatio`);
         }
-        // One pinned axis derives the other from the drawing's own ratio (CSS `width: 120; height: auto`).
-        // A bitmap needs a decode pass before it can do this; an SVG knows it from its viewBox.
+        // Its own ratio fills an open axis, as for a bitmap - which needs a decode pass for it; an SVG
+        // knows it from its viewBox. Unsized, it is its own size scaled down to fit: a 24pt icon stays 24pt.
         const intrinsic = this.intrinsic ?? { width: 0, height: 0 };
         if (this.sizing.aspectRatio === undefined && intrinsic.width > 0 && intrinsic.height > 0) {
-            const ratio = intrinsic.width / intrinsic.height;
-            if (w !== undefined && h === undefined)
-                h = bounds.constrainHeight(w / ratio);
-            else if (h !== undefined && w === undefined)
-                w = bounds.constrainWidth(h * ratio);
+            ({ width: w, height: h } = sizeAtOwnRatio(w, h, intrinsic, bounds));
         }
-        // Nothing pinned: draw at the intrinsic size, as an unsized `<img>` does - never fill the region,
-        // which would blow a 24pt icon up to the whole page.
         return {
             width: w ?? bounds.constrainWidth(intrinsic.width),
             height: h ?? bounds.constrainHeight(intrinsic.height),

package/dist/elements/text-element.d.ts

@@ -22,8 +22,16 @@ export interface TextSegment {
     /** Unset inherits the Text's own setting; `true`/`false` overrides it for this run only. */
     underline?: boolean;
     strikethrough?: boolean;
+    skipInk?: boolean;
     /** Extra space after every glyph, in points; unset inherits the Text's own value. */
     letterSpacing?: number;
+    textTransform?: TextTransform;
+    wordSpacing?: number;
+    ligatures?: boolean;
+    /** How a word wider than the box splits, for the characters of THIS run (Chrome: a break after a
+     *  character is allowed by that character's own `overflow-wrap`). */
+    breakWord?: boolean;
+    hyphenate?: Hyphenator;
     /**
      * CSS `vertical-align`, for a footnote marker or a formula index. Shifts THIS run's baseline;
      * it does not resize the text, and it does not change the line's height - set `fontSize` yourself
@@ -119,6 +127,7 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private direction;
     private fontFallback;
     private resolved?;
+    private broken;
     private textTransform;
     private wordSpacing;
     private textIndent;
@@ -187,7 +196,14 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
      *  the lines (a box that is too short cuts them, it does not reflow them). */
     protected sizeInputs(constraints: BoxConstraints): BoxConstraints;
     protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
-    private measuredHeight;
+    /**
+     * The one sizing path, for measuring and layout alike: a bounded width wraps to it (in a Column), an
+     * unbounded one takes the natural single-line width (in a Row). The lines are what layout checks.
+     * The style is resolved here, as drawing reads it.
+     */
+    /** The text broken at `width`: once per context and width, for measuring, layout and splitting. */
+    private linesAt;
+    private sizeWith;
     /** The unwrapped single-line width of the content (used when width is unbounded, e.g. inside a Row).
      *  Must match the breaker's one-line sum BIT for bit - it adds `width + (space + word)`, and the same
      *  numbers grouped differently drift by a sub-ULP, enough to wrap a text inside its own natural-width

package/dist/elements/text-element.js

@@ -3,14 +3,15 @@ import { BoxConstraints } from "../layout/box-constraints.js";
 import { applyTextTransform } from "../text/text-style.js";
 import { splitByFont } from "../text/font-fallback.js";
 import { runAdvance } from "../text/advance.js";
-import { singleLineWidth, MAX_SPACE_SHRINK, breakSegmentsIntoLines, } from "../text/line-breaker.js";
+import { runStyleOf, singleLineWidth, MAX_SPACE_SHRINK, breakSegmentsIntoLines, } from "../text/line-breaker.js";
 import { hyphenPieces } from "../text/hyphen-breaks.js";
 import { adjustForOrphansWidows, DEFAULT_ORPHANS, DEFAULT_WIDOWS, } from "../text/orphans-widows.js";
-import { lineBoxForSegmentLine, textHeight } from "../text/line-metrics.js";
+import { lineBoxForSegmentLine, linesHeight } from "../text/line-metrics.js";
 import { HorizontalAlignment, SizedPDFElement } from "./pdf-element.js";
 import { normalizeContent } from "../text/whitespace.js";
 import { coverText } from "../text/glyph-coverage.js";
-import { pageOf } from "../common/diagnostics.js";
+import { diagnose, pageOf } from "../common/diagnostics.js";
+import { BuiltFromContext } from "../layout/layout-cache.js";
 /** How far a run sits off the baseline, as a fraction of its font size (up is positive). */
 export const VERTICAL_TEXT_SHIFT = {
     baseline: 0,
@@ -31,6 +32,7 @@ function finitePoints(value, name) {
 export class TextElement extends SizedPDFElement {
     constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, ligatures, role, shownLines, }) {
         super({ x: 0, y: 0 });
+        this.broken = new BuiltFromContext(() => false);
         /** What `covered` had to remove, reported where the text is laid out on its page (see
          *  `calculateLayout`). A split paragraph's first piece carries its parent's, as `lostBefore`. */
         this.lostGlyphs = [];
@@ -140,14 +142,15 @@ export class TextElement extends SizedPDFElement {
     recased() {
         // A string is one span: from here on, measuring, breaking and drawing know only spans.
         const spans = typeof this.content === "string" ? [{ content: this.content }] : this.content;
-        if (this.textTransform === "none")
+        const transformOf = (seg) => seg.textTransform ?? this.textTransform;
+        if (spans.every((seg) => transformOf(seg) === "none"))
             return spans;
         // The capitalisation state runs THROUGH the spans: `span("hel") + span("lo")` is one word.
         let atWordStart = true;
         return spans.map((seg) => {
-            const done = applyTextTransform(seg.content, this.textTransform, atWordStart);
+            const done = applyTextTransform(seg.content, transformOf(seg), atWordStart);
             atWordStart = done.atWordStart;
-            return { ...seg, content: done.text };
+            return done.text === seg.content ? seg : { ...seg, content: done.text };
         });
     }
     lineOptions() {
@@ -194,7 +197,7 @@ export class TextElement extends SizedPDFElement {
         // would cut a paragraph at a line count it is never drawn with. Each line's height comes from
         // the fonts on it, so lines are packed by their cumulative height.
         const defaults = this.segmentDefaults();
-        const lines = breakSegmentsIntoLines(content, defaults, width, ctx.metrics, this.maxLines, this.overflow);
+        const lines = this.linesAt(width, ctx);
         let used = 0;
         let packed = 0;
         for (const line of lines) {
@@ -251,7 +254,8 @@ export class TextElement extends SizedPDFElement {
     // the same width reproduces exactly those lines (greedy is deterministic).
     cloneWithContent(content, indent = this.textIndent, piece = {}) {
         return new TextElement({
-            content,
+            // Cut from `display()`, already recased - a span's own transform too.
+            content: content.map((seg) => (seg.textTransform ?? "none") === "none" ? seg : { ...seg, textTransform: "none" }),
             fontSize: this.fontSize,
             fontFamily: this.fontFamily,
             fontStyle: this.fontStyle,
@@ -271,8 +275,8 @@ export class TextElement extends SizedPDFElement {
             textIndent: indent,
             role: this.role,
             fontFallback: this.fontFallback,
-            // The content is cut from `display()`, already recased: `capitalize` again would capitalise
-            // the half of a word continued on the next page.
+            // Already recased: `capitalize` again would capitalise the half of a word continued on the next
+            // page.
             textTransform: "none",
             breakWord: this.breakWord,
             hyphenate: this.hyphenate,
@@ -281,12 +285,7 @@ export class TextElement extends SizedPDFElement {
         }).asPieceOf(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
     }
     calculateLayout(constraints, offset, ctx) {
-        // Bounded width (e.g. inside a Column) wraps to that width; an unbounded width
-        // (e.g. inside a Row) means the text takes its natural single-line width and does
-        // not wrap. Sized by `measure`, so a measured text and a laid-out one cannot differ. The style is
-        // resolved here too: a size from the cache skips `computeSize`, and drawing reads the style.
-        this.resolveStyle(ctx);
-        const size = this.measure(constraints, ctx);
+        const { size, lines } = this.sizeWith(constraints, ctx);
         this.x = offset.x;
         this.y = offset.y;
         this.resolved = this.display(ctx.metrics);
@@ -295,6 +294,20 @@ export class TextElement extends SizedPDFElement {
             ctx.metrics.reportMissingGlyph?.(lost, this, pageOf(ctx));
         this.width = size.width;
         this.height = size.height;
+        // A line with a piece that could not break is drawn past the edge - say so.
+        const overrun = Math.max(0, ...lines.map((line) => line.overrun));
+        if (constraints.hasBoundedWidth && overrun > 0.01) {
+            diagnose(ctx.diagnostics, {
+                code: "overflow-wide",
+                severity: "warning",
+                message: `A line of this Text runs ${Math.round(overrun)}pt past its ${Math.round(size.width)}pt; ` +
+                    "a word in it cannot break. Let it break (`breakWord`, `hyphenate`), make room, or clip " +
+                    'with a Box\'s `overflow: "hidden"`.',
+                about: this,
+                page: pageOf(ctx),
+                fallback: "silent",
+            });
+        }
         // Top-left coordinates (y = top of the text box). The baseline offset and the
         // Y-flip are applied downstream (the line-builder positions baselines, the seam
         // flips to PDF), so the element stays coordinate-system-blind.
@@ -311,29 +324,42 @@ export class TextElement extends SizedPDFElement {
         return BoxConstraints.loose(constraints.maxWidth, Infinity);
     }
     computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx).size;
+    }
+    /**
+     * The one sizing path, for measuring and layout alike: a bounded width wraps to it (in a Column), an
+     * unbounded one takes the natural single-line width (in a Row). The lines are what layout checks.
+     * The style is resolved here, as drawing reads it.
+     */
+    /** The text broken at `width`: once per context and width, for measuring, layout and splitting. */
+    linesAt(width, ctx) {
+        return this.broken.get(ctx, width, () => breakSegmentsIntoLines(this.display(ctx.metrics), this.segmentDefaults(), width, ctx.metrics, this.maxLines, this.overflow));
+    }
+    sizeWith(constraints, ctx) {
         this.resolveStyle(ctx);
-        const content = this.display(ctx.metrics);
         const width = constraints.hasBoundedWidth
             ? constraints.maxWidth
             : this.naturalWidth(ctx.metrics);
-        return { width, height: this.measuredHeight(ctx.metrics, width, content) };
-    }
-    measuredHeight(metrics, width, content) {
-        return textHeight(content, this.segmentDefaults(), width, metrics, this.maxLines, this.overflow, this.lineHeight);
+        const defaults = this.segmentDefaults();
+        const lines = this.linesAt(width, ctx);
+        return {
+            size: { width, height: linesHeight(lines, defaults, ctx.metrics, this.lineHeight) },
+            lines,
+        };
     }
     /** The unwrapped single-line width of the content (used when width is unbounded, e.g. inside a Row).
      *  Must match the breaker's one-line sum BIT for bit - it adds `width + (space + word)`, and the same
      *  numbers grouped differently drift by a sub-ULP, enough to wrap a text inside its own natural-width
      *  box. `singleLineWidth` is that sum. */
     naturalWidth(metrics) {
-        // The breaker's own sum, to the last bit - see `singleLineWidth`.
-        const oneLine = (text, family, size, style, letterSpacing) => singleLineWidth(text, 
-        // `ligatures` is part of the font: it decides which glyphs are drawn, hence the width.
-        { fontFamily: family, fontSize: size, fontStyle: style, ligatures: this.ligatures }, metrics, letterSpacing, this.wordSpacing);
+        const defaults = this.segmentDefaults();
         // The FIRST line starts `textIndent` in, so an unbounded box has to be that much wider.
         const indent = Math.max(0, this.textIndent);
-        return this.display(metrics).reduce((sum, seg) => sum +
-            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing), indent);
+        return this.display(metrics).reduce((sum, seg) => {
+            // The breaker's own sum, to the last bit - see `singleLineWidth`.
+            const run = runStyleOf(seg, defaults);
+            return (sum + singleLineWidth(seg.content, run.font, metrics, run.letterSpacing, run.wordSpacing));
+        }, indent);
     }
     /**
      * The widest piece of this text that cannot be broken - CSS's `min-content` width. A shrinking flex
@@ -350,25 +376,22 @@ export class TextElement extends SizedPDFElement {
             return 0;
         this.resolveStyle(ctx);
         const metrics = ctx.metrics;
-        const widest = (text, family, size, style, letterSpacing) => {
-            // `ligatures` belongs to the FONT: it decides which glyphs are drawn and therefore how wide the
-            // piece is. Leaving it out here would measure a floor the drawing never matches.
-            const font = {
-                fontFamily: family,
-                fontSize: size,
-                fontStyle: style,
-                ligatures: this.ligatures,
-            };
+        // The run style is the FONT a piece is measured in: `ligatures` decides which glyphs are drawn and
+        // therefore how wide it is. Leaving it out would measure a floor the drawing never matches.
+        const widest = (text, run) => {
             // Split on the same boundaries the breaker uses - a hard break ends a line too, and so may a
-            // hyphen inside a word.
-            const pieces = this.breakWord || this.hyphenate ? [...text] : text.split(/[ \n]/).flatMap(hyphenPieces);
-            return pieces.reduce((max, piece) => Math.max(max, runAdvance(metrics, piece, font, letterSpacing)), 0);
+            // hyphen inside a word. A run that may split its words may split them anywhere.
+            const pieces = run.splitting.breakWord || run.splitting.hyphenate
+                ? [...text]
+                : text.split(/[ \n]/).flatMap(hyphenPieces);
+            return pieces.reduce((max, piece) => Math.max(max, runAdvance(metrics, piece, run.font, run.letterSpacing)), 0);
         };
+        const defaults = this.segmentDefaults();
         const content = this.display(metrics);
         // Segments join without a space, so a word may straddle two of them; taking the widest piece per
         // segment can therefore UNDER-estimate. That errs towards squeezing a little too far, which lands
         // back on the old overflow behaviour rather than on something new.
-        return content.reduce((max, seg) => Math.max(max, widest(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing)), 0);
+        return content.reduce((max, seg) => Math.max(max, widest(seg.content, runStyleOf(seg, defaults))), 0);
     }
     getProps() {
         return {

package/dist/ir/display-list.d.ts

@@ -1,3 +1,4 @@
+import type { ImageColor, Orientation } from "../utils/image-helper.js";
 import { Color } from "../common/color.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
@@ -62,7 +63,7 @@ export interface Rect {
     y: number;
     width: number;
     height: number;
-    /** Solid colour, or a gradient whose anchor points are in absolute page coordinates. */
+    /** Solid color, or a gradient whose anchor points are in absolute page coordinates. */
     fill?: Color | Gradient;
     stroke?: Color;
     strokeWidth: number;
@@ -94,6 +95,10 @@ export interface Image {
     imageType: string;
     /** Flate-compressed DeviceGray alpha channel for a transparent PNG, embedded as the XObject's /SMask. */
     smask?: string;
+    /** What the samples mean (a JPEG keeps the space it was saved in); absent = RGB. */
+    color?: ImageColor;
+    /** How the stored pixels turn upright inside the placement box (EXIF); absent = as stored. */
+    orientation?: Orientation;
     /** cover/contain fits clip the placement to the element's original frame. */
     clip?: {
         x: number;

package/dist/layout/box-constraints.d.ts

@@ -110,6 +110,18 @@ export declare function resolveSize(width: ExtentSpec, height: ExtentSpec, aspec
     height?: number;
     constraints: BoxConstraints;
 };
+/**
+ * The open axes of a box that has its own size (an image, an SVG), after `resolveSize`: one pinned axis
+ * derives the other from the own ratio; none pinned is the own size, scaled down to `bounds` and never
+ * up - the cap is what keeps it on the page.
+ */
+export declare function sizeAtOwnRatio(width: number | undefined, height: number | undefined, own: {
+    width: number;
+    height: number;
+}, bounds: BoxConstraints): {
+    width?: number;
+    height?: number;
+};
 /** The size an element resolves to and returns UP the tree. */
 export interface Size {
     width: number;

package/dist/layout/box-constraints.js

@@ -167,3 +167,20 @@ export function resolveSize(width, height, aspectRatio, constraints) {
         constraints: bounds,
     };
 }
+/**
+ * The open axes of a box that has its own size (an image, an SVG), after `resolveSize`: one pinned axis
+ * derives the other from the own ratio; none pinned is the own size, scaled down to `bounds` and never
+ * up - the cap is what keeps it on the page.
+ */
+export function sizeAtOwnRatio(width, height, own, bounds) {
+    const ratio = own.width / own.height;
+    if (width === undefined && height === undefined) {
+        // The width clamp does the width; a height cap is turned into a width at the ratio.
+        width = bounds.constrainWidth(Math.min(own.width, bounds.maxHeight * ratio));
+    }
+    if (width !== undefined && height === undefined)
+        height = bounds.constrainHeight(width / ratio);
+    else if (height !== undefined && width === undefined)
+        width = bounds.constrainWidth(height * ratio);
+    return { width, height };
+}

package/dist/layout/collect-images.js

@@ -19,10 +19,10 @@ export function collectImageElements(root) {
                 visit(c);
         else if (hasChildProp(props))
             visit(props.child);
-        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer and a
-        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there). A
-        // DeferredElement's `composed` is null until layout runs, so it cannot be reached from this
-        // pre-layout pass; an image inside a deferred subtree just skips aspect pre-resolution.
+        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer, a
+        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there), and the `sources` a
+        // DeferredElement builds from. What a PageBuilder builds does not exist yet; an image there that
+        // cannot tell its size without waiting is reported by its layout (`image-unsized`).
         const w = props;
         if (w.header instanceof PDFElement)
             visit(w.header);
@@ -30,6 +30,10 @@ export function collectImageElements(root) {
             visit(w.footer);
         if (w.body instanceof PDFElement)
             visit(w.body);
+        if (Array.isArray(w.sources))
+            for (const s of w.sources)
+                if (s instanceof PDFElement)
+                    visit(s);
     };
     visit(root);
     return out;

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

@@ -5,5 +5,7 @@ export declare function flexibleOf(child: PDFElement): FlexiblePDFElement | unde
 export declare function alignSelfOf(child: PDFElement): CrossAlign | undefined;
 /** CSS `order`, 0 when unset. */
 export declare function orderOf(child: PDFElement): number;
+/** The child is a `Box` with percentage padding. */
+export declare function hasPercentPaddingItem(child: PDFElement): boolean;
 /** CSS `flex-shrink`, 1 when unset (the CSS default). */
 export declare function flexShrinkOf(child: PDFElement): number;

package/dist/layout/flex-item.js

@@ -5,10 +5,15 @@ import { FlexiblePDFElement } from "../elements/pdf-element.js";
  * `display: contents` is: an `Expanded`, `alignSelf`, `order` or `flexShrink` inside it acts as if the
  * wrapper were not there. A value set on the wrapper itself wins over one set inside it.
  */
-/** The child, then each element it is transparent for, outermost first. */
+/**
+ * The child, then each element it is transparent for, outermost first. An `Expanded` is one of them:
+ * `Expanded(child)` is `flex: 1` on the child, so the child's `alignSelf` and `order` are the item's.
+ */
 function* itemChain(child) {
-    for (let el = child; el; el = el.proxied())
+    for (let el = child; el;) {
         yield el;
+        el = el.proxied() ?? (el instanceof FlexiblePDFElement ? el.layoutChildren()[0] : undefined);
+    }
 }
 /** The `Expanded`/`Spacer` that makes this child flexible, if any. */
 export function flexibleOf(child) {
@@ -30,6 +35,13 @@ export function orderOf(child) {
             return el.order;
     return 0;
 }
+/** The child is a `Box` with percentage padding. */
+export function hasPercentPaddingItem(child) {
+    for (const el of itemChain(child))
+        if (el.hasPercentPadding())
+            return true;
+    return false;
+}
 /** CSS `flex-shrink`, 1 when unset (the CSS default). */
 export function flexShrinkOf(child) {
     for (const el of itemChain(child))

package/dist/layout/fragmentation.d.ts

@@ -9,13 +9,15 @@ import { LayoutContext, PDFElement } from "../elements/pdf-element.js";
  * rest, so no information flows back UP after a break. This one-way flow is what keeps
  * fragmentation terminating (no overflow-cascade fixpoint).
  */
+export type ForcedBreak = boolean | "column";
 export interface FragmentResult {
     fitted: PDFElement | null;
     remainder: PDFElement | null;
-    /** The split ended at a FORCED page break (a `PageBreak`), not because the region filled up. The
-     *  remainder must start a fresh page, and an enclosing flow must stop packing too - so this bubbles
-     *  up through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
-    forceBreak?: boolean;
+    /** The split ended at a FORCED break, not because the region filled up: `true` for a page break (the
+     *  remainder starts a fresh page), `"column"` for a `ColumnBreak` in a Flow's Region (it starts the
+     *  next Region; the Flow consumes it). An enclosing flow stops packing too - so this bubbles up
+     *  through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
+    forceBreak?: ForcedBreak;
 }
 /**
  * An element that knows how to split itself across regions. Width is already finalized
@@ -40,6 +42,8 @@ export type OverflowPolicy = "error" | "warn" | "ignore";
  */
 export declare function insetContext(ctx: LayoutContext, chrome: number): LayoutContext;
 export declare function reportOverflow(child: PDFElement, childHeight: number, maxHeight: number, ctx: LayoutContext): void;
+/** Content cut off at the bottom, under the author's `onOverflow` policy. */
+export declare function reportClipped(about: PDFElement, detail: string, ctx: LayoutContext): void;
 /**
  * True if packing `children` will hit a forced cut INSIDE them: a child that IS a break, contains one
  * deeper in its subtree, or asks to break before/after itself. A flow container reports this from
@@ -48,6 +52,8 @@ export declare function reportOverflow(child: PDFElement, childHeight: number, m
  * (`breaksBefore`), so it moves whole - which is what a `keepTogether` around it relies on.
  */
 export declare function childrenForceBreak(children: PDFElement[]): boolean;
+/** The packer kept every child as it was - none came back as a piece of itself (a sized Flow). */
+export declare function packedUnchanged(children: PDFElement[], fitted: PDFElement[]): boolean;
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -65,5 +71,5 @@ export declare function childrenForceBreak(children: PDFElement[]): boolean;
 export declare function packChildren(children: PDFElement[], maxHeight: number, width: number, ctx: LayoutContext, gap?: number): {
     fitted: PDFElement[];
     remainder: PDFElement[];
-    forceBreak: boolean;
+    forceBreak: ForcedBreak;
 };