@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/README.md

@@ -0,0 +1,38 @@
+# API Reference
+
+| Section | Modules | Description |
+|---------|---------|-------------|
+| [Syntax](./syntax/README.md) | `pdfTokenizer`, `pdfParser`, `pdfXref`, `pdfTrailer` | ISO 32000-2 §7.2–§7.5 — binary layer. |
+| [Document](./document/README.md) | `pdfCatalog`, `pdfPages`, `pdfPage`, `pdfDocument`, `pdfResources`, `pdfWriter`, `pdfBuilder`, `pdfIncrementalWriter`, `pdfEncryptedWriter`, `pdfXrefStreamWriter` | §7.7 / §7.8.3 — typed document layer. |
+| [Content](./content/README.md) | `pdfContentOps`, `pdfContentStream`, `pdfGraphics`, `pdfText`, `pdfColor`, `pdfImages` | §7.8 / §8 / §9.3–§9.4 — content streams. |
+| [Font](./font/README.md) | `pdfFont`, `pdfFontEncoding`, `pdfType3`, `pdfFontEmbed` | §9.6 / §9.7 / §9.9 — fonts. |
+| [Form](./form/README.md) | `pdfAcroForm`, `pdfFieldTree`, `pdfButtonField`, `pdfTextField`, `pdfChoiceField`, `pdfSignatureField`, `pdfAppearance` | §12.7 / §12.5.5 — interactive forms. |
+| [Annot](./annot/README.md) | `pdfAnnot`, `pdfTextAnnot`, `pdfLinkAnnot`, `pdfMarkupAnnot`, `pdfShapeAnnot`, `pdfFreeTextAnnot`, `pdfInkAnnot`, `pdfStampAnnot`, `pdfFileAttachAnnot`, `pdfWidgetAnnot`, `pdfPopupAnnot`, `pdfProjectionAnnot`, `pdfRedactAnnot` | §12.5 — annotations. |
+| [Tagged](./tagged/README.md) | `pdfStructTree`, `pdfStructElement`, `pdfRoleMap`, `pdfParentTree`, `pdfClassMap`, `pdfMarkedContent` | §14.6 / §14.7 / §14.8 — Tagged PDF, PDF/UA-2. |
+| [Crypto](./crypto/README.md) | `pdfSecurity`, `pdfStandardV4`, `pdfStandardV5`, `pdfStandardV6`, `pdfPermissions`, `pdfAesGcm` | §7.6 + ISO TS 32003 — encryption. |
+| [Sig](./sig/README.md) | `pdfSignature`, `pdfSign`, `pdfByteRange`, `pdfTimestamp`, `pdfCertChain`, `pdfDssBuilder`, `pdfSigOids`, `pdfSha1` | §12.8 + ISO TS 32001/32002 — signatures. |
+| [OCG](./ocg/README.md) | `pdfOCG`, `pdfOCConfig` | §8.11 — optional content. |
+| [Outline](./outline/README.md) | `pdfOutline` | §12.3.3 — bookmarks. |
+| [Destination](./destination/README.md) | `pdfDestination` | §12.3.2. |
+| [Action](./action/README.md) | `pdfAction`, `pdfActionGoTo`, `pdfActionUri`, `pdfActionNamed`, `pdfActionLaunch` | §12.6 — actions. |
+| [Embedded](./embedded/README.md) | `pdfFileSpec`, `pdfEmbeddedFile`, `pdfCollection` | §7.11 — attachments. |
+| [Linearization](./linearization/README.md) | `pdfLinearization` | Annex F — Fast Web View. |
+| [Metadata](./metadata/README.md) | `pdfInfo`, `pdfXmp` | §14.3 — metadata. |
+| [Prepress](./prepress/README.md) | `pdfOutputIntent`, `pdfPageBoundary` | §14.11 — prepress. |
+| [Associated Files](./associatedFiles/README.md) | `pdfAssociatedFiles` | PDF 2.0 / PDF20_AN002-AF. |
+| [Extras](./extra/README.md) | 32 opt-in modules (P0/P1/P2/P3/legacy) | L3+ coverage — color fonts, CID, full ExtGState, PAdES, AES-GCM, PDF/A, PDF/X, PDF/UA, WTPDF, 3D, JBIG2, legacy XFA, RC4, LZW… |
+| [Bundles](./bundles/README.md) | `pdf-large`, `pdf-full`, `pdf-legacy` | Pre-wired factories combining core + extras. |
+
+## Top-level
+
+| Module | Source | Description |
+|--------|--------|-------------|
+| [`pdf`](./pdf.md) | [`src/pdf.js`](../../src/pdf.js) | Public orchestrator, `.use()` hook. |
+| [`pdfErrors`](./errors.md) | [`src/errors.js`](../../src/errors.js) | `PdfError` hierarchy. |
+| [`pdfShared`](./_shared/README.md) | [`src/_shared/index.js`](../../src/_shared/index.js) | Byte-level constants and stateless helpers. |
+| `main` (re-export) | [`src/main.js`](../../src/main.js) | See [`main`](./main.md). |
+
+## See also
+
+- [Documentation index](../README.md)
+- [Guide getting-started](../guide/getting-started.md)

package/docs/api/_shared/README.md

@@ -0,0 +1,91 @@
+---
+module: pdfShared
+category: _shared
+dependencies: []
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfShared
+
+> PDF byte-level constants and stateless helpers, shared across `@awacloud/pdf` factories.
+
+**Module** `pdfShared` | **Source** `packages/front/office/pdf/src/_shared/index.js` | **Deps** _(none)_ | **Worker-safe** yes
+
+Magic bytes, ASCII byte values, the ISO 32000-2 §7.2 character classes, a hex
+lookup table, text codec instances and a few byte helpers. `pdfTokenizer` and
+the top-level [`pdf`](../pdf.md) declare it as a dependency; other modules
+(the filters, `pdfWriter`, `pdfSerializer`) still carry their own inline
+copies of some of these helpers.
+
+## Resolve
+
+```js
+const shared = runtime.resolve('pdfShared');
+// → { HEADER_PREFIX, EOF_MARKER, BINARY_MARKER,
+//     ASCII,
+//     isWs, isEol, isDigit, isHex, isDelim, isRegular, hexNibble,
+//     HEX_LO,
+//     te, tdUtf8, tdUtf8Lenient, tdLatin1,
+//     encodeAscii, decodeUtf8, decodeUtf8Lenient, decodeLatin1,
+//     pad10, hexLit, bytesEqual, concatBytes }
+```
+
+`pdfShared` is exported by name from the package root (`import { pdfShared }
+from '@awacloud/pdf'`); it has no sub-path of its own.
+
+## API
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `HEADER_PREFIX` | `Uint8Array` | The 5 bytes `%PDF-`. |
+| `EOF_MARKER` | `Uint8Array` | The 5 bytes `%%EOF`. |
+| `BINARY_MARKER` | `Uint8Array` | The binary-marker comment line written after the header (§7.5.2): bytes `0x25 0xE2 0xE3 0xCF 0xD3 0x0A`. |
+| `ASCII` | `object<string, number>` | Frozen byte values: `NUL`, `HT`, `LF`, `FF`, `CR`, `SP`, `HASH`, `PERCENT`, `LPAREN`, `RPAREN`, `PLUS`, `MINUS`, `DOT`, `SLASH`, `ZERO`, `NINE`, `LANGLE`, `RANGLE`, `A_UP`, `F_UP`, `Z_UP`, `LBRACK`, `BACKSLASH`, `RBRACK`, `A_LO`, `F_LO`, `Z_LO`, `LBRACE`, `RBRACE`. |
+| `isWs(b)` | `(number) => boolean` | PDF white-space byte (`NUL`, `HT`, `LF`, `FF`, `CR`, `SP`), §7.2.3. |
+| `isEol(b)` | `(number) => boolean` | `LF` or `CR`. |
+| `isDigit(b)` | `(number) => boolean` | `0`–`9`. |
+| `isHex(b)` | `(number) => boolean` | `0`–`9`, `A`–`F`, `a`–`f`. |
+| `isDelim(b)` | `(number) => boolean` | A delimiter: `( ) < > [ ] { } / %`. |
+| `isRegular(b)` | `(number) => boolean` | Neither white space nor a delimiter. |
+| `hexNibble(b)` | `(number) => number` | The value of one hex digit byte, `-1` when `b` is not one. |
+| `HEX_LO` | `Int8Array` (128 entries) | Lookup table with the same result as `hexNibble`, indexed by ASCII byte. |
+| `te` | `TextEncoder` | One instance per factory call. |
+| `tdUtf8` / `tdUtf8Lenient` | `TextDecoder` | UTF-8 decoders. Both are non-fatal (`fatal: false`, the `TextDecoder` default): a malformed sequence decodes to U+FFFD in either. |
+| `tdLatin1` | `TextDecoder` | `latin1` decoder. |
+| `encodeAscii(s)` | `(string) => Uint8Array` | `te.encode(s)` — UTF-8, so it equals ASCII only for an ASCII string. |
+| `decodeUtf8(bytes)` / `decodeUtf8Lenient(bytes)` | `(Uint8Array) => string` | Wrappers over `tdUtf8` / `tdUtf8Lenient`. |
+| `decodeLatin1(bytes)` | `(Uint8Array) => string` | Wrapper over `tdLatin1`. |
+| `pad10(n)` | `(number) => string` | `n` left-padded with zeros to 10 digits (a cross-reference entry offset). |
+| `hexLit(bytes)` | `(Uint8Array) => string` | The PDF hex-string literal `<…>`, upper-case digits. |
+| `bytesEqual(a, b, n?)` | `(Uint8Array, Uint8Array, number?) => boolean` | Equality of two byte arrays without an early exit. Without `n`, both lengths must match; with `n`, compares the first `n` bytes and requires both arrays to be at least that long. `false` when either array is missing. |
+| `concatBytes(arrays)` | `(Uint8Array[]) => Uint8Array` | One new array holding every input in order. |
+
+## Examples
+
+```js
+const shared = runtime.resolve('pdfShared');
+
+shared.decodeLatin1(shared.HEADER_PREFIX);              // '%PDF-'
+shared.isWs(shared.ASCII.SP);                           // true
+shared.hexNibble(0x61);                                 // 10 ('a')
+shared.hexLit(Uint8Array.of(0xde, 0xad));               // '<DEAD>'
+shared.pad10(42);                                       // '0000000042'
+shared.bytesEqual(Uint8Array.of(1, 2, 3), Uint8Array.of(1, 2, 4), 2);   // true
+shared.concatBytes([Uint8Array.of(1), Uint8Array.of(2, 3)]);            // Uint8Array [1, 2, 3]
+```
+
+## Notes
+
+- **Worker-safe**: every member is a constant, a pure function, or a codec
+  instance created inside the factory body, so `factory.toString()` is a
+  self-contained closure.
+- **No mutable module state**: `ASCII` is frozen; each `factory()` call
+  creates its own codec instances and tables.
+
+## See also
+
+- [`pdfErrors`](../errors.md) — the other dependency-free core module.
+- [`pdfTokenizer`](../syntax/tokenizer.md) — a consumer of the character classes.
+- [API index](../README.md)

package/docs/api/action/README.md

@@ -0,0 +1,29 @@
+# Actions — ISO 32000-2 §12.6
+
+Actions executed from annotations, outlines, form fields.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfAction`](./action.md) | `{ typeAction }` | `pdfErrors`, `pdfParser` | Dispatcher, §12.6. |
+| [`pdfActionGoTo`](./goTo.md) | `{ typeGoTo, typeGoToR, typeGoToE }` | `pdfErrors`, `pdfParser` | §12.6.4.2–4. |
+| [`pdfActionUri`](./uri.md) | `{ typeUri }` | `pdfErrors`, `pdfParser` | §12.6.4.7. |
+| [`pdfActionNamed`](./named.md) | `{ typeNamed }` | `pdfErrors`, `pdfParser` | §12.6.4.11. |
+| [`pdfActionLaunch`](./launch.md) | `{ typeLaunch }` | `pdfErrors`, `pdfParser` | §12.6.4.5. |
+
+## Pattern
+
+```js
+const a = runtime.resolve('pdfAction');
+const typers = {
+    GoTo:  runtime.resolve('pdfActionGoTo').typeGoTo,
+    GoToR: runtime.resolve('pdfActionGoTo').typeGoToR,
+    URI:   runtime.resolve('pdfActionUri').typeUri,
+    Named: runtime.resolve('pdfActionNamed').typeNamed,
+    Launch:runtime.resolve('pdfActionLaunch').typeLaunch
+};
+const action = a.typeAction(dict, typers);
+```
+
+## See also
+
+- [Destination](../destination/README.md) · [Outline](../outline/README.md) · [Annot — Link / Widget](../annot/README.md)

package/docs/api/action/action.md

@@ -0,0 +1,81 @@
+---
+module: pdfAction
+category: pdf/action
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAction
+
+> Action dispatcher — ISO 32000-2 §12.6, walks `/Next` with cycle protection.
+
+**Module** `pdfAction` | **Source** `packages/front/office/pdf/src/action/action.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`typeAction(dict, typers, opts)` dispatches on `/S` to the specialized typer supplied in `typers` (`GoTo`, `GoToR`, `GoToE`, `URI`, `Named`, `Launch`, …). When no matching typer is supplied, falls back to a generic `{ kind, raw, _extras }` record — additionally flagged `vendor: true` when `/S` is outside the set of standard action kinds this module recognizes by name (Thread, Sound, Movie, Hide, SubmitForm, ResetForm, ImportData, SetOCGState, Rendition, Trans, GoTo3DView, GoToDp, JavaScript, RichMediaExecute, plus the ones with dedicated typers). Follows the `/Next` chain (recursive, either a single dict or an array) bounded by depth (`opts.maxDepth`, default **16**) and detecting cycles via a `Set` of already-visited dict objects.
+
+## Resolve
+
+```js
+const a = runtime.resolve('pdfAction');
+// Returns: { typeAction }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeAction` | `(dict, typers, opts?: { maxDepth? }) => Action` | Dispatched record + `next` chain. |
+
+`typers` is a dict `{ GoTo: fn, GoToR: fn, URI: fn, Named: fn, Launch: fn, … }` — typically composed from the other action modules.
+
+### Shape `Action`
+
+```js
+{ kind, /* fields per typer, or { raw, _extras, vendor? } for unrecognized/generic kinds */, next?: Action[] }
+```
+
+## Examples
+
+### Composing the typers
+
+```js
+const a = runtime.resolve('pdfAction');
+const goTo = runtime.resolve('pdfActionGoTo');
+const uri  = runtime.resolve('pdfActionUri');
+const typers = {
+    GoTo:  goTo.typeGoTo,
+    GoToR: goTo.typeGoToR,
+    URI:   uri.typeUri,
+    Named: runtime.resolve('pdfActionNamed').typeNamed,
+    Launch:runtime.resolve('pdfActionLaunch').typeLaunch
+};
+const action = a.typeAction(dict, typers);
+```
+
+### Walking the action chain
+
+```js
+let cur = action;
+while (cur) {
+    console.log(cur.kind);
+    cur = cur.next ? cur.next[0] : null;
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/action/max-depth` | `ParseError` | `/Next` chain exceeds `opts.maxDepth`. |
+| `pdf/action/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/action/cycle` | `ParseError` | Action already visited. |
+| `pdf/action/bad-type` | `ParseError` | `/Type` ≠ `/Action`. |
+| `pdf/action/missing-s` | `ParseError` | `/S` absent. |
+| `pdf/action/bad-next` | `ParseError` | `/Next` is neither a dict nor an array. |
+
+## See also
+
+- [`pdfActionGoTo`](./goTo.md) · [`pdfActionUri`](./uri.md) · [`pdfActionNamed`](./named.md) · [`pdfActionLaunch`](./launch.md)
+- [`pdfLinkAnnot`](../annot/link.md) · [`pdfWidgetAnnot`](../annot/widget.md)

package/docs/api/action/goTo.md

@@ -0,0 +1,66 @@
+---
+module: pdfActionGoTo
+category: pdf/action
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfActionGoTo
+
+> GoTo / GoToR / GoToE — ISO 32000-2 §12.6.4.2 / §12.6.4.3 / §12.6.4.4.
+
+**Module** `pdfActionGoTo` | **Source** `packages/front/office/pdf/src/action/goTo.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Three navigation variants:
+- **GoTo** (`/S /GoTo`) — destination inside the current document, `/D` entry.
+- **GoToR** (`/S /GoToR`) — remote file, `/F` (file spec) and `/D` entries, optional `/NewWindow`.
+- **GoToE** (`/S /GoToE`) — embedded file, `/D` entry plus optional `/F` and `/T` (target dict), optional `/NewWindow`.
+
+## Resolve
+
+```js
+const goto = runtime.resolve('pdfActionGoTo');
+// Returns: { typeGoTo, typeGoToR, typeGoToE }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeGoTo` | `(dict) => { kind: 'GoTo', dest, raw }` | Internal destination. |
+| `typeGoToR` | `(dict) => { kind: 'GoToR', file, dest, newWindow?, raw }` | Remote file. |
+| `typeGoToE` | `(dict) => { kind: 'GoToE', dest, file?, target?, newWindow?, raw }` | Embedded file. |
+
+## Examples
+
+### Internal link via outline
+
+```js
+const a = runtime.resolve('pdfActionGoTo').typeGoTo(actionDict);
+const d = runtime.resolve('pdfDestination').typeDestination(a.dest, names, resolveRef);
+```
+
+### Remote link
+
+```js
+const a = runtime.resolve('pdfActionGoTo').typeGoToR(actionDict);
+a.file;          // file spec (/F)
+a.dest;          // destination inside the remote document (/D)
+a.newWindow;     // boolean, when /NewWindow is present
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/action/goto/missing-d` | `ParseError` | `/D` absent. |
+| `pdf/action/gotor/missing-f` | `ParseError` | `/F` absent. |
+| `pdf/action/gotor/missing-d` | `ParseError` | `/D` absent. |
+| `pdf/action/gotoe/missing-d` | `ParseError` | `/D` absent. |
+| `pdf/action/goto/not-dict` · `gotor/not-dict` · `gotoe/not-dict` | `ParseError` | Argument is not a dict. |
+
+## See also
+
+- [`pdfAction`](./action.md) · [`pdfDestination`](../destination/destination.md) · [`pdfFileSpec`](../embedded/fileSpec.md)

package/docs/api/action/launch.md

@@ -0,0 +1,58 @@
+---
+module: pdfActionLaunch
+category: pdf/action
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfActionLaunch
+
+> Launch action — ISO 32000-2 §12.6.4.5.
+
+**Module** `pdfActionLaunch` | **Source** `packages/front/office/pdf/src/action/launch.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/S /Launch` action — requests launching an external application. `/F` (file spec) or the platform-specific `/Win`/`/Mac`/`/Unix` entries. Optional `/NewWindow` boolean. **Major attack surface** — this module **never executes anything**; it always returns `sandboxed: true` and a `securityWarning` string alongside the typed entries, so the host application decides what to do (typically: ignore, or prompt the user).
+
+## Resolve
+
+```js
+const launch = runtime.resolve('pdfActionLaunch');
+// Returns: { typeLaunch }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeLaunch` | `(dict) => { kind: 'Launch', sandboxed: true, securityWarning: string, file?, win?, mac?, unix?, newWindow?, raw }` | Typing only — no execution. |
+
+## Examples
+
+### Inspection without execution
+
+```js
+const a = runtime.resolve('pdfActionLaunch').typeLaunch(actionDict);
+console.warn('Launch action present', a.file);   // refused by default
+```
+
+### Filtering in a viewer
+
+```js
+function safeDispatch(action) {
+    if (action.kind === 'Launch') return false;
+    // …
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/action/launch/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/action/launch/empty` | `ParseError` | No target at all (`/F`, `/Win`, `/Mac`, `/Unix` all absent). |
+
+## See also
+
+- [`pdfAction`](./action.md) · [`pdfFileSpec`](../embedded/fileSpec.md)

package/docs/api/action/named.md

@@ -0,0 +1,55 @@
+---
+module: pdfActionNamed
+category: pdf/action
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfActionNamed
+
+> Named action — ISO 32000-2 §12.6.4.11.
+
+**Module** `pdfActionNamed` | **Source** `packages/front/office/pdf/src/action/named.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/S /Named` action — invokes a predefined viewer command. Requires `/N`. Standard names per §12.6.4.11: `NextPage`, `PrevPage`, `FirstPage`, `LastPage`; vendor-defined names are accepted but flagged via `standard: false`. PDF readers often extend the set with `GoBack`, `GoForward`, `GoToPage`, `Find`, `Print`, `SaveAs`.
+
+## Resolve
+
+```js
+const named = runtime.resolve('pdfActionNamed');
+// Returns: { typeNamed }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeNamed` | `(dict) => { kind: 'Named', name: string, standard: boolean, raw }` | Typing. |
+
+## Examples
+
+```js
+const a = runtime.resolve('pdfActionNamed').typeNamed(actionDict);
+switch (a.name) {
+    case 'NextPage':  viewer.next(); break;
+    case 'PrevPage':  viewer.prev(); break;
+    case 'FirstPage': viewer.first(); break;
+    case 'LastPage':  viewer.last(); break;
+    default:
+        if (!a.standard) console.warn('vendor-defined named action', a.name);
+        viewer.invokeNamed(a.name);
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/action/named/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/action/named/missing-n` | `ParseError` | `/N` absent or not a name. |
+
+## See also
+
+- [`pdfAction`](./action.md)

package/docs/api/action/uri.md

@@ -0,0 +1,54 @@
+---
+module: pdfActionUri
+category: pdf/action
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfActionUri
+
+> URI action — ISO 32000-2 §12.6.4.7.
+
+**Module** `pdfActionUri` | **Source** `packages/front/office/pdf/src/action/uri.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/S /URI` action — opens an external resource (HTTP, mailto, …). Requires `/URI` (ASCII string), optional `/IsMap` boolean (for server-side image maps). Note: the factory only actually uses its `errors` parameter (a self-contained `isType` helper is inlined so the module tolerates a stub `parser`), even though `pdfParser` is declared as a dependency.
+
+## Resolve
+
+```js
+const uri = runtime.resolve('pdfActionUri');
+// Returns: { typeUri }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeUri` | `(dict) => { kind: 'URI', uri: string, isMap?: boolean, raw }` | Typing. |
+
+## Examples
+
+```js
+const a = runtime.resolve('pdfActionUri').typeUri(actionDict);
+a.uri;           // 'https://example.com'
+window.open(a.uri, a.isMap ? '_blank' : '_self');
+```
+
+### Sanitization
+
+```js
+if (a.uri.startsWith('javascript:')) reject();
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/action/uri/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/action/uri/missing` | `ParseError` | `/URI` absent or not a string. |
+
+## See also
+
+- [`pdfAction`](./action.md) · [`pdfLinkAnnot`](../annot/link.md)

package/docs/api/annot/README.md

@@ -0,0 +1,53 @@
+# Annotations — ISO 32000-2 §12.5
+
+Interactive annotation layer: a generic dispatcher plus one typer per
+subtype.
+
+| Module | Returns | Deps | Description |
+|--------|---------|------|-------------|
+| [`pdfAnnot`](./annot.md) | `{ BASE_KEYS, typeBaseAnnot, captureExtras, typeAnnot }` | `pdfErrors`, `pdfParser` | Dispatcher §12.5.2. |
+| [`pdfTextAnnot`](./text.md) | `{ typeTextAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Sticky note §12.5.6.4. |
+| [`pdfLinkAnnot`](./link.md) | `{ typeLinkAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Hyperlink §12.5.6.5. |
+| [`pdfMarkupAnnot`](./markup.md) | `{ typeMarkupAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Highlight/Underline/… §12.5.6.10. |
+| [`pdfShapeAnnot`](./square.md) | `{ typeShapeAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Line/Square/Circle/Polygon §12.5.6.7–9. |
+| [`pdfFreeTextAnnot`](./freeText.md) | `{ typeFreeTextAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Free text §12.5.6.6. |
+| [`pdfInkAnnot`](./ink.md) | `{ typeInkAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Freehand ink §12.5.6.13. |
+| [`pdfStampAnnot`](./stamp.md) | `{ typeStampAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Rubber stamp §12.5.6.12. |
+| [`pdfFileAttachAnnot`](./fileAttach.md) | `{ typeFileAttachAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | File attachment §12.5.6.15. |
+| [`pdfWidgetAnnot`](./widget.md) | `{ typeWidgetAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Form widget §12.5.6.19. |
+| [`pdfPopupAnnot`](./popup.md) | `{ typePopupAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Pop-up §12.5.6.14. |
+| [`pdfProjectionAnnot`](./projection.md) | `{ typeProjectionAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | 3D measurement §12.5.6.23. |
+| [`pdfRedactAnnot`](./redact.md) | `{ typeRedactAnnot }` | `pdfErrors`, `pdfParser`, `pdfAnnot` | Redaction (ISO TS 32005). |
+
+## Common pattern
+
+`typeAnnot` takes a second argument — a **typers map** wiring each subtype
+family to its specialised typer. Omit it and every subtype falls back to
+base typing (`typeBaseAnnot` plus a full `_extras` capture).
+
+```js
+const annot = runtime.resolve('pdfAnnot');
+const typers = {
+    Text:           runtime.resolve('pdfTextAnnot').typeTextAnnot,
+    Link:           runtime.resolve('pdfLinkAnnot').typeLinkAnnot,
+    Markup:         runtime.resolve('pdfMarkupAnnot').typeMarkupAnnot,
+    Shape:          runtime.resolve('pdfShapeAnnot').typeShapeAnnot,
+    FreeText:       runtime.resolve('pdfFreeTextAnnot').typeFreeTextAnnot,
+    Ink:            runtime.resolve('pdfInkAnnot').typeInkAnnot,
+    Stamp:          runtime.resolve('pdfStampAnnot').typeStampAnnot,
+    Popup:          runtime.resolve('pdfPopupAnnot').typePopupAnnot,
+    FileAttachment: runtime.resolve('pdfFileAttachAnnot').typeFileAttachAnnot,
+    Widget:         runtime.resolve('pdfWidgetAnnot').typeWidgetAnnot,
+    Redact:         runtime.resolve('pdfRedactAnnot').typeRedactAnnot,
+    Projection:     runtime.resolve('pdfProjectionAnnot').typeProjectionAnnot
+};
+for (const ref of page.annots) {
+    const a = annot.typeAnnot(doc._raw.resolve(ref), typers);
+    switch (a.kind) { /* … */ }
+}
+```
+
+## See also
+
+- [Document layer](../document/README.md) — `pdfPage.annots`.
+- [Form](../form/README.md) — `/Widget` is a special case.

package/docs/api/annot/annot.md

@@ -0,0 +1,114 @@
+---
+module: pdfAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAnnot
+
+> Annotation orchestrator — ISO 32000-2 §12.5, dispatch on `/Subtype`.
+
+**Module** `pdfAnnot` | **Source** `packages/front/office/pdf/src/annot/annot.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`typeAnnot` reads a `/Type /Annot` dictionary (§12.5.2 Table 166) and delegates
+to a specialised typer selected by `/Subtype`: `Text`, `Link`, `FreeText`,
+`Line`/`Square`/`Circle`/`Polygon`/`PolyLine`,
+`Highlight`/`Underline`/`Squiggly`/`StrikeOut`/`Caret`, `Stamp`, `Ink`, `Popup`,
+`FileAttachment`, `Widget`, `Redact`, `Projection`. Those delegates are supplied
+by the caller through the second `typers` argument — when it is missing, or when
+the relevant slot is not a function, the subtype falls back to base typing plus a
+full `_extras` capture. The known-but-unhandled subtypes (`Sound`, `Movie`,
+`Screen`, `PrinterMark`, `TrapNet`, `Watermark`, `3D`, `RichMedia`) always take
+that fallback; any other name returns `{ kind, raw, _extras }` with every
+dictionary entry copied into `_extras`.
+
+`typeBaseAnnot` factors out the entries common to every annotation (`/Rect`,
+`/Contents`, `/P`, `/NM`, `/M`, `/F`, `/AP`, `/AS`, `/Border`, `/C`,
+`/StructParent`, `/OC`, `/AF`, `/CA`, `/BS`, `/BE`) — exactly the names held by
+the exported `BASE_KEYS` set, plus `/Type` and `/Subtype`.
+
+## Resolve
+
+```js
+const annot = runtime.resolve('pdfAnnot');
+// Returns: { BASE_KEYS, typeBaseAnnot, captureExtras, typeAnnot }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `BASE_KEYS` | `Set<string>` | The 18 base `/Type /Annot` keys consumed by `typeBaseAnnot`. |
+| `typeBaseAnnot` | `(dict) => BaseAnnot` | §12.5.2 entries only. |
+| `captureExtras` | `(target, dict, known) => void` | Copies every entry outside `BASE_KEYS` and outside the optional `known` set into `target._extras`. Used by every subtype typer. |
+| `typeAnnot` | `(dict, typers?) => Annotation` | Typed record carrying `kind`, derived from `/Subtype`. |
+
+### The `typers` map
+
+Keys are typer *families*, not subtype names — `Shape` covers
+`Line`/`Square`/`Circle`/`Polygon`/`PolyLine`, `Markup` covers
+`Highlight`/`Underline`/`Squiggly`/`StrikeOut`/`Caret`, and both receive the
+expected subtype as a second argument:
+
+```js
+{ Text, Link, FreeText, Shape, Markup, Stamp, Ink, Popup,
+  FileAttachment, Widget, Redact, Projection }
+```
+
+### `BaseAnnot` shape
+
+```js
+{
+    subtype, rect: [llx,lly,urx,ury]|null, contents, p: {num,gen}|null,
+    nm, m, f: number,          // /F flags (bit 1 Invisible, 2 Hidden, …)
+    ap, as, border, c,         // /AP /AS /Border /C
+    structParent, oc, af, ca,
+    bs, be, raw, _extras
+}
+```
+
+## Examples
+
+### Dispatch an annotation
+
+```js
+const annot = runtime.resolve('pdfAnnot');
+const typers = { Text: runtime.resolve('pdfTextAnnot').typeTextAnnot };
+for (const ref of page.annots) {
+    const a = annot.typeAnnot(doc._raw.resolve(ref), typers);
+    a.kind;     // 'Text' | 'Link' | 'Highlight' | …
+}
+```
+
+### Base typing only
+
+```js
+const base = annot.typeBaseAnnot(dict);
+base.rect;     // [llx, lly, urx, ury]
+base.f & 0x02; // Hidden flag
+```
+
+### Unknown subtype
+
+```js
+const a = annot.typeAnnot(weirdDict);
+a.kind === 'CustomVendor';  // preserved; _extras holds every entry
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/annot/bad-type` | `ParseError` | `/Type` present but not `/Annot`. |
+| `pdf/annot/missing-subtype` | `ParseError` | `/Subtype` missing or not a name (`typeAnnot` only). |
+
+## See also
+
+- [`pdfTextAnnot`](./text.md) · [`pdfLinkAnnot`](./link.md) · [`pdfMarkupAnnot`](./markup.md) · [`pdfShapeAnnot`](./square.md)
+- [`pdfFreeTextAnnot`](./freeText.md) · [`pdfInkAnnot`](./ink.md) · [`pdfStampAnnot`](./stamp.md) · [`pdfFileAttachAnnot`](./fileAttach.md)
+- [`pdfWidgetAnnot`](./widget.md) · [`pdfPopupAnnot`](./popup.md) · [`pdfProjectionAnnot`](./projection.md) · [`pdfRedactAnnot`](./redact.md)
+- [`pdfPage`](../document/page.md)