@jasy/pdf 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/elements/forms/push-button-element.js

@@ -0,0 +1,49 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A push button (AcroForm /Btn, Pushbutton flag). Holds no value - it fires an action. Draws nothing
+ * itself: it reserves its box and emits a `formfield` IR node whose caption is baked into an /AP at the
+ * seam, so the button looks identical in every viewer and in print.
+ */
+export class PushButtonElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "pushbutton",
+            name: p.name,
+            label: p.label,
+            action: p.action,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(154, 164, 178),
+            background: p.background ?? new Color(238, 240, 245),
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height, fontSize };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 120);
+        this.height = this.requested.height ?? this.requested.fontSize + 14;
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/forms/radio-element.d.ts

@@ -0,0 +1,52 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldStyle, RadioSpec } from "../../forms/field.js";
+export interface RadioParams {
+    /** The shared group name - radios with the same `group` are one mutually-exclusive field. */
+    group: string;
+    /** This button's export value - unique within the group. */
+    value: string;
+    /** Whether this button starts selected (at most one per group should be). */
+    selected?: boolean;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Show but do not allow changing the group. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Button diameter in points (default 14). */
+    size?: number;
+    /** Dot colour (default black). */
+    color?: Color;
+    /** Ring colour (default a mid grey). */
+    border?: Color;
+    /** Fill behind the ring. */
+    background?: Color;
+    /** Ring thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * One radio button (AcroForm /Btn, Radio flag). A small round leaf; several sharing a `group` become one
+ * mutually-exclusive field (see `RadioGroup` for the ergonomic wrapper). Draws nothing itself - it emits a
+ * `formfield` IR node whose radio spec bakes the ring + dot /AP at the seam.
+ */
+export declare class RadioElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private size;
+    constructor(p: RadioParams);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: RadioSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/radio-element.js

@@ -0,0 +1,49 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * One radio button (AcroForm /Btn, Radio flag). A small round leaf; several sharing a `group` become one
+ * mutually-exclusive field (see `RadioGroup` for the ergonomic wrapper). Draws nothing itself - it emits a
+ * `formfield` IR node whose radio spec bakes the ring + dot /AP at the seam.
+ */
+export class RadioElement extends SizedPDFElement {
+    constructor(p) {
+        const size = p.size ?? 14;
+        super({ x: 0, y: 0, width: size, height: size });
+        this.size = size;
+        this.spec = {
+            kind: "radio",
+            group: p.group,
+            value: p.value,
+            selected: p.selected,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(102, 102, 102),
+            background: p.background,
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize: 0,
+            borderWidth: p.borderWidth ?? 1,
+        };
+    }
+    calculateLayout(_constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.size;
+        this.height = this.size;
+        return { width: this.size, height: this.size };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/forms/signature-element.d.ts

@@ -0,0 +1,54 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldStyle, SignatureSpec } from "../../forms/field.js";
+export interface SignatureFieldParams {
+    /** The field name (/T) - unique in the document. */
+    name: string;
+    /** A hint drawn inside the empty box, e.g. "Signature". */
+    label?: string;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Draw it but do not let it be signed. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Box width in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points (default 48 - room for a signature). */
+    height?: number;
+    /** Hint font size (default 9). */
+    fontSize?: number;
+    /** Hint colour (default a muted grey). */
+    color?: Color;
+    /** Box border + signing-rule colour (default a mid grey). */
+    border?: Color;
+    /** Box background fill. */
+    background?: Color;
+    /** Border thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * A signature field (AcroForm /Sig) - a PLACEHOLDER someone can sign later. jasy creates the field and
+ * its empty "sign here" appearance; it does not sign (that needs a certificate and a byte-range digest -
+ * a separate feature). Draws nothing itself: it reserves its box and emits a `formfield` IR node.
+ */
+export declare class SignatureFieldElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: SignatureFieldParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: SignatureSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/signature-element.js

@@ -0,0 +1,47 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A signature field (AcroForm /Sig) - a PLACEHOLDER someone can sign later. jasy creates the field and
+ * its empty "sign here" appearance; it does not sign (that needs a certificate and a byte-range digest -
+ * a separate feature). Draws nothing itself: it reserves its box and emits a `formfield` IR node.
+ */
+export class SignatureFieldElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        this.spec = {
+            kind: "signature",
+            name: p.name,
+            label: p.label,
+            tooltip: p.tooltip,
+            readOnly: p.readOnly,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border ?? new Color(154, 164, 178),
+            background: p.background,
+            color: p.color ?? new Color(107, 114, 128),
+            fontSize: p.fontSize ?? 9,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 240);
+        this.height = this.requested.height ?? 48;
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/forms/text-field-element.d.ts

@@ -0,0 +1,61 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { FieldAlign, FieldStyle, TextFieldSpec } from "../../forms/field.js";
+export interface TextFieldParams {
+    /** The field name (/T) - unique in the document; you read the value back by it. */
+    name: string;
+    /** Initial value (/V). */
+    value?: string;
+    /** Tooltip / accessible name (/TU). */
+    tooltip?: string;
+    /** Wrap across lines instead of one line. */
+    multiline?: boolean;
+    /** Mask the input. */
+    password?: boolean;
+    /** Maximum character count. */
+    maxLength?: number;
+    /** Show but do not allow editing. */
+    readOnly?: boolean;
+    /** How the value sits in the box (default left). */
+    align?: FieldAlign;
+    /** Mark it as a field that must be filled in before submitting. */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). */
+    print?: boolean;
+    /** Box width in points; omit to fill the offered width. */
+    width?: number;
+    /** Box height in points; omit for a single-line default (`multiline` wants an explicit height). */
+    height?: number;
+    /** Value font size; `0` = viewer auto-size. */
+    fontSize?: number;
+    /** Value text colour. */
+    color?: Color;
+    /** Box border colour (omit for no border). */
+    border?: Color;
+    /** Box background fill (omit for transparent). */
+    background?: Color;
+    /** Border thickness in points. */
+    borderWidth?: number;
+}
+/**
+ * A text input field (AcroForm /Tx). A leaf that draws NOTHING itself: it reserves its box in the layout
+ * and emits a `formfield` IR node that becomes a Widget annotation + /AcroForm field at the seam.
+ */
+export declare class TextFieldElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private requested;
+    constructor(p: TextFieldParams);
+    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: TextFieldSpec;
+        style: FieldStyle;
+    };
+}

package/dist/elements/forms/text-field-element.js

@@ -0,0 +1,54 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A text input field (AcroForm /Tx). A leaf that draws NOTHING itself: it reserves its box in the layout
+ * and emits a `formfield` IR node that becomes a Widget annotation + /AcroForm field at the seam.
+ */
+export class TextFieldElement extends SizedPDFElement {
+    constructor(p) {
+        super({ x: 0, y: 0, width: p.width, height: p.height });
+        const fontSize = p.fontSize ?? 12;
+        this.spec = {
+            kind: "text",
+            name: p.name,
+            value: p.value,
+            tooltip: p.tooltip,
+            multiline: p.multiline,
+            password: p.password,
+            maxLength: p.maxLength,
+            readOnly: p.readOnly,
+            align: p.align,
+            required: p.required,
+            hidden: p.hidden,
+            print: p.print,
+        };
+        this.style = {
+            border: p.border,
+            background: p.background,
+            color: p.color ?? new Color(0, 0, 0),
+            fontSize,
+            borderWidth: p.borderWidth ?? 1,
+        };
+        this.requested = { width: p.width, height: p.height, fontSize };
+    }
+    calculateLayout(constraints, offset, _ctx) {
+        this.x = offset.x;
+        this.y = offset.y;
+        // Width: explicit, else fill the offered box (a form field with no width spans the column).
+        this.width = this.requested.width ?? (constraints.hasBoundedWidth ? constraints.maxWidth : 200);
+        // Height: explicit, else a comfortable single line (font size + padding). Multiline without an
+        // explicit height still gets the single-line default - the caller should size a multiline box.
+        this.height = this.requested.height ?? this.requested.fontSize + 9;
+        return { width: this.width, height: this.height };
+    }
+    getProps() {
+        return {
+            x: this.x,
+            y: this.y,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
+            spec: this.spec,
+            style: this.style,
+        };
+    }
+}

package/dist/elements/index.d.ts

@@ -6,6 +6,14 @@ export * from "./rectangle-element.js";
 export * from "./image-element.js";
 export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
+export * from "./layout/page-break-element.js";
+export * from "./layout/keep-together-element.js";
+export * from "./forms/text-field-element.js";
+export * from "./forms/checkbox-element.js";
+export * from "./forms/radio-element.js";
+export * from "./forms/choice-element.js";
+export * from "./forms/push-button-element.js";
+export * from "./forms/signature-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

package/dist/elements/index.js

@@ -6,6 +6,14 @@ export * from "./rectangle-element.js";
 export * from "./image-element.js";
 export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
+export * from "./layout/page-break-element.js";
+export * from "./layout/keep-together-element.js";
+export * from "./forms/text-field-element.js";
+export * from "./forms/checkbox-element.js";
+export * from "./forms/radio-element.js";
+export * from "./forms/choice-element.js";
+export * from "./forms/push-button-element.js";
+export * from "./forms/signature-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

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/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/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;