@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/syntax/xref.md

@@ -0,0 +1,139 @@
+---
+module: pdfXref
+category: pdf/syntax
+dependencies: [pdfErrors, pdfTokenizer, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfXref
+
+> Classical cross-reference table, ISO 32000-2 §7.5.4 — locate + parse + trailer; plus the xref-stream dict reader and emitter the incremental writer uses.
+
+**Module** `pdfXref` | **Source** `packages/front/office/pdf/src/syntax/xref.js` | **Deps** `pdfErrors`, `pdfTokenizer`, `pdfParser` | **Worker-safe** yes
+
+Reads the **classical table** (`xref` keyword plus 20-byte subsection entries)
+only. Cross-reference streams (`/Type /XRef`, §7.5.8) and object streams
+(`/Type /ObjStm`, §7.5.7) are handled by the dedicated
+[`pdfCrossRefStream`](./crossRefStream.md) and [`pdfObjStream`](./objStream.md)
+modules, which [`pdfDocument`](../document/document.md) composes: the section
+walk calls `parseXrefTable` only when the bytes at the offset actually start
+with `xref`. The backward scan tolerance for `startxref`
+is widened to 8192 bytes (versus the 1024 of the spec) to absorb annotated
+`%%EOF` tails.
+
+Two cross-reference-stream helpers serve
+[`pdfIncrementalWriter`](../document/incrementalWriter.md).
+`readXrefStreamDict` reads only the **dictionary** of a `/Type /XRef` stream
+section and never decodes its data, so it needs no filter module.
+`buildXrefStream` emits one uncompressed `/Type /XRef` stream section for an
+incremental update. Decoding a stream's entries stays the job of
+[`pdfCrossRefStream`](./crossRefStream.md).
+
+## Resolve
+
+```js
+const xref = runtime.resolve('pdfXref');
+// Returns: { locateStartXref, readStartXref, parseXrefTable, parseTrailerDict,
+//            readXrefStreamDict, buildXrefStream }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `locateStartXref` | `(bytes: Uint8Array) => number` | Offset of the last `startxref`, or `-1`. |
+| `readStartXref` | `(bytes: Uint8Array, at: number) => number` | Offset of the xref it points to. |
+| `parseXrefTable` | `(bytes: Uint8Array, at: number) => { entries, end }` | Table plus the offset just after it. |
+| `parseTrailerDict` | `(bytes: Uint8Array, at: number) => { dict, end }` | Raw trailer plus the offset just after it. |
+| `readXrefStreamDict` | `(bytes: Uint8Array, at: number) => { num, gen, dict }` | The raw dict of the `/Type /XRef` stream object at `at`; the data is not decoded. |
+| `buildXrefStream` | `(opts: XrefStreamOpts) => Uint8Array` | One complete `num 0 obj … endobj` xref-stream section. The caller appends `startxref`/`%%EOF`. |
+
+### `XrefStreamOpts`
+
+```js
+{
+    num:     number,                              // the stream's own object number (>= 1)
+    offset:  number,                              // byte offset where the object will start
+    entries: [ { num, offset, gen? }, … ],        // type-1 rows; object 0's free head and
+                                                  // the stream's own row are added for you
+    prev:    number,                              // /Prev — the previous section's offset
+    root:    { num, gen },                        // /Root
+    info?:   { num, gen } | null,                 // /Info
+    id?:     [ Uint8Array, Uint8Array ] | null,   // /ID
+    size?:   number,                              // /Size = max(size, num + 1)
+    encrypt?: { num, gen } | null                 // /Encrypt, written right after /ID
+}
+```
+
+`encrypt` repeats an encrypted document's `/Encrypt` in the update
+(ISO 32000-2 §7.5.6). Only an indirect reference is accepted. Without it
+the output is unchanged.
+
+`/W` is the narrowest `[1 w2 w3]` that fits the rows, and `/Index` holds one
+pair per contiguous run of object numbers. No `/Filter` is written.
+
+### `entries` shape
+
+```js
+{
+    [num: number]: { offset: number, gen: number, free: boolean }
+}
+```
+
+`free === true` corresponds to the `f` flag (released object; must not be
+dereferenced).
+
+## Examples
+
+### Full xref pipeline
+
+```js
+const xref = runtime.resolve('pdfXref');
+
+const sxAt = xref.locateStartXref(bytes);
+if (sxAt < 0) throw new Error('no startxref');
+const xrefAt = xref.readStartXref(bytes, sxAt);
+
+const { entries, end } = xref.parseXrefTable(bytes, xrefAt);
+const { dict: trailer } = xref.parseTrailerDict(bytes, end);
+```
+
+### Chaining through `/Prev` (incremental update)
+
+```js
+const sections = [];
+let cursor = xrefAt;
+for (let i = 0; i < 32 && cursor >= 0; i++) {
+    const s = xref.parseXrefTable(bytes, cursor);
+    sections.push(s);
+    const { dict } = xref.parseTrailerDict(bytes, s.end);
+    const prev = dict.entries.Prev;
+    cursor = prev && prev.type === 'int' ? prev.value : -1;
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/xref/no-startxref` | `ParseError` | No `startxref` keyword at `at`. |
+| `pdf/xref/bad-startxref` | `ParseError` | `startxref` not followed by an int ≥ 0. |
+| `pdf/xref/no-xref-keyword` | `ParseError` | No `xref` at the expected offset. `pdfDocument` never produces it for a cross-reference stream — it inspects the bytes first and takes the stream path. |
+| `pdf/xref/bad-subsection-header` | `ParseError` | Invalid `<first> <count>` header. |
+| `pdf/xref/truncated-entry` | `ParseError` | Subsection cut short. |
+| `pdf/xref/bad-entry-format` | `ParseError` | Missing space at column 10 or 16. |
+| `pdf/xref/bad-entry-flag` | `ParseError` | Final flag is neither `n` nor `f`. |
+| `pdf/xref/bad-digit` | `ParseError` | Non-ASCII-digit character inside `xxxxxxxxxx`/`ggggg`. |
+| `pdf/xref/no-trailer` | `ParseError` | No `trailer` keyword. |
+| `pdf/xref/trailer-not-dict` | `ParseError` | `trailer` not followed by a dictionary. |
+| `pdf/xref/not-xref-stream` | `ParseError` | `readXrefStreamDict`: no indirect object at `at`, or one that is not a `/Type /XRef` stream. |
+| `pdf/xref/bad-stream-section` | `RenderError` | `buildXrefStream`: unusable `num`, `offset`, `prev`, `root`, `encrypt` (anything but an indirect reference) or entry. |
+
+## See also
+
+- [`pdfTrailer`](./trailer.md) — types the dictionary returned here.
+- [`pdfCrossRefStream`](./crossRefStream.md) — the §7.5.8 alternative.
+- [`pdfDocument`](../document/document.md) — orchestrates xref plus the `/Prev` chain.
+- [`pdfTokenizer`](./tokenizer.md), [`pdfParser`](./parser.md)

package/docs/api/tagged/README.md

@@ -0,0 +1,25 @@
+# Tagged PDF — ISO 32000-2 §14.6 / §14.7 / §14.8
+
+Logical layer: structure tree, marked content, role mapping. Basis of PDF/UA-2 (ISO 14289-2).
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfStructTree`](./structTree.md) | `{ typeStructTreeRoot }` | `pdfErrors`, `pdfParser` | Root, §14.7.2. |
+| [`pdfStructElement`](./structElement.md) | `{ typeStructElement }` | `pdfErrors`, `pdfParser` | Elem, §14.7.3. |
+| [`pdfRoleMap`](./roleMap.md) | `{ typeRoleMap, resolveStandardType, isStandardType, STANDARD_TYPES }` | `pdfErrors`, `pdfParser` | RoleMap, §14.7.4. |
+| [`pdfParentTree`](./parentTree.md) | `{ lookupParent }` | `pdfErrors`, `pdfParser` | ParentTree, §14.7.5. |
+| [`pdfClassMap`](./classMap.md) | `{ typeClassMap, getClassAttributes }` | `pdfErrors`, `pdfParser` | ClassMap, §14.7.6. |
+| [`pdfMarkedContent`](./markedContent.md) | `{ extractMcids, resolveMcidToStruct }` | `pdfErrors`, `pdfParser`, `pdfParentTree` | BMC/BDC/EMC, §14.6. |
+
+## PDF/UA-2 pattern
+
+```js
+const st = runtime.resolve('pdfStructTree');
+const root = st.typeStructTreeRoot(doc._raw.resolve(doc.catalog.structTreeRoot));
+// walk root.kids → pdfStructElement.typeStructElement
+```
+
+## See also
+
+- [Content streams](../content/README.md)
+- [Annot — Widget](../annot/widget.md)

package/docs/api/tagged/classMap.md

@@ -0,0 +1,67 @@
+---
+module: pdfClassMap
+category: pdf/tagged
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfClassMap
+
+> ClassMap — ISO 32000-2 §14.7.6 — dict of reusable named attribute sets.
+
+**Module** `pdfClassMap` | **Source** `packages/front/office/pdf/src/tagged/classMap.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/ClassMap` (on StructTreeRoot) is a dict `name → dict | array<dict>`: each key is an attribute-class name, the value is one or more attribute dicts (§14.7.7). A `StructElement` may reference one or more classes via `/C`. `getClassAttributes(typed, name, owner?)` always returns an **array** — filtered to entries whose `/O` equals `owner` when supplied, or the full list otherwise (never a bare dict, never `null`).
+
+## Resolve
+
+```js
+const cm = runtime.resolve('pdfClassMap');
+// Returns: { typeClassMap, getClassAttributes }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeClassMap` | `(dict) => { classes: Record<string, dict[]>, raw }` | Typing — `classes` is a **plain object**, not a `Map`. |
+| `getClassAttributes` | `(typed, name, owner?: string) => dict[]` | Lookup; `[]` when `name` is unknown. |
+
+## Examples
+
+### Reading the classes
+
+```js
+const cm = runtime.resolve('pdfClassMap').typeClassMap(root.classMap);
+cm.classes.Heading1;     // [{type:'dict', entries:{O:{value:'Layout'}, …}}, …]
+```
+
+### Lookup by owner
+
+```js
+const layout = cm.getClassAttributes(cm, 'Heading1', 'Layout');
+if (layout.length) layout[0].entries.SpaceBefore;
+```
+
+### Applying to a StructElement
+
+```js
+const el = runtime.resolve('pdfStructElement').typeStructElement(dict);
+for (const className of (el.c && el.c.items) || []) {
+    const attrs = cm.getClassAttributes(cm, className.value);
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/tagged/class-map/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/tagged/class-map/bad-value` | `ParseError` | Value is neither a dict nor an array. |
+| `pdf/tagged/class-map/bad-item` | `ParseError` | An array element is not a dict. |
+
+## See also
+
+- [`pdfStructElement`](./structElement.md) · [`pdfStructTree`](./structTree.md)

package/docs/api/tagged/markedContent.md

@@ -0,0 +1,62 @@
+---
+module: pdfMarkedContent
+category: pdf/tagged
+dependencies: [pdfErrors, pdfParser, pdfParentTree]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfMarkedContent
+
+> Marked-content sequences — ISO 32000-2 §14.6 — bridge between content streams and the struct tree.
+
+**Module** `pdfMarkedContent` | **Source** `packages/front/office/pdf/src/tagged/markedContent.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfParentTree` | **Worker-safe** yes
+
+The `BMC` / `BDC` / `EMC` operators (§14.6.1) delimit marked sequences in a content stream. `BDC` may carry an `MCID` in its properties dict, used as the key into the `ParentTree` (§14.7.5) to link content back to a `StructElement`. This module provides `extractMcids` (walks an ops list already typed by [`pdfContentStream`](../content/stream.md)) and `resolveMcidToStruct` (full resolution via `pdfParentTree.lookupParent`).
+
+## Resolve
+
+```js
+const mc = runtime.resolve('pdfMarkedContent');
+// Returns: { extractMcids, resolveMcidToStruct }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `extractMcids` | `(opsList) => Array<{ tag, start, end, mcid, properties }>` | Linear walk, tracks the BMC/BDC/EMC stack; `start`/`end` are inclusive op-index positions, sorted by `start`. |
+| `resolveMcidToStruct` | `(pageDict, mcid, parentTree, resolveRef) => PdfObject \| null` | Lookup via `pdfParentTree.lookupParent`, indexed by the page's `/StructParents` then `mcid`. |
+
+## Examples
+
+### Extraction from a content stream
+
+```js
+const ops = runtime.resolve('pdfContentStream').parseContentStream(streamBytes);
+const mc  = runtime.resolve('pdfMarkedContent');
+const seqs = mc.extractMcids(ops);
+// [{ tag: 'P', start: 3, end: 9, mcid: 0, properties: {…} }, …]
+```
+
+### Resolution to the struct elem
+
+```js
+const elemRef = mc.resolveMcidToStruct(pageDict, 0, parentTree, resolveRef);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/tagged/marked-content/bad-ops` | `ParseError` | Argument is not an array. |
+| `pdf/tagged/marked-content/unmatched-emc` | `ParseError` | `EMC` without a matching `BMC`/`BDC`. |
+| `pdf/tagged/marked-content/unterminated` | `ParseError` | Non-empty stack at end of stream. |
+| `pdf/tagged/marked-content/bad-tag` | `ParseError` | `BMC`/`BDC` tag is not a name. |
+| `pdf/tagged/marked-content/bad-page` | `ParseError` | Page argument is not a dict. |
+| `pdf/tagged/marked-content/bad-entry` | `ParseError` | ParentTree entry for the page is not an array. |
+
+## See also
+
+- [`pdfContentStream`](../content/stream.md) · [`pdfStructTree`](./structTree.md) · [`pdfParentTree`](./parentTree.md)

package/docs/api/tagged/parentTree.md

@@ -0,0 +1,67 @@
+---
+module: pdfParentTree
+category: pdf/tagged
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfParentTree
+
+> ParentTree — ISO 32000-2 §14.7.5 — number tree, MCID → struct element / OBJR.
+
+**Module** `pdfParentTree` | **Source** `packages/front/office/pdf/src/tagged/parentTree.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+The StructTreeRoot's `/ParentTree` is a *number tree* (§7.9.7) mapping `StructParents`/`StructParent` keys (on pages, annotations, content-stream objects) to their parent structure elements. The module provides `lookupParent(tree, key, resolveRef, opts?)`, which descends `/Kids` nodes (checking `/Limits`) then scans `/Nums` leaves until `key` is found. Returns either a single ref (annotations/form XObjects) or an array indexed by MCID (pages).
+
+## Resolve
+
+```js
+const pt = runtime.resolve('pdfParentTree');
+// Returns: { lookupParent }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `lookupParent` | `(tree, key: number, resolveRef, opts?: { maxDepth? }) => PdfObject \| null` | Value of the number tree for `key`. |
+
+`opts.maxDepth` defaults to `32`. Returns `null` when `key` is not found.
+
+## Examples
+
+### Finding the struct elem of an MCID on a page
+
+```js
+const pt = runtime.resolve('pdfParentTree');
+const page = doc.pages[0];
+const parents = pt.lookupParent(structRoot.parentTree, page.structParents, resolveRef);
+// parents is an array PdfObject: parents.items[mcid] -> ref to the StructElement
+const elemRef = parents.items[42];
+```
+
+### Parent of an annotation
+
+```js
+const annotParent = pt.lookupParent(parentTree, annot.structParent, resolveRef);
+// direct ref to the StructElement
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/tagged/parent-tree/max-depth` | `ParseError` | Depth exceeds `opts.maxDepth`. |
+| `pdf/tagged/parent-tree/not-dict` | `ParseError` | Node is not a dict. |
+| `pdf/tagged/parent-tree/non-ref-kid` | `ParseError` | `/Kids` contains a non-ref entry. |
+| `pdf/tagged/parent-tree/bad-child` | `ParseError` | Resolved child is not a dict. |
+| `pdf/tagged/parent-tree/empty-node` | `ParseError` | Node has neither `/Kids` nor `/Nums`. |
+| `pdf/tagged/parent-tree/bad-nums` | `ParseError` | `/Nums` is not an even-length array. |
+| `pdf/tagged/parent-tree/bad-key` | `ParseError` | `/Nums` key is not a number. |
+| `pdf/tagged/parent-tree/bad-limits` | `ParseError` | `/Limits` malformed. |
+
+## See also
+
+- [`pdfStructTree`](./structTree.md) · [`pdfStructElement`](./structElement.md) · [`pdfMarkedContent`](./markedContent.md)

package/docs/api/tagged/roleMap.md

@@ -0,0 +1,67 @@
+---
+module: pdfRoleMap
+category: pdf/tagged
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfRoleMap
+
+> RoleMap — ISO 32000-2 §14.7.4 — maps custom roles onto standard structure types.
+
+**Module** `pdfRoleMap` | **Source** `packages/front/office/pdf/src/tagged/roleMap.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+`/RoleMap` (on the `StructTreeRoot`) is a dict `name → name`. It lets a custom role (e.g. `MyTitle`) be interpreted as a standard structure type (e.g. `H1`). Resolution is iterative with cycle detection. The module knows the PDF 2.0 standard types (§14.8.4) — `Document`, `DocumentFragment`, `Part`, `Art`, `Sect`, `Div`, `BlockQuote`, `Caption`, `TOC`, `TOCI`, `Index`, `NonStruct`, `Private`, `Aside`, `Title`, `FENote`, `P`, `H`, `H1`–`H7`, `L`, `LI`, `Lbl`, `LBody`, `Table`, `TR`, `TH`, `TD`, `THead`, `TBody`, `TFoot`, `Span`, `Quote`, `Note`, `Reference`, `BibEntry`, `Code`, `Link`, `Annot`, `Em`, `Strong`, `Ruby`, `RB`, `RT`, `RP`, `Warichu`, `WT`, `WP`, `Figure`, `Formula`, `Form`, `Artifact`. It also supports the PDF 2.0 namespace model (`/Namespaces`, per-element `/NS`, and a namespace's own `/RoleMapNS` taking precedence via `resolveStandardType`'s `namespaceMap` argument).
+
+## Resolve
+
+```js
+const rm = runtime.resolve('pdfRoleMap');
+// Returns: { typeRoleMap, resolveStandardType, isStandardType, STANDARD_TYPES }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeRoleMap` | `(dict) => { map: Record<string,string>, raw }` | Typing — `map` is a **plain object**, not a `Map`. |
+| `resolveStandardType` | `(name, map, namespaceMap?) => { standard: string \| null, chain: string[] }` | Recursively resolves toward a standard type; cycle-safe. |
+| `isStandardType` | `(name) => boolean` | Tests against the §14.8.4 table. |
+| `STANDARD_TYPES` | `Set<string>` | The full standard-type set used by `isStandardType`/`resolveStandardType`. |
+
+## Examples
+
+### Resolution
+
+```js
+const rm = runtime.resolve('pdfRoleMap');
+const r  = rm.typeRoleMap(root.roleMap);
+const out = rm.resolveStandardType('MyTitle', r.map);
+out.standard;  // 'H1'
+out.chain;     // ['MyTitle', 'Heading', 'H1']
+```
+
+### PDF/UA validation
+
+```js
+for (const [custom, target] of Object.entries(r.map)) {
+    void target;
+    if (!rm.isStandardType(rm.resolveStandardType(custom, r.map).standard)) {
+        /* warning: custom role unresolved */
+    }
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/tagged/role-map/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/tagged/role-map/bad-value` | `ParseError` | A value is not a name. |
+| `pdf/tagged/role-map/cycle` | `ParseError` | Cycle detected while resolving. |
+
+## See also
+
+- [`pdfStructTree`](./structTree.md) · [`pdfStructElement`](./structElement.md)

package/docs/api/tagged/structElement.md

@@ -0,0 +1,76 @@
+---
+module: pdfStructElement
+category: pdf/tagged
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfStructElement
+
+> Structure element — ISO 32000-2 §14.7.3, the granularity of Tagged PDF §14.8.
+
+**Module** `pdfStructElement` | **Source** `packages/front/office/pdf/src/tagged/structElement.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types a `/Type /StructElem` dict. Fields: `/S` (structure type — required), `/P` (parent), `/ID`, `/Pg` (owning page), `/K` (kids — `int`/`ref`/`dict` or array), `/A`/`/C` (attributes/classes), `/R` (revision), `/T`/`/Lang`/`/Alt`/`/E`/`/ActualText` (accessibility), `/AF` (PDF 2.0 associated files), `/NS` (namespace), `/PhoneticAlphabet`/`/Phoneme`. Kids are normalized to records `{ kind: 'mcid'|'elem'|'mcr'|'objr', … }`.
+
+## Resolve
+
+```js
+const se = runtime.resolve('pdfStructElement');
+// Returns: { typeStructElement }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeStructElement` | `(dict) => StructElement` | Typing (kids are not recursively typed — each `kind: 'elem'` kid still carries a raw `ref`, resolved and re-typed by the caller). |
+
+### Shape of a kid
+
+```js
+{ kind: 'mcid', mcid: number }
+{ kind: 'elem', ref: { type:'ref', num, gen } }
+{ kind: 'mcr',  pg?, stm?, stmOwn?, mcid: number|null, raw }   // /Type /MCR
+{ kind: 'objr', pg?, obj?, raw }                                // /Type /OBJR
+```
+
+## Examples
+
+### Recursive walk
+
+```js
+function walk(elDict, resolveRef, depth = 0) {
+    const e = runtime.resolve('pdfStructElement').typeStructElement(elDict);
+    console.log(' '.repeat(depth) + e.s + (e.alt ? ` [${e.alt}]` : ''));
+    for (const k of e.k) {
+        if (k.kind === 'elem') walk(resolveRef(k.ref), resolveRef, depth + 1);
+    }
+}
+```
+
+### Accessibility
+
+```js
+const el = runtime.resolve('pdfStructElement').typeStructElement(dict);
+el.s;          // 'Figure'
+el.alt;        // alt-text (required for PDF/UA)
+el.actualText;
+el.lang;       // 'fr-FR'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/tagged/struct-elem/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/tagged/struct-elem/bad-type` | `ParseError` | `/Type` present and ≠ `/StructElem`. |
+| `pdf/tagged/struct-elem/missing-s` | `ParseError` | `/S` missing or not a name. |
+| `pdf/tagged/struct-elem/bad-kid` | `ParseError` | Kid of an unhandled shape. |
+
+## See also
+
+- [`pdfStructTree`](./structTree.md) · [`pdfMarkedContent`](./markedContent.md)
+- [`pdfRoleMap`](./roleMap.md) — resolution of custom `/S` values.

package/docs/api/tagged/structTree.md

@@ -0,0 +1,75 @@
+---
+module: pdfStructTree
+category: pdf/tagged
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfStructTree
+
+> Structure Tree Root — ISO 32000-2 §14.7.2, basis of PDF/UA-2 (ISO 14289-2).
+
+**Module** `pdfStructTree` | **Source** `packages/front/office/pdf/src/tagged/structTree.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types the `/Type /StructTreeRoot` dict referenced by the Catalog. Carries `/K` (root kid(s)), `/IDTree` (ID name tree), `/ParentTree` (number tree mapping MCIDs and OBJRs), `/ParentTreeNextKey`, `/RoleMap`, `/ClassMap`, `/Namespaces` (PDF 2.0), `/AF`, `/PronunciationLexicon`. `/K` is normalized to `Array<ref|dict>`.
+
+## Resolve
+
+```js
+const st = runtime.resolve('pdfStructTree');
+// Returns: { typeStructTreeRoot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeStructTreeRoot` | `(dict) => StructTreeRoot` | Typing of the root. |
+
+### Shape
+
+```js
+{
+    kids: Array<ref|dict>,
+    idTree, parentTree,
+    parentTreeNextKey: number,
+    roleMap, classMap, namespaces, af, pronunciationLexicon,
+    raw, _extras
+}
+```
+
+## Examples
+
+### Walking from the Catalog
+
+```js
+const st = runtime.resolve('pdfStructTree');
+const root = st.typeStructTreeRoot(doc._raw.resolve(doc.catalog.structTreeRoot));
+for (const kid of root.kids) {
+    const el = runtime.resolve('pdfStructElement').typeStructElement(
+        kid.type === 'ref' ? doc._raw.resolve(kid) : kid
+    );
+}
+```
+
+### Mapping custom roles
+
+```js
+const rm = runtime.resolve('pdfRoleMap').typeRoleMap(root.roleMap);
+rm.map.MyCustomP;   // -> 'P'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|--------|------|
+| `pdf/tagged/struct-tree/not-dict` | `ParseError` | Argument is not a dict. |
+| `pdf/tagged/struct-tree/bad-type` | `ParseError` | `/Type` ≠ `/StructTreeRoot`. |
+| `pdf/tagged/struct-tree/bad-kid` | `ParseError` | `/K` is neither ref/dict, or an array with an invalid entry. |
+
+## See also
+
+- [`pdfStructElement`](./structElement.md) · [`pdfRoleMap`](./roleMap.md) · [`pdfParentTree`](./parentTree.md) · [`pdfClassMap`](./classMap.md)
+- [`pdfMarkedContent`](./markedContent.md)