pretext-pdf 0.5.3 → 0.8.1

package/CHANGELOG.md

@@ -7,8 +7,71 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 
 ---
 
+## [0.8.1] — 2026-04-20
+
+### Fixed
+
+- **Browser support** — `pretext-pdf` now imports cleanly in browsers. Module-init in `src/fonts.ts` previously called `fileURLToPath(import.meta.url)` and `createRequire(import.meta.url)` eagerly, which threw `"The URL must be of scheme file"` whenever the module was loaded from a non-`file://` URL (esm.sh, jsdelivr, Vite dev server). Both calls are now gated on a runtime `IS_NODE` check, and the bundled-Inter `BUNDLED_INTER_PATHS` arrays are constructed only in Node.
+- **Browser font-loading errors** — `loadFontBytes` now throws clear `FONT_LOAD_FAILED` messages when bundled Inter or string font paths are requested in a browser, pointing the consumer at the correct workaround (supply `Uint8Array` bytes via `doc.fonts`).
+
+### Notes for browser users
+
+- Always supply Inter (or your default font) explicitly via `doc.fonts: [{ family: 'Inter', weight: 400, src: <Uint8Array> }, { family: 'Inter', weight: 700, src: <Uint8Array> }]`. The library cannot read local font files in the browser.
+- SVG / chart / qr-code / barcode elements still depend on `@napi-rs/canvas` at runtime; in the browser, the native `OffscreenCanvas` is used instead and the polyfill is skipped automatically.
+
+---
+
+## [0.8.0] — 2026-04-19
+
+### Added
+
+- **`qr-code` element** — generate QR codes as inline PDF content using the `qrcode` optional peer dependency. Supports `data`, `size`, `errorCorrectionLevel` (L/M/Q/H), `foreground`/`background` hex colours, `margin`, `align`, `spaceBefore`/`spaceAfter`. Fully serverless — pure JS, no canvas required.
+- **`barcode` element** — generate 100+ barcode symbologies (EAN-13, Code128, PDF417, QR, DataMatrix, etc.) via the `bwip-js` optional peer dependency. Supports `symbology`, `data`, `width`, `height`, `includeText`, `align`, `spaceBefore`/`spaceAfter`. Pure JS, Lambda/Edge safe.
+- **`chart` element** — embed Vega-Lite charts as vector SVG using `vega` + `vega-lite` optional peer deps. Accepts any Vega-Lite `spec`, `width`, `height`, `caption`, `align`. Rendered with `renderer: 'none'` — zero canvas/puppeteer dependency.
+- **`pretext-pdf/markdown` entry point** — `markdownToContent(md, options?)` converts a Markdown string to `ContentElement[]`. Requires optional `marked` peer dep. Supports headings, bold/italic/links (→ rich-paragraph), lists (2 levels), blockquotes, code blocks, and HR.
+- **`pretext-pdf/templates` entry point** — three typed template functions with zero extra dependencies: `createInvoice(data)` (generic invoice with currency, tax, discount, QR payment), `createGstInvoice(data)` (GST-compliant Indian tax invoice with IGST/CGST+SGST, UPI QR, bank details, amount in words), `createReport(data)` (structured business report with optional TOC).
+- **New error codes** — `QR_DEP_MISSING`, `QR_GENERATE_FAILED`, `BARCODE_DEP_MISSING`, `BARCODE_GENERATE_FAILED`, `BARCODE_SYMBOLOGY_INVALID`, `CHART_DEP_MISSING`, `CHART_SPEC_INVALID`, `CHART_RENDER_FAILED`, `MARKDOWN_DEP_MISSING`.
+
+---
+
+## [0.7.1] — 2026-04-19
+
+### Changed
+
+- **Upstream pretext pinned to `f2014338487a`** — picks up unreleased CJK opening-bracket annotation fix, Hangul jamo line-walker alignment fix, and two internal line-object churn reductions. No public API changes.
+
+### Fixed
+
+- **List nesting depth enforced at validation** — `ListItem.items` (2nd-level items) now correctly rejects any further `.items` property, matching the documented 2-level maximum. Previously the validation silently passed 3-level data which could cause undefined render behaviour.
+- **3 phase-11 list tests corrected** — test data incorrectly contained 3-level nesting while named "2-level"; data trimmed to match documented contract.
+
+---
+
 ## [Unreleased]
 
+### Added (Phase 11 — Cross-cutting Enhancements)
+
+- **`floatSpans` on image elements** — rich-text alternative to plain `floatText`. Accepts `InlineSpan[]` for mixed bold/italic/color/link captions beside float images. Mutually exclusive with `floatText` (validated).
+- **2-level list nesting** — `ListItem.items` now supports one further level of nesting (depth 0 → 1 → 2). Unordered marker: `▪`. Ordered: inherits parent counter or restarts via `nestedNumberingStyle: 'restart'`.
+- **Table `rowspan`** — `TableCell.rowspan` spans a cell across multiple rows. Works alongside `colspan`. Origin cell draws background over full span height; continuation rows automatically receive placeholder cells.
+- **`onFormFieldError` callback** — `doc.onFormFieldError: (name, err) => 'skip' | 'throw'` mirrors `onImageLoadError`. Controls render behaviour when a form field fails.
+- **`createFootnoteSet(defs)`** — helper exported from `pretext-pdf` that generates footnote definition/reference pairs with globally unique IDs. Returns `Array<{ id, def }>`.
+- **`renderDate` field** — `doc.renderDate: Date | string` overrides the PDF creation date. Useful for reproducible builds and testing.
+- **`{{date}}` and `{{author}}` tokens** in header/footer text — join existing `{{pageNumber}}` / `{{totalPages}}`. `{{date}}` resolves from `renderDate`; `{{author}}` resolves from `doc.metadata.author`.
+- **`tabularNumbers`** on `rich-paragraph` — digits rendered at uniform slot width (widest digit in font), so columns of numbers align without OpenType TNUM feature.
+- **`smallCaps` + `letterSpacing` per span** — `InlineSpan.smallCaps` and `InlineSpan.letterSpacing` now respected in `rich-paragraph` rendering.
+- **Per-span `fontSize`** — `InlineSpan.fontSize` overrides the element-level font size for that span. Enables mixed-size text in a single paragraph.
+
+### Fixed (Phase 11)
+
+- `resolveTokens()` used `.replace()` (replaces first occurrence only) — changed to `.replaceAll()` for all four tokens.
+- Table span grid: continuation-row cursor was advancing by 1 instead of `colspan` when skipping a spanned column — now advances by full span width.
+- Font family names now validated for safe characters (`/^[a-zA-Z0-9 _-]+$/`) in `requireFamily()` — rejects null bytes and control characters.
+- Annotation `color` and `author` fields now validated in `validateElement()` for both `paragraph` and `heading` annotations.
+- `buildOutlineTree` memoizes `parentIdxOf()` into a pre-computed array — eliminates O(n²) scan for documents with large heading counts.
+- Table grid-line renderer pre-computes active boundary set — eliminates O(rows × cols) inner loop for large tables.
+- `addLinkAnnotation()` re-validates URL scheme at render time (defense-in-depth; `validate.ts` is the primary gate).
+
 ### Planned (Phase 9+)
 
 - Phase 9A: Digital signatures (cryptographic PKCS#7 via `@signpdf/signpdf`)
@@ -17,6 +80,29 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 
 ---
 
+## [0.7.0] — 2026-04-17
+
+### Added
+
+- **6 production templates** (`templates/`) — GST invoice, international invoice, resume, multi-section report, NDA, and meeting minutes. Each is a self-contained `.ts` file outputting a valid PDF. Smoke-tested in Phase 2F Block D.
+- **StackBlitz live demo** (`demo/stackblitz/`) — 4-tab UI (Invoice, Report, Resume, Custom) backed by a Node.js render server. Edit JSON and generate PDFs instantly, no install required. Accessible at the StackBlitz link in the README.
+- **`## Performance` section in README** — measured render times and PDF sizes for 1-page, 10-page, and mixed-element documents. Font subsetting behaviour documented.
+- **Stress tests and benchmarks** (`test/phase-2f-stress.test.ts`) — 32 tests across 4 blocks: large document stress (400-element, 200-row table), edge case stress (CJK, RTL, empty arrays, extreme sizes), timing benchmarks (1-page < 500 ms, 10-page < 5,000 ms), and template smoke tests.
+- **Error code coverage** — new tests for `COLUMN_WIDTH_TOO_NARROW`, `IMAGE_LOAD_FAILED`, `SVG_LOAD_FAILED`, and `ASSEMBLY_FAILED`. 16 of 19 error codes now have direct test coverage.
+
+### Changed
+
+- **`as any` audit** — eliminated 10 casts in `validate.ts` by introducing a typed `FormFieldElement` local binding. The remaining 8 instances (pdf-lib interop, dynamic import, internal back-references) are now documented with one-line comments explaining the constraint.
+- **Comparison article** (`docs/articles/pretext-pdf-vs-pdfmake-2026.md`) — 2,200-word draft covering feature matrix, typography quality, API design, performance, and migration quick-start. Marked `published: false` pending live demo.
+- **Migration guide** (`docs/MIGRATION_FROM_PDFMAKE.md`) — 30+ pdfmake → pretext-pdf mappings, complete before/after invoice example, and a quick-start checklist. Linked from README.
+
+### Fixed
+
+- **Phase 2F test types** — `fontWeight: 700 as 700` cast in pre-constructed rows array; removed non-existent `creationDate` from `DocumentMetadata`; replaced `allowCopying: false` with correct `encryption: { permissions: { copying: false } }`.
+- **StackBlitz integration** — added `.stackblitzrc` so WebContainer auto-runs `npm start` and opens the browser preview on port 3000.
+
+---
+
 ## [0.5.3] — 2026-04-16
 
 ### Changed
@@ -46,17 +132,21 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 ## [0.4.0] — 2026-04-08
 
 ### Breaking Changes
+
 - **Migrated from `pdf-lib` to `@cantoo/pdf-lib`** — `@cantoo/pdf-lib` is now a direct `dependency` (always installed). Previously it was an optional peer dependency required only for encryption. This removes the `ENCRYPTION_NOT_AVAILABLE` error code and the separate `npm install @cantoo/pdf-lib` installation step. Encryption now works out of the box.
 - **`ENCRYPTION_NOT_AVAILABLE` error code removed** — encryption is now always available. Update any `switch` statements that handled this code.
 
 ### Why this change
+
 `pdf-lib` (the original) has not received a meaningful commit since November 2021. `@cantoo/pdf-lib` is the actively maintained fork (v2.6.5, 107+ releases, MIT license). pretext-pdf was already using `@cantoo/pdf-lib` for encryption — this commit makes it the single source of truth for all PDF operations.
 
 ### Added
+
 - `test/pretext-api-contract.test.ts` — canary test that asserts `@chenglou/pretext` exports the exact functions pretext-pdf depends on. Breaks loudly if pretext changes its API.
 - `docs/ROADMAP.md` — public multi-phase development plan
 
 ### Changed
+
 - `@chenglou/pretext` version pinned to exact `0.0.3` (no caret) — prevents surprise breaking changes from upstream auto-updates
 - `test:contract` script added — runs the pretext API contract test before the full test suite
 - All internal comments updated from `pdf-lib` to `@cantoo/pdf-lib`
@@ -66,6 +156,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 ## [0.3.1] — 2026-04-08
 
 ### Fixed
+
 - **Critical: Font resolution when installed as npm package** — `@fontsource/inter` is now resolved via `createRequire(import.meta.url)` instead of a hardcoded relative path. Previously, `path.join(__dirname, '..', 'node_modules', '@fontsource', 'inter', ...)` failed when npm hoisted the dependency to the consumer's top-level `node_modules`, causing `FONT_LOAD_FAILED` on every install. Now resolves correctly regardless of npm hoisting behavior.
 
 ---
@@ -73,6 +164,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 ## [0.3.0] — 2026-04-08
 
 ### Added (Phase 8B — Interactive Forms)
+
 - New `form-field` element type — creates interactive AcroForm fields in PDFs
 - `fieldType: 'text' | 'checkbox' | 'radio' | 'dropdown' | 'button'`
 - `label` renders above the field as static text
@@ -86,6 +178,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - 10 comprehensive tests covering all form field types
 
 ### Added (Phase 8E — Signature Placeholder)
+
 - `doc.signature` — visual signature box drawn on a specified page
 - Fields: `signerName`, `reason`, `location`, `x`, `y`, `width`, `height`, `page`, `borderColor`, `fontSize`
 - Draws signature line, date line, and optional text inside a bordered rectangle
@@ -93,6 +186,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - 6 comprehensive tests
 
 ### Added (Phase 8D — Callout Boxes)
+
 - New `callout` element type — styled highlight box with optional title
 - Preset styles: `style: 'info'` (blue), `'warning'` (amber), `'tip'` (green), `'note'` (gray)
 - Optional `title` rendered bold above content with left border accent
@@ -101,6 +195,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - 8 comprehensive tests
 
 ### Added (Phase 8F — Document Metadata Extensions)
+
 - `doc.metadata.language` — sets PDF `/Lang` catalog entry (BCP47 tag e.g. `'en-US'`, `'hi'`)
 - `doc.metadata.producer` — sets PDF producer field (e.g. `'MyApp v2.1'`)
 - Both fields validate as non-empty strings
@@ -111,6 +206,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 ## [0.2.0] — 2026-04-08
 
 ### Added (Phase 8H — Inline Formatting)
+
 - `verticalAlign: 'superscript' | 'subscript'` on `InlineSpan` in rich-paragraphs
 - Superscript renders at 65% font size, baseline shifted up by 40% of font size
 - Subscript renders at 65% font size, baseline shifted down by 20% of font size
@@ -120,6 +216,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - 8 comprehensive tests covering all inline formatting functionality
 
 ### Added (Phase 8A — Annotations/Comments)
+
 - New `comment` element type — sticky note annotation at position in document
 - `annotation?: AnnotationSpec` on `ParagraphElement` and `HeadingElement` — attach note to element
 - Supports: `contents`, `author`, `color` (hex), `open` (popup default state)
@@ -127,6 +224,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - 8 comprehensive tests covering all annotation functionality
 
 ### Added (Phase 8C — Document Assembly)
+
 - New `merge(pdfs: Uint8Array[])` exported function — combine pre-rendered PDFs
 - New `assemble(parts: AssemblyPart[])` exported function — mix rendered docs + existing PDFs
 - `AssemblyPart` interface: `{ doc?: PdfDocument, pdf?: Uint8Array }`
@@ -134,6 +232,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - 8 comprehensive tests covering all assembly functionality
 
 ### Fixed
+
 - **CI case-sensitivity bug**: `test/phase-7-integration.test.ts` used `'en-US'` (uppercase) for hyphenation language. On Linux CI (case-sensitive filesystem) this failed with `UNSUPPORTED_LANGUAGE`. Changed to `'en-us'` to match package name `hyphenation.en-us`.
 
 ---
@@ -141,6 +240,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 ## [0.1.1] — 2026-04-08
 
 ### Added
+
 - **Phase 8G: Hyperlinks** — Complete link annotation support:
   - `paragraph.url` for external URI links on paragraphs
   - `heading.url` for external URI links on headings
@@ -151,6 +251,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
   - 9 comprehensive tests covering all hyperlink functionality
 
 ### Fixed
+
 - **Memory leak in test suite**: Removed module-level `_hypherCache` in `src/measure.ts` that accumulated ~188KB per language across 255+ test runs. Changed from cached Hypher instances to fresh instances per call (negligible performance impact, massive memory savings).
 - **Node.js version compatibility**: Replaced `--experimental-strip-types` with `tsx` runner to support Node.js 18.x, 20.x, and 22.x in CI
 - **Broken CI examples**: Removed references to non-existent Phase 8 example scripts from GitHub Actions workflow
@@ -158,12 +259,14 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - **Test suite OOM issues**: Split large test files (paginate.test.ts) into paginate-basic.test.ts to work around Node.js `--experimental-strip-types` heap exhaustion bug on files >17KB
 
 ### Changed
+
 - `test:unit` now runs only `test/paginate-basic.test.ts` (fast, no canvas overhead)
 - Reorganized test scripts: `test:unit`, `test:validate`, `test:e2e`, `test:phases` for better memory management
 - Moved internal planning documentation to archive (preserved, not published)
 - `devDependencies`: Added `@napi-rs/canvas` explicitly (was missing, causing CI failures)
 
 ### Added
+
 - `CONTRIBUTING.md`: Development setup, TDD workflow, PR process guide
 - `CHENG_LOU_EMAIL_DRAFT.md`: Template for requesting endorsement from pretext creator
 - `examples/comparison-pdfmake.ts`: pdfmake version of invoice for typography comparison
@@ -173,6 +276,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 ## [0.1.0] — 2026-04-07
 
 ### Added (Phase 7G — Encryption)
+
 - `doc.encryption` configuration for password-protecting PDFs
 - User password and owner password support
 - Granular permission restrictions: printing, copying, modifying, annotating
@@ -180,6 +284,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Error code: `ENCRYPTION_NOT_AVAILABLE` when encryption is requested but dependency not installed
 
 ### Added (Phase 7F — RTL Text Support)
+
 - Right-to-left text support for Arabic, Hebrew, and other RTL languages
 - Unicode bidirectional text algorithm via `bidi-js`
 - `dir` attribute on text elements: `'ltr'` | `'rtl'` | `'auto'` for per-element control
@@ -187,6 +292,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Automatic detection of mixed LTR/RTL content
 
 ### Added (Phase 7E — SVG Support)
+
 - `{ type: 'svg', svg: '<...' }` element for embedding SVG graphics
 - SVG rasterization via `@napi-rs/canvas`
 - ViewBox auto-sizing: automatic height calculation from viewBox aspect ratio
@@ -196,6 +302,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Error code: `SVG_RENDER_FAILED` for SVG rasterization errors
 
 ### Added (Phase 7D — Table of Contents)
+
 - `{ type: 'toc' }` element for automatic TOC generation
 - Two-pass rendering pipeline ensures accurate page numbers
 - Configurable: `title`, `showTitle`, `minLevel`/`maxLevel`, dot leaders, level indentation
@@ -203,6 +310,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Supports custom formatting via `fontSize`, `color`, `spaceAfter` parameters
 
 ### Added (Phase 7C — Hyphenation)
+
 - Automatic word hyphenation for better justified text layout
 - `doc.hyphenation: { language: 'en-US' }` for document-level config
 - Liang's algorithm via `hypher` package for accurate break points
@@ -211,6 +319,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Error code: `UNSUPPORTED_LANGUAGE` when language not available
 
 ### Added (Phase 7B — Watermarks)
+
 - `doc.watermark` for text or image watermarks on every page
 - Text watermarks: `text`, `fontSize`, `fontWeight`, `color`, `opacity`, `rotation`
 - Image watermarks: `image` (Uint8Array), `opacity`, `rotation`, `color` (tint)
@@ -219,6 +328,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Validation: must provide either text or image, never both required
 
 ### Added (Phase 7A — Bookmarks / PDF Outline)
+
 - PDF sidebar bookmarks auto-generated from heading structure
 - Enabled by default: `bookmarks: true` or `bookmarks: { minLevel: 1, maxLevel: 3 }`
 - Level filtering: include/exclude heading levels from outline
@@ -226,6 +336,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Keyboard navigation: Cmd/Ctrl+Opt/Alt+O in PDF readers to toggle bookmark sidebar
 
 ### Added (Phase 6 — Advanced Features)
+
 - Header and footer support with {{pageNumber}} and {{totalPages}} tokens
 - Text decoration: strikethrough, underline
 - Text alignment: left, center, right, justify
@@ -234,6 +345,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Tables with colspan/rowspan support
 
 ### Added (Phase 5 — Rich Text / Builder API)
+
 - Fluent builder API for programmatic document construction
 - Rich text element with nested formatting (bold, italic, links)
 - Inline code and code blocks with syntax highlighting
@@ -242,6 +354,7 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 - Numbered and bulleted lists with nesting
 
 ### Added (Phases 1–4 — Core Engine)
+
 - Core PDF generation via `pdf-lib`
 - Element types: paragraph, heading, table, image, list, code, blockquote
 - Font support: Inter bundled, custom TTF embedding
@@ -305,6 +418,7 @@ npm run test:visual      # Visual regression tests
 ## Dependencies
 
 ### Required
+
 - `@chenglou/pretext` — Pretext text layout engine
 - `pdf-lib` — PDF document manipulation
 - `@fontsource/inter` — Font: Inter (bundled)
@@ -313,6 +427,7 @@ npm run test:visual      # Visual regression tests
 - `hyphenation.en-us` — English hyphenation patterns (Phase 7C)
 
 ### Optional (Peer)
+
 - `@napi-rs/canvas` — SVG rasterization (Phase 7E)
 - `@cantoo/pdf-lib` — PDF encryption (Phase 7G)