pretext-pdf 0.9.3 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,143 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 
 ---
 
+## [1.0.1] — 2026-05-02
+
+Patch: strict mode correctness fixes. No API changes.
+
+### Fixed
+
+- **`levenshteinDist` early-exit bug** — per-cell `if (curr[j]! > 2) return 999` inside
+  the inner DP loop fired on intermediate cells, causing d=1 pairs like `hrefs→href` and
+  `spaceafter→spaceAfter` to incorrectly return 999 instead of 1. Fix: removed the per-cell
+  guard; final check only (`prev[n]! > 2 ? 999 : prev[n]!`).
+- **Seven path-prefix annotations** — strict-mode error paths had `(type)` suffixes
+  (e.g. `doc(table).rows[0]`) that no other validator used and that tests didn't expect.
+  All seven removed so paths are plain dot-notation.
+- **`encryption` block not strict-checked** — unknown props inside `doc.encryption`
+  were silently accepted in strict mode. Now validated against `ALLOWED_PROPS_SUB['encryption']`.
+- **Root path was `'document'` not `'doc'`** — top-level `assertUnknownProps` was called
+  with `'document'` as the path prefix, producing paths like `document.content[0]` instead
+  of `doc.content[0]`. Corrected to `'doc'`.
+- **Suggestion format mismatched** — `Did you mean 'x'?` → `did you mean "x"` (lowercase,
+  double-quotes) to match the format tests asserted.
+- **`formatErrors` missing header** — multi-error output now begins with
+  `Strict validation failed (N issues):\n` so callers can detect strict vs. regular errors.
+
+### Tests
+
+- Added `test/validate-strict.test.ts` (35 tests) to `test:unit` script — these tests were
+  written but not wired into CI in v1.0.0.
+
+---
+
+## [1.0.0] — 2026-05-02
+
+First stable release. Completes the plugin extension API, closes all v1.0 gate requirements,
+and ships a fully verified public surface with zero breaking changes from 0.9.x.
+
+### Added
+
+- **Plugin extension API** — Register custom element types via `RenderOptions.plugins`.
+  Each `PluginDefinition` participates in all four pipeline stages: `validate`, `loadAsset`,
+  `measure`, and `render`. Plugins are fully typed and tree-shaken from documents
+  that don't use them. See README § Custom element types (plugins) and
+  `examples/plugin-custom-element.ts` for a runnable example.
+- **`PluginDefinition`, `PluginMeasureContext`, `PluginMeasureResult`, `PluginRenderContext`**
+  exported from `pretext-pdf` public surface (previously internal).
+- **`PdfBuilder` and `PdfBuilderOptions`** exported from `pretext-pdf` (enables type-safe
+  builder construction in downstream code without re-declaring the interface).
+- **`TocEntryElement`** exported from `pretext-pdf` public surface (was in the `ContentElement`
+  union but not individually importable).
+- **`plugins` option on `createPdf()`** — `PdfBuilderOptions.plugins` threads plugins through
+  the builder's `build()` call automatically.
+- **`Intl.Segmenter` pre-flight guard** in `render()` — throws `RENDER_FAILED` with a clear
+  message on Node.js < 16 or runtimes without full-ICU data, instead of silently producing
+  incorrect line breaks.
+- **`PluginRenderContext.pageWidth/pageHeight/margins`** — render hooks now receive full page
+  geometry for layout calculations (page-relative positioning, bleed boxes, etc.).
+- **`render` context Y-coordinate docs** — expanded JSDoc with multi-line text example showing
+  how to position text baselines relative to `context.y`.
+- **Benchmark corpora manifest** and **smoke staging** tests wired into `npm test`
+  (previously orphaned).
+- **`test/table-determinism.test.ts`** — asserts that table pagination produces identical
+  layout traces across repeated invocations of `prepareLayoutState`.
+- **`test/validate-strict.test.ts`** (35 tests) — comprehensive contract for `strict: true`
+  validation covering all element types, nested structures, Levenshtein suggestions, error
+  message format, doc-level and sub-structure prop checks. Total test count: 676.
+- `examples/plugin-custom-element.ts` — runnable plugin example (`npm run example:plugin`).
+
+### Fixed
+
+- **`SIGNATURE_CERT_AND_ENCRYPTION` error code** — was declared in the `ErrorCode` union
+  but never thrown; validate.ts now uses it correctly when a document specifies both
+  signatures and encryption (previously threw a generic `VALIDATION_ERROR`).
+- **Build break under `exactOptionalPropertyTypes: true`** — `PdfBuilder.build()` no longer
+  passes `{ plugins: undefined }` to `runPipeline` when no plugins are configured.
+- **Plugin `validate` hook empty-string normalization** — `plugin.validate()` returning `''`
+  now correctly accepts the element (was previously treated as a rejection message).
+- **`toc` element reaching render default arm** — `render.ts` now has an explicit
+  `case 'toc': return` guard before the default arm; TOC elements are pre-processed
+  during pagination and should never reach the renderer.
+- **`RichLine` and `RichFragment`** demoted from `@public` to `@internal`; these are
+  implementation details of the rich-text pipeline, not intended for external use.
+- **Sentinel value documentation** — `MeasuredBlock` comment now explicitly states that
+  `lines: []`, `fontSize: 0`, `lineHeight: 0`, `fontKey: ''` applies to spacers, tables,
+  images, hr, *and plugin blocks* — not a bug but a documented convention.
+
+### Internal
+
+- `src/plugin-registry.ts` (new): Pure orchestration helpers for the four plugin injection
+  points (`findPlugin`, `runPluginValidate`, `runPluginLoadAsset`, `runPluginMeasure`,
+  `runPluginRender`).
+- `src/plugin-types.ts` (new): `PluginDefinition` interface and context/result types.
+- `src/layout-state.ts`: `prepareLayoutState` now accepts `options?: RenderOptions` and
+  threads plugins to `stageValidate`, `stageLoadAssets`, and `stageMeasure`.
+- `docs/V1.0-RUNBOOK.md`: Full release runbook with first-principles audit, anti-hallucination
+  protocol, verified-facts table, and phase-by-phase plan.
+
+---
+
+## [0.9.4] — 2026-05-02
+
+> **Note:** This release was never published to npm as a standalone tag. All changes listed
+> here shipped as part of [1.0.0] on the same date.
+
+Architecture hardening + API surface snapshot. No public API changes; internal
+restructuring to eliminate circular dependencies and add drift guards before v1.0 freeze.
+
+### Added
+
+- **API surface snapshot** (`etc/pretext-pdf.api.md`) checked into source control as
+  the v1.0 baseline. The `api:check` CI step will fail on unintentional public-API drift.
+- **`src/layout-state.ts`** — `prepareLayoutState()` and `summarizeLayoutState()` extracted
+  from the pipeline for testability; `layout-contract` and `hard-text-contract` tests
+  wired into `test:unit`.
+- **`src/benchmarks/corpora.ts`** — benchmark corpus manifest (`getBenchmarkCorpora()`)
+  restored from git history; `benchmark-baseline.test.ts` wired into `test:contract`.
+- **Drift guards** (`test/drift-guards.test.ts`) — asserts that `ELEMENT_TYPES`,
+  `ALLOWED_PROPS`, `validate.ts` cases, and `render.ts` cases all agree at test time.
+  Catches any future element-type addition that isn't plumbed through all four places.
+- **`render.ts` default arm** — unknown element types now throw immediately instead of
+  silently producing a blank block.
+
+### Refactored
+
+- **Circular dependency broken**: `src/post-process.ts` extracted so `builder.ts` and
+  `index.ts` no longer form a cycle through each other.
+- **`ELEMENT_TYPES` extracted** to `src/element-types.ts` as single source of truth;
+  re-exported from `index.ts`, imported by `validate.ts` — eliminates the previous
+  per-file string-literal duplication.
+
+### Fixed
+
+- `post-process.ts`: drop raw signing library error message from `SIGNATURE_FAILED`
+  to avoid leaking certificate or passphrase details in error output.
+- `layout-state.ts`: polyfill install wrapped in try/catch; throws `CANVAS_UNAVAILABLE`
+  on failure instead of an untyped exception.
+
+---
+
 ## [0.9.3] — 2026-04-23
 
 Strict validation release. Opt-in property validation to catch unknown properties on elements and sub-structures via typo detection and precise JSONPath error reporting.
@@ -192,7 +329,10 @@ Three additive enhancements that broaden the package's surface without growing i
 
 ---
 
-## [Unreleased]
+## [0.7.2] — 2026-04-20
+
+Phase 11 cross-cutting enhancements. This section was left as `[Unreleased]` in earlier
+entries and is being attributed retroactively to 0.7.2 for historical accuracy.
 
 ### Added (Phase 11 — Cross-cutting Enhancements)