v1.0.5 — watermark centering & CLI docs

Released 2026-04-27

Patch release. Two bug fixes in the watermark module (vertical centering and Unicode encoding) plus first-class documentation for the official command-line interface, pdfnative-cli. 100% backward-compatible with v1.0.4 — no public API surface changes, no breaking changes, no byte-shift in non-watermarked PDFs.

Highlights

• fix(watermark): text watermarks are now mathematically centered. The previous offset ignored cap-height; affected output now matches the visual center of the page in both axes.
• fix(watermark): Unicode watermarks (Arabic, Hebrew, CJK, Devanagari, Bengali, Tamil, Cyrillic, Greek, Georgian, Armenian) now render correctly when the document uses a CIDFont. Watermark text is encoded through the active encoding context instead of being forced through WinAnsi.
• docs(cli): new CLI Guide documents pdfnative-cli — the official render / sign / inspect command-line tool. Covers installation, security model, CI/CD pipelines, and library-vs-CLI decision guidance.
• docs(architecture): Ecosystem section now spans both companion packages (pdfnative-cli and pdfnative-mcp) with parallel treatment in README.md and the architecture guide.

Fixed

• fix(core/watermark): vertical offset of text watermarks now derives from the active font's capHeight / unitsPerEm ratio (with a 0.718 fallback matching Helvetica) instead of the prior -fontSize/2. Glyphs are now centered on their cap-height baseline midpoint, eliminating the visible vertical drift previously observed at large rotation angles. (src/core/pdf-watermark.ts)
• fix(core/watermark): watermark text is now encoded via enc.ps() (the document's active encoding context) instead of pdfString() (WinAnsi-only). Documents using a CIDFont (Identity-H) now emit watermarks as 2-byte hex GIDs and render correctly across all 16 supported scripts. (src/core/pdf-watermark.ts)

Added

• feat(tests): 6 new regression tests in tests/core/pdf-watermark.test.ts covering cap-height-based vertical offset, horizontal centering, Latin WinAnsi encoding, Unicode CIDFont 2-byte GID hex encoding, font-metric-driven offset in Unicode mode, and rotation invariance of the visual centering bounding box.

Documentation

• docs(cli): new CLI Guide (docs/guides/cli.html + docs/guides/cli.md).
• docs(index): new CLI feature card on pdfnative.dev homepage with dedicated icon (.fi-cli).
• docs(quickstart): new "Command line — pdfnative-cli" section in the Quick Start guide plus link from the Next steps list.
• docs(architecture): Ecosystem section in architecture guide now documents pdfnative-cli alongside pdfnative-mcp with parallel diagrams.
• docs(readme): README.md now lists both companion packages in the Ecosystem section, includes a pdfnative-cli npm version badge, and a CLI bullet in the Highlights list.

Deferred

• #28 (PDF/A Latin font embedding): integration of an embedded Latin font (e.g. Liberation Sans / Arimo) for PDF/A documents has been deferred to v1.1.0. The change requires object renumbering across multiple builders and ships ~30–60 KB of additional bytes per PDF/A output, which is out of scope for a patch release. Tracking issue: #28.

Install

npm install pdfnative@1.0.5

Upgrade

No breaking changes. Drop-in replacement for v1.0.4. Documents that did not use watermarks produce byte-identical output to v1.0.4. Documents using watermarks will produce visually-corrected output (vertical centering, Unicode encoding) — verify visual regression baselines if your test suite pixel-compares watermarked PDFs.

Links

• CHANGELOG
• Full diff
• CLI repository
• Roadmap