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

package/dist/edit/writer.js

@@ -0,0 +1,283 @@
+import { isDict, isRef, isStream, isString, stringsIn, } from "./objects.js";
+/**
+ * Writing changes back into an existing PDF, as an **incremental update**.
+ *
+ * The original bytes are never rewritten. Changed objects are APPENDED, followed by a fresh
+ * cross-reference section whose `/Prev` points back at the old one. That is what the format was designed
+ * for, and it buys three things: we never have to understand (let alone re-emit) the parts of a foreign
+ * file we did not come for; an existing signature over the original bytes stays intact; and the result
+ * carries a property worth testing - **the original file is a literal PREFIX of the output**.
+ */
+const enc = (s) => new TextEncoder().encode(s);
+/**
+ * A PDF string, written back byte-faithfully.
+ *
+ * Only printable ASCII goes into a `(literal)`. Anything else becomes a `<hex>` string, which carries
+ * the SAME bytes but survives the UTF-8 encoder this file is finally written through - a literal holding
+ * byte 0xE4 would otherwise leave as the two bytes 0xC3 0xA4 and read back as mojibake.
+ */
+const stringToken = (b) => {
+    const printable = b.every((byte) => byte >= 0x20 && byte <= 0x7e);
+    if (!printable) {
+        return `<${Array.from(b, (byte) => byte.toString(16).padStart(2, "0").toUpperCase()).join("")}>`;
+    }
+    let out = "";
+    for (const byte of b) {
+        if (byte === 0x28 || byte === 0x29 || byte === 0x5c)
+            out += "\\" + String.fromCharCode(byte);
+        else
+            out += String.fromCharCode(byte);
+    }
+    return `(${out})`;
+};
+/** Escape a PDF name: everything outside the regular characters becomes `#XX`. */
+const escNameToken = (s) => Array.from(enc(s))
+    .map((b) => b >= 0x21 && b <= 0x7e && !"()<>[]{}/%#".includes(String.fromCharCode(b))
+    ? String.fromCharCode(b)
+    : "#" + b.toString(16).padStart(2, "0").toUpperCase())
+    .join("");
+const num = (n) => (Number.isInteger(n) ? String(n) : String(Number(n.toFixed(6))));
+/**
+ * Serialise an object back to PDF syntax. Used only for objects we deliberately change - everything we
+ * do not touch stays in the original bytes, untouched and unre-encoded.
+ *
+ * A string keeps the spelling it was read with: a name written as `<FEFF…>` stays hex, because that is
+ * how the producer encodes unicode and rewriting it as a literal would corrupt it.
+ */
+export function serialize(o, cipher) {
+    if (o === undefined || o === null)
+        return "null";
+    if (typeof o === "number")
+        return num(o);
+    if (typeof o === "boolean")
+        return String(o);
+    if (Array.isArray(o))
+        return `[${o.map((e) => serialize(e, cipher)).join(" ")}]`;
+    if (isRef(o))
+        return `${o.num} ${o.gen} R`;
+    if (isString(o)) {
+        // In an encrypted document every string was deciphered on open, so it is PLAINTEXT here. Writing it
+        // back as-is would leak it; the caller pre-enciphers each one and passes the result in.
+        const enciphered = cipher?.get(o);
+        if (enciphered !== undefined)
+            return enciphered;
+        // A string the producer wrote as hex stays hex; the rest is decided by its bytes.
+        return o.hex
+            ? `<${Array.from(o.bytes, (b) => b.toString(16).padStart(2, "0").toUpperCase()).join("")}>`
+            : stringToken(o.bytes);
+    }
+    if (isStream(o))
+        return `${serialize(o.dict, cipher)}\nstream\n<<stream data>>\nendstream`;
+    if (isDict(o)) {
+        const parts = [];
+        for (const [k, v] of o.map)
+            parts.push(`/${escNameToken(k)} ${serialize(v, cipher)}`);
+        return `<< ${parts.join(" ")} >>`;
+    }
+    return `/${escNameToken(o.name)}`;
+}
+export class IncrementalWriter {
+    constructor(doc) {
+        this.doc = doc;
+        /** Object number -> its new body, in PDF syntax. */
+        this.changed = new Map();
+        /** Numbers this writer invented, as opposed to ones it replaces - they have no recorded generation. */
+        this.added = new Set();
+        // New objects continue after the highest number the file already uses.
+        this.nextNum = Math.max(0, ...doc.objectNumbers()) + 1;
+    }
+    /** Replace an existing object. */
+    update(objNum, body) {
+        this.changed.set(objNum, body);
+    }
+    /** Append a new object and return its number. */
+    add(body) {
+        const n = this.nextNum++;
+        this.added.add(n);
+        this.changed.set(n, body);
+        return n;
+    }
+    /** A shared Helvetica for regenerated appearances, added once and only when one is drawn. */
+    helv() {
+        return (this.helvNum ?? (this.helvNum = this.add("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>")));
+    }
+    /** The generation to write for an object: the file's own for one we replace, 0 for one we add. */
+    generationOf(objNum) {
+        return this.added.has(objNum) ? 0 : this.doc.generationOf(objNum);
+    }
+    get hasChanges() {
+        return this.changed.size > 0;
+    }
+    /**
+     * Produce the updated file: the original bytes, then every changed object, then a new cross-reference
+     * section chained to the old one.
+     */
+    save() {
+        if (this.changed.size === 0)
+            return this.doc.bytes;
+        const original = this.doc.bytes;
+        const chunks = [original];
+        let offset = original.length;
+        // A file that does not end in a newline would run its last line into our first object.
+        if (original[original.length - 1] !== 10 && original[original.length - 1] !== 13) {
+            chunks.push(enc("\n"));
+            offset += 1;
+        }
+        const offsets = new Map();
+        for (const [objNum, body] of [...this.changed].sort((a, b) => a[0] - b[0])) {
+            offsets.set(objNum, offset);
+            // The generation has to match what the file records, or the new entry describes a different
+            // object than the one being replaced. Objects we ADD are new numbers, and those start at 0.
+            const head = enc(`${objNum} ${this.generationOf(objNum)} obj\n`);
+            chunks.push(head);
+            offset += head.length;
+            if (typeof body === "string") {
+                const b = enc(`${body}\nendobj\n`);
+                chunks.push(b);
+                offset += b.length;
+            }
+            else {
+                const open = enc(`<< ${body.dict} /Length ${body.data.length} >>\nstream\n`);
+                const close = enc(`\nendstream\nendobj\n`);
+                chunks.push(open, body.data, close);
+                offset += open.length + body.data.length + close.length;
+            }
+        }
+        const xrefOffset = offset;
+        chunks.push(this.xrefSection(offsets, xrefOffset));
+        let total = 0;
+        for (const c of chunks)
+            total += c.length;
+        const out = new Uint8Array(total);
+        let at = 0;
+        for (const c of chunks) {
+            out.set(c, at);
+            at += c.length;
+        }
+        return out;
+    }
+    /**
+     * The new cross-reference section, as BYTES.
+     *
+     * Bytes, not a string: an xref stream is binary, and running it through a UTF-8 encoder would turn
+     * every value above 127 into two bytes - which is most offsets, so the whole index becomes garbage.
+     *
+     * A classic table is written when the file already had one; an xref-STREAM file gets a stream,
+     * because mixing the two leaves readers that follow only one kind unable to walk the chain back.
+     */
+    xrefSection(offsets, xrefOffset) {
+        const prev = this.previousStartXref();
+        const rootRef = this.doc.trailer.map.get("Root");
+        const idRef = this.doc.trailer.map.get("ID");
+        const infoRef = this.doc.trailer.map.get("Info");
+        // /Encrypt MUST be carried over. Dropping it declares the file plaintext while its contents are
+        // still ciphertext, so every reader - including ours - hands back raw bytes as field names.
+        const encryptRef = this.doc.trailer.map.get("Encrypt");
+        // An xref stream is itself an object and has to appear in its own index, so its number is taken
+        // first and its offset is where this whole section begins.
+        const all = new Map(offsets);
+        let selfNum;
+        if (this.doc.usesXrefStream) {
+            selfNum = this.nextNum++;
+            all.set(selfNum, xrefOffset);
+        }
+        const size = Math.max(this.nextNum, ...all.keys()) + 1;
+        // Group consecutive object numbers into subsections, which is what both formats want.
+        const nums = [...all.keys()].sort((a, b) => a - b);
+        const runs = [];
+        for (const n of nums) {
+            const last = runs[runs.length - 1];
+            if (last && n === last[0] + last[1].length)
+                last[1].push(n);
+            else
+                runs.push([n, [n]]);
+        }
+        const entry = (key, ref) => ref === undefined ? "" : `${key} ${serialize(ref)}`;
+        if (selfNum !== undefined) {
+            // Rows of `/W [1 4 2]`: in-use marker, 4-byte offset, 2-byte generation. Left uncompressed - a
+            // filter is optional, and a readable appended section is worth more here than a few hundred bytes.
+            const rows = new Uint8Array(nums.length * 7);
+            nums.forEach((n, i) => {
+                const off = all.get(n);
+                const g = n === selfNum ? 0 : this.generationOf(n);
+                rows.set([
+                    1,
+                    (off >>> 24) & 0xff,
+                    (off >>> 16) & 0xff,
+                    (off >>> 8) & 0xff,
+                    off & 0xff,
+                    (g >>> 8) & 0xff,
+                    g & 0xff,
+                ], i * 7);
+            });
+            const index = runs.map(([start, group]) => `${start} ${group.length}`).join(" ");
+            const dict = [
+                "/Type /XRef",
+                `/Size ${size}`,
+                `/Index [${index}]`,
+                "/W [1 4 2]",
+                entry("/Root", rootRef),
+                entry("/Info", infoRef),
+                entry("/ID", idRef),
+                entry("/Encrypt", encryptRef),
+                prev !== undefined ? `/Prev ${prev}` : "",
+                `/Length ${rows.length}`,
+            ].filter(Boolean);
+            const head = enc(`${selfNum} 0 obj\n<< ${dict.join(" ")} >>\nstream\n`);
+            const tail = enc(`\nendstream\nendobj\nstartxref\n${xrefOffset}\n%%EOF\n`);
+            const out = new Uint8Array(head.length + rows.length + tail.length);
+            out.set(head, 0);
+            out.set(rows, head.length);
+            out.set(tail, head.length + rows.length);
+            return out;
+        }
+        let table = "xref\n";
+        for (const [start, group] of runs) {
+            table += `${start} ${group.length}\n`;
+            for (const n of group) {
+                const g = String(this.generationOf(n)).padStart(5, "0");
+                table += `${String(all.get(n)).padStart(10, "0")} ${g} n \n`;
+            }
+        }
+        const trailer = [
+            `/Size ${size}`,
+            entry("/Root", rootRef),
+            entry("/Info", infoRef),
+            entry("/ID", idRef),
+            entry("/Encrypt", encryptRef),
+            prev !== undefined ? `/Prev ${prev}` : "",
+        ].filter(Boolean);
+        return enc(`${table}trailer\n<< ${trailer.join(" ")} >>\nstartxref\n${xrefOffset}\n%%EOF\n`);
+    }
+    /** The offset the ORIGINAL file's `startxref` pointed at - our `/Prev`. */
+    previousStartXref() {
+        const tail = new TextDecoder("latin1").decode(this.doc.bytes.subarray(Math.max(0, this.doc.bytes.length - 2048)));
+        const at = tail.lastIndexOf("startxref");
+        if (at < 0)
+            return undefined;
+        const m = /startxref\s+(\d+)/.exec(tail.slice(at));
+        return m ? Number(m[1]) : undefined;
+    }
+}
+/** Bytes as an enciphered PDF hex string, the form every rewritten string takes in an encrypted file. */
+const hexString = (b) => `<${Array.from(b, (x) => x.toString(16).padStart(2, "0").toUpperCase()).join("")}>`;
+/**
+ * Encipher every string the given objects carry, into the cipher map `serialize` consults.
+ *
+ * Not optional on an encrypted document: `serialize` writes any string missing from the map as
+ * PLAINTEXT, so an object rewritten without this pass leaks whatever it holds.
+ */
+export async function carryStrings(doc, objects, into = new Map()) {
+    if (!doc.isEncrypted)
+        return into;
+    for (const o of objects) {
+        for (const str of stringsIn(o)) {
+            if (into.has(str))
+                continue;
+            const cipher = await doc.encryptForWrite(str.bytes);
+            if (cipher)
+                into.set(str, hexString(cipher));
+        }
+    }
+    return into;
+}

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

@@ -1,7 +1,7 @@
-import { MainAlign, CrossAlign } from "../utils/flex-layout";
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { Fragmentable, FragmentResult } from "../layout/fragmentation";
-import { LayoutContext, SizedElement, SizedPDFElement, WithChildren } from "./pdf-element";
+import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
+import { LayoutContext, SizedElement, SizedPDFElement, WithChildren } from "./pdf-element.js";
 interface ContainerElementParams extends SizedElement, WithChildren {
     /** Space between children. */
     gap?: number;
@@ -9,13 +9,45 @@ interface ContainerElementParams extends SizedElement, WithChildren {
     main?: MainAlign;
     /** Horizontal alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Lay the children out backwards along the main axis (CSS `row-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap`). */
+    wrap?: boolean;
+    /** How the block of wrapped lines sits across the axis (CSS `align-content`). */
+    alignContent?: MainAlign;
+    /** Width/height as a fraction (0..1) of the offered box instead of `width`/`height` (relative sizing). */
+    widthFactor?: number;
+    heightFactor?: number;
+    /** Lower / upper bounds per axis, in points or as a fraction; see `SizingParams`. */
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    minWidthFactor?: number;
+    maxWidthFactor?: number;
+    minHeightFactor?: number;
+    maxHeightFactor?: number;
+    /** width / height; derives whichever axis is left open (CSS `aspect-ratio`). */
+    aspectRatio?: number;
+    /** Start this stack on a fresh page (CSS `break-before: page`). */
+    breakBefore?: boolean;
+    /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
 }
 export declare class ContainerElement extends SizedPDFElement implements Fragmentable {
     private children;
     private gap;
     private main;
     private cross;
-    constructor({ x, y, width, height, children, gap, main, cross }: ContainerElementParams);
+    private reverse;
+    private wrap;
+    private alignContent?;
+    private breakBefore;
+    private breakAfter;
+    private requested;
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }: ContainerElementParams);
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     /**
      * Splits the vertical stack across pages. Children are measured against the content
      * width and packed until one would exceed `maxHeight`. That straddling child is itself
@@ -27,8 +59,21 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
      * Flex children make the container absorb the leftover space, so it never overflows -
      * in that case we don't fragment and hand the whole container back as `fitted`.
      */
+    hasForcedBreak(): boolean;
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private cloneWithChildren;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    /**
+     * A Column stacks vertically, so a flex child of its OWN only ever needs a bounded height. But the need
+     * also propagates: a `Spacer` two levels down is just as unable to resolve against an infinite axis, so
+     * we ask the children too - on both axes, since a nested Row's `Spacer` needs a bounded WIDTH and a
+     * Column nested in a Row is exactly where that width goes missing.
+     *
+     * An explicit extent on an axis short-circuits it: the element already knows how big it is there, and
+     * with no flex descendant nothing needs distributing, so it keeps shrink-wrapping. That is what leaves
+     * every existing layout untouched.
+     */
+    needsBoundedMain(horizontal: boolean): boolean;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): ContainerElementParams;
 }

package/dist/elements/container-element.js

@@ -1,16 +1,26 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContainerElement = void 0;
-const flex_layout_1 = require("../utils/flex-layout");
-const fragmentation_1 = require("../layout/fragmentation");
-const pdf_element_1 = require("./pdf-element");
-class ContainerElement extends pdf_element_1.SizedPDFElement {
-    constructor({ x, y, width, height, children, gap, main, cross }) {
+import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
+import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
+import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
+export class ContainerElement extends SizedPDFElement {
+    constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }) {
         super({ x, y, width, height });
         this.children = children;
-        this.gap = gap !== null && gap !== void 0 ? gap : 0;
-        this.main = main !== null && main !== void 0 ? main : "start";
-        this.cross = cross !== null && cross !== void 0 ? cross : "stretch";
+        this.gap = gap ?? 0;
+        this.main = main ?? "start";
+        this.cross = cross ?? "stretch";
+        this.reverse = reverse ?? false;
+        this.wrap = wrap ?? false;
+        this.alignContent = alignContent;
+        this.requested = { ...sizing, width, height };
+        this.breakBefore = breakBefore ?? false;
+        this.breakAfter = breakAfter ?? false;
+    }
+    breaksBefore() {
+        return this.breakBefore;
+    }
+    breaksAfter() {
+        return this.breakAfter;
     }
     /**
      * Splits the vertical stack across pages. Children are measured against the content
@@ -23,57 +33,109 @@ class ContainerElement extends pdf_element_1.SizedPDFElement {
      * Flex children make the container absorb the leftover space, so it never overflows -
      * in that case we don't fragment and hand the whole container back as `fitted`.
      */
+    hasForcedBreak() {
+        return childrenForceBreak(this.children);
+    }
     fragment(maxHeight, width, ctx) {
-        const { fitted, remainder } = (0, fragmentation_1.packChildren)(this.children, maxHeight, width, ctx, this.gap);
-        // Fits as one region: hand the whole container back so the page renders unchanged
-        // (its normal layout distributes flex / fills the page).
-        if (remainder.length === 0)
+        const { fitted, remainder, forceBreak } = packChildren(this.children, maxHeight, width, ctx, this.gap);
+        // Fits as one region with no forced cut: hand the whole container back so the page renders
+        // unchanged (its normal layout distributes flex / fills the page). A forced break is excluded
+        // here even when nothing follows it (a trailing `PageBreak`): return the packed children, which
+        // no longer hold the consumed break marker, so it does not leak into the render pass.
+        if (remainder.length === 0 && !forceBreak)
             return { fitted: this, remainder: null };
         return {
             fitted: this.cloneWithChildren(fitted),
-            remainder: this.cloneWithChildren(remainder),
+            // Only the CONTINUATION carries `breakAfter`, so a stack that splits across pages still breaks
+            // after its LAST fragment (not after the first one). `breakBefore` is dropped on both: it was
+            // already honoured by the parent before this stack was ever fragmented.
+            remainder: remainder.length === 0 ? null : this.cloneWithChildren(remainder, this.breakAfter),
+            forceBreak,
         };
     }
-    cloneWithChildren(children) {
+    cloneWithChildren(children, breakAfter = false) {
         return new ContainerElement({
             x: this.x,
             y: this.y,
-            width: this.width,
-            height: this.height,
+            // Carry the requested WIDTH (a %-width column keeps its width on every page); the height is
+            // intentionally dropped so each fragment shrink-wraps to the content it actually holds.
+            width: this.requested.width,
+            widthFactor: this.requested.widthFactor,
             children,
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            reverse: this.reverse,
+            wrap: this.wrap,
+            alignContent: this.alignContent,
+            breakAfter,
         });
     }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.requested.widthFactor : this.requested.heightFactor;
+    }
+    /**
+     * A Column stacks vertically, so a flex child of its OWN only ever needs a bounded height. But the need
+     * also propagates: a `Spacer` two levels down is just as unable to resolve against an infinite axis, so
+     * we ask the children too - on both axes, since a nested Row's `Spacer` needs a bounded WIDTH and a
+     * Column nested in a Row is exactly where that width goes missing.
+     *
+     * An explicit extent on an axis short-circuits it: the element already knows how big it is there, and
+     * with no flex descendant nothing needs distributing, so it keeps shrink-wrapping. That is what leaves
+     * every existing layout untouched.
+     */
+    needsBoundedMain(horizontal) {
+        const requested = horizontal
+            ? [this.requested.width, this.requested.widthFactor]
+            : [this.requested.height, this.requested.heightFactor];
+        if (requested.some((v) => v !== undefined))
+            return false;
+        const ownFlexChild = !horizontal && this.children.some((c) => c instanceof FlexiblePDFElement);
+        return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
+    }
     calculateLayout(constraints, offset, ctx) {
-        // The container fills the width/height it is offered; when an axis is unbounded it
-        // shrink-wraps to its children instead (mirrors how Row shrink-wraps). Width unbounded
-        // happens for a Column nested in a Row (the Row offers its fixed children unbounded
-        // width); passing 0 there would collapse every child to width 0.
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
-        if (constraints.hasBoundedHeight)
-            this.height = constraints.maxHeight;
         this.x = offset.x;
         this.y = offset.y;
-        const crossAvail = constraints.hasBoundedWidth ? this.width : Infinity;
-        const mainAvail = constraints.hasBoundedHeight ? this.height : Infinity;
+        // Relative sizing: a pinned extent (fixed points or a fraction of the offered box, clamped into
+        // the constraints) wins; else fill a bounded axis; else stay `undefined` and shrink-wrap below.
+        // A Column nested in a Row gets unbounded width - passing 0 there would collapse children to 0.
+        const specs = extentSpecs(this.requested);
+        const resolved = resolveSize(specs.width, specs.height, this.requested.aspectRatio, constraints);
+        const { width: explicitWidth, height: explicitHeight, constraints: bounds } = resolved;
+        // Fill-or-shrink-wrap is decided by the constraints we were GIVEN; a min/max only caps the result.
+        const boundedWidth = explicitWidth !== undefined
+            ? bounds.constrainWidth(explicitWidth)
+            : constraints.hasBoundedWidth
+                ? bounds.maxWidth
+                : undefined;
+        const boundedHeight = explicitHeight !== undefined
+            ? bounds.constrainHeight(explicitHeight)
+            : constraints.hasBoundedHeight
+                ? bounds.maxHeight
+                : undefined;
+        // Vertical stack: cross = width (children fill it), main = height (the stacking extent).
+        const crossAvail = boundedWidth ?? Infinity;
+        const mainAvail = boundedHeight ?? Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children) {
             // Vertical flex stack (main = height, cross = width). The shared helper measures
             // fixed children, distributes the leftover to flex children, and places everything
             // in source order.
-            result = flex_layout_1.FlexLayoutHelper.layout(this.children, flex_layout_1.VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
+            result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, {
+                gap: this.gap,
+                main: this.main,
+                cross: this.cross,
+                reverse: this.reverse,
+                wrap: this.wrap,
+                alignContent: this.alignContent,
+            }, ctx);
         }
-        // Bounded: fill the offered extent. Unbounded: shrink to the children (height = the
-        // stack, width = the widest child). Top-left coordinates; the container draws nothing,
-        // and the Y-flip happens once at the IR -> backend seam.
-        const width = constraints.hasBoundedWidth ? this.width : result.crossUsed;
-        const height = constraints.hasBoundedHeight ? this.height : result.mainUsed;
-        this.width = width;
-        this.height = height;
-        return { width, height };
+        // Pinned/bounded axis takes that extent; an unbounded one shrink-wraps to the children (height =
+        // the stack, width = the widest child). Top-left coordinates; the container draws nothing, and
+        // the Y-flip happens once at the IR -> backend seam.
+        this.width = boundedWidth ?? result.crossUsed;
+        this.height = boundedHeight ?? result.mainUsed;
+        return { width: this.width, height: this.height };
     }
     getProps() {
         return {
@@ -88,4 +150,3 @@ class ContainerElement extends pdf_element_1.SizedPDFElement {
         };
     }
 }
-exports.ContainerElement = ContainerElement;

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

@@ -0,0 +1,51 @@
+import { Color } from "../../common/color.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, SizedPDFElement } from "../pdf-element.js";
+import type { CheckboxSpec, FieldStyle } from "../../forms/field.js";
+export interface CheckboxParams {
+    /** The field name (/T) - unique in the document. */
+    name: string;
+    /** Whether it starts checked. */
+    checked?: boolean;
+    /** The "on" export value (default `"Yes"`). */
+    onValue?: string;
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+    /** Show but do not allow toggling. */
+    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 side length in points (default 14). */
+    size?: number;
+    /** Checkmark colour (default black). */
+    color?: Color;
+    /** Box border colour (default a mid grey, so the box is visible). */
+    border?: Color;
+    /** Box background fill. */
+    background?: Color;
+    /** Border thickness (default 1). */
+    borderWidth?: number;
+}
+/**
+ * A checkbox (AcroForm /Btn). A small square leaf that draws nothing itself: it reserves its box and
+ * emits a `formfield` IR node whose checkbox spec bakes an /AP checkmark at the seam.
+ */
+export declare class CheckboxElement extends SizedPDFElement {
+    private spec;
+    private style;
+    private size;
+    constructor(p: CheckboxParams);
+    calculateLayout(_constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    getProps(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        spec: CheckboxSpec;
+        style: FieldStyle;
+    };
+}

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

@@ -0,0 +1,48 @@
+import { Color } from "../../common/color.js";
+import { SizedPDFElement } from "../pdf-element.js";
+/**
+ * A checkbox (AcroForm /Btn). A small square leaf that draws nothing itself: it reserves its box and
+ * emits a `formfield` IR node whose checkbox spec bakes an /AP checkmark at the seam.
+ */
+export class CheckboxElement extends SizedPDFElement {
+    constructor(p) {
+        const size = p.size ?? 14;
+        super({ x: 0, y: 0, width: size, height: size });
+        this.size = size;
+        this.spec = {
+            kind: "checkbox",
+            name: p.name,
+            checked: p.checked,
+            onValue: p.onValue,
+            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,
+        };
+    }
+}