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

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

@@ -0,0 +1,43 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
+/**
+ * A wrapper that is transparent to layout (Flutter's `RenderProxyBox`): its one child gets the same
+ * constraints, sits at the same offset and gives the same size. Every sizing and pagination signal the
+ * child sends is passed on, so wrapping something never changes how it is sized or broken across
+ * pages - a `PageBreak` inside a `Link` breaks, a `Bookmark` around a chapter splits like the chapter.
+ *
+ * What a wrapper adds (a link, a jump target, a role, inherited text defaults) it adds through two
+ * hooks: `childContext` for what the child is laid out in, and `rewrap` for the pieces of a split.
+ */
+export declare abstract class ProxyElement extends PDFElement implements Fragmentable {
+    protected readonly child: PDFElement;
+    protected x: number;
+    protected y: number;
+    protected width: number;
+    protected height: number;
+    protected constructor(child: PDFElement);
+    /** The context the child is laid out in: unchanged, unless the wrapper hands something down. */
+    protected childContext(ctx: LayoutContext): LayoutContext;
+    /**
+     * This wrapper around a piece of its split child. `continued` is true for every piece but the first
+     * one that holds something: a wrapper that marks a single place (a jump target, an outline entry)
+     * returns the piece bare there, so the mark is not repeated on the next page.
+     */
+    protected abstract rewrap(child: PDFElement, continued: boolean): PDFElement;
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    layoutChildren(): readonly PDFElement[];
+    /** Transparent to a surrounding Row or Column too: it sees the child's flex properties. */
+    proxied(): PDFElement;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    needsBoundedMain(horizontal: boolean): boolean;
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
+    isPageBreak(): boolean;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
+    /** Splittable exactly when the child is; otherwise the parent moves it to the next page whole. */
+    canFragment(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+}

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

@@ -0,0 +1,94 @@
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+import { PDFElement } from "../pdf-element.js";
+/**
+ * A wrapper that is transparent to layout (Flutter's `RenderProxyBox`): its one child gets the same
+ * constraints, sits at the same offset and gives the same size. Every sizing and pagination signal the
+ * child sends is passed on, so wrapping something never changes how it is sized or broken across
+ * pages - a `PageBreak` inside a `Link` breaks, a `Bookmark` around a chapter splits like the chapter.
+ *
+ * What a wrapper adds (a link, a jump target, a role, inherited text defaults) it adds through two
+ * hooks: `childContext` for what the child is laid out in, and `rewrap` for the pieces of a split.
+ */
+export class ProxyElement extends PDFElement {
+    constructor(child) {
+        super();
+        this.child = child;
+        // The box the child took, for renderers that mark it (a link's hit area, a jump target's top).
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+    }
+    /** The context the child is laid out in: unchanged, unless the wrapper hands something down. */
+    childContext(ctx) {
+        return ctx;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        const size = this.child.calculateLayout(constraints, offset, this.childContext(ctx));
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.child.measure(constraints, this.childContext(ctx));
+    }
+    layoutChildren() {
+        return [this.child];
+    }
+    /** Transparent to a surrounding Row or Column too: it sees the child's flex properties. */
+    proxied() {
+        return this.child;
+    }
+    relativeSizeFactor(horizontal) {
+        return this.child.relativeSizeFactor(horizontal);
+    }
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
+    minIntrinsicMain(horizontal, ctx) {
+        return this.child.minIntrinsicMain(horizontal, this.childContext(ctx));
+    }
+    isPageBreak() {
+        return this.child.isPageBreak();
+    }
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
+    /** Splittable exactly when the child is; otherwise the parent moves it to the next page whole. */
+    canFragment() {
+        return isFragmentable(this.child);
+    }
+    fragment(maxHeight, width, ctx) {
+        if (!isFragmentable(this.child))
+            return { fitted: null, remainder: this };
+        const childCtx = this.childContext(ctx);
+        const split = this.child.fragment(maxHeight, width, childCtx);
+        // The child handed itself back (it all fits, or none of it does): so does the wrapper, mark included.
+        const wrap = (piece, continued) => {
+            if (piece === this.child)
+                return this;
+            const wrapped = this.rewrap(piece, continued);
+            // A wrapper dropped from a continued piece still leaves that piece in its place in the flow.
+            return wrapped === piece ? piece.takeFlexItemFrom(this) : wrapped.asPieceOf(this);
+        };
+        // A fitted piece with no height (what a leading `PageBreak` leaves) holds nothing to mark: the
+        // mark goes on with the remainder, where the content is.
+        const placed = split.fitted !== null &&
+            (split.remainder === null ||
+                split.fitted.measure(BoxConstraints.loose(width, Infinity), childCtx).height > 0);
+        return {
+            fitted: split.fitted && wrap(split.fitted, !placed),
+            remainder: split.remainder && wrap(split.remainder, placed),
+            forceBreak: split.forceBreak,
+        };
+    }
+}

package/dist/elements/layout/repeating-header-element.d.ts

@@ -17,7 +17,13 @@ export declare class RepeatingHeaderElement extends PDFElement implements Fragme
     private height;
     constructor(header: PDFElement, body: PDFElement, gap?: number);
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** The one sizing path: `layout` places header and body (relative to this box), `measure` sizes. */
+    private sizeWith;
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    /** A break inside the body is a break in the flow the table sits in. */
+    hasForcedBreak(): boolean;
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         x: number;
         y: number;

package/dist/elements/layout/repeating-header-element.js

@@ -1,5 +1,5 @@
 import { BoxConstraints } from "../../layout/box-constraints.js";
-import { isFragmentable } from "../../layout/fragmentation.js";
+import { insetContext, isFragmentable, } from "../../layout/fragmentation.js";
 import { PDFElement } from "../pdf-element.js";
 /**
  * Stacks a `header` above a `body` and, when it paginates, **repeats the header on every
@@ -19,30 +19,57 @@ export class RepeatingHeaderElement extends PDFElement {
         this.height = 0;
     }
     calculateLayout(constraints, offset, ctx) {
+        const size = this.sizeWith(constraints, ctx, "layout");
         this.x = offset.x;
         this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.sizeWith(constraints, ctx, "measure");
+    }
+    /** The one sizing path: `layout` places header and body (relative to this box), `measure` sizes. */
+    sizeWith(constraints, ctx, mode) {
         const width = constraints.hasBoundedWidth ? constraints.maxWidth : 0;
-        const h = this.header.calculateLayout(BoxConstraints.loose(width, Infinity), { x: this.x, y: this.y }, ctx);
-        const b = this.body.calculateLayout(BoxConstraints.loose(width, Infinity), { x: this.x, y: this.y + h.height + this.gap }, ctx);
-        this.width = width;
-        this.height = h.height + this.gap + b.height;
-        return { width: this.width, height: this.height };
+        const inner = BoxConstraints.loose(width, Infinity);
+        const h = mode === "layout"
+            ? this.header.calculateLayout(inner, { x: 0, y: 0 }, ctx)
+            : this.header.measure(inner, ctx);
+        const b = mode === "layout"
+            ? this.body.calculateLayout(inner, { x: 0, y: h.height + this.gap }, ctx)
+            : this.body.measure(inner, ctx);
+        return { width, height: h.height + this.gap + b.height };
     }
     fragment(maxHeight, width, ctx) {
         // Reserve the header's height on every page; the body flows in what's left.
-        const headerHeight = this.header.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
+        const headerHeight = this.header.measure(BoxConstraints.loose(width, Infinity), ctx).height;
         if (!isFragmentable(this.body))
             return { fitted: this, remainder: null };
-        const split = this.body.fragment(Math.max(0, maxHeight - headerHeight - this.gap), width, ctx);
-        // Body fits whole → the whole thing fits on this page.
-        if (split.remainder === null)
+        const chrome = headerHeight + this.gap;
+        const split = this.body.fragment(Math.max(0, maxHeight - chrome), width, insetContext(ctx, chrome));
+        // Body fits whole, no break inside → the whole thing fits on this page.
+        if (split.remainder === null && !split.forceBreak)
             return { fitted: this, remainder: null };
-        // Re-wrap each body piece with the SAME header → it reappears on the next page too.
+        // Re-wrap each body piece with the SAME header → it reappears on the next page too. A forced
+        // break inside the body is passed on, so the page ends there.
         return {
-            fitted: split.fitted ? new RepeatingHeaderElement(this.header, split.fitted, this.gap) : null,
-            remainder: new RepeatingHeaderElement(this.header, split.remainder, this.gap),
+            fitted: split.fitted
+                ? new RepeatingHeaderElement(this.header, split.fitted, this.gap).asPieceOf(this)
+                : null,
+            remainder: split.remainder
+                ? new RepeatingHeaderElement(this.header, split.remainder, this.gap).asPieceOf(this)
+                : null,
+            forceBreak: split.forceBreak,
         };
     }
+    /** A break inside the body is a break in the flow the table sits in. */
+    hasForcedBreak() {
+        return this.body.hasForcedBreak();
+    }
+    layoutChildren() {
+        return [this.header, this.body];
+    }
     getProps() {
         return {
             x: this.x,

package/dist/elements/layout/rotated-box-element.d.ts

@@ -23,7 +23,13 @@ export declare class RotatedBoxElement extends PDFElement {
         child: PDFElement;
     });
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** 90 or 270 degrees swap the axes: the child experiences the box's constraints turned. */
+    private get quarter();
+    private childConstraints;
+    private swap;
     /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    layoutChildren(): readonly PDFElement[];
     getProps(): {
         angle: number;
         child: PDFElement;

package/dist/elements/layout/rotated-box-element.js

@@ -22,25 +22,38 @@ export class RotatedBoxElement extends PDFElement {
         this.child = child;
     }
     calculateLayout(constraints, offset, ctx) {
-        const quarter = this.turns % 2 === 1; // 90 or 270: axes swap
-        // A quarter-turned child experiences the box's constraints with the axes swapped.
-        const childConstraints = quarter
-            ? new BoxConstraints(constraints.minHeight, constraints.maxHeight, constraints.minWidth, constraints.maxWidth)
-            : constraints;
         // Measure the child to learn its natural size, then take that size swapped as our own box.
-        const child = this.child.calculateLayout(childConstraints, offset, ctx);
-        this.width = quarter ? child.height : child.width;
-        this.height = quarter ? child.width : child.height;
+        const child = this.child.measure(this.childConstraints(constraints), ctx);
+        const size = this.swap(child);
+        this.width = size.width;
+        this.height = size.height;
         this.x = offset.x;
         this.y = offset.y;
-        // Re-place the child CENTERED on the box center: a rotation around that center then maps the
-        // child's (w x h) box exactly onto our (swapped) box - so the shared renderer needs no special case.
-        const cx = this.x + this.width / 2;
-        const cy = this.y + this.height / 2;
-        this.child.calculateLayout(childConstraints, { x: cx - child.width / 2, y: cy - child.height / 2 }, ctx);
-        return { width: this.width, height: this.height };
+        // Place the child CENTERED on the box center (relative to our top-left): a rotation around that
+        // center then maps the child's (w x h) box exactly onto our (swapped) box - so the shared renderer
+        // needs no special case.
+        this.child.calculateLayout(this.childConstraints(constraints), { x: (this.width - child.width) / 2, y: (this.height - child.height) / 2 }, ctx);
+        return size;
+    }
+    computeSize(constraints, ctx) {
+        return this.swap(this.child.measure(this.childConstraints(constraints), ctx));
+    }
+    /** 90 or 270 degrees swap the axes: the child experiences the box's constraints turned. */
+    get quarter() {
+        return this.turns % 2 === 1;
+    }
+    childConstraints(constraints) {
+        return this.quarter
+            ? new BoxConstraints(constraints.minHeight, constraints.maxHeight, constraints.minWidth, constraints.maxWidth)
+            : constraints;
+    }
+    swap(child) {
+        return this.quarter ? { width: child.height, height: child.width } : child;
     }
     /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    layoutChildren() {
+        return [this.child];
+    }
     getProps() {
         return {
             angle: this.turns * 90,

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

@@ -21,6 +21,13 @@ export declare class RotatedElement extends PDFElement {
         child: PDFElement;
     });
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints, ctx: LayoutContext): Size;
+    layoutChildren(): readonly PDFElement[];
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    needsBoundedMain(horizontal: boolean): boolean;
+    minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     getProps(): {
         angle: number;
         child: PDFElement;

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

@@ -19,15 +19,38 @@ export class RotatedElement extends PDFElement {
         this.child = child;
     }
     calculateLayout(constraints, offset, ctx) {
-        // Delegate entirely to the child, then record its box (position + size) as our own - the
+        // Delegate entirely to the child (at our own top-left), then record its size as our own - the
         // rotation does not change what space we take, only how the child is painted.
-        const size = this.child.calculateLayout(constraints, offset, ctx);
+        const size = this.child.calculateLayout(constraints, { x: 0, y: 0 }, ctx);
         this.x = offset.x;
         this.y = offset.y;
         this.width = size.width;
         this.height = size.height;
         return size;
     }
+    computeSize(constraints, ctx) {
+        return this.child.measure(constraints, ctx);
+    }
+    layoutChildren() {
+        return [this.child];
+    }
+    // It takes the child's space, so the child's sizing hints and its break-before/after are its own.
+    // It is never split - half a rotation on each page means nothing - so a break INSIDE stays inside.
+    relativeSizeFactor(horizontal) {
+        return this.child.relativeSizeFactor(horizontal);
+    }
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
+    minIntrinsicMain(horizontal, ctx) {
+        return this.child.minIntrinsicMain(horizontal, ctx);
+    }
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
     getProps() {
         return {
             angle: this.angle,

package/dist/elements/layout/struct-group.d.ts

@@ -1,28 +1,20 @@
-import { PDFElement, LayoutContext } from "../pdf-element.js";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
-import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-element.js";
 /**
- * A layout-TRANSPARENT wrapper that assigns an accessibility structure role (Table / TR / TH / TD / …) to
- * its single child. It delegates ALL layout and fragmentation to the child, so the visual result is byte-
- * identical; only its renderer opens a structure element and nests the child's tags underneath.
+ * A layout-transparent wrapper (a `ProxyElement`) that assigns an accessibility structure role
+ * (Table / TR / TH / TD / …) to its single child; only its renderer opens a structure element and nests
+ * the child's tags underneath.
  *
- * Split across pages, the fitted and remainder halves share this group's `structId`, so it stays ONE
- * logical structure element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
+ * Split across pages, the pieces share this group's `structId`, so it stays ONE logical structure
+ * element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
  */
-export declare class StructGroup extends PDFElement implements Fragmentable {
+export declare class StructGroup extends ProxyElement {
     private role;
-    private child;
     constructor({ role, child }: {
         role: string;
         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;
-    /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
-     *  not clipped at the boundary (isFragmentable honours this veto). */
-    canFragment(): boolean;
-    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    protected rewrap(child: PDFElement): PDFElement;
     getProps(): {
         role: string;
         child: PDFElement;

package/dist/elements/layout/struct-group.js

@@ -1,44 +1,19 @@
-import { PDFElement } from "../pdf-element.js";
-import { isFragmentable } from "../../layout/fragmentation.js";
+import { ProxyElement } from "./proxy-element.js";
 /**
- * A layout-TRANSPARENT wrapper that assigns an accessibility structure role (Table / TR / TH / TD / …) to
- * its single child. It delegates ALL layout and fragmentation to the child, so the visual result is byte-
- * identical; only its renderer opens a structure element and nests the child's tags underneath.
+ * A layout-transparent wrapper (a `ProxyElement`) that assigns an accessibility structure role
+ * (Table / TR / TH / TD / …) to its single child; only its renderer opens a structure element and nests
+ * the child's tags underneath.
  *
- * Split across pages, the fitted and remainder halves share this group's `structId`, so it stays ONE
- * logical structure element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
+ * Split across pages, the pieces share this group's `structId`, so it stays ONE logical structure
+ * element (a table broken over pages is a single <Table>, exactly as Acrobat produces).
  */
-export class StructGroup extends PDFElement {
+export class StructGroup extends ProxyElement {
     constructor({ role, child }) {
-        super();
+        super(child);
         this.role = role;
-        this.child = 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);
-    }
-    /** Only splittable when the wrapped child is - so a StructGroup(Row) is moved whole to the next page,
-     *  not clipped at the boundary (isFragmentable honours this veto). */
-    canFragment() {
-        return isFragmentable(this.child);
-    }
-    fragment(maxHeight, width, ctx) {
-        if (!isFragmentable(this.child))
-            return { fitted: null, remainder: this };
-        const { fitted, remainder } = this.child.fragment(maxHeight, width, ctx);
-        // Re-wrap each half with the SAME role + identity, so both pages point at one structure element.
-        return {
-            fitted: fitted
-                ? new StructGroup({ role: this.role, child: fitted }).adoptStructId(this)
-                : null,
-            remainder: remainder
-                ? new StructGroup({ role: this.role, child: remainder }).adoptStructId(this)
-                : null,
-        };
+    rewrap(child) {
+        return new StructGroup({ role: this.role, child });
     }
     getProps() {
         return { role: this.role, child: this.child };

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

@@ -17,6 +17,7 @@ export declare class LineElement extends SizedPDFElement {
     private sizeMemory;
     constructor({ color, strokeWidth, x, y, xEnd, yEnd }: LineElementParams);
     calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    protected computeSize(constraints: BoxConstraints): Size;
     getProps(): {
         x: number;
         y: number;

package/dist/elements/line-element.js

@@ -24,6 +24,12 @@ export class LineElement extends SizedPDFElement {
         // Top-left coordinates; the Y-flip happens once at the IR -> backend seam.
         return { width: this.width ?? 0, height: this.height ?? 0 };
     }
+    computeSize(constraints) {
+        if (!constraints.hasBoundedWidth) {
+            throw new Error("The LineElement must be placed inside a parent container that defines its width");
+        }
+        return { width: this.width ?? 0, height: this.height ?? 0 };
+    }
     getProps() {
         return {
             x: this.x,

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

@@ -59,19 +59,26 @@ export interface PageBands {
  * resolve a `Positioned` against this same box, so `top`/`bottom` mean the same thing in each.
  *
  * `layoutPageBands` lays the bands out, so its caller must hand it a context carrying this frame -
- * otherwise a `Positioned` in a band has nothing to resolve against (ISSUE-4). A caller that only
- * wants the band HEIGHTS may throw the frame away without draining it: an out-of-flow child
- * contributes no height.
+ * otherwise a `Positioned` in a band has nothing to resolve against (ISSUE-4). An out-of-flow child
+ * contributes no height, so a caller that only wants the band HEIGHTS needs nothing more.
  */
 export declare function pageFrame(config: PDFPageConfig): PositioningFrame;
 export declare function layoutPageBands(config: PDFPageConfig, header: PDFElement | undefined, footer: PDFElement | undefined, ctx: LayoutContext): PageBands;
 export declare class PageElement extends PDFElement {
+    private readonly ownConfig;
     private config;
     private children;
     private header?;
     private footer?;
     constructor({ children, config, header, footer }: PDFPageParams);
     calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    /** Its size is its own page config. */
+    dependsOnPage(): boolean;
+    /** A page is as large as its content box, whatever it holds. */
+    protected computeSize(_constraints: BoxConstraints, ctx: LayoutContext): Size;
+    /** The document defaults with this page's own settings on top. Pure: no pass has to run first. */
+    resolveConfig(defaults: PDFPageConfig | undefined): PDFPageConfig;
+    layoutChildren(): readonly PDFElement[];
     getProps(): PDFPageParams;
     addTextElement(element: TextElement): this;
 }

package/dist/elements/page-element.js

@@ -2,6 +2,7 @@ import { pageFormats, PageSize } from "../constants/page-sizes.js";
 import { Orientation } from "../renderer/pdf-config.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { PDFElement } from "./pdf-element.js";
+import { positionedIn } from "./layout/positioned-element.js";
 /**
  * The full page (media box) size in points, orientation applied. This is what a `PageBuilder` sees as
  * `pageSize`; `resolvePageContentBox` below then subtracts the margins.
@@ -19,14 +20,14 @@ export function resolvePageSize(config) {
  * driver so they can never drift.
  */
 export function resolvePageContentBox(config) {
+    // The margins are the TURNED page's: `left` is the left edge of a landscape page, as `origin` says.
     const margin = config.margin;
-    const [pageW, pageH] = config.customSize ?? pageFormats[config.pageSize];
-    let width = pageW - margin.left - margin.right;
-    let height = pageH - margin.top - margin.bottom;
-    if (config.orientation === Orientation.landscape) {
-        [width, height] = [height, width];
-    }
-    return { origin: { x: margin.left, y: margin.top }, width, height };
+    const page = resolvePageSize(config);
+    return {
+        origin: { x: margin.left, y: margin.top },
+        width: page.width - margin.left - margin.right,
+        height: page.height - margin.top - margin.bottom,
+    };
 }
 /**
  * Lays out the header (top) and footer (bottom) of a page and returns the body band left
@@ -41,13 +42,12 @@ export function resolvePageContentBox(config) {
  * resolve a `Positioned` against this same box, so `top`/`bottom` mean the same thing in each.
  *
  * `layoutPageBands` lays the bands out, so its caller must hand it a context carrying this frame -
- * otherwise a `Positioned` in a band has nothing to resolve against (ISSUE-4). A caller that only
- * wants the band HEIGHTS may throw the frame away without draining it: an out-of-flow child
- * contributes no height.
+ * otherwise a `Positioned` in a band has nothing to resolve against (ISSUE-4). An out-of-flow child
+ * contributes no height, so a caller that only wants the band HEIGHTS needs nothing more.
  */
 export function pageFrame(config) {
     const { origin, width, height } = resolvePageContentBox(config);
-    return { origin, size: { width, height }, place: [] };
+    return { origin, size: { width, height } };
 }
 export function layoutPageBands(config, header, footer, ctx) {
     const { origin, width, height } = resolvePageContentBox(config);
@@ -57,13 +57,8 @@ export function layoutPageBands(config, header, footer, ctx) {
     }
     let footerHeight = 0;
     if (footer) {
-        // Measure first to learn its height, then place it flush against the bottom edge. The MEASURING
-        // pass gets a throwaway `place` list: an out-of-flow child registers a placement every time it is
-        // laid out, and this subtree is laid out twice. Only the second, real pass may register.
-        const measureCtx = ctx.frame
-            ? { ...ctx, frame: { ...ctx.frame, place: [] } }
-            : ctx;
-        footerHeight = footer.calculateLayout(BoxConstraints.loose(width, Infinity), origin, measureCtx).height;
+        // Measure first to learn its height, then place it flush against the bottom edge.
+        footerHeight = footer.measure(BoxConstraints.loose(width, Infinity), ctx).height;
         footer.calculateLayout(BoxConstraints.loose(width, Infinity), { x: origin.x, y: origin.y + height - footerHeight }, ctx);
     }
     return {
@@ -78,20 +73,21 @@ export class PageElement extends PDFElement {
     constructor({ children, config, header, footer }) {
         super();
         this.children = children;
-        this.config = config ?? {};
+        this.ownConfig = config ?? {};
+        this.config = this.ownConfig;
         this.header = header;
         this.footer = footer;
     }
     calculateLayout(_constraints, _offset, ctx) {
-        // Merge the document defaults (carried in the context) with this page's overrides,
-        // then hand descendants a context bound to THIS page's geometry. This is what
-        // fixes the old last-page-wins global page-config bug.
-        this.config = { ...ctx.pageConfig, ...this.config };
+        // Hand descendants a context bound to THIS page's geometry. This is what fixes the old
+        // last-page-wins global page-config bug.
+        this.config = this.resolveConfig(ctx.pageConfig);
         const pageCtx = {
             metrics: ctx.metrics,
             pageConfig: this.config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            diagnostics: ctx.diagnostics,
             pageInfo: ctx.pageInfo, // the render pass supplies it; absent during pagination
         };
         // The PAGE is a positioning frame, and the frame is the content box - not the body region left
@@ -110,16 +106,28 @@ export class PageElement extends PDFElement {
         const bands = layoutPageBands(this.config, this.header, this.footer, frameCtx);
         const childConstraints = BoxConstraints.loose(bands.bodyWidth, bands.bodyHeight);
         this.children.forEach((child) => child.calculateLayout(childConstraints, bands.bodyOrigin, frameCtx));
-        // Drained last, once every band and the body have registered: an out-of-flow child is placed
-        // against the final frame box and paints on top of the flow content.
-        //
-        // The callback gets `frameCtx`, not `pageCtx`: a `Positioned` NESTED inside an out-of-flow child
-        // must still see a frame. It appends to `frame.place` while we walk it, and a `for..of` over an
-        // array visits what was appended, so nested placements drain in the same loop.
-        for (const place of frame.place)
-            place(frame, frameCtx);
+        // Last, once the bands and the body are laid out: the page's out-of-flow descendants, placed
+        // relative to its content box. Each is drawn at its own place in the tree (tree order).
+        for (const p of positionedIn([this.header, ...this.children, this.footer]))
+            p.placeIn(frame.size, frameCtx);
         return { width: frame.size.width, height: frame.size.height };
     }
+    /** Its size is its own page config. */
+    dependsOnPage() {
+        return true;
+    }
+    /** A page is as large as its content box, whatever it holds. */
+    computeSize(_constraints, ctx) {
+        const { width, height } = resolvePageContentBox(this.resolveConfig(ctx.pageConfig));
+        return { width, height };
+    }
+    /** The document defaults with this page's own settings on top. Pure: no pass has to run first. */
+    resolveConfig(defaults) {
+        return { ...defaults, ...this.ownConfig };
+    }
+    layoutChildren() {
+        return [this.header, ...this.children, this.footer].filter((el) => el !== undefined);
+    }
     getProps() {
         return {
             children: this.children,

package/dist/elements/pdf-document-element.d.ts

@@ -14,6 +14,9 @@ export declare class PDFDocumentElement extends PDFElement {
     /** The document-level text defaults; the renderer merges them into the cascade root. */
     getDefaultTextStyle(): Partial<ResolvedTextStyle> | undefined;
     calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    /** The root has no size of its own. */
+    protected computeSize(): Size;
+    layoutChildren(): readonly PDFElement[];
     getProps(): PDFDocumentParams;
 }
 export {};