pdfnative 1.0.4 → 1.1.0

package/README.md

@@ -10,6 +10,8 @@
 [![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)
 
 Pure native PDF generation library — zero vendor dependencies. ISO 32000-1 (PDF 1.7) compliant.
 
@@ -44,6 +46,8 @@ Pure native PDF generation library — zero vendor dependencies. ISO 32000-1 (PD
 - **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)
+- **Command-line interface** — render, sign, and inspect PDFs from the shell with [`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) — zero-config, scriptable, ideal for CI/CD pipelines
 
 ## Installation
 
@@ -177,6 +181,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');
@@ -208,6 +217,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)
 
@@ -365,7 +376,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)
@@ -804,6 +815,77 @@ const pdf = buildPDFBytes(params, { compress: true });
 | `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 two official companion packages cover the most common non-library use cases. Both live in separate repositories and depend on `pdfnative` only through the public API.
+
+### pdfnative-cli — command-line interface
+
+[`pdfnative-cli`](https://github.com/Nizoka/pdfnative-cli) v0.2.0 is the **official CLI**. It exposes four commands — `render`, `sign`, `inspect`, **`verify`** — covering the full `pdfnative` v1.0.5 surface for use in shell scripts, Makefiles, GitHub Actions, and Docker images. Zero extra runtime dependencies, npm-provenance-signed.
+
+**Highlights (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 a brand-new `verify` command for byte-range integrity and certificate-chain validation. **100 % backward-compatible** with v0.1.0.
+
+```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 the full v0.2.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.
+
+```bash
+npx -y pdfnative-mcp
+```
+
+### Available tools
+
+| 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_barcode` | QR Code, Code 128, EAN-13, Data Matrix, PDF417 |
+| `add_international_text` | 16 non-Latin scripts with BiDi & OpenType shaping |
+| `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) |
+
+### Claude Desktop configuration
+
+```json
+{
+  "mcpServers": {
+    "pdfnative": {
+      "command": "npx",
+      "args": ["-y", "pdfnative-mcp"],
+      "env": {
+        "PDFNATIVE_MPC_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.
+
 ## Architecture
 
 ```
@@ -867,7 +949,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)
 ```
 
@@ -881,7 +963,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
@@ -946,17 +1028,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 ✅