@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/extra/legacy-rc4-read.md

@@ -0,0 +1,74 @@
+---
+module: pdfLegacyRc4Read
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLegacyRc4Read
+
+> RC4 v2/v3 password validation + stream decrypt, read-only — legacy.
+
+**Module** `pdfLegacyRc4Read` | **Source** `packages/front/office/pdf/src/extra/legacy-rc4-read.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Implements the RC4 stream cipher locally plus the read side of the Standard Security Handler PDF 1.7 §7.6.3.3-4: 40-bit RC4 (revision 2, V=1) and 128-bit RC4 (revision 3, V=2), password validation against `/O`/`/U`, per-object key derivation (file-key ‖ objectId/MD5) for `/Encrypt V <= 2`. PDF 2.0 forbids RC4 on write; this module is intentionally read-only.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfLegacyRc4Read');
+// Returns: { rc4, md5, padPassword, computeFileKey, computeU,
+//   validateUserPassword, objectKey, decryptString,
+//   decryptStream, PASSWORD_PADDING }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `rc4` | `(key: Uint8Array, data: Uint8Array) => Uint8Array` | Stream cipher. |
+| `md5` | `(bytes) => Uint8Array(16)` | Hash. |
+| `padPassword` | `(password) => Uint8Array(32)` | §7.6.3.3 step 1. |
+| `computeFileKey` | `(password, params: { O, P, idFirst, revision, keyLength, encryptMetadata }) => Uint8Array` | File-key derivation, §7.6.3.3 Algorithm 2. |
+| `computeU` | `(fileKey, idFirst, revision) => Uint8Array` | Computes the `/U` value. |
+| `validateUserPassword` | `(password, params: { O, P, idFirst, revision, keyLength, encryptMetadata, U }) => { ok: true, fileKey } \| { ok: false }` | |
+| `objectKey` | `(fileKey, objNum, gen) => Uint8Array` | Per-object key. |
+| `decryptString` / `decryptStream` | `(fileKey, objNum, gen, bytes) => Uint8Array` | |
+| `PASSWORD_PADDING` | `Uint8Array(32)` | Padding constant, §7.6.3.3. |
+
+## Examples
+
+### Validate a password
+
+```js
+const ext = runtime.resolve('pdfLegacyRc4Read');
+const r = ext.validateUserPassword('', {
+    O, P, idFirst, revision: 3, keyLength: 128, encryptMetadata: true, U
+});
+if (!r.ok) throw new Error('wrong password');
+const fileKey = r.fileKey;
+```
+
+### Decrypt a stream
+
+```js
+const plain = ext.decryptStream(fileKey, 5, 0, encStreamBytes);
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/rc4/bad-input` | `EncryptionError` | `rc4` arguments invalid. |
+| `pdf/md5/bad-input` | `EncryptionError` | `md5` input is not a Uint8Array. |
+| `pdf/rc4/bad-password` | `EncryptionError` | Password/pad input invalid. |
+| `pdf/rc4/bad-O` | `EncryptionError` | `/O` invalid (must be a 32-byte Uint8Array). |
+| `pdf/rc4/bad-id` | `EncryptionError` | `/ID` first element missing/invalid. |
+
+## See also
+
+- [`pdfStandardV5`](../crypto/standardV5.md)
+- [`pdfSecurity`](../crypto/security.md)
+- [Extras index](./README.md)

package/docs/api/extra/legacy-xfa-read.md

@@ -0,0 +1,65 @@
+---
+module: pdfLegacyXfaRead
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLegacyXfaRead
+
+> Opaque read-only reader for `/XFA` (XDP packets) — legacy.
+
+**Module** `pdfLegacyXfaRead` | **Source** `packages/front/office/pdf/src/extra/legacy-xfa-read.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+PDF 2.0 forbids writing XFA, but legacy documents must still be parsed. `/XFA` on the AcroForm dict comes in two shapes: (a) a single complete XDP stream, or (b) an array alternating string keys and streams (`['preamble', stream, 'config', stream, …]`). Surfaces the packets as opaque XML bytes on `_legacy.xfa` — no further interpretation.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfLegacyXfaRead');
+// Returns: { readXfa, isKnownPacket, KNOWN_PACKETS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `readXfa` | `(value) => { _legacy: { xfa: { shape, … } } }` | Stream or array shape. |
+| `isKnownPacket` | `(name) => boolean` | |
+| `KNOWN_PACKETS` | `Set` | `xdp`, `preamble`, `config`, `template`, `localeSet`, `datasets`, `form`, `connectionSet`, `sourceSet`, `stylesheet`, `xmpmeta`, `signature`, `postamble`, `pdf`. |
+
+## Examples
+
+### Read a stream
+
+```js
+const ext = runtime.resolve('pdfLegacyXfaRead');
+const r = ext.readXfa(xfaStream);
+r._legacy.xfa.shape;  // 'stream'
+r._legacy.xfa.xdp;    // Uint8Array
+```
+
+### Read an array
+
+```js
+const r = ext.readXfa(xfaArray);
+r._legacy.xfa.packets.template;  // Uint8Array
+r._legacy.xfa.order;             // ['preamble','template','datasets']
+r._legacy.xfa.unknownPackets;    // []
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/xfa/bad-packet` | `ParseError` | Array item is neither a string key nor a stream. |
+| `pdf/xfa/bad-key` | `ParseError` | Array key decoding failed. |
+| `pdf/xfa/odd-array` | `ParseError` | Odd item count (key/stream pairs expected). |
+| `pdf/xfa/bad-shape` | `ParseError` | Neither a stream nor an array. |
+
+## See also
+
+- [`pdfAcroForm`](../form/acroform.md)
+- [Extras index](./README.md)

package/docs/api/extra/linearization-write.md

@@ -0,0 +1,71 @@
+---
+module: pdfLinearizationWrite
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLinearizationWrite
+
+> Linearization Parameter Dictionary emitter — Annex F (write-side stub).
+
+**Module** `pdfLinearizationWrite` | **Source** `packages/front/office/pdf/src/extra/linearization-write.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Builds a `/Linearized` dict and a placeholder hint-stream for emission as the first indirect object of a linearized PDF (ISO 32000-2 Annex F). The full hint table (page-offset / shared-objects) remains future work — the stub is length-0 to keep the structural shape correct.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfLinearizationWrite');
+// Returns: { buildLinearizedDict, buildHintStreamStub,
+//   validateLinearizedDict, LINEARIZED_KEYS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `buildLinearizedDict` | `(params) => dictObj` | Typed `/Linearized` dict. |
+| `buildHintStreamStub` | `() => streamObj` | Length-0 stub. |
+| `validateLinearizedDict` | `(dict) => { pass, errors, warnings }` | Validates the Table F.1 shape. |
+| `LINEARIZED_KEYS` | frozen array | `['Linearized','L','H','O','E','N','T']`. |
+
+### Required `params`
+
+`version` (defaults to 1.0), `fileLength`, `hintOffset`, `hintLength`, `firstPageObj`, `firstPageEnd`, `pageCount`, `mainXrefOffset`, and optionally `firstPage`.
+
+## Examples
+
+### Build the dict
+
+```js
+const ext = runtime.resolve('pdfLinearizationWrite');
+const dict = ext.buildLinearizedDict({
+    version: 1.0, fileLength: 12345,
+    hintOffset: 678, hintLength: 200,
+    firstPageObj: 5, firstPageEnd: 4000,
+    pageCount: 10, mainXrefOffset: 12000
+});
+```
+
+### Validate
+
+```js
+ext.validateLinearizedDict(parsedDict).pass;  // true
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/linwrite/bad-params` | `RenderError` | `params` is not an object. |
+| `pdf/extra/linwrite/missing-<key>` | `RenderError` | A required numeric parameter is absent (`fileLength`, `firstPageObj`, `firstPageEnd`, `pageCount`, `mainXrefOffset`). |
+| `pdf/extra/linwrite/missing-hint` | `RenderError` | `hintOffset`/`hintLength` absent. |
+| `pdf/extra/linwrite/validate/not-dict` | `RenderError` | `validateLinearizedDict` argument is not a dict. |
+
+## See also
+
+- [`pdfLinearization`](../linearization/linearization.md)
+- [Extras index](./README.md)

package/docs/api/extra/misc.md

@@ -0,0 +1,93 @@
+---
+module: pdfMisc
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfMisc
+
+> Miscellaneous Catalog-level typing (SpiderInfo, Threads, Legal, …).
+
+**Module** `pdfMisc` | **Source** `packages/front/office/pdf/src/extra/misc.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Long tail of Catalog entries that don't warrant their own L1 module:
+- `/SpiderInfo` (§14.10.2) — Web-Capture provenance
+- `/Threads` (§12.4.3) — articles
+- `/Legal` (§12.8.5) — legal attestation
+- `/Requirements` (§12.10)
+- `/Perms` (§12.8.2) — DocMDP, UR3, UR
+- `/NeedsRendering` — XFA indicator
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfMisc');
+// Returns: { typeSpiderInfo, typeThreads, typeLegal, typeRequirements,
+//   typeDocMdpParams, typePerms, typeNeedsRendering,
+//   REQUIREMENT_S_VALUES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeSpiderInfo` | `(dict) => { version?, commands?, raw, _extras }` | §14.10.2. |
+| `typeThreads` | `(array) => Array<dict\|ref>` | §12.4.3, entries left unresolved. |
+| `typeLegal` | `(dict) => { raw, flags, attestation?, _extras }` | §12.8.5. |
+| `typeRequirements` | `(array) => Array<{ raw, s, standard, rh }>` | §12.10. |
+| `typeDocMdpParams` | `(dict) => { permission?, version?, raw, _extras }` | §12.8.2.2. |
+| `typePerms` | `(dict) => { docMDP?, ur3?, ur?, raw, _extras }` | §12.8.2. |
+| `typeNeedsRendering` | `(value) => boolean` | XFA indicator. |
+| `REQUIREMENT_S_VALUES` | `Set` | `EnableJavaScripts`. |
+
+## Examples
+
+### SpiderInfo
+
+```js
+const ext = runtime.resolve('pdfMisc');
+const s = ext.typeSpiderInfo(catalog.spiderInfo);
+s.version;  // 1.0
+```
+
+### Threads
+
+```js
+const ts = ext.typeThreads(catalog.threads);
+ts.length;
+```
+
+### NeedsRendering
+
+```js
+ext.typeNeedsRendering({ type: 'bool', value: true });  // true
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/misc/spider-not-dict` | `ParseError` | SpiderInfo is not a dict. |
+| `pdf/misc/spider-bad-V` | `ParseError` | `/V` is not numeric. |
+| `pdf/misc/spider-bad-C` | `ParseError` | `/C` is not an array. |
+| `pdf/misc/threads-not-array` | `ParseError` | `/Threads` is not an array. |
+| `pdf/misc/thread-bad-entry` | `ParseError` | Entry is neither dict nor ref. |
+| `pdf/misc/legal-not-dict` | `ParseError` | Legal is not a dict. |
+| `pdf/misc/legal-bad-flag` | `ParseError` | A flag is not an int. |
+| `pdf/misc/legal-bad-attestation` | `ParseError` | `/Attestation` is not a string. |
+| `pdf/misc/req-not-array` | `ParseError` | Requirements is not an array. |
+| `pdf/misc/req-bad-entry` | `ParseError` | Entry is not a dict. |
+| `pdf/misc/req-missing-S` | `ParseError` | `/S` absent. |
+| `pdf/misc/docmdp-not-dict` | `ParseError` | DocMDP is not a dict. |
+| `pdf/misc/docmdp-bad-P` | `ParseError` | `/P` is not an int. |
+| `pdf/misc/docmdp-bad-V` | `ParseError` | `/V` is not a name. |
+| `pdf/misc/perms-not-dict` | `ParseError` | Perms is not a dict. |
+| `pdf/misc/needsrendering-bad` | `ParseError` | Not a bool. |
+
+## See also
+
+- [`pdfCatalog`](../document/catalog.md)
+- [Extras index](./README.md)

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

@@ -0,0 +1,83 @@
+---
+module: pdfOptionalContentExtended
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfOptionalContentExtended
+
+> Extended OCG/OCMD — VE (Visibility Expression), Order tree, RBGroups, Intent — ISO 32000-2 §8.11.
+
+**Module** `pdfOptionalContentExtended` | **Source** `packages/front/office/pdf/src/extra/optional-content-extended.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+§8.11.2.4 defines OCMD `/VE` (Visibility Expression) as a nested array `[op, operand, …]` with ops `And`, `Or`, `Not`. This module evaluates such expressions, types `/Order` (including sub-heading strings), and surfaces RBGroups and `/Intent` (View vs Design).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfOptionalContentExtended');
+// Returns: { evaluateVE, typeOrderTree, typeRBGroups,
+//   classifyOcgIntent, VE_OPERATORS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `evaluateVE` | `(ve, onSet: Set<string>) => boolean` | Recursively evaluates; `onSet` holds `"num gen"` keys of "on" OCGs. |
+| `typeOrderTree` | `(orderArray) => OrderNode[]` | Nodes shaped `{ kind: 'heading', text } \| { kind: 'group', children } \| { kind: 'ocg', ref } \| { kind: 'other', value }`. |
+| `typeRBGroups` | `(arr) => Array<Array<{ num, gen }>>` | Mutually-exclusive radio-button groups. |
+| `classifyOcgIntent` | `(value) => { view: boolean, design: boolean, names: string[] }` | |
+| `VE_OPERATORS` | frozen array | `['And','Or','Not']`. |
+
+## Examples
+
+### Evaluate VE
+
+```js
+const ext = runtime.resolve('pdfOptionalContentExtended');
+const visible = ext.evaluateVE(
+    { type: 'array', items: [
+        { type: 'name', value: 'And' }, ocgRefA,
+        { type: 'array', items: [{ type: 'name', value: 'Not' }, ocgRefB] }
+    ] },
+    onSet
+);
+```
+
+### Order tree
+
+```js
+const tree = ext.typeOrderTree(orderArr);
+// [ { kind: 'heading', text: 'Layer group' }, { kind: 'group', children: [...] }, … ]
+```
+
+### Intent
+
+```js
+ext.classifyOcgIntent({ type: 'name', value: 'View' });
+// { view: true, design: false, names: ['View'] }
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/ocgx/ve/null` | `ParseError` | VE expression is null. |
+| `pdf/extra/ocgx/ve/bad-state` | `ParseError` | `onSet` is not a `Set`. |
+| `pdf/extra/ocgx/ve/bad-shape` | `ParseError` | Neither an array nor a ref. |
+| `pdf/extra/ocgx/ve/bad-op` | `ParseError` | Operator outside `VE_OPERATORS`. |
+| `pdf/extra/ocgx/ve/not-arity` | `ParseError` | Wrong arity (`Not` = 1, `And`/`Or` ≥ 1). |
+| `pdf/extra/ocgx/order/not-array` | `ParseError` | `/Order` is not an array. |
+| `pdf/extra/ocgx/rbg/not-array` | `ParseError` | `/RBGroups` is not an array. |
+| `pdf/extra/ocgx/rbg/bad-group` | `ParseError` | A group entry is not an array. |
+| `pdf/extra/ocgx/intent/bad` | `ParseError` | Intent is neither a name nor an array. |
+
+## See also
+
+- [`pdfOCG`](../ocg/ocg.md)
+- [`pdfOCConfig`](../ocg/config.md)
+- [Extras index](./README.md)

package/docs/api/extra/pdf-a-output-intent.md

@@ -0,0 +1,65 @@
+---
+module: pdfAOutputIntent
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAOutputIntent
+
+> PDF/A detection (`/S /GTS_PDFA1`) and basic validation — ISO 19005-{1..4}.
+
+**Module** `pdfAOutputIntent` | **Source** `packages/front/office/pdf/src/extra/pdf-a-output-intent.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Recognizes an `/OutputIntent` whose `/S` is `GTS_PDFA1` (or later ISO 19005-2/3/4 profile names), extracts the conformance-level letter (a/b/u/e/f), and maps `/OutputConditionIdentifier` to a known registry profile.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfAOutputIntent');
+// Returns: { detectPdfAProfile, validatePdfABasics, PDFA_PROFILES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `detectPdfAProfile` | `(outputIntentDict) => { isPdfA, subtype, identifier, profile, part, level, catalog, raw }` | Detected profile fields (`part`/`level`/`catalog` are `null` when the identifier is unrecognized). |
+| `validatePdfABasics` | `(typedDoc) => { pass, errors, warnings }` | Lints Catalog/Metadata basics. |
+| `PDFA_PROFILES` | frozen catalog | `'1a'`, `'1b'`, `'2a'`, …, `'4f'` → `{ part, level, iso, notes }`. |
+
+## Examples
+
+### Detect the profile
+
+```js
+const ext = runtime.resolve('pdfAOutputIntent');
+const p = ext.detectPdfAProfile(outputIntent);
+p.part;   // 2
+p.level;  // 'b'
+p.catalog.iso;  // 'ISO 19005-2:2011'
+```
+
+### Lint
+
+```js
+const r = ext.validatePdfABasics(typedDoc);
+r.pass;      // false
+r.errors;    // [ 'catalog requires /Metadata XMP stream', … ]
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/pdfa/not-dict` | `ParseError` | outputIntent is not a dict. |
+| `pdf/extra/pdfa/lint/bad-doc` | `ParseError` | typedDoc is not an object. |
+
+## See also
+
+- [`pdfOutputIntent`](../prepress/outputIntent.md)
+- [`pdfXmp`](../metadata/xmp.md)
+- [`pdfXPrepress`](./pdf-x-prepress.md)
+- [Extras index](./README.md)

package/docs/api/extra/pdf-sandbox.md

@@ -0,0 +1,76 @@
+---
+module: pdfSandbox
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSandbox
+
+> Strict sandbox linter for active-content PDF features.
+
+**Module** `pdfSandbox` | **Source** `packages/front/office/pdf/src/extra/pdf-sandbox.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Flags actions that request active/external behaviour when a document is opened in an untrusted context: `/Launch`, `/JavaScript`, `/ImportData` (errors — execution, scripting, or file-system reads); `/SubmitForm`, `/Rendition` (with a `/JS` payload), `/URI` (warnings — network or navigation side effects). Benign actions (`GoTo`, `Named`, …) are ignored. The linter consumes already-typed action records (e.g. from `pdfFormActionsExtended.typeExtendedAction`), it does not parse raw dicts itself.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfSandbox');
+// Returns: { lintAction, lintActions, ACTIVE_KINDS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `lintAction` | `(rec: { kind, sandboxed? }) => Issue \| null` | `null` for non-objects, benign kinds, or a `Rendition` record with `sandboxed` falsy. |
+| `lintActions` | `(records: Iterable<Record>) => { sandboxed: true, issues: Issue[], hasActiveContent: boolean, hasErrors: boolean }` | Aggregates `lintAction` over an iterable. |
+| `ACTIVE_KINDS` | frozen catalog | Action kind → `{ severity: 'error' \| 'warning', message }`. |
+
+### Shape `Issue`
+
+```js
+{ kind, code: 'pdf/sandbox/active-' + kind.toLowerCase(),
+  severity: 'error' | 'warning', message, context: { sandboxed: boolean } }
+```
+
+## Examples
+
+### Lint a single action
+
+```js
+const ext = runtime.resolve('pdfSandbox');
+const issue = ext.lintAction({ kind: 'Launch', sandboxed: true });
+issue.severity;  // 'error'
+issue.code;      // 'pdf/sandbox/active-launch'
+```
+
+### Lint a list of typed actions
+
+```js
+const r = ext.lintActions([
+    { kind: 'Launch', sandboxed: true },
+    { kind: 'GoTo' },
+    { kind: 'URI' }
+]);
+r.issues.length;       // 2
+r.hasActiveContent;    // true
+r.hasErrors;           // true (Launch is an error-severity kind)
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/sandbox/bad-input` | `ContractError` | `lintActions` argument is not iterable. |
+
+`lintAction` never throws — it returns `null` for any input it cannot classify.
+
+## See also
+
+- [`pdfFormActionsExtended`](./form-actions-extended.md)
+- [`pdfAction`](../action/action.md)
+- [Extras index](./README.md)

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

@@ -0,0 +1,63 @@
+---
+module: pdfUaTagged
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfUaTagged
+
+> PDF/UA-1 linter (ISO 14289-1) and draft PDF/UA-2 (ISO 14289-2).
+
+**Module** `pdfUaTagged` | **Source** `packages/front/office/pdf/src/extra/pdf-ua-tagged.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+Static linter. Catalog checks: `/StructTreeRoot` required, `/MarkInfo /Marked true`, `/Lang`, `/ViewerPreferences /DisplayDocTitle true`. Structure-element checks: Figures need `/Alt` or `/ActualText`; `/Span` is discouraged as a top-level type; the accessible-permission bit (bit 10) must be set.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfUaTagged');
+// Returns: { validatePdfUa, validateUaStructElement, UA_STRUCTURE }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `validatePdfUa` | `(typedDoc) => { pass, errors, warnings }` | Document-level lint. |
+| `validateUaStructElement` | `(node) => { pass, errors, warnings }` | Lints a single structure node. |
+| `UA_STRUCTURE` | frozen catalog | `{ required, forbidden, figure, headings }` structural rule lists. |
+
+## Examples
+
+### Global lint
+
+```js
+const ext = runtime.resolve('pdfUaTagged');
+const r = ext.validatePdfUa(typedDoc);
+r.pass;      // false
+r.errors;    // [ 'catalog requires /Lang string', … ]
+```
+
+### Lint a node
+
+```js
+const r = ext.validateUaStructElement(figureNode);
+r.errors[0];  // 'Figure requires /Alt or /ActualText'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/pdfua/bad-doc` | `ParseError` | typedDoc is not an object. |
+| `pdf/extra/pdfua/struct/bad-node` | `ParseError` | node is not an object. |
+
+## See also
+
+- [`pdfStructTree`](../tagged/structTree.md)
+- [`pdfWellTagged`](./well-tagged-pdf.md)
+- [`pdfTaggedPdfTyped`](./tagged-pdf-typed.md)
+- [Extras index](./README.md)

package/docs/api/extra/pdf-x-prepress.md

@@ -0,0 +1,65 @@
+---
+module: pdfXPrepress
+category: pdf/extra
+dependencies: [pdfErrors, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfXPrepress
+
+> PDF/X conformance (X-1a, X-3, X-4, …, X-6) — ISO 15930.
+
+**Module** `pdfXPrepress` | **Source** `packages/front/office/pdf/src/extra/pdf-x-prepress.js` | **Deps** `pdfErrors`, `pdfParser` | **Worker-safe** yes
+
+PDF/X profile family (X-1a/X-3/X-4/X-4p/X-5g/X-5n/X-5pg/X-6) with `/OutputIntent /S /GTS_PDFX`. Structural lint: `/TrimBox` (or `/ArtBox`, never both) on every page, plus a `/BleedBox` presence warning.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfXPrepress');
+// Returns: { typePdfXOutputIntent, lintPdfXPage, PDFX_PROFILES, COLOR_POLICY }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typePdfXOutputIntent` | `(dict) => { isPdfX, subtype, identifier, profile, catalog, raw }` | Typed output intent. |
+| `lintPdfXPage` | `(page) => { pass, errors, warnings }` | Structural per-page lint. |
+| `PDFX_PROFILES` | frozen catalog | Profile name → `{ iso, color, flavor }`. |
+| `COLOR_POLICY` | frozen catalog | `None`/`Convert`/`Tag`/`Embed` → description. |
+
+## Examples
+
+### Detect the profile
+
+```js
+const ext = runtime.resolve('pdfXPrepress');
+const oi = ext.typePdfXOutputIntent(outputIntent);
+oi.profile;        // 'X-4'
+oi.catalog.iso;    // 'ISO 15930-7:2010'
+```
+
+### Lint a page
+
+```js
+const r = ext.lintPdfXPage(page);
+r.pass;    // false
+r.errors;  // [ 'page requires /TrimBox or /ArtBox' ]
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/pdfx/not-dict` | `ParseError` | outputIntent is not a dict. |
+| `pdf/extra/pdfx/lint/bad-page` | `ParseError` | page is not a typed page dict. |
+
+## See also
+
+- [`pdfPageBoundary`](../prepress/pageBoundary.md)
+- [`pdfOutputIntent`](../prepress/outputIntent.md)
+- [`pdfAOutputIntent`](./pdf-a-output-intent.md)
+- [Extras index](./README.md)