@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/extra/embedded-files-portfolio.md

@@ -0,0 +1,87 @@
+---
+module: pdfEmbeddedFilesPortfolio
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfEmbeddedFilesPortfolio
+
+> Deep typing of the PDF Portfolio (`/Collection`).
+
+**Module** `pdfEmbeddedFilesPortfolio` | **Source** `packages/front/office/pdf/src/extra/embedded-files-portfolio.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Augments the L1 `/Collection` typing with deep inspection: `/Schema` field defs, `/Sort` criteria, `/Navigator`, the initial `/D` entry, the `/View` mode (`D`/`T`/`H`/`C`), and the `/CI` (Collection Item) custom icon.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfEmbeddedFilesPortfolio');
+// Returns: { typePortfolio, typeSchema, typeSchemaField, typeSort,
+//   typeNavigator, typeCustomIcon, typeCollectionItem,
+//   VIEW_MODES, SCHEMA_SUBTYPES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typePortfolio` | `(collectionDict) => Portfolio` | Full view `{ raw, _extras, schema?, initialDoc?, view?, sort?, navigator? }`. |
+| `typeSchema` | `(dict) => { fields, raw }` | `/Schema` fields, keyed by their dict key. |
+| `typeSchemaField` | `(name, dict) => Field` | A single field definition. |
+| `typeSort` | `(dict) => Sort` | `/Sort` `/S`/`/A`. |
+| `typeNavigator` | `(value) => Navigator` | Ref or typed dict. |
+| `typeCustomIcon` | `(dict) => { raw }` | `/CI` icon. |
+| `typeCollectionItem` | `(dict) => CI` | Per-file metadata. |
+| `VIEW_MODES` | `Set` | `D`, `T`, `H`, `C`. |
+| `SCHEMA_SUBTYPES` | `Set` | `S`, `D`, `N`, `F`, `Desc`, `ModDate`, `CreationDate`, `Size`. |
+
+## Examples
+
+### Load a portfolio
+
+```js
+const ext = runtime.resolve('pdfEmbeddedFilesPortfolio');
+const p = ext.typePortfolio(catalog.collection);
+p.view;                    // 'D'
+p.schema.fields.Title.displayName;  // 'Title'
+```
+
+### Sort
+
+```js
+ext.typeSort(sortDict);
+// { keys: ['Date','Size'], ascending: [false, true], raw, _extras }
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/portfolio/bad-schema-field` | `ParseError` | Field is not a dict. |
+| `pdf/portfolio/bad-schema-subtype` | `ParseError` | `/Subtype` outside the set. |
+| `pdf/portfolio/bad-schema-n` | `ParseError` | `/N` is not a string. |
+| `pdf/portfolio/bad-schema-o` | `ParseError` | `/O` is not an int. |
+| `pdf/portfolio/bad-schema-v` | `ParseError` | `/V` wrong type. |
+| `pdf/portfolio/bad-schema-e` | `ParseError` | `/E` wrong type. |
+| `pdf/portfolio/bad-schema` | `ParseError` | `/Schema` dict invalid. |
+| `pdf/portfolio/bad-sort` | `ParseError` | `/Sort` dict invalid. |
+| `pdf/portfolio/bad-sort-s-item` | `ParseError` | `/S` array item is not a name. |
+| `pdf/portfolio/bad-sort-s` | `ParseError` | `/S` is neither name nor array. |
+| `pdf/portfolio/bad-sort-a-item` | `ParseError` | `/A` array item is not a bool. |
+| `pdf/portfolio/bad-sort-a` | `ParseError` | `/A` is neither bool nor array. |
+| `pdf/portfolio/bad-navigator` | `ParseError` | Navigator invalid. |
+| `pdf/portfolio/bad-ci` | `ParseError` | `/CI` is not a dict or stream. |
+| `pdf/portfolio/not-dict` | `ParseError` | Collection is not a dict. |
+| `pdf/portfolio/bad-type` | `ParseError` | `/Type` is not `/Collection`. |
+| `pdf/portfolio/bad-d` | `ParseError` | `/D` is not a string. |
+| `pdf/portfolio/bad-view` | `ParseError` | `/View` outside `VIEW_MODES`. |
+| `pdf/portfolio/ci-not-dict` | `ParseError` | `typeCollectionItem` argument is not a dict. |
+
+## See also
+
+- [`pdfCollection`](../embedded/collection.md)
+- [`pdfFileSpec`](../embedded/fileSpec.md)
+- [Extras index](./README.md)

package/docs/api/extra/font-cid-typed.md

@@ -0,0 +1,77 @@
+---
+module: pdfFontCidTyped
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFontCidTyped
+
+> Typed CIDFont, CIDSystemInfo, `/W` glyph widths, and the predefined-CMap catalog — ISO 32000-2 §9.7.
+
+**Module** `pdfFontCidTyped` | **Source** `packages/front/office/pdf/src/extra/font-cid-typed.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+Covers `/CIDFontType0` and `/CIDFontType2` (§9.7.4), `/CIDSystemInfo` (§9.7.3), `/CIDToGIDMap` (§9.7.4.3), `/W /W2 /DW /DW2` (§9.7.4.3), and the frozen list of predefined CMaps (§9.7.5.2).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfFontCidTyped');
+// Returns: { typeCIDFont, typeCIDSystemInfo, decodeWidthsW, PREDEFINED_CMAPS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeCIDFont` | `(dict) => CIDFont` | Record for `/Type /Font /Subtype /CIDFontType{0,2}`. |
+| `typeCIDSystemInfo` | `(dict) => { registry, ordering, supplement }` | §9.7.3. |
+| `decodeWidthsW` | `(array) => Array<{ first, last, widths? , width? }>` | Expands `/W` runs. |
+| `PREDEFINED_CMAPS` | frozen catalog | Map `registry-ordering` → list of CMap names. |
+
+## Examples
+
+### Type a CIDFont
+
+```js
+const cid = ext.typeCIDFont(doc._raw.resolve(cidFontRef));
+cid.subtype;         // 'CIDFontType2'
+cid.cidSystemInfo.registry; // 'Adobe'
+cid.dw;              // 1000
+```
+
+### Decode `/W`
+
+```js
+ext.decodeWidthsW(arr);
+// [ { first: 1, last: 3, widths: [500, 500, 500] }, { first: 10, last: 10, width: 600 } ]
+```
+
+### Predefined CMap
+
+```js
+ext.PREDEFINED_CMAPS['Adobe-GB1'].includes('GB-EUC-H'); // true
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/cid-font/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/extra/cid-font/bad-type` | `ParseError` | `/Type` present and not `/Font`. |
+| `pdf/extra/cid-font/bad-subtype` | `ParseError` | `/Subtype` is not a CIDFontType. |
+| `pdf/extra/cid-font/missing-csi` | `ParseError` | `/CIDSystemInfo` missing. |
+| `pdf/extra/cid-system-info/not-dict` | `ParseError` | CIDSystemInfo is not a dictionary. |
+| `pdf/extra/cid-system-info/incomplete` | `ParseError` | A required field is absent. |
+| `pdf/extra/cid-font/bad-w` | `ParseError` | `/W` is not an array. |
+| `pdf/extra/cid-font/bad-w-c` | `ParseError` | First value is not numeric. |
+| `pdf/extra/cid-font/bad-w-item` | `ParseError` | Array item is not numeric. |
+| `pdf/extra/cid-font/bad-w-range` | `ParseError` | Range form is malformed. |
+
+## See also
+
+- [`pdfFont`](../font/font.md)
+- [`pdfFontEncoding`](../font/encoding.md)
+- [Extras index](./README.md)

package/docs/api/extra/font-color-tagging.md

@@ -0,0 +1,76 @@
+---
+module: pdfFontColorTagging
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFontColorTagging
+
+> Detection of OpenType color fonts (COLR/CPAL/sbix/SVG/CBDT) and FontDescriptor flags — ISO 32000-2 §9.8.2.
+
+**Module** `pdfFontColorTagging` | **Source** `packages/front/office/pdf/src/extra/font-color-tagging.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+PDF has no single "is-color-font" flag. This module cross-references the FontDescriptor flags (Table 121) with an sfnt-table scan of an embedded `/FontFile3 /Subtype /OpenType` program to detect color OT tables.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfFontColorTagging');
+// Returns: { decodeFontDescriptorFlags, detectColorFontTables,
+//   typeFontFile3OpenType, FONT_DESCRIPTOR_FLAGS, COLOR_OT_TABLES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `decodeFontDescriptorFlags` | `(int) => FlagsRecord` | Decodes each bit into a named boolean. |
+| `detectColorFontTables` | `(Uint8Array) => { hasCOLR, hasSbix, hasSVG, hasCBDT, tables }` | Scans the sfnt table directory. |
+| `typeFontFile3OpenType` | `(streamObj) => { subtype, length, metadata, color, raw, _extras }` | Typed wrapper around `/FontFile3`. |
+| `FONT_DESCRIPTOR_FLAGS` | frozen catalog | Bit name → mask (FixedPitch, Serif, Symbolic, Script, Nonsymbolic, Italic, AllCap, SmallCap, ForceBold). |
+| `COLOR_OT_TABLES` | frozen array | `['COLR','CPAL','sbix','SVG ','CBDT','CBLC']`. |
+
+## Examples
+
+### Detect a color font
+
+```js
+const r = ext.detectColorFontTables(fontBytes);
+r.tables;      // ['COLR', 'CPAL', ...]
+r.hasCOLR;     // true
+```
+
+### Decode the flags
+
+```js
+const f = ext.decodeFontDescriptorFlags(0x44);
+f.symbolic;    // true
+f.nonsymbolic; // false
+```
+
+### Type `/FontFile3 /Subtype /OpenType`
+
+```js
+const ff3 = ext.typeFontFile3OpenType(stream);
+ff3.subtype;  // 'OpenType'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/font-flags/bad-input` | `ParseError` | Argument is not numeric. |
+| `pdf/extra/color-font/bad-input` | `ParseError` | Argument is not a Uint8Array. |
+| `pdf/extra/color-font/truncated` | `ParseError` | sfnt header truncated. |
+| `pdf/extra/fontfile3/not-stream` | `ParseError` | `/FontFile3` is not a stream. |
+| `pdf/extra/fontfile3/no-dict` | `ParseError` | Stream has no dict. |
+| `pdf/extra/fontfile3/bad-subtype` | `ParseError` | `/Subtype` is not `/OpenType`. |
+
+## See also
+
+- [`pdfFontEmbed`](../font/embed.md)
+- [`pdfFontCidTyped`](./font-cid-typed.md)
+- [Extras index](./README.md)

package/docs/api/extra/form-actions-extended.md

@@ -0,0 +1,75 @@
+---
+module: pdfFormActionsExtended
+category: pdf/extra
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFormActionsExtended
+
+> Extended action subtypes (GoTo3DView, SetOCGState, …) — ISO 32000-2 §12.6.4.
+
+**Module** `pdfFormActionsExtended` | **Source** `packages/front/office/pdf/src/extra/form-actions-extended.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+Covers: GoTo3DView (§12.6.4.15), SetOCGState (§12.6.4.12), Trans (§12.6.4.13), Rendition (§12.6.4.14), Hide (§12.6.4.10), SubmitForm (§12.6.4.4), ResetForm (§12.6.4.5), ImportData (§12.6.4.6), JavaScript (§12.6.4.7, sandboxed flag only). Returns `{ kind, ...typed, raw, _extras }`.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfFormActionsExtended');
+// Returns: { typeExtendedAction, EXTENDED_ACTION_SUBTYPES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeExtendedAction` | `(dict) => ExtendedAction` | Dispatches on `/S`. |
+| `EXTENDED_ACTION_SUBTYPES` | `Set<string>` | The 9 covered subtypes. |
+
+## Examples
+
+### Type an action
+
+```js
+const ext = runtime.resolve('pdfFormActionsExtended');
+const a = ext.typeExtendedAction(actionDict);
+a.kind;  // 'SubmitForm' | 'JavaScript' | …
+```
+
+### SetOCGState
+
+```js
+a.kind;   // 'SetOCGState'
+a.state;  // raw /State array items
+```
+
+### JavaScript
+
+```js
+a.kind;        // 'JavaScript'
+a.js;          // string or stream
+a.sandboxed;   // true
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/extra/action-ext/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/extra/action-ext/bad-type` | `ParseError` | `/Type` present and not `/Action`. |
+| `pdf/extra/action-ext/unsupported` | `ParseError` | `/S` outside `EXTENDED_ACTION_SUBTYPES`. |
+| `pdf/extra/action-ext/bad-state` | `ParseError` | SetOCGState `/State` malformed. |
+| `pdf/extra/action-ext/bad-trans` | `ParseError` | `/Trans` dict invalid. |
+| `pdf/extra/action-ext/missing-t` | `ParseError` | `/T` absent (Hide). |
+| `pdf/extra/action-ext/bad-t` | `ParseError` | `/T` wrong type. |
+| `pdf/extra/action-ext/missing-f` | `ParseError` | `/F` absent (SubmitForm/ImportData). |
+| `pdf/extra/action-ext/missing-js` | `ParseError` | `/JS` absent. |
+| `pdf/extra/action-ext/bad-js` | `ParseError` | `/JS` wrong type. |
+
+## See also
+
+- [`pdfAction`](../action/action.md)
+- [Extras index](./README.md)

package/docs/api/extra/info-dict-deprecated.md

@@ -0,0 +1,72 @@
+---
+module: pdfInfoDictDeprecated
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfInfoDictDeprecated
+
+> `/Info` linter (deprecated in PDF 2.0) with XMP mapping.
+
+**Module** `pdfInfoDictDeprecated` | **Source** `packages/front/office/pdf/src/extra/info-dict-deprecated.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+PDF 2.0 (ISO 32000-2 §14.3.3) deprecates the Document Information Dictionary in favour of the XMP metadata stream. This module inspects a Catalog + `/Info` pair and emits structured warnings when `/Info` is present on a PDF 2.0 document, with a suggested XMP mapping per the standard's recommended namespaces.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfInfoDictDeprecated');
+// Returns: { lint, mapInfoKey, suggestionsFor, INFO_TO_XMP, isVersion2OrHigher }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `lint` | `({ version, info, xmpPresent }) => { version, isPdf2, hasInfo, xmpPresent, warnings }` | Top-level lint. |
+| `mapInfoKey` | `(name) => { ns, field } \| null` | Lookup by Info key. |
+| `suggestionsFor` | `(infoDict) => Suggestion[]` | List of per-entry mappings. |
+| `INFO_TO_XMP` | object | Info key → `{ ns, field }`. |
+| `isVersion2OrHigher` | `(version) => boolean` | |
+
+## Examples
+
+### Lint
+
+```js
+const ext = runtime.resolve('pdfInfoDictDeprecated');
+const r = ext.lint({ version: 2.0, info: infoDict, xmpPresent: false });
+r.warnings;
+// [ { code: 'pdf/info-deprecated', severity: 'warn', message: '…', suggestions: [...] },
+//   { code: 'pdf/info-without-xmp', severity: 'warn', message: '…' } ]
+```
+
+### Map a key
+
+```js
+ext.mapInfoKey('Author');  // { ns: 'dc', field: 'creator' }
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/info-deprecated/bad-version` | `ParseError` | version is not string/name/number. |
+| `pdf/info-deprecated/bad-info` | `ParseError` | Info is not a dict. |
+
+### Warning codes (lint output)
+
+| Code | Severity | When |
+|------|----------|------|
+| `pdf/info-deprecated` | warn | PDF 2.0 + `/Info` present. |
+| `pdf/info-without-xmp` | warn | PDF 2.0 + `/Info` without XMP. |
+
+## See also
+
+- [`pdfInfo`](../metadata/info.md)
+- [`pdfXmp`](../metadata/xmp.md)
+- [`pdfXmpExtended`](./xmp-extended.md)
+- [Extras index](./README.md)

package/docs/api/extra/jbig2-read.md

@@ -0,0 +1,80 @@
+---
+module: pdfJbig2Read
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: partial
+---
+
+# pdfJbig2Read
+
+> JBIG2 segment reader, header-only (PARTIAL).
+
+**Module** `pdfJbig2Read` | **Source** `packages/front/office/pdf/src/extra/jbig2-read.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+JBIG2 is the bilevel codec referenced by `/Filter /JBIG2Decode` (ISO 32000-2 §7.4.7). A full decoder is out of scope; this module parses the segment-header chain (ISO/IEC 14492:2001 §7.2) and returns descriptors for enumeration. **Status: PARTIAL — header-only**, unrelated to the real T.4/T.6 codec shipped by [`pdfCcittFaxDecoder`](./ccitt-fax-decoder.md).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfJbig2Read');
+// Returns: { parseSegments, enumerateGenericRegions, decode,
+//   SEGMENT_TYPES, STATUS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `parseSegments` | `(Uint8Array) => Segment[]` | Walks the segment chain. |
+| `enumerateGenericRegions` | `(Uint8Array) => Segment[]` | Filters types 36/38/39. |
+| `decode` | `(Uint8Array) => never` | Always throws `not-implemented`. |
+| `SEGMENT_TYPES` | object | Type number → name. |
+| `STATUS` | string | `'partial — header-only'`. |
+
+### Shape `Segment`
+
+```js
+{ segmentNumber, type, typeName, referredCount,
+  retain, deferredNonRetain, dataOffset, dataLength, unknownLength }
+```
+
+## Examples
+
+### Enumerate segments
+
+```js
+const ext = runtime.resolve('pdfJbig2Read');
+const segs = ext.parseSegments(jbig2Bytes);
+segs[0].typeName;  // 'symbolDictionary'
+```
+
+### Generic regions
+
+```js
+ext.enumerateGenericRegions(jbig2Bytes).length;
+```
+
+### Status check
+
+```js
+ext.STATUS;  // 'partial — header-only'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/jbig2/bad-input` | `ParseError` | Not a Uint8Array. |
+| `pdf/jbig2/truncated-header` | `ParseError` | Header chain cut short. |
+| `pdf/jbig2/truncated-data-length` | `ParseError` | Data-length field missing. |
+| `pdf/jbig2/truncated-data` | `ParseError` | Payload cut short. |
+| `pdf/jbig2/not-implemented` | `ParseError` | Always, from `decode()`. |
+
+## See also
+
+- [`pdfFilters`](../syntax/filters/README.md)
+- [`pdfImages`](../content/images.md)
+- [`pdfCcittFaxDecoder`](./ccitt-fax-decoder.md)
+- [Extras index](./README.md)

package/docs/api/extra/legacy-deprecated-annots.md

@@ -0,0 +1,89 @@
+---
+module: pdfLegacyDeprecatedAnnots
+category: pdf/extra
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLegacyDeprecatedAnnots
+
+> Sound (§12.5.6.16), Movie (§12.5.6.17), Screen (§12.5.6.18) — legacy.
+
+**Module** `pdfLegacyDeprecatedAnnots` | **Source** `packages/front/office/pdf/src/extra/legacy-deprecated-annots.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Typed payloads for the multimedia subtypes that PDF 2.0 deprecates in favour of `/RichMedia` and the `/Screen` + `/Rendition` pattern:
+- `/Subtype /Sound` (ISO 32000-1 §12.5.6.16): `/Sound` stream, `/Name` icon.
+- `/Subtype /Movie` (§12.5.6.17): `/Movie` dict, `/A` activation, `/T` title.
+- `/Subtype /Screen` (§12.5.6.18): `/MK` appearance, `/A` rendition action, `/AA` additional actions.
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfLegacyDeprecatedAnnots');
+// Returns: { typeSoundAnnot, typeSoundStream, typeMovieAnnot,
+//   typeScreenAnnot, SOUND_MODES, MOVIE_OP_MODES }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `typeSoundAnnot` | `(dict) => SoundAnnot` | `{ subtype: 'Sound', sound, iconName?, raw, _extras }`. |
+| `typeSoundStream` | `(stream) => { samplingRate?, channels?, bitsPerSample?, encoding?, compression?, mode?, raw, _extras }` | `/Sound` stream payload. |
+| `typeMovieAnnot` | `(dict) => MovieAnnot` | `{ subtype: 'Movie', movie, title?, activation?, raw, _extras }`. |
+| `typeScreenAnnot` | `(dict) => ScreenAnnot` | `{ subtype: 'Screen', title?, mk?, action?, additionalActions?, page?, raw, _extras }`. |
+| `SOUND_MODES` | `Set` | `Mono`, `Stereo`. |
+| `MOVIE_OP_MODES` | `Set` | `Once`, `Open`, `Repeat`, `Palindrome`. |
+
+## Examples
+
+### Sound
+
+```js
+const ext = runtime.resolve('pdfLegacyDeprecatedAnnots');
+const s = ext.typeSoundAnnot(annot);
+s.sound;      // stream ref
+s.iconName;   // 'Speaker'
+```
+
+### Movie
+
+```js
+const m = ext.typeMovieAnnot(annot);
+m.activation.mode;  // 'Once' (when /A is a dict with /Mode)
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/legacy-annot/not-dict` | `ParseError` | Argument is not a dictionary. |
+| `pdf/legacy-annot/bad-subtype` | `ParseError` | Subtype is not Sound/Movie/Screen. |
+| `pdf/legacy-annot/sound-missing` | `ParseError` | `/Sound` absent. |
+| `pdf/legacy-annot/sound-bad-stream` | `ParseError` | `/Sound` is not a stream or ref. |
+| `pdf/legacy-annot/sound-bad-name` | `ParseError` | `/Name` is not a name. |
+| `pdf/legacy-annot/sound-stream` | `ParseError` | Sound payload is not a stream. |
+| `pdf/legacy-annot/sound-bad-R` | `ParseError` | `/R` is not numeric. |
+| `pdf/legacy-annot/sound-bad-C` | `ParseError` | `/C` is not numeric. |
+| `pdf/legacy-annot/sound-bad-B` | `ParseError` | `/B` is not numeric. |
+| `pdf/legacy-annot/sound-bad-E` | `ParseError` | `/E` is not a name. |
+| `pdf/legacy-annot/sound-bad-CO` | `ParseError` | `/CO` is not a name. |
+| `pdf/legacy-annot/sound-bad-mode` | `ParseError` | Mode outside `SOUND_MODES`. |
+| `pdf/legacy-annot/movie-missing` | `ParseError` | `/Movie` absent. |
+| `pdf/legacy-annot/movie-bad` | `ParseError` | `/Movie` is not a dict. |
+| `pdf/legacy-annot/movie-bad-T` | `ParseError` | `/T` is not a string. |
+| `pdf/legacy-annot/movie-bad-A` | `ParseError` | `/A` is neither bool nor dict. |
+| `pdf/legacy-annot/movie-bad-mode` | `ParseError` | Mode outside `MOVIE_OP_MODES`. |
+| `pdf/legacy-annot/screen-bad-T` | `ParseError` | `/T` is not a string. |
+| `pdf/legacy-annot/screen-bad-MK` | `ParseError` | `/MK` is not a dict. |
+| `pdf/legacy-annot/screen-bad-A` | `ParseError` | `/A` is not a dict. |
+| `pdf/legacy-annot/screen-bad-AA` | `ParseError` | `/AA` is not a dict. |
+| `pdf/legacy-annot/screen-bad-P` | `ParseError` | `/P` is neither ref nor dict. |
+
+## See also
+
+- [`pdfAnnot`](../annot/annot.md)
+- [`pdf3dRichMedia`](./3d-richmedia.md)
+- [Extras index](./README.md)

package/docs/api/extra/legacy-deprecated-filters.md

@@ -0,0 +1,78 @@
+---
+module: pdfLegacyDeprecatedFilters
+category: pdf/extra
+dependencies: [pdfErrors, lzw, pdfCcittFaxDecoder]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLegacyDeprecatedFilters
+
+> LZWDecode (via fw) + CCITTFax (via `pdfCcittFaxDecoder`) + DCT/JPX passthrough — legacy.
+
+**Module** `pdfLegacyDeprecatedFilters` | **Source** `packages/front/office/pdf/src/extra/legacy-deprecated-filters.js` | **Deps** `pdfErrors`, `lzw` (fw binding), `pdfCcittFaxDecoder` | **Worker-safe** yes
+
+Read side of three legacy filters. LZWDecode = wrapper over `@awacloud/fw/io/compress/lzw` (TIFF profile, MSB-first, 8-bit min, CLEAR/END), supports `/EarlyChange`. CCITTFaxDecode validates the `DecodeParms` shape and then delegates the actual Group 3/Group 4 decode to the [`pdfCcittFaxDecoder`](./ccitt-fax-decoder.md) dependency — this module is a thin, validated pass-through, not a decoder itself. DCTDecode/JPXDecode are signature-checked passthroughs (JPEG/JPX bytes returned unchanged).
+
+## Resolve
+
+```js
+const ext = runtime.resolve('pdfLegacyDeprecatedFilters');
+// Returns: { lzwDecode, lzwEncode, validateCcittParms, ccittFaxDecode,
+//   dctDecode, jpxDecode, CCITT_KEYS }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `lzwDecode` | `(bytes, decodeParms?) => Uint8Array` | TIFF-profile LZW decode. |
+| `lzwEncode` | `(bytes) => Uint8Array` | TIFF-profile LZW encode. |
+| `validateCcittParms` | `(parms) => NormalizedParms` | Validates and normalizes the CCITT `DecodeParms` shape. |
+| `ccittFaxDecode` | `(bytes, decodeParms) => Uint8Array` | Validates parms then calls `pdfCcittFaxDecoder.decode(bytes, parms)`. |
+| `dctDecode` | `(bytes) => Uint8Array` | Checks the JPEG SOI marker, then passthrough. |
+| `jpxDecode` | `(bytes) => Uint8Array` | Checks the JP2/codestream signature, then passthrough. |
+| `CCITT_KEYS` | `Set` | Accepted CCITT `DecodeParms` keys (`K`, `EndOfLine`, `EncodedByteAlign`, `Columns`, `Rows`, `EndOfBlock`, `BlackIs1`, `DamagedRowsBeforeError`). |
+
+## Examples
+
+### LZW decode
+
+```js
+const ext = runtime.resolve('pdfLegacyDeprecatedFilters');
+const plain = ext.lzwDecode(streamBytes, { EarlyChange: 1 });
+```
+
+### CCITT parms validation + decode
+
+```js
+const p = ext.validateCcittParms({ K: -1, Columns: 1728, Rows: 100 });
+p.K;        // -1 (Group 4)
+p.Columns;  // 1728
+
+const image = ext.ccittFaxDecode(streamBytes, { K: -1, Columns: 1728, Rows: 100 });
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/filters/missing-lzw` | `ParseError` | The `lzw` fw dependency has no `decode`/`encode`. |
+| `pdf/filters/missing-ccitt` | `ParseError` | The `pdfCcittFaxDecoder` dependency has no `decode`. |
+| `pdf/filters/bad-input` | `ParseError` | bytes is not a Uint8Array. |
+| `pdf/lzw/bad-earlychange` | `ParseError` | `/EarlyChange` is not 0 or 1. |
+| `pdf/lzw/decode-failed` | `ParseError` | The fw decode threw. |
+| `pdf/lzw/encode-failed` | `ParseError` | The fw encode threw. |
+| `pdf/ccitt/bad-parms` | `ParseError` | parms is not an object. |
+| `pdf/ccitt/unknown-parm` | `ParseError` | A key outside `CCITT_KEYS`. |
+| `pdf/dct/bad-soi` | `ParseError` | JPEG SOI marker absent. |
+| `pdf/jpx/bad-signature` | `ParseError` | Not a recognized JPEG 2000 codestream or JP2 box stream. |
+
+Actual T.4/T.6 decode failures (truncation, unrecognized codes) surface through `pdfCcittFaxDecoder`'s own error codes (see that page) — this module does not wrap or rename them.
+
+## See also
+
+- [`pdfCcittFaxDecoder`](./ccitt-fax-decoder.md)
+- [`pdfFilters`](../syntax/filters/README.md)
+- [Extras index](./README.md)