@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/document/encryptedWriter.md

@@ -0,0 +1,149 @@
+---
+module: pdfEncryptedWriter
+category: pdf/document
+dependencies: [pdfErrors, pdfWriter, pdfStandardV5, pdfStandardV6, pdfStandardV4, pdfAesGcm]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfEncryptedWriter
+
+> Emits an `/Encrypt`-protected PDF — wraps `pdfWriter` with the Standard Security Handlers.
+
+**Module** `pdfEncryptedWriter` | **Source** `packages/front/office/pdf/src/document/encryptedWriter.js` | **Deps** `pdfErrors`, `pdfWriter`, `pdfStandardV5`, `pdfStandardV6`, `pdfStandardV4`, `pdfAesGcm` | **Worker-safe** yes
+
+Encrypts a from-scratch indirect-object graph (same shape as `pdfWriter`'s
+`indirects`) and emits the result with an `/Encrypt` dictionary. Supports:
+
+- **V=4, R=4** (PDF 1.6) — method `'AESV2'` (AES-128-CBC, default) or `'V2'`
+  (RC4-128), delegated to `pdfStandardV4`.
+- **V=5, R=5** (historical AES-256, Adobe Extension Level 3) — delegated to `pdfStandardV5`.
+- **V=5, R=6** (ISO 32000-2:2020 hardening) — delegated to `pdfStandardV6`. Method
+  `'AESV3'` (AES-256-CBC, default) or `'AESV4'` (AES-256-GCM, ISO TS 32003 — requires `pdfAesGcm`).
+
+An optional distinct cipher for `/Type /EmbeddedFile` streams (`/EFF`, ISO
+32000-1 §7.6.5) is selected via `opts.encrypt.effMethod`, validated against
+the same (version, method) rules as the main `method`. Every `string` and
+`stream.raw` payload in the indirect graph is walked and encrypted in place
+(fresh IV per object) before the `/Encrypt` indirect is appended and the
+trailer patched.
+
+## Resolve
+
+```js
+const ew = runtime.resolve('pdfEncryptedWriter');
+// Returns: { writeEncryptedDocument }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `writeEncryptedDocument` | `(opts: EncWriteOpts) => EncWriteResult` | Encrypted PDF bytes plus the derived crypto material. |
+
+### `EncWriteOpts`
+
+Mirrors `pdfWriter`'s `WriteOpts` (`indirects`, `root`, `info?`, `id?`, `version?`) plus:
+
+```js
+{
+    encrypt: {
+        version: 4 | 5,
+        revision: 4 | 5 | 6,
+        method?:     'AESV2' | 'V2' | 'AESV3' | 'AESV4',  // default per version
+        effMethod?:  'AESV2' | 'V2' | 'AESV3' | 'AESV4',  // optional, /Type /EmbeddedFile only
+        keyBits?:    number,           // default 128 (V4) / 256 (V5)
+        ownerPassword?: string | Uint8Array,
+        userPassword?:  string | Uint8Array,
+        permissions?:   number,        // /P bitmask (Table 24)
+        encryptMetadata?: boolean,     // default true
+        randomBytes?: (n: number) => Uint8Array  // default globalThis.crypto.getRandomValues
+    }
+}
+```
+
+`randomBytes` supplies every key, salt and IV the writer draws. When it is
+omitted the writer uses `globalThis.crypto.getRandomValues`, read at call
+time; when neither exists the call throws `pdf/crypto/enc-writer/no-random`
+before producing any output. There is no non-cryptographic fallback.
+
+### `EncWriteResult`
+
+```js
+{
+    bytes: Uint8Array, encryptObjNum: number,
+    fek: Uint8Array, id: [Uint8Array, Uint8Array],
+    O, U, OE?, UE?, Perms?: Uint8Array,
+    version, revision, method, effMethod
+}
+```
+
+## Examples
+
+### V=5 R=6, AES-256-CBC, deterministic (test) randomness
+
+```js
+const ew = runtime.resolve('pdfEncryptedWriter');
+const out = ew.writeEncryptedDocument({
+    indirects, root: { num: 1, gen: 0 },
+    encrypt: {
+        version: 5, revision: 6,
+        ownerPassword: 'owner', userPassword: 'user',
+        permissions: -4,
+        randomBytes: makeDeterministicRand(1)   // test-only PRNG
+    }
+});
+out.bytes;   // encrypted PDF, ready to write to disk
+```
+
+### V=4 R=4, legacy RC4-128
+
+```js
+const out = ew.writeEncryptedDocument({
+    indirects, root: { num: 1, gen: 0 },
+    encrypt: { version: 4, revision: 4, method: 'V2', userPassword: 'user' }
+});
+```
+
+### Distinct cipher for embedded-file streams (`/EFF`)
+
+```js
+const out = ew.writeEncryptedDocument({
+    indirects, root: { num: 1, gen: 0 },
+    encrypt: {
+        version: 5, revision: 6, method: 'AESV3',
+        effMethod: 'AESV4',   // embedded files get AES-GCM, everything else AES-CBC
+        userPassword: 'user'
+    }
+});
+```
+
+### Recovering the FEK to decrypt
+
+```js
+const v6 = runtime.resolve('pdfStandardV6');
+const r = v6.tryPassword(typedEncryptDict, 'user', false);
+r.fileEncryptionKey; // === out.fek, when the password matches
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/crypto/enc-writer/missing-writer` | `EncryptionError` | Constructed without a `pdfWriter.writeDocument` function (module wiring). |
+| `pdf/crypto/enc-writer/unsupported-version` | `EncryptionError` | `(version, revision)` outside `{4,4}`, `{5,5}`, `{5,6}`. |
+| `pdf/crypto/enc-writer/missing-v4` | `EncryptionError` | `version: 4` requested but `pdfStandardV4` not supplied. |
+| `pdf/crypto/enc-writer/bad-input` | `RenderError` | `opts` missing or not an object. |
+| `pdf/crypto/enc-writer/no-encrypt` | `RenderError` | `opts.encrypt` missing. |
+| `pdf/crypto/enc-writer/bad-method` | `RenderError` | `method` incompatible with `version` (V=4 wants AESV2/V2, V=5 wants AESV3/AESV4). |
+| `pdf/crypto/enc-writer/missing-gcm` | `EncryptionError` | `method` or `effMethod` is `'AESV4'` but `pdfAesGcm` not supplied. |
+| `pdf/crypto/enc-writer/bad-eff-method` | `RenderError` | `effMethod` incompatible with `version`. |
+| `pdf/crypto/enc-writer/no-random` | `EncryptionError` | No `randomBytes` and no `globalThis.crypto.getRandomValues`. |
+| `pdf/crypto/enc-writer/no-trailer` / `no-trailer-close` | `RenderError` | Internal: the base `writeDocument` output didn't contain a patchable trailer (should not occur in practice). |
+
+## See also
+
+- [`pdfWriter`](./writer.md) — the base emitter this wraps.
+- [`pdfStandardV4`](../crypto/standardV4.md) · [`pdfStandardV5`](../crypto/standardV5.md) · [`pdfStandardV6`](../crypto/standardV6.md) · [`pdfAesGcm`](../crypto/aesGcm.md)
+- [`pdfSecurity`](../crypto/security.md) — the read-side dispatcher.

package/docs/api/document/incrementalWriter.md

@@ -0,0 +1,148 @@
+---
+module: pdfIncrementalWriter
+category: pdf/document
+dependencies: [pdfErrors, pdfSerializer, pdfTokenizer, pdfParser, pdfXref, pdfTrailer]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfIncrementalWriter
+
+> Append-only incremental update — ISO 32000-2 §7.5.6.
+
+**Module** `pdfIncrementalWriter` | **Source** `packages/front/office/pdf/src/document/incrementalWriter.js` | **Deps** `pdfErrors`, `pdfSerializer`, `pdfTokenizer`, `pdfParser`, `pdfXref`, `pdfTrailer` | **Worker-safe** yes
+
+`appendIncremental(pdfBytes, opts)` produces a new PDF that carries the
+original bytes **verbatim**, followed by an incremental-update section:
+`originalBytes ‖ newObjects ‖ xref ‖ trailer (with /Prev) ‖ %%EOF`. It locates
+the previous `startxref`/trailer to chain `/Prev` and carry over `/Root`,
+`/Info`, `/Size`, `/ID` unless the caller overrides them, then emits a fresh
+cross-reference section covering only the newly-added object numbers (one
+subsection per contiguous run — object 0's free-list head is always
+re-emitted), in the form the section-selection rule below picks. A reader that follows the `/Prev` chain (e.g. `pdfDocument`)
+sees the new entries win over older ones automatically. This is the
+non-destructive counterpart of a full re-emit: existing objects are never
+patched in place, only appended to — the mechanism behind PAdES levels
+T/LT/LTA (`pdfSign`) appending DSS/DocTimeStamp updates.
+
+Scope: no ObjStm grouping; hybrid-reference bases are refused (below).
+
+## Section forms and the selection rule
+
+The update's cross-reference section takes the form of the base's **newest**
+section, the one the final `startxref` designates:
+
+| Newest base section | Update written | Trailer keys come from |
+|---|---|---|
+| Classical `xref` table | Classical table + `trailer` dict, `/Prev` = the base's `startxref` offset. **Byte-identical** to the output of earlier versions, which wrote only this form. | The newest trailer dict alone. |
+| `/Type /XRef` stream (§7.5.8) | One uncompressed `/Type /XRef` stream object (no `/Filter`), carrying `/W`, `/Index`, `/Size`, `/Prev`, `/Root` and, when known, `/Info` and `/ID`. No `trailer` keyword. The stream takes object number `max(size, prevSize, newMaxNum + 1)`, and the written `/Size` is one more. | The newest-first merge of every section's dict in the `/Prev` chain, as [`pdfDocument`](./document.md) types it. So a linearized file whose `/Root` sits in only one of its two xref streams still resolves `/Root`. |
+| Hybrid-reference file: a classical trailer carrying `/XRefStm`, anywhere in the chain | **Refused**, `pdf/incremental/hybrid-base`. | — |
+| Neither a table nor an xref stream | **Refused**, `pdf/incremental/unsupported-base`. | — |
+
+Hybrid-reference bases are refused on purpose. A hybrid file carries two
+cross-reference forms, so two conforming readers can resolve different
+objects in it, and an update over it could read differently from viewer to
+viewer. The refusal is reversible: support can be added once a real hybrid
+file is available to choose and test a form against.
+
+The emitted stream is read back by this library's own reader: an update over
+a stream base re-reads with both the base objects and the appended ones
+reachable (`tests/real-shapes.integration.test.js`).
+
+## Resolve
+
+```js
+const iw = runtime.resolve('pdfIncrementalWriter');
+// Returns: { appendIncremental, appendIncrementalWithOffsets, readBaseTrailer }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `appendIncremental` | `(pdfBytes: Uint8Array, opts: AppendOpts) => Uint8Array` | The original bytes plus one incremental-update section. |
+| `appendIncrementalWithOffsets` | `(pdfBytes: Uint8Array, opts: AppendOpts) => { bytes, offsets, xrefOffset }` | Same as `appendIncremental`: same options, same validation and refusals, and `bytes` is byte-identical to its return value. `offsets` is a `Map<num, byteOffset>` giving where each update's `num gen obj` header starts in `bytes`. `xrefOffset` is where the update's cross-reference section (table or stream object) starts, which is the offset the new `startxref` records. |
+| `readBaseTrailer` | `(pdfBytes: Uint8Array) => { form, xrefOffset, trailer }` | The trailer an update over `pdfBytes` starts from. Nothing is written. `form` is `'table'` or `'stream'` (the newest section's form). `trailer` is the typed newest-first merge of every section's dict, as `pdfDocument` types it, for classical bases too. It is `null` when no section supplies a usable `/Size` and `/Root`. The base is vetted as `appendIncremental` vets it, so a hybrid-reference base throws `pdf/incremental/hybrid-base` and a `startxref` that designates neither form throws `pdf/incremental/unsupported-base`. |
+
+`appendIncrementalWithOffsets` and `readBaseTrailer` were added for
+[`pdfSign`](../sig/sign.md). The signer reads the merged `/Size`
+to number its signature object. It then patches the fixed-width `/ByteRange`
+placeholder inside that object, found from its offset, without changing the
+byte length. Every offset recorded in the cross-reference section therefore
+stays valid.
+
+### `AppendOpts`
+
+```js
+{
+    updates: [ { num, gen?, value }, … ],   // required — num >= 1
+    root?:   { num, gen },                  // defaults to the previous /Root
+    info?:   { num, gen },                  // defaults to the previous /Info
+    id?:     [ Uint8Array, Uint8Array ],    // defaults to the previous /ID
+    size?:   number,                        // defaults to max(prevSize, newMaxNum + 1)
+    encrypt?: { num, gen }                  // the base's /Encrypt, repeated in the update; never defaulted
+}
+```
+
+`opts.root` is mandatory only when no section of the base supplies a usable
+`/Root` (and `/Size`) — on a classical base, when the newest trailer does not.
+
+`opts.encrypt` is the base's `/Encrypt` reference (the `{ num, gen }` that
+`readBaseTrailer(...).trailer.encrypt` reports). It is written as
+`/Encrypt n g R` right after `/ID`, in the trailer or in the cross-reference
+stream dictionary. An update over an encrypted document needs it to
+conform (ISO 32000-2 §7.5.6): every trailer of an encrypted file carries
+`/Encrypt`. It is not taken from the base by default. Without it the output
+is byte-identical to what it was before the option existed. A direct
+`/Encrypt` dictionary (a typed `{ type: 'dict' }`) is written as it is in a
+classical trailer. Over a cross-reference stream base it is refused with
+`pdf/xref/bad-stream-section`.
+
+## Examples
+
+### Append a new indirect object to an existing PDF
+
+```js
+const iw = runtime.resolve('pdfIncrementalWriter');
+const updated = iw.appendIncremental(originalBytes, {
+    updates: [
+        { num: 42, gen: 0, value: { type: 'dict', entries: {
+            Type: { type: 'name', value: 'Example' }
+        } } }
+    ]
+});
+// `updated` re-parses via pdfDocument.readDocument, following /Prev.
+```
+
+### Update the Catalog to point at a new object (e.g. DSS)
+
+```js
+const nextNum = 43;
+const updated = iw.appendIncremental(signedBytes, {
+    updates: [
+        { num: nextNum, gen: 0, value: dssDict },
+        { num: 1, gen: 0, value: updatedCatalogDict } // re-defines obj 1
+    ],
+    root: { num: 1, gen: 0 }
+});
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/incremental/bad-input` | `RenderError` | `pdfBytes` is not a `Uint8Array` (every member). |
+| `pdf/incremental/no-updates` | `RenderError` | `opts.updates` is not an array. |
+| `pdf/incremental/bad-update` | `RenderError` | An update entry lacks a finite `num >= 1`. |
+| `pdf/incremental/no-startxref` | `ParseError` | `pdfBytes` has no `startxref` — not a valid PDF. |
+| `pdf/incremental/no-root` | `RenderError` | `opts.root` missing and no `/Root` can be read from the base (see the table above). |
+| `pdf/incremental/hybrid-base` | `RenderError` | A classical section in the base's `/Prev` chain carries `/XRefStm` (hybrid-reference file). Nothing is written. |
+| `pdf/incremental/unsupported-base` | `ParseError` | `startxref` designates neither a classical `xref` table nor a `/Type /XRef` stream. Nothing is written. |
+| `pdf/xref/bad-stream-section` | `RenderError` | Cross-reference stream base, and `opts.encrypt` is not an indirect reference (propagated from `pdfXref.buildXrefStream`). |
+
+## See also
+
+- [`pdfWriter`](./writer.md) — full re-emit (the `{ num, gen, value }` update shape mirrors `writeDocument`'s `indirects`).
+- [`pdfSign`](../sig/sign.md) — appends every signature (all levels), the LT/LTA DSS and the LTA DocTimeStamp through this module.
+- [`pdfDssBuilder`](../sig/dss.md) — produces the DSS updates typically appended here.

package/docs/api/document/page.md

@@ -0,0 +1,99 @@
+---
+module: pdfPage
+category: pdf/document
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfPage
+
+> Typing of a `/Type /Page` dictionary, ISO 32000-2 §7.7.3.3 — boxes, contents, rotate, annots.
+
+**Module** `pdfPage` | **Source** `packages/front/office/pdf/src/document/page.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Normalises a Page dictionary:
+
+- The boxes (`MediaBox`, `CropBox`, `BleedBox`, `TrimBox`, `ArtBox`) are
+  flattened to `[llx, lly, urx, ury]` numeric tuples.
+- `/Contents` is always exposed as `Array<{num, gen}>` (empty, single, or
+  multiple).
+- `/Rotate` is normalised to a multiple of 90 within `[0, 270]`; an invalid
+  value becomes 0.
+- `/Resources` is inheritable (§7.7.3.4) — not resolved here, kept raw.
+- Unknown entries go to `_extras`.
+
+## Resolve
+
+```js
+const page = runtime.resolve('pdfPage');
+// Returns: { typePage }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typePage` | `(dict: PdfDict) => TypedPage` | Typed record. |
+
+### `TypedPage` shape
+
+```js
+{
+    parent:    { num, gen } | null,
+    mediaBox:  [number, number, number, number] | null,
+    cropBox?:  [number, number, number, number],
+    bleedBox?, trimBox?, artBox?: same,
+    resources: PdfObject | null,
+    contents:  Array<{ num, gen }>,        // always an array, sometimes empty
+    rotate:    number,                     // 0 | 90 | 180 | 270
+    annots:    Array<PdfObject>,           // references or inline annotations
+    userUnit?: number,
+    tabs?:     string,
+    metadata?: PdfRef,
+    group?:    PdfObject,
+    raw:       PdfDict,
+    _extras:   Object<string, PdfObject>
+}
+```
+
+## Examples
+
+### Dimensions of the first page
+
+```js
+const doc = api.read(bytes);
+const p0 = doc.pages[0];
+const [llx, lly, urx, ury] = p0.mediaBox;  // e.g. [0, 0, 612, 792]
+console.log('rotate=', p0.rotate);
+```
+
+### Iterating the content streams
+
+```js
+for (const ref of p0.contents) {
+    const stream = doc._raw.resolve({ type: 'ref', ...ref });
+    // stream.raw: Uint8Array — decode /Filter with pdfFilterDispatch
+}
+```
+
+### Counting annotations
+
+```js
+doc.pages.reduce((n, p) => n + p.annots.length, 0);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/page/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/page/bad-type` | `ParseError` | `/Type` present but not `/Page`. |
+
+## See also
+
+- [`pdfPages`](./pages.md) — produces the reference list typed here.
+- [`pdfResources`](./resources.md) — resolves the inheritable `/Resources`.
+- [`pdfDocument`](./document.md)
+- [`pdfErrors`](../errors.md)

package/docs/api/document/pages.md

@@ -0,0 +1,82 @@
+---
+module: pdfPages
+category: pdf/document
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfPages
+
+> Page-tree walker, ISO 32000-2 §7.7.3 — `/Pages` tree → ordered list of leaf references.
+
+**Module** `pdfPages` | **Source** `packages/front/office/pdf/src/document/pages.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Descends `/Kids` recursively from the root pointed at by the Catalog. Guard
+rails: maximum depth (`maxDepth = 64`), maximum page count
+(`maxPages = 200000`), cycle detection through a `Set<'num:gen'>`. Tolerant of
+intermediate nodes without `/Type` (present in some older PDFs): the fallback
+test is the presence of `/Kids`.
+
+## Resolve
+
+```js
+const pages = runtime.resolve('pdfPages');
+// Returns: { walkPageTree, readPageCount }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `walkPageTree` | `(rootRef, resolveRef, opts?: { maxDepth?, maxPages? }) => Array<{num, gen}>` | Leaf references in document order. |
+| `readPageCount` | `(node: PdfDict) => number \| null` | Reads `/Count` off an intermediate node. |
+
+`resolveRef` must accept `{ type: 'ref', num, gen }` and return the materialised
+dictionary — typically `doc._raw.resolve`.
+
+## Examples
+
+### Standard walk
+
+```js
+const pages = runtime.resolve('pdfPages');
+const refs  = pages.walkPageTree(doc.catalog.pages, doc._raw.resolve);
+refs.length;             // page count
+refs[0];                 // { num: 3, gen: 0 }
+```
+
+### `/Count` sanity check
+
+```js
+const root = doc._raw.resolve({ type: 'ref', ...doc.catalog.pages });
+const declared = pages.readPageCount(root);
+const actual   = pages.walkPageTree(doc.catalog.pages, doc._raw.resolve).length;
+if (declared !== null && declared !== actual) {
+    console.warn('page tree /Count mismatch', { declared, actual });
+}
+```
+
+### Limiting the depth
+
+```js
+pages.walkPageTree(rootRef, resolve, { maxDepth: 16 });
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/pages/max-depth` | `ParseError` | Tree deeper than `maxDepth`. |
+| `pdf/pages/cycle` | `ParseError` | Reference already visited during the walk. |
+| `pdf/pages/not-dict` | `ParseError` | A resolved node is not a dictionary. |
+| `pdf/pages/too-many` | `ParseError` | More than `maxPages` leaves found. |
+| `pdf/pages/missing-kids` | `ParseError` | Intermediate node without `/Kids`. |
+| `pdf/pages/non-ref-kid` | `ParseError` | `/Kids` holds something other than a reference. |
+
+## See also
+
+- [`pdfPage`](./page.md) — types each leaf.
+- [`pdfCatalog`](./catalog.md) — supplies `catalog.pages`.
+- [`pdfDocument`](./document.md)

package/docs/api/document/resources.md

@@ -0,0 +1,102 @@
+---
+module: pdfResources
+category: pdf/document
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfResources
+
+> Resolution of a Page's or Form XObject's `/Resources` dictionary — ISO 32000-2 §7.8.3.
+
+**Module** `pdfResources` | **Source** `packages/front/office/pdf/src/document/resources.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Six named sub-dictionaries map the **local names** used inside a content stream
+to indirect objects: `/Font`, `/XObject`, `/ColorSpace`, `/ExtGState`,
+`/Pattern`, `/Shading`. A legacy `/ProcSet` is read but never required
+(deprecated in PDF 2.0). Resources are **inheritable**: a Page without its own
+`/Resources` walks up the page tree's `/Parent` chain (§7.7.3.4).
+`resolvePageResources` implements that walk with a cycle guard.
+
+Any category value may itself be an indirect reference (§7.3.10). Real
+documents do this: a measured ANSSI guide carries `/ExtGState` as
+`N 0 R` on 56 of its 58 pages. Rejecting that used to throw away the
+page's whole resource map, fonts included. The resolver you pass reaches
+objects inside object streams,
+because it is the document's own `_raw.resolve`.
+
+## Resolve
+
+```js
+const r = runtime.resolve('pdfResources');
+// Returns: { typeResources, resolvePageResources, lookupResource }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeResources` | `(dict\|null, resolveRef?) => Resources` | Direct typing. With `resolveRef`, an indirect category (`/Font 12 0 R`) is resolved through it; a category that resolves to `null` is treated as absent. |
+| `resolvePageResources` | `(pageDict, resolveRef) => Resources` | Inherited walk, at most 64 levels; passes `resolveRef` on to `typeResources`. |
+| `lookupResource` | `(resources, category, name, resolveRef?) => object` | Named lookup. |
+
+### `Resources` shape
+
+```js
+{
+    Font:       { [name]: PdfObject },
+    XObject:    { [name]: PdfObject },
+    ColorSpace: { [name]: PdfObject },
+    ExtGState:  { [name]: PdfObject },
+    Pattern:    { [name]: PdfObject },
+    Shading:    { [name]: PdfObject },
+    ProcSet:    string[] | null,
+    raw:        object | null
+}
+```
+
+`lookupResource` returns the resolved object directly (ref → object) when
+`resolveRef` is supplied, otherwise the typed entry (possibly a `ref`).
+
+## Examples
+
+### Page → Resources
+
+```js
+const r = runtime.resolve('pdfResources');
+const res = r.resolvePageResources(pageDict, doc._raw.resolve);
+res.Font;       // { F1: <typed font dict>, F2: … }
+res.ExtGState;  // { GS1: … }
+```
+
+### Look up a named font
+
+```js
+const fontDict = r.lookupResource(res, 'Font', 'F1', doc._raw.resolve);
+const typed = runtime.resolve('pdfFont').typeFont(fontDict);
+```
+
+### Direct typing without the walk
+
+```js
+const res = r.typeResources(pageDict.entries.Resources);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/resources/not-dict` | `ParseError` | `/Resources` is not a dictionary. |
+| `pdf/resources/bad-subdict` | `ParseError` | A sub-dictionary (`/Font`, …) is not a dictionary — or it is an indirect reference and no `resolveRef` was supplied. |
+| `pdf/resources/bad-shape` | `ParseError` | `/Resources` is neither a dictionary nor a reference. |
+| `pdf/resources/cycle` | `ParseError` | Cycle detected in the `/Parent` chain. |
+| `pdf/resources/unknown-category` | `ParseError` | Invalid category passed to `lookupResource`. |
+| `pdf/resources/missing-name` | `ParseError` | Name not found in the category. |
+
+## See also
+
+- [`pdfPage`](./page.md) — supplies `pageDict`.
+- [`pdfPages`](./pages.md) — page-tree walk.
+- [`pdfFont`](../font/font.md), [`pdfImages`](../content/images.md) — typers for the resolved entries.