pretext-pdf 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -7,6 +7,61 @@ Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
 
 ---
 
+## [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.
+
+### Added
+
+- **Strict validation mode**: Pass `{ strict: true }` to `render(doc, options)` to reject unknown properties. Non-strict mode (default) remains permissive for backwards compatibility.
+- **`render()` options parameter**: Updated signature to `render(doc: PdfDocument, options?: RenderOptions)` where `RenderOptions = { strict?: boolean }`.
+- **`validate()` public export**: `validate()` is now exported from `pretext-pdf` for standalone validation and testing.
+- **Validation error details**:
+  - Unknown properties reported with Levenshtein edit-distance suggestions (distance ≤2) for typo correction.
+  - Errors include JSONPath-like paths (`content[3].table.rows[0].cells[1].align`) for precise location reporting.
+  - Error accumulation: all violations collected before throwing a single VALIDATION_ERROR with formatted multi-line message.
+  - First 20 errors shown; overflow indicator present.
+- **Compile-time drift guards**: `src/allowed-props.ts` uses `Exact<T, Keys>` TypeScript type assertions to catch property definition drift at type-check time. If element types change, `tsc --noEmit` will error if allowed-props lists don't match.
+- **Property allowlists**:
+  - `ALLOWED_PROPS`: 22 element types (paragraph, heading, table, image, code, list, etc.)
+  - `ALLOWED_PROPS_SUB`: 8 sub-structures (document, metadata, table-row, table-cell, list-item, inline-span, column-def, annotation)
+
+### Internal
+
+- `src/allowed-props.ts` (new): Central configuration for allowed properties with compile-time assertions.
+- `src/validate.ts` (enhanced): Added `levenshteinDist()`, `closestMatch()`, `assertUnknownProps()`, and `formatErrors()` helpers; threading strict flag through `validateElement()` for nested structure validation (tables, lists, rich-paragraphs, float-groups, annotations).
+
+---
+
+## [0.9.2] — 2026-04-22
+
+Maintenance release. Engine refresh + repo-hygiene automation. No runtime behavior changes beyond the `@chenglou/pretext` bump.
+
+### Changed
+
+- **Bumped `@chenglou/pretext` to 0.0.6** (from 0.0.5). Brings two upstream improvements: (a) CJK text followed by opening-bracket annotations now wraps like browsers instead of leaving the opening bracket on the previous line (upstream PR #148), (b) native numeric `letterSpacing` support on `prepare()` and `prepareWithSegments()` (upstream PRs #108/#156). Our manual letterSpacing compensation in `src/measure-blocks.ts` and `src/rich-text.ts` continues to work unchanged — delegating to pretext's native path is tracked as Tier 1 follow-up in `docs/ROADMAP.md`. All 624 tests green, all 5 visual regression baselines green.
+
+### Fixed
+
+- **README badges matched to reality**: `runtime-deps-7` → `runtime-deps-8` (there are 8 direct `dependencies`, not 7), `tests-600+` → `tests-624` (the full `npm test` chain runs 624 tests across 5 subsuites). Drift guarded by a new CI step; see below.
+
+### Added
+
+- `scripts/verify-badges.js` + CI step — compares README shields.io badge values against `package.json` dep count and `npm test` total. Fails CI on drift. Fast path via `SKIP_TEST_RUN=1` for pre-commit use.
+- `release` job in `ci.yml` — on `v*` tag push, auto-extracts the matching `## [X.Y.Z]` section from this file and creates the GitHub release (requires publish to succeed first). Closes the "tag exists but no release page" gap that affected v0.9.1. (Note: originally shipped as `.github/workflows/release-on-tag.yml`; merged into `ci.yml` for dependency ordering in Tier 0.5.)
+- `renovate.json` — watches dependencies, auto-merges devDependency bumps that pass CI, opens PRs (without auto-merge) for runtime, peer, and `@chenglou/pretext` engine bumps. Closes the gap that left us one release behind upstream.
+
+### Removed
+
+- `test/smoke-staging.test.ts` — exercised a non-existent `{ type: 'paragraph', footnote: {...} }` shape that the permissive validator silently accepted. False coverage. A strict validator rollout (rejecting unknown element properties) is the root fix and is tracked as a Tier 1 item in the rewritten `docs/ROADMAP.md`.
+- `src/brain/` — inert auto-logger artifact (34 blank-body entries, no active writer). Never published to npm.
+
+### Docs
+
+- `docs/ROADMAP.md` — complete rewrite as a living document (Now / Next / Under consideration / Shipped / History + Update discipline). The previous "master remediation plan" with phase-numbered sections was dropped: phases 0–5 all shipped by v0.9.1, and the document had rotted to the point of contradicting `package.json` on dependency pinning and `CHANGELOG.md` on what was live. History section preserves the prior plan's origin date and scope for reference.
+
+---
+
 ## [0.9.1] — 2026-04-21
 
 Bug-fix + hardening release. Ships the callout + rich-text rendering fixes from PR #2 together with PR #3's producer-validator contract around measured blocks.
@@ -455,112 +510,3 @@ Three additive enhancements that broaden the package's surface without growing i
 - Image formats: PNG, JPG, WebP
 - Table features: custom column widths, cell padding, borders, header styling
 - Colors: hex color codes throughout (text, backgrounds, borders)
-
----
-
-## Features by Phase
-
-| Phase | Feature | Status | Tests | Version |
-|-------|---------|--------|-------|---------|
-| 7A | Bookmarks / PDF Outline | ✅ Complete | 8 | 0.1.0 |
-| 7B | Watermarks | ✅ Complete | 8 | 0.1.0 |
-| 7C | Hyphenation | ✅ Complete | 10 | 0.1.0 |
-| 7D | Table of Contents | ✅ Complete | 10 | 0.1.0 |
-| 7E | SVG Support | ✅ Complete | 8 | 0.1.0 |
-| 7F | RTL Text Support | ✅ Complete | 12 | 0.1.0 |
-| 7G | Encryption | ✅ Complete | 7 | 0.1.0 |
-| Integration | Feature Combinations | ✅ Complete | 6 | 0.1.0 |
-| 6 | Advanced Features | ✅ Complete | — | 0.1.0 |
-| 5 | Rich Text / Builder API | ✅ Complete | — | 0.1.0 |
-| 1–4 | Core Engine | ✅ Complete | — | 0.1.0 |
-
----
-
-## How to Use Examples
-
-All Phase 7 features have working examples in the `examples/` directory. Run them with:
-
-```bash
-npm run example:watermark    # Phase 7B — Watermarks
-npm run example:bookmarks    # Phase 7A — Bookmarks
-npm run example:toc          # Phase 7D — Table of Contents
-npm run example:rtl          # Phase 7F — RTL Text Support
-npm run example:encryption   # Phase 7G — Encryption
-```
-
-PDF output is written to `output/phase7-*.pdf`.
-
----
-
-## Test Coverage
-
-All phases include comprehensive test coverage:
-
-```bash
-npm test                  # Run all 75+ tests
-npm run test:unit        # Unit tests only
-npm run test:e2e         # End-to-end tests
-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)
-- `bidi-js` — Bidirectional text algorithm (Phase 7F)
-- `hypher` — Hyphenation algorithm (Phase 7C)
-- `hyphenation.en-us` — English hyphenation patterns (Phase 7C)
-
-### Optional (Peer)
-
-- `@napi-rs/canvas` — SVG rasterization (Phase 7E)
-- `@cantoo/pdf-lib` — PDF encryption (Phase 7G)
-
----
-
-## Architecture
-
-pretext-pdf uses a modular, layered architecture:
-
-```
-render(doc) → validate → layout → paginate → render-pages → PDF bytes
-```
-
-Each phase adds features orthogonally:
-- Phase 1–4: Core engine, pagination, typography
-- Phase 5: Rich text and builder patterns
-- Phase 6: Advanced layout and formatting
-- Phase 7: Security, internationalization, accessibility
-
----
-
-## Future Roadmap
-
-Potential Phase 8+ features (not yet implemented):
-- Hyperlinks and anchors
-- Justified text alignment
-- Enhanced text decorations
-- Font subsetting for file size reduction
-- Browser compatibility improvements
-- Performance optimizations
-
----
-
-## Contributing
-
-pretext-pdf is actively maintained. To report issues, request features, or contribute:
-
-1. Check existing issues on the project repo
-2. Write failing tests first (TDD)
-3. Submit pull requests with test coverage ≥80%
-
----
-
-## License
-
-Check LICENSE file in repository root.