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

package/dist/crypto/legacy-handler.js

@@ -0,0 +1,145 @@
+import { aesCbcDecrypt } from "./webcrypto.js";
+import { md5 } from "../utils/md5.js";
+/**
+ * The OLDER standard security handlers, for READING only: R2 and R3 (RC4, 40 and 128 bit) and R4
+ * (RC4 or AES-128).
+ *
+ * Read-only is a deliberate asymmetry, not an omission. RC4 is broken - biased keystream, and R2 uses a
+ * 40-bit key that is brute-forced in minutes - and PDF 2.0 removed it outright. But it is what PDFKit,
+ * react-pdf and Ghostscript still produce BY DEFAULT when you ask them for a password, so refusing to
+ * open such a file means refusing most of the encrypted PDFs anyone actually has. Writing one would be
+ * a different matter: offering a user "protection" we know to be broken helps nobody, so `encrypt`
+ * here throws.
+ *
+ * Two things distinguish these revisions from the modern R6:
+ * - the file key comes from MD5 over the password, `/O`, `/P` and the first `/ID` string (algorithm 2);
+ * - every object gets its OWN key, derived from the file key plus its number and generation
+ *   (algorithm 1). That is why `SecurityHandler.encrypt/decrypt` take a `ref`.
+ */
+/** The padding every legacy revision prepends to a password (algorithm 2, step a). */
+const PAD = new Uint8Array([
+    0x28, 0xbf, 0x4e, 0x5e, 0x4e, 0x75, 0x8a, 0x41, 0x64, 0x00, 0x4e, 0x56, 0xff, 0xfa, 0x01, 0x08,
+    0x2e, 0x2e, 0x00, 0xb6, 0xd0, 0x68, 0x3e, 0x80, 0x2f, 0x0c, 0xa9, 0xfe, 0x64, 0x53, 0x69, 0x7a,
+]);
+/** A password padded (or truncated) to the 32 bytes the algorithm wants. */
+function padPassword(password) {
+    const pw = new Uint8Array(32);
+    // Latin-1: the legacy handlers predate unicode passwords entirely.
+    const raw = Uint8Array.from(password, (c) => c.charCodeAt(0) & 0xff);
+    const take = Math.min(raw.length, 32);
+    pw.set(raw.subarray(0, take), 0);
+    pw.set(PAD.subarray(0, 32 - take), take);
+    return pw;
+}
+/** RC4. Not available in WebCrypto - for good reasons - so it is written out here, for reading only. */
+function rc4(key, data) {
+    const s = new Uint8Array(256);
+    for (let i = 0; i < 256; i++)
+        s[i] = i;
+    for (let i = 0, j = 0; i < 256; i++) {
+        j = (j + s[i] + key[i % key.length]) & 0xff;
+        [s[i], s[j]] = [s[j], s[i]];
+    }
+    const out = new Uint8Array(data.length);
+    for (let k = 0, i = 0, j = 0; k < data.length; k++) {
+        i = (i + 1) & 0xff;
+        j = (j + s[i]) & 0xff;
+        [s[i], s[j]] = [s[j], s[i]];
+        out[k] = data[k] ^ s[(s[i] + s[j]) & 0xff];
+    }
+    return out;
+}
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+};
+export class StandardLegacy {
+    constructor(fileKey, aes) {
+        this.fileKey = fileKey;
+        this.aes = aes;
+        this.canEncrypt = false;
+    }
+    encryptDict() {
+        throw new Error("@jasy/pdf: this handler only READS legacy encryption; jasy writes AES-256 (R6) exclusively");
+    }
+    async encrypt() {
+        throw new Error("@jasy/pdf: refusing to write RC4 or AES-128 - they are obsolete; jasy writes AES-256 (R6)");
+    }
+    async decrypt(data, ref) {
+        const key = this.objectKey(ref);
+        if (!this.aes)
+            return rc4(key, data);
+        if (data.length <= 16)
+            return new Uint8Array(0); // an IV and nothing else
+        return aesCbcDecrypt(key, data.subarray(0, 16), data.subarray(16));
+    }
+    /**
+     * Algorithm 1: every object is enciphered with its own key, derived from the file key plus the
+     * object's number and generation. Miss this and every single object decrypts to noise.
+     */
+    objectKey(ref) {
+        const num = ref?.num ?? 0;
+        const gen = ref?.gen ?? 0;
+        const extra = new Uint8Array(this.aes ? 9 : 5);
+        extra[0] = num & 0xff;
+        extra[1] = (num >> 8) & 0xff;
+        extra[2] = (num >> 16) & 0xff;
+        extra[3] = gen & 0xff;
+        extra[4] = (gen >> 8) & 0xff;
+        // AES adds the literal "sAlT" - the spec really does spell it that way.
+        if (this.aes)
+            extra.set([0x73, 0x41, 0x6c, 0x54], 5);
+        const digest = md5(concat(this.fileKey, extra));
+        return digest.subarray(0, Math.min(this.fileKey.length + 5, 16));
+    }
+    /**
+     * Open a legacy-encrypted document: derive the file key from the password (algorithm 2), then CHECK it
+     * against `/U` (algorithm 6) so a wrong password is rejected rather than silently producing noise.
+     */
+    static open(password, info) {
+        const keyLength = info.revision === 2 ? 5 : Math.max(5, Math.floor(info.keyBits / 8));
+        const p = new Uint8Array(4);
+        new DataView(p.buffer).setInt32(0, info.permissions, true); // little-endian, signed
+        let input = concat(padPassword(password), info.o.subarray(0, 32), p, info.id);
+        // R4 with /EncryptMetadata false folds in four 0xFF bytes.
+        if (info.revision >= 4 && !info.encryptMetadata) {
+            input = concat(input, new Uint8Array([0xff, 0xff, 0xff, 0xff]));
+        }
+        let key = md5(input);
+        if (info.revision >= 3) {
+            // 50 further rounds over the first keyLength bytes only.
+            for (let i = 0; i < 50; i++)
+                key = md5(key.subarray(0, keyLength));
+        }
+        key = key.subarray(0, keyLength);
+        if (!StandardLegacy.passwordMatches(key, info)) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        return new StandardLegacy(key, info.aes);
+    }
+    /** Algorithm 6: rebuild what `/U` must look like for this key and compare. */
+    static passwordMatches(key, info) {
+        if (info.revision === 2) {
+            const expect = rc4(key, PAD);
+            return expect.every((b, i) => b === info.u[i]);
+        }
+        // R3+ : MD5 over the padding and the /ID, then 20 rounds of RC4 with the key XORed by the round.
+        let x = md5(concat(PAD, info.id));
+        x = rc4(key, x);
+        for (let round = 1; round <= 19; round++) {
+            const rk = Uint8Array.from(key, (b) => b ^ round);
+            x = rc4(rk, x);
+        }
+        // Only the first 16 bytes are meaningful; the rest of /U is arbitrary padding.
+        for (let i = 0; i < 16; i++)
+            if (x[i] !== info.u[i])
+                return false;
+        return true;
+    }
+}
+export { rc4 };

package/dist/crypto/security-handler.d.ts

@@ -1,5 +1,8 @@
 /** A handler encrypts/decrypts the strings + streams of a document and describes itself as an `/Encrypt` dict. */
 export interface SecurityHandler {
+    /** Whether this scheme may be WRITTEN. False for the legacy revisions: we open them as a service to
+     *  files that already exist, but handing a user protection known to be broken is not one. */
+    readonly canEncrypt: boolean;
     /** The `/Encrypt` dictionary body (between `<<` and `>>`). Its own strings are never encrypted. */
     encryptDict(): string;
     /** Encrypt one string/stream. `ref` is unused for V5/R6 (one file key) but kept for future per-object schemes. */
@@ -33,6 +36,7 @@ declare class StandardAes256 implements SecurityHandler {
     private readonly dict;
     private constructor();
     static create(opts: EncryptOptions): Promise<StandardAes256>;
+    readonly canEncrypt = true;
     encryptDict(): string;
     encrypt(data: Uint8Array): Promise<Uint8Array>;
     decrypt(data: Uint8Array): Promise<Uint8Array>;
@@ -40,6 +44,18 @@ declare class StandardAes256 implements SecurityHandler {
      *  password is rejected, not silently turned into a garbage key), then decrypt /UE. The groundwork the
      *  future "open/edit existing PDF" path reuses. Throws on a wrong password. */
     static recoverFileKey(userPassword: string, u: Uint8Array, ue: Uint8Array): Promise<Uint8Array>;
+    /**
+     * A handler for READING an existing file: recover its key from the password, then decrypt with it.
+     * The `/Encrypt` dictionary is the file's own, so this handler never has to describe one.
+     *
+     * `revision` 6 is the standard (ISO 32000-2). Revision **5** is Adobe's withdrawn 2008 extension and
+     * differs in ONE respect: the key is a plain SHA-256 of password + salt, without the iterated
+     * procedure of algorithm 2.B. The cipher is the same AES-256, which is why supporting it costs almost
+     * nothing - and it matters, because PDFKit and react-pdf both emit R5 when asked for AES.
+     */
+    static forReading(userPassword: string, u: Uint8Array, ue: Uint8Array, revision?: 5 | 6): Promise<SecurityHandler>;
+    /** Revision 5: validate against /U with a single SHA-256, then unwrap /UE the same way R6 does. */
+    private static recoverFileKeyR5;
 }
 /** The factory = the seam. Today it always returns the AES-256 handler. */
 export declare function createSecurityHandler(opts: EncryptOptions): Promise<SecurityHandler>;

package/dist/crypto/security-handler.js

@@ -59,6 +59,7 @@ class StandardAes256 {
     constructor(fileKey, dict) {
         this.fileKey = fileKey;
         this.dict = dict;
+        this.canEncrypt = true;
     }
     static async create(opts) {
         const user = utf8(opts.userPassword);
@@ -118,6 +119,31 @@ class StandardAes256 {
         const intermediate = await hash2B(pw, u.subarray(40, 48), new Uint8Array(0));
         return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
     }
+    /**
+     * A handler for READING an existing file: recover its key from the password, then decrypt with it.
+     * The `/Encrypt` dictionary is the file's own, so this handler never has to describe one.
+     *
+     * `revision` 6 is the standard (ISO 32000-2). Revision **5** is Adobe's withdrawn 2008 extension and
+     * differs in ONE respect: the key is a plain SHA-256 of password + salt, without the iterated
+     * procedure of algorithm 2.B. The cipher is the same AES-256, which is why supporting it costs almost
+     * nothing - and it matters, because PDFKit and react-pdf both emit R5 when asked for AES.
+     */
+    static async forReading(userPassword, u, ue, revision = 6) {
+        const key = revision === 6
+            ? await StandardAes256.recoverFileKey(userPassword, u, ue)
+            : await StandardAes256.recoverFileKeyR5(userPassword, u, ue);
+        return new StandardAes256(key, "");
+    }
+    /** Revision 5: validate against /U with a single SHA-256, then unwrap /UE the same way R6 does. */
+    static async recoverFileKeyR5(userPassword, u, ue) {
+        const pw = utf8(userPassword);
+        const check = await sha(256, concat(pw, u.subarray(32, 40)));
+        if (!bytesEqual(check, u.subarray(0, 32))) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        const intermediate = await sha(256, concat(pw, u.subarray(40, 48)));
+        return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
+    }
 }
 /** The factory = the seam. Today it always returns the AES-256 handler. */
 export async function createSecurityHandler(opts) {

package/dist/edit/acroform-reader.d.ts

@@ -0,0 +1,70 @@
+import { type PdfDocument } from "./document.js";
+/**
+ * Reads an existing document's `/AcroForm` into a flat list of fields.
+ *
+ * The field tree is the part every producer lays out differently, and where a naive reader goes wrong:
+ *
+ * - **A field and its widget need not be the same object.** pdf-lib splits them (the field carries
+ *   `/T`, `/FT` and `/V`; its `/Kids` are bare widget annotations); PDFKit and our own writer merge
+ *   them into one. Both are legal, so the walk must cope with either.
+ * - **Attributes are inherited.** `/FT`, `/Ff`, `/V` and `/MaxLen` all pass down the tree, so a child may
+ *   state none of them and still have a type, flags and a value (ISO 32000-1 table 220).
+ * - **Names are hierarchical.** The name you address a field by is the `/T` values along the path,
+ *   joined with dots - `address.street`, not `street`.
+ * - **A field may own several widgets** (a radio group, or one field shown on several pages). It is
+ *   still ONE field with one value.
+ */
+/** One field found in an existing document, in the terms a caller thinks in. */
+export interface ReadField {
+    /** The fully qualified name: the `/T` values from the root down, joined with dots. */
+    name: string;
+    /** `Tx` text · `Btn` button (check box, radio, push button) · `Ch` choice · `Sig` signature. */
+    type: "Tx" | "Btn" | "Ch" | "Sig";
+    /** The current value as text, if it has one. A button's value is a name (`Yes`, `Off`). */
+    value?: string;
+    /** A multi-select choice field's values. */
+    values?: string[];
+    /** The `/Ff` field flags, already merged with anything inherited. */
+    flags: number;
+    /** `/MaxLen`: the longest text the field accepts, in characters. Inherited like the type. */
+    maxLen?: number;
+    /** The selectable options of a choice field, as `[export, label]`. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** For a check box or radio group: every export name its widgets can take, besides `Off`. */
+    onValues?: string[];
+    /** The object number of the FIELD dictionary - where `/V` lives, and what an update rewrites. */
+    objNum?: number;
+    /** The widgets that display this field. A radio group has one per button, and each knows only its
+     *  OWN export name, which is what its `/AS` has to be set to. */
+    widgets: ReadWidget[];
+    /** True when no widget carries an appearance stream - filling it means generating one. */
+    needsAppearance: boolean;
+}
+/** One widget annotation belonging to a field. */
+export interface ReadWidget {
+    num?: number;
+    /** The export names this particular widget can show (its `/AP /N` keys, minus `Off`). */
+    onValues: string[];
+    hasAppearance: boolean;
+}
+/** What a document says about its form as a whole. */
+export interface ReadForm {
+    fields: ReadField[];
+    /** The form asks viewers to regenerate every appearance. */
+    needAppearances: boolean;
+    /**
+     * The document carries an XFA packet beside the AcroForm (a "hybrid" form). Filling only the AcroForm
+     * side can be ignored by a viewer that prefers XFA, so this is reported rather than glossed over.
+     */
+    hasXfa: boolean;
+    /** True when the cross-reference table had to be rebuilt to read the file at all. */
+    recovered: boolean;
+}
+/**
+ * Read the form of a loaded document. Returns `undefined` when there is no `/AcroForm` at all - that is
+ * a plain PDF, not an error.
+ */
+export declare function readAcroForm(doc: PdfDocument): ReadForm | undefined;

package/dist/edit/acroform-reader.js

@@ -0,0 +1,126 @@
+import { PdfEncryptedError } from "./document.js";
+import { get, isDict, isRef, nameOf, numberOf, textOf } from "./objects.js";
+const FIELD_TYPES = new Set(["Tx", "Btn", "Ch", "Sig"]);
+/** Join a parent's qualified name with a child's partial name. */
+const joinName = (parent, part) => part === undefined || part === "" ? parent : parent === "" ? part : `${parent}.${part}`;
+/** `/Opt` entries are either a bare string or a `[export, label]` pair. */
+function readOptions(doc, raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.map((entry) => {
+        const e = doc.resolve(entry);
+        if (Array.isArray(e)) {
+            const value = textOf(doc.resolve(e[0])) ?? "";
+            return { value, label: textOf(doc.resolve(e[1])) ?? value };
+        }
+        const value = textOf(e) ?? "";
+        return { value, label: value };
+    });
+}
+/** A value that may be a single string/name or an array of them (a multi-select choice). */
+function readValue(doc, raw) {
+    const v = doc.resolve(raw);
+    if (Array.isArray(v)) {
+        const values = v.map((x) => textOf(doc.resolve(x)) ?? nameOf(doc.resolve(x)) ?? "");
+        return { value: values[0], values };
+    }
+    const single = textOf(v) ?? nameOf(v);
+    return { value: single, values: undefined };
+}
+/** The export names a button widget can show, read from the keys of its `/AP /N` state dictionary. */
+function readOnValues(doc, widget) {
+    const normal = doc.resolve(get(doc.resolve(get(widget, "AP")), "N"));
+    if (normal === undefined || !isDict(normal))
+        return [];
+    return [...normal.map.keys()].filter((k) => k !== "Off");
+}
+/**
+ * Read the form of a loaded document. Returns `undefined` when there is no `/AcroForm` at all - that is
+ * a plain PDF, not an error.
+ */
+export function readAcroForm(doc) {
+    // Until the password has been accepted, every string in an encrypted file is still ciphertext, so a
+    // field "name" read out of it is noise. Handing that back would be the silent guess this reader exists
+    // to avoid. `PdfDocument.open(bytes, { password })` is what makes it readable.
+    if (!doc.isReadable) {
+        throw new PdfEncryptedError("this PDF is encrypted; open it with PdfDocument.open(bytes, { password }) first");
+    }
+    const acro = doc.lookup(doc.catalog, "AcroForm");
+    if (acro === undefined || !isDict(acro))
+        return undefined;
+    const roots = doc.resolve(get(acro, "Fields"));
+    const fields = [];
+    if (Array.isArray(roots)) {
+        for (const ref of roots)
+            walk(doc, ref, "", { type: undefined, flags: 0, maxLen: undefined, value: undefined }, fields, 0);
+    }
+    return {
+        fields,
+        needAppearances: doc.resolve(get(acro, "NeedAppearances")) === true,
+        hasXfa: get(acro, "XFA") !== undefined,
+        recovered: doc.recovered,
+    };
+}
+/**
+ * Walk one node of the field tree. A node is a FIELD when it has a type (its own or inherited); its
+ * `/Kids` are either more fields or the widgets that display it. The two are told apart by the kids
+ * themselves: a widget has no `/T` and no `/FT` of its own.
+ */
+function walk(doc, ref, parentName, parent, out, depth) {
+    if (depth > 32)
+        return; // a cyclic file must not hang us
+    const node = doc.resolve(ref);
+    if (node === undefined || !isDict(node))
+        return;
+    const name = joinName(parentName, textOf(doc.lookup(node, "T")));
+    const type = nameOf(doc.lookup(node, "FT")) ?? parent.type;
+    const flags = numberOf(doc.lookup(node, "Ff")) ?? parent.flags;
+    const maxLen = numberOf(doc.lookup(node, "MaxLen")) ?? parent.maxLen;
+    const rawValue = get(node, "V") ?? parent.value;
+    const kidsRaw = doc.lookup(node, "Kids");
+    const kids = Array.isArray(kidsRaw) ? kidsRaw : [];
+    // Kids that are themselves fields (they name themselves or state a type) mean this node is only a
+    // branch; otherwise the kids are this field's widget annotations.
+    const childFields = kids.filter((k) => {
+        const kid = doc.resolve(k);
+        return get(kid, "T") !== undefined || get(kid, "FT") !== undefined;
+    });
+    if (childFields.length > 0) {
+        for (const k of childFields)
+            walk(doc, k, name, { type, flags, maxLen, value: rawValue }, out, depth + 1);
+        return;
+    }
+    if (type === undefined || !FIELD_TYPES.has(type))
+        return;
+    // The widgets: either the kids, or this very object when field and widget are merged.
+    const widgetRefs = kids.length > 0 ? kids : [ref];
+    const widgets = widgetRefs.map((w) => doc.resolve(w));
+    const readWidgets = widgetRefs.map((w, i) => ({
+        num: isRef(w) ? w.num : undefined,
+        onValues: type === "Btn" ? readOnValues(doc, widgets[i]) : [],
+        hasAppearance: get(widgets[i], "AP") !== undefined,
+    }));
+    let { value, values } = readValue(doc, rawValue);
+    const onValues = type === "Btn" ? [...new Set(readWidgets.flatMap((w) => w.onValues))] : undefined;
+    // A button's value is a NAME by spec (`/Yes`), and that is what its `/AP` state keys are. Producers
+    // disagree: PDFKit writes the string `(Yes)`, react-pdf the string `(/Yes)`. All three mean the same
+    // export value, so the leading slash is dropped - otherwise comparing a value against the appearance
+    // states, which is exactly what filling does, would silently never match.
+    if (type === "Btn" && value !== undefined && value.startsWith("/"))
+        value = value.slice(1);
+    out.push({
+        name,
+        type: type,
+        value,
+        values,
+        flags,
+        maxLen,
+        options: readOptions(doc, doc.lookup(node, "Opt")),
+        onValues: onValues && onValues.length > 0 ? onValues : undefined,
+        objNum: isRef(ref) ? ref.num : undefined,
+        widgets: readWidgets,
+        // Only meaningful when we know where the widgets are; a field whose widgets all lack /AP has to
+        // have one generated before its value can be seen.
+        needsAppearance: readWidgets.every((w) => !w.hasAppearance),
+    });
+}

package/dist/edit/appearance.d.ts

@@ -0,0 +1,47 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import type { FieldAlign, FieldStyle } from "../forms/field.js";
+import type { PdfDocument } from "./document.js";
+import type { ReadField } from "./acroform-reader.js";
+import { type PdfObject } from "./objects.js";
+/**
+ * Font metrics for measuring. Created per call rather than kept in a module-level variable: jasy has no
+ * global object manager by design (a shared one caused the mixed-page-size bug), and a reader that holds
+ * mutable state at module scope would quietly reintroduce it.
+ */
+export declare function fontMetrics(): PDFObjectManager;
+/** What the widget says about how it should look. Missing entries fall back to the sober defaults. */
+export interface WidgetLook {
+    width: number;
+    height: number;
+    style: FieldStyle;
+    align: FieldAlign;
+    multiline: boolean;
+    password: boolean;
+}
+export declare function readLook(doc: PdfDocument, widget: PdfObject | undefined, field: ReadField): WidgetLook | undefined;
+/**
+ * The content stream for a text or choice field showing `value`, and the BBox it is drawn in.
+ * Returns `undefined` for a kind we do not draw (a button keeps its own state pictures).
+ */
+export declare function bakeAppearance(look: WidgetLook, field: ReadField, value: string | undefined, values: string[] | undefined, metrics?: PDFObjectManager): {
+    content: string;
+    bbox: [number, number, number, number];
+} | undefined;
+/** The `/DR` a regenerated appearance refers to: our own Helvetica, added when the form has none. */
+export declare const HELV_FONT = "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>";
+/** True when the form's `/DR /Font` already offers a usable `/Helv`. */
+export declare function hasHelv(doc: PdfDocument): boolean;
+/**
+ * The two state pictures a check box or radio button needs, for a widget that ships none at all.
+ *
+ * A button's `/AP /N` is a dictionary of STATES, not a picture of a value, so an existing one stays
+ * valid however often the value changes - this is only for the producers that write none (PDFKit,
+ * react-pdf) and leave every box empty until a viewer redraws it. `on` is the export name the widget
+ * switches to.
+ */
+export declare function bakeButtonStates(look: WidgetLook, on: string, radio: boolean): {
+    on: string;
+    off: string;
+    bbox: [number, number, number, number];
+    state: string;
+};

package/dist/edit/appearance.js

@@ -0,0 +1,171 @@
+import { PDFObjectManager, FontStyle } from "../utils/pdf-object-manager.js";
+import { checkboxOff, checkboxOn, fieldDrawSize, listBoxFace, radioOff, radioOn, textFieldFace, wrapFieldValue, } from "../forms/appearance.js";
+import { Color } from "../common/color.js";
+import { get, isDict, isString, numberOf } from "./objects.js";
+import { latin1FromBytes } from "../utils/bytes.js";
+/**
+ * Re-drawing a field's appearance after its value changed.
+ *
+ * A widget's appearance is a picture of its value. Change the value and the picture is wrong - which is
+ * why filling used to DROP it and ask the viewer to redraw (`/NeedAppearances`). That works, but it hands
+ * control of how the value looks to whatever program opens the file, and it leaves the field invisible in
+ * anything that does not honour the flag. Baking it is what jasy does when it CREATES a field; there is
+ * no reason the edit side should be different.
+ *
+ * The face builders in `forms/appearance.ts` need nothing from the writer - plain numbers, a style and
+ * pre-measured lines - so the only pieces to bring are the font metrics and the widget's own style, and
+ * the latter is readable straight out of the file: `/DA` for size and colour, `/MK` for the border and
+ * background, `/Q` for alignment, `/Ff` for multiline.
+ */
+const FF_MULTILINE = 1 << 12;
+const FF_PASSWORD = 1 << 13;
+/**
+ * Font metrics for measuring. Created per call rather than kept in a module-level variable: jasy has no
+ * global object manager by design (a shared one caused the mixed-page-size bug), and a reader that holds
+ * mutable state at module scope would quietly reintroduce it.
+ */
+export function fontMetrics() {
+    const om = new PDFObjectManager();
+    om.registerFont("Helvetica", FontStyle.Normal, "Helvetica");
+    return om;
+}
+/** `[r g b]` in 0..1, as `/MK` writes colours. An empty array means "none". */
+function colorOf(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const n = raw.map((x) => (typeof x === "number" ? x : 0));
+    if (n.length === 1)
+        return new Color(n[0] * 255, n[0] * 255, n[0] * 255); // grey
+    if (n.length >= 3)
+        return new Color(n[0] * 255, n[1] * 255, n[2] * 255);
+    return undefined;
+}
+/**
+ * The bits of `/DA` we need: the font size and the fill colour.
+ *
+ * `/DA` is a content-stream fragment, not a dictionary - `"/Helv 12 Tf 0 0 0 rg"`. Size `0` is the PDF
+ * convention for "auto, fit the box", which is what a viewer would do; we resolve it the same way the
+ * writer does when it bakes.
+ */
+function fromDA(da) {
+    let size = 0;
+    let color = new Color(0, 0, 0);
+    if (da) {
+        const tf = /(-?[\d.]+)\s+Tf/.exec(da);
+        if (tf)
+            size = Number(tf[1]);
+        const rg = /(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s+rg/.exec(da);
+        const g = /(-?[\d.]+)\s+g\b/.exec(da);
+        if (rg)
+            color = new Color(Number(rg[1]) * 255, Number(rg[2]) * 255, Number(rg[3]) * 255);
+        else if (g)
+            color = new Color(Number(g[1]) * 255, Number(g[1]) * 255, Number(g[1]) * 255);
+    }
+    return { size, color };
+}
+export function readLook(doc, widget, field) {
+    const rect = doc.lookup(widget, "Rect");
+    if (!Array.isArray(rect) || rect.length < 4)
+        return undefined;
+    const n = rect.map((x) => (typeof x === "number" ? x : NaN));
+    if (n.some(Number.isNaN))
+        return undefined;
+    const width = Math.abs(n[2] - n[0]);
+    const height = Math.abs(n[3] - n[1]);
+    // /DA may be on the widget, the field, or the form - it is inheritable.
+    const daOf = (o) => {
+        const v = doc.lookup(o, "DA");
+        return isString(v) ? latin1FromBytes(v.bytes) : undefined;
+    };
+    const acro = doc.lookup(doc.catalog, "AcroForm");
+    const da = daOf(widget) ??
+        (field.objNum !== undefined ? daOf(doc.getObject(field.objNum)) : undefined) ??
+        daOf(acro);
+    const { size, color } = fromDA(da);
+    const mk = doc.resolve(get(widget, "MK"));
+    const border = isDict(mk) ? colorOf(doc.lookup(mk, "BC")) : undefined;
+    const background = isDict(mk) ? colorOf(doc.lookup(mk, "BG")) : undefined;
+    const bs = doc.resolve(get(widget, "BS"));
+    const borderWidth = border ? (numberOf(isDict(bs) ? doc.lookup(bs, "W") : undefined) ?? 1) : 0;
+    // /Q is inheritable in the same chain as /DA: widget, then field, then the form.
+    const q = numberOf(doc.lookup(widget, "Q")) ??
+        (field.objNum !== undefined
+            ? numberOf(doc.lookup(doc.getObject(field.objNum), "Q"))
+            : undefined) ??
+        numberOf(doc.lookup(acro, "Q")) ??
+        0;
+    return {
+        width,
+        height,
+        style: { border, background, color, fontSize: size, borderWidth },
+        align: q === 1 ? "center" : q === 2 ? "right" : "left",
+        multiline: (field.flags & FF_MULTILINE) !== 0,
+        password: (field.flags & FF_PASSWORD) !== 0,
+    };
+}
+/** The auto-size a viewer would pick: fit the cap height into the box, clamped to something readable. */
+function drawSize(look, capHeight) {
+    return fieldDrawSize(look.style.fontSize, look.height, look.style.borderWidth, capHeight);
+}
+/**
+ * The content stream for a text or choice field showing `value`, and the BBox it is drawn in.
+ * Returns `undefined` for a kind we do not draw (a button keeps its own state pictures).
+ */
+export function bakeAppearance(look, field, value, values, metrics) {
+    if (field.type !== "Tx" && field.type !== "Ch")
+        return undefined;
+    const om = metrics ?? fontMetrics();
+    const { capHeight } = om.getFontDecoration("Helvetica", FontStyle.Normal);
+    const size = drawSize(look, capHeight);
+    const innerWidth = Math.max(1, look.width - 2 * (2 + look.style.borderWidth));
+    const measure = (t) => ({
+        text: t,
+        width: om.getStringWidth(t, "Helvetica", size, FontStyle.Normal),
+    });
+    let content;
+    if (field.type === "Ch" && field.options && look.height > size * 2) {
+        // A list box draws every option, with the selected ones highlighted.
+        const chosen = new Set(values ?? (value !== undefined ? [value] : []));
+        const rows = field.options.map((o) => ({
+            ...measure(o.label),
+            selected: chosen.has(o.value),
+        }));
+        content = listBoxFace(look.width, look.height, look.style, rows, capHeight, size, "Helv");
+    }
+    else {
+        // A choice stores an EXPORT value but shows its label - "DE" in /V, "Germany" on screen.
+        const display = field.type === "Ch" ? (field.options?.find((o) => o.value === value)?.label ?? value) : value;
+        const shown = look.password ? "•".repeat([...(display ?? "")].length) : (display ?? "");
+        const lines = shown
+            ? wrapFieldValue(shown, "Helvetica", size, FontStyle.Normal, innerWidth, om, look.multiline).map(measure)
+            : [];
+        content = textFieldFace(look.width, look.height, look.style, lines, capHeight, size, "Helv", look.multiline, look.align);
+    }
+    return { content, bbox: [0, 0, look.width, look.height] };
+}
+/** The `/DR` a regenerated appearance refers to: our own Helvetica, added when the form has none. */
+export const HELV_FONT = "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>";
+/** True when the form's `/DR /Font` already offers a usable `/Helv`. */
+export function hasHelv(doc) {
+    const dr = doc.lookup(doc.lookup(doc.catalog, "AcroForm"), "DR");
+    const fonts = doc.lookup(dr, "Font");
+    return isDict(fonts) && fonts.map.has("Helv");
+}
+/**
+ * The two state pictures a check box or radio button needs, for a widget that ships none at all.
+ *
+ * A button's `/AP /N` is a dictionary of STATES, not a picture of a value, so an existing one stays
+ * valid however often the value changes - this is only for the producers that write none (PDFKit,
+ * react-pdf) and leave every box empty until a viewer redraws it. `on` is the export name the widget
+ * switches to.
+ */
+export function bakeButtonStates(look, on, radio) {
+    const w = look.width;
+    const h = look.height;
+    return {
+        on: radio ? radioOn(w, h, look.style) : checkboxOn(w, h, look.style),
+        off: radio ? radioOff(w, h, look.style) : checkboxOff(w, h, look.style),
+        bbox: [0, 0, w, h],
+        state: on,
+    };
+}