pretext-pdf 1.1.1 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,665 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 
 ---
 
+## [1.6.0] — 2026-05-25
+
+Internal restructuring + SVG sanitizer hardening. **No public API changes.** The previously-monolithic `src/assets.ts` (961 lines pre-sprint) has been split into 10 focused files under `src/assets/`. A 14-line back-compat shim at `src/assets.ts` re-exports the barrel so every existing consumer (internal modules, public API, and direct test imports via `dist/assets.js`) keeps working unchanged.
+
+### Security
+
+- **SVG sanitizer hardening** — `sanitizeSvg` now strips three additional payload classes that survived the previous regex chain:
+  - **`<foreignObject>` blocks** — the only XML-in-SVG construct that can host arbitrary HTML/XML namespaces. Both self-closing and paired forms are removed wholesale; sibling SVG primitives (`<rect/>`, `<path/>`, etc.) are preserved.
+  - **`javascript:` / `vbscript:` / `data:` hrefs on `<a>` elements** — previously only `<image>`/`<use>` hrefs were filtered. Only the dangerous href attribute is dropped, so the `<a>` element's text children still render.
+  - **CSS `expression(...)` calls inside `<style>` blocks** — legacy IE XSS vector. Only the `expression(...)` call site is excised; the surrounding stylesheet remains parseable.
+
+  Coverage: new `test/svg-sanitizer.test.ts` (10 cases) plus expanded MA-4 / MA-5 fixtures in `test/data/assets-split-tripwire.json` (30 fixtures total).
+
+### Changed
+
+- **`src/assets.ts` split into 10 files** under `src/assets/` (see Internal). No public API change — the file at `src/assets.ts` is now a 14-line re-export shim that aggregates the new barrel `src/assets/index.ts`. Consumers importing from `dist/assets.js` continue to resolve every previously-public symbol (`loadImages`, `assertPathAllowed`, `sanitizeSvg`, `assertSafeUrl`, `resolveAndValidateUrl`, `normalizeIpv4Hostname`, `fetchWithTimeout`, `redactPath`, `VECTOR_RASTER_CONCURRENCY`, plus the `ResolvedSafeUrl` type) at the same module path.
+- **`PretextPdfError` constructor signature snapshot refreshed** — `etc/pretext-pdf.api.md` now reflects the `options?: ErrorOptions` parameter that was added in v1.2.1 but never re-snapshotted. No code change — the parameter has been live for several releases. The snapshot was stale; this release reconciles it.
+
+### Internal
+
+- **New `src/assets/` directory layout:**
+  ```
+  src/assets/
+  ├── index.ts                    # internal barrel
+  ├── util/
+  │   └── redact-path.ts          # commit 4
+  ├── security/
+  │   ├── path-allowlist.ts       # commit 5
+  │   ├── ipv4-normalize.ts       # commit 6
+  │   ├── url-validation.ts       # commit 7
+  │   └── fetch.ts                # commit 8 (undici Agent stays lazy)
+  ├── svg/
+  │   ├── sanitize.ts             # commit 9 (+ SVG_MAX_BYTES)
+  │   ├── dimensions.ts           # commit 10
+  │   ├── resolve-content.ts      # commit 10
+  │   └── rasterize.ts            # commit 11 (@napi-rs/canvas dynamic)
+  ├── generators/
+  │   ├── qr.ts                   # commit 12 (qrcode dynamic)
+  │   ├── barcode.ts              # commit 12 (bwip-js dynamic)
+  │   └── chart.ts                # commit 12 (vega/vega-lite dynamic)
+  └── loaders/
+      ├── images.ts               # commit 13
+      ├── vectors.ts              # commit 14
+      ├── watermark.ts            # commit 15
+      └── orchestrator.ts         # commit 15 (top-level loadImages)
+  ```
+  All optional peer-dependency dynamic imports (`@napi-rs/canvas`, `qrcode`, `bwip-js`, `vega`, `vega-lite`, `undici`) are preserved as lazy loads — cold-start cost is unchanged.
+- **7 verification gates (G1–G7) added** to catch regressions during the split:
+  - **G1** Snapshot tripwire (`test/assets-split-tripwire.test.ts`) — 30 fixtures covering sanitizer output, URL normalization, path allowlist, and error code surface
+  - **G2** DNS lookup dedup (`test/assets-dns-dedup.test.ts`)
+  - **G3** SSRF blocking (`test/security-ssrf.test.ts`, expanded)
+  - **G4** Parallel-render concurrency (`test/assets-concurrency.test.ts`) — 10× concurrent `render()` calls must produce bit-identical PDFs
+  - **G5** ErrorCode stability (`test/assets-errorcode-stability.test.ts`)
+  - **G6** api-extractor diff against `etc/pretext-pdf.api.md`
+  - **G7** Cold-start perf (`test/assets-perf-coldstart.test.ts`, baseline at `test/data/perf-coldstart-baseline.json`) — 100 sequential renders within 2.5× the v1.5.2 baseline
+- **G7 measurement on the final shim**: 12,224ms / 100 renders (vs 21,205ms baseline = -42%, i.e. the split happens to be *faster*, well under the upper bound).
+
+---
+
+## [1.5.2] — 2026-05-25
+
+Security hotfix. **No public API changes.** **Upgrade recommended for any deployment that accepts user-controlled image / SVG URLs.**
+
+### Security
+
+- **CVE-class SSRF bypass via IPv4 alternative notations** — `isPrivateAddress` in `src/assets.ts` applied dotted-decimal regexes (`/^127\./`, `/^10\./`, …) against `URL#hostname`. The WHATWG URL parser does NOT normalize non-dotted IPv4 forms, so an attacker could reach private services by encoding the target in any inet_aton-compatible form:
+  - Pure decimal: `https://2130706433/x` → 127.0.0.1
+  - Pure hex: `https://0x7f000001/x` → 127.0.0.1
+  - Octal octet: `https://0177.0.0.1/x` → 127.0.0.1
+  - Hex octet: `https://0x7f.0.0.1/x` → 127.0.0.1
+  - Short form: `https://127.1/x` → 127.0.0.1
+
+  Without normalization, `parsed.hostname` is e.g. `"2130706433"`, the private-range regex chain misses it, the `isIpv4Literal` (4-dot) check misses it, and the URL falls through to DNS — which on Linux's `getaddrinfo` resolves to 127.0.0.1 and bypasses the SSRF guard. Same vector reaches RFC 1918 ranges (10/8, 192.168/16, 172.16/12), link-local (169.254.169.254 — AWS IMDS), and CGNAT.
+
+  **Fix:** new internal helper `normalizeIpv4Hostname()` implements inet_aton-style parsing (decimal/octal/hex per part, short-form packing for 1/2/3-part inputs, strict 32-bit range guard). `resolveAndValidateUrl` normalizes before the private-IP check AND before DNS, then treats the normalized form as an IP literal so undici never re-resolves a non-dotted private encoding. `isPrivateAddress` also normalizes its input as defense-in-depth on the post-DNS path. Public alternative encodings (e.g. `134744072` == 8.8.8.8) continue to resolve and fetch normally.
+
+  **Test coverage:** new `test/security-ipv4-bypass.test.ts` adds 24 cases — every blocked encoding above, public regression cases, plus direct unit tests for `normalizeIpv4Hostname` (round-trips, range guards, malformed-octal rejection, public-IP allowlist). Wired into the `test:phases` stage; phases stage grows from 417 to 441 tests.
+
+### Fixed
+
+- **`measure-blocks/float-group.ts` — fontSize fallback intent clarified** — v1.5.1 M5a removed a dead `baseFontSize = doc.defaultFontSize ?? 12` plus per-block `fontSize = block.fontSize || baseFontSize` local that was never read (the item assignment used `block.fontSize` directly). Audit of upstream measure helpers (measure-paragraph, measure-heading, …) confirms `block.fontSize` is always populated with a positive value for real content, so the fallback would never have fired in practice. Added a leading comment so future contributors don't reintroduce the fallback in the mistaken belief that `block.fontSize === 0` is a real case. No behavior change.
+
+---
+
+## [1.5.1] — 2026-05-24
+
+Hotfix batch closing 9 audit findings from the 6-agent v1.5.0 review. **No public API changes** — guarded by `test/public-api-surface.test.ts`. **No behavior changes other than the documented fixes**. Snapshot baseline expanded from 68 to 73 fixtures (5 new: 2 metadata.keywords + 3 watermark.image).
+
+### Security
+
+- **Watermark image URL scheme validation (H1)** — `doc.watermark.image` now passes through the same `validateUrl` pre-flight check used by `validateImage`. Unsafe schemes (`javascript:`, `data:`, `vbscript:`, `blob:`, `about:`, `file:`) are rejected at validate-time so CLI lint and MCP validate tools catch them before render. Relative file paths fall through unchanged. The shared URL-shape helper `looksLikeUrl` was moved from `validate/elements/media.ts` to `validate/helpers.ts`.
+
+### Fixed
+
+- **`metadata.keywords[]` element validation (H3)** — Previously, `for (const field of [...'keywords'...])` was paired with `typeof val === 'string'`, which silently no-op'd for the `string[]`-shaped `keywords` field. Each keyword entry is now validated for control-character injection and the 1000-character length cap via `validateMetadataString(kw, \`keywords[\${i}]\`)`.
+- **highlight.js dynamic-import error logging (H4)** — Previously, `catch { /* not installed */ }` silently swallowed every failure including real module-load errors. The catch now logs a warning unless the error code is `ERR_MODULE_NOT_FOUND`/`MODULE_NOT_FOUND` (the only legitimate "optional dep absent" signal).
+- **`hljs.highlight()` runtime exception logging (M2)** — Same silent-fallback issue as H4 but for tokenization failures. Now logs a warning naming the language before falling back to plain text.
+- **Font-variant registration logging (M3)** — `installNodePolyfill` now tracks per-variant success and warns when an individual Inter weight (400 or 700) fails to register, instead of only warning when *both* failed. Text metrics for the missing variant may be inaccurate; operators see this in logs.
+
+### Changed
+
+- **Removed redundant `as import('...').X` casts in `validate/elements/forms-floats.ts` (M1)** — `validateFormField`, `validateFootnoteDef`, and `validateFloatGroup` already accept `Extract<ContentElement, { type: 'X' }>`-typed `el`. The inner `const ff = el as FormFieldElement` casts were no-ops; removed.
+- **Removed unreachable `toc-entry` validator (M4)** — The pre-switch throw at `validate/index.ts:260` already rejects `toc-entry` before dispatch. The `case 'toc-entry':` arm (guarded with `@ts-expect-error`) and the `validateTocEntry` function in `validate/elements/structural-simple.ts` were unreachable dead code. Drift-guard test updated with `VALIDATE_DISPATCHER_EXCLUDES` (mirrors the existing `MEASURE_DISPATCHER_EXCLUDES` pattern) to keep the orchestrator scan honest.
+- **tsconfig: `noUnusedParameters` + `noUnusedLocals` enabled (M5a)** — Catches dead destructured locals and unused imports at build time. Cascade: 51 errors → 0. 30 of those were per-type `type _X = Exact<...>` drift guards in `allowed-props.ts` (load-bearing scaffolding) — consolidated into a single exported tuple `_AllowedPropsDriftGuard` that TypeScript counts as used. The remaining 20 were genuine unused-locals / unused-imports cleanup across measure, render, rich-text, and assets modules.
+- **tsconfig: `verbatimModuleSyntax` enabled (M5b)** — Enforces `import type` discipline. Cascade was only 6 errors, all `HyphenatorOpts` runtime imports that needed splitting into `import type`. Well under the 30-line cascade-defer threshold.
+
+---
+
+## [1.5.0] — 2026-05-24
+
+Architecture sprint completing the v1.4.0 god-file split debt. Six items shipped, single minor release. **No public API changes** — guarded by `test/public-api-surface.test.ts`. **No behavioral changes** — Item A's security-critical extraction guarded by new `test/validate-document-snapshot.test.ts` (68 fixtures, bit-exact preservation verified).
+
+### Changed (internal structure — non-breaking)
+
+- **`src/validate/index.ts` (594L) → orchestrator (322L) + `src/validate/document.ts` (324L)** —
+  Extracted 11 doc-level check categories (pageSize, margins, fonts, header/footer, defaultParagraphStyle, sections, watermark, encryption, signature, bookmarks, hyphenation, metadata) into a new `validateDocumentLevel(doc, ctx)` function. Single function with labeled `// ── name ──` blocks. **Security-critical**: snapshot tripwire test (68 fixtures across all 11 categories) verified bit-exact error preservation through the move.
+- **`src/measure-blocks/index.ts` (337L) → dispatcher (243L) + `src/measure-blocks/simple-blocks.ts` (151L)** —
+  Extracted 7 simple measurement arms (spacer, page-break, comment, form-field, hr, toc, footnote-def). Throw-guards for image/svg/qr-code/barcode/chart stay in dispatcher (security invariants tied to routing).
+- **`src/validate/elements/structural.ts` (239L grab-bag) → `structural-simple.ts` (120L) + `forms-floats.ts` (128L)** —
+  Split light element validators (spacer, hr, toc, toc-entry, comment) from heavy ones (form-field, footnote-def, float-group). Cleaner separation of concerns.
+
+### Added
+
+- **`src/validate/elements/README.md`** — Placement guide + validator signature contract + `_ctx` policy documentation + `withCycleGuard` usage guidance. Onboarding aid for adding new element types.
+- **`test/validate-document-snapshot.test.ts`** + `test/data/validate-document-snapshot.json` — Bit-exact error preservation tripwire for `validateDocumentLevel`. 68 fixtures across pageSize, margins, fonts, header/footer, defaultParagraphStyle, sections, watermark, encryption, signature, bookmarks, hyphenation, metadata, content guards, and valid-doc sanity cases.
+
+### Fixed
+
+- **`dist/` no longer tracked in git** (168 files removed) — was already in `.gitignore` but tracked from prior history.
+
+### Notes
+
+- 12 commits across 6 items, each independently revertable via the 3-commit-per-split pattern (stage → route → delete) proven in v1.4.0.
+- Test suite: 416 pass / 1 skip / 0 fail throughout the sprint, plus the new snapshot tripwire test (passes against generated baseline).
+- Public API surface unchanged: 15 runtime exports × 6 entry points.
+- `_ctx` policy decision: keep underscore-prefixed param for validators that don't currently consume context. Documented in `validate/elements/README.md` — stable signature lets future strict-mode or context-aware checks be added without changing call sites.
+- `loadedFamilies` initialization order: populated after `validateDocumentLevel` returns. Audit confirmed no order dependency — `document.ts` never reads `loadedFamilies`, only `validateFontSpec` for shape validation.
+- Path-traversal pre-flight in `validateImage` deferred to v2.0 — runtime SSRF + `allowedFileDirs` guards already provide defense-in-depth.
+
+---
+
+## [1.4.1] — 2026-05-23
+
+Cleanup batch addressing audit findings surfaced by the v1.4.0 god-file split. Five MEDIUM-severity items, all internal — no public API changes, no behavioral changes for callers using documented schemas. Test suite unchanged: 416 pass / 1 skip / 0 fail.
+
+### Fixed
+
+- **M1 — Dead outer `withCycleGuard` removed from `validateElement` dispatcher (`src/validate/index.ts`).** The dispatcher wrapped `list` and `float-group` cases in an outer `withCycleGuard` with an empty body, then the inner element validators (`validateList` in `elements/list.ts`, `validateFloatGroup` in `elements/structural.ts`) immediately opened their own guard on the same element. The outer guard ran a no-op body and `finally`-deleted the element from `seen` BEFORE the inner guard added it — dead code communicating false intent. The inner validators own the guard. Import of `withCycleGuard` also dropped from `index.ts` since it is no longer used there.
+- **M2 — `measure-blocks/float-group.ts ↔ measure-blocks/index.ts` runtime cycle broken (Option C: dependency injection).** `float-group.ts` previously imported `measureBlock` from `./index.js`, while `index.ts` re-exported `measureFloatGroup` from `./float-group.js` — a real ESM cycle that hoisting tolerated but which violated module-boundary discipline. Resolved by promoting `measureBlock` to an explicit parameter of `measureFloatGroup` (new exported `MeasureBlockFn` type). The sole caller (the orchestrator in `measure.ts`) already has `measureBlock` in scope, so the change is non-invasive. Option C was chosen over Option A (inlining the dispatch — too much duplication) and Option B (extracting `dispatch.ts` — restructured more than needed for a one-edge cycle).
+
+### Changed
+
+- **M3 — Concurrent validate test annotated with sync-vs-async semantics (`test/validate-concurrent.test.ts`).** Added a comment block above the parallel-validate `describe` clarifying that `validateDocument` is synchronous, so `Promise.all` over it cannot exercise real concurrent execution. The test now explicitly documents what it does prove (shape stability across N invocations) versus what it does not (concurrent isolation — guaranteed structurally by the per-call `WeakSet` opened at the top of `validate()` in `src/validate/index.ts`). The async render-path tests later in the same file DO exercise real concurrency because `render()` crosses `await` boundaries.
+- **M4 — Benchmark harness upgraded (`scripts/run-bench-snapshot.mjs`).** Default measured runs raised from 3 to 10. New `--runs N` CLI flag for callers to override (CI: 5, dev: 3, full: 10). Output now reports `median`, `p90`, and `min` in addition to `avg`. Variance on cold-tsx invocations can hit ±70%, which made any <10% regression gate meaningless at N=3.
+
+### Added
+
+- **M5 — URL scheme check in `validateImage` (`src/validate/elements/media.ts`).** When `el.src` is a string that looks like a URL (matches `data:`, `javascript:`, `vbscript:`, `blob:`, `about:`, `file:`, or any `scheme://` form), the validator now routes through `validateUrl` from `validate/helpers.ts`. Matches the runtime SSRF guard's posture in `src/compat.ts` so validate-only callers (CLI lint, MCP `validate_document` tool) catch unsafe schemes pre-flight instead of letting them through to the asset-loader guard. http/https/ftp/mailto/anchor links still pass.
+
+---
+
+## [1.4.0] — 2026-05-23
+
+Architecture sprint: four god-files split into thin orchestrators + cohesive sub-modules. **No public API changes** — guarded by `test/public-api-surface.test.ts` (15 runtime exports across 6 entry points, snapshot tripwire). 12 granular commits, each independently revertable.
+
+### Changed (internal structure — non-breaking)
+
+- **`src/validate.ts` (1834L) → `src/validate/` (9 files, ~250L each)** —
+  `validate/index.ts` orchestrator + `helpers.ts`, `fonts.ts`, `errors.ts`, and per-element validators under `elements/`. Introduced explicit `ValidationContext` ({ errors, strict, loadedFamilies, seen, options }) threaded into every element validator instead of relying on closure-captured locals. Per-call `WeakSet` for cycle detection — concurrent isolation verified by `test/validate-concurrent.test.ts`.
+- **`src/measure-blocks.ts` (1600L) → `src/measure-blocks/` (10 files)** —
+  `measure-blocks/index.ts` dispatcher + `text-blocks.ts`, `list.ts`, `image.ts`, `float-group.ts`, `highlight.ts`, `helpers.ts`, plus `table/{measure,spans,columns}.ts`. Added explicit case arms for `qr-code`, `barcode`, `chart` (previously fell through to "Unknown element type"). `_hljsCache` intentionally remains module-scoped in `highlight.ts` — idempotent process-wide cache, not concurrent-isolated state.
+- **`src/render-blocks.ts` (1277L) → `src/render-blocks/` (13 files)** —
+  Per-render-function modules. Each independent (no shared state). Dropped four unused imports from the original (`PDFFont`, `PDFName`, `renderTocEntry`, `renderFormField` — never referenced).
+- **`src/types-public.ts` (1200L) → `src/types-public/` (8 files)** —
+  Split by domain: `document.ts`, `elements-{text,block,media}.ts`, `union.ts`, `validation.ts`, `render-options.ts`. Type-only intra-package cycles are erased at runtime (verified by clean tsc build).
+
+### Added
+
+- **`test/drift-guards.test.ts` — measure-blocks dispatcher case-arm guard.** New invariant mirrors the existing validate + render guards: every `ELEMENT_TYPES` entry must have an explicit `case` arm in `src/measure-blocks/index.ts` (except internal `toc-entry`). Catches future additions to `ELEMENT_TYPES` that forget to handle measurement.
+
+### Fixed
+
+- **Dead imports removed:** `validate` was imported but never used in `src/builder.ts` after the split. Removed.
+- **Unused locals/params:** `lineHeight` in `float-group.ts` and `table/measure.ts` (computed but never read); `doc` param in `measureCallout` and `measureCode` (preserved as `_doc` for signature compatibility, signals intentional non-use).
+
+### Notes
+
+- Public API surface tripwire: 15 runtime exports across 6 entry points, all unchanged.
+- Benchmark gate: 5/7 corpora within 5% of v1.3.4; two corpora (`rich-text-mixed-spans` +12.9%, `table-stress` +7.2%) breach but match documented run-to-run variance (5-10% noise on dev machine). Cold-start module-load unchanged. CI re-snapshot recommended to disambiguate variance from regression.
+- Known follow-up: ESM-fragile circular import in `measure-blocks/float-group.ts` ↔ `measure-blocks/index.ts` (load-safe today because `measureBlock` is async-runtime only; revisit if top-level `await` is ever added).
+- Known follow-up: type-only intra-cycles in `types-public/` (no runtime risk — erased at compile time).
+
+---
+
+## [1.3.6] — 2026-05-23
+
+Architecture-sprint scaffolding release: vendor integrity check, concurrent isolation tests, signing import correctness, public API tripwire.
+
+### Added
+
+- **Boot-time vendor integrity check (#12)** — `src/version-check.ts` exports `assertVendorIntegrity()`, called once at the start of every `render()`. Verifies the vendored pretext version (`src/vendor/pretext/VERSION.ts`) is in the compatible range. Warns (does not throw) on drift. Inline semver matcher avoids adding a `semver` dependency.
+- **Concurrent validate/render isolation tests (#25)** — `test/validate-concurrent.test.ts` exercises 8 parallel `validate()` calls plus 4 parallel `render()` calls across different fonts AND different scripts (en/he/ar/th). Byte-identical fingerprints between parallel and sequential runs prove `vendor/pretext/measurement.ts` and `vendor/pretext/analysis.ts` shared state holds up under concurrent use.
+- **Public API surface tripwire** — `test/public-api-surface.test.ts` snapshots all 15 runtime exports across 6 entry points. Will guard against accidental API drift during the upcoming v1.4.0 god-file splits.
+- **P12/CMS crypto verification test (#26)** — `test/signatures-crypto.test.ts` adds a real `crypto.createVerify('RSA-SHA256')` round-trip with positive + negative cases. **Currently `t.skip`'d** — see KNOWN ISSUES below.
+- **`pretextPdf.mcpCompat`** field in `package.json` — declares `>=1.4.0 <2.0.0` compatibility range for the pretext-pdf-mcp consumer. MCP-side check ships separately.
+
+### Fixed
+
+- **`signpdf` v3 API + import correctness** — `src/post-process.ts` was destructuring `pdflibAddPlaceholder` from `@signpdf/signpdf` where it does not exist; the symbol lives in `@signpdf/placeholder-pdf-lib`. Also updated to the v3 API (`new P12Signer(buffer, { passphrase })` instead of `signer.sign(buffer, { passphrase })`). Added `@signpdf/placeholder-pdf-lib` and `@signpdf/signer-p12` to `peerDependencies` + `peerDependenciesMeta.optional` (mirroring `@signpdf/signpdf`).
+- **`SIGNATURE_DEP_MISSING` error message** — now identifies exactly which `@signpdf/*` packages are missing and tells the user which to install, instead of always listing all three.
+
+### KNOWN ISSUES (deferred to follow-up sprint)
+
+- **Signing path is architecturally non-functional** — even with correct imports, `@cantoo/pdf-lib`'s serializer is fork-incompatible with `@signpdf/placeholder-pdf-lib`. The placeholder ByteRange dict is emitted in a shape that `@signpdf/utils.findByteRange` cannot parse. End-to-end signing has never worked. The crypto verify test (#26) is correctly written and ready to run once signing is repaired. Three fix paths exist: `@signpdf/placeholder-plain` swap (breaks AcroForm), porting placeholder-pdf-lib onto cantoo primitives, or a merge-bytes approach. None are in v1.3.6 scope. The `SIGNATURE_DEP_MISSING` message now pre-warns callers.
+
+## [1.3.5] — 2026-05-22
+
+### Fixed
+
+- **`toc-entry` drift-guard regression** —
+  `test/drift-guards.test.ts` was failing because `src/validate.ts` had no
+  `case 'toc-entry':` arm. `toc-entry` elements are produced internally by
+  the TOC two-pass processor, but the drift guard correctly insists every
+  registered `ElementType` has a validator case. Added a defensive validator
+  for `text`, `pageNumber`, `level`, `levelIndent`, and `leader` so
+  user-authored `toc-entry` payloads (rare but possible) fail loud instead
+  of slipping through.
+
+### Removed
+
+- **`test/pretext-api-contract.test.ts`** —
+  Reframed in v1.3.3 as a local export-shape guard for the vendored pretext
+  layout module, but the test was tautological: it could only fail if
+  someone hand-edited `src/vendor/pretext/*.ts` to remove an export, in
+  which case TypeScript would already fail the build. Deleted along with
+  its entry in the `test:contract` npm script. Drift guards in
+  `test/drift-guards.test.ts` cover the real risk (registry vs. switch
+  arms going out of sync).
+
+### Performance
+
+- **v1.3.2+ benchmark numbers captured** —
+  Re-ran the seven core corpora against `benchmarks/benchmark-baseline.json`
+  (recorded 2026-04-10 at v1.3.0). Results documented in
+  `benchmarks/v1.3.2-results.md`: ~1.66x geometric-mean speedup across
+  corpora, with the largest wins on text-heavy workloads (table-stress
+  -52%, punctuation-heavy -51%, rtl-layout -43%). Confirms the DNS dedup,
+  parallel raster, and word-width cache work landed in v1.3.2 was real
+  rather than aspirational.
+
+### Docs
+
+- **README version table extended** —
+  Added 1.1.x (vendor switch), 1.2.x (security + benchmarks), and
+  1.3.0–1.3.4 (perf + drift guards) rows so the version table no longer
+  stops at 1.0.6.
+
+### Tooling
+
+- **`scripts/run-bench-snapshot.mjs`** —
+  Small one-shot runner that prints avg/min render time per corpus across
+  three measured runs (after a warmup). Used to capture the v1.3.5
+  benchmark results above; useful for ad-hoc perf checks without touching
+  the regression-guarded `test/benchmark-baseline.test.ts`.
+
+---
+
+## [1.3.4] — 2026-05-17
+
+### Fixed
+
+- **DNS dedup test now imports from source** —
+  `test/assets-dns-dedup.test.ts` previously imported `fetchWithTimeout` /
+  `assertSafeUrl` from `../dist/assets.js`, which would silently pass against
+  a stale build (false confidence). Switched to `../src/assets.js` so the
+  test always runs against the current source tree under tsx.
+
+### Added
+
+- **FIFO eviction boundary test for word-width cache** —
+  `test/measure-text-cache.test.ts` now asserts that when the cache is
+  pre-filled to `WORD_WIDTH_CACHE_MAX` and a new `measureWord` call is made,
+  `cache.size` stays at the cap, the oldest insertion (`syn0`) is evicted,
+  and a re-accessed entry (`syn1`) survives — proving FIFO semantics, not LRU.
+
+### Changed
+
+- **Constant tunability scope documented** — `VECTOR_RASTER_CONCURRENCY` and
+  `WORD_WIDTH_CACHE_MAX` are exported as read-only constants for observability
+  and test introspection. Consumers wanting different values must fork;
+  runtime tunability (env vars or options) is a future enhancement and not
+  planned for the v1.x line.
+
+---
+
+## [1.3.3] — 2026-05-17
+
+### Fixed
+
+- **Parallel rasterization concurrency cap** — `loadVectorAssets` now runs at
+  most 4 SVG/QR/barcode/chart rasterization tasks concurrently (was unbounded).
+  Prevents file-descriptor / worker exhaustion on documents with many vector
+  assets. New exported constant: `VECTOR_RASTER_CONCURRENCY`.
+- **Word-width cache memory bound** — `measureWord` now FIFO-evicts at 50,000
+  entries to bound memory for long-running processes that reuse a single
+  `wordWidthCache`. New exported constant: `WORD_WIDTH_CACHE_MAX`.
+
+### Changed
+
+- **Pretext API contract test reframed** — `test/pretext-api-contract.test.ts`
+  header clarified: this is a local export-shape guard for the vendored
+  pretext layout module, not an upstream version canary. Pretext has been
+  vendored at `src/vendor/pretext/` since v1.1.0.
+- **CHANGELOG clarification on v1.3.2 parallel rasterization** — see updated
+  v1.3.2 entry below; the speedup is real for I/O-bound fan-out, but CPU
+  rasterization still serializes on the V8 main thread.
+
+### Documented (not changed)
+
+- **Word-width cache scope (H1)** — the cache is currently consulted on the
+  hyphenation path (`measureTextWithHyphenation`) only. The non-hyphenation
+  branch of `measureText` delegates directly to pretext's `layoutWithLines`
+  to preserve CJK character-level breaking, RTL/bidi, Thai segmentation,
+  kerning, and justify semantics that word-by-word summing would diverge
+  from. Documents that do not configure a hyphenator will not see
+  cross-paragraph cache reuse; this is intentional for correctness.
+
+---
+
+## [1.3.2] — 2026-05-17
+
+### Performance
+
+- Removed double DNS resolution in image/SVG fetch (one lookup per remote asset, not two)
+- Parallel SVG/QR/barcode generation+rasterization (sequential embed retained for pdf-lib safety)
+  - Sub-note (added in v1.3.3): the parallelism is real for the I/O-bound fan-out
+    (remote SVG fetches overlap). CPU rasterization (sharp/svg2pdfkit) still
+    contends on the V8 main thread, so wall-clock improvement is dominated by
+    remote-asset latency, not raster throughput.
+- Document-level word-width measurement cache (cross-paragraph dedup of common-word measurements)
+  - Sub-note (added in v1.3.3): the cache is consulted on the hyphenation code
+    path only. See v1.3.3 "Documented (not changed)" for the rationale.
+
+---
+
+## [1.3.1] — 2026-05-17
+
+### Fixed
+
+- Internal test fixtures updated to set `allowedFileDirs` (resolved with `path.resolve` for Windows drive-letter compatibility) after the v1.2.2 deny-by-default flip — no library behavior change. Affected: `signatures-crypto`, `signatures-validation`, `svg`, `image-floats` test files.
+- `markdown-gfm` compat test updated to use an `https:` image src; `data:` URLs are blocked by the scheme guard added in v1.3.0, so the pre-existing fixture no longer round-tripped — test-only change.
+
+---
+
+## [1.3.0] — 2026-05-17
+
+### ⚠️ BREAKING (retroactive note covering v1.2.2)
+
+- **`assertPathAllowed` is now deny-by-default.** Documents using `file://` image sources without an explicit `allowedFileDirs` configuration will throw `PATH_TRAVERSAL`. This was shipped in v1.2.2 as a security fix but is technically a breaking change — consumers on `^1.2.0` who upgrade past v1.2.1 must either set `allowedFileDirs` or migrate away from `file://` sources. v1.3.0 is the recommended upgrade target with full semver signal.
+
+### Fixed
+
+- **Scheme guard whitespace bypass** in `compat.ts` — leading whitespace in image src (e.g. `" file:///etc/passwd"`) no longer bypasses scheme stripping.
+- **Extended scheme blocklist** in `compat.ts` — added `vbscript:`, `blob:`, `about:` alongside existing `file://`, `data:`, `javascript:`.
+
+### Tests
+
+- Added redirect-chain SSRF test using a local mock HTTP server.
+- Pinned CLI exit-code assertion to detect regressions.
+
+---
+
+## [1.2.2] — 2026-05-17
+
+### Security
+
+- **`assertPathAllowed` is now deny-by-default** — Previously, when `doc.allowedFileDirs` was
+  undefined or empty, local file:// paths were silently allowed. Now the function throws
+  `PATH_TRAVERSAL` unless `allowedFileDirs` is explicitly configured with at least one directory.
+  This closes an unintended open-access footgun for server-side deployments.
+
+- **`compat.ts` — dangerous image schemes stripped in `fromPdfmake`** — `file://`, `data:`, and
+  `javascript:` image `src` values are now silently dropped during pdfmake→pretext-pdf translation
+  rather than forwarded verbatim. This prevents the compat shim from acting as an indirect
+  bypass for the scheme-level SSRF guards in `assets.ts`.
+
+- **`compat.ts` — `allowedFileDirs` forwarded from `PdfmakeDocument`** — The `PdfmakeDocument`
+  interface now accepts `allowedFileDirs?: string[]`, which is forwarded into the resulting
+  `PdfDocument`. Callers who previously passed file paths via the compat shim can now
+  allowlist their directories explicitly.
+
+- **CLI validates before rendering** — `pretext-pdf` now calls `validateDocument()` before
+  invoking `render()`. Invalid documents produce a `VALIDATION_ERROR` message on stderr and
+  exit with code 1, avoiding wasted work during the render phase.
+
+---
+
+## [1.2.1] — 2026-05-16
+
+### Fixed
+
+- **`PretextPdfError` now preserves root cause via `err.cause`** — `ASSEMBLY_FAILED` errors
+  thrown by `merge()` and `assemble()` now carry the original pdf-lib error as `err.cause`,
+  making root-cause debugging possible without losing the upstream message.
+
+- **`form.updateFieldAppearances()` failure is now logged** — Previously silently swallowed
+  (`catch { /* non-fatal */ }`). Now emits a structured warning via the document logger or
+  `console.warn`. Behaviour is unchanged (non-fatal); the warning aids debugging.
+
+- **Owner-only encryption now warns explicitly** — When `doc.encryption` is set without
+  `userPassword`, a `console.warn` is emitted explaining that the PDF will open without a
+  password. Owner-only encryption remains valid (it restricts editing/printing, not opening).
+
+- **`assemble([{}])` now throws `VALIDATION_ERROR`** — Regression from v1.2.0 discriminated
+  union changes: passing a part with neither `doc` nor `pdf` previously crashed with a
+  `TypeError` (no `.code` property). Now throws a proper `VALIDATION_ERROR` with a clear
+  message before attempting to render.
+
+- **`watermark: {}` now throws `VALIDATION_ERROR`** — Regression from v1.2.0: the
+  `WatermarkSpec` discriminated union enforced text/image presence at compile-time but the
+  runtime validation was missing. A watermark object with neither `text` nor `image` now
+  correctly throws at validate time.
+
+- **`svg: ''` (empty string) now throws `VALIDATION_ERROR`** — Empty SVG strings passed
+  the validation stage and surfaced as `SVG_LOAD_FAILED` during render. Now caught at
+  validate time with a clear `VALIDATION_ERROR`.
+
+### Changed
+
+- **`PretextPdfError` constructor accepts optional `ErrorOptions`** — Third argument
+  `options?: ErrorOptions` (i.e. `{ cause?: unknown }`) is now accepted and passed to the
+  native `Error` constructor. Fully backwards-compatible — all existing call sites unchanged.
+
+- **bidi-js missing-peer warning routes through document logger** — When a `logger` is
+  passed to `render()`, bidi-js peer-dependency warnings are now routed through
+  `logger.warn` instead of always using `console.warn`. New low-level export:
+  `setBidiWarnFn(fn)` (prefer the `logger` render option in application code).
+
+---
+
+## [1.2.0] — 2026-05-16
+
+Post-audit hardening release. Type system tightened, concurrency-safe validation,
+@internal type leaks closed, RTL/asset failures surface as structured errors,
+SSRF defense upgraded to undici-pinned IP. No source-level API removals from the
+package entry point — see migration notes below for `@internal` types that were
+already not exported from `src/index.ts`.
+
+### Added
+
+- **Discriminated unions on four public types** (`src/types-public.ts`, audit Phase B) —
+  `WatermarkSpec`, `AssemblyPart`, `SvgElement`, and `ImageElement` (float variants)
+  now use TypeScript discriminated unions instead of flat optional structs. The
+  compiler now prevents invalid combinations (e.g., a watermark with both `text`
+  and `image`, or an SVG element with neither `svg` nor `src`) that previously
+  could only be caught at runtime. Existing valid usages continue to compile.
+
+- **`pdf-lib` type augmentation** (`src/vendor/pdf-lib-augment.d.ts`, audit Phase D) —
+  Documents the load-bearing `as any` casts against pdf-lib internals
+  (`PDFArray.push`, `PDFFont.embedder`) and removes the one genuinely-avoidable
+  cast in `measure.ts`.
+
+- **DNS rebinding defense via undici Agent IP pinning** (`src/assets.ts`, audit B6) —
+  `assertSafeUrl` was upgraded to `resolveAndValidateUrl` which returns the
+  resolved IP, and `fetchWithTimeout` now uses an undici `Agent` whose
+  `connect.lookup` callback always returns the pre-validated IP. Closes the
+  TOCTOU window where DNS could rebind between validation and connect.
+  Extended private-range coverage: 0.0.0.0/8, 192.0.0/24, 198.18/15, IPv6
+  multicast, and IPv4-mapped IPv6 normalization. +14 SSRF tests (25 total).
+
+- **Per-call cycle-detection state** (`src/validate.ts`, audit Perf-1) — Moved
+  `seenInRecursion` WeakSet from module scope into `validate()` and threaded
+  through `withCycleGuard`. Makes validation reentrant and concurrency-safe
+  (no shared mutable state across parallel `validate()` calls). +1 regression
+  test.
+
+- **Structured error codes on RTL + asset failures** (`src/errors.ts`,
+  `src/measure-text.ts`, `src/assets.ts`, audit silent-failure pass) —
+  - `RTL_REORDER_FAILED` — surfaces when `bidi-js` is installed but throws.
+    Previously fell through with `isRTL:true` on logical-order text =
+    visually broken Arabic/Hebrew renders. Missing `bidi-js` still degrades
+    gracefully (warn + LTR render) since it is an optional peer dep.
+  - `CHART_LOAD_FAILED` — embedded in warn logs from QR/barcode/chart loaders
+    so failures are debuggable from log scraping alone.
+  - `FONT_ENCODE_FAIL` — replaces the prior bare `catch` in `src/fonts.ts`
+    that silently swallowed font subset failures (audit B2).
+
+### Changed
+
+- **`@internal` types removed from the `types.ts` barrel** (audit H8 / type-design HIGH) —
+  `RichLine`, `RichFragment`, and `TocEntryElement` were tagged `@internal`
+  but re-exported through `src/types.ts`. They have been removed from that
+  barrel and canonicalized in `src/types-internal.ts`. `TocEntryElement` is
+  no longer a member of the public `ContentElement` union (it was always
+  pipeline-synthesized, never user-constructed). Internal imports updated
+  in `rich-text.ts`, `measure.ts`, `render-extras.ts`, `allowed-props.ts`,
+  `validate.ts`, `measure-blocks.ts`, `fonts.ts`. **Migration note:** these
+  types were never exported from `src/index.ts` (the package entry point),
+  so consumers using the supported import path (`import { ... } from
+  'pretext-pdf'`) are unaffected. Deep imports (`'pretext-pdf/src/types'`)
+  are unsupported and never were stable.
+
+- **`api-extractor` enforcement escalated to `error`** (`api-extractor.json`) —
+  `ae-forgotten-export` log level changed from `warning` to `error` so CI
+  fails on future `@internal` type leaks. `etc/pretext-pdf.api.md` baseline
+  regenerated.
+
+- **`assertUnknownProps` parameter tightened** (`src/validate.ts`) —
+  `obj: any` → `obj: unknown` with an explicit type guard at the boundary.
+  Removes one of the few remaining `any` exposures at a security-sensitive
+  validation entrypoint.
+
+### Fixed
+
+- **Concurrent validation false positives** (`src/validate.ts`) — Two
+  simultaneous `validateDocument(doc)` calls on the same object reference
+  could produce a false "cyclic reference detected" error because the
+  WeakSet was at module scope. Per-call WeakSet fix closes this and any
+  future re-entrant validator scenarios.
+
+- **Stale `tests-743` badge** (`README.md`) — Replaced with the durable
+  `tests-passing` (current unit count is 319).
+
+- **Dead `case 'toc-entry'` branch** (`src/fonts.ts:collectTextByFont`) —
+  After `TocEntryElement` left the public `ContentElement` union, the
+  branch became unreachable.
+
+### Migration notes (v1.1.x → v1.2.0)
+
+If you only import from `'pretext-pdf'`: **no source changes needed.**
+
+If you do unsupported deep imports of internal types
+(`'pretext-pdf/src/types'`):
+- `RichLine`, `RichFragment`, `TocEntryElement` — import from
+  `'pretext-pdf/src/types-internal'` instead, with the understanding that
+  these are not part of the stable public API and may change in any release.
+
+If you construct `WatermarkSpec` / `AssemblyPart` / `SvgElement` / `ImageElement`
+literals: you may need to delete fields you weren't using anyway. TypeScript
+will flag any literals that previously satisfied the loose type but violated
+the actual invariants.
+
+---
+
+## [1.1.3] — 2026-05-15
+
+### Added
+
+- **Cycle detection + depth cap on TableElement walk** (`src/validate.ts`, Sprint 3 / M2) —
+  The rows/cells iteration is now wrapped in `withCycleGuard`, matching the
+  protection already in place for `ListItem.items`, `FloatGroup.content`, and
+  `RichParagraph.spans`. A self-referential row or cell shape now produces a
+  structured `VALIDATION_ERROR` instead of an unbounded walk.
+
+- **Root-level depth guard for `document.content` entries** (`src/validate.ts`, Sprint 3 / M1) —
+  Each top-level element call into `validateElement` now runs an explicit
+  `assertDepthOk(depth, prefix)` so the `MAX_VALIDATION_DEPTH = 32` cap fires
+  even for plugin-typed elements that do not open their own `withCycleGuard`
+  scope. Internal recursive walks (`list`, `float-group`, `rich-paragraph`,
+  `table`) continue to enforce the cap via `withCycleGuard`.
+
+- **Round-trip tests for the pdfmake compatibility shim** (`test/compat.test.ts`, Sprint 3 / M3) —
+  Four new tests covering pdfmake → pretext → render integration, style
+  propagation, sanity rendering of native pretext docs, and large-table
+  preservation (5 columns × 10 rows).
+
+- **`## Validation` section in `README.md`** (Sprint 3 / M4) — Explicit guidance
+  to call `validateDocument()` before `render()` on untrusted input, with the
+  concrete failure modes (stack overflow on cyclic input, prototype pollution
+  via `__proto__`, runtime 500s on malformed shapes) the validator prevents.
+
+### Fixed
+
+- **Type safety in validateDocument** (`src/validate.ts`) — Replaced unchecked `as PdfDocument` cast with `isValidPdfDocumentLike()` type guard. Returns proper error when input is not a plain object.
+
+- **Prototype pollution in mergeStyles** (`src/compat.ts`) — `Object.assign(merged, s)` allowed user-supplied pdfmake JSON to pollute the prototype chain. Replaced with `copySafeStyleProperties()` that whitelists only known safe style keys (fontSize, bold, italics, color, alignment, font).
+
+- **Path traversal in digital signatures** (`src/post-process.ts`) — P12 certificate path bypassed the `allowedFileDirs` security check. Now validates path via `assertPathAllowed()` before reading, preventing directory traversal attacks via signature feature.
+
+- **Fragile errorCount regex in validateDocument** (`src/validate.ts`) — Original regex could match anywhere in error message. Refined to header-only pattern (`^Strict validation failed`) to extract true error count even when >20 errors are returned (capped array but accurate count in message).
+
+- **Fake test coverage** (`test/validate-document.test.ts`) — Removed describe block with `assert.ok(true, 'TODO')` placeholder. Replaced with documentation explaining why the non-PretextPdfError code path is manually audited.
+
+- **Missing LICENSE for vendored code** (`src/vendor/pretext/LICENSE`) — Added MIT license file with attribution to upstream pretext library and this fork, satisfying legal compliance for vendored dependencies.
+
+### Documentation
+
+- **`Logger` interface guidance** (`src/types-public.ts`, audit L2) — Expanded
+  JSDoc on the `Logger` interface and the `logger?` field on `RenderOptions`
+  to call out that passing a no-op (`{ warn: () => {} }`) silences **every**
+  advisory warning — fine in tests, dangerous in production. Documents the
+  default (`console.warn`) and recommends pino/winston for production
+  routing. No code change.
+
+- **pdfmake `defaultStyle` / `styles` mapping** (`src/compat.ts`, audit L3) —
+  Added JSDoc to `PdfmakeStyle` enumerating the supported subset
+  (`font`, `fontSize`, `bold`, `italics`, `color`, `alignment`) and the
+  silently-dropped pdfmake properties (`lineHeight`, `marginX/Y`,
+  `decoration`, `background`, `characterSpacing`, `noWrap`, etc.) that
+  consumers migrating from pdfmake commonly trip over. `fromPdfmake()`
+  now documents how `defaultStyle.font` / `.fontSize` route to
+  document-level `defaultFont` / `defaultFontSize` and how all other
+  `defaultStyle` properties cascade through `mergeStyles()`.
+
+### Changed
+
+- **Benchmark floor override** (`test/benchmark-baseline.test.ts`, audit L4) —
+  The per-corpus regression guard now honors a `PRETEXT_BENCHMARK_FLOOR_MS`
+  environment variable. Set it to a positive integer to raise the 5000ms
+  default floor on slow CI runners; set it to `skip` / `0` / `false` / `off`
+  to bypass the timing assertion entirely. The structural assertions (corpus
+  IDs match baseline, stages present) still run.
+
+### Notes — Phase A / B / D history
+
+The cycle-detection and depth-cap machinery (`withCycleGuard`,
+`MAX_VALIDATION_DEPTH`, the per-container guards on `list`, `float-group`,
+`rich-paragraph`) and the discriminated-union refactor of `ContentElement`
+plus the typed `pdf-lib` augmentation were landed during in-flight audit
+sprints between `[1.0.x]` and `[1.1.0]` that were not individually tagged.
+Sprint 3 (this release) backfills those gaps with the M1/M2 root + table
+guards, plus explicit tests and documentation.
+
+---
+
+## [1.1.2] — 2026-05-08
+
+### Fixed
+
+- **Silent font-subset failure** (`src/fonts.ts`) — Bare `catch {}` on `pdfFont.encodeText()`
+  silently swallowed glyph-encoding errors, producing wrong characters with no signal.
+  Now logs a `console.warn` so callers know which font key failed.
+
+- **Explicit RTL direction silently flipping to LTR** (`src/measure-text.ts`) — When
+  `dir:'rtl'` was set and `bidi-js` threw during reordering, the fallback incorrectly
+  returned `isRTL: false`, causing Arabic/Hebrew paragraphs to align and wrap as LTR.
+  The fallback now preserves `isRTL: true` so the layout engine honours the explicit
+  direction even without bidi reordering.
+
+- **SSRF DNS rebinding window** (`src/assets.ts`) — `assertSafeUrl()` was synchronous.
+  An attacker with TTL=0 DNS could pass the hostname check then rebind to `169.254.x.x`
+  between the check and the actual `fetch()` call. The function is now async and
+  pre-resolves hostnames via `dns.lookup()` before the private-range check, closing
+  the TOCTOU window. Falls back gracefully when DNS is unavailable (fetch will also
+  fail in that case). All call sites updated to `await assertSafeUrl()`.
+
+- **Concurrent PDFDocument mutation race** (`src/pipeline.ts`) — `loadFonts` and
+  `loadImages` were run with `Promise.all()` over the same `PDFDocument` instance.
+  Both mutate the cross-reference table, causing intermittent xref corruption under
+  load. Now sequenced: `loadFonts` completes before `loadImages` begins.
+
+- **Test suite cascade: 692 tests silently dropped on benchmark failure** (`package.json`,
+  `scripts/test-all.mjs`) — The `&&`-chained `npm test` command aborted all downstream
+  stages when `test:contract` failed. Replaced with a Node.js runner that executes all
+  4 stages and collects failures. Benchmark is now in a separate `test:benchmark` script
+  (not in `test:contract`) with `FLOOR_MS` raised to 5s to absorb dev-hardware variance.
+
+---
+
 ## [1.1.1] — 2026-05-08
 
 ### Fixed