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

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

@@ -16,26 +16,34 @@ export class ExpandedElement extends FlexiblePDFElement {
         return this.child.minIntrinsicMain(horizontal, ctx);
     }
     calculateLayout(constraints, offset, ctx) {
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
+        Validator.validateFlexElement(this);
+        const size = this.sizeWith(constraints, ctx, offset);
         // Absolute placement from the parent; assignment (not +=) so re-layout is idempotent.
         this.x = offset.x;
         this.y = offset.y;
-        Validator.validateFlexElement(this);
-        if (constraints.hasBoundedHeight) {
-            // A bounded region: fill it - the normal flex behavior.
-            this.height = constraints.maxHeight;
-            this.child.calculateLayout(BoxConstraints.loose(this.width, this.height), { x: this.x, y: this.y }, ctx);
-        }
-        else {
-            // 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 childSize = this.child.calculateLayout(BoxConstraints.loose(this.width, Infinity), { x: this.x, y: this.y }, ctx);
-            this.height = childSize.height;
-        }
-        // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
-        return { width: this.width, height: this.height };
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, null);
+    }
+    /** The one sizing path: with an `offset` the child is laid out there, with `null` only measured. */
+    sizeWith(constraints, ctx, offset) {
+        // It fills its MAIN axis only. Across it, it is an ordinary child: with no width bound it takes
+        // its content's width, from THIS call - never one left over from an earlier layout.
+        const width = constraints.hasBoundedWidth ? constraints.maxWidth : Infinity;
+        // 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);
+        const childSize = offset
+            ? this.child.calculateLayout(childConstraints, { x: offset.x, y: offset.y }, ctx)
+            : this.child.measure(childConstraints, ctx);
+        return {
+            width: constraints.hasBoundedWidth ? width : childSize.width,
+            height: constraints.hasBoundedHeight ? constraints.maxHeight : childSize.height,
+        };
     }
     /**
      * When the column paginates, a flex region can't "fill" across pages, so it delegates to
@@ -51,8 +59,19 @@ export class ExpandedElement extends FlexiblePDFElement {
         return {
             fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
             remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
+            forceBreak: split.forceBreak,
         };
     }
+    // A break inside the flex child is a break in the flow it sits in.
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
     cloneWithChild(child) {
         // The basis has to come along: a fragment that lost it would claim only its share of the leftover,
         // so a `flexBasis` slot would silently change width on the page it continues onto.
@@ -61,7 +80,10 @@ export class ExpandedElement extends FlexiblePDFElement {
             basis: this.basis,
             basisFactor: this.basisFactor,
             child,
-        });
+        }).asPieceOf(this);
+    }
+    layoutChildren() {
+        return [this.child];
     }
     getProps() {
         return {

package/dist/elements/layout/keep-together-element.d.ts

@@ -1,10 +1,9 @@
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
-import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { FragmentResult } from "../../layout/fragmentation.js";
 import { LayoutContext, PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-element.js";
 /**
- * A layout-TRANSPARENT wrapper that tries to keep its content on ONE page (CSS `break-inside: avoid`).
- * It delegates all layout and rendering to its child, so the visual result is byte-identical to the
- * unwrapped content; only pagination behaves differently.
+ * A layout-transparent wrapper (a `ProxyElement`) that tries to keep its content on ONE page (CSS
+ * `break-inside: avoid`). Only pagination behaves differently from the unwrapped content.
  *
  * The rule, decided in `fragment`:
  *   1. Fits in the space offered here           -> place it whole.
@@ -20,23 +19,14 @@ import { LayoutContext, PDFElement } from "../pdf-element.js";
  * keeping it together: the break wins (CSS behaves the same), and we WARN once rather than silently
  * swallowing either intent.
  */
-export declare class KeepTogetherElement extends PDFElement implements Fragmentable {
-    private child;
-    private warnedBreakConflict;
+export declare class KeepTogetherElement extends ProxyElement {
     constructor({ child }: {
         child: PDFElement;
     });
-    /** Layout-transparent: the floor is whatever the wrapped child needs. */
-    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
-    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
-    relativeSizeFactor(horizontal: boolean): number | undefined;
-    needsBoundedMain(horizontal: boolean): boolean;
-    hasForcedBreak(): boolean;
-    breaksBefore(): boolean;
-    breaksAfter(): boolean;
+    protected rewrap(child: PDFElement): PDFElement;
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
-    /** Delegate the actual split to the child, unwrapping - once we have decided to break the group, the
-     *  pieces just flow (any INNER keepTogether lives in the child subtree and still vetoes there). */
+    /** Split like any wrapper - once we have decided to break the group, the pieces flow bare but keep
+     *  the group's place in the flex line (any INNER keepTogether lives in the child and still vetoes). */
     private splitChild;
     getProps(): {
         child: PDFElement;

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

@@ -1,10 +1,9 @@
 import { BoxConstraints } from "../../layout/box-constraints.js";
-import { isFragmentable } from "../../layout/fragmentation.js";
-import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-element.js";
+import { diagnose, pageOf } from "../../common/diagnostics.js";
 /**
- * A layout-TRANSPARENT wrapper that tries to keep its content on ONE page (CSS `break-inside: avoid`).
- * It delegates all layout and rendering to its child, so the visual result is byte-identical to the
- * unwrapped content; only pagination behaves differently.
+ * A layout-transparent wrapper (a `ProxyElement`) that tries to keep its content on ONE page (CSS
+ * `break-inside: avoid`). Only pagination behaves differently from the unwrapped content.
  *
  * The rule, decided in `fragment`:
  *   1. Fits in the space offered here           -> place it whole.
@@ -20,50 +19,29 @@ import { PDFElement } from "../pdf-element.js";
  * keeping it together: the break wins (CSS behaves the same), and we WARN once rather than silently
  * swallowing either intent.
  */
-export class KeepTogetherElement extends PDFElement {
+export class KeepTogetherElement extends ProxyElement {
     constructor({ child }) {
-        super();
-        this.warnedBreakConflict = false;
-        this.child = child;
+        super(child);
     }
-    /** Layout-transparent: the floor is whatever the wrapped child needs. */
-    minIntrinsicMain(horizontal, ctx) {
-        return this.child.minIntrinsicMain(horizontal, ctx);
-    }
-    calculateLayout(constraints, offset, ctx) {
-        return this.child.calculateLayout(constraints, offset, ctx);
-    }
-    // Transparent: forward the sizing hints the flex parent reads, so a %-sized or Spacer-holding child
-    // keeps working when it is wrapped (the wrapper must not swallow these).
-    relativeSizeFactor(horizontal) {
-        return this.child.relativeSizeFactor(horizontal);
-    }
-    needsBoundedMain(horizontal) {
-        return this.child.needsBoundedMain(horizontal);
-    }
-    // Transparent to break control: a break-before/after on the wrapped element still applies to the group
-    // as a whole, and an inner forced break still forces the parent to fragment us (so `fragment` runs).
-    hasForcedBreak() {
-        return this.child.hasForcedBreak();
-    }
-    breaksBefore() {
-        return this.child.breaksBefore();
-    }
-    breaksAfter() {
-        return this.child.breaksAfter();
+    // Once the group is broken, its pieces flow bare (see `splitChild`).
+    rewrap(child) {
+        return child;
     }
     fragment(maxHeight, width, ctx) {
         // Contradiction: a forced break inside the group beats keeping it together. Split at the break by
         // delegating to the child (which honours it), and say so once - never keep such a group whole.
         if (this.child.hasForcedBreak()) {
-            if (!this.warnedBreakConflict) {
-                this.warnedBreakConflict = true;
-                console.warn("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.");
-            }
+            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.",
+                about: this,
+                page: pageOf(ctx),
+            });
             return this.splitChild(maxHeight, width, ctx);
         }
-        const natural = this.child.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
+        const natural = this.child.measure(BoxConstraints.loose(width, Infinity), ctx).height;
         // 1. Fits in the offered space: keep whole.
         if (natural <= maxHeight)
             return { fitted: this, remainder: null };
@@ -76,12 +54,10 @@ export class KeepTogetherElement extends PDFElement {
         // 3. Bigger than a whole page: it can never be kept together, so split it.
         return this.splitChild(maxHeight, width, ctx);
     }
-    /** Delegate the actual split to the child, unwrapping - once we have decided to break the group, the
-     *  pieces just flow (any INNER keepTogether lives in the child subtree and still vetoes there). */
+    /** Split like any wrapper - once we have decided to break the group, the pieces flow bare but keep
+     *  the group's place in the flex line (any INNER keepTogether lives in the child and still vetoes). */
     splitChild(maxHeight, width, ctx) {
-        if (!isFragmentable(this.child))
-            return { fitted: null, remainder: this };
-        return this.child.fragment(maxHeight, width, ctx);
+        return super.fragment(maxHeight, width, ctx);
     }
     getProps() {
         return { child: this.child };

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

@@ -1,26 +1,21 @@
-import { PDFElement, LayoutContext } from "../pdf-element.js";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-element.js";
 /**
  * Makes its child a clickable hyperlink. `href` is an external URL; `dest` is an internal named
- * destination (an `Anchor` elsewhere in the document) - exactly one is set. Layout-transparent: it
- * delegates `calculateLayout` to the child and records the resulting box, which the renderer turns into
- * a `Link` IR node (and the page renderer into a /Link annotation). The link draws nothing itself -
- * style the child (e.g. a blue Text) if you want it to look like a link.
+ * destination (an `Anchor` elsewhere in the document) - exactly one is set. Layout-transparent (a
+ * `ProxyElement`); the renderer turns the child's box into a `Link` IR node (and the page renderer into
+ * a /Link annotation). The link draws nothing itself - style the child (e.g. a blue Text) if you want it
+ * to look like a link. Split across pages, every piece stays clickable.
  */
-export declare class LinkElement extends PDFElement {
+export declare class LinkElement extends ProxyElement {
     private href?;
     private dest?;
-    private child;
-    private x;
-    private y;
-    private width;
-    private height;
     constructor({ href, dest, child }: {
         href?: string;
         dest?: string;
         child: PDFElement;
     });
-    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected rewrap(child: PDFElement): PDFElement;
     getProps(): {
         href: string | undefined;
         dest: string | undefined;

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

@@ -1,29 +1,19 @@
-import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-element.js";
 /**
  * Makes its child a clickable hyperlink. `href` is an external URL; `dest` is an internal named
- * destination (an `Anchor` elsewhere in the document) - exactly one is set. Layout-transparent: it
- * delegates `calculateLayout` to the child and records the resulting box, which the renderer turns into
- * a `Link` IR node (and the page renderer into a /Link annotation). The link draws nothing itself -
- * style the child (e.g. a blue Text) if you want it to look like a link.
+ * destination (an `Anchor` elsewhere in the document) - exactly one is set. Layout-transparent (a
+ * `ProxyElement`); the renderer turns the child's box into a `Link` IR node (and the page renderer into
+ * a /Link annotation). The link draws nothing itself - style the child (e.g. a blue Text) if you want it
+ * to look like a link. Split across pages, every piece stays clickable.
  */
-export class LinkElement extends PDFElement {
+export class LinkElement extends ProxyElement {
     constructor({ href, dest, child }) {
-        super();
-        this.x = 0;
-        this.y = 0;
-        this.width = 0;
-        this.height = 0;
+        super(child);
         this.href = href;
         this.dest = dest;
-        this.child = child;
     }
-    calculateLayout(constraints, offset, ctx) {
-        const size = this.child.calculateLayout(constraints, offset, ctx);
-        this.x = offset.x;
-        this.y = offset.y;
-        this.width = size.width;
-        this.height = size.height;
-        return size;
+    rewrap(child) {
+        return new LinkElement({ href: this.href, dest: this.dest, child });
     }
     getProps() {
         return {

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

@@ -5,11 +5,19 @@ import { type EdgeSpecs } from "../../layout/insets.js";
 interface PaddingElementParams extends WithChild {
     /** Still unresolved: a side may be a percentage of the offered WIDTH (see `Insets`). */
     margin: EdgeSpecs;
+    /** This is a `Box`'s own padding: a percentage resolves against what the Box was offered
+     *  (`ctx.boxPaddingBase`), as CSS resolves it against the containing block. */
+    ofBox?: boolean;
 }
 export declare class PaddingElement extends SizedPDFElement implements Fragmentable {
     private child;
     private margin;
-    constructor({ margin, child }: PaddingElementParams);
+    readonly ofBox: boolean;
+    constructor({ margin, child, ofBox }: PaddingElementParams);
+    /** 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;
+    private childContext;
     /**
      * Splits the padded box across pages (box-decoration-break: clone - every fragment
      * keeps its full top/bottom inset). The child is fragmented into the space left after
@@ -17,6 +25,8 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
      * child can't be split, the whole padding moves on as the remainder.
      */
     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;
     hasForcedBreak(): boolean;
     breaksBefore(): boolean;
     breaksAfter(): boolean;
@@ -27,6 +37,10 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
      */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** The one sizing path: `layout` places the child (relative to this box), `measure` only sizes it. */
+    private sizeWith;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;
         y: number;

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

@@ -1,13 +1,22 @@
 import { Validator } from "../../validators/element-validator.js";
 import { SizedPDFElement } from "../pdf-element.js";
 import { BoxConstraints } from "../../layout/box-constraints.js";
-import { isFragmentable } from "../../layout/fragmentation.js";
+import { insetContext, isFragmentable, } from "../../layout/fragmentation.js";
 import { resolveEdges } from "../../layout/insets.js";
 export class PaddingElement extends SizedPDFElement {
-    constructor({ margin, child }) {
+    constructor({ margin, child, ofBox = false }) {
         super({ x: 0, y: 0 });
         this.child = child;
         this.margin = margin;
+        this.ofBox = ofBox;
+    }
+    /** 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 };
     }
     /**
      * Splits the padded box across pages (box-decoration-break: clone - every fragment
@@ -19,16 +28,20 @@ export class PaddingElement extends SizedPDFElement {
         if (!isFragmentable(this.child)) {
             return { fitted: null, remainder: this };
         }
-        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, width);
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, this.percentBase(width, ctx));
         const childWidth = width - marginLeft - marginRight;
         const childMaxHeight = maxHeight - marginTop - marginBottom;
-        const split = this.child.fragment(childMaxHeight, childWidth, ctx);
+        const split = this.child.fragment(childMaxHeight, childWidth, insetContext(this.childContext(ctx), marginTop + marginBottom));
         return {
             fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
             remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
             forceBreak: split.forceBreak,
         };
     }
+    /** A wrapper: it needs a bound exactly when its child does, and passes the bound on. */
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
     hasForcedBreak() {
         return this.child.hasForcedBreak();
     }
@@ -41,7 +54,7 @@ export class PaddingElement extends SizedPDFElement {
         return this.child.breaksAfter();
     }
     cloneWithChild(child) {
-        return new PaddingElement({ margin: this.margin, child });
+        return new PaddingElement({ margin: this.margin, child, ofBox: this.ofBox }).asPieceOf(this);
     }
     /**
      * The child plus our own insets. A PERCENTAGE inset counts as zero here: it resolves against a width
@@ -52,33 +65,48 @@ export class PaddingElement extends SizedPDFElement {
         return (this.child.minIntrinsicMain(horizontal, ctx) + (horizontal ? left + right : top + bottom));
     }
     calculateLayout(constraints, offset, ctx) {
-        // Padding takes the width it is offered; its height shrink-wraps the child.
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
+        const size = this.sizeWith(constraints, ctx, "layout");
         this.x = offset.x;
         this.y = offset.y;
-        // Percentages resolve against the width we were OFFERED, so every pass gets the same answer.
-        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, constraints.maxWidth);
-        // The child is inset by the margins: shifted down/right, narrowed by the
-        // horizontal margins, and left height-unbounded so it sizes to its own content.
-        const childOffset = {
-            x: this.x + marginLeft,
-            y: this.y + marginTop,
-        };
+        this.width = size.width;
+        this.height = size.height;
+        Validator.validateSizedElement(this);
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, "measure");
+    }
+    /** The one sizing path: `layout` places the child (relative to this box), `measure` only sizes it. */
+    sizeWith(constraints, ctx, mode) {
+        // Percentages resolve against the width we were OFFERED (a Box's: what the Box was offered), so
+        // every pass gets the same answer.
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, this.percentBase(constraints.maxWidth, ctx));
+        // The child is inset by the margins: shifted down/right, narrowed by the horizontal margins, and
+        // left height-unbounded so it sizes to its own content - unless it cannot lay itself out without a
+        // bound (a stack holding a Spacer): that one gets the height inside the margins, as it would without
+        // the padding.
         const childWidth = constraints.hasBoundedWidth
             ? Math.max(0, constraints.maxWidth - marginLeft - marginRight)
             : Infinity;
-        const childConstraints = BoxConstraints.loose(childWidth, Infinity);
-        const childSize = this.child.calculateLayout(childConstraints, childOffset, ctx);
-        this.height = childSize.height + marginTop + marginBottom;
-        // Unbounded width (e.g. a fixed child in a Row): shrink-wrap to the child + insets,
-        // mirroring how Container/Row shrink-wrap. Bounded width was set above (unchanged).
-        if (!constraints.hasBoundedWidth) {
-            this.width = childSize.width + marginLeft + marginRight;
-        }
-        Validator.validateSizedElement(this);
-        // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
-        return { width: this.width ?? 0, height: this.height };
+        const childHeight = constraints.hasBoundedHeight && this.child.needsBoundedMain(false)
+            ? Math.max(0, constraints.maxHeight - marginTop - marginBottom)
+            : Infinity;
+        const childConstraints = BoxConstraints.loose(childWidth, childHeight);
+        const childCtx = this.childContext(ctx);
+        const childSize = mode === "layout"
+            ? this.child.calculateLayout(childConstraints, { x: marginLeft, y: marginTop }, childCtx)
+            : this.child.measure(childConstraints, childCtx);
+        // Padding takes the width it is offered; its height shrink-wraps the child. Unbounded width (a
+        // fixed child in a Row) shrink-wraps to the child + insets, as Container/Row do.
+        return {
+            width: constraints.hasBoundedWidth
+                ? constraints.maxWidth
+                : childSize.width + marginLeft + marginRight,
+            height: childSize.height + marginTop + marginBottom,
+        };
+    }
+    layoutChildren() {
+        return [this.child];
     }
     getProps() {
         return {

package/dist/elements/layout/page-break-element.d.ts

@@ -10,7 +10,10 @@ import { LayoutContext, PDFElement } from "../pdf-element.js";
  * too. A break wins over a `keepTogether` (a forced break cannot be avoided) - CSS behaves the same.
  */
 export declare class PageBreakElement extends PDFElement {
-    calculateLayout(_constraints: BoxConstraints, _offset: Offset, _ctx: LayoutContext): Size;
+    /** The page it was last laid out on - only so an ineffective break can name it. */
+    page?: number;
+    calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(): Size;
     isPageBreak(): boolean;
     hasForcedBreak(): boolean;
     getProps(): Record<string, never>;

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

@@ -1,4 +1,5 @@
 import { PDFElement } from "../pdf-element.js";
+import { pageOf } from "../../common/diagnostics.js";
 /**
  * A forced page break. Placed in a flow (a `Column`/`Row`/`Box`), it makes everything AFTER it start
  * on a fresh page, no matter how much space is left. It takes zero space and draws nothing - the
@@ -9,7 +10,11 @@ import { PDFElement } from "../pdf-element.js";
  * too. A break wins over a `keepTogether` (a forced break cannot be avoided) - CSS behaves the same.
  */
 export class PageBreakElement extends PDFElement {
-    calculateLayout(_constraints, _offset, _ctx) {
+    calculateLayout(_constraints, _offset, ctx) {
+        this.page = pageOf(ctx);
+        return { width: 0, height: 0 };
+    }
+    computeSize() {
         return { width: 0, height: 0 };
     }
     isPageBreak() {

package/dist/elements/layout/page-builder-element.d.ts

@@ -26,6 +26,11 @@ export declare class PageBuilderElement extends PDFElement {
     /** The real page info during the render pass; a provisional "1 of 1" while paginating. */
     private infoFrom;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** It is built from the page it lands on. */
+    dependsOnPage(): boolean;
+    /** Builds a throwaway subtree to size it; only a real layout keeps what it built. */
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         composed: PDFElement | undefined;
     };

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

@@ -36,9 +36,20 @@ export class PageBuilderElement extends PDFElement {
         this.composed = this.build(this.infoFrom(ctx));
         return this.composed.calculateLayout(constraints, offset, ctx);
     }
+    /** It is built from the page it lands on. */
+    dependsOnPage() {
+        return true;
+    }
+    /** Builds a throwaway subtree to size it; only a real layout keeps what it built. */
+    computeSize(constraints, ctx) {
+        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.
+    layoutChildren() {
+        return this.composed ? [this.composed] : [];
+    }
     getProps() {
         return { composed: this.composed };
     }

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

@@ -38,10 +38,22 @@ interface PositionedElementParams extends WithChild, PositionedInsets {
 export declare class PositionedElement extends PDFElement {
     private child;
     private insets;
+    private placeCtx?;
     constructor({ child, top, right, bottom, left, h, v, x, y }: PositionedElementParams);
     calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
-    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
-    private placeInFrame;
+    /** Out of flow: it takes no room, and measuring registers nothing with the frame. */
+    protected computeSize(): Size;
+    layoutChildren(): readonly PDFElement[];
+    /**
+     * Lays the child out at the resolved position inside (or overflowing) a frame of `frameSize`. The
+     * offset is relative to the frame's top-left; its owner draws the child from there.
+     */
+    placeIn(frameSize: Size, frameCtx: LayoutContext): void;
     getProps(): WithChild;
 }
+/**
+ * The `Positioned` elements a frame owns, in tree order: every one below `roots`, including those
+ * inside another `Positioned`, but none below a nested frame - that one places its own.
+ */
+export declare function positionedIn(roots: readonly (PDFElement | undefined)[]): PositionedElement[];
 export {};

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

@@ -24,12 +24,24 @@ export class PositionedElement extends PDFElement {
             throw new Error("Positioned found no positioning frame. It must sit inside a Page (header, footer or body) " +
                 "or inside a Box({ relative: true }).");
         }
-        // Defer to the frame: it calls back once it has sized itself. Out of flow either way.
-        ctx.frame.place.push((frame, frameCtx) => this.placeInFrame(frame, frameCtx));
+        // Out of flow: it takes no room here. The frame's owner places it once it knows its own size.
+        this.placeCtx = ctx;
         return { width: 0, height: 0 };
     }
-    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
-    placeInFrame(frame, ctx) {
+    /** Out of flow: it takes no room, and measuring registers nothing with the frame. */
+    computeSize() {
+        return { width: 0, height: 0 };
+    }
+    layoutChildren() {
+        return [this.child];
+    }
+    /**
+     * Lays the child out at the resolved position inside (or overflowing) a frame of `frameSize`. The
+     * offset is relative to the frame's top-left; its owner draws the child from there.
+     */
+    placeIn(frameSize, frameCtx) {
+        const ctx = this.placeCtx ?? frameCtx;
+        const frame = { origin: { x: 0, y: 0 }, size: frameSize };
         const { top, right, bottom, left, h, v, x: nudgeX, y: nudgeY } = this.insets;
         // An axis is PINNED (stretched) only when BOTH of its EDGES are given; otherwise the child
         // shrink-wraps its content (unbounded), the CSS rule for an absolutely-positioned element. An
@@ -42,12 +54,7 @@ export class PositionedElement extends PDFElement {
             : Infinity;
         const constraints = BoxConstraints.loose(width, height);
         // Measure first (so end/center anchors and right/bottom edges resolve against the child's size).
-        // The measuring pass gets a throwaway `place` list: this subtree is laid out twice, and a nested
-        // out-of-flow child would otherwise register its placement on both passes.
-        const measureCtx = ctx.frame
-            ? { ...ctx, frame: { ...ctx.frame, place: [] } }
-            : ctx;
-        const measured = this.child.calculateLayout(constraints, { x: 0, y: 0 }, measureCtx);
+        const measured = this.child.measure(constraints, ctx);
         // Resolve one axis: a near-edge pins to origin, a far-edge pins to the far side; otherwise the
         // anchor (default `start`) positions the child and the nudge shifts it from there.
         const place = (origin, frameExtent, childExtent, nearEdge, farEdge, anchor, nudge) => {
@@ -71,3 +78,22 @@ export class PositionedElement extends PDFElement {
         return { child: this.child };
     }
 }
+/**
+ * The `Positioned` elements a frame owns, in tree order: every one below `roots`, including those
+ * inside another `Positioned`, but none below a nested frame - that one places its own.
+ */
+export function positionedIn(roots) {
+    const found = [];
+    const walk = (el) => {
+        if (el instanceof PositionedElement)
+            found.push(el);
+        if (el.isPositioningFrame())
+            return;
+        for (const child of el.layoutChildren())
+            walk(child);
+    };
+    for (const root of roots)
+        if (root)
+            walk(root);
+    return found;
+}