@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/extra/3d-richmedia.md

@@ -0,0 +1,76 @@
+---
+module: pdf3dRichMedia
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdf3dRichMedia
+
+> 3D (§13.6.2) and RichMedia (§13.6.3) annotations — ISO 32000-2.
+
+**Module** `pdf3dRichMedia` | **Source** `packages/front/office/pdf/src/extra/3d-richmedia.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/Subtype /3D` → references a 3D stream via `/3DD`, default view (`/3DV`), activation (`/3DA`), interactive flag (`/3DI`). `/Subtype /RichMedia` → `/RichMediaContent` with `/Assets`, `/Configurations`, `/Views`, and `/RichMediaSettings`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdf3dRichMedia');
+// Returns: { type3DAnnot, type3DActivation, typeRichMediaAnnot,
+//   typeRichMediaContent, classifyRmInstanceState,
+//   RM_INSTANCE_STATES, ACTIVATION_CONDITIONS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `type3DAnnot` | `(dict) => ThreeDAnnot` | `{ threeDD, threeDV, threeDA, threeDI, threeDB, raw, _extras }`. |
+| `type3DActivation` | `(dict) => Activation` | `/3DA` fields `{ a, ais, d, dis, tb, np, raw }`. |
+| `typeRichMediaAnnot` | `(dict) => RichMediaAnnot` | `{ content, settings, raw, _extras }`. |
+| `typeRichMediaContent` | `(dict) => Content` | `{ assets, configurations, views, raw }`. |
+| `classifyRmInstanceState` | `(name: string) => 'active' \| 'loaded' \| 'uninstantiated' \| null` | Looks up `RM_INSTANCE_STATES`. |
+| `RM_INSTANCE_STATES` | frozen catalog | `{ A: 'active', L: 'loaded', U: 'uninstantiated' }`. |
+| `ACTIVATION_CONDITIONS` | frozen catalog | `{ XA: 'explicit activate', PO: 'page open', PV: 'page visible' }`. |
+
+## Examples
+
+### 3D annotation
+
+```js
+const ext = runtime.resolve('pdf3dRichMedia');
+const a = ext.type3DAnnot(annotDict);
+a.threeDD;       // ref to the 3D stream
+a.threeDA.a;     // 'PO' (activation condition)
+```
+
+### RichMedia content
+
+```js
+const c = ext.typeRichMediaContent(contentDict);
+c.assets;          // raw /Assets entry
+c.configurations;  // raw /Configurations entry
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/3d/not-dict` | `ParseError` | Not a dict. |
+| `pdf/extra/3d/bad-subtype` | `ParseError` | `/Subtype` is not `/3D`. |
+| `pdf/extra/3d/missing-3dd` | `ParseError` | `/3DD` absent. |
+| `pdf/extra/3d/act/not-dict` | `ParseError` | Activation is not a dict. |
+| `pdf/extra/rm/not-dict` | `ParseError` | Not a dict. |
+| `pdf/extra/rm/bad-subtype` | `ParseError` | `/Subtype` is not `/RichMedia`. |
+| `pdf/extra/rm/missing-content` | `ParseError` | `/RichMediaContent` absent. |
+| `pdf/extra/rm/content/not-dict` | `ParseError` | Content is not a dict. |
+| `pdf/extra/rm/state/bad` | `ParseError` | State is not a string. |
+
+## See also
+
+- [`pdfAnnotExtended`](./annot-extended.md)
+- [`pdfAnnot`](../annot/annot.md)
+- [Extras index](./README.md)

package/docs/api/extra/README.md

@@ -0,0 +1,99 @@
+# Extras — L3+ opt-in coverage
+
+Optional modules beyond core PDF 2.0. Each is a `{ name, dependencies, factory }` descriptor, consumable directly via `runtime.resolve(name)` or through `pdfApi.use(...)`. Grouped by phase priority.
+
+## P0 — critical coverage (7)
+
+| Module | Status | Description |
+|--------|--------|-------------|
+| [`pdfContentOpsExtended`](./content-ops-extended.md) | read | Extended gstate operators + full ExtGState catalog §8.4.5. |
+| [`pdfFontCidTyped`](./font-cid-typed.md) | read | CIDFont, CSI, `/W`, predefined CMaps §9.7. |
+| [`pdfFontColorTagging`](./font-color-tagging.md) | read | Color fonts (COLR/CPAL/sbix/SVG) §9.8.2. |
+| [`pdfTaggedPdfTyped`](./tagged-pdf-typed.md) | read | Structural attribute owners §14.8.5. |
+| [`pdfAnnotExtended`](./annot-extended.md) | read | Watermark/3D/RichMedia/Sound/Movie/Screen §12.5.6. |
+| [`pdfAOutputIntent`](./pdf-a-output-intent.md) | lint | PDF/A detection + basic lint. |
+| [`pdfUaTagged`](./pdf-ua-tagged.md) | lint | PDF/UA-1/2 linter. |
+
+## P1 — extended coverage (14)
+
+| Module | Status | Description |
+|--------|--------|-------------|
+| [`pdfFormActionsExtended`](./form-actions-extended.md) | read | Extended actions §12.6.4. |
+| [`pdfColorSpacesExtended`](./color-spaces-extended.md) | read | Typed color spaces §8.6. |
+| [`pdfShadingTyped`](./shading-typed.md) | read | Shadings 1-7 + Functions 0/2/3/4 §8.7.4 / §7.10. |
+| [`pdfTransparencyTyped`](./transparency-typed.md) | read | Transparency Group + Soft Mask + blend modes §11. |
+| [`pdfSigPades`](./sig-pades.md) | read | PAdES profile + DSS + Reference §12.8.4.3. |
+| [`pdfSigAesGcm`](./sig-aes-gcm.md) | read | AES-GCM crypt filter ISO/TS 32003. |
+| [`pdfDocumentParts`](./document-parts.md) | read | DPartRoot/DPart/DPM ISO/TS 32004. |
+| [`pdfRedactionIso32005`](./redaction-iso32005.md) | read | Redaction workflow ISO/TS 32005. |
+| [`pdfXPrepress`](./pdf-x-prepress.md) | lint | PDF/X profiles ISO 15930. |
+| [`pdfWellTagged`](./well-tagged-pdf.md) | lint | WTPDF 1.0 best-practices. |
+| [`pdfOptionalContentExtended`](./optional-content-extended.md) | read | OCG VE + Order tree + RBGroups §8.11. |
+| [`pdfEmbeddedFilesPortfolio`](./embedded-files-portfolio.md) | read | Portfolio `/Schema`/`/Sort`/`/Navigator`. |
+| [`pdfAssociatedFiles2`](./associated-files.md) | read | Extended `/AF`, PDF 2.0. |
+| [`pdfXmpExtended`](./xmp-extended.md) | read | XMP packet extractor. |
+
+## P2 — PDF 2.0 long tail (3)
+
+| Module | Status | Description |
+|--------|--------|-------------|
+| [`pdfLinearizationWrite`](./linearization-write.md) | write | Linearization Parameter Dict (Annex F). |
+| [`pdf3dRichMedia`](./3d-richmedia.md) | read | Detailed 3D/RichMedia §13.6. |
+| [`pdfJbig2Read`](./jbig2-read.md) | read (partial) | JBIG2 segment headers — decode not implemented. |
+
+## P3 — Catalog + Info tail, sandbox (3)
+
+| Module | Status | Description |
+|--------|--------|-------------|
+| [`pdfMisc`](./misc.md) | read | SpiderInfo/Threads/Legal/Requirements/Perms/NeedsRendering. |
+| [`pdfInfoDictDeprecated`](./info-dict-deprecated.md) | lint | Deprecated Info dict → XMP mapping. |
+| [`pdfSandbox`](./pdf-sandbox.md) | lint | Active-content (Launch/JavaScript/SubmitForm/…) sandbox linter. |
+
+## Legacy — PDF 1.7 read + deprecated filters (5)
+
+| Module | Status | Description |
+|--------|--------|-------------|
+| [`pdfLegacyXfaRead`](./legacy-xfa-read.md) | read-only | Opaque `/XFA` packets. |
+| [`pdfLegacyRc4Read`](./legacy-rc4-read.md) | read-only | RC4 v2/v3 password + decrypt. |
+| [`pdfCcittFaxDecoder`](./ccitt-fax-decoder.md) | read + write | Full CCITT Group 3/Group 4 (T.4/T.6) codec. |
+| [`pdfLegacyDeprecatedFilters`](./legacy-deprecated-filters.md) | read | LZW + CCITT (via `pdfCcittFaxDecoder`) + DCT + JPX. |
+| [`pdfLegacyDeprecatedAnnots`](./legacy-deprecated-annots.md) | read | Sound/Movie/Screen in detail. |
+
+## 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 ext = rt.resolve('pdfContentOpsExtended');
+ext.typeExtGState(dict);
+```
+
+Unlike the `modules` array, `extras` entries are **not** part of the package
+root's additive re-export list (`import { pdfContentOpsExtended } from
+'@awacloud/pdf'` does not exist) — each extra is only reachable through the
+`extras` array above, through `ModuleRuntime`, or through its own
+`./extra/*` export subpath. A sibling composer that wants to avoid building a
+runtime can import the extra directly by subpath and resolve its declared
+`dependencies` (always core `modules` members, reachable from the package
+root) itself:
+
+```js
+import { pdfContentOpsExtended } from '@awacloud/pdf/extra/content-ops-extended';
+import { pdfErrors, pdfParserObj } from '@awacloud/pdf';
+
+const ext = pdfContentOpsExtended.factory(pdfErrors.factory(), pdfParserObj.factory());
+ext.typeExtGState(dict);
+```
+
+## See also
+
+- [Bundles](../bundles/README.md)
+- [API index](../README.md)

package/docs/api/extra/annot-extended.md

@@ -0,0 +1,71 @@
+---
+module: pdfAnnotExtended
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAnnotExtended
+
+> Extended annotation subtypes (Watermark, 3D, RichMedia, …) — ISO 32000-2 §12.5.6.
+
+**Module** `pdfAnnotExtended` | **Source** `packages/front/office/pdf/src/extra/annot-extended.js` | **Deps** `pdfErrors`, `pdfParserObj`, `pdfAnnot` | **Worker-safe** yes
+
+Extends `pdfAnnot` with: Watermark (§12.5.6.22), 3D (§13.6), RichMedia (§13.6.2), Sound (§12.5.6.16 legacy), Movie (§12.5.6.17 legacy), Screen (§12.5.6.18), PrinterMark (§12.5.6.20), TrapNet (§12.5.6.21), extended FreeText (§12.5.6.6, `/RC`, `/DS`, `/LE`). Composes the core `typeBaseAnnot`/`captureExtras`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfAnnotExtended');
+// Returns: { typeAnnotExtended, typeWatermarkAnnot, type3DAnnot,
+//   typeRichMediaAnnot, typeSoundAnnot, typeMovieAnnot,
+//   typeScreenAnnot, typePrinterMarkAnnot, typeTrapNetAnnot,
+//   typeFreeTextExtended, FREETEXT_LINE_ENDINGS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeAnnotExtended` | `(dict) => Annot` | Dispatches on `/Subtype`. |
+| `typeWatermarkAnnot` | `(dict) => Annot` | `/FixedPrint`. |
+| `type3DAnnot` | `(dict) => Annot` | Surfaces to `pdf3dRichMedia`. |
+| `typeRichMediaAnnot` | `(dict) => Annot` | Same. |
+| `typeSoundAnnot` / `typeMovieAnnot` / `typeScreenAnnot` | `(dict) => Annot` | Legacy multimedia. |
+| `typePrinterMarkAnnot` / `typeTrapNetAnnot` | `(dict) => Annot` | Prepress §12.5.6.20–21. |
+| `typeFreeTextExtended` | `(dict) => Annot` | FreeText with `/RC`, `/DS`, `/LE`. |
+| `FREETEXT_LINE_ENDINGS` | frozen array | `Square`, `Circle`, `Diamond`, `OpenArrow`, `ClosedArrow`, `None`, `Butt`, `ROpenArrow`, `RClosedArrow`, `Slash`. |
+
+## Examples
+
+### Extended dispatcher
+
+```js
+const ext = runtime.resolve('pdfAnnotExtended');
+const a = ext.typeAnnotExtended(annotDict);
+a.kind;  // 'Watermark' | '3D' | 'RichMedia' | …
+```
+
+### FreeText with `/LE`
+
+```js
+const ft = ext.typeFreeTextExtended(dict);
+ft.le;  // 'OpenArrow' or ['OpenArrow', 'ClosedArrow']
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/annot-ext/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/extra/annot-ext/unsupported` | `ParseError` | `/Subtype` outside the extended coverage. |
+| `pdf/extra/annot-ext/unreachable` | `ParseError` | Unreachable branch (defensive). |
+
+## See also
+
+- [`pdfAnnot`](../annot/annot.md)
+- [`pdf3dRichMedia`](./3d-richmedia.md)
+- [`pdfLegacyDeprecatedAnnots`](./legacy-deprecated-annots.md)
+- [Extras index](./README.md)

package/docs/api/extra/associated-files.md

@@ -0,0 +1,70 @@
+---
+module: pdfAssociatedFiles2
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAssociatedFiles2
+
+> Extended `/AF` (Associated Files) — PDF 2.0 / PDF20_AN002-AF.
+
+**Module** `pdfAssociatedFiles2` | **Source** `packages/front/office/pdf/src/extra/associated-files.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+PDF 2.0 allows `/AF` on the Catalog, Page, XObject (Form), Mark, StructElem, Annot, or DParams. Each item references a File Specification that MUST carry `/AFRelationship`. Vocabulary: `Source`, `Data`, `Alternative`, `Supplement`, `EncryptedPayload`, `FormData`, `Schema`, `Unspecified`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfAssociatedFiles2');
+// Returns: { typeAf, typeAfEntry, resolveFileSpec,
+//   isStandardRelationship, listStandardRelationships,
+//   STANDARD_REL, CARRIER_HINTS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeAf` | `(afArray, opts?: { resolveRef?, carrier? }) => { entries, carrier }` | Types a top-level `/AF` array. |
+| `typeAfEntry` | `(entry, resolveRef?, index?) => Entry` | Types one item. |
+| `resolveFileSpec` | `(entry, resolveRef?) => { resolved, dict?, ref? }` | Dereferences an entry. |
+| `isStandardRelationship` | `(name) => boolean` | |
+| `listStandardRelationships` | `() => string[]` | |
+| `STANDARD_REL` | `Set` | The 8 standard relationships. |
+| `CARRIER_HINTS` | `Set` | `Catalog`, `Page`, `XObject`, `StructElem`, `Annot`, `Mark`, `DParams`. |
+
+## Examples
+
+### Load a page's AF array
+
+```js
+const ext = runtime.resolve('pdfAssociatedFiles2');
+const af = ext.typeAf(page.af, { resolveRef: ref => doc._raw.resolve(ref), carrier: 'Page' });
+af.entries[0].relationship;  // 'Data'
+```
+
+### Check a custom relationship
+
+```js
+ext.isStandardRelationship('CustomXYZ');  // false
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/af2/bad-entry` | `ParseError` | Entry is neither a dict nor a ref. |
+| `pdf/af2/not-filespec` | `ParseError` | Resolved entry is not a dict. |
+| `pdf/af2/bad-filespec-type` | `ParseError` | `/Type` is not `/Filespec`. |
+| `pdf/af2/bad-relationship` | `ParseError` | `/AFRelationship` is not a name. |
+| `pdf/af2/bad-carrier` | `ParseError` | Carrier outside `CARRIER_HINTS`. |
+| `pdf/af2/not-array` | `ParseError` | `/AF` is not an array. |
+
+## See also
+
+- [`pdfAssociatedFiles`](../associatedFiles/associatedFiles.md)
+- [`pdfFileSpec`](../embedded/fileSpec.md)
+- [Extras index](./README.md)

package/docs/api/extra/ccitt-fax-decoder.md

@@ -0,0 +1,74 @@
+---
+module: pdfCcittFaxDecoder
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfCcittFaxDecoder
+
+> CCITTFaxDecode codec (ITU-T T.4 / T.6), full Group 3/Group 4 read + write.
+
+**Module** `pdfCcittFaxDecoder` | **Source** `packages/front/office/pdf/src/extra/ccitt-fax-decoder.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Implements the CCITT Group 3/Group 4 fax codec referenced by `/Filter /CCITTFaxDecode` (ISO 32000-2 §7.4.6): `K < 0` selects Group 4 (T.6, pure 2D coding), `K == 0` selects Group 3 one-dimensional (T.4 baseline, white/black run Huffman), `K > 0` selects Group 3 mixed 1D/2D (T.4 with a K-row block and a tag bit). Output is a packed bitstream of `Columns` bits per row, MSB-first, with polarity following `/BlackIs1` (default: white = 1). This is the real decoder that [`pdfLegacyDeprecatedFilters`](./legacy-deprecated-filters.md)'s `ccittFaxDecode` delegates to after validating `DecodeParms`; it is registered directly in `src/main.js#extras` and can also be resolved and used standalone.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfCcittFaxDecoder');
+// Returns: { decode, encode, _internals }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `decode` | `(bytes: Uint8Array, parms: { Columns, Rows?, K?, EndOfLine?, EncodedByteAlign?, BlackIs1?, DamagedRowsBeforeError?, EndOfBlock? }) => Uint8Array` | Packed bitstream, `Columns`-bits-per-row, MSB-first. |
+| `encode` | `(lines: Uint8Array[], parms?: { Columns?, K?, EndOfLine?, EncodedByteAlign?, EndOfBlock? }) => Uint8Array` | Encodes an array of one-byte-per-pixel rows (0=white, 1=black) into a CCITT bitstream, including RTC (G3) / EOFB (G4) terminators. |
+| `_internals` | object | Test/introspection surface: `{ WHITE_MAP, BLACK_MAP, MODE_CODES, EOL_BITS, codeForRun, encode1DLine, encode2DLine, decode1DLine, decode2DLine, makeBitReader, makeBitWriter, findB1, findNextChange, findChangeFrom }`. Not part of the stable public contract. |
+
+## Examples
+
+### Decode a Group 4 stream
+
+```js
+const ext = runtime.resolve('pdfCcittFaxDecoder');
+const bits = ext.decode(streamBytes, { K: -1, Columns: 1728, Rows: 100 });
+// bits.length === Math.ceil(1728 / 8) * 100
+```
+
+### Round-trip encode then decode
+
+```js
+const rows = [ new Uint8Array(1728), new Uint8Array(1728) ]; // all-white
+const encoded = ext.encode(rows, { Columns: 1728, K: -1 });
+const decoded = ext.decode(encoded, { Columns: 1728, Rows: rows.length, K: -1 });
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/ccitt/bad-input` | `ParseError` | `bytes` is not a Uint8Array. |
+| `pdf/ccitt/bad-columns` | `ParseError` | `Columns` is `<= 0` or `> 65535`. |
+| `pdf/ccitt/bad-runcode` | `ParseError` | An unrecognized white/black run-length code is read. |
+| `pdf/ccitt/bad-2d-mode` | `ParseError` | An unrecognized 2D mode code is read. |
+| `pdf/ccitt/unsupported-2d-mode` | `ParseError` | A resolved 2D mode has no vertical-offset handling (defensive). |
+| `pdf/ccitt/truncated` | `ParseError` | Stream ends mid-line and `DamagedRowsBeforeError` does not tolerate it. |
+| `pdf/ccitt/decode-failed` | `ParseError` | Any other decode-time error, wrapped with `cause`. |
+
+`encode` does not throw a validated-input error of its own; malformed `lines`/`parms` produce best-effort output.
+
+## Notes
+
+- The encoder side is production-grade (greedy make-up code choice, `EncodedByteAlign` padding, RTC/EOFB terminators, full 2D state machine) even though the module is filed as a "legacy read" extra alongside [`pdfLegacyDeprecatedFilters`](./legacy-deprecated-filters.md) — it is exercised by that module's `ccittFaxDecode`/`validateCcittParms` pair but is independently usable.
+- Rows tolerant of damage (`DamagedRowsBeforeError > 0`) are filled with a blank (all-white) row instead of throwing.
+
+## See also
+
+- [`pdfLegacyDeprecatedFilters`](./legacy-deprecated-filters.md)
+- [`pdfFilters`](../syntax/filters/README.md)
+- [Extras index](./README.md)

package/docs/api/extra/color-spaces-extended.md

@@ -0,0 +1,72 @@
+---
+module: pdfColorSpacesExtended
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfColorSpacesExtended
+
+> Typed color spaces (CalGray/CalRGB/Lab/ICCBased/Indexed/Separation/DeviceN/NChannel/Pattern) — ISO 32000-2 §8.6.
+
+**Module** `pdfColorSpacesExtended` | **Source** `packages/front/office/pdf/src/extra/color-spaces-extended.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+Types color spaces expressed as an array whose first element is the family name, plus the named device families. Coverage: CalGray (§8.6.5.2), CalRGB (§8.6.5.3), Lab (§8.6.5.4), ICCBased (§8.6.5.5, with Metadata), Indexed (§8.6.6.3), Separation (§8.6.6.4), DeviceN (§8.6.6.5) with `/Attributes`, NChannel (a DeviceN subtype with `/Process`), Pattern (§8.7).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfColorSpacesExtended');
+// Returns: { typeColorSpace, COLOR_SPACE_FAMILIES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeColorSpace` | `(value) => CS` | Record `{ family, ..., raw }`. |
+| `COLOR_SPACE_FAMILIES` | `Set<string>` | The 12 known families. |
+
+## Examples
+
+### Type a CS array
+
+```js
+const ext = runtime.resolve('pdfColorSpacesExtended');
+const cs = ext.typeColorSpace(arrayCs);
+cs.family;    // 'ICCBased'
+cs.n;         // 3
+cs.metadata;  // streamObj | null
+```
+
+### DeviceN
+
+```js
+cs.family;      // 'DeviceN'
+cs.names;       // ['Cyan','Magenta','Yellow','Black','PANTONE 185 C']
+cs.attributes;  // dict | null
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/colorspace/bad-shape` | `ParseError` | Neither a name nor an array. |
+| `pdf/extra/colorspace/bad-family` | `ParseError` | Entry 0 is not a name. |
+| `pdf/extra/colorspace/unknown` | `ParseError` | Family outside `COLOR_SPACE_FAMILIES`. |
+| `pdf/extra/colorspace/cal-no-dict` | `ParseError` | CalGray/CalRGB without a dict. |
+| `pdf/extra/colorspace/cal-truncated` | `ParseError` | CalGray/CalRGB truncated. |
+| `pdf/extra/colorspace/lab-truncated` | `ParseError` | Lab without a dict. |
+| `pdf/extra/colorspace/icc-no-stream` | `ParseError` | ICCBased without a stream. |
+| `pdf/extra/colorspace/indexed-truncated` | `ParseError` | Indexed incomplete. |
+| `pdf/extra/colorspace/indexed-bad-hival` | `ParseError` | hival is not an int. |
+| `pdf/extra/colorspace/sep-truncated` | `ParseError` | Separation incomplete. |
+| `pdf/extra/colorspace/devn-truncated` | `ParseError` | DeviceN incomplete. |
+
+## See also
+
+- [`pdfColor`](../content/color.md)
+- [`pdfShadingTyped`](./shading-typed.md)
+- [Extras index](./README.md)

package/docs/api/extra/content-ops-extended.md

@@ -0,0 +1,82 @@
+---
+module: pdfContentOpsExtended
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfContentOpsExtended
+
+> Extended graphics-state operators and full ExtGState catalog — ISO 32000-2 §8.4.5.
+
+**Module** `pdfContentOpsExtended` | **Source** `packages/front/office/pdf/src/extra/content-ops-extended.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+Covers `d0`/`d1` (Type 3 glyph-width operators, §9.6.4) and every key of the `/ExtGState` dictionary (Table 57). Unknown keys are preserved under `_extras`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfContentOpsExtended');
+// Returns: { typeExtGState, decodeType3CharOp, EXT_GSTATE_KEYS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeExtGState` | `(dict) => ExtGState` | Typed record covering every §8.4.5 Table 57 entry. |
+| `decodeType3CharOp` | `(op: string, operands: number[]) => { kind, wx, wy, bbox? }` | `d0` or `d1`. |
+| `EXT_GSTATE_KEYS` | frozen catalog | Map key → `{ kind, doc }`. |
+
+### Shape `ExtGState`
+
+```js
+{
+    type, lw, lc, lj, ml, d, ri, op, opNs, opm, font,
+    bg, bg2, ucr, ucr2, tr, tr2, ht, fl, sm, sa,
+    bm, sMask, ca, caNs, ais, tk, useBlackPtComp, hto,
+    raw, _extras
+}
+```
+
+## Examples
+
+### Type a full ExtGState
+
+```js
+const ext = runtime.resolve('pdfContentOpsExtended');
+const gs = ext.typeExtGState(doc._raw.resolve(extGStateRef));
+gs.ca;    // 0.5
+gs.bm;    // { type: 'name', value: 'Multiply' }
+```
+
+### Decode a Type 3 operator
+
+```js
+ext.decodeType3CharOp('d1', [600, 0, 0, 0, 500, 700]);
+// { kind: 'd1', wx: 600, wy: 0, bbox: [0, 0, 500, 700] }
+```
+
+### Key catalog
+
+```js
+ext.EXT_GSTATE_KEYS.CA.doc;  // 'stroke alpha [0,1]'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/ext-gstate/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/extra/ext-gstate/bad-type` | `ParseError` | `/Type` present and not `/ExtGState`. |
+| `pdf/extra/content-ops/unknown` | `ParseError` | Operator is neither `d0` nor `d1`. |
+| `pdf/extra/content-ops/bad-d0` | `ParseError` | `d0` does not have exactly 2 operands. |
+| `pdf/extra/content-ops/bad-d1` | `ParseError` | `d1` does not have exactly 6 operands. |
+
+## See also
+
+- [`pdfContentOps`](../content/ops.md)
+- [`pdfFont`](../font/font.md)
+- [Extras index](./README.md)

package/docs/api/extra/document-parts.md

@@ -0,0 +1,69 @@
+---
+module: pdfDocumentParts
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfDocumentParts
+
+> Document Parts hierarchical tree (`/DPartRoot`, `/DPart`, `/DPM`) — ISO/TS 32004.
+
+**Module** `pdfDocumentParts` | **Source** `packages/front/office/pdf/src/extra/document-parts.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+TS 32004 introduces a "Document Parts" tree rooted in the Catalog under `/DPartRoot`. Each node is a `/Type /DPart` dict with `/Parent`, `/DParts` (child nodes or pages), `/Start`/`/End`, `/DPM` (metadata), `/NodeNameTree`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfDocumentParts');
+// Returns: { typeDPartRoot, typeDPart, typeDPM, walkDParts }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeDPartRoot` | `(dict) => DPartRoot` | Root `/DPartRoot`. |
+| `typeDPart` | `(dict) => DPart` | A tree node. |
+| `typeDPM` | `(dict) => DPM` | Metadata dict. |
+| `walkDParts` | `(root, visit) => void` | Depth-first traversal. |
+
+## Examples
+
+### Load the root
+
+```js
+const ext = runtime.resolve('pdfDocumentParts');
+const root = ext.typeDPartRoot(doc._raw.resolve(catalog.dPartRoot));
+root.rootNode; // ref
+```
+
+### Traversal
+
+```js
+ext.walkDParts(rootNode, (node) => {
+    console.log(node.start, '-', node.end);
+});
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/dparts/root/not-dict` | `ParseError` | Root is not a dict. |
+| `pdf/extra/dparts/root/bad-type` | `ParseError` | `/Type` is not `/DPartRoot`. |
+| `pdf/extra/dparts/root/missing-node` | `ParseError` | `/DPartRootNode` absent. |
+| `pdf/extra/dparts/node/not-dict` | `ParseError` | Node is not a dict. |
+| `pdf/extra/dparts/node/bad-type` | `ParseError` | `/Type` is not `/DPart`. |
+| `pdf/extra/dparts/node/bad-dpm` | `ParseError` | `/DPM` is not a dict. |
+| `pdf/extra/dparts/dpm/not-dict` | `ParseError` | DPM is not a dict. |
+| `pdf/extra/dparts/walk/bad-visit` | `ParseError` | `visit` is not a function. |
+
+## See also
+
+- [`pdfCatalog`](../document/catalog.md)
+- [`pdfXmpExtended`](./xmp-extended.md)
+- [Extras index](./README.md)