@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/document/writer.md

@@ -0,0 +1,157 @@
+---
+module: pdfWriter
+category: pdf/document
+dependencies: [pdfErrors, pdfSerializer]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfWriter
+
+> Model → PDF 2.0 `Uint8Array` — header, indirects, classical xref, trailer.
+
+**Module** `pdfWriter` | **Source** `packages/front/office/pdf/src/document/writer.js` | **Deps** `pdfErrors`, `pdfSerializer` | **Worker-safe** yes
+
+Emits a complete PDF document per ISO 32000-2 §7.5.2–7.5.5:
+
+1. Header `%PDF-x.y\n` plus the binary marker comment.
+2. For each indirect, `serializeIndirect` and the recording of its offset.
+3. Classical xref table — `xref` keyword, one `0 N` subsection, 20-byte entries
+   (`0000000000 65535 f ` for the free-list head, `oooooooooo 00000 n ` for live
+   objects, `0000000000 00000 f ` for holes).
+4. Trailer dictionary plus `startxref` and `%%EOF`.
+
+`writeDocument` is model-agnostic: it happily emits a from-scratch indirect list
+(see the second example). `assembleIndirects(model)` covers the **read → write
+round trip**: it forces full resolution of a model read through `pdf.read()`,
+then snapshots the `_raw.indirects` cache into an ordered list ready for
+`writeDocument`. The result is byte-different but semantically equivalent.
+
+Two sibling factories build on this one: `pdfBuilder` (`{ builder }`) offers a
+chainable constructive DSL — `addPage`, `addContent`, `addFont`, `addMetadata`,
+`setVersion`, `setId`, `build()` — and `pdfIncrementalWriter`
+(`{ appendIncremental }`) appends an incremental-update section (§7.5.6) to
+existing bytes. `pdfEncryptedWriter` (`{ writeEncryptedDocument }`) wraps
+`writeDocument` with the standard security handlers.
+
+## Resolve
+
+```js
+const writer = runtime.resolve('pdfWriter');
+// Returns: { writeDocument, assembleIndirects }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `writeDocument` | `(opts: WriteOpts) => Uint8Array` | Complete document. |
+| `assembleIndirects` | `(model: ReadModel, opts?: { strict?: boolean }) => Array<{num, gen, value}>` | Ordered snapshot; carries `skippedObjects` (see below). |
+
+### `WriteOpts`
+
+```js
+{
+    indirects: [ { num, gen, value }, … ],   // required — num >= 1, no duplicates
+    root:      { num, gen },                 // required — trailer /Root
+    info?:     { num, gen },                 // optional — /Info
+    version?:  '2.0' | '1.7' | …             // default '2.0', matches /^\d\.\d$/
+    id?:       [ Uint8Array, Uint8Array ]    // 2 × 16 bytes for /ID
+}
+```
+
+`indirects` is sorted by `num` before emission, so the caller need not supply it
+in ascending order.
+
+### Unresolvable objects (`skippedObjects`, `strict`)
+
+`assembleIndirects` forces resolution of every in-use xref entry. An entry whose
+resolution throws cannot be written, so it never reaches the snapshot. The loss is
+reported, not silent:
+
+- **Lenient (default)** — the snapshot is returned as before (byte-identical
+  output for a fully resolvable model) and carries the skipped entries on its
+  **non-enumerable** `skippedObjects` property: `Array<{ num, gen, code }>`,
+  empty when nothing was skipped. `code` is the caught error's `code` when it is a
+  typed pdf error, else `'unknown'`. Being non-enumerable, it does not change
+  iteration, spreading, `JSON.stringify` or deep equality of the array.
+- **`opts.strict === true`** — throws a `RenderError` coded
+  `pdf/writer/unresolvable-objects` (message names the count) whose
+  `context.objects` is the same list.
+
+```js
+const indirects = writer.assembleIndirects(model);
+if (indirects.skippedObjects.length > 0) {
+    console.warn('dropped', indirects.skippedObjects);   // [{ num, gen, code }, …]
+}
+writer.assembleIndirects(model, { strict: true });        // throws instead of dropping
+```
+
+`pdf.write(model)` calls `assembleIndirects(model)` in lenient mode and does not
+forward the list; call `assembleIndirects` directly to observe or forbid drops.
+
+## Examples
+
+### Read → write round trip
+
+```js
+const pdf = runtime.resolve('pdf');
+const writer = runtime.resolve('pdfWriter');
+
+const model = pdf.read(srcBytes);
+const indirects = writer.assembleIndirects(model);
+const out = writer.writeDocument({
+    indirects,
+    root: { num: model.trailer.root.num, gen: model.trailer.root.gen },
+    info: model.trailer.info,
+    version: model.version
+});
+```
+
+### Minimal from-scratch document
+
+```js
+const writer = runtime.resolve('pdfWriter');
+const out = writer.writeDocument({
+    indirects: [
+        { num: 1, gen: 0, value: { type: 'dict', entries: {
+            Type: { type: 'name', value: 'Catalog' },
+            Pages: { type: 'ref', num: 2, gen: 0 }
+        }}},
+        { num: 2, gen: 0, value: { type: 'dict', entries: {
+            Type: { type: 'name', value: 'Pages' },
+            Count: { type: 'int', value: 0 },
+            Kids: { type: 'array', items: [] }
+        }}}
+    ],
+    root: { num: 1, gen: 0 }
+});
+```
+
+### `/ID` for reproducibility
+
+```js
+const id = new Uint8Array(16); /* … filled … */
+writer.writeDocument({ indirects, root, id: [id, id] });
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/writer/bad-input` | `RenderError` | `opts.indirects` is not an array. |
+| `pdf/writer/no-root` | `RenderError` | `opts.root` missing or `num` not finite. |
+| `pdf/writer/bad-version` | `RenderError` | `version` does not match `/^\d\.\d$/`. |
+| `pdf/writer/bad-indirect` | `RenderError` | An element without a finite `num` ≥ 1. |
+| `pdf/writer/duplicate-num` | `RenderError` | Two entries share the same `num`. |
+| `pdf/writer/bad-model` | `RenderError` | `assembleIndirects` given something other than a `pdf.read()` model. |
+| `pdf/writer/unresolvable-objects` | `RenderError` | `assembleIndirects(model, { strict: true })` and at least one in-use object could not be resolved; `context.objects` is `Array<{ num, gen, code }>`. |
+
+It also propagates every code from [`pdfSerializer`](../syntax/serializer.md).
+
+## See also
+
+- [`pdfSerializer`](../syntax/serializer.md) — per-object emission.
+- [`pdfDocument`](./document.md) — inverse operation.
+- [`pdfErrors`](../errors.md)

package/docs/api/document/xrefStreamWriter.md

@@ -0,0 +1,122 @@
+---
+module: pdfXrefStreamWriter
+category: pdf/document
+dependencies: [pdfErrors, pdfSerializer, pdfFlate]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfXrefStreamWriter
+
+> Alternative emitter using a `/Type /XRef` cross-reference stream instead of a classical table.
+
+**Module** `pdfXrefStreamWriter` | **Source** `packages/front/office/pdf/src/document/xrefStreamWriter.js` | **Deps** `pdfErrors`, `pdfSerializer`, `pdfFlate` | **Worker-safe** yes
+
+An alternative to `pdfWriter.writeDocument`: instead of a classical
+`xref`/`trailer` tail, `writeXrefStreamDocument` emits the cross-reference as a
+single `/Type /XRef` stream object (PDF 1.5+ / ISO 32000-2:2020 §7.5.8), with
+`/W` widths sized to fit the largest observed offset/generation values and a
+full `/Index`. Optionally (`useObjStm: true`), non-stream indirects with
+`gen === 0` are grouped into `/Type /ObjStm` compressed object streams
+(§7.5.7, chunked by `objStmCapacity`) and referenced as type-2 xref entries;
+stream objects and non-zero-generation objects are always left as
+uncompressed, type-1 entries. The xref-stream object itself is always
+appended last and given a fresh, freshly-computed object number, then
+flate-compressed like any other stream.
+
+> **Note:** a document produced by this writer round-trips through the
+> package's own read path — `pdfDocument.readDocument` composes
+> [`pdfCrossRefStream`](../syntax/crossRefStream.md) and
+> [`pdfObjStream`](../syntax/objStream.md), so both the plain and the
+> `useObjStm` outputs re-read end to end (see [`pdfDocument`](./document.md)).
+> What it cannot do is receive an **incremental update**:
+> [`pdfIncrementalWriter`](./incrementalWriter.md) emits classical tables only.
+
+## Resolve
+
+```js
+const xw = runtime.resolve('pdfXrefStreamWriter');
+// Returns: { writeXrefStreamDocument }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `writeXrefStreamDocument` | `(opts: XrefStmWriteOpts) => Uint8Array` | A full PDF: header + serialized indirects (+ ObjStm wrappers if requested) + xref-stream object + `startxref`/`%%EOF`. |
+
+### `XrefStmWriteOpts`
+
+```js
+{
+    indirects: [ { num, gen, value }, … ],  // required, num >= 1, no duplicates
+    root:      { num, gen },                // required
+    info?:     { num, gen },
+    id?:       [ string | Uint8Array, string | Uint8Array ],
+    version?:  string,          // default '2.0', must match /^\d\.\d$/
+    useObjStm?: boolean,        // default false — group compressible indirects into ObjStm(s)
+    objStmCapacity?: number     // default 64 — max members per ObjStm
+}
+```
+
+Object 0 (the free-list head) is always synthesized and included in the
+xref-stream's `/Index`; the xref-stream's own entry is always type 1
+(uncompressed), pointing at its own byte offset, per §7.5.8.
+
+## Examples
+
+### Minimal document, classical-style indirects, xref-stream output
+
+```js
+const { writeXrefStreamDocument } = runtime.resolve('pdfXrefStreamWriter');
+const bytes = writeXrefStreamDocument({
+    indirects: [
+        { num: 1, gen: 0, value: obj.dict({ Type: obj.name('Catalog'), Pages: obj.ref(2, 0) }) },
+        { num: 2, gen: 0, value: obj.dict({ Type: obj.name('Pages'), Kids: obj.array([obj.ref(3, 0)]), Count: obj.int(1) }) },
+        { num: 3, gen: 0, value: obj.dict({ Type: obj.name('Page'), Parent: obj.ref(2, 0),
+            MediaBox: obj.array([obj.int(0), obj.int(0), obj.int(612), obj.int(792)]) }) }
+    ],
+    root: { num: 1, gen: 0 }
+});
+```
+
+### Grouping non-stream objects into ObjStm(s)
+
+```js
+const bytes = writeXrefStreamDocument({
+    indirects,
+    root: { num: 1, gen: 0 },
+    useObjStm: true,
+    objStmCapacity: 32   // split across several ObjStms once exceeded
+});
+```
+
+### `/Info` and `/ID`
+
+```js
+const bytes = writeXrefStreamDocument({
+    indirects,
+    root: { num: 1, gen: 0 },
+    info: { num: 4, gen: 0 },
+    id: [Uint8Array.of(0x00, 0x11), Uint8Array.of(0xAA, 0xBB)]
+});
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/xrefstm-writer/bad-input` | `RenderError` | `opts.indirects` is not an array. |
+| `pdf/xrefstm-writer/no-root` | `RenderError` | `opts.root` missing or `opts.root.num` not finite. |
+| `pdf/xrefstm-writer/no-flate` | `RenderError` | `pdfFlate.encode` unavailable — required to emit the xref-stream and any ObjStm. |
+| `pdf/xrefstm-writer/bad-version` | `RenderError` | `version` doesn't match `/^\d\.\d$/`. |
+| `pdf/xrefstm-writer/bad-indirect` | `RenderError` | An indirect lacks a finite `num >= 1`. |
+| `pdf/xrefstm-writer/duplicate-num` | `RenderError` | Two indirects share the same `num`. |
+
+## See also
+
+- [`pdfWriter`](./writer.md) — the classical-xref counterpart (same `indirects`/`root`/`info`/`id` shape).
+- [`pdfDocument`](./document.md) — the top-level reader; it reads this module's output back, see the note above.
+- [`pdfCrossRefStream`](../syntax/crossRefStream.md) · [`pdfObjStream`](../syntax/objStream.md) — the parser-side counterparts `pdfDocument` composes to read back a document this module produced.
+- [`pdfFlate`](../syntax/filters/flate.md) — required for both the xref-stream payload and any ObjStm.

package/docs/api/embedded/README.md

@@ -0,0 +1,13 @@
+# Embedded Files — ISO 32000-2 §7.11
+
+Attachments and portfolios.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfFileSpec`](./fileSpec.md) | `{ typeFileSpec }` | `pdfErrors`, `pdfParser` | §7.11.3 — file specification. |
+| [`pdfEmbeddedFile`](./embeddedFile.md) | `{ typeEmbeddedFile }` | `pdfErrors`, `pdfParser` | §7.11.4 — embedded file stream. |
+| [`pdfCollection`](./collection.md) | `{ typeCollection }` | `pdfErrors`, `pdfParser` | §7.11.6 — portfolio. |
+
+## See also
+
+- [`pdfFileAttachAnnot`](../annot/fileAttach.md) · [`pdfAssociatedFiles`](../associatedFiles/README.md)

package/docs/api/embedded/collection.md

@@ -0,0 +1,80 @@
+---
+module: pdfCollection
+category: pdf/embedded
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfCollection
+
+> Collection (portfolio) — ISO 32000-2 §7.11.6.
+
+**Module** `pdfCollection` | **Source** `packages/front/office/pdf/src/embedded/collection.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/Type /Collection` lives on the Catalog. It describes a "PDF Portfolio": a cover PDF plus a set of embedded files. Entries: `/Schema` (dict of column definitions, kept raw), `/D` (default-displayed item name), `/View` (`D` details / `T` tile / `H` hidden / `C` custom), `/Sort` (kept raw), `/Navigator` (dict or ref, custom navigator extension).
+
+## Resolve
+
+```js
+const coll = runtime.resolve('pdfCollection');
+// Returns: { typeCollection }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeCollection` | `(dict) => Collection` | Typing. |
+
+### Shape `Collection`
+
+```js
+{
+    schema: PdfDict | undefined,       // /Schema, untyped
+    initialDoc: string | undefined,    // /D
+    view: 'D' | 'T' | 'H' | 'C' | undefined,
+    sort: PdfDict | undefined,         // /Sort, untyped
+    navigator: PdfDict | PdfRef | undefined,
+    raw, _extras
+}
+```
+
+## Examples
+
+### Reading a portfolio
+
+```js
+const coll = runtime.resolve('pdfCollection').typeCollection(catalog.collection);
+coll.view;         // 'D' = details
+coll.initialDoc;   // name of the item shown by default
+```
+
+### Items
+
+Portfolio items are the embedded files reachable from the Catalog's `/Names /EmbeddedFiles` name tree; each file spec carries `/CI` for the schema column values (kept raw on `pdfFileSpec`'s `.ci`).
+
+```js
+for (const [name, fsRef] of nameTree.entries(catalog.names.embeddedFiles)) {
+    const fs = runtime.resolve('pdfFileSpec').typeFileSpec(resolveRef(fsRef));
+    fs.ci;
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/collection/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/collection/bad-type` | `ParseError` | `/Type` is not `/Collection`. |
+| `pdf/collection/bad-schema` | `ParseError` | `/Schema` is not a dict. |
+| `pdf/collection/bad-d` | `ParseError` | `/D` is not a string. |
+| `pdf/collection/bad-view` | `ParseError` | `/View` is outside `D`/`T`/`H`/`C`. |
+| `pdf/collection/bad-sort` | `ParseError` | `/Sort` is not a dict. |
+| `pdf/collection/bad-navigator` | `ParseError` | `/Navigator` is neither a dict nor a ref. |
+
+## See also
+
+- [`pdfFileSpec`](./fileSpec.md) · [`pdfEmbeddedFile`](./embeddedFile.md)
+- [`pdfCatalog`](../document/catalog.md)

package/docs/api/embedded/embeddedFile.md

@@ -0,0 +1,86 @@
+---
+module: pdfEmbeddedFile
+category: pdf/embedded
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfEmbeddedFile
+
+> Embedded file stream — ISO 32000-2 §7.11.4.
+
+**Module** `pdfEmbeddedFile` | **Source** `packages/front/office/pdf/src/embedded/embeddedFile.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types the stream pointed at by a file spec's `/EF` entry. The stream dict carries `/Type /EmbeddedFile`, an optional `/Subtype` (MIME type as a name), and an optional `/Params` sub-dictionary (`/Size`, `/CreationDate`, `/ModDate`, `/CheckSum`). The binary content is the stream's raw (pre-filter) bytes.
+
+## Resolve
+
+```js
+const ef = runtime.resolve('pdfEmbeddedFile');
+// Returns: { typeEmbeddedFile }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeEmbeddedFile` | `(stream) => EmbeddedFile` | Typing. |
+
+### Shape `EmbeddedFile`
+
+```js
+{
+    subtype: string | undefined,     // MIME, e.g. 'application/pdf'
+    params: Params | undefined,
+    bytes: Uint8Array,                // raw stream (pre-filter)
+    raw: PdfStream,
+    _extras
+}
+```
+
+`Params` (the decoded `/Params` sub-dict):
+
+```js
+{
+    size: number | undefined,
+    creationDate: string | undefined,  // raw PDF date string, not parsed
+    modDate: string | undefined,       // raw PDF date string, not parsed
+    checkSum: string | undefined,      // 16-byte MD5, as the string bytes
+    raw, _extras
+}
+```
+
+## Examples
+
+### Extraction
+
+```js
+const ef = runtime.resolve('pdfEmbeddedFile').typeEmbeddedFile(stream);
+const dispatch = runtime.resolve('pdfFilterDispatch');
+const plain = dispatch.decode(ef.raw);
+```
+
+### Metadata
+
+```js
+ef.subtype;                // 'application/json'
+ef.params?.size;           // original byte size
+ef.params?.checkSum;       // MD5, as raw string bytes
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/embedded/not-stream` | `ParseError` | Argument is not a stream. |
+| `pdf/embedded/no-dict` | `ParseError` | Stream has no dict. |
+| `pdf/embedded/bad-type` | `ParseError` | `/Type` is not `/EmbeddedFile`. |
+| `pdf/embedded/bad-subtype` | `ParseError` | `/Subtype` is not a name. |
+| `pdf/embedded/bad-params` | `ParseError` | `/Params` is not a dict. |
+
+## See also
+
+- [`pdfFileSpec`](./fileSpec.md) · [`pdfCollection`](./collection.md)
+- [`pdfFilterDispatch`](../syntax/filters/README.md)

package/docs/api/embedded/fileSpec.md

@@ -0,0 +1,87 @@
+---
+module: pdfFileSpec
+category: pdf/embedded
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFileSpec
+
+> File specification — ISO 32000-2 §7.11.3.
+
+**Module** `pdfFileSpec` | **Source** `packages/front/office/pdf/src/embedded/fileSpec.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types a `/Type /Filespec` (or legacy `/Type /F`) dictionary. Entries: `/FS` (file system — `URL` or absent for local), `/F`/`/UF` (standard/Unicode path — `UF` preferred since 1.7), `/DOS`/`/Mac`/`/Unix` (platform-specific paths), `/ID` (array of 2 byte-strings — file identity), `/V` (volatile flag), `/EF` (dict of embedded-file stream refs — `F`/`UF`/`DOS`/`Mac`/`Unix`), `/RF` (related-files dict), `/Desc` (description), `/CI` (collection item), `/AFRelationship` (PDF 2.0 associated-file relationship name).
+
+## Resolve
+
+```js
+const fs = runtime.resolve('pdfFileSpec');
+// Returns: { typeFileSpec }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeFileSpec` | `(dict) => FileSpec` | Strict typing; throws on malformed entries. |
+
+### Shape `FileSpec`
+
+```js
+{
+    fs: 'URL' | undefined,
+    f, uf, dos, mac, unix,             // string paths, whichever are present
+    id: string[] | undefined,          // /ID, filtered to string items
+    volatile: boolean | undefined,     // /V
+    embedded: { F?, UF?, DOS?, Mac?, Unix? } | undefined,  // /EF entries (raw)
+    related: object | undefined,       // /RF entries (raw)
+    desc: string | undefined,
+    ci: PdfDict | undefined,           // /CI, untyped
+    afRelationship: string | undefined,
+    afRelationshipStandard: boolean,   // true iff afRelationship is one of
+                                        // the 8 standard values
+    raw, _extras
+}
+```
+
+## Examples
+
+### Reading an attachment
+
+```js
+const fs   = runtime.resolve('pdfFileSpec').typeFileSpec(dict);
+const file = runtime.resolve('pdfEmbeddedFile').typeEmbeddedFile(
+    doc._raw.resolve(fs.embedded.F)
+);
+fs.uf;            // 'attachment.txt'
+file.bytes;       // Uint8Array
+```
+
+### AF relationship (PDF 2.0)
+
+```js
+fs.afRelationship;          // 'Source' | 'Data' | 'Alternative' | 'Supplement' | …
+fs.afRelationshipStandard;  // false for a non-standard relationship name
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/filespec/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/filespec/bad-type` | `ParseError` | `/Type` is neither `/Filespec` nor `/F`. |
+| `pdf/filespec/bad-fs` | `ParseError` | `/FS` is not a name. |
+| `pdf/filespec/bad-path` | `ParseError` | `/F`/`/UF`/`/DOS`/`/Mac`/`/Unix` is not a string. |
+| `pdf/filespec/bad-id` | `ParseError` | `/ID` is not an array. |
+| `pdf/filespec/bad-ef` | `ParseError` | `/EF` is not a dict. |
+| `pdf/filespec/bad-rf` | `ParseError` | `/RF` is not a dict. |
+| `pdf/filespec/bad-desc` | `ParseError` | `/Desc` is not a string. |
+| `pdf/filespec/bad-afrel` | `ParseError` | `/AFRelationship` is not a name. |
+| `pdf/filespec/empty` | `ParseError` | No path and no `/EF` present. |
+
+## See also
+
+- [`pdfEmbeddedFile`](./embeddedFile.md) · [`pdfCollection`](./collection.md) · [`pdfAssociatedFiles`](../associatedFiles/associatedFiles.md)

package/docs/api/errors.md

@@ -0,0 +1,110 @@
+---
+module: pdfErrors
+category: pdf
+dependencies: []
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfErrors
+
+> Typed error hierarchy for `@awacloud/pdf` — base `PdfError` + 4 subclasses.
+
+**Module** `pdfErrors` | **Source** `packages/front/office/pdf/src/errors.js` | **Deps** none | **Worker-safe** yes
+
+Every error carries a stable kebab-case `code` (`'pdf/xref/truncated'`, `'pdf/page/bad-type'`, …), a human `message`, an optional structured `context`, and a chainable `cause`. No function in the package `throw new Error(...)` raw — everything goes through this hierarchy.
+
+The classes are not exported at the top level from `@awacloud/pdf`: the only export is the `pdfErrors` factory descriptor. Consumers resolve the 5 classes (`PdfError`, `ParseError`, `RenderError`, `ContractError`, `EncryptionError`) + the `isPdfError` helper via `runtime.resolve('pdfErrors')` or `pdfErrors.factory()`. The classes are declared inside the factory body, so **each `factory()` call creates a fresh set of classes**: an error built from one call is not `instanceof` the classes of another, and that call's `isPdfError` returns `false` for it. A `ModuleRuntime` caches the resolved instance, so every module resolved through the same runtime shares one set of classes — catch with the classes resolved from that runtime, or compare `e.code` / `e.name` when the error may come from elsewhere.
+
+## Resolve
+
+```js
+const errs = runtime.resolve('pdfErrors');
+// Returns: { PdfError, ParseError, RenderError, ContractError, EncryptionError, isPdfError }
+```
+
+Stand-alone (without a `ModuleRuntime`):
+
+```js
+import { pdfErrors } from '@awacloud/pdf';
+const { ParseError, EncryptionError } = pdfErrors.factory();
+```
+
+## API
+
+| Class / method | Signature | Returns |
+|------------------|-----------|----------|
+| `PdfError` | `new (code: string, message: string, opts?: { context?, cause? })` | Instance. |
+| `ParseError` | extends `PdfError` | Read-side / malformed bytes. |
+| `RenderError` | extends `PdfError` | Invalid model at write time (L1+). |
+| `ContractError` | extends `PdfError` | Consumer API contract violation. |
+| `EncryptionError` | extends `PdfError` | Crypto / signatures (L3+). |
+| `isPdfError` | `(e: any) => boolean` | `true` if `e instanceof PdfError`. |
+
+### `new PdfError(code, message, opts?)`
+
+`code`: kebab-case (e.g. `'pdf/bad-header'`). `opts.context`: arbitrary payload (`{ offset, num, gen, raw }`). `opts.cause`: source `Error` (re-throw).
+
+## Examples
+
+### Typed catch at the root
+
+```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 { isPdfError } = rt.resolve('pdfErrors');   // the classes api throws
+
+try {
+    api.read(bytes);
+} catch (e) {
+    if (isPdfError(e)) {
+        console.log(e.name, e.code, e.context);
+    } else {
+        throw e;
+    }
+}
+```
+
+### Disambiguation by subclass
+
+```js
+const errs = rt.resolve('pdfErrors');
+try { rt.resolve('pdf').read(bytes); }
+catch (e) {
+    if (e instanceof errs.ParseError)      console.log('malformed input');
+    else if (e instanceof errs.ContractError) console.log('API misuse');
+    else throw e;
+}
+```
+
+## Errors
+
+This page **defines** the codes; the modules emit them. Prefixes by domain:
+
+- `pdf/tokenizer/...` — emitted by [`pdfTokenizer`](./syntax/tokenizer.md).
+- `pdf/parser/...` — emitted by [`pdfParser`](./syntax/parser.md).
+- `pdf/xref/...` — emitted by [`pdfXref`](./syntax/xref.md).
+- `pdf/trailer/...` — emitted by [`pdfTrailer`](./syntax/trailer.md).
+- `pdf/catalog/...` — emitted by [`pdfCatalog`](./document/catalog.md).
+- `pdf/pages/...` — emitted by [`pdfPages`](./document/pages.md).
+- `pdf/page/...` — emitted by [`pdfPage`](./document/page.md).
+- `pdf/document/...` — emitted by [`pdfDocument`](./document/document.md).
+- `pdf/writer/...` — emitted by [`pdfWriter`](./document/writer.md); includes `pdf/writer/unresolvable-objects` (`RenderError`, `context.objects` = `Array<{ num, gen, code }>`), thrown by `assembleIndirects(model, { strict: true })` when an in-use object cannot be resolved.
+- `pdf/use/...` — emitted by [`pdf`](./pdf.md).
+- `pdf/sig/...` — emitted by [`pdfSignature`](./sig/signature.md), [`pdfByteRange`](./sig/byteRange.md), [`pdfCertChain`](./sig/certChain.md). The public-key verification path is wired and executed by construction — there is no `pdf/sig/pk-verify-not-wired` code; see [`pdfSignature`](./sig/signature.md)'s Errors table for the full `pdf/sig/*` and `pdf/sig/verify-pk/*` set.
+- `pdf/ts/...` — emitted by [`pdfTimestamp`](./sig/timestamp.md) (RFC 3161) and by [`pdfSignature`](./sig/signature.md)'s `/DocTimeStamp` verification branch.
+- `pdf/cert/...` — emitted by [`pdfCertChain`](./sig/certChain.md).
+- `pdf/crypto/...` — emitted by [`pdfStandardV5`](./crypto/standardV5.md), [`pdfStandardV6`](./crypto/standardV6.md), [`pdfPermissions`](./crypto/permissions.md), [`pdfSecurity`](./crypto/security.md), [`pdfAesGcm`](./crypto/aesGcm.md).
+- `pdf/sandbox/...` — emitted by the opt-in `pdfSandbox` module (bundle `pdf-full`).
+
+## See also
+
+- [`pdf`](./pdf.md) — emitter of `ContractError` on the `.use()` side.
+- [`pdfDocument`](./document/document.md) — propagates `ParseError` for full reads.