pdfnative 1.0.5 → 1.2.0

package/README.md

@@ -15,6 +15,24 @@
 
 Pure native PDF generation library — zero vendor dependencies. ISO 32000-1 (PDF 1.7) compliant.
 
+## Ecosystem
+
+pdfnative ships as three coordinated packages — pick whichever entry point fits your workflow:
+
+| Package | Latest | Use it for |
+|---|:---:|---|
+| [`pdfnative`](https://www.npmjs.com/package/pdfnative) | **v1.2.0** | The library itself — call from Node, browsers, Workers, Deno, Bun. |
+| [`pdfnative-cli`](https://www.npmjs.com/package/pdfnative-cli) | **v0.3.0** | Render JSON → PDF, sign (RSA + ECDSA-SHA256, RFC 3161 detection), inspect, and verify CMS signatures from the shell. New in v0.3.0: `--watch`, `--template`, `--font {latin,emoji}`, auto signature placeholder. |
+| [`pdfnative-mcp`](https://www.npmjs.com/package/pdfnative-mcp) | **v0.3.0** | Use pdfnative from Claude Desktop, Cursor, Continue, Zed (or any stdio MCP client) — **9 structured tools** including the new `inspect_pdf`, a `pdfA` flag on every doc tool, multi-script `lang`, and per-tool `outputSchema` (MCP 2025-06-18). |
+
+```bash
+npm install pdfnative                 # library
+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) · [Onboarding cheatsheet](docs/guides/onboarding.md).
+
 ## Highlights
 
 - **Zero dependencies** — built from scratch in pure TypeScript. Zero runtime dependencies, tree-shakeable, auditable
@@ -22,17 +40,19 @@ Pure native PDF generation library — zero vendor dependencies. ISO 32000-1 (PD
 - **16 Unicode scripts** — Thai, Japanese, Chinese (SC), Korean, Greek, Devanagari, Turkish, Vietnamese, Polish, Arabic, Hebrew, Cyrillic, Georgian, Armenian, Bengali, Tamil
 - **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** — simplified Unicode Bidirectional Algorithm (UAX #9) with glyph mirroring
+- **BiDi text layout** — Unicode Bidirectional Algorithm (UAX #9) with glyph mirroring, isolates (LRI/RLI/FSI/PDI), and explicit embeddings (LRE/RLE/LRO/RLO/PDF)
+- **USE-lite cluster classifier** — public API (`classifyUseCategory`, `classifyClusters`) with per-script tables for Devanagari, Bengali, Tamil (v1.2.0; shaper rewire lands in v1.3)
 - **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)
 - **PDF Encryption** — AES-128 (V4/R4) and AES-256 (V5/R6), owner + user passwords, granular permissions
 - **Free-form document builder** — headings, paragraphs, lists, tables, images, barcodes, SVG paths, form fields, spacers, page breaks, table of contents
+- **Smart tables** — multi-page slicing with repeated headers, auto-wrap on column overflow, zebra striping, captions, and smart auto-fit columns (v1.2.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 path rendering** — path, rect, circle, ellipse, line, polyline, polygon as native PDF operators
 - **AcroForm fields** — text, multiline, checkbox, radio, dropdown, listbox with appearance streams (ISO 32000-1 §12.7)
-- **Digital signatures** — CMS/PKCS#7 detached signatures with RSA + ECDSA, SHA-256/384/512, X.509 parsing (ISO 32000-1 §12.8)
-- **Streaming output** — AsyncGenerator-based progressive PDF emission with configurable chunk size
+- **Digital signatures** — CMS/PKCS#7 detached signatures with RSA + ECDSA, SHA-256/384/512, X.509 parsing (ISO 32000-1 §12.8). One-call placeholder injection via `addSignaturePlaceholder()` (v1.2.0)
+- **Streaming output** — AsyncGenerator-based progressive PDF emission with configurable chunk size, plus object-boundary page-by-page streaming (`buildPDFStreamPageByPage()`, v1.2.0)
 - **PDF parser & modifier** — read existing PDFs (tokenizer, xref, object parser, FlateDecode inflate) + incremental modification
 - **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
@@ -42,7 +62,7 @@ Pure native PDF generation library — zero vendor dependencies. ISO 32000-1 (PD
 - **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
-- **95%+ test coverage** — 1588+ tests across 40 files, fuzz suite, performance benchmarks
+- **95%+ test coverage** — 1822+ tests across 53 files, fuzz suite, performance benchmarks
 - **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
@@ -181,6 +201,11 @@ registerFonts({
   hy: () => import('pdfnative/fonts/noto-armenian-data.js'),
   bn: () => import('pdfnative/fonts/noto-bengali-data.js'),
   ta: () => import('pdfnative/fonts/noto-tamil-data.js'),
+  // 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');
@@ -212,6 +237,8 @@ const pdf = buildPDFBytes({
 | 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)
 
@@ -369,7 +396,7 @@ Generate sample PDFs for all supported languages to visually verify output:
 npm run test:generate
 ```
 
-This creates **140+ PDF files** in `test-output/` (git-ignored), organized in twenty-three categories.
+This creates **150+ PDF files** in `test-output/` (git-ignored), organized in twenty-five categories (including `emoji/` and `pdfa-latin/` added in v1.1.0).
 See [scripts/README.md](scripts/README.md) for the modular generator architecture.
 
 ### Financial Statements (per language)
@@ -814,24 +841,39 @@ pdfnative ships as a library, but two official companion packages cover the most
 
 ### pdfnative-cli — command-line interface
 
-[`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) is the **official CLI**. It exposes three commands — `render`, `sign`, `inspect` — for use in shell scripts, Makefiles, GitHub Actions, and Docker images. Zero extra runtime dependencies, npm-provenance-signed.
+[`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) v0.3.0 is the **official CLI**. It exposes four commands — `render`, `sign`, `inspect`, **`verify`** — covering the full `pdfnative` v1.1.0 surface for use in shell scripts, Makefiles, GitHub Actions, and Docker images. Zero extra runtime dependencies, npm-provenance-signed.
 
-```bash
-# render a JSON document spec to PDF
-npx pdfnative-cli render document.json --output report.pdf
+**New in v0.3.0:** ECDSA-SHA256 (P-256) signing fully wired, real CMS/PKCS#7 verification with RFC 3161 timestamp detection, automatic signature-placeholder injection on `sign`, plus three iteration-friendly `render` flags (`--watch`, `--template`, `--font {latin,emoji}`). **100 % backward-compatible** with v0.2.0.
 
-# sign an existing PDF (RSA or ECDSA, CMS/PKCS#7)
-npx pdfnative-cli sign report.pdf --cert cert.pem --key key.pem --output signed.pdf
+**Previously (v0.2.0):** hybrid `flags + --layout file.json` model, encryption (AES-128/256), watermarks (text + image), header/footer page templates with `{page}/{pages}/{date}/{title}`, PDF/A-3 attachments (Factur-X / ZUGFeRD pattern), multilingual fonts via `--lang`, table-variant rendering, signing metadata + intermediate cert chains, `inspect --verbose/--pages/--check`, and the `verify` command.
 
-# inspect a PDF (page count, metadata, fonts, signatures)
-npx pdfnative-cli inspect signed.pdf
+```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)
+npx pdfnative-cli verify --input signed.pdf --strict --trust ca-root.pem
+
+# inspect with CI assertions (exit 1 on failure)
+npx pdfnative-cli inspect --input signed.pdf \
+  --check pdfa --check signed --format json
 ```
 
-See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for full reference, security model, and pipeline examples.
+See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for the full v0.3.0 reference, security model, recipes, and the `--conformance` → `--tagged` migration path. 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) is a **Model Context Protocol server** that bridges pdfnative to any MCP-compatible AI client. Once configured, your AI assistant can generate PDFs, embed barcodes, create forms, sign documents, and render international text — all without writing code.
+[`pdfnative-mcp`](https://github.com/Nizoka/pdfnative-mcp) v0.3.0 is a **Model Context Protocol server** that bridges pdfnative to any MCP-compatible AI client. Once configured, your AI assistant can generate PDFs, embed barcodes, create forms, sign documents, render international text, and **inspect** existing PDFs — all without writing code.
+
+**New in v0.3.0:** `inspect_pdf` (the 9th tool, structured metadata/page/signature/PDF/A report), `pdfA` flag on every document tool, multi-script `lang` (`string | string[] | csv`) with bundled `latin` + `emoji` codes, `add_table` `autoFitColumns`/`clipCells`, and per-tool `outputSchema` per the MCP 2025-06-18 spec.
 
 ```bash
 npx -y pdfnative-mcp
@@ -842,13 +884,14 @@ npx -y pdfnative-mcp
 | Tool | Purpose |
 |------|---------|
 | `generate_basic_pdf` | Multi-page documents from structured blocks (headings, paragraphs, lists) |
-| `add_table` | Tabular reports from column headers and data rows |
+| `add_table` | Tabular reports from column headers and data rows (v0.3.0: `autoFitColumns`, `clipCells`) |
 | `add_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 |
-| `add_international_text` | 16 non-Latin scripts with BiDi & OpenType shaping |
+| `add_international_text` | 16 non-Latin scripts with BiDi & OpenType shaping (v0.3.0: multi-script `lang`) |
 | `add_form` | Interactive AcroForm PDFs (text, checkbox, radio, dropdown) |
 | `embed_image` | Embed a JPEG or PNG image (base64) |
 | `prepare_signature_placeholder` | PDF with a `/Sig` field ready to be signed |
 | `sign_pdf` | CMS/PKCS#7 digital signatures (RSA-SHA256 / ECDSA-SHA256) |
+| `inspect_pdf` | **New in v0.3.0** — structured PDF report (metadata, pages, signatures, PDF/A) |
 
 ### Claude Desktop configuration
 
@@ -931,7 +974,7 @@ src/
 fonts/                    # Pre-built font data modules (16 scripts)
 tools/                    # CLI: build-font-data.cjs (TTF → JS module)
 scripts/                  # Modular sample PDF generation (23 generators, 140+ PDFs)
-tests/                    # 1588+ tests (40 files: unit + integration + fuzz + parser)
+tests/                    # 1726+ tests (48 files: unit + integration + fuzz + parser)
 bench/                    # Performance benchmarks (vitest bench)
 ```
 
@@ -945,7 +988,7 @@ npm install
 npm run build            # tsup → dist/ (ESM + CJS + .d.ts)
 npm run test             # vitest run (1588+ tests)
 npm run test:coverage    # vitest with v8 coverage (95%+)
-npm run test:generate       # Generate 140+ sample PDFs → test-output/
+npm run test:generate       # Generate 150+ 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
@@ -1010,17 +1053,26 @@ When `tagged` is set, the output includes:
 
 The `tagged` option is backward-compatible — omitting it or setting `false` produces the same output as before.
 
-> **PDF/A status (v1.0.4).** As of v1.0.4 every PDF emits a trailer
-> `/ID` and the `/Info CreationDate` is byte-equivalent to the
-> `xmp:CreateDate` (with timezone offset) — closing two veraPDF
-> reference-validator findings. **Latin font embedding** is **not yet
-> implemented**: standard 14 Helvetica is still emitted as an
-> unembedded reference, which veraPDF flags under ISO 19005-1 §6.3.4.
-> Treat the `pdfaid:part` claim in XMP as aspirational until **v1.0.5**
-> lands. See [docs/guides/pdfa.html](docs/guides/pdfa.html) and the
-> tracking issue [release-notes/draft-issue-v1.0.5-latin-embedding.md](release-notes/draft-issue-v1.0.5-latin-embedding.md).
-> Run `npm run validate:pdfa` locally (with veraPDF installed) to
-> verify against the reference validator.
+> **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 ✅