@jasy/pdf 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/forms/acroform.js

@@ -0,0 +1,427 @@
+import { NORMAL_STYLE, escName, num2, pdfColor } from "./pdf.js";
+import { checkboxOff, checkboxOn, listBoxFace, pushButtonFace, radioOff, radioOn, signatureFace, fieldDrawSize, textFieldFace, wrapFieldValue, } from "./appearance.js";
+// AcroForm field flags (/Ff), by 1-based bit position per the PDF spec.
+const FF_READ_ONLY = 1 << 0; // bit 1
+const FF_REQUIRED = 1 << 1; // bit 2: must be filled in before the form is submitted
+const FF_MULTILINE = 1 << 12; // bit 13 (text)
+const FF_PASSWORD = 1 << 13; // bit 14 (text)
+const FF_NO_TOGGLE_OFF = 1 << 14; // bit 15 (button): clicking the selected radio does not clear it
+const FF_RADIO = 1 << 15; // bit 16 (button): the group's kids are mutually exclusive
+const FF_PUSHBUTTON = 1 << 16; // bit 17 (button): a click target with no value
+const FF_COMBO = 1 << 17; // bit 18 (choice): a dropdown, not a list box
+const FF_EDIT = 1 << 18; // bit 19 (choice): a combo whose value may be typed, not only picked
+const FF_MULTI_SELECT = 1 << 21; // bit 22 (choice): a list box that allows several selections
+/** The `/MK` (appearance characteristics) + `/BS` (border style) shared by every widget: the box border
+ *  colour + fill + width. `extraMK` adds field-specific entries (a push button's `/CA` caption) to the
+ *  SAME /MK dict. Empty when the field has neither a border, a background nor an extra entry. */
+function boxChrome(node, extraMK = "") {
+    const { style } = node;
+    const mk = [];
+    if (extraMK)
+        mk.push(extraMK);
+    if (style.border)
+        mk.push(`/BC [${pdfColor(style.border)}]`);
+    if (style.background)
+        mk.push(`/BG [${pdfColor(style.background)}]`);
+    let out = mk.length ? ` /MK << ${mk.join(" ")} >>` : "";
+    if (style.border && style.borderWidth > 0)
+        out += ` /BS << /W ${num2(style.borderWidth)} /S /S >>`;
+    return out;
+}
+/** The annotation flags (/F). Bit 2 = Hidden, bit 3 = Print. A widget prints by default; `hidden`
+ *  removes it from screen AND print, `print: false` keeps it on screen only. */
+function annotFlags(f) {
+    if (f.hidden)
+        return 2;
+    return f.print === false ? 0 : 4;
+}
+/** The field flags every kind shares. */
+function commonFlags(f) {
+    return (f.readOnly ? FF_READ_ONLY : 0) | (f.required ? FF_REQUIRED : 0);
+}
+/** Quadding (/Q): 0 left (the default, so we omit it), 1 centre, 2 right. */
+function quadding(align) {
+    if (align === "center")
+        return " /Q 1";
+    if (align === "right")
+        return " /Q 2";
+    return "";
+}
+function rectOf(node) {
+    return `[${num2(node.x)} ${num2(node.y)} ${num2(node.x + node.width)} ${num2(node.y + node.height)}]`;
+}
+/** A text field (/Tx). `apRef` is its baked appearance (the default); without one the field carries only
+ *  /DA and the viewer draws the value itself (`fieldAppearances: false`). */
+function buildTextWidget(node, daFont, om, apRef) {
+    const f = node.field;
+    if (f.kind !== "text")
+        throw new Error("buildTextWidget: not a text field");
+    const parts = [`/Type /Annot /Subtype /Widget /FT /Tx`, `/T ${om.pdfString(f.name)}`];
+    if (f.value !== undefined)
+        parts.push(`/V ${om.pdfString(f.value)}`);
+    if (f.tooltip !== undefined)
+        parts.push(`/TU ${om.pdfString(f.tooltip)}`);
+    let flags = commonFlags(f);
+    if (f.multiline)
+        flags |= FF_MULTILINE;
+    if (f.password)
+        flags |= FF_PASSWORD;
+    if (flags)
+        parts.push(`/Ff ${flags}`);
+    if (f.maxLength !== undefined)
+        parts.push(`/MaxLen ${f.maxLength}`);
+    parts.push(`/Rect ${rectOf(node)} /F ${annotFlags(f)}${quadding(f.align)}`);
+    parts.push(`/DA ${om.pdfString(`/${daFont} ${num2(node.style.fontSize)} Tf ${pdfColor(node.style.color)} rg`)}`);
+    if (apRef !== undefined)
+        parts.push(`/AP << /N ${apRef} 0 R >>`);
+    return `<< ${parts.join(" ")}${boxChrome(node)} >>`;
+}
+/** A checkbox (/Btn). Bakes its own /AP appearance streams for the on + off states, so the check is
+ *  visible everywhere (print / headless / PDF-A), not only in viewers that honour /NeedAppearances. */
+function buildCheckboxWidget(node, om) {
+    const f = node.field;
+    if (f.kind !== "checkbox")
+        throw new Error("buildCheckboxWidget: not a checkbox");
+    // Export values become Name tokens, so they are #XX-escaped, not string-escaped.
+    const on = escName(f.onValue ?? "Yes");
+    const state = f.checked ? on : "Off";
+    const bbox = `[0 0 ${num2(node.width)} ${num2(node.height)}]`;
+    // One Form XObject per state; the widget's /AS picks which one shows.
+    const onRef = om.addFormXObject(bbox, checkboxOn(node.width, node.height, node.style));
+    const offRef = om.addFormXObject(bbox, checkboxOff(node.width, node.height, node.style));
+    const parts = [`/Type /Annot /Subtype /Widget /FT /Btn`, `/T ${om.pdfString(f.name)}`];
+    if (f.tooltip !== undefined)
+        parts.push(`/TU ${om.pdfString(f.tooltip)}`);
+    if (commonFlags(f))
+        parts.push(`/Ff ${commonFlags(f)}`);
+    parts.push(`/V /${state} /AS /${state}`);
+    parts.push(`/Rect ${rectOf(node)} /F ${annotFlags(f)}`);
+    parts.push(`/AP << /N << /${on} ${onRef} 0 R /Off ${offRef} 0 R >> >>`);
+    // The check mark lives in ZapfDingbats. We bake the appearance ourselves, so this /DA is only read by
+    // a viewer that REGENERATES (which /NeedAppearances asks for) - but then it needs it, and it needs the
+    // matching /DR entry, or it silently draws an empty box.
+    parts.push(`/DA ${om.pdfString(`/ZaDb 0 Tf ${pdfColor(node.style.color)} rg`)}`);
+    return `<< ${parts.join(" ")}${boxChrome(node)} >>`;
+}
+/** What a choice field has selected. A multi-select box uses `values`; a single-select one uses `value`
+ *  but tolerates a one-entry `values` - the two props are easy to confuse, and silently dropping the
+ *  user's selection is worse than accepting either spelling. */
+function choiceSelection(f) {
+    if (f.multiSelect)
+        return f.values ?? (f.value !== undefined ? [f.value] : []);
+    if (f.value !== undefined)
+        return [f.value];
+    return f.values?.length ? [f.values[0]] : [];
+}
+/** A choice field (/Ch): a dropdown (combo) or list box. `apRef` is its baked appearance (the default);
+ *  without one the viewer draws the selected value from /DA + /V. */
+function buildChoiceWidget(node, daFont, om, apRef) {
+    const f = node.field;
+    if (f.kind !== "choice")
+        throw new Error("buildChoiceWidget: not a choice");
+    // /Opt: each entry is [ (export) (display) ], so a label can differ from the stored value.
+    const opt = f.options
+        .map((o) => `[${om.pdfString(o.value)} ${om.pdfString(o.label ?? o.value)}]`)
+        .join(" ");
+    const parts = [
+        `/Type /Annot /Subtype /Widget /FT /Ch`,
+        `/T ${om.pdfString(f.name)}`,
+        `/Opt [${opt}]`,
+    ];
+    if (f.tooltip !== undefined)
+        parts.push(`/TU ${om.pdfString(f.tooltip)}`);
+    let flags = commonFlags(f);
+    if (f.combo)
+        flags |= FF_COMBO | (f.editable ? FF_EDIT : 0);
+    else if (f.multiSelect)
+        flags |= FF_MULTI_SELECT;
+    if (flags)
+        parts.push(`/Ff ${flags}`);
+    const indexOf = (v) => f.options.findIndex((o) => o.value === v);
+    const chosen = choiceSelection(f);
+    if (chosen.length > 0) {
+        // A multi-select field's value is an ARRAY of strings; every other choice field holds one string.
+        parts.push(f.multiSelect
+            ? `/V [${chosen.map((v) => `${om.pdfString(v)}`).join(" ")}]`
+            : `/V ${om.pdfString(chosen[0])}`);
+        const idx = chosen.map(indexOf).filter((i) => i >= 0);
+        if (idx.length)
+            parts.push(`/I [${idx.join(" ")}]`);
+    }
+    parts.push(`/Rect ${rectOf(node)} /F ${annotFlags(f)}${quadding(f.align)}`);
+    parts.push(`/DA ${om.pdfString(`/${daFont} ${num2(node.style.fontSize)} Tf ${pdfColor(node.style.color)} rg`)}`);
+    if (apRef !== undefined)
+        parts.push(`/AP << /N ${apRef} 0 R >>`);
+    return `<< ${parts.join(" ")}${boxChrome(node)} >>`;
+}
+/** The `/A` action a push button fires. Scripted actions are deliberately not offered. */
+function actionDict(a, om) {
+    switch (a.kind) {
+        case "reset":
+            return `/A << /S /ResetForm >>`;
+        case "submit":
+            // /Flags 4 = ExportFormat: post the field values as HTML form data rather than FDF, which is what
+            // an ordinary web endpoint expects.
+            return `/A << /S /SubmitForm /F << /FS /URL /F ${om.pdfString(a.url)} >> /Flags 4 >>`;
+        case "url":
+            return `/A << /S /URI /URI ${om.pdfString(a.url)} >>`;
+    }
+}
+/**
+ * Collects the document's form fields as pages render, then emits the catalog `/AcroForm` dictionary at
+ * finalize. Mirrors `OutlineBuilder` / `DestRegistry`: a no-op returning "" when no field was placed, so
+ * a document without a form stays byte-identical.
+ */
+export class AcroFormCollector {
+    constructor() {
+        this.fieldRefs = [];
+        this.radioGroups = new Map();
+        // Only set when appearance baking is OFF - then the viewer has to draw every value. With baking on
+        // (the default) it stays absent, which is also what PDF/A requires.
+        this.needAppearances = false;
+        // Set once a signature field exists; the catalog then needs /SigFlags.
+        this.hasSignature = false;
+        // Field name -> its kind, so a collision can say WHAT collided.
+        this.usedNames = new Map();
+        // Bake every field's appearance (default). Off = emit no /AP and set /NeedAppearances, i.e. let the
+        // viewer draw everything - what react-pdf/pdfkit always does, and what we did before this step.
+        this.bake = true;
+    }
+    /** Turn appearance baking off (`renderToBytes(doc, { fieldAppearances: false })`). */
+    setBakeAppearances(on) {
+        this.bake = on;
+    }
+    /** The size to draw a value at. A field may ask for `0` - the PDF convention for "auto-size"; we then
+     *  fit the capitals comfortably inside the box, which is what a viewer's auto-size does. */
+    drawSize(style, height, capHeight) {
+        return fieldDrawSize(style.fontSize, height, style.borderWidth, capHeight);
+    }
+    /** Measure one line for the appearance generator. */
+    line(om, text, size) {
+        return { text, width: om.getStringWidth(text, "Helvetica", size, NORMAL_STYLE) };
+    }
+    /** Bake a text field's value into an appearance stream; returns the XObject number. */
+    bakeText(node, om) {
+        const f = node.field;
+        if (f.kind !== "text")
+            throw new Error("bakeText: not a text field");
+        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const size = this.drawSize(node.style, node.height, capHeight);
+        // A password field shows the mask, never the characters - the value still lives in /V.
+        const value = f.password ? "•".repeat([...(f.value ?? "")].length) : (f.value ?? "");
+        const innerWidth = Math.max(1, node.width - 2 * (2 + node.style.borderWidth));
+        let lines = [];
+        if (value) {
+            const texts = wrapFieldValue(value, "Helvetica", size, NORMAL_STYLE, innerWidth, om, f.multiline ?? false);
+            lines = texts.map((t) => this.line(om, t, size));
+        }
+        const face = textFieldFace(node.width, node.height, node.style, lines, capHeight, size, "Helv", f.multiline ?? false, f.align);
+        return om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, `/Font << /Helv ${this.helv(om)} 0 R >>`);
+    }
+    /** Bake a choice field: a combo shows its current value on one line, a list box shows its options
+     *  with the selected rows highlighted. */
+    bakeChoice(node, om) {
+        const f = node.field;
+        if (f.kind !== "choice")
+            throw new Error("bakeChoice: not a choice");
+        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const size = this.drawSize(node.style, node.height, capHeight);
+        const shown = (v) => f.options.find((o) => o.value === v)?.label ?? v;
+        const chosen = choiceSelection(f);
+        const selected = new Set(chosen);
+        let face;
+        if (f.combo) {
+            const current = chosen.length ? [this.line(om, shown(chosen[0]), size)] : [];
+            face = textFieldFace(node.width, node.height, node.style, current, capHeight, size, "Helv", false, f.align);
+        }
+        else {
+            const rows = f.options.map((o) => ({
+                ...this.line(om, o.label ?? o.value, size),
+                selected: selected.has(o.value),
+            }));
+            face = listBoxFace(node.width, node.height, node.style, rows, capHeight, size, "Helv", f.align);
+        }
+        return om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, `/Font << /Helv ${this.helv(om)} 0 R >>`);
+    }
+    get isEmpty() {
+        return this.fieldRefs.length === 0;
+    }
+    helv(om) {
+        return (this.helvNum ?? (this.helvNum = om.addObject(`<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>`)));
+    }
+    /**
+     * ZapfDingbats, the font a check mark lives in. Needed even though we bake the appearance ourselves:
+     * a viewer told to regenerate (`/NeedAppearances`, which filling a form sets) redraws a check box from
+     * its `/DA`, and the conventional `/DA` for one names `/ZaDb`. Without the matching `/DR` entry the
+     * viewer cannot resolve the font - poppler says "Unknown font tag 'ZaDb'" and draws no check at all.
+     * No encoding: ZapfDingbats brings its own.
+     */
+    zadb(om) {
+        return (this.zadbNum ?? (this.zadbNum = om.addObject(`<< /Type /Font /Subtype /Type1 /BaseFont /ZapfDingbats >>`)));
+    }
+    /**
+     * A field name is its identity: two fields sharing one are ONE field to every viewer, showing the same
+     * value in both places and overwriting each other as the reader types. The format allows it and says
+     * nothing, so the mistake surfaces only when someone fills the form. Named here instead.
+     *
+     * A radio GROUP is the exception - its buttons deliberately share a name, which is what makes them
+     * mutually exclusive - so it never comes through here.
+     */
+    claimName(name, kind) {
+        const taken = this.usedNames.get(name);
+        if (taken !== undefined) {
+            throw new Error(`@jasy/pdf: two form fields are called "${name}" (a ${taken} and a ${kind}). A name is a field's ` +
+                "identity - a viewer would treat them as one field and show the same value in both places. " +
+                "Give them different names, or use a RadioGroup if they are meant to belong together.");
+        }
+        this.usedNames.set(name, kind);
+    }
+    /** Emit the widget object for one form-field IR node, register it as a field, and return its object
+     *  number so the PageRenderer can add it to that page's /Annots. */
+    addField(node, om) {
+        if (node.field.kind === "radio")
+            return this.addRadio(node, om);
+        this.claimName(node.field.name, node.field.kind);
+        let dict;
+        if (node.field.kind === "checkbox") {
+            this.zadb(om); // its /DA names /ZaDb, so /DR has to carry it
+            dict = buildCheckboxWidget(node, om);
+        }
+        else if (node.field.kind === "pushbutton") {
+            dict = this.buildPushButtonWidget(node, om);
+        }
+        else if (node.field.kind === "signature") {
+            dict = this.buildSignatureWidget(node, om);
+        }
+        else if (node.field.kind === "choice") {
+            this.helv(om);
+            dict = buildChoiceWidget(node, "Helv", om, this.bake ? this.bakeChoice(node, om) : undefined);
+            // Only text and choice depend on the flag; the other kinds always carry a complete appearance,
+            // so a document of checkboxes alone must not ask the viewer to redraw anything.
+            if (!this.bake)
+                this.needAppearances = true;
+        }
+        else {
+            this.helv(om);
+            dict = buildTextWidget(node, "Helv", om, this.bake ? this.bakeText(node, om) : undefined);
+            if (!this.bake)
+                this.needAppearances = true;
+        }
+        const objNum = om.addObject(dict);
+        this.fieldRefs.push(objNum);
+        return objNum;
+    }
+    /** A push button (/Btn, Pushbutton flag): no value, an optional action, and a baked caption. The
+     *  caption is measured here (the appearance module stays free of font metrics) and drawn into an
+     *  appearance stream that carries its own font resource. */
+    buildPushButtonWidget(node, om) {
+        const f = node.field;
+        if (f.kind !== "pushbutton")
+            throw new Error("buildPushButtonWidget: not a push button");
+        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        // `fontSize: 0` means auto-size, here as everywhere: resolve it before measuring or drawing.
+        const size = this.drawSize(node.style, node.height, capHeight);
+        const width = om.getStringWidth(f.label, "Helvetica", size, NORMAL_STYLE);
+        const fontNum = this.helv(om);
+        const face = pushButtonFace(node.width, node.height, node.style, f.label, width, capHeight, "Helv", size);
+        const apRef = om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, face, `/Font << /Helv ${fontNum} 0 R >>`);
+        const parts = [`/Type /Annot /Subtype /Widget /FT /Btn`, `/T ${om.pdfString(f.name)}`];
+        if (f.tooltip !== undefined)
+            parts.push(`/TU ${om.pdfString(f.tooltip)}`);
+        parts.push(`/Ff ${FF_PUSHBUTTON | commonFlags(f)}`);
+        parts.push(`/Rect ${rectOf(node)} /F ${annotFlags(f)}`);
+        // /DA as well as the baked /AP: a viewer that REGENERATES the face (poppler does this for push
+        // buttons; others do it while the button is pressed) needs the font + size + colour, or it draws the
+        // box with no caption. With /DA it reproduces what we baked.
+        parts.push(`/DA ${om.pdfString(`/Helv ${num2(size)} Tf ${pdfColor(node.style.color)} rg`)}`);
+        parts.push(`/AP << /N ${apRef} 0 R >>`);
+        if (f.action)
+            parts.push(actionDict(f.action, om));
+        // /MK /CA is the caption the viewer falls back to when IT regenerates the face (e.g. while pressed).
+        return `<< ${parts.join(" ")}${boxChrome(node, `/CA ${om.pdfString(f.label)}`)} >>`;
+    }
+    /** A radio button: one KID widget of its group's shared field. The group field is reserved on first
+     *  sight (and added to /Fields); each button adds itself to that field's /Kids. Returns the kid widget
+     *  number, which goes into the PAGE /Annots (the parent field does not). */
+    addRadio(node, om) {
+        const f = node.field;
+        if (f.kind !== "radio")
+            throw new Error("addRadio: not a radio");
+        let g = this.radioGroups.get(f.group);
+        if (!g) {
+            // Claimed ONCE, when the group comes into being: its buttons share the name deliberately, but the
+            // group as a whole still has to collide with a text field of the same name like any other field.
+            // A SECOND RadioGroup of the same name therefore joins this one rather than colliding - that is
+            // how the buttons of one question are placed in two different spots and stay exclusive.
+            this.claimName(f.group, "radio group");
+            g = { parentNum: om.addObject(""), kids: [], flags: 0 };
+            this.radioGroups.set(f.group, g);
+            this.fieldRefs.push(g.parentNum);
+        }
+        // The flags live on the shared field, so every button contributes: marking any one of them
+        // required (or read-only) applies to the group.
+        g.flags |= commonFlags(f);
+        if (f.selected)
+            g.selected = f.value;
+        const bbox = `[0 0 ${num2(node.width)} ${num2(node.height)}]`;
+        const onRef = om.addFormXObject(bbox, radioOn(node.width, node.height, node.style));
+        const offRef = om.addFormXObject(bbox, radioOff(node.width, node.height, node.style));
+        const as = f.selected ? f.value : "Off";
+        this.zadb(om); // same as a check box: a regenerating viewer draws the dot from /DA + /DR
+        const parts = [
+            `/Type /Annot /Subtype /Widget /Parent ${g.parentNum} 0 R`,
+            `/Rect ${rectOf(node)} /F ${annotFlags(f)}`,
+            `/AP << /N << /${escName(f.value)} ${onRef} 0 R /Off ${offRef} 0 R >> >>`,
+            `/AS /${escName(as)}`,
+            `/DA ${om.pdfString(`/ZaDb 0 Tf ${pdfColor(node.style.color)} rg`)}`,
+        ];
+        const kidNum = om.addObject(`<< ${parts.join(" ")}${boxChrome(node)} >>`);
+        g.kids.push(kidNum);
+        return kidNum;
+    }
+    /** A signature field (/Sig): an EMPTY placeholder with a baked "sign here" face. No /V - an unsigned
+     *  field has no value; a signing tool fills that in (and replaces this appearance) later. */
+    buildSignatureWidget(node, om) {
+        const f = node.field;
+        if (f.kind !== "signature")
+            throw new Error("buildSignatureWidget: not a signature");
+        this.hasSignature = true;
+        const label = f.label ?? "";
+        const { capHeight } = om.getFontDecoration("Helvetica", NORMAL_STYLE);
+        const size = this.drawSize(node.style, node.height, capHeight);
+        const labelWidth = label ? om.getStringWidth(label, "Helvetica", size, NORMAL_STYLE) : 0;
+        const fontNum = this.helv(om);
+        const apRef = om.addFormXObject(`[0 0 ${num2(node.width)} ${num2(node.height)}]`, signatureFace(node.width, node.height, node.style, label, labelWidth, "Helv", size), `/Font << /Helv ${fontNum} 0 R >>`);
+        const parts = [`/Type /Annot /Subtype /Widget /FT /Sig`, `/T ${om.pdfString(f.name)}`];
+        if (f.tooltip !== undefined)
+            parts.push(`/TU ${om.pdfString(f.tooltip)}`);
+        if (commonFlags(f))
+            parts.push(`/Ff ${commonFlags(f)}`);
+        parts.push(`/Rect ${rectOf(node)} /F ${annotFlags(f)}`);
+        parts.push(`/AP << /N ${apRef} 0 R >>`);
+        return `<< ${parts.join(" ")}${boxChrome(node)} >>`;
+    }
+    finalize(om) {
+        // Fill each reserved radio-group field now that all its buttons (Kids) are known.
+        for (const [name, g] of this.radioGroups) {
+            const kids = g.kids.map((k) => `${k} 0 R`).join(" ");
+            const ff = FF_RADIO | FF_NO_TOGGLE_OFF | g.flags;
+            om.replaceObject(g.parentNum, `<< /FT /Btn /Ff ${ff} /T ${om.pdfString(name)} /V /${escName(g.selected ?? "Off")} /Kids [${kids}] >>`);
+        }
+        if (this.fieldRefs.length === 0)
+            return "";
+        const fields = this.fieldRefs.map((r) => `${r} 0 R`).join(" ");
+        // /DR only lists the fonts a field's /DA actually references: /Helv for text, choice and button
+        // captions, /ZaDb for the check mark of a box or radio button.
+        const fonts = [
+            this.helvNum ? `/Helv ${this.helvNum} 0 R` : "",
+            this.zadbNum ? `/ZaDb ${this.zadbNum} 0 R` : "",
+        ].filter(Boolean);
+        const dr = fonts.length ? ` /DR << /Font << ${fonts.join(" ")} >> >>` : "";
+        const na = this.needAppearances ? " /NeedAppearances true" : "";
+        // /SigFlags 3 = SignaturesExist | AppendOnly: the document holds a signature field, and it must be
+        // updated incrementally so an existing signature stays verifiable.
+        const sig = this.hasSignature ? " /SigFlags 3" : "";
+        return `/AcroForm << /Fields [${fields}]${dr}${na}${sig} >>`;
+    }
+}

package/dist/forms/appearance.d.ts

@@ -0,0 +1,58 @@
+import type { FieldAlign, FieldStyle } from "./field.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+/** The unchecked appearance: just the box. */
+export declare function checkboxOff(w: number, h: number, style: FieldStyle): string;
+/** The checked appearance: the box plus a vector checkmark (font-free, so it renders everywhere). */
+export declare function checkboxOn(w: number, h: number, style: FieldStyle): string;
+/** An unselected radio button: just the ring. */
+export declare function radioOff(w: number, h: number, style: FieldStyle): string;
+/** A selected radio button: the ring plus a filled inner dot. */
+export declare function radioOn(w: number, h: number, style: FieldStyle): string;
+/**
+ * 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 declare function pushButtonFace(w: number, h: number, style: FieldStyle, caption: string, captionWidth: number, capHeight: number, fontRes: string, size: number): string;
+/**
+ * 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 declare function signatureFace(w: number, h: number, style: FieldStyle, label: string, labelWidth: number, fontRes: string, size: number): string;
+/** 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 declare function wrapFieldValue(value: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, multiline: boolean): string[];
+/**
+ * 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 declare function fieldDrawSize(fontSize: number, height: number, borderWidth: number, capHeight: number): number;
+export interface FieldLine {
+    text: string;
+    width: number;
+    /** List box only: draw a selection highlight behind this row. */
+    selected?: boolean;
+}
+/**
+ * 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 declare function textFieldFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, fontRes: string, multiline: boolean, align?: FieldAlign): string;
+/**
+ * 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 declare function listBoxFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, fontRes: string, align?: FieldAlign): string;