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

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

@@ -1,6 +1,6 @@
-import { PDFElement, LayoutContext, FlexiblePDFElement, WithChild, FlexibleElement } from "../pdf-element";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints";
-import { Fragmentable, FragmentResult } from "../../layout/fragmentation";
+import { PDFElement, LayoutContext, FlexiblePDFElement, WithChild, FlexibleElement } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
 interface ExpandedElementParams extends FlexibleElement, WithChild {
 }
 export declare class ExpandedElement extends FlexiblePDFElement implements Fragmentable {
@@ -9,7 +9,7 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
     private y;
     private width;
     private height;
-    constructor({ flex, child }: ExpandedElementParams);
+    constructor({ flex, basis, basisFactor, child }: ExpandedElementParams);
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     /**
      * When the column paginates, a flex region can't "fill" across pages, so it delegates to
@@ -24,6 +24,8 @@ export declare class ExpandedElement extends FlexiblePDFElement implements Fragm
         y: number;
         width: number;
         height: number;
+        basis: number;
+        basisFactor: number | undefined;
         child: PDFElement;
     };
 }

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

@@ -1,13 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExpandedElement = void 0;
-const element_validator_1 = require("../../validators/element-validator");
-const pdf_element_1 = require("../pdf-element");
-const box_constraints_1 = require("../../layout/box-constraints");
-const fragmentation_1 = require("../../layout/fragmentation");
-class ExpandedElement extends pdf_element_1.FlexiblePDFElement {
-    constructor({ flex, child }) {
-        super({ flex });
+import { Validator } from "../../validators/element-validator.js";
+import { FlexiblePDFElement, } from "../pdf-element.js";
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+export class ExpandedElement extends FlexiblePDFElement {
+    constructor({ flex, basis, basisFactor, child }) {
+        super({ flex, basis, basisFactor });
         this.x = 0;
         this.y = 0;
         this.width = 0;
@@ -20,17 +17,17 @@ class ExpandedElement extends pdf_element_1.FlexiblePDFElement {
         // Absolute placement from the parent; assignment (not +=) so re-layout is idempotent.
         this.x = offset.x;
         this.y = offset.y;
-        element_validator_1.Validator.validateFlexElement(this);
+        Validator.validateFlexElement(this);
         if (constraints.hasBoundedHeight) {
-            // A bounded region: fill it - the normal flex behaviour.
+            // A bounded region: fill it - the normal flex behavior.
             this.height = constraints.maxHeight;
-            this.child.calculateLayout(box_constraints_1.BoxConstraints.loose(this.width, this.height), { x: this.x, y: this.y }, ctx);
+            this.child.calculateLayout(BoxConstraints.loose(this.width, this.height), { x: this.x, y: this.y }, ctx);
         }
         else {
             // Unbounded (measuring while paginating): there's no leftover space to fill, so
             // collapse to the child's natural height. This lets an overflowing column flow
             // instead of the flex silently hiding the overflow.
-            const childSize = this.child.calculateLayout(box_constraints_1.BoxConstraints.loose(this.width, Infinity), { x: this.x, y: this.y }, ctx);
+            const childSize = this.child.calculateLayout(BoxConstraints.loose(this.width, Infinity), { x: this.x, y: this.y }, ctx);
             this.height = childSize.height;
         }
         // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
@@ -43,7 +40,7 @@ class ExpandedElement extends pdf_element_1.FlexiblePDFElement {
      * whole Expanded moves on.
      */
     fragment(maxHeight, width, ctx) {
-        if (!(0, fragmentation_1.isFragmentable)(this.child)) {
+        if (!isFragmentable(this.child)) {
             return { fitted: null, remainder: this };
         }
         const split = this.child.fragment(maxHeight, width, ctx);
@@ -53,7 +50,14 @@ class ExpandedElement extends pdf_element_1.FlexiblePDFElement {
         };
     }
     cloneWithChild(child) {
-        return new ExpandedElement({ flex: this.flex, child });
+        // The basis has to come along: a fragment that lost it would claim only its share of the leftover,
+        // so a `flexBasis` slot would silently change width on the page it continues onto.
+        return new ExpandedElement({
+            flex: this.flex,
+            basis: this.basis,
+            basisFactor: this.basisFactor,
+            child,
+        });
     }
     getProps() {
         return {
@@ -61,8 +65,9 @@ class ExpandedElement extends pdf_element_1.FlexiblePDFElement {
             y: this.y,
             width: this.width,
             height: this.height,
+            basis: this.basis,
+            basisFactor: this.basisFactor,
             child: this.child,
         };
     }
 }
-exports.ExpandedElement = ExpandedElement;

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

@@ -1,8 +1,10 @@
-import { PDFElement, LayoutContext, WithChild, SizedPDFElement } from "../pdf-element";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints";
-import { Fragmentable, FragmentResult } from "../../layout/fragmentation";
+import { PDFElement, LayoutContext, WithChild, SizedPDFElement } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { type EdgeSpecs } from "../../layout/insets.js";
 interface PaddingElementParams extends WithChild {
-    margin: [number, number, number, number];
+    /** Still unresolved: a side may be a percentage of the offered WIDTH (see `Insets`). */
+    margin: EdgeSpecs;
 }
 export declare class PaddingElement extends SizedPDFElement implements Fragmentable {
     private child;
@@ -15,6 +17,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(): {
@@ -22,7 +27,7 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
         y: number;
         width: number | undefined;
         height: number | undefined;
-        margin: [number, number, number, number];
+        margin: EdgeSpecs;
         child: PDFElement;
     };
 }

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

@@ -1,11 +1,9 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PaddingElement = void 0;
-const element_validator_1 = require("../../validators/element-validator");
-const pdf_element_1 = require("../pdf-element");
-const box_constraints_1 = require("../../layout/box-constraints");
-const fragmentation_1 = require("../../layout/fragmentation");
-class PaddingElement extends pdf_element_1.SizedPDFElement {
+import { Validator } from "../../validators/element-validator.js";
+import { SizedPDFElement } from "../pdf-element.js";
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+import { resolveEdges } from "../../layout/insets.js";
+export class PaddingElement extends SizedPDFElement {
     constructor({ margin, child }) {
         super({ x: 0, y: 0 });
         this.child = child;
@@ -18,29 +16,41 @@ class PaddingElement extends pdf_element_1.SizedPDFElement {
      * child can't be split, the whole padding moves on as the remainder.
      */
     fragment(maxHeight, width, ctx) {
-        if (!(0, fragmentation_1.isFragmentable)(this.child)) {
+        if (!isFragmentable(this.child)) {
             return { fitted: null, remainder: this };
         }
-        const [marginTop, marginRight, marginBottom, marginLeft] = this.margin;
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, width);
         const childWidth = width - marginLeft - marginRight;
         const childMaxHeight = maxHeight - marginTop - marginBottom;
         const split = this.child.fragment(childMaxHeight, childWidth, ctx);
         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 });
     }
     calculateLayout(constraints, offset, ctx) {
-        var _a;
         // Padding takes the width it is offered; its height shrink-wraps the child.
         if (constraints.hasBoundedWidth)
             this.width = constraints.maxWidth;
         this.x = offset.x;
         this.y = offset.y;
-        const [marginTop, marginRight, marginBottom, marginLeft] = this.margin;
+        // Percentages resolve against the width we were OFFERED, so every pass gets the same answer.
+        const [marginTop, marginRight, marginBottom, marginLeft] = resolveEdges(this.margin, constraints.maxWidth);
         // The child is inset by the margins: shifted down/right, narrowed by the
         // horizontal margins, and left height-unbounded so it sizes to its own content.
         const childOffset = {
@@ -50,7 +60,7 @@ class PaddingElement extends pdf_element_1.SizedPDFElement {
         const childWidth = constraints.hasBoundedWidth
             ? Math.max(0, constraints.maxWidth - marginLeft - marginRight)
             : Infinity;
-        const childConstraints = box_constraints_1.BoxConstraints.loose(childWidth, Infinity);
+        const childConstraints = BoxConstraints.loose(childWidth, Infinity);
         const childSize = this.child.calculateLayout(childConstraints, childOffset, ctx);
         this.height = childSize.height + marginTop + marginBottom;
         // Unbounded width (e.g. a fixed child in a Row): shrink-wrap to the child + insets,
@@ -58,9 +68,9 @@ class PaddingElement extends pdf_element_1.SizedPDFElement {
         if (!constraints.hasBoundedWidth) {
             this.width = childSize.width + marginLeft + marginRight;
         }
-        element_validator_1.Validator.validateSizedElement(this);
+        Validator.validateSizedElement(this);
         // Top-left coordinates; the Y-flip now happens once at the IR -> backend seam.
-        return { width: (_a = this.width) !== null && _a !== void 0 ? _a : 0, height: this.height };
+        return { width: this.width ?? 0, height: this.height };
     }
     getProps() {
         return {
@@ -73,4 +83,3 @@ class PaddingElement extends pdf_element_1.SizedPDFElement {
         };
     }
 }
-exports.PaddingElement = PaddingElement;

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,45 @@
+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,
+            subPageNumber: 1,
+            subPageTotalPages: 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

@@ -0,0 +1,47 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PDFElement, WithChild } from "../pdf-element.js";
+/** A position anchor along one axis: `start` (left/top), `center`, or `end` (right/bottom). */
+export type PositionAnchor = "start" | "center" | "end";
+/**
+ * How a `Positioned` child sits in its frame. Two ways, pick per axis:
+ *  - EDGE pinning: `top`/`right`/`bottom`/`left` (points from that edge; negative pokes outside).
+ *    Pinning BOTH sides of an axis stretches the child to fill between them.
+ *  - ANCHOR + nudge: `h`/`v` anchor the child (start/center/end) and `x`/`y` nudge it from there
+ *    (e.g. `{ h: "center", x: -10 }` = centered minus 10pt). The child shrink-wraps to its content.
+ * An edge wins over an anchor on the same axis. With nothing set the child sits at the top-left.
+ */
+export interface PositionedInsets {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    h?: PositionAnchor;
+    v?: PositionAnchor;
+    x?: number;
+    y?: number;
+}
+interface PositionedElementParams extends WithChild, PositionedInsets {
+}
+/**
+ * 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 declare class PositionedElement extends PDFElement {
+    private child;
+    private insets;
+    constructor({ child, top, right, bottom, left, h, v, x, y }: PositionedElementParams);
+    calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    /** Lays the child out at the resolved position inside (or overflowing) the frame box. */
+    private placeInFrame;
+    getProps(): WithChild;
+}
+export {};