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

package/dist/forms/appearance.js

@@ -0,0 +1,204 @@
+import { escPdf, num2, pdfColor } from "./pdf.js";
+import { wrapStringIntoLines } from "../text/line-breaker.js";
+// Appearance streams (/AP): the actual drawn content of a field's box, in the field's OWN coordinate
+// space (bottom-left origin, [0 0 w h]). Shared between CREATE (bake the field's look now) and, later,
+// FILL-existing (regenerate a field's look after setting its value). This is why it is its own module.
+/** Draw the field box: background fill + border stroke, inset so the stroke stays inside the BBox. */
+function box(w, h, style) {
+    const ops = [];
+    if (style.background)
+        ops.push(`${pdfColor(style.background)} rg 0 0 ${num2(w)} ${num2(h)} re f`);
+    if (style.border && style.borderWidth > 0) {
+        const bw = style.borderWidth;
+        const i = bw / 2;
+        ops.push(`${pdfColor(style.border)} RG ${num2(bw)} w ${num2(i)} ${num2(i)} ${num2(w - bw)} ${num2(h - bw)} re S`);
+    }
+    return ops.join("\n");
+}
+/** The unchecked appearance: just the box. */
+export function checkboxOff(w, h, style) {
+    return box(w, h, style);
+}
+/** The checked appearance: the box plus a vector checkmark (font-free, so it renders everywhere). */
+export function checkboxOn(w, h, style) {
+    const lw = Math.max(1, Math.min(w, h) * 0.12);
+    // A tick: down-stroke to the low point, then up-stroke to the high point. Round caps/joins (2 J / 1 j).
+    const p = (fx, fy) => `${num2(fx * w)} ${num2(fy * h)}`;
+    const tick = `${pdfColor(style.color)} RG ${num2(lw)} w 2 J 1 j ` +
+        `${p(0.22, 0.52)} m ${p(0.42, 0.3)} l ${p(0.78, 0.74)} l S`;
+    return `${box(w, h, style)}\n${tick}`;
+}
+// A circle path (4 cubic-bezier arcs, kappa = 0.5523) around (cx, cy) with radius r. Not stroked/filled -
+// the caller appends `S` (stroke) or `f` (fill).
+function circlePath(cx, cy, r) {
+    const k = 0.5523 * r;
+    const n = num2;
+    return (`${n(cx + r)} ${n(cy)} m ` +
+        `${n(cx + r)} ${n(cy + k)} ${n(cx + k)} ${n(cy + r)} ${n(cx)} ${n(cy + r)} c ` +
+        `${n(cx - k)} ${n(cy + r)} ${n(cx - r)} ${n(cy + k)} ${n(cx - r)} ${n(cy)} c ` +
+        `${n(cx - r)} ${n(cy - k)} ${n(cx - k)} ${n(cy - r)} ${n(cx)} ${n(cy - r)} c ` +
+        `${n(cx + k)} ${n(cy - r)} ${n(cx + r)} ${n(cy - k)} ${n(cx + r)} ${n(cy)} c`);
+}
+/** The ring of a radio button (the outline), in [0 0 w h]. */
+function radioRing(w, h, style) {
+    const r = Math.min(w, h) / 2;
+    const bw = style.borderWidth > 0 ? style.borderWidth : 1;
+    const ops = [];
+    if (style.background)
+        ops.push(`${pdfColor(style.background)} rg ${circlePath(w / 2, h / 2, r)} f`);
+    const stroke = style.border ?? style.color;
+    ops.push(`${pdfColor(stroke)} RG ${num2(bw)} w ${circlePath(w / 2, h / 2, r - bw / 2)} S`);
+    return ops.join("\n");
+}
+/** An unselected radio button: just the ring. */
+export function radioOff(w, h, style) {
+    return radioRing(w, h, style);
+}
+/** A selected radio button: the ring plus a filled inner dot. */
+export function radioOn(w, h, style) {
+    const r = Math.min(w, h) / 2;
+    const dot = `${pdfColor(style.color)} rg ${circlePath(w / 2, h / 2, r * 0.45)} f`;
+    return `${radioRing(w, h, style)}\n${dot}`;
+}
+/**
+ * A push button's face: the box plus its caption, centred. The caller measures the caption (this module
+ * stays free of font metrics and the writer) and passes `captionWidth` in points and `capHeight` as an em
+ * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `fontRes` is
+ * the font's resource name inside the appearance stream's own /Resources.
+ */
+export function pushButtonFace(w, h, style, caption, captionWidth, capHeight, fontRes, size) {
+    // Baseline placed so the CAPITALS sit optically centred in the box, not the em square.
+    const y = (h - capHeight * size) / 2;
+    const caption_ = caption ? centredText(w, h, style, caption, captionWidth, y, fontRes, size) : "";
+    return `${box(w, h, style)}\n${caption_}`;
+}
+/** One centred, clipped text run inside a field box. Clipping means an over-long caption is cut at the
+ *  border instead of bleeding across the page. Shared by the push button and the signature placeholder. */
+function centredText(w, h, style, text, textWidth, baselineY, fontRes, size) {
+    return (`q 0 0 ${num2(w)} ${num2(h)} re W n ` +
+        `BT /${fontRes} ${num2(size)} Tf ${pdfColor(style.color)} rg ` +
+        `${num2((w - textWidth) / 2)} ${num2(baselineY)} Td (${escPdf(text)}) Tj ET Q`);
+}
+/**
+ * An EMPTY signature field: the box, a signing rule across the lower third, and an optional hint centred
+ * just above it. This is the placeholder look - once someone actually signs, the signing tool replaces
+ * this appearance with its own.
+ */
+export function signatureFace(w, h, style, label, labelWidth, fontRes, size) {
+    const ruleY = h * 0.3;
+    const inset = w * 0.08;
+    const stroke = style.border ?? style.color;
+    const rule = `${pdfColor(stroke)} RG ${num2(Math.max(0.5, style.borderWidth * 0.75))} w ` +
+        `${num2(inset)} ${num2(ruleY)} m ${num2(w - inset)} ${num2(ruleY)} l S`;
+    const hint = label ? centredText(w, h, style, label, labelWidth, ruleY + 6, fontRes, size) : "";
+    return `${box(w, h, style)}\n${rule}\n${hint}`;
+}
+// Horizontal padding inside a field box, on top of the border - the same small inset Acrobat leaves so
+// the value does not touch the frame.
+const FIELD_PAD = 2;
+// A list box highlights its selected rows. Viewers each pick their own colour; once we bake the
+// appearance WE decide, and this light blue is the familiar selection tint.
+const SELECTION_TINT = "0.60 0.75 0.95";
+/** One pre-measured line of field text. The caller owns wrapping + measuring, so this module stays free
+ *  of font metrics (and can be reused verbatim when filling an existing PDF). */
+/**
+ * A field value split into the lines it is DRAWN as.
+ *
+ * An explicit line break in the value is a line break, and only then does width wrapping apply within
+ * each paragraph. Wrapping on width alone ran the paragraphs together - a multi-line field showed
+ * "first lineSecond line" - and it did so on BOTH paths, creating a field and filling one, which is why
+ * this lives here rather than in either of them.
+ */
+export function wrapFieldValue(value, fontFamily, fontSize, fontStyle, maxWidth, metrics, multiline) {
+    if (!multiline)
+        return [value.replace(/\r\n?|\n/g, " ")];
+    // CR, LF and CRLF all mean one break (PDF 7.3.4.2 says the same about a literal string).
+    return value
+        .split(/\r\n?|\n/)
+        .flatMap((para) => para === ""
+        ? [""]
+        : wrapStringIntoLines(para, fontFamily, fontSize, fontStyle, maxWidth, metrics));
+}
+/**
+ * The size a field draws its value at. `0` in `/DA` is the PDF convention for "auto, fit the box", and
+ * both paths - creating a field and filling one - have to resolve it the SAME way, or the same field
+ * comes out at two different sizes depending on which one touched it last.
+ */
+export function fieldDrawSize(fontSize, height, borderWidth, capHeight) {
+    if (fontSize > 0)
+        return fontSize;
+    const available = height - 2 * (2 + borderWidth);
+    return Math.max(4, Math.min(12, (available * 0.7) / (capHeight || 0.7)));
+}
+/** Where a line of `width` starts, given the box, its padding and the requested alignment. */
+function alignX(boxWidth, pad, width, align = "left") {
+    if (align === "center")
+        return (boxWidth - width) / 2;
+    if (align === "right")
+        return boxWidth - pad - width;
+    return pad;
+}
+/**
+ * `BT … ET` for absolutely-placed lines. `Tm` (not `Td`) so each line's position is independent.
+ *
+ * Field text is drawn UNKERNED (a plain `Tj`, never a `TJ` array), even though ordinary document text
+ * kerns by default. That is deliberate: the moment someone clicks into a field, the viewer regenerates
+ * this appearance from `/DA` - and viewers do not kern field text. Kerning here would make the value
+ * visibly shift on first click. The measurement matches: `getStringWidth` is the plain glyph sum, so
+ * measured still equals drawn.
+ */
+function textBlock(lines, style, size, fontRes) {
+    const runs = lines
+        .map((l) => `1 0 0 1 ${num2(l.x)} ${num2(l.y)} Tm (${escPdf(l.text)}) Tj`)
+        .join("\n");
+    return `BT /${fontRes} ${num2(size)} Tf ${pdfColor(style.color)} rg\n${runs}\nET`;
+}
+/** Everything a field draws is clipped to its own box, so a long value is cut at the frame rather than
+ *  bleeding across the page. */
+function clipped(w, h, ops) {
+    return `q 0 0 ${num2(w)} ${num2(h)} re W n\n${ops}\nQ`;
+}
+/**
+ * A text field's value, baked. `lines` is already wrapped (one entry for a single-line field). A
+ * single line sits optically centred; a multi-line field stacks from the top, both measured off the
+ * font's cap height rather than a guessed ratio.
+ */
+export function textFieldFace(w, h, style, lines, capHeight, size, fontRes, multiline, align = "left") {
+    const face = box(w, h, style);
+    if (lines.length === 0)
+        return face;
+    const pad = FIELD_PAD + style.borderWidth;
+    const lineHeight = size * 1.15;
+    const placed = lines.map((l, i) => ({
+        text: l.text,
+        x: alignX(w, pad, l.width, align),
+        // Multi-line: the first line's capitals start one cap-height below the top inset, then step down.
+        // Single line: centre the capitals in the box.
+        y: multiline ? h - pad - capHeight * size - i * lineHeight : (h - capHeight * size) / 2,
+    }));
+    return `${face}\n${clipped(w, h, textBlock(placed, style, size, fontRes))}`;
+}
+/**
+ * A list box, baked: the visible options stacked from the top, with a highlight behind the selected
+ * ones. A combo box (dropdown) uses `textFieldFace` instead - it shows only its current value.
+ */
+export function listBoxFace(w, h, style, lines, capHeight, size, fontRes, align = "left") {
+    const pad = FIELD_PAD + style.borderWidth;
+    const lineHeight = size * 1.15;
+    const rowTop = (i) => h - pad - (i + 1) * lineHeight;
+    // Highlights first, so the text sits on top of them.
+    const highlights = lines
+        .map((l, i) => l.selected
+        ? `${SELECTION_TINT} rg ${num2(pad / 2)} ${num2(rowTop(i))} ${num2(w - pad)} ${num2(lineHeight)} re f`
+        : "")
+        .filter(Boolean)
+        .join("\n");
+    const placed = lines.map((l, i) => ({
+        text: l.text,
+        x: alignX(w, pad, l.width, align),
+        // Baseline inside the row: lift it off the row bottom by the slack under the capitals.
+        y: rowTop(i) + (lineHeight - capHeight * size) / 2,
+    }));
+    const inner = [highlights, textBlock(placed, style, size, fontRes)].filter(Boolean).join("\n");
+    return `${box(w, h, style)}\n${clipped(w, h, inner)}`;
+}

package/dist/forms/field.d.ts

@@ -0,0 +1,164 @@
+import type { Color } from "../common/color.js";
+/**
+ * The semantic description of ONE AcroForm field, independent of whether it is being CREATED (the field
+ * elements produce it) or FILLED in an existing PDF (the reader parses existing fields into it, later).
+ * This shared model is the spine that makes "create" and "fill existing" two parts of one feature.
+ *
+ * A discriminated union, one `kind` per PDF field family (/Tx, /Btn, /Ch, /Sig) - all of them
+ * implemented, so a `switch` over `kind` is exhaustive.
+ */
+export type FormFieldSpec = TextFieldSpec | CheckboxSpec | RadioSpec | ChoiceSpec | PushButtonSpec | SignatureSpec;
+/**
+ * What every field kind shares, whatever its family. Kept in one place so a new field type cannot
+ * silently miss them.
+ */
+export interface CommonFieldProps {
+    /** A tooltip / accessible name (/TU). */
+    tooltip?: string;
+    /** Show the field but do not let it be changed. */
+    readOnly?: boolean;
+    /** Mark it as a field that must be filled in before the form is submitted (/Ff Required). */
+    required?: boolean;
+    /** Hide the widget entirely - neither on screen nor in print. */
+    hidden?: boolean;
+    /** Include the widget when printing (default true). `false` keeps it on screen only. */
+    print?: boolean;
+}
+/** How a value is aligned inside its field box (the PDF calls this "quadding", /Q). */
+export type FieldAlign = "left" | "center" | "right";
+/**
+ * A variable text field (/Tx). The PDF variants live in field flags; here they are typed props, so you
+ * never hand-assemble a `/Ff` bitmask.
+ */
+export interface TextFieldSpec extends CommonFieldProps {
+    kind: "text";
+    /** The field's name (/T) - what you read the value back by. Must be unique in the document. */
+    name: string;
+    /** The current text value (/V). */
+    value?: string;
+    /** A tooltip / accessible name for the field (/TU). */
+    tooltip?: string;
+    /** Wrap across multiple lines instead of a single line (the Multiline flag). */
+    multiline?: boolean;
+    /** Mask the typed characters (the Password flag). */
+    password?: boolean;
+    /** How the value sits in the box (default left). Applies to the baked appearance AND /Q. */
+    align?: FieldAlign;
+    /** Maximum number of characters the field accepts (/MaxLen). */
+    maxLength?: number;
+}
+/**
+ * A checkbox (/Btn, neither the Radio nor the Pushbutton flag). Its value is the "on" export name when
+ * checked and `Off` when not - PDF checkboxes use NAMES, not strings; we hide that behind `checked`.
+ */
+export interface CheckboxSpec extends CommonFieldProps {
+    kind: "checkbox";
+    /** The field name (/T). */
+    name: string;
+    /** Whether it starts checked. */
+    checked?: boolean;
+    /** The "on" export value (the /AP state name + /V when checked). Default `"Yes"`. */
+    onValue?: string;
+}
+/**
+ * One radio button (/Btn with the Radio flag). Every radio sharing a `group` is ONE AcroForm field whose
+ * `/Kids` are the individual buttons - mutually exclusive, so picking one clears the rest. `value` is this
+ * button's export name (unique within the group); it becomes the field's value when this one is picked.
+ */
+export interface RadioSpec extends CommonFieldProps {
+    kind: "radio";
+    /** The shared group name (/T of the parent field). All radios with the same `group` are one field. */
+    group: string;
+    /** This button's export value - unique in the group; the field's /V when this one is selected. */
+    value: string;
+    /** Whether this button starts selected (at most one per group should be). */
+    selected?: boolean;
+}
+/** One entry of a choice field. `label` is what the reader sees; `value` is what gets stored. */
+export interface ChoiceOption {
+    value: string;
+    label?: string;
+}
+/**
+ * A choice field (/Ch): a dropdown (combo box) or a list box. `combo` picks which. The value(s) are
+ * export strings from `options`. A combo may be `editable` (the reader can type a value not in the list);
+ * a list box may allow `multiSelect`.
+ */
+export interface ChoiceSpec extends CommonFieldProps {
+    kind: "choice";
+    /** The field name (/T). */
+    name: string;
+    /** The selectable options. */
+    options: ChoiceOption[];
+    /** `true` = dropdown (combo box), `false` = list box. */
+    combo: boolean;
+    /** Combo only: let the reader type a value that is not in the list. */
+    editable?: boolean;
+    /** List box only: allow more than one selection. */
+    multiSelect?: boolean;
+    /** The selected value (single-select). */
+    value?: string;
+    /** How the value sits in the box (default left). */
+    align?: FieldAlign;
+    /** The selected values (a `multiSelect` list box). */
+    values?: string[];
+    /** Tooltip / accessible name. */
+    tooltip?: string;
+}
+/**
+ * What a push button does when clicked. A typed union, so an action can never be half-specified (a
+ * submit without a target is not expressible). Scripted (JavaScript) actions are deliberately out of
+ * scope - a jasy form is data, not a program.
+ */
+export type ButtonAction = {
+    kind: "reset";
+} | {
+    kind: "submit";
+    url: string;
+} | {
+    kind: "url";
+    url: string;
+};
+/**
+ * A push button (/Btn with the Pushbutton flag). Unlike every other field it holds NO value - it is a
+ * click target that fires an action. Its caption is baked into the appearance stream, so the button
+ * looks the same in every viewer and in print.
+ */
+export interface PushButtonSpec extends CommonFieldProps {
+    kind: "pushbutton";
+    /** The field name (/T). */
+    name: string;
+    /** The caption drawn on the button. */
+    label: string;
+    /** What clicking it does; omit for a button that does nothing (a plain label). */
+    action?: ButtonAction;
+}
+/**
+ * A signature field (/Sig) - a PLACEHOLDER where a signature can later be applied. jasy creates the
+ * field and its empty appearance; it does not sign (real signing needs a certificate and a byte-range
+ * digest, a separate feature). An unsigned field has no /V; a signer fills that in later.
+ */
+export interface SignatureSpec extends CommonFieldProps {
+    kind: "signature";
+    /** The field name (/T). */
+    name: string;
+    /** A hint drawn inside the empty box, e.g. "Signature" or the signer's role. */
+    label?: string;
+}
+/**
+ * How a field's WIDGET is painted: the box (border + fill) and how its value looks (font size + colour).
+ * Kept separate from the semantic spec because it maps to the widget `/MK` + `/DA`, not the field value -
+ * and the fill-existing path reuses it to restyle a field it did not create.
+ */
+export interface FieldStyle {
+    /** Border (stroke) colour of the field box. Omit for no border. */
+    border?: Color;
+    /** Background fill of the field box. Omit for transparent. */
+    background?: Color;
+    /** The value's text colour (drawn into `/DA`). */
+    color: Color;
+    /** Font size in points; `0` lets the viewer auto-size to the box (the PDF convention). */
+    fontSize: number;
+    /** Border thickness in points (only drawn when a `border` is set). */
+    borderWidth: number;
+}

package/dist/forms/field.js

@@ -0,0 +1 @@
+export {};

package/dist/forms/pdf.d.ts

@@ -0,0 +1,19 @@
+import type { Color } from "../common/color.js";
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+/** The regular face, for measuring a field's built-in Helvetica. `FontStyle` is a string enum, so this
+ *  is its exact value - asserted here once instead of importing the enum (which would be a runtime
+ *  import of the writer, see above). */
+export declare const NORMAL_STYLE: FontStyle;
+/** Escape a PDF literal string: backslash first, then the string delimiters. */
+export declare const escPdf: (s: string) => string;
+/** Trim a number to 2 decimals (PDF operands). */
+export declare const num2: (n: number) => number;
+/** A colour as PDF operands "r g b" in 0..1 (Color stores 0..255). */
+export declare const pdfColor: (c: Color) => string;
+/**
+ * Escape a PDF **Name** token (`/Yes`, `/Off`, a checkbox's export value). A Name may only hold the
+ * regular characters; whitespace, the delimiters `()<>[]{}/%` and `#` itself must be written `#XX` by
+ * BYTE. Without this, an export value like `"Ja / Nein"` would break the dictionary it sits in.
+ * Literal strings - `(text)` - use `escPdf` instead; the two escapes are not interchangeable.
+ */
+export declare const escName: (s: string) => string;

package/dist/forms/pdf.js

@@ -0,0 +1,28 @@
+// Small PDF-writer helpers shared across the forms module (widget dicts + appearance streams).
+//
+// Note: everything under `forms/` imports the object manager TYPE-ONLY. Keeping the runtime dependency
+// one-way (the writer owns a collector, never the reverse) avoids an ESM import cycle.
+/** The regular face, for measuring a field's built-in Helvetica. `FontStyle` is a string enum, so this
+ *  is its exact value - asserted here once instead of importing the enum (which would be a runtime
+ *  import of the writer, see above). */
+export const NORMAL_STYLE = "normal";
+/** Escape a PDF literal string: backslash first, then the string delimiters. */
+export const escPdf = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+/** Trim a number to 2 decimals (PDF operands). */
+export const num2 = (n) => Number(n.toFixed(2));
+/** A colour as PDF operands "r g b" in 0..1 (Color stores 0..255). */
+export const pdfColor = (c) => c
+    .toArray()
+    .map((v) => (v / 255).toFixed(3))
+    .join(" ");
+/**
+ * Escape a PDF **Name** token (`/Yes`, `/Off`, a checkbox's export value). A Name may only hold the
+ * regular characters; whitespace, the delimiters `()<>[]{}/%` and `#` itself must be written `#XX` by
+ * BYTE. Without this, an export value like `"Ja / Nein"` would break the dictionary it sits in.
+ * Literal strings - `(text)` - use `escPdf` instead; the two escapes are not interchangeable.
+ */
+export const escName = (s) => Array.from(new TextEncoder().encode(s))
+    .map((b) => b >= 0x21 && b <= 0x7e && !"()<>[]{}/%#".includes(String.fromCharCode(b))
+    ? String.fromCharCode(b)
+    : "#" + b.toString(16).padStart(2, "0").toUpperCase())
+    .join("");

package/dist/ir/display-list.d.ts

@@ -1,5 +1,6 @@
 import { Color } from "../common/color.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
 /**
  * Display list - the seam between layout and the PDF backend.
  *
@@ -35,6 +36,7 @@ export interface TextRun {
     fontStyle: FontStyle;
     fontSize: number;
     color: Color;
+    letterSpacing?: number;
     tag?: StructTag;
 }
 /** An axis-aligned rectangle. An absent `fill` or `stroke` means that part is not drawn. */
@@ -144,6 +146,21 @@ export interface Outline {
     title: string;
     level: number;
 }
+/**
+ * An interactive form field (AcroForm). Like `Link` it draws NOTHING into the content stream - it becomes
+ * a Widget ANNOTATION on the page (`/Annots`) and a field in the catalog `/AcroForm`, both built from the
+ * shared `FormFieldSpec`. The rect is the field box in top-left engine coords; the Y-flip converts it to
+ * page space. See `forms/acroform.ts` for the widget/field assembly.
+ */
+export interface FormFieldNode {
+    type: "formfield";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    field: FormFieldSpec;
+    style: FieldStyle;
+}
 /**
  * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the
  * matching `TransformPop` is painted through `matrix`. This is what `Rotated` wraps its child's nodes
@@ -226,4 +243,4 @@ export interface Path {
     tag?: StructTag;
 }
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | TransformPush | TransformPop;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | FormFieldNode | TransformPush | TransformPop;

package/dist/layout/fragmentation.d.ts

@@ -12,6 +12,10 @@ import { LayoutContext, PDFElement } from "../elements/pdf-element.js";
 export interface FragmentResult {
     fitted: PDFElement | null;
     remainder: PDFElement | null;
+    /** The split ended at a FORCED page break (a `PageBreak`), not because the region filled up. The
+     *  remainder must start a fresh page, and an enclosing flow must stop packing too - so this bubbles
+     *  up through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
+    forceBreak?: boolean;
 }
 /**
  * An element that knows how to split itself across regions. Width is already finalized
@@ -29,6 +33,13 @@ export declare function isFragmentable(element: PDFElement): element is PDFEleme
  * logs and clips, `"ignore"` clips silently.
  */
 export type OverflowPolicy = "error" | "warn" | "ignore";
+export declare function reportOverflow(child: PDFElement, childHeight: number, maxHeight: number, policy: OverflowPolicy): void;
+/**
+ * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
+ * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
+ * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ */
+export declare function childrenForceBreak(children: PDFElement[]): boolean;
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -46,4 +57,5 @@ export type OverflowPolicy = "error" | "warn" | "ignore";
 export declare function packChildren(children: PDFElement[], maxHeight: number, width: number, ctx: LayoutContext, gap?: number): {
     fitted: PDFElement[];
     remainder: PDFElement[];
+    forceBreak: boolean;
 };

package/dist/layout/fragmentation.js

@@ -10,7 +10,7 @@ export function isFragmentable(element) {
     const canFragment = element.canFragment;
     return typeof canFragment !== "function" || canFragment.call(element);
 }
-function reportOverflow(child, childHeight, maxHeight, policy) {
+export function reportOverflow(child, childHeight, maxHeight, policy) {
     if (policy === "ignore")
         return;
     const name = child.constructor.name.replace(/Element$/, "");
@@ -21,6 +21,14 @@ function reportOverflow(child, childHeight, maxHeight, policy) {
         throw new Error(`Layout overflow: ${detail}`);
     console.warn(`Layout overflow (clipped): ${detail}`);
 }
+/**
+ * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
+ * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
+ * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ */
+export function childrenForceBreak(children) {
+    return children.some((child) => child.hasForcedBreak() || child.breaksBefore() || child.breaksAfter());
+}
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -39,30 +47,61 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
     const fitted = [];
     const remainder = [];
     let usedHeight = 0;
+    // Everything from index `from` onward spills to the next region; `broke` says whether the cut was
+    // a FORCED page break (so an enclosing flow stops too) rather than the region filling up.
+    const spill = (from, broke) => {
+        for (let j = from; j < children.length; j++)
+            remainder.push(children[j]);
+        return { fitted, remainder, forceBreak: broke };
+    };
     for (let i = 0; i < children.length; i++) {
         const child = children[i];
+        // A forced break: consume the marker (it draws nothing) and send everything after it to a fresh
+        // page, regardless of how much room is left.
+        if (child.isPageBreak())
+            return spill(i + 1, true);
+        // break-before: this child wants a fresh page. Honour it only if something is already on this region
+        // (CSS ignores break-before at the top of a page); that guard also prevents an empty page + a loop.
+        if (child.breaksBefore() && fitted.length > 0)
+            return spill(i, true);
         const childHeight = child.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
         // A gap precedes every child except the first one placed in this region.
         const lead = fitted.length > 0 ? gap : 0;
-        if (usedHeight + lead + childHeight <= maxHeight) {
+        // Place whole only if it fits AND holds no forced break: a child that fits by height but contains
+        // a `PageBreak` (or a break-before/after) in its subtree must still be fragmented, or the break
+        // would be swallowed.
+        if (usedHeight + lead + childHeight <= maxHeight && !child.hasForcedBreak()) {
             fitted.push(child);
             usedHeight += lead + childHeight;
+            // break-after: everything after this child starts a fresh page.
+            if (child.breaksAfter())
+                return spill(i + 1, true);
             continue;
         }
-        // `child` straddles the boundary. Try to split it; otherwise place/defer it whole.
+        // `child` straddles the boundary, or carries a forced break. Split it; otherwise place/defer whole.
         const remaining = maxHeight - usedHeight - lead;
         let placedPart = false;
+        let childBroke = false;
         if (isFragmentable(child)) {
             const split = child.fragment(Math.max(0, remaining), width, ctx);
+            childBroke = split.forceBreak ?? false;
             if (split.fitted) {
                 fitted.push(split.fitted);
+                // The child fully fit and triggered no cut: it only reached this path because its subtree
+                // FLAGGED a possible break (hasForcedBreak) that turned out to be a no-op here - e.g. a
+                // break-before at the top of the region, which CSS ignores. Keep packing the siblings after
+                // it instead of spilling them, so break-before does not accidentally push later content away.
+                if (!split.remainder && !childBroke) {
+                    usedHeight += lead + childHeight;
+                    continue;
+                }
                 if (split.remainder)
                     remainder.push(split.remainder);
                 placedPart = true;
             }
         }
         if (!placedPart) {
-            if (fitted.length === 0) {
+            if (fitted.length === 0 && !childBroke) {
                 // Taller than the whole region and unsplittable: force it on (it overflows and is clipped)
                 // so the next region still advances - and surface it per the overflow policy.
                 reportOverflow(child, childHeight, maxHeight, ctx.onOverflow ?? "ignore");
@@ -72,9 +111,7 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
                 remainder.push(child);
             }
         }
-        for (let j = i + 1; j < children.length; j++)
-            remainder.push(children[j]);
-        break;
+        return spill(i + 1, childBroke);
     }
-    return { fitted, remainder };
+    return { fitted, remainder, forceBreak: false };
 }

package/dist/renderer/form-field-renderer.d.ts

@@ -0,0 +1,20 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { TextFieldElement } from "../elements/forms/text-field-element.js";
+import { CheckboxElement } from "../elements/forms/checkbox-element.js";
+import { RadioElement } from "../elements/forms/radio-element.js";
+import { ChoiceElement } from "../elements/forms/choice-element.js";
+import { PushButtonElement } from "../elements/forms/push-button-element.js";
+import { SignatureFieldElement } from "../elements/forms/signature-element.js";
+import { IRNode } from "../ir/display-list.js";
+/** Any form-field element exposes its box + shared spec + style through `getProps()`. */
+type FormFieldElement = TextFieldElement | CheckboxElement | RadioElement | ChoiceElement | PushButtonElement | SignatureFieldElement;
+/**
+ * Renders a form-field element to a single `formfield` IR node - the field's box + its shared
+ * `FormFieldSpec` + style. It draws nothing; the PageRenderer peels it into a Widget /Annot and the
+ * /AcroForm (via forms/acroform.ts). One renderer serves every field element (the spec's `kind`
+ * discriminates downstream).
+ */
+export declare class FormFieldRenderer {
+    static render(element: FormFieldElement, _objectManager: PDFObjectManager): Promise<IRNode[]>;
+}
+export {};

package/dist/renderer/form-field-renderer.js

@@ -0,0 +1,12 @@
+/**
+ * Renders a form-field element to a single `formfield` IR node - the field's box + its shared
+ * `FormFieldSpec` + style. It draws nothing; the PageRenderer peels it into a Widget /Annot and the
+ * /AcroForm (via forms/acroform.ts). One renderer serves every field element (the spec's `kind`
+ * discriminates downstream).
+ */
+export class FormFieldRenderer {
+    static async render(element, _objectManager) {
+        const { x, y, width, height, spec, style } = element.getProps();
+        return [{ type: "formfield", x, y, width, height, field: spec, style }];
+    }
+}

package/dist/renderer/keep-together-renderer.d.ts

@@ -0,0 +1,10 @@
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { IRNode } from "../ir/display-list.js";
+/**
+ * A `keepTogether` is layout-transparent: it just renders its child. All of its work happens in the
+ * layout pass (`fragment`), never here.
+ */
+export declare class KeepTogetherRenderer {
+    static render(group: KeepTogetherElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/keep-together-renderer.js

@@ -0,0 +1,12 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+/**
+ * A `keepTogether` is layout-transparent: it just renders its child. All of its work happens in the
+ * layout pass (`fragment`), never here.
+ */
+export class KeepTogetherRenderer {
+    static async render(group, objectManager) {
+        const { child } = group.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        return renderer ? await renderer(child, objectManager) : [];
+    }
+}