@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/syntax/objStream.md

@@ -0,0 +1,88 @@
+---
+module: pdfObjStream
+category: pdf/syntax
+dependencies: [pdfErrors, pdfParserObj, pdfTokenizer, pdfParser]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfObjStream
+
+> Object-stream parser `/Type /ObjStm` — ISO 32000-2 §7.5.7.
+
+**Module** `pdfObjStream` | **Source** `packages/front/office/pdf/src/syntax/objStream.js` | **Deps** `pdfErrors`, `pdfParserObj`, `pdfTokenizer`, `pdfParser` | **Worker-safe** yes
+
+An object stream is a compressed container holding several non-stream indirect
+objects. Its dictionary carries `/N` (object count), `/First` (offset of the
+first body inside the decoded payload) and, optionally, `/Extends`. The payload
+starts with `N` pairs `<num> <byteOffset>` (offsets relative to `/First`),
+followed by the bodies concatenated without `obj`/`endobj`. The generation is
+always `0` by spec §7.5.8.4 (compressed objects). The payload must already be
+decoded: [`pdfDocument`](../document/document.md) composes this module and runs
+the container through [`pdfFilterDispatch`](./filters/dispatch.md) — once per
+container per document — so `doc._raw.resolve(ref)` returns a compressed object
+like any other indirect. Callers driving the parser on its own apply `/Filter`
+(typically Flate) themselves.
+
+## Resolve
+
+```js
+const objStm = runtime.resolve('pdfObjStream');
+// Returns: { parseObjectStream }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `parseObjectStream` | `(decoded: Uint8Array, dict: PdfDict) => Array<{num, gen:0, value}>` | Every member object. |
+
+### `parseObjectStream`
+
+1. Validates `/Type /ObjStm` when present.
+2. Reads `/N` and `/First` (required, integers ≥ 0).
+3. Tokenises `[0, First[` to recover the `(num, offset)` pairs.
+4. Slices each body `[First+off[i], First+off[i+1][` (or to the end for the
+   last one) and feeds it to the standard `parseObject`.
+
+Out-of-order or out-of-payload offsets raise `pdf/objstm/bad-offset`.
+
+## Examples
+
+### Parse a freshly inflated ObjStm
+
+```js
+const objStm = runtime.resolve('pdfObjStream');
+const dict = streamObj.dict;             // { type: 'dict', entries: { Type, N, First, … } }
+const decoded = filterDispatch.decode(streamObj);
+const members = objStm.parseObjectStream(decoded, dict);
+// → [{ num: 5, gen: 0, value: { type: 'dict', entries: { Type: …, Count: … } } }, …]
+```
+
+### Feed the members back into a resolver
+
+```js
+for (const { num, value } of members) {
+    indirects.set(`${num}:0`, { value, offset: -1 });   // -1 → "compressed"
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/objstm/bad-input` | `ParseError` | `decoded` is not a `Uint8Array`. |
+| `pdf/objstm/bad-dict` | `ParseError` | `dict` is not a typed dictionary. |
+| `pdf/objstm/wrong-type` | `ParseError` | `/Type` present but not `/ObjStm`. |
+| `pdf/objstm/missing-int` | `ParseError` | `/N` or `/First` missing or not an int. |
+| `pdf/objstm/bad-N` | `ParseError` | `/N` negative. |
+| `pdf/objstm/bad-First` | `ParseError` | `/First` outside the payload range. |
+| `pdf/objstm/bad-pair` | `ParseError` | Malformed `(num, off)` header pair. |
+| `pdf/objstm/bad-offset` | `ParseError` | Member offset out of range. |
+
+## See also
+
+- [`pdfCrossRefStream`](./crossRefStream.md) — points at ObjStm members (type 2).
+- [`pdfParser`](./parser.md) — consumed for each body.
+- [`pdfFilterDispatch`](./filters/dispatch.md) — mandatory `/Filter` decode beforehand.

package/docs/api/syntax/parser-obj.md

@@ -0,0 +1,97 @@
+---
+module: pdfParserObj
+category: pdf/syntax
+dependencies: []
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfParserObj
+
+> Typed constructors and reflection helpers for PDF objects — split out of `parser.js`.
+
+**Module** `pdfParserObj` | **Source** `packages/front/office/pdf/src/syntax/parser-obj.js` | **Deps** none | **Worker-safe** yes
+
+Companion file to [`parser.js`](./parser.md), extracted to keep the orchestrator
+under 300 LOC. The factory declares no dependencies and returns three members:
+
+- `obj` — the constructor factory (`obj.nul`, `obj.bool`, `obj.int`, `obj.real`,
+  `obj.name`, `obj.string`, `obj.array`, `obj.dict`, `obj.ref`, `obj.stream`).
+- `getEntry(dict, key)` — safe `dict.entries[key]` access, `undefined` when
+  `dict` is not a typed dictionary.
+- `isType(v, kind)` — discriminant test `v && v.type === kind`.
+
+Every builder is **pure** and always returns a fresh object — no cache, no pool.
+`pdfParser` re-exposes all three members for convenience.
+
+## Resolve
+
+```js
+const po = runtime.resolve('pdfParserObj');
+// Returns: { obj, getEntry, isType }
+```
+
+`@awacloud/pdf` re-exports module *descriptors* only (`pdfParserObj`), never resolved
+instances — always go through `runtime.resolve`.
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `obj.nul` | `() => object` | `{ type: 'null' }` |
+| `obj.bool` | `(v: any) => object` | `{ type: 'bool', value: !!v }` |
+| `obj.int` | `(v: number) => object` | `{ type: 'int', value: v\|0 }` |
+| `obj.real` | `(v: number) => object` | `{ type: 'real', value: +v }` |
+| `obj.name` | `(s: string) => object` | `{ type: 'name', value: String(s) }` |
+| `obj.string` | `(bytes: Uint8Array, syntax?: 'lit'\|'hex') => object` | `{ type: 'string', value, syntax }` |
+| `obj.array` | `(items?: object[]) => object` | `{ type: 'array', items }` |
+| `obj.dict` | `(entries?: object) => object` | `{ type: 'dict', entries }` |
+| `obj.ref` | `(num: number, gen?: number) => object` | `{ type: 'ref', num, gen }` |
+| `obj.stream` | `(dict: object, raw: Uint8Array) => object` | `{ type: 'stream', dict, raw }` |
+| `getEntry` | `(dict, key: string) => object\|undefined` | value or `undefined` |
+| `isType` | `(v, kind: string) => boolean` | `v?.type === kind` |
+
+## Examples
+
+### Build a literal Catalog
+
+```js
+const { obj } = runtime.resolve('pdfParserObj');
+
+const catalog = obj.dict({
+    Type:    obj.name('Catalog'),
+    Pages:   obj.ref(2, 0),
+    Version: obj.name('2.0')
+});
+```
+
+### Build a stream
+
+```js
+const { obj } = runtime.resolve('pdfParserObj');
+const data = new TextEncoder().encode('BT /F1 12 Tf (Hi) Tj ET');
+const stream = obj.stream(
+    obj.dict({ Length: obj.int(data.length) }),
+    data
+);
+```
+
+### Typed lookup
+
+```js
+const { getEntry, isType } = runtime.resolve('pdfParserObj');
+
+if (isType(catalog, 'dict')) {
+    const pages = getEntry(catalog, 'Pages');
+    if (isType(pages, 'ref')) console.log(pages.num);
+}
+```
+
+## Errors
+
+Pure builders and predicates — this module raises no `PdfError`.
+
+## See also
+
+- [`pdfParser`](./parser.md) — orchestrator that consumes these helpers

package/docs/api/syntax/parser.md

@@ -0,0 +1,151 @@
+---
+module: pdfParser
+category: pdf/syntax
+dependencies: [pdfErrors, pdfParserObj, pdfTokenizer]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfParser
+
+> Typed PDF objects, ISO 32000-2 §7.3 — token stream → `{ type, value/items/entries }` tree.
+
+**Module** `pdfParser` | **Source** `packages/front/office/pdf/src/syntax/parser.js` | **Deps** `pdfErrors`, `pdfParserObj`, `pdfTokenizer` | **Worker-safe** yes
+
+Produces the typed objects `null`, `bool`, `int`, `real`, `name`, `string`,
+`array`, `dict`, `ref`, `stream`. The `<int> <int> R` form is recognised
+speculatively as a `ref`. Indirect definitions `<num> <gen> obj … endobj` are
+read by `parseIndirect`, which promotes `dict + stream` into
+`{ type: 'stream', dict, raw }`. The parser validates neither xref integrity nor
+`/Length` — that is the document layer's job.
+
+The module re-exposes the injected `pdfTokenizer`'s `tokenize` and the whole
+`pdfParserObj` surface (`obj`, `getEntry`, `isType`) so a consumer needs a
+single resolve to go from bytes to a typed tree.
+
+## Resolve
+
+```js
+const parser = runtime.resolve('pdfParser');
+// Returns: { tokenize, parseObject, parseIndirect, parseFromBytes,
+//            parseIndirectFromBytes, parserLimits, setParserLimits,
+//            obj, getEntry, isType }
+```
+
+## API
+
+| Member | Signature | Returns |
+|--------|-----------|---------|
+| `tokenize` | `(bytes: Uint8Array, opts?) => Tokenizer` | Re-export of [`pdfTokenizer.tokenize`](./tokenizer.md). |
+| `parseObject` | `(tok: Tokenizer) => PdfObject` | One typed object. |
+| `parseIndirect` | `(tok: Tokenizer, resolveRef?) => { num, gen, value }` | Full indirect definition. |
+| `parseFromBytes` | `(bytes: Uint8Array) => PdfObject` | Helper — tokenize then `parseObject`. |
+| `parseIndirectFromBytes` | `(bytes: Uint8Array, at: number, resolveRef?) => { num, gen, value }` | Offset helper. |
+| `parserLimits` | `{ maxDepth, maxArrayLen, maxStreamBytes }` | Live, mutable per-instance guard-rails. |
+| `setParserLimits` | `(partial) => parserLimits` | Merges positive integer overrides and returns the updated object. |
+| `obj` | builders | Primitive constructors (see below). |
+| `getEntry` | `(dict, key: string) => PdfObject \| undefined` | Lookup on `{type:'dict'}`. |
+| `isType` | `(v, kind: string) => boolean` | Test `v.type === kind`. |
+
+### `parserLimits` defaults
+
+| Key | Default | Guards |
+|-----|---------|--------|
+| `maxDepth` | `200` | Nesting depth — `pdf/parser/depth-exceeded`. |
+| `maxArrayLen` | `1_000_000` | Array element count — `pdf/parser/array-too-long`. |
+| `maxStreamBytes` | `268_435_456` (256 MiB) | Stream payload quota during `parseIndirect`. |
+
+Only positive integers are accepted; anything else is ignored, so
+`setParserLimits({})` is a no-op that simply returns the current limits.
+
+### `obj` builders
+
+| Helper | Signature |
+|--------|-----------|
+| `obj.nul()` | `→ { type: 'null' }` |
+| `obj.bool(v)` | `→ { type: 'bool', value }` |
+| `obj.int(v)` | `→ { type: 'int', value }` |
+| `obj.real(v)` | `→ { type: 'real', value }` |
+| `obj.name(s)` | `→ { type: 'name', value }` |
+| `obj.string(bytes, syntax?)` | `syntax ∈ 'lit'\|'hex'` |
+| `obj.array(items?)` | |
+| `obj.dict(entries?)` | |
+| `obj.ref(num, gen?)` | |
+| `obj.stream(dict, raw)` | |
+
+## Token → type mapping
+
+| Token | Output type |
+|-------|-------------|
+| `kw 'null'/'true'/'false'` | `null` / `bool` |
+| `name` | `name` |
+| `string` | `string` (`syntax:'lit'`) |
+| `hex` | `string` (`syntax:'hex'`) |
+| `int` + `int` + `kw 'R'` | `ref` |
+| `int` | `int` |
+| `real` | `real` |
+| `open_arr … close_arr` | `array` |
+| `open_dict … close_dict` | `dict` |
+| `dict` + `kw 'stream'` (via `parseIndirect`) | `stream` |
+
+## Examples
+
+### Parse a standalone object
+
+```js
+const parser = runtime.resolve('pdfParser');
+const o = parser.parseFromBytes(new TextEncoder().encode('<< /Size 6 /Root 1 0 R >>'));
+o.type;                            // 'dict'
+parser.getEntry(o, 'Size').value;  // 6
+parser.getEntry(o, 'Root');        // { type: 'ref', num: 1, gen: 0 }
+```
+
+### Read an indirect definition carrying a stream
+
+```js
+const tok = parser.tokenize(bytes, { start: offset });
+const def = parser.parseIndirect(tok, ref => doc._raw.resolve(ref));
+def.value.type;            // 'stream'
+def.value.raw;             // Uint8Array
+```
+
+### Tighten the limits for untrusted input
+
+```js
+parser.setParserLimits({ maxDepth: 32, maxStreamBytes: 8 * 1024 * 1024 });
+parser.parserLimits.maxDepth;   // 32
+```
+
+### Build with `obj`
+
+```js
+const o = parser.obj.dict({
+    Type: parser.obj.name('Catalog'),
+    Pages: parser.obj.ref(2, 0)
+});
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/parser/eof` | `ParseError` | End of stream during `parseObject`. |
+| `pdf/parser/unexpected-keyword` | `ParseError` | Unrecognised keyword in object position. |
+| `pdf/parser/unexpected-token` | `ParseError` | Foreign token (e.g. a lone `n`). |
+| `pdf/parser/unbalanced` | `ParseError` | `]` or `>>` without an opener. |
+| `pdf/parser/unterminated-array` | `ParseError` | `[` never closed. |
+| `pdf/parser/unterminated-dict` | `ParseError` | `<<` never closed. |
+| `pdf/parser/dict-key-not-name` | `ParseError` | Dictionary key is not a name. |
+| `pdf/parser/depth-exceeded` | `ParseError` | Nesting deeper than `parserLimits.maxDepth`. |
+| `pdf/parser/array-too-long` | `ParseError` | Array longer than `parserLimits.maxArrayLen`. |
+| `pdf/parser/indirect-bad-num` / `-bad-gen` / `-missing-obj` / `-missing-endobj` | `ParseError` | Malformed `<n> <g> obj … endobj`. |
+| `pdf/parser/stream/no-endstream` | `ParseError` | `endstream` not found. |
+| `pdf/parser/stream/expected-endstream` | `ParseError` | Something else found instead. |
+
+## See also
+
+- [`pdfTokenizer`](./tokenizer.md)
+- [`pdfParserObj`](./parser-obj.md)
+- [`pdfXref`](./xref.md) — uses `parseObject` for the trailer.
+- [`pdfErrors`](../errors.md)

package/docs/api/syntax/serializer.md

@@ -0,0 +1,109 @@
+---
+module: pdfSerializer
+category: pdf/syntax
+dependencies: [pdfErrors]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfSerializer
+
+> Typed PDF objects → `Uint8Array` — canonical emission, ISO 32000-2 §7.3.
+
+**Module** `pdfSerializer` | **Source** `packages/front/office/pdf/src/syntax/serializer.js` | **Deps** `pdfErrors` | **Worker-safe** yes
+
+Strict inverse of [`pdfParser`](./parser.md). Emits any typed object (`null`,
+`bool`, `int`, `real`, `name`, `string`, `array`, `dict`, `ref`) as bytes.
+`stream` objects are not emitted directly — go through `serializeIndirect`,
+which rewrites `/Length` to the exact raw byte count. `real` values follow
+§7.3.3 (fixed point, no exponent notation, trailing zeros stripped). `name`
+values are `#xx`-escaped for every delimiter, space, or byte outside `!`..`~`.
+`string` values automatically pick the literal `(…)` or hex `<…>` form based on
+the density of non-printable bytes, unless `syntax: 'hex'` is explicit.
+
+## Resolve
+
+```js
+const ser = runtime.resolve('pdfSerializer');
+// Returns: { serializeObject, serializeIndirect, formatReal }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `serializeObject` | `(obj: PdfObject) => Uint8Array` | Bytes of a standalone object. |
+| `serializeIndirect` | `(num: number, gen: number, body: PdfObject) => Uint8Array` | `<n> <g> obj … endobj\n`. |
+| `formatReal` | `(n: number) => string` | Canonical real per §7.3.3. |
+
+### `serializeIndirect`
+
+For a `stream` body, the dictionary is cloned with `/Length` forced to
+`body.raw.length`. The result follows
+`<n> <g> obj\n<<…>>\nstream\n<raw>\nendstream\nendobj\n`. Any other type is
+serialised inline between `obj` and `endobj`.
+
+## Examples
+
+### Emit a dictionary
+
+```js
+const ser = runtime.resolve('pdfSerializer');
+const dict = {
+    type: 'dict',
+    entries: {
+        Type: { type: 'name', value: 'Catalog' },
+        Pages: { type: 'ref', num: 2, gen: 0 }
+    }
+};
+const bytes = ser.serializeObject(dict);
+// → "<< /Type /Catalog /Pages 2 0 R >>"
+```
+
+### Emit an indirect definition
+
+```js
+const def = ser.serializeIndirect(1, 0, dict);
+// → "1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n"
+```
+
+### Emit a stream — `/Length` recomputed
+
+```js
+const raw = new TextEncoder().encode('BT /F1 12 Tf (Hi) Tj ET');
+const stream = {
+    type: 'stream',
+    dict: { type: 'dict', entries: {} },
+    raw
+};
+const bytes = ser.serializeIndirect(4, 0, stream);
+// `/Length` is raw.length, whatever the dict said.
+```
+
+### Canonical reals
+
+```js
+ser.formatReal(1.5);        // '1.5'
+ser.formatReal(2);          // '2'
+ser.formatReal(0.0500);     // '0.05'
+ser.formatReal(-0);         // '0'
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/serializer/bad-input` | `RenderError` | `serializeObject` given something other than a typed object. |
+| `pdf/serializer/bad-num` | `RenderError` | `num` not a non-negative integer. |
+| `pdf/serializer/bad-gen` | `RenderError` | `gen` not a non-negative integer. |
+| `pdf/serializer/bad-real` | `RenderError` | Non-finite real (`NaN`, `Infinity`). |
+| `pdf/serializer/bad-string` | `RenderError` | `string.value` is not a `Uint8Array`. |
+| `pdf/serializer/inline-stream` | `RenderError` | Attempt to serialise a `stream` through `serializeObject`. |
+| `pdf/serializer/unknown-type` | `RenderError` | Unrecognised `obj.type`. |
+
+## See also
+
+- [`pdfParser`](./parser.md) — inverse operation.
+- [`pdfWriter`](../document/writer.md) — main consumer.
+- [`pdfErrors`](../errors.md)

package/docs/api/syntax/tokenizer.md

@@ -0,0 +1,104 @@
+---
+module: pdfTokenizer
+category: pdf/syntax
+dependencies: [pdfErrors, pdfShared]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTokenizer
+
+> Binary lexer, ISO 32000-2 §7.2 — bytes → token stream.
+
+**Module** `pdfTokenizer` | **Source** `packages/front/office/pdf/src/syntax/tokenizer.js` | **Deps** `pdfErrors`, `pdfShared` | **Worker-safe** yes
+
+Emits `{ kind, value?, offset, end }` tokens for the PDF lexical conventions.
+The tokenizer is **stream-aware at the keyword level**: when it emits
+`{ kind: 'kw', value: 'stream' }`, the consumer skips the binary payload itself
+(using the preceding dictionary's `/Length`) and then resumes at `endstream`.
+
+## Resolve
+
+```js
+const tokMod = runtime.resolve('pdfTokenizer');
+// Returns: { tokenize, lastIndexOfBytes }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `tokenize` | `(bytes: Uint8Array, opts?: { keepWhitespace?, start?, end? }) => Tokenizer` | Iterator (`next`, `peek`, `pos`, `seek`, `bytes`). |
+| `lastIndexOfBytes` | `(bytes: Uint8Array, needle: Uint8Array, from?: number) => number` | Offset (or `-1`) of the last match. |
+
+### Token kinds
+
+| `kind` | Payload |
+|--------|---------|
+| `ws` | whitespace run (only when `keepWhitespace`) |
+| `comment` | comment body (bytes between `%` and EOL) |
+| `name` | `value: string` (`#xx` escapes decoded) |
+| `int` / `real` | `value: number`, `raw: string` |
+| `string` | `value: Uint8Array` — literal `(...)` form only |
+| `hex` | `value: Uint8Array` — hex `<...>` form |
+| `open_arr` / `close_arr` | `[` / `]` |
+| `open_dict` / `close_dict` | `<<` / `>>` |
+| `kw` | `value: string` (`obj`, `endobj`, `R`, `stream`, `endstream`, `xref`, `trailer`, `startxref`, `true`, `false`, `null`, `n`, `f`) |
+| `eof_marker` | `%%EOF` |
+
+### Tokenizer interface
+
+| Member | Description |
+|--------|-------------|
+| `next()` | Consumes and returns the next token (or `null` at EOF). |
+| `peek()` | Looks ahead without consuming. |
+| `pos()` | Current offset. |
+| `seek(n)` | Forces the offset (used after skipping a stream body). |
+| `bytes` | Reference to the source `Uint8Array`. |
+
+## Examples
+
+### Iterating a stream
+
+```js
+const tok = tokMod.tokenize(bytes);
+let t;
+while ((t = tok.next())) {
+    if (t.kind === 'kw' && t.value === 'xref') break;
+}
+```
+
+### Locating `startxref` by backward scan
+
+```js
+const needle = new Uint8Array([0x73,0x74,0x61,0x72,0x74,0x78,0x72,0x65,0x66]);
+const at = tokMod.lastIndexOfBytes(bytes, needle);
+```
+
+### Starting from a known offset
+
+```js
+const tok = tokMod.tokenize(bytes, { start: 12345 });
+tok.next();   // first token at or after 12345
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/tokenizer/bad-input` | `ParseError` | `bytes` is not a `Uint8Array`. |
+| `pdf/tokenizer/bad-seek` | `ParseError` | `seek(n)` out of range. |
+| `pdf/tokenizer/bad-name-escape` | `ParseError` | `#xx` truncated or non-hex. |
+| `pdf/tokenizer/bad-number` | `ParseError` | Empty or unparsable numeric token. |
+| `pdf/tokenizer/bad-string` | `ParseError` | Trailing backslash. |
+| `pdf/tokenizer/unterminated-string` | `ParseError` | `(...)` never closed. |
+| `pdf/tokenizer/bad-hex` | `ParseError` | Non-hex character inside `<...>`. |
+| `pdf/tokenizer/unexpected-rangle` | `ParseError` | Lone `>` outside a hex string. |
+| `pdf/tokenizer/empty-keyword` | `ParseError` | Empty keyword. |
+
+## See also
+
+- [`pdfParser`](./parser.md) — main consumer.
+- [`pdfXref`](./xref.md) — uses `lastIndexOfBytes` for `startxref`.
+- [`pdfErrors`](../errors.md)

package/docs/api/syntax/trailer.md

@@ -0,0 +1,85 @@
+---
+module: pdfTrailer
+category: pdf/syntax
+dependencies: [pdfErrors, pdfParserObj]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfTrailer
+
+> Typing of the trailer dictionary, ISO 32000-2 §7.5.5 — `{ size, root, info?, prev?, id?, encrypt? }`.
+
+**Module** `pdfTrailer` | **Source** `packages/front/office/pdf/src/syntax/trailer.js` | **Deps** `pdfErrors`, `pdfParserObj` | **Worker-safe** yes
+
+A thin layer over the raw trailer dictionary. It checks the **required** entries
+(`/Size`, `/Root`) and extracts the well-defined optional ones. `/Encrypt` is
+left raw (a reference is narrowed to `{num, gen}`, an inline dictionary is passed
+through). Entries this typer does not model — `/XRefStm` for hybrid-reference
+files among them — are reachable only through `raw`.
+
+## Resolve
+
+```js
+const trailer = runtime.resolve('pdfTrailer');
+// Returns: { typeTrailer }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeTrailer` | `(dict: PdfDict) => TypedTrailer` | Typed record (see shape). |
+
+### `TypedTrailer` shape
+
+```js
+{
+    size:    number,                              // /Size — required
+    root:    { num: number, gen: number },        // /Root — required
+    info?:   { num: number, gen: number },        // /Info — only when a ref
+    id?:     [Uint8Array, Uint8Array],            // /ID — pair of strings
+    prev?:   number,                              // /Prev — previous xref offset
+    encrypt?: { num, gen } | PdfObject,           // /Encrypt — ref or inline dict
+    raw:     PdfDict                              // the original dictionary
+}
+```
+
+## Examples
+
+### Plain typing
+
+```js
+const xref = runtime.resolve('pdfXref');
+const trailer = runtime.resolve('pdfTrailer');
+
+const { dict } = xref.parseTrailerDict(bytes, end);
+const t = trailer.typeTrailer(dict);
+t.size;          // 42
+t.root;          // { num: 1, gen: 0 }
+t.prev;          // 12345 (on an incremental update)
+```
+
+### Detecting an encrypted file
+
+```js
+if (t.encrypt) {
+    const sec = runtime.resolve('pdfSecurity');
+    // → see the crypto layer
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/trailer/not-dict` | `ParseError` | Argument is not `{type:'dict'}`. |
+| `pdf/trailer/missing-size` | `ParseError` | `/Size` missing or not a non-negative int. |
+| `pdf/trailer/missing-root` | `ParseError` | `/Root` missing or not a reference. |
+
+## See also
+
+- [`pdfXref`](./xref.md) — produces the raw dictionary consumed here.
+- [`pdfDocument`](../document/document.md) — chains trailers through `/Prev`.
+- [`pdfErrors`](../errors.md)