pdfnative 1.0.3 → 1.0.5

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.
 
@@ -42,6 +44,10 @@ Pure native PDF generation library — zero vendor dependencies. ISO 32000-1 (PD
 - **Tree-shakeable** — ESM + CJS dual build with TypeScript declarations
 - **95%+ test coverage** — 1588+ tests across 40 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
+- **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
 
@@ -802,6 +808,66 @@ 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) 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.
+
+```bash
+# render a JSON document spec to PDF
+npx pdfnative-cli render document.json --output report.pdf
+
+# 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
+
+# inspect a PDF (page count, metadata, fonts, signatures)
+npx pdfnative-cli inspect signed.pdf
+```
+
+See the [CLI Guide](https://pdfnative.dev/guides/cli.html) for full reference, security model, and pipeline examples.
+
+### 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
 
 ```
@@ -944,6 +1010,18 @@ 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 Encryption — Implemented ✅
 
 AES-128 and AES-256 encryption with owner/user passwords and granular permissions:

package/dist/index.cjs

@@ -4623,9 +4623,26 @@ function buildStructureTree(root, startObjNum, pageObjToStructParents) {
     totalObjects: nextObj - startObjNum
   };
 }
-function buildXMPMetadata(title, createDate, pdfaPart = 2, pdfaConformance = "B") {
+function buildPdfMetadata(now = /* @__PURE__ */ new Date()) {
+  const pad2 = (n) => String(n).padStart(2, "0");
+  const yyyy = now.getFullYear();
+  const mm = pad2(now.getMonth() + 1);
+  const dd = pad2(now.getDate());
+  const hh = pad2(now.getHours());
+  const mi = pad2(now.getMinutes());
+  const ss = pad2(now.getSeconds());
+  const tzMinutes = -now.getTimezoneOffset();
+  const tzSign = tzMinutes >= 0 ? "+" : "-";
+  const tzAbs = Math.abs(tzMinutes);
+  const tzH = pad2(Math.floor(tzAbs / 60));
+  const tzM = pad2(tzAbs % 60);
+  const pdfDate = `D:${yyyy}${mm}${dd}${hh}${mi}${ss}${tzSign}${tzH}'${tzM}'`;
+  const xmpDate = `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}${tzSign}${tzH}:${tzM}`;
+  return { pdfDate, xmpDate };
+}
+function buildXMPMetadata(title, createDate, pdfaPart = 2, pdfaConformance = "B", author) {
   const escapedTitle = escapeXml(title);
-  return [
+  const lines = [
     '<?xpacket begin="\xEF\xBB\xBF" id="W5M0MpCehiHzreSzNTczkc9d"?>',
     '<x:xmpmeta xmlns:x="adobe:ns:meta/">',
     ' <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">',
@@ -4634,17 +4651,24 @@ function buildXMPMetadata(title, createDate, pdfaPart = 2, pdfaConformance = "B"
     '    xmlns:pdf="http://ns.adobe.com/pdf/1.3/"',
     '    xmlns:xmp="http://ns.adobe.com/xap/1.0/"',
     '    xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/">',
-    `   <dc:title><rdf:Alt><rdf:li xml:lang="x-default">${escapedTitle}</rdf:li></rdf:Alt></dc:title>`,
-    "   <dc:creator><rdf:Seq><rdf:li>pdfnative</rdf:li></rdf:Seq></dc:creator>",
+    `   <dc:title><rdf:Alt><rdf:li xml:lang="x-default">${escapedTitle}</rdf:li></rdf:Alt></dc:title>`
+  ];
+  if (author !== void 0 && author !== "") {
+    lines.push(`   <dc:creator><rdf:Seq><rdf:li>${escapeXml(author)}</rdf:li></rdf:Seq></dc:creator>`);
+  }
+  lines.push(
     "   <pdf:Producer>pdfnative</pdf:Producer>",
     `   <xmp:CreateDate>${createDate}</xmp:CreateDate>`,
+    `   <xmp:ModifyDate>${createDate}</xmp:ModifyDate>`,
+    `   <xmp:MetadataDate>${createDate}</xmp:MetadataDate>`,
     `   <pdfaid:part>${pdfaPart}</pdfaid:part>`,
     `   <pdfaid:conformance>${pdfaConformance}</pdfaid:conformance>`,
     "  </rdf:Description>",
     " </rdf:RDF>",
     "</x:xmpmeta>",
     '<?xpacket end="w"?>'
-  ].join("\n");
+  );
+  return lines.join("\n");
 }
 function buildOutputIntentDict(iccStreamObjNum, subtype = "GTS_PDFA1") {
   return `<< /Type /OutputIntent /S /${subtype} /OutputConditionIdentifier (sRGB IEC61966-2.1) /RegistryName (http://www.color.org) /DestOutputProfile ${iccStreamObjNum} 0 R >>`;
@@ -5256,7 +5280,7 @@ endstream`);
     _offset += d;
   }, objOffsets, parts };
 }
-function writeXrefTrailer(w, totalObjs, infoObjNum, encState) {
+function writeXrefTrailer(w, totalObjs, infoObjNum, encState, idSeed = "") {
   let encryptObjNum = 0;
   if (encState) {
     encryptObjNum = totalObjs + 1;
@@ -5274,11 +5298,13 @@ function writeXrefTrailer(w, totalObjs, infoObjNum, encState) {
 `);
   }
   w.emit("trailer\n");
+  const docId = encState ? encState.docId : md5(new TextEncoder().encode(`pdfnative|${idSeed}|${totalObjs}`));
+  const idArray = buildIdArray(docId);
   if (encState) {
-    w.emit(`<< /Size ${totalObjs + 1} /Root 1 0 R /Info ${infoObjNum} 0 R /Encrypt ${encryptObjNum} 0 R /ID ${buildIdArray(encState.docId)} >>
+    w.emit(`<< /Size ${totalObjs + 1} /Root 1 0 R /Info ${infoObjNum} 0 R /Encrypt ${encryptObjNum} 0 R /ID ${idArray} >>
 `);
   } else {
-    w.emit(`<< /Size ${totalObjs + 1} /Root 1 0 R /Info ${infoObjNum} 0 R >>
+    w.emit(`<< /Size ${totalObjs + 1} /Root 1 0 R /Info ${infoObjNum} 0 R /ID ${idArray} >>
 `);
   }
   w.emit("startxref\n");
@@ -5475,6 +5501,7 @@ var DEFAULT_TEXT_COLOR = "0.75 0.75 0.75";
 var DEFAULT_TEXT_OPACITY = 0.15;
 var DEFAULT_TEXT_ANGLE = -45;
 var DEFAULT_IMAGE_OPACITY = 0.1;
+var DEFAULT_CAP_HEIGHT_RATIO = 0.718;
 function validateWatermark(watermark, pdfaLevel) {
   if (pdfaLevel === "pdfa1b") {
     const textOpacity = watermark.text?.opacity ?? DEFAULT_TEXT_OPACITY;
@@ -5529,10 +5556,12 @@ function _buildTextWatermarkOps(wm, pgW, pgH, enc, gsName) {
   const cy = pgH / 2;
   const textWidth = enc.tw(wm.text, sz);
   const offsetX = -textWidth / 2;
-  const offsetY = -sz / 2;
+  const fd = enc.fontData;
+  const capHeightRatio = fd ? fd.metrics.capHeight / fd.metrics.unitsPerEm : DEFAULT_CAP_HEIGHT_RATIO;
+  const offsetY = -sz * capHeightRatio / 2;
   const tx = cx + offsetX * cos - offsetY * sin;
   const ty = cy + offsetX * sin + offsetY * cos;
-  const escapedText = pdfString(wm.text);
+  const escapedText = enc.ps(wm.text);
   const ops = [
     "q",
     `${gsName} gs`,
@@ -6014,10 +6043,7 @@ function buildPDF(params, layoutOptions) {
   }
   const baseObjCount = enc.isUnicode ? 4 + fontEntries.length * 5 + wmExtraObjs + totalPages * 2 : 4 + wmExtraObjs + totalPages * 2;
   const infoObjNum = baseObjCount + 1;
-  const now = /* @__PURE__ */ new Date();
-  const pad2 = (n) => String(n).padStart(2, "0");
-  const pdfDate = `D:${now.getFullYear()}${pad2(now.getMonth() + 1)}${pad2(now.getDate())}${pad2(now.getHours())}${pad2(now.getMinutes())}${pad2(now.getSeconds())}`;
-  const isoDate = `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}T${pad2(now.getHours())}:${pad2(now.getMinutes())}:${pad2(now.getSeconds())}`;
+  const { pdfDate, xmpDate: isoDate } = buildPdfMetadata();
   const infoTitle = params.docTitle || title || "";
   emitObj(
     infoObjNum,
@@ -6097,7 +6123,7 @@ endobj
     }
   }
   const writer = { emit, emitObj, emitStreamObj, offset: getOffset, adjustOffset, objOffsets, parts };
-  writeXrefTrailer(writer, totalObjs, infoObjNum, encState);
+  writeXrefTrailer(writer, totalObjs, infoObjNum, encState, `${infoTitle}|${pdfDate}`);
   return parts.join("");
 }
 function buildPDFBytes(params, layoutOptions) {
@@ -9703,10 +9729,7 @@ function buildDocumentPDF(params, layoutOptions) {
   }
   const baseObjCount = enc.isUnicode ? 4 + fontEntries.length * 5 + imageCount + wmExtraObjs + totalPages * 2 + totalAnnots + totalFormObjs + formFontObjs : 4 + imageCount + wmExtraObjs + totalPages * 2 + totalAnnots + totalFormObjs + formFontObjs;
   const infoObjNum = baseObjCount + 1;
-  const now = /* @__PURE__ */ new Date();
-  const pad2 = (n) => String(n).padStart(2, "0");
-  const pdfDate = `D:${now.getFullYear()}${pad2(now.getMonth() + 1)}${pad2(now.getDate())}${pad2(now.getHours())}${pad2(now.getMinutes())}${pad2(now.getSeconds())}`;
-  const isoDate = `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}T${pad2(now.getHours())}:${pad2(now.getMinutes())}:${pad2(now.getSeconds())}`;
+  const { pdfDate, xmpDate: isoDate } = buildPdfMetadata();
   const infoTitle = params.title ?? "";
   const metaParts = [`/Title ${encodePdfTextString(infoTitle)}`, "/Producer (pdfnative)", `/CreationDate (${pdfDate})`];
   if (params.metadata?.author) {
@@ -9734,7 +9757,7 @@ function buildDocumentPDF(params, layoutOptions) {
     structTreeRootObjNum = tree.structTreeRootObjNum;
     totalObjs = treeStart + tree.totalObjects - 1;
     xmpObjNum = totalObjs + 1;
-    const xmpContent = buildXMPMetadata(infoTitle, isoDate, pdfaConfig.pdfaPart, pdfaConfig.pdfaConformance);
+    const xmpContent = buildXMPMetadata(infoTitle, isoDate, pdfaConfig.pdfaPart, pdfaConfig.pdfaConformance, params.metadata?.author);
     emitStreamObj(
       xmpObjNum,
       `<< /Type /Metadata /Subtype /XML /Length ${xmpContent.length}`,
@@ -9840,7 +9863,7 @@ endobj
     }
   }
   const writer = { emit, emitObj, emitStreamObj, offset: getOffset, adjustOffset, objOffsets, parts };
-  writeXrefTrailer(writer, totalObjs, infoObjNum, encState);
+  writeXrefTrailer(writer, totalObjs, infoObjNum, encState, `${infoTitle}|${pdfDate}`);
   return parts.join("");
 }
 function buildDocumentPDFBytes(params, layoutOptions) {