@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/form/button.md

@@ -0,0 +1,97 @@
+---
+module: pdfButtonField
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfButtonField
+
+> Typing of an `/FT /Btn` field — ISO 32000-2 §12.7.5.2.
+
+**Module** `pdfButtonField` | **Source** `packages/front/office/pdf/src/form/button.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+A button field covers three subtypes selected by the `/Ff` flag word:
+
+- **Pushbutton** (bit 17) — momentary, no retained state.
+- **Radio** (bit 16) — exclusive.
+- **Checkbox** — default when neither Pushbutton nor Radio.
+
+Additional sub-flags: **NoToggleToOff** (bit 15, radio only) and **RadiosInUnison** (bit 26). `/V` is a `name` (`/Yes`, `/Off`, ...); `/Opt` is an array of strings/names for the export values. Any non-canonical entry falls into `_extras`.
+
+## Resolve
+
+```js
+const bf = runtime.resolve('pdfButtonField');
+// Returns: { typeButtonField }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeButtonField` | `(dict) => ButtonField` | Typing. |
+
+### Shape `ButtonField`
+
+```js
+{
+    ft: 'Btn',
+    flags: number,
+    kind: 'pushbutton' | 'radio' | 'checkbox',
+    noToggleToOff:  boolean,
+    radiosInUnison: boolean,
+    v:   string | null,       // name value
+    dv:  string | null,
+    opt: Array<string|Uint8Array>,
+    t:   Uint8Array | null,   // /T partial name
+    raw: object,
+    _extras: { [key]: PdfObject }
+}
+```
+
+## Examples
+
+### Typing
+
+```js
+const bf = runtime.resolve('pdfButtonField');
+const btn = bf.typeButtonField(record.node);
+btn.kind;       // 'checkbox'
+btn.v;          // 'Yes' | 'Off'
+```
+
+### Radio detection
+
+```js
+if (btn.kind === 'radio') {
+    btn.opt;             // ['First option', 'Second option', ...]
+    btn.noToggleToOff;   // bit 15
+}
+```
+
+### Pushbutton (no retained state)
+
+```js
+if (btn.kind === 'pushbutton') {
+    // No /V to change; behavior is driven by /AA (actions).
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/btn/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/form/btn/bad-ft` | `ParseError` | `/FT` present but ≠ `/Btn`. |
+| `pdf/form/btn/bad-opt` | `ParseError` | `/Opt` is not an array. |
+| `pdf/form/btn/bad-opt-entry` | `ParseError` | `/Opt` entry is not a string/name. |
+
+## See also
+
+- [`pdfAcroForm`](./acroform.md) — roots.
+- [`pdfFieldTree`](./fieldTree.md) — field discovery.
+- [`pdfAppearance`](./appearance.md) — `/AP` with `states` for checkbox/radio.
+- [`pdfTextField`](./text.md), [`pdfChoiceField`](./choice.md), [`pdfSignatureField`](./signature.md).

package/docs/api/form/choice.md

@@ -0,0 +1,96 @@
+---
+module: pdfChoiceField
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfChoiceField
+
+> Typing of a choice field `/FT /Ch` (list box or combo box) — ISO 32000-2 §12.7.5.4.
+
+**Module** `pdfChoiceField` | **Source** `packages/front/office/pdf/src/form/choice.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+A choice field is either a **list box** (default) or a **combo** (bit 18). Sub-flags: **Edit** (bit 19, combo + free text entry), **Sort** (bit 20), **MultiSelect** (bit 22, list only), **DoNotSpellCheck** (bit 23, Edit-combo only), **CommitOnSelChange** (bit 27). `/Opt` accepts two shapes: `string|name` (display = export) or a 2-element `[export, display]` array. `/V` is a `string` or `array<string>`. `/I` is a parallel array of indices.
+
+## Resolve
+
+```js
+const cf = runtime.resolve('pdfChoiceField');
+// Returns: { typeChoiceField }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeChoiceField` | `(dict) => ChoiceField` | Typing. |
+
+### Shape `ChoiceField`
+
+```js
+{
+    ft: 'Ch',
+    flags: number,
+    kind: 'list' | 'combo',
+    editable, sort, multiSelect, doNotSpellCheck, commitOnSelChange,  // booleans
+    opt: Array<{ export: string|Uint8Array, display: string|Uint8Array }>,
+    v:   Array<string|Uint8Array> | null,
+    dv:  Array<string|Uint8Array> | null,
+    i:   number[],          // indices
+    ti:  number,            // top index
+    da:  Uint8Array | null,
+    q:   number,
+    t:   Uint8Array | null,
+    raw, _extras
+}
+```
+
+`editable` is computed as `combo && Edit`. `multiSelect` is computed as `!combo && MultiSelect` (combos cannot be multi-select).
+
+## Examples
+
+### Typical list box
+
+```js
+const cf = runtime.resolve('pdfChoiceField');
+const ch = cf.typeChoiceField(record.node);
+ch.kind;          // 'list'
+ch.opt;           // [{export:'A',display:'Alpha'}, ...]
+ch.v;             // ['A']
+```
+
+### Editable combo
+
+```js
+if (ch.kind === 'combo' && ch.editable) {
+    // The user can enter a value outside /Opt
+}
+```
+
+### Multi-select
+
+```js
+if (ch.multiSelect) {
+    ch.v;   // ['A','C']
+    ch.i;   // [0, 2]
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/ch/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/form/ch/bad-ft` | `ParseError` | `/FT` present but ≠ `/Ch`. |
+| `pdf/form/ch/bad-opt` | `ParseError` | `/Opt` is not an array. |
+| `pdf/form/ch/bad-opt-entry` | `ParseError` | Invalid entry (shape, length, or types). |
+| `pdf/form/ch/bad-v` | `ParseError` | `/V` array contains a non-string. |
+
+## See also
+
+- [`pdfFieldTree`](./fieldTree.md) — discovery.
+- [`pdfButtonField`](./button.md), [`pdfTextField`](./text.md), [`pdfSignatureField`](./signature.md).
+- [`pdfAppearance`](./appearance.md) — re-rendering when `NeedAppearances`.

package/docs/api/form/fieldTree.md

@@ -0,0 +1,93 @@
+---
+module: pdfFieldTree
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFieldTree
+
+> Form-field tree walker — ISO 32000-2 §12.7.4.
+
+**Module** `pdfFieldTree` | **Source** `packages/front/office/pdf/src/form/fieldTree.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Form fields form a tree rooted at `AcroForm./Fields`. Each node may carry `/Kids` (refs to child fields or widget annotations) and **inherits** `/FT`, `/Ff`, `/V`, `/DV`, `/DA`, `/Q`, `/MaxLen` from its ancestors (§12.7.4.2). A **terminal** field is one whose kids are widgets (no `/T`) or has none. Guardrails: max depth 32, max total 100,000 fields, cycle detection via a `Set<num:gen>`.
+
+## Resolve
+
+```js
+const ft = runtime.resolve('pdfFieldTree');
+// Returns: { walkFieldTree, getInherited }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `walkFieldTree` | `(rootRefs, resolveRef, opts?) => FieldRecord[]` | Pre-order walk. |
+| `getInherited` | `(node, ancestors, key) => PdfObject \| undefined` | Inherited lookup. |
+
+### Options
+
+```js
+{ maxDepth?: number = 32, maxFields?: number = 100000 }
+```
+
+### Shape `FieldRecord`
+
+```js
+{
+    ref:       { num: number, gen: number },
+    node:      object,           // typed dict
+    ancestors: object[],         // root → parent (typed dicts)
+    terminal:  boolean
+}
+```
+
+`getInherited` only accepts inheritable keys: `FT`, `Ff`, `V`, `DV`, `DA`, `Q`, `MaxLen`. Otherwise returns `undefined`.
+
+## Examples
+
+### Walk from AcroForm
+
+```js
+const ft = runtime.resolve('pdfFieldTree');
+const records = ft.walkFieldTree(form.fields, doc._raw.resolve);
+records.filter(r => r.terminal).length;
+```
+
+### Inherited FT
+
+```js
+for (const r of records) {
+    if (!r.terminal) continue;
+    const val = ft.getInherited(r.node, r.ancestors, 'FT');
+    if (val && val.value === 'Tx') console.log('text field', r.ref);
+}
+```
+
+### Custom limits
+
+```js
+const records = ft.walkFieldTree(roots, resolveRef, { maxDepth: 8, maxFields: 500 });
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/tree/bad-roots` | `ParseError` | `rootRefs` is not an array. |
+| `pdf/form/tree/max-depth` | `ParseError` | Depth > `maxDepth`. |
+| `pdf/form/tree/bad-ref` | `ParseError` | Malformed reference (no numeric `num`). |
+| `pdf/form/tree/cycle` | `ParseError` | Cycle detected (same `num:gen` seen again). |
+| `pdf/form/tree/not-dict` | `ParseError` | Resolved node is not a dict. |
+| `pdf/form/tree/too-many` | `ParseError` | Total > `maxFields`. |
+| `pdf/form/tree/non-ref-kid` | `ParseError` | `/Kids` entry is not a ref. |
+
+## See also
+
+- [`pdfAcroForm`](./acroform.md) — supplies the root refs.
+- [`pdfButtonField`](./button.md), [`pdfTextField`](./text.md), [`pdfChoiceField`](./choice.md), [`pdfSignatureField`](./signature.md) — typing by `/FT`.
+- [`pdfAppearance`](./appearance.md) — `/AP` on terminal widgets.

package/docs/api/form/signature.md

@@ -0,0 +1,90 @@
+---
+module: pdfSignatureField
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSignatureField
+
+> Typing of a signature field `/FT /Sig` — ISO 32000-2 §12.7.5.5.
+
+**Module** `pdfSignatureField` | **Source** `packages/front/office/pdf/src/form/signature.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+A signature field carries an opaque signature dict in `/V` (PKCS#7 / CMS, ByteRange, MDP). The **signature payload** itself is typed at L3 in `src/sig/` — here `/V` is kept as a raw typed object (ref or inline dict) so the caller decides whether to descend into it. `/Lock` (post-signature lock) and `/SV` (seed value) are also preserved. `signed` is `true` iff `/V` is present and well-formed.
+
+## Resolve
+
+```js
+const sf = runtime.resolve('pdfSignatureField');
+// Returns: { typeSignatureField }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeSignatureField` | `(dict) => SignatureField` | Typing. |
+
+### Shape `SignatureField`
+
+```js
+{
+    ft: 'Sig',
+    flags:  number,
+    v:      object | null,   // signature dict ref|dict (opaque at this level)
+    lock:   object | null,   // ref|dict
+    sv:     object | null,   // ref|dict — seed value
+    t:      Uint8Array | null,
+    signed: boolean,
+    raw:    object,
+    _extras:{ [key]: PdfObject }
+}
+```
+
+## Examples
+
+### Detecting a present signature
+
+```js
+const sf = runtime.resolve('pdfSignatureField');
+const sig = sf.typeSignatureField(record.node);
+if (sig.signed) {
+    const sigDict = sig.v.type === 'ref' ? doc._raw.resolve(sig.v) : sig.v;
+    // → hand off to the L3 src/sig/ API
+}
+```
+
+### Lock / seed value
+
+```js
+sig.lock;   // /Lock — post-signature restrictions
+sig.sv;     // /SV — constraints for the signer
+```
+
+### Combining with AcroForm.sigFlags
+
+```js
+const af = runtime.resolve('pdfAcroForm').typeAcroForm(...);
+const signaturesExist = (af.sigFlags & 1) !== 0;
+const appendOnly      = (af.sigFlags & 2) !== 0;
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/sig/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/form/sig/bad-ft` | `ParseError` | `/FT` present but ≠ `/Sig`. |
+| `pdf/form/sig/bad-v` | `ParseError` | `/V` is neither a dict nor a ref. |
+| `pdf/form/sig/bad-lock` | `ParseError` | `/Lock` is neither a dict nor a ref. |
+| `pdf/form/sig/bad-sv` | `ParseError` | `/SV` is neither a dict nor a ref. |
+
+## See also
+
+- [`pdfAcroForm`](./acroform.md) — `/SigFlags`.
+- [`pdfFieldTree`](./fieldTree.md) — discovery.
+- [`pdfAppearance`](./appearance.md) — visual representation.
+- [`pdfButtonField`](./button.md), [`pdfTextField`](./text.md), [`pdfChoiceField`](./choice.md).

package/docs/api/form/text.md

@@ -0,0 +1,88 @@
+---
+module: pdfTextField
+category: pdf/form
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTextField
+
+> Typing of a text field `/FT /Tx` — ISO 32000-2 §12.7.5.3.
+
+**Module** `pdfTextField` | **Source** `packages/front/office/pdf/src/form/text.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Text field — free-form input. `/V` is a string (or a stream for very long content — retrieved as `Uint8Array` via `stream.raw`). The `/Ff` word carries the sub-flags: **Multiline** (bit 13), **Password** (bit 14), **FileSelect** (bit 21), **DoNotSpellCheck** (bit 23), **DoNotScroll** (bit 24), **Comb** (bit 25, requires `/MaxLen`), **RichText** (bit 26). The module enforces the `Comb` ⇒ `/MaxLen` present constraint.
+
+## Resolve
+
+```js
+const tf = runtime.resolve('pdfTextField');
+// Returns: { typeTextField }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeTextField` | `(dict) => TextField` | Typing. |
+
+### Shape `TextField`
+
+```js
+{
+    ft: 'Tx',
+    flags: number,
+    multiline, password, fileSelect,
+    doNotSpellCheck, doNotScroll, comb, richText,   // booleans
+    v:      Uint8Array | null,
+    dv:     Uint8Array | null,
+    maxLen: number | null,
+    da:     Uint8Array | null,
+    q:      number,                // 0=left, 1=center, 2=right
+    t:      Uint8Array | null,
+    raw:    object,
+    _extras:{ [key]: PdfObject }
+}
+```
+
+## Examples
+
+### Simple typing
+
+```js
+const tf = runtime.resolve('pdfTextField');
+const tx = tf.typeTextField(record.node);
+new TextDecoder('utf-8').decode(tx.v);  // current value
+```
+
+### Comb with MaxLen
+
+```js
+if (tx.comb) {
+    tx.maxLen;  // guaranteed defined, otherwise a ParseError would have been thrown
+}
+```
+
+### Password detection
+
+```js
+if (tx.password) {
+    // Don't render tx.v in clear text in the UI.
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/form/tx/not-dict` | `ParseError` | Argument is not a typed dict. |
+| `pdf/form/tx/bad-ft` | `ParseError` | `/FT` present but ≠ `/Tx`. |
+| `pdf/form/tx/comb-without-maxlen` | `ParseError` | `Comb` flag set but `/MaxLen` absent. |
+
+## See also
+
+- [`pdfFieldTree`](./fieldTree.md) — discovery.
+- [`pdfAppearance`](./appearance.md) — `/AP /N` regenerated when `NeedAppearances`.
+- [`pdfButtonField`](./button.md), [`pdfChoiceField`](./choice.md), [`pdfSignatureField`](./signature.md).

package/docs/api/linearization/README.md

@@ -0,0 +1,11 @@
+# Linearization — ISO 32000-2 Annex F
+
+Fast Web View — progressive prefetch over an HTTP byte-range transport.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfLinearization`](./linearization.md) | `{ typeLinearizationDict }` | `pdfErrors`, `pdfParser` | Annex F parameter dict, read-only. |
+
+## See also
+
+- [Document](../document/README.md)

package/docs/api/linearization/linearization.md

@@ -0,0 +1,81 @@
+---
+module: pdfLinearization
+category: pdf/linearization
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLinearization
+
+> Linearization parameter dict — ISO 32000-2 Annex F.
+
+**Module** `pdfLinearization` | **Source** `packages/front/office/pdf/src/linearization/linearization.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+The "Linearized" parameter dict is the very first object of a file optimized for progressive (Fast Web View) download. Fields: `/Linearized` (version, usually 1.0), `/L` (file length), `/H` (hint-stream offsets/lengths — array of at least 2 numbers), `/O` (first-page object number), `/E` (end-of-first-page offset), `/N` (page count), `/T` (offset of the first entry in the main xref table), `/P` (optional, first page number).
+
+Read-only: `pdf.write` does not linearize (no writer module references this module), and `extra/linearization-write` only builds the `/Linearized` dictionary and a zero-length hint-stream placeholder.
+
+## Resolve
+
+```js
+const lin = runtime.resolve('pdfLinearization');
+// Returns: { typeLinearizationDict }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeLinearizationDict` | `(dict) => Linearization` | Strict typing; throws if invalid. |
+
+### Shape
+
+```js
+{
+    version: number,              // /Linearized
+    length: number,                // /L — total file length
+    hintOffsets: number[],         // /H — at least 2 numbers
+    firstPageObject: number,       // /O
+    endOfFirstPage: number,        // /E
+    numberOfPages: number,         // /N
+    mainXrefOffset: number,        // /T
+    firstPageNumber?: number,      // /P, when present
+    raw, _extras
+}
+```
+
+## Examples
+
+### Fast Web View detection
+
+```js
+const lin = runtime.resolve('pdfLinearization');
+try {
+    const l = lin.typeLinearizationDict(firstObject.value);
+    console.log('linearized,', l.numberOfPages, 'pages, hint at', l.hintOffsets[0]);
+} catch (e) {
+    console.log('not linearized');
+}
+```
+
+### Reading just the first page
+
+```js
+const firstPageBytes = bytes.subarray(0, l.endOfFirstPage);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/linearization/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/linearization/not-linearized` | `ParseError` | `/Linearized` absent. |
+| `pdf/linearization/missing-h` | `ParseError` | `/H` absent or not an array. |
+| `pdf/linearization/bad-h` | `ParseError` | `/H` has fewer than 2 numeric elements. |
+| `pdf/linearization/missing-l`, `-o`, `-e`, `-n`, `-t` | `ParseError` | The corresponding required key is absent or non-numeric. |
+
+## See also
+
+- [`pdfDocument`](../document/document.md) · [`pdfXref`](../syntax/xref.md)

package/docs/api/main.md

@@ -0,0 +1,116 @@
+---
+category: pdf
+status: complete
+---
+
+# main
+
+> Entry point of `@awacloud/pdf` — re-exports every factory and the ordered `modules` list for `ModuleRuntime`.
+
+**Source** `packages/front/office/pdf/src/main.js` | **Sub-path** `@awacloud/pdf` (the `.` export) — not a module descriptor
+
+No factory of its own — this file is a declarative manifest: it imports every `pdf*` module descriptor and aggregates them into five arrays (`fw_require`, `pkg_require`, `modules`, `extras`, `bundle`), plus one additive re-export block, to provide a single import point (`@awacloud/pdf`). The `modules` array is topologically sorted: `register(m)` in order guarantees each dependency precedes its dependents.
+
+## Resolve
+
+`main` is not a DI module; it is used via direct import:
+
+```js
+import { pdf, pdfErrors, modules } from '@awacloud/pdf';
+```
+
+The error classes (`PdfError`, `ParseError`, `RenderError`, `ContractError`, `EncryptionError`) are not exported at the top level — they are resolved via `pdfErrors.factory()` (see [`pdfErrors`](./errors.md)).
+
+## API (exports)
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `pdf` | factory | Orchestrator — see [`pdf`](./pdf.md). |
+| `pdfErrors` | factory | See [`pdfErrors`](./errors.md) — resolves the 5 error classes. |
+| `pdfTokenizer` | factory | See [`pdfTokenizer`](./syntax/tokenizer.md). |
+| `pdfParser` | factory | See [`pdfParser`](./syntax/parser.md). |
+| `pdfXref` | factory | See [`pdfXref`](./syntax/xref.md). |
+| `pdfTrailer` | factory | See [`pdfTrailer`](./syntax/trailer.md). |
+| `pdfCatalog` | factory | See [`pdfCatalog`](./document/catalog.md). |
+| `pdfPages` | factory | See [`pdfPages`](./document/pages.md). |
+| `pdfPage` | factory | See [`pdfPage`](./document/page.md). |
+| `pdfDocument` | factory | See [`pdfDocument`](./document/document.md). |
+| `fw_require` | `factory[]` | The `@awacloud/fw` module descriptors required by fw-bound modules, their own transitive dependencies included (zlib, aes, asn1, rsa, ecc, ed25519, …). |
+| `pkg_require` | `factory[]` | Cross-package descriptors: the whole `@awacloud/fonts` manifest (`fw_require` + `modules`) plus 4 internal `embed-pdf/subsetForPdf` helper descriptors (`embedClosure`, `embedCmapBuilder`, `embedGlyphRewriter`, `embedHash`) not re-exported by `@awacloud/fonts` itself — needed to resolve `pdfFontEmbed`'s full transitive graph. |
+| `modules` | `factory[]` | PDF core — topologically ordered for `ModuleRuntime.register`. |
+| `extras` | `factory[]` | The opt-in extras (P0/P1/P2/P3 + legacy + sandbox). |
+| `bundle` | `factory[]` | Three descriptors: `pdfLargeBundle` / `pdfFullBundle` / `pdfLegacyBundle`. They are reachable through this array or their own sub-paths (`@awacloud/pdf/pdf-large`, …), not as named exports of the root — see [Bundles](./bundles/README.md). |
+
+Beyond these arrays, **every module descriptor listed in `modules`** — from `pdfErrors`/`pdfShared` through the final `pdf` orchestrator, covering syntax, document, content, font, form, annotations, tagged PDF, encryption, signatures, OCG, outlines/destinations/actions, embedded files, linearization, metadata, prepress and associated files — **is additionally re-exported by its own binding name** (e.g. `import { pdfSignature, pdfCertChain } from '@awacloud/pdf'`), together with the 4 `pkg_require` fonts helper bindings. This is purely additive: the five arrays above stay byte-unchanged. The `extras` and `bundle` descriptors are **not** re-exported by name.
+
+### Named descriptor exports
+
+Derived from the `export { … }` block of `src/main.js` (its group comments
+included):
+
+| Group | Named exports |
+|-------|---------------|
+| Errors / shared | `pdfErrors`, `pdfShared` |
+| Syntax | `pdfTokenizer`, `pdfParserObj`, `pdfParser`, `pdfXref`, `pdfTrailer`, `pdfSerializer`, `pdfFlate`, `pdfAsciiHex`, `pdfAscii85`, `pdfRunLength`, `pdfFilterDispatch`, `pdfObjStream`, `pdfCrossRefStream` |
+| Document | `pdfCatalog`, `pdfPages`, `pdfPage`, `pdfDocument`, `pdfWriter`, `pdfBuilder`, `pdfEncryptedWriter`, `pdfIncrementalWriter`, `pdfXrefStreamWriter`, `pdfResources` |
+| Content | `pdfContentOps`, `pdfContentStream`, `pdfGraphics`, `pdfText`, `pdfColor`, `pdfImages` |
+| Font | `pdfFont`, `pdfFontEncoding`, `pdfType3`, `pdfFontEmbed` |
+| Form | `pdfAcroForm`, `pdfFieldTree`, `pdfButtonField`, `pdfTextField`, `pdfChoiceField`, `pdfSignatureField`, `pdfAppearance` |
+| Annotations | `pdfAnnot`, `pdfTextAnnot`, `pdfLinkAnnot`, `pdfMarkupAnnot`, `pdfShapeAnnot`, `pdfFreeTextAnnot`, `pdfInkAnnot`, `pdfStampAnnot`, `pdfFileAttachAnnot`, `pdfWidgetAnnot`, `pdfPopupAnnot`, `pdfProjectionAnnot`, `pdfRedactAnnot` |
+| Tagged | `pdfStructTree`, `pdfStructElement`, `pdfRoleMap`, `pdfParentTree`, `pdfClassMap`, `pdfMarkedContent` |
+| Encryption | `pdfSecurity`, `pdfStandardV4`, `pdfStandardV5`, `pdfStandardV6`, `pdfPermissions`, `pdfAesGcm` |
+| Signatures | `pdfSigOids`, `pdfSha1`, `pdfSignature`, `pdfByteRange`, `pdfTimestamp`, `pdfCertChain`, `pdfDssBuilder`, `pdfSign` |
+| Optional Content | `pdfOCG`, `pdfOCConfig` |
+| Outlines / Destinations / Actions | `pdfOutline`, `pdfDestination`, `pdfAction`, `pdfActionGoTo`, `pdfActionUri`, `pdfActionNamed`, `pdfActionLaunch` |
+| Embedded files | `pdfFileSpec`, `pdfEmbeddedFile`, `pdfCollection` |
+| Linearization / Metadata / Prepress / Associated | `pdfLinearization`, `pdfInfo`, `pdfXmp`, `pdfOutputIntent`, `pdfPageBoundary`, `pdfAssociatedFiles` |
+| Top-level | `pdf` |
+| `pkg_require` — `@awacloud/fonts` subset helper bindings | `embedClosure`, `embedCmapBuilder`, `embedGlyphRewriter`, `embedHash` | See each module's own category page (e.g. [`pdfSignature`](./sig/signature.md), [`pdfAcroForm`](./form/acroform.md)) for its individual API.
+
+## Examples
+
+### Wire via the fw runtime
+
+`fw_require` is needed as soon as a resolved module reaches an `@awacloud/fw`
+factory — `pdf` does, through the Flate filter — so register it first:
+
+```js
+import { ModuleRuntime } from '@awacloud/fw/core/runtime.js';
+import { fw_require, modules } from '@awacloud/pdf';
+
+const rt = new ModuleRuntime();
+for (const m of fw_require) rt.register(m);
+for (const m of modules)    rt.register(m);
+
+const api = rt.resolve('pdf');
+const doc = api.read(bytes);
+```
+
+### Stand-alone, without a runtime
+
+`pdf.factory()` takes its dependencies as positional arguments; the
+zero-argument entry is the committed framework-free build:
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+pdfBundled.factory().read(bytes);
+```
+
+### Typed catch subscription
+
+```js
+import { pdfErrors } from '@awacloud/pdf';
+const { PdfError } = pdfErrors.factory();
+
+try { /* … */ }
+catch (e) { if (e instanceof PdfError) console.log(e.code); else throw e; }
+```
+
+## Errors
+
+This module throws no errors of its own — it only re-exports.
+
+## See also
+
+- [`pdf`](./pdf.md) — main orchestrator.
+- [Getting started](../guide/getting-started.md)

package/docs/api/metadata/README.md

@@ -0,0 +1,10 @@
+# Metadata — ISO 32000-2 §14.3
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfInfo`](./info.md) | `{ typeInfo }` | `pdfErrors`, `pdfParser` | Info dict §14.3.3. |
+| [`pdfXmp`](./xmp.md) | `{ typeXmpStream }` | `pdfErrors`, `pdfParser` | XMP §14.3.2 / ISO 16684-1. |
+
+## See also
+
+- [Document](../document/README.md) · [Prepress](../prepress/README.md)