@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/extra/redaction-iso32005.md

@@ -0,0 +1,65 @@
+---
+module: pdfRedactionIso32005
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfRedactionIso32005
+
+> Opt-in: typing of the ISO/TS 32005 apply-redaction audit record (read side). The TS text is not vendored; the entries below are what this module recognises. No content removal is performed.
+
+**Module** `pdfRedactionIso32005` | **Source** `packages/front/office/pdf/src/extra/redaction-iso32005.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+TS 32005 layers an "apply-redaction" workflow on top of the `/Redact` annotation (§12.5.6.21). Captures the audit record: applied annotations, overlay hints (`/RD`, `/IC`, `/RO`), content-stream markers (`/Redact … BMC … EMC`).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfRedactionIso32005');
+// Returns: { typeRedactionRecord, findRedactMarkers, REDACT_MARKERS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeRedactionRecord` | `(dict) => RedactionRecord` | `{ appliedAt, tool, annotations, rd, ro, ic, markedRegions, raw, _extras }`. |
+| `findRedactMarkers` | `(Uint8Array) => { regions: Array<{ beginOffset, endOffset, kind }> }` | Scans BMC/BDC/EMC markers. |
+| `REDACT_MARKERS` | frozen catalog | `{ begin: '/Redact BMC', beginPropertyList: '/Redact BDC', end: 'EMC', notes }`. |
+
+## Examples
+
+### Audit record
+
+```js
+const ext = runtime.resolve('pdfRedactionIso32005');
+const r = ext.typeRedactionRecord(auditDict);
+r.appliedAt;     // '2026-05-15'
+r.annotations;   // [ ref, ref, … ]
+```
+
+### Markers in the content stream
+
+```js
+const m = ext.findRedactMarkers(contentBytes);
+m.regions.length;        // 1
+m.regions[0].kind;       // 'BMC'
+m.regions[0].endOffset;  // > beginOffset, or null if EMC is missing
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/redact32005/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/extra/redact32005/bad-annotations` | `ParseError` | `/Annotations` is not an array. |
+| `pdf/extra/redact32005/scan/bad-input` | `ParseError` | Bytes are not a Uint8Array. |
+
+## See also
+
+- [`pdfRedactAnnot`](../annot/redact.md)
+- [`pdfContentStream`](../content/stream.md)
+- [Extras index](./README.md)

package/docs/api/extra/shading-typed.md

@@ -0,0 +1,73 @@
+---
+module: pdfShadingTyped
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfShadingTyped
+
+> Typed Shading dicts (§8.7.4) and Function dicts (§7.10) — ISO 32000-2.
+
+**Module** `pdfShadingTyped` | **Source** `packages/front/office/pdf/src/extra/shading-typed.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+Shadings 1–7 (Function-based, Axial, Radial, Free-form Gouraud, Lattice-form Gouraud, Coons patch mesh, Tensor-product patch mesh). Functions 0/2/3/4 (Sampled, Exponential, Stitching, PostScript).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfShadingTyped');
+// Returns: { typeShading, typeFunction }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeShading` | `(dict\|stream) => Shading` | Record shaped by `/ShadingType`. |
+| `typeFunction` | `(dict\|stream) => Function` | Record shaped by `/FunctionType`. |
+
+## Examples
+
+### Axial shading
+
+```js
+const ext = runtime.resolve('pdfShadingTyped');
+const sh = ext.typeShading(shadingDict);
+sh.shadingType;  // 2
+sh.coords;       // [x0, y0, x1, y1]
+sh.function;     // raw /Function entry
+```
+
+### Stitching function
+
+```js
+const fn = ext.typeFunction(fnDict);
+fn.functionType;  // 3
+fn.functions;     // array of sub-function entries
+fn.bounds;        // [...]
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/shading/not-dict-or-stream` | `ParseError` | Invalid input. |
+| `pdf/extra/shading/missing-type` | `ParseError` | `/ShadingType` absent. |
+| `pdf/extra/shading/bad-type` | `ParseError` | `/ShadingType` outside 1..7. |
+| `pdf/extra/shading/lattice-missing-vpr` | `ParseError` | Type 5 without `/VerticesPerRow`. |
+| `pdf/extra/shading/mesh-missing-bits` | `ParseError` | Type 4/6/7 without `/BitsPerCoordinate`/`/BitsPerComponent`. |
+| `pdf/extra/shading/mesh-missing-decode` | `ParseError` | `/Decode` absent. |
+| `pdf/extra/shading/mesh-missing-flag` | `ParseError` | `/BitsPerFlag` absent (Type 4/6/7). |
+| `pdf/extra/shading/bad-coords` | `ParseError` | `/Coords` malformed. |
+| `pdf/extra/function/not-dict-or-stream` | `ParseError` | Invalid input. |
+| `pdf/extra/function/missing-type` | `ParseError` | `/FunctionType` absent. |
+| `pdf/extra/function/bad-type` | `ParseError` | `/FunctionType` outside {0,2,3,4}. |
+
+## See also
+
+- [`pdfColorSpacesExtended`](./color-spaces-extended.md)
+- [`pdfGraphics`](../content/graphics.md)
+- [Extras index](./README.md)

package/docs/api/extra/sig-aes-gcm.md

@@ -0,0 +1,69 @@
+---
+module: pdfSigAesGcm
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSigAesGcm
+
+> AES-GCM crypt filter (`/CFM /AESV4`) — ISO/TS 32003.
+
+**Module** `pdfSigAesGcm` | **Source** `packages/front/office/pdf/src/extra/sig-aes-gcm.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+TS 32003 adds `/CFM /AESV4` (AES-256 GCM) to the Standard Security Handler v6. Wire format: `IV (12) ‖ ciphertext ‖ tag (16)`. This module inspects an `/Encrypt` dict, locates the CF entries, and surfaces a typed view identifying GCM crypt filters.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfSigAesGcm');
+// Returns: { typeEncryptForGcm, typeCfEntry, validateGcmFraming, CFM_CATALOG }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeEncryptForGcm` | `(encryptDict) => { v, r, length, stmF, strF, eff, cf, hasAesGcm, raw, _extras }` | GCM-focused view. |
+| `typeCfEntry` | `(dict) => { cfm, authEvent, length, catalog, raw, _extras }` | A single `/CF` entry. |
+| `validateGcmFraming` | `(Uint8Array) => { iv, ciphertext, tag }` | Splits the TS 32003 framing. |
+| `CFM_CATALOG` | frozen catalog | CFM name → `{ cipher, keyBits, mode?, notes }`. |
+
+## Examples
+
+### Detect AES-GCM
+
+```js
+const ext = runtime.resolve('pdfSigAesGcm');
+const e = ext.typeEncryptForGcm(encryptDict);
+e.hasAesGcm;        // true
+e.cf.StdCF.cfm;     // 'AESV4'
+```
+
+### Split a framed buffer
+
+```js
+const f = ext.validateGcmFraming(framedBytes);
+f.iv.length;   // 12
+f.tag.length;  // 16
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/sig-aes-gcm/not-dict` | `ParseError` | encryptDict is not a dict. |
+| `pdf/extra/sig-aes-gcm/bad-cf` | `ParseError` | `/CF` is not a dict. |
+| `pdf/extra/sig-aes-gcm/bad-cf-entry` | `ParseError` | A CF entry is not a dict. |
+| `pdf/extra/sig-aes-gcm/cf-entry-not-dict` | `ParseError` | `typeCfEntry` argument is not a dict. |
+| `pdf/extra/sig-aes-gcm/bad-input` | `EncryptionError` | Framing input is not a Uint8Array. |
+| `pdf/extra/sig-aes-gcm/too-short` | `EncryptionError` | Framed buffer is under 28 bytes. |
+
+## See also
+
+- [`pdfStandardV6`](../crypto/standardV6.md)
+- [`pdfAesGcm`](../crypto/aesGcm.md)
+- [`pdfSigPades`](./sig-pades.md)
+- [Extras index](./README.md)

package/docs/api/extra/sig-pades.md

@@ -0,0 +1,103 @@
+---
+module: pdfSigPades
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSigPades
+
+> PAdES profile detection (ETSI EN 319 142-1), `/Reference` array, DSS, DocMDP and B-LTA chain validation — ISO 32000-2 §12.8.4.3.
+
+**Module** `pdfSigPades` | **Source** `packages/front/office/pdf/src/extra/sig-pades.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+PAdES profiles by `/SubFilter`: `ETSI.CAdES.detached` (B-B/B-T), `ETSI.RFC3161` (Document Timestamp), `adbe.pkcs7.detached` (non-PAdES). Inferred levels: B-B (signature only), B-T (+timestamp), B-LT (+DSS), B-LTA (+DocTimeStamp over DSS). Does NOT verify the cryptography.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfSigPades');
+// Returns: { detectPadesProfile, typeReferenceArray, typeDSS,
+//   validateDocMdp, validateBLtaChain, SIG_SUBFILTERS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `detectPadesProfile` | `(sigDict, ctx?) => { subFilter, isPades, level, hasTimestamp }` | `level` is `B-B`/`B-T`/`B-LT`/`B-LTA` or `null` when not PAdES. |
+| `typeReferenceArray` | `(array) => Reference[]` | Records for `/Reference` items. |
+| `typeDSS` | `(dict) => DSS` | `{ certs, ocsps, crls, vri, raw, _extras }`. |
+| `validateDocMdp` | `(reference) => { valid, level, issues }` | Validates a DocMDP `/Reference` entry (`/TransformMethod /DocMDP`). |
+| `validateBLtaChain` | `(steps) => { chainLevel, trace }` | Walks a chronological list of `{ sigDict, hasDss, hasDocTimestamp, hasSignatureTimestamp }` steps and reports the resulting PAdES level at each step. |
+| `SIG_SUBFILTERS` | frozen catalog | SubFilter name → `{ pades, kind }`. |
+
+## Examples
+
+### PAdES detection
+
+```js
+const ext = runtime.resolve('pdfSigPades');
+const p = ext.detectPadesProfile(sigDict, { dss: {}, hasDocTimestampOverDss: false });
+p.level;   // 'B-LT'
+```
+
+### DSS
+
+```js
+const dss = ext.typeDSS(dssDict);
+dss.certs.length;  // 3
+dss.vri;           // { 'C1D2E3...': { cert, crl, ocsp, tu, ts } }
+```
+
+### DocMDP reference
+
+```js
+const v = ext.validateDocMdp(referenceRecord);
+v.valid;   // true | false
+v.level;   // 1 | 2 | 3 | null
+```
+
+### B-LTA chain
+
+```js
+const chain = ext.validateBLtaChain([
+    { sigDict: firstSig, hasDss: false },
+    { sigDict: secondSig, hasDss: true, hasDocTimestamp: true }
+]);
+chain.chainLevel;  // 'B-LTA'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/pades/not-dict` | `ParseError` | sigDict is not a dict. |
+| `pdf/extra/pades/bad-reference` | `ParseError` | `/Reference` is not an array. |
+| `pdf/extra/pades/bad-reference-item` | `ParseError` | An item is not a dict. |
+| `pdf/extra/pades/bad-reference-type` | `ParseError` | `/Type` is not `/SigRef`. |
+| `pdf/extra/pades/dss-not-dict` | `ParseError` | DSS is not a dict. |
+| `pdf/extra/pades/dss-bad-type` | `ParseError` | `/Type` is not `/DSS`. |
+| `pdf/extra/pades/dss-bad-array` | `ParseError` | `/Certs`/`/OCSPs`/`/CRLs` is not an array. |
+| `pdf/extra/pades/chain/bad-input` | `ParseError` | `validateBLtaChain` argument is not an array. |
+| `pdf/extra/pades/chain/missing-sig` | `ParseError` | A step is missing `sigDict`. |
+
+### DocMDP validation issues (non-throwing, returned in `issues`)
+
+| Code | When |
+|------|------|
+| `pdf/extra/pades/mdp/wrong-transform` | Reference is not a DocMDP transform. |
+| `pdf/extra/pades/mdp/missing-params` | `/TransformParams` dict missing. |
+| `pdf/extra/pades/mdp/bad-p-type` | `/P` is not an integer. |
+| `pdf/extra/pades/mdp/bad-p-value` | `/P` is not 1, 2, or 3. |
+| `pdf/extra/pades/mdp/bad-version` | Unknown DocMDP `/V`. |
+| `pdf/extra/pades/mdp/missing-digest` | `/DigestMethod` absent on the reference. |
+
+## See also
+
+- [`pdfSignature`](../sig/signature.md)
+- [`pdfTimestamp`](../sig/timestamp.md)
+- [`pdfSigAesGcm`](./sig-aes-gcm.md)
+- [Extras index](./README.md)

package/docs/api/extra/tagged-pdf-typed.md

@@ -0,0 +1,78 @@
+---
+module: pdfTaggedPdfTyped
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTaggedPdfTyped
+
+> Typing of structural attribute dictionaries (`/O` Owner) — ISO 32000-2 §14.8.5.
+
+**Module** `pdfTaggedPdfTyped` | **Source** `packages/front/office/pdf/src/extra/tagged-pdf-typed.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+Covers the standard attribute owners: Layout (§14.8.5.4), List (§14.8.5.5), Table (§14.8.5.7), PrintField (§14.8.5.6), Artifact (§14.8.2.2), UserProperties (§14.8.5.10). Dispatches on `/O`; unknown keys are preserved under `_extras`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfTaggedPdfTyped');
+// Returns: { typeStructAttribute, ATTRIBUTE_OWNERS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeStructAttribute` | `(dict) => StructAttr` | Record `{ owner, ...typed, raw, _extras }`. |
+| `ATTRIBUTE_OWNERS` | `Set<string>` | `Layout`, `List`, `Table`, `PrintField`, `Artifact`, `UserProperties`. |
+
+### Shape `StructAttr` (Layout)
+
+```js
+{ owner: 'Layout', placement, writingMode, backgroundColor,
+  borderColor, borderStyle, borderThickness, padding,
+  color, spaceBefore, spaceAfter, …, raw, _extras }
+```
+
+## Examples
+
+### Type a Layout attribute
+
+```js
+const ext = runtime.resolve('pdfTaggedPdfTyped');
+const a = ext.typeStructAttribute(layoutDict);
+a.owner;            // 'Layout'
+a.placement;        // 'Block'
+a.writingMode;      // 'LrTb'
+```
+
+### UserProperties
+
+```js
+const up = ext.typeStructAttribute(userPropsDict);
+up.properties;  // [ { name: 'role', value: 'caption', formatted: false, hidden: false }, … ]
+```
+
+### Catalog
+
+```js
+ext.ATTRIBUTE_OWNERS.has('Table');  // true
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/tagged/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/extra/tagged/missing-owner` | `ParseError` | `/O` missing or not a name. |
+| `pdf/extra/tagged/bad-user-property` | `ParseError` | A `/P` item is malformed. |
+
+## See also
+
+- [`pdfStructTree`](../tagged/structTree.md)
+- [`pdfStructElement`](../tagged/structElement.md)
+- [`pdfUaTagged`](./pdf-ua-tagged.md)
+- [Extras index](./README.md)

package/docs/api/extra/transparency-typed.md

@@ -0,0 +1,74 @@
+---
+module: pdfTransparencyTyped
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTransparencyTyped
+
+> Transparency Group (§11.6.6), Soft Mask (§11.6.5.2), blend modes (§11.3.5) — ISO 32000-2.
+
+**Module** `pdfTransparencyTyped` | **Source** `packages/front/office/pdf/src/extra/transparency-typed.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Types the group attributes `/Group /S /Transparency` (§11.6.6), the soft masks `/Luminosity` / `/Alpha` with `/TR` transfer (§11.6.5.2), and exposes the frozen catalog of standard blend modes (§11.3.5 Table 136).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfTransparencyTyped');
+// Returns: { typeTransparencyGroup, typeSoftMask, resolveBlendMode, BLEND_MODES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeTransparencyGroup` | `(dict) => Group` | `{ s, cs, isolated, knockout, raw, _extras }`. |
+| `typeSoftMask` | `(dict) => SoftMask` | `{ kind, g, backdrop, transfer, raw, _extras }`. |
+| `resolveBlendMode` | `(value) => string \| null` | Decodes a name or the first recognized name in an array. |
+| `BLEND_MODES` | frozen array | 17 standard modes (includes `Compatible`). |
+
+## Examples
+
+### Group
+
+```js
+const ext = runtime.resolve('pdfTransparencyTyped');
+const g = ext.typeTransparencyGroup(groupDict);
+g.s;         // 'Transparency'
+g.cs;        // raw /CS entry
+g.isolated;  // true
+g.knockout;  // false
+```
+
+### Blend mode resolution
+
+```js
+ext.resolveBlendMode({ type: 'name', value: 'Multiply' }); // 'Multiply'
+ext.resolveBlendMode({ type: 'array', items: [
+    { type: 'name', value: 'Saturation' },
+    { type: 'name', value: 'Normal' }
+]}); // 'Saturation' (first recognized name)
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/transparency-group/not-dict` | `ParseError` | Group is not a dict. |
+| `pdf/extra/transparency-group/bad-type` | `ParseError` | `/Type` present and not `/Group`. |
+| `pdf/extra/transparency-group/bad-s` | `ParseError` | `/S` is not `/Transparency`. |
+| `pdf/extra/soft-mask/not-dict` | `ParseError` | SoftMask is not a dict. |
+| `pdf/extra/soft-mask/bad-type` | `ParseError` | `/Type` is not `/Mask`. |
+| `pdf/extra/soft-mask/bad-s` | `ParseError` | `/S` is not `Luminosity`/`Alpha`. |
+| `pdf/extra/soft-mask/missing-g` | `ParseError` | `/G` (transparency group XObject) absent. |
+| `pdf/extra/blend-mode/bad-type` | `ParseError` | Value is neither a name nor an array. |
+
+## See also
+
+- [`pdfGraphics`](../content/graphics.md)
+- [`pdfContentOpsExtended`](./content-ops-extended.md)
+- [Extras index](./README.md)

package/docs/api/extra/well-tagged-pdf.md

@@ -0,0 +1,61 @@
+---
+module: pdfWellTagged
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfWellTagged
+
+> WTPDF 1.0 (Well-Tagged PDF) linter — best practices beyond PDF/UA.
+
+**Module** `pdfWellTagged` | **Source** `packages/front/office/pdf/src/extra/well-tagged-pdf.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+WTPDF 1.0 (PDF Association, 2024). Rule families: Artifact placement (tagged decorative content), `/Span` use (no bare pseudo-paragraph span), Table (`/Table` → `/TR` → `/TH`/`/TD`), List (`/L` → `/LI` → `/Lbl` + `/LBody`), heading-level jumps.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfWellTagged');
+// Returns: { lintWellTagged, checkArtifactPlacement, WTPDF_RULES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `lintWellTagged` | `(structTree) => { pass, errors, warnings }` | Walks the tree and applies the WTPDF checks. |
+| `checkArtifactPlacement` | `(regions) => { pass, errors, warnings }` | Checks an array of content regions. |
+| `WTPDF_RULES` | frozen catalog | Rule id → description (`wtpdf/artifact`, `wtpdf/span/empty`, `wtpdf/table/empty`, `wtpdf/table/row`, `wtpdf/list/empty`, `wtpdf/list/item`, `wtpdf/heading/jump`). |
+
+## Examples
+
+### Lint a tree
+
+```js
+const ext = runtime.resolve('pdfWellTagged');
+const r = ext.lintWellTagged(structTree);
+r.errors.find(e => e.rule === 'wtpdf/table/empty');
+```
+
+### Artifact placement
+
+```js
+ext.checkArtifactPlacement(regions).errors;
+// [ { rule: 'wtpdf/artifact', message: '…', mcid } ]
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/wtpdf/bad-tree` | `ParseError` | structTree is not an object. |
+| `pdf/extra/wtpdf/regions/bad-input` | `ParseError` | regions is not an array. |
+
+## See also
+
+- [`pdfUaTagged`](./pdf-ua-tagged.md)
+- [`pdfStructTree`](../tagged/structTree.md)
+- [Extras index](./README.md)

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

@@ -0,0 +1,65 @@
+---
+module: pdfXmpExtended
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfXmpExtended
+
+> Minimal XMP packet (RDF/XML) extractor.
+
+**Module** `pdfXmpExtended` | **Source** `packages/front/office/pdf/src/extra/xmp-extended.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Tokenizes an XMP RDF/XML packet for a fixed set of well-known namespaces and pulls out tag→value pairs. Not a full RDF parser — it walks the element stream and harvests qualified tags whose prefix maps to a known namespace.
+
+Supported namespaces: `dc`, `xmp`, `xmpMM`, `pdf`, `pdfaid`, `pdfuaid`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfXmpExtended');
+// Returns: { parsePacket, extract, group, KNOWN_NAMESPACES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `parsePacket` | `(string \| Uint8Array) => { pairs, grouped }` | Top-level entry point. |
+| `extract` | `(input) => Pair[]` | Flat list `{ prefix, ns, localName, value, attrs }`. |
+| `group` | `(pairs) => { [prefix]: { [localName]: value \| values[] } }` | Re-groups a flat pair list. |
+| `KNOWN_NAMESPACES` | object | URI → prefix. |
+
+## Examples
+
+### Parse
+
+```js
+const ext = runtime.resolve('pdfXmpExtended');
+const r = ext.parsePacket(xmpBytes);
+r.grouped.dc.title;    // 'My Document'
+r.grouped.pdfaid.part; // '2'
+```
+
+### Flat extract
+
+```js
+ext.extract(xmpBytes);
+// [ { prefix: 'dc', ns: '...', localName: 'title', value: '...', attrs: {} }, … ]
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/xmp2/bad-input` | `ParseError` | Neither a string nor a Uint8Array. |
+| `pdf/xmp2/unclosed-tag` | `ParseError` | Malformed XML (unclosed tag). |
+
+## See also
+
+- [`pdfXmp`](../metadata/xmp.md)
+- [`pdfInfoDictDeprecated`](./info-dict-deprecated.md)
+- [Extras index](./README.md)

package/docs/api/font/README.md

@@ -0,0 +1,25 @@
+# Font — ISO 32000-2 §9.6 / §9.7 / §9.9
+
+Typing of PDF Font dicts + `/Encoding` resolution + the embedding adapter. Parsing of the font files themselves (TrueType, Type1, CFF, CIDFont) is delegated to `@awacloud/fonts`.
+
+| Module | Returns | Deps | Description |
+|--------|----------|------|-------------|
+| [`pdfFont`](./font.md) | `{ typeFont, resolveDescendant }` | `pdfErrors`, `pdfParser` | Font dict, §9.6 / §9.7. |
+| [`pdfFontEncoding`](./encoding.md) | `{ resolveEncoding }` | `pdfErrors` | `/Encoding`, §9.6.5. |
+| [`pdfType3`](./type3.md) | `{ typeType3 }` | `pdfErrors`, `pdfParser` | PDF-specific Type 3, §9.6.4. |
+| [`pdfFontEmbed`](./embed.md) | `{ embedSimple, embedCid }` | `pdfErrors`, `embedSubsetForPdf`, `embedFontDescriptor`, `embedCidSystemInfo`, `embedToUnicodeBuilder` | Write-side adapter, §9.9 / ISO TS 32001. |
+
+## Common pattern
+
+```js
+const f = runtime.resolve('pdfFont');
+const enc = runtime.resolve('pdfFontEncoding');
+const font = f.typeFont(resources.Font.F1);
+const table = enc.resolveEncoding(font.encoding, lookupNamed);
+```
+
+## See also
+
+- [`pdfText`](../content/text.md) — `extractText` consumes `subtype` + ToUnicode.
+- [`pdfResources`](../document/resources.md) — supplies the dicts.
+- [Syntax layer](../syntax/README.md) — the underlying `pdfParser`.