# pdfnative

> Pure native PDF generation library in TypeScript. Zero runtime dependencies, tree-shakeable, producing output that conforms to ISO 32000-1 (PDF 1.7) and ISO 19005 (PDF/A-1b/2b/2u/3b) — the latter validated against the veraPDF reference validator in CI. Works in Node.js, browsers, Deno, Bun, and Web Workers. 22 Unicode scripts with OpenType GSUB/GPOS shaping and full UAX #9 BiDi. PAdES digital signatures with long-term validation (B-B → B-LTA). Current version: 1.7.0.

_Verified on 2026-08-29 against the source tree by `npm run verify:docs`; the canonical manifest is <https://pdfnative.dev/assets/ecosystem.json>._

## Docs

- [README](https://github.com/Nizoka/pdfnative/blob/main/README.md): Full feature list, install, quick start, API surface, examples.
- [ROADMAP](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md): Shipped milestones (v1.0 → v1.7; v1.7: PAdES LTV B-B → B-LTA, charts v2, colour-emoji flag/ZWJ sequences, UAX #9 conformance, print production, PDF/A declaration guards, `updateMetadata`; v1.6: parser-side decryptor, streaming merge/split/extract, fill & flatten AcroForms, native vector charts, `extractText`, re-encrypt output; v1.5: math/technical-symbols font, `pdfnative/tools` font compiler/parser, SVG `<text>`, page-labels reader, layout debug overlay + `inspectDocumentLayout`, markup annotation read/write, AI-agent governance; v1.4: document outline/bookmarks, page labels, page-tree manipulation (merge/split/extract), streamToFile, COLRv1 advanced compositing; v1.3: COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, validatePdfUA) + long-term (WASM, full USE).
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md): Per-version changes.
- [Release notes v1.7.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.7.0.md): PAdES LTV signing B-B → B-LTA (`signPdfBytesWithTimestamp` RFC 3161 timestamps, `addValidationInfo` `/DSS` + `/VRI` OCSP/CRL material, `addDocumentTimestamp`, `listSignatures`, multi-signature via `addSignaturePlaceholder({ allowMultiple })` — network transport injected through `setTimestampProvider`/`setRevocationProvider`, the engine never opens a socket), charts v2 (stackedBar/stackedBarH/area/scatter, secondary right axis, log + UTC time scales, data labels, x-label collision handling), colour-emoji flag & ZWJ sequences (51 flags + 22 ZWJ as COLR ligatures), UAX #9 conformance fixes (RTL digit order, glyph mirroring, ALEF joining, Persian presentation forms), PDF/A declaration guards (`strict`/`onDiagnostic`), incremental writer/xref hardening, `PdfModifier.updateMetadata()`.
- [Release notes v1.6.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.6.0.md): Standard Security Handler reader/decryptor (`openPdf(bytes, { password })`, RC4/AES-128/AES-256; `PdfSourceInput`/`MergeOptions.password` for encrypted merge/split sources), streaming page-tree manipulation (`streamMergedPdfs`/`streamSplitPdf`/`streamExtractPages`), fill & flatten existing AcroForm PDFs (`readFormFields`/`fillForm`/`flattenForm`) — encrypted documents included (encrypted incremental update), native vector charts (`chart` block: bar/barH/line/pie/donut), text extraction (`extractText`: per-page reading-order text + positioned runs, encrypted PDFs supported), re-encrypt merge/split output (`MergeOptions.encrypt`, AES-128/256), expanded colour-emoji subset (221 → 1167 incl. complete Transport & Map). Fixes: spec-compliant R6 hash + all-strings encryption on the writer; incremental trailer carries `/Encrypt` forward.
- [Release notes v1.5.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.5.0.md): math/technical-symbols font (lang `'math'`, `registerFont`), `pdfnative/tools` (`compileFontData`/`parseFontData`), SVG `<text>` rendering, page-labels reader (`getPageLabels()`), layout debug overlay (`layout: { debug: true }`) + `inspectDocumentLayout()`, markup annotation read/write (`buildAnnotation`/`getAnnotations`/`addAnnotation`), control-character hardening (#58), table descender fix (#59), AI-agent governance (#56).
- [Release notes v1.4.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.4.0.md): document outline/bookmarks (`/Outlines`, `outline: 'auto'`), page labels (`/PageLabels`), page-tree manipulation (`mergePdfs`/`splitPdf`/`extractPages`, secure-by-default 256 MiB `maxOutputSize` cap), `streamToFile()`, COLRv1 sweep gradients + `PaintComposite` blend modes, pluggable signature crypto provider (`setCryptoProvider`), font-data validator (`validateFontData`), viewer preferences (`/ViewerPreferences`), nested lists, table cell borders + vertical alignment.
- [Release notes v1.3.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.3.0.md): COLRv1 colour emoji, USE-lite shaper integration, true constant-memory streaming, UAX #9 X4–X5 overrides, pixel-diff visual regression, Telugu + Amharic/Sinhala/Tibetan/Khmer/Myanmar scripts, opt-in NFC normalization, CSPRNG-only crypto, configurable block limit, validatePdfUA, colour-emoji selector/BBox fixes, #48 CP-1252 fix.
- [Release notes v1.2.0](https://github.com/Nizoka/pdfnative/blob/main/release-notes/v1.2.0.md): `addSignaturePlaceholder()`, ASN.1 grandchild fix (#46), page-by-page streaming, UAX #9 embeddings, USE-lite classifier.
- [Learn pdfnative](https://pdfnative.dev/learn/): Eight-step guided path from installing the package to generating 100,000 pages. Each step introduces one concept. Start here if you have never generated a PDF programmatically.
- [Quick Start](https://pdfnative.dev/guides/quickstart.html): Install + first PDF in Node or browser.
- [Architecture](https://pdfnative.dev/guides/architecture.html): Two builders, module dependency flow, design decisions.
- [PDF/A conformance](https://pdfnative.dev/guides/pdfa.html): How `tagged: true` produces veraPDF-valid PDF/A-1b/2b/2u/3b.
- [Digital signatures](https://pdfnative.dev/guides/signatures.html): CMS/PKCS#7 and PAdES + `addSignaturePlaceholder()` three-line workflow; multiple signatures, signature metadata, RSA SHA-256/384/512 + ECDSA P-256.
- [Long-term validation](https://pdfnative.dev/guides/ltv.html): PAdES B-B → B-LTA — RFC 3161 signature timestamps, `/DSS` + `/VRI` revocation material, document timestamps, injected `TimestampProvider`/`RevocationProvider` (no built-in networking).
- [Print production](https://pdfnative.dev/guides/print.html): Bleed/trim/art/crop page boxes (`layout.print`), crop + registration marks, `/Trapped` with XMP parity, duplex/tray/copies print defaults, custom OutputIntent ICC, large-format `/UserUnit`.
- [Accessibility](https://pdfnative.dev/guides/accessibility.html): Tagged PDF, /ActualText, PDF/UA structure tree.
- [Onboarding](https://pdfnative.dev/guides/onboarding.html): 90-second ecosystem tour — library + CLI + MCP.
- [Choosing your surface](https://pdfnative.dev/guides/choose.html): Library, CLI, MCP or React? The decision tree plus a verified capability × surface matrix, with an honest em-dash where a surface lacks a capability.
- [FAQ](https://pdfnative.dev/guides/faq.html): Custom fonts, encryption, BiDi, workers, vs other libs.
- [Troubleshooting](https://pdfnative.dev/guides/troubleshooting.html): Missing glyphs, RTL appearing backwards, oversized PDFs, parser errors.
- [Colour-emoji CLI](https://pdfnative.dev/guides/colour-emoji-cli.html): `npx pdfnative-build-emoji-font` — generate a colour-emoji data module covering any glyph subset up to the full ~3,600-glyph Noto Color Emoji set, plus flag & ZWJ sequences via `--sequences` / `--sequence-list`; pinned download + SHA-256 verification.
- [Charts](https://pdfnative.dev/guides/charts.html): Native vector `chart` blocks — 9 kinds (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut) with secondary right axis, log and time scales, data labels, x-label collision handling. Path operators, no rasterisation; `/Figure` tagging with alt text.
- [Text extraction](https://pdfnative.dev/guides/text-extraction.html): `extractText()` — reading-order Unicode via `/ToUnicode`, optional positioned runs, works on encrypted PDFs with a password. The RAG / agent-ingestion entry point.
- [Form filling](https://pdfnative.dev/guides/form-filling.html): `readFormFields()` / `fillForm()` / `flattenForm()` on existing AcroForms, including encrypted PDFs via incremental update.
- [PDF manipulation](https://pdfnative.dev/guides/pdf-manipulation.html): `openPdf()` (with `{ password }`), merge / split / extract pages, re-encrypt on output, and their streaming variants.
- [Streaming output](https://pdfnative.dev/guides/streaming.html): `buildDocumentPDFStream` vs `buildDocumentPDFStreamTrue`, `streamToFile`, and the exact memory profile of each.
- [Smart tables](https://pdfnative.dev/guides/tables.html): Multi-page tables — auto-wrap, repeated headers, zebra striping, cell borders, vertical alignment, auto-fit columns.
- [Annotations](https://pdfnative.dev/guides/annotations.html): Markup annotations (highlight, underline, note, shape, freetext) applied by incremental update so signatures stay valid.
- [Outlines & page labels](https://pdfnative.dev/guides/outlines.html): Document bookmarks (`outline: 'auto'` or an explicit tree) and `/PageLabels` numbering.
- [Viewer preferences](https://pdfnative.dev/guides/viewer-preferences.html): `/ViewerPreferences` — page layout, page mode, and display hints.
- [Colour emoji](https://pdfnative.dev/guides/colour-emoji.html): COLRv1 rendering — solid, linear and radial gradient layers as native PDF Form XObjects; flag & ZWJ sequences (51 flags + 22 ZWJ bundled) render as single ligature glyphs.
- [Layout debugging](https://pdfnative.dev/guides/debugging.html): `inspectDocumentLayout()` and the `debug: true` overlay for diagnosing pagination.
- [Font validation](https://pdfnative.dev/guides/font-validation.html): `validateFontData()` — check a font module before registering it.
- [Self-verifying generation](https://pdfnative.dev/guides/self-verify.html): The generate → inspect → assert → correct loop — `inspectDocumentLayout()` before building, then `extractText()` / `validatePdfUA()` / `listSignatures()` against the emitted bytes; the same loop on the CLI (`inspect --check`, stable exit codes) and MCP (`inspect_pdf`).
- [Agentic workflows](https://pdfnative.dev/guides/agentic-workflows.html): Patterns for driving pdfnative from AI agents on public, validated APIs.
- [Use cases](https://pdfnative.dev/guides/use-cases.html): Four ecosystem architectures with diagrams — store the DocSpec instead of the PDF and render on-device, air-gapped PAdES B-LTA archiving, a CI document-regression gate with `compare`, and edge-rendered PDFs with correct HTTP caching.
- [AI governance](https://pdfnative.dev/guides/ai-governance.html): The human-in-the-loop contract — agents draft, humans review, approve and submit.
- [Responsibility](https://pdfnative.dev/responsibility.html): Sustainability, supply-chain and accessibility position — every claim linked to its proof, plus an explicit list of what is deliberately not claimed.
- [Ecosystem manifest](https://pdfnative.dev/assets/ecosystem.json): Machine-readable versions and counts for the whole ecosystem (canonical, enforced by `npm run verify:docs`).

> Every guide is pre-rendered: the HTML at `https://pdfnative.dev/guides/<name>.html` already contains the full article, so a fetcher that does not execute JavaScript gets the whole page. The Markdown source is served at the same path with `.md` (`https://pdfnative.dev/guides/charts.md`) and is declared as a `text/markdown` alternate in each page head — the same text without the page chrome, and the cheaper fetch of the two. Both work without JavaScript.

## Agent and AI integration

- [Copilot instructions](https://github.com/Nizoka/pdfnative/blob/main/.github/copilot-instructions.md): Canonical project conventions — architecture, code style, build/test, PDF-specific invariants.
- [AGENTS.md](https://github.com/Nizoka/pdfnative/blob/main/AGENTS.md): Editor-agnostic agent guidance (Cursor / Aider / Claude Code / Continue).
- [MCP integration](https://pdfnative.dev/guides/mcp.html): `pdfnative-mcp` v1.6.0 — use pdfnative from Claude Desktop, Cursor, Continue, Zed via 28 tools — the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), `update_metadata`, the read-only `inspect_layout` pagination preview, all 13 block kinds in `generate_basic_pdf`, print production, charts v2, native vector `add_chart`, `read_form_fields` / `fill_form`, `encrypt_pdf` / `decrypt_pdf`, markup `annotate_pdf`, the network-free `draft_governance_issue`, and the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages`. MCP 2026-07-28 spec with legacy fallback. Built on pdfnative 1.7.0.
- [CLI](https://pdfnative.dev/guides/cli.html): `pdfnative-cli` v1.4.0 — 21 commands from the terminal — render, fill, annotate, metadata, merge / split / extract, sign (RFC 3161 `--timestamp`, B-T), ltv (B-LT, air-gapped collect → embed), doc-timestamp (B-LTA), verify, encrypt, decrypt, inspect, extract-text, compare, batch (incl. declarative `--manifest` pipelines), doctor, schema, completion, govern; agent-native `--json`/`E_*`/`--dry-run` contract (12 error codes, 19 schema subjects). Built on pdfnative 1.7.0 (pins `^1.7.0`), Node ≥ 22.
- [React](https://pdfnative.dev/guides/react.html): `pdfnative-react` v1.2.0 — declarative JSX components compiled on-device to pdfnative blocks; charts v2, print production, PDF/A diagnostics channel, `renderToResponse` HTTP caching, 25 lint rules, render functions, client hooks, token-frugal DocSpec. Peers: React 19 + pdfnative `^1.7.0`.

## Source

- [src/](https://github.com/Nizoka/pdfnative/tree/main/src): Library source (core, crypto, fonts, parser, shaping, types, worker).
- [scripts/generators/](https://github.com/Nizoka/pdfnative/tree/main/scripts/generators): 48 sample generators producing 242 reference PDFs.
- [tests/](https://github.com/Nizoka/pdfnative/tree/main/tests): 2691+ tests across 123 files. 95%+ statements measured at v1.6.0; CI enforces ≥88%.

## Machine-readable artefacts

- [agent-brief.md](https://pdfnative.dev/agent-brief.md): A compact briefing for AI agents writing code with pdfnative — the core API, the verified pitfalls that produce wrong code, the surface decision tree, and the self-verification loop. Designed to be pasted into a coding agent's context.
- [llms-full.txt](https://pdfnative.dev/llms-full.txt): This index plus the README and the full Markdown source of every guide, in one request.
- [llms-recipes.txt](https://pdfnative.dev/llms-recipes.txt): The executable recipe corpus — standalone TypeScript files importing from `pdfnative`, each executed in CI with its `@expect` assertions verified, so the code you copy is proven to compile and to produce exactly the artefact its header describes.
- [api.json](https://pdfnative.dev/assets/api.json): The public API surface, derived mechanically from the export statements of `src/index.ts` — name, kind, source module, signature and TSDoc summary where extractable. The substitute for the unpublished `index.d.ts`.
- [surfaces.json](https://pdfnative.dev/data/surfaces.json): The capability × surface matrix (library / CLI / MCP / React) behind the [Choosing your surface](https://pdfnative.dev/guides/choose.html) guide.
- [errors.json](https://pdfnative.dev/data/errors.json): The engine's diagnostic registry — every `PDFA_` diagnostic code with its meaning and remedy, two-way verified against `src/` by the `error-parity` rule.
- [llms-index.json](https://pdfnative.dev/llms-index.json): Per-page machine index — HTML and raw-Markdown URL, title, summary, section anchors, and exact byte / approximate token sizes for every artefact, so you can decide what to fetch before spending the tokens.
- Every guide serves its raw Markdown at the same URL with `.md` instead of `.html`, declared via `<link rel="alternate" type="text/markdown">` in each page head. All of these URLs are listed in the sitemap.

## Ecosystem

- [pdfnative-cli](https://github.com/Nizoka/pdfnative-cli): CLI wrapper for pdfnative (v1.4.0, built on pdfnative 1.7.0 — pins `^1.7.0`, Node ≥ 22) — render, fill, annotate, metadata, merge, split, extract, sign, verify, ltv, doc-timestamp, encrypt, decrypt, inspect, extract-text, compare, batch, doctor, schema, completion, govern.
- [pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp): Model Context Protocol server exposing pdfnative as 28 AI tools (v1.6.0, built on pdfnative 1.7.0).
- [pdfnative-react](https://github.com/Nizoka/pdfnative-react): React renderer — declarative JSX components compiled on-device to pdfnative blocks (v1.2.0, React 19 + pdfnative ^1.7.0 peers).

---
<!-- source: README.md -->
# pdfnative

[![CI](https://github.com/Nizoka/pdfnative/actions/workflows/ci.yml/badge.svg)](https://github.com/Nizoka/pdfnative/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Nizoka/pdfnative/actions/workflows/codeql.yml/badge.svg)](https://github.com/Nizoka/pdfnative/actions/workflows/codeql.yml)
[![npm version](https://img.shields.io/npm/v/pdfnative)](https://www.npmjs.com/package/pdfnative)
[![npm downloads](https://img.shields.io/npm/dm/pdfnative)](https://www.npmjs.com/package/pdfnative)
[![bundle size](https://img.shields.io/bundlephobia/minzip/pdfnative)](https://bundlephobia.com/package/pdfnative)
[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/pdfnative)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![npm provenance](https://img.shields.io/badge/provenance-signed-blueviolet)](https://docs.npmjs.com/generating-provenance-statements)
[![website](https://img.shields.io/badge/pdfnative.dev-0066FF?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxyZWN0IHg9IjMiIHk9IjIiIHdpZHRoPSIxNCIgaGVpZ2h0PSIxOCIgcng9IjIiIGZpbGw9Im5vbmUiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iMS41Ii8+PHBhdGggZD0iTTcgN2g2TTcgMTFoOE03IDE1aDQiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iMS41IiBzdHJva2UtbGluZWNhcD0icm91bmQiLz48L3N2Zz4=)](https://pdfnative.dev)
[![pdfnative-mcp](https://img.shields.io/npm/v/pdfnative-mcp?label=pdfnative-mcp&color=6366f1)](https://www.npmjs.com/package/pdfnative-mcp)
[![pdfnative-cli](https://img.shields.io/npm/v/pdfnative-cli?label=pdfnative-cli&color=0e7490)](https://www.npmjs.com/package/pdfnative-cli)
[![pdfnative-react](https://img.shields.io/npm/v/pdfnative-react?label=pdfnative-react&color=06b6d4)](https://www.npmjs.com/package/pdfnative-react)

Pure native PDF generation library — zero vendor dependencies. Conforms to ISO 32000-1 (PDF 1.7).

## Ecosystem

pdfnative ships as four coordinated packages — pick whichever entry point fits your workflow:

| Package | Latest | Use it for |
|---|:---:|---|
| [`pdfnative`](https://www.npmjs.com/package/pdfnative) | **v1.7.0** | The library itself — call from Node, browsers, Workers, Deno, Bun. |
| [`pdfnative-cli`](https://www.npmjs.com/package/pdfnative-cli) | **v1.4.0** | Render JSON → PDF, sign with the **complete PAdES ladder** (`sign --timestamp` B-T, `ltv` B-LT with air-gapped collect → embed, `doc-timestamp` B-LTA; RSA-SHA256/384/512 + ECDSA, native constant-time crypto by default), inspect, verify, **compare** (CI text + structure diff), signature-safe **metadata** edits, **merge / split / extract** pages, **annotate**, **govern** (AI-governance / HITL gate), declarative **batch `--manifest`** pipelines, and emit JSON Schemas from the shell. Pins pdfnative `^1.7.0`: 22 scripts + COLRv1 emoji, `--font math`, charts v2, print production, `render --strict` PDF/A gating, and an agent-native `--json`/`E_*`/`--dry-run`/`--summary` contract. Node ≥ 22. |
| [`pdfnative-mcp`](https://www.npmjs.com/package/pdfnative-mcp) | **v1.6.0** | Use pdfnative from Claude Desktop, Cursor, Continue, Zed (or any MCP client, stdio or HTTP) — **28 production tools** spanning the engine's full document model: all 13 block kinds in `generate_basic_pdf`, layout options, build-time `encrypt` that keeps the AcroForm, image watermarks, print production (page boxes, bleed, marks, `/UserUnit`, OutputIntent), charts v2 (stacked / area / scatter, dual axis, log & time scales), the complete PAdES ladder B-B → B-LTA (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`, `verify_pdf ltv: true`), `update_metadata`, the read-only `inspect_layout` pagination preview, honest PDF/A (`embedFonts` / `strict` / diagnostics), six MCP prompts, token-frugal read modes (`verbosity` / `fields`), the network-free `draft_governance_issue` (AI-governance / HITL), and the MCP **2026-07-28** spec with automatic legacy fallback. No outbound request by default — the only permitted egress is operator-configured TSA / OCSP / CRL. Pins pdfnative `^1.7.0`. |
| [`pdfnative-react`](https://www.npmjs.com/package/pdfnative-react) | **v1.2.0** | Write PDFs as declarative JSX — `<Document>`, `<Page>`, `<Table>`, `<Barcode>`, `<Svg>`, `<FormField>`… compiled on-device to pdfnative blocks by a custom React 19 reconciler. Charts v2 (9 kinds, dual axes, log/time scales), print production (`<Document print>`), the PDF/A diagnostics channel (`layout.strict` / `onDiagnostic`), HTTP caching on `renderToResponse` (`etag` / `cacheControl`), 25 lint rules, client hooks & components (`usePdf`, `PDFViewer`, `PDFDownloadLink`), and a versioned `DocSpec` grammar (`docSpecSchema()`) for AI agents. Peer: pdfnative ^1.7.0, React ^19.0.0, Node ≥22. (A 1.6 engine would throw mid-render on the charts-v2 fields.) |

```bash
npm install pdfnative                 # library
npm install pdfnative pdfnative-react react   # React renderer (pdfnative + React 19 peers)
npm install -g pdfnative-cli          # CLI
npm install -g pdfnative-mcp          # MCP server
```

Detailed docs: [CLI guide](docs/guides/cli.md) · [MCP guide](docs/guides/mcp.md) · [React guide](docs/guides/react.md) · [Onboarding cheatsheet](docs/guides/onboarding.md).

## Highlights

- **Zero dependencies** — built from scratch in pure TypeScript. Zero runtime dependencies, tree-shakeable, auditable
- **Conforms to ISO 32000-1** — valid xref tables, /Info metadata, proper font embedding
- **22 Unicode scripts** — Thai, Japanese, Chinese (SC), Korean, Greek, Devanagari, Telugu, Turkish, Vietnamese, Polish, Arabic, Hebrew, Cyrillic, Georgian, Armenian, Bengali, Tamil, Sinhala, Tibetan, Khmer, Myanmar, Ethiopic
- **Thai OpenType shaping** — GSUB substitution + GPOS mark-to-base + mark-to-mark positioning
- **Arabic positional shaping** — GSUB isolated/initial/medial/final forms + lam-alef ligatures
- **BiDi text layout** — Unicode Bidirectional Algorithm (UAX #9) with isolates (LRI/RLI/FSI/PDI) and explicit embeddings (LRE/RLE/LRO/RLO/PDF) including character-level X4–X5 overrides (v1.3.0). **v1.7.0** implements I1/I2 even embedding levels so digit runs (European, Arabic-Indic, Extended Arabic-Indic) keep logical order in RTL text, and full rule-L4 glyph mirroring through the complete 428-pair `BidiMirroring.txt` table
- **USE-lite shaping** — `classifyUseCategory` / `classifyClusters` drive joiner classification across the Devanagari, Bengali, and Tamil shapers, fixing nukta+virama, half-form, eyelash-ra, and ya-phalaa edge cases (v1.3.0)
- **Colour emoji (COLRv1)** — opt-in Noto Color Emoji subset (**expanded to 1167 glyphs in v1.6.0**, ~4.5 MB with the v1.7.0 sequence ligatures, incl. the complete Transport & Map block); solid + linear + radial gradient layers rendered as native PDF Form XObjects; monochrome fallback when not registered (v1.3.0). Variation selectors, ZWJ/ZWNJ, and skin-tone modifiers no longer leave tofu, and glyph `/BBox` is computed from contour bounds so emoji are never clipped (v1.3.0). **Advanced compositing** (v1.4.0): COLRv1 sweep (conic) gradients render as native flat-shaded wedges, and `PaintComposite` separable blend modes (Multiply, Screen, Overlay, Darken, Lighten, …) map to PDF `/BM` ExtGState; structural Porter-Duff modes fall back to monochrome. **Flag & ZWJ sequences** (v1.7.0): 51 flags + 22 ZWJ sequences (families, professions, rainbow/pirate flags, …) resolve through the source font's GSUB into single colour ligature glyphs with a longest-match pre-pass — both VS-16 spellings match, uncovered sequences degrade to the historical per-codepoint rendering, and the CLI bundles any custom set (`--sequences`, `--sequence-list`, skin tones included). [Guide →](docs/guides/colour-emoji.md)
- **Multi-font fallback** — automatic cross-script font switching with continuation bias
- **TTF subsetting** — only used glyphs embedded (dramatic file size reduction)
- **Tagged PDF / PDF/A** — structure tree, /ActualText, XMP metadata, sRGB OutputIntent (PDF/A-1b, 2b, 2u, 3b with embedded file attachments). **Conformance guards** (v1.7.0): configurations that would break the declared PDF/A level (no embedded fonts, DeviceCMYK images) surface a diagnostic — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error under `strict: true`. [Guide →](docs/guides/pdfa.md)
- **PDF Encryption (round-trip)** — **write** AES-128 (V4/R4) and AES-256 (V5/R6) encrypted PDFs (RC4 is never emitted), and **read** all of AES-128, AES-256, and legacy RC4 (V1–V4); owner + user passwords, granular permissions. **v1.6.0** adds a Standard Security Handler **decryptor** — `openPdf(bytes, { password })` decrypts transparently, the merge/split API ingests encrypted sources **and re-encrypts its output** (`MergeOptions.encrypt`, AES only, fresh keys) — closing the full *open → edit → re-secure* round trip. [Guide →](docs/guides/pdf-manipulation.md)
- **Native vector charts** (v1.6.0, **charts v2 in v1.7.0**) — bar, horizontal-bar, line, pie, donut, **stacked bars, area, and scatter** `chart` blocks rendered as pure PDF path operators (zero deps, no rasterisation); multi-series, legends, "nice" axis ticks, negative values, tagged `/Figure` + alt text. v1.7.0 adds a **secondary right axis**, **log and UTC-deterministic time scales**, **per-point data labels**, and x-label collision handling (automatic stride + `labelStride` / `labelRotation`). [Guide →](docs/guides/charts.md)
- **Text extraction** (v1.6.0) — `extractText()` decodes page content streams into per-page reading-order Unicode text plus optional positioned runs; `/ToUnicode` CMap, `/Encoding /Differences`, and WinAnsi/MacRoman decoding; works on encrypted documents (`{ password }`); hard `maxTextLength` memory cap for untrusted input. [Guide →](docs/guides/text-extraction.md)
- **Free-form document builder** — headings, paragraphs, lists (incl. **nested / hierarchical** bullet & numbered lists, v1.4.0), tables, images, barcodes, SVG paths, form fields, spacers, page breaks, table of contents. Configurable block limit via `layout.maxBlocks` (default 100 000) for very large reports (v1.3.0)
- **Smart tables** — multi-page slicing with repeated headers, auto-wrap on column overflow, zebra striping, captions, and smart auto-fit columns (v1.2.0), plus per-cell **borders** (`cellBorders`) and **vertical alignment** (`cellVAlign` / `ColumnDef.vAlign`, v1.4.0). [Guide →](docs/guides/tables.md)
- **Barcode & QR code generation** — Code 128, EAN-13, QR Code, Data Matrix, PDF417 — pure PDF path operators (no images)
- **SVG rendering** — path, rect, circle, ellipse, line, polyline, polygon as native PDF operators, plus `<text>` elements rendered as upright PDF text with `x`/`y` positioning and `text-anchor` (start/middle/end) support (v1.5.0)
- **AcroForm fields** — text, multiline, checkbox, radio, dropdown, listbox with appearance streams (ISO 32000-1 §12.7). **v1.6.0** adds **fill & flatten of existing forms**: `readFormFields()`, `fillForm()` (regenerates appearances), and `flattenForm()` — non-destructive incremental update that preserves prior signatures, **including on encrypted documents** (appended objects are encrypted under the document's existing scheme). [Guide →](docs/guides/form-filling.md)
- **Digital signatures** — CMS/PKCS#7 detached signatures with RSA (SHA-256/384/512, v1.7.0) + ECDSA-SHA256 (P-256) and X.509 parsing (ISO 32000-1 §12.8). One-call placeholder injection via `addSignaturePlaceholder()` (v1.2.0). Pluggable **native crypto provider** (`setCryptoProvider()` / `PdfSignOptions.provider`, v1.4.0) for constant-time, hardware-backed signing (`node:crypto` / Web Crypto / HSM). **v1.7.0**: PAdES baseline profile (`profile: 'pades'` — ESS signing-certificate-v2, `ETSI.CAdES.detached`), **multiple signatures** (`allowMultiple` + `fieldName` selector), and `listSignatures()` inspection. [Guide →](docs/guides/signatures.md)
- **Print production** (v1.7.0) — bleed/trim/art/crop **page boxes** (`layout.print`, with a one-line `bleed` shorthand), **crop & registration marks** drawn as pure vector operators outside the TrimBox, `/Trapped` metadata with XMP parity, print-dialog defaults (**duplex**, tray pick, page range, copies), caller-supplied **OutputIntent ICC profile** (tagged mode), and large-format `/UserUnit` (banners, plans). Boxes survive `mergePdfs`/`splitPdf`. Byte-identical output when unused. [Guide →](docs/guides/print.md)
- **Long-term validation (LTV, PAdES B-B → B-LTA)** (v1.7.0) — RFC 3161 **signature timestamps** (`signPdfBytesWithTimestamp()`), embedded revocation material in `/DSS` + per-signature `/VRI` (`addValidationInfo()` — OCSP RFC 6960 + CRL RFC 5280), and **document timestamps** (`addDocumentTimestamp()`). Network transport is injected (`TimestampProvider` / `RevocationProvider`) — the engine stays offline and zero-dependency; rejected or tampered TSA tokens are never embedded. [Guide →](docs/guides/ltv.md)
- **Streaming output** — AsyncGenerator-based progressive PDF emission with configurable chunk size, object-boundary page-by-page streaming, and **true constant-memory streaming** (`buildDocumentPDFStreamTrue()`, v1.3.0) where the full PDF binary never materialises. One-call `streamToFile()` drains any stream to disk with back-pressure and `AbortSignal` support (v1.4.0). [Guide →](docs/guides/streaming.md)
- **Document outline & page labels** — nested bookmarks (`/Outlines` tree, with bold/italic/colour, collapsible nodes via `open: false`, explicit or `outline: 'auto'` from headings) and logical page numbering (`/PageLabels`: decimal, roman, alpha, prefixes, custom start) (v1.4.0). [Guide →](docs/guides/outlines.md)
- **Viewer preferences** — `PdfLayoutOptions.viewerPreferences` controls initial `/PageLayout` & `/PageMode` plus the `/ViewerPreferences` dict (hide toolbar/menubar, fit/center window, display doc title, non-full-screen mode, reading direction, print scaling) — PDF/A-safe (v1.4.0). **v1.7.0** adds the print-dialog defaults: `duplex`, `pickTrayByPDFSize`, `printPageRange`, `numCopies`. [Guide →](docs/guides/viewer-preferences.md)
- **Font-data validator** — opt-in `validateFontData()` structurally checks custom font modules (SFNT magic, base64 integrity, cmap coverage, glyph-id range, width array, finite metrics) and returns `{ valid, errors, warnings }` (v1.4.0). [Guide →](docs/guides/font-validation.md)
- **PDF parser & modifier** — read existing PDFs (tokenizer, xref, object parser, FlateDecode inflate) + incremental modification. Read-only PDF/UA structural checker `validatePdfUA()` (ISO 14289-1: MarkInfo, StructTree, ParentTree, Lang, per-page MCID uniqueness) (v1.3.0). **Page-tree manipulation** (v1.4.0): `mergePdfs()`, `splitPdf()`, `extractPages()` rebuild a clean object graph (inherited attributes resolved, annotations/signatures optionally dropped, deterministic trailer `/ID`, bounded-depth copy, 256 MiB output cap via `maxOutputSize`). **Round-trip readers** (v1.5.0): `getPageLabels()` parses `/PageLabels` back into a typed `PageLabelRange[]`; `getAnnotations()` / `getPageRef()` read page annotations, and `PdfModifier.addAnnotation()` injects new ones incrementally. **v1.6.0**: a Standard Security Handler **decryptor** (`openPdf(bytes, { password })`, RC4/AES-128/AES-256) lets the reader and page-tree API ingest encrypted sources, and **constant-memory streaming** variants `streamMergedPdfs()` / `streamSplitPdf()` / `streamExtractPages()` emit merges/splits in fixed-size chunks (byte-identical to the buffered functions). [Guide →](docs/guides/pdf-manipulation.md)
- **Markup annotations** — typed annotation model (text, highlight, underline, strikeout, squiggly, square, circle, line, freetext) via `buildAnnotation()` / `buildAnnotationBody()`, plus `PdfReader.getAnnotations()` and `PdfModifier.addAnnotation()` for round-trip read/write (v1.5.0); **v1.6.0** lets `addAnnotation()` operate on encrypted documents (RC4/AES sources, annotations stored encrypted). [Guide →](docs/guides/annotations.md)
- **Layout debug & inspection** — opt-in `layout: { debug: true }` overlays margin / content / cell boxes for visual layout debugging; `inspectDocumentLayout()` returns a programmatic per-page block-geometry report. Byte-identical when debug is off (v1.5.0). [Guide →](docs/guides/debugging.md)
- **Math & technical symbols** — bundleable math font under lang `'math'`; mathematical operators, Greek, arrows, and technical symbols route automatically via script detection (v1.5.0)
- **Font-data tooling** — `pdfnative/tools` exposes `compileFontData()` / `parseFontData()` to build and introspect font-data modules programmatically (v1.5.0)
- **Image embedding** — JPEG (DCTDecode) and PNG (FlateDecode) with auto-scaling and alignment
- **Hyperlinks** — PDF link annotations (/URI) with URL validation, blue underlined text, tagged /Link
- **Header/footer templates** — configurable `PageTemplate` with left/center/right zones and `{page}`/`{pages}`/`{date}`/`{title}` placeholders
- **Watermarks** — text and image overlays with configurable opacity, rotation, and position (background/foreground)
- **Table of contents** — auto-generated TOC with internal /GoTo links, dot leaders, and page numbers
- **FlateDecode compression** — zlib stream compression (50–90% size reduction), zero-dependency, platform-native
- **Web Worker support** — off-main-thread generation for large datasets
- **Tree-shakeable** — ESM + CJS dual build with TypeScript declarations
- **Heavily tested** — 2691+ tests across 123 files, fuzz suite, dual-mode visual-regression suite, performance benchmarks; 95.41% statement coverage measured at the v1.6.0 release, with CI enforcing ≥88% statements / 80% branches / 85% functions / 90% lines (vitest.config.ts)
- **NPM provenance** — signed builds via GitHub Actions OIDC
- **On-device generation** — runs in Node, browsers, Workers, Deno, Bun. No SaaS round-trip; documents never leave the calling process unless your application explicitly sends them
- **No telemetry, no network calls** — verifiable in source. The library never opens a socket, fetches remote fonts, or phones home
- **AI client integration** — use pdfnative from Claude Desktop, Cursor, Continue, and Zed via [`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) — **28 production tools** (generate, tables, barcodes, forms, sign with the full PAdES ladder, verify, validate, attachments, extraction, inspect, metadata, layout preview, plus page-tree `merge_pdfs` / `split_pdf` / `extract_pages`)
- **Command-line interface** — render, sign, verify, inspect, and batch-render PDFs from the shell with [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) — zero-config, scriptable, agent-native (`--json`/`E_*`/`--dry-run`), ideal for CI/CD pipelines
- **React renderer** — author PDFs as declarative JSX with [`pdfnative-react`](https://github.com/Nizoka/pdfnative-react): `<Document>`/`<Table>`/`<Barcode>` components, `usePdf`/`PDFViewer` client hooks, on-device rendering with no DOM or headless browser

## Installation

```bash
npm install pdfnative
```

**Requirements:** Node.js >= 22 | Modern browsers | Deno | Bun

## Documentation

- 🌐 **Website:** [pdfnative.dev](https://pdfnative.dev) — landing page, live in-browser demo with 12 examples, comparisons, benchmarks.
- 📘 **Quick Start:** [docs/guides/quickstart.md](docs/guides/quickstart.md) — Node.js, browser, Web Worker, streaming.
- 🏛️ **Architecture:** [docs/guides/architecture.md](docs/guides/architecture.md) — modules, builders, generation pipeline.
- ♿ **Accessibility:** [docs/guides/accessibility.md](docs/guides/accessibility.md) — tagged PDF, PDF/UA, PDF/A.
- ❓ **FAQ:** [docs/guides/faq.md](docs/guides/faq.md) — fonts, encryption, signatures, comparisons.
- 🤖 **Agentic workflows:** [docs/guides/agentic-workflows.md](docs/guides/agentic-workflows.md) — extend the engine at runtime (register fonts without a release) and embed agent-generated images.
- 🛠️ **Troubleshooting:** [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) — common pitfalls.
- 🎮 **Playgrounds:** ten interactive demos at [docs/playgrounds/](docs/playgrounds/) — [extreme-scripts](docs/playgrounds/extreme-scripts.html) (live BiDi/Indic stress tests), [all-scripts](docs/playgrounds/all-scripts.html) (every Unicode script), [scale](docs/playgrounds/scale.html) (1k-100k pages, Web Worker + true streaming), [authoring-plus](docs/playgrounds/authoring-plus.html) (SVG text, layout overlay, annotations), [toolkit](docs/playgrounds/toolkit.html) (bookmarks, page labels, viewer prefs, merge/split/extract, and v1.6.0 form fill/flatten), [charts](docs/playgrounds/charts.html) (native vector charts — all 9 v1.7.0 types), [inspect](docs/playgrounds/inspect.html) (drop any PDF and read a full report, entirely client-side), plus [cli](docs/playgrounds/cli.html), [mcp](docs/playgrounds/mcp.html) and [react](docs/playgrounds/react.html) ecosystem explorers.
- 🧪 **Sample PDFs:** [scripts/generators/](scripts/generators/) — 242 sample PDFs across 37 categories (48 generators) (see [Sample PDFs](#sample-pdfs) below).
- 🎓 **Learn:** [docs/learn/](docs/learn/) — an eight-step guided path from installing the package to generating 100,000 pages, live at [pdfnative.dev/learn/](https://pdfnative.dev/learn/).
- 🤖 **Machine-readable:** [llms.txt](llms.txt) (doc index for LLMs), [AGENTS.md](AGENTS.md) (agent guidance), and [docs/assets/ecosystem.json](docs/assets/ecosystem.json) — the canonical manifest of ecosystem versions and counts, enforced by `npm run verify:docs`.

## Why pdfnative?

pdfnative was designed for teams that need **ISO-compliant, production-grade PDF generation** with zero supply-chain risk. Here is how it compares to other popular JavaScript PDF libraries:

| Feature | pdfnative | jsPDF | pdfkit | pdf-lib | pdfmake |
|---------|:---------:|:-----:|:------:|:-------:|:------:|
| Runtime dependencies | **0** | 3 | 6 | 4 | 3 |
| TypeScript declarations | Built-in | Built-in | @types/* | Built-in | @types/* |
| PDF/A (ISO 19005) | 1b, 2b, 2u, 3b | — | — | — | — |
| Tagged PDF / PDF/UA | ✅ | — | ✅ | — | — |
| Encryption (read + write) | AES-128/256 + RC4 read | write (RC4) | write | — | write |
| Complex text shaping (GSUB/GPOS) | ✅ Thai, Arabic, Devanagari, Bengali, Tamil | — | Via fontkit | Via @pdf-lib/fontkit | Via pdfkit |
| BiDi (RTL) layout | ✅ | — | — | — | — |
| Modify existing PDFs | ✅ (incremental) | — | — | ✅ | — |
| Forms (create + fill + flatten) | ✅ all three | create | create | create + fill | — |
| Native charts (vector) | ✅ 9 kinds incl. stacked/area/scatter | — | — | — | — |
| Digital signatures | ✅ (RSA + ECDSA, PAdES) | — | — | — | — |
| LTV / timestamps (PAdES B-LTA) | ✅ RFC 3161 + /DSS | — | — | — | — |
| Print production (bleed/trim boxes, marks) | ✅ | — | — | — | — |
| Barcode / QR code (native) | ✅ 5 formats | — | — | — | QR |
| SVG path rendering | ✅ | Plugin | ✅ | Paths only | ✅ |
| Streaming output | ✅ | — | ✅ | — | ✅ |
| PDF parser | ✅ | — | — | ✅ | — |
| Tree-shakeable (ESM) | ✅ | — | — | ✅ | — |
| NPM provenance (SLSA) | ✅ | — | — | — | ✅ |

> **Data sources:** npm registry metadata and official README/documentation for each library, compared on **2026-07-28** (pdfkit 0.19.1, jsPDF 4.2.1, pdfmake 0.3.11, pdf-lib 1.17.1 — see [docs/data/comparison-2026-07-28.json](docs/data/comparison-2026-07-28.json)). Dependency counts reflect direct `dependencies` listed in each package's published manifest. "—" means the feature is not supported or not documented. Feature claims about third-party libraries are based on their public documentation and may not reflect the latest version — please verify against current releases. Sample PDFs validate with veraPDF (PDF/A) and Adobe Acrobat.

**When to choose another library:** You need advanced vector graphics (complex gradients, arbitrary transforms), rich interactive form scripting (JavaScript actions), or mature ecosystem integrations with existing toolchains.

**When to choose pdfnative:** You need zero-dependency PDF generation with ISO archival compliance (PDF/A), accessibility (tagged PDF), AES encryption, digital signatures, multi-script Unicode support — particularly Arabic/Hebrew BiDi and Thai GSUB/GPOS shaping — form fields, barcode generation, SVG rendering, or the ability to parse and incrementally modify existing PDFs.

## Quick Start

```typescript
import { buildPDFBytes, downloadBlob } from 'pdfnative';

const pdf = buildPDFBytes({
  title: 'Monthly Report',
  infoItems: [
    { label: 'Period', value: 'January 2026' },
    { label: 'Account', value: 'Main Account' },
  ],
  balanceText: 'Balance: $1,234.56',
  countText: '42 transactions',
  headers: ['Date', 'Description', 'Category', 'Amount', 'Status'],
  rows: [
    { cells: ['01/15', 'Grocery Store', 'Food', '-$45.00', ''], type: 'debit', pointed: false },
    { cells: ['01/16', 'Salary', 'Income', '+$3,000.00', 'X'], type: 'credit', pointed: true },
  ],
  footerText: 'Generated by MyApp',
});

// Browser: trigger download
downloadBlob(pdf, 'report.pdf');

// Node.js: write to file
import { writeFileSync } from 'fs';
writeFileSync('report.pdf', pdf);
```

### Document Builder

Build free-form documents with headings, paragraphs, lists, tables, images, barcodes, and more:

```typescript
import { buildDocumentPDFBytes } from 'pdfnative';

const pdf = buildDocumentPDFBytes({
  title: 'Project Report',
  blocks: [
    { type: 'toc' },
    { type: 'heading', text: 'Executive Summary', level: 1 },
    { type: 'paragraph', text: 'This quarter saw strong growth across all divisions...' },
    { type: 'image', data: jpegBytes, width: 400, align: 'center', alt: 'Revenue chart' },
    { type: 'list', items: ['Revenue up 15%', 'Costs down 8%', 'Net profit +23%'], style: 'bullet' },
    { type: 'table', headers: ['Q1', 'Q2', 'Q3', 'Q4'], rows: [
      { cells: ['$1.2M', '$1.4M', '$1.6M', '$1.8M'], type: 'credit', pointed: false },
    ]},
    { type: 'spacer', height: 20 },
    { type: 'heading', text: 'Next Steps', level: 2 },
    { type: 'paragraph', text: 'Focus areas for next quarter include...', align: 'left' },
    { type: 'link', text: 'View full report online', url: 'https://example.com/report' },
    { type: 'barcode', format: 'qr', data: 'https://example.com/report', align: 'center' },
  ],
  footerText: 'Confidential',
}, {
  headerTemplate: { center: 'Project Report', right: '{date}' },
  footerTemplate: { left: 'Confidential', right: 'Page {page} of {pages}' },
});
```

## Unicode Font Support

For non-Latin scripts, register font data loaders (lazy-loaded on demand):

```typescript
import { registerFonts, loadFontData, buildPDFBytes } from 'pdfnative';

registerFonts({
  th: () => import('pdfnative/fonts/noto-thai-data.js'),
  ja: () => import('pdfnative/fonts/noto-jp-data.js'),
  zh: () => import('pdfnative/fonts/noto-sc-data.js'),
  ko: () => import('pdfnative/fonts/noto-kr-data.js'),
  el: () => import('pdfnative/fonts/noto-greek-data.js'),
  hi: () => import('pdfnative/fonts/noto-devanagari-data.js'),
  tr: () => import('pdfnative/fonts/noto-turkish-data.js'),
  vi: () => import('pdfnative/fonts/noto-vietnamese-data.js'),
  pl: () => import('pdfnative/fonts/noto-polish-data.js'),
  ar: () => import('pdfnative/fonts/noto-arabic-data.js'),
  he: () => import('pdfnative/fonts/noto-hebrew-data.js'),
  ru: () => import('pdfnative/fonts/noto-cyrillic-data.js'),
  ka: () => import('pdfnative/fonts/noto-georgian-data.js'),
  hy: () => import('pdfnative/fonts/noto-armenian-data.js'),
  bn: () => import('pdfnative/fonts/noto-bengali-data.js'),
  ta: () => import('pdfnative/fonts/noto-tamil-data.js'),
  te: () => import('pdfnative/fonts/noto-telugu-data.js'), // v1.3.0
  si: () => import('pdfnative/fonts/noto-sinhala-data.js'), // v1.3.0
  bo: () => import('pdfnative/fonts/noto-tibetan-data.js'), // v1.3.0
  km: () => import('pdfnative/fonts/noto-khmer-data.js'), // v1.3.0
  my: () => import('pdfnative/fonts/noto-myanmar-data.js'), // v1.3.0
  am: () => import('pdfnative/fonts/noto-ethiopic-data.js'), // v1.3.0
  // v1.1.0+ — optional Latin fallback for PDF/A documents with curly quotes,
  // em-dash, ellipsis, etc. (activates automatically when needed):
  latin: () => import('pdfnative/fonts/noto-sans-data.js'),
  // v1.1.0+ — optional monochrome emoji:
  emoji: () => import('pdfnative/fonts/noto-emoji-data.js'),
});

const thaiFont = await loadFontData('th');

const pdf = buildPDFBytes({
  title: 'รายงานประจำเดือน',
  // ... other params
  fontEntries: thaiFont ? [{ fontData: thaiFont, fontRef: '/F3', lang: 'th' }] : [],
});
```

### Supported Languages

| Language | Code | Font | Script |
|----------|------|------|--------|
| Thai | `th` | Noto Sans Thai | GSUB + GPOS shaping |
| Japanese | `ja` | Noto Sans JP | CJK ideographs + kana |
| Chinese (Simplified) | `zh` | Noto Sans SC | CJK ideographs |
| Korean | `ko` | Noto Sans KR | Hangul syllables |
| Greek | `el` | Noto Sans Greek | Greek alphabet |
| Hindi (Devanagari) | `hi` | Noto Sans Devanagari | GSUB conjuncts + GPOS marks |
| Turkish | `tr` | Noto Sans Turkish | Latin extended (İ/ı) |
| Vietnamese | `vi` | Noto Sans Vietnamese | Latin + combining marks |
| Polish | `pl` | Noto Sans Polish | Latin extended (Ł/ł) |
| Arabic | `ar` | Noto Sans Arabic | GSUB positional shaping |
| Hebrew | `he` | Noto Sans Hebrew | Right-to-left script |
| Russian (Cyrillic) | `ru` | Noto Sans | Cyrillic alphabet |
| Georgian | `ka` | Noto Sans Georgian | Mkhedruli script |
| Armenian | `hy` | Noto Sans Armenian | Armenian alphabet |
| Bengali | `bn` | Noto Sans Bengali | GSUB conjuncts + GPOS marks |
| Tamil | `ta` | Noto Sans Tamil | GSUB ligatures + split vowels |
| Latin (PDF/A) | `latin` | Noto Sans VF | WinAnsi-extended Latin (curly quotes, em-dash, ellipsis…) |
| Emoji | `emoji` | Noto Emoji | Monochrome emoji (BMP/SMP, Fitzpatrick, ZWJ, VS-15/16) |

## Multi-Font (Mixed Scripts)

Generate PDFs with multiple scripts in the same document:

```typescript
const fonts = await Promise.all([
  loadFontData('th'),
  loadFontData('ja'),
  loadFontData('zh'),
]);

const fontEntries = fonts
  .filter(Boolean)
  .map((fd, i) => ({ fontData: fd!, fontRef: `/F${3 + i}`, lang: ['th', 'ja', 'zh'][i] }));

const pdf = buildPDFBytes({
  title: 'Multi-Language Report',
  headers: ['Date', 'Description', 'Category', 'Amount', 'Status'],
  rows: [
    { cells: ['01/01', 'English text', 'Test', '+100', 'OK'], type: 'credit', pointed: false },
    { cells: ['01/02', 'ข้อความไทย', 'ทดสอบ', '-50', ''], type: 'debit', pointed: false },
    { cells: ['01/03', '日本語テキスト', 'テスト', '+200', '済'], type: 'credit', pointed: true },
  ],
  // ... other params
  fontEntries,
});
```

## Web Worker (Large Datasets)

```typescript
import { createPDF } from 'pdfnative';

const pdf = await createPDF(params, {
  workerUrl: new URL('pdfnative/worker', import.meta.url),
  threshold: 500, // use Worker above 500 rows
  timeout: 30000, // Worker timeout in ms (default: 60000)
  onProgress: (percent) => console.log(`${percent}%`),
});
```

For lower-level control, use `generatePDFInWorker` directly with `WorkerGenerationOptions`:

```typescript
import { generatePDFInWorker } from 'pdfnative';
import type { WorkerGenerationOptions } from 'pdfnative';

const options: WorkerGenerationOptions = {
  timeout: 15000,
  onProgress: (percent) => console.log(`${percent}%`),
};

const pdf = await generatePDFInWorker(workerUrl, params, options);
```

## Layout Customization

```typescript
const pdf = buildPDFBytes(params, {
  pageWidth: 595.28,   // A4 (default)
  pageHeight: 841.89,  // A4 (default)
  margins: { t: 45, r: 36, b: 35, l: 36 },
  colors: {
    title: '#2563EB',           // hex — primary format
    credit: [15, 145, 121],     // RGB tuple [0–255]
    debit: '0.863 0.149 0.149', // PDF operator string [0.0–1.0]
    // ... see PdfColors type
  },
  columns: [
    { f: 0.15, a: 'l', mx: 12, mxH: 12 },
    { f: 0.35, a: 'l', mx: 50, mxH: 50 },
    { f: 0.20, a: 'r', mx: 20, mxH: 20 },
    { f: 0.30, a: 'r', mx: 30, mxH: 30 },
  ],
});
```

### Color Formats

All color values accept three formats:

| Format | Example | Description |
|--------|---------|-------------|
| Hex string | `'#2563EB'` or `'#26E'` | Primary format — `#RRGGBB` or `#RGB` |
| RGB tuple | `[37, 99, 235]` | Array with values 0–255 |
| PDF operator | `'0.145 0.388 0.922'` | Raw PDF RGB string (0.0–1.0) |

```typescript
import { parseColor } from 'pdfnative';

parseColor('#2563EB');           // '0.145 0.388 0.922'
parseColor([37, 99, 235]);       // '0.145 0.388 0.922'
parseColor('0.145 0.388 0.922'); // '0.145 0.388 0.922'
```

All inputs are validated and normalized before interpolation into PDF content streams, preventing operator injection.

### Font Sizes

Customize font sizes for each zone (title, info bar, table header, table cells, footer):

```typescript
const pdf = buildPDFBytes(params, {
  fontSizes: {
    title: 20,   // Title text (default: 16)
    info: 10,    // Info bar items (default: 9)
    th: 9,       // Table header cells (default: 8)
    td: 8,       // Table body cells (default: 7.5)
    ft: 8,       // Footer text (default: 7)
  },
});
```

| Zone | Key | Default | Description |
|------|-----|---------|-------------|
| Title | `title` | 16 | PDF title text |
| Info bar | `info` | 9 | Key-value pairs below title |
| Table header | `th` | 8 | Column header row |
| Table cells | `td` | 7.5 | Data row cells |
| Footer | `ft` | 7 | Page footer text |

All values are in PDF points (1pt = 1/72 inch). Partial overrides are supported — unspecified keys use defaults.

## Building Custom Font Data

### Obtaining TTF Files

For Noto Sans fonts, download the raw `.ttf` file directly from the [noto-fonts GitHub repository](https://github.com/notofonts):

1. Navigate to the font's GitHub repository (e.g., `github.com/notofonts/bengali`)
2. Find the TTF file under `fonts/NotoSansBengali/unhinted/ttf/` (or similar path)
3. Click the file, then click **"Download raw file"** (or use the raw URL)
4. Save it to `fonts/ttf/`

No zip download or extraction needed — each TTF is a standalone file you can download directly.

### Building the Data Module

Convert any TTF font into an importable data module:

```bash
npx pdfnative-build-font fonts/ttf/MyFont.ttf fonts/my-font-data.js
```

The tool extracts cmap, widths, metrics, GSUB, GPOS, and embeds the raw TTF as base64.

### Full colour-emoji coverage (`pdfnative-build-emoji-font`)

The bundled colour-emoji module (`pdfnative/fonts/noto-color-emoji-data.js`)
ships a lean curated subset to keep the package small. When you need glyphs
beyond that subset — up to the **full ~3,600-glyph** Noto Color Emoji set — a
second bundled binary generates a custom data module on demand, so even
**pdfnative-only** users get full coverage without the package ever carrying the
~32 MB source font:

```bash
# Download the pinned Noto Color Emoji (SHA-256 verified) and emit every glyph
npx pdfnative-build-emoji-font --download --all --out my-color-emoji-data.js

# …or build from a local TTF, selecting only the glyphs you need
npx pdfnative-build-emoji-font --ttf NotoColorEmoji-Regular.ttf \
  --codepoints "1F600,1F680,2764" --out my-color-emoji-data.js
```

Select glyphs with `--all`, `--preset`, `--codepoints`, or `--ranges`, then
register the generated module under lang `'emoji'`. See the
[Colour-emoji CLI guide](docs/guides/colour-emoji-cli.md).

## Agentic workflows

pdfnative is shaped so an AI agent can do more than *call* the engine — it can
**extend** it at runtime and **feed it content it generated itself**, without
waiting for a library release. Both patterns use already-shipped, public APIs.

**1. Extend the engine at runtime — no release required.** The font registry is a
runtime API. An agent can compile a TTF/OTF in memory and register it on the spot,
so a document renders the moment it needs a new script, symbol set, or brand font:

```js
import { registerFont, loadFontData, buildDocumentPDFBytes } from 'pdfnative';
registerFont('th', () => import('pdfnative/fonts/noto-thai-data.js'));
const th = await loadFontData('th');
if (!th) throw new Error('Thai font failed to load');
const bytes = buildDocumentPDFBytes({
  title: 'Thai demo',
  blocks: [{ type: 'paragraph', text: 'สวัสดีชาวโลก' }],
  fontEntries: [{ fontData: th, fontRef: '/F3', lang: 'th' }], // /F1 and /F2 are reserved
});
```

This is how the bundled **Noto Sans Math** font existed as a *working runtime
pattern* before it shipped as a default in v1.5.0. Use `compileFontData()` to emit
a reusable `*-data.js` module (byte-identical to `npx pdfnative-build-font`).

**2. Embed agent-generated images.** Image-generating agents (e.g. Antigravity,
ChatGPT, and other multimodal assistants) can pipe a generated PNG/JPEG straight
into a document — via the `image` block (library / CLI) or the `embed_image` MCP
tool. pdfnative parses and embeds it natively (no rasterization) and validates it
at the boundary.

Runtime extensibility is **not** autonomous modification of the published package:
the agent extends its own in-process instance; the repository is only ever changed
by a human under the [AI-governance / human-in-the-loop contract](docs/guides/ai-governance.md).
See the [Agentic workflows guide](docs/guides/agentic-workflows.md) for the full walkthrough.

## Visual PDF Inspection

<a id="sample-pdfs"></a>

Generate sample PDFs for all supported languages to visually verify output:

```bash
npm run test:generate
```

This creates **242 sample PDFs** in `test-output/` (git-ignored), organized in 37 categories produced by 48 generators (including `charts/` native vector charts, `bidi/` Persian and mirroring showcases, `signatures/` LTV pipelines, and `print/` prepress output added in v1.7.0).
See [scripts/README.md](scripts/README.md) for the modular generator architecture.

### Financial Statements (per language)

| File | Content |
|------|---------|
| `sample-latin.pdf` | English / Helvetica |
| `sample-th.pdf` | Thai with GSUB + GPOS shaping |
| `sample-ja.pdf` | Japanese (CJK ideographs) |
| `sample-zh.pdf` | Chinese Simplified |
| `sample-ko.pdf` | Korean (Hangul) |
| `sample-el.pdf` | Greek |
| `sample-hi.pdf` | Hindi (Devanagari) |
| `sample-tr.pdf` | Turkish (İ/ı special casing) |
| `sample-vi.pdf` | Vietnamese (combining marks) |
| `sample-pl.pdf` | Polish (Ł/ł) |
| `sample-ar.pdf` | Arabic (RTL, positional shaping) |
| `sample-he.pdf` | Hebrew (RTL) |
| `sample-ru.pdf` | Russian (Cyrillic) |
| `sample-ka.pdf` | Georgian (Mkhedruli) |
| `sample-hy.pdf` | Armenian |
| `sample-bn.pdf` | Bengali (GSUB conjuncts + GPOS marks) |
| `sample-ta.pdf` | Tamil (GSUB + split vowel decomposition) |
| `sample-multi.pdf` | Mixed: all 22 scripts in one PDF |
| `sample-pagination.pdf` | 200 rows, multi-page layout |

### Diverse Use Cases (non-financial)

| File | Content |
|------|---------|
| `diverse-student-transcript.pdf` | University academic transcript (Latin) |
| `diverse-recipe-th.pdf` | Thai recipe — Tom Yum Goong ingredients (Thai) |
| `diverse-server-ja.pdf` | Server monitoring dashboard (Japanese) |
| `diverse-inventory-zh.pdf` | Warehouse product inventory (Chinese) |
| `diverse-sports-ko.pdf` | K-League football standings (Korean) |
| `diverse-library-el.pdf` | Classical Greek library catalog (Greek) |
| `diverse-medical-hi.pdf` | Blood test lab results (Hindi) |
| `diverse-menu-tr.pdf` | Turkish restaurant dinner menu (Turkish) |
| `diverse-weather-vi.pdf` | Weekly weather forecast — Hanoi (Vietnamese) |
| `diverse-train-pl.pdf` | Train schedule — Warsaw (Polish) |
| `diverse-marketplace-ar.pdf` | Gold marketplace catalog — Dubai (Arabic) |
| `diverse-museum-he.pdf` | Museum exhibition catalog — Jerusalem (Hebrew) |

### Alphabet / Character Coverage

| File | Content |
|------|---------|
| `alphabet-thai.pdf` | 44 consonants, vowels, tone marks, digits |
| `alphabet-japanese.pdf` | Hiragana, Katakana, Kanji numerals & common |
| `alphabet-chinese.pdf` | 121 characters by category (HSK frequency) |
| `alphabet-korean.pdf` | Hangul jamo, syllables, complex clusters |
| `alphabet-greek.pdf` | Full uppercase/lowercase, accented, archaic |
| `alphabet-devanagari.pdf` | Vowels, consonants, matras, conjuncts, digits |
| `alphabet-turkish.pdf` | 29 letters, İ/ı dotted-I distinction test |
| `alphabet-vietnamese.pdf` | 7 base vowels × 6 tones, all diacritics |
| `alphabet-polish.pdf` | 32 letters, digraphs, pangram |
| `alphabet-arabic.pdf` | 28 letters, harakat, numerals, ligatures |
| `alphabet-hebrew.pdf` | 22 letters, final forms, vowel points |
| `alphabet-cyrillic.pdf` | 33 Russian letters, Ukrainian/Serbian extended |
| `alphabet-georgian.pdf` | 33 Mkhedruli letters, Asomtavruli |
| `alphabet-armenian.pdf` | 38 letters, ligatures |
| `alphabet-bengali.pdf` | Vowels, consonants, conjuncts, digits |
| `alphabet-tamil.pdf` | Vowels, consonants, compound characters, digits |

### PDF/A Conformance Variants

| File | Content |
|------|---------|
| `tagged-pdfa2b-default.pdf` | PDF/A-2b (tagged=true, default) |
| `tagged-pdfa2b-explicit.pdf` | PDF/A-2b (tagged='pdfa2b', explicit) |
| `tagged-pdfa1b.pdf` | PDF/A-1b (tagged='pdfa1b', legacy) |
| `tagged-pdfa2u.pdf` | PDF/A-2u (tagged='pdfa2u', Unicode) |
| `tagged-pdfa3b.pdf` | PDF/A-3b (tagged='pdfa3b', embedded file attachments) |

### Encrypted PDFs

| File | Content |
|------|---------|
| `encrypted-aes128.pdf` | AES-128 (V4/R4) owner-only |
| `encrypted-aes256.pdf` | AES-256 (V5/R6) owner-only |
| `encrypted-aes128-user.pdf` | AES-128 with user+owner passwords |
| `encrypted-aes256-user.pdf` | AES-256 with user+owner passwords |
| `encrypted-readonly.pdf` | AES-128 read-only (no copy/modify) |
| `encrypted-noprint.pdf` | AES-128 fully restricted |

**Sample passwords** (for testing only — all documented in `scripts/generate-samples.ts`):

| File | Owner Password | User Password |
|------|---------------|---------------|
| `encrypted-aes128.pdf` | `owner123` | _(none — opens freely)_ |
| `encrypted-aes256.pdf` | `owner256` | _(none — opens freely)_ |
| `encrypted-aes128-user.pdf` | `owner123` | `user456` |
| `encrypted-aes256-user.pdf` | `owner256` | `user789` |
| `encrypted-readonly.pdf` | `owner-ro` | _(none — opens freely)_ |
| `encrypted-noprint.pdf` | `owner-np` | _(none — opens freely)_ |
| `doc-encrypted-aes128.pdf` | `docowner` | `docuser` |
| `doc-encrypted-aes256.pdf` | `strongowner256` | _(none — opens freely)_ |

### Document Builder Samples

| File | Content |
|------|---------|
| `doc-headings-paragraphs.pdf` | H1/H2/H3 + paragraphs with text wrapping |
| `doc-lists.pdf` | Bullet + numbered lists |
| `doc-links.pdf` | External hyperlink annotations |
| `doc-table.pdf` | Embedded table in document |
| `doc-spacer-pagebreak.pdf` | Spacers + forced page breaks (3 pages) |
| `doc-encrypted-aes128.pdf` | Document builder + AES-128 encryption |
| `doc-encrypted-aes256.pdf` | Document builder + AES-256 encryption |
| `doc-image.pdf` | Image embedding (JPEG, centered) |
| `doc-custom-colors.pdf` | Color formats (hex, tuple, PDF operator) |
| `doc-japanese.pdf` | Japanese Unicode document (headings, lists, table) |
| `doc-arabic.pdf` | Arabic RTL document (headings, lists, table, BiDi) |
| `doc-hebrew.pdf` | Hebrew RTL document (headings, lists, table, BiDi) |
| `doc-thai.pdf` | Thai user manual (GSUB+GPOS shaping, pricing table) |
| `doc-bengali.pdf` | Bengali document (GSUB conjuncts + GPOS marks) |
| `doc-tamil.pdf` | Tamil document (GSUB substitution + split vowels) |
| `doc-devanagari.pdf` | Hindi (Devanagari) document — GSUB conjuncts, reph reordering, matra reordering, split vowels |
| `doc-telugu.pdf` | Telugu document (virama conjuncts + GPOS marks, no reph) |
| `doc-sinhala.pdf` | Sinhala document (virama conjuncts + pre-base kombuva reordering) |
| `doc-tibetan.pdf` | Tibetan document (vertical subjoined-consonant stacking) |
| `doc-khmer.pdf` | Khmer document (USE-lite: coeng subscripts, pre-base vowels) |
| `doc-myanmar.pdf` | Myanmar document (USE-lite: medials, pre-base reordering) |
| `doc-amharic.pdf` | Amharic/Ethiopic document (syllabic abugida, no reordering) |
| `doc-chinese-catalog.pdf` | Chinese product catalog (tables, ordering info) |
| `doc-multi-language.pdf` | Multi-language showcase: all 22 Unicode scripts in one PDF |
| `doc-invoice.pdf` | Invoice template (line items, totals, payment link) |
| `doc-report-multipage.pdf` | 3-page technical report (7 sections, 4 tables) |
| `doc-contract-bilingual.pdf` | Bilingual EN/AR contract (legal sections, signatures) |
| `doc-showcase-all-blocks.pdf` | All 13 block types in one PDF |

### Compressed PDFs (FlateDecode)

| File | Content |
|------|---------|
| `compressed-latin-100rows.pdf` | 100-row Latin table (87% smaller) |
| `uncompressed-latin-100rows.pdf` | Same 100-row table without compression (baseline) |
| `compressed-japanese.pdf` | Japanese CIDFont + TTF subset (62% smaller) |
| `compressed-arabic.pdf` | Arabic RTL + GSUB shaping (compressed) |
| `compressed-thai.pdf` | Thai GSUB+GPOS shaping (compressed) |
| `compressed-tagged-pdfa2b.pdf` | FlateDecode + Tagged PDF/A-2b (XMP uncompressed) |
| `compressed-encrypted-aes128.pdf` | FlateDecode + AES-128 encryption |
| `doc-compressed.pdf` | Document builder with FlateDecode |

### Stress Test PDFs

| File | Content |
|------|---------|  
| `stress-test-10k-rows.pdf` | 10,000-row table (167 pages, 4.3MB) |
| `doc-extreme-bidi-wrapping.pdf` | Extreme BiDi mixed-script text wrapping |
| `table-heavy-text-overflow.pdf` | Dense table with heavy text overflow |
| `media-rich-document.pdf` | Media-rich document with multiple images |
| `tagged-accessibility-complex.pdf` | Complex tagged PDF/A accessibility tree |
| `layout-extreme-customization.pdf` | Extreme layout customization (margins, columns, colors) |

### Edge-Case Stress Tests

| File | Content |
|------|---------|  
| `doc-unbreakable-text.pdf` | 1000-char words with no spaces (DNA, URL, Base64) |
| `table-micro-columns.pdf` | Extreme column fractions (f=0.025, mx=1) |
| `doc-link-annotation-bomb.pdf` | 500 link annotations across 10 pages |
| `zero-content-empty-table.pdf` | Table with headers but 0 rows |
| `zero-content-empty-doc.pdf` | Document with no blocks |
| `zero-content-empty-strings.pdf` | Empty headings, paragraphs, and list items |
| `doc-heavy-buffer-5mb.pdf` | 5 MB synthetic JPEG embedded (memory stress) |

### Barcode & QR Code Samples

| File | Content |
|------|---------|
| `barcode-showcase.pdf` | All 5 formats: Code 128, EAN-13, QR Code, Data Matrix, PDF417 |
| `barcode-alignment-sizing.pdf` | Alignment (left/center/right) and custom size variations |
| `barcode-tagged-pdfa.pdf` | Barcodes in tagged PDF/A-2b mode (/Figure structure elements) |

### SVG Path Rendering Samples

| File | Content |
|------|---------|
| `svg-basic-shapes.pdf` | Rect, circle, ellipse, line, polyline, polygon |
| `svg-complex-paths.pdf` | Cubic/quadratic Bézier curves, arcs, combined paths |
| `svg-tagged-pdfa.pdf` | SVG elements in tagged PDF/A-2b mode |

### Form Field Samples

| File | Content |
|------|---------|
| `form-fields.pdf` | All field types: text, multiline, checkbox, radio, dropdown, listbox |
| `form-contact.pdf` | Contact form with name, email, message, and submit fields |

### Digital Signature Samples

| File | Content |
|------|---------|
| `sig-rsa-self-signed.pdf` | RSA PKCS#1 v1.5 self-signed signature |
| `sig-ecdsa-p256.pdf` | ECDSA P-256 digital signature |
| `sig-multi-field.pdf` | PDF with multiple signature fields |

### Streaming Output Samples

| File | Content |
|------|---------|
| `streaming-document.pdf` | Document streamed via `buildDocumentPDFStream()` |
| `streaming-table.pdf` | Table streamed via `buildPDFStream()` |

### PDF Parser & Modifier Samples

| File | Content |
|------|---------|
| `parser-original.pdf` | Generated → parsed → verified round-trip |
| `parser-modified.pdf` | Generated → parsed → modified → incremental save |
| `parser-document.pdf` | Document builder → parser round-trip verification |

### Outline & Page Label Samples (v1.4.0)

| File | Content |
|------|---------|
| `outline/outline-explicit.pdf` | Nested bookmarks (`/Outlines`) + roman/decimal page labels |
| `outline/outline-auto.pdf` | `outline: 'auto'` — bookmarks derived from headings |
| `outline/page-labels.pdf` | Roman front matter + prefixed appendix page labels |

### PDF Manipulation Samples (v1.4.0)

| File | Content |
|------|---------|
| `manipulation/merged.pdf` | `mergePdfs()` — multiple documents combined |
| `manipulation/split-report.pdf` | `splitPdf()` — first page range |
| `manipulation/split-invoice.pdf` | `splitPdf()` — second page range |
| `manipulation/extract-reordered.pdf` | `extractPages()` — selected pages, reordered |
| `manipulation/streamed.pdf` | `streamToFile()` — document streamed straight to disk |

## API Reference

### Core

| Function | Description |
|----------|-------------|
| `buildPDF(params, layout?)` | Build table-centric PDF as binary string |
| `buildPDFBytes(params, layout?)` | Build table-centric PDF as `Uint8Array` |
| `buildDocumentPDF(params, layout?)` | Build free-form document PDF as binary string |
| `buildDocumentPDFBytes(params, layout?)` | Build free-form document PDF as `Uint8Array` |
| `wrapText(text, maxWidth, fontSize, enc)` | Word-wrap text into lines |
| `createPDF(params, options?)` | Smart dispatch (Worker or main thread) |
| `initNodeCompression()` | Initialize native zlib for ESM (call once before `compress: true`) |
| `downloadBlob(bytes, filename)` | Trigger browser download |
| `toBytes(str)` | Convert binary string to `Uint8Array` |
| `slugify(str)` | Sanitize string for filename |

### Image Support

| Function | Description |
|----------|-------------|
| `parseImage(bytes)` | Auto-detect and parse JPEG or PNG |
| `parseJPEG(bytes)` | Parse JPEG image (DCTDecode) |
| `parsePNG(bytes)` | Parse PNG image (FlateDecode) |
| `detectImageFormat(bytes)` | Detect JPEG or PNG from magic bytes |
| `buildImageXObject(img, smaskObj?)` | Build PDF Image XObject dictionary |
| `buildImageOperators(ref, x, y, w, h)` | Build `q cm Do Q` content stream operators |

### Link Annotations

| Function | Description |
|----------|-------------|
| `validateURL(url)` | Validate URL scheme (http/https/mailto only) |
| `buildLinkAnnotation(annot)` | Build PDF /Link annotation with /URI action |
| `buildInternalLinkAnnotation(link)` | Build PDF /Link with /GoTo action |
| `isLinkAnnotation(annot)` | Type guard for LinkAnnotation |

### BiDi & Arabic/Hebrew Shaping

| Function | Description |
|----------|-------------|
| `resolveBidiRuns(text)` | Resolve text into BiDi runs with levels |
| `containsRTL(text)` | Check if text contains RTL characters |
| `shapeArabicText(str, fontData)` | Arabic GSUB positional shaping |
| `containsArabic(text)` | Check for Arabic characters |
| `containsHebrew(text)` | Check for Hebrew characters |

### Barcode & QR Code

| Function | Description |
|----------|-------------|
| `renderBarcode(format, data, x, y, opts?)` | Unified barcode renderer (dispatches to format-specific function) |
| `encodeCode128(data)` | Encode data into Code 128 barcode pattern (ISO 15417) |
| `renderCode128(data, x, y, w, h)` | Render Code 128 barcode as PDF path operators |
| `ean13CheckDigit(digits)` | Compute EAN-13 check digit (ISO 15420) |
| `renderEAN13(data, x, y, w, h)` | Render EAN-13 barcode with guard bars and digits |
| `generateQR(data, ecLevel?)` | Generate QR Code matrix (ISO 18004) |
| `renderQR(data, x, y, size, ecLevel?)` | Render QR Code as PDF path operators |
| `generateDataMatrix(data)` | Generate Data Matrix ECC 200 matrix (ISO 16022) |
| `renderDataMatrix(data, x, y, size)` | Render Data Matrix as PDF path operators |
| `encodePDF417(data, ecLevel?)` | Encode data into PDF417 codewords (ISO 15438) |
| `renderPDF417(data, x, y, w, h, ecLevel?)` | Render PDF417 barcode as PDF path operators |

### SVG Rendering

| Function | Description |
|----------|-------------|
| `parseSvgPath(d)` | Parse SVG path `d` attribute into segments |
| `renderSvg(segments, options?)` | Render SVG segments (paths + `<text>`) as PDF operators |

### Markup Annotations

| Function | Description |
|----------|-------------|
| `buildAnnotation(annot, objNum)` | Build a full markup annotation indirect object (v1.5.0) |
| `buildAnnotationBody(annot)` | Build a markup annotation dictionary body (for the modifier) (v1.5.0) |

Supported `MarkupAnnotation` types: `text`, `highlight`, `underline`, `strikeout`, `squiggly`, `square`, `circle`, `line`, `freetext`.

### Layout Debug & Inspection

| Function | Description |
|----------|-------------|
| `inspectDocumentLayout(params, layout?)` | Return a programmatic per-page block-geometry `LayoutInspection` (v1.5.0) |

Enable the visual overlay via `layout: { debug: true }` or a granular `LayoutDebugOptions` (`showMargins` / `showContentBounds` / `showCells`). Byte-identical when debug is off.

### Font-Data Tools (`pdfnative/tools`)

| Function | Description |
|----------|-------------|
| `compileFontData(buffer, opts?)` | Compile a TTF/OTF `Uint8Array` into a font-data module source string (v1.5.0) |
| `parseFontData(buffer, opts?)` | Parse a TTF/OTF `Uint8Array` into a `FontDataObject` (metrics, cmap, widths, glyph coverage) (v1.5.0) |

### AcroForm Fields

| Function | Description |
|----------|-------------|
| `buildFormWidget(field, objNum, pageRef)` | Build form field widget annotation + appearance stream |
| `buildAcroFormDict(fieldRefs)` | Build `/AcroForm` dictionary for catalog |
| `buildRadioGroupParent(group)` | Build radio button group parent object |
| `buildAppearanceStreamDict(width, height)` | Build appearance stream dictionary |
| `defaultFieldHeight(type)` | Default height by field type |

### Digital Signatures

| Function | Description |
|----------|-------------|
| `buildSigDict(options)` | Build `/Sig` dictionary with ByteRange/Contents placeholders (`subFilter: 'ETSI.CAdES.detached'` for PAdES, v1.7.0) |
| `buildDocTimeStampDict(contentsSize?)` | Build a `/DocTimeStamp` dictionary variant (ISO 32000-2 §12.8.5, v1.7.0) |
| `signPdfBytes(pdf, options)` | Sign a PDF with CMS/PKCS#7 detached signature (`profile: 'pades'`, `digestAlgorithm`, multi-signature `fieldName` selector, v1.7.0) |
| `signPdfBytesWithTimestamp(pdf, options)` | Sign + embed a verified RFC 3161 signature timestamp (PAdES B-T, v1.7.0) |
| `listSignatures(pdf)` | Enumerate signature fields — SubFilter, ByteRange, /Contents, placeholder/timestamp flags (v1.7.0) |
| `collectValidationInfo(pdf, opts?)` | Gather certificates + OCSP/CRL material for every signature via the injected `RevocationProvider` (v1.7.0) |
| `embedValidationInfo(pdf, data)` | Write pre-collected LTV material as `/DSS` + `/VRI` — sync, offline, deterministic (v1.7.0) |
| `addValidationInfo(pdf, opts?)` | Collect + embed in one call (PAdES B-LT, v1.7.0) |
| `addDocumentTimestamp(pdf, opts?)` | Append a `/DocTimeStamp` revision (PAdES B-LTA, v1.7.0) |
| `estimateContentsSize(certSizes, algorithm?, opts?)` | Estimate `/Contents` size (`{ timestamp: true }` adds RFC 3161 headroom, v1.7.0) |
| `setCryptoProvider(provider)` | Install (or clear with `null`) a global native signature provider (v1.4.0) |
| `getCryptoProvider()` | Return the current global `CryptoProvider`, or `null` (v1.4.0) |
| `setTimestampProvider(provider)` / `getTimestampProvider()` | Global RFC 3161 transport — TimeStampReq bytes in, TimeStampResp bytes out (v1.7.0) |
| `setRevocationProvider(provider)` / `getRevocationProvider()` | Global OCSP/CRL transport (v1.7.0) |

### Streaming Output

| Function | Description |
|----------|-------------|
| `buildDocumentPDFStream(params, layout?, streamOpts?)` | Stream document PDF as `AsyncGenerator<Uint8Array>` |
| `buildPDFStream(params, layout?, streamOpts?)` | Stream table PDF as `AsyncGenerator<Uint8Array>` |
| `buildDocumentPDFStreamTrue(params, layout?, streamOpts?)` | **True constant-memory** document streaming — frees each part as it yields (v1.3.0) |
| `buildPDFStreamTrue(params, layout?, streamOpts?)` | **True constant-memory** table streaming (v1.3.0) |
| `buildDocumentPDFStreamPageByPage(params, layout?)` | Stream document PDF chunked at PDF object boundaries |
| `buildPDFStreamPageByPage(params, layout?)` | Stream table PDF chunked at PDF object boundaries |
| `validateDocumentStreamable(params, layout?)` | Validate document is compatible with streaming (no TOC, no `{pages}`) |
| `validateTableStreamable(params, layout?)` | Validate table is compatible with streaming |
| `chunkBinaryString(str, chunkSize)` | Split binary string into `Uint8Array` chunks |
| `concatChunks(chunks)` | Concatenate `Uint8Array` chunks into one |
| `streamByteLength(stream)` | Count total bytes from an async stream |
| `streamToFile(stream, filePath, opts?)` | Drain an `AsyncGenerator<Uint8Array>` to disk with back-pressure + `AbortSignal` (Node) — returns `{ bytesWritten, path }` (v1.4.0) |

### Crypto (Hashing, ASN.1, RSA, ECDSA, X.509, CMS)

| Function | Description |
|----------|-------------|
| `sha1(data)` | SHA-1 — `/VRI` keying and OCSP CertID identification only, never a security digest (v1.7.0) |
| `sha384(data)` / `sha512(data)` | SHA-384 / SHA-512 hash (FIPS 180-4) |
| `hmacSha256(key, data)` | HMAC-SHA-256 (RFC 2104) |
| `derDecode(data)` | Decode DER-encoded ASN.1 |
| `derSetOf(...values)` / `derGeneralizedTime(date)` | Canonical DER SET OF (X.690 §11.6) / GeneralizedTime encoder (v1.7.0) |
| `rsaSign(msg, key, digest?)` / `rsaVerify(msg, sig, key, digest?)` | RSA PKCS#1 v1.5 sign/verify — SHA-256/384/512 (digest param v1.7.0) |
| `ecdsaSign(hash, key)` / `ecdsaVerify(hash, sig, key)` | ECDSA P-256 sign/verify |
| `parseCertificate(der)` | Parse X.509 DER certificate — incl. SKI/AKI, EKU, AIA (OCSP/caIssuers URLs), CRL distribution points (v1.7.0) |
| `certHasEku(cert, oid)` | Check an extended-key-usage OID (v1.7.0) |
| `buildCmsSignedData(options)` | Build CMS SignedData — PKCS#7 or PAdES profile, SHA-256/384/512 (v1.7.0) |
| `parseCmsSignedData(der)` / `addUnsignedAttribute(cms, attr)` / `buildAttribute(oid, ...v)` | CMS inspection + unsigned-attribute surgery, signed bytes untouched (v1.7.0) |
| `buildTimestampRequest(imprint, opts?)` / `parseTimestampResponse(der)` / `parseTimestampToken(der)` / `verifyTimestampImprint(info, hash)` | RFC 3161 timestamp protocol (v1.7.0) |
| `buildOcspRequest(cert, issuer, opts?)` / `parseOcspResponse(der)` | OCSP RFC 6960 (v1.7.0) |
| `parseCrl(der)` / `isSerialRevoked(crl, serial)` | CRL RFC 5280 (v1.7.0) |
| `initCrypto()` | Initialize crypto module (lazy load) |

### PDF Parser & Modifier

| Function | Description |
|----------|-------------|
| `openPdf(bytes, opts?)` | Parse a PDF `Uint8Array` and return a `PdfReader`. Pass `{ password }` to open an encrypted document (RC4, AES-128, AES-256) |
| `createModifier(reader)` | Create an incremental `PdfModifier` from a `PdfReader` |
| `createTokenizer(data, offset?)` | Create a low-level PDF tokenizer |
| `parseValue(tok)` | Parse a single PDF value from token stream |
| `parseIndirectObject(tok)` | Parse an indirect object (`N M obj ... endobj`) |
| `findStartxref(data)` | Find `startxref` offset in PDF bytes |
| `parseXrefTable(data, offset)` | Parse xref table/stream at given offset |
| `isRef(v)` / `isDict(v)` / `isArray(v)` / `isStream(v)` | Type guards for parsed PDF values |
| `dictGet(dict, key)` / `dictGetName(dict, key)` | Dictionary value accessors |
| `inflateSync(data)` | Decompress FlateDecode data (zlib inflate) |
| `validatePdfUA(bytes)` | Read-only PDF/UA structural checker — returns `{ valid, errors, warnings }` (v1.3.0) |
| `mergePdfs(sources, opts?)` | Merge multiple PDFs into one, rebuilding a clean object graph; `opts.maxOutputSize` caps output at 256 MiB by default (v1.4.0); `opts.encrypt` re-encrypts the output (AES-128/AES-256, v1.6.0) |
| `splitPdf(src, ranges, opts?)` | Split a PDF into multiple documents by inclusive 0-based page ranges (v1.4.0) |
| `extractPages(src, indices, opts?)` | Extract specific pages (0-based) into a new PDF (v1.4.0) |
| `reader.getPageLabels()` | Parse an existing `/PageLabels` number tree into `PageLabelRange[]` or `null` (v1.5.0) |
| `reader.getAnnotations(pageIndex)` | Read a page's annotations into `ParsedAnnotation[]` (v1.5.0) |
| `reader.getPageRef(pageIndex)` | Get the indirect `PdfRef` for a page (v1.5.0) |
| `modifier.addAnnotation(pageIndex, body)` | Inject a new annotation on a page via incremental update (v1.5.0) |
| `extractText(bytes, opts?)` | Extract per-page reading-order Unicode text (+ optional positioned runs) from any PDF, incl. encrypted (`opts.password`); `ToUnicode`/`Differences`/WinAnsi/MacRoman decoding, hard `maxTextLength` memory cap (v1.6.0) |

### Document Block Types

| Type | Description |
|------|-------------|
| `HeadingBlock` | H1/H2/H3 with color, auto-wrapped |
| `ParagraphBlock` | Text with fontSize, lineHeight, align, indent, color |
| `TableBlock` | Headers + rows using PdfRow/ColumnDef |
| `ListBlock` | Bullet or numbered items; entries may be plain strings or nested `ListItem` `{ text, items }` for hierarchical lists (v1.4.0) |
| `ImageBlock` | JPEG/PNG with optional width, height, align, alt text |
| `LinkBlock` | Hyperlink with URL, blue underline, tagged /Link |
| `SpacerBlock` | Vertical whitespace |
| `PageBreakBlock` | Force new page |
| `TocBlock` | Auto-generated table of contents with /GoTo links |
| `BarcodeBlock` | Barcode / QR code rendered via PDF path operators |
| `SvgBlock` | SVG path/shape rendering as native PDF path operators |
| `FormFieldBlock` | AcroForm interactive fields (text, checkbox, radio, dropdown, listbox) |

### Tagged PDF & PDF/A

| Function | Description |
|----------|-------------|
| `resolvePdfAConfig(tagged)` | Resolve tagged option → PDF/A config (version, part, conformance) |
| `encodePdfTextString(str)` | Encode string as PDF text (PDFDocEncoding or UTF-16BE hex) |

### Encryption

Encryption is configured via the `encryption` option in layout options. Since v1.6.0 the reader side is public too — `openPdf(bytes, { password })` plus the `PdfPasswordError`, `PdfEncryptionUnsupportedError` and `PdfEncryptionInfo` exports.

```typescript
const pdf = buildPDFBytes(params, {
  encryption: { userPassword: 'secret', ownerPassword: 'admin', permissions: { print: true } }
});
```

### Color Utilities

| Function | Description |
|----------|-------------|
| `parseColor(input)` | Parse hex / tuple / PDF string → validated PDF RGB string |
| `isValidPdfRgb(str)` | Check if string is valid `"R G B"` format (0.0–1.0) |
| `normalizeColors(colors)` | Validate and normalize all fields in a PdfColors object |

### Compression

| Function | Description |
|----------|-------------|
| `initNodeCompression()` | Initialize native zlib (async, call once in ESM before `compress: true`) |
| `setDeflateImpl(fn)` | Inject custom DEFLATE function (e.g. for browser polyfill) |

**Browser compression** — In browser environments without native zlib, inject a third-party DEFLATE via `setDeflateImpl`:

```typescript
import { setDeflateImpl, buildPDFBytes } from 'pdfnative';
import { deflateSync } from 'fflate'; // or pako

setDeflateImpl(deflateSync);

const pdf = buildPDFBytes(params, { compress: true });
```

### Fonts

| Function | Description |
|----------|-------------|
| `registerFont(lang, loader)` | Register a font data loader |
| `registerFonts(map)` | Register multiple font loaders |
| `loadFontData(lang)` | Lazy-load font data (cached) |
| `hasFontLoader(lang)` | Check if loader is registered |
| `getRegisteredLangs()` | List registered language codes |
| `createEncodingContext(fontEntries)` | Create encoding context |
| `validateFontData(data)` | Opt-in structural validation of custom font data — returns `{ valid, errors, warnings }` (v1.4.0) |

### Shaping

| Function | Description |
|----------|-------------|
| `shapeThaiText(str, fontData)` | Thai OpenType shaping (GSUB + GPOS) |
| `shapeBengaliText(str, fontData)` | Bengali GSUB conjuncts + GPOS marks |
| `shapeTamilText(str, fontData)` | Tamil GSUB + split vowel decomposition |
| `shapeDevanagariText(str, fontData)` | Devanagari cluster shaping + GSUB/GPOS |
| `shapeTeluguText(str, fontData)` | Telugu GSUB conjuncts + GPOS marks (v1.3.0) |
| `shapeSinhalaText(str, fontData)` | Sinhala conjuncts + pre-base reorder + GSUB/GPOS (v1.3.0) |
| `shapeTibetanText(str, fontData)` | Tibetan vertical subjoined stacking (v1.3.0) |
| `shapeKhmerText(str, fontData)` | Khmer USE-lite — coeng subscripts + pre-base vowels (v1.3.0) |
| `shapeMyanmarText(str, fontData)` | Myanmar USE-lite — medials + virama stacking (v1.3.0) |
| `detectFallbackLangs(texts, primaryLang)` | Detect needed fallback fonts |
| `detectCharLang(codePoint)` | Map codepoint to preferred font language |
| `splitTextByFont(str, fontEntries)` | Multi-font text run splitting |
| `needsUnicodeFont(str)` | Check if text needs CIDFont |
| `containsThai(str)` | Check for Thai characters |
| `resolveBidiRuns(text)` | Resolve BiDi runs (UAX #9) |
| `containsRTL(text)` | Detect RTL content |
| `shapeArabicText(str, fontData)` | Arabic GSUB positional shaping |
| `containsArabic(text)` | Detect Arabic content |
| `containsHebrew(text)` | Detect Hebrew content |
| `containsTelugu(text)` | Detect Telugu content (v1.3.0) |
| `isTeluguCodepoint(cp)` | Telugu codepoint predicate (v1.3.0) |
| `containsSinhala(text)` / `containsTibetan(text)` / `containsKhmer(text)` / `containsMyanmar(text)` / `containsEthiopic(text)` | Detect script content (v1.3.0) |
| `isSinhalaCodepoint(cp)` / `isTibetanCodepoint(cp)` / `isKhmerCodepoint(cp)` / `isMyanmarCodepoint(cp)` / `isEthiopicCodepoint(cp)` | Codepoint predicates (v1.3.0) |
| `containsMath(text)` / `isMathCodepoint(cp)` | Detect / test mathematical symbols → lang `'math'` (v1.5.0) |

### Layout Constants

| Constant | Description |
|----------|-------------|
| `PG_W` / `PG_H` | A4 page dimensions (points) |
| `DEFAULT_MARGINS` | Default margins `{ t, r, b, l }` |
| `DEFAULT_COLORS` | Default color palette |
| `DEFAULT_COLUMNS` | Default 5-column layout |
| `ROW_H` / `TH_H` | Row / header heights |
| `HEADER_H` | Header zone height (15pt) |
| `PAGE_SIZES` | Preset page dimensions (A4, Letter, Legal, A3, Tabloid) |
| `resolveTemplate(tpl, page, pages, title, date)` | Resolve header/footer template placeholders |

## Ecosystem

pdfnative ships as a library, but three official companion packages cover the most common non-library use cases — a CLI, an MCP server, and a React renderer. All live in separate repositories and depend on `pdfnative` only through the public API, so the core library stays zero-dependency.

### pdfnative-cli — command-line interface

[`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) v1.4.0 is the **official CLI**, built on `pdfnative` v1.7.0. It exposes 21 commands in five groups — create & edit (`render`, `fill`, `annotate`, `metadata`), page tree (`merge`, `split`, `extract`), security (`sign`, `verify`, `ltv`, `doc-timestamp`, `encrypt`, `decrypt`), read & extract (`inspect`, `extract-text`, `compare`), and automation & meta (`batch`, `doctor`, `schema`, `completion`, `govern`) — for use in shell scripts, Makefiles, GitHub Actions, and Docker images. Zero extra runtime dependencies, npm-provenance-signed, with a CycloneDX SBOM attached to every release. Requires Node ≥ 22.

**New in v1.1.0:** **22 Unicode scripts + COLRv1 colour emoji** through the `--font`/`--lang` shortcuts, **true constant-memory streaming** (`--stream-true`), a `--max-blocks` cap for very large documents, and a **PDF/UA (ISO 14289-1) structural validator** (`inspect --pdfua` / `--check pdfua`). It also adds an **agent-native contract** — a global `--json` status/error envelope, stable `E_*` error codes, a `--dry-run` validation mode, the new **`schema`** command (Draft 2020-12), and token-economy output projection (`--summary` / `--fields` + compact JSON) that cuts agent output ~90 %. **100 % backward-compatible.**

<!-- verify-docs:allow version-token (historical: CLI v1.2.0 shipped on the pdfnative 1.5.0 engine) -->
**New in v1.2.0:** five new commands — **`merge`**, **`split`**, **`extract`** (page-tree manipulation via pdfnative 1.5.0), **`annotate`** (markup annotations via incremental save, so existing signatures stay intact), and **`govern`** (the AI-governance / Human-in-the-Loop contract: `govern rules` / `govern policy` / `govern verify-issue`, with a stable `E_POLICY` error code). Plus PDF bookmarks (`--outline auto` or an explicit tree), the bundled math font (`--font math`), layout introspection (`--inspect-layout` / `--debug-layout`), and native constant-time crypto by default in `sign` (opt out with `--pure-crypto`).

**New in v1.3.0:** five more commands on the pdfnative 1.6 engine — **`fill`** (fill, flatten, and export existing AcroForms via incremental save, encrypted PDFs included), **`encrypt`** / **`decrypt`** (AES-128/256 re-securing and password removal; RC4 never emitted), **`extract-text`** (reading-order Unicode text as text/JSON/NDJSON, `--runs`, `--password`), and **`doctor`** (offline environment preflight). Also native vector charts in `render`, `--password` + `--encrypt` re-encryption on merge/split/extract, an agent capability manifest (`schema manifest` + `llms.txt`), and PowerShell completion.

**New in v1.4.0:** the **complete PAdES ladder** from the shell — `sign --timestamp <tsa-url>` (RFC 3161, B-T), **`ltv`** (B-LT `/DSS`; `collect` gathers revocation evidence as replayable JSON so `embed` can run fully offline in air-gapped environments), and **`doc-timestamp`** (B-LTA document-timestamp revisions) — plus **`metadata`** (signature-safe `/Info` + XMP edits), **`compare`** (text + structure diff with CI exit codes), **`batch --manifest`** declarative pipelines with `@id` references and an `--allow-network` opt-in, `render --strict` PDF/A gating, `inspect --signatures`, RSA-SHA384/512, and a global `--max-inflate-size` zip-bomb cap. Every network path is an explicit opt-in behind an SSRF guard. Built on pdfnative 1.7.0, Node ≥ 22.

```bash
# render with full layout coverage (encryption + watermark + PDF/A-2b)
npx pdfnative-cli render --input doc.json --output report.pdf \
  --tagged pdfa2b --compress \
  --watermark-text "DRAFT" --watermark-opacity 0.15

# sign with metadata and intermediate cert chain
npx pdfnative-cli sign --input report.pdf --output signed.pdf \
  --reason "Approved" --name "Finance Team" \
  --signing-time 2026-04-28T10:00:00Z \
  --cert-chain intermediate.pem

# verify embedded signatures (byte-range + chain + trust + revocation)
npx pdfnative-cli verify --input signed.pdf --strict --trust ca-root.pem

# inspect with CI assertions, incl. PDF/UA accessibility gate (exit 1 on failure)
npx pdfnative-cli inspect --input signed.pdf \
  --check pdfa --check signed --check pdfua --json --summary
```

<!-- verify-docs:allow version-token (pdfnative-cli's own current version, not the engine) -->
See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for the full v1.4.0 reference, agent contract, security model, and recipes. Try the [interactive CLI playground](https://pdfnative.dev/playgrounds/cli.html) to build commands without leaving the browser.

### pdfnative-mcp — Model Context Protocol server

[`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) v1.6.0 is a **Model Context Protocol server** that bridges pdfnative to any MCP-compatible AI client. Once configured, your AI assistant can generate PDFs and native vector charts, embed barcodes, create, read, fill and flatten forms, sign documents through the complete PAdES ladder (B-B → B-LTA with RFC 3161 timestamps and embedded revocation material), verify signatures and document timestamps, encrypt and decrypt PDFs, validate PDF/UA structure, embed and extract attachments, extract Unicode text, render international text, merge, split and extract pages, annotate existing PDFs, rewrite document metadata, preview pagination without producing a PDF, draft governance-compliant GitHub issues (human-in-the-loop), and inspect existing PDFs — all without writing code.

<!-- verify-docs:allow stale-token (historical: MCP v1.0.0 shipped 12 tools) -->
**v1.0.0:** first stable MCP release with 12 tools, `verify_pdf`, `add_attachment` (Factur-X / ZUGFeRD PDF/A-3), `extract_text`, smart-table options, auto-placeholder signing, and `_meta.apiVersion`.

**v1.1.0:** adds `validate_pdf`, six additional scripts (Telugu, Sinhala, Tibetan, Khmer, Myanmar, Ethiopic), and COLRv1 colour-emoji support via the pdfnative 1.3.0 engine. <!-- verify-docs:allow version-token (historical engine reference) -->

**v1.2.0:** adds `extract_attachments`, watermark options on document tools, Unicode `normalize` (NFC/NFD/NFKC/NFKD), token-frugal read modes (`verbosity`/`fields`), and returns base64 PDF bytes once via a `resource` block.

**v1.3.0:** adds the page-tree trio `merge_pdfs` / `split_pdf` / `extract_pages` (**17 tools** total)<!-- verify-docs:allow stale-token (historical: MCP v1.3.0 total) -->, enriched authoring options (`outline`, `pageLabels`, nested lists, `viewerPreferences`, `cellBorders`, `cellVAlign`), a constant-time `node:crypto` signing provider, and DNS-rebinding protection on the HTTP transport — all via the pdfnative 1.4.0 engine.

**v1.4.0:** adds `annotate_pdf` (markup via incremental update) and the network-free `draft_governance_issue` (**19 tools**)<!-- verify-docs:allow stale-token (historical: MCP v1.4.0 total, on the pdfnative 1.5.0 engine) -->, the MCP `prompts` capability (`governance_contract`, `draft_issue_workflow`), `pageLabels[]` in `inspect_pdf`, and the explicit `math` script — via the pdfnative 1.5.0 engine.

**v1.5.0:** adds `add_chart`, `read_form_fields`, `fill_form`, `encrypt_pdf`, `decrypt_pdf` (**24 tools**)<!-- verify-docs:allow stale-token (historical: MCP v1.5.0 total) -->, `password` support on the read-only and page-tree tools, MCP resources (`pdfnative://output/…`), and tool annotations — via the pdfnative 1.6.0 engine.

**v1.6.0:** adds `add_ltv`, `timestamp_pdf`, `update_metadata`, `inspect_layout` (**28 tools**), all 13 block kinds in `generate_basic_pdf`, layout options and build-time `encrypt` on the document tools, image watermarks, print production, charts v2, honest PDF/A (`embedFonts` / `strict` / diagnostics), PAdES timestamps on `sign_pdf`, four new recipe prompts, and the MCP 2026-07-28 spec — via the pdfnative 1.7.0 engine.

```bash
npx -y pdfnative-mcp
```

### Available tools

| Tool | Purpose |
|------|---------|
| `generate_basic_pdf` | Multi-page documents from structured blocks — all 13 block kinds since v1.6.0 (incl. tables, images, links, TOC, barcodes, SVG, form fields); optional `outline`, `pageLabels`, `pdfA`, layout options, build-time `encrypt`, print production |
| `add_table` | Smart tables (`wrap`, `repeatHeader`, `zebra`, `caption`, `minRowHeight`, `cellPadding`, `cellBorders`, `cellVAlign`) |
| `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 |
| `add_international_text` | 25 `lang` font codes (22 Unicode scripts + `latin` + `emoji` + explicit `math`) with BiDi and OpenType shaping |
| `add_form` | Interactive AcroForm PDFs (`text`, `textarea`, `checkbox`, `radio`, `dropdown`, `listbox` since v1.6.0) |
| `embed_image` | Embed a JPEG or PNG image (base64), with `align` / `alt` since v1.6.0 |
| `prepare_signature_placeholder` | PDF with a `/Sig` field ready to be signed (optional — `sign_pdf` auto-injects one); `subFilter` / `reserveTimestamp` since v1.6.0 |
| `sign_pdf` | PAdES CMS signatures (RSA-SHA256/384/512 / ECDSA-SHA256 P-256); `profile: 'pades'`, RFC 3161 `timestamp`, cert chains, multiple signatures since v1.6.0 |
| `add_ltv` | Embed `/DSS` + `/VRI` long-term-validation material — PAdES B-LT (v1.6.0) |
| `timestamp_pdf` | Append a `/DocTimeStamp` through the operator TSA — PAdES B-LTA (v1.6.0) |
| `validate_pdf` | Read-only PDF/UA structural validation |
| `verify_pdf` | Verify every PAdES signature and `/DocTimeStamp` (integrity + value + optional chain trust; `ltv: true` reports the achieved PAdES level since v1.6.0) |
| `add_attachment` | PDF/A-3 with embedded files (Factur-X / ZUGFeRD) |
| `extract_attachments` | Extract embedded files (optionally metadata-only) |
| `extract_text` | Unicode text extraction (positioned runs; `password` since v1.5.0) |
| `merge_pdfs` | Concatenate 2–50 PDFs (encrypted sources via `password`; re-encrypt since v1.5.0) |
| `split_pdf` | Split one PDF into one document per page range |
| `extract_pages` | Pull an arbitrary, order-preserving page subset into a new PDF |
| `annotate_pdf` | Overlay markup annotations (9 types) via incremental update; not a redaction |
| `draft_governance_issue` | Governance-compliant GitHub-issue draft, network-free, never submits (HITL) |
| `add_chart` | Native vector charts, zero rasterisation — nine types since v1.6.0 (bar, horizontal bar, stacked bar, stacked horizontal bar, line, area, scatter, pie, donut), dual axis, log & time scales |
| `read_form_fields` | List an existing AcroForm's fields (types, values, options) |
| `fill_form` | Fill and optionally flatten an existing AcroForm (encrypted PDFs supported) |
| `encrypt_pdf` | Re-secure with AES-128/AES-256, owner/user passwords + permissions |
| `decrypt_pdf` | Remove encryption in-server (RC4 / AES-128 / AES-256 sources) |
| `update_metadata` | Rewrite `/Info` (+ XMP) of an existing PDF via incremental update (v1.6.0) |
| `inspect_pdf` | Structured report (metadata, pages, signatures, PDF/A, attachments, `encryptionInfo`, `pageLabels`; annotation and signature inventories, `dss`, page boxes since v1.6.0) |
| `inspect_layout` | Read-only pagination dry run — page count and block geometry, no PDF produced (v1.6.0) |

### Claude Desktop configuration

```json
{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs"
      }
    }
  }
}
```

See the [MCP Integration Guide](https://pdfnative.dev/guides/mcp.html) and the [pdfnative-mcp repository](https://github.com/Nizoka/pdfnative-mcp) for configuration on Cursor, Continue, Zed, and more.

### pdfnative-react — declarative JSX renderer

[`pdfnative-react`](https://github.com/Nizoka/pdfnative-react) v1.2.0 turns declarative **JSX** into real, on-device PDFs powered by the zero-dependency pdfnative engine — no DOM, no headless browser, no SaaS round-trips. A custom React reconciler compiles your component tree synchronously into the pdfnative block model. v1.2.0 follows the pdfnative 1.7.0 engine: charts v2 (9 kinds, secondary axis, log/time scales, data labels), print production via `<Document print>`, the PDF/A diagnostics channel (`layout.strict` / `onDiagnostic`), HTTP caching on `renderToResponse` (`etag` / `cacheControl`), and 25 lint rules — all additive. Requires **React 19**, **pdfnative ^1.7.0** and **Node.js ≥ 22**. React and pdfnative are peer dependencies; the package itself adds one runtime dependency, `react-reconciler`. The pdfnative engine remains dependency-free.

```tsx
import { Document, Heading, Text, Table, renderToBytes } from 'pdfnative-react';

const bytes = renderToBytes(
  <Document title="Invoice #1024" footerText="Acme Inc">
    <Heading level={1}>Invoice #1024</Heading>
    <Text>Thank you for your business.</Text>
    <Table
      headers={['Item', 'Qty', 'Total']}
      rows={[{ cells: ['Pro plan', '1', '$49.00'], type: 'default', pointed: false }]}
      zebra
    />
  </Document>,
); // → Uint8Array, a valid PDF
```

Every component (`Document`, `Page`, `Section`, `Heading`, `Paragraph`/`Text`, `List`/`Item`, `Table`/`Row`/`Cell`, `Image`, `Link`, `Spacer`, `PageBreak`, `TableOfContents` (alias `Toc`), `Barcode`, `Svg`, `Chart`, `FormField`) maps 1:1 onto a pdfnative block. Render with `renderToBytes` / `renderToBlob` / `renderToStream` / `renderToFile` / `renderToFileStream` / `renderToResponse`, introspect with `inspectDocument` / `lintDocument`, preview live with the `usePdf` / `usePdfStream` hooks and `PDFViewer` / `PDFDownloadLink` / `BlobProvider` client components, or let AI agents author documents with the token-frugal `DocSpec` (terse JSON tuples that compile to the *same* PDF, validated by a versioned JSON Schema).

See the [React Guide](https://pdfnative.dev/guides/react.html) for the full component reference, and try the [interactive React playground](https://pdfnative.dev/playgrounds/react.html) to render JSX to PDF in your browser.

## Architecture

```
src/
├── index.ts              # Public API — single entry point
├── types/
│   ├── pdf-types.ts      # Core TypeScript type definitions
│   └── pdf-document-types.ts  # Document builder type definitions (blocks, params)
├── core/
│   ├── pdf-builder.ts    # Table-centric PDF assembly + /Info metadata + tagged PDF
│   ├── pdf-document.ts   # Free-form document builder (headings, paragraphs, lists, tables, images)
│   ├── pdf-assembler.ts  # Shared PDF binary assembly primitives (xref, trailer, writer)
│   ├── encoding-context.ts # Encoding context factory (dependency inversion from fonts/)
│   ├── pdf-image.ts      # JPEG/PNG parsing + PDF Image XObject builder
│   ├── pdf-text.ts       # Text rendering (Latin + CIDFont + shaped + tagged)
│   ├── pdf-stream.ts     # Binary utilities + download
│   ├── pdf-stream-writer.ts # AsyncGenerator streaming output
│   ├── pdf-layout.ts     # Layout constants & computation
│   ├── pdf-tags.ts       # Tagged PDF: structure tree, XMP metadata, ICC profile
│   ├── pdf-annot.ts      # Link annotations: /URI, /GoTo, URL validation + control-char hardening
│   ├── pdf-color.ts      # Color parsing, validation, normalization
│   ├── pdf-compress.ts   # FlateDecode stream compression (zlib, stored-block fallback)
│   ├── pdf-watermark.ts  # Text/image watermarks with ExtGState transparency
│   ├── pdf-barcode.ts    # Barcode/QR code encoders + PDF path rendering (5 formats)
│   ├── pdf-svg.ts        # SVG path/shape rendering as native PDF operators
│   ├── pdf-form.ts       # AcroForm interactive fields with appearance streams
│   ├── pdf-signature.ts  # CMS/PKCS#7 digital signatures (RSA + ECDSA)
│   └── pdf-encrypt.ts    # AES-128/256 encryption, MD5, SHA-256, key derivation
├── crypto/
│   ├── sha.ts            # SHA-384, SHA-512, HMAC-SHA-256
│   ├── asn1.ts           # ASN.1 DER encoding/decoding
│   ├── rsa.ts            # RSA PKCS#1 v1.5 sign/verify
│   ├── ecdsa.ts          # ECDSA P-256 sign/verify
│   ├── x509.ts           # X.509 certificate parsing
│   └── cms.ts            # CMS SignedData (PKCS#7) builder
├── parser/
│   ├── pdf-inflate.ts    # DEFLATE decompression (zlib inflate)
│   ├── pdf-tokenizer.ts  # PDF lexical scanner (ISO 32000-1 §7.2)
│   ├── pdf-object-parser.ts # PDF object parser with type guards
│   ├── pdf-xref-parser.ts # Cross-reference table/stream parser
│   ├── pdf-reader.ts     # High-level PDF reader (page tree, stream decode)
│   └── pdf-modifier.ts   # Incremental modification (non-destructive save)
├── fonts/
│   ├── encoding.ts       # WinAnsi + CIDFont pure encoding functions (no shaping deps)
│   ├── font-loader.ts    # Configurable font registry + cache
│   ├── font-subsetter.ts # TTF subsetting engine (with buffer bounds checking)
│   └── font-embedder.ts  # CMap builder + width arrays
├── shaping/
│   ├── script-registry.ts # Centralized Unicode range constants & script predicates
│   ├── thai-shaper.ts    # Thai GSUB + GPOS shaping pipeline
│   ├── bengali-shaper.ts # Bengali GSUB conjuncts + GPOS mark positioning
│   ├── tamil-shaper.ts   # Tamil GSUB + split vowel decomposition
│   ├── script-detect.ts  # Unicode script range detection (uses script-registry)
│   ├── multi-font.ts     # Cross-script font run splitting
│   ├── bidi.ts           # Unicode Bidirectional Algorithm (UAX #9)
│   └── arabic-shaper.ts  # Arabic GSUB positional shaping (uses script-registry)
└── worker/
    ├── worker-api.ts     # Worker/main-thread dispatch
    └── pdf-worker.ts     # Self-contained worker entry

fonts/                    # Pre-built font data modules (22 scripts)
tools/                    # CLI: build-font-data.cjs (TTF → JS module)
scripts/                  # Modular sample PDF generation (48 generators, 242 PDFs)
tests/                    # 2691+ tests (123 files: unit + integration + fuzz + parser + docs)
bench/                    # Performance benchmarks (vitest bench)
```

## Development

```bash
git clone https://github.com/Nizoka/pdfnative.git
cd pdfnative
npm install

npm run build            # tsup → dist/ (ESM + CJS + .d.ts)
npm run test             # vitest run (2691+ tests)
npm run test:coverage    # vitest with v8 coverage (95.41% statements at the v1.6.0 release; CI gates: 88/80/85/90)
npm run test:generate       # Generate 242 sample PDFs → test-output/
npm run lint                # ESLint 9 + typescript-eslint strict
npm run typecheck           # tsc --noEmit (src/)
npm run typecheck:tests     # tsc --project tsconfig.test.json
npm run typecheck:scripts   # tsc --project tsconfig.scripts.json
npm run typecheck:all       # Typecheck src/ + tests/ + scripts/
npm run bench               # Performance benchmarks (vitest bench)
```

### Quality Metrics

| Metric | Value |
|--------|-------|
| Tests | 2691+ (123 files) |
| Statement coverage | 95.41% (measured at the v1.6.0 release; CI enforces ≥88%, vitest.config.ts) |
| Branch coverage | 87.79% (measured at the v1.6.0 release; CI enforces ≥80%) |
| Function coverage | 98.5% (measured at the v1.6.0 release; CI enforces ≥85%; lines gate: ≥90%) |
| Fuzz tests | 89 tests in 5 files (`tests/fuzzing/`) |
| Benchmarks | Latin 500 rows ~10ms, Unicode ~13ms (Apple M1, Node 22) |
| Dependencies | 0 runtime |
| CI | Node 22/24 matrix |
| Provenance | npm signed builds |

## Known Limitations — Visual vs. Semantic PDF

pdfnative generates **visually pixel-perfect** PDFs for all 22 supported scripts. However, PDF is fundamentally a *visual* format (a digital printer), not a *semantic* one. This distinction matters for **text extraction** (copy-paste, `pdftotext`, screen readers):

### Complex Text Layout (CTL) scripts

For scripts with combining marks — **Thai**, **Devanagari**, **Vietnamese tones** — the shaper positions each mark in its own `BT…ET` block with precise GPOS offsets. PDF viewers **render** this correctly, but text extractors reconstruct content by spatial position rather than logical order. This can produce garbled output when copying text from the PDF.

| Scenario | Visual rendering | Text extraction (Ctrl+C) |
|----------|:---:|:---:|
| Latin, Greek, Polish, Turkish | ✅ Perfect | ✅ Perfect |
| CJK (Japanese, Chinese, Korean) | ✅ Perfect | ✅ Perfect |
| Vietnamese (combining diacritics) | ✅ Perfect | ⚠️ May show Win-1252 fallback artifacts |
| Thai (GSUB + GPOS shaping) | ✅ Perfect | ⚠️ Combining marks may be reordered |
| Devanagari (matras, conjuncts) | ✅ Perfect | ⚠️ Combining marks may be reordered |
| Bengali (conjuncts, GPOS marks) | ✅ Perfect | ⚠️ Combining marks may be reordered |
| Tamil (split vowels, GSUB) | ✅ Perfect | ⚠️ Split vowel recomposition may fail |

### Why this happens

This is an inherent limitation of the PDF spec (ISO 32000-1), not a bug in pdfnative. The ToUnicode CMap correctly maps glyph IDs back to Unicode code points, but extractors that rely on spatial reconstruction rather than CMap lookup will produce artifacts. This behavior is shared by most PDF generators that don't use Tagged PDF.

### Tagged PDF, /ActualText & PDF/A — Implemented ✅

All three roadmap items are now implemented and available via the `tagged` layout option:

```ts
const pdf = buildPDFBytes(params, { tagged: true });       // PDF/A-2b (default)
const pdf1b = buildPDFBytes(params, { tagged: 'pdfa1b' }); // PDF/A-1b (legacy)
const pdf2u = buildPDFBytes(params, { tagged: 'pdfa2u' }); // PDF/A-2u (Unicode)
```

When `tagged` is set, the output includes:

- **Tagged PDF (PDF/UA)** — full structure tree (`/Document → /Table → /TR → /TH|/TD`, `/H1-H3`, `/P`, `/L → /LI`, `/Figure`, `/Link`) with `/Span` marked content operators and `/StructParents` on every page
- **/ActualText** — original Unicode string attached as UTF-16BE hex to every `/Span BDC...EMC` sequence, solving text extraction for GPOS-repositioned glyphs (Thai, Arabic, Devanagari)
- **PDF/A-2b compliance** (default) — PDF 1.7, XMP metadata with `pdfaid:part=2` + `pdfaid:conformance=B`, sRGB ICC OutputIntent (`GTS_PDFA1`), `/MarkInfo << /Marked true >>` on Catalog
- **PDF/A-1b compatibility** — explicit `tagged: 'pdfa1b'` uses PDF 1.4, `pdfaid:part=1`
- **PDF/A-2u variant** — `tagged: 'pdfa2u'` uses PDF 1.7, `pdfaid:conformance=U`

The `tagged` option is backward-compatible — omitting it or setting `false` produces the same output as before.

> **PDF/A status (v1.1.0).** Every PDF/A-claiming sample now passes
> the **veraPDF** reference validator (1b / 2b / 2u / 3b) when the
> Latin font module is registered. Trailer `/ID` and
> `/Info CreationDate` are byte-equivalent to `xmp:CreateDate`
> (with timezone offset). `<dc:title>`, `<dc:description>`,
> `<pdf:Keywords>` mirror `/Info /Title`, `/Subject`, `/Keywords`
> byte-for-byte (ISO 19005-1 §6.7.3 t1 / t4 / t5). Object 3 / Object 4
> are emitted as Type0 redirector dicts pointing to the embedded
> CIDFontType2 chain — no more unembedded `Helvetica` references
> (ISO 19005-1 §6.3.4 / ISO 19005-2 §6.2.11.4.1). To produce strict
> PDF/A:
>
> ```ts
> import { registerFont } from 'pdfnative';
> registerFont('latin', () => import('pdfnative/fonts/noto-sans-data.js'));
> ```
>
> Run `npm run validate:pdfa` locally (with veraPDF installed, see
> [docs/guides/pdfa.html](docs/guides/pdfa.html)) to verify against
> the reference validator. CI runs veraPDF as a blocking check.

### PDF Encryption — Implemented ✅

AES-128 and AES-256 encryption with owner/user passwords and granular permissions:

```ts
const pdf = buildPDFBytes(params, {
  encryption: {
    ownerPassword: 'owner123',       // Required — full access password
    userPassword: 'user456',         // Optional — password to open the PDF
    algorithm: 'aes128',             // 'aes128' (default) or 'aes256'
    permissions: {
      print: true,                   // Allow printing (default: true)
      copy: false,                   // Allow copy/paste (default: false)
      modify: false,                 // Allow modification (default: false)
      extractText: true,             // Allow text extraction (default: true)
    },
  },
});
```

| Algorithm | PDF Version | Revision | Key Length | CFM |
|-----------|------------|----------|------------|-----|
| `aes128` | 1.4 | R4 (V4) | 128-bit | /AESV2 |
| `aes256` | 1.4 | R6 (V5) | 256-bit | /AESV3 |

**Note:** PDF/A and encryption are mutually exclusive (ISO 19005-1 §6.3.2). Setting both `tagged` and `encryption` will throw an error.

## Typography Convention: En-Dash Separator

pdfnative uses **en-dash** `–` (U+2013) with surrounding spaces as the standard title and footer separator:

```
"Arabic Script Coverage – الأبجدية العربية"    ✅ recommended
"Arabic Script Coverage — الأبجدية العربية"    ⚠️ works, but wider gap
```

**Why en-dash?**

| Property | Em-dash `—` (U+2014) | En-dash `–` (U+2013) |
|----------|:---:|:---:|
| Helvetica width | 1000 units (1 em) | 556 units (0.56 em) |
| Visual gap at 16pt | ~24pt with spaces | ~18pt with spaces |
| WinAnsi encodable | ✅ (0x97) | ✅ (0x96) |
| International standard | US English only | ISO / Europe / technical |
| Cursive script rendering | Disproportionate gap | Balanced spacing |

The en-dash is **44% narrower** than the em-dash and follows ISO/international typography standards. This eliminates disproportionate visual gaps in cursive scripts (Arabic, Thai) where compact shaped text amplifies the perceived space around wider separators.

Both em-dash and en-dash are **fully supported** by the library (encoding, width metrics, BiDi classification) — this is a typographic recommendation for the best cross-script visual balance, not a restriction.

## Stream Compression (FlateDecode)

Enable FlateDecode compression for dramatically smaller PDFs:

```typescript
import { initNodeCompression, buildPDFBytes } from 'pdfnative';

// Initialize native zlib (required once in ESM context)
await initNodeCompression();

const pdf = buildPDFBytes(params, { compress: true });
```

| Stream Type | Compressed? | Typical Reduction |
|-------------|:-----------:|:-----------------:|
| Page content (text operators) | ✅ | 80–90% |
| FontFile2 (TTF subset) | ✅ | 60–80% |
| ToUnicode CMap | ✅ | 80–90% |
| ICC sRGB profile | ✅ | 40–60% |
| XMP metadata | ❌ (tagged mode) | — |
| JPEG image | ❌ (already DCTDecode) | — |
| PNG image | ❌ (already FlateDecode) | — |

### Compression + Encryption

Both features compose correctly — compression is applied **before** encryption per ISO 32000-1 §7.3.8:

```typescript
const pdf = buildPDFBytes(params, {
  compress: true,
  encryption: {
    ownerPassword: 'owner123',
    algorithm: 'aes128',
  },
});
```

### Platform Support

| Runtime | Compression Method | Performance |
|---------|-------------------|-------------|
| Node.js 22+ | `zlib.deflateSync()` (native C) | Optimal |
| Browser | Stored-block fallback (valid FlateDecode) | No size reduction |
| Deno / Bun | CJS require fallback | Depends on compat layer |

For browser contexts with full compression, call `setDeflateImpl()` with a custom DEFLATE function.

## Browser & Runtime Compatibility

pdfnative targets ES2020 and works in any environment that supports `Uint8Array`, `TextEncoder`, and `crypto.getRandomValues()`.

| Runtime | Version | Status | Notes |
|---------|---------|:------:|-------|
| Node.js | 22, 24+ | ✅ Tested in CI | Full support (ESM + CJS) |
| Chrome | 80+ | ✅ | ESM via bundler or `<script type="module">` |
| Firefox | 80+ | ✅ | ESM via bundler or `<script type="module">` |
| Safari | 14+ | ✅ | ESM via bundler or `<script type="module">` |
| Edge | 80+ | ✅ | Chromium-based |
| Deno | 1.0+ | ✅ | Native ESM imports |
| Bun | 1.0+ | ✅ | Native ESM imports |
| Web Workers | — | ✅ | Via `pdfnative/worker` entry point |
| React Native | — | ⚠️ | Requires `TextEncoder` polyfill |

**Bundle format:** ESM (`dist/index.js`) + CJS (`dist/index.cjs`) + TypeScript declarations (`dist/index.d.ts`). Tree-shakeable with `sideEffects: false`.

## Origin

pdfnative was born inside [**plika.app**](https://plika.app) — a personal finance application where high-quality, multi-language PDF generation (bank statements, transaction reports) was a core requirement. Rather than depending on heavy third-party libraries, the PDF engine was built from scratch with zero dependencies, strict ISO compliance, and native support for 22 Unicode scripts.

The decision was then made to extract the engine into an independent open-source library so that everyone can benefit from production-grade PDF generation — not just plika.app users.

> **Where it all started** — the PDF engine that became pdfnative was originally built inside [plika.app](https://plika.app), a personal finance app generating multi-language bank statements and financial summaries across 16 scripts.<!-- verify-docs:allow stale-token (historical: origin story) -->

## Security

- No `eval()`, `Function()`, or dynamic code execution
- Input validation at `buildPDF()` and `buildDocumentPDF()` entry: type checks, row/block limits
- URL validation at `validateURL()`: blocks `javascript:`, `file:`, `data:` URI schemes + control characters (U+0000–U+001F, U+007F–U+009F)
- RGBA PNG rejection: unsupported color types rejected at parse boundary with descriptive errors
- PDF string escaping for `\`, `(`, `)` — prevents injection
- CIDFont hex encoding — no string injection vector
- TTF subsetting uses typed arrays with bounds checking + compound glyph iteration limits
- XRef offset guard: validates byte offsets before writing cross-reference table
- JPEG parser robustness: validates SOF markers and handles edge-case byte sequences
- PDF encryption: AES-128/256 with per-object keys, random IVs — no ECB mode
- No external crypto dependencies — pure TypeScript AES, MD5, SHA-256 implementations
- NPM provenance — signed builds via GitHub Actions OIDC

For more details, see [SECURITY.md](SECURITY.md).

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:

- Development environment setup
- Running tests, linting, and type checking
- Code style requirements (strict TypeScript, pure functions, ESM-first)
- Branch strategy and PR process

## Citing pdfnative

If you use pdfnative in academic, governmental, or compliance work, please cite it. Citation metadata is available in [CITATION.cff](CITATION.cff).

```bibtex
@software{pdfnative,
  author  = {Nizoka},
  title   = {pdfnative: Zero-dependency, ISO 32000-1 compliant PDF generation for TypeScript},
  url     = {https://github.com/Nizoka/pdfnative},
  year    = {2026}
}
```

## License

MIT — see [LICENSE](LICENSE).

Font data files in `fonts/` are licensed under [SIL Open Font License 1.1](https://scripts.sil.org/OFL). Unicode Character Database source files in `scripts/data/` are © Unicode, Inc., used under the [Unicode License v3](https://www.unicode.org/license.txt). See [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) for the aggregated notices.

---
<!-- source: docs/guides/accessibility.md -->
# Accessibility

> **Tagged PDF, PDF/UA and screen-reader-friendly output.** Pass `layout: { tagged: true }` (or a PDF/A level) and pdfnative emits the structure tree, `/ActualText` and metadata that assistive technology needs — then check the result with the read-only `validatePdfUA()`.

pdfnative produces **tagged, accessible PDFs** out of the box. This guide covers PDF/UA, PDF/A, the structure tree, and best practices for screen-reader-friendly output.

## Why tagged PDF matters

A tagged PDF carries a parallel **structure tree** alongside the visual content. Assistive technologies (screen readers, refreshable braille displays, reflow tools) walk the structure tree to present the document in reading order — without it, they fall back to heuristic guessing of what's a heading, a paragraph, or a table cell.

pdfnative's tagged mode targets two related standards:

- **PDF/UA** (ISO 14289-1) — accessibility conformance, structure tree required.
- **PDF/A** (ISO 19005) — long-term archival, with PDF/A-2u additionally requiring Unicode mapping for every glyph.

## Enabling tagged mode

```typescript
const pdf = buildDocumentPDFBytes(params, { tagged: true });
```

`tagged: true` is shorthand for `tagged: 'pdfa2b'` — the modern default.

| Option | PDF version | Standard | Use case |
|--------|-------------|----------|----------|
| `tagged: false` (default) | 1.4 | ISO 32000-1 | Simple PDFs, no accessibility guarantees |
| `tagged: true` | 1.7 | PDF/A-2b | **Recommended** — accessible + archival |
| `tagged: 'pdfa1b'` | 1.4 | PDF/A-1b | Legacy archives requiring PDF 1.4 |
| `tagged: 'pdfa2u'` | 1.7 | PDF/A-2u | Archive with mandatory text extraction |
| `tagged: 'pdfa3b'` | 1.7 | PDF/A-3b | PDF/A-2b + embedded files (e.g. ZUGFeRD invoices) |

## What pdfnative emits

When `tagged` is enabled, the document gets:

- **Structure tree** (`/StructTreeRoot`) with semantic roles:
  - `/Document` (root)
  - `/H1`, `/H2`, `/H3` for headings
  - `/P` for paragraphs
  - `/L` → `/LI` for lists
  - `/Table` → `/TR` → `/TH` / `/TD` for tables
  - `/Figure` for images, barcodes, SVG (with `/Alt` text)
  - `/Link` for hyperlinks (with `/Contents` description)
  - `/Form` for AcroForm fields
  - `/TOC` → `/TOCI` for tables of contents
- **Marked content** (`/Span << /MCID n /ActualText <hex> >> BDC`) wrapping every text run, so screen readers receive the original Unicode even when the visible glyph is a shaped Arabic ligature or Devanagari conjunct.
- **Per-page parent trees** (`/StructParents` + `/ParentTree`) — required by ISO 14289-1 §7.10.3.
- **Document metadata** in XMP (PDF/A-required).
- **sRGB ICC OutputIntent** so colors remain stable across viewers.

## Block-level accessibility hints

### Images and SVG → require `alt`

```typescript
{ type: 'image',  data: pngBytes, width: 300, alt: 'Q1 revenue chart, $1.2M peak in March' }
{ type: 'svg',    data: logoSvg, width: 200, alt: 'Company logo' }   // note: property is `data`
```

Only `image` and `svg` blocks accept an `alt` property (and `chart` accepts `altText`, auto-generated when omitted); a `barcode` block has **no** `alt` field — its accessible description cannot currently be customised. Every `/Figure` in the structure tree gets an `/Alt` entry from the `alt` property. **Always provide alt text** for non-decorative images — empty strings are treated as decorative and may be skipped by screen readers.

### Links → meaningful link text

```typescript
{ type: 'link', text: 'Read the API reference', url: 'https://github.com/Nizoka/pdfnative#api' }
```

Avoid `text: 'click here'` — screen reader users who navigate by link list lose context.

### Tables → header rows are detected automatically

When you pass a `headers` array, those cells are tagged `/TH` and the data rows are tagged `/TD`. For complex tables with span-cells or merged headers, pdfnative currently emits flat `/Table → /TR → /TH|TD` — explicit cell scopes (`/Scope = Row|Column`) are not yet exposed.

### Forms → label every field

```typescript
{ type: 'formField', fieldType: 'text', name: 'email', label: 'Email address', width: 400 }
```

The `label` is drawn as a visible text label next to the widget. pdfnative does not emit a `/TU` (tooltip) entry, so the visible label is the field's only accessible name — keep it present and descriptive.

## Verifying conformance

### veraPDF (PDF/A)

```bash
# veraPDF is a Java application, not an npm package — install it from
# https://verapdf.org/software/ (installer) or run it via Docker:
docker run --rm -v "$PWD:/data" verapdf/cli --format text /data/my-document.pdf
```

veraPDF is the reference PDF/A validator. The pdfnative test suite generates 242 sample PDFs and the PDF/A samples are validated against veraPDF on every release.

### PAC 2024 (PDF/UA)

[PAC](https://pac.pdf-accessibility.org/) (PDF Accessibility Checker) is a free Windows tool that walks the structure tree and reports PDF/UA issues. Run it on samples in `test-output/tagged/`.

### Screen reader spot-check

For a real-world test, open your PDF with **NVDA** (Windows, free), **VoiceOver** (macOS, built in), or **TalkBack** (Android). Listen to the reading order — it should match the visual order.

## Limitations and known caveats

| Area | Status |
|------|--------|
| Heading roles `/H1`–`/H3` | Supported |
| `/H4`–`/H6` | Mapped to `/H3` (PDF/UA permits this) |
| Cell scope `/Scope` | Not yet exposed — flat table tags |
| Reading order overrides | Implicit (block insertion order) — no explicit `/Order` array |
| Language tags per text run | Document-level only (`/Lang` in catalog) |
| Artifact tagging (decorative content) | Not yet exposed — header/footer/watermark are tagged as content |

Contributions to address these are welcome — see the [Roadmap](https://github.com/Nizoka/pdfnative/blob/main/ROADMAP.md).

> **PDF/A declaration guards** _(v1.7.0)_. Tagged documents that also claim
> PDF/A are now checked at build time: configurations that would break the
> declared level (base-14 text without embedded fonts, form fields under a
> claim, DeviceCMYK images against the sRGB OutputIntent) surface a diagnostic
> — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error
> under `strict: true`. Base-14 dictionaries under tagged mode also gain full
> `/ToUnicode` coverage, which changes output bytes versus 1.6.0. Details in
> the [PDF/A guide](pdfa.html).

## Testing your PDFs are accessible

A pragmatic checklist for solo developers:

- [ ] `tagged: true` is set on every user-facing PDF.
- [ ] Every `image` / `svg` / `barcode` block has a meaningful `alt`.
- [ ] Every `link` has descriptive text (no "click here").
- [ ] Every `formField` has a `label`.
- [ ] Sample passes veraPDF for the chosen PDF/A variant.
- [ ] Sample reads in the correct order in NVDA/VoiceOver.
- [ ] If the document is multi-language, the dominant language is set in the document title.

## Further reading

- [ISO 14289-1 (PDF/UA-1)](https://www.iso.org/standard/64599.html) — full PDF/UA specification.
- [Matterhorn Protocol 1.1](https://www.pdfa.org/resource/the-matterhorn-protocol/) — ~136 verifiable PDF/UA failure conditions.
- [veraPDF documentation](https://docs.verapdf.org/) — running validation in CI.
- [WebAIM PDF accessibility](https://webaim.org/techniques/acrobat/) — accessibility primer.

---
<!-- source: docs/guides/agentic-workflows.md -->
# Agentic workflows

> **How AI agents compose with pdfnative.** pdfnative is designed so an autonomous
> agent can do more than *call* the engine — it can **extend** it at runtime and
> **feed it content it generated itself**, all without waiting for a library
> release. This guide documents two concrete, factual patterns and the exact
> public APIs they rely on.

Both patterns are built entirely on already-shipped, public API surfaces:

- The library's `registerFont()` / `loadFontData()` font registry, the
  `pdfnative/tools` sub-path (`parseFontData` / `compileFontData`, since v1.5.0),
  and the bundled `pdfnative-build-font` CLI.
- The image entry points: the `image` document block (library + CLI) and the
  `embed_image` MCP tool.

There is **no new API** here — the point is that the existing surfaces were
shaped so agents can use them autonomously, under the project's
[AI-governance / human-in-the-loop contract](ai-governance.md).

---

## Pattern 1 — extend the engine at runtime, without a release

pdfnative ships 26 bundled font-data modules (22 scripts plus Latin, math, and monochrome + colour emoji). But its font
system is **open**: any TrueType/OpenType font becomes a first-class,
CIDFont-embedded, subset-on-use font once it is *registered*. Registration is a
runtime call — it does not require rebuilding or republishing pdfnative.

This is what lets an agent add a capability the moment a document needs it. In a
previous iteration of this project, an agent using the MCP server needed
mathematical symbols before the bundled **Noto Sans Math** font existed as a
release. Because the font registry is a public runtime API, the agent was able to
compile the font data and register it on the spot; the same font later shipped as
`registerFont('math', …)` in pdfnative 1.5.0. <!-- verify-docs:allow version-token (historical) --> The library did not need to change
for the document to render — the release simply promoted an already-working
runtime pattern into a bundled default.

### The three building blocks

| API | Sub-path | What it does |
|---|---|---|
| `registerFont(lang, loader)` / `registerFonts({ … })` | `pdfnative` | Register a lazy font-data loader under a `lang` code. `loadFontData(lang)` resolves it on first use. |
| `parseFontData(bytes)` → `FontDataObject` | `pdfnative/tools` | Parse a TTF/OTF **in memory** into a registerable font-data object (metrics, cmap, widths, GSUB/GPOS, `/W` array). Pure — no `fs`, no `child_process`, works in browsers / Deno / edge. |
| `compileFontData(bytes, { fontName })` → `string` | `pdfnative/tools` | Emit the ES/CJS module **source** for a font-data file — byte-identical to the `pdfnative-build-font` CLI. Useful when the agent wants to persist a reusable `*-data.js`. |

### An agent registers a font at runtime

```ts
import { buildDocumentPDFBytes, registerFont, loadFontData } from 'pdfnative';
import { parseFontData } from 'pdfnative/tools';

// The agent obtained the TTF bytes however it likes — a bundled asset,
// a user upload, or a fetch it performed itself.
const ttfBytes: Uint8Array = await getFontBytes();

// Parse in memory → a registerable font-data object.
const fontData = parseFontData(ttfBytes);

// Register it under a lang code. No release, no rebuild.
registerFont('custom', () => Promise.resolve(fontData));

// The registry is only consulted through loadFontData + fontEntries —
// load the data and pass it explicitly (fontRef must be a PDF name; /F1 and /F2 are reserved):
const custom = await loadFontData('custom');
if (!custom) throw new Error('custom font failed to load');

// It is now a first-class font: pdfnative subsets and embeds it on use.
const pdf = buildDocumentPDFBytes({
  title: 'Runtime font',
  blocks: [{ type: 'paragraph', text: 'Rendered with an agent-registered font.' }],
  fontEntries: [{ fontData: custom, fontRef: '/F3', lang: 'custom' }],
});
```

### Persisting a reusable data module

When an agent wants the font to be reusable across runs — or to hand a ready-made
module to a human — it can emit the module source instead:

```ts
import { compileFontData } from 'pdfnative/tools';

const source = compileFontData(ttfBytes, { fontName: 'My Font' });
// `source` is byte-identical to what `pdfnative-build-font` writes to disk.
// A human (or a sandboxed file tool) can save it as `my-font-data.js`.
```

The equivalent one-liner for a human at a terminal is the bundled CLI:

```bash
npx pdfnative-build-font fonts/ttf/MyFont.ttf fonts/my-font-data.js
```

### Via the MCP server — the local install is the extension point

`pdfnative-mcp` **bundles no font data of its own**. At runtime it resolves the
locally installed `pdfnative` package and lazily imports font modules from that
package's `fonts/` directory — its `lang` table is a mapping from language codes
to files it expects to find there. That design has a useful consequence for
agents operating on the host: **whatever the local `pdfnative` installation
provides, the MCP server serves.** A coding agent with filesystem access can
compile a missing font with `compileFontData`, drop the resulting `*-data.js`
into the resolved local install, wire up the local mapping, and the very next
MCP tool call renders with it — no release of either package in the loop. That
is exactly how the mathematical-symbols gap above was closed locally before
Noto Sans Math shipped upstream.

Two honest limits, so the pattern is used with open eyes:

- The **published** `add_international_text` tool exposes a closed `lang` enum
  in its JSON Schema (an unknown code is rejected with `UNSUPPORTED_LANG`), so
  serving a *new* language code requires the agent to adjust the local mapping
  too — it is a local code-level extension, not a configuration flag.
- There is **no operator-facing extension point yet** (no fonts-directory
  environment variable). Exposing one is a roadmap candidate, not a shipped
  capability.

Local, in-place extension by an agent and upstreaming through the
[governance contract](ai-governance.md) are complementary: the first unblocks
*this* document today, the second makes the capability durable for everyone.

> **Why this matters.** The engine's coverage is not frozen at release time. An
> agent can close a glyph gap — a new script, a symbol set, a brand font — the
> instant a document requires it, then optionally graduate that work into a
> committed data module for the whole team. This is *runtime extensibility*, not
> autonomous modification of the published package: the agent extends its own
> in-process pdfnative instance; the repository is only ever changed by a human
> under the [governance contract](ai-governance.md).

---

## Pattern 2 — agent-generated images in the PDF

Modern agents can *generate* raster content — charts, diagrams, illustrations,
photos. Image-generating agents (for example Antigravity, ChatGPT, and other
multimodal assistants) can pipe that output straight into a pdfnative document.
pdfnative treats a generated PNG/JPEG exactly like any other image: it parses it
natively and embeds it as an Image XObject (`/DCTDecode` for JPEG,
`/FlateDecode` for PNG) — no rasterization, no headless browser.

### Via the MCP server — `embed_image`

An agent that produced an image returns it as base64 and calls `embed_image`:

```jsonc
{
  "tool": "embed_image",
  "input": {
    "title": "Quarterly trend",
    "imageBase64": "<base64 PNG/JPEG the agent just generated>",
    "mimeType": "image/png",
    "outputMode": "base64"
  }
}
```

For a richer layout, the same base64 payload can be dropped into an `image`
block on `generate_basic_pdf`, alongside headings, tables, and barcodes the agent
assembles in the same call.

### Via the library or CLI — the `image` block

In code, a generated image is just another block:

```ts
import { buildDocumentPDFBytes } from 'pdfnative';

const pdf = buildDocumentPDFBytes({
  title: 'Report with a generated figure',
  blocks: [
    { type: 'heading', text: 'Findings', level: 1 },
    { type: 'paragraph', text: 'The figure below was generated on-device by the agent.' },
    { type: 'image', data: generatedPngBytes, width: 480 },
  ],
});
```

From the shell, an agent driving `pdfnative-cli render` supplies the same block
in its JSON document (image bytes are provided as a block field or an asset path,
subject to the CLI's path-validation rules).

> **Safety.** pdfnative validates image inputs at the boundary — it parses the
> JPEG/PNG structure natively and rejects malformed or unsupported payloads
> (e.g. raw RGBA). The agent supplies pixels; pdfnative decides whether they are
> a well-formed image before embedding.

---

## How the two patterns fit together

A single agent turn can combine both: register a brand font, generate a cover
image, and assemble a signed, archive-grade PDF — in one MCP conversation or one
CLI pipeline, without a pdfnative release in the loop.

![Agentic workflows: an AI agent generates images (embedded via the image block / embed_image) and compiles fonts (registered at runtime via registerFont + parseFontData), both feeding the pdfnative public API to produce an ISO 32000-1 PDF. Repository changes stay human-gated under the AI-governance / HITL contract.](../assets/agentic-workflows.svg)

The engine stays zero-dependency and unchanged; the agent supplies fonts and
images through public, validated entry points. Anything that would modify the
**repository** — a new bundled font, a code change — still goes through a human
under the [AI-governance / human-in-the-loop contract](ai-governance.md).

---

## See also

- [AI governance & human-in-the-loop](ai-governance.md) — the contract that keeps
  repository changes human-gated.
- [MCP integration](mcp.md) — the 28 MCP tools, including `embed_image` and
  `draft_governance_issue`.
- [CLI guide](cli.md) — driving pdfnative from the shell.
- [Font validation](font-validation.md) — `validateFontData()` for sanity-checking
  a font module before registering it.

---
<!-- source: docs/guides/ai-governance.md -->
# AI governance & human-in-the-loop

> **Shipped in v1.5.0.** pdfnative is developed with the help of AI coding
> agents — and it governs them. This repository ships a **machine-readable
> governance contract** and a **human-in-the-loop (HITL) protocol** that keep
> AI agents in an advisory role: they may *draft* proposals, but a human always
> reviews, approves, and submits. Nothing reaches GitHub autonomously.

This page exists for **transparency**. If you evaluate pdfnative for production,
you should be able to see exactly how AI participates in its maintenance — and
where the hard limits are.

![AI governance and human-in-the-loop flow — an agent drafts across four steps (detect, reproduce, self-check, draft into .github/drafts/), automated checks run verify-issue.mjs and produce a compliance report, then a human review and sign-off gate is the only path to a submission published under the human's own GitHub identity. A red callout lists what agents must never do.](../assets/ai-governance.svg)

## Why this exists

Modern open-source projects increasingly receive AI-generated issues and pull
requests. Unbounded, that creates noise, low-signal duplicates, and — worst of
all — a diffusion of responsibility: *who actually stands behind this change?*

pdfnative's answer is a written, enforceable contract:

- **Agents are draftsmen, never submitters.** Their authority ends at producing
  a local markdown draft plus a compliance report.
- **A human is always in the loop.** A person explicitly reviews, approves, and
  triggers every issue, comment, pull request, and release.
- **Identity integrity.** Anything submitted is published under the human's own
  GitHub identity — so a human always shares responsibility for the content.

The two source-of-truth files live in the repository and are loaded by any agent
that scans project configuration on start-up:

- [.github/AGENT_RULES.md](https://github.com/Nizoka/pdfnative/blob/main/.github/AGENT_RULES.md)
  — the human-and-agent-readable protocol.
- [.github/ai-governance.json](https://github.com/Nizoka/pdfnative/blob/main/.github/ai-governance.json)
  — the machine-readable contract.

## The six mandatory rules

Every agent (Copilot, Cursor, Claude, Antigravity, Aider, Cline, Windsurf,
Gemini CLI, …) must satisfy all six before proposing anything:

1. **Zero runtime dependencies.** Never suggest, add, or import an external npm
   package for a runtime feature. This is a non-negotiable blocker.
2. **No duplicates.** Search open *and* closed issues/PRs first. Surface a
   matching one instead of opening a new report.
3. **Local validation & reproduction.** Create and *execute* a minimal
   reproduction. If it does not fail or show a measurable regression, do not
   propose an issue.
4. **Byte-identity awareness.** For changes touching the builders, confirm the
   change is additive and existing output stays byte-identical — or report any
   intentional byte change.
5. **Human-in-the-loop gate (ethics).** Agents are strictly forbidden from
   creating, editing, or submitting issues, comments, PRs, or releases via any
   tool or API. They produce a local draft in
   [.github/drafts/](https://github.com/Nizoka/pdfnative/tree/main/.github) and
   present it with a compliance report.
6. **Identity integrity.** The agent reminds the user that anything submitted is
   published under their GitHub identity and that they share responsibility.

## The human-in-the-loop workflow

```
[Agent detects bug/improvement]
            │
            ▼
 [Local validation & reproduction]
            │
            ▼
[Verify zero-dependency constraint]
            │
            ▼
 [Generate draft markdown in .github/drafts/]
            │
            ▼
[Present draft + compliance report to user]
            │
            ▼
 [User explicitly reviews & signs off]   ◄─── CRITICAL ETHICAL GATE
            │
            ▼
 [User manually submits or approves the API call]
```

The agent's job ends at the draft. The **human gate** is the only path from a
proposal to a published issue, PR, or release.

## The compliance report

Every draft must be accompanied by a structured compliance report so the human
can review with full context. At minimum it contains:

| Field | What it confirms |
|---|---|
| **Zero-dependency confirmed** | no new runtime dependency introduced |
| **Reproduction command** | the exact command the agent ran |
| **Reproduction result** | the observed failure or regression |
| **Duplicate search** | what was searched and what was found |
| **Affected packages** | which monorepo packages are impacted |
| **Identity reminder shown** | the user was told it publishes under their name |

## Validate a draft before presenting it

A small, dependency-free verifier checks a draft mechanically:

```bash
node scripts/verify-issue.mjs .github/drafts/my-issue.md
# or via the npm script
npm run verify:issue .github/drafts/my-issue.md
```

It fails when the draft proposes an external dependency or omits a reproduction
code block. A passing check is **necessary but not sufficient** — the human
review gate above always applies. The verifier is advisory in CI and exposes a
pure `validateIssueMarkdown(content)` function so its logic is unit-tested.

## The machine-readable contract

[.github/ai-governance.json](https://github.com/Nizoka/pdfnative/blob/main/.github/ai-governance.json)
encodes the policy so agents that scan repository configuration can honour it
without parsing prose. Key fields:

```jsonc
{
  "policy": {
    "automatic_issue_reporting": false,
    "runtime_dependencies_allowed": false,
    "human_in_the_loop_mandatory": true,
    "autonomous_github_writes_allowed": false,
    "required_issue_fields": [
      "minimal_reproduction", "environment", "expected_behavior"
    ]
  },
  "human_in_the_loop": {
    "role_of_agent": "draftsman",
    "gate": "A human MUST explicitly review, sign off on, and trigger any GitHub issue, comment, PR, or release.",
    "draft_location": ".github/drafts/"
  }
}
```

The contract `applies_to` the whole ecosystem — `pdfnative`, `pdfnative-cli`,
`pdfnative-mcp`, and `pdfnative-react`.

Since pdfnative-mcp 1.6.0, that package's mirror of the charter also states
the **single permitted egress class**: the server makes no outbound request by
default, and the only network calls it can ever perform go to the TSA / OCSP /
CRL endpoints the *operator* configures for the PAdES tools — never to a URL
taken from a tool argument, and never to GitHub. "No GitHub write path" and
"no telemetry" remain absolute.

## What agents must never do

- Add a runtime dependency.
- Open, edit, label, close, or comment on issues/PRs autonomously.
- Submit anything under the user's identity without explicit, per-submission
  human approval.
- Bypass local validation or duplicate checks.

## In short

pdfnative treats AI as a **force multiplier for humans, not a replacement for
human judgement**. Agents accelerate the tedious parts — reproduction, drafting,
compliance checking — while every externally visible action stays under
deliberate human control. That is the standard we hold ourselves to, and we
publish it so you can hold us to it too.

---
<!-- source: docs/guides/annotations.md -->
# Annotations (read & write)

> **New in v1.5.0.** pdfnative now has a typed **markup-annotation** model plus
> round-trip **read** and **write** support. Build annotations for a new
> document, read the annotations out of an existing PDF, or inject new ones into
> an existing PDF via incremental update — all zero-dependency, all
> ISO 32000-1 §12.5.

## Supported annotation types

| `type` | PDF `/Subtype` | Use |
|---|---|---|
| `text` | `/Text` | Sticky-note comment with an icon |
| `highlight` | `/Highlight` | Highlight a text region |
| `underline` | `/Underline` | Underline a text region |
| `strikeout` | `/StrikeOut` | Strike through a text region |
| `squiggly` | `/Squiggly` | Squiggly (spellcheck-style) underline |
| `square` | `/Square` | Rectangle |
| `circle` | `/Circle` | Ellipse |
| `line` | `/Line` | Straight line |
| `freetext` | `/FreeText` | Typewriter / callout text |

Every type shares `AnnotationBase`: `rect`, and optional `contents`, `color`,
`opacity`, `title`, `modified`, `flags`.

## Building annotations

```ts
import { buildAnnotation } from 'pdfnative';
import type { MarkupAnnotation } from 'pdfnative';

const note: MarkupAnnotation = {
  type: 'text',
  rect: [72, 700, 96, 724],
  contents: 'Please double-check this figure.',
  title: 'Reviewer',
  icon: 'Comment',
};

// Full indirect object, ready to concatenate into a PDF you assemble yourself:
const obj = buildAnnotation(note, /* objNum */ 42);
```

- `buildAnnotation(annot, objNum)` returns a complete `N 0 obj … endobj` string.
- `buildAnnotationBody(annot)` returns just the dictionary body — used by the
  modifier when injecting into an existing file.

`/Contents` and `/T` are safely encoded (UTF-16BE when needed), `/C` / `/IC`
run through `parseColor`, `/QuadPoints` are auto-derived from `rect` for the
text-markup types, and `/F` defaults to `4` (Print).

## Reading annotations from an existing PDF

```ts
import { openPdf } from 'pdfnative';

const reader = openPdf(existingBytes);
const annots = reader.getAnnotations(0); // page index 0

for (const a of annots) {
  console.log(a.subtype, a.rect, a.contents, a.url);
}
```

`getAnnotations(pageIndex)` returns `ParsedAnnotation[]` with `subtype`, `rect`,
and optional `contents` (UTF-16BE decoded), `title`, `color`, `quadPoints`, and
`url` (for URI-action links). `getPageRef(pageIndex)` returns the page's
indirect reference when you need it.

## Writing annotations into an existing PDF

Add a new annotation to an existing document with a non-destructive incremental
update:

```ts
import { openPdf, createModifier, buildAnnotationBody } from 'pdfnative';

const reader = openPdf(existingBytes);
const modifier = createModifier(reader);

const body = buildAnnotationBody({
  type: 'highlight',
  rect: [72, 640, 300, 656],
  color: '#ffe14d',
  contents: 'Key clause',
});

modifier.addAnnotation(0, body); // inject on page 0
const updated = modifier.save();  // appended incremental section, original preserved
```

`addAnnotation()` appends the annotation object and rewrites the page's
`/Annots` array in an incremental update section — the original bytes are never
mutated, so any existing signature's byte range upstream of the appended section
stays intact.

**Encrypted documents** are supported since v1.6.0: open with
`openPdf(bytes, { password })` and annotate as usual — the appended
annotation objects are encrypted under the document's existing scheme
(RC4, AES-128 and AES-256 sources), so the annotation text never appears
in cleartext in the file.

```ts
const modifier = createModifier(openPdf(encryptedBytes, { password: 'secret' }));
modifier.addAnnotation(0, body);
const updated = modifier.save(); // annotation stored encrypted
```

## Sample

[annotations-showcase.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/annotations-showcase.ts)
builds a document with every annotation type, reads them back out, and injects a
highlight into an existing PDF.

---
<!-- source: docs/guides/architecture.md -->
# Architecture Guide

> **Two builders, one strict dependency flow.** `buildPDFBytes` is the table-centric builder, `buildDocumentPDFBytes` the free-form document builder; beneath them the modules flow types → core ← fonts ← shaping ← worker, with standalone crypto and parser modules — no circular imports anywhere.

## Two Builders

pdfnative provides two PDF builders for different use cases:

### `buildPDF()` / `buildPDFBytes()` — Table-Centric

Best for: financial statements, reports, tabular data.

```typescript
import { buildPDFBytes } from 'pdfnative';

const pdf = buildPDFBytes({
  title: 'Monthly Report',
  headers: ['Date', 'Description', 'Amount'],
  rows: [
    { cells: ['01/15', 'Grocery', '-$45.00'], type: 'debit', pointed: false },
  ],
  // ... infoItems, balanceText, countText, footerText
});
```

Produces a structured table layout with title, info items, balance line, column headers, data rows, and footer. Supports pagination, tagged PDF, encryption, compression.

### `buildDocumentPDF()` / `buildDocumentPDFBytes()` — Free-Form

Best for: reports, manuals, invoices, any document with mixed content.

```typescript
import { buildDocumentPDFBytes } from 'pdfnative';

const pdf = buildDocumentPDFBytes({
  title: 'Project Report',
  blocks: [
    { type: 'heading', text: 'Introduction', level: 1 },
    { type: 'paragraph', text: 'This report covers...' },
    { type: 'table', headers: ['Q', 'Revenue'], rows: [...] },
    { type: 'image', data: pngBytes, width: 300 },
    { type: 'barcode', format: 'qr', data: 'https://example.com' },
  ],
});
```

Supports 13 block types: heading, paragraph, list, table, image, link, spacer, pageBreak, toc, barcode, svg, formField, chart.

## Generation Pipeline

```
Input (params + options)
  │
  ├─ resolveLayout()         → page dimensions, margins, column positions
  ├─ normalizeColors()       → validate & normalize color values
  ├─ createEncodingContext()  → font encoding (WinAnsi + CIDFont)
  │
  ├─ Content Loop ─────────────────────────────────
  │   ├─ Text rendering      → BT/ET operators, font selection
  │   ├─ Image embedding     → XObject + Do operator
  │   ├─ Barcode rendering   → PDF path operators (re f)
  │   ├─ SVG rendering       → PDF path operators (m l c)
  │   └─ Page breaks         → new page object
  │
  ├─ Font subsetting         → TTF subset per used font
  ├─ Tagged PDF (optional)   → structure tree, /ActualText, MCID
  ├─ PDF/A (optional)        → XMP metadata, ICC OutputIntent
  ├─ Encryption (optional)   → AES-128/256, key derivation
  ├─ Compression (optional)  → FlateDecode on content streams
  │
  └─ Assembly ─────────────────────────────────────
      ├─ createPdfWriter()   → binary writer with offset tracking
      ├─ Object emission     → N 0 obj ... endobj
      └─ writeXrefTrailer()  → xref table + trailer + startxref
```

## Module Dependency Flow

```
types/ → core/ ← fonts/ ← shaping/ ← worker/
              ↑
          crypto/ (near-standalone, imports core/pdf-encrypt for sha256)
          parser/ (imports core/pdf-compress, pdf-encrypt, pdf-tags)
```

- **No circular dependencies** — strict unidirectional flow, with **one
  sanctioned, documented reverse edge**: the signature-workflow core modules
  (`pdf-dss`, `pdf-sig-utils`, `pdf-doc-timestamp`, `pdf-sig-placeholder`,
  `pdf-form-fill`) import the parser to read existing documents before
  appending incremental revisions
- **crypto/** is near-standalone — its only cross-module import is `sha256` from `core/pdf-encrypt.ts` (re-exported by `crypto/sha.ts`)
- **parser/** imports from `core/pdf-compress.ts` (FlateDecode), `core/pdf-encrypt.ts` (decryption, incremental `/ID`) and `core/pdf-tags.ts` (XMP resync in `updateMetadata`)
- **fonts/** imports from `shaping/` for script detection
- **shaping/** imports from `fonts/` encoding context (via `core/encoding-context.ts` to break cycle)

## Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| No classes | Pure functions — easier to test, tree-shake, and reason about |
| String-based PDF operators | Direct control over output, no AST overhead |
| Lazy font loading | `registerFonts()` + `loadFontData()` — load only needed scripts |
| Shared assembler | `pdf-assembler.ts` eliminates xref/trailer duplication between builders |
| Extracted renderers | `pdf-renderers.ts` — block renderers, text wrapping, constants extracted from `pdf-document.ts` for maintainability. `planTable()` and `TableSlice` provide planner-driven multi-page table rendering — `_paginateBlocks()` measures once then slices at row boundaries, keeping `renderTable()` page-lifecycle-free. See [Smart tables guide](tables.md). |
| Encoding context in core/ | Dependency inversion — breaks fonts/ → shaping/ cycle |

## Ecosystem

The architecture diagram above shows the **internal library modules**. External consumers sit above the library and import from `pdfnative` like any npm package. Three official companion packages — a CLI, an MCP server, and a React renderer — cover the most common non-library workflows. All live in separate repositories, version independently, and depend on `pdfnative` only through its public API, so the core engine stays zero-dependency.

```
                         ┌─────────────────────────────────────────────┐
   [shell / CI / Docker] │  pdfnative-cli (npm) — 21 commands          │
                         └─────────────────────────────────────────────┘
                         ┌─────────────────────────────────────────────┐
    [Claude / Cursor / …] │  pdfnative-mcp (npm) — 28 AI tools          │
                         └───────────────────────────────────────────┘
                         ┌─────────────────────────────────────────────┐
   [React / Next.js app] │  pdfnative-react (npm) — declarative JSX    │
                         └─────────────────────────────────────────────┘
                            │  import { … } from 'pdfnative'  (public API only)
                         ┌─────────────────────────────────────────────┐
                         │  pdfnative (npm) — zero-dependency engine   │  ← this repo
                         └─────────────────────────────────────────────┘
```

### pdfnative-cli

[pdfnative-cli](https://github.com/Nizoka/pdfnative-cli) is the **official command-line interface**. It exposes twenty-one commands — `render`, `fill`, `annotate`, `metadata`, `merge`, `split`, `extract`, `sign`, `verify`, `ltv`, `doc-timestamp`, `encrypt`, `decrypt`, `inspect`, `extract-text`, `compare`, `batch`, `doctor`, `schema`, `completion`, `govern` — that map directly to public `pdfnative` APIs, with an agent-native `--json`/`E_*`/`--dry-run` automation contract:

```
[shell / Makefile / GitHub Actions / Docker]
              │ argv + stdin/stdout
     ┌──────────────────────────┐
     │  pdfnative-cli (npm)     │  ← dispatch layer, 21 commands + agent contract
     └──────────────────────────┘
              │ import { buildDocumentPDFBytes, signPdfBytes, openPdf, validatePdfUA } from 'pdfnative'
     ┌──────────────────────────┐
     │      pdfnative (npm)     │  ← core library (this repo)
     └──────────────────────────┘
```

Like `pdfnative-mcp` and `pdfnative-react`, the CLI lives in a separate repository and depends on `pdfnative` only via the public API surface. See the [CLI Guide](cli.html) for usage and the security model.

### pdfnative-mcp

[pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is a **Model Context Protocol server** that wraps the pdfnative public API and exposes it as 28 structured tools to any MCP-compatible AI client (Claude Desktop, Cursor, Continue, Zed, ChatGPT, …). It commits to API stability via a per-tool `_meta.apiVersion` field.

```
[Claude Desktop / Cursor / Continue / Zed]
              │ MCP stdio protocol
     ┌──────────────────────────┐
      │  pdfnative-mcp (npm)     │  ← MCP server, 28 tools
     └──────────────────────────┘
              │ import { buildDocumentPDFBytes, … } from 'pdfnative'
     ┌──────────────────────────┐
     │      pdfnative (npm)     │  ← core library (this repo)
     └──────────────────────────┘
```

pdfnative-mcp is **not an internal module** — it is a separate npm package with its own repository, versioning, and release cadence. It references `pdfnative` only through the public API.

For setup instructions, tool reference, and per-client configuration, see the [MCP Integration Guide](mcp.html).

### pdfnative-react

[pdfnative-react](https://github.com/Nizoka/pdfnative-react) v1.2.0 is the **declarative React renderer**. A custom React reconciler compiles a JSX component tree — synchronously, with no DOM — into the pdfnative `DocumentParams` model, which the engine renders to bytes:

```
[React / Next.js / Remix component tree]
              │ custom react-reconciler (no DOM, no headless browser)
     ┌──────────────────────────┐
     │  pdfnative-react (npm)   │  ← <Document>/<Table>/<Barcode> → pdfnative blocks
     └──────────────────────────┘
              │ import { buildDocumentPDFBytes, … } from 'pdfnative'
     ┌──────────────────────────┐
     │      pdfnative (npm)     │  ← core library (this repo)
     └──────────────────────────┘
```

**React 19 is a peer dependency of `pdfnative-react` only** — the core `pdfnative` engine remains zero-dependency. Components map 1:1 onto pdfnative blocks, and the token-frugal `DocSpec` lets AI agents author the same documents with a fraction of the tokens. See the [React Guide](react.html) for the component reference and the [React playground](../playgrounds/react.html) to try it in your browser.

---
<!-- source: docs/guides/charts.md -->
# Charts (native vector)

> **New in v1.6.0, extended in v1.7.0.** Render bar, horizontal-bar, stacked-bar,
> line, area, scatter, pie, and donut charts as **pure PDF path operators** —
> rectangles, line segments, and cubic-Bézier arcs. Zero dependencies, no
> rasterisation, no image embedding. Charts are crisp at any zoom, searchable
> (labels are real text), and PDF/A-safe.

## TL;DR

```ts
import { buildDocumentPDFBytes } from 'pdfnative';

const pdf = buildDocumentPDFBytes({
  title: 'Report',
  blocks: [
    {
      type: 'chart',
      chartType: 'bar',
      title: 'Quarterly revenue vs cost',
      categories: ['Q1', 'Q2', 'Q3', 'Q4'],
      series: [
        { label: 'Revenue', values: [120, 150, 170, 140] },
        { label: 'Cost',    values: [80, 90, 100, 95] },
      ],
    },
  ],
});
```

Add a `chart` block anywhere in a document's `blocks` array, like a heading,
paragraph, or table.

## Chart types

| `chartType` | Shape | Series |
|-------------|-------|--------|
| `'bar'`     | Vertical grouped bars | 1+ |
| `'barH'`    | Horizontal grouped bars | 1+ |
| `'line'`    | Multi-series line, optional markers | 1+ |
| `'pie'`     | Pie | exactly 1 |
| `'donut'`   | Donut (pie with a hole) | exactly 1 |
| `'stackedBar'` (v1.7.0) | Vertical stacked bars (positive and negative running totals stack separately) | 1+ |
| `'stackedBarH'` (v1.7.0) | Horizontal stacked bars | 1+ |
| `'area'` (v1.7.0) | Line closed to the zero baseline, opaque tinted fill | 1+ |
| `'scatter'` (v1.7.0) | X/Y point markers positioned by `xValues` | 1+ |

## The `ChartBlock`

```ts
interface ChartBlock {
  type: 'chart';
  chartType: 'bar' | 'barH' | 'line' | 'pie' | 'donut'
    | 'stackedBar' | 'stackedBarH' | 'area' | 'scatter';    // last four: v1.7.0
  series: {
    label: string;
    values: number[];
    color?: PdfColor;
    xValues?: (number | string)[]; // x positions for scatter / linear / time x-axes (v1.7.0)
    yAxis?: 'left' | 'right';      // bind the series to the secondary right axis (v1.7.0)
  }[];
  categories?: string[];        // x-axis / slice labels; defaults to 1-based indices
  width?: number;               // plot width in pt (clamped to content width). Default 460
  height?: number;              // plot-area height in pt. Default 240
  title?: string;
  legend?: 'bottom' | 'none';   // default: shown for multi-series / pie
  axis?: { yMin?: number; yMax?: number; ticks?: number; grid?: boolean;
           scale?: 'linear' | 'log' };                      // scale: v1.7.0
  axis2?: { yMin?: number; yMax?: number; ticks?: number;
            scale?: 'linear' | 'log' };                     // right value axis (v1.7.0)
  xAxis?: { type?: 'category' | 'linear' | 'time';          // v1.7.0
            min?: number | string; max?: number | string;
            ticks?: number; grid?: boolean };
  dataLabels?: boolean                                      // v1.7.0
    | { decimals?: number; prefix?: string; suffix?: string };
  labelStride?: number;         // draw every Nth category label. Default: auto (v1.7.0)
  labelRotation?: number;       // rotate category labels 0–90 degrees (v1.7.0)
  markers?: boolean;            // line only. Default false
  colors?: PdfColor[];          // palette override (per series / per slice)
  align?: 'left' | 'center' | 'right';
  altText?: string;             // tagged-PDF /Figure /Alt (auto-generated if omitted)
}
```

Colours accept the same forms as the rest of pdfnative — `'#4e79a7'`,
`[78, 121, 167]`, or a PDF RGB string — and are validated (injection-safe). When
omitted, a built-in 8-colour categorical palette is used deterministically.

## Examples

### Multi-series line with markers

```ts
{
  type: 'chart', chartType: 'line', markers: true,
  categories: ['Jan', 'Feb', 'Mar', 'Apr'],
  series: [
    { label: 'Free', values: [10, 25, 22, 40] },
    { label: 'Paid', values: [3, 8, 12, 18] },
  ],
}
```

### Donut with a custom palette

```ts
{
  type: 'chart', chartType: 'donut', title: 'Traffic sources',
  categories: ['Organic', 'Referral', 'Direct', 'Social'],
  colors: ['#59a14f', '#4e79a7', '#f28e2b', '#e15759'],
  series: [{ label: 'Share', values: [55, 20, 15, 10] }],
}
```

### Negative values

Bar and line charts anchor at a zero baseline, so negative values render below
the axis automatically:

```ts
{ type: 'chart', chartType: 'bar', categories: ['Jan', 'Feb', 'Mar'],
  series: [{ label: 'Net flow', values: [30, -15, 20] }] }
```

### Stacked bars (v1.7.0)

Positive and negative values stack in separate running totals per category, so
mixed-sign data reads correctly:

```ts
{
  type: 'chart', chartType: 'stackedBar',
  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
  series: [
    { label: 'EMEA', values: [40, 55, 60, 52] },
    { label: 'APAC', values: [25, 30, 35, 41] },
    { label: 'AMER', values: [50, 48, 62, 70] },
  ],
}
```

### Area with data labels (v1.7.0)

The area fill is the series colour mixed 35 % toward white — an **opaque
tint**, not transparency, so area charts remain PDF/A-safe (PDF/A-1b forbids
`/ExtGState` alpha):

```ts
{
  type: 'chart', chartType: 'area',
  categories: ['Jan', 'Feb', 'Mar', 'Apr'],
  dataLabels: { suffix: ' k€', decimals: 1 },
  series: [{ label: 'ARR', values: [10.4, 12.1, 13.8, 16.2] }],
}
```

`dataLabels: true` reuses the axis tick formatter; the object form controls
`decimals` and adds a `prefix`/`suffix`.

### Scatter on a time axis (v1.7.0)

`scatter` positions each point by `xValues` (required). On `xAxis.type: 'time'`,
`xValues` accepts ISO-8601 strings or epoch milliseconds; tick positions and
labels are computed with **UTC getters only** — never `Intl` or the host time
zone — so output bytes are identical on every machine:

```ts
{
  type: 'chart', chartType: 'scatter',
  xAxis: { type: 'time', grid: true },
  series: [{
    label: 'Deploys',
    xValues: ['2026-01-05', '2026-02-14', '2026-03-02', '2026-04-20'],
    values: [3, 7, 5, 11],
  }],
}
```

`line` and `area` charts may also opt into a `'linear'` or `'time'` x-axis;
`bar` variants stay categorical.

### Dual value axes & log scale (v1.7.0)

Bind a series to a secondary right axis with `yAxis: 'right'` and configure its
range with `axis2`. The right axis (and its gutter) appears only when at least
one series binds to it. Either axis can switch to `scale: 'log'` (decade
ticks); log scales require strictly positive values and cannot be combined
with stacked charts:

```ts
{
  type: 'chart', chartType: 'line', markers: true,
  categories: ['2023', '2024', '2025', '2026'],
  axis2: { scale: 'log' },
  series: [
    { label: 'Revenue (k€)', values: [120, 150, 170, 140] },
    { label: 'Requests/day', values: [900, 8000, 65000, 400000], yAxis: 'right' },
  ],
}
```

### Crowded category labels (v1.7.0)

Long or numerous x-labels no longer collide (issue #67). By default the engine
measures every label and draws every *N*th one — the smallest stride at which
labels no longer overlap (`1` when everything fits, so existing charts are
unchanged). Override with `labelStride` (`1` forces every label), or rotate
instead:

```ts
{
  type: 'chart', chartType: 'bar',
  categories: ['January', 'February', 'March', 'April', 'May', 'June'],
  labelRotation: 45,   // 0–90° counter-clockwise, right-aligned to the tick
  series: [{ label: 'Signups', values: [12, 18, 14, 22, 19, 27] }],
}
```

Rotated labels read upward toward their tick; setting `labelRotation` disables
the automatic stride (rotation defeats horizontal overlap on its own) unless
`labelStride` is also set. Both options apply to category axes only —
`scatter` charts reject them.

## Accessibility (tagged PDF)

In tagged mode (`{ tagged: true }` or a PDF/A profile), each chart is emitted as
a `/Figure` structure element with an `/Alt` description. Provide `altText` for a
meaningful summary; otherwise a deterministic one is generated
(`"bar chart: 2 series, 4 categories"`). Charts use solid fills only — no
transparency — so they are **PDF/A-safe**. That includes area charts: the fill
is an opaque tint (series colour mixed toward white), never `/ExtGState` alpha.

## Internationalised labels

All chart text (title, axis ticks, category labels, legend, slice percentages)
flows through pdfnative's standard text pipeline, so CJK, Arabic/RTL, and emoji
labels shape correctly when the matching font is registered — no extra work.

## Limits & scope (v1.7.0)

- **In:** bar, horizontal bar, stacked bar (both orientations), multi-series
  line (straight segments + optional markers), area, scatter, pie, donut;
  linear and log value axes with "nice"/decade ticks; secondary right value
  axis; category, linear, and time (UTC-deterministic) x-axes; gridlines;
  legend; negative values; per-point data labels; automatic label stride and
  0–90° label rotation.
- **Out (planned):** curved (spline) line interpolation, error bars, bubble
  sizing, combined chart types in one plot.
- A hard guard rejects charts with more than **10,000** total data points.
- Validation is strict and throws before any bytes are produced: log scales
  reject non-positive values (and stacked charts), `scatter` requires
  `xValues` on every series, `xValues` lengths must match `values`,
  `'linear'`/`'time'` x-axes apply only to line/area/scatter, date strings in
  `xValues` require `xAxis.type: 'time'`, `yAxis: 'right'` is cartesian-only,
  and `labelStride`/`labelRotation` apply to category axes only.

## See also

- [Tables](tables.html) — tabular data blocks
- [SVG rendering](../guides/architecture.html) — arbitrary vector paths
- [Accessibility](accessibility.html) — tagged PDF / PDF-UA
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/choose.md -->
# Choosing your surface

> **Write application code → the library. Drive a shell, Makefile or CI job →
> `pdfnative-cli`. Give a conversational AI assistant tool access →
> `pdfnative-mcp`. Author documents inside a React 19 app →
> `pdfnative-react`.** All four surfaces sit on the same zero-dependency
> engine and produce the same ISO 32000-1 / PDF/A-conformant bytes, so the
> choice is about *who is calling*, not about what comes out — and you can
> switch later without re-authoring your documents.

## The decision, in prose

**You are writing application code** — a Node.js, Deno, Bun or browser
service, a worker, a script with logic around the PDF. Use the **library**
(`npm install pdfnative`). It is the full surface: synchronous builders, the
parser, signatures with long-term validation, streaming, Web Worker support.
Everything the other three surfaces do, they do by calling this package.

**You are driving a shell, a CI pipeline, a container, or a build tool in
another language.** Use the **CLI** (`pdfnative-cli`, binary `pdfnative`) —
21 commands over stdin/stdout pipelines, with an agent-native automation
contract: a `--json` envelope, stable `E_*` error codes, `--dry-run`, and
compact `--summary` / `--fields` output projection. No JavaScript required.

**You are (or you are building) a conversational assistant with tool
access** — Claude Desktop, Cursor, Continue, Zed, or any Model Context
Protocol client. Use the **MCP server** (`pdfnative-mcp`, `npx -y
pdfnative-mcp`) — 28 tools with strict JSON Schemas, read-back tools for
self-verification, and no outbound network access except the
operator-configured TSA/OCSP/CRL endpoints.

**Your host application is React 19.** Use the **React renderer**
(`pdfnative-react`) — declarative JSX compiled on-device to pdfnative blocks
by a custom reconciler (no DOM, no headless browser), with live-preview hooks
and the token-frugal `DocSpec` for agent authoring. React 19 is a peer
dependency of this package only; the engine stays zero-dependency.

## Capability × surface

The same facts in machine-readable form live in
[`docs/data/surfaces.json`](../data/surfaces.json); tool, command and export
names are verified against
[`docs/assets/ecosystem.json`](../assets/ecosystem.json) and the engine's
export surface by the documentation CI. Version annotations name the release
*of that surface's own package* which introduced the capability; an em-dash
means the surface does not offer it.

| Capability | Library (`pdfnative`) | CLI (`pdfnative-cli`) | MCP (`pdfnative-mcp`) | React (`pdfnative-react`) |
|---|---|---|---|---|
| Generate documents | `buildDocumentPDFBytes` / `buildPDFBytes` | `render` | `generate_basic_pdf` (+ the dedicated document tools) | `renderToBytes` and friends, `<Document>` tree |
| Smart tables | `table` block | `render` (`table` block, or `--variant table`) | `add_table` | `<Table>` |
| Native vector charts | `chart` block _(v1.6.0)_ | `render` (`chart` block) _(v1.3.0)_ | `add_chart` _(v1.5.0)_ | `<Chart>` _(v1.1.0; charts v2 — nine kinds, secondary axis, log/time scales, data labels — since v1.2.0)_ |
| Digital signatures (PAdES CMS) | `addSignaturePlaceholder` _(v1.2.0)_ + `signPdfBytes` | `sign` | `sign_pdf` (+ `prepare_signature_placeholder`) | — |
| LTV ladder (B-T → B-LTA) | `signPdfBytesWithTimestamp`, `addValidationInfo`, `addDocumentTimestamp` _(v1.7.0)_ | `sign --timestamp`, `ltv`, `doc-timestamp` _(v1.4.0)_ | `add_ltv`, `timestamp_pdf` _(v1.6.0)_ | — |
| Encrypt / decrypt | build-time `encryption` layout option; existing PDFs via the page-tree `encrypt` option and `openPdf` with a password | `encrypt` / `decrypt` _(v1.3.0)_ | `encrypt_pdf` / `decrypt_pdf` _(v1.5.0)_ | build-time only, via the `layout` render option |
| Fill / flatten forms | `readFormFields`, `fillForm`, `flattenForm` _(v1.6.0)_ | `fill` _(v1.3.0)_ | `read_form_fields`, `fill_form` _(v1.5.0)_ | — |
| Extract text | `extractText` _(v1.6.0)_ | `extract-text` _(v1.3.0)_ | `extract_text` | — |
| Merge / split / extract pages | `mergePdfs`, `splitPdf`, `extractPages` _(v1.4.0)_ | `merge` / `split` / `extract` _(v1.2.0)_ | `merge_pdfs` / `split_pdf` / `extract_pages` _(v1.3.0)_ | — |
| Markup annotations | `buildAnnotation` + `PdfModifier.addAnnotation` _(v1.5.0)_ | `annotate` _(v1.2.0)_ | `annotate_pdf` _(v1.4.0)_ | — |
| Inspect layout (pagination dry run) | `inspectDocumentLayout` _(v1.5.0)_ | `render --inspect-layout` _(v1.2.0)_ | `inspect_layout` _(v1.6.0)_ | `inspectDocument` |
| Validate PDF/UA | `validatePdfUA` _(v1.3.0)_ | `inspect --pdfua` _(v1.1.0)_ | `validate_pdf` _(v1.1.0)_ | — (`lintDocument` checks the authoring model before rendering, not the emitted PDF) |
| Update metadata (signature-safe) | `PdfModifier.updateMetadata` _(v1.7.0)_ | `metadata` _(v1.4.0)_ | `update_metadata` _(v1.6.0)_ | — |
| Compare two PDFs (text + structure) | — (compose `openPdf` / `extractText` / the readers) | `compare` _(v1.4.0)_ | — | — |
| Runtime font registration | `registerFont` / `registerFonts` _(v1.5.0, any loader — incl. fonts you compile with `compileFontData`)_ | `render --font` (bundled fonts only) _(v1.1.0)_ | — (fixed `lang` enum; fonts resolved from the local `pdfnative` install) | `registerFont` / `registerFonts` (re-exported) |

## Honest notes

- **LTV transport differs by surface on purpose.** The engine opens no socket:
  in the **library**, the RFC 3161 / OCSP / CRL transport is *injected by your
  code* (`setTimestampProvider` / `setRevocationProvider`). On **MCP**, the
  transport is *operator-configured* through environment variables
  (`PDFNATIVE_MCP_TSA_URL`, `PDFNATIVE_MCP_REVOCATION`, an allow-list) — never
  from tool arguments. On the **CLI** (since v1.4.0, which completes the
  write-side ladder), every network touch is an *explicit per-invocation
  opt-in* — `sign --timestamp <url>`, `ltv --online`, `doc-timestamp --url` —
  behind an SSRF guard, and `ltv collect` / `ltv embed` split the ladder across
  an air gap: evidence is gathered as replayable JSON on a connected machine
  and embedded fully offline.
- **The engine ships no cryptographic signature verifier.** `listSignatures`
  is an inventory; full verification (digest, CMS, chain, trust, timestamps,
  revocation) lives in `pdfnative-cli verify` and the MCP `verify_pdf` tool.
- **React is an authoring surface.** It generates documents (including charts,
  barcodes, SVG, form *widgets* and build-time encryption via the `layout`
  render option) but does not operate on existing PDFs — no fill, extract,
  merge or signing. When a React app needs those, call the library directly:
  it is already installed as the renderer's peer dependency.
- **The MCP tool names, CLI commands and library exports in the table are the
  complete story for these capabilities**, not a sample — where a cell is an
  em-dash, the surface genuinely lacks the capability today rather than
  hiding it under another name.

## You can switch later

All four surfaces call the same engine, so the artefacts are interchangeable:
a PDF rendered by the React reconciler can be signed by the CLI, inspected by
an MCP tool, and have its text extracted by the library. Document *inputs*
travel too — the CLI's `render` consumes the same `DocumentParams` JSON the
library takes, the MCP `generate_basic_pdf` blocks mirror the engine's block
kinds, and `pdfnative-react` compiles JSX (or a `DocSpec`) into that same
model. Starting on the "wrong" surface costs a call-site migration, not a
document rewrite.

## Further reading

- [Onboarding](onboarding.html) — the 90-second install-and-first-call for
  each surface.
- [Ecosystem use cases](use-cases.html) — four production architectures that
  compose these surfaces, with diagrams.
- [Self-verifying generation](self-verify.html) — the generate → inspect →
  assert → correct loop on every surface.
- [Architecture](architecture.html) — how the four packages relate.
- [CLI guide](cli.html) · [MCP guide](mcp.html) · [React guide](react.html) —
  the complete per-surface references.
- [Agent brief](../agent-brief.md) — the same decision tree in
  paste-into-context form for AI agents.

---
<!-- source: docs/guides/cli.md -->
# pdfnative-cli — Command-Line Interface Guide

> **Tracks the latest published `pdfnative-cli`** (v1.4.0, built on pdfnative 1.7.0 — pins `^1.7.0`). The CLI versions independently from the library. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-cli releases](https://github.com/Nizoka/pdfnative-cli/releases).

[`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) is the **official command-line interface** for the [`pdfnative`](https://github.com/Nizoka/pdfnative) library. It exposes 21 commands in five groups — create & edit (`render`, `fill`, `annotate`, `metadata`), page tree (`merge`, `split`, `extract`), security (`sign`, `verify`, `ltv`, `doc-timestamp`, `encrypt`, `decrypt`), read & extract (`inspect`, `extract-text`, `compare`), and automation & meta (`batch`, `doctor`, `schema`, `completion`, `govern`) — that together cover the full document lifecycle from JSON to a signed, timestamped, archive-grade PDF with the complete PAdES ladder (B-B → B-T → B-LT → B-LTA), plus page-tree editing, markup annotations, document comparison, and an AI-governance gate, with an agent-native automation contract for autonomous AI and CI pipelines.

> **Why a CLI?** Many real-world workflows live outside Node.js: shell scripts, CI pipelines, Docker containers, Makefiles, batch jobs, build tools written in other languages. The CLI lets all of them call `pdfnative` without writing JavaScript, and is fully composable through stdin/stdout pipelines.

The CLI is a **pure dispatch layer** over `pdfnative`. No PDF logic lives in the CLI itself — every command forwards to a public `pdfnative` API:

| CLI command | `pdfnative` API |
|---|---|
| `render` | `buildDocumentPDFBytes()` / `buildDocumentPDFStream()` / `buildDocumentPDFStreamTrue()` / `buildPDFBytes()` (table variant = `buildPDFBytes`, the table-centric builder; document variant = `buildDocumentPDFBytes`, the free-form block builder) |
| `fill` | `readFormFields()` / `fillForm()` / `flattenForm()` |
| `encrypt` / `decrypt` | `openPdf(bytes, { password })` + `MergeOptions.encrypt` |
| `extract-text` | `extractText()` |
| `doctor` | — (environment probe, no library equivalent) |
| `sign` | `signPdfBytes()` / `addSignaturePlaceholder()` — the native constant-time provider is implemented in the CLI (`createNativeCryptoProvider` is a CLI utility, not a pdfnative API) and passed per call as `options.provider` (pdfnative also exposes a global `setCryptoProvider()`, which the CLI does not use) |
| `inspect` | `openPdf()` / `getInfo()` / `pageCount` / `getPageLabels()` / `getAnnotations()` / `validatePdfUA()` |
| `verify` | `openPdf()` + `verifyCertSignature()` (X.509 certificate-signature checks); the CMS/PKCS#7, RFC 3161 timestamp and OCSP/CRL revocation verification is implemented in the CLI itself |
| `merge` | `mergePdfs()` |
| `split` | `splitPdf()` |
| `extract` | `extractPages()` |
| `annotate` | `PdfModifier.addAnnotation()` / `buildAnnotationBody()` |
| `metadata` | `PdfModifier.updateMetadata()` — incremental `/Info` + XMP edits that keep existing signatures valid for their revision |
| `ltv` | `collectValidationInfo()` / `embedValidationInfo()` / `addValidationInfo()` (PAdES B-LT `/DSS`) |
| `doc-timestamp` | `addDocumentTimestamp()` — an RFC 3161 `/DocTimeStamp` revision (PAdES B-LTA) |
| `compare` | `openPdf()` / `extractText()` / `readFormFields()` / `getAnnotations()` / `listSignatures()` — text + structure diff, implemented in the CLI |
| `govern` | AI-governance contract (`.github/ai-governance.json`, `AGENT_RULES.md`) — draft gating uses the CLI's own `validateGovernanceDraft()` (the core repo's equivalent check is a repo script, not a published API) |
| `batch` | the `render` pipeline, applied in parallel across a directory |
| `schema` | versioned JSON Schemas (Draft 2020-12) for every input/output shape |

This means **every feature of the library is one release away from the CLI**, and any bug fix in `pdfnative` is automatically picked up by `pdfnative-cli` on its next dependency bump.

---

## Installation

```bash
# Run directly with npx — no global install required
npx pdfnative-cli render --input document.json --output report.pdf

# Or install globally
npm install --global pdfnative-cli
pdfnative render --input document.json --output report.pdf
```

**Requirements:** Node.js ≥ 22 *(v1.4.0 — Node 20 reached end-of-life on 2026-04-30)* · Bun · Deno (`node dist/cli.cjs`).

The CLI ships with **NPM provenance** — verify the published artifact with `npm audit signatures` or on [npmjs.com](https://www.npmjs.com/package/pdfnative-cli).

---

## When to use the CLI vs the library

| Use the **CLI** when… | Use the **library** when… |
|---|---|
| You write shell scripts, Makefiles, or Bash/PowerShell pipelines | You build a Node.js / Bun / Deno service |
| Your CI/CD job runs in Docker or GitHub Actions | You need fine-grained streaming control or Web Worker offloading |
| You want to compose with `cat`, `jq`, `tee`, `gzip`, etc. | You target browsers, Web Workers, or Deno Deploy |
| You sign, verify, or inspect PDFs ad-hoc from the terminal | You bundle PDFs through a custom pipeline (custom font registry, hooks, etc.) |
| You want a one-liner instead of a 30-line Node.js script | You need 100 % programmatic control of the API surface |

The two are **complementary**. A typical full-stack project uses the library at runtime and the CLI in CI scripts and operator workflows.

---

## Quick start

### 1. Render a document

Create `report.json`:

```json
{
  "title": "April 2026 Report",
  "blocks": [
    { "type": "heading", "text": "April 2026 Report", "level": 1 },
    { "type": "paragraph", "text": "Summary for the financial period ending 30 April 2026." },
    { "type": "list", "style": "bullet", "items": [
      "Revenue: +18% year-on-year",
      "Net Promoter Score: 72",
      "Active customers: 12,400"
    ]},
    { "type": "table",
      "headers": ["Quarter", "Revenue", "Profit"],
      "rows": [
        { "cells": ["Q1", "$1.2M", "$400K"], "type": "credit", "pointed": false },
        { "cells": ["Q2", "$1.5M", "$600K"], "type": "credit", "pointed": true }
      ]
    }
  ],
  "footerText": "Confidential",
  "metadata": { "author": "Finance Team", "subject": "April 2026 Report" }
}
```

Render it:

```bash
pdfnative render --input report.json --output report.pdf
```

That's it — the file `report.pdf` is now a valid ISO 32000-1 PDF, ready to send.

### 2. Sign the rendered PDF (with metadata)

```bash
# Set keys via environment variables (recommended for CI/CD — never logged)
export PDFNATIVE_SIGN_KEY="$(cat private.pem)"
export PDFNATIVE_SIGN_CERT="$(cat cert.pem)"

pdfnative sign \
  --input report.pdf \
  --output report.signed.pdf \
  --reason "Approved by Finance" \
  --name "Finance Team" \
  --location "Paris, FR" \
  --signing-time 2026-04-28T10:00:00Z
```

The CLI accepts both **RSA PKCS#1 v1.5** and **ECDSA P-256** keys, both with SHA-256 digests. The signed PDF carries a CMS/PKCS#7 signature embedded as ISO 32000-1 §12.8 prescribes, validatable by Adobe Acrobat, MuPDF, and any other PAdES-compatible reader.

### 3. Verify embedded signatures

```bash
pdfnative verify --input report.signed.pdf --strict --trust ca-root.pem
```

v0.3.0 performs **real CMS/PKCS#7 verification** — the CLI recomputes the byte-range digest, validates the signature value (RSA-SHA256 or ECDSA-SHA256), walks the certificate chain via `pdfnative`'s `verifyCertSignature`, evaluates trust against `--trust` roots and self-signed acceptance, and reports the presence of an RFC 3161 timestamp token. Exit code is 0 on success, 1 on any failure under `--strict`.

A sample JSON report:

```json
{
  "signatures": [
    {
      "integrity": true,
      "signatureValid": true,
      "signatureAlgorithm": "ecdsa-sha256",
      "chainValid": true,
      "trustedRoot": true,
      "timestampPresent": false,
      "signerSubject": "CN=pdfnative-cli ECDSA Test, O=pdfnative-cli, C=FR",
      "signerIssuer": "CN=pdfnative-cli ECDSA Test, O=pdfnative-cli, C=FR",
      "notes": ["no --trust provided; accepted self-signed root"]
    }
  ]
}
```

<!-- legacy anchor preserved for incoming external links -->
<a id="pdfnative-verify-new-in-v020"></a>

### 4. Inspect any PDF

```bash
pdfnative inspect --input report.signed.pdf --format text
```

```
Version:        1.7
Pages:          2
Encrypted:      no
PDF/A:          none
Signatures:     1
Title:          April 2026 Report
Author:         Finance Team
Created:        2026-04-28T10:00:00+00:00
Subject:        April 2026 Report
Producer:       —
```

JSON output (default) is suited for piping into `jq` or storing as a CI artifact.

---

## Hybrid layout model

`render` adopts the same layout philosophy as `gh`, `kubectl`, and `docker`: high-frequency knobs are first-class flags, while the full `PdfLayoutOptions` shape is reachable via a JSON layout file.

**Precedence:** `CLI flags > --layout file > pdfnative defaults`.

```bash
# 1) Flags only — best for ad-hoc invocations
pdfnative render --input doc.json --output report.pdf \
  --page-size A4 --margin 50 --compress --tagged pdfa2b

# 2) Layout file only — best for reproducible CI configs
pdfnative render --input doc.json --output report.pdf \
  --layout layout.json

# 3) Hybrid — base config in a file, per-job overrides on the CLI
pdfnative render --input doc.json --output report.pdf \
  --layout layout.json \
  --watermark-text "DRAFT $(date +%Y-%m-%d)"
```

`layout.json` accepts any subset of `PdfLayoutOptions`:

```json
{
  "pageSize": { "width": 595, "height": 842 },
  "margin": { "top": 60, "right": 50, "bottom": 60, "left": 50 },
  "compress": true,
  "tagged": "pdfa2b",
  "headerTemplate": { "left": "{title}", "right": "{date}" },
  "footerTemplate": { "center": "Page {page} / {pages}" }
}
```

> **Security:** `--layout` paths are validated against directory traversal, and any `attachments[].data` field embedded in the JSON is **stripped on load**. Binary attachment payloads must come from `--attachment <path>` so the CLI can apply the same path-validation rules.

---

## Command reference

### `pdfnative render`

Renders a JSON document into a PDF. Supports both renderer variants exposed by `pdfnative`.

#### Core flags

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | JSON file ([`DocumentParams`](https://pdfnative.dev/#api) for `--variant document`, `PdfParams` for `--variant table`) |
| `--output <file>` | stdout | Output PDF path |
| `--variant document\|table` | `document` | Selects `buildDocumentPDFBytes` (free-form) or `buildPDFBytes` (table-centric) |
| `--stream` | off | Streaming output via `buildDocumentPDFStream` (`AsyncGenerator<Uint8Array>`) — recommended for >100-page documents |
| `--stream-page-by-page` | off | Streaming chunked at PDF object boundaries. Assembles the full document first, so TOC blocks and `{pages}` **are** supported. Mutually exclusive with `--stream` |
| `--stream-true` *(v1.1.0)* | off | Streaming via `buildDocumentPDFStreamTrue` / `buildPDFStreamTrue` — PDF parts are emitted and freed as they go, so the joined binary never materialises. Byte-identical to the buffered builders. Same constraints as `--stream` (no TOC, no `{pages}`); mutually exclusive with the other `--stream*` flags |
| `--max-blocks <n>` *(v1.1.0)* | `100000` | Exposes `layout.maxBlocks` so very large multi-thousand-page reports no longer hit a spurious ceiling |
| `--layout <file.json>` | — | Load any subset of `PdfLayoutOptions` |
| `--chunk-size <n>` *(v1.4.0)* | `65536` | Chunk size in bytes for the `--stream` / `--stream-true` output (not applicable to `--stream-page-by-page`) |
| `--strict` *(v1.4.0)* | off | Escalate PDF/A diagnostics (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`, `PDFA_DEVICE_CMYK_IMAGE`) into a hard failure **before the first output byte** — exit 1, `E_CHECK_FAILED`. Without it they are `warning:` lines on stderr (hidden by `--quiet`) plus an additive `diagnostics[]` array in the `--json` envelope |

#### Smart tables _(v1.3.0, document variant)_

These flags fill `TableBlock` fields left unset in the JSON (caption is per-table — set it in the JSON `TableBlock`):

| Flag | Description |
|------|-------------|
| `--table-wrap <mode>` | `auto` (default), `always`, or `never` |
| `--repeat-header [true\|false]` | Repeat the header row on continuation pages |
| `--zebra [true\|false\|"R G B"]` | Alternate-row striping |
| `--min-row-height <pt>` | Minimum row height in points |
| `--cell-padding <pt>` | Horizontal cell padding in points |

#### Page geometry

| Flag | Default | Description |
|------|---------|-------------|
| `--page-size <name\|WxH>` | `a4` | Named (`a4`, `letter`, `legal`, `a3`, `tabloid`, `a5`) or `WxH` in points |
| `--margin <N>` or `<t,r,b,l>` | `50` | Uniform or per-side margin in points |
| `--compress` | off | Apply `/Filter /FlateDecode` to all content streams |

#### PDF/A conformance

| Flag | Default | Description |
|------|---------|-------------|
| `--tagged <level>` | `none` | Unified PDF/A flag: `none`, `pdfa1b`, `pdfa2b`, `pdfa2u`, `pdfa3b` |
| `--conformance <level>` | — | **Deprecated.** Maps to `--tagged pdfa<level>` with a one-line stderr notice. Removed in v1.0.0 |

#### Watermarks

| Flag | Description |
|------|-------------|
| `--watermark-text <str>` | Diagonal text watermark |
| `--watermark-image <path>` | Image watermark (PNG/JPEG, centered, aspect-preserved) |
| `--watermark-opacity <0..1>` | ExtGState `/ca` value |
| `--watermark-angle <deg>` | Rotation angle |
| `--watermark-color <hex\|R,G,B>` | Fill color (text only) |
| `--watermark-font-size <pt>` | Font size (text only) |
| `--watermark-position background\|foreground` | Drawing order vs. content |

> Watermarks with transparency are **mutually exclusive** with PDF/A-1b (ISO 19005-1 §6.4). The pdfnative core enforces this at render time — the run fails with the generic exit code 1 (`Watermark transparency is not allowed with PDF/A-1b`), not a CLI usage error.

#### Headers / footers

| Flag | Description |
|------|-------------|
| `--header-left <str>` / `--header-center` / `--header-right` | Page-template zones |
| `--footer-left <str>` / `--footer-center` / `--footer-right` | Page-template zones |

Supported placeholders: `{page}`, `{pages}`, `{date}`, `{title}`. The `{pages}` placeholder is rejected with `--stream` because the total page count is only known after multi-pass pagination.

#### Encryption

Since v1.3.0, `render` speaks the same **unified encryption vocabulary** as `merge` / `split` / `extract`:

| Flag | Env var | Description |
|------|---------|-------------|
| `--encrypt [aes-128\|aes-256]` | — | Enable encryption (bare `--encrypt` = `aes-128`) |
| `--owner-password <pass>` | `PDFNATIVE_ENCRYPT_OWNER_PASS` | **Required** whenever encryption is requested |
| `--user-password <pass>` | `PDFNATIVE_ENCRYPT_USER_PASS` | Optional password needed to open the document |
| `--permissions <list>` | — | Comma list: `print`, `copy`, `modify`, `extract` |

The legacy v0.2.0 flags — `--encrypt-algorithm`, `--encrypt-owner-pass`, `--encrypt-user-pass`, `--encrypt-permissions` — remain accepted as aliases; when both are given, the unified value wins.

Env vars take precedence over flags, ensuring secrets never appear in shell history. Encryption is **mutually exclusive** with `--tagged pdfa*` per ISO 19005-1 §6.3.2 — rejected with exit 2.

#### PDF/A-3 attachments

| Flag | Description |
|------|-------------|
| `--attachment <path>[:mime[:rel[:desc]]]` | Embed a file as `/EmbeddedFile`. Repeatable |

The Windows drive-letter colon (`D:\path`) is detected and not split — see *Troubleshooting*.

#### Multilingual fonts

| Flag | Description |
|------|-------------|
| `--lang <code,code>` | Activate font loaders for the listed languages (e.g. `th,ja,ar,te,si,km`) |
| `--font <name>` *(v1.1.0)* | Register a bundled pdfnative font shortcut. Repeatable. Allow-list covers every bundled font: `latin`, `emoji`, `color-emoji`, `math` *(v1.2.0)*, and the 22 script codes (`ar hy bn ru hi am ka el he ja km ko my pl zh si ta te th bo tr vi`). Each shortcut name doubles as its `--lang` code |

`--lang` activates a *programmatically registered* font loader via `loadFontData(code)`. Latin scripts are built-in. With v1.1.0, every bundled font is registrable directly through `--font` — no wrapper script needed for the 22 bundled scripts, colour emoji, or Latin. pdfnative routes each code point to the font whose cmap covers it. See *Recipes → Multilang fonts* only for fonts you ship yourself (those require calling the library directly).

#### Bookmarks, math &amp; layout tooling _(v1.2.0)_

| Flag | Description |
|------|-------------|
| `--outline auto\|<tree.json>` | Add a navigable PDF bookmark tree (`/Outlines`). `auto` derives it from the document's headings; a file supplies an explicit `OutlineItem[]` tree |
| `--font math` | Register the bundled **Noto Sans Math** font; pdfnative auto-routes math-operator and geometric-shape code points to it |
| `--inspect-layout` | Emit a `LayoutInspection` JSON report (per-page blocks, positions, sizes) instead of a PDF (document variant only) |
| `--debug-layout [margins,content,cells]` | Render a normal PDF with the opt-in layout-debug guides overlaid |

```bash
# Bookmarks derived from headings + math font
pdfnative render --input paper.json --output paper.pdf --outline auto --font math

# Layout introspection instead of a PDF
pdfnative render --input report.json --inspect-layout > layout.json
```

#### Print production, images from JSON &amp; charts v2 _(v1.4.0)_

Everything here rides on the pdfnative 1.7.0 engine and is reachable through the existing `--layout` file and the document JSON — no new flags needed:

- **Image blocks in the document JSON** — `{ "type": "image", "src": "logo.png" }` (path resolved relative to the `--input` JSON, same validation as `--attachment`) or `{ "type": "image", "dataBase64": "…" }` for inline JPEG/PNG.
- **`layout.print`** — `bleed`, `trimBox` / `bleedBox` / `artBox` / `cropBox`, vector printer's marks (`print.marks`), and `/UserUnit` (1–75 000). `merge` / `split` / `extract` now preserve these boxes too.
- **`layout.outputIntent`** — a custom RGB ICC output intent; **`layout.viewerPreferences`** — `duplex`, `pickTrayByPDFSize`, `printPageRange`, `numCopies`.
- **`params.metadata`** — `author`, `subject`, `keywords`, and `trapped: True|False|Unknown`, written to `/Info` and XMP.
- **Charts v2** — the `chart` block now covers 9 types (adds `stackedBar`, `stackedBarH`, `area`, `scatter`), a secondary Y axis (`series.yAxis: "right"` + `axis2`), `category` / `linear` / `time` X axes, log scale, `dataLabels`, `labelStride`, and `labelRotation`.

#### Iteration helpers _(v0.3.0)_

| Flag | Description |
|------|-------------|
| `--watch` | Re-render on input file change. 200 ms debounce, stderr-only logs. Requires `--input <file>` and a file `--output` (stdin / stdout pipelines are not supported — watch needs a stable on-disk source) |
| `--template <file.json>` | Deep-merge a base template under stdin / `--input`. Plain objects merge recursively; arrays and primitives are replaced (caller wins). Useful for centralising title / layout / headers in CI |

```bash
# Watch a file
pdfnative render --input report.json --output report.pdf --watch

# Template + override (template carries title/layout/headers, stdin overrides body)
echo '{"blocks":[{"type":"paragraph","text":"Today only."}]}' \
  | pdfnative render --template template.json -o today.pdf

# Bundled fonts via flag (no wrapper)
echo '{"blocks":[{"type":"paragraph","text":"Hi \ud83d\ude80"}]}' \
  | pdfnative render --font latin --font emoji --lang latin,emoji -o out.pdf
```

### `pdfnative sign`

Applies a CMS/PKCS#7 digital signature to an existing PDF.

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Input PDF |
| `--output <file>` | stdout | Output signed PDF |
| `--key <file>` | `PDFNATIVE_SIGN_KEY` env | PEM-encoded private key (env var takes precedence) |
| `--cert <file>` | `PDFNATIVE_SIGN_CERT` env | PEM-encoded X.509 certificate (env var takes precedence) |
| `--cert-chain <file>` | `PDFNATIVE_SIGN_CHAIN` env | Intermediate-CA PEM (repeatable, concatenated into `certChain[]`) |
| `--algorithm <algo>` | `rsa-sha256` | `rsa-sha256` or `ecdsa-sha256` (both fully wired in v0.3.0; SEC1 / PKCS#8 P-256 keys accepted) |
| `--reason <str>` | — | `PdfSignOptions.reason` |
| `--name <str>` | — | `PdfSignOptions.name` |
| `--location <str>` | — | `PdfSignOptions.location` |
| `--contact <str>` | — | `PdfSignOptions.contact` |
| `--signing-time <ISO 8601>` | now | Explicit timestamp; validated up-front before any credential I/O |
| `--pure-crypto` *(v1.2.0)* | off | Force pdfnative's portable **pure-JS** bignum CMS path instead of the default native provider |
| `--timestamp <tsa-url>` *(v1.4.0)* | — | Embed an **RFC 3161 timestamp token** from the given TSA (PAdES **B-T** — combine with `--profile pades` for a true ETSI baseline). The only network opt-in on `sign` — SSRF-guarded, no fallback: transport failure is `E_NETWORK`, a malformed response is `E_PARSE`. `--dry-run` never touches the network |
| `--timestamp-digest <algo>` *(v1.4.0)* | `sha256` | TSA digest: `sha256`, `sha384`, or `sha512` |
| `--timestamp-nonce <hex>` *(v1.4.0)* | random | Explicit RFC 3161 nonce (testing / reproducibility) |
| `--digest <algo>` *(v1.4.0)* | `sha256` | CMS digest for RSA keys: `sha256`, `sha384`, or `sha512`. Combining `sha384`/`sha512` with `--algorithm ecdsa-sha256` is a usage error (exit 2) — ECDSA is SHA-256 only |
| `--profile <p>` *(v1.4.0)* | `pkcs7` | `pkcs7` or `pades` — `pades` emits `ETSI.CAdES.detached` with the ESS signing-certificate-v2 attribute and omits signing-time |
| `--allow-multiple` *(v1.4.0)* | off | Add a signature to an already-signed PDF instead of refusing (the 1.x idempotent default is preserved) |
| `--field-name <name>` *(v1.4.0)* | auto | Explicit signature field name (auto-suffixed on collision) |
| `--signature-rect <x1,y1,x2,y2>` / `--signature-page <n>` *(v1.4.0)* | invisible | Place a visible signature widget |
| `--placeholder-bytes <n>` *(v1.4.0)* | auto | Reserve a larger `/Contents` placeholder (e.g. for long chains or large timestamp tokens) |

> **Native constant-time signing (v1.2.0).** `sign` now routes CMS signing through Node's `node:crypto` by default (via `createNativeCryptoProvider`), for side-channel-resistant RSA/ECDSA. Pass **`--pure-crypto`** to select the portable pure-JS path (e.g. on a runtime without `node:crypto`).

> **PAdES B-T (v1.4.0).** `--timestamp <tsa-url>` — previously a reserved flag that failed with `E_UNSUPPORTED` — is now functional: the CLI POSTs an RFC 3161 request through its SSRF guard, verifies the token, and embeds it in the CMS unsigned attributes via `signPdfBytesWithTimestamp`. Pair it with `--profile pades`: the default `pkcs7` profile writes `/SubFilter /adbe.pkcs7.detached`, a valid CMS signature but not an ETSI EN 319 142-1 baseline. The typical ladder:
>
> ```bash
> pdfnative sign --timestamp <tsa> --profile pades   # → B-T
> pdfnative ltv add --online                         # → B-LT
> pdfnative doc-timestamp --url <tsa>                # → B-LTA
> pdfnative ltv add --online                         # LTV for the doc-timestamp itself
> ```
>
> Continue with [`ltv`](#pdfnative-ltv-v140) (B-LT) and [`doc-timestamp`](#pdfnative-doc-timestamp-v140) (B-LTA) below.

Signing keys are **never logged** — not in error output, not in debug traces, not in stack traces. The CLI redacts them at every code path that surfaces error context.

### `pdfnative inspect`

Inspects metadata and conformance of an existing PDF. Read-only — never modifies the input.

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Input PDF |
| `--format <fmt>` | `json` | `json` or `text` |
| `--verbose` | off | Adds `verbose.{trailerKeys, catalogKeys, objectCount, xmpMetadata}`. Sanitised — no raw stream bytes |
| `--pages` | off | Adds `pages: [{ index, width, height, rotation, annotations, formFields }]` — since v1.4.0 also `cropBox` / `trimBox` / `bleedBox` / `artBox` and `userUnit` when present. (`metadata.trapped` is reported unconditionally since v1.4.0, with or without `--pages`) |
| `--pdfua` *(v1.1.0)* | off | Adds a `pdfua: { valid, errors, warnings }` report from `validatePdfUA()` (ISO 14289-1 structural checks: MarkInfo, StructTree, ParentTree, Lang, per-page MCID uniqueness) |
| `--annotations` *(v1.2.0)* | off | Lists markup + link annotations per page (from `getAnnotations()`). `/PageLabels` are reported automatically when present |
| `--form-fields` *(v1.3.0)* | off | Lists AcroForm fields (name, type, value, required/read-only) |
| `--encryption` *(v1.3.0)* | off | Reports the encryption scheme (algorithm, revision, opened-as) |
| `--password <pass>` *(v1.3.0)* | — | Password for an encrypted PDF (env `PDFNATIVE_PASSWORD`) |
| `--signatures` *(v1.4.0)* | off | Structural signature inventory via `listSignatures()` — `fieldName`, `subFilter`, `byteRange`, `isDocTimestamp`, `isPlaceholder`, `sigObjNum`, `contentsLength`. Never emits the signature bytes themselves |
| `--check <assertion>` | — | Repeatable; ANDed. Values: `pdfa`, `signed`, `encrypted`, `pdfua` *(v1.1.0)*, `signatures>=N` *(v1.4.0)*. Sets exit 0 = pass, 1 = fail |
| `--summary` *(v1.1.0)* | off | Under `--json`, emit a canonical minimal verdict (`{ pages, encrypted, signatures, pdfa }`) |
| `--fields <a,b.c>` *(v1.1.0)* | — | Project the JSON result to named dot-paths (array segments map over elements; unknown paths omitted) |
| `--pretty` | off | Force indented JSON even under the global `--json` (agent mode is compact) |

Composable example:

```bash
pdfnative inspect --input dist/q1.pdf \
  --check pdfa --check signed \
  --format json > dist/q1.report.json
echo "exit code: $?"   # 0 if both assertions hold
```

> **Behaviour change in v1.4.0:** `--check signed` now counts only *actual* signatures — unsigned placeholders and `/DocTimeStamp` revisions no longer satisfy it. A placeholder-only PDF that passed under v1.3.0 fails under v1.4.0; this is a deliberate correctness fix. v1.4.0 also fixes the `signatures` and `formFields` counters in the JSON body, which previously always reported 0. Use `--check "signatures>=1"` together with `--signatures` when you need the structural inventory.

### `pdfnative verify`

Verifies CMS/PKCS#7 signatures embedded in a PDF.

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Input PDF |
| `--format <fmt>` | `json` | `json` or `text` |
| `--strict` | off | Exit 1 on any failure or zero signatures |
| `--trust <pem>` | — | Trust-anchor certificate (repeatable) |
| `--revocation <mode>` | `offline` | `offline` (embedded `/DSS` only), `online` (opt-in, SSRF-guarded OCSP/CRL fetch), or `disabled` |
| `--revocation-policy <p>` | `soft-fail` | `soft-fail` or `strict` |
| `--summary` *(v1.1.0)* | off | Under `--json`, emit a minimal verdict (`{ valid, signatures, invalid }`) |
| `--fields <a,b.c>` *(v1.1.0)* | — | Project the JSON result to named dot-paths |
| `--pretty` | off | Indented JSON even under the global `--json` |

**Scope (since v1.0.0):**

- ✅ Byte-range integrity (SHA-256 recomputed and compared with CMS `messageDigest` attribute)
- ✅ Signature value verification — RSA-SHA256, ECDSA-SHA256, and *(v1.4.0)* RSA-SHA384 / RSA-SHA512
- ✅ Certificate chain verification via `pdfnative`'s `verifyCertSignature`
- ✅ Trust evaluation against `--trust` roots, with self-signed acceptance for testing
- ✅ **RFC 3161 timestamp validation (PAdES-T)** — TSA signature, `messageImprint` binding, chain, `genTime`
- ✅ **OCSP (RFC 6960) + CRL (RFC 5280) revocation** — embedded `/DSS` offline by default, opt-in SSRF-guarded online via AIA / CDP
- ✅ *(v1.4.0)* **`/DocTimeStamp` revisions** validated as RFC 3161 tokens; each signature in the report now carries `fieldName` and `isDocTimestamp` (additive fields, no new flags)

> Since v1.4.0 the CLI also **creates** LTV material — `sign --timestamp` (B-T), [`ltv`](#pdfnative-ltv-v140) (B-LT `/DSS`), and [`doc-timestamp`](#pdfnative-doc-timestamp-v140) (B-LTA) — so `verify` and the write side now cover the same PAdES ladder.

### `pdfnative ltv` _(v1.4.0)_

Embeds long-term-validation material — certificates, OCSP responses, CRLs — into a signed PDF's `/DSS` dictionary (PAdES **B-LT**), via the engine's `collectValidationInfo` / `embedValidationInfo` / `addValidationInfo`.

```bash
# Connected machine: gather the revocation evidence as replayable JSON
pdfnative ltv collect --input signed.pdf --online --output ltv-data.json

# Air-gapped machine: embed it — no network I/O is even possible here
pdfnative ltv embed --input signed.pdf --data ltv-data.json --output signed.lt.pdf

# Or both in one pass on a connected machine
pdfnative ltv add --input signed.pdf --online --output signed.lt.pdf
```

| Flag | Default | Description |
|------|---------|-------------|
| `collect` \| `embed` \| `add` | — *(required)* | Subcommand: gather evidence, embed evidence, or both |
| `--input <file>` | stdin | Signed source PDF |
| `--output <file>` | stdout | Destination — `collect` writes the evidence JSON, `embed`/`add` write the PDF |
| `--online` | off | **Required for `collect` / `add`** — the explicit network opt-in (refused with exit 2 without it). `embed` is 100 % offline by design |
| `--data <file>` | — | Evidence JSON produced by `collect` (for `embed`) |
| `--prefer <src>` | — | `ocsp` or `crl` when both are available |
| `--extra-cert <pem>` | — | Additional certificate for the `/DSS` (repeatable) |
| `--timeout <ms>` | `10000` | Per-fetch network timeout |
| `--dry-run` | off | Validate without writing |

The evidence JSON (`schema ltv-data`, versioned, DER as base64) is the air-gap bridge: `collect` on a connected machine, transfer the JSON, `embed` inside the enclave. Network fetches go through the same SSRF guard as `verify --revocation online`; failures surface as `E_NETWORK`.

### `pdfnative doc-timestamp` _(v1.4.0)_

Appends an RFC 3161 **document timestamp** revision (`/DocTimeStamp`, `/SubFilter /ETSI.RFC3161` — ISO 32000-2 §12.8.5) covering every byte of the document (PAdES **B-LTA**). Earlier revisions stay byte-identical; run it again years later to renew the protection before the TSA's certificate expires.

```bash
pdfnative doc-timestamp --input signed.lt.pdf \
  --url https://tsa.example.com/rfc3161 --output signed.lta.pdf
```

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Source PDF |
| `--output <file>` | stdout | Output PDF |
| `--url <tsa-url>` | — *(required)* | TSA endpoint — requiring it makes the network use an explicit opt-in |
| `--digest <algo>` | `sha256` | `sha256`, `sha384`, or `sha512` |
| `--field-name <name>` | `DocTimeStamp1` | Field name (auto-suffixed on collision) |
| `--placeholder-bytes <n>` | `12288` | Reserved `/Contents` size for the token |
| `--nonce <hex>` | random | Explicit RFC 3161 nonce |
| `--timeout <ms>` | `10000` | Network timeout |
| `--dry-run` | off | Validate without writing (never touches the network) |

### `pdfnative merge` _(v1.2.0)_

Concatenates **2–50** PDFs into one document, in order, via `mergePdfs`.

```bash
pdfnative merge a.pdf b.pdf c.pdf --output combined.pdf
```

| Flag | Default | Description |
|------|---------|-------------|
| `<paths…>` / `--input <file>` | — *(required)* | Source PDFs — positional paths and/or repeatable `--input`. 2–50 total |
| `--output <file>` | stdout | Output PDF |
| `--drop-annotations` | off | Drop non-link annotations from the sources |
| `--max-output-size <bytes>` | 256 MiB | Reject an output larger than this ceiling |
| `--password <pass>` *(v1.3.0)* | — | Password for encrypted sources (env `PDFNATIVE_PASSWORD`). One password is applied to every source; mixed passwords fail with `E_PASSWORD` |
| `--encrypt [aes-128\|aes-256]` *(v1.3.0)* | — | Re-encrypt the output (bare = `aes-128`); needs `--owner-password` |
| `--owner-password` / `--user-password` *(v1.3.0)* | — | Passwords for `--encrypt` (env `PDFNATIVE_ENCRYPT_OWNER_PASS` / `_USER_PASS`) |
| `--permissions <list>` *(v1.3.0)* | `print,extract` | Comma list: `print`, `copy`, `modify`, `extract` — without the flag, print and extract are allowed, copy and modify denied |
| `--stream` *(v1.3.0)* | off | Constant-memory streaming output (`--chunk-size N`) |
| `--dry-run` | off | Validate inputs without writing output |

> Encrypted sources are **supported since v1.3.0** via `--password` (a single password applied to every source), and the output can be re-encrypted via `--encrypt`. Signatures and `/AcroForm` are dropped (page edits invalidate `/ByteRange`); self-contained URI `/Link` annotations are preserved. Every path — positionals included — is validated against traversal.

### `pdfnative split` _(v1.2.0)_

Splits one PDF into many via `splitPdf` — one output per page (default) or one per comma-separated range.

```bash
# One output per page
pdfnative split --input report.pdf --output-dir pages/ --prefix page

# One output per range (1-based, inclusive)
pdfnative split --input report.pdf --output-dir out/ --pages "1-2,3-4"
```

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Source PDF |
| `--output-dir <dir>` | — *(required)* | Destination directory; parts are written as `<prefix>-<n>.pdf` (zero-padded) |
| `--prefix <str>` | input basename (`part` on stdin) | Output filename prefix |
| `--pages <ranges>` | per-page | Comma-separated 1-based inclusive ranges (e.g. `1-2,3-4`) |
| `--max-output-size <bytes>` | 256 MiB | Per-part output ceiling |
| `--password <pass>` *(v1.3.0)* | — | Password for an encrypted source (env `PDFNATIVE_PASSWORD`) |
| `--encrypt [aes-128\|aes-256]` *(v1.3.0)* | — | Re-encrypt each output (needs `--owner-password`; `--user-password` / `--permissions` as in `merge`) |
| `--stream` *(v1.3.0)* | off | Constant-memory streaming output (`--chunk-size N`) |
| `--dry-run` | off | Validate without writing |

### `pdfnative extract` _(v1.2.0)_

Pulls a selected, order-preserving subset of pages into a single PDF via `extractPages`.

```bash
pdfnative extract --input report.pdf --output cover.pdf --pages "4,1-2"
```

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Source PDF |
| `--output <file>` | stdout | Output PDF |
| `--pages <list>` | — *(required)* | 1-based page list/ranges; **order is preserved and repeats are allowed** |
| `--max-output-size <bytes>` | 256 MiB | Output ceiling |
| `--password <pass>` *(v1.3.0)* | — | Password for an encrypted source (env `PDFNATIVE_PASSWORD`) |
| `--encrypt [aes-128\|aes-256]` *(v1.3.0)* | — | Re-encrypt the output (needs `--owner-password`; `--user-password` / `--permissions` as in `merge`) |
| `--stream` *(v1.3.0)* | off | Constant-memory streaming output (`--chunk-size N`) |
| `--dry-run` | off | Validate without writing |

### `pdfnative annotate` _(v1.2.0)_

Attaches markup annotations to an existing PDF via an **incremental save**, so the original bytes — and any existing signature — stay intact.

```bash
pdfnative annotate --input report.pdf --output annotated.pdf \
  --annotations notes.json
```

`notes.json` is a JSON array (or `{ "annotations": […] }`), each entry a markup annotation plus a 1-based `page`:

```json
[
  { "page": 1, "type": "highlight", "rect": [72, 700, 520, 715], "color": "#ffe066", "contents": "Review this clause" },
  { "page": 2, "type": "text", "rect": [80, 640, 100, 660], "contents": "Sticky note" }
]
```

Supported types: `text`, `highlight`, `underline`, `strikeout`, `squiggly`, `square`, `circle`, `line`, `freetext`. Only known fields are forwarded (no dictionary injection). Read them back with `inspect --annotations`. Since v1.4.0, `--password <pass>` (env `PDFNATIVE_PASSWORD`) lets you annotate an encrypted PDF — the added objects are encrypted under the document's existing scheme.

> **Overlay, not redaction.** Annotations are a *visual review layer*; the underlying bytes remain. They do **not** remove or obscure content for security purposes.

### `pdfnative metadata` _(v1.4.0)_

Updates `/Info` and XMP metadata via an **incremental save** — the original bytes are kept as a prefix, so existing signatures remain valid for their revision. `xmp:ModifyDate` and `pdf:Keywords` stay synchronised. Reading metadata remains `inspect`'s job.

```bash
pdfnative metadata --input report.pdf --output revised.pdf \
  --title "Quarterly report (revised)" --keywords "finance,Q2"
```

| Flag | Default | Description |
|------|---------|-------------|
| `--input <file>` | stdin | Source PDF |
| `--output <file>` | stdout | Output PDF |
| `--title` / `--author` / `--subject` / `--keywords` | — | Individual `/Info` + XMP fields (at least one field is required) |
| `--mod-date <ISO 8601>` | now | Explicit modification date |
| `--from-json <file>` | — | All fields from a JSON file (`schema metadata`) — mutually exclusive with the individual flags |
| `--password <pass>` | — | Open an encrypted source (env `PDFNATIVE_PASSWORD`) |
| `--dry-run` | off | Validate without writing |

### `pdfnative govern` _(v1.2.0)_

Surfaces pdfnative's **AI-governance / Human-in-the-Loop (HITL)** contract. Agents act as **draftsmen**: a human must always review and submit under their own GitHub identity.

```bash
pdfnative govern rules                  # human/agent protocol (AGENT_RULES)
pdfnative govern policy --json          # machine-readable policy JSON
pdfnative govern verify-issue draft.md  # gate a draft (exit 1 / E_POLICY)
```

| Subcommand | Description |
|------|-------------|
| `rules` | Print the human-and-agent protocol (mirrors `.github/AGENT_RULES.md`) |
| `policy [--json]` | Print the governance policy (mirrors `.github/ai-governance.json`) |
| `verify-issue <draft.md>` | Gate a local issue draft; exit `1` / `E_POLICY` on a violation (proposes a runtime dependency, omits a reproduction code block). Missing recommended fields surface as warnings |

> `verify-issue` is a pure, **fully offline** validator — no GitHub or network access. A passing check is *necessary but not sufficient*: the human review gate always applies.

### `pdfnative fill` _(v1.3.0)_

Fill, flatten or export an AcroForm. The three modes compose into a round trip:
export the current values, edit the JSON, feed it back.

```bash
pdfnative fill --input form.pdf --export --output values.json   # read
pdfnative fill --input form.pdf --data values.json --output filled.pdf
pdfnative fill --input filled.pdf --flatten --output flat.pdf   # freeze
```

| Flag | Default | Purpose |
|---|---|---|
| `--data <file>` | — | Values JSON. Required unless `--flatten` or `--export` |
| `--flatten` | off | Flatten after filling, or flatten the existing values |
| `--export` | off | Read-only: emit current values in `--data` shape |
| `--force` | off | Flatten even when a signed signature field is present |
| `--on-unknown <mode>` | `throw` | `throw` or `ignore` for unknown field names |
| `--need-appearances` | off | Set `/NeedAppearances` to allow non-WinAnsi values |
| `--password <pass>` | — | Open an encrypted form (env `PDFNATIVE_PASSWORD`) |
| `--dry-run` | off | Validate and enumerate fields without writing |

Flattening a signed document invalidates the signature, which is why `--force`
exists rather than it being silent.

### `pdfnative encrypt` _(v1.3.0)_

Re-secure an existing PDF. `--owner-password` is required; without a
`--user-password` the document **opens with no prompt** and the owner password
only governs permissions.

```bash
pdfnative encrypt --input report.pdf --output secure.pdf \
  --owner-password "$OWNER" --user-password "$USER" \
  --algorithm aes-256 --permissions print,extract
```

| Flag | Default | Purpose |
|---|---|---|
| `--owner-password <pass>` | — | **Required.** Env `PDFNATIVE_ENCRYPT_OWNER_PASS` |
| `--user-password <pass>` | — | Password needed to open. Env `PDFNATIVE_ENCRYPT_USER_PASS` |
| `--algorithm <alg>` | `aes-128` | `aes-128` or `aes-256` |
| `--permissions <list>` | `print,extract` | Comma-separated: `print`, `copy`, `modify`, `extract` — without the flag, print and extract are allowed, copy and modify denied |
| `--password <pass>` | — | Open an already-encrypted source (password rotation) |
| `--drop-annotations` | off | Drop all annotations; the default keeps URI links |
| `--max-output-size <n>` | 256 MiB | Cap on the assembled size |
| `--stream` | off | Stream the output (`--chunk-size N`) |
| `--dry-run` | off | Validate without writing |

### `pdfnative decrypt` _(v1.3.0)_

Remove encryption, given the password. Reads RC4, AES-128 and AES-256 sources.

```bash
pdfnative decrypt --input secure.pdf --password "$PASS" --output plain.pdf
```

| Flag | Default | Purpose |
|---|---|---|
| `--password <pass>` | — | Document password. Env `PDFNATIVE_PASSWORD` |
| `--drop-annotations` | off | Drop all annotations; the default keeps URI links |
| `--max-output-size <n>` | 256 MiB | Cap on the assembled size |
| `--stream` | off | Stream the output (`--chunk-size N`) |
| `--dry-run` | off | Validate without writing |

### `pdfnative extract-text` _(v1.3.0)_

Reading-order Unicode text from an existing PDF. `ndjson` emits one JSON object
per page, which makes it a natural feed for a RAG ingestion pipeline.

```bash
pdfnative extract-text --input paper.pdf --format ndjson --runs > pages.ndjson
pdfnative extract-text --input paper.pdf --pages 1,3,5-7 --format text
```

| Flag | Default | Purpose |
|---|---|---|
| `--format, -f <fmt>` | `text` | `text`, `json`, or `ndjson` (one object per page) |
| `--pages <selector>` | all | 1-based selector, e.g. `1,3,5-7` |
| `--runs` | off | Include positioned runs `{ text, x, y, fontSize, fontName }` |
| `--password <pass>` | — | Extract from an encrypted PDF |
| `--max-length <n>` | 16000000 | Hard cap on total characters; `0` disables |
| `--summary` | off | (json) Emit only `{ pages, characters }` |
| `--fields <paths>` | — | (json) Comma-separated dot-paths to keep |

Text comes from the `/ToUnicode` mapping, so it is real Unicode rather than
glyph indices. A page whose content decodes entirely to U+FFFD is reported as
not extractable rather than returning noise.

### `pdfnative compare` _(v1.4.0)_

Compares two PDFs by extracted text and by structure — page count, page/print boxes, metadata, form fields, annotations, encryption, signatures. Built for CI: identical documents exit 0; differences print the report on stdout **first**, then exit 1 with `E_CHECK_FAILED`.

```bash
pdfnative compare golden.pdf candidate.pdf --mode both --format json --pretty
```

| Flag | Default | Description |
|------|---------|-------------|
| `<a.pdf> <b.pdf>` | — *(required)* | The two documents, as positionals |
| `--mode <m>` | `both` | `text`, `structure`, or `both` |
| `--format <fmt>` | `text` | `text` or `json` |
| `--tolerance <pt>` | `0` | Geometric tolerance in points for box comparisons |
| `--ignore-whitespace` | off | Normalise whitespace before the text diff |
| `--pages <selector>` | all | 1-based page selector |
| `--password-a` / `--password-b` | — | Passwords for encrypted inputs |
| `--pretty` | off | Indented JSON |

> **Not a visual diff.** pdfnative has no rasteriser, so pixel comparison is out of scope by design — `compare` diffs what the format itself declares (text and structure). Pair it with an external rasteriser if you need pixel-level checks.

### `pdfnative doctor` _(v1.3.0)_

Environment and capability preflight. The first thing to run in a new
environment, and the first thing an agent should call before planning work.

```bash
pdfnative doctor              # human-readable
pdfnative doctor --format json --pretty
```

| Flag | Default | Purpose |
|---|---|---|
| `--format, -f <fmt>` | `text` | `text` or `json` |
| `--pretty` | off | Indented JSON even under the global `--json` |

### `pdfnative batch`

Renders every JSON file in a directory to PDF **in parallel**, reusing the full `render` pipeline.

| Flag | Default | Description |
|------|---------|-------------|
| `--input-dir <dir>` | — *(required)* | Directory of `*.json` documents |
| `--output-dir <dir>` | — *(required)* | Destination directory for `*.pdf` (created if absent) |
| `--concurrency <n>` | `4` | Bounded parallelism |
| `--fail-fast` | off | Abort on the first failure |
| `--dry-run` *(v1.1.0)* | off | Validate every input without writing output |
| `--json` / `--summary` *(v1.1.0)* | off | Machine-readable per-file report; `--summary` emits `{ total, succeeded, failed }` |
| `--format <fmt>` | `text` | Report format: `text` or `json` |
| `[render options]` | — | `--layout`, `--variant`, smart tables, PDF/A, compression… — every `render` option is honoured and applied to each file |
| `--manifest <tasks.json>` *(v1.4.0)* | — | **Declarative pipeline mode** — see below. Mutually exclusive with `--input-dir` / `--output-dir` (exit 2) |
| `--allow-network` *(v1.4.0)* | off | Required before any network flag inside a manifest (`--timestamp`, `--url`, `--online`, `--revocation online`) — an untrusted manifest can never trigger network I/O on its own |
| `--continue-on-error` *(v1.4.0)* | off | Keep going after a task fails; tasks that reference the failed output via `@id` are skipped |

```bash
pdfnative batch --input-dir inputs/ --output-dir outputs/ --tagged pdfa2b --concurrency 4
```

#### Manifest mode _(v1.4.0)_

`--manifest tasks.json` runs a declarative pipeline — `{ "version": 1, "tasks": [{ "id", "command", "flags" }] }` (`schema batch-manifest`). Flag names are written **bare, without the leading dashes** (a dashed key is rejected with exit 2). A flag value of `"@<id>"` references the output of an earlier task; relative paths resolve against the manifest's directory. The whole manifest is validated **before** anything runs, then executed sequentially and fail-fast (unless `--continue-on-error`).

```json
{
  "version": 1,
  "tasks": [
    { "id": "report",  "command": "render", "flags": { "input": "report.json", "output": "report.pdf", "tagged": "pdfa2b" } },
    { "id": "stamped", "command": "metadata", "flags": { "input": "@report", "output": "final.pdf", "title": "Q2 report" } }
  ]
}
```

Only a fixed **14-command whitelist** is allowed inside a manifest — `render`, `sign`, `verify`, `inspect`, `merge`, `split`, `extract`, `extract-text`, `fill`, `encrypt`, `decrypt`, `annotate`, `metadata`, `doc-timestamp`. `ltv` and `compare` are excluded (they take positionals, which manifest tasks — a flat flag map — cannot express), and the meta commands (`batch`, `govern`, `schema`, `completion`, `doctor`) can never nest. Manifests are capped at 1 000 tasks with the same path-traversal checks as direct flags. Error classes: a structural violation, an invalid flag name or value type, or a network-reaching flag without `--allow-network` exits 2/`E_USAGE`; an invalid or duplicate task id, a non-whitelisted command, or a broken `@ref` exits 1/`E_INPUT`; malformed JSON is 1/`E_PARSE`.

### `pdfnative schema`

Prints a versioned **JSON Schema (Draft 2020-12)** for a CLI input/output shape, so agents can self-validate before invoking a command. The `$id` embeds the CLI version.

```bash
pdfnative schema render            # input schema for `render`
pdfnative schema inspect-summary   # compact inspect verdict shape
pdfnative schema list              # enumerate every subject
```

Subjects (19): `render`, `inspect`, `verify`, `batch`, `annotate` *(v1.2.0)*, `govern-verify` *(v1.2.0)*, `extract-text`, `fill`, `form-export`, `status`, `manifest`, `doctor` *(all v1.3.0)*, `metadata`, `ltv-data`, `compare`, `batch-manifest` *(all v1.4.0)*, and the compact `inspect-summary` / `verify-summary` / `batch-summary` shapes. `pdfnative schema list` enumerates them all.

### `pdfnative completion`

Emits a shell-completion script: `pdfnative completion bash|zsh|fish|powershell` *(PowerShell added in v1.3.0)*.

---

## Agent-native automation contract

v1.1.0 makes the CLI deterministic to drive from autonomous AI agents and CI pipelines. The full contract is documented in [pdfnative-cli AGENTS.md](https://github.com/Nizoka/pdfnative-cli/blob/main/AGENTS.md).

- **Global `--json` envelope.** Any command run with `--json` emits a single machine-readable object on **stderr**: `{ ok: false, command, error: { code, message } }` on failure, and a `{ ok: true, … }` status line for `render` / `sign` / `batch` on success (since v1.3.0, every write command emits the success line). stdout stays reserved for the primary artifact (PDF, report, schema, script).
- **Stable `E_*` error codes** on every failure: `E_USAGE`, `E_INPUT`, `E_PARSE`, `E_IO`, `E_SIGN`, `E_VERIFY_FAILED`, `E_CHECK_FAILED`, `E_POLICY` *(v1.2.0 — governance-gate failure)*, `E_UNSUPPORTED`, `E_PASSWORD` *(v1.3.0 — encrypted PDF: password missing or incorrect)*, `E_NETWORK` *(v1.4.0 — an opt-in network operation failed: TSA / OCSP / CRL fetch)*, `E_RUNTIME`. Numeric exit codes (0/1/2) are unchanged.
- **`--dry-run`** for `render`, `sign`, `batch`, and — since v1.2.0 — `merge`, `split`, `extract`, and `annotate` (v1.3.0 extends it to `fill`, `encrypt` and `decrypt`; v1.4.0 to `metadata`, `ltv` and `doc-timestamp`) — fully validate inputs (and, for `sign`, parse credentials and prepare the PDF) without producing output. A dry run never touches the network.
- **Global `--max-inflate-size <bytes>`** *(v1.4.0)* caps the decompressed size of each PDF stream when parsing untrusted inputs (anti zip-bomb; default 100 MiB).
- **Token-economy output projection** (`inspect` / `verify` / `batch` / `extract-text`): stdout JSON is **compact by default** under `--json` (`--pretty` opts back into the human 2-space form), **`--summary`** emits a canonical minimal verdict, and **`--fields a,b.c`** projects the result to named dot-paths. Typically ~90 % fewer output tokens with no loss of the fields agents branch on. Non-`--json` human output is unchanged.

```bash
# Agent-friendly: compact verdict on stdout, structured status on stderr
pdfnative inspect --input report.pdf --json --summary 2>status.json

# Branch on a stable error class
pdfnative verify --input report.pdf --json --strict \
  || echo "failed: $(jq -r .error.code status.json)"
```

---

## Recipes

### Render → sign → verify → inspect, in a single chain

```bash
cat report.json \
  | pdfnative render --tagged pdfa2b --compress \
  | pdfnative sign --reason "Approved" \
  | tee signed.pdf \
  | pdfnative verify --strict --trust ca.pem
pdfnative inspect --input signed.pdf --check pdfa --check signed
```

### Encrypted PDF/A-3 hybrid invoice (Factur-X / ZUGFeRD)

```bash
pdfnative render \
  --input invoice.json --output invoice.pdf \
  --tagged pdfa3b \
  --attachment factur-x.xml:application/xml:Source:"Structured invoice data" \
  --footer-center "Page {page} / {pages}"
```

### Encrypted distribution copy

```bash
pdfnative render \
  --input contract.json --output contract.encrypted.pdf \
  --encrypt-algorithm aes256 \
  --encrypt-permissions print
# PDFNATIVE_ENCRYPT_OWNER_PASS read from the env — never on the command line
```

### Multilang fonts

For the 22 bundled scripts (plus `latin`, `emoji`, `color-emoji`, `math`), no wrapper is needed — `--font` registers each bundled font inside the CLI process:

```bash
echo '{"blocks":[{"type":"paragraph","text":"สวัสดี こんにちは"}]}' \
  | pdfnative render --font th --font ja --lang th,ja -o out.pdf
```

For a font you ship yourself (not bundled), the CLI cannot use it: in-memory font registration does not cross a process boundary, so a wrapper that registers fonts and then *spawns* the CLI does not work. Call the library directly instead:

```javascript
// render-custom-font.mjs
import { registerFont, loadFontData, buildDocumentPDFBytes } from 'pdfnative';
import { writeFile } from 'node:fs/promises';

registerFont('th', () => import('./fonts/my-thai-data.js'));
const th = await loadFontData('th');
if (!th) throw new Error('Thai font failed to load');
const bytes = buildDocumentPDFBytes({
  title: 'Thai demo',
  blocks: [{ type: 'paragraph', text: 'สวัสดี' }],
  fontEntries: [{ fontData: th, fontRef: '/F3', lang: 'th' }], // /F1 and /F2 are reserved
});
await writeFile('out.pdf', bytes);
```

### CI assertion (GitHub Actions)

```yaml
- name: Render and assert PDF/A + signed
  run: |
    pdfnative render --input data/q1.json --output dist/q1.pdf --tagged pdfa2b
    pdfnative sign  --input dist/q1.pdf  --output dist/q1.signed.pdf
    pdfnative verify --input dist/q1.signed.pdf --strict
    pdfnative inspect --input dist/q1.signed.pdf --check pdfa --check signed
```

### Batch-render a directory of JSON files

```bash
for f in inputs/*.json; do
  pdfnative render --input "$f" --output "outputs/$(basename "$f" .json).pdf" --tagged pdfa2b
done
```

---

## Security model

`pdfnative-cli` is built with the same zero-trust posture as the underlying library:

- **No `eval`, no `Function`, no dynamic code** — input JSON is parsed via the standard `JSON.parse` with a 50 MB cap to prevent memory exhaustion.
- **Path traversal protection** — all `--input` / `--output` / `--key` / `--cert` / `--cert-chain` / `--trust` / `--layout` / `--attachment` / `--watermark-image` paths are validated against `..` segments before any file system access.
- **Secrets never logged** — `loadPem` / `loadPemChain` surface only generic error messages on parse failure; raw key material never appears in `CliError` messages or stderr. Encryption passwords are never echoed.
- **Layout-file injection blocked** — `attachments[].data` fields embedded in `--layout` JSON are **stripped on load**. Binary attachment payloads must come from `--attachment <path>` so the CLI can apply path validation.
- **Env-var precedence for secrets** — `PDFNATIVE_SIGN_KEY` / `PDFNATIVE_SIGN_CERT` / `PDFNATIVE_SIGN_CHAIN` / `PDFNATIVE_ENCRYPT_OWNER_PASS` / `PDFNATIVE_ENCRYPT_USER_PASS` are preferred over file-path flags so secrets never enter shell history.
- **Stdin/stdout safe** — binary streams are passed through without interpretation; no shell-quoting issues.
- **Zip-bomb cap** *(v1.4.0)* — the global `--max-inflate-size` bounds the decompressed size of every PDF stream (default 100 MiB).
- **NPM provenance** — every published version is signed via GitHub Actions OIDC. Verify with `npm audit signatures`.

The CLI opens **no network connection unless you explicitly opt in** — the only network paths are `verify --revocation online`, `sign --timestamp <url>`, `ltv --online`, `doc-timestamp --url <url>`, and `batch --allow-network`, and all of them go through the same SSRF guard: http/https only, private / loopback / metadata addresses blocked, DNS pinning, 10 s timeout, 5 MiB response cap, no redirects. Response bodies are never echoed into CLI output. It never writes to system directories outside the working directory or loads arbitrary code.

---

## Comparison with the library API

The CLI now covers nearly the full library surface; only Web Worker offloading remains library-only.

| Feature | CLI v1.4.0 | Library |
|---|---|---|
| Document rendering (13 block types) | ✅ | ✅ |
| Streaming output | ✅ `--stream` / `--stream-true` | ✅ `buildDocumentPDFStream()` / `buildDocumentPDFStreamTrue()` |
| Configurable block cap | ✅ `--max-blocks` | ✅ `layout.maxBlocks` |
| PDF/A conformance (1b, 2b, 2u, 3b) | ✅ `--tagged` | ✅ `tagged: '…'` |
| Digital signatures (RSA-SHA256/384/512) | ✅ (`--digest`, v1.4.0 for 384/512) | ✅ `signPdfBytes()` |
| Digital signatures (ECDSA-SHA256) | ✅ `--algorithm ecdsa-sha256` | ✅ `signPdfBytes()` |
| **PAdES B-T timestamp at signing** | ✅ `sign --timestamp` *(v1.4.0)* | ✅ `signPdfBytesWithTimestamp()` |
| **PAdES B-LT `/DSS` (LTV)** | ✅ `ltv collect / embed / add` *(v1.4.0)* | ✅ `collectValidationInfo()` / `embedValidationInfo()` / `addValidationInfo()` |
| **PAdES B-LTA document timestamp** | ✅ `doc-timestamp` *(v1.4.0)* | ✅ `addDocumentTimestamp()` |
| **Metadata update (signature-safe)** | ✅ `metadata` *(v1.4.0)* | ✅ `PdfModifier.updateMetadata()` |
| **Text + structure diff** | ✅ `compare` *(v1.4.0 — implemented in the CLI)* | — (compose the readers) |
| **Native constant-time signing** | ✅ default (`--pure-crypto` opts out; the native provider is a CLI utility) | ✅ `setCryptoProvider()` (accepts any `CryptoProvider`) |
| Inspection / metadata | ✅ | ✅ `PdfReader` |
| **PDF/UA structural validation** | ✅ `inspect --pdfua` | ✅ `validatePdfUA()` |
| **Annotation listing** | ✅ `inspect --annotations` | ✅ `getAnnotations()` |
| **Signature verification (CMS/PKCS#7)** | ✅ `verify` (real CMS, RSA + ECDSA — implemented in the CLI) | ➖ `openPdf()` + `verifyCertSignature()` only (X.509 certificate-signature check, not CMS PDF-signature verification) |
| **PAdES-T timestamp + OCSP/CRL revocation** | ✅ `verify --revocation` (implemented in the CLI) | — |
| **Encryption (AES-128/256)** | ✅ `--encrypt-*` | ✅ `encryption: {…}` |
| **Watermarks** | ✅ `--watermark-*` | ✅ `watermark: {…}` |
| **PDF/A-3 attachments** | ✅ `--attachment` | ✅ `attachments: [...]` |
| **22 scripts + COLRv1 emoji + math** | ✅ `--font` / `--lang` | ✅ `registerFont()` / `loadFontData()` |
| **Page-tree editing (merge / split / extract)** | ✅ `merge` / `split` / `extract` | ✅ `mergePdfs()` / `splitPdf()` / `extractPages()` |
| **Markup annotations** | ✅ `annotate` | ✅ `PdfModifier.addAnnotation()` / `buildAnnotationBody()` |
| **Bookmarks / outline** | ✅ `render --outline` | ✅ `outline: '…'` |
| **Layout introspection / debug** | ✅ `render --inspect-layout` / `--debug-layout` | ✅ `inspectDocumentLayout()` / `layout.debug` |
| **AI-governance / HITL gate** | ✅ `govern` (draft validation via the CLI's `validateGovernanceDraft()`) | — (contract files in the repo; the core's check is a repo script, not a published API) |
| **Parallel batch render** | ✅ `batch` | — (compose `render`) |
| **JSON Schema export** | ✅ `schema` | — N/A |
| **Agent-native `--json`/`E_*`/`--dry-run`** | ✅ | — N/A |
| **Table-centric variant** | ✅ `--variant table` | ✅ `buildPDFBytes()` |
| **Full `PdfLayoutOptions`** | ✅ `--layout file.json` | ✅ |
| **Web Worker offloading** | ❌ N/A | ✅ `pdfWorker.ts` |

---

## Examples — ready-to-run

The [`samples/`](https://github.com/Nizoka/pdfnative-cli/tree/main/samples) directory in the CLI repository ships **40+ ready-to-run examples** organized by feature:

| Category | What it shows |
|---|---|
| `render/document/` | Minimal document, all blocks reference, invoice, technical spec, multi-page report |
| `render/table/` | Project status, financial summary |
| `render/table-variant/` | `PdfParams`-shaped financial ledger via `--variant table` |
| `render/barcode/` | QR code, Code 128, EAN-13 |
| `render/form/` | Contact form, survey |
| `render/toc/` | Auto-generated table of contents with `/GoTo` links |
| `render/link/` | Resource directory with hyperlinks |
| `render/watermark/` | Draft / Confidential watermarks |
| `render/layout/` | US Letter, A5 portrait, A4 landscape |
| `render/pdfa/` | PDF/A-1b, 2b, 3b archival conformance |
| `render/encryption/` | AES-128 password-protected PDF |
| `render/headers-footers/` | Page templates with `{page}/{pages}/{date}/{title}` |
| `render/attachments/` | PDF/A-3 hybrid invoice with embedded XML (Factur-X / ZUGFeRD) |
| `render/multilang/` | Multilang rendering via the bundled `--font` shortcuts |
| `render/chart/` | Native vector charts (bar, line, pie, donut) *(v1.3.0)* |
| `render/math/` | Noto Sans Math font routing *(v1.2.0)* |
| `render/outline/` | `/Outlines` bookmark trees (`--outline auto` and explicit JSON) *(v1.2.0)* |
| `render/table-smart/` | Smart-table flags (`--table-wrap`, `--zebra`, …) *(v1.3.0)* |
| `render/font/`, `render/template/`, `render/watch/`, `render/inspect-layout/` | Font shortcuts, templates, watch mode, layout introspection |
| `fill/` | AcroForm fill / flatten / export round trip *(v1.3.0)* |
| `encrypt/` | Encrypt / decrypt an existing PDF *(v1.3.0)* |
| `extract-text/` | Reading-order text extraction (`text` / `json` / `ndjson`) *(v1.3.0)* |
| `merge/`, `split/`, `extract/`, `annotate/` | Page-tree editing and markup annotations *(v1.2.0)* |
| `sign/` | Bash + PowerShell signing scripts (basic + with metadata) |
| `inspect/` | JSON & text inspection, `--verbose --pages`, `--check pdfa` |
| `verify/` | Self-signed verification, strict-mode CI gating |
| `batch/`, `doctor/`, `govern/`, `completion/`, `agent/`, `config/` | Automation, preflight, governance, shell completion, agent patterns |
| `streaming/` | 200-section document via streaming render |

Render them all at once:

```bash
git clone https://github.com/Nizoka/pdfnative-cli
cd pdfnative-cli
node samples/run-all.js
```

---

## Release history

### What's new in v1.4.0

v1.4.0 is built on **pdfnative 1.7.0** (pin `^1.7.0`) and completes the signature story: the full **PAdES ladder** (B-B → B-T → B-LT → B-LTA) is now writable from the command line, alongside signature-safe metadata edits, a CI-grade document diff, and a declarative batch pipeline. **No contract change** — every flag, default, exit code, error code and envelope from 1.x behaves identically on Node ≥ 22.

| Area | v1.3.0 | v1.4.0 |
|---|---|---|
| Commands | 17 commands <!-- verify-docs:allow stale-token (v1.3.0-era count) --> | adds **`metadata`** (incremental `/Info` + XMP edits that keep signatures valid), **`ltv`** (PAdES B-LT — `collect` / `embed` / `add`, air-gap-friendly), **`doc-timestamp`** (PAdES B-LTA `/DocTimeStamp` revisions), and **`compare`** (text + structure diff with CI exit codes) |
| Signing | `--timestamp` reserved (`E_UNSUPPORTED`) | **`sign --timestamp <tsa-url>` works** (RFC 3161, PAdES B-T) with `--timestamp-digest` / `--timestamp-nonce`; plus `--digest sha384\|sha512` (RSA), `--profile pades`, `--allow-multiple`, `--field-name`, visible signatures (`--signature-rect` / `--signature-page`), `--placeholder-bytes` |
| Verification | RSA/ECDSA-SHA256 | adds **rsa-sha384 / rsa-sha512** and validates `/DocTimeStamp` revisions; per-signature `fieldName` and `isDocTimestamp` (additive) |
| Inspection | metadata, forms, encryption | adds `--signatures` (structural inventory), `--check "signatures>=N"`, print boxes (`cropBox` / `trimBox` / `bleedBox` / `artBox`, `userUnit`), `trapped`; **`--check signed` no longer counts unsigned placeholders** (correctness fix) |
| `render` | charts v1 (5 types) | **`--strict`** PDF/A gate, image blocks from JSON, print production (`layout.print`, output intent, viewer preferences, `/Trapped`), **charts v2** (9 types, dual axes, log/time scales, data labels), `--chunk-size` |
| Automation | per-directory `batch` | **`batch --manifest`** — declarative pipeline with `@id` references, a 14-command whitelist, `--allow-network` opt-in and `--continue-on-error` |
| Hardening | — | global **`--max-inflate-size`** (anti zip-bomb, default 100 MiB); all network paths opt-in behind the SSRF guard |
| Agent contract | 11 codes, 15 subjects | **`E_NETWORK`**; `schema` grows to 19 subjects (`metadata`, `ltv-data`, `compare`, `batch-manifest`); 600 tests on Node 22/24 |
| Compatibility | `pdfnative ^1.6.0`, Node ≥ 20 | `pdfnative ^1.7.0`, **Node ≥ 22** |

Full changelog: [pdfnative-cli release notes v1.4.0](https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.4.0).

### What's new in v1.3.0

v1.3.0 is built on the **pdfnative 1.6 engine** (pin `^1.6.0`) and surfaces its engine additions as five new commands (`extract-text`, `fill`, `encrypt`, `decrypt`, `doctor`), native vector charts in `render`, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent `render --encrypt` no-op. **100 % backward-compatible** with v1.2.0.

| Area | v1.2.0 | v1.3.0 |
|---|---|---|
| Commands | 12 commands <!-- verify-docs:allow stale-token (v1.2.0-era count) --> | adds **`fill`** (fill / flatten / **export** AcroForms via an incremental save), **`encrypt`**, **`decrypt`**, **`extract-text`** (reading-order Unicode text: `text` \| `json` \| `ndjson`), and **`doctor`** (offline environment / capability preflight) |
| Charts | — | the engine's `chart` document block (bar, barH, line, pie, donut — the pdfnative 1.6 set) renders as pure vector path operators through `render` |
| Encryption vocabulary | `--encrypt-*` flags on `render` only | **unified vocabulary** — `--encrypt [aes-128\|aes-256]`, `--owner-password`, `--user-password`, `--permissions print,copy,modify,extract` — shared by `render`, `merge`, `split` and `extract` (legacy `--encrypt-*` flags kept as aliases) |
| Page-tree commands | plaintext sources only | **`--password`** reads encrypted sources; **`--encrypt`** re-encrypts the output; **`--stream`** (+ `--chunk-size`) streams the output with constant memory |
| Inspection | metadata, PDF/UA, annotations | adds `inspect --form-fields`, `--encryption` and `--password` |
| Shell completion | bash, zsh, fish | adds **powershell** |
| Agent contract | `--json` / `E_*` / `--dry-run` / schemas | adds the stable **`E_PASSWORD`** code and an agent capability manifest (`schema manifest` + `llms.txt`) |
| Compatibility | `pdfnative ^1.5.0` | `pdfnative ^1.6.0` |

Full changelog: [pdfnative-cli release notes v1.3.0](https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.3.0). <!-- verify-docs:allow version-token (historical link) -->

### What's new in v1.2.0

<!-- verify-docs:allow version-token (historical release entry) -->
v1.2.0 lands the **pdfnative 1.5.0** engine's page-tree and annotation APIs on the CLI as five new commands, adds document bookmarks, a math font, layout introspection, native constant-time signing, and — for autonomous agents — surfaces pdfnative's **AI-governance / Human-in-the-Loop (HITL)** contract. **100 % backward-compatible** with v1.1.0.

| Area | v1.1.0 | v1.2.0 |
|---|---|---|
| Commands | render, sign, inspect, verify, batch, schema | adds **`merge`**, **`split`**, **`extract`** (page-tree), **`annotate`** (markup), and **`govern`** (`rules` / `policy` / `verify-issue`) |
| Bookmarks | — | **`render --outline auto`** derives a `/Outlines` bookmark tree from headings; `--outline <tree.json>` supplies an explicit `OutlineItem[]` |
| Math font | — | **`render --font math`** registers the bundled Noto Sans Math font; pdfnative auto-routes math-operator / geometric-shape code points to it |
| Layout tooling | — | **`render --inspect-layout`** emits a `LayoutInspection` JSON report; **`--debug-layout [margins,content,cells]`** overlays layout guides on a normal PDF |
| Signing | pure-JS bignum CMS | **native `node:crypto` by default** (constant-time, side-channel-resistant RSA/ECDSA); **`--pure-crypto`** opts back into the portable pure-JS path |
| Inspection | metadata, PDF/UA | **`inspect --annotations`** lists markup + link annotations; `/PageLabels` are reported automatically when present |
| Agent / governance | `--json`/`E_*`/`--dry-run` | adds the stable **`E_POLICY`** code; `schema` gains `annotate` + `govern-verify` subjects; `--dry-run` now also covers `merge` / `split` / `extract` / `annotate` |
| Compatibility | `pdfnative ^1.3.0` | `pdfnative ^1.5.0` |

Full changelog: [pdfnative-cli release notes v1.2.0](https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.2.0). <!-- verify-docs:allow version-token (historical link) -->

### Previously in v1.1.0

<!-- verify-docs:allow version-token (historical release entry) -->
v1.1.0 is built on **pdfnative 1.3.0** and surfaces its new engine capabilities through the CLI, plus a full agent-native automation contract. **100 % backward-compatible** with v0.3.0.

| Area | v0.3.0 | v1.1.0 |
|---|---|---|
| Fonts | `--font {latin,emoji}` | **22 Unicode scripts + COLRv1 colour emoji** — `--font`/`--lang` allow-list covers every bundled font (`latin`, `emoji`, `color-emoji`, and the 22 script codes incl. Telugu `te`, Sinhala `si`, Tibetan `bo`, Khmer `km`, Myanmar `my`, Amharic `am`) |
| Streaming | `--stream` (single-pass), page-by-page | adds **`--stream-true`** — true constant-memory streaming via `buildDocumentPDFStreamTrue` / `buildPDFStreamTrue`; the joined binary never materialises |
| Block cap | hard-coded ceiling | **`--max-blocks <n>`** exposes `layout.maxBlocks` (default 100 000) for very large reports |
| Accessibility | — | **PDF/UA (ISO 14289-1) structural validator** — `inspect --pdfua` and `--check pdfua` as a CI accessibility gate |
| Agent contract | — | global **`--json`** status/error envelope on stderr, stable **`E_*` error codes**, **`--dry-run`**, token-economy **`--summary`** / **`--fields`** projection, compact JSON by default |
| Commands | render, sign, inspect, verify | adds **`batch`** (parallel directory render) and **`schema`** (JSON Schema export) |
| Supply chain | provenance | adds a CycloneDX **SBOM** (`sbom.cdx.json`) attached to every release + OpenSSF Scorecard badge |
| Compatibility | `pdfnative ^1.1.0` | `pdfnative ^1.3.0` |

Full changelog: [pdfnative-cli release notes v1.1.0](https://github.com/Nizoka/pdfnative-cli/releases/tag/v1.1.0). <!-- verify-docs:allow version-token (historical link) -->

### Previously in v0.3.0

v0.3.0 finished the digital-signature story and added three iteration-friendly `render` flags. **100 % backward-compatible** with v0.2.0.

| Area | v0.2.0 | v0.3.0 |
|---|---|---|
| `sign` algorithm | RSA-SHA256 only (ECDSA stub) | RSA-SHA256 **and** ECDSA-SHA256 — fully wired via `parseEcPrivateKey` (SEC1 / PKCS#8 P-256) |
| `sign` placeholder | Required a prior `prepare_signature_placeholder` call | **Auto-injection** — CLI detects PDFs with no AcroForm signature field and adds `/Sig` via a single incremental update |
| `verify` scope | Byte-range integrity + cert chain | Real CMS/PKCS#7 verification — signature value (RSA + ECDSA), message digest, certificate chain, trust roots, RFC 3161 timestamp detection |
| `render --watch` | — | Re-render on input change (200 ms debounce, stderr-only logs) |
| `render --template <file.json>` | — | Deep-merge a base template under stdin / `--input` |
| `render --font <name>` | — | Bundled font shortcut (`latin`, `emoji`) |
| Compatibility | `pdfnative ^1.0.5` | `pdfnative ^1.1.0` |

### Previously in v0.2.0

The v0.2.0 release expanded the CLI from ~10 flags to a near-complete projection of the `pdfnative` v1.0.5 surface, while remaining 100 % backward-compatible with v0.1.0.

| Area | v0.1.0 | v0.2.0 |
|---|---|---|
| Layout | `--conformance` only | Hybrid model — high-frequency knobs as flags, full `PdfLayoutOptions` via `--layout file.json` |
| PDF/A | `--conformance 1b\|2b\|3b` | `--tagged none\|pdfa1b\|pdfa2b\|pdfa2u\|pdfa3b` (`--conformance` deprecated) |
| Encryption | — | `--encrypt-owner-pass`, `--encrypt-user-pass`, `--encrypt-algorithm`, `--encrypt-permissions` (env-var precedence) |
| Watermarks | — | `--watermark-text`/`-image`/`-opacity`/`-angle`/`-color`/`-font-size`/`-position` |
| Headers / footers | — | `--header-{l,c,r}`, `--footer-{l,c,r}` with `{page}/{pages}/{date}/{title}` placeholders |
| PDF/A-3 attachments | — | `--attachment <path>[:mime[:rel[:desc]]]` (repeatable) |
| Multilingual fonts | — | `--lang th,ja,ar` (at the time, required a wrapper registering fonts via `registerFont()`; superseded by `--font` in v1.1.0) |
| `verify` command | n/a | byte-range integrity + cert chain + `--trust` roots

---

## Migration v0.3.0 → v1.1.0

**100 % backward-compatible.** Every v0.3.0 invocation continues to produce a byte-equivalent PDF. New, optional opportunities:

```diff
# 1. True constant-memory streaming for very large reports
- pdfnative render --input big.json --output big.pdf --stream
+ pdfnative render --input big.json --output big.pdf --stream-true

# 2. CI accessibility gate (PDF/UA)
+ pdfnative inspect --input report.pdf --check pdfua

# 3. Agent-native, token-frugal output
+ pdfnative inspect --input report.pdf --json --summary

# 4. Parallel directory render
+ pdfnative batch --input-dir inputs/ --output-dir outputs/ --concurrency 4
```

## Migration v0.2.0 → v0.3.0

**100 % backward-compatible.** Three forward-looking opportunities:

```diff
# 1. ECDSA signing now works without a workaround
- pdfnative sign -i in.pdf -o out.pdf --algorithm rsa-sha256 ...
+ pdfnative sign -i in.pdf -o out.pdf --algorithm ecdsa-sha256 \
+   --key ec-key.pem --cert ec-cert.pem

# 2. Sign without a prior placeholder step
- pdfnative sign -i with-placeholder.pdf -o signed.pdf ...
+ pdfnative sign -i any-pdf.pdf -o signed.pdf ...   # placeholder auto-injected
```

## Migration v0.1.0 → v0.2.0

**100 % backward-compatible** — every v0.1.0 invocation continues to produce a byte-equivalent PDF, modulo a one-line stderr notice for `--conformance`. All v0.1.0 exit codes and JSON shapes are preserved; new `inspect` JSON fields are additive only.

The only soft change you should plan for:

```diff
- pdfnative render --input doc.json --output report.pdf --conformance 2b
+ pdfnative render --input doc.json --output report.pdf --tagged pdfa2b
```

`--conformance` will be **removed in v1.0.0** of the CLI.

---

## Troubleshooting

### `command not found: pdfnative`
You installed via `npx` (one-shot) and not globally. Either prepend `npx` to every invocation, or run `npm install --global pdfnative-cli`.

### `JSON parse error: input too large`
The CLI caps input JSON at 50 MB to prevent memory exhaustion. For very large documents, either split the document into multiple PDFs or use the library directly with the streaming API.

### `Error: invalid private key`
Both RSA PKCS#1 and ECDSA P-256 keys are accepted, but they must be **PEM-encoded**. Convert DER to PEM with `openssl pkcs8 -topk8 -in key.der -out key.pem -nocrypt`. As of v0.3.0, ECDSA support in `sign` is fully wired (SEC1 / PKCS#8 P-256 via `parseEcPrivateKey`).

### `Encryption requires an owner password. Provide --owner-password <pass> or $PDFNATIVE_ENCRYPT_OWNER_PASS.`
Any encryption flag was set without an owner password. Provide it via `--owner-password <pass>` (legacy alias: `--encrypt-owner-pass`) or — recommended — the `PDFNATIVE_ENCRYPT_OWNER_PASS` env var so it never enters shell history.

### `Error: --tagged pdfa* and --encrypt-* are mutually exclusive`
ISO 19005-1 §6.3.2 forbids encryption in PDF/A. Pick one — either an archival PDF/A document, or an encrypted distribution copy, but not both.

### `E_NETWORK: opt-in network operation failed`
A TSA / OCSP / CRL fetch (`sign --timestamp`, `ltv --online`, `doc-timestamp`, `verify --revocation online`) failed at the transport level. The SSRF guard allows http/https only, blocks private / loopback / metadata addresses, follows no redirects, and enforces a 10 s timeout and a 5 MiB response cap — check the URL is public and reachable, or raise `--timeout` where the command exposes it (`ltv`, `doc-timestamp`). A *malformed* TSA response is `E_PARSE` instead. There is never a silent fallback: either the token is embedded and verified, or the command fails.

### `E_PARSE` on a PDF that other tools open
If the message mentions an inflate cap, one of the PDF's compressed streams expands past the anti-zip-bomb ceiling (default 100 MiB). For a trusted file, raise it with the global `--max-inflate-size <bytes>` *(v1.4.0)*.

### `ENOENT: no such file or directory, 'D\'`  (Windows)
This was a v0.1.0 / pre-v0.2.0 regression: `--attachment D:\file.xml` was split at the drive-letter colon. Fixed in v0.2.0 — make sure you're on `pdfnative-cli@^0.2.0`.

### Layout file is ignored when I also pass CLI flags
That is the **intended precedence**: `CLI flags > --layout file > pdfnative defaults`. To merge nested objects (e.g. a watermark in the layout file plus a `--watermark-text` on the CLI), the CLI now correctly merges `params.layout` with CLI-derived flags as of v0.2.0 (previously the JSON-embedded layout could be silently dropped — fixed).

### `--lang th` does not produce Thai glyphs
`--lang` only *activates* fonts that are registered in the CLI process — pass `--font th` as well so the bundled Noto Thai module is registered (`--font` covers all 22 bundled scripts, `latin`, `emoji`, `color-emoji`, `math`). A wrapper script that registers fonts and then spawns the CLI does **not** work: in-memory registration does not cross a process boundary. For a non-bundled font you ship yourself, call the library directly — see *Recipes → Multilang fonts*.

### Signed PDF fails Adobe verification
Ensure your certificate's signing-key usage extension includes `digitalSignature` (key usage 0). Self-signed certificates work for testing but require the validator to trust the issuer — pass `--trust ca-root.pem` to `verify` for self-signed setups.

---

## Resources

- 📦 **npm:** [pdfnative-cli](https://www.npmjs.com/package/pdfnative-cli)
- 🏛️ **Repo:** [Nizoka/pdfnative-cli](https://github.com/Nizoka/pdfnative-cli)
- 📚 **Knowledge base:** [pdfnative-cli/docs/KNOWLEDGE_BASE.md](https://github.com/Nizoka/pdfnative-cli/blob/main/docs/KNOWLEDGE_BASE.md) — full architecture, integration patterns, FAQ
- 📁 **Samples:** [pdfnative-cli/samples](https://github.com/Nizoka/pdfnative-cli/tree/main/samples)
- 🧪 **Try it interactively:** [CLI playground](../playgrounds/cli.html) — build commands without leaving the browser
- 🔧 **Underlying library:** [`pdfnative`](https://github.com/Nizoka/pdfnative)
- 🤖 **AI integration:** [pdfnative-mcp guide](mcp.html) — same library exposed as a Model Context Protocol server
- 🐛 **Report a bug:** [Nizoka/pdfnative-cli/issues](https://github.com/Nizoka/pdfnative-cli/issues)
- 💬 **Discuss:** [Nizoka/pdfnative-cli/discussions](https://github.com/Nizoka/pdfnative-cli/discussions)

---

## Citation

If you use the CLI in research or academic pipelines, cite both repositories:

```bibtex
@software{pdfnative_cli_2026,
  title  = {pdfnative-cli: Official CLI for the pdfnative PDF generation library},
  author = {Nizoka},
  year   = {2026},
  url    = {https://github.com/Nizoka/pdfnative-cli},
  license = {MIT}
}
```

---
<!-- source: docs/guides/colour-emoji-cli.md -->
# Colour-emoji font CLI (`pdfnative-build-emoji-font`)

> **New in v1.4.0, expanded in v1.6.0 and v1.7.0.** pdfnative ships a curated
> 1167-glyph colour-emoji module by default (plus 73 flag/ZWJ sequences since
> v1.7.0). When you need **more emoji — up to the full ~3 600-glyph set, or
> skin-tone sequence variants** — the
> `pdfnative-build-emoji-font` CLI generates a data module containing exactly the
> glyphs and sequences you choose. It's bundled with the `pdfnative` package, so
> any user can run it with `npx` — no extra install, no editing library source.

## Why a CLI instead of bundling everything?

The complete Noto Color Emoji font is ~24 MB and resolves to a ~32 MB data
module. Bundling that into the npm package would penalise **every** install,
including the vast majority of users who only ever need a handful of emoji. The
lean curated subset stays the default; the CLI lets you opt into precisely the
coverage you need, when you need it. This is the same deterministic build core
that produces the bundled module — you get identical, reproducible output.

## TL;DR

```bash
# Full coverage — download + checksum-verify the font, then build every glyph:
npx pdfnative-build-emoji-font --download --all --out ./emoji-full.js

# Exactly the emoji you need (hex scalars and/or inclusive ranges):
npx pdfnative-build-emoji-font --download \
  --ranges 1F600-1F64F,2600-27BF --codepoints 2764,1F680 --out ./emoji.js

# Offline: point at a font you already have on disk:
npx pdfnative-build-emoji-font --ttf ./NotoColorEmoji-Regular.ttf --all

# Flag/ZWJ sequences (v1.7.0) — the curated sets plus any skin-tone form you need:
npx pdfnative-build-emoji-font --download --sequences all \
  --sequence-list 1F468-1F3FB-200D-1F4BB,1F469-1F3FD-200D-2695-FE0F --out ./emoji.js
```

Then register the module you generated, load it, and pass it via `fontEntries`:

```ts
import { registerFont, loadFontData, buildDocumentPDFBytes } from 'pdfnative';

registerFont('emoji', () => import('./emoji-full.js'));
const emoji = await loadFontData('emoji');
if (!emoji) throw new Error('emoji font failed to load');

const bytes = buildDocumentPDFBytes({
  title: 'Emoji',
  blocks: [{ type: 'paragraph', text: 'Ship it 🚀🎉🥳🦄🌈' }],
  fontEntries: [{ fontData: emoji, fontRef: '/F3', lang: 'emoji' }], // /F1 and /F2 are reserved
});
```

## Getting the source font

The CLI needs a COLRv1/CPAL colour font — the canonical one is
**NotoColorEmoji-Regular.ttf** (OFL-1.1). Two ways to provide it:

- **`--download`** fetches it from the official Google Fonts repository and
  verifies its SHA-256 against the build pdfnative was tested with. A mismatch is
  a transparent **warning** (Google periodically ships newer Unicode revisions),
  not a hard failure — the download is still used.
- **`--ttf <path>`** uses a font already on disk (fully offline, no network).

> Only the pinned official Google Fonts URL is ever contacted; the CLI never
> fetches arbitrary user-supplied URLs.

## Selecting glyphs

Combine these freely; selections are merged, de-duplicated and sorted. If you
pass none, the curated set is used.

| Flag | Meaning |
|---|---|
| `--all` | Every colour glyph in the font (large module). |
| `--preset curated` | pdfnative's lean 1167-glyph default set. |
| `--preset all` | Same as `--all`. |
| `--codepoints <list>` | Comma-separated hex scalars: `1F600,1F680,2764`. `U+`, `0x`, `#` prefixes are tolerated. |
| `--ranges <list>` | Comma-separated **inclusive** hex ranges: `1F600-1F64F,2600-27BF`. |

## Selecting sequences (v1.7.0)

Multi-codepoint emoji — flags (regional-indicator pairs) and ZWJ sequences —
are selected separately from single glyphs. Each requested sequence is
resolved through the font's GSUB ligature lookups to a **single colour glyph**
and emitted in the module's `sequences` table; both the VS-16 and the
VS-16-free spelling register to the same glyph. Default: **none** (the
pre-1.7 output shape, plus an inert `sequences = null` export).

| Flag | Meaning |
|---|---|
| `--sequences <preset>` | `flags` (the curated 51-flag set), `zwj` (the curated 22-sequence ZWJ set), `all` (both), or `none`. |
| `--sequence-list <list>` | Comma-separated entries: a 2-letter country code (`FR`, `DE`) and/or hyphen-joined hex scalars (`1F468-200D-1F680`, `1F469-1F3FD-200D-2695-FE0F`). Skin-tone forms welcome. |

Selections merge and de-duplicate, so `--sequences flags --sequence-list
1F469-1F3FB-200D-2695-FE0F` is valid. The bundled npm module already carries
the curated 51 + 22 set — reach for the CLI when you need skin-tone variants
or sequences beyond it. Note that flags render **flat** (Noto's wave-shading
overlay uses a COLRv1 compositing mask with no PDF equivalent — see the
[colour-emoji guide](colour-emoji.html)).

## Output options

| Flag | Default | Meaning |
|---|---|---|
| `--out <path>` | `./noto-color-emoji-data.js` | Output `.js` path. A sibling `.d.ts` is written next to it. |
| `--font-name <name>` | `NotoColorEmoji-Regular` | Embedded PostScript font name. |
| `--types <path>` | `pdfnative` | The type import used in the generated `.d.ts` (e.g. `'pdfnative'` or a relative path). |

The generated module exports the same shape as the bundled one
(`metrics`, `cmap`, `widths`, `pdfWidthArray`, `colorGlyphs`, `sequences`,
`ttfBase64`, …), so it drops straight into
`registerFont('emoji', () => import('…'))`.

## Verifying the result

Pair the CLI with [`validateFontData()`](font-validation.html) to sanity-check a
freshly generated module before shipping it:

```ts
import { validateFontData } from 'pdfnative';
import * as emoji from './emoji-full.js';

const report = validateFontData(emoji);
if (!report.valid) console.error(report.errors);
```

## Full option reference

```text
pdfnative-build-emoji-font — colour-emoji font data module generator

Source font (one of):
  --ttf <path>            Path to a COLRv1/CPAL colour font.
  --download              Fetch the official Noto Color Emoji (OFL-1.1) and verify checksum.

Glyph selection (combine freely; default: --preset curated):
  --all                   Every colour glyph in the font.
  --preset <curated|all>  Named selection.
  --codepoints <list>     Comma-separated hex scalars, e.g. 1F600,1F680,2764.
  --ranges <list>         Comma-separated inclusive hex ranges, e.g. 1F600-1F64F.

Sequence selection (v1.7.0; default: none):
  --sequences <preset>    flags | zwj | all | none — bundle the curated flag
                          and/or ZWJ sequence sets (GSUB-resolved ligatures).
  --sequence-list <list>  Comma-separated country codes and/or hyphen-joined
                          hex sequences, e.g. FR,DE,1F468-200D-1F680,
                          1F469-1F3FD-200D-2695-FE0F (skin tones welcome).

Output:
  --out <path>            Output .js path (a sibling .d.ts is written).
  --font-name <name>      Embedded PostScript font name.
  --types <path>          Type import used in the generated .d.ts.

Other:
  -h, --help              Show this help.
```

## Licensing

Noto Color Emoji is licensed under the **SIL Open Font License 1.1 (OFL-1.1)**.
Generated modules embed a subset of that font; keep the OFL notice with any
redistributed module, exactly as you would for any other Noto data module that
pdfnative ships.

## See also

- [Colour emoji (COLRv1)](colour-emoji.html) — how colour glyphs render to PDF
- [Font-data validation](font-validation.html) — `validateFontData()`
- [PDF Toolkit playground](../playgrounds/toolkit.html)
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/colour-emoji.md -->
# Colour emoji (COLRv1)

> **New in v1.3.0.** pdfnative renders colour emoji natively — no rasterisation, no external dependency. Glyph colour layers become PDF Form XObjects with solid fills and axial/radial gradients. The monochrome emoji font is unchanged and remains the default.

## TL;DR

```ts
import { registerFont, loadFontData, buildDocumentPDFBytes } from 'pdfnative';

// Opt in to the curated colour-emoji subset (1167 glyphs + 73 sequences, ~4.5 MB).
registerFont('emoji', () => import('pdfnative/fonts/noto-color-emoji-data.js'));

const emoji = await loadFontData('emoji');
if (!emoji) throw new Error('emoji font failed to load');

const bytes = buildDocumentPDFBytes({
  title: 'Colour emoji',
  blocks: [
    { type: 'paragraph', text: 'Status: 🟢 online · 🔴 offline · 🎉 launch day!' },
  ],
  fontEntries: [{ fontData: emoji, fontRef: '/F3', lang: 'emoji' }], // /F1 and /F2 are reserved
});
```

The `registerFont('emoji', …)` call swaps the monochrome Noto Emoji font for
the COLR/CPAL colour build — but registration alone embeds nothing: you must
`await loadFontData('emoji')` and pass the result in `fontEntries` (as above)
or the emoji render as tofu. With the entry in place, everything else —
detection, multi-font run splitting, line breaking — is automatic.

## How it works

Noto Color Emoji is an OpenType **COLR/CPAL** font: each emoji codepoint maps
to a base glyph plus a *colour glyph* describing ordered paint layers. pdfnative
parses these tables with self-written, zero-dependency readers
([`src/fonts/colr-parser.ts`](https://github.com/Nizoka/pdfnative/blob/main/src/fonts/colr-parser.ts),
[`src/fonts/glyf-outline.ts`](https://github.com/Nizoka/pdfnative/blob/main/src/fonts/glyf-outline.ts))
and renders each colour glyph as a **PDF Form XObject**:

| COLR feature | PDF mapping |
|---|---|
| Solid layer (COLR v0 / `PaintSolid`) | `rg` fill of the layer's `glyf` outline, clipped with `W n` |
| Linear gradient (`PaintLinearGradient`) | `/ShadingType 2` axial shading + `/ExtGState` constant alpha |
| Radial gradient (`PaintRadialGradient`) | `/ShadingType 3` radial shading |
| Sweep gradient (`PaintSweepGradient`) | flat-colour triangular wedges fanned around the centre (**v1.4.0**) |
| Compositing (`PaintComposite`) | separable blend modes mapped to PDF `/BM` (Multiply, Screen, Overlay, Darken, Lighten, …) (**v1.4.0**) |
| CPAL palette | per-stop RGB(A) colours |

Each unique emoji produces **one indirect Form XObject**, deduplicated and
forward-referenced into every page's `/XObject` resource dictionary. The text
run emits `q s 0 0 s x y cm /CEm0 Do Q` to place the glyph.

> **Advanced compositing (v1.4.0).** COLRv1 **sweep (conic) gradients** render as
> native flat-shaded wedges, and `PaintComposite` **separable blend modes** map to
> PDF `/BM` ExtGState operators. Structural Porter-Duff modes (Clear / Src / Dest /
> Xor / …) and `PaintMask` fall back to the documented monochrome path — except
> that since **v1.7.0**, a composite whose *source* subtree alone is unsupported
> keeps its backdrop layers (this is what makes flags render flat instead of
> monochrome).

## Opt-in, not default

Colour emoji is **opt-in** for two reasons:

1. **Module size.** The curated subset is ~4.5 MB (expanded to 1167 glyphs in
   v1.6.0, plus 73 flag/ZWJ sequences in v1.7.0); bundling it by default would
   bloat every consumer. Register it only when you need colour.
2. **Byte stability.** When no colour-emoji font is registered, documents are
  byte-identical to the pre-colour-emoji path — the colour path is fully gated.

To keep monochrome emoji instead, register the monochrome font:

```ts
registerFont('emoji', () => import('pdfnative/fonts/noto-emoji-data.js'));
```

## Coverage & limits

The bundled module is a **curated subset** of **1167 common single-codepoint
emoji** (expanded from 221 in v1.6.0): the complete Emoticons and Supplemental
Symbols & Pictographs blocks, Miscellaneous Symbols & Pictographs through
U+1F53D (nature, food, objects, hearts, office, av/ui symbols) plus clocks and
the emoji-presentation stragglers, and the **complete assigned Transport & Map
block** (U+1F680–1F6FF). Since v1.7.0 it also carries **73 multi-codepoint
sequences** — 51 flags and 22 ZWJ sequences (see the next section). Symbols &
Pictographs Extended-A (U+1FA70–1FAFF) is
not bundled — use the CLI below. It ships pre-built because every file under the package
`files` allowlist is included in the npm tarball regardless of tree-shaking — the
full Noto Color Emoji build (thousands of glyphs, ~32 MB) would weigh down
*every* `npm install`, even for consumers who never touch emoji. The subset keeps
the install within a 5120 KB budget (actual: ~4.5 MB) while the lazy
`() => import(...)` keeps it out of bundles that don't reference it.

> **Out of scope for the bundled subset:** skin-tone-modified forms
> (`👍🏽`, `👩🏻‍🚀`, …) and any flag or ZWJ sequence beyond the curated 73. The
> combinatorial skin-tone set is deliberately CLI territory — build a module
> with `--sequences` / `--sequence-list` below to cover exactly the forms you
> need. An uncovered sequence degrades to the per-codepoint behaviour
> described further down (base emoji render, joiners drop) — never worse.

To cover the **full** Noto Color Emoji set — or any custom selection — pdfnative
ships an official generator CLI, `pdfnative-build-emoji-font`, so you never have
to edit library source:

```bash
# Every colour glyph (~3 600), fetched + checksum-verified from Google Fonts:
npx pdfnative-build-emoji-font --download --all --out ./emoji-full.js

# Or exactly the emoji you need (hex scalars and/or inclusive ranges):
npx pdfnative-build-emoji-font --download \
  --ranges 1F600-1F64F,2600-27BF --codepoints 2764,1F680 --out ./emoji.js
```

Then register the module you generated:

```ts
registerFont('emoji', () => import('./emoji-full.js'));
```

See the [colour-emoji CLI guide](colour-emoji-cli.html) for every flag, offline
usage with `--ttf`, and the checksum/licensing details.

## Flag & ZWJ sequences (v1.7.0)

Multi-codepoint emoji now render as **single colour glyphs**. The bundled
module resolves the font's GSUB ligature lookups at build time into a
`sequences` table (first codepoint → resolved ligature glyph), and the text
pipeline runs a longest-match pre-pass over it, so a flag pair or a ZWJ
sequence produces exactly one COLR Form XObject:

- **51 flags** — 🇪🇺 EU, 🇺🇳 UN, the G20 members, and other widely used
  locales (regional-indicator pairs).
- **22 ZWJ sequences** — families (`👨‍👩‍👧`), professions (`👩‍🚀`, `👨‍💻`),
  `❤️‍🔥`, `🏳️‍🌈`, `🏳️‍⚧️`, `🏴‍☠️`, `🐻‍❄️`, `😮‍💨`, and friends —
  in their skin-tone-free RGI forms.

No API change is required: register the bundled colour-emoji module as usual
and write the sequences in your text. Three behaviours worth knowing:

- **VS-16 tolerance.** Both the VS-16 spelling and the VS-16-free spelling of
  a sequence match the same glyph — real-world text is inconsistent about
  presentation selectors, so `❤️‍🔥` works with or without the invisible
  U+FE0F.
- **Fallback is never worse.** A sequence absent from the table degrades to
  exactly the historical per-codepoint behaviour: unmatched joiners,
  variation selectors, and skin-tone modifiers are dropped, and unmatched
  regional indicators pass through the normal cmap lookup. A module without a
  `sequences` table renders byte-identically to v1.6.0.
- **Flags render flat.** Noto's flag glyphs stack a wave-shading overlay on
  the flat artwork via a COLRv1 `PaintComposite` SRC_IN mask that has no PDF
  equivalent. pdfnative degrades the composite to its supported backdrop, so
  every flag renders as its flat (unwaved) artwork rather than falling back
  to monochrome.

Skin-tone-modified sequences stay CLI-only — generate a module with
`--sequences` / `--sequence-list` (see the [CLI guide](colour-emoji-cli.html)).

## Advanced compositing (v1.4.0)

COLRv1 includes two paint types beyond solid + axial/radial gradients, and
pdfnative now maps both where a faithful PDF translation exists:

| COLRv1 feature | PDF mapping (v1.4.0) |
|---|---|
| Sweep / conic gradient (`PaintSweepGradient`, format 8) | Flat-shaded triangular **wedges** fanned around the centre — no `/Shading` resource, pure path fills. Matrix rotation is folded into the start/end angles via `Math.atan2`. |
| Composite (`PaintComposite`, format 32) — *separable* blend modes | Backdrop + source layers, with the source tagged via a `/BM` (blend mode) `/ExtGState`: Normal, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion, Hue, Saturation, Color, Luminosity. |
| Composite — *structural* Porter-Duff modes (`SrcOver`, `DestIn`, clipping masks, …) | No exact PDF equivalent → the glyph falls back to the **monochrome** outline. Since v1.7.0, when only the composite's *source* subtree is unsupported, its partial layers roll back and the **backdrop renders alone** (best-effort) — Noto's flags degrade to their flat artwork this way. |

Sweep wedges approximate the smooth conic sweep with a fan of flat-colour
triangles whose count scales with the angular span — close enough for emoji at
text sizes while staying within plain PDF path operators. Separable blend modes
are exactly the set PDF defines in ISO 32000-1 §11.3.5, so they round-trip
faithfully in any conformant viewer.

> **PDF/A note:** blend modes and constant-alpha `/ExtGState` are transparency
> features that PDF/A-1b forbids. Use solid-layer emoji for archival documents.

## Limitations

- **`PaintMask`** and COLRv1 variable (animated) paints are not yet rendered;
  glyphs using them fall back gracefully — to the backdrop layers when the
  unsupported paint sits inside a composite's source subtree (v1.7.0), to the
  monochrome outline otherwise. Tracked for a future release.
- **PDF/A:** gradient transparency uses `/ExtGState` alpha, which PDF/A-1b
  forbids. Use solid-layer emoji or a non-PDF/A document for colour gradients.

## Variation selectors & skin-tone modifiers (v1.3.0)

Text such as `❤️` carries an invisible **VS-16** variation selector
(U+FE0F), and `👍🏽` carries a **Fitzpatrick** skin-tone modifier
(U+1F3FB–U+1F3FF); ZWJ sequences (`👨‍👩‍👧`) join several codepoints. Before
v1.3.0 these zero-width formatting characters could route to the Latin font and
render as `.notdef` tofu (the  box). As of v1.3.0 they are **dropped during
run-splitting** when no registered font covers them, so the base emoji renders
cleanly. (Internally this is the `isZeroWidthFormat(cp)` predicate in the
shaping engine — it is not part of the published API surface.) Joiners are
still preserved when an Indic shaper font maps them.

Since **v1.7.0**, sequences covered by the registered font's `sequences` table
take a different path entirely: the whole sequence — joiners, selectors and
all — resolves to a single colour ligature glyph before run-splitting (see
[Flag & ZWJ sequences](#flag--zwj-sequences-v170) above). The drop-during-run-splitting
behaviour described here remains the fallback for uncovered sequences.

Colour-glyph Form `/BBox` is also now computed from the glyph's transformed
contour bounds (v1.3.0), so emoji that dip below the baseline are no longer
clipped at the top or bottom.

## See also

- [Quick start](quickstart.html)
- [Troubleshooting](troubleshooting.html) — missing glyphs / tofu
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/debugging.md -->
# Layout debugging & inspection

> **New in v1.5.0.** Two complementary tools help you understand *where*
> pdfnative places every block on the page: an **opt-in visual overlay**
> (`layout: { debug: true }`) that draws margin / content / cell boxes straight
> onto the PDF, and a **programmatic inspection** API
> (`inspectDocumentLayout()`) that returns the per-page block geometry as plain
> data. Both are byte-neutral: when debug is off, output is **byte-identical**
> to previous releases.

## TL;DR

```ts
import { buildDocumentPDFBytes, inspectDocumentLayout } from 'pdfnative';

const params = {
  title: 'Invoice',
  blocks: [
    { type: 'heading', level: 1, text: 'Invoice #42' },
    { type: 'paragraph', text: 'Thanks for your business.' },
  ],
};

// 1. Visual overlay — margin / content / cell boxes drawn on the PDF
const pdf = buildDocumentPDFBytes(params, { debug: true });

// 2. Programmatic geometry — no rendering, just data
const layout = inspectDocumentLayout(params);
for (const page of layout.pages) {
  for (const block of page.blocks) {
    console.log(page.index, block.type, block.x, block.top, block.width, block.height);
  }
}
```

## Visual overlay

Pass `debug: true` (or a granular object) in the layout options:

```ts
buildDocumentPDFBytes(params, { debug: true });

// or select exactly what you want to see:
buildDocumentPDFBytes(params, {
  debug: { showMargins: true, showContentBounds: true, showCells: false },
});
```

| Option | Colour | Draws |
|---|---|---|
| `showMargins` | blue | the page margin box (content area boundary) |
| `showContentBounds` | red | a rectangle around every rendered block |
| `showCells` | green | per-cell rectangles for tables |

`debug: true` is shorthand for enabling all three. The overlay is drawn **last**,
on top of the content, each shape wrapped in its own graphics state (`q … Q`) so
it never leaks colour or line-width into your document. Turn it off (or omit it)
and the bytes are exactly what you'd get without the option.

## Programmatic inspection

`inspectDocumentLayout(params, layout?)` runs the **same pagination engine** as
the builder but produces data instead of PDF bytes — no rendering, no font
embedding:

```ts
import { inspectDocumentLayout } from 'pdfnative';
import type { LayoutInspection } from 'pdfnative';

const report: LayoutInspection = inspectDocumentLayout(params);

report.pages.forEach((page) => {
  console.log(`Page ${page.index + 1}: ${page.blocks.length} blocks`);
  page.blocks.forEach((b) => {
    console.log(`  ${b.type} @ (${b.x}, ${b.top}) ${b.width}×${b.height}`);
  });
});
```

### Shape

| Type | Fields |
|---|---|
| `LayoutInspection` | `{ pageWidth, pageHeight, margins, totalPages, pages: InspectedPage[] }` |
| `InspectedPage` | `{ index, blocks: InspectedBlock[] }` |
| `InspectedBlock` | `{ type, page, x, top, width, height }` (PDF user-space points, origin bottom-left; `top` is the block's upper edge, `height` extends downward) |

Because it shares the builder's `estimateBlockHeight` / `planTable` logic and
constants, the reported geometry matches where the real renderer places each
block — including table slicing across page breaks.

## When to use which

- **Overlay** — eyeball a single document: "why is this paragraph clipped?",
  "is my table overflowing the margin?" Open the PDF and *see* the boxes.
- **Inspection** — automate it: assert block positions in a test, drive a
  layout linter, or feed geometry to another tool.

## Sample

[layout-debug-overlay.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/layout-debug-overlay.ts)
renders the same document twice — once clean, once with the overlay — and prints
the `inspectDocumentLayout()` report.

---
<!-- source: docs/guides/faq.md -->
# FAQ

> **Frequently asked questions about pdfnative** — getting started, custom
> fonts, PDF/A variants, encryption, BiDi text, browser / Deno / Bun support,
> signatures, workers, and how it compares with other libraries. Can't find
> your answer? Open a [discussion](https://github.com/Nizoka/pdfnative/discussions) or read the [Troubleshooting guide](troubleshooting.html).

## Getting started

### How do I generate my first PDF?

```typescript
import { buildDocumentPDFBytes, downloadBlob } from 'pdfnative';

const pdf = buildDocumentPDFBytes({
  title: 'Hello',
  blocks: [
    { type: 'heading',   text: 'Hello world', level: 1 },
    { type: 'paragraph', text: 'My first PDF.' },
  ],
});

downloadBlob(pdf, 'hello.pdf');     // browser
// or, in Node.js:
// fs.writeFileSync('hello.pdf', pdf);
```

See the [Quick Start guide](quickstart.html) for Node.js, browser, and Web Worker walkthroughs.

### Which builder should I pick: `buildPDFBytes` or `buildDocumentPDFBytes`?

| Builder | Best for | Key shape |
|---------|----------|-----------|
| `buildPDFBytes` | Tabular reports, bank statements, invoices with a single table | `{ title, headers, rows, infoItems, balanceText, ... }` |
| `buildDocumentPDFBytes` | Mixed-content documents (manuals, articles, multi-section reports) | `{ title, blocks: [...] }` with 13 block types |

Both return `Uint8Array` and accept the same layout / encryption / compression / tagged-PDF options.

### Does it work in the browser?

Yes — pdfnative is a dual ESM/CJS build with zero Node.js-specific APIs in the core:

```typescript
import { buildDocumentPDFBytes, downloadBlob } from 'pdfnative';

const pdf = buildDocumentPDFBytes({ title: 'Hello', blocks: [/* … */] });
downloadBlob(pdf, 'output.pdf');
```

For optimal compression in Node.js, call `initNodeCompression()` once at startup. In the browser, a stored-block fallback is used automatically.

### Does it work with Deno / Bun?

Yes. The library is standard ESM with no Node.js-specific imports in the core. Both Deno and Bun import it directly.

---

## Fonts and Unicode

### Can I use custom fonts?

Yes. Build a font data module from any TTF file:

```bash
npx pdfnative-build-font path/to/MyFont.ttf my-font-data.js
```

Then register it:

```typescript
import { registerFonts, loadFontData, buildDocumentPDFBytes } from 'pdfnative';

registerFonts({
  custom: () => import('./my-font-data.js'),
});

const myFont = await loadFontData('custom');
const pdf = buildDocumentPDFBytes({
  blocks: [{ type: 'paragraph', text: '…' }],
  fontEntries: [{ fontData: myFont!, fontRef: '/F3', lang: 'custom' }],
});
```

Font subsetting is automatic — only the glyphs you actually used are embedded.

### How do I render Arabic / Hebrew / Thai / Devanagari?

Register the matching pre-built font module and pass it as a `fontEntry`:

```typescript
registerFonts({
  ar: () => import('pdfnative/fonts/noto-arabic-data.js'),
  he: () => import('pdfnative/fonts/noto-hebrew-data.js'),
  th: () => import('pdfnative/fonts/noto-thai-data.js'),
  hi: () => import('pdfnative/fonts/noto-devanagari-data.js'),
});

const langs = ['ar', 'he', 'th', 'hi'];
const fontEntries = (await Promise.all(langs.map(loadFontData)))
  .map((fd, i) => (fd ? { fontData: fd, fontRef: `/F${3 + i}`, lang: langs[i] } : null))
  .filter((e): e is NonNullable<typeof e> => e !== null); // .filter(Boolean) alone does not narrow the type

const pdf = buildDocumentPDFBytes({
  blocks: [
    { type: 'paragraph', text: 'مرحبا — שלום — สวัสดี — नमस्ते' },
  ],
  fontEntries,
});
```

The `lang` property triggers BiDi resolution for RTL scripts and OpenType GSUB/GPOS shaping for Arabic, Devanagari, Bengali, Tamil, Telugu, Sinhala, Tibetan, Khmer, Myanmar, and Thai.

### Why does my Arabic text appear backwards?

The most common cause: missing `lang: 'ar'` on the font entry. Without it, BiDi resolution and Arabic positional shaping are skipped. See [Troubleshooting → RTL Text Backwards](troubleshooting.html).

### Which scripts are supported out of the box?

26 Noto font-data modules ship with the package: the 22 scripts — Amharic/Ethiopic, Arabic, Armenian, Bengali, Cyrillic, Devanagari, Georgian, Greek, Hebrew, Japanese, Khmer, Korean, Myanmar, Polish, Simplified Chinese, Sinhala, Tamil, Telugu, Thai, Tibetan, Turkish, Vietnamese — plus Latin (Noto Sans), math (Noto Sans Math), and monochrome + COLRv1 colour emoji.

---

## Standards and compliance

### What PDF versions can pdfnative produce?

| Mode | PDF version | Standard |
|------|-------------|----------|
| Default | 1.4 | ISO 32000-1 |
| `tagged: true` | 1.7 | PDF/A-2b (default tagged mode, ISO 19005-2) |
| `tagged: 'pdfa1b'` | 1.4 | PDF/A-1b (ISO 19005-1) |
| `tagged: 'pdfa2u'` | 1.7 | PDF/A-2u (ISO 19005-2 with unicode) |
| `tagged: 'pdfa3b'` | 1.7 | PDF/A-3b (ISO 19005-3, supports embedded files) |

### Which PDF/A variant should I pick?

- **PDF/A-1b** — strictest, oldest. Pick only if your validator requires PDF 1.4 and you don't need transparency, JPEG2000, or layers.
- **PDF/A-2b** *(recommended default)* — PDF 1.7, supports transparency, layers, OpenType. Most modern archive systems target 2b.
- **PDF/A-2u** — same as 2b plus mandatory Unicode mapping for all text. Pick if downstream consumers need text extraction.
- **PDF/A-3b** — PDF/A-2b + ability to embed arbitrary attachments (e.g. source XML for invoicing standards like ZUGFeRD/Factur-X). Note: not all archive policies allow A-3.

### Can I combine PDF/A and encryption?

No. ISO 19005-1 §6.3.2 forbids encryption inside PDF/A documents. pdfnative validates this at the `buildPDF()` boundary and throws an error if both are requested. Pick one or the other.

### Is the output tagged for accessibility (PDF/UA)?

Yes — when you set `tagged: true` (or any PDF/A mode), pdfnative emits a structure tree with `/Document → /Table → /TR → /TH|TD`, `/H1`–`/H3`, `/P`, `/L`/`/LI`, `/Figure`, `/Link`, `/Form`, `/TOC`/`/TOCI`, and uses `/ActualText` for shaped Unicode. See the [Accessibility guide](accessibility.html).

---

## Security

### How do I encrypt a PDF?

```typescript
const pdf = buildPDFBytes(params, {
  encryption: {
    algorithm: 'aes256',           // or 'aes128'
    userPassword: 'reader',
    ownerPassword: 'editor',
    permissions: {
      print: true,        // default: true
      copy: false,        // default: false
      modify: false,      // default: false
      extractText: true,  // accessibility text extraction — default: true
    },
  },
});
```

`aes256` (V5/R6) is recommended for new documents. Use `aes128` (V4/R4) only when you need compatibility with very old viewers.

### How do I sign a PDF digitally?

```typescript
import { addSignaturePlaceholder, signPdfBytes, parseCertificate, parseRsaPrivateKey } from 'pdfnative';

// 1. The PDF must contain a /Sig placeholder — add one if it doesn't
//    (skipping this throws "No /Contents placeholder found"):
const prepared = addSignaturePlaceholder(pdfBytes);

// 2. Sign it
const signed = signPdfBytes(prepared, {
  signerCert: parseCertificate(certDer),   // DER-encoded X.509 certificate
  rsaKey: parseRsaPrivateKey(keyDer),      // DER-encoded RSA key (or `ecKey` for ECDSA P-256)
  algorithm: 'rsa-sha256',                 // or 'ecdsa-sha256'
  reason: 'Approved',
  name: 'Jane Doe',
});
```

pdfnative implements ISO 32000-1 §12.8 — CMS/PKCS#7 SignedData with RSA (PKCS#1 v1.5) or ECDSA (P-256); RSA also offers SHA-384/512 since v1.7.0. The crypto stack is implemented in pure TypeScript inside `src/crypto/` — no native modules, no `node:crypto` (an optional constant-time native provider can be plugged in via `setCryptoProvider`).

### How do I make a signature "LTV enabled" (valid for years)?

Since v1.7.0 pdfnative covers the full PAdES baseline (ETSI EN 319 142-1):
sign with `profile: 'pades'`, add an RFC 3161 timestamp with
`signPdfBytesWithTimestamp`, embed revocation material with
`addValidationInfo` (`/DSS` + `/VRI`), and cap with `addDocumentTimestamp`.
The engine never opens sockets — you inject the TSA/OCSP/CRL transport via
`setTimestampProvider` / `setRevocationProvider`. Full pipeline in the
[LTV guide](ltv.html).

### Can a PDF carry several signatures?

Yes (v1.7.0): create each placeholder with `allowMultiple: true` and target
it by `fieldName` when signing. Each signature is appended as a
non-destructive incremental revision, so earlier signatures remain valid;
inspect any file with `listSignatures(bytes)`. See
[signatures — multiple signatures](signatures.html).

### Is the build supply-chain safe?

- **Zero runtime dependencies** — `npm install pdfnative` brings in nothing transitive at runtime.
- **NPM provenance** — every release is signed via GitHub Actions OIDC (SLSA L3-equivalent).
- **OpenSSF Scorecard** scanned weekly; CodeQL on every push.
- **Pinned dev dependencies** managed via Dependabot.

---

## Modifying existing PDFs

### Can I read or modify existing PDFs?

Yes. pdfnative includes a tokenizer, object parser, xref/stream parser, and a non-destructive incremental modifier:

```typescript
import { openPdf, createModifier } from 'pdfnative';

const reader = openPdf(new Uint8Array(fs.readFileSync('input.pdf')));

console.log(`Pages: ${reader.pageCount}`);
console.log(`Title: ${reader.getInfo()?.get('Title')}`);

const mod = createModifier(reader);
mod.setMetadata('Title', 'Updated Title');
const updated = mod.save();   // appends a new xref/trailer with /Prev chain
```

### What's the maximum document size?

`buildPDFBytes` enforces a 100 000 row limit on tables. `buildDocumentPDFBytes` paginates automatically, with a default cap of **100 000 blocks** (`DEFAULT_MAX_BLOCKS`) that you can raise via `layout.maxBlocks`; past that, the practical ceiling is your available memory. For very large documents, see the streaming question below.

### How do I avoid loading the whole PDF into memory?

Use the streaming API — it returns an `AsyncGenerator<Uint8Array>` that yields chunks as they're produced:

```typescript
import { buildDocumentPDFStream } from 'pdfnative';

for await (const chunk of buildDocumentPDFStream(params, {}, { chunkSize: 65536 })) {
  await writeStream.write(chunk);
}
```

---

## Performance

### How can I make the PDF smaller?

1. **Enable compression**: `compress: true` (FlateDecode, 50–90 % size reduction).
2. **Initialize native zlib in Node.js**: `await initNodeCompression()` once at startup.
3. **Use JPEG for photos** — JPEG (DCTDecode) is already compressed; PNG is FlateDecode-compressed.
4. **Font subsetting is automatic** — but each script you embed adds one subset.

### Can I generate PDFs in a Web Worker?

Yes. For large datasets pdfnative ships a built-in worker pipeline — use `createPDF`, which routes to a worker or the main thread for you:

```typescript
import { createPDF } from 'pdfnative';

const pdf = await createPDF(params, {
  workerUrl: new URL('./pdf-worker.js', import.meta.url),
  threshold: 500, // default WORKER_THRESHOLD = 500 rows
});
```

Tables above the threshold run off the main thread (with an automatic main-thread fallback); smaller ones render synchronously. The lower-level `generatePDFInWorker(workerUrl, params, { timeout, onProgress })` drives a worker directly — the worker URL is its first argument, and it has no threshold logic.

---

## Why pdfnative?

### How does it compare to jsPDF / pdfkit / pdf-lib / pdfmake?

See the [feature comparison table](https://github.com/Nizoka/pdfnative#why-pdfnative) in the README. Key differentiators:

- **Zero runtime dependencies** (others ship 3–6).
- **22 Unicode scripts** with built-in BiDi and OpenType GSUB/GPOS shaping.
- **PDF/A** (1b, 2b, 2u, 3b) — none of the others support this directly.
- **Built-in digital signatures** (RSA + ECDSA) without external crypto modules.
- **5 native barcode formats** (Code 128, EAN-13, QR, Data Matrix, PDF417) as PDF vector paths.

### Does it convert HTML to PDF?

No, and it never will. HTML→PDF is a different problem domain (browser engine, CSS, layout) better solved by tools like `puppeteer` or `weasyprint`. pdfnative is a **structured-data → PDF** library — you describe blocks, it emits ISO-compliant PDF.

### Why no classes / no inheritance?

pdfnative is built from pure functions. State is passed explicitly. This makes the library trivially tree-shakeable, easy to test, and easy to reason about. See the [Architecture guide](architecture.html).

---

## Common errors

| Error | Likely cause | Fix |
|-------|--------------|-----|
| Blank / missing glyphs for a script (no error is thrown) | `loadFontData('xx')` resolved to `null` because no loader was registered for that code — it returns `null` rather than throwing | Call `registerFonts({ xx: … })` (or `registerFont`) first, then check the `loadFontData` result for `null` before building `fontEntries` |
| `PDF/A and encryption are mutually exclusive` | `tagged: 'pdfa…'` combined with `encryption: …` | Pick one |
| `Invalid color format: …` / `Invalid color tuple …` | Unrecognized color value passed to a layout option | Use `#rrggbb`, an `[r, g, b]` tuple with channels **0–255**, or a PDF RGB string `'r g b'` with channels 0.0–1.0 |
| Boxes / blank glyphs | Font for that script is not loaded | See [Troubleshooting → Missing glyphs](troubleshooting.html) |
| Parser throws on external PDF | Encrypted PDF opened without a password, or non-standard structure | Pass `openPdf(bytes, { password })` — the parser decrypts RC4, AES-128 and AES-256 since v1.6.0. A missing or wrong password throws `PdfPasswordError` |

For more cases, see the [Troubleshooting guide](troubleshooting.html).

---
<!-- source: docs/guides/font-validation.md -->
# Font-data validation

> **New in v1.4.0.** `validateFontData()` is an opt-in, read-only structural
> sanity check for **custom** font-data modules built from an untrusted or
> unfamiliar TTF/OTF. It catches the common failure modes early and returns
> `{ valid, errors, warnings }` instead of letting a cryptic `.notdef`/`NaN`
> surface deep inside the encoding/subsetting pipeline. The bundled
> `pdfnative/fonts/*` modules are already trusted — this is for fonts **you**
> build via `tools/build-font-data.cjs` or by hand.

## TL;DR

```ts
import { validateFontData } from 'pdfnative';
import type { FontValidationResult } from 'pdfnative';

const result: FontValidationResult = validateFontData(myFontData);
if (!result.valid) {
  console.error('Font rejected:', result.errors);
}
for (const w of result.warnings) console.warn('Font warning:', w);
```

## What it checks

| Area | Rule |
|---|---|
| Metrics | `unitsPerEm > 0`, finite; `bbox` is 4 finite numbers |
| Identity | `fontName` non-empty |
| Coverage | `cmap` non-empty; every glyph id is an integer in `[0, numGlyphs)` |
| Widths | `widths` present (missing → **warning**); `pdfWidthArray` non-empty |
| Binary | `ttfBase64` decodes as valid base64 and begins with an SFNT magic (`0x00010000`, `OTTO`, `true`, `ttcf`) |

Blocking problems land in `errors`; suspicious-but-survivable ones land in
`warnings`. It **never throws** — even on completely malformed input.

## It is opt-in by design

`validateFontData()` is **not** invoked automatically by `registerFont()`:
running it on every load would add cost and risk false-rejecting edge-valid
fonts. Call it yourself once when ingesting third-party font data, e.g. in a
build step or a test:

```ts
import { validateFontData, registerFont } from 'pdfnative';
import myFont from './my-font-data.js';

const { valid, errors } = validateFontData(myFont);
if (!valid) throw new Error(`Bad font data: ${errors.join('; ')}`);
registerFont('mylang', () => Promise.resolve(myFont));
```

## Sample

[font-validation-showcase.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/font-validation-showcase.ts)
validates a bundled font plus deliberately broken payloads and renders the
verdicts into a report PDF.

---
<!-- source: docs/guides/form-filling.md -->
# Form filling & flattening

> **New in v1.6.0.** Read, fill, and flatten the **interactive AcroForm fields
> of existing PDFs** — whether authored by pdfnative or a third party — via
> non-destructive incremental update. Complements the form *builder* (which
> creates fields from scratch).

## TL;DR

```ts
import { readFormFields, fillForm, flattenForm } from 'pdfnative';
import { readFileSync, writeFileSync } from 'node:fs';

const src = readFileSync('application.pdf');

// 1. Discover the fields
for (const f of readFormFields(src)) {
  console.log(f.name, f.type, f.value);
}

// 2. Fill by field name
const filled = fillForm(src, {
  fullName: 'Ada Lovelace',
  agree: true,               // checkbox
  country: 'France',         // dropdown option
});
writeFileSync('filled.pdf', filled);

// 3. Optionally flatten (make it non-editable)
writeFileSync('flat.pdf', flattenForm(filled));
```

## `readFormFields(bytes, options?)`

Returns a `ParsedFormField[]` describing every terminal field:

```ts
interface ParsedFormField {
  name: string;                               // fully-qualified (dotted) name
  type: 'text' | 'checkbox' | 'radio' | 'dropdown' | 'listbox'
      | 'button' | 'signature' | 'unknown';
  value: string | string[] | boolean | null;
  readOnly: boolean;
  required: boolean;
  multiline: boolean;
  options?: { export: string; label: string }[]; // choice fields
  maxLen?: number;
  onState?: string;                           // checkbox/radio "on" state name
  widgets: { pageIndex: number; rect: [number, number, number, number] }[];
  ref: number;                                // terminal field object number
}
```

Inherited attributes (`/FT`, `/Ff`, `/DA`, `/Opt`, `/MaxLen`) are resolved up the
`/Parent` chain, and UTF-16BE names/values are decoded.

## `fillForm(bytes, values, options?)`

`values` maps **fully-qualified field name → value**:

| Field type | Value |
|------------|-------|
| text / multiline | `string` |
| dropdown | `string` (one option's export/label) |
| listbox | `string` or `string[]` (multi-select) |
| checkbox / radio | `boolean`, or the export-state `string` |

```ts
interface FillFormOptions {
  flatten?: boolean;                          // fill then flatten in one call
  onUnknownField?: 'throw' | 'ignore';        // default 'throw'
  nonWinAnsi?: 'throw' | 'needAppearances';   // default 'throw'
  password?: string;                          // for encrypted documents (see below)
}
```

- Text/choice fields get a freshly generated, **self-contained** Helvetica
  appearance stream (its own `/Resources /Helv`), so filling never depends on the
  document's `/DR`.
- Checkbox/radio set `/V` and `/AS` from the widget's **own** `/AP` on/off states,
  preserving the document's original look.
- Non-WinAnsi text (e.g. CJK) can't be drawn with the built-in Helvetica
  appearance; pass `nonWinAnsi: 'needAppearances'` to write the value and let the
  viewer regenerate the appearance, or the call throws by default.

Errors: `FormFieldNotFoundError`, `FormValueTypeError`, `FormUnsupportedError`.

## `flattenForm(bytes, options?)`

Stamps each widget's appearance into its page content and removes the
interactive layer (`/AcroForm`, widget `/Annots`):

```ts
interface FlattenFormOptions {
  force?: boolean;      // flatten even over a signed signature field
  password?: string;    // for encrypted documents
}
```

Flattening a document with a **signed signature field** throws by default
(flattening is destructive to what was signed); pass `{ force: true }` to
override.

## Encrypted & signed documents

- **Encrypted documents are supported** (v1.6.0): pass the password —

  ```ts
  const filled = fillForm(encryptedPdf, { fullName: 'Grace Hopper' }, { password: 'secret' });
  const flat = flattenForm(filled, { password: 'secret' });
  ```

  The appended objects — field values, regenerated appearance streams,
  flatten overlays — are **encrypted under the document's existing scheme**
  (same `/Encrypt` dictionary, same file key; RC4, AES-128 and AES-256
  sources all work), so no plaintext ever leaks into an encrypted file and
  no downgrade or upgrade of the scheme is possible. A wrong or missing
  password throws `PdfPasswordError`. Note: the `/P` permission bits are
  **not enforced** — the update proceeds if the password authenticates;
  honouring the modify bit is the caller's responsibility
  (`openPdf(bytes, { password }).encryption.authenticatedAs` tells you
  which password opened the file).
- **Signed documents:** filling *non-signature* fields is allowed and preserves
  the signed revision byte-for-byte (incremental update only appends). Viewers
  will report "document modified after signing" for the added revision — expected,
  since the fill is a new, unsigned revision layered on top. Adding a *new*
  signature placeholder to an **encrypted** document is not supported
  (`addSignaturePlaceholder` needs a verbatim byte layout that cannot be
  transparently encrypted — it fails fast with a clear error).

## How it works

Both operations use the incremental modifier
([`createModifier`](architecture.html)), so the original bytes are never
rewritten — the update is appended after the existing body with a new xref and a
`/Prev` chain. That is why signatures on earlier revisions stay valid.

> **Searchable form text** _(v1.7.0)_. The AcroForm `/Helv` font dictionary now
> carries a `/ToUnicode` CMap in every mode, so text typed into form fields is
> searchable and extractable (see the [text extraction guide](text-extraction.html)).
> Because of that CMap, **every form-carrying document changes bytes** compared
> to v1.6.0 output (about 20 bytes) — a deliberate correctness fix, recorded in
> the v1.7.0 release notes. Under a PDF/A claim, a form field also raises the
> `PDFA_UNEMBEDDED_FORM_FONT` diagnostic (see the [PDF/A guide](pdfa.html)).

## See also

- [Signatures](signatures.html) — CMS/PKCS#7 signing
- [PDF manipulation](pdf-manipulation.html) — merge/split/extract, decryption
- [Accessibility](accessibility.html)
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/ltv.md -->
# Long-term validation (LTV) — PAdES B-B to B-LTA

> **New in v1.7.0.** pdfnative signs PDFs that stay verifiable for decades: PAdES baseline signatures (ETSI EN 319 142-1), RFC 3161 signature timestamps, embedded revocation material (`/DSS` + `/VRI`), and document timestamps — all with **zero runtime dependencies** and **zero network access in the engine**. Transport is injected by your code.

## TL;DR

```ts
import {
  buildDocumentPDFBytes, addSignaturePlaceholder, estimateContentsSize,
  signPdfBytesWithTimestamp, addValidationInfo, addDocumentTimestamp,
  setTimestampProvider, setRevocationProvider,
} from 'pdfnative';

// 1. Your transports (the engine never fetches on its own).
setTimestampProvider({
  async getTimestamp(request) {           // DER TimeStampReq in…
    const res = await fetch('https://freetsa.org/tsr', {
      method: 'POST',
      headers: { 'Content-Type': 'application/timestamp-query' },
      body: request.slice(),
    });
    return new Uint8Array(await res.arrayBuffer());  // …DER TimeStampResp out
  },
});
setRevocationProvider({
  async fetchOcsp(url, request) {
    const res = await fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/ocsp-request' },
      body: request.slice(),
    });
    return new Uint8Array(await res.arrayBuffer());
  },
  async fetchCrl(url) {
    const res = await fetch(url);
    return new Uint8Array(await res.arrayBuffer());
  },
});

// 2. Build → placeholder → sign+timestamp → embed validation → archive.
const unsigned = addSignaturePlaceholder(buildDocumentPDFBytes(params), {
  metadata: { subFilter: 'ETSI.CAdES.detached', reason: 'Contract v2' },
  placeholderBytes: estimateContentsSize([certDer.length], 'rsa-sha256', { timestamp: true }),
});
const signed  = await signPdfBytesWithTimestamp(unsigned, {
  signerCert, certChain: [intermediateCert], rsaKey,
  profile: 'pades',                       // ESS signing-certificate-v2, no CMS signing-time
});
const ltv     = await addValidationInfo(signed);       // /DSS + /VRI (B-LT)
const archive = await addDocumentTimestamp(ltv);       // DocTimeStamp (B-LTA)
```

Every step appends a non-destructive incremental revision — earlier bytes are never modified, so prior signatures stay intact.

## Why LTV

A plain signature proves *who* signed, but its verifiability decays: certificates expire, CAs go offline, revocation servers disappear. The PAdES baseline levels fix each failure mode in turn:

| Level | Adds | Protects against |
|---|---|---|
| **B-B** | CAdES signature with the ESS `signing-certificate-v2` attribute | Certificate substitution |
| **B-T** | RFC 3161 signature timestamp (`id-aa-signatureTimeStampToken`) | "Was the signature made while the certificate was valid?" |
| **B-LT** | `/DSS`: embedded certificates + OCSP/CRL responses, per-signature `/VRI` | Revocation servers disappearing |
| **B-LTA** | `/DocTimeStamp` covering the whole document | Algorithm/key aging — re-timestamp before the TSA certificate expires to extend the chain |

Adobe Reader shows a B-LT/B-LTA document as **"LTV enabled"** (with the chain's root trusted).

## The provider architecture

pdfnative **never opens a socket**. Two small interfaces move bytes; you own transport, proxies, retries and trust decisions:

```ts
interface TimestampProvider {
  getTimestamp(request: Uint8Array): Promise<Uint8Array>;   // TimeStampReq → TimeStampResp
}
interface RevocationProvider {
  fetchOcsp?(url: string, request: Uint8Array): Promise<Uint8Array>; // OCSPRequest → OCSPResponse
  fetchCrl?(url: string): Promise<Uint8Array>;                      // → CertificateList
}
```

Install globally (`setTimestampProvider` / `setRevocationProvider`) or pass per call (`timestampProvider:` / `revocationProvider:` options — per-call wins). pdfnative builds and parses every RFC 3161 / RFC 6960 / RFC 5280 structure itself, verifies the token's message imprint and nonce echo, and **refuses to embed** a rejected or tampered response.

## Step by step

### B-B — a PAdES baseline signature

```ts
const signed = signPdfBytes(placeheld, {
  signerCert, certChain, rsaKey,
  profile: 'pades',          // adds ESS signing-certificate-v2 (RFC 5035)
});
```

Pair `profile: 'pades'` with the placeholder's `metadata: { subFilter: 'ETSI.CAdES.detached' }` so the `/Sig` dictionary declares the PAdES SubFilter. The legacy default (`adbe.pkcs7.detached`, `profile: 'pkcs7'`) is unchanged. `digestAlgorithm: 'sha384' | 'sha512'` upgrades the whole CMS digest chain.

### B-T — the signature timestamp

`signPdfBytesWithTimestamp` (async) signs, hashes the CMS signature value, asks your `TimestampProvider` for a token, verifies it, and attaches it as an unsigned attribute — the signed bytes are untouched, so the signature stays valid. Reserve room for the token when creating the placeholder:

```ts
placeholderBytes: estimateContentsSize(certSizes, 'rsa-sha256', { timestamp: true })  // +8 KiB
```

### B-LT — the Document Security Store

```ts
const data = await collectValidationInfo(signed);   // async: chains + OCSP/CRL via provider
const ltv  = embedValidationInfo(signed, data);     // sync, offline, deterministic
// …or in one call: await addValidationInfo(signed)
```

`collectValidationInfo` walks every signed signature (and the TSA certificates inside embedded timestamp tokens), deduplicates the certificate pool, and requests OCSP (preferred) or CRL data for every certificate that advertises a source via its AIA / CRL-distribution-point extensions — skipping self-signed roots and `id-pkix-ocsp-nocheck` responders. Missing intermediates can be supplied with `extraCertificates`.

`embedValidationInfo` writes the `/DSS` dictionary — `/Certs`, `/OCSPs`, `/CRLs` stream arrays plus a `/VRI` entry per signature keyed by the uppercase-hex SHA-1 of its full `/Contents` value (the Adobe convention; `vriKeyForContents` exposes the computation). An existing `/DSS` is merged, never replaced. The split matters: collect once online, embed deterministically offline (or in tests).

### B-LTA — the document timestamp

```ts
const archive = await addDocumentTimestamp(ltv);
```

Appends a signature field whose dictionary is `/Type /DocTimeStamp /SubFilter /ETSI.RFC3161` with a **bare** TimeStampToken as `/Contents` (ISO 32000-2 §12.8.5 — no `/M`: the token's genTime is the time assertion). Field names auto-suffix (`DocTimeStamp1`, `DocTimeStamp2`, …) so periodic re-timestamping chains naturally.

## Multiple signatures

```ts
const a = signPdfBytes(addSignaturePlaceholder(pdf, { fieldName: 'Author' }), opts);
const b = signPdfBytes(
  addSignaturePlaceholder(a, { fieldName: 'Reviewer', allowMultiple: true }),
  { ...opts, fieldName: 'Reviewer' },
);
```

`allowMultiple: true` opts out of the historical one-signature short-circuit; the `fieldName` selector on `signPdfBytes` targets the right placeholder. Signed signatures are located by their real ByteRange values and can never be overwritten. Inspect any document with `listSignatures(bytes)`.

## Testing without a real TSA or CA

The repository ships a deterministic offline mock PKI (`scripts/helpers/mock-pki.ts`): a root CA, a signer with AIA/CRL-DP extensions, a TSA with the critical `id-kp-timeStamping` EKU and an OCSP responder with `ocsp-nocheck` — plus providers that produce **real, signed** TimeStampTokens, BasicOCSPResponses and CRLs. The `signature/signature-pades-*.pdf` samples and the `ltv-pipeline` integration suite run the full B-LTA chain with zero network. Public TSAs for manual testing include `https://freetsa.org/tsr`.

## Verification checklist

- `listSignatures(bytes)` — every entry, its SubFilter, ByteRange, placeholder/timestamp status.
- Adobe Reader: *Signature Panel → Certificate Details* — trust the mock/company root, then look for **"LTV enabled"** on B-LT documents and a valid document timestamp on B-LTA.
- `openssl ts -reply -in token.der -text` inspects extracted timestamp tokens.
- pdfnative itself ships **no signature verifier** — validation belongs to dedicated tooling (veraPDF for PDF/A, Adobe/DSS for signatures, `pdfnative-cli verify` for full cryptographic verification: CMS signature values, certificate chain and trust, RFC 3161 timestamps, OCSP/CRL revocation).

## Limits & scope (v1.7.0)

- ECDSA stays P-256 with SHA-256; RSA supports SHA-256/384/512.
- Chain building uses exact issuer-name matching over the embedded pool; cross-certification and bridge PKIs are out of scope.
- `collectValidationInfo` fetches from the **first** advertised OCSP/CRL URL; provider-side failover is your transport's business.
- Encrypted documents cannot take signature placeholders (unchanged from v1.2).
- PDF 2.0 `/Extensions` declarations are not emitted; the ISO 32000-2 constructs used here are accepted by all mainstream validators.

---
<!-- source: docs/guides/mcp.md -->
# pdfnative-mcp — AI Client Integration Guide

> **Tracks the latest published `pdfnative-mcp`** (v1.6.0, built on pdfnative 1.7.0). Full release notes: [pdfnative-mcp releases](https://github.com/Nizoka/pdfnative-mcp/releases). Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html).

[pdfnative-mcp](https://github.com/Nizoka/pdfnative-mcp) is an **MCP server** that exposes the full pdfnative library to any AI client supporting the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Cursor, Continue, Zed, ChatGPT, and more.

> **What is MCP?** The Model Context Protocol is an open standard (originally developed by Anthropic) that lets AI assistants call external tools in a structured, safe way. An MCP server declares a set of tools with typed inputs and outputs; the AI client invokes those tools on your behalf during a conversation.

With `pdfnative-mcp` installed, you can say to your AI assistant:

> _"Generate a Q1 2026 financial report as PDF/A-2b with a QR code pointing to our dashboard, then inspect the result to confirm it's archive-grade."_

…and the AI will call the right combination of `generate_basic_pdf`, `add_barcode`, `add_table`, and `inspect_pdf` tools, returning a ready-to-download PDF.

---

## Installation

```bash
# Run directly with npx — no global install required (recommended)
npx -y pdfnative-mcp

# Or install globally
npm install -g pdfnative-mcp
pdfnative-mcp
```

**Requirements:** Node.js ≥ 22.

---

## Configuration by client

### Claude Desktop

Edit the config file for your OS:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs"
      }
    }
  }
}
```

Restart Claude Desktop after saving. The `pdfnative` server will appear in the tools panel.

### Cursor

In your project `.cursor/mcp.json` (or global `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/path/to/pdf-output"
      }
    }
  }
}
```

### Continue

In your `~/.continue/config.json`:

```json
{
  "mcpServers": [
    {
      "name": "pdfnative",
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/path/to/pdf-output"
      }
    }
  ]
}
```

### Zed

In your Zed `settings.json`:

```json
{
  "context_servers": {
    "pdfnative": {
      "command": {
        "path": "npx",
        "args": ["-y", "pdfnative-mcp"],
        "env": {
          "PDFNATIVE_MCP_OUTPUT_DIR": "/path/to/pdf-output"
        }
      }
    }
  }
}
```

---

## Environment variables

| Variable | Purpose |
|---|---|
| `PDFNATIVE_MCP_OUTPUT_DIR` | Absolute path to the sandbox directory. **Required to enable `outputMode: "file"`**. When unset, only `base64` output is available. (The misspelt `PDFNATIVE_MPC_OUTPUT_DIR` still works as a deprecated alias.) |
| `PDFNATIVE_MCP_CACHE_DIR` | Absolute path to enable the persistent SHA-256-keyed result cache (1 h TTL, 256 MiB LRU). When unset, the cache is disabled. |
| `PDFNATIVE_MCP_PORT` | When set to a valid port (1–65535), starts an HTTP server on `http://127.0.0.1:<port>/mcp` instead of stdio. |
| `PDFNATIVE_MCP_HTTP_TOKEN` _(v1.6.0)_ | Opt-in bearer token for the HTTP transport (≥ 16 characters, no whitespace — a weaker value aborts startup). When set, `/mcp` requires `Authorization: Bearer <token>`; otherwise requests get `401` + `WWW-Authenticate`. Without it the loopback endpoint has **no authentication**. Never logged. |
| `PDFNATIVE_MCP_MAX_INFLATE_BYTES` _(v1.6.0)_ | Operator override of the engine's 100 MiB per-stream decompression cap (integer ≥ 1024, read once at startup; an invalid value refuses to start with one clean `fatal:` line). |
| `PDFNATIVE_MCP_TSA_URL` _(v1.6.0)_ | RFC 3161 timestamp authority endpoint. Required by `sign_pdf timestamp: true` and `timestamp_pdf` (`TSA_NOT_CONFIGURED` otherwise). |
| `PDFNATIVE_MCP_TSA_AUTH` _(v1.6.0)_ | Optional `Authorization` header value sent to the TSA. Treated as a secret; never logged. |
| `PDFNATIVE_MCP_REVOCATION` _(v1.6.0)_ | Revocation sources for `add_ltv mode: 'online'` — `ocsp`, `crl`, or `ocsp,crl` (`REVOCATION_NOT_CONFIGURED` otherwise). |
| `PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS` _(v1.6.0)_ | Mandatory allow-list of hosts the OCSP/CRL fetcher may contact. A certificate-supplied URL outside the list fails with `NETWORK_HOST_NOT_ALLOWED`. |
| `PDFNATIVE_MCP_NETWORK_TIMEOUT_MS` _(v1.6.0)_ | Network timeout for TSA/OCSP/CRL requests (1000–120000 ms, default 10000). |

> **Network charter** _(v1.6.0)_. The server still makes **no outbound request by default**. The only egress it can ever perform goes to the TSA / OCSP / CRL endpoints the **operator** configures via the variables above — URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard (allow-list, http(s) only, no credentials, no redirects, internal address literals rejected, size caps, timeouts).

---

## Tool reference

`pdfnative-mcp` exposes **28 tools**:

| Tool | Purpose |
|---|---|
| `generate_basic_pdf` | Multi-page documents from structured blocks — all **13 block kinds** since v1.6.0 (headings, paragraphs, lists, tables, images, links, TOC, barcodes, SVG, form fields, charts, page breaks, spacers). Accepts optional `pdfA`, layout options, build-time `encrypt`, and print-production fields. |
| `add_table` | Tabular PDF reports from column headers and data rows. Optional `autoFitColumns` and `clipCells`. Accepts `pdfA`. |
| `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 — embedded in a single-page PDF. Accepts `pdfA`. |
| `add_international_text` | 25 `lang` font codes — the 22 writing systems plus `latin`, `emoji` and the explicit `math` script (Noto Sans Math, on-demand) — with BiDi & OpenType shaping. `lang` accepts `string`, `string[]`, or comma-separated. |
| `add_form` | Interactive AcroForm PDFs with text fields, text areas, checkboxes, radio buttons, dropdowns, and list boxes _(v1.6.0)_. Accepts `pdfA`. |
| `embed_image` | Embed a JPEG or PNG image (base64-encoded) into a titled PDF document, with `align` and `alt` _(v1.6.0)_. Accepts `pdfA`. |
| `prepare_signature_placeholder` | Create a PDF with a `/Sig` AcroForm placeholder ready to be signed; `subFilter`, `reserveTimestamp` and frozen signer metadata _(v1.6.0)_. Accepts `pdfA`. |
| `sign_pdf` | PAdES CMS digital signatures — RSA-SHA256/384/512 and ECDSA-SHA256 P-256, `profile: 'pades'`, RFC 3161 `timestamp` (B-T), certificate chains, named fields and multiple signatures _(v1.6.0)_. |
| `add_ltv` _(v1.6.0)_ | Embed long-term-validation material (`/DSS` + `/VRI`) into a signed PDF — PAdES **B-LT** — online through the operator-configured revocation provider or offline from caller-supplied material. |
| `timestamp_pdf` _(v1.6.0)_ | Append a `/DocTimeStamp` (ETSI.RFC3161) through the operator TSA — PAdES **B-LTA** — with auto-suffixed field names for periodic re-timestamping. |
| `inspect_pdf` | Read-only inspection. Returns `version`, `pageCount`, `encryption`, `pdfA`, `signatureCount`, `info`, optional `perPage`, optional `pageLabels[]`, and — _(v1.6.0)_ — an optional `signatures[]` inventory, `annotations[]`, page boxes + `userUnit`, `dss` / `docTimestampCount` / `trapped`, plus `checks` + `checksPassed`. |
| `inspect_layout` _(v1.6.0)_ | Read-only pagination **dry run** — page count, page geometry and each block's position for a prospective document, with no PDF produced. |
| `validate_pdf` | Read-only PDF/UA structural validation (`valid`, `errors`, `warnings`). |
| `verify_pdf` | Real CMS/PKCS#7 signature verification — RSA & ECDSA, message digest, certificate chain. Since v1.6.0, `/DocTimeStamp` entries are verified as RFC 3161 tokens and `ltv: true` reports the achieved PAdES level (B-B → B-LTA). |
| `add_attachment` | Embed files (e.g. Factur-X / ZUGFeRD e-invoice XML) into PDF/A-3b output. |
| `extract_attachments` | Extract embedded files from an existing PDF (optionally metadata-only). |
| `extract_text` | Extract text content from an existing PDF via the native parser. |
| `merge_pdfs` | Concatenate 2–50 PDFs into one document via the page-tree API (drops signatures/`/AcroForm`, keeps URI links). |
| `split_pdf` | Split one PDF into one document per page range — multi-output `{ mode, count, totalBytes, parts[] }`. In-memory assembly is capped by `maxOutputSizeBytes`, default **256 MiB**; each emitted PDF is separately capped at 50 MiB. |
| `extract_pages` | Pull an arbitrary, order-preserving page subset (max 5000) into a single PDF. |
| `annotate_pdf` | Overlay markup annotations (text / highlight / underline / strikeout / squiggly / square / circle / line / freetext) on an existing PDF via incremental update. A visual review layer, **not** a redaction. |
| `draft_governance_issue` | Assemble a governance-compliant GitHub-issue draft plus a structured `compliance` report **locally** — network-free by construction; never submits. |
| `add_chart` _(v1.5.0)_ | Render a chart as **native PDF vector paths** — nine types since v1.6.0 (`bar`, `barH`, `stackedBar`, `stackedBarH`, `line`, `area`, `scatter`, `pie`, `donut`), with a secondary axis, log and time scales, and data labels. Tagged as `/Figure` with alt text when `pdfA` is set. |
| `read_form_fields` _(v1.5.0)_ | List an existing AcroForm's fields with their types, current values and available options — the read half of the fill round-trip. Accepts `password`. |
| `fill_form` _(v1.5.0)_ | Fill AcroForm field values and optionally `flatten` them into static page content. Works on encrypted PDFs via incremental update. |
| `encrypt_pdf` _(v1.5.0)_ | Re-secure an existing PDF with AES-128 or AES-256 — owner/user passwords and an explicit permission set. |
| `decrypt_pdf` _(v1.5.0)_ | Remove encryption from a password-protected PDF **in-server** — RC4, AES-128 and AES-256 sources. |
| `update_metadata` _(v1.6.0)_ | Rewrite an existing PDF's `/Info` dictionary (+ XMP) — title, author, subject, keywords, pinned `modDate` — as a non-destructive incremental update. |

Every tool publishes an `outputSchema` advertised in `tools/list`. Since v1.6.0 the server speaks the [MCP 2026-07-28 spec](https://modelcontextprotocol.io/specification/2026-07-28) (stateless envelope, `server/discover`, `resultType`, cache hints) on SDK v2, while 2025-era clients (2025-11-25 / 2025-06-18 / 2025-03-26) keep working through the automatic legacy fallback.

---

### `generate_basic_pdf`

Produces a multi-page document from a list of content blocks.

```jsonc
{
  "title": "Q1 2026 Report",
  "blocks": [
    { "type": "heading",   "text": "Executive Summary", "level": 1 },
    { "type": "paragraph", "text": "Revenue grew 24 % year over year." },
    { "type": "list",      "style": "bullet", "items": ["Strong APAC", "Stable EU", "Soft NA"] },
    { "type": "pageBreak" },
    { "type": "heading",   "text": "Details", "level": 2 }
  ],
  "footerText": "Confidential — Internal use only",
  "outputMode": "base64"
}
```

**Block types supported:** all **13 engine block kinds** since v1.6.0 — `heading` (levels 1–3), `paragraph`, `list` (`bullet` / `numbered`, nested items to depth 6), `table`, `image`, `link` (`http:` / `https:` / `mailto:` only), `toc` (a contents page with internal `/GoTo` links, pairs with `outline: 'auto'`), `barcode`, `svg` (a safe subset: paths, shapes and text — no XML parser, no external reference ever fetched), `formField`, `chart` (same body as `add_chart`), `pageBreak`, and `spacer` (`height` in points). The `table` / `image` / `barcode` / `formField` blocks share their body with the dedicated tools, so a standalone artefact and an inline block validate and render identically.

**Layout options** _(v1.6.0)_, available on all nine document tools: `pageSize` (`A4` default, `Letter`, `Legal`, `A3`, `Tabloid`), `margins` (all four sides, 0–200 pt), running `headerTemplate` / `footerTemplate` (`left` / `center` / `right` zones with `{page}` `{pages}` `{title}` `{date}` placeholders — a `footerTemplate` replaces the default footer, so `footerText` is then ignored), `compress`, and `debug`.

**Build-time `encrypt`** _(v1.6.0)_, on `generate_basic_pdf`, `add_table`, `add_form`, `add_international_text`, `embed_image`, `add_barcode` and `add_chart`: AES-128 (default) or AES-256 with owner/user passwords and permissions — and unlike `encrypt_pdf`, it **keeps the AcroForm**, making encrypted fillable forms reachable. Exclusive with `pdfA` (ISO 19005-1 §6.3.2); never cached.

**Print production** _(v1.6.0)_, on the nine document tools: `print` (TrimBox / BleedBox / ArtBox / CropBox, a `bleed` shorthand, crop + registration `marks`, `/UserUnit`), `metadata` (`/Author`, `/Subject`, `/Keywords`, `/Trapped` with XMP parity), and `outputIntent` (custom RGB ICC profile). `viewerPreferences` gains `duplex`, `pickTrayByPDFSize`, `printPageRange` (1-based), `numCopies`. Boxes survive `merge_pdfs` / `split_pdf` / `extract_pages` and are reported by `inspect_pdf`.

**Honest PDF/A** _(v1.6.0)_: text rendered through the viewer's base-14 Helvetica is not embedded, so a PDF/A claim on such a file is rejected by veraPDF. `embedFonts: true` embeds Noto Sans Latin for a valid claim; `strict: true` fails instead of producing a non-conformant file; `includeDiagnostics: true` echoes the engine's diagnostics (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`, `PDFA_DEVICE_CMYK_IMAGE`).

**Reproducible output** _(v1.6.0)_: `creationDate` (ISO-8601) on all nine document tools pins `/Info /CreationDate`, the XMP dates and therefore the trailer `/ID` — byte-identical output on the same host time zone.

---

### `add_table`

Generates a tabular report from column headers and rows.

```jsonc
{
  "title": "Monthly Sales",
  "headers": ["Region", "Units", "Revenue"],
  "rows": [
    ["APAC", "1 200", "$240,000"],
    ["EMEA", "800",   "$160,000"]
  ],
  "infoItems":      [{ "label": "Period", "value": "January 2026" }],
  "footerText":     "Internal use only",
  "autoFitColumns": true,
  "clipCells":      true,
  "pdfA":           "pdfa2b",
  "outputMode":     "base64"
}
```

`autoFitColumns` and `clipCells` transparently switch to the document-block backend so cell content fits its column or is clipped at the boundary, leveraging pdfnative's `TableBlock` props. Optional `pdfA` produces an archive-grade variant.

> **Smart-table fields (v1.0.0).** `add_table` exposes the six pdfnative 1.2 `TableBlock` fields: `wrap` (`'auto'` | `'always'` | `'never'`, default `'auto'`), `repeatHeader` (default `true`), `zebra`, `caption`, `minRowHeight`, `cellPadding`. Multi-page tables reprint headers and wrap on overflow by default — agent-driven invoice/report workflows get multi-page-safe output out of the box. See the [Smart tables guide](tables.md) for full semantics.

---

### `add_barcode`

```jsonc
{
  "format":     "qr",
  "data":       "https://pdfnative.dev",
  "caption":    "Scan to learn more",
  "ecLevel":    "H",
  "outputMode": "file",
  "outputPath": "tickets/event-42.pdf"
}
```

**Supported formats:** `qr`, `code128`, `ean13`, `datamatrix`, `pdf417`.  
**Error correction levels** (QR only): `L`, `M`, `Q`, `H`.

---

### `add_international_text`

```jsonc
{
  "title":      "مرحبا بالعالم 👋",
  "lang":       ["ar", "emoji"],
  "paragraphs": [
    "هذا اختبار للنص العربي مع تشكيل OpenType ومحارف ثنائية الاتجاه.",
    "Mixed content: العربية + English + emoji 🚀 ✓"
  ]
}
```

**Supported `lang` codes:** `ar` (Arabic), `he` (Hebrew), `th` (Thai), `ja` (Japanese), `zh` (Chinese Simplified), `ko` (Korean), `el` (Greek), `hi` (Devanagari/Hindi), `bn` (Bengali), `ta` (Tamil), `te` (Telugu), `si` (Sinhala), `bo` (Tibetan), `km` (Khmer), `my` (Myanmar), `am` (Ethiopic), `ru` (Cyrillic/Russian), `ka` (Georgian), `hy` (Armenian), `tr` (Turkish), `vi` (Vietnamese), `pl` (Polish), plus **`latin`** (Noto Sans VF), **`emoji`** (Noto Emoji/COLRv1) and the explicit **`math`** symbols font *(v1.4.0)*.

`lang` accepts `string`, `string[]`, or a comma-separated value — e.g. `"ar,emoji"` or `["ar", "emoji"]`. When `pdfA` is set on this tool, the `latin` font is auto-registered so curly quotes, em-dashes, and ellipses validate cleanly under PDF/A.

---

### `add_form`

Creates an interactive AcroForm PDF.

```jsonc
{
  "title": "Employee Onboarding",
  "fields": [
    { "fieldType": "text",     "name": "fullName", "label": "Full Name",   "required": true },
    { "fieldType": "dropdown", "name": "dept",     "label": "Department",  "options": ["Engineering", "Sales", "HR"] },
    { "fieldType": "checkbox", "name": "agree",    "label": "I agree to the terms", "checked": false }
  ],
  "outputMode": "base64"
}
```

**Field types:** `text`, `textarea`, `checkbox`, `radio`, `dropdown`, and `listbox` _(v1.6.0)_. Text fields accept an optional `placeholder` _(v1.6.0)_. Since v1.6.0, `textarea` maps to the engine's true multi-line field (`/Ff 4096`) — in v1.5.0 it rendered as a single-line widget.

---

### `embed_image`

```jsonc
{
  "title":       "Product Photo",
  "imageBase64": "<base64-encoded JPEG bytes>",
  "mimeType":    "image/jpeg",
  "caption":     "Front view of Model X",
  "width":       400,
  "outputMode":  "base64"
}
```

> **Note:** Alpha-channel PNGs (color type 6) are not supported. Pre-process such images to remove the alpha channel before embedding.

Since v1.6.0 the tool also accepts `align` (horizontal placement) and `alt` (accessibility text written as `/Figure /Alt` in tagged output).

---

### `prepare_signature_placeholder`

Creates a PDF pre-wired with an AcroForm `/Sig` field, ready to be signed by `sign_pdf`.

```jsonc
{
  "title":      "Service Agreement",
  "signerName": "Alice Dupont",
  "reason":     "Approved",
  "location":   "Paris, FR",
  "blocks": [
    { "type": "paragraph", "text": "By signing below, I accept the terms and conditions." }
  ],
  "outputMode": "base64"
}
```

Since v1.6.0 the placeholder also takes `subFilter`, `reserveTimestamp` (extra `/Contents` room for a later RFC 3161 token), `placeholderBytes`, and `signingTime` — and the signer metadata (`signerName`, `reason`, `location`, `contactInfo`, `signingTime`) is **baked into the `/Sig` dictionary at placeholder time**, fixing a pre-1.7 engine bug where those values never reached the signed document.

---

### `sign_pdf`

Signs any PDF. When the input already contains a `/Sig` placeholder (e.g. produced by `prepare_signature_placeholder`) it is signed in place; otherwise the placeholder is auto-injected first (`autoInjectPlaceholder` defaults to `true`; set it to `false` to require an existing placeholder).

```jsonc
{
  "pdfBase64":           "<base64 PDF bytes>",
  "algorithm":           "rsa-sha256",
  "certDerBase64":       "<base64 X.509 certificate in DER format>",
  "rsaKeyPkcs1DerBase64":"<base64 PKCS#1 RSAPrivateKey in DER format>",
  "signerName":          "Alice",
  "reason":              "Approval",
  "location":            "Paris, FR",
  "signingTime":         "2026-01-15T10:30:00Z"
}
```

For ECDSA P-256: use `"algorithm": "ecdsa-sha256"` and supply either `ecPrivateScalarHex` (64 hex chars, raw scalar `d`) or `ecPrivateKeyDerBase64` (SEC1 / PKCS#8 DER, base64 — signed through the constant-time `node:crypto` path) instead of `rsaKeyPkcs1DerBase64`. The two EC inputs are mutually exclusive.

**PAdES and timestamps** _(v1.6.0)_:

- `algorithm` also accepts `rsa-sha384` and `rsa-sha512`.
- `profile: 'pades'` produces an ETSI.CAdES.detached signature (PAdES **B-B**).
- `timestamp: true` requests an RFC 3161 timestamp from the operator-configured TSA (`PDFNATIVE_MCP_TSA_URL`) and embeds it in the CMS — PAdES **B-T**. Fails with `TSA_NOT_CONFIGURED` when no TSA is set, `TSA_REJECTED` when the authority declines.
- `certChainDerBase64` embeds intermediate certificates alongside the signer certificate.
- `fieldName` targets a specific `/Sig` field (`SIGNATURE_FIELD_NOT_FOUND` when absent, `PLACEHOLDER_AMBIGUOUS` when several placeholders exist and none is named); `allowMultiple: true` adds a signature next to existing ones instead of rejecting.
- The default placeholder reservation is now `max(16384, estimated CMS size)` — plus 8192 bytes when `timestamp: true` — instead of a flat 16384 bytes. To pin it exactly, build the placeholder with `prepare_signature_placeholder` and its `placeholderBytes` input.

To climb the rest of the PAdES ladder, follow with [`add_ltv`](#add_ltv-v160) (B-LT) and [`timestamp_pdf`](#timestamp_pdf-v160) (B-LTA), then check the achieved level with `verify_pdf ltv: true`. The server's `pades_ladder` prompt walks through the full recipe.

---

### `inspect_pdf`

Read-only PDF inspection over `openPdf()`. Never modifies the input.

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "pages":     true,
  "check":     ["pdfa", "signed"]
}
```

**Inputs:**
- `pdfBase64` — base64 PDF bytes (required).
- `password` — password for an encrypted PDF *(v1.5.0)*.
- `pages` — when `true`, includes per-page `index`, `width`, `height` — and, since v1.6.0, the declared page boxes and `userUnit`.
- `signatures` *(v1.6.0)* — when `true`, a per-signature inventory: `subFilter`, `isDocTimestamp`, `isPlaceholder`, `byteRange`, `vriKey`.
- `annotations` *(v1.6.0)* — when `true`, an `annotations[]` list (0-based `page`, `subtype`, `rect`, and when present `contents`, `title`, `color`, `quadPoints`, link `url`) plus `annotationCount`.
- `check` — array of CI assertions. Allowed values: `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`, and — *(v1.6.0)* — `dss`, `docTimestamp`, `trapped`, `annotations`. The response includes `checks` (per-assertion result) and `checksPassed` (boolean AND). Since v1.6.0, `checks` contains **only the requested keys**.
- `verbosity` — `'full'` (default) or `'summary'` (token-frugal scalar subset).
- `fields` — optional dot-path projection of the result.

**Outputs:** `version`, `pageCount`, `encryption` (`'none'` / `'aes-128'` / `'aes-256'` / `'rc4'` / `'unknown'`), optional `encryptionInfo` (`{ algorithm, revision, authenticatedAs }`, present when the document is encrypted and opened successfully), `pdfA` (`null` or the detected claim string), `signatureCount`, `hasSignaturePlaceholder`, `attachments[]` (embedded-file summaries), `info` (decoded `/Info` entries), optional `perPage[]`, optional `pageLabels[]` (when `/PageLabels` is declared), optional `checks` + `checksPassed` — plus, presence-gated since v1.6.0, `dss`, `docTimestampCount` and `trapped`.

Useful in CI as a final assertion step before publishing a PDF artifact:

```jsonc
{ "tool": "inspect_pdf",
  "input": { "pdfBase64": "<...>", "check": ["pdfa", "signed"] } }
// → { ..., "checks": { "pdfa": true, "signed": true }, "checksPassed": true }
```

---

### `merge_pdfs`

Concatenates **2–50** PDFs into a single document via pdfnative's page-tree API. Encrypted sources are supported since v1.5.0 via `password` (a single password applied to every encrypted source), and the output can be re-encrypted via `encrypt`. Signatures and `/AcroForm` are dropped because page edits invalidate `/ByteRange`; self-contained URI `/Link` annotations are kept.

```jsonc
{
  "pdfsBase64": ["<base64 PDF 1>", "<base64 PDF 2>", "<base64 PDF 3>"],
  "outputMode": "base64"
}
```

**Errors:** `PASSWORD_REQUIRED` / `PASSWORD_INVALID` (encrypted source without / with the wrong `password`), `OUTPUT_TOO_LARGE` (50 MiB per emitted PDF; assembly capped by `maxOutputSizeBytes`, default 256 MiB), `PDF_PARSE_FAILED`.

---

### `split_pdf`

Splits one PDF into one document per page range, returning a **multi-output** shape. Ranges are **0-based and inclusive**; `end` defaults to `start` (a single page).

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "ranges": [{ "start": 0, "end": 2 }, { "start": 3, "end": 9 }],
  "outputMode": "base64"
}
// → { "mode": "base64", "count": 2, "totalBytes": 123456, "parts": [ { "index": 0, "sizeBytes": 61000, "base64": "..." }, ... ] }
```

Each part is capped at **50 MiB**; the aggregate output is capped at **200 MiB**.

---

### `extract_pages`

Pulls an arbitrary, order-preserving page subset (**max 5000** pages) into a single PDF.

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "pages": [0, 2, 4, 1],
  "outputMode": "base64"
}
```

Page indices are **0-based**; the output preserves the order you request.

### `annotate_pdf`

Overlays markup annotations on an existing PDF via **incremental update**, so the original bytes — and any existing signature — stay intact.

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "annotations": [
    { "type": "highlight", "page": 0, "rect": [72, 700, 520, 715], "color": "#ffe066", "contents": "Review this clause" },
    { "type": "text",      "page": 1, "rect": [80, 640, 100, 660], "contents": "Sticky note" }
  ],
  "outputMode": "base64"
}
```

Types: `text`, `highlight`, `underline`, `strikeout`, `squiggly`, `square`, `circle`, `line`, `freetext`. Each takes a **0-based** `page`, a `rect: [x1, y1, x2, y2]`, and optional `color` / `contents`. Encrypted sources → `ENCRYPTED_SOURCE`; an out-of-range `page` → a validation error.

> **Overlay, not redaction.** `annotate_pdf` is a *visual review layer*; the underlying bytes remain. It does **not** remove or obscure content — see the deferred `redact_pdf` note under *What's new in v1.4.0*.

### `draft_governance_issue`

Assembles a governance-compliant GitHub-issue draft plus a structured `compliance` report **locally** and returns them. It **never submits** and makes **no** network call — there is no HTTP client, no GitHub SDK, and no `fetch` anywhere in the server.

```jsonc
{
  "title": "SVG <text> word-wrap not supported",
  "issueType": "feature",
  "summary": "renderSvg() emits <text> on a single line with no automatic wrapping.",
  "reproduction": {
    "command": "node repro.mjs",
    "result": "Long <text> overflows the viewport instead of wrapping."
  },
  "expectedBehavior": "Optional word-wrap for SVG <text>.",
  "targetRepo": "pdfnative",
  "affectedPackages": ["pdfnative"],
  "duplicateSearchPerformed": true,
  "outputMode": "inline"
}
```

`duplicateSearchPerformed` **must be `true`**. A draft that proposes a runtime dependency, omits a reproduction, or sets it to `false` is rejected with `GOVERNANCE_VIOLATION`. Present the returned `draftMarkdown` + `compliance` to the user; a **human** submits it. Read the `governance_contract` / `draft_issue_workflow` prompts first.

### `add_chart` _(v1.5.0)_

Renders a chart as **native PDF vector paths** — no rasterisation, no image round-trip. Multi-series bar/line, legends, gridlines and negative values are supported; the chart is tagged `/Figure` with `/Alt` (auto-generated when `altText` is omitted).

```jsonc
{
  "chartType": "bar",
  "title": "Revenue by quarter",
  "series": [{ "label": "2026", "values": [1.2, 1.5, 1.4, 1.9] }],
  "intro": "Quarterly revenue in $M.",
  "pdfA": "pdfa2b",
  "outputMode": "base64"
}
```

**Inputs:** `chartType` (`bar` / `barH` / `line` / `pie` / `donut`, plus — _(v1.6.0)_ — `stackedBar` / `stackedBarH` / `area` / `scatter`) and `series` (required; pie/donut take exactly one series), plus `title`, `legend` (`'bottom'` / `'none'`), `markers` (line series), `colors` (hex palette override), `altText`, `intro` (paragraph above the chart), `pdfA`, `outputMode` / `outputPath`. For a chart amongst headings/paragraphs/tables, use a `chart` block inside `generate_basic_pdf` — both build identical pdfnative blocks.

**Charts v2** _(v1.6.0)_: per-series `xValues` with `xAxis.type: 'linear' | 'time'` (UTC-deterministic time axes), a secondary right axis (`axis2`), `axis.scale: 'log'`, `dataLabels`, and `labelStride` / `labelRotation` for crowded x labels. Engine cross-field rules surface as `CHART_ERROR` with a remedy.

### `read_form_fields` _(v1.5.0)_

Read-only enumeration of an existing PDF's AcroForm — the discovery half of the fill round-trip.

```jsonc
{ "pdfBase64": "<base64 PDF bytes>", "verbosity": "full" }
```

**Inputs:** `pdfBase64` (required), `password` (encrypted sources), `verbosity` (`'full'` default / `'summary'` = `{ fieldCount }` only), `fields` (dot-path projection).  
**Outputs:** `fieldCount` and `fields[]` — each with `name` (fully-qualified), `type` (`text` / `checkbox` / `radio` / `dropdown` / `listbox` / `button` / `signature` / `unknown`), current `value`, `readOnly` / `required` / `multiline` flags, `options[]` (`{ export, label }` for choice fields), `maxLen`, `onState`, and `widgets[]` (0-based page + rect).

### `fill_form` _(v1.5.0)_

Fills (and optionally flattens) the AcroForm of an *existing* PDF via a non-destructive **incremental update**, so a prior signature stays valid for its revision. Works on encrypted documents via `password` (appended objects are encrypted under the document's existing scheme).

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "values": { "fullName": "Alice Dupont", "agree": true },
  "flatten": false,
  "outputMode": "base64"
}
```

**Inputs:** `pdfBase64` (required), `values` (name → string | boolean | string[]; omit with `flatten: true` for a pure flatten), `flatten` (default `false`), `onUnknownField` (`'throw'` default / `'ignore'`), `nonWinAnsi` (`'throw'` default / `'needAppearances'`), `password`, `outputMode` / `outputPath`.  
**Errors:** `FORM_FIELD_NOT_FOUND`, `FORM_VALUE_TYPE_ERROR`, `FORM_UNSUPPORTED` (signature fields cannot be filled/flattened), `PASSWORD_REQUIRED` / `PASSWORD_INVALID`.

### `encrypt_pdf` _(v1.5.0)_

Re-secures an existing PDF with AES-128 (default, widest compatibility) or AES-256 via the page-tree re-encryption path. An already-encrypted source can be rotated to a new password by supplying its current `password`.

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "ownerPassword": "s3cret-owner",
  "userPassword": "open-me",
  "algorithm": "aes256",
  "permissions": { "print": true, "copy": false, "modify": false, "extractText": false },
  "outputMode": "base64"
}
```

**Inputs:** `pdfBase64` and `ownerPassword` (required), `userPassword` (omitted/empty = opens without a prompt), `algorithm` (`'aes128'` default / `'aes256'`), `permissions` (`{ print?, copy?, modify?, extractText? }`, each allowed when omitted), `password` (current password of an encrypted source), `outputMode` / `outputPath`.

> Like merge/split/extract, encryption rebuilds the page tree: existing signatures and `/AcroForm` are **dropped**, and only self-contained URI link annotations are kept. Encrypt **before** signing, not after. Excluded from the response cache.

### `decrypt_pdf` _(v1.5.0)_

Opens an encrypted PDF (RC4, AES-128 or AES-256) and emits an unencrypted copy **in-server** — no external tool needed.

```jsonc
{ "pdfBase64": "<base64 encrypted PDF>", "password": "open-me", "outputMode": "base64" }
```

**Inputs:** `pdfBase64` (required), `password` (user or owner; omit only for documents with an empty user password), `outputMode` / `outputPath`.

> The rebuild drops signatures and `/AcroForm`. To *read* an encrypted PDF without rebuilding it, pass `password` to `inspect_pdf` / `extract_text` / `extract_attachments` instead. Excluded from the response cache.

### `add_ltv` _(v1.6.0)_

Embeds long-term-validation material — a `/DSS` (Document Security Store) with `/VRI` entries — into an already-signed PDF via incremental update, taking a PAdES B-T document to **B-LT**.

```jsonc
{
  "pdfBase64": "<base64 signed PDF>",
  "mode": "online",
  "preferOcsp": true,
  "outputMode": "base64"
}
```

**Inputs:** `pdfBase64` (required), `mode` (`'online'` default — fetches OCSP responses / CRLs through the operator-configured revocation provider; `'offline'` — embeds parse-validated caller-supplied material), `preferOcsp`, `certificatesDerBase64[]` / `ocspResponsesDerBase64[]` / `crlsDerBase64[]` (offline material), `outputMode` / `outputPath`. The structured result includes a `summary` of what was embedded.

**Errors:** `LTV_NO_SIGNATURE` (nothing to validate), `LTV_EMPTY` (no material gathered), `LTV_MATERIAL_INVALID`, `LTV_ERROR`, `REVOCATION_NOT_CONFIGURED` (online mode without `PDFNATIVE_MCP_REVOCATION`), `NETWORK_HOST_NOT_ALLOWED`, `NETWORK_ERROR`, `ENCRYPTED_SOURCE` (decrypting would destroy the signatures — sign before encrypting).

> Online mode is the **only** network-touching path in the server besides the TSA, and it only ever contacts operator-allow-listed hosts. See *Environment variables* above.

### `timestamp_pdf` _(v1.6.0)_

Appends a `/DocTimeStamp` signature field (ETSI.RFC3161) through the operator-configured TSA, taking a B-LT document to **B-LTA**. The token's status, message imprint and nonce are checked before embedding; its own CMS signature is verified by `verify_pdf`.

```jsonc
{
  "pdfBase64": "<base64 signed PDF>",
  "outputMode": "base64"
}
```

**Inputs:** `pdfBase64` (required), `fieldName` (auto-suffixed `DocTimeStamp1`, `DocTimeStamp2`, … when omitted — supporting periodic re-timestamping), `placeholderBytes` (4096–65536), `outputMode` / `outputPath`.

**Errors:** `TSA_NOT_CONFIGURED`, `TSA_REJECTED`, `NETWORK_ERROR`, `ENCRYPTED_SOURCE`.

### `update_metadata` _(v1.6.0)_

Rewrites an existing PDF's `/Info` dictionary — and its XMP packet when present — via a non-destructive **incremental update**, so earlier revisions stay a byte-exact prefix.

```jsonc
{
  "pdfBase64": "<base64 PDF bytes>",
  "title": "Quarterly Report — Final",
  "author": "Finance Team",
  "keywords": "finance, Q1, 2026",
  "modDate": "2026-08-25T09:00:00+02:00",
  "outputMode": "base64"
}
```

**Inputs:** `pdfBase64` (required), `title`, `author`, `subject`, `keywords` (≤ 1000 characters), `modDate` (ISO-8601 with offset — pinned for reproducible bytes), `outputMode` / `outputPath`.

**Errors:** `ENCRYPTED_SOURCE` (use `decrypt_pdf` → `update_metadata` → `encrypt_pdf`), `METADATA_ERROR`, `PDF_PARSE_FAILED`.

### `inspect_layout` _(v1.6.0)_

A read-only pagination **dry run**: measures how a prospective document would paginate — without producing a PDF and without consuming output tokens on base64 bytes. The seventh read tool with `verbosity` / `fields`.

```jsonc
{
  "title": "Q1 2026 Report",
  "blocks": [
    { "type": "heading", "text": "Executive Summary", "level": 1 },
    { "type": "paragraph", "text": "Revenue grew 24 % year over year." }
  ],
  "verbosity": "summary"
}
// → { "pageWidth": 595.28, "pageHeight": 841.89, "totalPages": 1, "blockCount": 2 }
```

**Inputs:** `title` and `blocks` (required), plus every input that moves a block — `footerText`, `pdfA`, `normalize`, `embedFonts`, `pageSize`, `margins`, `headerTemplate`, `footerTemplate` — and `verbosity` / `fields`.

**Outputs (full):** `pageWidth`, `pageHeight`, `margins`, `totalPages`, and `pages[].blocks[]` with each block's `type`, `page`, `x`, `top`, `width`, `height` (2-decimal points).

> **Known engine gap:** a `toc` block is measured as 0 pt, so a document with a printed contents page may paginate one page later than previewed.

---

## MCP prompts

Since v1.4.0 the server advertises the MCP **`prompts`** capability; v1.6.0 grows it to **six prompts** — the two governance prompts plus four recipe prompts:

| Prompt | Purpose |
|---|---|
| `governance_contract` | The full AI-governance / Human-in-the-Loop contract. |
| `draft_issue_workflow` | The step-by-step recipe for producing a compliant issue draft with `draft_governance_issue`. |
| `pades_ladder` _(v1.6.0)_ | The B-B → B-T → B-LT → B-LTA recipe: `sign_pdf` → `add_ltv` → `timestamp_pdf`, verified with `verify_pdf ltv: true`. |
| `print_ready` _(v1.6.0)_ | Producing press-ready output: bleed, printer's marks, custom OutputIntent. |
| `reproducible_output` _(v1.6.0)_ | Byte-stable output via pinned `creationDate` / `signingTime` / `modDate`. |
| `pdfa_valid` _(v1.6.0)_ | Producing a PDF/A file that veraPDF actually accepts (`embedFonts`, `strict`, diagnostics). |

## Error codes

| `code` | Raised by | Meaning / fix |
|---|---|---|
| `ENCRYPTED_SOURCE` | `annotate_pdf`, `update_metadata`, `add_ltv`, `timestamp_pdf` | The source PDF is encrypted and the tool has no `password` parameter. Remedies are tool-specific since v1.6.0: for `annotate_pdf` / `update_metadata`, `decrypt_pdf` → edit → `encrypt_pdf`; for `add_ltv` / `timestamp_pdf`, decrypting would destroy the signatures — sign before encrypting. |
| `PASSWORD_REQUIRED` *(v1.5.0)* | password-aware tools (`inspect_pdf`, `verify_pdf`, `extract_text`, `extract_attachments`, `read_form_fields`, `fill_form`, page-tree trio, `encrypt_pdf`, `decrypt_pdf`) | The source is encrypted and no `password` was supplied. |
| `PASSWORD_INVALID` *(v1.5.0)* | password-aware tools | The supplied `password` does not open the document. |
| `ENCRYPTION_UNSUPPORTED` *(v1.5.0)* | password-aware tools | The document uses an encryption scheme the reader does not support. |
| `FORM_FIELD_NOT_FOUND` *(v1.5.0)* | `fill_form` | A `values` key matches no field (with `onUnknownField: 'throw'`, the default). |
| `FORM_VALUE_TYPE_ERROR` *(v1.5.0)* | `fill_form` | A value's type does not match the field (e.g. a boolean for a text field). |
| `FORM_UNSUPPORTED` *(v1.5.0)* | `fill_form` | The field cannot be filled/flattened (e.g. a signature field). |
| `OUTPUT_TOO_LARGE` | PDF-emitting tools | An emitted PDF exceeds 50 MiB (for `split_pdf`, also the 200 MiB aggregate), or assembly exceeds `maxOutputSizeBytes` (default 256 MiB). |
| `PDF_PARSE_FAILED` | page-tree tools | The source bytes are not a parseable PDF. |
| `GOVERNANCE_VIOLATION` | `draft_governance_issue` | The draft breaks the AI-governance contract (proposes a runtime dependency, omits a reproduction, or `duplicateSearchPerformed: false`). Fix the draft and retry. |
| `TSA_NOT_CONFIGURED` *(v1.6.0)* | `sign_pdf` (`timestamp: true`), `timestamp_pdf` | No `PDFNATIVE_MCP_TSA_URL` is set. Configure the TSA in the server environment. |
| `TSA_REJECTED` *(v1.6.0)* | `sign_pdf`, `timestamp_pdf` | The timestamp authority declined the request. |
| `REVOCATION_NOT_CONFIGURED` *(v1.6.0)* | `add_ltv` (`mode: 'online'`) | No `PDFNATIVE_MCP_REVOCATION` sources are set. Configure them, or use `mode: 'offline'` with caller-supplied material. |
| `NETWORK_HOST_NOT_ALLOWED` *(v1.6.0)* | `add_ltv` | A certificate-supplied OCSP/CRL URL points outside `PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS`. |
| `NETWORK_ERROR` *(v1.6.0)* | TSA/LTV tools | The TSA/OCSP/CRL request failed (timeout, refusal, size cap). |
| `LTV_NO_SIGNATURE` / `LTV_EMPTY` / `LTV_MATERIAL_INVALID` / `LTV_ERROR` *(v1.6.0)* | `add_ltv` | No signature to validate / no material gathered / supplied DER material does not parse / embedding failed. |
| `METADATA_ERROR` *(v1.6.0)* | `update_metadata` | The incremental `/Info` + XMP rewrite failed. |
| `PRINT_ERROR` *(v1.6.0)* | document tools with `print` | The requested page boxes are inconsistent (e.g. do not fit `pageSize`). |
| `CHART_ERROR` *(v1.6.0)* | `add_chart`, `chart` blocks | An engine cross-field chart rule failed (the message carries the remedy). |
| `PLACEHOLDER_AMBIGUOUS` *(v1.6.0)* | `sign_pdf` | Several unsigned placeholders exist and no `fieldName` was given. |
| `SIGNATURE_FIELD_NOT_FOUND` *(v1.6.0)* | `sign_pdf` | The named `fieldName` does not exist. |
| `CMS_PARSE_FAILED` *(v1.6.0)* | `verify_pdf` | A CMS structure is shorter or more malformed than the parser expects. |

> **Protocol errors** *(v1.6.0)*: calling an unknown tool or prompt name is now a JSON-RPC `-32602` error (`[UNKNOWN_TOOL]` / `[UNKNOWN_PROMPT]`), not an `isError` result. Likewise, an unknown or misspelt input key — top-level or nested — fails with `VALIDATION_ERROR` ("Unrecognized key") instead of being silently stripped.

---

## The `pdfA` flag

Every document tool (`generate_basic_pdf`, `add_table`, `add_form`, `embed_image`, `add_barcode`, `prepare_signature_placeholder`, `add_international_text`, `add_chart` *(v1.5.0)*) accepts an optional `pdfA` field. `add_attachment` is the special case: it always produces **PDF/A-3b** (the only conformance level that allows arbitrary embedded files), so it has no `pdfA` input.

| `pdfA` value | PDF version | Notes |
|---|---|---|
| `"pdfa1b"` | 1.4 | Most conservative — no transparency, no AES |
| `"pdfa2b"` | 1.7 | Default archive target |
| `"pdfa2u"` | 1.7 | 2b + Unicode mapping for every glyph |
| `"pdfa3b"` | 1.7 | 2b + arbitrary `/EmbeddedFile` attachments |

When set on `add_international_text`, the `latin` font auto-registers so non-WinAnsi Latin characters validate cleanly. Mutually exclusive with the underlying pdfnative encryption layer (ISO 19005-1 §6.3.2).

---

## Output modes

Every document-producing tool accepts an `outputMode` field. The seven read-only
tools (`inspect_pdf`, `inspect_layout`, `validate_pdf`, `verify_pdf`, `extract_text`,
`extract_attachments`, `read_form_fields`) return JSON only and have no
`outputMode`:

| Mode | Behaviour |
|---|---|
| `"base64"` *(default)* | The PDF bytes are returned inline in the MCP response as a base64 string. Suitable for pipelines that immediately consume or display the bytes. |
| `"file"` | The PDF is written to the sandbox directory configured via `PDFNATIVE_MCP_OUTPUT_DIR`. An `outputPath` (relative, `.pdf` extension) is required. **Disabled unless the environment variable is set.** |

> **Exception:** `draft_governance_issue` uses `outputMode: "inline" | "file"` (not `base64`) and writes a **`.md`** draft — not a PDF — when `file` mode is selected.

---

## End-to-end example: signed document

This workflow uses two tools in sequence:

```jsonc
// Step 1 — create the placeholder
{
  "tool": "prepare_signature_placeholder",
  "input": {
    "title":      "Purchase Order #42",
    "signerName": "Jane Smith",
    "reason":     "CFO approval",
    "location":   "London, UK",
    "blocks": [
      { "type": "paragraph", "text": "Total amount: $128,000" }
    ],
    "outputMode": "base64"
  }
}

// Step 2 — sign the returned PDF
{
  "tool": "sign_pdf",
  "input": {
    "pdfBase64":            "<result from step 1>",
    "algorithm":            "rsa-sha256",
    "certDerBase64":        "<your DER certificate>",
    "rsaKeyPkcs1DerBase64": "<your PKCS#1 private key>",
    "signerName":           "Jane Smith",
    "reason":               "CFO approval",
    "location":             "London, UK",
    "signingTime":          "2026-04-26T09:00:00Z",
    "outputMode":           "base64"
  }
}
```

---

## Security model

`pdfnative-mcp` is designed to run safely inside your AI client:

- **No network access by default** — the server opens no outbound connection unless the **operator** configures TSA/OCSP/CRL endpoints for the PAdES tools (see the network charter under *Environment variables*). URLs never come from tool arguments, and certificate-supplied OCSP/CRL URLs pass an SSRF guard.
- **Sandboxed file writes** — `file` output mode is gated by `PDFNATIVE_MCP_OUTPUT_DIR`. When unset, file writes are rejected with a `SecurityError`.
- **Path traversal protection** — absolute paths, `..` sequences, NUL bytes, and non-`.pdf` extensions are all rejected.
- **Output size cap** — PDF output is capped at **50 MiB** per call. `split_pdf` additionally enforces **50 MiB per part** and a **200 MiB aggregate** ceiling across its parts, returning `OUTPUT_TOO_LARGE` when exceeded.
- **HTTP transport hardening** — when bound to `PDFNATIVE_MCP_PORT`, the HTTP transport is loopback-only and rejects foreign `Host` / `Origin` headers with **403** (DNS-rebinding protection). An opt-in bearer token (`PDFNATIVE_MCP_HTTP_TOKEN`) adds authentication _(v1.6.0)_ — without it, the loopback endpoint has none.
- **Input validation** — every tool validates inputs against strict JSON Schemas and Zod runtime checks at the boundary. Since v1.6.0 every schema is `.strict()` at every nesting level, so an unknown or misspelt key is a `VALIDATION_ERROR` instead of being silently stripped, and PEM armour where DER base64 is expected fails with the exact `openssl … -outform DER` remedy.
- **Decompression cap** — the engine's 100 MiB per-stream inflate cap is operator-tunable via `PDFNATIVE_MCP_MAX_INFLATE_BYTES` _(v1.6.0)_.

See [SECURITY.md](https://github.com/Nizoka/pdfnative-mcp/blob/main/SECURITY.md) for responsible disclosure.

---

## Fonts come from the local `pdfnative` install

`pdfnative-mcp` bundles **no font data of its own**: at runtime it resolves the
locally installed `pdfnative` package and lazily imports the Noto font modules
from that package's `fonts/` directory, embedding a font only when a request
actually uses it. Two practical consequences:

- **Upgrading the local `pdfnative` upgrades the server's font coverage** —
  nothing to configure, nothing re-downloaded.
- **The local install is an extension point for agents.** A coding agent on the
  host can compile a font with `compileFontData` (`pdfnative/tools`) into the
  resolved local install and the next tool call serves it — the pattern that
  closed the mathematical-symbols gap locally before Noto Sans Math shipped in
  the engine. The published `lang` enum is closed and there is no operator-level
  fonts variable yet (a roadmap candidate), so this is a local code-level
  pattern — see [Agentic workflows → Via the MCP server](agentic-workflows.html#via-the-mcp-server--the-local-install-is-the-extension-point)
  for the honest, step-by-step version.

---

## Troubleshooting

**The server does not appear in my AI client.**  
Verify that Node.js ≥ 22 is installed (`node --version`) and that the config file path is correct for your OS. Restart the client after any config change.

**`file` output mode returns a SecurityError.**  
Set the `PDFNATIVE_MCP_OUTPUT_DIR` environment variable to an existing absolute path in the client config.

**`add_international_text` produces blank text.**  
The Noto fonts ship bundled with `pdfnative` — no network access is needed. Blank text usually means an unsupported `lang` code or a corrupted install; check the `lang` value against the supported list and reinstall `pdfnative` if needed.

**`sign_pdf` fails with "invalid placeholder".**  
By default `sign_pdf` auto-injects a `/Sig` placeholder when the input has none (`autoInjectPlaceholder: true`), so this error normally only appears when `autoInjectPlaceholder` was set to `false` — either drop that flag or call `prepare_signature_placeholder` first, and make sure the placeholder PDF was not modified between creation and signing.

**Output PDF exceeds 50 MB.**  
Split the content across multiple tool calls or reduce image/barcode count.

---

## Release history

The current release is **v1.6.0** (28 tools, built on pdfnative 1.7.0 — see the header note). Per-release notes, oldest first:

### What's new in v1.0.0

v1.0.0 is the **first stable release**, built on `pdfnative` 1.2.0, and commits to API stability via a per-tool `_meta.apiVersion` field. New fields are optional and backward-compatible — omitting them produces byte-identical output. Tool count: **12** (was 9).

- **Three new tools:**
  - **`verify_pdf`** — read-only verification of every PAdES Baseline / `adbe.pkcs7.detached` signature: recomputes the `ByteRange` SHA-256, validates the CMS `messageDigest`, and verifies the `signatureValue` with the embedded signer certificate (RSA-SHA256 + ECDSA-SHA256 P-256). Optional `trustedRootsDerBase64` enables chain trust.
  - **`add_attachment`** — generate a **PDF/A-3 (ISO 19005-3)** document with one or more embedded files. Primary use case: **Factur-X / ZUGFeRD** electronic invoices (XML payload with `relationship: 'Source'`). 8 MiB per-file cap.
  - **`extract_text`** — best-effort plain-text extraction from a non-encrypted PDF (operands of `Tj` / `'` / `"` / `TJ`). Reports `extractable: false` when a page yields no text; encrypted PDFs are rejected.
- **Smart-table fields on `add_table`** — `wrap`, `repeatHeader`, `zebra`, `caption`, `minRowHeight`, `cellPadding` (pdfnative 1.2 `TableBlock` props). Multi-page tables reprint headers and wrap on overflow by default.
- **Signing ergonomics** — `sign_pdf` accepts ECDSA SEC1 / PKCS#8 DER keys and `autoInjectPlaceholder: true` (default) transparently calls `addSignaturePlaceholder()` when the input lacks a `/Sig` widget (one-call signing of any PDF).
- **`inspect_pdf`** now reports `hasSignaturePlaceholder` and an `attachments[]` summary; two new `check` values: `placeholder`, `attachments`. The `signed` check is now `signatureCount > 0 && !hasSignaturePlaceholder`.
- **Opt-in result cache** (`PDFNATIVE_MCP_CACHE_DIR`) — SHA-256 keyed over canonical JSON of `{tool, apiVersion, input}`, 1 h TTL, 256 MiB LRU. Skips `outputMode: 'file'` calls.
- **`_meta.apiVersion = '1.0.0'`** and per-tool **`_meta.examples`** on every tool listing for AI-agent discovery — anchored to [`docs/API_STABILITY.md`](https://github.com/Nizoka/pdfnative-mcp/blob/main/docs/API_STABILITY.md).
- **`pdfA` flag on every document tool** — values `pdfa1b`, `pdfa2b`, `pdfa2u`, `pdfa3b`, mapping to pdfnative's `tagged` option (spread straight from pdfnative's exported `PDF_A_CONFORMANCE_TARGETS`).
- **Env-var rename:** the canonical name is `PDFNATIVE_MCP_OUTPUT_DIR` (was the misspelt `PDFNATIVE_MPC_OUTPUT_DIR`, which still works as a deprecated alias with a one-shot stderr warning, scheduled for removal in v2.0.0).

**Deferred to v1.1:** `merge_pdfs`, `split_pdf`, `redact_pdf` — require pdfnative page-tree primitives not yet exported.

### What's new in v1.1.0

v1.1.0 upgrades the server to the `pdfnative` 1.3.0 engine and adds accessibility-first read tooling:

- **New tool: `validate_pdf`** — read-only PDF/UA structural conformance checks (ISO 14289-1).
- **Six additional scripts** in `add_international_text`: Telugu (`te`), Sinhala (`si`), Tibetan (`bo`), Khmer (`km`), Myanmar (`my`), Ethiopic (`am`).
- **COLRv1 colour emoji support** through the upgraded engine.
- **Paragraph newline sanitization** to avoid malformed text blocks when callers send embedded `\n`.

### What's new in v1.2.0

v1.2.0 keeps full backward compatibility and extends MCP ergonomics for AI workflows:

- **New tool: `extract_attachments`** — read embedded files from PDF/A-3 documents (Factur-X / ZUGFeRD round-trip).
- **Watermark support** on `generate_basic_pdf` and `add_table` (text, opacity, angle, color, position).
- **Opt-in Unicode normalization** (`normalize`: `NFC` / `NFD` / `NFKC` / `NFKD`) on international/document flows.
- **Token-frugal read modes** on read-only tools via `verbosity: 'summary'` and selective `fields` projection.
- **Base64 payload deduplication**: generated bytes are returned once via `resource` in base64 mode.

### What's new in v1.3.0

<!-- verify-docs:allow version-token (historical release entry) -->
v1.3.0 upgrades the engine to **pdfnative 1.4.0**, adds a page-tree tool trio, and stays fully backward-compatible — tool count rises to **17**:

- **Three new page-tree tools:**
  - **`merge_pdfs`** — concatenate **2–50** source PDFs into one document via pdfnative's page-tree API. Encrypted sources are rejected; signatures and `/AcroForm` are dropped (page edits invalidate `/ByteRange`); self-contained URI `/Link` annotations are preserved.
  - **`split_pdf`** — split one PDF into one document per page range, returning a **multi-output** shape `{ mode, count, totalBytes, parts[] }`. Caps: **50 MiB per part**, **200 MiB aggregate**.
  - **`extract_pages`** — pull an arbitrary, order-preserving page subset (**max 5000** pages) into a single PDF.
- **Enriched authoring options** (from pdfnative 1.4.0): <!-- verify-docs:allow version-token (historical) -->
  - `generate_basic_pdf` gains `outline` (`'auto'` or an explicit nested tree), `pageLabels`, **nested `list` items** (max depth 6), and `viewerPreferences`.
  - `add_table` gains `cellBorders` (top/right/bottom/left, color, width, style), `cellVAlign` (`'top'` / `'middle'` / `'bottom'`), and `viewerPreferences`.
  - `add_international_text` gains `viewerPreferences`.
- **Constant-time signing** — `sign_pdf` now signs RSA and EC-DER keys through a per-call `node:crypto` provider (constant-time) with a transparent pure-JS fallback; pure-scalar `ecPrivateScalarHex` remains pure-JS.
- **HTTP transport hardening** — the `PDFNATIVE_MCP_PORT` Streamable HTTP transport now rejects foreign `Host` / `Origin` headers with **403** (DNS-rebinding protection). `serverInfo` advertises a human-readable `title` + `description` (MCP 2025-11-25 alignment).
- **New error codes** on the page-tree tools: `ENCRYPTED_SOURCE`, `OUTPUT_TOO_LARGE`, `PDF_PARSE_FAILED`.
- **Spec alignment** — MCP SDK `^1.29` (2025-11-25 revision), JSON Schema 2020-12, and `_meta.apiVersion` bumped to `1.3.0` on every tool.

---

### What's new in v1.4.0

v1.4.0 upgrades the engine to **pdfnative 1.5.0**, brings the pdfnative **AI-governance / Human-in-the-Loop (HITL)** system to the MCP surface, and adds markup annotations — taking the catalogue to **19 tools** at that release.<!-- verify-docs:allow stale-token (historical: v1.4.0 total) --> Fully backward-compatible: every v1.3.0 call works unchanged and default responses are byte-identical.

- **Two new tools:**
  - **`draft_governance_issue`** — an agent drafts a fully compliant GitHub issue **locally** (a draft `.md` plus a machine-readable `compliance` report) and stops. The agent is a **draftsman, never an autonomous submitter**: a human is the only gate, and — by construction, not just policy — the server makes **zero** GitHub writes and **no** outbound network call. A draft that proposes a runtime dependency, omits a reproduction, or sets `duplicateSearchPerformed: false` is rejected with the new `GOVERNANCE_VIOLATION` error.
  - **`annotate_pdf`** — overlay `text`, `highlight`, `underline`, `strikeout`, `squiggly`, `square`, `circle`, `line`, and `freetext` annotations on an existing PDF via incremental update. A **visual review layer, not a redaction** — the underlying bytes remain. Encrypted sources → `ENCRYPTED_SOURCE`.
- **MCP `prompts` capability** — the server now advertises two prompts: `governance_contract` (the full HITL contract) and `draft_issue_workflow` (the step-by-step recipe).
- **Page labels in `inspect_pdf`** — read-only surfacing of `/PageLabels` ranges via a new optional `pageLabels[]` output field (present only when the PDF declares them).
- **Math / scientific script** — `add_international_text` accepts the explicit `math` lang (Noto Sans Math), embedded on demand only (e.g. `lang: ['latin', 'math']`); there is **no** global auto-routing.
- **Engine upgrade** — pdfnative `^1.4.0` → `^1.5.0` (additive, no breaking changes); `_meta.apiVersion` bumped to `1.4.0` on every tool.

> **`redact_pdf` is deferred by design.** pdfnative's annotation writer can only *overlay* content; an overlay-only “redaction” would leave the original bytes intact and create **false security**. It is intentionally **not** shipped and is tracked as an upstream true content-removal request — a fitting first use of `draft_governance_issue`.

### What's new in v1.5.0

v1.5.0 upgrades the engine to **pdfnative 1.6.0** and takes the catalogue to **24 tools** at that release,<!-- verify-docs:allow stale-token (historical: v1.5.0 total) --> closing the read/modify loop on documents the assistant did not create.

- **Five new tools:**
  - `add_chart` — bar, horizontal-bar, line, pie and donut charts drawn as **native PDF vector paths**. No rasterisation and no image round-trip, so the output stays sharp at any zoom and tags as `/Figure` with alt text. If you were previously asking an agent to render a chart to PNG and push it through `embed_image`, stop — this replaces that.
  - `read_form_fields` — list an AcroForm's fields with types, current values and options.
  - `fill_form` — fill values and optionally `flatten` them into static page content. Works on encrypted documents via incremental update.
  - `encrypt_pdf` — re-secure with AES-128 or AES-256, setting owner/user passwords and a permission set.
  - `decrypt_pdf` — remove encryption **in-server**, for RC4, AES-128 and AES-256 sources.
- **Passwords on the read tools.** `inspect_pdf`, `verify_pdf`, `extract_text` and `extract_attachments` accept a `password`, as do the page-tree trio. Encrypted sources are no longer rejected outright.
- **New error codes:** `PASSWORD_REQUIRED`, `PASSWORD_INVALID`, `ENCRYPTION_UNSUPPORTED`, `FORM_FIELD_NOT_FOUND`, `FORM_VALUE_TYPE_ERROR`, `FORM_UNSUPPORTED`.
- **Generated PDFs are exposed as MCP resources** (`pdfnative://output/{path}`), so a client can list and re-read them without a second tool call. File-mode results carry a `resource_link`.
- **Tool annotations** (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are published in `tools/list`, letting a client reason about which calls are safe to retry.
- The encryption tools are deliberately **excluded from the response cache**.

### What's new in v1.6.0

v1.6.0 aligns the server with the **MCP 2026-07-28** specification and grows the catalogue to **28 tools**, exposing the engine's full document model and completing the PAdES baseline ladder. No breaking changes: every v1.5.0 call keeps its inputs, error codes and response shape, and a superset gate against the published 1.5.0 catalogue proves it.

- **Four new tools:**
  - `add_ltv` — embed `/DSS` + `/VRI` long-term-validation material (PAdES **B-LT**), online through the operator-configured revocation provider or offline from caller-supplied material.
  - `timestamp_pdf` — append a `/DocTimeStamp` through the operator TSA (PAdES **B-LTA**), with auto-suffixed field names for periodic re-timestamping.
  - `update_metadata` — rewrite `/Info` (+ XMP) of an existing PDF as an incremental update.
  - `inspect_layout` — a read-only pagination dry run: page count and block positions with no PDF produced.
- **Full engine coverage** — `generate_basic_pdf` composes all **13 block kinds** (`table`, `image`, `link`, `toc`, `barcode`, `svg`, `formField` join the six existing ones); `pageSize`, `margins`, running `headerTemplate` / `footerTemplate`, `compress` and `debug` on the nine document tools; build-time `encrypt` that **keeps the AcroForm**; image watermarks with `position`.
- **PAdES signing** — `sign_pdf` gains `profile: 'pades'`, `timestamp: true` (RFC 3161, B-T), RSA-SHA384/512, `certChainDerBase64`, `fieldName` / `allowMultiple`; `verify_pdf ltv: true` reports profile, timestamp, embedded revocation status and the achieved level; `prepare_signature_placeholder` gains `subFilter` / `reserveTimestamp` and freezes signer metadata into the `/Sig` dictionary (fixing a pre-1.7 engine bug where those values were silently dropped).
- **Network charter** — still **no outbound request by default**; the single permitted egress class is the operator-configured TSA / OCSP / CRL endpoints, never a URL from a tool argument, behind an SSRF guard. Seven new environment variables configure the HTTP bearer token, the inflate cap and the network providers.
- **Print production** — `print` page boxes, `bleed`, printer's `marks`, `/UserUnit`, `metadata` with `/Trapped`, custom `outputIntent`; boxes survive the page-tree tools and are reported by `inspect_pdf`.
- **Charts v2** — `stackedBar` / `stackedBarH` / `area` / `scatter`, per-series `xValues` with linear or time axes, secondary `axis2`, `axis.scale: 'log'`, `dataLabels`, `labelStride` / `labelRotation`.
- **Honest PDF/A** — `embedFonts: true` (embed Noto Sans Latin for a claim veraPDF accepts), `strict: true` (fail instead of emitting a non-conformant file), `includeDiagnostics: true`; two new diagnostics; an advisory veraPDF corpus runs locally and in CI.
- **MCP 2026-07-28 transport** — SDK v2 (`@modelcontextprotocol/server`), `server/discover`, `resultType`, cache hints, per-result `serverInfo`, deterministic `tools/list`; 2025-era clients keep working via the automatic legacy fallback.
- **Four new recipe prompts** — `pades_ladder`, `print_ready`, `reproducible_output`, `pdfa_valid` — taking the prompt catalogue to six.
- **Reproducible output** — `creationDate` on all nine document tools, `signingTime` on the placeholder, `modDate` on `update_metadata`.

**Migrating from v1.5.0** — six behaviour changes, all on error paths or on inputs the published schema already declared invalid:

1. **Stray keys fail.** An unknown or misspelt key, top-level or nested, is now `VALIDATION_ERROR` ("Unrecognized key") instead of being silently stripped — the schemas always declared `additionalProperties: false`.
2. **Page-index mistakes are `VALIDATION_ERROR`.** Out-of-range pages / ranges on `merge_pdfs` / `split_pdf` / `extract_pages` were `PDF_PARSE_FAILED`; the message now carries a 0-based hint.
3. **`validate_pdf` on unparsable bytes is an error, not a verdict.** v1.5.0 returned `{ valid: false }`; v1.6.0 returns `isError: true` `[PDF_PARSE_FAILED]` — a parse failure is not a PDF/UA verdict.
4. **Unknown tool or prompt names are protocol errors** — JSON-RPC `-32602` (`[UNKNOWN_TOOL]` / `[UNKNOWN_PROMPT]`), no `isError` result.
5. **`inspect_pdf.checks` holds only the keys you asked for** — read `checksPassed` or the requested key, never an absent one.
6. **`add_form` text areas change bytes.** `fieldType: 'textarea'` now produces a real multi-line field (`/Ff 4096`).

---

## Further reading

- [pdfnative-mcp on GitHub](https://github.com/Nizoka/pdfnative-mcp) — source, issues, CHANGELOG
- [pdfnative-mcp on npm](https://www.npmjs.com/package/pdfnative-mcp) — version history, install stats
- [pdfnative Quick Start](quickstart.html) — pdfnative library directly in Node.js / browser
- [Architecture guide](architecture.html) — how pdfnative-mcp sits in the ecosystem
- [Model Context Protocol specification](https://modelcontextprotocol.io) — MCP standard reference

---
<!-- source: docs/guides/onboarding.md -->
# Onboarding — the pdfnative ecosystem in 90 seconds

> **Pick your entry point:** the library for code, the CLI for shell scripts, MCP for AI assistants, and React for declarative JSX. They all produce the same ISO 32000-1 / PDF/A-conformant PDFs from the same zero-dependency engine. Live versions for every package are shown at the top of the [documentation home](../index.html).

---

## 1. Library (Node, browser, Deno, Bun) — 30 seconds

```bash
npm install pdfnative
```

```ts
import { buildDocumentPDFBytes, registerFont, loadFontData } from 'pdfnative';

// Optional: enable a non-Latin script — register under the script code ('ar'),
// then load the data and pass it via fontEntries (registration alone is a no-op):
registerFont('ar', () => import('pdfnative/fonts/noto-arabic-data.js'));
const ar = await loadFontData('ar');
if (!ar) throw new Error('Arabic font failed to load');

// Synchronous — returns a Uint8Array, not a Promise.
const bytes = buildDocumentPDFBytes({
  title: 'Hello pdfnative',              // top-level, not inside metadata
  metadata: { author: 'Me' },            // author / subject / keywords only
  blocks: [
    { type: 'heading', text: 'Hello pdfnative', level: 1 },
    { type: 'paragraph', text: 'Pure native PDF, zero runtime dependencies.' },
  ],
  fontEntries: [{ fontData: ar, fontRef: '/F3', lang: 'ar' }], // /F1 and /F2 are reserved
  layout: { tagged: 'pdfa2b' },          // optional PDF/A-2b
});

// In Node: await fs.writeFile('out.pdf', bytes);
// In browser: new Blob([bytes], { type: 'application/pdf' });
```

Next: [Quick Start →](quickstart.html) · [Architecture →](architecture.html) · [PDF/A conformance →](pdfa.html)

---

## 2. CLI — 30 seconds

```bash
npm install -g pdfnative-cli   # or: npx pdfnative-cli ...
```

> The package is named `pdfnative-cli`, but the binary it puts on your PATH is
> **`pdfnative`**. Under `npx`, either name works.

```bash
# Check the environment first — the fastest way to confirm the install worked
pdfnative doctor

# Render a JSON document → PDF. Input and output are flags, not positionals;
# with neither, render reads stdin and writes stdout.
pdfnative render --input doc.json --output out.pdf --tagged pdfa2b

# Sign it (auto-injects a signature placeholder if needed)
pdfnative sign --input out.pdf --output signed.pdf \
  --key signer.key --cert signer.crt --algorithm rsa-sha256

# Verify the embedded CMS signature
pdfnative verify --input signed.pdf --json
```

Iteration helpers: `--watch` re-renders on save, `--template` deep-merges a base document under your input (caller wins; arrays replace), `--font` enables any of the 22 bundled scripts + colour emoji + the math font. v1.1.0 added `--stream-true`, `inspect --pdfua` (accessibility gate), and an agent-native `--json`/`E_*`/`--dry-run` contract; v1.2.0 added page-tree `merge` / `split` / `extract`, markup `annotate`, an AI-governance `govern` gate, and `render --outline` / `--font math` / `--inspect-layout`; v1.3.0 added `fill`, `encrypt`, `decrypt`, `extract-text` and `doctor`, native `chart` blocks in `render`, passwords on the page-tree commands, and PowerShell completion; **v1.4.0** adds the full PAdES ladder (`sign --timestamp`, `ltv`, `doc-timestamp`), signature-safe `metadata` edits, a CI-grade `compare` diff, and declarative `batch --manifest` pipelines (Node ≥ 22).

> **Upgrading from v1.2.0?** `render --encrypt` was a silent no-op in that
> release — documents you thought were encrypted were written in the clear.
> v1.3.0 fixes it and unifies the flags under `--encrypt` / `--owner-password` /
> `--user-password` / `--permissions`. Re-run any affected job.

Next: [CLI guide →](cli.html) · [CLI playground →](../playgrounds/cli.html)

---

## 3. MCP (Claude Desktop, Cursor, Continue, Zed) — 30 seconds

```bash
npm install -g pdfnative-mcp
```

Add the server to your client config — Claude Desktop example (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"]
    }
  }
}
```

Then prompt your assistant:

> *Create a PDF/A-2b invoice for ACME Inc, add a multilingual paragraph in Arabic, and sign it with my key.*

The assistant calls `generate_basic_pdf` (with `pdfA: "pdfa2b"`), then `add_international_text` (with `lang: ["ar", "emoji"]`), `add_table`, `sign_pdf`, and finally `inspect_pdf` — confirming the result. v1.6.0 ships **28 tools**, including the complete PAdES ladder (`sign_pdf` with RFC 3161 timestamps, `add_ltv`, `timestamp_pdf`), the page-tree trio `merge_pdfs`, `split_pdf`, `extract_pages`, markup `annotate_pdf`, `update_metadata`, the read-only `inspect_layout` pagination preview, the network-free `draft_governance_issue`, plus `validate_pdf`, `verify_pdf`, `add_attachment`, `extract_attachments`, and `extract_text`.

Next: [MCP guide →](mcp.html) · [MCP playground →](../playgrounds/mcp.html)

---

## 4. React (Next.js, Remix, any React 19 app) — 30 seconds

```bash
npm install pdfnative-react pdfnative react
```

```tsx
import { Document, Heading, Text, Table, renderToBytes } from 'pdfnative-react';

const bytes = renderToBytes(
  <Document title="Invoice #1024" footerText="Acme Inc">
    <Heading level={1}>Invoice #1024</Heading>
    <Text>Thank you for your business.</Text>
    <Table headers={['Item', 'Total']} rows={[{ cells: ['Pro plan', '$49.00'], type: 'default', pointed: false }]} zebra />
  </Document>,
); // → Uint8Array, a valid PDF
```

A custom React reconciler compiles your JSX to pdfnative blocks on-device — no DOM, no headless browser. Preview live with the `usePdf` hook / `PDFViewer`, or let AI agents author with the token-frugal `DocSpec`. **React 19 is a peer dependency of `pdfnative-react` only** — the engine stays zero-dependency.

Next: [React guide →](react.html) · [React playground →](../playgrounds/react.html)

---

## What to read next

- New to PDFs in code? Start with [Quick Start](quickstart.html) and [Architecture](architecture.html).
- Need accessible / archive-grade output? Read [Accessibility](accessibility.html) and [PDF/A conformance](pdfa.html).
- Hit a snag? See [Troubleshooting](troubleshooting.html) and the [FAQ](faq.html).
- Curious about the trade-offs? The [FAQ](faq.html) compares pdfnative with pdfkit, jsPDF, and pdf-lib.

If pdfnative saved you time, a ⭐ on [GitHub](https://github.com/Nizoka/pdfnative) helps others find it. Thanks!

---
<!-- source: docs/guides/outlines.md -->
# Outlines & page labels

> **New in v1.4.0.** Give long documents a navigable **bookmark tree**
> (`/Outlines`) and **logical page numbering** (`/PageLabels`) — roman-numbered
> front matter, prefixed appendices, custom starting numbers. Both are opt-in
> `DocumentParams` fields and add zero overhead when unused.

## TL;DR

```ts
import { buildDocumentPDFBytes } from 'pdfnative';

const bytes = buildDocumentPDFBytes({
  title: 'Annual Report',
  outline: 'auto',                       // bookmarks derived from headings
  pageLabels: [
    { startPage: 0, style: 'roman' },    // startPage is 0-based — i, ii, iii … (front matter)
    { startPage: 3, style: 'decimal' },  // 1, 2, 3 … (body, from the 4th page)
  ],
  blocks: [
    { type: 'heading', level: 1, text: 'Overview' },
    { type: 'paragraph', text: '…' },
    { type: 'heading', level: 2, text: 'Highlights' },
    { type: 'paragraph', text: '…' },
  ],
});
```

## Document outline (bookmarks)

The outline appears in the viewer's sidebar / bookmarks panel and lets readers
jump straight to a section. Set `DocumentParams.outline` to either `'auto'` or
an explicit nested tree.

### Automatic outline from headings

```ts
outline: 'auto'
```

pdfnative walks your `HeadingBlock`s and builds a nested tree by heading level
(`level: 1` → top level, `level: 2` → child, …), each bookmark linking to the
page the heading lands on. This is the zero-effort option for structured
reports.

### Explicit outline

For full control over titles, nesting, ordering, styling, and destinations,
pass an array of `OutlineItem`:

```ts
import type { OutlineItem } from 'pdfnative';

const outline: OutlineItem[] = [
  {
    title: 'Part I — Introduction',
    pageIndex: 0,       // 0-based page index
    bold: true,
    children: [
      { title: 'Background', pageIndex: 0 },
      { title: 'Scope',      pageIndex: 1 },
    ],
  },
  {
    title: 'Part II — Results',
    pageIndex: 2,
    color: [0.1, 0.3, 0.9], // RGB 0–1; also accepts '#1a4fd6'
    children: [
      { title: 'Findings', pageIndex: 2, italic: true },
    ],
  },
];
```

| `OutlineItem` field | Type | Description |
|---|---|---|
| `title` | `string` | Bookmark label (encoded as PDF text, UTF-16BE when needed) |
| `pageIndex` | `number` | 0-based page index to jump to |
| `y` | `number?` | Optional vertical destination (PDF user units from the bottom); defaults to the top of the page |
| `bold` | `boolean?` | Render the label bold (`/F` flag 2) |
| `italic` | `boolean?` | Render the label italic (`/F` flag 1) |
| `color` | `PdfColor?` | Label colour (`/C`) — `[r,g,b]` 0–1 or a hex string |
| `open` | `boolean?` | Initial expansion state. `true` (default) renders the bookmark expanded; `false` renders it **collapsed** (negative `/Count`), hiding its children until the reader expands it. Only meaningful with `children`. |
| `children` | `OutlineItem[]?` | Nested bookmarks |

Destinations use `/XYZ` with the page's top-left as the default anchor, so the
viewer scrolls the target page into view at 100 % zoom.

### Collapsed bookmarks

Deep hierarchies read better when some branches start collapsed. Set
`open: false` on any item with children:

```ts
const outline: OutlineItem[] = [
  { title: 'Front matter', pageIndex: 0 },
  {
    title: 'Appendices',
    pageIndex: 12,
    open: false,            // collapsed on open — children hidden until expanded
    children: [
      { title: 'Appendix A', pageIndex: 12 },
      { title: 'Appendix B', pageIndex: 18 },
    ],
  },
];
```

pdfnative emits the spec-correct signed `/Count` (ISO 32000-1 §12.3.3): a
positive count for open items, a negative count for collapsed ones, and a
collapsed node contributes only itself — not its hidden descendants — to its
ancestors' visible counts.

## Page labels

By default a viewer numbers pages `1, 2, 3 …`. `/PageLabels` overrides that with
*logical* numbering — front matter in lowercase roman, the body in decimal,
appendices with an `A-` prefix, and so on. The labels show in the viewer's page
thumbnail / "go to page" box and in printed page references.

```ts
import type { PageLabelRange } from 'pdfnative';

const pageLabels: PageLabelRange[] = [
  { startPage: 0, style: 'roman' },                 // i, ii, iii
  { startPage: 3, style: 'decimal' },               // 1, 2, 3
  { startPage: 20, style: 'decimal', prefix: 'A-', start: 1 }, // A-1, A-2
];
```

| `PageLabelRange` field | Type | Description |
|---|---|---|
| `startPage` | `number` | 0-based page index where this range begins |
| `style` | `PageLabelStyle?` | `'decimal'` · `'roman'` (i, ii) · `'Roman'` (I, II) · `'alpha'` (a, b) · `'Alpha'` (A, B) · `'none'` (label is the prefix only) |
| `prefix` | `string?` | Text prepended to each label (e.g. `'A-'`) |
| `start` | `number?` | First number in the range (default `1`) |

Ranges must be ordered by `startPage` and stay within the document's page
count — both are validated at the boundary with a descriptive error.

## How it works

- **Outline** — `buildOutlineObjects()`
  ([`src/core/pdf-outline.ts`](https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-outline.ts))
  emits the `/Outlines` dictionary plus one indirect object per bookmark, wired
  with `/First /Last /Next /Prev /Parent /Count`. The objects are appended as
  trailing indirect objects and the catalog gains `/Outlines N 0 R`.
- **Page labels** — `buildPageLabelsDict()`
  ([`src/core/pdf-page-labels.ts`](https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-page-labels.ts))
  emits an inline `/PageLabels << /Nums [...] >>` number tree in the catalog, so
  it adds no indirect objects.

Both features are fully additive: a document with neither field is **byte-identical**
to the pre-v1.4.0 output.

## See also

- [Quick start](quickstart.html)
- [PDF manipulation](pdf-manipulation.html) — merge/split/extract
- [Accessibility](accessibility.html) — tagged structure & TOC
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/pdf-manipulation.md -->
# PDF manipulation (merge / split / extract)

> **New in v1.4.0.** Combine, slice, and reorder existing PDFs with a
> production-safe page-tree API. Each operation **rebuilds a clean object graph**
> rather than patching bytes in place — inherited page attributes are resolved,
> dangling references are pruned, and the result is a fresh, well-formed PDF.

## TL;DR

```ts
import { mergePdfs, splitPdf, extractPages } from 'pdfnative';
import { readFileSync, writeFileSync } from 'node:fs';

const a = readFileSync('cover.pdf');
const b = readFileSync('body.pdf');

// Merge
writeFileSync('combined.pdf', mergePdfs([a, b]));

// Split into page ranges (0-based, end inclusive; end defaults to start)
const [intro, rest] = splitPdf(b, [
  { start: 0, end: 1 },   // pages 0–1
  { start: 2, end: 9 },   // pages 2–9
]);

// Extract specific pages (0-based)
writeFileSync('selected.pdf', extractPages(b, [0, 3, 7]));
```

All three accept and return `Uint8Array` PDF bytes.

> **New in v1.6.0.** Encrypted sources are now **decrypted on ingest** — pass a
> password (see [Encrypted sources](#encrypted-sources)) — the rebuilt output
> can be **re-encrypted** with `encrypt` (see
> [Re-encrypting the output](#re-encrypting-the-output)), and there are
> constant-memory **streaming** variants (`streamMergedPdfs` / `streamSplitPdf` /
> `streamExtractPages`, see [Streaming merge & split](#streaming-merge--split)).

## `mergePdfs(sources, options?)`

Concatenates multiple PDFs into one, in order.

```ts
function mergePdfs(
  sources: readonly PdfSourceInput[],
  options?: MergeOptions,
): Uint8Array;

// Raw bytes, or bytes + password for an encrypted source (v1.6.0):
type PdfSourceInput = Uint8Array | { bytes: Uint8Array; password?: string };

interface MergeOptions {
  /** Strip digital-signature widgets/fields from the result. Default false. */
  dropSignatures?: boolean;
  /** Strip all annotations (links, comments, …) from the result. Default false. */
  dropAnnotations?: boolean;
  /** Password used to decrypt encrypted sources (default for every source). v1.6.0 */
  password?: string;
  /**
   * Maximum size, in bytes, of the assembled output. The operation throws as
   * soon as the copied object graph would exceed this limit — even mid-copy,
   * before an oversized stream is materialised — so a malicious or accidentally
   * huge source cannot exhaust process memory. Defaults to **256 MiB**; pass
   * `Infinity` to disable (not recommended for untrusted input).
   */
  maxOutputSize?: number;
}
```

- Up to **50 source documents** per call (`MAX_MERGE_SOURCES`).
- Output is hard-capped at **256 MiB** by default (`maxOutputSize`) so a hostile
  source cannot OOM the process; raise it for legitimately large merges.
- Page resources (`/Font`, `/XObject`, …) are deep-copied into a fresh
  object-number space, so there are no collisions between sources.
- Inherited attributes (`/MediaBox`, `/CropBox`, `/Rotate`, `/Resources`) are
  resolved from each page's ancestors and folded onto the page, so pages keep
  their geometry even when the original relied on inheritance.

> Merging a signed PDF invalidates its signature (the bytes change). Pass
> `dropSignatures: true` to remove the now-meaningless signature fields.

## `splitPdf(source, ranges)`

Splits one PDF into several, one output per range.

```ts
function splitPdf(
  source: Uint8Array,
  ranges: readonly PageRange[],
  options?: MergeOptions,
): Uint8Array[];

interface PageRange {
  /** 0-based first page (inclusive). */
  start: number;
  /** 0-based last page (inclusive). Defaults to `start` (single page). */
  end?: number;
}
```

Ranges may overlap and need not be contiguous. Each output is an independent,
fully-formed PDF. `options` (including `maxOutputSize`) applies to every emitted
document.

## `extractPages(source, indices)`

Builds a new PDF from an explicit list of **0-based** page indices, in the order
given — handy for reordering or cherry-picking.

```ts
function extractPages(
  source: Uint8Array,
  indices: readonly number[],
  options?: MergeOptions,
): Uint8Array;

extractPages(pdf, [4, 0, 1]); // page 5 first, then 1, then 2
```

`options` (including `maxOutputSize` and `dropAnnotations`) is honoured here too.

## Encrypted sources

Since **v1.6.0**, `mergePdfs` / `splitPdf` / `extractPages` decrypt encrypted
sources transparently (Standard Security Handler — RC4, AES-128, AES-256). Give
the password either per-source or as a shared default:

```ts
// Per-source password (only that source is encrypted):
mergePdfs([cover, { bytes: encryptedBody, password: 'secret' }]);

// Shared password for every source, via options:
mergePdfs([a, b], { password: 'secret' });

// splitPdf / extractPages take the password on options:
splitPdf(encrypted, [{ start: 0, end: 2 }], { password: 'secret' });
```

A wrong or missing password throws `PdfPasswordError`; an unsupported handler
(e.g. public-key) throws `PdfEncryptionUnsupportedError`. The rebuilt output is
unencrypted **unless you set `encrypt`** (below). See the
[reader guide](../guides/architecture.html) for `openPdf(bytes, { password })`.

## Re-encrypting the output

Since **v1.6.0**, `MergeOptions.encrypt` re-encrypts the rebuilt document —
closing the round trip: *open encrypted → edit → re-secure*. It takes the same
shape as the document builder's `encryption` option:

```ts
import { mergePdfs, splitPdf } from 'pdfnative';

// Merge, then protect the result (AES-256):
const secured = mergePdfs([a, b], {
  encrypt: {
    ownerPassword: 'owner-secret',      // required, non-empty
    userPassword: 'user-secret',        // optional (empty = opens freely)
    algorithm: 'aes256',                // 'aes128' (V4/R4, default) | 'aes256' (V5/R6)
    permissions: { print: true, copy: false, modify: false },
  },
});

// Change a document's password: decrypt on ingest, re-encrypt on output.
const rekeyed = mergePdfs(
  [{ bytes: oldPdf, password: 'old-password' }],
  { encrypt: { ownerPassword: 'new-password', algorithm: 'aes256' } },
);

// Works identically on splitPdf / extractPages and the streaming variants.
splitPdf(src, [{ start: 0, end: 4 }], { encrypt: { ownerPassword: 'o' } });
```

Notes:

- **AES only** — new output is never RC4-encrypted (legacy RC4 is read-only).
- **CSPRNG required** — a missing Web Crypto secure random source throws
  before any copying starts (encryption keys are never derived from
  `Math.random()`).
- **Fresh keys** — no key material, permissions, or passwords from any source
  document are reused; the caller states the new protection explicitly.
- **Non-deterministic output** — random IVs/salts and a random document `/ID`
  mean encrypted output is not byte-reproducible (the unencrypted path keeps
  its content-addressed deterministic `/ID`).

## Streaming merge & split

For large documents, the streaming variants emit the result as fixed-size
chunks while holding only the cross-reference offsets and small object dicts in
memory — stream payloads flow straight from the (in-memory) source bytes, so the
fully-joined document is never materialised. Each is **byte-identical** to its
buffered counterpart (except with `encrypt`, where fresh random IVs make each
invocation structurally — not byte — identical) and composes with
[`streamToFile`](streaming.html):

```ts
import { streamMergedPdfs, streamSplitPdf, streamToFile } from 'pdfnative';

// Constant-memory merge straight to disk:
await streamToFile(streamMergedPdfs([a, b]), 'combined.pdf');

// Split: one output stream per range (drain each fully before advancing):
for await (const part of streamSplitPdf(body, [{ start: 0, end: 1 }, { start: 2, end: 9 }])) {
  await streamToFile(part.pdf, `part-${part.index}.pdf`);
}
```

`StreamMergeOptions` adds `chunkSize` (1 KiB–16 MiB, default 64 KiB) on top of
`MergeOptions`. For multi-gigabyte merges pass `maxOutputSize: Infinity` — safe
with streaming because output bytes are never buffered (the sources themselves
are still in-memory `Uint8Array`s).

For freshly *built* (not merged) documents, combine the true streaming builders
with [`streamToFile`](streaming.html) so the binary never fully materialises:

```ts
import { buildDocumentPDFStreamTrue, streamToFile } from 'pdfnative';

await streamToFile(buildDocumentPDFStreamTrue(params), 'report.pdf');
```

## Updating metadata in place

> **New in v1.7.0.** `PdfModifier.updateMetadata()` rewrites a document's
> metadata as a non-destructive incremental revision — no re-serialisation,
> existing signatures over earlier revisions stay intact.

```ts
import { openPdf, createModifier } from 'pdfnative';

const modifier = createModifier(openPdf(bytes));
modifier.updateMetadata({
  title: 'Q3 report (final)',
  author: 'Finance',
  keywords: 'quarterly, revenue',
  // modDate: new Date('2026-08-21T00:00:00Z'),  // pin for reproducible bytes
});
const updated = modifier.save();
```

Only the fields you pass change; the rest of `/Info` is preserved. `/ModDate`
is always refreshed (pass `modDate` to pin it). When the document carries an
XMP packet, it is resynchronised in the same revision — `dc:title`,
`dc:creator`, `dc:description`, `pdf:Keywords`, `xmp:ModifyDate` and
`xmp:MetadataDate` — while `xmp:CreateDate` and any `pdfaid:*` conformance
claim are preserved, so Info↔XMP parity holds for PDF/A documents.

## Safety & limits

- **Encrypted input is decrypted on ingest** (v1.6.0) when a valid password is
  supplied; a wrong/missing password throws `PdfPasswordError`. Output is
  unencrypted unless `encrypt` re-protects it (AES-128/AES-256, CSPRNG
  required, fresh keys only).
- **Annotations are filtered to URI `/Link` only** during the rebuild (plus the
  full strip when `dropAnnotations` is set), so interactive form/JS annotations
  don't leak across documents.
- **Bounded-depth copy.** The object-graph copy is capped at a fixed recursion
  depth, so a pathologically nested or adversarial source can never overflow the
  stack — it throws a descriptive error instead.
- **Bounded output size.** Cumulative output is capped at **256 MiB** by default
  (`maxOutputSize`), checked *before* each stream is materialised, so a source
  full of multi-gigabyte objects is rejected rather than allowed to exhaust
  memory. Tune or disable (`Infinity`) per call.
- **Deterministic output.** Every unencrypted result carries a
  content-addressed trailer `/ID` (ISO 32000-1 §7.5.5) derived from the
  assembled bytes, so the same inputs always produce a byte-identical PDF —
  friendly to caching, diffing, and reproducible builds. (With `encrypt`, the
  `/ID` is the encryption state's random document ID, as the file key is bound
  to it.)
- **Full rebuild, not in-place surgery.** The clean-graph approach trades a
  little speed for correctness and is safe to run on third-party PDFs.
- **Page boxes survive** _(v1.7.0)_. Declared `/TrimBox`, `/BleedBox`,
  `/ArtBox`, `/CropBox` and `/UserUnit` entries are preserved through
  `mergePdfs` / `splitPdf` / `extractPages` (they were dropped by the rebuild
  before 1.7.0) — so print-ready sources keep their geometry. See the
  [print production guide](print.html).

## How it works

[`src/parser/pdf-pagetree.ts`](https://github.com/Nizoka/pdfnative/blob/main/src/parser/pdf-pagetree.ts)
opens each source with the built-in [PDF reader](architecture.html), walks the
page tree, and deep-copies every kept page plus its transitive object graph into
a new document (`obj 1` = Catalog, `obj 2` = Pages root, `obj 3+` = the copied
graph). The copy is **memoised per reader** and **cycle-safe**, and all values
are serialised binary-safe (Latin-1) so embedded fonts and image streams survive
intact.

## See also

- [Architecture](architecture.html) — the parser/reader internals
- [Streaming output](streaming.html) — `streamToFile`
- [Outlines & page labels](outlines.html)
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/pdfa.md -->
# PDF/A conformance in pdfnative

> **PDF/A-1b, 2b, 2u and 3b via `layout: { tagged: … }`, validated against the veraPDF reference validator in CI.** Since v1.7.0, a configuration that would break the declared level surfaces a diagnostic — `console.warn` by default, a custom `onDiagnostic` sink, or a thrown error under `strict: true`.

PDF/A is the ISO archival profile for PDF (ISO 19005). pdfnative supports
PDF/A-1b, 2b, 2u, and 3b via the `tagged` build option. This guide
explains what works today, what's still in flight, and how to validate
your output against the official reference validator.

## TL;DR

```ts
import { buildPDFBytes } from 'pdfnative';

const pdf = buildPDFBytes(params, { tagged: true });        // PDF/A-2b (default)
const pdf1b = buildPDFBytes(params, { tagged: 'pdfa1b' });  // PDF/A-1b
const pdf2u = buildPDFBytes(params, { tagged: 'pdfa2u' });  // PDF/A-2u
const pdf3b = buildPDFBytes(params, { tagged: 'pdfa3b' });  // PDF/A-3b + attachments
```

> ### `tagged` alone is not enough: embed a font
>
> ISO 19005 requires **every** font in the file to be embedded. `tagged` writes the
> XMP conformance declaration, the structure tree and the output intent — but it does
> not embed a font for you. If your document uses only the viewer's built-in fonts
> (which is what happens when you pass no `fontEntries`), pdfnative writes a file that
> *claims* PDF/A while referencing non-embedded Helvetica, and veraPDF will reject it.
>
> Pass at least a Latin font whenever you set `tagged`:
>
> ```ts
> import { buildDocumentPDFBytes, registerFonts, loadFontData } from 'pdfnative';
>
> registerFonts({ latin: () => import('pdfnative/fonts/noto-sans-data.js') });
> const fontData = await loadFontData('latin');
>
> // fontRef becomes a PDF resource name, so it needs the leading slash.
> // /F1 and /F2 are reserved by the engine — start at /F3.
>
> const pdf = buildDocumentPDFBytes(
>   { title: 'Archival', blocks, fontEntries: [{ fontData, fontRef: '/F3', lang: 'latin' }] },
>   { tagged: 'pdfa2b' },
> );
> ```
>
> Since **v1.7.0** the builders guard this declaration themselves: requesting any
> `'pdfa*'` level (or `tagged: true`) with no `fontEntries` emits the
> `PDFA_NO_FONT_ENTRIES` diagnostic — a `console.warn` by default, or a thrown
> `Error` under `strict: true`, before any output bytes are produced. See
> *Conformance diagnostics* below.
>
> The sample generators in `scripts/generators/` all do this, which is why the veraPDF
> CI job passes. If you author through `pdfnative-react`, its `lintDocument()` rule
> `L_TAGGED_NO_FONTS` still catches the same trap earlier, at the document-model
> level — a complementary check to the core diagnostic.

Every output written with `tagged` set ships:

- A full structure tree (`/Document → /Table → /TR → /TH|/TD`, `/H1–H3`,
  `/P`, `/L → /LI`, `/Figure`, `/Link`).
- `/ActualText` UTF-16BE on every marked content `/Span`.
- An XMP metadata stream with `pdfaid:part` and `pdfaid:conformance`.
- An sRGB ICC `OutputIntent` (`GTS_PDFA1`).
- `/MarkInfo << /Marked true >>` on the catalog.
- A trailer `/ID` derived deterministically from the document title and
  creation timestamp.
- `/Info CreationDate` byte-equivalent to `xmp:CreateDate`, both with
  timezone offsets.

## Conformance diagnostics (v1.7.0)

Configurations that produce a PDF/A claim veraPDF would reject no longer fail
silently. Both builders (`buildPDFBytes` and `buildDocumentPDFBytes`) surface
them through a single diagnostics channel:

| Code | Trigger |
|------|---------|
| `PDFA_NO_FONT_ENTRIES` | A `'pdfa*'` level (or `tagged: true`) requested with no `fontEntries` — the file would claim PDF/A while referencing unembedded standard-14 Helvetica (ISO 19005 §6.2.11.4.1). |
| `PDFA_DEVICE_CMYK_IMAGE` | A DeviceCMYK image embedded under a PDF/A claim with an sRGB `OutputIntent` (ISO 19005-2 §6.2.4.3). |
| `PDFA_UNEMBEDDED_FORM_FONT` | AcroForm fields under a PDF/A claim — form appearances render through an unembedded base-14 `/Helv` font (same §6.2.11.4.1 rule). Flatten the form or drop the level. |

By default each diagnostic is a `console.warn`, deduplicated **once per code
per build**. Two layout options change that:

```ts
import { buildPDFBytes, type PdfDiagnostic } from 'pdfnative';

// CI / tests: escalate to a thrown Error, before any bytes are produced.
buildPDFBytes(params, { tagged: 'pdfa2b', strict: true });

// Custom sink — receives every diagnostic (no deduplication).
// Pass () => {} to silence entirely.
const diagnostics: PdfDiagnostic[] = [];
const pdf = buildPDFBytes(params, {
  tagged: 'pdfa2b',
  onDiagnostic: (d) => diagnostics.push(d),
});
```

Each `PdfDiagnostic` carries a machine-readable `code`, a `severity`
(`'warning'`), and an actionable `message` that includes the remedy.
`onDiagnostic` is ignored when `strict` is set — diagnostics throw instead.
The code list is a stable, additions-only union (`PdfDiagnosticCode`), so a
sink written today keeps compiling as future codes are added.

> **On the MCP surface** _(pdfnative-mcp 1.6.0)_, the same honesty is exposed
> as three opt-in inputs on every document tool: `embedFonts: true` embeds
> Noto Sans Latin so a PDF/A claim on base-14 text is actually accepted by
> veraPDF, `strict: true` fails instead of producing a non-conformant file,
> and `includeDiagnostics: true` echoes the engine's diagnostics
> (`PDFA_NO_FONT_ENTRIES`, `PDFA_UNEMBEDDED_FORM_FONT`,
> `PDFA_DEVICE_CMYK_IMAGE`) in the tool result. Known engine limitation:
> `add_form` (or a `formField` block) under a PDF/A claim still fails
> veraPDF even with `embedFonts` — the AcroForm `/DR /Helv` font is an
> unembedded Type1 (ISO 19005-2 §6.2.11.4.1).

## v1.1.0 status — fully validated

v1.1.0 ships full PDF/A-1b / 2b / 2u / 3b conformance against the
official veraPDF reference validator. The validator runs as a
**blocking** check on every PR (see
[.github/workflows/verapdf.yml](https://github.com/Nizoka/pdfnative/blob/main/.github/workflows/verapdf.yml)).

| Rule | Status | Fixed in |
|------|--------|----------|
| ISO 19005-1 §6.1.3 — trailer `/ID` always present | ✅ | v1.0.4 |
| veraPDF 6.7.3 t1 — `CreationDate` ↔ `xmp:CreateDate` parity | ✅ | v1.0.4 |
| veraPDF 6.7.3 t1 — `dc:title` ↔ `/Info /Title` parity | ✅ | v1.1.0 |
| veraPDF 6.7.3 t4 — `dc:description` ↔ `/Info /Subject` parity | ✅ | v1.1.0 |
| veraPDF 6.7.3 t5 — `pdf:Keywords` ↔ `/Info /Keywords` parity | ✅ | v1.1.0 |
| veraPDF 6.7.3 — `dc:creator` ↔ `/Info /Author` parity | ✅ | v1.0.4 |
| ISO 19005-1 §6.3.4 — Latin font embedding | ✅ | v1.1.0 |
| ISO 19005-2 §6.2.11.4.1 — Type0 font references | ✅ | v1.1.0 |
| veraPDF 6.2.3.3 — DeviceRGB OutputIntent | ✅ | v1.0.4 |

To produce a strictly veraPDF-compliant PDF/A document, register the Latin
font module **and resolve it**. Registering alone is not enough: the builders
are synchronous and cannot await a loader, so the font never reaches the
document and you get an unembedded Helvetica reference — verified: 0 embedded
fonts.

```ts
import { registerFonts, loadFontData, buildPDFBytes } from 'pdfnative';

registerFonts({ latin: () => import('pdfnative/fonts/noto-sans-data.js') });
const fontData = await loadFontData('latin');

const pdf = buildPDFBytes(
  { ...params, fontEntries: [{ fontData, fontRef: '/F3', lang: 'latin' }] },
  { tagged: true },
);
```

Without the `'latin'` font registered, pdfnative falls back to the
unembedded Helvetica standard-14 references for byte-stable v1.0.x
output — convenient for non-archival rendering but invalid under
PDF/A.

## Validating your output

pdfnative ships a thin wrapper around the official veraPDF CLI:

```bash
# 1. Generate the sample suite (writes test-output/)
npm run test:generate

# 2. Run veraPDF against every PDF/A-claiming sample
npm run validate:pdfa
```

The script auto-detects veraPDF on `$PATH` or via the `VERAPDF_HOME`
env var. If veraPDF is not installed it exits 0 with install
instructions — local development never blocks. CI installs veraPDF
deterministically (pinned to 1.30.2) and runs the same script on every
engine PR — see [.github/workflows/verapdf.yml](https://github.com/Nizoka/pdfnative/blob/main/.github/workflows/verapdf.yml) —
and again as a blocking gate before every npm publish.

Detection is automatic and guarded: every sample declaring
`pdfaid:part` — currently the 18 PDF/A-claiming samples — is validated
without any registration, and a **coverage canary** fails the run if the
detected count drifts from `declared.pdfaSamples` in
`docs/assets/ecosystem.json` (bump it when adding or removing a
claiming sample; a mismatch with no sample change means detection or
generation regressed).

> **Which samples are subject to PDF/A validation?** Only files that
> *declare* a conformance level in their XMP (`pdfaid:part`) — the ones
> built with `tagged: 'pdfa…'`, e.g. the `pdfa/` and `pdfa-latin/` sample
> categories. The script skips everything else. Most showcase samples
> (`bidi/`, `alphabet/`, `charts/`, …) intentionally make **no** PDF/A
> claim: they have no XMP packet at all, so force-validating one against a
> PDF/A profile in the veraPDF GUI fails by construction (missing
> `/Metadata`, uncalibrated DeviceRGB, …) — that is expected and not a
> defect.

veraPDF is invoked as an **external** Java tool. pdfnative remains a
zero-runtime-dependency library; veraPDF is never bundled, linked, or
required by consumers of the npm package.

### Installing veraPDF locally

veraPDF is a Java application. Pick whichever path matches your OS.
After install, either expose `verapdf` on `$PATH` or set the
`VERAPDF_HOME` environment variable to the install directory.

**macOS** — Homebrew cask:

```bash
brew install --cask verapdf
verapdf --version
```

**Linux** — official installer (headless):

```bash
curl -fsSL -o verapdf-installer.zip https://software.verapdf.org/rel/verapdf-installer.zip
unzip verapdf-installer.zip
java -jar verapdf-izpack-installer-*.jar -console
# follow the prompts; defaults are sane
export VERAPDF_HOME="$HOME/verapdf"
export PATH="$VERAPDF_HOME:$PATH"
```

**Windows** — official GUI installer from
<https://docs.verapdf.org/install/>, or the same headless install CI
uses (download the pinned zip, run
`java -jar verapdf-izpack-installer-*.jar auto-install.xml` — the
descriptor is shown in [CONTRIBUTING](https://github.com/Nizoka/pdfnative/blob/main/CONTRIBUTING.md)).
After install, either add the install directory to `PATH` or:

```powershell
$env:VERAPDF_HOME = "C:\Program Files\verapdf"
$env:Path += ";$env:VERAPDF_HOME"
verapdf.bat --version
```

The `.bat` launcher is fully supported by `npm run validate:pdfa`
since v1.7.0 (it is spawned through a shell, as recent Node versions
require for batch files).

**No install at all?** Drop the file into the official online demo
at <https://demo.verapdf.org>. It validates against the same engine,
which is convenient for ad-hoc checks but does not scale to a CI
suite.

### Troubleshooting

**"My PDF fails veraPDF for missing XMP / DeviceRGB / unembedded
font, but I never asked for PDF/A."**

If the file was generated **without** `tagged: true`, it is a plain
ISO 32000-1 document and should not be validated against any PDF/A
profile. The veraPDF online demo lets you pick a profile manually,
which will then surface failures by design — every PDF/A rule about
metadata, output intents, font embedding, transparency, and color
spaces will fire because the file never claimed any of those things.

The `npm run validate:pdfa` wrapper avoids this trap: it scans each
PDF for a `pdfaid:part` declaration in the XMP packet and skips
files that don't claim PDF/A. The summary line reports how many were
skipped:

```
Scanned 242 PDF(s); 18 claim PDF/A, 224 skipped (not PDF/A).
```

If you want a file to be validated, generate it with `tagged: true`
(or any `'pdfa*'` value).

**"My tagged file still fails rule 6.3.4 (font embedding)."**

Register the Latin font module **and pass the resolved data as `fontEntries`**
(see the TL;DR above). Registration on its own does nothing for the synchronous
builders. Without it, pdfnative emits Helvetica as an unembedded standard-14
reference for byte-stable v1.0.x output. With it, every glyph used
in the document is embedded as `CIDFontType2` / `FontFile2` — see
the v1.1.0 status table above. Since v1.7.0 this configuration also emits the
`PDFA_NO_FONT_ENTRIES` diagnostic at build time (a thrown error under
`strict: true`), so the failure surfaces before veraPDF ever runs.

### Output bytes change in v1.0.4

v1.0.4 has no public API break, but PDF outputs differ byte-for-byte
from v1.0.3:

- Trailer `/ID` array is now always present.
- `/Info CreationDate` and `xmp:CreateDate` carry timezone offsets.
- `dc:creator` is emitted only when an author is provided.

If your test fixtures snapshot full PDF bytes, regenerate them.

## PDF/A vs encryption

ISO 19005-1 §6.3.2 forbids combining PDF/A with PDF encryption.
pdfnative validates this at the build boundary — passing both
`tagged: …` and `encryption: …` in the same call throws.

## Choosing a flavour

| Flavour | Base PDF | Notes |
|---------|----------|-------|
| PDF/A-1b (`'pdfa1b'`) | PDF 1.4 | Most conservative — required by some legacy archival systems. No transparency, no JPEG2000, no AES. |
| PDF/A-2b (`true` / `'pdfa2b'`) | PDF 1.7 | Default. Allows transparency, layers, embedded TrueType. |
| PDF/A-2u (`'pdfa2u'`) | PDF 1.7 | 2b + Unicode mapping for every glyph. Required when `/ActualText` and ToUnicode CMap completeness matter (recommended for accessibility). |
| PDF/A-3b (`'pdfa3b'`) | PDF 1.7 | 2b + arbitrary `/EmbeddedFile` attachments (XML, source data, etc.). |

All four flavours share the same XMP / OutputIntent / structure-tree
infrastructure — pdfnative only varies the PDF version, the
`pdfaid:part`, and the `pdfaid:conformance` value.

### Canonical list for tooling

The four legal `tagged` strings are also exposed as a
typed constant for tooling that needs to populate a JSON-schema
`enum:` (`pdfnative-mcp` does this for its MCP tool descriptions so
Gemini-CLI and other agents can autocomplete the right value):

```ts
import { PDF_A_CONFORMANCE_TARGETS, type PdfAConformanceTarget } from 'pdfnative';

PDF_A_CONFORMANCE_TARGETS;
// → readonly ['pdfa1b', 'pdfa2b', 'pdfa2u', 'pdfa3b']

function isValidTarget(s: string): s is PdfAConformanceTarget {
  return (PDF_A_CONFORMANCE_TARGETS as readonly string[]).includes(s);
}
```

The constant is the single source of truth — adding a new target in a
future minor release will surface automatically in every downstream
consumer that imports it.

## Hard invariants for contributors

These rules are documented in the contributor instruction file
[.github/instructions/pdfa-conformance.instructions.md](https://github.com/Nizoka/pdfnative/blob/main/.github/instructions/pdfa-conformance.instructions.md):

- `/Info CreationDate` and `xmp:CreateDate` come from the **same**
  `buildPdfMetadata()` call. Never inline `new Date()` in the builders.
- The unencrypted trailer `/ID` is derived deterministically from
  `MD5(title + creationDate + objectCount)`. Never randomize — it
  breaks `buildPDFBytes(params)` byte-equality tests.
- `dc:creator` is emitted only when an author is provided and is
  XML-escaped.
- XMP metadata streams are never compressed.
- Compression always happens **before** encryption (ISO 32000-1
  §7.3.8).

## See also

- [CHANGELOG.md](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)
  — full v1.0.4 release notes.
- [veraPDF](https://verapdf.org) — the official reference validator.
- [ISO 19005-1](https://www.iso.org/standard/38920.html) /
  [ISO 19005-2](https://www.iso.org/standard/50655.html) /
  [ISO 19005-3](https://www.iso.org/standard/57229.html).

---
<!-- source: docs/guides/print.md -->
# Print production — bleed, trim & printer's marks

> **New in v1.7.0.** Print-ready PDFs with zero dependencies: page geometry boxes (`/TrimBox`, `/BleedBox`, `/ArtBox`, `/CropBox`), crop and registration marks drawn as pure vector operators, `/Trapped` metadata with XMP parity, print-dialog defaults (duplex, tray, page range, copies), a caller-supplied OutputIntent ICC profile, and large-format `/UserUnit`. Everything is opt-in — output is byte-identical when unused.

## TL;DR

```ts
import { buildDocumentPDFBytes, PAGE_SIZES } from 'pdfnative';

const BLEED = 8.5; // 3 mm in points

const pdf = buildDocumentPDFBytes(params, {
  // Design the page at trim size + bleed on every side…
  pageWidth:  PAGE_SIZES.A4.width  + 2 * BLEED,
  pageHeight: PAGE_SIZES.A4.height + 2 * BLEED,
  margins: { t: 36 + BLEED, r: 36 + BLEED, b: 36 + BLEED, l: 36 + BLEED },
  // …declare the geometry and draw the marks:
  print: { bleed: BLEED, marks: true },
  viewerPreferences: { duplex: 'duplexFlipLongEdge', pickTrayByPDFSize: true },
});
```

Open the result in Acrobat with *Preferences → Page Display → Show art, trim & bleed boxes* to see the geometry.

## The box model (ISO 32000-1 §14.11.2)

```
┌─────────────────────────────┐  MediaBox — the physical page (sheet)
│  ┌───────────────────────┐  │  BleedBox — content clipped in production
│  │ ┌───────────────────┐ │  │  TrimBox — the finished page after cutting
│  │ │      ArtBox       │ │  │  ArtBox — meaningful-content extent
│  │ └───────────────────┘ │  │
│  │  backgrounds run here │  │  ← bleed zone: extend backgrounds into it
│  └───────────────────────┘  │
└─────────────────────────────┘
```

| Option | PDF key | Meaning |
|---|---|---|
| `print.bleed` | derives both | Shorthand: `TrimBox` = MediaBox inset by the bleed, `BleedBox` = MediaBox |
| `print.trimBox` | `/TrimBox` | Finished page size after cutting |
| `print.bleedBox` | `/BleedBox` | Clipping extent in production |
| `print.artBox` | `/ArtBox` | Meaningful-content extent |
| `print.cropBox` | `/CropBox` | Region viewers display/print |

Boxes are validated (within the MediaBox, trim within bleed) and are pure page-dictionary metadata — the layout engine is untouched, so design the page at *trim + 2×bleed* and enlarge the margins by the bleed, letting backgrounds run to the page edge.

`mergePdfs` / `splitPdf` / `extractPages` preserve all four boxes (and `/UserUnit`).

## Printer's marks (§14.11.3)

`print.marks: true` draws, on every page, strictly **outside** the TrimBox:

- **Crop marks** — 8 corner hairlines (default 0.25 pt, 14 pt long, 5 pt clear of the trim edge) showing where to cut.
- **Registration targets** — circle-and-cross targets on the four edge midpoints, used to align separations.

Fine-tune with an object: `marks: { crop, registration, length, offset, weight }`.

> Marks are stroked in RGB black. A true all-separation *registration colour* requires CMYK content support, which is on the roadmap together with PDF/X — see below.

## /Trapped and prepress metadata

```ts
buildDocumentPDFBytes({ ...params, metadata: { trapped: 'False' } }, { tagged: 'pdfa2b' });
```

Writes `/Info /Trapped /False` and mirrors it as `pdf:Trapped` in the XMP packet, telling the RIP whether trapping has been applied. Because `pdf:Trapped` is not part of the XMP-2005 Adobe PDF schema that PDF/A pins, pdfnative also emits the required PDF/A extension schema declaring the property (ISO 19005 §6.6.2.3.2) — the document stays veraPDF-compliant. Per ISO 32000-1 Table 317, `trapped: 'Unknown'` is written to `/Info` only: unknown maps to the *absence* of `pdf:Trapped` in XMP.

## Print-dialog defaults (`viewerPreferences`)

| Option | PDF key | Values |
|---|---|---|
| `duplex` | `/Duplex` | `'simplex'`, `'duplexFlipShortEdge'`, `'duplexFlipLongEdge'` |
| `pickTrayByPDFSize` | `/PickTrayByPDFSize` | boolean (Windows viewers) |
| `printPageRange` | `/PrintPageRange` | 1-based `[first, last]` pairs, e.g. `[[1, 4], [7, 7]]` |
| `numCopies` | `/NumCopies` | positive integer |

These join the existing v1.4.0 viewer preferences and remain PDF/A-safe metadata.

## Custom OutputIntent (tagged/PDF-A)

Replace the built-in minimal sRGB profile with a real ICC profile:

```ts
import { readFileSync } from 'node:fs';

buildDocumentPDFBytes(params, {
  tagged: 'pdfa2b',
  outputIntent: {
    iccProfile: new Uint8Array(readFileSync('sRGB-IEC61966-2.1.icc')),
    outputConditionIdentifier: 'sRGB IEC61966-2.1',
    outputCondition: 'sRGB display',
    info: 'IEC 61966-2.1 reference profile',
  },
});
```

RGB profiles only — pdfnative emits RGB content, and a mismatched intent fails PDF/A validation (a CMYK profile throws with an actionable message). Omitted, the historical built-in profile is used byte-identically.

## Large formats — `/UserUnit`

PDF user space caps pages at 14 400 units (200 in). For banners and plans, `print.userUnit` scales the unit (1 unit = `userUnit`/72 inch, up to 75 000):

```ts
// A 5 m × 1 m banner: 1417 × 283 units at 10/72 inch per unit.
buildDocumentPDFBytes(params, { pageWidth: 1417, pageHeight: 283, print: { userUnit: 10 } });
```

`/UserUnit` needs PDF 1.6+, so the header is raised to `%PDF-1.7` when the option is set — and it is rejected under `tagged: 'pdfa1b'` (PDF/A-1 is PDF 1.4; use `pdfa2b` or later).

## Limits & scope (v1.7.0)

- Marks are RGB black; **no CMYK content**, spot colours, colour bars or **PDF/X** conformance claims yet — all on the roadmap as one coherent CMYK workstream.
- One geometry per document (pages share the same boxes), matching the single-page-size layout model.
- The OutputIntent (custom or built-in) is emitted under `tagged` modes only.

See the [print samples](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/print-showcase.ts): `print/print-bleed-marks.pdf`, `print/print-explicit-boxes.pdf`, `print/print-large-format.pdf`.

---
<!-- source: docs/guides/quickstart.md -->
# Quick Start

> **One install, one function.** `npm install pdfnative`, then `buildDocumentPDFBytes({ title, blocks })` returns a `Uint8Array` — synchronously, in Node, browsers, Deno and Bun. No config, no build step, no service.

Generate your first PDF in under a minute.

## Install

```bash
npm install pdfnative
```

> **Requirements:** Node.js ≥ 22 · modern browsers · Deno · Bun.
> Zero runtime dependencies are installed.

## Node.js

```typescript
import { writeFileSync } from 'node:fs';
import { buildDocumentPDFBytes } from 'pdfnative';

const pdf = buildDocumentPDFBytes({
  title: 'Hello',
  blocks: [
    { type: 'heading',   text: 'Hello, pdfnative', level: 1 },
    { type: 'paragraph', text: 'Pure native PDF — zero dependencies, ISO 32000-1.' },
  ],
});

writeFileSync('hello.pdf', pdf);
```

For optimal compression on Node.js, enable native zlib once at startup:

```typescript
import { initNodeCompression, buildDocumentPDFBytes } from 'pdfnative';

await initNodeCompression();

const pdf = buildDocumentPDFBytes(params, { compress: true });
```

## Browser

```html
<script type="module">
  import { buildDocumentPDFBytes, downloadBlob } from 'https://esm.sh/pdfnative@1.7.0';

  document.getElementById('go').addEventListener('click', () => {
    const pdf = buildDocumentPDFBytes({
      title: 'Hello',
      blocks: [
        { type: 'heading', text: 'Hello from the browser', level: 1 },
      ],
    });
    downloadBlob(pdf, 'hello.pdf');
  });
</script>
```

A stored-block compression fallback works automatically — no native zlib needed in the browser.

## Tabular reports — `buildPDFBytes`

For bank statements, invoices, and any single-table report:

```typescript
import { buildPDFBytes } from 'pdfnative';

const pdf = buildPDFBytes({
  title: 'Monthly Report',
  infoItems: [
    { label: 'Period',  value: 'January 2026' },
    { label: 'Account', value: 'Main' },
  ],
  balanceText: 'Balance: $1,234.56',
  countText: '42 transactions',
  headers: ['Date', 'Description', 'Amount'],
  rows: [
    { cells: ['01/15', 'Grocery', '-$45.00'],   type: 'debit',  pointed: false },
    { cells: ['01/16', 'Salary',  '+$3,000.00'], type: 'credit', pointed: true  },
  ],
  footerText: 'Generated by MyApp',
});
```

## Free-form documents — `buildDocumentPDFBytes`

For mixed content (manuals, articles, multi-section reports):

```typescript
const pdf = buildDocumentPDFBytes({
  title: 'Project Report',
  blocks: [
    { type: 'toc' },
    { type: 'heading',   text: 'Executive Summary', level: 1 },
    { type: 'paragraph', text: 'This quarter saw strong growth.' },
    { type: 'list', style: 'bullet', items: ['Revenue +15%', 'Costs −8%'] },
    { type: 'image', data: chartBytes, width: 400, alt: 'Revenue chart' },
    { type: 'barcode', format: 'qr', data: 'https://example.com', width: 80 },
    { type: 'pageBreak' },
    { type: 'heading',   text: 'Details', level: 1 },
    { type: 'table', headers: ['Q', 'Revenue'], rows: [
      { cells: ['Q1', '$1.2M'], type: '', pointed: false },
      { cells: ['Q2', '$1.4M'], type: '', pointed: false },
    ] },
  ],
  footerText: 'Confidential',
});
```

13 block types are available: `heading`, `paragraph`, `list`, `table`, `image`, `link`, `spacer`, `pageBreak`, `toc`, `barcode`, `svg`, `formField`, `chart`.

## Multi-language

```typescript
import { registerFonts, loadFontData, buildDocumentPDFBytes } from 'pdfnative';

registerFonts({
  th: () => import('pdfnative/fonts/noto-thai-data.js'),
  ar: () => import('pdfnative/fonts/noto-arabic-data.js'),
});

const fontEntries = await Promise.all([
  loadFontData('th').then(fd => ({ fontData: fd!, fontRef: '/F3', lang: 'th' })),
  loadFontData('ar').then(fd => ({ fontData: fd!, fontRef: '/F4', lang: 'ar' })),
]);

const pdf = buildDocumentPDFBytes({
  blocks: [{ type: 'paragraph', text: 'สวัสดี — مرحبا' }],
  fontEntries,
});
```

Note that `lang` is a property of each **font entry**, not of a block: pdfnative detects the script per character and routes to the matching font, so a single paragraph can mix Thai, Arabic and Latin. BiDi resolution and OpenType shaping follow from that routing. See the [FAQ → Fonts and Unicode](faq.html#fonts-and-unicode) for the full list of codes.

## Web Worker

`createPDF` is the recommended entry point — it decides between the main thread and a worker for you:

```typescript
import { createPDF } from 'pdfnative';

const pdf = await createPDF(params, {
  workerUrl: new URL('./pdf-worker.js', import.meta.url), // your worker script
  threshold: 500,   // rows above this go to the worker (default WORKER_THRESHOLD = 500)
  onProgress: (p) => console.log(`${p}%`),
});
```

At or below the `threshold` (or when `Worker` / `workerUrl` is unavailable) the PDF is generated on the main thread; above it, the worker at `workerUrl` is spawned, with an automatic main-thread fallback if the worker fails.

To drive a worker directly, use `generatePDFInWorker(workerUrl, params, { timeout, onProgress })` — note the worker URL is the **first** argument, and the options are `timeout` (ms, default 60 000) and `onProgress` (there is no threshold at this level).

## Streaming

```typescript
import { buildDocumentPDFStream, concatChunks } from 'pdfnative';

// buildDocumentPDFStream(params, layoutOptions?, streamOptions?)
// chunkSize lives in the 3rd argument (StreamOptions)
const chunks: Uint8Array[] = [];

for await (const chunk of buildDocumentPDFStream(
  params,
  {},                        // layoutOptions
  { chunkSize: 65536 },      // streamOptions
)) {
  chunks.push(chunk);
}

const pdf = concatChunks(chunks);
```

The async iterable yields `Uint8Array` chunks as the PDF is produced — no full-document buffering. The three-argument API (`params`, `layoutOptions`, `streamOptions`) keeps layout concerns (tagged, compress, watermark) and streaming concerns (chunk size) separate.

## Playgrounds

The interactive playgrounds on [pdfnative.dev](https://pdfnative.dev) run entirely in the browser:

- [Extreme scripts](../playgrounds/extreme-scripts.html) — live BiDi, Tamil, Bengali + Devanagari, Arabic harakat
- [Scale](../playgrounds/scale.html) — 1,000 to 100,000 pages, Web Worker + true streaming

> **Local testing:** opening the playgrounds as `file://` disables the Web Worker
> (browsers block cross-origin Worker imports from `file:` origins).
> Serve the docs directory instead:
> ```bash
> npm run docs:serve   # → http://localhost:5000
> ```

## Command line — pdfnative-cli

Prefer the terminal? [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) wraps the same library with 21 commands — including `render`, `fill`, `sign`, `verify`, `ltv`, `encrypt`, `decrypt`, `merge`, `split`, `extract`, `extract-text` and `compare`:

```bash
# Install once
npm install --global pdfnative-cli

# Render a JSON document to a PDF
pdfnative render --input report.json --output report.pdf

# Sign with an RSA key (loaded from env var, never logged)
export PDFNATIVE_SIGN_KEY="$(cat private.pem)"
export PDFNATIVE_SIGN_CERT="$(cat cert.pem)"
pdfnative sign --input report.pdf --output report.signed.pdf

# Inspect any PDF (encryption, signatures, PDF/A, metadata)
pdfnative inspect --input report.signed.pdf --format text
```

Stdin/stdout makes it composable in shell pipelines:

```bash
cat report.json | pdfnative render | pdfnative sign | pdfnative inspect --format text
```

See the dedicated [CLI guide](cli.html) for the full command reference, security model, and CI/CD recipes.

## Next steps

- [Architecture](architecture.html) — modules, builders, generation pipeline.
- [CLI](cli.html) — pdfnative-cli command-line interface.
- [Accessibility](accessibility.html) — tagged PDF, PDF/UA, PDF/A.
- [FAQ](faq.html) — fonts, encryption, signatures, comparisons.
- [Troubleshooting](troubleshooting.html) — common pitfalls and fixes.
- [Sample generators](https://github.com/Nizoka/pdfnative/tree/main/scripts/generators) — 242 PDFs across 37 categories (48 generators).

---
<!-- source: docs/guides/react.md -->
# pdfnative-react — Declarative JSX Renderer Guide

> **Tracks the latest published `pdfnative-react`** (v1.2.0, built on pdfnative 1.7.0), with **React 19** and `pdfnative` ^1.7.0 as peer dependencies. Live package versions — and the `pdfnative` version each one is built on — are shown at the top of the [documentation home](../index.html). Full history: [pdfnative-react releases](https://github.com/Nizoka/pdfnative-react/releases).

[`pdfnative-react`](https://github.com/Nizoka/pdfnative-react) turns declarative **JSX** into real, on-device PDFs powered by the zero-dependency [`pdfnative`](https://github.com/Nizoka/pdfnative) engine — no DOM, no headless browser, no SaaS round-trips. Your documents never leave the process.

> **Why a React renderer?** Front-end teams already think in components. `pdfnative-react` lets you author a PDF the same way you author a UI — with familiar `@react-pdf/renderer`-style ergonomics (`Document`, `Page`, `Text`, `usePdf`, `PDFViewer`) — while the actual bytes are produced locally by pdfnative. It is the **frontend gateway** to the pdfnative ecosystem.

```tsx
import { Document, Heading, Text, Table, renderToBytes } from 'pdfnative-react';

const bytes = renderToBytes(
  <Document title="Invoice #1024" footerText="Acme Inc">
    <Heading level={1}>Invoice #1024</Heading>
    <Text>Thank you for your business.</Text>
    <Table
      headers={['Item', 'Qty', 'Total']}
      rows={[{ cells: ['Pro plan', '1', '$49.00'], type: 'default', pointed: false }]}
      zebra
    />
  </Document>,
); // → Uint8Array, a valid PDF (%PDF-… …%%EOF)
```

---

## How it works

A custom **React reconciler** compiles your component tree — synchronously, with no DOM — into the `pdfnative` `DocumentParams` model, which the engine then renders to bytes. There is **no CSS/flexbox engine** and no `<View>`: it is an honest, declarative **block flow** where every component maps 1:1 onto a pdfnative block.

```
[your JSX tree]
      │ custom react-reconciler (synchronous, no DOM)
┌──────────────────────────┐
│   pdfnative-react (npm)  │  ← components compile to pdfnative blocks
└──────────────────────────┘
      │ import { buildDocumentPDFBytes, … } from 'pdfnative'
┌──────────────────────────┐
│      pdfnative (npm)     │  ← zero-dependency PDF engine
└──────────────────────────┘
```

> **Zero-dependency invariant preserved.** React 19 is a **peer dependency of `pdfnative-react` only**. The core `pdfnative` library remains zero-dependency — adding the React renderer to your app never adds a dependency to the engine itself.

---

## Installation

```bash
npm install pdfnative-react pdfnative react
```

**Requirements:** **React 19** and **pdfnative ^1.7.0** (both peer dependencies) · **Node.js ≥ 22**. The package adds one runtime dependency of its own, `react-reconciler`. Works in Node, browsers and SSR frameworks.

> **Next.js and other React Server Component setups.** The root barrel is deliberately *not* marked `'use client'`, and importing it from a Server Component or a `'use server'` file **fails** — the reconciler needs `createContext`, which is unavailable under React's `react-server` condition. Render from a **Route Handler** instead (see [Server rendering](#server-rendering) below). The hooks and viewer components carry the directive and are published separately at `pdfnative-react/client`; import them from there in an app that mixes server and client components, because the directive does not survive bundling in the root barrel.

The package ships **NPM provenance** — verify the published artifact with `npm audit signatures` or on [npmjs.com](https://www.npmjs.com/package/pdfnative-react).

---

## When to use the React renderer

| Use **pdfnative-react** when… | Use the **library** / **CLI** when… |
|---|---|
| You already build UIs in React and want PDFs the same way | You write a non-React Node service → use `pdfnative` directly |
| You want a live `<iframe>` preview in the browser (`usePdf` / `PDFViewer`) | You operate from shell scripts or CI → use [`pdfnative-cli`](cli.html) |
| You are migrating from `@react-pdf/renderer` | You drive PDFs from an AI assistant → use [`pdfnative-mcp`](mcp.html) |
| You want AI agents to author with the token-frugal `DocSpec` | You need Web Worker offloading or 100 % programmatic control |

The packages are **complementary** and all sit on the same engine, so a PDF authored in any of them is byte-compatible with the others.

---

## Components

Every component maps 1:1 onto a pdfnative block (`Section` being the one intentional composite).

| Component | Renders |
|---|---|
| `Document` | The required root (`title`, `footerText`, `metadata`, `fontEntries`, `layout`, and — v1.2.0 — `print`). |
| `Page` | An explicit page boundary (content auto-paginates otherwise). |
| `Heading` | A section heading (`level` 1–3); feeds the auto `TableOfContents`. |
| `Paragraph` / `Text` | A wrapping paragraph (`fontSize`, `lineHeight`, `align`, `indent`, `color`). |
| `List` / `Item` | A bullet or numbered (`ordered`) list. |
| `Table` / `Row` / `Cell` | A data table (data-driven `headers`/`rows`, or JSX `<Row>`/`<Cell>`). |
| `Image` | An embedded JPEG/PNG (`data: Uint8Array`). |
| `Link` | A clickable hyperlink (`url`/`href`). |
| `Spacer` | Vertical whitespace (`height`). |
| `PageBreak` | A hard page break. |
| `TableOfContents` / `Toc` | An auto-generated TOC built from headings. |
| `Barcode` | QR, Code 128, EAN-13, PDF417, Data Matrix (`format`, `data`). |
| `Svg` | Inline vector graphics (path data or markup). |
| `FormField` | Interactive AcroForm widgets (`fieldType`, `name`). |
| `Chart` | A native vector chart (`chartType`, `series`, `categories`, `altText`, …) — see [Charts](#charts). |
| `Section` | *Composite* (the one exception to the 1:1 mapping): expands to an optional `PageBreak` + a `Heading` + its children before the reconciler runs. Props: `title`, `level` (default `2`), `color`, `break`. |

---

## Server rendering

`renderToResponse` returns a web-standard `Response`, so the same call works in a
Next.js Route Handler, a Remix loader, Deno, Bun, Cloudflare Workers and any
other runtime with the Fetch API. This is the supported way to render from a
server framework.

```tsx
// app/invoice/route.tsx — Next.js Route Handler
import { renderToResponse } from 'pdfnative-react';

export async function GET() {
  return renderToResponse(<Invoice />, {
    fileName: 'invoice.pdf',
  });
}
```

`renderSpecToResponse` does the same from a `DocSpec` object rather than JSX,
which is the shape an AI agent is most likely to produce.

## Charts

`<Chart>` compiles to the engine's native `chart` block — vector path operators,
no rasterisation, and `/Figure` tagging with alt text.

```tsx
<Chart
  chartType="bar"            // bar | barH | line | pie | donut | stackedBar | stackedBarH | area | scatter
  title="Quarterly revenue"
  categories={['Q1', 'Q2', 'Q3', 'Q4']}
  series={[{ label: 'Revenue', values: [50, 62, 70, 81] }]}
  altText="Bar chart of quarterly revenue, rising each quarter"
/>
```

**Charts v2 (v1.2.0)** widens the surface to the engine's nine chart types and
adds five props: `axis2` (a secondary Y axis — put a series on it with
`yAxis: 'right'`), `xAxis` (`category` | `linear` | `time` positional axes; a
log scale is available on the *value* axes via `axis` / `axis2`
`scale: 'log'`), `dataLabels`, `labelStride` and `labelRotation`. The
exported `ChartPropsCoversChartBlock` compile-time lock guarantees `<Chart>`
covers every engine `ChartBlock` field — which is exactly why the `pdfnative`
peer floor is `^1.7.0`: a 1.6 engine would throw mid-render on the v2 fields.

## Print production &amp; conformance diagnostics _(v1.2.0)_

`<Document print={…}>` is document-level sugar over `layout.print` — the typed
`PrintOptions` covers `bleed` (a shorthand that derives `TrimBox` and
`BleedBox`), explicit `trimBox` / `bleedBox` / `artBox` / `cropBox` page boxes,
vector printer's marks, and `/UserUnit`. The companion types ship from the root
barrel: `PrintOptions`, `PrinterMarksOptions`, `PageBox`, `CustomOutputIntent`,
and `PdfColors`. Viewer preferences (`duplex`, `pickTrayByPDFSize`,
`printPageRange`, `numCopies`) and a custom RGB ICC `outputIntent` pass through
`layout` untouched.

```tsx
const bytes = renderToBytes(
  <Document title="Poster" print={{ bleed: 8.5, marks: { crop: true } }}>
    <Heading level={1}>Print-ready</Heading>
  </Document>,
);
```

The engine's conformance channel is exposed the same way: `layout.strict`
escalates PDF/A diagnostics (`PdfDiagnosticCode` — e.g.
`PDFA_UNEMBEDDED_FORM_FONT`) into a hard failure before any bytes are produced,
while `layout.onDiagnostic` (a `PdfDiagnosticHandler` receiving each
`PdfDiagnostic`) lets you collect them without failing. In a DocSpec only
`strict: true` is expressible — `onDiagnostic` is function-valued and therefore
not JSON-representable.

## Linting

`lintDocument` runs 25 deterministic rules over a compiled tree — no I/O, so it
is safe in a test or a CI step. It catches the classes of mistake a type system
cannot, including `L_TAGGED_NO_FONTS`: declaring PDF/A without embedding a font,
which produces a file that claims conformance it does not have. Thirteen of the
rules pre-empt an engine throw with a named, actionable finding.

v1.2.0 adds seven rules for the new surface: `L_CHART_LOG_SCALE`,
`L_CHART_X_AXIS` and `L_CHART_LABELS` (charts v2 misconfigurations),
`L_PRINT_BOXES` (print geometry — it delegates to the engine's
`validatePrintOptions` and reports its message verbatim, so the rule can never
drift from what the engine enforces), `L_VIEWER_PRINT_RANGE`,
`L_OUTPUT_INTENT_IGNORED` (warning: an `outputIntent` without `tagged` is a
silent no-op), and `L_TAGGED_FORM_FONTS` (warning: PDF/A plus form fields needs
embedded form fonts).

```ts
import { lintDocument, LINT_RULES } from 'pdfnative-react';

const report = lintDocument(<Invoice />);
if (!report.ok) {
  const first = report.findings.find((f) => f.severity === 'error');
  throw new Error(first?.message ?? 'lint failed');
}
```

## Agent surface

`capabilityManifest()` and `doctor()` return plain JSON describing what the
package can do and whether the environment supports it — the discovery pair an
autonomous agent should call before planning work. `validateSpec`, `schema(subject?)`
and `SCHEMA_SUBJECTS` cover DocSpec validation; `aiGovernancePolicy()`,
`agentRulesText()` and `validateIssueDraft()` expose the human-in-the-loop contract.

## Rendering

```ts
import {
  renderToBytes,   // (node, options?) => Uint8Array
  renderToBlob,    // (node, options?) => Blob (application/pdf)
  renderToStream,  // (node, options?) => AsyncGenerator<Uint8Array>
  renderToFile,    // (node, path, options?) => Promise<void> (Node only)
  renderToResponse,// (node, options?) => Promise<Response> (web standard)
  renderToFileStream, // (node, path, options?) => Promise<StreamToFileResult> — { bytesWritten, path } (Node only)
  inspectDocument, // (node) => layout diagnostics, no render
  compileDocument, // (node) => DocumentParams (inspect the model, no render)
} from 'pdfnative-react';
```

`options` is `{ layout?: Partial<PdfLayoutOptions>; fontEntries?: FontEntry[]; fonts?: FontsMap }` and merges on top of anything set on `<Document>` — page size, margins, colors, PDF/A mode, encryption, and non-Latin fonts. Note that `fonts` is only honored by the **async** entry points (`renderToFile`, `renderToFileStream`, `renderToResponse`, `usePdf`, `usePdfStream`) — font loading is asynchronous, so the synchronous entries (`renderToBytes`, `renderToBlob`, `renderToStream`) ignore it; resolve manually first (`fontEntries: await resolveFonts(fonts)`).

> ### `resolveFonts` fixed in v1.2.0 — re-render affected documents
>
> Before v1.2.0, `resolveFonts` (and the `fonts` option, which calls it) set each
> entry's `fontRef` to the bare language code instead of a slash-prefixed PDF
> name, yielding invalid syntax like `latin 12 Tf` — Acrobat refuses such a file
> ("an error occurred while reading this document (14)") and Chrome draws raw
> glyph indices. **v1.2.0 fixes this**: `resolveFonts` now prefixes the slash,
> emitting valid PDF names like `/latin` and `/th`. If you shipped PDFs through
> `resolveFonts` or the `fonts` option under v1.1.0, re-render them. Hand-built
> `fontEntries` using a correct `/F3`-style ref were never affected (`/F1` and
> `/F2` remain reserved by the engine).
>
> When building entries by hand, keep failing loudly — `loadFontData` resolves to
> `null` (it does not throw) when a code has no registered loader:
>
> ```ts
> import { registerFonts, loadFontData } from 'pdfnative';
>
> registerFonts({ latin: () => import('pdfnative/fonts/noto-sans-data.js') });
> const fontData = await loadFontData('latin');
> if (!fontData) throw new Error('font failed to load — did you call registerFonts first?');
> const bytes = renderToBytes(<Doc />, { fontEntries: [{ fontData, fontRef: '/F3', lang: 'latin' }] });
> ```
>
> Rendering is synchronous, so registering without awaiting `loadFontData` embeds
> nothing at all and every non-Latin glyph comes out blank.

Two `renderToResponse` / `renderSpecToResponse` options arrived in v1.2.0 for
HTTP caching: `cacheControl` (a verbatim `Cache-Control` header) and `etag` — a
verbatim string, or `true` to derive a strong validator from the rendered bytes
(which implies buffering the response instead of streaming it). v1.2.0 also
validates streamability **before** the first byte: a document that cannot
stream (a TOC, `{pages}` placeholders) now fails up-front instead of mid-response
with the headers already sent.

```ts
const bytes = renderToBytes(<Invoice />, {
  layout: { tagged: 'pdfa2b', compress: true },
});
```

---

## Hooks & client components

The published root bundle does **not** carry `'use client'` (a directive in an internal module does not survive single-file bundling); import hooks and viewer components from `pdfnative-react/client` in a React Server Components app, or add the directive to your own file as below.

```tsx
'use client';
import { usePdf } from 'pdfnative-react';

function Preview({ doc }: { doc: React.ReactElement }) {
  const { url, loading } = usePdf(doc);
  return loading ? <p>Rendering…</p> : <iframe title="preview" src={url} />;
}
```

- `usePdf(element, options?)` → `{ url, blob, bytes, loading, error, update }`
- `usePdfStream(element, options?)` → `{ getStream() }`
- `PDFViewer` — live `<iframe>` preview.
- `PDFDownloadLink` — one-click download (supports a render-prop child).
- `BlobProvider` — render-prop access to the raw `Blob`.

> Try it live in the [React playground](../playgrounds/react.html) — edit JSX or a `DocSpec` and see the PDF render in your browser.

---

## Agent authoring — the token-frugal `DocSpec`

`pdfnative-react` is a *library*, so the place LLM agents spend tokens is **authoring** documents. The compact `DocSpec` expresses the same document as terse, JSON-serializable tuples — and compiles to the **exact same** PDF as the JSX, because it is built on the very same components.

```ts
import { renderSpecToBytes, type DocSpec } from 'pdfnative-react';

const spec: DocSpec = {
  title: 'Invoice #1024',
  footerText: 'Acme Inc',
  blocks: [
    ['h1', 'Invoice #1024'],
    ['p', 'Thank you for your business.', { align: 'right' }],
    ['table', { h: ['Item', 'Total'], r: [['Pro plan', '$49.00']], zebra: true }],
    ['qr', 'https://acme.example/pay/1024', { align: 'right' }],
  ],
};

const bytes = renderSpecToBytes(spec);
```

The equivalent JSX is several times more tokens for a typical document, because every block carries opening/closing tags and prop names. Same bytes out, far fewer tokens in.

- `compileSpec(spec)` → `DocumentParams` · `specToElement(spec)` → `<Document>` element
- `renderSpecToBytes` / `renderSpecToBlob` / `renderSpecToStream` / `renderSpecToFile`
- `docSpecSchema()` → a Draft 2020-12 JSON Schema whose `$id` embeds the package version, so agents can self-validate a spec before rendering; `docSpecSchemaId()` returns the `$id`.

**Block tuples:** `['h1'|'h2'|'h3', text, opts?]`, `['p', text, opts?]`, `['ul'|'ol', items, opts?]`, `['table', { h?, r }]`, `['img', { data }]`, `['link', text, { url }]`, `['sp', height?]`, `['br']`, `['page', blocks]`, `['toc', opts?]`, `['qr'|'code128'|'ean13'|'pdf417'|'datamatrix', data, opts?]`, `['svg', data, opts?]`, `['chart', { chartType, series, … }]`, `['field', { fieldType, name, … }]`.

Since v1.2.0 a spec can also carry a top-level `print` field (the same
`PrintOptions` shape as `<Document print>`), and the generated JSON Schema
covers every charts-v2 field — so an agent can self-validate a print-ready,
dual-axis document before rendering it.

---

## Fonts & environment

Re-exported from the engine: `registerFonts`, `registerFont`, `loadFontData`, `validateFontData`, `downloadBlob` (browser), `initNodeCompression` (Node), and — v1.2.0 — `setDeflateImpl`, which plugs a **synchronous** deflate implementation into the engine for compressed client-side rendering (the function's output is written verbatim, so it must produce a zlib-wrapped RFC 1950 stream — e.g. fflate's `zlibSync`; the async browser `CompressionStream` cannot be plugged in). (`loadFontData` is a pure dynamic import — it works in the browser too.) Pass non-Latin fonts via the `fontEntries` render option (or on `<Document fontEntries={…}>`), unlocking all 22 bundled Unicode scripts and COLRv1 colour emoji exactly as in the core library.

```tsx
import { Document, Text, renderToBytes, registerFont, loadFontData } from 'pdfnative-react';

registerFont('th', () => import('pdfnative/fonts/noto-thai-data.js'));
const th = await loadFontData('th');
if (!th) throw new Error('Thai font failed to load');
const bytes = renderToBytes(
  <Document
    title="สวัสดี"
    fontEntries={[{ fontData: th, fontRef: '/F3', lang: 'th' }]} // /F1 and /F2 are reserved
  >
    <Text>สวัสดีชาวโลก</Text>
  </Document>,
);
```

---

## Migrating from `@react-pdf/renderer`

| `@react-pdf/renderer` | pdfnative-react |
|---|---|
| `<Document>` / `<Page>` | `<Document>` / `<Page>` |
| `<Text>` | `<Text>` (alias of `<Paragraph>`) |
| `<View>` + flexbox styles | *(none — declarative block flow; use blocks + `<Spacer>`)* |
| `StyleSheet` | per-component props (`align`, `color`, `fontSize`, …) |
| `<PDFViewer>` / `<PDFDownloadLink>` / `<BlobProvider>` | same names, same shape |
| <!-- verify-docs:allow api-exists (left column names the @react-pdf/renderer API being migrated from) --> `usePDF()` | `usePdf()` |

The biggest mental shift: there is **no flexbox layout engine**. Documents are a top-to-bottom block flow. Use `<Spacer>`, `<PageBreak>`, tables, and per-component alignment props instead of `<View>` containers.

---

## Diagnostics

`PdfStructureError` is thrown with an actionable message when a tree cannot be mapped onto the document model (for example, a `<Cell>` outside a `<Row>`, or an unsupported child of `<Document>`). Catch it to surface authoring mistakes early:

```ts
import { PdfStructureError, renderToBytes } from 'pdfnative-react';

try {
  const bytes = renderToBytes(<MyDoc />);
} catch (e) {
  if (e instanceof PdfStructureError) console.error('Invalid document tree:', e.message);
  else throw e;
}
```

---

## Release history

### What's new in v1.2.0

v1.2.0 follows the pdfnative 1.7.0 engine — charts v2, print production, and the conformance channel — and is **100 % additive**: no component, hook or function was removed or changed shape. The only floor that moves is the `pdfnative` peer, `^1.6.0` → `^1.7.0`.

| Area | v1.1.0 | v1.2.0 |
|---|---|---|
| Charts | 5 types | **9 types** (`stackedBar`, `stackedBarH`, `area`, `scatter`) + `axis2`, `xAxis` (category / linear / time), log scale on the value axes, `dataLabels`, `labelStride`, `labelRotation` |
| Print | — | **`<Document print>`** / `DocSpec.print` — bleed shorthand, page boxes, printer's marks, `/UserUnit`; viewer preferences and a custom output intent via `layout` |
| Conformance | — | `layout.strict` / `layout.onDiagnostic` expose the engine's PDF/A diagnostics channel; new `PdfDiagnostic*` types |
| HTTP | `renderToResponse` | + `cacheControl` and `etag` options; streamability validated **before** the first byte |
| Linting | 18 rules | **25 rules** (7 new, incl. `L_PRINT_BOXES` which delegates to the engine's `validatePrintOptions`) |
| Fonts | `resolveFonts` emitted an invalid bare `fontRef` | **fixed** — slash-prefixed PDF names (`/latin`, `/th`, …); re-render anything produced through `resolveFonts` / the `fonts` option |
| Exports | — | +`setDeflateImpl` and 8 types (`PrintOptions`, `PrinterMarksOptions`, `PageBox`, `CustomOutputIntent`, `PdfDiagnostic`, `PdfDiagnosticCode`, `PdfDiagnosticHandler`, `PdfColors`) |
| Quality | — | 292 tests / 18 files · 95 % statement coverage · a veraPDF gate over an 11-file PDF/A corpus (with 2 negative canaries) blocks CI and publish |
| Compatibility | `pdfnative ^1.6.0` peer | **`pdfnative ^1.7.0`** peer; React `^19.0.0` and Node ≥ 22 unchanged |

Full changelog: [pdfnative-react release notes v1.2.0](https://github.com/Nizoka/pdfnative-react/releases/tag/v1.2.0).

### Previously in v1.1.0

<!-- verify-docs:allow version-token (historical release entry) -->
v1.1.0 brought the engine's 1.6 surface to the renderer — `<Chart>`, the `DocSpec` chart tuple, and the agent discovery pair (`capabilityManifest` / `doctor`) — on the `pdfnative ^1.6.0` peer.

---

## Resources

- 📦 **npm:** [pdfnative-react](https://www.npmjs.com/package/pdfnative-react)
- 🏛️ **Repo:** [Nizoka/pdfnative-react](https://github.com/Nizoka/pdfnative-react)
- 📚 **Knowledge base:** [pdfnative-react/docs/KNOWLEDGE_BASE.md](https://github.com/Nizoka/pdfnative-react/blob/main/docs/KNOWLEDGE_BASE.md) — the compile pipeline, the react-reconciler version contract, and the agent authoring contract
- 📁 **Samples:** [pdfnative-react/samples](https://github.com/Nizoka/pdfnative-react/tree/main/samples)
- 🧪 **Try it interactively:** [React playground](../playgrounds/react.html) — render JSX to PDF in your browser
- 🔧 **Underlying library:** [`pdfnative`](https://github.com/Nizoka/pdfnative)
- 🤖 **AI integration:** [pdfnative-mcp guide](mcp.html) · 💻 **Terminal:** [pdfnative-cli guide](cli.html)
- 🐛 **Report a bug:** [Nizoka/pdfnative-react/issues](https://github.com/Nizoka/pdfnative-react/issues)

---
<!-- source: docs/guides/self-verify.md -->
# Self-verifying generation

> **pdfnative can read what it writes, so a generated PDF never has to ship
> unchecked.** Plan pagination with `inspectDocumentLayout()` *before* building,
> then run `extractText()`, `validatePdfUA()` and `listSignatures()` /
> `openPdf()` against the emitted bytes, assert what matters, and correct the
> input until every assertion holds. The same generate → inspect → assert →
> correct loop runs on all four surfaces: in the library, on the CLI
> (`inspect --check`, stable exit codes and `E_*` error classes), and on MCP
> (`inspect_pdf` check assertions) — so a test suite, a CI job or an AI agent
> can close the loop without a human ever opening a viewer.

## Why a PDF is normally a blind artefact

Most PDF generators are write-only: the library that produced the file cannot
parse it back. The only verification available is a human opening the result in
a viewer — which no pipeline, test suite or autonomous agent can do. So defects
ship silently: a table that slipped onto a second page, a template placeholder
that was never substituted, a PDF/A claim the file cannot honour, a signature
placeholder that was never actually signed.

pdfnative bundles a parser next to the writer, in the same zero-dependency
package. The read side (`openPdf()`, `extractText()`, `validatePdfUA()`,
`listSignatures()`) consumes exactly what the write side emits — and any other
PDF — which turns generation into a closed loop:

1. **Plan** — measure pagination with `inspectDocumentLayout()` before a single
   byte is produced.
2. **Generate** — build the document.
3. **Inspect** — read the emitted bytes back with the parser.
4. **Assert & correct** — check the facts you care about; on failure, fix the
   *input* and regenerate. Never patch the output bytes.

The rest of this guide walks the four verifiers with realistic
failure → fix examples, then shows the identical loop on the CLI and on MCP.

## Verifier 1 — `inspectDocumentLayout()`: geometry, before generating

_(v1.5.0)_ A pagination dry run: the same planning logic as the builder, but it
returns data instead of PDF bytes — no rendering, no font embedding.

```ts
import { buildDocumentPDFBytes, inspectDocumentLayout } from 'pdfnative';

const params = {
  title: 'Invoice #2026-041',
  blocks: [
    { type: 'heading', level: 1, text: 'Invoice #2026-041' },
    { type: 'paragraph', text: intro },
    { type: 'table', headers: ['Item', 'Qty', 'Total'], rows },
  ],
};

// Plan — no PDF is produced.
const layout = inspectDocumentLayout(params);

// Assert: a one-page invoice.
if (layout.totalPages !== 1) {
  throw new Error(`expected 1 page, planned ${layout.totalPages}`);
}

// Assert: the table starts on page 1, not after a stray break.
const table = layout.pages[0].blocks.find((b) => b.type === 'table');
if (!table) throw new Error('table was pushed off page 1');

// Only now generate.
const bytes = buildDocumentPDFBytes(params);
```

**Failure → fix.** `totalPages` comes back as `2` because this month's `rows`
grew by three entries. Fixes live in the input: shorten `intro`, reduce the
margins in the layout options, or accept the second page and change the
assertion — the table planner repeats headers on continuation pages by default,
so a deliberate two-pager stays readable. Re-run the inspection until the
assertion holds, then build.

> **Honest caveat.** `inspectDocumentLayout()` shares the builder's measurement
> code (`estimateBlockHeight` / `planTable` and its constants) — that is
> precisely why its geometry matches where the renderer places each block,
> including table slicing across page breaks. But it is a *prediction from the
> shared engine*, not an independent re-parse of the emitted bytes. For
> verification of the actual output, pair it with `extractText()` below. See
> [Layout debugging & inspection](debugging.html) for the full data shape and
> the visual overlay variant.

## Verifier 2 — `extractText()`: is the content actually in the file?

_(v1.6.0)_ Reading-order Unicode text per page, decoded from the content
streams of the emitted bytes — pdfnative-generated documents round-trip
losslessly, including CJK, Arabic and emoji.

```ts
import { buildDocumentPDFBytes, extractText } from 'pdfnative';

const bytes = buildDocumentPDFBytes(params);

const pages = extractText(bytes);               // ExtractedPageText[]
// Each entry: { pageIndex: number, text: string, runs?: ExtractedTextRun[] }
const flat = pages.map((p) => p.text).join('\n');

for (const required of ['Invoice #2026-041', 'Total', '1 240,00 €']) {
  if (!flat.includes(required)) {
    throw new Error(`missing from the emitted PDF: "${required}"`);
  }
}
if (flat.includes('{{')) {
  throw new Error('an unresolved template placeholder reached the PDF');
}
```

**Failure → fix.** The total is missing: the value never entered `blocks` —
typically a renamed data field, or a templating step that ran after the build
instead of before it. The `{{` guard catches the classic half-rendered
template. Fix the data flow and regenerate. Positioned runs
(`{ includeRuns: true }`) additionally give each string's `x` / `y` /
`fontSize` when you need to assert *where* something landed, not just that it
exists.

Extraction has documented limits (no OCR on image content, lossy conjuncts in
shaped Indic scripts) — see [Text extraction](text-extraction.html) before
asserting on those cases.

## Verifier 3 — `validatePdfUA()`: structural PDF/UA

Read-only ISO 14289-1 structural checks over the emitted bytes: `/MarkInfo`,
the structure tree, the parent tree, a document `/Lang`, per-page MCID
uniqueness.

```ts
import { buildDocumentPDFBytes, validatePdfUA } from 'pdfnative';

const bytes = buildDocumentPDFBytes(params, { tagged: true });

const report = validatePdfUA(bytes);   // { valid, errors, warnings }
if (!report.valid) {
  throw new Error(`PDF/UA structure: ${report.errors.join('; ')}`);
}
```

**Failure → fix.** The most common failure is building without `tagged` — the
document then has no structure tree at all, and every structural check fires.
Set `layout: { tagged: true }` (or a `'pdfa*'` level) and regenerate. Warnings
are non-blocking best-practice notes; decide explicitly whether your pipeline
tolerates them.

> **Honest caveat.** This is a *structural* validation, not an accessibility
> audit. A passing report means the machine-checkable structure is present and
> consistent — it cannot judge whether the reading order makes sense to a
> human, whether alt text is meaningful, or whether colour contrast is
> adequate. And it is not a PDF/A validator: for archival conformance, run
> veraPDF as described in [PDF/A conformance](pdfa.html).

## Verifier 4 — `listSignatures()` + `openPdf()`: signatures, encryption, metadata

`listSignatures()` _(v1.7.0)_ inventories every signature field in the
document; `openPdf()` (available since v1.0.0) exposes page count, encryption
state and the `/Info` dictionary.

```ts
import { openPdf, listSignatures } from 'pdfnative';

const sigs = listSignatures(signedBytes);
if (sigs.length === 0) throw new Error('no signature field found');
if (sigs.some((s) => s.isPlaceholder)) {
  throw new Error('a /Sig field is still an unsigned placeholder');
}
// Per entry: fieldName?, subFilter, byteRange, isDocTimestamp, isPlaceholder.
const pades = sigs.filter((s) => s.subFilter === 'ETSI.CAdES.detached');

const reader = openPdf(signedBytes);
if (reader.encryption !== null) throw new Error('expected an unencrypted document');
if (reader.pageCount < 2) throw new Error('terms page missing');
const info = reader.getInfo();
```

**Failure → fix.** `isPlaceholder: true` means `addSignaturePlaceholder()` ran
but `signPdfBytes()` never filled that field — usually a skipped signing step,
or a `fieldName` selector that targeted a different placeholder. Sign the
document (or the right field) and re-check. `isDocTimestamp` distinguishes
`/DocTimeStamp` entries when you assert on the PAdES ladder.

> **Honest caveat.** `listSignatures()` is an inventory, not a cryptographic
> verdict — the pdfnative engine deliberately ships no signature verifier.
> Full verification (byte-range digest, CMS signature value, certificate
> chain, trust, timestamps, revocation) lives in `pdfnative-cli verify` and in
> the MCP `verify_pdf` tool, below. See
> [Long-term validation (LTV)](ltv.html).

## The same loop on the CLI

`pdfnative-cli` turns the assertions into exit codes, which is what a shell or
CI step branches on:

```bash
# Plan (pre-flight): pagination report instead of a PDF   (v1.2.0)
pdfnative render --input invoice.json --inspect-layout > layout.json

# Generate, then assert — exit 0 when every --check holds, 1 otherwise
pdfnative render  --input invoice.json --output invoice.pdf --tagged pdfa2b
pdfnative inspect --input invoice.pdf --check pdfa --check pdfua --json --summary
echo $?   # 0 = all assertions hold, 1 = at least one failed

# Content presence, pipeline-style
pdfnative extract-text --input invoice.pdf --format text | grep -q 'Invoice #2026-041'
```

- `inspect --check` takes repeatable, ANDed assertions — `pdfa`, `signed`,
  `encrypted`, `pdfua` _(v1.1.0)_ — and sets the exit code accordingly; under
  `--json`, a failed assertion also emits the stable error class
  `E_CHECK_FAILED` in the machine-readable envelope on stderr
  (`{ ok: false, command, error: { code, message } }`).
- `--summary` _(v1.1.0)_ shrinks the stdout verdict to
  `{ pages, encrypted, signatures, pdfa }`; `--fields a,b.c` projects arbitrary
  dot-paths — both exist so agents branch on facts without paying for the full
  report.
- `pdfnative verify --strict` performs the cryptographic half: byte-range
  digest, CMS signature value (RSA and ECDSA), certificate chain and trust
  against `--trust` roots, RFC 3161 timestamps, OCSP/CRL revocation — exit 1
  and `E_VERIFY_FAILED` on any failure *or on zero signatures*.

The full command reference, including every `--check` flag and the `E_*`
catalogue, is in the [CLI guide](cli.html).

## The same loop on MCP

`pdfnative-mcp` gives a conversational agent the identical verifiers as
read-only tools — the natural final step after any document tool call:

| Tool | Verifies |
|---|---|
| `inspect_pdf` | Version, page count, encryption, PDF/A claim, signatures, attachments, `/Info` — plus `check` assertions with a boolean verdict. |
| `inspect_layout` _(v1.6.0)_ | Pagination dry run for a prospective document — page count and block geometry, no PDF produced, no base64 output tokens spent. |
| `validate_pdf` | Structural PDF/UA — `{ valid, errors, warnings }`. |
| `verify_pdf` | Cryptographic signature verification; `ltv: true` _(v1.6.0)_ reports the achieved PAdES level (B-B → B-LTA). |

```jsonc
{ "tool": "inspect_pdf",
  "input": { "pdfBase64": "<...>", "check": ["pdfa", "signed"] } }
// → { ..., "checks": { "pdfa": true, "signed": true }, "checksPassed": true }
```

- `check` accepts `pdfa`, `signed`, `encrypted`, `placeholder`, `attachments`,
  and — _(v1.6.0)_ — `dss`, `docTimestamp`, `trapped`, `annotations`.
  `checksPassed` is the AND of all requested assertions; since v1.6.0 `checks`
  contains **only** the requested keys, so branch on `checksPassed` or on a key
  you asked for, never on an absent one.
- `inspect_layout` accepts the same `title` / `blocks` (plus every input that
  moves a block) as `generate_basic_pdf`, so an agent can iterate on pagination
  before spending output tokens on real bytes. Known engine gap: a `toc` block
  is measured as 0 pt, so a document with a printed contents page may paginate
  one page later than previewed.
- `validate_pdf` on unparsable bytes is an error (`PDF_PARSE_FAILED`), not a
  `{ valid: false }` verdict, since v1.6.0 — a parse failure is not a PDF/UA
  result.

Tool-by-tool inputs and error codes are in the [MCP guide](mcp.html).

## Wire it into CI and agent loops

**CI.** Chain the loop with `set -e` so any failed assertion fails the job —
no PDF-viewing human in the path:

```bash
set -e
pdfnative render  --input report.json --output report.pdf --tagged pdfa2b
pdfnative sign    --input report.pdf  --output signed.pdf --key k.pem --cert c.pem
pdfnative inspect --input signed.pdf  --check pdfa --check signed --json --summary
pdfnative verify  --input signed.pdf  --strict --trust ca-root.pem
```

`--dry-run` on the write commands validates inputs without producing output,
which makes a cheap first CI stage; `--summary` / `--fields` keep logs and
agent context small.

**Agent loops.** Treat every generation as unfinished until a read tool
confirms it: after `generate_basic_pdf` (or any document tool), call
`inspect_pdf` with the `check` list that encodes the user's requirements and
branch on `checksPassed`; on failure, correct the tool input and regenerate
rather than apologising with an unverified file. Use `inspect_layout` before
generating and `verbosity: "summary"` on the read tools to keep token spend
proportional. The [agent brief](../agent-brief.md) condenses this contract
into a paste-into-context form.

## Further reading

- [Agent brief](../agent-brief.md) — the compact form of this loop for AI
  agents, verified by the documentation CI.
- [Layout debugging & inspection](debugging.html) — the visual overlay and the
  full `LayoutInspection` data shape.
- [Text extraction](text-extraction.html) — decoding rules, positioned runs,
  documented limits.
- [PDF/A conformance](pdfa.html) — validating archival claims with veraPDF,
  and the build-time `PDFA_*` diagnostics.
- [Long-term validation (LTV)](ltv.html) — the PAdES ladder the signature
  assertions climb.
- [CLI guide](cli.html) · [MCP guide](mcp.html) — the complete surface
  references.

---
<!-- source: docs/guides/signatures.md -->
# Digital signatures in pdfnative

> **CMS/PKCS#7 detached signatures in pure TypeScript** — RSA PKCS#1 v1.5 (SHA-256/384/512) and ECDSA P-256, the PAdES baseline profile and multiple signatures since v1.7.0, with a one-call `addSignaturePlaceholder()` workflow. For timestamps and B-T → B-LTA, see the [LTV guide](ltv.html).

pdfnative ships a zero-dependency CMS/PKCS#7 detached signature
implementation (ISO 32000-1 §12.8) with full crypto in pure TypeScript —
RSA PKCS#1 v1.5 (SHA-256, plus SHA-384/512 since v1.7.0) and ECDSA P-256 (SHA-256), X.509 DER parsing,
and ASN.1 DER encoding. No OpenSSL, no node-forge, no external crypto.

## TL;DR — sign any PDF in 3 lines

```ts
import {
    buildDocumentPDFBytes,
    addSignaturePlaceholder,
    signPdfBytes,
    parseCertificate,
    parseRsaPrivateKey,
} from 'pdfnative';

const unsigned = buildDocumentPDFBytes(params);
const placeheld = addSignaturePlaceholder(unsigned, { fieldName: 'Author' });
const signed = signPdfBytes(placeheld, {
    signerCert: parseCertificate(certDer),  // X509Certificate (from DER bytes)
    rsaKey: parseRsaPrivateKey(keyDer),     // RsaPrivateKey (from DER bytes)
    algorithm: 'rsa-sha256',
});
```

That's it. `addSignaturePlaceholder()` injects an
AcroForm + invisible signature widget + `/Sig` dictionary into the
existing PDF via an incremental update (ISO 32000-1 §7.5.6), then
`signPdfBytes()` computes the `/ByteRange`, hashes the document, builds
the CMS SignedData, and writes the result into the `/Contents`
placeholder.

## Three-step pipeline

```
buildDocumentPDFBytes(params)
        │
        ▼
   unsigned PDF
        │
        │  addSignaturePlaceholder()  ← injects AcroForm + /Sig dict
        ▼
   PDF with /ByteRange + /Contents placeholder
        │
        │  signPdfBytes()             ← hashes, signs, fills /Contents
        ▼
   signed PDF (Adobe Reader ✓ / openssl-cms ✓)
```

### 1. `addSignaturePlaceholder(pdfBytes, options?)`

Idempotent. If the input already contains an `/FT /Sig` widget,
returns the input unchanged. Throws on encrypted input.

Options:

| Option            | Default          | Notes                                             |
|-------------------|------------------|---------------------------------------------------|
| `placeholderBytes`| `16384`          | Size of the `/Contents` hex placeholder           |
| `fieldName`       | `'Signature1'`   | AcroForm field name                               |
| `pageIndex`       | `0`              | Page to attach the (invisible) widget to          |
| `rect`            | `[0, 0, 0, 0]`   | Widget rectangle (invisible by default)           |
| `allowMultiple`   | `false`          | Append a placeholder even when signature fields already exist — the multi-signature flow (v1.7.0, see below) |

To size `placeholderBytes` from your actual certificate chain instead of
relying on the 16 KiB default, use `estimateContentsSize(certSizes, algorithm)`.
Since v1.7.0 it takes an options object: `estimateContentsSize(certSizes,
'rsa-sha256', { timestamp: true })` reserves ~8 KiB of extra headroom for an
RFC 3161 timestamp token (covering the TSA's own certificate chain) when an
external signer will add one to the CMS.

Signer metadata (`name`, `reason`, `location`, `contactInfo`, `signingTime`)
is **not** set here — the placeholder writes an empty `/Sig` dictionary; pass
the metadata to `signPdfBytes`, which writes it at signing time.

### 2. `signPdfBytes(pdfBytes, options)`

Reads the `/ByteRange`, hashes the two byte ranges (everything except
the `/Contents` slot), builds a CMS SignedData with the certificate
chain and `signedAttrs` (content-type, message-digest, signing-time),
signs the `signedAttrs` digest, and writes the DER-encoded CMS into
`/Contents`.

Options:

- `signerCert` — `X509Certificate` (parse DER bytes with `parseCertificate`).
- `rsaKey` _or_ `ecKey` — the private key. Parse RSA keys from DER with
  `parseRsaPrivateKey`; for ECDSA there is no DER parser in the engine — supply
  the `EcPrivateKey` scalar directly, or install a crypto provider
  (`setCryptoProvider` / per-call `provider`) and omit the raw key entirely.
- `algorithm` — `'rsa-sha256' | 'rsa-sha384' | 'rsa-sha512' | 'ecdsa-sha256'`
  (default `'rsa-sha256'`; the SHA-384/512 RSA variants are new in v1.7.0).
- `certChain?` — additional intermediate-CA certificates for the chain.
- `signingTime?` — forwarded to `signedAttrs`.
- `fieldName?` — with several unsigned placeholders in the file (the
  `allowMultiple` flow below), selects which one to sign by its AcroForm field
  name. With a single placeholder — the only case prior to v1.7.0 — the option
  is unnecessary and behaviour is unchanged. (v1.7.0)

### 3. Verifying

The library does **not** ship a PDF-signature verifier — its
verification surface is limited to `openPdf()` plus
`verifyCertSignature()` (an X.509 certificate-signature check). To
verify a signed PDF end to end (byte-range digest, CMS signature value,
chain, trust, timestamps, revocation), use
[`pdfnative-cli verify`](cli.html#pdfnative-verify) or the
[`verify_pdf` MCP tool](mcp.html) — the CMS verification logic lives
there. Since pdfnative-mcp 1.6.0, `verify_pdf` also validates
`/DocTimeStamp` fields as RFC 3161 tokens and reports the achieved
PAdES level (B-B → B-LTA) with `ltv: true`.

## Why a separate placeholder step?

The PDF signature spec is unusual: the `/Contents` field of the `/Sig`
dictionary must contain the CMS bytes, **but the `/ByteRange` excludes
exactly that slot**. So the PDF is hashed _without_ the bytes we're
about to write, which means the file must already have the right
layout — including the placeholder reserved bytes — before we sign.

`addSignaturePlaceholder()` is the canonical way to produce that
layout. It replaces the ad-hoc reimplementations that downstream
tooling (notably `pdfnative-cli`'s `sign` command and `pdfnative-mcp`'s
`prepare_signature_placeholder` workaround) previously had to ship.

## Multiple signatures (v1.7.0)

Simply repeating the placeholder + sign pass does **not** add a second
signature: `addSignaturePlaceholder()` is idempotent by contract, so on a PDF
that already carries any `/FT /Sig` field it returns the input unchanged. To
add further signatures, opt in with `allowMultiple` and give each signature its
own field name:

```ts
// First signer.
let pdf = addSignaturePlaceholder(unsigned, { fieldName: 'Author' });
pdf = signPdfBytes(pdf, {
    signerCert: authorCert, rsaKey: authorKey, algorithm: 'rsa-sha256',
});

// Second signer — appended as a fresh incremental update.
pdf = addSignaturePlaceholder(pdf, { fieldName: 'Reviewer', allowMultiple: true });
pdf = signPdfBytes(pdf, {
    signerCert: reviewerCert, rsaKey: reviewerKey, algorithm: 'rsa-sha256',
    fieldName: 'Reviewer', // selects which unsigned placeholder to fill
});
```

The exact semantics:

- **`allowMultiple: false`** (default) preserves the 1.x idempotent
  short-circuit: any existing signature field returns the input unchanged.
- **`allowMultiple: true`** — an existing *unsigned* placeholder with the same
  `fieldName` returns the input unchanged (per-name idempotence); a *signed*
  field with the same name throws (pass a fresh `fieldName`); other signature
  fields are left alone and a new placeholder is appended via incremental
  update, so `/Prev` chains compose naturally.
- **`signPdfBytes` with several unsigned placeholders** requires the
  `fieldName` selector — without it, the call throws and lists the unsigned
  field names. Already-signed signatures are never modified.

## Inspecting signatures — `listSignatures()` (v1.7.0)

`listSignatures(pdfBytes)` enumerates every signature field in a PDF, in
AcroForm `/Fields` order — signed signatures, document timestamps, and
still-unsigned placeholders:

```ts
import { listSignatures } from 'pdfnative';

for (const sig of listSignatures(signedPdf)) {
    console.log(sig.fieldName, sig.subFilter, sig.isPlaceholder);
}
// → 'Author'   'adbe.pkcs7.detached' false
// → 'Reviewer' 'adbe.pkcs7.detached' false
```

Each entry is a `PdfSignatureInfo`:

| Field | Type | Meaning |
|-------|------|---------|
| `fieldName?` | `string` | The widget's `/T` field name, when present |
| `subFilter` | `string` | `/SubFilter` — e.g. `'adbe.pkcs7.detached'`, `'ETSI.CAdES.detached'`, `'ETSI.RFC3161'` (`''` when absent) |
| `byteRange` | `readonly number[]` | `/ByteRange` offsets |
| `contents` | `Uint8Array` | The full decoded `/Contents` value, trailing zero padding included |
| `isDocTimestamp` | `boolean` | `true` for `/Type /DocTimeStamp` entries (ISO 32000-2 §12.8.5) |
| `isPlaceholder` | `boolean` | `true` for an unsigned placeholder (all-zero `/ByteRange`) |
| `sigObjNum` | `number` | Object number of the `/Sig` dictionary |

`listSignatures()` is a read-only inspection API — it never **verifies**
anything (see *Verifying* above for the verification story).

Related v1.7.0 addition: `SigDictMetadata` — the metadata subset shared by
`buildSigDict()` and the signing options — gains a `subFilter` field,
`'adbe.pkcs7.detached'` (default, unchanged legacy behaviour) or
`'ETSI.CAdES.detached'` to declare a PAdES (ETSI EN 319 142) signature.
`buildSigDict()` writes it into the `/Sig` dictionary, and `listSignatures()`
reports it back on each entry. When declaring `'ETSI.CAdES.detached'`, pair it
with the `profile: 'pades'` signing option so the CMS carries the matching
ESS `signing-certificate-v2` attribute.

## Algorithms

| Algorithm        | Hash      | Curve / Modulus     | Notes                          |
|------------------|-----------|---------------------|--------------------------------|
| `rsa-sha256`     | SHA-256   | 2048 / 3072 / 4096  | PKCS#1 v1.5 (default)          |
| `rsa-sha384`     | SHA-384   | 2048 / 3072 / 4096  | PKCS#1 v1.5 (v1.7.0)           |
| `rsa-sha512`     | SHA-512   | 2048 / 3072 / 4096  | PKCS#1 v1.5 (v1.7.0)           |
| `ecdsa-sha256`   | SHA-256   | P-256 (secp256r1)   | DER-encoded ECDSA signature    |

That is the complete `SignatureAlgorithm` union — the RSA variants widened
to SHA-384/512 in v1.7.0; ECDSA is offered with SHA-256 only.

All primitives live under [src/crypto/](https://github.com/Nizoka/pdfnative/tree/main/src/crypto):
SHA-256/384/512 in `sha.ts`, ASN.1 DER in `asn1.ts`, RSA modular
arithmetic in `rsa.ts`, ECDSA P-256 in `ecdsa.ts`, X.509 parsing in
`x509.ts`, and the CMS SignedData builder in `cms.ts`.

## Validating the output

```bash
# openssl-cms — extract the CMS payload and verify against the certificate
openssl pkcs7 -in signed.pdf -inform DER -print_certs

# Adobe Reader — open signed.pdf; signatures panel shows the field name,
# signing time, signer subject, and a green check if the chain validates.

# pdfnative-cli — full CMS verification (the library itself has no PDF-signature verifier)
npx pdfnative-cli verify --input signed.pdf --strict
# → { "signatures": [ { "integrity": true, "signatureValid": true, ... } ] }
```

## Reading the validator output

Two warnings commonly surface when testing the sample PDFs in Adobe Reader.
Both are **expected by spec** — they are not pdfnative bugs.

### "Validity unknown" / "Identité du signataire inconnue"

Adobe shows this whenever the signing certificate's issuer chain does
not terminate in a root CA listed in Adobe's Approved Trust List (AATL)
or in the user's locally configured Trusted Identities.

- The `scripts/generators/digital-signature.ts` sample uses a
  **self-signed demo CA** so it can ship deterministically. The
  cryptographic signature itself is valid (Adobe says so:
  *"Le document n'a pas été modifié depuis l'apposition de la signature"*);
  only the identity link to a public root is missing.
- To remove the warning in Adobe Reader: **Preferences → Signatures →
  Identités → Identités autorisées → Ajouter** and import the demo
  certificate as a trusted root.
- To verify the CMS independently of any trust store, use
  `openssl pkcs7 -in signed.pdf -inform DER -print_certs` and
  `openssl cms -verify -CAfile demo-ca.pem`.
- For production signatures, use a certificate issued by a CA in the
  Adobe Approved Trust List (Sectigo, DigiCert, GlobalSign…) or your
  organisation's enterprise CA distributed via group policy.

### "Signature non valable" on a placeholder PDF

A PDF that has only been through `addSignaturePlaceholder()` (i.e. not
yet `signPdfBytes()`) **will** read as invalid in Adobe — and that is
correct behaviour. The `/Sig` dictionary's `/Contents` slot is
zero-padded hex by design, reserved for the CMS SignedData that the
external signer will produce. Adobe sees a malformed CMS and reports
the signature as broken.

The `scripts/generators/signature-placeholder.ts` sample produces
exactly this shape on purpose, to demonstrate:

1. The placeholder layout is byte-stable (the `-idempotent` companion
   PDF proves it — re-running the function produces identical bytes).
2. Downstream tooling (HSMs, cloud KMS, smartcards) can fill in
   `/Contents` without touching the surrounding objects.

To turn a placeholder into a valid signature, call `signPdfBytes()` on
the placeholder bytes — that's the pipeline shown in the TL;DR above.

## Caveats

- **Encrypted PDFs.** `addSignaturePlaceholder()` throws on encrypted
  input — sign before encrypting, or decrypt first.
- **Timestamping (RFC 3161).** Supported since v1.7.0 —
  `signPdfBytesWithTimestamp()` embeds a verified TSA token as the
  `id-aa-signatureTimeStampToken` unsigned attribute, and
  `addDocumentTimestamp()` appends `/DocTimeStamp` revisions. See the
  [Long-term validation guide](ltv.html) for the full PAdES B-B → B-LTA
  pipeline (timestamps, `/DSS` + `/VRI`, injected providers).
- **Multiple signatures.** Supported since v1.7.0, but **not** by naively
  repeating the placeholder + sign pass — `addSignaturePlaceholder()` is
  idempotent and returns an already-signed PDF unchanged. Pass
  `allowMultiple: true` with a fresh `fieldName`, then select that field in
  `signPdfBytes` — see [Multiple signatures](#multiple-signatures-v170)
  above.
- **PDF/A + signatures.** PDF/A-2b/3b allow signatures; ISO 19005-2
  §6.3.5 forbids certain `/Sig` dictionary fields (`/Reference`,
  `/Changes`). pdfnative emits only the conformant subset.
- **Timing side-channels (pure-JS BigInt).** The RSA/ECDSA math runs on
  JavaScript `BigInt`, which is **not** constant-time — the RSA modular
  exponentiation in particular is a secret-dependent square-and-multiply
  loop. Signing a PDF once per user action is not meaningfully
  exploitable, but a high-frequency server signing thousands of PDFs/s
  with the same key under adversarial timing observation could
  theoretically leak key material. For such pipelines, install a native
  constant-time signer via `setCryptoProvider()` (see below) — or compute the
  CMS/PKCS#7 blob with a constant-time native backend (Node.js
  `crypto.sign()` or WebCrypto `crypto.subtle.sign()`) and inject it via
  `signPdfBytes()`. See [SECURITY.md](https://github.com/Nizoka/pdfnative/blob/main/SECURITY.md#cryptographic-implementation-scope--known-limitations)
  for the full analysis.

## Native crypto provider (v1.4.0)

For high-security, high-frequency server pipelines you can replace
pdfnative's pure-JS RSA/ECDSA math with a native, **constant-time** signer
without giving up the zero-dependency default. Install a provider globally
with `setCryptoProvider(provider)`, or pass one per call via
`PdfSignOptions.provider` (per-call wins over global). When a provider is set,
`rsaKey` / `ecKey` are no longer required.

```ts
import { setCryptoProvider, signPdfBytes } from 'pdfnative';
import { createSign, createPrivateKey } from 'node:crypto';

const key = createPrivateKey(pemPrivateKey);

setCryptoProvider({
    // `tbs` is the DER-encoded CMS signed attributes. The provider hashes it
    // with SHA-256 internally (node:crypto does this for you) and returns the
    // raw signature value (RSA PKCS#1 v1.5, or a DER-encoded ECDSA-P256 sig).
    sign(tbs, algorithm) {
        return new Uint8Array(createSign('sha256').update(tbs).sign(key));
    },
});

const signed = signPdfBytes(placeheld, {
    signerCert: cert,
    algorithm: 'rsa-sha256', // rsaKey/ecKey no longer needed
});

// Restore the pure-JS default at any time:
setCryptoProvider(null);
```

This is the in-library escape hatch for the BigInt timing caveat above — the
secret-dependent math runs in `node:crypto` / Web Crypto / an HSM while
pdfnative's CMS/PKCS#7 assembly is reused unchanged.

## Full example

See [scripts/generators/digital-signature.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/digital-signature.ts)
for a runnable RSA + ECDSA sample (key generation, certificate
construction, sign, verify) and
[scripts/generators/signature-placeholder.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/signature-placeholder.ts)
for the idempotency proof.

## Related guides

- [PDF/A conformance →](pdfa.html) — how signatures interact with PDF/A-2b/3b.
- [Architecture →](architecture.html) — where the crypto module sits in the dependency graph.
- [CLI →](cli.html) — `pdfnative-cli sign` wraps this exact pipeline.
- [MCP integration →](mcp.html) — `pdfnative-mcp` exposes signing as an AI tool, and since v1.6.0 the complete PAdES ladder: `sign_pdf` (`profile: 'pades'`, RFC 3161 `timestamp`) → `add_ltv` (`/DSS` + `/VRI`, B-LT) → `timestamp_pdf` (`/DocTimeStamp`, B-LTA), verified with `verify_pdf ltv: true`.

---
<!-- source: docs/guides/streaming.md -->
# Streaming output

> **pdfnative emits PDFs as `AsyncGenerator<Uint8Array>`** so you can pipe them to disk, an HTTP response, or a Web Stream without buffering the whole document. **New in v1.3.0:** a mode in which the fully-joined PDF binary never exists in memory — see [what this does and does not buy you](#what-this-does-and-does-not-buy-you) for the exact profile.

## Three streaming modes

| Function | Memory profile | When to use |
|---|---|---|
| `buildDocumentPDFStream` / `buildPDFStream` | Assembles full binary, then yields fixed-size chunks | Simple back-pressure-friendly piping |
| `buildDocumentPDFStreamPageByPage` / `buildPDFStreamPageByPage` | Assembles full binary, yields one PDF object per chunk | Object-granular persistence / diagnostics |
| **`buildDocumentPDFStreamTrue` / `buildPDFStreamTrue`** | **Never joins the binary — frees each part as it yields** | Large documents, and anything over ~512 MB of output |

All three produce **byte-identical** output to `buildDocumentPDFBytes()` /
`buildPDFBytes()`.

## Streaming without joining the binary (v1.3.0)

```ts
import { createWriteStream } from 'node:fs';
import { buildDocumentPDFStreamTrue } from 'pdfnative';

const out = createWriteStream('report.pdf');
for await (const chunk of buildDocumentPDFStreamTrue(params, layout, { chunkSize: 65536 })) {
  out.write(chunk);
}
out.end();
```

Internally, the builder assembles the PDF into an array of raw parts (objects,
xref, trailer) and the generator walks that array, encoding each part to bytes
and **freeing it (`parts[i] = ''`) as soon as it is emitted**.

### What this does and does not buy you

Being precise here matters, because the two claims are often conflated.

**What it avoids.** The joined PDF binary never exists. That removes a full
second copy of the document, and it lifts the hard ceiling that
`buildDocumentPDFStream` hits: that variant joins everything into one JavaScript
string, and V8 caps a single string at roughly 512 MB. Past that point it throws
regardless of how much RAM the machine has. `buildDocumentPDFStreamTrue` has no
such ceiling.

**What it does not avoid.** `assembleDocumentParts()` runs to completion before
the first chunk is yielded, so every part is resident at that moment. Peak memory
is therefore still proportional to total output size — roughly 2 bytes per output
character, since JavaScript strings are UTF-16. From the first yield onwards
memory falls monotonically as parts are freed, but the peak has already happened.

Two practical consequences:

- Budget for about twice your expected output size, not for a fixed ceiling.
  A 300 MB PDF wants roughly 600 MB of headroom.
- **There is no progress signal during assembly.** Most of the wall-clock time is
  spent inside `assembleDocumentParts()`, which yields nothing, so a percentage
  bar covering that phase would be invented rather than measured. Report an
  indeterminate state until the first chunk arrives, then switch to a byte
  counter. The [scale playground](../playgrounds/scale.html) does exactly this.

True page-by-page assembly — where peak memory is bounded by one page rather than
the whole document — is not implemented yet.

### HTTP response (Node)

```ts
import { buildDocumentPDFStreamTrue } from 'pdfnative';

app.get('/report.pdf', async (req, res) => {
  res.setHeader('Content-Type', 'application/pdf');
  for await (const chunk of buildDocumentPDFStreamTrue(params)) {
    res.write(chunk);
  }
  res.end();
});
```

### Web Streams (browser / Deno / edge)

```ts
const stream = new ReadableStream({
  async pull(controller) {
    for await (const chunk of buildDocumentPDFStreamTrue(params)) {
      controller.enqueue(chunk);
    }
    controller.close();
  },
});
return new Response(stream, { headers: { 'Content-Type': 'application/pdf' } });
```

## Options

```ts
interface StreamOptions {
  /** Bytes per yielded chunk. Default 65536 (64 KB). Clamped to 1 KB–16 MB. */
  chunkSize?: number;
}
```

## Draining to a file: `streamToFile` (v1.4.0)

`streamToFile()` drains **any** `AsyncGenerator<Uint8Array>` — including all
three streaming modes above — straight to a file on disk in Node.js. It honours
the OS write back-pressure (awaiting the `'drain'` event when the kernel buffer
fills) and supports cancellation via an `AbortSignal`, so a single call covers
the common "generate a large PDF to disk without buffering it" case.

```ts
import { buildDocumentPDFStreamTrue, streamToFile } from 'pdfnative';

const { bytesWritten, path } = await streamToFile(
  buildDocumentPDFStreamTrue(params),
  'report.pdf',
);
console.log(`Wrote ${bytesWritten} bytes to ${path}`);
```

### Cancellation

```ts
const ac = new AbortController();
setTimeout(() => ac.abort(), 5000); // give up after 5s

await streamToFile(buildDocumentPDFStreamTrue(params), 'report.pdf', {
  signal: ac.signal,
}); // rejects with the abort reason; the partial file is closed
```

On abort — or on any write error — `streamToFile` releases the file descriptor
and **removes the partially-written file** (best-effort), so a cancelled or
failed run never leaves an orphaned half-written PDF on disk.

`streamToFile` is Node-only — it loads `node:fs` lazily via a dynamic import,
so importing it in a browser or Deno bundle adds no static Node dependency. In
non-Node runtimes, drive the generator yourself with the Web Streams snippet
above.

## Streaming merge & split (v1.6.0)

The page-tree API has constant-memory variants —
`streamMergedPdfs` / `streamSplitPdf` / `streamExtractPages` — that emit the
assembled document as fixed-size chunks while holding only the cross-reference
offsets in memory. Each is byte-identical to its buffered counterpart and
composes with `streamToFile`. (Exception: with `MergeOptions.encrypt` the
output is AES-encrypted with fresh random IVs/salts, so repeated invocations
are structurally — not byte — identical.)

```ts
import { streamMergedPdfs, streamSplitPdf, streamToFile } from 'pdfnative';

await streamToFile(streamMergedPdfs([a, b]), 'combined.pdf');

for await (const part of streamSplitPdf(body, ranges)) {
  await streamToFile(part.pdf, `part-${part.index}.pdf`);   // drain each fully, in order
}
```

Note the honest memory profile: **output** bytes are never buffered, but the
**source** PDFs are still in-memory `Uint8Array`s. See the
[PDF manipulation guide](pdf-manipulation.html#streaming-merge--split) for the
full API.

## Constraints

Streaming is incompatible with two features that need a second pass over the
whole document. Both are validated at the boundary and throw a descriptive
error:

- **TOC blocks** — the table of contents requires multi-pass pagination to
  resolve page numbers.
- **`{pages}` placeholder** in header/footer templates — the total page count
  is unknown during progressive emission. Use `{page}` instead, or fall back to
  `buildDocumentPDFBytes()`.

## See also

- [Quick start](quickstart.html)
- [Architecture](architecture.html)
- [CHANGELOG](https://github.com/Nizoka/pdfnative/blob/main/CHANGELOG.md)

---
<!-- source: docs/guides/tables.md -->
# Smart tables

> **Multi-page-safe tables by default.** Long tables wrap on column overflow,
> slice cleanly across pages and reprint their header on every continuation
> page; zebra striping, captions, per-cell padding and minimum row heights are
> one field each on `TableBlock`. Backward-compatible with v1.1.0 — existing
> single-page tables produce byte-identical output.

pdfnative's table renderer is **planner-driven** and **multi-page-safe** by default. Long tables wrap on column overflow, slice cleanly across pages, and reprint their header on every continuation page — matching the behaviour readers expect from commercial PDF libraries.

This guide documents the `TableBlock` fields, the planner architecture, the tagged-mode contract, and migration tips.

---

## TL;DR

```ts
import { buildDocumentPDFBytes } from 'pdfnative';

const bytes = buildDocumentPDFBytes({
    title: 'Invoice',
    blocks: [
        {
            type: 'table',
            headers: ['Item', 'Qty', 'Price'],
            // PdfRow[]: e.g. { cells: ['Pro plan', '1', '$49.00'], type: 'default', pointed: false }
            rows: bigInvoiceRows, // any length
            columns: [            // optional ColumnDef[]: f = width fraction, a = align,
                                  // mx / mxH = char caps (data / header), plus minWidth? / maxWidth?
                { f: 0.6, a: 'l', mx: 40, mxH: 20 },
                { f: 0.2, a: 'r', mx: 10, mxH: 8 },
                { f: 0.2, a: 'r', mx: 10, mxH: 8 },
            ],
            autoFitColumns: true,  // content-aware widths (respects minWidth/maxWidth)
            wrap: 'auto',          // ← new (default)
            repeatHeader: true,    // ← new (default)
            zebra: true,           // ← new (opt-in)
            caption: 'Invoice line items',
            minRowHeight: 14,
            cellPadding: 5,
        },
    ],
});
```

Existing v1.1.0 code with no new fields continues to work and produces **byte-identical** output on single-page tables.

---

## `TableBlock` fields (all optional)

| Field          | Type                            | Default                     | Description                                                                  |
| -------------- | ------------------------------- | --------------------------- | ---------------------------------------------------------------------------- |
| `wrap`         | `'auto' \| 'always' \| 'never'` | `'auto'`                    | Per-cell wrap policy.                                                        |
| `repeatHeader` | `boolean`                       | `true`                      | Reprint the header row at the top of each continuation page.                 |
| `zebra`        | `boolean \| PdfColor`           | `false`                     | Alternating data-row fill. `true` uses `'0.969 0.973 0.984'`.                |
| `caption`      | `string`                        | `undefined`                 | Caption printed once above the first slice.                                  |
| `minRowHeight` | `number` (points)               | `12`                        | Minimum visual row height.                                                   |
| `cellPadding`  | `number` (points)               | `3`                         | Internal cell padding.                                                       |
| `cellBorders`  | `CellBorders`                   | `undefined`                 | Per-cell vector borders (v1.4.0). Omit for byte-identical pre-1.4.0 output.   |
| `cellVAlign`   | `'top' \| 'middle' \| 'bottom'` | `undefined`                 | Vertical alignment of cell text within the row band (v1.4.0).                |

### `wrap`

- **`'auto'`** (default) — single-line rendering when cell content fits within the column width; wraps on overflow only. This is the GAFAM-grade default — fast typical case, correct edge case.
- **`'always'`** — every cell is run through the word-wrapper. Use when row heights need to be uniform regardless of content length.
- **`'never'`** — v1.1.0 behaviour. Content is clipped at the column boundary. Use when output byte-stability against v1.1.0 is mandatory.

### `repeatHeader`

- **`true`** (default) — header row reprints at the top of every continuation page.
- **`false`** — header appears only once. Set this alongside `wrap: 'never'` to preserve the exact v1.1.0 multi-page rendering shape.

### `zebra`

- **`false`** (default) — no row fill.
- **`true`** — alternating even data rows (1-indexed, so the second row, fourth row, …) are filled with `'0.969 0.973 0.984'` (a soft cool-grey tuned for accessibility contrast).
- A [`PdfColor`](https://github.com/Nizoka/pdfnative#api-reference) — hex (`'#f7f8fa'`), tuple (`[247, 248, 250]`, channels **0–255**), or PDF-rgb string (`'0.97 0.97 0.98'`, channels 0.0–1.0) — overrides the default.

### `caption`

- Printed once at the top of the table (above the first slice), using Helvetica 9pt.
- In tagged mode, emitted as a `/Caption` structure element child of `/Table` (ISO 14289-1 §7.10.6).
- Multi-line captions wrap to fit the table width.

### `minRowHeight` / `cellPadding`

- `minRowHeight` enforces a floor so rows look consistent even with short text.
- `cellPadding` is the internal padding around each cell's text. Header padding inherits this but the baseline offset is a fixed v1.1.0-compatible constant (preserves byte-stability for the row body).

### `cellBorders` (v1.4.0)

Draw per-cell vector borders. All sides are off by default — omitting `cellBorders` entirely keeps the table byte-identical to pre-1.4.0 (header underline + row separators only).

```ts
{
    type: 'table',
    headers: ['Item', 'Qty'],
    rows: [/* … */],
    cellBorders: {
        all: true,            // shorthand for top+right+bottom+left
        color: '#cccccc',     // PdfColor — default '0.8 0.8 0.8'
        width: 0.5,           // points — default 0.5
        style: 'solid',       // 'solid' | 'dashed' | 'dotted'
    },
}
```

| Field   | Type                                | Default         | Description                                          |
| ------- | ----------------------------------- | --------------- | ---------------------------------------------------- |
| `top` / `right` / `bottom` / `left` | `boolean`     | `false`         | Enable individual edges.                             |
| `all`   | `boolean`                           | `false`         | Shorthand — enables all four edges.                  |
| `color` | `PdfColor`                          | `'0.8 0.8 0.8'` | Stroke colour (hex / tuple / PDF-rgb).               |
| `width` | `number` (points)                   | `0.5`           | Stroke width.                                        |
| `style` | `'solid' \| 'dashed' \| 'dotted'`   | `'solid'`       | Stroke style. The dash is reset after each cell so row separators stay solid. |

Borders are pure vector strokes (`m … l S`), so output stays PDF/A-safe.

### `cellVAlign` (v1.4.0)

Vertically align cell text within the row band. Useful when rows have a tall `minRowHeight` or wrapped cells of differing height. A per-column [`ColumnDef.vAlign`](#tableblock-fields-all-optional) overrides the table default.

```ts
{ type: 'table', headers: [/* … */], rows: [/* … */], minRowHeight: 30, cellVAlign: 'middle' }
```

`'top'` | `'middle'` | `'bottom'`. When omitted, the historic baseline placement is preserved exactly (byte-identical to pre-1.4.0).

---

## `ColumnDef.kind` field (optional)

| Field  | Type       | Default     | Description                                                                                                                                                                                                                  |
| ------ | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `kind` | `'amount'` | `undefined` | Semantic hint. When set to `'amount'`, data cells in this column render in Helvetica-Bold with credit/debit colouring driven by `row.type`. Replaces the pre-1.2.0 hardcoded `i === 3` heuristic in `renderTable`. |

```ts
{
  type: 'table',
  headers: ['Date', 'Description', 'Status', 'Amount'],
  columns: [
    { f: 0.20, a: 'l', mx: 12, mxH: 12 },
    { f: 0.45, a: 'l', mx: 60, mxH: 60 },
    { f: 0.20, a: 'l', mx: 20, mxH: 20 },
    { f: 0.15, a: 'r', mx: 18, mxH: 18, kind: 'amount' }, // ← opt-in bold + credit/debit colour
  ],
  rows: [
    { cells: ['2026-05-01', 'Salary', 'Cleared', '+3 000.00'], type: 'credit', pointed: false },
    { cells: ['2026-05-03', 'Rent',   'Pending', '-1 250.00'], type: 'debit',  pointed: false },
  ],
}
```

> **Behaviour change for document-builder tables without `kind`.** Previously the renderer applied Helvetica-Bold + credit/debit colour to whichever column happened to be at index 3. The current renderer removes that heuristic — opt in explicitly via `kind: 'amount'`. The legacy `buildPDF()` (financial-statement) path keeps the historical heuristic for byte-identical v1.0/v1.1 output.

---

## How multi-page tables are sliced

pdfnative uses a two-phase pipeline:

1. **Plan phase** — `planTable()` ([src/core/pdf-renderers.ts](https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-renderers.ts)) measures the entire table once: resolves columns (including `autoFit`), word-wraps each cell according to `wrap`, computes per-row heights, and produces a `TablePlan` containing every row's exact pixel height.
2. **Slice phase** — `_paginateBlocks()` in [src/core/pdf-document.ts](https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-document.ts) walks the plan greedily: it packs rows onto the current page until the next row would overflow, then emits a `TableSlice` ( `{ fromRow, toRow, drawCaption, drawHeader, isFinalSlice }`) and starts a new page. The caption is emitted once (on the first slice); the header is emitted on every slice when `repeatHeader: true`.

`renderTable()` is page-lifecycle-free — it accepts an optional `slice` parameter and renders exactly the rows the paginator asked for. There is no recursive "if I overflow, start a new page" inside the renderer; pagination decisions are deterministic and centralised.

### Edge cases handled

- **Empty `rows` array** — emits a header-only slice with caption (if any). No crash, no zero-height row.
- **Single row taller than a fresh page** — emitted as a one-row slice; `clipCells` (existing v1.1.0 behaviour) handles vertical overflow inside the cell.
- **No room on current page even after pushing the table to start** — paginator forces a new page and retries.

---

## Tagged-mode / PDF/UA

When the document is built with `tagged: true` (or any explicit PDF/A mode), the table emits the following structure tree:

```text
/Table
├── /Caption       (only when caption is present)
├── /TR  ← header
│   ├── /TH
│   ├── /TH
│   └── /TH
├── /TR  ← data row 1
│   ├── /TD
│   ├── /TD
│   └── /TD
└── /TR  ← data row N
    └── …
```

The structure is **single** even when the table spans multiple pages. `_paginateBlocks()` shares a `tableStructAccum` array across all slices of the same table; the final slice commits it as `{ type: 'Table', children: tableStructAccum }`. Each `/TR` carries the correct `/StructParents` for its page so screen readers reconstruct the logical reading order correctly (ISO 14289-1 §7.10.6).

Repeated headers in `repeatHeader: true` mode are **not** re-emitted in the structure tree — they are visual continuations only. The single `/TR` for the header sits at the top of the `/Table` element.

---

## Tagged-mode + zebra

Zebra fills are decorative — they do not appear in the structure tree. PDF/UA conformance is preserved.

> ⚠️ **PDF/A-1b note.** PDF/A-1b forbids transparency (ISO 19005-1 §6.4). Zebra fills are opaque solid rectangles, so they are safe under PDF/A-1b, but **avoid combining zebra with `pdfa1b` watermarks** that rely on `/ExtGState`. Default `tagged: true` (PDF/A-2b) has no such restriction.

---

## Migration from v1.1.0

> **One unconditional fix.** Right- and centre-aligned **bold header** cells now use Helvetica-Bold metrics for width measurement (Adobe AFM), where pre-1.2.0 they were measured with Helvetica-Regular. This corrects a 2–5pt overshoot per cell that visually clipped the trailing glyph (e.g. the `t` in `Amount`). The fix shifts header glyph positioning by 2–5pt vs v1.1.0 — a genuine correctness improvement, not a regression. There is no opt-out.

| You want…                                       | Setting                                                                 |
| ----------------------------------------------- | ----------------------------------------------------------------------- |
| Exact byte-identical v1.1.0 multi-page _body_ output | `wrap: 'never', repeatHeader: false` (header positioning still corrected) |
| Modern default (recommended)                    | Omit all new fields — defaults are correct.                             |
| Invoice / report parity with commercial libs    | `wrap: 'auto', repeatHeader: true, zebra: true, caption: '…'`           |
| Uniform row heights regardless of content       | `wrap: 'always', minRowHeight: 18`                                      |
| Maximum information density                     | `wrap: 'auto', cellPadding: 2, minRowHeight: 10`                        |

---

## Samples shipped

Run `npm run test:generate` to produce:

- `test-output/document/table-wrap-auto.pdf` — wrap-on-overflow demo
- `test-output/document/table-multipage-header-repeat.pdf` — 60-row table across 2+ pages with repeated header
- `test-output/document/table-zebra-caption.pdf` — zebra + caption + min row height
- `test-output/document/table-smart-autofit.pdf` — `autoFit` columns + wrap

Generator: [scripts/generators/document-table-parity.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/document-table-parity.ts).

---

## Reference

- ISO 32000-1:2008 §9 — text rendering and positioning.
- ISO 14289-1:2014 §7.10.6 — tagged-PDF table structure (`/Table`, `/TR`, `/TH`, `/TD`, `/Caption`).
- ISO 19005-2:2011 — PDF/A-2b conformance.

### Internal contracts (for contributors)

- `planTable()` and `TableSlice` live in [src/core/pdf-renderers.ts](https://github.com/Nizoka/pdfnative/blob/main/src/core/pdf-renderers.ts). They are **not** re-exported from the package root. Treat them as internal — they may change without a major bump as long as the public `TableBlock` contract is preserved.
- Single-line row rendering uses `rowTop - rowH + 3` baseline for data and `rowTop - rowH + 4` for headers. These constants (`CELL_PAD_BOTTOM`, `HEADER_PAD_BOTTOM`) preserve byte-stability with v1.1.0 single-page output.
- The default `minRowHeight` (`12`) and default header height (`15`) match v1.1.0's `ROW_H` and `TH_H` constants exactly.

---

## See also

- [Architecture](architecture.md) — overall module layout.
- [PDF/A conformance](pdfa.md) — tagged-mode rules.
- [API reference](https://github.com/Nizoka/pdfnative/blob/main/README.md#api-reference) — full `TableBlock` type.

---
<!-- source: docs/guides/text-extraction.md -->
# Text extraction

> **New in v1.6.0.** Extract Unicode text from **any PDF** — including
> encrypted ones — with `extractText()`: per-page reading-order text plus
> optional positioned runs. Pure content-stream decoding, zero
> dependencies, no OCR engine, no rasterisation.

## TL;DR

```ts
import { extractText } from 'pdfnative';
import { readFileSync } from 'node:fs';

const bytes = readFileSync('report.pdf');

for (const page of extractText(bytes)) {
  console.log(`--- page ${page.pageIndex + 1} ---`);
  console.log(page.text);
}

// Encrypted documents: pass the password (decryption is transparent).
const secret = extractText(readFileSync('locked.pdf'), { password: 'hunter2' });

// Positioned runs for layout-aware consumers (search hit boxes, RAG chunking).
const [first] = extractText(bytes, { includeRuns: true, pages: [0] });
for (const run of first.runs ?? []) {
  console.log(run.text, `@ (${run.x.toFixed(1)}, ${run.y.toFixed(1)})`, run.fontSize);
}
```

## `extractText(bytes, options?)`

Returns one `ExtractedPageText` per requested page, in ascending page order:

```ts
interface ExtractTextOptions {
  password?: string;        // for encrypted documents (delegated to openPdf)
  pages?: number[];         // 0-based page indices; default: all pages
  includeRuns?: boolean;    // also return positioned runs (default false)
  maxTextLength?: number;   // hard cap on total characters (default 16 000 000)
}

interface ExtractedPageText {
  pageIndex: number;        // 0-based index in the source document
  text: string;             // reading-order text, '\n' between lines
  runs?: ExtractedTextRun[];// content-stream order, when includeRuns is true
}

interface ExtractedTextRun {
  text: string;             // decoded text of one show operation
  x: number; y: number;     // device-space origin of the run (points)
  fontSize: number;         // effective size (Tf size scaled by Tm × CTM)
  fontName: string;         // font resource name, e.g. 'F1'
}
```

## How text is decoded

For every shown string, the extractor resolves each character code in
this order:

| Source | Used for | Notes |
| --- | --- | --- |
| `/ToUnicode` CMap | any font that embeds one | `bfchar`, `bfrange` (both destination forms), surrogate pairs |
| `/Encoding /Differences` | simple fonts | glyph names resolved through a compact AGL subset + `uniXXXX` / `uXXXX[XX]` patterns |
| Base encoding | simple fonts | `WinAnsiEncoding` (CP-1252) or `MacRomanEncoding` tables |
| Fallback | no `/Encoding` at all | WinAnsi heuristic (covers pdfnative's own base-14 output and most western PDFs) |
| No mapping anywhere | — | U+FFFD `�` per code |

Type0 (CID) fonts are decoded as 2-byte codes (`Identity-H`/`Identity-V`),
mapped through their `/ToUnicode` CMap — which pdfnative's own CIDFont
output always embeds, so **pdfnative-generated documents round-trip
losslessly**, including CJK, Arabic, and emoji.

Since pdfnative **1.7.0** the `/ToUnicode` coverage is complete across both
builders: base-14 font dictionaries are reached under tagged mode and the
AcroForm `/Helv` dictionary carries a CMap in every mode — so base-14 text in
tagged documents and **text typed into form fields** now extract cleanly too.

## Reading order and runs

`page.text` is assembled geometrically: runs are grouped into lines by
baseline (tolerance scales with font size), lines are sorted top→bottom,
runs within a line left→right, and a space is inserted where a visible
horizontal gap separates two runs. Large negative `TJ` kerning
adjustments (≤ −180/1000 em) are treated as word spaces.

`page.runs` (opt-in) preserves **content-stream order** — useful when you
need the emitter's sequence rather than the geometric one. Positions are
device-space points: `Tm × CTM` is tracked through `q`/`Q`/`cm`, so
rotated and scaled content reports its true placement. Text inside Form
XObjects is extracted too (`Do` recursion, depth-capped).

## Encrypted documents

`extractText` rides on `openPdf`: RC4, AES-128 and AES-256 documents
decrypt transparently with `options.password`. A missing or wrong
password throws `PdfPasswordError`; a document with an empty user
password opens without one.

## Safety bounds

Designed to be safe on untrusted input:

- `maxTextLength` (default 16 M characters) hard-caps the total output —
  exceeding it throws rather than exhausting memory.
- Decompressed stream sizes are bounded by the parser's global inflate
  cap (`setMaxInflateOutputSize`).
- The interpreter is recursion-free with capped stacks (graphics state,
  operands, CMap entries, Form-XObject depth) and never throws on
  malformed content streams — unknown operators are skipped, unbalanced
  `BT`/`q` tolerated, inline images (`BI…EI`) byte-skipped.

## Limitations

By design (documented, not bugs):

- **No OCR** — image-only/scanned pages yield empty text.
- Type3 fonts are decoded via their encoding/`ToUnicode` only (glyph
  procedures are not interpreted).
- Non-Identity CMap `/Encoding`s (e.g. predefined UTF-16 CJK CMaps) are
  decoded best-effort as 2-byte codes through `/ToUnicode`.
- Vertical writing mode is treated as horizontal.
- The structure tree / `/ActualText` is not consulted — order is
  geometric, and ligature reversal is only as good as the embedded
  `/ToUnicode`. In practice this means **shaped Indic scripts**
  (Devanagari, Bengali, Tamil, Telugu, Sinhala, …) extract with U+FFFD
  for conjunct/ligature glyphs that have no single-codepoint mapping —
  the PDF *renders* correctly; only extraction of those clusters is
  lossy. Latin, CJK, Arabic and emoji round-trip cleanly.

## Samples

Generated by `npm run test:generate`:

- `parser/text-extract-source.pdf` — a rich source document.
- `parser/text-extract-report.pdf` — its extraction rendered back to PDF
  (text + positioned-run table).
- `parser/text-extract-encrypted-report.pdf` — AES-256 encrypted source,
  extracted with a password.

## See also

- [PDF manipulation](pdf-manipulation.html) — merge / split / extract pages.
- [Form filling](form-filling.html) — read and fill AcroForm fields.
- [Debugging & layout inspection](debugging.html) — geometry the writer
  side reports.

---
<!-- source: docs/guides/troubleshooting.md -->
# Troubleshooting

> **Symptom-first fixes for the classic failures** — tofu boxes (a font registered but never loaded), RTL text appearing backwards, oversized files, PDF/A validation errors, parser rejections — each with the check that identifies it and the change that fixes it.

## Font Not Rendering (Boxes or Blank)

**Symptom:** Non-Latin text shows as empty rectangles or missing glyphs.

**Cause:** The font for that script is not registered or not loaded.

**Fix:**
```typescript
import { registerFonts, loadFontData } from 'pdfnative';

// 1. Register font loaders (lazy — no data loaded yet)
registerFonts({
  th: () => import('pdfnative/fonts/noto-thai-data.js'),
  ar: () => import('pdfnative/fonts/noto-arabic-data.js'),
});

// 2. Load font data when needed
const thaiFont = await loadFontData('th');

// 3. Pass fontEntries to your builder
const pdf = buildDocumentPDFBytes({
  blocks: [{ type: 'paragraph', text: 'สวัสดี' }],
  fontEntries: [{ fontData: thaiFont!, fontRef: '/F3', lang: 'th' }],
});
```

## PDF File Too Large

**Symptom:** Output PDF is unexpectedly large (>1 MB for text content).

**Causes & fixes:**

1. **Enable compression:**
   ```typescript
   buildPDFBytes(params, { compress: true });
   ```
   FlateDecode typically reduces size by 50–90%.

2. **Initialize native compression (Node.js):**
   ```typescript
   import { initNodeCompression } from 'pdfnative';
   await initNodeCompression();
   ```
   Without this, a stored-block fallback is used (minimal compression).

3. **Large images:** JPEG is already compressed (DCTDecode). For PNG, the raw pixels are FlateDecode-compressed. Use JPEG for photos.

4. **Font subsetting:** Automatic — only used glyphs are embedded. If you're embedding many scripts, each adds a font subset.

## RTL Text Backwards

**Symptom:** Arabic or Hebrew text appears in logical order instead of visual (right-to-left) order.

**Cause:** Font entries must include the correct `lang` property for BiDi detection.

**Fix:**
```typescript
const fontEntries = [
  { fontData: arabicFont, fontRef: '/F3', lang: 'ar' },
  { fontData: hebrewFont, fontRef: '/F4', lang: 'he' },
];
```

The `lang` property triggers:
- BiDi run detection (`containsRTL()`)
- Arabic positional shaping (GSUB forms)
- Glyph mirroring for brackets and other paired delimiters (the full 428-pair
  Unicode BidiMirroring table since v1.7.0, per UAX #9 rule L4)

**Reversed digits or backwards parentheses in RTL text?** Fixed in v1.7.0 with
no API change: digit runs now take even embedding levels (UAX #9 rules I1/I2),
so a number like `1405` keeps its digit order instead of rendering `5041`, and
rule L4 mirrors delimiters during reversal, so a logical `(X)` no longer
renders `)X(`. If you see either symptom, upgrade pdfnative.

## PDF/A Validation Fails

**Symptom:** veraPDF reports non-conformance.

**Common issues:**

1. **Missing tagged mode:**
   ```typescript
   buildPDFBytes(params, { tagged: true }); // PDF/A-2b
   // or
   buildPDFBytes(params, { tagged: 'pdfa1b' }); // PDF/A-1b
   ```

2. **PDF/A + encryption conflict:** ISO 19005-1 §6.3.2 forbids encryption in PDF/A. Use one or the other.

3. **Transparency in PDF/A-1b:** Watermarks with opacity < 1.0 are blocked in PDF/A-1b (ISO 19005-1 §6.4). Use PDF/A-2b or remove transparency.

## "Document has too many blocks" / Very Large Documents

**Symptom:** Generating a multi-thousand-page report throws a "too many blocks" error.

**Cause:** The document builder caps the number of content blocks as a safety rail. Before v1.3.0 this was a hard-coded 10 000. As of **v1.3.0** the default is **100 000** and is configurable.

**Fix:** raise the limit via the layout option:

```typescript
buildDocumentPDFBytes(params, { maxBlocks: 500000 });
// also honoured by the streaming builders:
buildDocumentPDFStream(params, { maxBlocks: 500000 }, { chunkSize: 65536 });
```

For very large outputs, prefer the streaming builders (`buildDocumentPDFStream`, or `buildDocumentPDFStreamTrue` for constant memory) so the full binary never has to sit in memory at once.

## Parser Fails on External PDF

**Symptom:** `openPdf()` throws on a PDF file not generated by pdfnative.

**Common causes:**

1. **Encrypted PDF opened without a password:** Since v1.6.0 the parser decrypts the Standard Security Handler (RC4 V1-V4, AES-128, AES-256 R6) — but it needs the password. Call `openPdf(bytes, { password })`. Without one you get `PdfPasswordError`; with an algorithm the handler does not cover, `PdfEncryptionUnsupportedError`.
2. **Linearized PDF:** The parser follows standard xref/trailer. Linearized hint tables may cause offset issues.
3. **Non-standard formatting:** Some PDF generators produce non-compliant output. The parser follows ISO 32000-1 strictly.

## Build / Import Issues

**ESM import paths:**
```typescript
// Bare package import — no extension involved
import { buildPDFBytes } from 'pdfnative';

// Font data modules — the .js extension IS required here (ESM subpath),
// and the modules only have named exports, so use a namespace import:
import * as thaiData from 'pdfnative/fonts/noto-thai-data.js';
```

**Browser vs Node.js:** The library works in both environments. For compression in Node.js, call `initNodeCompression()` once at startup.

---
<!-- source: docs/guides/use-cases.md -->
# Ecosystem use cases

> **Four production architectures, each built from parts the ecosystem already
> ships.** Store a kilobyte of JSON instead of a megabyte of PDF and render on
> the reader's own device; sign to PAdES B-LTA across an air gap; gate template
> changes in CI with a real document diff; and serve edge-rendered PDFs with
> honest HTTP caching. Every arrow in the diagrams below is a public, shipped
> API — nothing here is aspirational.

The [capability × surface matrix](choose.html) tells you *what* each surface
can do; this guide shows *how the surfaces compose* into systems. Each case
names its exact building blocks, shows the load-bearing code, and states its
limits.

## Case 1 — Store the spec, not the PDF

A typical generated PDF weighs hundreds of kilobytes — most of it embedded
fonts and compressed streams that are **recomputed identically on every
render**. The document's actual information content is the text and structure,
which fits in a few kilobytes of JSON. So: persist the compact
[`DocSpec`](react.html#agent-authoring--the-token-frugal-docspec) (or a
`DocumentParams` JSON), and let the device that *asks* for the PDF produce it.

![Architecture: a server stores kilobyte-sized DocSpec JSON documents in a database instead of megabyte-sized PDFs in object storage. When a client requests a document, the server sends the JSON; the client's own browser renders it to a PDF locally with pdfnative-react and the zero-dependency pdfnative engine — uncompressed by default, or compressed by plugging a synchronous deflate implementation into setDeflateImpl. Storage shrinks by roughly two orders of magnitude and the PDF bytes never transit the network.](../assets/use-case-spec-storage.svg)

Why this works in a browser at all: the engine has **zero dependencies and no
Node-only code paths** on this route. Rendering is synchronous and the output
is a valid, uncompressed PDF — and since the bytes stay on the device, their
size costs nothing on the wire.

```tsx
// On the reader's device — nothing but the two packages and React.
import { renderSpecToBytes, downloadBlob } from 'pdfnative-react';

const spec = await fetch(`/api/documents/${id}`).then((r) => r.json()); // ~2 KB
const bytes = renderSpecToBytes(spec);       // rendered locally, synchronously
downloadBlob(bytes, 'invoice.pdf');          // builds the Blob itself
```

Want compressed output too? `setDeflateImpl` accepts a **synchronous** deflate
function whose result is written into the file verbatim, so it must produce a
**zlib-wrapped (RFC 1950)** stream — `/FlateDecode` is zlib per ISO 32000-1
§7.3.8. The browser's `CompressionStream` cannot be plugged in (it is
asynchronous by nature); a tiny synchronous library can:

```tsx
import { zlibSync } from 'fflate';           // synchronous, zlib-wrapped output
import { setDeflateImpl, renderSpecToBytes } from 'pdfnative-react';

setDeflateImpl((bytes) => zlibSync(bytes));
const compressed = renderSpecToBytes({ ...spec, layout: { ...spec.layout, compress: true } });
```

What you gain, concretely:

- **Storage** — a 2 KB spec versus a 300 KB PDF is a ~150× reduction, before
  database compression. A million archived invoices stop being a storage line
  item.
- **Bandwidth and latency** — the payload that crosses the network is the JSON,
  not the PDF.
- **Diffability** — specs are plain data: version them, diff them, patch a
  typo without a byte-level regeneration pipeline.
- **Re-branding for free** — yesterday's specs render with today's template
  and fonts.

Honest limits: the client re-renders with the engine version it has, so a spec
is **not a byte-frozen archival artefact** — for documents that must never
change (or that carry signatures), render once and archive the bytes (see
Case 2). Non-Latin scripts need their font modules delivered to the client
(each is a lazily imported module; ship only what the spec's languages need).
The engine renders identical bytes for identical input *on the same version* —
pin the engine when reproducibility matters.

## Case 2 — Air-gapped PAdES B-LTA archiving

Long-term signature validation has a paradox: the evidence that keeps a
signature verifiable for decades (OCSP responses, CRLs, timestamps) comes from
the network — but the most sensitive signing environments are exactly the ones
with no network. CLI 1.4.0 resolves it by splitting the ladder: **evidence is
collected as replayable JSON on a connected machine, and embedded fully
offline inside the enclave**.

![Architecture: two network zones. In the connected zone, a machine runs pdfnative sign with the PAdES profile and an RFC 3161 timestamp URL, reaching PAdES B-T, then ltv collect with the online opt-in gathers OCSP responses and CRLs into a replayable ltv-data.json file. Only that JSON file crosses the controlled transfer boundary into the air-gapped enclave, where ltv embed writes the evidence into the PDF's DSS dictionary with no network access, reaching B-LT, and doc-timestamp appends a document-timestamp revision for B-LTA on the way out through the gateway.](../assets/use-case-airgap-ltv.svg)

```bash
# Connected zone — sign with a timestamp (B-T), then gather the evidence.
pdfnative sign --input contract.pdf --output signed.pdf \
  --profile pades \                                    # ETSI.CAdES.detached
  --timestamp https://tsa.example.com/rfc3161          # RFC 3161, SSRF-guarded
pdfnative ltv collect --input signed.pdf --online --output ltv-data.json

# ── controlled transfer of ltv-data.json across the air gap ──

# Enclave — no network I/O is even possible in `embed`, by design.
pdfnative ltv embed --input signed.pdf --data ltv-data.json --output signed.lt.pdf

# Gateway (network) — cap the ladder with a document timestamp (B-LTA).
pdfnative doc-timestamp --input signed.lt.pdf \
  --url https://tsa.example.com/rfc3161 --output signed.lta.pdf

# Anywhere, later — verify the whole ladder offline from the embedded /DSS.
pdfnative verify --input signed.lta.pdf --strict --revocation offline
```

`--profile pades` is not optional here: the default is `pkcs7`, which writes
`/SubFilter /adbe.pkcs7.detached` — a valid CMS signature, but not an
ETSI EN 319 142-1 baseline, so the whole B-T → B-LTA ladder would sit on a
non-PAdES foundation.

The evidence file is versioned JSON (`pdfnative schema ltv-data`) with DER
payloads as base64 — auditable before it crosses the boundary, replayable if
the embed step must be re-run. Every network touch on the connected side is an
explicit per-invocation opt-in behind an SSRF guard (http/https only, private
addresses blocked, no redirects). Years later, run `doc-timestamp` again to
renew the protection before the TSA certificate expires — earlier revisions
stay byte-identical.

Honest limits: `ltv embed` trusts the evidence it is given — the transfer
process, not the tool, is what makes the air gap meaningful. The MCP surface
offers the same ladder (`add_ltv`, `timestamp_pdf`) with operator-configured
transport instead; the React renderer deliberately does not sign (post-process
its output with the CLI or the library).

## Case 3 — A document-regression gate in CI

Templates drift. A dependency bump changes a wrap point, a copy edit pushes a
table onto page 3, a refactor silently drops the footer — and nobody notices
until a customer does, because PDFs in CI are write-only artefacts nobody
opens. CLI 1.4.0's `compare` turns them into asserted artefacts: **exit 0 when
the golden and the candidate agree, exit 1 with a diff report when they do
not**.

![Architecture: a CI pipeline triggered by a pull request renders the changed template to a candidate PDF with render using the strict PDF/A gate, then runs pdfnative compare between the committed golden PDF and the candidate. Identical documents exit 0 and the check passes; differences print a text-and-structure report and exit 1, failing the pull request. An optional veraPDF step validates the PDF/A claim, and an approved change promotes the candidate to become the new golden file.](../assets/use-case-ci-gate.svg)

```yaml
# .github/workflows/documents.yml
- name: Render candidate (hard-fail on PDF/A diagnostics)
  run: pdfnative render --input templates/invoice.json \
         --output out/candidate.pdf --tagged pdfa2b --strict

- name: Diff against the golden file
  run: pdfnative compare golden/invoice.pdf out/candidate.pdf \
         --mode both --ignore-whitespace --format json
  # identical → exit 0 · different → report on stdout, then exit 1 / E_CHECK_FAILED
```

The `both` mode diffs the extracted reading-order text **and** the declared
structure — page count, page and print boxes, metadata, form fields,
annotations, encryption, signatures — with a `--tolerance` in points for
geometry. `render --strict` upgrades PDF/A diagnostics (an unembedded form
font, a DeviceCMYK image under the wrong profile) from warnings to a failed
build *before the first output byte*. When a change is intentional, promoting
the candidate to golden is a one-line copy in the same PR.

Honest limits: `compare` is **not a visual diff** — pdfnative has no
rasteriser, so pixel-level rendering changes that alter neither text nor
structure pass; pair it with an external rasteriser if that matters to you.
Note that engine upgrades can legitimately change bytes without changing
content (the diff compares content, not bytes — which is exactly why it works
across engine versions where a checksum would not).

## Case 4 — Edge-rendered PDFs with honest HTTP caching

Rendering PDFs in a central service means queues, SaaS round-trips, or a
container with a headless browser. The engine's zero-dependency, Fetch-native
design removes the constraint: `renderToResponse` returns a web-standard
`Response`, so the same code runs in a Next.js route handler, Cloudflare
Workers, Deno Deploy or Bun — and since pdfnative-react 1.2.0 it speaks real
HTTP caching.

![Architecture: browsers request a PDF from an edge or serverless runtime. The handler calls renderToResponse from pdfnative-react, which streams the PDF with constant memory and sets Cache-Control and a strong ETag derived from the rendered bytes. The CDN in front caches the response; repeat requests are served from cache, and revalidation requests answered with 304 Not Modified cost no render at all. No central PDF service, no headless browser, no SaaS round-trip.](../assets/use-case-edge-cache.svg)

```tsx
// app/invoice/[id]/route.tsx — identical on Workers / Deno / Bun.
import { renderToResponse } from 'pdfnative-react';

export async function GET(_req: Request, { params }: { params: { id: string } }) {
  const data = await loadInvoice(params.id);
  return renderToResponse(<Invoice data={data} />, {
    fileName: `invoice-${params.id}.pdf`,
    cacheControl: 'public, max-age=300, s-maxage=86400',
    etag: true, // strong validator derived from the rendered bytes
  });
}
```

`cacheControl` is emitted verbatim, so the CDN tier does the heavy lifting;
`etag: true` derives a strong validator from the actual bytes, so conditional
requests revalidate correctly and a `304 Not Modified` costs no render.
Streamability is validated **before the first byte** — a document that cannot
stream (a table of contents, `{pages}` placeholders) fails up-front instead of
mid-response with the headers already sent.

Honest limits: `etag: true` must buffer the response to hash it — for very
large documents choose either streaming (constant memory, no strong ETag) or
the buffered validator, not both. A per-user document should say
`private` in its `Cache-Control`, and remember the PDF inherits whatever
authorisation bug the route has — cache keys must include whatever
distinguishes users.

## Picking parts, not a platform

The four cases share one property: each is assembled from surfaces that also
work alone, so none of them locks you in. The specs of Case 1 render fine
server-side the day you need a byte archive; the golden files of Case 3 are
ordinary PDFs any tool can open; the ladder of Case 2 verifies in Adobe
Acrobat, not just in `pdfnative verify`. Start with the case closest to your
bottleneck and borrow pieces from the others as they become relevant.

## See also

- [Choosing your surface](choose.html) — the capability × surface matrix
  behind every arrow above.
- [Long-term validation](ltv.html) — the PAdES ladder in engine terms.
- [Self-verifying generation](self-verify.html) — the assert-your-own-output
  loop that pairs naturally with Case 3.
- [React guide](react.html) — `DocSpec`, rendering entry points and the
  1.2.0 HTTP caching options.
- [CLI guide](cli.html) — the complete v1.4.0 command reference.

---
<!-- source: docs/guides/viewer-preferences.md -->
# Viewer preferences

> **New in v1.4.0.** Control how a conforming reader **presents** your PDF the
> moment it opens — initial page layout, the bookmark/thumbnail panel, full-screen
> kiosk mode, window fit/centering, UI-chrome visibility, reading direction, and
> print scaling. Set via `DocumentParams.layout.viewerPreferences`. Purely
> presentational, PDF/A-safe, and zero overhead when unused.

## TL;DR

```ts
import { buildDocumentPDFBytes } from 'pdfnative';
import type { ViewerPreferences } from 'pdfnative';

const viewerPreferences: ViewerPreferences = {
  pageLayout: 'twoColumnLeft',  // continuous two-up, odd pages left
  pageMode: 'useOutlines',      // open the bookmark panel
  displayDocTitle: true,        // titlebar shows /Info /Title, not the filename
  fitWindow: true,
  centerWindow: true,
};

const bytes = buildDocumentPDFBytes({
  title: 'Annual Report',
  blocks: [/* … */],
  outline: 'auto',
  layout: { viewerPreferences },
});
```

## Page layout (`/PageLayout`)

How pages are arranged in the viewport:

| Value | Behaviour |
|---|---|
| `singlePage` | One page at a time |
| `oneColumn` | Continuous single column |
| `twoColumnLeft` / `twoColumnRight` | Continuous two columns; odd pages on the left / right |
| `twoPageLeft` / `twoPageRight` | Two pages at a time; odd pages on the left / right |

## Page mode (`/PageMode`)

Which panel (if any) is open and whether the document opens full-screen:

| Value | Behaviour |
|---|---|
| `useNone` | Neither bookmarks nor thumbnails |
| `useOutlines` | Bookmark panel open |
| `useThumbs` | Thumbnail panel open |
| `fullScreen` | Full-screen presentation, no menu/panel |
| `useOC` | Optional-content (layers) panel |
| `useAttachments` | Attachments panel |

An explicit `pageMode` **overrides** the `/UseOutlines` default that a document
automatically gets when it has an `outline`.

## ViewerPreferences flags

| Field | Effect |
|---|---|
| `hideToolbar` | Hide the reader tool bars |
| `hideMenubar` | Hide the menu bar |
| `hideWindowUI` | Hide scrollbars / navigation, leaving only the page |
| `fitWindow` | Resize the window to the first page |
| `centerWindow` | Centre the window on screen |
| `displayDocTitle` | Show `/Info /Title` in the titlebar instead of the filename |
| `nonFullScreenPageMode` | Mode to use after exiting full-screen |
| `direction` | `'l2r'` (default) or `'r2l'` reading order |
| `printScaling` | `'none'` or `'appDefault'` print-dialog default |
| `duplex` | `'simplex'`, `'duplexFlipShortEdge'` or `'duplexFlipLongEdge'` print-dialog default (v1.7.0) |
| `pickTrayByPDFSize` | Select the paper tray from the PDF page size (v1.7.0) |
| `printPageRange` | Default print range as 1-based `[from, to]` pairs (v1.7.0) |
| `numCopies` | Default copy count in the print dialog (v1.7.0) |

The four print-dialog defaults ship with v1.7.0's print-production support —
see the [print production guide](print.html) for bleed/trim boxes, printer's
marks and `/Trapped`.

## Full-screen kiosk

```ts
const viewerPreferences: ViewerPreferences = {
  pageMode: 'fullScreen',
  nonFullScreenPageMode: 'useThumbs',
  hideToolbar: true,
  hideMenubar: true,
  direction: 'r2l',
  printScaling: 'none',
};
```

## PDF/A note

Viewer preferences are metadata only — no transparency, no scripting — so they
are safe to combine with any PDF/A conformance level. Sample generators:
[viewer-prefs-showcase.ts](https://github.com/Nizoka/pdfnative/blob/main/scripts/generators/viewer-prefs-showcase.ts).