@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/syntax/crossRefStream.md

@@ -0,0 +1,115 @@
+---
+module: pdfCrossRefStream
+category: pdf/syntax
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfCrossRefStream
+
+> Cross-reference stream parser `/Type /XRef` — ISO 32000-2 §7.5.8.
+
+**Module** `pdfCrossRefStream` | **Source** `packages/front/office/pdf/src/syntax/crossRefStream.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+An xref stream replaces the classical `xref` + `trailer` pair (PDF 1.5+). Its
+dictionary carries `/Size`, `/W` (3-tuple of field widths in bytes), optionally
+`/Index` (pairs `[first count …]`, default `[0 Size]`) and `/Prev`, plus every
+trailer entry (`/Root`, `/Info`, `/Encrypt`, `/ID`). The payload encodes one
+record per entry: three big-endian fields of the `/W` widths:
+
+| type | f2 | f3 |
+|------|----|----|
+| 0 | offset of the next free object | gen |
+| 1 | byte offset | gen |
+| 2 | number of the containing ObjStm | index inside that ObjStm |
+
+A zero width means "default value" (default type = 1). The payload must already
+be decoded: [`pdfDocument`](../document/document.md) composes this module and
+runs the stream through [`pdfFilterDispatch`](./filters/dispatch.md) first, so
+reading a 1.5+ file needs no explicit call. Callers driving the parser on its
+own decode `/Filter` themselves.
+
+## Resolve
+
+```js
+const xrefStm = runtime.resolve('pdfCrossRefStream');
+// Returns: { parseCrossRefStream }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `parseCrossRefStream` | `(decoded: Uint8Array, dict: PdfDict) => { entries, size, trailer }` | Xref table plus trailer. |
+
+### Return shape
+
+```js
+{
+    entries: {
+        [num]: {
+            type: 0 | 1 | 2,
+            offset: number,        // type 1 only — 0 otherwise
+            gen: number,           // type 0/1
+            free: boolean,
+            objStm?: number,       // type 2
+            index?: number         // type 2
+        }
+    },
+    size: number,                  // /Size, or the entry count
+    trailer: PdfDict               // the dictionary itself (carries /Root /Info …)
+}
+```
+
+## Examples
+
+### Parse an xref-stream section
+
+```js
+const xrefStm = runtime.resolve('pdfCrossRefStream');
+const decoded = filterDispatch.decode(streamObj);
+const { entries, size, trailer } = xrefStm.parseCrossRefStream(decoded, streamObj.dict);
+console.log(size, Object.keys(entries).length);
+```
+
+### Resolve a compressed object
+
+```js
+const e = entries[12];
+if (e.type === 2) {
+    const objStmRef = { type: 'ref', num: e.objStm, gen: 0 };
+    // → fetch the streamObj at objStmRef, decode, parseObjectStream,
+    //   then pick the member at e.index.
+}
+```
+
+### Non-trivial `/Index`
+
+```js
+// dict.entries.Index = array([int(0), int(1), int(10), int(3)])
+// → 4 entries in total: num 0, then num 10..12.
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/xrefstm/bad-input` | `ParseError` | `decoded` is not a `Uint8Array`. |
+| `pdf/xrefstm/bad-dict` | `ParseError` | `dict` is not a typed dictionary. |
+| `pdf/xrefstm/wrong-type` | `ParseError` | `/Type` missing or not `/XRef`. |
+| `pdf/xrefstm/bad-W` | `ParseError` | `/W` not an array, or not 3 entries. |
+| `pdf/xrefstm/bad-W-entry` | `ParseError` | A `/W` entry is not a non-negative int. |
+| `pdf/xrefstm/bad-W-zero` | `ParseError` | The `/W` widths sum to 0. |
+| `pdf/xrefstm/bad-Index` | `ParseError` | `/Index` not an array, or odd length. |
+| `pdf/xrefstm/bad-Index-entry` | `ParseError` | A `/Index` entry is not an int. |
+| `pdf/xrefstm/missing-int` | `ParseError` | `/Size` required and missing. |
+| `pdf/xrefstm/truncated` | `ParseError` | Payload too short for the announced entry count. |
+
+## See also
+
+- [`pdfXref`](./xref.md) — classical table §7.5.4.
+- [`pdfObjStream`](./objStream.md) — resolves type-2 entries.
+- [`pdfTrailer`](./trailer.md) — typing of the trailer dictionary.
+- [`pdfDocument`](../document/document.md) — composes this parser in the section walk.

package/docs/api/syntax/filters/README.md

@@ -0,0 +1,50 @@
+# Filters — ISO 32000-2 §7.4
+
+The `/Filter` + `/DecodeParms` chain on streams. Every filter exposes
+`{ decode, encode }`.
+
+| Module | PDF filter | Abbrev. | Spec | Deps |
+|--------|------------|---------|------|------|
+| [`pdfFlate`](./flate.md) | `FlateDecode` | `Fl` | §7.4.4 | `pdfErrors`, `zlib` (`@awacloud/fw`) |
+| [`pdfAsciiHex`](./asciiHex.md) | `ASCIIHexDecode` | `AHx` | §7.4.2 | `pdfErrors` |
+| [`pdfAscii85`](./ascii85.md) | `ASCII85Decode` | `A85` | §7.4.3 | `pdfErrors` |
+| [`pdfRunLength`](./runLength.md) | `RunLengthDecode` | `RL` | §7.4.5 | `pdfErrors` |
+| [`pdfFilterDispatch`](./dispatch.md) | orchestrator | — | §7.4 | `pdfErrors` + the four above |
+
+## Coverage (decode / encode)
+
+The table below describes the `decoders` map that `pdfFilterDispatch` ships out
+of the box.
+
+| Filter | decode | encode | Notes |
+|--------|--------|--------|-------|
+| `FlateDecode` | yes | yes | `/Predictor` 1, 2 and 10–15 supported in both directions. |
+| `ASCIIHexDecode` | yes | yes | Encodes uppercase, wraps every 32 bytes. |
+| `ASCII85Decode` | yes | yes | Handles `z` and `~>`. |
+| `RunLengthDecode` | yes | yes | Greedy encoder. |
+| `DCTDecode` | passthrough | passthrough | The PDF stores the raw JPEG bytes. |
+| `JPXDecode` | passthrough | passthrough | Raw JPEG 2000. |
+| `Crypt` | passthrough | passthrough | Real handling lives in the [crypto layer](../../crypto/README.md). |
+| `LZWDecode` | not registered | — | An implementation exists on the [`pdfLegacyDeprecatedFilters`](../../extra/legacy-deprecated-filters.md) extra (`lzwDecode`/`lzwEncode`, over `@awacloud/fw/io/compress/lzw`). |
+| `CCITTFaxDecode` | not registered | — | Implementations exist on `pdfCcittFaxDecoder` and on `pdfLegacyDeprecatedFilters` (`ccittFaxDecode`). |
+| `JBIG2Decode` | not registered | — | Header-only support on the [`pdfJbig2Read`](../../extra/jbig2-read.md) extra. |
+
+No extra auto-registers itself into the dispatch map: wire the ones you need
+with `dispatch.register(name, impl)` — see [`pdfFilterDispatch`](./dispatch.md).
+
+`Fl`, `AHx`, `A85`, `RL`, `LZW`, `DCT`, `JPX` and `CCF` are recognised as
+abbreviations and expanded to the full filter name before dispatch — so an
+unregistered `LZW` raises `pdf/filter/unsupported` under the name `LZWDecode`.
+
+## Common pattern
+
+```js
+const dispatch = runtime.resolve('pdfFilterDispatch');
+const decoded = dispatch.decode(streamObj);
+```
+
+## See also
+
+- [Syntax layer](../README.md)
+- [`pdfObjStream`](../objStream.md) — decoding is mandatory before parsing.
+- [`pdfCrossRefStream`](../crossRefStream.md) — likewise.

package/docs/api/syntax/filters/ascii85.md

@@ -0,0 +1,76 @@
+---
+module: pdfAscii85
+category: pdf/syntax/filters
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAscii85
+
+> `ASCII85Decode` ISO 32000-2 §7.4.3 — base 85, 5 chars ↔ 4 bytes.
+
+**Module** `pdfAscii85` | **Source** `packages/front/office/pdf/src/syntax/filters/ascii85.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Five ASCII characters in the `!`..`u` range decode to 4 binary bytes,
+interpreted as a big-endian 32-bit integer in base 85. The special character `z`
+stands for 4 zero bytes and may appear only at a group boundary. The stream is
+terminated by `~>`. The final group may be 2..4 characters, decoding to 1..3
+trailing bytes (padded with `u` = 84, keeping `count - 1` bytes). Whitespace is
+ignored.
+
+## Resolve
+
+```js
+const a85 = runtime.resolve('pdfAscii85');
+// Returns: { decode, encode }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `decode` | `(bytes: Uint8Array) => Uint8Array` | Binary bytes. |
+| `encode` | `(bytes: Uint8Array) => Uint8Array` | ASCII85 plus the `~>` EOD. |
+
+## Examples
+
+### Decode
+
+```js
+const a85 = runtime.resolve('pdfAscii85');
+const src = new TextEncoder().encode('87cURD]j~>');
+const out = a85.decode(src);
+new TextDecoder().decode(out);   // 'Hello'
+```
+
+### Zero group (`z`)
+
+```js
+a85.decode(new TextEncoder().encode('z~>'));   // [0,0,0,0]
+```
+
+### Round trip with a tail
+
+```js
+const bin = new Uint8Array([1, 2, 3]);         // 3 bytes → 4 chars + ~>
+const enc = a85.encode(bin);
+const back = a85.decode(enc);
+// back equals bin.
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/ascii85/bad-input` | `ParseError` | Argument is not a `Uint8Array`. |
+| `pdf/ascii85/bad-eod` | `ParseError` | `~` not followed by `>`. |
+| `pdf/ascii85/bad-z` | `ParseError` | `z` inside a group (`count !== 0`). |
+| `pdf/ascii85/bad-digit` | `ParseError` | Character outside `!`..`u`, not whitespace, not `z`/`~`. |
+
+## See also
+
+- [`pdfAsciiHex`](./asciiHex.md) — simpler alternative, 2 chars per byte.
+- [`pdfFilterDispatch`](./dispatch.md)
+- [Filters index](./README.md)

package/docs/api/syntax/filters/asciiHex.md

@@ -0,0 +1,73 @@
+---
+module: pdfAsciiHex
+category: pdf/syntax/filters
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfAsciiHex
+
+> `ASCIIHexDecode` ISO 32000-2 §7.4.2 — pairs of hex digits → bytes.
+
+**Module** `pdfAsciiHex` | **Source** `packages/front/office/pdf/src/syntax/filters/asciiHex.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Each ASCII hex pair decodes to one byte. Whitespace (`SP`, `HT`, `LF`, `CR`,
+`FF`, `NUL`) is ignored. The `>` terminator stops the stream. An odd number of
+digits is treated as if a trailing `0` were present (spec §7.4.2). Mixed case is
+tolerated on decode; the encoder emits uppercase hex with a line break every 32
+bytes and a final `>`.
+
+## Resolve
+
+```js
+const ahx = runtime.resolve('pdfAsciiHex');
+// Returns: { decode, encode }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `decode` | `(bytes: Uint8Array) => Uint8Array` | Binary bytes. |
+| `encode` | `(bytes: Uint8Array) => Uint8Array` | ASCII hex plus the `>` EOD. |
+
+## Examples
+
+### Decode
+
+```js
+const ahx = runtime.resolve('pdfAsciiHex');
+const src = new TextEncoder().encode('48 65 6C 6C 6F>');
+const out = ahx.decode(src);
+new TextDecoder().decode(out);   // 'Hello'
+```
+
+### Trailing odd digit (implicit `0`)
+
+```js
+ahx.decode(new TextEncoder().encode('A>'));   // [0xA0]
+```
+
+### Encode round trip
+
+```js
+const bin = new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]);
+const enc = ahx.encode(bin);                  // 'DEADBEEF>'
+const back = ahx.decode(enc);
+// back equals bin.
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/asciiHex/bad-input` | `ParseError` | Argument is not a `Uint8Array`. |
+| `pdf/asciiHex/bad-digit` | `ParseError` | Byte outside `0-9`, `A-F`, `a-f`, whitespace, or `>`. |
+
+## See also
+
+- [`pdfAscii85`](./ascii85.md) — denser 5-for-4 encoding.
+- [`pdfFilterDispatch`](./dispatch.md)
+- [Filters index](./README.md)

package/docs/api/syntax/filters/dispatch.md

@@ -0,0 +1,125 @@
+---
+module: pdfFilterDispatch
+category: pdf/syntax/filters
+dependencies: [pdfErrors, pdfFlate, pdfAsciiHex, pdfAscii85, pdfRunLength]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFilterDispatch
+
+> The `/Filter` + `/DecodeParms` chain — ISO 32000-2 §7.4.
+
+**Module** `pdfFilterDispatch` | **Source** `packages/front/office/pdf/src/syntax/filters/dispatch.js` | **Deps** `pdfErrors`, `pdfFlate`, `pdfAsciiHex`, `pdfAscii85`, `pdfRunLength` | **Worker-safe** yes
+
+Reads `/Filter` (a name or an array of names) and applies the decoders **in
+order** — the first name is applied first, which is the spec convention and the
+reverse of the encoding order. Recognised PDF abbreviations: `Fl`, `AHx`, `A85`,
+`RL`, `LZW`, `DCT`, `JPX`, `CCF`. Opaque filters exposed as passthrough:
+`DCTDecode`, `JPXDecode`, `Crypt`. Any filter absent from `decoders` raises
+`pdf/filter/unsupported`.
+
+`decodeStream` marshals `/DecodeParms` from the typed AST form
+(`{type:'dict', entries:{K: {type, value}}}`) to a plain `key → value`
+object (reading `entry.value` per key) before handing it to a decoder —
+decoders such as `pdfFlate` read plain properties (`params.Predictor`,
+`params.Columns`, …), never typed nodes. The three `/DecodeParms` shapes
+are all handled: absent (→ `null` params for every filter), a single dict
+(→ applies to the first filter only, `null` for the rest, per spec), and
+an array parallel to `/Filter` (→ one marshalled dict per filter, `null`
+entries preserved).
+
+## Resolve
+
+```js
+const dispatch = runtime.resolve('pdfFilterDispatch');
+// Returns: { decode, decodeChain, encodeChain, register, names, decoders,
+//            normalizeFilterList, applyDecodeChain, applyEncodeChain,
+//            decodeStream }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `decode` | `(streamObj: PdfStream) => Uint8Array` | End-to-end decode from the typed stream, against the built-in `decoders`. |
+| `decodeChain` | `(bytes, filters: string[], params?: object[]) => Uint8Array` | Explicit decode against the built-in `decoders`. |
+| `encodeChain` | `(bytes, filters: string[], params?: object[]) => Uint8Array` | Explicit encode against the built-in `decoders`. |
+| `register` | `(name: string, impl: { decode, encode? }) => void` | Adds or replaces a decoder in `decoders`. |
+| `names` | `() => string[]` | Lists the currently registered filter names. |
+| `decoders` | `object` | The live map itself (escape hatch — mutating it is what `register` does). |
+| `normalizeFilterList` | `(filterEntry) => string[]` | Expands abbreviations and returns the canonical name list. Useful to inspect a chain without decoding. |
+| `applyDecodeChain` | `(bytes, filters, params, decoders) => Uint8Array` | Lower-level decode against a **caller-supplied** decoder map. |
+| `applyEncodeChain` | `(bytes, filters, params, decoders) => Uint8Array` | Lower-level encode against a caller-supplied decoder map. |
+| `decodeStream` | `(streamObj, decoders) => Uint8Array` | Lower-level `decode`: reads `/Filter` + `/DecodeParms` off the stream dictionary, then delegates to `applyDecodeChain`. |
+
+`decode`, `decodeChain` and `encodeChain` are thin bindings of the three
+lower-level helpers over the module's own `decoders` map; the `apply*`/
+`decodeStream` triple is exported so a caller can run a chain against an
+isolated map without mutating the shared one.
+
+## Examples
+
+### End-to-end decode
+
+```js
+const dispatch = runtime.resolve('pdfFilterDispatch');
+const decoded = dispatch.decode(streamObj);   // reads Filter + DecodeParms
+```
+
+### Explicit chain
+
+```js
+const out = dispatch.decodeChain(bytes, ['ASCII85Decode', 'FlateDecode']);
+// Applies ASCII85 then Flate (= array order).
+```
+
+### Register a custom decoder (LZW)
+
+```js
+const legacy = runtime.resolve('pdfLegacyDeprecatedFilters');
+dispatch.register('LZWDecode', {
+    decode: (bytes, params) => legacy.lzwDecode(bytes, params),
+    encode: (bytes) => legacy.lzwEncode(bytes)
+});
+```
+
+### Decode against an isolated map
+
+```js
+const isolated = { ...dispatch.decoders, DCTDecode: myJpegDecoder };
+const out = dispatch.decodeStream(streamObj, isolated);
+```
+
+### Inspect a chain without decoding
+
+```js
+dispatch.normalizeFilterList(streamObj.dict.entries.Filter);
+// ['ASCII85Decode', 'FlateDecode']
+```
+
+### List the available filters
+
+```js
+dispatch.names();
+// ['FlateDecode', 'ASCIIHexDecode', 'ASCII85Decode', 'RunLengthDecode',
+//  'DCTDecode', 'JPXDecode', 'Crypt']
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/filter/non-name` | `ParseError` | An entry of the `/Filter` array is not a name. |
+| `pdf/filter/bad-type` | `ParseError` | `/Filter` is neither a name nor an array. |
+| `pdf/filter/unsupported` | `ParseError` | Filter absent from `decoders`. |
+| `pdf/filter/no-encoder` | `ParseError` | `encodeChain` invoked for a filter with no `encode`. |
+| `pdf/filter/not-stream` | `ParseError` | `decode()`/`decodeStream()` given something other than a typed stream. |
+| `pdf/filter/bad-decodeparms` | `ParseError` | `/DecodeParms` is neither a dict, an array, nor null. |
+
+## See also
+
+- [Filters index](./README.md)
+- [`pdfFlate`](./flate.md), [`pdfAsciiHex`](./asciiHex.md), [`pdfAscii85`](./ascii85.md), [`pdfRunLength`](./runLength.md)
+- [`pdfObjStream`](../objStream.md), [`pdfCrossRefStream`](../crossRefStream.md) — consumers.

package/docs/api/syntax/filters/flate.md

@@ -0,0 +1,134 @@
+---
+module: pdfFlate
+category: pdf/syntax/filters
+dependencies: [pdfErrors, zlib]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFlate
+
+> `FlateDecode` ISO 32000-2 §7.4.4 — wrapper over `@awacloud/fw` zlib (RFC 1950), with predictors.
+
+**Module** `pdfFlate` | **Source** `packages/front/office/pdf/src/syntax/filters/flate.js` | **Deps** `pdfErrors`, `zlib` (`@awacloud/fw/io/compress/zlib`) | **Worker-safe** yes
+
+PDF `FlateDecode` is full zlib framing (CMF/FLG header + deflate payload +
+Adler32 trailer). The raw compression is delegated to `@awacloud/fw`'s `zlib` module,
+which produces and consumes exactly that format.
+
+**`/DecodeParms /Predictor` is handled here**, in both directions:
+
+| `Predictor` | Meaning |
+|-------------|---------|
+| `1` | None (default) |
+| `2` | TIFF Predictor 2 — requires `BitsPerComponent = 8` |
+| `10`–`14` | PNG None / Sub / Up / Average / Paeth, per row |
+| `15` | PNG optimum — the encoder picks per row; the decoder reads the tag byte either way |
+
+`Columns`, `Colors` and `BitsPerComponent` are read alongside `Predictor`
+(defaults `1`, `1`, `8`) and accepted in both the PDF spelling (`Predictor`,
+`Columns`, …) and the lowercase spelling (`predictor`, `columns`, …).
+
+## Resolve
+
+```js
+const flate = runtime.resolve('pdfFlate');
+// Returns: { decode, encode }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `decode` | `(bytes: Uint8Array, params?: object) => Uint8Array` | Inflated payload, un-predicted when `params` requests it; the decoded prefix, flagged `truncated`, for a stream that ends before its final block. |
+| `encode` | `(bytes: Uint8Array, params?: object) => Uint8Array` | Predicted (when requested) then zlib-deflated payload. |
+
+`params` is optional: omit it, or leave `Predictor` at `1`, and the byte stream
+is passed through the raw zlib codec untouched.
+
+## Truncated streams
+
+Some producers write `FlateDecode` streams whose deflate data ends before the
+final block — the input runs out mid-stream, though `/Length` is exact.
+Viewers display what decodes, and so does `decode`: when the strict inflate
+fails only because the input ended before the final block, the payload is
+decoded again through fw's streaming decoder (`UnzlibStream`, without the
+end-of-input signal) and the bytes decoded so far are returned.
+
+- The returned `Uint8Array` carries a **non-enumerable** own property
+  `truncated: true`. It is invisible to `Object.keys`, spread and deep
+  equality, so callers that ignore it see an ordinary byte array; callers
+  that care test `out.truncated === true`. A complete stream never carries it.
+- With a `Predictor`, only the **whole** predicted rows of the prefix are
+  decoded (a trailing partial row is dropped), so a truncated image or xref
+  stream does not fail with `pdf/flate/png-row-mismatch`. A complete stream
+  keeps the strict row check.
+- The streaming decoder holds back the last 4 input bytes as a presumed
+  Adler-32 trailer, so the recovered prefix can stop a few bytes short of
+  everything the input encodes.
+
+Everything else still throws `pdf/flate/inflate-failed`: a bad zlib header,
+an invalid block type, length or distance, a stream truncated inside its
+header, and a truncated stream from which nothing could be decoded. The
+error's `cause` is the original strict-inflate error.
+
+```js
+const out = flate.decode(streamObj.raw);
+if (out.truncated) {
+    // a decoded prefix — the stream ended before its final deflate block
+}
+```
+
+## Examples
+
+### Decode a Flate stream
+
+```js
+const flate = runtime.resolve('pdfFlate');
+const decoded = flate.decode(streamObj.raw);
+```
+
+### Decode with a PNG predictor
+
+```js
+const decoded = flate.decode(streamObj.raw, {
+    Predictor: 12, Columns: 5, Colors: 1, BitsPerComponent: 8
+});
+```
+
+### Round trip
+
+```js
+const enc = new TextEncoder().encode('hello, pdf');
+const compressed = flate.encode(enc);
+const back = flate.decode(compressed);
+new TextDecoder().decode(back);   // 'hello, pdf'
+```
+
+### Through the dispatch
+
+```js
+const dispatch = runtime.resolve('pdfFilterDispatch');
+const out = dispatch.decode(streamObj);  // resolves /Filter and /DecodeParms
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/flate/missing-fw` | `ParseError` | Factory invoked without the `@awacloud/fw` zlib module (no `zlibSync`/`unzlibSync`). |
+| `pdf/flate/bad-input` | `ParseError` | Argument is not a `Uint8Array`. |
+| `pdf/flate/inflate-failed` | `ParseError` | `unzlibSync` threw — corrupt or non-zlib payload, or a truncated stream from which nothing could be decoded (see [Truncated streams](#truncated-streams)). `cause` is the original error. |
+| `pdf/flate/deflate-failed` | `ParseError` | `zlibSync` threw. |
+| `pdf/flate/bad-predictor` | `ParseError` | `Predictor` outside `{1, 2, 10..15}`. |
+| `pdf/flate/bad-predictor-params` | `ParseError` | `Columns`, `Colors` or `BitsPerComponent` ≤ 0. |
+| `pdf/flate/bad-png-filter` | `ParseError` | Row tag byte outside `0..4`. |
+| `pdf/flate/tiff-bpc-unsupported` | `ParseError` | TIFF Predictor 2 with `BitsPerComponent ≠ 8`. |
+| `pdf/flate/png-row-mismatch` | `ParseError` | Payload length of a complete stream not a whole number of predicted rows. |
+
+## See also
+
+- [`pdfFilterDispatch`](./dispatch.md) — filter orchestrator.
+- [Filters index](./README.md)
+- [`pdfObjStream`](../objStream.md) — typical consumer (ObjStm streams are almost always Flate-encoded).

package/docs/api/syntax/filters/runLength.md

@@ -0,0 +1,78 @@
+---
+module: pdfRunLength
+category: pdf/syntax/filters
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfRunLength
+
+> `RunLengthDecode` ISO 32000-2 §7.4.5 — run-length coding.
+
+**Module** `pdfRunLength` | **Source** `packages/front/office/pdf/src/syntax/filters/runLength.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Each control byte `n` is read as:
+
+- `0..127` → copy the next `n + 1` bytes literally (1..128 bytes);
+- `128` → end of data (EOD), decoding stops;
+- `129..255` → repeat the next byte `257 - n` times (2..128 repetitions).
+
+The encoder is greedy: it first tries a repeat run when 3 or more identical
+bytes are available, otherwise it accumulates up to 128 literal bytes, stopping
+just before a productive run.
+
+## Resolve
+
+```js
+const rl = runtime.resolve('pdfRunLength');
+// Returns: { decode, encode }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `decode` | `(bytes: Uint8Array) => Uint8Array` | Expanded bytes. |
+| `encode` | `(bytes: Uint8Array) => Uint8Array` | Encoded bytes plus the EOD (`128`). |
+
+## Examples
+
+### Decode a repeat run
+
+```js
+const rl = runtime.resolve('pdfRunLength');
+// 0xFB = 251 → repeat the next byte (257-251 = 6) times; 128 = EOD
+const src = new Uint8Array([0xFB, 0x41, 0x80]);
+rl.decode(src);   // [0x41, 0x41, 0x41, 0x41, 0x41, 0x41]  ('AAAAAA')
+```
+
+### Decode a literal run
+
+```js
+// 0x02 → copy (2+1=3) literal bytes
+rl.decode(new Uint8Array([0x02, 0x48, 0x69, 0x21, 0x80]));   // 'Hi!'
+```
+
+### Round trip
+
+```js
+const bin = new Uint8Array([1, 1, 1, 1, 1, 2, 3, 4]);
+const enc = rl.encode(bin);
+const back = rl.decode(enc);
+// back equals bin.
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/runLength/bad-input` | `ParseError` | Argument is not a `Uint8Array`. |
+| `pdf/runLength/truncated-literal` | `ParseError` | Literal run announced but the payload is truncated. |
+| `pdf/runLength/truncated-repeat` | `ParseError` | Repeat run announced but no value byte follows. |
+
+## See also
+
+- [`pdfFilterDispatch`](./dispatch.md)
+- [Filters index](./README.md)