@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

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

@@ -0,0 +1,73 @@
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { PDFElement } from "../pdf-element.js";
+/**
+ * An out-of-flow child, placed relative to the nearest enclosing positioning frame: a `relative`
+ * Box, or failing that the page's content box. It takes ZERO space in the normal flow -
+ * `calculateLayout` returns `Size(0,0)` and instead registers a placement closure on the frame. The
+ * frame runs that closure once it knows its own size, so `right`/`bottom` resolve against the final
+ * box and the child can overflow it (a negative `top`/`left` makes it poke into / out of the
+ * corner, e.g. a badge or tab).
+ *
+ * Every page supplies a frame - header, footer and body alike - so within a document there is
+ * always one. Outside of one we REFUSE rather than draw: the element used to fall through to its
+ * child's default (0, 0), which is how a header watermark landed silently in the page corner
+ * (ISSUE-4). Content that lands somewhere unasked is worse than content that does not render.
+ */
+export class PositionedElement extends PDFElement {
+    constructor({ child, top, right, bottom, left, h, v, x, y }) {
+        super();
+        this.child = child;
+        this.insets = { top, right, bottom, left, h, v, x, y };
+    }
+    calculateLayout(_constraints, _offset, ctx) {
+        if (!ctx.frame) {
+            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));
+        return { width: 0, height: 0 };
+    }
+    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
+    placeInFrame(frame, ctx) {
+        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
+        // anchor never stretches - it positions a content-sized child.
+        const width = left !== undefined && right !== undefined
+            ? Math.max(0, frame.size.width - left - right)
+            : Infinity;
+        const height = top !== undefined && bottom !== undefined
+            ? Math.max(0, frame.size.height - top - bottom)
+            : 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);
+        // 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) => {
+            if (nearEdge !== undefined)
+                return origin + nearEdge;
+            if (farEdge !== undefined)
+                return origin + frameExtent - childExtent - farEdge;
+            const base = anchor === "center"
+                ? (frameExtent - childExtent) / 2
+                : anchor === "end"
+                    ? frameExtent - childExtent
+                    : 0; // start (default)
+            return origin + base + (nudge ?? 0);
+        };
+        const x = place(frame.origin.x, frame.size.width, measured.width, left, right, h, nudgeX);
+        const y = place(frame.origin.y, frame.size.height, measured.height, top, bottom, v, nudgeY);
+        // Place it for real at the resolved position.
+        this.child.calculateLayout(constraints, { x, y }, ctx);
+    }
+    getProps() {
+        return { child: this.child };
+    }
+}

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

@@ -1,6 +1,6 @@
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints";
-import { Fragmentable, FragmentResult } from "../../layout/fragmentation";
-import { LayoutContext, PDFElement } from "../pdf-element";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
 /**
  * Stacks a `header` above a `body` and, when it paginates, **repeats the header on every
  * fragment**. Used by `Table` so column headings reappear at the top of each page. Layout

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

@@ -1,16 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RepeatingHeaderElement = void 0;
-const box_constraints_1 = require("../../layout/box-constraints");
-const fragmentation_1 = require("../../layout/fragmentation");
-const pdf_element_1 = require("../pdf-element");
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { 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
  * fragment**. Used by `Table` so column headings reappear at the top of each page. Layout
  * is just header-then-body (like a 2-row Column); the magic is in `fragment`: it splits the
  * body and re-wraps each piece with the same header, so every physical page gets its own.
  */
-class RepeatingHeaderElement extends pdf_element_1.PDFElement {
+export class RepeatingHeaderElement extends PDFElement {
     constructor(header, body, gap = 0) {
         super();
         this.header = header;
@@ -25,16 +22,16 @@ class RepeatingHeaderElement extends pdf_element_1.PDFElement {
         this.x = offset.x;
         this.y = offset.y;
         const width = constraints.hasBoundedWidth ? constraints.maxWidth : 0;
-        const h = this.header.calculateLayout(box_constraints_1.BoxConstraints.loose(width, Infinity), { x: this.x, y: this.y }, ctx);
-        const b = this.body.calculateLayout(box_constraints_1.BoxConstraints.loose(width, Infinity), { x: this.x, y: this.y + h.height + this.gap }, ctx);
+        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 };
     }
     fragment(maxHeight, width, ctx) {
         // Reserve the header's height on every page; the body flows in what's left.
-        const headerHeight = this.header.calculateLayout(box_constraints_1.BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
-        if (!(0, fragmentation_1.isFragmentable)(this.body))
+        const headerHeight = this.header.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, 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.
@@ -57,4 +54,3 @@ class RepeatingHeaderElement extends pdf_element_1.PDFElement {
         };
     }
 }
-exports.RepeatingHeaderElement = RepeatingHeaderElement;

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

@@ -0,0 +1,35 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Rotates its child by whole quarter-turns and, unlike `RotatedElement` (paint-only), makes the
+ * rotation LAYOUT-AWARE: for a 90 / 270 turn it SWAPS width and height, so the box reports the rotated
+ * footprint UP and siblings reflow around it. A tall text becomes a narrow vertical strip that actually
+ * reserves its narrow width and its long height - the "vertical label beside a table" case.
+ *
+ * `turns` is the number of 90-degree CLOCKWISE quarter-turns (like Flutter's `RotatedBox.quarterTurns`):
+ * 0 = none, 1 = 90, 2 = 180, 3 = 270. The child lays out with the box's constraints swapped, then it is
+ * placed centered on the box's center so a plain center-rotation (the shared renderer) maps it exactly
+ * onto the swapped box.
+ */
+export declare class RotatedBoxElement extends PDFElement {
+    private turns;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ turns, child }: {
+        turns: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    getProps(): {
+        angle: number;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,54 @@
+import { PDFElement } from "../pdf-element.js";
+import { BoxConstraints } from "../../layout/box-constraints.js";
+/**
+ * Rotates its child by whole quarter-turns and, unlike `RotatedElement` (paint-only), makes the
+ * rotation LAYOUT-AWARE: for a 90 / 270 turn it SWAPS width and height, so the box reports the rotated
+ * footprint UP and siblings reflow around it. A tall text becomes a narrow vertical strip that actually
+ * reserves its narrow width and its long height - the "vertical label beside a table" case.
+ *
+ * `turns` is the number of 90-degree CLOCKWISE quarter-turns (like Flutter's `RotatedBox.quarterTurns`):
+ * 0 = none, 1 = 90, 2 = 180, 3 = 270. The child lays out with the box's constraints swapped, then it is
+ * placed centered on the box's center so a plain center-rotation (the shared renderer) maps it exactly
+ * onto the swapped box.
+ */
+export class RotatedBoxElement extends PDFElement {
+    constructor({ turns, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.turns = ((Math.trunc(turns) % 4) + 4) % 4;
+        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;
+        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 };
+    }
+    /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    getProps() {
+        return {
+            angle: this.turns * 90,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

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

@@ -0,0 +1,32 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Rotates its single child at PAINT time only (like Flutter's `Transform.rotate`): the child lays out
+ * in its normal, axis-aligned box and the element reports that same box UP, so siblings never reflow
+ * around the rotated shape. Only the drawing is rotated, around the box's center, by the renderer.
+ *
+ * Layout-transparent: it delegates `calculateLayout` to the child and just records the resulting box,
+ * which the renderer needs as the pivot. Not `Fragmentable` on purpose - a rotated subtree is atomic
+ * w.r.t. pagination (it moves whole to the next page rather than splitting mid-rotation).
+ */
+export declare class RotatedElement extends PDFElement {
+    private angle;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ angle, child }: {
+        angle: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        angle: number;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,41 @@
+import { PDFElement } from "../pdf-element.js";
+/**
+ * Rotates its single child at PAINT time only (like Flutter's `Transform.rotate`): the child lays out
+ * in its normal, axis-aligned box and the element reports that same box UP, so siblings never reflow
+ * around the rotated shape. Only the drawing is rotated, around the box's center, by the renderer.
+ *
+ * Layout-transparent: it delegates `calculateLayout` to the child and just records the resulting box,
+ * which the renderer needs as the pivot. Not `Fragmentable` on purpose - a rotated subtree is atomic
+ * w.r.t. pagination (it moves whole to the next page rather than splitting mid-rotation).
+ */
+export class RotatedElement extends PDFElement {
+    constructor({ angle, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.angle = angle;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        // Delegate entirely to the child, then record its box (position + 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);
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    getProps() {
+        return {
+            angle: this.angle,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

package/dist/elements/layout/sized-container-element.d.ts

@@ -1,5 +1,5 @@
-import { SizedElement, WithChildren, SizedPDFElement, LayoutContext } from "../pdf-element";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints";
+import { SizedElement, WithChildren, SizedPDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
 interface ContainerElementParams extends SizedElement, WithChildren {
     color?: [number, number, number];
     backgroundColor?: [number, number, number];

package/dist/elements/layout/sized-container-element.js

@@ -1,15 +1,11 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SizedContainerElement = void 0;
-const pdf_element_1 = require("../pdf-element");
-const box_constraints_1 = require("../../layout/box-constraints");
-class SizedContainerElement extends pdf_element_1.SizedPDFElement {
+import { SizedPDFElement, } from "../pdf-element.js";
+import { BoxConstraints } from "../../layout/box-constraints.js";
+export class SizedContainerElement extends SizedPDFElement {
     constructor({ width, height, children }) {
         super({ x: 0, y: 0, width, height });
         this.children = children;
     }
     calculateLayout(constraints, offset, ctx) {
-        var _a, _b;
         if (constraints.hasBoundedWidth)
             this.width = constraints.maxWidth;
         if (constraints.hasBoundedHeight)
@@ -17,10 +13,10 @@ class SizedContainerElement extends pdf_element_1.SizedPDFElement {
         // Absolute placement from the parent; assignment (not +=) so re-layout is idempotent.
         this.x = offset.x;
         this.y = offset.y;
-        const width = (_a = this.width) !== null && _a !== void 0 ? _a : 0;
-        const height = (_b = this.height) !== null && _b !== void 0 ? _b : 0;
+        const width = this.width ?? 0;
+        const height = this.height ?? 0;
         if (this.children)
-            this.children.forEach((child) => child.calculateLayout(box_constraints_1.BoxConstraints.loose(width, height), { x: this.x, y: this.y }, ctx));
+            this.children.forEach((child) => child.calculateLayout(BoxConstraints.loose(width, height), { x: this.x, y: this.y }, ctx));
         // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
         return { width, height };
     }
@@ -34,4 +30,3 @@ class SizedContainerElement extends pdf_element_1.SizedPDFElement {
         };
     }
 }
-exports.SizedContainerElement = SizedContainerElement;

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

@@ -0,0 +1,28 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.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.
+ *
+ * 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).
+ */
+export declare class StructGroup extends PDFElement implements Fragmentable {
+    private role;
+    private child;
+    constructor({ role, child }: {
+        role: string;
+        child: PDFElement;
+    });
+    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;
+    getProps(): {
+        role: string;
+        child: PDFElement;
+    };
+}

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

@@ -0,0 +1,42 @@
+import { PDFElement } from "../pdf-element.js";
+import { isFragmentable } from "../../layout/fragmentation.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.
+ *
+ * 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).
+ */
+export class StructGroup extends PDFElement {
+    constructor({ role, child }) {
+        super();
+        this.role = role;
+        this.child = child;
+    }
+    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,
+        };
+    }
+    getProps() {
+        return { role: this.role, child: this.child };
+    }
+}

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

@@ -1,6 +1,6 @@
-import { Color } from "../common/color";
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { LayoutContext, SizedElement, SizedPDFElement } from "./pdf-element";
+import { Color } from "../common/color.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { LayoutContext, SizedElement, SizedPDFElement } from "./pdf-element.js";
 interface LineElementParams extends SizedElement {
     color?: Color;
     strokeWidth?: number;

package/dist/elements/line-element.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LineElement = void 0;
-const color_1 = require("../common/color");
-const pdf_element_1 = require("./pdf-element");
-class LineElement extends pdf_element_1.SizedPDFElement {
-    constructor({ color = new color_1.Color(0, 0, 0), strokeWidth, x, y, xEnd, yEnd }) {
+import { Color } from "../common/color.js";
+import { SizedPDFElement } from "./pdf-element.js";
+export class LineElement extends SizedPDFElement {
+    constructor({ color = new Color(0, 0, 0), strokeWidth, x, y, xEnd, yEnd }) {
         super({ x: x, y: y, width: xEnd, height: y + yEnd });
         this.color = color;
         this.strokeWidth = strokeWidth ? strokeWidth : 1;
@@ -15,7 +12,6 @@ class LineElement extends pdf_element_1.SizedPDFElement {
         this.sizeMemory = { x, y, width: xEnd, height: yEnd };
     }
     calculateLayout(constraints, offset, _ctx) {
-        var _a, _b;
         // Set relative to parent
         this.x = this.sizeMemory.x + offset.x;
         this.y = this.sizeMemory.y + offset.y;
@@ -26,7 +22,7 @@ class LineElement extends pdf_element_1.SizedPDFElement {
         this.xEnd = offset.x + constraints.maxWidth - this.sizeMemory.width;
         this.yEnd = offset.y + this.sizeMemory.height;
         // Top-left coordinates; the Y-flip happens once at the IR -> backend seam.
-        return { width: (_a = this.width) !== null && _a !== void 0 ? _a : 0, height: (_b = this.height) !== null && _b !== void 0 ? _b : 0 };
+        return { width: this.width ?? 0, height: this.height ?? 0 };
     }
     getProps() {
         return {
@@ -41,4 +37,3 @@ class LineElement extends pdf_element_1.SizedPDFElement {
         };
     }
 }
-exports.LineElement = LineElement;

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

@@ -1,11 +1,13 @@
-import { PageSize } from "../constants/page-sizes";
-import { Orientation } from "../renderer/pdf-config";
-import type { ColorMode, DefaultFont, Margin } from "../renderer";
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { LayoutContext, PDFElement, WithChildren } from "./pdf-element";
-import { TextElement } from "./text-element";
+import { PageSize } from "../constants/page-sizes.js";
+import { Orientation } from "../renderer/pdf-config.js";
+import type { ColorMode, DefaultFont, Margin } from "../renderer/index.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { LayoutContext, PDFElement, PositioningFrame, WithChildren } from "./pdf-element.js";
+import { TextElement } from "./text-element.js";
 export interface PDFPageConfig {
     pageSize?: PageSize;
+    /** Explicit [width, height] in points; overrides `pageSize` (e.g. a custom label format). */
+    customSize?: [number, number];
     orientation?: Orientation;
     margin?: Margin;
     colorMode?: ColorMode;
@@ -18,6 +20,14 @@ interface PDFPageParams extends WithChildren {
     /** Laid out at the BOTTOM of the content box, repeated on every physical page. */
     footer?: PDFElement;
 }
+/**
+ * The full page (media box) size in points, orientation applied. This is what a `PageBuilder` sees as
+ * `pageSize`; `resolvePageContentBox` below then subtracts the margins.
+ */
+export declare function resolvePageSize(config: PDFPageConfig): {
+    width: number;
+    height: number;
+};
 /**
  * The content box of a page (inside the margins, orientation applied) for a fully
  * resolved config. Single source of truth, shared by `PageElement` layout and the page
@@ -44,6 +54,16 @@ export interface PageBands {
  * no header/footer the bands are zero and the body equals the full content box - identical
  * to a page without them.
  */
+/**
+ * The page's positioning frame: its CONTENT box (paper minus margins). Header, footer and body all
+ * 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.
+ */
+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 config;