@awacloud/pdf 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,144 @@
+---
+module: pdfLargeBundle
+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]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLargeBundle
+
+> Core PDF + P0/P1 extras — the common PDF 2.0 features.
+
+**Module** `pdfLargeBundle` | **Source** `packages/front/office/pdf/src/bundles/pdf-large.js` | **Deps** `pdf` + the 21 extras enumerated under [Extras wired](#extras-wired) (22 names total, listed literally in the frontmatter `dependencies`) | **Worker-safe** yes
+
+A module descriptor that declares the core `pdf` and **21 P0+P1 extras** as dependencies. The runtime supplies the already-constructed instances; the factory wires them into `pdf` via `.use(...)` and returns the enriched instance. Fits most production use where the long tail (PDF 1.7 legacy, deprecated filters, the linearization-dictionary builder) is not required.
+
+## 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('pdfLargeBundle');
+const doc = api.read(pdfBytes);
+doc.pages.length;
+```
+
+`@awacloud/pdf`'s root entry re-exports the **five descriptor arrays** (`fw_require`, `pkg_require`, `modules`, `extras`, `bundle`) plus every `modules` descriptor by binding name. The `extras` and `bundle` descriptors are **not** individually re-exported from the root — `import { pdfLargeBundle } from '@awacloud/pdf'` is `undefined`. Register the arrays as above, or import a single bundle descriptor from its own subpath export:
+
+```js
+import { pdfLargeBundle } from '@awacloud/pdf/pdf-large';        // or '@awacloud/pdf/bundles/pdf-large'
+```
+
+Every dependency listed in `dependencies` must be `register()`ed on the `ModuleRuntime` before `resolve('pdfLargeBundle')` — the runtime resolves by name and throws `Module not found: <name>` if one is missing. Registering all five arrays is the pattern used by the package's own test bootstrap (`tests/_helpers/build.js`); `pdf-large` itself resolves without `fw_require`/`pkg_require` registered, but the sibling bundles do not (see [`pdf-legacy`](./pdf-legacy.md)), so registering all five is the safe default.
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `pdfLargeBundle` | Descriptor `{ name, dependencies, factory }`. Resolved by `ModuleRuntime` → `pdf` instance wired with the P0+P1 extras. |
+
+The resolved instance is the core `pdf` object (`src/pdf.js`) with the 21 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 (its own name, e.g. `'pdfSigPades'`), so `api.usedExtension('pdfSigPades')` is `true` right after resolve — `api.usedExtension('pdfLargeBundle')` is `false`, since the bundle's own descriptor name is never itself passed to `.use()`. |
+
+## Extras wired
+
+| # | 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 |
+
+## When to choose
+
+- **`pdf-large`** — standard production use, typed PDF 2.0 read/write of the common features. No linearization-dictionary builder, no 3D/RichMedia, no legacy 1.7.
+- `pdf-full` — adds the linearization-dictionary builder, 3D/RichMedia, JBIG2 segment-header read, `/Info` lint, misc tail. Choose it when you need every PDF 2.0 extra.
+- `pdf-legacy` — adds XFA read, RC4 decryption helpers, LZW / CCITT fax decode, Sound/Movie/Screen typing. Choose it for PDF 1.7 reading.
+
+## Examples
+
+### Read + extra
+
+```js
+const api = rt.resolve('pdfLargeBundle');
+const doc = api.read(bytes);
+
+// Use a wired extra via api.<extName>
+const padesProfile = api.pdfSigPades.detectPadesProfile(sigDict, ctx);
+```
+
+### Write
+
+```js
+const api = rt.resolve('pdfLargeBundle');
+const out = api.write(doc);   // PDF 2.0 bytes
+```
+
+### Header only
+
+```js
+const api = rt.resolve('pdfLargeBundle');
+api.header(bytes);   // { version: '2.0', end: <offset> } — no xref/catalog walk
+```
+
+### Checking a wired extra
+
+```js
+const api = rt.resolve('pdfLargeBundle');
+api.usedExtension('pdfSigPades');       // true — wired by the bundle factory
+api.usedExtension('not-a-real-extra');  // false
+```
+
+### Adding a custom extra
+
+```js
+const api = rt.resolve('pdfLargeBundle');
+api.use({ name: 'myThing', register(self) { return { myThing: {/* … */} }; } });
+```
+
+## 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-full`](./pdf-full.md)
+- [`pdf-legacy`](./pdf-legacy.md)
+- [Bundles index](./README.md)
+- [Extras index](../extra/README.md)

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

@@ -0,0 +1,169 @@
+---
+module: pdfLegacyBundle
+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, pdfLegacyXfaRead, pdfLegacyRc4Read, pdfLegacyDeprecatedFilters, pdfLegacyDeprecatedAnnots]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLegacyBundle
+
+> `pdfFullBundle` + the PDF 1.7 legacy readers.
+
+**Module** `pdfLegacyBundle` | **Source** `packages/front/office/pdf/src/bundles/pdf-legacy.js` | **Deps** `pdf` + the 31 extras enumerated under [Extras wired](#extras-wired) (32 names total, listed literally in the frontmatter `dependencies`; the `@awacloud/fw` `lzw` binding is a further transitive requirement of `pdfLegacyDeprecatedFilters`, not a direct entry) | **Worker-safe** yes
+
+A module descriptor that adds the `legacy-*` extras on top of `pdfFullBundle`:
+
+- `legacy-xfa-read` — accepts `/XFA` on read, surfaces it as opaque XML.
+- `legacy-rc4-read` — RC4 v2/v3 password validation + stream decrypt.
+- `legacy-deprecated-filters` — LZWDecode (via the `@awacloud/fw` `lzw` factory), CCITTFaxDecode (a full ITU-T T.4 / T.6 decoder, through `pdfCcittFaxDecoder`), DCT/JPX passthrough. These decoders are called through the extra's own API; they are not registered into `pdfFilterDispatch`, so `read` does not apply them to streams by itself.
+- `legacy-deprecated-annots` — Sound/Movie/Screen typing (read-only; no conversion to RichMedia).
+
+`pdfInfoDictDeprecated` (Info dict lint) is already wired by `pdf-full`; `pdf-legacy` re-lists it idempotently.
+
+**Writing PDF 1.7 is never supported** — `write` always emits a `%PDF-2.0` header. It does **not** convert legacy content: it re-emits the objects of the model it is given, so an `/XFA` entry, an RC4 `/Encrypt` dictionary, an LZW-filtered stream or a Sound/Movie annotation read from a 1.7 file is written back as it was. Converting it is the caller's work.
+
+## 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);   // provides the real `lzw` fw binding
+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('pdfLegacyBundle');
+const doc = api.read(oldPdfBytes);   // PDF 1.7 OK
+const out = api.write(doc);          // always PDF 2.0
+```
+
+The `extras` and `bundle` descriptors are **not** re-exported from the package root by binding name — `import { pdfLegacyBundle } from '@awacloud/pdf'` is `undefined`. Register the arrays as above, or import the single descriptor from its own subpath export (`import { pdfLegacyBundle } from '@awacloud/pdf/pdf-legacy';`). Unlike `pdf-large` and `pdf-full`, `pdf-legacy` **cannot** be resolved without `fw_require` registered: omitting it throws `Module not found: lzw`.
+
+`pdfLegacyDeprecatedFilters` validates its `lzw` dependency eagerly at construction time — if a stub/invalid binding is registered under the name `lzw` instead of the real `@awacloud/fw/io/compress/lzw.js` export, resolving the bundle throws `pdf/filters/missing-lzw` immediately (not lazily on first decode).
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `pdfLegacyBundle` | Descriptor `{ name, dependencies, factory }`. Resolved by `ModuleRuntime` → `pdf` instance wired with every P0-P3 extra + the 4 legacy extras (listed under [Extras wired](#extras-wired)). |
+
+The resolved instance is the core `pdf` object (`src/pdf.js`) with the 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 (accepts PDF 1.7). |
+| `header` | `(bytes: Uint8Array) => { version, end }` | Header-only read, no xref/catalog walk. |
+| `write` | `(doc) => Uint8Array` | Always 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. `'pdfLegacyRc4Read'`), so `api.usedExtension('pdfLegacyRc4Read')` is `true` right after resolve — `api.usedExtension('pdfLegacyBundle')` is `false`, since the bundle's own descriptor name is never itself passed to `.use()`. |
+
+## Extras wired
+
+Items 1-27 are [`pdf-full`](./pdf-full.md)'s extras, re-listed here so every member of the resolved instance is documented on this page; items 28-31 are `pdf-legacy`'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 |
+| 28 | [`pdfLegacyXfaRead`](../extra/legacy-xfa-read.md) | legacy | read-only |
+| 29 | [`pdfLegacyRc4Read`](../extra/legacy-rc4-read.md) | legacy | read-only |
+| 30 | [`pdfLegacyDeprecatedFilters`](../extra/legacy-deprecated-filters.md) | legacy | read (needs the `lzw` + `pdfCcittFaxDecoder` dependencies) |
+| 31 | [`pdfLegacyDeprecatedAnnots`](../extra/legacy-deprecated-annots.md) | legacy | read |
+
+`pdfCcittFaxDecoder` (the CCITT Fax decode helper `legacy-deprecated-filters` depends on) is a separate, 32nd module in the package's overall `extras` manifest array, but it is a private sub-dependency here — it is resolved transitively, not wired onto the bundle's own namespace via a `.use()` call, so there is no `api.pdfCcittFaxDecoder`.
+
+## When to choose
+
+- `pdf-large` — strict PDF 2.0 production minimal.
+- `pdf-full` — strict PDF 2.0 complete.
+- **`pdf-legacy`** — mixed legacy corpus (1.7 + 2.0). Choose it when ingesting older PDFs (XFA, RC4, LZW, Sound/Movie); conversion to PDF 2.0 equivalents is left to the caller.
+
+## Examples
+
+### Reading an RC4-encrypted PDF 1.7 file
+
+`read` refuses an encrypted file (`pdf/document/encrypted`); opt in to the raw
+container, then decrypt with the extra's helpers (see
+[`pdfLegacyRc4Read`](../extra/legacy-rc4-read.md) for the `params` shape):
+
+```js
+const api = rt.resolve('pdfLegacyBundle');
+const doc = api.read(pdf17Bytes, { allowEncrypted: true });   // strings and streams still ciphertext
+const r = api.pdfLegacyRc4Read.validateUserPassword('', params);
+if (r.ok) {
+    const plain = api.pdfLegacyRc4Read.decryptStream(r.fileKey, objNum, gen, streamBytes);
+}
+```
+
+### Reading an XFA form
+
+```js
+const api = rt.resolve('pdfLegacyBundle');
+const doc = api.read(xfaFormBytes);
+const xfa = api.pdfLegacyXfaRead.readXfa(acroFormDict.entries.XFA);
+// xfa._legacy.xfa: the XDP payload, opaque; api.write(doc) keeps /XFA as it was
+```
+
+### Legacy filter
+
+```js
+const plain = api.pdfLegacyDeprecatedFilters.lzwDecode(streamBytes, { EarlyChange: 1 });
+```
+
+### Header only
+
+```js
+api.header(pdf17Bytes);   // { version: '1.7', end: <offset> } — no xref/catalog walk
+```
+
+### Checking a wired extra
+
+```js
+api.usedExtension('pdfLegacyRc4Read');  // true — wired by the bundle factory
+api.usedExtension('not-a-real-extra');  // false
+```
+
+## 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). |
+| `pdf/filters/missing-lzw` | `ParseError` | `pdfLegacyDeprecatedFilters` is constructed without a valid `@awacloud/fw` `lzw` factory output (`decode`/`encode` functions). |
+| `pdf/filters/missing-ccitt` | `ParseError` | Same, for a missing/invalid `pdfCcittFaxDecoder` output. |
+
+## See also
+
+- [`pdf-large`](./pdf-large.md)
+- [`pdf-full`](./pdf-full.md)
+- [Bundles index](./README.md)
+- [Extras index](../extra/README.md)

package/docs/api/content/README.md

@@ -0,0 +1,29 @@
+# Content — ISO 32000-2 §7.8 / §8 / §9.3–§9.4
+
+Content-stream layer: decoded `Uint8Array` → typed ops → gstate / text / colour
+applied, plus typed XObjects.
+
+| Module | Returns | Deps | Description |
+|--------|---------|------|-------------|
+| [`pdfContentOps`](./ops.md) | `{ OPS, OP_NAMES, lookupOp, isOp }` | none | Operator table §8.2 + §9.4. |
+| [`pdfContentStream`](./stream.md) | `{ parseContentStream }` | `pdfErrors`, `pdfParser`, `pdfContentOps` | Bytes → ops §7.8. |
+| [`pdfGraphics`](./graphics.md) | `{ GStateStack, createStack, applyOp, initialGState, mulCtm }` | `pdfErrors` | Graphics-state stack §8.4. |
+| [`pdfText`](./text.md) | `{ setFont, beginTextObject, td, tdSetLeading, setTextMatrix, nextLine, rawStringBytes, extractText }` | `pdfErrors` | Text state + Tm/Tlm §9.3. |
+| [`pdfColor`](./color.md) | `{ applyColorOp }` | `pdfErrors` | Colour §8.6. |
+| [`pdfImages`](./images.md) | `{ typeImageXObject, typeFormXObject, typeXObject }` | `pdfErrors`, `pdfParser` | XObjects §8.9 / §8.10. |
+
+## Common pattern
+
+```js
+const cs = runtime.resolve('pdfContentStream');
+const g  = runtime.resolve('pdfGraphics');
+const ops = cs.parseContentStream(decodedBytes);
+const stack = g.createStack();
+for (const op of ops) g.applyOp(stack, op);
+```
+
+## See also
+
+- [Document layer](../document/README.md) — supplies `pageDict` and Resources.
+- [Font layer](../font/README.md) — feeds `pdfText.extractText`.
+- [Syntax layer](../syntax/README.md) — the underlying `pdfParser`.

package/docs/api/content/color.md

@@ -0,0 +1,99 @@
+---
+module: pdfColor
+category: pdf/content
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfColor
+
+> Applying the colour operators to a graphics state — ISO 32000-2 §8.6.
+
+**Module** `pdfColor` | **Source** `packages/front/office/pdf/src/content/color.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Mutates `gstate.strokeColor` / `gstate.fillColor` for the 12 PDF colour
+operators: `g`/`G`, `rg`/`RG`, `k`/`K`, `cs`/`CS`, `sc`/`SC`, `scn`/`SCN`.
+Pattern / Separation / DeviceN spaces accept a trailing `/PatternName` on
+`scn`/`SCN` — captured as `gstate.<slot>.pattern`. When `scn`/`SCN` carries no
+trailing name, any previously captured `pattern` is deleted.
+
+## Resolve
+
+```js
+const c = runtime.resolve('pdfColor');
+// Returns: { applyColorOp }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `applyColorOp` | `(gstate, { op, args }) => void` | Mutates the gstate in place. |
+
+### Operator → mutation
+
+| Op | Target | Effect |
+|----|--------|--------|
+| `g` / `G` | fill / stroke | `{ space: 'DeviceGray', components: [n] }` |
+| `rg` / `RG` | fill / stroke | `{ space: 'DeviceRGB', components: [r,g,b] }` |
+| `k` / `K` | fill / stroke | `{ space: 'DeviceCMYK', components: [c,m,y,k] }` |
+| `cs` / `CS` | fill / stroke | `{ space: name, components: device default }` |
+| `sc` / `SC` | fill / stroke | replaces `components` only (numeric args kept, others dropped) |
+| `scn` / `SCN` | fill / stroke | `components` plus an optional `pattern` when the last arg is a name |
+
+### Defaults per named space
+
+| Space | Default `components` |
+|-------|----------------------|
+| `DeviceGray` | `[0]` |
+| `DeviceRGB` | `[0, 0, 0]` |
+| `DeviceCMYK` | `[0, 0, 0, 1]` |
+| any other | `[]` |
+
+## Examples
+
+### Set the fill colour in RGB
+
+```js
+const c = runtime.resolve('pdfColor');
+c.applyColorOp(gstate, {
+    op: 'rg',
+    args: [{type:'real',value:0.8},{type:'real',value:0.2},{type:'real',value:0.1}]
+});
+gstate.fillColor;  // { space:'DeviceRGB', components:[0.8,0.2,0.1] }
+```
+
+### Set the stroke space
+
+```js
+c.applyColorOp(gstate, { op: 'CS', args: [{type:'name',value:'DeviceCMYK'}] });
+gstate.strokeColor;  // { space:'DeviceCMYK', components:[0,0,0,1] }
+```
+
+### Pattern through `scn`
+
+```js
+c.applyColorOp(gstate, {
+    op: 'scn',
+    args: [{type:'real',value:0.5}, {type:'name',value:'P1'}]
+});
+gstate.fillColor.pattern;     // 'P1'
+gstate.fillColor.components;  // [0.5]
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/color/unknown-op` | `ContractError` | `applyColorOp` called with a non-colour operator. |
+| `pdf/color/bad-name` | `ContractError` | `cs`/`CS` without a `name` argument. |
+| `pdf/color/short-args` | `ContractError` | Fewer numeric arguments than required by `g`/`rg`/`k` and their stroke variants. |
+| `pdf/color/bad-num` | `ContractError` | An argument expected to be numeric has another type. |
+
+## See also
+
+- [`pdfGraphics`](./graphics.md) — hosts `strokeColor`/`fillColor`.
+- [`pdfContentStream`](./stream.md) — produces the ops.
+- [`pdfContentOps`](./ops.md) — categorisation.

package/docs/api/content/graphics.md

@@ -0,0 +1,114 @@
+---
+module: pdfGraphics
+category: pdf/content
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfGraphics
+
+> Graphics-state stack for a content-stream interpreter — ISO 32000-2 §8.4.
+
+**Module** `pdfGraphics` | **Source** `packages/front/office/pdf/src/content/graphics.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Implements the **device-independent** subset (§8.4.1, Table 53) of the graphics
+state: CTM, line width/cap/join, miter limit, dash pattern, rendering intent,
+flatness — plus the nested `text` sub-tree (driven by [`pdfText`](./text.md))
+and `strokeColor`/`fillColor` (driven by [`pdfColor`](./color.md)). This is
+**not** a renderer: it is a faithful model of the `gstate` chain that the upper
+layers (text extraction, MCID tracking, redaction) consume.
+
+## Resolve
+
+```js
+const g = runtime.resolve('pdfGraphics');
+// Returns: { GStateStack, createStack, applyOp, initialGState, mulCtm }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `GStateStack` | `new GStateStack()` | Instance, starting from `initialGState`. |
+| `createStack` | `() => GStateStack` | Equivalent helper. |
+| `applyOp` | `(stack, { op, args }, handlers?) => void` | Applies one gstate op. |
+| `initialGState` | `() => object` | Identity-state snapshot. |
+| `mulCtm` | `(a: number[6], b: number[6]) => number[6]` | 2×3 matrix product. |
+
+### `GStateStack` methods
+
+| Method | Description |
+|--------|-------------|
+| `current()` | Top of stack (mutable). |
+| `save()` | `q` — pushes a deep copy of the sensitive fields. |
+| `restore()` | `Q` — pops; throws `pdf/gstate/unbalanced-Q` on an empty stack. |
+| `depth()` | Current depth (≥ 1). |
+| `concatCtm(matrix)` | `cm` — `ctm = matrix × ctm`. |
+
+### `gstate` shape
+
+```js
+{
+    ctm: [1,0,0,1,0,0],
+    lineWidth: 1, lineCap: 0, lineJoin: 0,
+    miterLimit: 10,
+    dash: { array: [], phase: 0 },
+    renderingIntent: 'RelativeColorimetric',
+    flatness: 1,
+    text: { charSpace: 0, wordSpace: 0, scale: 100, leading: 0,
+            font: null, fontSize: 0, renderMode: 0, rise: 0 },
+    strokeColor: { space: 'DeviceGray', components: [0] },
+    fillColor:   { space: 'DeviceGray', components: [0] }
+}
+```
+
+`applyOp` routes only `q`, `Q`, `cm`, `w`, `J`, `j`, `M`, `d`, `ri`, `i`. Any
+other operator falls through to `handlers.unhandled(op, stack)` when supplied.
+
+## Examples
+
+### Walking a content stream
+
+```js
+const g = runtime.resolve('pdfGraphics');
+const stack = g.createStack();
+for (const op of ops) {
+    g.applyOp(stack, op, {
+        unhandled: (o) => {
+            if (o.op.startsWith('T')) applyTextOp(stack.current(), o);
+        }
+    });
+}
+```
+
+### Composing CTMs
+
+```js
+const scale = [2, 0, 0, 2, 0, 0];
+const translate = [1, 0, 0, 1, 100, 50];
+const ctm = g.mulCtm(scale, translate);
+```
+
+### Detecting an unbalanced stack
+
+```js
+try { g.applyOp(stack, { op: 'Q', args: [] }); }
+catch (e) { if (e.code === 'pdf/gstate/unbalanced-Q') { /* … */ } }
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/gstate/unbalanced-Q` | `ContractError` | `Q` without a matching `q`. |
+| `pdf/gstate/bad-cm` | `ContractError` | `cm` matrix is not 6 elements. |
+| `pdf/gstate/bad-arg-type` | `ContractError` | Non-numeric argument for `w`, `J`, `j`, `M`, `i`. |
+| `pdf/gstate/bad-name-arg` | `ContractError` | Non-`name` argument for `ri`. |
+
+## See also
+
+- [`pdfContentStream`](./stream.md) — produces the op list.
+- [`pdfText`](./text.md) — the nested text state.
+- [`pdfColor`](./color.md) — `strokeColor` / `fillColor`.

package/docs/api/content/images.md

@@ -0,0 +1,124 @@
+---
+module: pdfImages
+category: pdf/content
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfImages
+
+> Typing of XObjects (Image + Form) — ISO 32000-2 §8.9 / §8.10.
+
+**Module** `pdfImages` | **Source** `packages/front/office/pdf/src/content/images.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types an XObject stream into a flat, ready-to-consume structure. It
+distinguishes:
+
+- **Image XObject** (`/Subtype /Image`, §8.9) — carries Width, Height,
+  ColorSpace, BitsPerComponent, Filter, DecodeParms, Decode, ImageMask, Mask,
+  SMask, Interpolate, Intent, Metadata.
+- **Form XObject** (`/Subtype /Form`, §8.10) — carries FormType, BBox, Matrix,
+  Resources, Group, Metadata, StructParent(s).
+
+The `raw` bytes are passed through **untouched**: it is the consumer's job
+(renderer) to decode the `/Filter` chain via `pdfFilterDispatch`.
+
+## Resolve
+
+```js
+const im = runtime.resolve('pdfImages');
+// Returns: { typeImageXObject, typeFormXObject, typeXObject }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeImageXObject` | `(stream) => ImageXObject` | Image typing. |
+| `typeFormXObject` | `(stream) => FormXObject` | Form typing. |
+| `typeXObject` | `(stream) => ImageXObject \| FormXObject \| Opaque` | Dispatch on `/Subtype`. |
+
+### `ImageXObject` shape
+
+```js
+{
+    kind: 'image',
+    width, height,
+    bitsPerComponent,        // int or null
+    colorSpace, filter, decodeParms, decode,   // raw typed objects or null
+    imageMask,               // boolean, default false
+    mask, sMask,
+    interpolate,             // boolean, default false
+    intent,                  // name or null
+    metadata,
+    raw: Uint8Array, dict
+}
+```
+
+### `FormXObject` shape
+
+```js
+{
+    kind: 'form',
+    formType: 1,             // /FormType, default 1
+    bbox:   [llx,lly,urx,ury] | null,
+    matrix: [1,0,0,1,0,0],   // default
+    resources, group, metadata,
+    structParents, structParent,   // ints or null
+    raw: Uint8Array, dict
+}
+```
+
+When `/Subtype` is neither `Image` nor `Form` (e.g. the PostScript XObject
+deprecated in PDF 2.0), `typeXObject` returns `{ kind: <subtype>, raw, dict }`.
+
+## Examples
+
+### Type an XObject invoked by `Do`
+
+```js
+const im = runtime.resolve('pdfImages');
+const xobjName = op.args[0].value;  // 'Im1'
+const stream = doc._raw.resolve(resources.XObject[xobjName]);
+const typed = im.typeXObject(stream);
+if (typed.kind === 'image') console.log(typed.width, typed.height);
+```
+
+### Type an image directly
+
+```js
+const img = im.typeImageXObject(stream);
+img.colorSpace;   // typed name / array / ref
+img.filter;       // typed name / array
+img.raw;          // Uint8Array — feed to pdfFilterDispatch
+```
+
+### Form XObject with a BBox
+
+```js
+const form = im.typeFormXObject(stream);
+form.bbox;        // [0, 0, 612, 792]
+form.matrix;      // [1, 0, 0, 1, 0, 0]
+form.resources;   // dict — pass to typeResources
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/image/not-stream` | `ParseError` | Argument is not a typed stream. |
+| `pdf/image/wrong-subtype` | `ParseError` | `/Subtype` present but not `/Image`. |
+| `pdf/image/missing-dim` | `ParseError` | `/Width` or `/Height` missing. |
+| `pdf/form-xobj/not-stream` | `ParseError` | Argument is not a typed stream. |
+| `pdf/form-xobj/wrong-subtype` | `ParseError` | `/Subtype` present but not `/Form`. |
+| `pdf/xobject/not-stream` | `ParseError` | Argument is not a typed stream. |
+| `pdf/xobject/bad-type` | `ParseError` | `/Type` present but not `/XObject`. |
+| `pdf/xobject/missing-subtype` | `ParseError` | `/Subtype` missing. |
+
+## See also
+
+- [`pdfContentStream`](./stream.md) — emits the `Do` op.
+- [`pdfResources`](../document/resources.md) — resolves the named `/XObject`.
+- [Filters](../syntax/filters/README.md) — decoding `raw`.