@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/annot/text.md

@@ -0,0 +1,69 @@
+---
+module: pdfTextAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTextAnnot
+
+> Sticky-note annotation — ISO 32000-2 §12.5.6.4.
+
+**Module** `pdfTextAnnot` | **Source** `packages/front/office/pdf/src/annot/text.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Text`: a sticky note. Subtype-specific entries are `/Open` (initial
+pop-up state), `/Name` (icon — `Note`, `Comment`, `Help`, `Insert`, `Key`,
+`NewParagraph`, `Paragraph`), `/State` and `/StateModel`. Everything from
+`typeBaseAnnot` is inherited; every other entry — including the markup entries
+`/T`, `/Subj`, `/RC`, `/CreationDate`, `/IRT`, `/RT`, `/Popup` — lands in
+`_extras`.
+
+## Resolve
+
+```js
+const text = runtime.resolve('pdfTextAnnot');
+// Returns: { typeTextAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeTextAnnot` | `(dict) => TextAnnot` | Base record plus `open`, `iconName`, `state`, `stateModel`. |
+
+`state` and `stateModel` are the raw `Uint8Array` payloads of the PDF strings;
+`open` defaults to `false` and `iconName` to `null`.
+
+## Examples
+
+### Type a sticky note
+
+```js
+const t = runtime.resolve('pdfTextAnnot').typeTextAnnot(dict);
+t.iconName;      // 'Note'
+t.open;          // false by default
+t._extras.T;     // /T (author) — typed string object
+```
+
+### Through the dispatcher
+
+```js
+const annot = runtime.resolve('pdfAnnot');
+const a = annot.typeAnnot(dict, { Text: runtime.resolve('pdfTextAnnot').typeTextAnnot });
+if (a.kind === 'Text') { /* … */ }
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/not-dict` | `ParseError` | Inherited from `typeBaseAnnot`. |
+| `pdf/annot/bad-type` | `ParseError` | Inherited from `typeBaseAnnot`. |
+| `pdf/annot/text/bad-subtype` | `ParseError` | `/Subtype` present and not `/Text`. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md)
+- [`pdfPopupAnnot`](./popup.md) — the associated `/Popup`.

package/docs/api/annot/widget.md

@@ -0,0 +1,69 @@
+---
+module: pdfWidgetAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfWidgetAnnot
+
+> Widget annotation (form field visual) — ISO 32000-2 §12.5.6.19.
+
+**Module** `pdfWidgetAnnot` | **Source** `packages/front/office/pdf/src/annot/widget.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Widget`: the visual half of an AcroForm field (§12.7), frequently
+merged into the field dictionary itself. Subtype-specific entries: `/H`
+(highlight mode), `/MK` (appearance characteristics —
+`BC`/`BG`/`CA`/`R`/`IF`/`I`/`RI`/`IX`/`TP`), `/A` and `/AA` (action plus trigger
+events) and `/Parent` (link back into the field tree). `/BS` belongs to the base
+record.
+
+## Resolve
+
+```js
+const w = runtime.resolve('pdfWidgetAnnot');
+// Returns: { typeWidgetAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeWidgetAnnot` | `(dict) => WidgetAnnot` | Base record plus `h`, `mk`, `action`, `aa`, `parent`. |
+
+`/A` is surfaced as `action` (only when it is a dictionary); `parent` is
+`{ num, gen }` when `/Parent` is an indirect reference, `null` otherwise.
+
+## Examples
+
+### Visual rendering of a text field
+
+```js
+const w = runtime.resolve('pdfWidgetAnnot').typeWidgetAnnot(dict);
+w.mk?.entries.BC;       // border colour
+w.mk?.entries.BG;       // background colour
+w.h;                    // 'I' (invert) | 'N' | 'O' | 'P' | 'T'
+```
+
+### Action triggers
+
+```js
+w.aa?.entries.K;        // keystroke action
+w.aa?.entries.V;        // validate action
+w.aa?.entries.F;        // format action
+w.action;               // /A — activation action dictionary
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/widget/bad-subtype` | `ParseError` | `/Subtype` present and not `/Widget`. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md)
+- [`pdfAcroForm`](../form/acroform.md) · [`pdfFieldTree`](../form/fieldTree.md)
+- [`pdfAction`](../action/action.md)

package/docs/api/associatedFiles/README.md

@@ -0,0 +1,9 @@
+# Associated Files — PDF 2.0 / PDF20_AN002-AF annex
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfAssociatedFiles`](./associatedFiles.md) | `{ typeAssociatedFiles }` | `pdfErrors`, `pdfParser` | `/AF` array, PDF 2.0. |
+
+## See also
+
+- [Embedded](../embedded/README.md)

package/docs/api/associatedFiles/associatedFiles.md

@@ -0,0 +1,78 @@
+---
+module: pdfAssociatedFiles
+category: pdf/associatedFiles
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAssociatedFiles
+
+> Associated Files — PDF 2.0 (PDF20_AN002-AF annex).
+
+**Module** `pdfAssociatedFiles` | **Source** `packages/front/office/pdf/src/associatedFiles/associatedFiles.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+PDF 2.0's *Associated Files* mechanism (§14.13) lets *any* PDF object (Catalog, page, annotation, image XObject, structure element, …) attach a file spec via `/AF`, tagged with the file spec's own `/AFRelationship`. This module types an `/AF` array (one or more file spec entries).
+
+Standard `/AFRelationship` values: `Source` (this PDF is derived from the source), `Data` (data used by the object), `Alternative` (alternate rendering), `Supplement` (supplementary info), `EncryptedPayload`, `FormData` (PDF 2.0), `Schema`, `Unspecified`.
+
+**The returned file spec is the raw parser dict node, not a `pdfFileSpec.typeFileSpec()` result** — call `typeFileSpec` yourself on `.filespec` if you need the convenience accessors (`.uf`, `.f`, …).
+
+## Resolve
+
+```js
+const af = runtime.resolve('pdfAssociatedFiles');
+// Returns: { typeAssociatedFiles }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeAssociatedFiles` | `(arr, resolveRef?) => AssociatedFile[]` | List of associated-file records. |
+
+### Shape `AssociatedFile`
+
+```js
+// entry successfully resolved to a dict:
+{ filespec: PdfDict, relationship: string | null, standard: boolean, ref?: { num, gen } }
+
+// entry is an unresolved ref and no resolveRef was supplied:
+{ ref: PdfRef, resolved: false }
+```
+
+## Examples
+
+### AF on the Catalog
+
+```js
+const af = runtime.resolve('pdfAssociatedFiles');
+const fileSpecModule = runtime.resolve('pdfFileSpec');
+const files = af.typeAssociatedFiles(catalog.af, doc._raw.resolve);
+for (const f of files) {
+    f.relationship;                                  // 'Source' | 'Data' | …
+    const fs = fileSpecModule.typeFileSpec(f.filespec);
+    fs.uf;                                            // filename
+}
+```
+
+### AF on an image (PDF/A-3, PDF/A-4)
+
+```js
+const files = af.typeAssociatedFiles(stream.dict.entries.AF, resolveRef);
+// Source data attached to the image
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/af/not-array` | `ParseError` | Argument is not an array. |
+| `pdf/af/bad-entry` | `ParseError` | An entry resolves to neither a dict nor a ref. |
+| `pdf/af/bad-relationship` | `ParseError` | `/AFRelationship` is not a name. |
+
+## See also
+
+- [`pdfFileSpec`](../embedded/fileSpec.md) · [`pdfEmbeddedFile`](../embedded/embeddedFile.md)
+- [`pdfCatalog`](../document/catalog.md) · [`pdfPage`](../document/page.md)

package/docs/api/bundles/README.md

@@ -0,0 +1,68 @@
+# Bundles — pre-wired pdf API factories
+
+Three module descriptors re-export the core PDF API with different subsets of extras wired in. Each declares its dependencies (core `pdf` + extras) and is resolved through a `ModuleRuntime`; the factory wires the extras into `pdf` via `.use(...)` and returns the enriched instance with `.read()`, `.write()`, `.use()`, and a namespace per wired extra.
+
+| Bundle | Extras | When to choose |
+|--------|--------|---------------|
+| [`pdfLargeBundle`](./pdf-large.md) | P0 + P1 | Standard production: the common PDF 2.0 features. No linearization-dictionary builder, no 3D, no legacy 1.7. |
+| [`pdfFullBundle`](./pdf-full.md) | P0 + P1 + P2 + P3 | Every PDF 2.0 extra. Adds the linearization-dictionary builder, 3D/RichMedia, JBIG2 segment-header read, Info lint, misc tail, sandbox. |
+| [`pdfLegacyBundle`](./pdf-legacy.md) | full + `legacy-*` | Legacy 1.7 ingestion. Adds XFA read, RC4 decryption helpers, LZW / CCITT fax decode and DCT / JPX passthrough, Sound/Movie/Screen typing. |
+
+Each bundle's extras are listed literally in its descriptor's `dependencies`
+and enumerated on its page.
+
+These three descriptors are the **source-side** bundles. The committed `dist/` build additionally crosses them with a Read / Read+Write family axis — see [Committed `dist/` bundle matrix](./dist-matrix.md) for the eight roots, the `-rw` naming scheme and the write inventory. Every `-rw` root also ships the signature verifier `pdfSignature` beside the signer, so a Read+Write bundle can verify what it signs; no Read root carries it.
+
+Bundles are `{ name, dependencies, factory }` descriptors — consumption is exclusively declarative via `ModuleRuntime`. The three bundle descriptors are reachable through the root `bundle` array (as above) or through their own subpath exports (`@awacloud/pdf/pdf-large`, `@awacloud/pdf/pdf-full`, `@awacloud/pdf/pdf-legacy`); they are **not** re-exported from the package root by binding name, so `import { pdfLargeBundle } from '@awacloud/pdf'` is `undefined`. The same holds for every `extras` descriptor.
+
+## Common pattern
+
+```js
+import { ModuleRuntime } from '@awacloud/fw/core/runtime.js';
+import { fw_require, pkg_require, modules, extras, bundle } from '@awacloud/pdf';
+
+const rt = new ModuleRuntime();
+for (const m of fw_require)  rt.register(m);
+for (const m of pkg_require) rt.register(m);
+for (const m of modules)     rt.register(m);
+for (const m of extras)      rt.register(m);
+for (const m of bundle)      rt.register(m);
+
+const api = rt.resolve('pdfLargeBundle');
+const doc = api.read(bytes);                 // PDF 2.0 read
+const out = api.write(doc);                  // PDF 2.0 write
+
+// Extras are reachable by their own name
+api.pdfSigPades.detectPadesProfile(sigDict, ctx);
+
+// Adding a custom extra
+api.use({
+    name: 'myExt',
+    register() { return { myExt: { /* … */ } }; }
+});
+```
+
+## Decision
+
+```
+Ingesting only PDF 2.0?
+├── strict + simple → pdf-large
+└── strict + complete (linearization dictionary, 3D, JBIG2 headers, Info lint) → pdf-full
+
+Ingesting PDF 1.7 (XFA, RC4, LZW, Sound/Movie)?
+└── → pdf-legacy  (write still emits a %PDF-2.0 header; legacy content is not converted)
+```
+
+## Common errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/use/bad-extension` | `ContractError` | `.use()` is called with an object missing `name`/`register` (thrown by the core `pdf` orchestrator itself; every bundle inherits it). |
+| `pdf/filters/missing-lzw` | `ParseError` | `pdf-legacy` only — `pdfLegacyDeprecatedFilters` constructed without a valid `@awacloud/fw` `lzw` factory output. |
+
+## See also
+
+- [Committed `dist/` bundle matrix](./dist-matrix.md)
+- [Extras](../extra/README.md)
+- [`pdf`](../pdf.md)
+- [API index](../README.md)

package/docs/api/bundles/dist-matrix.md

@@ -0,0 +1,165 @@
+---
+category: pdf/bundles
+status: complete
+---
+
+# Committed `dist/` bundle matrix
+
+> Two bundle families — Read and Read+Write — across the four size segments.
+
+This page is a reference page for the committed `dist/` build, not a module
+page: no descriptor is named `dist-matrix`.
+
+**Generated by** `packages/front/office/pdf/tools/generate-bundles.mjs` | **Surfaces** `dist/build/` (fw-mode) + `dist/standalone/` (framework-free) | **Since** 2026-08-04
+
+The committed build is a matrix of two independent axes:
+
+- **size segmentation** (frozen): `pdf` (bare core), `pdf-large`, `pdf-full`,
+  `pdf-legacy` — the extras layered on top of the core;
+- **capability family** (this page): **Read** and **Read+Write**.
+
+Both axes cross with the two path-discriminated surfaces (`dist/build/` and
+`dist/standalone/`), so every cell ships a `.js` / `.min.js` / `.meta.json`
+triplet: 8 roots × 2 surfaces × 3 files = 48 files, plus the single
+`dist/build/index.js` fw-mode barrel.
+
+## Naming scheme
+
+The discriminator is a trailing **`-rw` segment on the root name**; the
+**absence** of a discriminator marks the Read family. The four historical root
+names are frozen — renaming them to `pdf-read.js` etc. would have *removed* a
+published name, which the additive doctrine forbids.
+
+| Family | Root names | Path |
+|---|---|---|
+| Read | `pdf`, `pdf-large`, `pdf-full`, `pdf-legacy` | `@awacloud/pdf/{build,standalone}/<root>.js` |
+| Read+Write | `pdf-rw`, `pdf-large-rw`, `pdf-full-rw`, `pdf-legacy-rw` | `@awacloud/pdf/{build,standalone}/<root>.js` |
+
+Generated export names follow the surface suffix already in force:
+`pdfRwBundled` / `pdfRwPackage`, `pdfLargeRwBundled` / `pdfLargeRwPackage`, and
+so on.
+
+## The matrix
+
+Module counts are the `meta.json` `modules` closure (identical on both
+surfaces); byte sizes are the `standalone` / `build` dev sizes.
+
+| Segment | Read root | modules | Read+Write root | modules | Δ |
+|---|---|---|---|---|---|
+| bare core | `pdf` | 21 | `pdf-rw` | 35 | +14 |
+| large | `pdf-large` | 43 | `pdf-large-rw` | 57 | +14 |
+| full | `pdf-full` | 49 | `pdf-full-rw` | 63 | +14 |
+| legacy | `pdf-legacy` | 54 | `pdf-legacy-rw` | 68 | +14 |
+
+The composition is **strictly additive**: every Read root is a subset of its
+Read+Write twin, and adding the Read+Write family left the four Read roots
+unchanged.
+
+## Write inventory
+
+The Read+Write delta is the **write inventory** — the write-path modules that
+are separable from the `pdf` orchestrator core — plus the
+[verification surface](#verification-surface):
+
+| Module | Surface | In every `-rw` root |
+|---|---|---|
+| `pdfBuilder` | `builder()` | yes |
+| `pdfIncrementalWriter` | `appendIncremental()` | yes |
+| `pdfXrefStreamWriter` | `writeXrefStreamDocument()` | yes (required in every `-rw` root) |
+| `pdfEncryptedWriter` | `writeEncryptedDocument()` | yes |
+| `pdfSign` | `sign()` | yes |
+| `pdfDssBuilder` | `buildDss()` | yes (transitive via `pdfSign`) |
+
+Their closure also pulls in `pdfFlate`, `pdfAesGcm`, `pdfStandardV4/V5/V6`,
+`pdfSigOids`, `pdfByteRange`, `pdfSha1` — all classified **shared** (each
+exposes both directions, e.g. `encode`/`decode`, `encryptStream`/
+`decryptStream`).
+
+### Two documented exclusions
+
+- **`pdfSerializer` and `pdfWriter` are core-embedded.** They are write-path
+  (`serializeObject`, `writeDocument`) but are declared dependencies of
+  `src/pdf.js` itself — `pdf.write()` is part of the core facade. They cannot
+  be factored out without changing `src/pdf.js`, so they are *not* part of the
+  composable inventory and the Read-family purity lock is stated against the
+  six modules above.
+- **`pdfFontEmbed` is write-path but not shippable in a bundle.** Its four
+  declared dependencies (`embedSubsetForPdf`, `embedFontDescriptor`,
+  `embedCidSystemInfo`, `embedToUnicodeBuilder`) come from `pkg_require`
+  (`@awacloud/fonts`), which the generator's local registry
+  (`buildLocalRegistry(modules, extras)`) does not see — including it makes
+  `topoLocal` throw `Unknown module : embedSubsetForPdf`. Font embedding
+  therefore stays an fw-runtime-only capability.
+
+## Verification surface
+
+A bundle that can `sign()` can also verify: every `-rw` root ships the
+read-path signature verifier beside the signer.
+
+| Module | Surface | In every `-rw` root | In a Read root |
+|---|---|---|---|
+| `pdfSignature` | `verifySignature()`, `verifyAllSignatures()` | yes | no |
+
+`pdfSignature` is a **read** module, not part of the write inventory; the
+generator lists it separately (`VERIFY_SURFACE` in
+`tools/generate-bundles.mjs`) so the inventory above stays exactly the set of
+separable write modules.
+
+It rides the Read+Write family, not the Read family, because the four Read
+roots are byte-frozen: adding it left them, their `.meta.json` and the
+`dist/build/index.js` barrel byte-identical. Its crypto closure already ships
+through `pdfSign`, so it adds **no** `@awacloud/fw` dependency and no other
+module — only `pdfSignature` itself joins each `-rw` closure. Measured cost
+per `-rw` root: **+21.8 KB** minified (for example `build/pdf-rw.min.js`
+121,323 → 143,156 bytes, +18.0 %; `standalone/pdf-legacy-rw.min.js`
+336,801 → 358,735 bytes, +6.5 %) and **+6.4 KB** after gzip -9.
+
+An invoked `-rw` factory exposes the verifier on the returned core:
+
+```js
+import { pdfRwBundled } from '@awacloud/pdf/standalone/pdf-rw.js';
+
+const core = pdfRwBundled.factory();
+core.usedExtension('pdfSignature');          // → true
+const { signatures, timestamps } = core.pdfSignature.verifyAllSignatures(bytes);
+```
+
+## Module classification
+
+All 95 `src/main.js#modules` factories were classified from their **resolved
+API** (a fresh `ModuleRuntime` per module — the shared `pdf` singleton
+order-poisons `Object.keys`):
+
+| Class | Count | Rule |
+|---|---|---|
+| read | 68 | the returned API only parses, types, walks or verifies existing bytes |
+| write | 9 | the returned API emits or assembles PDF output |
+| shared | 18 | the returned API works both directions, or is a pure table/primitive |
+
+The per-module table is the composition's contract; it is kept in the
+source monorepo and is not published. The write and verification modules it
+selects are listed above.
+
+## Notes
+
+- **The Read+Write family is a `dist/` composition only.** Its four bundle
+  plan entries live in `tools/generate-bundles.mjs`, not in
+  `src/main.js#bundle`, so `runtime.resolve('pdfRwBundle')` is *not* a
+  supported call. On an `@awacloud/fw` runtime, register the write modules
+  from the `modules` array (or the `dist/build/index.js` barrel) directly.
+- **Invocability.** Every `dist/standalone` root is invocable with no
+  arguments, the layered ones included: the generator wraps each layered
+  entry in the `{ name, register }` envelope that `pdf.use()` requires, so
+  `pdfLargeBundled.factory()` or `pdfRwBundled.factory()` returns a core with
+  its extras registered (`core.usedExtension(name)`). The `dist/build`
+  roots need an `@awacloud/fw` runtime to inject their declared
+  dependencies.
+- Regeneration is idempotent: `bun run gen:bundles` re-emits byte-identical
+  output (no build stamp; every bundle opens with the `/*! … */` licence
+  banner at byte 0).
+
+## See also
+
+- [Bundles](./README.md)
+- [`pdfLargeBundle`](./pdf-large.md) · [`pdfFullBundle`](./pdf-full.md) · [`pdfLegacyBundle`](./pdf-legacy.md)
+- [API index](../README.md)

package/docs/api/bundles/pdf-full.md

@@ -0,0 +1,148 @@
+---
+module: pdfFullBundle
+category: pdf/bundles
+dependencies: [pdf, pdfContentOpsExtended, pdfFontCidTyped, pdfFontColorTagging, pdfTaggedPdfTyped, pdfAnnotExtended, pdfAOutputIntent, pdfUaTagged, pdfFormActionsExtended, pdfColorSpacesExtended, pdfShadingTyped, pdfTransparencyTyped, pdfSigPades, pdfSigAesGcm, pdfDocumentParts, pdfRedactionIso32005, pdfXPrepress, pdfWellTagged, pdfOptionalContentExtended, pdfEmbeddedFilesPortfolio, pdfAssociatedFiles2, pdfXmpExtended, pdfLinearizationWrite, pdf3dRichMedia, pdfJbig2Read, pdfMisc, pdfInfoDictDeprecated, pdfSandbox]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFullBundle
+
+> Full strict PDF 2.0 bundle — `pdfLargeBundle`'s 21 extras + 6 more.
+
+**Module** `pdfFullBundle` | **Source** `packages/front/office/pdf/src/bundles/pdf-full.js` | **Deps** `pdf` + the 27 extras enumerated under [Extras wired](#extras-wired) (28 names total, listed literally in the frontmatter `dependencies`) | **Worker-safe** yes
+
+A module descriptor — declares the core plus every P0/P1/P2/P3 extra **except** the `legacy-*` family (27 extras total, one flat list — the source does not distinguish a separate "sandbox tail" tier). The runtime resolves the dependencies; the factory wires them into `pdf` via `.use(...)`. Fits callers that need every PDF 2.0 extra. For PDF 1.7 reading use [`pdfLegacyBundle`](./pdf-legacy.md).
+
+## Resolve
+
+```js
+import { ModuleRuntime } from '@awacloud/fw/core/runtime.js';
+import { fw_require, pkg_require, modules, extras, bundle } from '@awacloud/pdf';
+
+const rt = new ModuleRuntime();
+for (const m of fw_require)  rt.register(m);
+for (const m of pkg_require) rt.register(m);
+for (const m of modules)     rt.register(m);
+for (const m of extras)      rt.register(m);
+for (const m of bundle)      rt.register(m);
+
+const api = rt.resolve('pdfFullBundle');
+const doc = api.read(pdfBytes);
+const out = api.write(doc);
+```
+
+The `extras` and `bundle` descriptors are **not** re-exported from the package root by binding name — `import { pdfFullBundle } from '@awacloud/pdf'` is `undefined`. Register the arrays as above, or import the single descriptor from its own subpath export (`import { pdfFullBundle } from '@awacloud/pdf/pdf-full';`).
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `pdfFullBundle` | Descriptor `{ name, dependencies, factory }`. Resolved by `ModuleRuntime` → `pdf` instance wired with all 27 P0-P3 extras. |
+
+The resolved instance is the core `pdf` object (`src/pdf.js`) with the 27 extras merged in — it carries `pdf`'s own 5 members plus one property per wired extra name:
+
+| Member | Signature | Description |
+|--------|-----------|--------------|
+| `read` | `(bytes: Uint8Array) => doc` | Full document read. |
+| `header` | `(bytes: Uint8Array) => { version, end }` | Header-only read, no xref/catalog walk. |
+| `write` | `(doc) => Uint8Array` | PDF 2.0 write. |
+| `use` | `(ext) => api` | Extension hook (idempotent by name); this is how the bundle factory wires each extra. |
+| `usedExtension` | `(name: string) => boolean` | Whether an extension name has already been applied via `.use()`. The bundle factory calls `.use({ name, register })` once per wired extra (e.g. `'pdfSandbox'`), so `api.usedExtension('pdfSandbox')` is `true` right after resolve — `api.usedExtension('pdfFullBundle')` is `false`, since the bundle's own descriptor name is never itself passed to `.use()`. |
+
+## Extras wired
+
+Items 1-21 are [`pdfLargeBundle`](./pdf-large.md)'s extras, re-listed here so every member of the resolved instance is documented on this page; items 22-27 are `pdf-full`'s own additions.
+
+| # | Extra | Phase | Status |
+|---|-------|-------|--------|
+| 1 | [`pdfContentOpsExtended`](../extra/content-ops-extended.md) | P0 | read |
+| 2 | [`pdfFontCidTyped`](../extra/font-cid-typed.md) | P0 | read |
+| 3 | [`pdfFontColorTagging`](../extra/font-color-tagging.md) | P0 | read |
+| 4 | [`pdfTaggedPdfTyped`](../extra/tagged-pdf-typed.md) | P0 | read |
+| 5 | [`pdfAnnotExtended`](../extra/annot-extended.md) | P0 | read |
+| 6 | [`pdfAOutputIntent`](../extra/pdf-a-output-intent.md) | P0 | lint |
+| 7 | [`pdfUaTagged`](../extra/pdf-ua-tagged.md) | P0 | lint |
+| 8 | [`pdfFormActionsExtended`](../extra/form-actions-extended.md) | P1 | read |
+| 9 | [`pdfColorSpacesExtended`](../extra/color-spaces-extended.md) | P1 | read |
+| 10 | [`pdfShadingTyped`](../extra/shading-typed.md) | P1 | read |
+| 11 | [`pdfTransparencyTyped`](../extra/transparency-typed.md) | P1 | read |
+| 12 | [`pdfSigPades`](../extra/sig-pades.md) | P1 | read |
+| 13 | [`pdfSigAesGcm`](../extra/sig-aes-gcm.md) | P1 | read |
+| 14 | [`pdfDocumentParts`](../extra/document-parts.md) | P1 | read |
+| 15 | [`pdfRedactionIso32005`](../extra/redaction-iso32005.md) | P1 | read |
+| 16 | [`pdfXPrepress`](../extra/pdf-x-prepress.md) | P1 | lint |
+| 17 | [`pdfWellTagged`](../extra/well-tagged-pdf.md) | P1 | lint |
+| 18 | [`pdfOptionalContentExtended`](../extra/optional-content-extended.md) | P1 | read |
+| 19 | [`pdfEmbeddedFilesPortfolio`](../extra/embedded-files-portfolio.md) | P1 | read |
+| 20 | [`pdfAssociatedFiles2`](../extra/associated-files.md) | P1 | read |
+| 21 | [`pdfXmpExtended`](../extra/xmp-extended.md) | P1 | read |
+| 22 | [`pdfLinearizationWrite`](../extra/linearization-write.md) | P2 | write |
+| 23 | [`pdf3dRichMedia`](../extra/3d-richmedia.md) | P2 | read |
+| 24 | [`pdfJbig2Read`](../extra/jbig2-read.md) | P2 | read (partial) |
+| 25 | [`pdfMisc`](../extra/misc.md) | P3 | read |
+| 26 | [`pdfInfoDictDeprecated`](../extra/info-dict-deprecated.md) | P3 | lint |
+| 27 | [`pdfSandbox`](../extra/pdf-sandbox.md) | P3 | opt-in audit hook |
+
+## When to choose
+
+- `pdf-large` — minimal: the common PDF 2.0 features.
+- **`pdf-full`** — every PDF 2.0 extra. Choose it when the linearization-dictionary builder, 3D/RichMedia, JBIG2 segment-header read, or Info-dict lint are required.
+- `pdf-legacy` — full + PDF 1.7 read (XFA, RC4, LZW, …).
+
+## Examples
+
+### Bootstrap
+
+```js
+const api = rt.resolve('pdfFullBundle');
+```
+
+### Header only
+
+```js
+api.header(bytes);   // { version: '2.0', end: <offset> } — no xref/catalog walk
+```
+
+### Checking a wired extra
+
+```js
+api.usedExtension('pdfSandbox');        // true — wired by the bundle factory
+api.usedExtension('not-a-real-extra');  // false
+```
+
+### Emitting a linearized dict
+
+```js
+const dict = api.pdfLinearizationWrite.buildLinearizedDict({
+    Linearized: 1.0, L: 50000, H: [200, 500],
+    O: 5, E: 4000, N: 10, T: 48000
+});
+```
+
+### Enumerating a JBIG2 stream
+
+```js
+const segs = api.pdfJbig2Read.parseSegments(jbig2Bytes);
+```
+
+### Info → XMP audit
+
+```js
+const r = api.pdfInfoDictDeprecated.lint({ version: 2.0, info, xmpPresent: false });
+r.warnings;
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/use/bad-extension` | `ContractError` | `.use()` is called with an object missing `name`/`register` (thrown by the core `pdf` orchestrator, not specific to bundles). |
+
+## See also
+
+- [`pdf-large`](./pdf-large.md)
+- [`pdf-legacy`](./pdf-legacy.md)
+- [Bundles index](./README.md)
+- [Extras index](../extra/README.md)