@jasy/pdf 1.0.0-alpha.7 → 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.
  *
@@ -145,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
@@ -227,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/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/page-renderer.js

@@ -74,14 +74,20 @@ export class PageRenderer {
         const num = (n) => Number(n.toFixed(2));
         const annotRefs = [];
         for (const node of flipped) {
+            // A form field: build its Widget annotation + register it as an /AcroForm field (the logic lives in
+            // forms/acroform.ts), then reference it here in the page /Annots - the same side channel as a link.
+            if (node.type === "formfield") {
+                annotRefs.push(`${objectManager.acroform.addField(node, objectManager)} 0 R`);
+                continue;
+            }
             if (node.type !== "link")
                 continue;
             const rect = `[${num(node.x)} ${num(node.y)} ${num(node.x + node.width)} ${num(node.y + node.height)}]`;
             // Either an external URL (/URI) or an internal named destination (/GoTo, resolved via /Names /Dests).
             // The Link IR guarantees exactly one is set; prefer `dest` when present.
             const action = node.dest !== undefined
-                ? `/A << /S /GoTo /D (${PdfBackend.escapePdfString(node.dest)}) >>`
-                : `/A << /S /URI /URI (${PdfBackend.escapePdfString(node.href ?? "")}) >>`;
+                ? `/A << /S /GoTo /D ${objectManager.pdfString(node.dest)} >>`
+                : `/A << /S /URI /URI ${objectManager.pdfString(node.href ?? "")} >>`;
             const annot = objectManager.addObject(`<< /Type /Annot /Subtype /Link /Rect ${rect} /Border [0 0 0] ${action} >>`);
             annotRefs.push(`${annot} 0 R`);
         }

package/dist/renderer/pdf-backend.js

@@ -65,6 +65,9 @@ export class PdfBackend {
                 case "link":
                     // A link's clickable rect flips around its bottom edge, exactly like a rect.
                     return { ...node, y: pageHeight - node.y - node.height };
+                case "formfield":
+                    // A form field's box flips around its bottom edge, exactly like a link rect.
+                    return { ...node, y: pageHeight - node.y - node.height };
                 case "outline":
                     // An outline anchor is a single point (the target's top); flip it like a text baseline.
                     return { ...node, y: pageHeight - node.y };
@@ -137,6 +140,7 @@ export class PdfBackend {
                 node.type === "link" ||
                 node.type === "outline" ||
                 node.type === "anchor" ||
+                node.type === "formfield" ||
                 ops === "")
                 return ops;
             const { open, close } = struct.mark(node.tag);
@@ -357,6 +361,10 @@ export class PdfBackend {
             case "anchor":
                 // A named destination draws nothing - it becomes a /Names /Dests entry (built in PageRenderer/PDFRenderer).
                 return "";
+            case "formfield":
+                // A form field draws nothing in the content stream - it becomes a Widget /Annot + /AcroForm field
+                // (built in PageRenderer via forms/acroform.ts).
+                return "";
             default: {
                 // Exhaustiveness guard: if a new IRNode variant is added, this fails to compile.
                 const unknown = node;

package/dist/renderer/pdf-renderer.js

@@ -31,6 +31,13 @@ import { AnchorRenderer } from "./anchor-renderer.js";
 import { PageBreakRenderer } from "./page-break-renderer.js";
 import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
 import { KeepTogetherRenderer } from "./keep-together-renderer.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 { FormFieldRenderer } from "./form-field-renderer.js";
 import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
 import { PageBuilderRenderer } from "./page-builder-renderer.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
@@ -51,6 +58,12 @@ export class PDFRenderer {
         RendererRegistry.register(PaddingElement, PaddingRenderer.render);
         RendererRegistry.register(PageBreakElement, PageBreakRenderer.render);
         RendererRegistry.register(KeepTogetherElement, KeepTogetherRenderer.render);
+        RendererRegistry.register(TextFieldElement, FormFieldRenderer.render);
+        RendererRegistry.register(CheckboxElement, FormFieldRenderer.render);
+        RendererRegistry.register(RadioElement, FormFieldRenderer.render);
+        RendererRegistry.register(ChoiceElement, FormFieldRenderer.render);
+        RendererRegistry.register(PushButtonElement, FormFieldRenderer.render);
+        RendererRegistry.register(SignatureFieldElement, FormFieldRenderer.render);
         RendererRegistry.register(DefaultTextStyleElement, DefaultTextStyleRenderer.render);
         RendererRegistry.register(ImageElement, ImageRenderer.render);
         RendererRegistry.register(LineElement, LineRenderer.render);
@@ -124,8 +137,13 @@ export class PDFRenderer {
         const outlineCatalog = objectManager.outline.finalize(objectManager);
         if (outlineCatalog)
             catalogParts.push(outlineCatalog);
+        // Interactive form fields: emit the catalog /AcroForm dict collected as pages rendered. Returns ""
+        // (no-op) when no field was placed, so a plain document's catalog is unchanged.
+        const acroformCatalog = objectManager.acroform.finalize(objectManager);
+        if (acroformCatalog)
+            catalogParts.push(acroformCatalog);
         // Named destinations (internal-link targets): a /Dests entry in the shared /Names dict.
-        const destsNames = objectManager.dests.finalize();
+        const destsNames = objectManager.dests.finalize(objectManager);
         if (destsNames)
             namesParts.push(destsNames);
         // Emit the single /Names dict if either embedded files or destinations contributed to it.

package/dist/utils/dest-registry.d.ts

@@ -1,3 +1,4 @@
+import type { PDFObjectManager } from "./pdf-object-manager.js";
 interface Dest {
     pageObjNum: number;
     top: number;
@@ -13,7 +14,9 @@ export declare class DestRegistry {
     add(name: string, dest: Dest): void;
     get isEmpty(): boolean;
     /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
-     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it. */
-    finalize(): string;
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it.
+     *  Takes the object manager only so the names go through its string choke-point and get encrypted
+     *  with everything else. */
+    finalize(om: PDFObjectManager): string;
 }
 export {};

package/dist/utils/dest-registry.js

@@ -1,5 +1,3 @@
-// A PDF literal string escape (backslash first, then the string delimiters).
-const esc = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
 const num = (n) => (Number.isFinite(n) ? Number(n.toFixed(2)) : 0);
 /**
  * Collects named destinations - the jump targets an internal `Link({ to })` points at, declared with
@@ -19,13 +17,15 @@ export class DestRegistry {
         return this.dests.size === 0;
     }
     /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
-     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it. */
-    finalize() {
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it.
+     *  Takes the object manager only so the names go through its string choke-point and get encrypted
+     *  with everything else. */
+    finalize(om) {
         if (this.dests.size === 0)
             return "";
         const entries = [...this.dests.keys()].sort().map((name) => {
             const d = this.dests.get(name);
-            return `(${esc(name)}) [${d.pageObjNum} 0 R /XYZ null ${num(d.top)} null]`;
+            return `${om.pdfString(name)} [${d.pageObjNum} 0 R /XYZ null ${num(d.top)} null]`;
         });
         return `/Dests << /Names [ ${entries.join(" ")} ] >>`;
     }

package/dist/utils/outline.js

@@ -1,5 +1,4 @@
 // A PDF literal string escape (same rule as elsewhere): backslash first, then the string delimiters.
-const esc = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
 const num = (n) => Number(n.toFixed(2));
 /**
  * Builds the PDF document outline (`/Outlines`) - the viewer's bookmark panel. Entries are collected
@@ -52,7 +51,7 @@ export class OutlineBuilder {
         // Emit each item dict, wired to its parent, siblings (prev/next) and first/last child.
         const emit = (nodes, parentNum) => {
             nodes.forEach((n, i) => {
-                const parts = [`/Title (${esc(n.title)})`, `/Parent ${parentNum} 0 R`];
+                const parts = [`/Title ${om.pdfString(n.title)}`, `/Parent ${parentNum} 0 R`];
                 if (i > 0)
                     parts.push(`/Prev ${objOf.get(nodes[i - 1])} 0 R`);
                 if (i < nodes.length - 1)