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

package/dist/elements/layout/deferred-element.js

@@ -1,16 +1,31 @@
 import { isFragmentable } from "../../layout/fragmentation.js";
 import { PDFElement } from "../pdf-element.js";
 import { BuiltFromContext } from "../../layout/layout-cache.js";
+const builtOnPage = (subtree) => subtree.dependsOnPage();
 /**
  * Builds its subtree at layout time via `resolve(ctx, width)`, so the tree can depend on font
  * metrics and on the width it gets (e.g. a Table fitting its `"auto"` and `fr` columns to the cell
  * content and its own width). The engine stays table-agnostic - the closure comes from the API layer.
  */
 export class DeferredElement extends PDFElement {
-    constructor(resolve) {
+    /**
+     * `sources`: the elements the subtree will be built from (a table's cells), so the async pass before
+     * layout can reach what is not built yet - an image from a URL in a cell.
+     */
+    constructor(resolve, sources = []) {
         super();
         this.resolve = resolve;
-        this.built = new BuiltFromContext();
+        this.sources = sources;
+        this.built = new BuiltFromContext(builtOnPage);
+    }
+    /** A copy builds a subtree of its own, from copies, so even element cells it holds are its own. */
+    clone() {
+        const copy = super.clone();
+        const resolve = this.resolve;
+        copy.resolve = (ctx, width) => resolve(ctx, width).clone();
+        copy.built = new BuiltFromContext(builtOnPage);
+        copy.composed = undefined;
+        return copy;
     }
     /** The subtree for this context and width: built once, and again only when one of them changes. */
     subtree(ctx, width) {
@@ -41,6 +56,6 @@ export class DeferredElement extends PDFElement {
         return this.composed ? [this.composed] : [];
     }
     getProps() {
-        return { composed: this.composed };
+        return { composed: this.composed, sources: this.sources };
     }
 }

package/dist/elements/layout/expanded-element.d.ts

@@ -12,6 +12,8 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
     constructor({ flex, basis, basisFactor, child }: ExpandedElementParams);
     /** Layout-transparent: the floor is whatever the wrapped child needs. */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
+    /** And the ceiling is the child's. */
+    maxExtent(horizontal: boolean): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
     /** The one sizing path: with an `offset` the child is laid out there, with `null` only measured. */
@@ -23,6 +25,8 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
      * whole Expanded moves on.
      */
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    needsRegion(): boolean;
+    needsBoundedMain(horizontal: boolean): boolean;
     hasForcedBreak(): boolean;
     breaksBefore(): boolean;
     breaksAfter(): boolean;

package/dist/elements/layout/expanded-element.js

@@ -15,6 +15,10 @@ export class ExpandedElement extends FlexiblePDFElement {
     minIntrinsicMain(horizontal, ctx) {
         return this.child.minIntrinsicMain(horizontal, ctx);
     }
+    /** And the ceiling is the child's. */
+    maxExtent(horizontal) {
+        return this.child.maxExtent(horizontal);
+    }
     calculateLayout(constraints, offset, ctx) {
         Validator.validateFlexElement(this);
         const size = this.sizeWith(constraints, ctx, offset);
@@ -36,7 +40,9 @@ export class ExpandedElement extends FlexiblePDFElement {
         // A bounded region: fill it - the normal flex behavior. Unbounded (measuring while paginating):
         // there's no leftover space to fill, so collapse to the child's natural height. This lets an
         // overflowing column flow instead of the flex silently hiding the overflow.
-        const childConstraints = BoxConstraints.loose(width, constraints.hasBoundedHeight ? constraints.maxHeight : Infinity);
+        // `Expanded(child)` is `flex: 1` on the child: the extent its line SET (the min) is the child's too,
+        // so its own width or height gives way to its share - as in CSS and Flutter.
+        const childConstraints = new BoxConstraints(constraints.minWidth, width, constraints.minHeight, constraints.hasBoundedHeight ? constraints.maxHeight : Infinity);
         const childSize = offset
             ? this.child.calculateLayout(childConstraints, { x: offset.x, y: offset.y }, ctx)
             : this.child.measure(childConstraints, ctx);
@@ -62,6 +68,13 @@ export class ExpandedElement extends FlexiblePDFElement {
             forceBreak: split.forceBreak,
         };
     }
+    needsRegion() {
+        return this.child.needsRegion();
+    }
+    // The child IS the flex item: what it needs across the line, the line must give it.
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
     // A break inside the flex child is a break in the flow it sits in.
     hasForcedBreak() {
         return this.child.hasForcedBreak();

package/dist/elements/layout/flow-element.d.ts

@@ -0,0 +1,109 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { type FragmentResult } from "../../layout/fragmentation.js";
+import { ContainerElement } from "../container-element.js";
+import { LayoutContext, PDFElement, SizedPDFElement } from "../pdf-element.js";
+/** What a template is built from: `index` counts THIS Flow's pages (0 = where it starts). */
+export interface FlowPage {
+    index: number;
+    pageNumber: number;
+}
+export type FlowTemplate = (page: FlowPage) => PDFElement;
+/** A template with no `Region` would place nothing on every page, forever. */
+export declare class FlowWithoutRegionError extends Error {
+    constructor();
+}
+/** A template that leaves every Region without room, where the Flow cannot move on to find more. */
+export declare class FlowRegionsEmptyError extends Error {
+    constructor(width: number, height: number);
+}
+/** Laid out with no height to fill: every line would land in the first Region. */
+export declare class FlowUnboundedError extends Error {
+    constructor();
+}
+/** A PageBuilder builds again for the page it is drawn on, so Regions inside it lose their content. */
+export declare class RegionInPageBuilderError extends Error {
+    constructor();
+}
+/**
+ * One page of a Flow: its template, with each Region holding its content. It is drawn laid out at the
+ * height it was filled at - not at its own size, which a template that does not fill (`50%`) differs from.
+ */
+export declare class FlowPieceElement extends SizedPDFElement {
+    private readonly template;
+    private readonly size;
+    private readonly bound;
+    private readonly page;
+    constructor(template: PDFElement, size: Size, bound: number, page: object);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(): Size;
+    layoutChildren(): readonly PDFElement[];
+    getProps(): {
+        child: PDFElement;
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Content flowing through the Regions of a template, page after page. It has no height of its own -
+ * like an `Expanded`, it takes what it is given: the rest of the page when it is fragmented, the rest
+ * of a box with a height otherwise. On its last page it shrinks to what the content used.
+ */
+export declare class FlowElement extends SizedPDFElement {
+    private readonly content;
+    private readonly template;
+    private readonly index;
+    private readonly balance;
+    private piece?;
+    constructor({ content, template, index, balance, }: {
+        content: ContainerElement;
+        template: FlowTemplate;
+        index?: number;
+        balance?: boolean;
+    });
+    needsRegion(): boolean;
+    /** Its height comes from the parent, as an `Expanded`'s does. */
+    needsBoundedMain(horizontal: boolean): boolean;
+    /** The template is built from the page it lands on. */
+    dependsOnPage(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Unbounded, it has no height of its own (a parent that bounds it asks again); bounded, it fills. */
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /**
+     * The one place a page of the Flow is made: the template at `width` x `maxHeight`, the content
+     * fragmented into its Regions in turn, and - when the content ends here - the template shrunk to
+     * what it used, or balanced.
+     */
+    private fill;
+    /**
+     * The content fragmented into the laid-out Regions in turn; each holds its piece. `fresh` is how tall
+     * each Region is on a full page - what a block that does not fit here may wait for.
+     */
+    private pour;
+    /**
+     * The last page, balanced: the smallest height at which the content, poured again, still ends here,
+     * so the Regions come out about equally full. Every candidate is a real pour - breaks,
+     * `keepTogether` and orphans hold as on any page - and the last one poured is the one drawn. A
+     * candidate is silent, and one that had to clip a block it could not break is too low.
+     */
+    private balanced;
+    /**
+     * The last page: the smallest height at which every filled Region still holds what it was given.
+     * Only a layout knows how a template's Regions answer a height (`%`, stacked, `minHeight`, fixed), so
+     * each candidate is laid out and checked. The first is exact for Regions side by side (the full bound
+     * less the smallest slack); below it the bound is searched, down to the template's own height.
+     * Content that overflowed its Region at full height asks for no more than it had there.
+     */
+    private shrink;
+    layoutChildren(): readonly PDFElement[];
+    getProps(): {
+        x: number;
+        y: number;
+        width: number | undefined;
+        height: number | undefined;
+        child: ContainerElement;
+        piece: FlowPieceElement | undefined;
+    };
+}

package/dist/elements/layout/flow-element.js

@@ -0,0 +1,317 @@
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { reportClipped } from "../../layout/fragmentation.js";
+import { Diagnostics, pageOf } from "../../common/diagnostics.js";
+import { SizedPDFElement } from "../pdf-element.js";
+import { PageBuilderElement } from "./page-builder-element.js";
+import { RegionElement } from "./region-element.js";
+/** A template with no `Region` would place nothing on every page, forever. */
+export class FlowWithoutRegionError extends Error {
+    constructor() {
+        super("@jasy/pdf: a Flow's template holds no Region, so the content has nowhere to go. Put at least " +
+            "one Region in the template (in @jasy/vue: the #page slot).");
+        this.name = "FlowWithoutRegionError";
+    }
+}
+/** A template that leaves every Region without room, where the Flow cannot move on to find more. */
+export class FlowRegionsEmptyError extends Error {
+    constructor(width, height) {
+        super(`@jasy/pdf: a Flow's template leaves its Regions no room in ${Math.round(width)} x ` +
+            `${Math.round(height)}pt - every Region is 0 wide or 0 tall (too many columns or gaps for the ` +
+            "width, or the rest of the template is taller than the space). Give the Regions room." +
+            (height <= 0
+                ? " In a wrapping Row a line is only as tall as its content - give the Row around the " +
+                    "Flow a height."
+                : ""));
+        this.name = "FlowRegionsEmptyError";
+    }
+}
+/** Laid out with no height to fill: every line would land in the first Region. */
+export class FlowUnboundedError extends Error {
+    constructor() {
+        super("@jasy/pdf: a Flow takes its height from where it sits - the page, or a box with a height. " +
+            "Here it has none (in a Row without a height, for instance). Give the Row or a Box around " +
+            "the Flow a height.");
+        this.name = "FlowUnboundedError";
+    }
+}
+/** A PageBuilder builds again for the page it is drawn on, so Regions inside it lose their content. */
+export class RegionInPageBuilderError extends Error {
+    constructor() {
+        super("@jasy/pdf: a Region inside a PageBuilder - it builds again for the page it is drawn on, and " +
+            "its Regions would come back empty. A Flow's template is built for every page already and " +
+            "gets { index, pageNumber }: build the Regions there.");
+        this.name = "RegionInPageBuilderError";
+    }
+}
+/** The Regions of a laid-out template, in tree order - the order the content flows through them. */
+function regionsIn(root) {
+    const out = [];
+    const visit = (el, built) => {
+        if (el instanceof RegionElement) {
+            if (built)
+                throw new RegionInPageBuilderError();
+            out.push(el);
+        }
+        else {
+            const inBuilder = built || el instanceof PageBuilderElement;
+            for (const child of el.layoutChildren())
+                visit(child, inBuilder);
+        }
+    };
+    visit(root, false);
+    return out;
+}
+const room = (r) => r.getProps().width > 0 && r.getProps().height > 0;
+const SLACK_EPSILON = 1e-6;
+// How close the last page's height gets to the tightest one that holds the content, in points.
+const SHRINK_PRECISION = 0.01;
+/**
+ * One page of a Flow: its template, with each Region holding its content. It is drawn laid out at the
+ * height it was filled at - not at its own size, which a template that does not fill (`50%`) differs from.
+ */
+export class FlowPieceElement extends SizedPDFElement {
+    constructor(template, size, bound, page) {
+        super({ x: 0, y: 0, ...size });
+        this.template = template;
+        this.size = size;
+        this.bound = bound;
+        this.page = page;
+    }
+    calculateLayout(_constraints, offset, ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.template.calculateLayout(BoxConstraints.loose(this.size.width, this.bound), { x: 0, y: 0 }, { ...ctx, flowPage: this.page });
+        return this.size;
+    }
+    computeSize() {
+        return this.size;
+    }
+    layoutChildren() {
+        return [this.template];
+    }
+    getProps() {
+        return { x: this.x, y: this.y, ...this.size, child: this.template };
+    }
+}
+/**
+ * Content flowing through the Regions of a template, page after page. It has no height of its own -
+ * like an `Expanded`, it takes what it is given: the rest of the page when it is fragmented, the rest
+ * of a box with a height otherwise. On its last page it shrinks to what the content used.
+ */
+export class FlowElement extends SizedPDFElement {
+    constructor({ content, template, index = 0, balance = false, }) {
+        super({ x: 0, y: 0 });
+        this.content = content;
+        this.template = template;
+        this.index = index;
+        this.balance = balance;
+    }
+    needsRegion() {
+        return true;
+    }
+    /** Its height comes from the parent, as an `Expanded`'s does. */
+    needsBoundedMain(horizontal) {
+        return !horizontal;
+    }
+    /** The template is built from the page it lands on. */
+    dependsOnPage() {
+        return true;
+    }
+    fragment(maxHeight, width, ctx) {
+        // Below other content, a template with no room here may find it on the next page.
+        const filled = this.fill(maxHeight, width, ctx, !ctx.belowContent);
+        // Nothing fit: move on whole. On a fresh page the packer forces it on, so this always advances.
+        if (!filled.placed)
+            return { fitted: null, remainder: this };
+        return {
+            fitted: filled.piece,
+            remainder: filled.rest
+                ? new FlowElement({
+                    content: filled.rest,
+                    template: this.template,
+                    index: this.index + 1,
+                    balance: this.balance,
+                })
+                : null,
+            forceBreak: filled.forceBreak,
+        };
+    }
+    calculateLayout(constraints, offset, ctx) {
+        if (!constraints.hasBoundedHeight || !constraints.hasBoundedWidth) {
+            throw new FlowUnboundedError();
+        }
+        this.x = offset.x;
+        this.y = offset.y;
+        const filled = this.fill(constraints.maxHeight, constraints.maxWidth, ctx, true);
+        // Not paginated here (a box with a height): what does not fit is cut, as any overflow is.
+        if (filled.rest) {
+            reportClipped(this, "a Flow has more content than its Regions hold here, and it cannot continue on a next " +
+                "page (it sits in a box with a height) - give the box more height, or let the Flow " +
+                "continue on the page.", ctx);
+        }
+        this.piece = filled.piece;
+        const size = this.piece.calculateLayout(constraints, { x: 0, y: 0 }, ctx);
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    /** Unbounded, it has no height of its own (a parent that bounds it asks again); bounded, it fills. */
+    computeSize(constraints, ctx) {
+        if (!constraints.hasBoundedHeight || !constraints.hasBoundedWidth) {
+            return { width: constraints.hasBoundedWidth ? constraints.maxWidth : 0, height: 0 };
+        }
+        return this.fill(constraints.maxHeight, constraints.maxWidth, ctx, false).piece.measure(constraints, ctx);
+    }
+    /**
+     * The one place a page of the Flow is made: the template at `width` x `maxHeight`, the content
+     * fragmented into its Regions in turn, and - when the content ends here - the template shrunk to
+     * what it used, or balanced.
+     */
+    fill(maxHeight, width, ctx, final) {
+        const template = this.template({ index: this.index, pageNumber: pageOf(ctx) ?? 1 });
+        // Laid out as this page of the Flow, its Regions claim themselves - wherever the template made
+        // them, a PageBuilder or a Table included - and are collected from the laid-out tree.
+        const pageCtx = { ...ctx, flowPage: this };
+        const layOut = (height) => template.calculateLayout(BoxConstraints.loose(width, height), { x: 0, y: 0 }, pageCtx);
+        const size = layOut(maxHeight);
+        const regions = regionsIn(template);
+        if (regions.length === 0)
+            throw new FlowWithoutRegionError();
+        // No room here: every Region is empty, or the rest of the template (its height with the Regions
+        // empty) is taller than the space.
+        const own = template.measure(BoxConstraints.loose(width, Infinity), ctx).height;
+        if (own > maxHeight + SLACK_EPSILON || !regions.some(room)) {
+            if (final)
+                throw new FlowRegionsEmptyError(width, maxHeight);
+            const piece = new FlowPieceElement(template, size, maxHeight, this);
+            return { piece, rest: this.content, placed: false, forceBreak: false };
+        }
+        const { rest, placed, forceBreak } = this.pour(regions, ctx);
+        const ends = !rest && placed;
+        const last = !ends
+            ? null
+            : this.balance && regions.filter(room).length > 1
+                ? this.balanced(regions, own, maxHeight, layOut, ctx)
+                : this.shrink(regions, own, maxHeight, layOut, ctx);
+        const piece = last
+            ? new FlowPieceElement(template, last.size, last.bound, this)
+            : new FlowPieceElement(template, size, maxHeight, this);
+        return { piece, rest, placed, forceBreak };
+    }
+    /**
+     * The content fragmented into the laid-out Regions in turn; each holds its piece. `fresh` is how tall
+     * each Region is on a full page - what a block that does not fit here may wait for.
+     */
+    pour(regions, ctx, fresh) {
+        let rest = this.content;
+        let placed = false;
+        let forceBreak = false;
+        for (const region of regions)
+            region.hold(null);
+        for (const region of regions) {
+            if (!rest)
+                break;
+            if (!room(region))
+                continue;
+            const { width: w, height: h } = region.getProps();
+            // Each Region is a fragmentation region of its own: a page break inside it is measured by it.
+            const split = rest.fragment(h, w, {
+                ...ctx,
+                pageBodyHeight: fresh?.get(region) ?? h,
+                inFlowRegion: true,
+                flowPage: undefined,
+            });
+            region.hold(split.fitted);
+            if (split.fitted)
+                placed = true;
+            rest = split.remainder;
+            // A column break is this Flow's: on to the next Region (or the next page's first).
+            if (split.forceBreak === "column")
+                continue;
+            if (split.forceBreak) {
+                forceBreak = true;
+                break;
+            }
+        }
+        return { rest, placed, forceBreak };
+    }
+    /**
+     * The last page, balanced: the smallest height at which the content, poured again, still ends here,
+     * so the Regions come out about equally full. Every candidate is a real pour - breaks,
+     * `keepTogether` and orphans hold as on any page - and the last one poured is the one drawn. A
+     * candidate is silent, and one that had to clip a block it could not break is too low.
+     */
+    balanced(regions, own, maxHeight, layOut, ctx) {
+        const fresh = new Map(regions.map((r) => [r, r.getProps().height]));
+        const endsAt = (bound) => {
+            layOut(bound);
+            let clipped = false;
+            const trial = new Diagnostics();
+            trial.setHandler((d) => (clipped || (clipped = d.code === "overflow-clipped")));
+            const poured = this.pour(regions, { ...ctx, onOverflow: "ignore", diagnostics: trial }, fresh);
+            return !poured.rest && poured.placed && !clipped;
+        };
+        let low = Math.min(maxHeight, own);
+        let high = maxHeight;
+        while (high - low > SHRINK_PRECISION) {
+            const mid = (low + high) / 2;
+            if (endsAt(mid))
+                high = mid;
+            else
+                low = mid;
+        }
+        const size = layOut(high);
+        this.pour(regions, ctx, fresh);
+        return { size, bound: high };
+    }
+    /**
+     * The last page: the smallest height at which every filled Region still holds what it was given.
+     * Only a layout knows how a template's Regions answer a height (`%`, stacked, `minHeight`, fixed), so
+     * each candidate is laid out and checked. The first is exact for Regions side by side (the full bound
+     * less the smallest slack); below it the bound is searched, down to the template's own height.
+     * Content that overflowed its Region at full height asks for no more than it had there.
+     */
+    shrink(regions, own, maxHeight, layOut, ctx) {
+        const filled = regions.filter((r) => r.held);
+        const needed = new Map(filled.map((r) => {
+            const { width, height } = r.getProps();
+            const used = r.held.measure(BoxConstraints.loose(width, Infinity), ctx).height;
+            return [r, Math.min(used, height)];
+        }));
+        const slack = Math.min(...filled.map((r) => r.getProps().height - needed.get(r)));
+        const fitsAt = (bound) => {
+            const size = layOut(bound);
+            const fits = filled.every((r) => r.getProps().height + SLACK_EPSILON >= needed.get(r));
+            return fits ? { size, bound } : null;
+        };
+        let low = Math.min(maxHeight, own);
+        let high = maxHeight;
+        const exact = fitsAt(Math.max(low, maxHeight - slack));
+        if (exact) {
+            if (exact.bound === low)
+                return exact;
+            high = exact.bound;
+        }
+        while (high - low > SHRINK_PRECISION) {
+            const mid = (low + high) / 2;
+            if (fitsAt(mid))
+                high = mid;
+            else
+                low = mid;
+        }
+        return { size: layOut(high), bound: high };
+    }
+    layoutChildren() {
+        return [this.content];
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+            child: this.content,
+            piece: this.piece,
+        };
+    }
+}

package/dist/elements/layout/keep-together-element.js

@@ -34,13 +34,25 @@ export class KeepTogetherElement extends ProxyElement {
             diagnose(ctx.diagnostics, {
                 code: "keep-together-split",
                 severity: "warning",
-                message: "keepTogether contains a forced page break (PageBreak / breakBefore / breakAfter). The break " +
-                    "wins and the group is split. Remove the break, or the keepTogether, to resolve this.",
+                message: "keepTogether contains a forced break (PageBreak, ColumnBreak, breakBefore / breakAfter). " +
+                    "The break wins and the group is split. Remove the break, or the keepTogether, to resolve this.",
                 about: this,
                 page: pageOf(ctx),
             });
             return this.splitChild(maxHeight, width, ctx);
         }
+        // A region-sized child (a Flow) has no height of its own to compare, so the same three rules ask
+        // whether it ENDS here, or on a fresh page.
+        if (this.child.needsRegion()) {
+            const here = this.splitChild(maxHeight, width, ctx);
+            if (!here.remainder)
+                return here;
+            const pageBody = ctx.pageBodyHeight ?? maxHeight;
+            if (maxHeight < pageBody && !this.splitChild(pageBody, width, ctx).remainder) {
+                return { fitted: null, remainder: this };
+            }
+            return here;
+        }
         const natural = this.child.measure(BoxConstraints.loose(width, Infinity), ctx).height;
         // 1. Fits in the offered space: keep whole.
         if (natural <= maxHeight)

package/dist/elements/layout/padding-element.d.ts

@@ -14,6 +14,8 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
     private margin;
     readonly ofBox: boolean;
     constructor({ margin, child, ofBox }: PaddingElementParams);
+    /** Some side is a percentage. */
+    get hasPercentSide(): boolean;
     /** The width a percentage side resolves against, and the context the child sees: a Box's base is
      *  for this padding alone, so it does not travel further down. */
     private percentBase;
@@ -27,6 +29,7 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     /** A wrapper: it needs a bound exactly when its child does, and passes the bound on. */
     needsBoundedMain(horizontal: boolean): boolean;
+    needsRegion(): boolean;
     hasForcedBreak(): boolean;
     breaksBefore(): boolean;
     breaksAfter(): boolean;

package/dist/elements/layout/padding-element.js

@@ -1,5 +1,5 @@
 import { Validator } from "../../validators/element-validator.js";
-import { SizedPDFElement } from "../pdf-element.js";
+import { SizedPDFElement, withPaddingBase, } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
 import { insetContext, isFragmentable, } from "../../layout/fragmentation.js";
 import { resolveEdges } from "../../layout/insets.js";
@@ -10,13 +10,17 @@ export class PaddingElement extends SizedPDFElement {
         this.margin = margin;
         this.ofBox = ofBox;
     }
+    /** Some side is a percentage. */
+    get hasPercentSide() {
+        return this.margin.some((side) => typeof side !== "number" && side.factor !== undefined);
+    }
     /** The width a percentage side resolves against, and the context the child sees: a Box's base is
      *  for this padding alone, so it does not travel further down. */
     percentBase(width, ctx) {
         return this.ofBox && ctx.boxPaddingBase !== undefined ? ctx.boxPaddingBase : width;
     }
     childContext(ctx) {
-        return ctx.boxPaddingBase === undefined ? ctx : { ...ctx, boxPaddingBase: undefined };
+        return withPaddingBase(ctx, undefined);
     }
     /**
      * Splits the padded box across pages (box-decoration-break: clone - every fragment
@@ -42,6 +46,9 @@ export class PaddingElement extends SizedPDFElement {
     needsBoundedMain(horizontal) {
         return this.child.needsBoundedMain(horizontal);
     }
+    needsRegion() {
+        return this.child.needsRegion();
+    }
     hasForcedBreak() {
         return this.child.hasForcedBreak();
     }

package/dist/elements/layout/page-builder-element.js

@@ -45,8 +45,8 @@ export class PageBuilderElement extends PDFElement {
         return this.build(this.infoFrom(ctx)).measure(constraints, ctx);
     }
     // Named `composed` (not `child`) like DeferredElement: the pre-layout image walk keys on `child`, and
-    // this subtree does not exist yet when it runs. So an Image inside a PageBuilder skips aspect-ratio
-    // pre-resolution - give it both width and height, exactly as inside a Deferred/Table subtree.
+    // this subtree does not exist yet when it runs. An Image built here reads its own size when layout
+    // asks; only one from a URL cannot, and reports `image-unsized`.
     layoutChildren() {
         return this.composed ? [this.composed] : [];
     }

package/dist/elements/layout/positioned-element.d.ts

@@ -11,6 +11,9 @@ export type PositionAnchor = "start" | "center" | "end";
  * An edge wins over an anchor on the same axis. With nothing set the child sits at the top-left.
  */
 export interface PositionedInsets {
+    /** Paint order within its stacking context: negative under the flow content, positive over it,
+     *  higher over lower; 0 or unset paints in tree order where it stands (CSS `z-index`). */
+    zIndex?: number;
     top?: number;
     right?: number;
     bottom?: number;
@@ -39,7 +42,9 @@ export declare class PositionedElement extends PDFElement {
     private child;
     private insets;
     private placeCtx?;
-    constructor({ child, top, right, bottom, left, h, v, x, y }: PositionedElementParams);
+    constructor({ child, top, right, bottom, left, h, v, x, y, zIndex }: PositionedElementParams);
+    /** Its paint order; 0 paints where it stands in the tree, anything else is sorted by its context. */
+    private readonly zIndex;
     calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
     /** Out of flow: it takes no room, and measuring registers nothing with the frame. */
     protected computeSize(): Size;
@@ -49,7 +54,9 @@ export declare class PositionedElement extends PDFElement {
      * offset is relative to the frame's top-left; its owner draws the child from there.
      */
     placeIn(frameSize: Size, frameCtx: LayoutContext): void;
-    getProps(): WithChild;
+    getProps(): WithChild & {
+        zIndex: number;
+    };
 }
 /**
  * The `Positioned` elements a frame owns, in tree order: every one below `roots`, including those