@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/metadata/info.md

@@ -0,0 +1,70 @@
+---
+module: pdfInfo
+category: pdf/metadata
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfInfo
+
+> Document Information dictionary — ISO 32000-2 §14.3.3.
+
+**Module** `pdfInfo` | **Source** `packages/front/office/pdf/src/metadata/info.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+The trailer's `/Info` entry carries legacy metadata: `/Title`, `/Author`, `/Subject`, `/Keywords`, `/Creator`, `/Producer`, `/CreationDate`, `/ModDate`, `/Trapped` (`True`/`False`/`Unknown`). PDF 2.0 deprecates it in favour of XMP (Catalog `/Metadata`), but `/Info` remains common. **Dates are returned as the raw PDF date string** (`D:YYYYMMDDHHmmSSOHH'mm'`) — `typeInfo` does not parse them into `Date` objects; the caller parses the string if it needs a `Date`.
+
+## Resolve
+
+```js
+const info = runtime.resolve('pdfInfo');
+// Returns: { typeInfo }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeInfo` | `(dict) => Info` | Typing. |
+
+### Shape `Info`
+
+```js
+{
+    title, author, subject, keywords, creator, producer,   // strings
+    creationDate: string | undefined,   // raw D:YYYYMMDDHHmmSSOHH'mm', unparsed
+    modDate: string | undefined,        // raw D:YYYYMMDDHHmmSSOHH'mm', unparsed
+    trapped: 'True' | 'False' | 'Unknown' | undefined,
+    raw, _extras
+}
+```
+
+## Examples
+
+### Reading the trailer's Info
+
+```js
+const info = runtime.resolve('pdfInfo').typeInfo(doc._raw.resolve(trailer.info));
+info.title;
+info.creationDate;   // 'D:20260115120000+01\'00\'' — raw, parse it yourself
+```
+
+### Prepress check
+
+```js
+if (info.trapped !== 'True') console.warn('document not trapped');
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/info/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/info/bad-string` | `ParseError` | A text field is not a string. |
+| `pdf/info/bad-date` | `ParseError` | `/CreationDate`/`/ModDate` is not a string. |
+| `pdf/info/bad-trapped` | `ParseError` | `/Trapped` is outside the allowed set. |
+
+## See also
+
+- [`pdfXmp`](./xmp.md) · [`pdfTrailer`](../syntax/trailer.md)

package/docs/api/metadata/xmp.md

@@ -0,0 +1,62 @@
+---
+module: pdfXmp
+category: pdf/metadata
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfXmp
+
+> XMP Metadata stream — ISO 32000-2 §14.3.2 / ISO 16684-1 (XMP).
+
+**Module** `pdfXmp` | **Source** `packages/front/office/pdf/src/metadata/xmp.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+The Catalog may carry `/Metadata`, pointing to a stream `/Type /Metadata /Subtype /XML`. The content is an XMP (RDF/XML) packet. This module validates the stream's conformance (`/Type`, `/Subtype`, dict presence) and exposes the raw bytes; parsing the XML/RDF itself is left to the caller (no XML dependency embedded).
+
+## Resolve
+
+```js
+const xmp = runtime.resolve('pdfXmp');
+// Returns: { typeXmpStream }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeXmpStream` | `(stream) => { type: 'Metadata', subtype: 'XML', bytes: Uint8Array, raw: PdfStream }` | Validation + extraction. |
+
+## Examples
+
+### Extracting the packet text
+
+```js
+const xmp = runtime.resolve('pdfXmp').typeXmpStream(
+    doc._raw.resolve(catalog.metadata)
+);
+const xml = new TextDecoder('utf-8').decode(xmp.bytes);
+// → '<?xpacket begin=…?><x:xmpmeta …>…'
+```
+
+### Common XMP fields
+
+An XMP packet typically carries:
+- `dc:title`, `dc:creator`, `dc:description` (Dublin Core).
+- `xmp:CreateDate`, `xmp:ModifyDate`, `xmp:CreatorTool`.
+- `pdf:Producer`, `pdf:Keywords`.
+- `pdfaid:part` / `pdfuaid:part` (PDF/A and PDF/UA conformance).
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/xmp/not-stream` | `ParseError` | Argument is not a stream. |
+| `pdf/xmp/no-dict` | `ParseError` | Stream has no dict. |
+| `pdf/xmp/bad-type` | `ParseError` | `/Type` is not `/Metadata`. |
+| `pdf/xmp/bad-subtype` | `ParseError` | `/Subtype` is not `/XML`. |
+
+## See also
+
+- [`pdfInfo`](./info.md) · [`pdfCatalog`](../document/catalog.md)

package/docs/api/ocg/README.md

@@ -0,0 +1,23 @@
+# Optional Content (Layers) — ISO 32000-2 §8.11
+
+Optional layers — conditional visibility of content.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfOCG`](./ocg.md) | `{ typeOCG, typeUsage }` | `pdfErrors`, `pdfParser` | OCG dict §8.11.2. |
+| [`pdfOCConfig`](./config.md) | `{ typeOCConfig, typeUsageApp }` | `pdfErrors`, `pdfParser` | OC Configuration §8.11.4. |
+
+## Read pattern
+
+```js
+const ocg = runtime.resolve('pdfOCG');
+const cfg = runtime.resolve('pdfOCConfig');
+const props = catalog.ocProperties;
+const groups = props.entries.OCGs.items.map(ref => ocg.typeOCG(resolveRef(ref)));
+const defaultCfg = cfg.typeOCConfig(resolveRef(props.entries.D));
+```
+
+## See also
+
+- [Catalog](../document/catalog.md) — `/OCProperties`.
+- [Content streams](../content/README.md) — `BMC /OC … EMC`.

package/docs/api/ocg/config.md

@@ -0,0 +1,95 @@
+---
+module: pdfOCConfig
+category: pdf/ocg
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfOCConfig
+
+> Optional Content Configuration — ISO 32000-2 §8.11.4.
+
+**Module** `pdfOCConfig` | **Source** `packages/front/office/pdf/src/ocg/config.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types the OC configuration dict referenced by `/OCProperties /D` (default config) or an entry of `/OCProperties /Configs`. Entries: `/Name`, `/Creator`, `/BaseState` (`ON`/`OFF`/`Unchanged`), `/ON` (refs forced visible), `/OFF` (refs forced hidden), `/Locked` (refs the user cannot toggle), `/Intent` (a name or array of names), `/AS` (auto-state — array of UsageApplication dicts), `/Order` (display tree for viewers, kept raw), `/ListMode` (`AllPages`/`VisiblePages`), `/RBGroups` (radio-button groups).
+
+## Resolve
+
+```js
+const cfg = runtime.resolve('pdfOCConfig');
+// Returns: { typeOCConfig, typeUsageApp }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeOCConfig` | `(dict) => OCConfig` | Typing. |
+| `typeUsageApp` | `(d) => UsageApplication` | Typing of one `/AS[*]` entry. |
+
+### Shape `OCConfig`
+
+```js
+{
+    name?, creator?,
+    baseState?: 'ON' | 'OFF' | 'Unchanged',
+    on?: PdfRef[], off?: PdfRef[], locked?: PdfRef[],
+    intent?: string[],
+    as?: UsageApplication[],
+    order?: PdfNode[],                 // /Order items, kept raw
+    listMode?: string,
+    rbGroups?: PdfRef[][],
+    raw, _extras
+}
+```
+
+### Shape `UsageApplication`
+
+```js
+{ event?: string, ocgs?: PdfRef[], category?: string[], raw }
+```
+
+## Examples
+
+### Default configuration
+
+```js
+const cfg = runtime.resolve('pdfOCConfig');
+const c = cfg.typeOCConfig(doc._raw.resolve(catalog.ocProperties.entries.D));
+c.baseState;      // 'ON'
+c.on;             // [ref, …] forced ON
+c.rbGroups;       // mutually-exclusive groups
+```
+
+### Applying UsageApplication entries
+
+```js
+for (const uaDict of c.as ?? []) {
+    const ua = cfg.typeUsageApp(uaDict);
+    ua.event;       // 'View' | 'Print' | 'Export'
+    ua.ocgs;        // refs this application applies to
+    ua.category;    // ['Zoom', …]
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/ocg/config/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/ocg/config/bad-name` | `ParseError` | `/Name` is not a string. |
+| `pdf/ocg/config/bad-creator` | `ParseError` | `/Creator` is not a string. |
+| `pdf/ocg/config/bad-base-state` | `ParseError` | `/BaseState` outside `ON`/`OFF`/`Unchanged`. |
+| `pdf/ocg/config/bad-intent` | `ParseError` | `/Intent` is neither a name nor an array. |
+| `pdf/ocg/config/bad-as` | `ParseError` | `/AS` is not an array. |
+| `pdf/ocg/config/bad-order` | `ParseError` | `/Order` is not an array. |
+| `pdf/ocg/config/bad-list-mode` | `ParseError` | `/ListMode` is not a name. |
+| `pdf/ocg/config/bad-rb` | `ParseError` | `/RBGroups` is not an array. |
+| `pdf/ocg/config/bad-refs` | `ParseError` | `/ON`/`/OFF`/`/Locked` is not an array. |
+| `pdf/ocg/config/as/not-dict` | `ParseError` | An `/AS` entry is not a dict. |
+
+## See also
+
+- [`pdfOCG`](./ocg.md) · [`pdfCatalog`](../document/catalog.md)

package/docs/api/ocg/ocg.md

@@ -0,0 +1,77 @@
+---
+module: pdfOCG
+category: pdf/ocg
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfOCG
+
+> Optional Content Group — ISO 32000-2 §8.11.2.
+
+**Module** `pdfOCG` | **Source** `packages/front/office/pdf/src/ocg/ocg.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types a `/Type /OCG` dict — a named optional (togglable) layer. Entries: `/Name` (required string), `/Intent` (a name or an array of names — e.g. `View`, `Design`), `/Usage` (sub-dict — `CreatorInfo`, `Language`, `Export`, `Zoom`, `Print`, `View`, `User`, `PageElement`, plus the state convenience entries `ViewState`/`PrintState`/`ExportState`). `typeUsage` decodes that sub-dict separately.
+
+## Resolve
+
+```js
+const ocg = runtime.resolve('pdfOCG');
+// Returns: { typeOCG, typeUsage }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `typeOCG` | `(dict) => { name, intent?, usage?, raw, _extras }` | OCG dict. |
+| `typeUsage` | `(dict) => Usage` | The `/Usage` sub-dict. |
+
+### Shape `Usage`
+
+`typeUsage` decodes the three `*State` entries into plain name strings; every other known `/Usage` entry (`creatorInfo`, `language`, `export`, `zoom`, `print`, `view`, `user`, `pageElement`) is copied through **as its raw parsed node** (still a `{ type: 'dict', entries: {...} }` object, not further typed) — callers that need its fields must read `entries` themselves.
+
+```js
+{
+    creatorInfo?, language?, export?, zoom?, print?, view?, user?, pageElement?,  // raw nodes
+    viewState?: string, printState?: string, exportState?: string,               // decoded names
+    raw, _extras
+}
+```
+
+## Examples
+
+### Reading an OCG
+
+```js
+const ocg = runtime.resolve('pdfOCG');
+const g = ocg.typeOCG(doc._raw.resolve(ocgRef));
+g.name;          // 'Layer 1'
+g.intent;        // ['View', 'Design']
+```
+
+### Visibility state
+
+```js
+const u = ocg.typeUsage(g.usage);
+u.viewState === 'ON';           // decoded convenience state
+u.zoom?.entries?.min?.value;    // /Zoom kept raw — read its entries directly
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/ocg/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/ocg/bad-type` | `ParseError` | `/Type` is not `/OCG`. |
+| `pdf/ocg/missing-name` | `ParseError` | `/Name` absent or not a string. |
+| `pdf/ocg/bad-usage` | `ParseError` | `/Usage` is not a dict. |
+| `pdf/ocg/usage/not-dict` | `ParseError` | `typeUsage` receives a non-dict. |
+| `pdf/ocg/usage/bad-state` | `ParseError` | `/ViewState`, `/PrintState` or `/ExportState` is not a name. |
+
+## See also
+
+- [`pdfOCConfig`](./config.md) — OC configuration.
+- [`pdfCatalog`](../document/catalog.md) — `/OCProperties`.

package/docs/api/outline/README.md

@@ -0,0 +1,11 @@
+# Outline — ISO 32000-2 §12.3.3
+
+Bookmarks / navigable table of contents.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfOutline`](./outline.md) | `{ walkOutline, typeOutlineItem }` | `pdfErrors`, `pdfParser` | §12.3.3 — flat depth-first walk. |
+
+## See also
+
+- [Destination](../destination/README.md) · [Action](../action/README.md)

package/docs/api/outline/outline.md

@@ -0,0 +1,107 @@
+---
+module: pdfOutline
+category: pdf/outline
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfOutline
+
+> Document outline (bookmarks) — ISO 32000-2 §12.3.3.
+
+**Module** `pdfOutline` | **Source** `packages/front/office/pdf/src/outline/outline.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+The outline (Catalog `/Outlines`) is a doubly-linked tree. Each item carries `/Title`, `/Parent`, `/Prev`, `/Next`, `/First`, `/Last`, `/Count` (signed — negative means collapsed), `/A` (action) or `/Dest`, `/C` (RGB colour), `/F` (style flags: 1 italic, 2 bold). `/SE` (structure element) is accepted but not decoded (kept in `_extras`). `walkOutline` walks the tree depth-first, enforcing a depth limit and detecting cycles.
+
+**`walkOutline` returns a flat array, not a nested tree** — there is no `children` field. Each record keeps its `parent`/`prev`/`next`/`first`/`last` entries as unresolved refs (`{ type: 'ref', num, gen }`); build a tree from the flat list yourself if you need one (e.g. by indexing records by `ref.num`).
+
+## Resolve
+
+```js
+const out = runtime.resolve('pdfOutline');
+// Returns: { walkOutline, typeOutlineItem }
+```
+
+## API
+
+| Method | Signature | Returns |
+|---------|-----------|----------|
+| `walkOutline` | `(rootDict, resolveRef, opts?) => OutlineItem[]` | Flat depth-first list. |
+| `typeOutlineItem` | `(dict) => OutlineItem` | Single item, refs left unresolved. |
+
+`opts`: `{ maxDepth = 64, maxItems = 100000 }`.
+
+### Shape `OutlineItem`
+
+```js
+{
+    title: string,
+    parent?, prev?, next?, first?, last?,   // { type: 'ref', num, gen } — unresolved
+    count?: number,                          // signed
+    action?,                                 // /A, kept raw
+    dest?,                                    // /Dest, kept raw
+    color?: [r, g, b],                        // /C, 3 numbers
+    F?: number,                               // style flags
+    ref?: { num, gen },                       // set by walkOutline only
+    raw, _extras
+}
+```
+
+## Examples
+
+### Full walk (flat list)
+
+```js
+const out  = runtime.resolve('pdfOutline');
+const root = doc._raw.resolve(doc.catalog.outlines);
+const items = out.walkOutline(root, doc._raw.resolve);
+for (const it of items) console.log(it.title);
+```
+
+### Rebuilding a tree from the flat list
+
+```js
+const byNum = new Map(items.map(it => [it.ref.num, it]));
+function children(it) {
+    const kids = [];
+    let cur = it.first;
+    while (cur) {
+        const child = byNum.get(cur.num);
+        if (!child) break;
+        kids.push(child);
+        cur = child.next;
+    }
+    return kids;
+}
+```
+
+### Navigating from an item
+
+```js
+if (item.dest) {
+    const d = runtime.resolve('pdfDestination')
+        .typeDestination(item.dest, catalog.names?.entries?.Dests, resolveRef);
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/outline/not-dict` | `ParseError` | Root or resolved item is not a dict. |
+| `pdf/outline/bad-first` | `ParseError` | `/First` is not a ref. |
+| `pdf/outline/no-resolver` | `ParseError` | `resolveRef` not supplied. |
+| `pdf/outline/max-depth` | `ParseError` | Depth exceeds `opts.maxDepth`. |
+| `pdf/outline/non-ref-sibling` | `ParseError` | A sibling entry is not a ref. |
+| `pdf/outline/cycle` | `ParseError` | An item was visited twice. |
+| `pdf/outline/too-many` | `ParseError` | Item count exceeds `opts.maxItems`. |
+| `pdf/outline/runaway` | `ParseError` | Sibling chain exceeds the item cap (infinite-loop guard). |
+| `pdf/outline/item/not-dict` | `ParseError` | `typeOutlineItem` receives a non-dict. |
+| `pdf/outline/missing-title` | `ParseError` | `/Title` absent. |
+
+## See also
+
+- [`pdfDestination`](../destination/destination.md) · [`pdfAction`](../action/action.md)
+- [`pdfCatalog`](../document/catalog.md)

package/docs/api/pdf.md

@@ -0,0 +1,152 @@
+---
+module: pdf
+category: pdf
+dependencies: [pdfErrors, pdfShared, pdfTokenizer, pdfParserObj, pdfParser, pdfXref, pdfTrailer, pdfSerializer, pdfCatalog, pdfPages, pdfPage, pdfDocument, pdfWriter]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdf
+
+> Top-level public orchestrator — `read`, `header`, `write`, and the `.use()` extension hook.
+
+**Module** `pdf` | **Source** `packages/front/office/pdf/src/pdf.js` | **Deps** `pdfErrors`, `pdfShared`, `pdfTokenizer`, `pdfParserObj`, `pdfParser`, `pdfXref`, `pdfTrailer`, `pdfSerializer`, `pdfCatalog`, `pdfPages`, `pdfPage`, `pdfDocument`, `pdfWriter` | **Worker-safe** yes
+
+The syntax + document layers are declared as `dependencies[]` and received as positional factory parameters; the file's top-level `import`s only bring in the dependency descriptors for the generated `deps` companion, and there is no internal bootstrap. `pdf.factory()` therefore cannot be called with no arguments. Register `fw_require` and `modules` from `src/main.js` into a `@awacloud/fw` `ModuleRuntime` to resolve it, or use the committed `dist/standalone/pdf.js` build, whose `pdfBundled.factory()` takes no arguments (same returned API either way). See [`main`](./main.md) for DI registration.
+
+## Resolve
+
+```js
+const api = runtime.resolve('pdf');
+// Returns: { read, header, write, use, usedExtension }
+```
+
+Or stand-alone, from the committed framework-free build:
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+const api = pdfBundled.factory();
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `read` | `(bytes: Uint8Array, opts?: { allowEncrypted?: boolean }) => Document` | Full typed document — see [`pdfDocument`](./document/document.md). Throws `pdf/document/encrypted` on an encrypted document unless `opts.allowEncrypted === true`. |
+| `header` | `(bytes: Uint8Array) => { version: string, end: number }` | Header only, without parsing the rest. |
+| `write` | `(model: Document \| WriteModel, opts?: { strict?, onSkipped? }) => Uint8Array` | Serializes a document model back to bytes. When `model._raw.resolve` is a function (i.e. `model` is a `Document` returned by `read`), builds the write model from it (indirects, root, info, id, version `'2.0'`) via `pdfWriter`'s `assembleIndirects`; otherwise passes `model` straight through to `pdfWriter.writeDocument`. The result carries a non-enumerable `skippedObjects` property — see [`pdf.write(model, opts)`](#pdfwritemodel-opts). |
+| `use` | `(ext: { name: string, register: function }) => api` | Applies an extension (idempotent per `name`). |
+| `usedExtension` | `(name: string) => boolean` | Tests whether an extension is wired. |
+
+### `pdf.write(model, opts)`
+
+A `Document` returned by `read` can hold in-use xref entries that cannot be resolved (a damaged object, a truncated stream). By default `write` is lenient: it drops those objects and still returns bytes, so the loss must be made visible.
+
+| Option | Type | Effect |
+|--------|------|--------|
+| `strict` | `boolean` | Only the value `true` counts (a truthy non-boolean such as `'yes'` or `1` stays lenient). With `strict: true`, `write` throws `pdf/writer/unresolvable-objects` instead of dropping anything; the error's `context.objects` lists every unresolvable entry. |
+| `onSkipped` | `(skipped) => void` | Lenient mode only. Called once, with a copy of the skip list, when at least one object was dropped. Never called when nothing was skipped or when `strict: true` throws. Anything that is not a function is ignored. |
+
+The returned `Uint8Array` always has a non-enumerable `skippedObjects` property: an array of `{ num, gen, code }` entries, one per dropped object (`code` is the caught error's `pdf/…` code, or `'unknown'`). It is `[]` for a clean `Document` and for a raw `WriteModel`. Being non-enumerable, it does not show up in `Object.keys`, spreading, `JSON.stringify` or `toEqual`, so the bytes compare exactly as before. A raw `WriteModel` has no xref to resolve, so `opts` is ignored for it. `write(model)` with no `opts` produces the same bytes as before.
+
+### `pdf.use(ext)`
+
+`ext.register(api, ctx)` is invoked with `ctx = { usedExtensions: Set<string> }`. If the return value is an object, its keys (except `use`) are merged into the API in place. The `api` object's identity is preserved — safe to capture.
+
+Applying the same `name` twice is a no-op (returns `api` without calling `register` again). See [`extending.md`](../guide/extending.md).
+
+## Examples
+
+### Read through a runtime
+
+```js
+import { ModuleRuntime } from '@awacloud/fw/core/runtime.js';
+import { fw_require, modules } from '@awacloud/pdf';
+
+const rt = new ModuleRuntime();
+for (const m of fw_require) rt.register(m);
+for (const m of modules)    rt.register(m);
+
+const api = rt.resolve('pdf');
+const doc = api.read(bytes);
+console.log(doc.version, doc.pages.length);
+```
+
+### Header only (quick smoke test)
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+
+const { version, end } = pdfBundled.factory().header(bytes);
+// version: the header's version, e.g. '1.7' or '2.0'; end: offset after the header line
+```
+
+### Write back
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+
+const api = pdfBundled.factory();
+const doc = api.read(bytes);
+const out = api.write(doc);   // Uint8Array
+```
+
+### Write strictly
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+
+const api = pdfBundled.factory();
+const doc = api.read(bytes);
+const out = api.write(doc, { strict: true });   // throws pdf/writer/unresolvable-objects if anything would be dropped
+```
+
+### Inspect what a lenient write dropped
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+
+const api = pdfBundled.factory();
+const doc = api.read(bytes);
+const out = api.write(doc, {
+    onSkipped(skipped) { console.warn(`${skipped.length} object(s) dropped`); }
+});
+for (const { num, gen, code } of out.skippedObjects) {
+    console.warn(`object ${num} ${gen} was not written (${code})`);
+}
+```
+
+### `.use()` hook
+
+```js
+import { pdfBundled } from '@awacloud/pdf/standalone/pdf.js';
+
+const api = pdfBundled.factory().use({
+    name: 'count-annots',
+    register(self) {
+        return {
+            countAnnots(b) {
+                return self.read(b).pages.reduce((n, p) => n + p.annots.length, 0);
+            }
+        };
+    }
+});
+api.countAnnots(bytes);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/use/bad-extension` | `ContractError` | `.use()` receives anything other than `{ name: string, register: function }`. |
+| `pdf/writer/unresolvable-objects` | `RenderError` | `.write(doc, { strict: true })` on a `Document` holding at least one in-use xref entry that cannot be resolved; `context.objects` is the `{ num, gen, code }` list. |
+
+`.read()` propagates every code from [`pdfDocument`](./document/document.md) (`pdf/document/*`, `pdf/xref/*`, …); `.write()` propagates `pdfWriter`'s other codes.
+
+## See also
+
+- [`pdfDocument`](./document/document.md) — back-end of `read` / `header`.
+- [`pdfErrors`](./errors.md)
+- [Extending via `.use()`](../guide/extending.md)
+- [Getting started](../guide/getting-started.md)

package/docs/api/prepress/README.md

@@ -0,0 +1,10 @@
+# Prepress — ISO 32000-2 §14.11
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfOutputIntent`](./outputIntent.md) | `{ typeOutputIntent }` | `pdfErrors`, `pdfParser` | §14.11.5 — target colour environment. |
+| [`pdfPageBoundary`](./pageBoundary.md) | `{ effectiveMediaBox, effectiveCropBox, effectiveTrimBox, effectiveBleedBox, effectiveArtBox }` | `pdfErrors`, `pdfParser` | §14.11.2 — boundary boxes. |
+
+## See also
+
+- [Document](../document/README.md) · [Metadata](../metadata/README.md)