@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/crypto/standardV4.md

@@ -0,0 +1,104 @@
+---
+module: pdfStandardV4
+category: pdf/crypto
+dependencies: [pdfErrors, aes, cbc, bitArray]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfStandardV4
+
+> Standard Security Handler V=4, R=4 — PDF 1.6 legacy (RC4-128 / AES-128-CBC).
+
+**Module** `pdfStandardV4` | **Source** `packages/front/office/pdf/src/crypto/standardV4.js` | **Deps** `pdfErrors`, `aes`, `cbc`, `bitArray` | **Worker-safe** yes
+
+Implements ISO 32000-1 §7.6.3 Algorithm 2 (128-bit file-key derivation, 50
+rounds of MD5), Algorithm 3 (`/O`), Algorithm 5 (`/U`), and per-object key
+derivation for the two V=4 crypt filter methods selectable via `/CF /StdCF`:
+
+- **AESV2** — AES-128-CBC; per-object key = `MD5(fileKey ‖ objId(3 LE) ‖ gen(2 LE) ‖ "sAlT")`
+  truncated to `min(fileKey.len + 5, 16)`; ciphertext is IV-prefixed, PKCS#7 padded.
+- **V2** — RC4-128; per-object key = `MD5(fileKey ‖ objId(3 LE) ‖ gen(2 LE))` truncated the same way.
+
+MD5 and RC4 are implemented locally (this handler predates fw's hash/cipher
+family and both primitives are legacy-only) — `aes`/`cbc` are the only fw
+crypto deps, for the AESV2 path.
+
+## Resolve
+
+```js
+const v4 = runtime.resolve('pdfStandardV4');
+// Returns: { tryPassword, decryptString, decryptStream,
+//            decryptEmbeddedFile, encryptEmbeddedFile,
+//            encryptString, encryptStream,
+//            buildOU, buildPerms,
+//            computeFileKey, computeU, computeO,
+//            objectKey, rc4, md5, padPassword, PASSWORD_PADDING }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `tryPassword` | `(typedEncrypt: { O, U, P, idFirst, EncryptMetadata? }, password, isOwner: boolean) => { fileEncryptionKey: Uint8Array \| null }` | `null` FEK on rejection; recovers the user password from `/O` first when `isOwner`. |
+| `decryptString` | `(typedEncrypt: { method }, fek, objNum, gen, ciphertext) => Uint8Array` | Dispatches on `typedEncrypt.method` (`'AESV2'` or `'V2'`/`'RC4'`). |
+| `decryptStream` | same signature as `decryptString` | Alias — identical implementation. |
+| `decryptEmbeddedFile` | same signature as `decryptString` | Alias for the `/EFF`-resolved method (ISO 32000-1 §7.6.5). |
+| `encryptString` | `(typedEncrypt: { method }, fek, objNum, gen, plaintext, iv?) => Uint8Array` | `iv` (16 bytes) required for `'AESV2'`; ignored for RC4. |
+| `encryptStream` | same signature as `encryptString` | Alias — identical implementation. |
+| `encryptEmbeddedFile` | same signature as `encryptString` | Alias for the `/EFF` write path. |
+| `buildOU` | `(ownerPassword, userPassword, P, idFirst: Uint8Array, encryptMetadata) => { O, U, fek }` | Builds a fresh `/O` + `/U` pair and the derived 16-byte file key. |
+| `buildPerms` | `() => null` | No-op — `/Perms` (Algorithm 8) is V≥5 only; kept for handler-dispatch symmetry with V5/V6. |
+| `computeFileKey` / `computeU` / `computeO` | internal Algorithm 2/5/3 primitives | Exposed for testing/interop. |
+| `objectKey` | `(fileKey, objNum, gen, isAes: boolean) => Uint8Array` | Per-object key derivation. |
+| `rc4` / `md5` | stream-cipher / hash primitives | Exposed for testing. |
+| `padPassword` | `(password: string \| Uint8Array) => Uint8Array` | The 32-byte padded password of Algorithm 2 step (a). Exposed for testing/interop. |
+| `PASSWORD_PADDING` | `Uint8Array` (32 bytes) | The Algorithm 2 padding string. |
+
+## Examples
+
+### Password check then decrypt (read side)
+
+```js
+const v4 = runtime.resolve('pdfStandardV4');
+const r = v4.tryPassword(
+    { O, U, P, idFirst, EncryptMetadata: true }, 'user', false);
+if (!r.fileEncryptionKey) throw new Error('bad password');
+const plain = v4.decryptStream(
+    { method: 'AESV2' }, r.fileEncryptionKey, objNum, gen, encryptedBytes);
+```
+
+### Building `/O` + `/U` for a fresh document (write side)
+
+```js
+const v4 = runtime.resolve('pdfStandardV4');
+const { O, U, fek } = v4.buildOU('owner', 'user', -4, idFirst, true);
+```
+
+This is the handler `pdfEncryptedWriter` selects internally for `version: 4, revision: 4`.
+
+## Errors
+
+All thrown as `EncryptionError`.
+
+| Code | When |
+|------|------|
+| `pdf/crypto/v4/missing-fw` | `aes`/`cbc`/`bitArray` fw modules unavailable (thrown at module construction). |
+| `pdf/crypto/v4/bad-password` | Password argument is neither `string` nor `Uint8Array`. |
+| `pdf/crypto/v4/bad-O` | `/O` is not a 32-byte `Uint8Array` (`computeFileKey`). |
+| `pdf/crypto/v4/bad-id` | First `/ID` element missing/invalid (`computeFileKey`, `buildOU`). |
+| `pdf/crypto/v4/bad-O-U` | `/O` or `/U` not exactly 32 bytes (`tryPassword`). |
+| `pdf/crypto/v4/bad-string` | AESV2 ciphertext shorter than 16 bytes (missing IV). |
+| `pdf/crypto/v4/bad-method` | `method` neither `'AESV2'` nor `'V2'`/`'RC4'` (decrypt or encrypt side). |
+| `pdf/crypto/v4/encrypt-bad-input` | `encryptString` plaintext is not a `Uint8Array`. |
+| `pdf/crypto/v4/encrypt-bad-iv` | AESV2 encrypt `iv` is not exactly 16 bytes. |
+| `pdf/crypto/v4/bad-ciphertext-len` / `bad-pt-len` | AES-CBC input length not a multiple of 16. |
+| `pdf/crypto/v4/aes-schedule-failed` / `aes-encrypt-schedule` | fw AES-128 key schedule failed. |
+| `pdf/crypto/v4/cbc-decrypt-failed` / `cbc-encrypt-failed` | fw CBC operation failed. |
+
+## See also
+
+- [`pdfEncryptedWriter`](../document/encryptedWriter.md) — selects this handler for `version: 4`.
+- [`pdfStandardV5`](./standardV5.md) · [`pdfStandardV6`](./standardV6.md) — modern (V=5) handlers.
+- [`pdfSecurity`](./security.md) — read-side dispatch.

package/docs/api/crypto/standardV5.md

@@ -0,0 +1,84 @@
+---
+module: pdfStandardV5
+category: pdf/crypto
+dependencies: [pdfErrors, aes, cbc, sha256, bitArray, pdfAesGcm]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfStandardV5
+
+> Standard Security Handler R=5 (historical AES-256, PDF 1.7 Adobe Extension Level 3).
+
+**Module** `pdfStandardV5` | **Source** `packages/front/office/pdf/src/crypto/standardV5.js` | **Deps** `pdfErrors`, `aes`, `cbc`, `sha256`, `bitArray`, `pdfAesGcm` | **Worker-safe** yes
+
+Implements the R=5 derivation: SHA-256 of password + validation salt → file encryption key via AES-CBC over `/OE`/`/UE`. This algorithm was deprecated by ISO 32000-2 in favor of R=6 hardening, but remains needed to read PDFs produced between 2009 and 2018. `pdfAesGcm` is an optional dependency, only required when a `/CF` crypt filter resolves to `AESV4` (ISO/TS 32003).
+
+## Resolve
+
+```js
+const v5 = runtime.resolve('pdfStandardV5');
+// Returns: { tryPassword, decryptString, decryptStream,
+//            encryptString, encryptStream,
+//            buildUUE, buildOOE, buildPerms }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `tryPassword` | `(typedEncrypt: { O, U, OE, UE }, password: string \| Uint8Array, isOwner: boolean) => { fileEncryptionKey: Uint8Array \| null }` | `null` on rejection. |
+| `decryptString` | `(typedEncrypt: { method? }, fek, objNum, gen, ciphertext) => Uint8Array` | AES-256-CBC (or AES-GCM when `typedEncrypt.method === 'AESV4'`), §7.6.4. `objNum`/`gen` are accepted but unused (V5 keys are not per-object). |
+| `decryptStream` | same signature as `decryptString` | Alias — identical implementation. |
+| `encryptString` | `(typedEncrypt: { method? }, fek, objNum, gen, plaintext, iv) => Uint8Array` | Encrypts (write side). `iv` must be 16 bytes for AES-CBC or 12 bytes for AESV4. |
+| `encryptStream` | same signature as `encryptString` | Alias — identical implementation. |
+| `buildUUE` | `(password, fek, valSalt: Uint8Array, keySalt: Uint8Array) => { U: Uint8Array(48), UE: Uint8Array(32) }` | Builds `/U` + `/UE` per Algorithm 2.A. |
+| `buildOOE` | `(password, fek, U48: Uint8Array, valSalt, keySalt) => { O: Uint8Array(48), OE: Uint8Array(32) }` | Builds `/O` + `/OE`. |
+| `buildPerms` | `(p: number, fek, encryptMetadata: boolean, randomBytes: (n) => Uint8Array) => Uint8Array(16)` | Algorithm 10 — encrypted `/Perms` block. |
+
+## Examples
+
+### Owner then user password attempt
+
+```js
+const v5 = runtime.resolve('pdfStandardV5');
+let r = v5.tryPassword(enc, ownerPwd, true);
+if (!r.fileEncryptionKey) r = v5.tryPassword(enc, userPwd, false);
+if (!r.fileEncryptionKey) throw new Error('bad password');
+const plain = v5.decryptStream(enc, r.fileEncryptionKey, num, gen, encStream);
+```
+
+### Building a fresh `/O`, `/U`, `/OE`, `/UE` set (write side)
+
+```js
+const v5 = runtime.resolve('pdfStandardV5');
+const { U, UE } = v5.buildUUE(userPwd, fek, valSalt, keySalt);
+const { O, OE } = v5.buildOOE(ownerPwd, fek, U, valSalt2, keySalt2);
+const permsBlock = v5.buildPerms(pBitmask, fek, true, cryptoRandomBytes);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/crypto/v5/missing-fw` | `EncryptionError` | fw bundle incomplete (thrown at module construction). |
+| `pdf/crypto/v5/bad-password` | `EncryptionError` | Invalid password argument. |
+| `pdf/crypto/v5/bad-ciphertext-len` | `EncryptionError` | Length not a multiple of 16. |
+| `pdf/crypto/v5/aes-schedule-failed` | `EncryptionError` | fw key schedule failed. |
+| `pdf/crypto/v5/cbc-decrypt-failed` | `EncryptionError` | fw CBC decrypt failed. |
+| `pdf/crypto/v5/bad-O-U` | `EncryptionError` | `/O` or `/U` not at least 48 bytes. |
+| `pdf/crypto/v5/bad-OE-UE` | `EncryptionError` | `/OE` or `/UE` not exactly 32 bytes. |
+| `pdf/crypto/v5/bad-string` | `EncryptionError` | Encrypted string shorter than 32 bytes (IV + 1 block). |
+| `pdf/crypto/v5/missing-gcm` | `EncryptionError` | `method === 'AESV4'` requested but `pdfAesGcm` was not supplied. |
+| `pdf/crypto/v5/bad-pt-len` | `EncryptionError` | Plaintext length not a multiple of 16 (`encryptString`/CBC path). |
+| `pdf/crypto/v5/aes-encrypt-schedule` | `EncryptionError` | fw key schedule failed on the encrypt side. |
+| `pdf/crypto/v5/cbc-encrypt-failed` | `EncryptionError` | fw CBC encrypt failed. |
+| `pdf/crypto/v5/encrypt-bad-input` | `EncryptionError` | `encryptString` plaintext is not a Uint8Array. |
+| `pdf/crypto/v5/encrypt-bad-iv` | `EncryptionError` | `iv` has the wrong length for the resolved method. |
+| `pdf/crypto/v5/perms-schedule` | `EncryptionError` | AES-256-ECB schedule failed while building `/Perms`. |
+
+## See also
+
+- [`pdfStandardV6`](./standardV6.md) — recommended algorithm.
+- [`pdfSecurity`](./security.md) · [`pdfPermissions`](./permissions.md) · [`pdfAesGcm`](./aesGcm.md)

package/docs/api/crypto/standardV6.md

@@ -0,0 +1,93 @@
+---
+module: pdfStandardV6
+category: pdf/crypto
+dependencies: [pdfErrors, aes, cbc, sha256, sha384, sha512, bitArray, pdfAesGcm]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfStandardV6
+
+> Standard Security Handler R=6 — AES-256 + hardening — ISO 32000-2 §7.6.4.
+
+**Module** `pdfStandardV6` | **Source** `packages/front/office/pdf/src/crypto/standardV6.js` | **Deps** `pdfErrors`, `aes`, `cbc`, `sha256`, `sha384`, `sha512`, `bitArray`, `pdfAesGcm` | **Worker-safe** yes
+
+Implements Algorithm 2.B (Annex A): 64+ rounds of SHA-{256/384/512} over password + salt (+ extra), resistant to brute-force/rainbow-table attacks. Which hash function runs at each round depends on the remainder mod 3 of the last byte of the round's AES-CBC output (`hardening-runaway` bounds the loop at 1024 rounds). String/stream decryption shape is identical to V5 (IV-prefixed AES-256-CBC, no per-object rekeying); `pdfAesGcm` is optional, only required for `AESV4` (ISO/TS 32003).
+
+## Resolve
+
+```js
+const v6 = runtime.resolve('pdfStandardV6');
+// Returns: { tryPassword, decryptString, decryptStream,
+//            encryptString, encryptStream,
+//            buildUUE, buildOOE, buildPerms }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `tryPassword` | `(typedEncrypt: { O, U, OE, UE }, password, isOwner: boolean) => { fileEncryptionKey: Uint8Array \| null }` | `null` = rejected (try the next password). |
+| `decryptString` | `(typedEncrypt: { method? }, fek, objNum, gen, ciphertext) => Uint8Array` | AES-256-CBC (or AES-GCM for `method === 'AESV4'`). |
+| `decryptStream` | same signature as `decryptString` | Alias — identical implementation. |
+| `encryptString` | `(typedEncrypt: { method? }, fek, objNum, gen, plaintext, iv) => Uint8Array` | Encrypts (write side). `iv`: 16 bytes CBC / 12 bytes AESV4. |
+| `encryptStream` | same signature as `encryptString` | Alias — identical implementation. |
+| `buildUUE` | `(password, fek, valSalt, keySalt) => { U: Uint8Array(48), UE: Uint8Array(32) }` | Algorithm 8 / 2.B with hardening. |
+| `buildOOE` | `(password, fek, U48, valSalt, keySalt) => { O: Uint8Array(48), OE: Uint8Array(32) }` | Same, owner side. |
+| `buildPerms` | `(p: number, fek, encryptMetadata: boolean, randomBytes: (n) => Uint8Array) => Uint8Array(16)` | Algorithm 10 — encrypted `/Perms` block. |
+
+## Examples
+
+### Full decryption
+
+```js
+const v6 = runtime.resolve('pdfStandardV6');
+const r = v6.tryPassword(enc, userPwd, false);
+if (!r.fileEncryptionKey) throw new Error('rejected');
+for (const obj of doc._raw.encryptedStreams) {
+    obj.plain = v6.decryptStream(enc, r.fileEncryptionKey, obj.num, obj.gen, obj.raw);
+}
+```
+
+### Permission validation
+
+```js
+const perms = runtime.resolve('pdfPermissions');
+const ok = perms.verifyPermsField(enc, r.fileEncryptionKey);
+ok.encryptMetadata === enc.EncryptMetadata;
+```
+
+### Building a fresh handler set (write side)
+
+```js
+const v6 = runtime.resolve('pdfStandardV6');
+const { U, UE } = v6.buildUUE(userPwd, fek, valSalt, keySalt);
+const { O, OE } = v6.buildOOE(ownerPwd, fek, U, valSalt2, keySalt2);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/crypto/v6/missing-fw` | `EncryptionError` | fw bundle incomplete (thrown at module construction). |
+| `pdf/crypto/v6/bad-password` | `EncryptionError` | Invalid password argument. |
+| `pdf/crypto/v6/bad-pt-len` | `EncryptionError` | Plaintext length not a multiple of 16. |
+| `pdf/crypto/v6/aes-schedule-failed` | `EncryptionError` | Key schedule failed (hardening round). |
+| `pdf/crypto/v6/bad-ct-len` | `EncryptionError` | Ciphertext length not a multiple of 16. |
+| `pdf/crypto/v6/aes-decrypt-schedule` | `EncryptionError` | Key schedule failed on decrypt. |
+| `pdf/crypto/v6/cbc-decrypt-failed` | `EncryptionError` | CBC decrypt failed. |
+| `pdf/crypto/v6/hardening-runaway` | `EncryptionError` | Hardening loop exceeded 1024 rounds. |
+| `pdf/crypto/v6/bad-O-U` | `EncryptionError` | `/O`/`/U` not at least 48 bytes. |
+| `pdf/crypto/v6/bad-OE-UE` | `EncryptionError` | `/OE`/`/UE` not exactly 32 bytes. |
+| `pdf/crypto/v6/bad-string` | `EncryptionError` | Encrypted string shorter than 32 bytes. |
+| `pdf/crypto/v6/missing-gcm` | `EncryptionError` | `method === 'AESV4'` requested but `pdfAesGcm` was not supplied. |
+| `pdf/crypto/v6/encrypt-bad-input` | `EncryptionError` | `encryptString` plaintext is not a Uint8Array. |
+| `pdf/crypto/v6/encrypt-bad-iv` | `EncryptionError` | `iv` has the wrong length for the resolved method. |
+| `pdf/crypto/v6/perms-schedule` | `EncryptionError` | AES-256-ECB schedule failed while building `/Perms`. |
+
+## See also
+
+- [`pdfStandardV5`](./standardV5.md) — legacy.
+- [`pdfAesGcm`](./aesGcm.md) — ISO/TS 32003 (AES-GCM).
+- [`pdfSecurity`](./security.md)

package/docs/api/destination/README.md

@@ -0,0 +1,9 @@
+# Destination — ISO 32000-2 §12.3.2
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfDestination`](./destination.md) | `{ typeDestination }` | `pdfErrors`, `pdfParser` | Explicit + named destinations. |
+
+## See also
+
+- [Action](../action/README.md) · [Outline](../outline/README.md) · [Annot](../annot/link.md)

package/docs/api/destination/destination.md

@@ -0,0 +1,79 @@
+---
+module: pdfDestination
+category: pdf/destination
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfDestination
+
+> Explicit and named destinations — ISO 32000-2 §12.3.2.
+
+**Module** `pdfDestination` | **Source** `packages/front/office/pdf/src/destination/destination.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+A destination describes a view within a document: `[page, fit, …args]`. `fit` is one of `XYZ`, `Fit`, `FitH`, `FitV`, `FitR`, `FitB`, `FitBH`, `FitBV`. `typeDestination` accepts an explicit array, a name/string (looked up through the supplied names dict — either `/Names /Dests` (PDF 1.2+ name tree) or the legacy PDF 1.1 `/Dests` dict), or a dict carrying `/D`.
+
+## Resolve
+
+```js
+const dest = runtime.resolve('pdfDestination');
+// Returns: { typeDestination }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeDestination` | `(value, namesDict?, resolveRef?) => Destination` | Typed form. |
+
+### Shape `Destination`
+
+```js
+{
+    page: { num, gen } | { pageNum: number },   // explicit ref, or remote page index
+    fit: 'XYZ' | 'Fit' | 'FitH' | 'FitV' | 'FitR' | 'FitB' | 'FitBH' | 'FitBV',
+    args: (number | null)[]                      // per `fit`'s expected arity
+}
+```
+
+## Examples
+
+### Explicit destination
+
+```js
+const dest = runtime.resolve('pdfDestination');
+const d = dest.typeDestination(dictItemD, null, resolveRef);
+d.fit === 'XYZ';
+d.args;     // [left, top, zoom]
+```
+
+### Named destination
+
+```js
+const d = dest.typeDestination(
+    { type: 'name', value: 'chap1' },
+    catalog.names?.entries?.Dests,
+    resolveRef
+);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/dest/bad-input` | `ParseError` | `value` is null or not a typed PDF object. |
+| `pdf/dest/bad-type` | `ParseError` | Value is neither array, name nor string. |
+| `pdf/dest/empty` | `ParseError` | Destination array is empty. |
+| `pdf/dest/bad-page` | `ParseError` | First element is neither a ref nor an int. |
+| `pdf/dest/missing-fit` | `ParseError` | Second element missing or not a name. |
+| `pdf/dest/unknown-fit` | `ParseError` | `fit` outside the known set. |
+| `pdf/dest/bad-arg` | `ParseError` | A fit argument is neither a number nor null. |
+| `pdf/dest/no-names` | `ParseError` | Named destination with no `namesDict` supplied. |
+| `pdf/dest/unknown-name` | `ParseError` | Name not found in `/Dests`. |
+
+## See also
+
+- [`pdfOutline`](../outline/outline.md) · [`pdfAction`](../action/action.md)
+- [`pdfLinkAnnot`](../annot/link.md)

package/docs/api/document/README.md

@@ -0,0 +1,29 @@
+# Document — ISO 32000-2 §7.7
+
+Typed document layer — Catalog, page tree, Page, read orchestrator, writers.
+
+| Module | Returns | Deps | Description |
+|--------|---------|------|-------------|
+| [`pdfCatalog`](./catalog.md) | `{ typeCatalog }` | `pdfErrors`, `pdfParser` | §7.7.2 — Catalog. |
+| [`pdfPages`](./pages.md) | `{ walkPageTree, readPageCount }` | `pdfErrors`, `pdfParser` | §7.7.3 — page-tree walker. |
+| [`pdfPage`](./page.md) | `{ typePage }` | `pdfErrors`, `pdfParser` | §7.7.3.3 — typed Page. |
+| [`pdfDocument`](./document.md) | `{ readDocument, readHeader }` | `pdfErrors`, `pdfTokenizer`, `pdfParser`, `pdfXref`, `pdfTrailer`, `pdfCatalog`, `pdfPage`, `pdfPages`, `pdfCrossRefStream`, `pdfObjStream`, `pdfFilterDispatch` | Top-level read orchestrator (classic tables, cross-reference streams, object streams, hybrid files). |
+| [`pdfResources`](./resources.md) | `{ typeResources, resolvePageResources, lookupResource }` | `pdfErrors`, `pdfParser` | §7.8.3 — inheritable `/Resources`. |
+| [`pdfWriter`](./writer.md) | `{ writeDocument, assembleIndirects }` | `pdfErrors`, `pdfSerializer` | Model → bytes §7.5.2–7.5.5. |
+| [`pdfBuilder`](./builder.md) | `{ builder }` | `pdfErrors`, `pdfParserObj`, `pdfWriter` | Chainable constructive DSL over `pdfWriter`. |
+| [`pdfIncrementalWriter`](./incrementalWriter.md) | `{ appendIncremental, appendIncrementalWithOffsets, readBaseTrailer }` | `pdfErrors`, `pdfSerializer`, `pdfTokenizer`, `pdfParser`, `pdfXref`, `pdfTrailer` | §7.5.6 — append-only incremental update. |
+| [`pdfEncryptedWriter`](./encryptedWriter.md) | `{ writeEncryptedDocument }` | `pdfErrors`, `pdfWriter`, `pdfStandardV5`, `pdfStandardV6`, `pdfStandardV4`, `pdfAesGcm` | Wraps `pdfWriter` with the Standard Security Handlers. |
+| [`pdfXrefStreamWriter`](./xrefStreamWriter.md) | `{ writeXrefStreamDocument }` | `pdfErrors`, `pdfSerializer`, `pdfFlate` | §7.5.8 — xref-stream + ObjStm alternative emitter. |
+
+## Common pattern
+
+```js
+const doc = runtime.resolve('pdfDocument').readDocument(bytes);
+doc.pages.forEach(p => console.log(p.mediaBox));
+```
+
+## See also
+
+- [Syntax layer](../syntax/README.md)
+- [Top-level `pdf`](../pdf.md)
+- [Read pipeline](../../guide/read-pdf.md)