@jasy/pdf 1.0.0-alpha.5 → 1.0.0-alpha.7

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

@@ -0,0 +1,42 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { LayoutContext, PDFElement } from "../pdf-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.
+ *
+ * The rule, decided in `fragment`:
+ *   1. Fits in the space offered here           -> place it whole.
+ *   2. Does not fit here but fits on a FRESH    -> veto the split: defer the whole group to the next
+ *      full page                                   page (`fitted: null`), so it lands together there.
+ *   3. Taller than a whole page                 -> drop the veto and split normally. A group that can
+ *                                                  never fit on one page must break, or pagination
+ *                                                  could not terminate. Inner `keepTogether`s survive
+ *                                                  this (they are separate elements, re-evaluated when
+ *                                                  the child splits) - graceful degrade, outer->inner.
+ *
+ * A forced page break inside the group (a `PageBreak`, or a `breakBefore`/`breakAfter`) contradicts
+ * 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;
+    constructor({ child }: {
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    needsBoundedMain(horizontal: boolean): boolean;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
+    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). */
+    private splitChild;
+    getProps(): {
+        child: PDFElement;
+    };
+}

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

@@ -0,0 +1,85 @@
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+import { PDFElement } from "../pdf-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.
+ *
+ * The rule, decided in `fragment`:
+ *   1. Fits in the space offered here           -> place it whole.
+ *   2. Does not fit here but fits on a FRESH    -> veto the split: defer the whole group to the next
+ *      full page                                   page (`fitted: null`), so it lands together there.
+ *   3. Taller than a whole page                 -> drop the veto and split normally. A group that can
+ *                                                  never fit on one page must break, or pagination
+ *                                                  could not terminate. Inner `keepTogether`s survive
+ *                                                  this (they are separate elements, re-evaluated when
+ *                                                  the child splits) - graceful degrade, outer->inner.
+ *
+ * A forced page break inside the group (a `PageBreak`, or a `breakBefore`/`breakAfter`) contradicts
+ * 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 {
+    constructor({ child }) {
+        super();
+        this.warnedBreakConflict = false;
+        this.child = child;
+    }
+    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();
+    }
+    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.");
+            }
+            return this.splitChild(maxHeight, width, ctx);
+        }
+        const natural = this.child.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
+        // 1. Fits in the offered space: keep whole.
+        if (natural <= maxHeight)
+            return { fitted: this, remainder: null };
+        // 2. Would fit on a fresh full page: veto the split, defer the whole group to the next page. Only
+        //    reachable in a PARTIAL region (something is already on this page); alone on a full page,
+        //    `maxHeight` IS the page body, so `natural > maxHeight` means case 3, never this.
+        const pageBody = ctx.pageBodyHeight ?? maxHeight;
+        if (natural <= pageBody)
+            return { fitted: null, remainder: this };
+        // 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). */
+    splitChild(maxHeight, width, ctx) {
+        if (!isFragmentable(this.child))
+            return { fitted: null, remainder: this };
+        return this.child.fragment(maxHeight, width, ctx);
+    }
+    getProps() {
+        return { child: this.child };
+    }
+}

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

@@ -0,0 +1,33 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.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.
+ */
+export declare class LinkElement extends PDFElement {
+    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;
+    getProps(): {
+        href: string | undefined;
+        dest: string | undefined;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,39 @@
+import { PDFElement } from "../pdf-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.
+ */
+export class LinkElement extends PDFElement {
+    constructor({ href, dest, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        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;
+    }
+    getProps() {
+        return {
+            href: this.href,
+            dest: this.dest,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

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

@@ -15,6 +15,9 @@ 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;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     private cloneWithChild;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {

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

@@ -25,8 +25,20 @@ export class PaddingElement extends SizedPDFElement {
         return {
             fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
             remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
+            forceBreak: split.forceBreak,
         };
     }
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    // Padding is a transparent single-child wrapper, so a break-before/after on the wrapped element must
+    // still be seen by the parent packer at this boundary (otherwise it is swallowed).
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
     cloneWithChild(child) {
         return new PaddingElement({ margin: this.margin, child });
     }

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

@@ -0,0 +1,17 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PDFElement } from "../pdf-element.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
+ * pagination packer consumes it at the cut, so it never reaches the render pass.
+ *
+ * Nesting works: a break deep inside a container is honoured because the packer fragments any child
+ * whose subtree `hasForcedBreak()`, and the resulting `forceBreak` bubbles up so the outer flow stops
+ * 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;
+    isPageBreak(): boolean;
+    hasForcedBreak(): boolean;
+    getProps(): Record<string, never>;
+}

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

@@ -0,0 +1,24 @@
+import { PDFElement } from "../pdf-element.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
+ * pagination packer consumes it at the cut, so it never reaches the render pass.
+ *
+ * Nesting works: a break deep inside a container is honoured because the packer fragments any child
+ * whose subtree `hasForcedBreak()`, and the resulting `forceBreak` bubbles up so the outer flow stops
+ * 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) {
+        return { width: 0, height: 0 };
+    }
+    isPageBreak() {
+        return true;
+    }
+    hasForcedBreak() {
+        return true;
+    }
+    getProps() {
+        return {};
+    }
+}

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

@@ -0,0 +1,32 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PageInfo, PDFElement } from "../pdf-element.js";
+/**
+ * Builds its subtree from the page it lands on, so a header, a footer or plain body content can show
+ * `pageNumber` / `pageCount`. The closure runs on EVERY layout, because the numbers differ between the
+ * two driver passes: pagination has to size the element before the page total exists, so it builds
+ * against a provisional "1 of 1"; the render pass then rebuilds it with the real `PageInfo`.
+ *
+ * Two consequences, and neither is magic - both come from the same chicken-and-egg: the content decides
+ * the page count that the content displays.
+ *
+ * 1. In the flowing BODY the box is reserved by the provisional build, so a much wider final string
+ *    (`"9 of 10"` vs `"1 of 1"`) can paint slightly past it. Keep dynamic body content roughly constant
+ *    in width.
+ * 2. A header/footer is re-laid out per page, so its real height is honoured - but the BODY band was
+ *    already sized against the provisional build. A later page whose header is SHORTER simply gains
+ *    room (harmless). A later page whose header is TALLER shrinks the band its body was measured for,
+ *    and that body can overflow. So: a conditional header may shrink on later pages, never grow.
+ */
+export declare class PageBuilderElement extends PDFElement {
+    private composed?;
+    private readonly build;
+    constructor({ build }: {
+        build: (info: PageInfo) => 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;
+    getProps(): {
+        composed: PDFElement | undefined;
+    };
+}

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

@@ -0,0 +1,43 @@
+import { PDFElement } from "../pdf-element.js";
+import { resolvePageSize } from "../page-element.js";
+/**
+ * Builds its subtree from the page it lands on, so a header, a footer or plain body content can show
+ * `pageNumber` / `pageCount`. The closure runs on EVERY layout, because the numbers differ between the
+ * two driver passes: pagination has to size the element before the page total exists, so it builds
+ * against a provisional "1 of 1"; the render pass then rebuilds it with the real `PageInfo`.
+ *
+ * Two consequences, and neither is magic - both come from the same chicken-and-egg: the content decides
+ * the page count that the content displays.
+ *
+ * 1. In the flowing BODY the box is reserved by the provisional build, so a much wider final string
+ *    (`"9 of 10"` vs `"1 of 1"`) can paint slightly past it. Keep dynamic body content roughly constant
+ *    in width.
+ * 2. A header/footer is re-laid out per page, so its real height is honoured - but the BODY band was
+ *    already sized against the provisional build. A later page whose header is SHORTER simply gains
+ *    room (harmless). A later page whose header is TALLER shrinks the band its body was measured for,
+ *    and that body can overflow. So: a conditional header may shrink on later pages, never grow.
+ */
+export class PageBuilderElement extends PDFElement {
+    constructor({ build }) {
+        super();
+        this.build = build;
+    }
+    /** The real page info during the render pass; a provisional "1 of 1" while paginating. */
+    infoFrom(ctx) {
+        return (ctx.pageInfo ?? {
+            pageNumber: 1,
+            pageCount: 1,
+            pageSize: resolvePageSize(ctx.pageConfig),
+        });
+    }
+    calculateLayout(constraints, offset, ctx) {
+        this.composed = this.build(this.infoFrom(ctx));
+        return this.composed.calculateLayout(constraints, offset, 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.
+    getProps() {
+        return { composed: this.composed };
+    }
+}

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

@@ -23,14 +23,17 @@ export interface PositionedInsets {
 interface PositionedElementParams extends WithChild, PositionedInsets {
 }
 /**
- * An out-of-flow child, placed relative to the nearest enclosing positioning frame (a `relative`
- * 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).
+ * 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).
  *
- * With no frame in scope the element is a no-op (nothing is drawn) - `Positioned` only makes sense
- * inside a `relative` Box.
+ * 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 declare class PositionedElement extends PDFElement {
     private child;

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

@@ -1,14 +1,17 @@
 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). 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).
+ * 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).
  *
- * With no frame in scope the element is a no-op (nothing is drawn) - `Positioned` only makes sense
- * inside a `relative` Box.
+ * 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 }) {
@@ -17,8 +20,12 @@ export class PositionedElement extends PDFElement {
         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));
+        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. */
@@ -35,7 +42,12 @@ 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).
-        const measured = this.child.calculateLayout(constraints, { x: 0, y: 0 }, ctx);
+        // 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) => {

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/page-element.d.ts

@@ -2,7 +2,7 @@ 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, WithChildren } from "./pdf-element.js";
+import { LayoutContext, PDFElement, PositioningFrame, WithChildren } from "./pdf-element.js";
 import { TextElement } from "./text-element.js";
 export interface PDFPageConfig {
     pageSize?: PageSize;
@@ -20,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
@@ -46,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;