@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/font/embed.md

@@ -0,0 +1,157 @@
+---
+module: pdfFontEmbed
+category: pdf/font
+dependencies: [pdfErrors, embedSubsetForPdf, embedFontDescriptor, embedCidSystemInfo, embedToUnicodeBuilder]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFontEmbed
+
+> Adapter between `@awacloud/fonts/embed-pdf` and PDF dicts — ISO 32000-2 §9.6 / §9.7 / §9.10.
+
+**Module** `pdfFontEmbed` | **Source** `packages/front/office/pdf/src/font/embed.js` | **Deps** `pdfErrors`, `embedSubsetForPdf`, `embedFontDescriptor`, `embedCidSystemInfo`, `embedToUnicodeBuilder` | **Worker-safe** yes
+
+The only file in `@awacloud/pdf` that knows about `@awacloud/fonts/embed-pdf`. It takes an already-parsed font (the output of `fonts.read(bytes)`) plus a set of code points, and produces the PDF dicts needed to embed a **subset** of that font — either simple (`/TrueType` + `/WinAnsiEncoding`) or composite (`/Type0` + `/Identity-H` + `/CIDFontType2`). The subsetting itself is delegated to `subsetForPdf`; this module exists so the writer's call sites don't re-derive the wiring.
+
+## Resolve
+
+```js
+const emb = runtime.resolve('pdfFontEmbed');
+// Returns: { embedSimple, embedCid }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `embedSimple` | `(parsedFont, codePoints, opts?) => SimpleEmbed` | `/TrueType` + `/WinAnsiEncoding`. Every code point must be CP1252-representable. |
+| `embedCid` | `(parsedFont, codePoints, opts?) => CidEmbed` | `/Type0` + `/Identity-H` with a `/CIDFontType2` descendant. Any Unicode code point. |
+
+`parsedFont` must be a real parsed `Font` — `unicodeMap`, `glyphIndexForCodePoint`, `advanceWidth` and a numeric `unitsPerEm` are all read. `codePoints` is any iterable of integers; it is de-duplicated and sorted, and the sorted array is echoed back as `codePoints`. `opts` is forwarded to `subsetForPdf` (`embedCid` adds `{ cid: true }`).
+
+The factory validates at construction that its four injected `@awacloud/fonts/embed-pdf` helpers (`subsetForPdf`, `buildFontDescriptor`, `buildCidSystemInfo`, `embedBuildToUnicode`) are functions, throwing `ContractError` otherwise.
+
+## What the adapter consumes
+
+`subsetForPdf(font, codePoints, opts?)` returns exactly eight keys — `subsetBytes`, `gidMap`, `glyphMap`, `encoding`, `widths`, `toUnicodeCmap`, `postScriptName`, `fontDescriptor`. The adapter reads all of them except `encoding` (always `null`: under `Identity-H` the encoding is the cmap). A unit-tier **contract-shape guard** (`src/font/embed.test.js`) resolves the REAL `embedSubsetForPdf` through a `ModuleRuntime` and asserts that key set, so the stub can never drift from the package again.
+
+Two conversions happen here and nowhere else:
+
+- **Widths.** `subset.widths` is indexed by NEW gid and expressed in **font units**. Everything this module emits (`/Widths`, `/W`, `widthOf`) is `round(w * 1000 / unitsPerEm)`.
+- **`/ToUnicode` source.** A `/ToUnicode` CMap is keyed by *character code*. For `embedCid` the code IS the CID (= the subset's new gid), which is exactly how `subset.toUnicodeCmap` is keyed — it is used verbatim. For `embedSimple` the codes are WinAnsi **bytes**, so the gid-keyed CMap would be wrong; the adapter builds the byte-keyed map and passes it to `embedBuildToUnicode` with `{ codeBytes: 1 }`, so the CMap declares a one-byte codespace (`<00> <FF>`) and 2-hex-digit codes; `embedCid` keeps the 2-byte default. Never both for one route.
+
+## The consumer's contract — the descriptor carries no font program
+
+`buildFontDescriptor` puts the raw subset bytes in `FontFile2` (TrueType) or `FontFile3` (CFF). The adapter **lifts them out**: the returned `descriptor` dict has no font-program key, and the bytes come back as `fontFile` with the key name in `fontFileKey`. The consumer must:
+
+1. allocate the font program as a **stream indirect** whose dict carries `/Length1 = fontFile.length` (the serializer adds `/Length`), and set `descriptor.entries[fontFileKey]` to that ref;
+2. allocate `toUnicodeStream` as a stream indirect too and set the font dict's `ToUnicode` to that ref — `pdfSerializer` refuses an inline stream (`pdf/serializer/inline-stream`).
+
+The font dict itself may be written inline or as an indirect; the descriptor nests fine inside it.
+
+Do this wiring in **new** dicts — spread the result's `entries` into a fresh
+`obj.dict({ … })` and add the references there — rather than by assigning into
+the result's own dicts. The embed result is then left untouched and can be
+reused for another document (or another page tree) as is.
+[`pdfBuilder`](../document/builder.md)'s `addFont({ name, embedded })` does
+exactly this wiring for you: it copies the entries into new dicts, never
+mutates the result, and allocates its indirects per document.
+
+### Shape `SimpleEmbed`
+
+```js
+{
+    subtype: 'TrueType',
+    fontDict:        typed dict (Type/Subtype/BaseFont/Encoding/FirstChar/LastChar/Widths/FontDescriptor/ToUnicode),
+    descriptor:      typed dict — no FontFile2/FontFile3 key,
+    toUnicodeStream: typed stream (byte-keyed CMap),
+    fontFile:        Uint8Array — the subset font program,
+    fontFileKey:     'FontFile2' | 'FontFile3',
+    encode(text):    Uint8Array — one WinAnsi byte per code point,
+    widthOf(cp):     number — 1000/em, 0 when the cp is not embedded,
+    codePoints:      number[] — de-duplicated, ascending
+}
+```
+
+`BaseFont` is the subsetter's `postScriptName` (already `ABCDEF+Family`). `FirstChar`/`LastChar` are the min/max WinAnsi bytes of the embedded set, and `Widths` covers `[FirstChar..LastChar]` with `0` in the unused slots.
+
+### Shape `CidEmbed`
+
+```js
+{
+    type0Dict:       typed dict (Type/Subtype:Type0/BaseFont/Encoding:Identity-H/DescendantFonts/ToUnicode),
+    cidFontDict:     typed dict (Subtype:CIDFontType2/CIDSystemInfo/FontDescriptor/DW/W/CIDToGIDMap:Identity),
+    descriptor:      typed dict — no FontFile2/FontFile3 key,
+    toUnicodeStream: typed stream (CID-keyed CMap),
+    fontFile:        Uint8Array,
+    fontFileKey:     'FontFile2' | 'FontFile3',
+    encode(text):    Uint8Array — 2 big-endian bytes (the CID) per code point;
+                     an unknown cp becomes CID 0 (.notdef) and bumps `encode.missing`,
+    widthOf(cp):     number — 1000/em, 0 when the cp is not embedded,
+    codePoints:      number[]
+}
+```
+
+The subset is renumbered, so **CID === new gid** and `/CIDToGIDMap` is `/Identity`. `/DW` is `1000`; `/W` is the compact `[c [w …] …]` form over the subset's gids.
+
+## Examples
+
+### Simple embed (`/TrueType` + `/WinAnsiEncoding`)
+
+```js
+const emb  = runtime.resolve('pdfFontEmbed');
+const { obj } = runtime.resolve('pdfParserObj');
+
+const e = emb.embedSimple(parsedFont, [...'Hello'].map(c => c.codePointAt(0)));
+
+// Clone, don't mutate: new dicts carry the two stream references,
+// `e` itself stays reusable for another document.
+const descriptor = obj.dict({ ...e.descriptor.entries, [e.fontFileKey]: obj.ref(6, 0) });
+const fontDict   = obj.dict({ ...e.fontDict.entries, FontDescriptor: descriptor, ToUnicode: obj.ref(7, 0) });
+
+const indirects = [
+    /* … catalog, pages, page, contents … */
+    { num: 5, gen: 0, value: fontDict },
+    { num: 6, gen: 0, value: obj.stream(obj.dict({ Length1: obj.int(e.fontFile.length) }), e.fontFile) },
+    { num: 7, gen: 0, value: obj.stream(obj.dict({}), e.toUnicodeStream.raw) }
+];
+
+// Content stream: the show-string is what `encode` produced.
+e.encode('Hello');    // Uint8Array [0x48, 0x65, 0x6C, 0x6C, 0x6F]
+e.widthOf(0x48);      // advance width of 'H' in 1000/em, never font units
+```
+
+### CID embed (composite `/Type0`)
+
+```js
+const e = emb.embedCid(parsedFont, [...'Uni é fi'].map(c => c.codePointAt(0)));
+
+const descriptor = obj.dict({ ...e.descriptor.entries, [e.fontFileKey]: obj.ref(6, 0) });
+const cidFont    = obj.dict({ ...e.cidFontDict.entries, FontDescriptor: descriptor });
+const type0      = obj.dict({ ...e.type0Dict.entries,
+                              DescendantFonts: obj.array([cidFont]),
+                              ToUnicode: obj.ref(7, 0) });
+// font program at 6 and e.toUnicodeStream at 7, as in the simple route
+
+const codes = e.encode('Uni é fi');   // 2 bytes per code point, big-endian CIDs
+e.encode.missing;                    // 0 — every cp was in the subset
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/embed/missing-fonts-embed` | `ContractError` | The injected `@awacloud/fonts/embed-pdf` helpers are absent or don't supply the 4 required functions (thrown at factory time). |
+| `pdf/embed/bad-font` | `ContractError` | `parsedFont` is not a parsed `Font` (missing `unicodeMap` / `glyphIndexForCodePoint` / `advanceWidth` / numeric `unitsPerEm`). |
+| `pdf/embed/bad-codepoints` | `ContractError` | `codePoints` is not iterable, is empty, or holds a non-integer / out-of-range value (`context.cp`). |
+| `pdf/embed/not-winansi` | `ContractError` | `embedSimple` was given a code point outside CP1252 (`context.cp`) — use `embedCid`. Also thrown by `SimpleEmbed.encode` for a character outside the embedded set. |
+
+## See also
+
+- [`pdfFont`](./font.md) — read-side typing.
+- [`pdfFontEncoding`](./encoding.md) — `/Encoding` resolution.
+- [`pdfWriter`](../document/writer.md) — consumes the payload.
+- [`parser-obj`](../syntax/parser-obj.md) — `obj.*` constructors.
+- `tests/font-embed-real.integration.test.js` — both routes written and read back against a REAL parsed font.

package/docs/api/font/encoding.md

@@ -0,0 +1,95 @@
+---
+module: pdfFontEncoding
+category: pdf/font
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFontEncoding
+
+> Resolution of a simple font's `/Encoding` entry — ISO 32000-2 §9.6.5.
+
+**Module** `pdfFontEncoding` | **Source** `packages/front/office/pdf/src/font/encoding.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Builds a 256-entry table of **glyph names** (or `null` for unmapped slots) from a PDF `/Encoding` entry. Three accepted shapes:
+
+- **absent** → `StandardEncoding`.
+- **name**: `/WinAnsiEncoding`, `/MacRomanEncoding`, `/MacExpertEncoding`, `/StandardEncoding`, `/SymbolEncoding`, `/ZapfDingbatsEncoding`.
+- **dict**: `{ BaseEncoding?: name, Differences?: array }` — overlays slots on top of the base table.
+
+The module is **pure**: it does not know the named tables themselves. The caller passes `lookupNamed` (typically `@awacloud/fonts/encodings#lookupEncoding`).
+
+## Resolve
+
+```js
+const enc = runtime.resolve('pdfFontEncoding');
+// Returns: { resolveEncoding }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `resolveEncoding` | `(entry, lookupNamed) => Array<string\|null>` | 256-entry table of glyph names. |
+
+### `Differences` format (§9.6.5.4)
+
+Array interleaving ints (starting slot) and names (consecutive glyphs):
+
+```
+[ 1 /a /b /c   65 /A /B ]
+  └─ slot 1=a, 2=b, 3=c
+                  └─ slot 65=A, 66=B
+```
+
+## Examples
+
+### Named encoding
+
+```js
+const enc = runtime.resolve('pdfFontEncoding');
+const table = enc.resolveEncoding(
+    { type: 'name', value: 'WinAnsiEncoding' },
+    lookupNamed
+);
+table[0x41];   // 'A'
+table[0x80];   // 'Euro' (WinAnsi)
+```
+
+### Encoding with Differences
+
+```js
+const entry = obj.dict({
+    BaseEncoding: obj.name('WinAnsiEncoding'),
+    Differences: obj.array([
+        obj.int(1), obj.name('exclamdown'), obj.name('cent')
+    ])
+});
+const table = enc.resolveEncoding(entry, lookupNamed);
+table[1];  // 'exclamdown'
+table[2];  // 'cent'
+```
+
+### Absent encoding → Standard
+
+```js
+const table = enc.resolveEncoding(null, lookupNamed);
+// → StandardEncoding
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/encoding/bad-base` | `ParseError` | `/BaseEncoding` is not a name. |
+| `pdf/encoding/bad-shape` | `ParseError` | `/Encoding` is neither a name nor a dict. |
+| `pdf/encoding/bad-differences` | `ParseError` | `/Differences` is not an array. |
+| `pdf/encoding/bad-differences-entry` | `ParseError` | A `/Differences` entry is neither int nor name. |
+
+## See also
+
+- [`pdfFont`](./font.md) — carries the `encoding` field.
+- [`pdfType3`](./type3.md) — accepts the same format.
+- [`pdfText`](../content/text.md) — `extractText` consumes the mapping.

package/docs/api/font/font.md

@@ -0,0 +1,97 @@
+---
+module: pdfFont
+category: pdf/font
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFont
+
+> Typing of a PDF Font dict — ISO 32000-2 §9.6 / §9.7.
+
+**Module** `pdfFont` | **Source** `packages/front/office/pdf/src/font/font.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+This module **does not parse font files** — all PFB/PFA, TrueType/OpenType, CFF, CIDFont byte reading is delegated to `@awacloud/fonts`. Here we only type the Font **dictionary** (Type, Subtype, BaseFont, Encoding, FirstChar, LastChar, Widths, FontDescriptor, ToUnicode, DescendantFonts) and classify the font among `Type0`, `Type1`, `MMType1`, `Type3`, `TrueType`, `CIDFontType0`, `CIDFontType2`. A Standard 14 fallback is available if the caller supplies `opts.standard14` (`isStandard14` / `lookupStandard14` lookup).
+
+## Resolve
+
+```js
+const f = runtime.resolve('pdfFont');
+// Returns: { typeFont, resolveDescendant }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeFont` | `(dict, opts?: { standard14 }) => Font` | Typing. |
+| `resolveDescendant` | `(type0Font, resolveRef) => Font \| null` | Reads the descendant CIDFont of a Type0. |
+
+### Shape `Font`
+
+```js
+{
+    subtype: 'Type0'|'Type1'|'MMType1'|'Type3'|'TrueType'|'CIDFontType0'|'CIDFontType2',
+    baseFont:        string | null,
+    encoding:        PdfObject | null,    // name | dict
+    firstChar:       int | null,
+    lastChar:        int | null,
+    widths:          number[] | null,
+    fontDescriptor:  PdfObject | null,
+    toUnicode:       PdfObject | null,
+    descendantFonts: PdfObject[] | null,
+    standard14:      object | null,       // set when the fallback triggers
+    raw:             object
+}
+```
+
+The Standard 14 fallback triggers only when: `subtype ∈ {Type1, MMType1}`, **no** `/FontDescriptor`, and `baseFont` is recognized by `isStandard14`.
+
+## Examples
+
+### Simple typing
+
+```js
+const f = runtime.resolve('pdfFont');
+const font = f.typeFont(resources.Font.F1);
+font.subtype;   // 'Type1'
+font.baseFont;  // 'Helvetica'
+```
+
+### Composite Type0 + descendant
+
+```js
+const type0 = f.typeFont(resources.Font.F1);
+if (type0.subtype === 'Type0') {
+    const cid = f.resolveDescendant(type0, doc._raw.resolve);
+    cid.subtype;  // 'CIDFontType2'
+}
+```
+
+### Standard 14 fallback
+
+```js
+const font = f.typeFont(dict, {
+    standard14: runtime.resolve('fontsStandard14')
+});
+font.standard14;  // { widths, bbox, italicAngle, ... } | null
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/font/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/font/bad-type` | `ParseError` | `/Type` present but ≠ `/Font`. |
+| `pdf/font/missing-subtype` | `ParseError` | `/Subtype` absent or not a name. |
+| `pdf/font/unknown-subtype` | `ParseError` | `/Subtype` outside the 7 known values. |
+
+## See also
+
+- [`pdfFontEncoding`](./encoding.md) — `/Encoding` resolution.
+- [`pdfType3`](./type3.md) — Type 3 font (PDF-specific).
+- [`pdfFontEmbed`](./embed.md) — write-side adapter.
+- [`pdfText`](../content/text.md) — consumes `subtype` for `extractText`.
+- [`pdfResources`](../document/resources.md) — supplies the dicts.

package/docs/api/font/type3.md

@@ -0,0 +1,89 @@
+---
+module: pdfType3
+category: pdf/font
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfType3
+
+> Typing of a Type 3 font (glyphs defined by content streams) — ISO 32000-2 §9.6.4.
+
+**Module** `pdfType3` | **Source** `packages/front/office/pdf/src/font/type3.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Unlike Type1/TrueType/CIDFont (which delegate to `@awacloud/fonts`), Type 3 fonts are **PDF-specific**: each glyph is defined by a content stream in `/CharProcs`. That is why this module lives here rather than in `@awacloud/fonts`. The exposed record carries `bbox`, `matrix` (defaults to `[0.001, 0, 0, 0.001, 0, 0]`), `charProcs`, `encoding`, `firstChar`/`lastChar`/`widths`, `fontDescriptor` (optional in PDF 2.0), and `resources` (local to the glyphs).
+
+## Resolve
+
+```js
+const t3 = runtime.resolve('pdfType3');
+// Returns: { typeType3 }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeType3` | `(dict) => Type3Font` | Typing. |
+
+### Shape `Type3Font`
+
+```js
+{
+    subtype: 'Type3',
+    bbox:   [llx,lly,urx,ury] | null,
+    matrix: [0.001,0,0,0.001,0,0],   // default
+    charProcs:      { [glyphName]: PdfObject },   // stream | ref
+    encoding:       PdfObject | null,
+    firstChar:      int | null,
+    lastChar:       int | null,
+    widths:         number[] | null,
+    fontDescriptor: PdfObject | null,
+    resources:      PdfObject | null,
+    raw:            object
+}
+```
+
+## Examples
+
+### Typing
+
+```js
+const t3 = runtime.resolve('pdfType3');
+const font = t3.typeType3(resources.Font.F1);
+font.subtype;     // 'Type3'
+font.bbox;        // [0, 0, 1000, 1000]
+font.matrix;      // [0.001, 0, 0, 0.001, 0, 0]
+```
+
+### Rendering a glyph stream
+
+```js
+const procRef = font.charProcs.a;     // ref to a content stream
+const proc = doc._raw.resolve(procRef);
+const ops = runtime.resolve('pdfContentStream').parseContentStream(proc.raw);
+// The first op is usually d0 or d1 (set glyph metrics)
+```
+
+### Encoding via the dedicated module
+
+```js
+const enc = runtime.resolve('pdfFontEncoding');
+const table = enc.resolveEncoding(font.encoding, lookupNamed);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/type3/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/type3/wrong-subtype` | `ParseError` | `/Subtype` absent, not a name, or ≠ `/Type3`. |
+
+## See also
+
+- [`pdfFont`](./font.md) — generic typing (other subtypes).
+- [`pdfFontEncoding`](./encoding.md) — `/Encoding` resolution.
+- [`pdfContentStream`](../content/stream.md) — parses `CharProcs`.
+- [`pdfContentOps`](../content/ops.md) — `d0` / `d1` Type3 ops.

package/docs/api/form/README.md

@@ -0,0 +1,35 @@
+# Form — ISO 32000-2 §12.7 / §12.5.5
+
+Interactive forms (AcroForm) layer: root dict typing, field-tree walk, typing by `/FT`, and `/AP` appearance streams.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfAcroForm`](./acroform.md) | `{ typeAcroForm }` | `pdfErrors`, `pdfParser` | `/AcroForm` dict, §12.7.3. |
+| [`pdfFieldTree`](./fieldTree.md) | `{ walkFieldTree, getInherited }` | `pdfErrors`, `pdfParser` | Walk + inheritance, §12.7.4. |
+| [`pdfButtonField`](./button.md) | `{ typeButtonField }` | `pdfErrors`, `pdfParser` | `/FT /Btn`, §12.7.5.2. |
+| [`pdfTextField`](./text.md) | `{ typeTextField }` | `pdfErrors`, `pdfParser` | `/FT /Tx`, §12.7.5.3. |
+| [`pdfChoiceField`](./choice.md) | `{ typeChoiceField }` | `pdfErrors`, `pdfParser` | `/FT /Ch`, §12.7.5.4. |
+| [`pdfSignatureField`](./signature.md) | `{ typeSignatureField }` | `pdfErrors`, `pdfParser` | `/FT /Sig`, §12.7.5.5. |
+| [`pdfAppearance`](./appearance.md) | `{ typeAppearanceStreams, listPopulatedSlots }` | `pdfErrors`, `pdfParser` | `/AP`, §12.5.5. |
+
+## Common pattern
+
+```js
+const af = runtime.resolve('pdfAcroForm').typeAcroForm(doc._raw.resolve(catalog.acroForm));
+const records = runtime.resolve('pdfFieldTree').walkFieldTree(af.fields, doc._raw.resolve);
+for (const r of records.filter(r => r.terminal)) {
+    const ft = r.node.entries.FT && r.node.entries.FT.value;
+    switch (ft) {
+        case 'Btn': runtime.resolve('pdfButtonField').typeButtonField(r.node); break;
+        case 'Tx':  runtime.resolve('pdfTextField').typeTextField(r.node);     break;
+        case 'Ch':  runtime.resolve('pdfChoiceField').typeChoiceField(r.node); break;
+        case 'Sig': runtime.resolve('pdfSignatureField').typeSignatureField(r.node); break;
+    }
+}
+```
+
+## See also
+
+- [Document layer](../document/README.md) — `pdfCatalog` carries `/AcroForm`.
+- [Content layer](../content/README.md) — `pdfContentStream` parses appearances.
+- [Syntax layer](../syntax/README.md) — the underlying `pdfParser`.

package/docs/api/form/acroform.md

@@ -0,0 +1,88 @@
+---
+module: pdfAcroForm
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAcroForm
+
+> Typing of the Catalog's `/AcroForm` dict — ISO 32000-2 §12.7.3.
+
+**Module** `pdfAcroForm` | **Source** `packages/front/office/pdf/src/form/acroform.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+The Catalog's `/AcroForm` describes the interactive-forms layer: root `/Fields`, `/NeedAppearances`, `/SigFlags` (bit 1 = SignaturesExist, bit 2 = AppendOnly), `/CO` (calculation order), `/DR` (default Resources), `/DA` (default appearance), `/Q` (default quadding, 0=left/1=center/2=right). `/XFA` (legacy 1.7) is preserved verbatim in `_extras` for 2.0 fidelity. Any unknown entry is also captured in `_extras`.
+
+## Resolve
+
+```js
+const af = runtime.resolve('pdfAcroForm');
+// Returns: { typeAcroForm }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeAcroForm` | `(dict) => AcroForm` | Typing. |
+
+### Shape `AcroForm`
+
+```js
+{
+    fields:          Array<{num:number, gen:number}>,
+    needAppearances: boolean,        // default false
+    sigFlags:        number,         // default 0
+    co:              Array<{num,gen}>, // calculation order
+    dr:              object|null,    // /DR dict
+    da:              Uint8Array|null,// /DA bytes
+    q:               number,         // default 0
+    raw:             object,
+    _extras:         { [key]: PdfObject }   // /XFA + others
+}
+```
+
+`/Fields` is required by §12.7.3 but a degenerate AcroForm dict without it is tolerated (result `[]`).
+
+## Examples
+
+### Typing from the Catalog
+
+```js
+const af = runtime.resolve('pdfAcroForm');
+if (doc.catalog.acroForm) {
+    const form = af.typeAcroForm(doc._raw.resolve(doc.catalog.acroForm));
+    form.fields.length;
+    (form.sigFlags & 1) !== 0;  // SignaturesExist
+    (form.sigFlags & 2) !== 0;  // AppendOnly
+}
+```
+
+### Walking the roots
+
+```js
+const ft = runtime.resolve('pdfFieldTree');
+const records = ft.walkFieldTree(form.fields, doc._raw.resolve);
+```
+
+### XFA preservation
+
+```js
+form._extras.XFA;  // typed array/stream — passed through as-is to the writer
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/acroform/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/form/acroform/bad-fields` | `ParseError` | `/Fields` is not an array of refs. |
+| `pdf/form/acroform/bad-co` | `ParseError` | `/CO` is not an array of refs. |
+
+## See also
+
+- [`pdfFieldTree`](./fieldTree.md) — walks `fields`.
+- [`pdfButtonField`](./button.md), [`pdfTextField`](./text.md), [`pdfChoiceField`](./choice.md), [`pdfSignatureField`](./signature.md) — typing by `/FT`.
+- [`pdfCatalog`](../document/catalog.md) — carries `acroForm`.

package/docs/api/form/appearance.md

@@ -0,0 +1,87 @@
+---
+module: pdfAppearance
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAppearance
+
+> Typing of the `/AP` appearance-streams dict — ISO 32000-2 §12.5.5.
+
+**Module** `pdfAppearance` | **Source** `packages/front/office/pdf/src/form/appearance.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+A widget annotation carries an `/AP` with 3 slots: **N** (Normal, required), **R** (Rollover, optional), **D** (Down, optional). Each slot is either a direct stream (or ref), or a sub-dict mapping **state names** (e.g. `/Yes`, `/Off`) to streams — the form used by checkbox/radio, with the current state selected by `/AS`. The module normalizes both shapes to `{ default, states }`.
+
+## Resolve
+
+```js
+const ap = runtime.resolve('pdfAppearance');
+// Returns: { typeAppearanceStreams, listPopulatedSlots }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeAppearanceStreams` | `(dict) => Appearance` | Typing. |
+| `listPopulatedSlots` | `(ap) => Array<'N'\|'R'\|'D'>` | Non-null slots. |
+
+### Shape `Appearance`
+
+```js
+{
+    N: { default: stream|ref|null, states: { [stateName]: stream|ref } },
+    R: { ... } | null,
+    D: { ... } | null,
+    raw: object,
+    _extras: { [key]: PdfObject }
+}
+```
+
+- If the slot was a bare stream/ref → `default` is set, `states = {}`.
+- If the slot was a sub-dict → `default = null`, `states` populated.
+- `/N` is always present (otherwise `pdf/form/ap/missing-n`).
+
+## Examples
+
+### Stateless (text field)
+
+```js
+const ap = runtime.resolve('pdfAppearance');
+const a = ap.typeAppearanceStreams(widget.entries.AP);
+a.N.default;        // typed stream
+a.N.states;         // {}
+```
+
+### Checkbox/radio (with states)
+
+```js
+const a = ap.typeAppearanceStreams(widget.entries.AP);
+const currentState = widget.entries.AS && widget.entries.AS.value;  // 'Yes' | 'Off'
+const visualStream = a.N.states[currentState] || a.N.default;
+```
+
+### Enumeration
+
+```js
+ap.listPopulatedSlots(a);   // ['N'] or ['N','R'] or ['N','R','D']
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/ap/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/form/ap/missing-n` | `ParseError` | `/N` absent (Normal slot required). |
+| `pdf/form/ap/bad-state` | `ParseError` | A state entry is neither a stream nor a ref. |
+| `pdf/form/ap/bad-slot` | `ParseError` | An `/N`/`/R`/`/D` slot is neither stream/ref nor a sub-dict. |
+
+## See also
+
+- [`pdfButtonField`](./button.md) — checkbox/radio uses the `states`.
+- [`pdfTextField`](./text.md), [`pdfChoiceField`](./choice.md), [`pdfSignatureField`](./signature.md).
+- [`pdfContentStream`](../content/stream.md) — parses the appearance streams.
+- [`pdfImages`](../content/images.md) — typing of the underlying Form XObjects.