feat: add measurement-validator module (Phase 1)

[Copilot]

Adds a new src/measurement-validator/ module that compares Pretext's canvas-based measurements against actual browser DOM rendering (via Range API) to surface per-line divergences and classify root causes.

New modules

• types.ts — Core types: MeasurementSample, ComparisonResult, DivergenceMetrics, LineComparison, Severity; severity thresholds and classifySeverity()
• dom-adapter.ts — measureDOM(): hidden container + document.fonts.ready + Range API + Intl.Segmenter grapheme walk to extract per-line widths as ground truth
• comparator.ts — compare() / compareAll(): runs prepareWithSegments + layoutWithLines alongside measureDOM, diffs line widths, and applies lightweight root-cause heuristics (bidi/RTL char ranges, emoji, line-count mismatch, Safari kerning)
• report-generator.ts — buildReport(), toJSON(), toConsoleText(), printReport()
• index.ts — Public re-exports

Tests & fixtures

• test/measurement-validator.test.ts — severity classification, report aggregation, Pretext layout integration, comparator arithmetic; uses the same fake canvas backend as layout.test.ts
• test/fixtures/english-samples.json — 10 English samples (varied widths, font sizes, pre-wrap, forced grapheme breaks)

Docs

• docs/measurement-validator.md — API reference, severity table, Phase 1 limitations

Usage

import { compare, buildReport, printReport } from '@chenglou/pretext/measurement-validator'

const result = await compare({
  text: 'The quick brown fox jumps over the lazy dog.',
  font: '16px Arial',
  maxWidth: 300,
})

console.log(result.metrics.severity)    // 'exact' | 'minor' | 'major' | 'critical'
console.log(result.metrics.maxLineDelta) // e.g. 0.042

printReport(buildReport([result]))

Severity thresholds

Level	Delta	Signal
exact	< 0.1 px	Sub-pixel rounding only
minor	0.1–0.5 px	Acceptable; worth noting in tight layouts
major	0.5–2.0 px	Visible in dense text; root cause should be identified
critical	≥ 2.0 px	Font/shaping mismatch; line breaks will diverge

DOM-dependent paths (measureDOM, compare, compareAll) require a real browser environment — JSDOM has no layout engine and will return zero-width lines.

Original prompt

Phase 1: Measurement Validator Implementation - BUILD STEP

OBJECTIVE

Implement the Measurement Validator module from scratch in the Pretext codebase. This is the FULL Phase 1 build, not a PR yet - we'll test locally first, then create PR.

WHAT WE'RE BUILDING

Core Components

1. types.ts - TypeScript interfaces for measurement validation
2. dom-adapter.ts - Browser DOM measurement functionality
3. comparator.ts - Pretext vs DOM comparison engine
4. report-generator.ts - JSON/console report formatting
5. index.ts - Module exports
6. measurement-validator.test.ts - Integration tests
7. fixtures - Test data
8. docs - User-facing documentation

Directory Structure

src/measurement-validator/
├── types.ts
├── dom-adapter.ts
├── comparator.ts
├── report-generator.ts
└── index.ts

test/
├── measurement-validator.test.ts
└── fixtures/
    └── english-samples.json

docs/
└── measurement-validator.md

FILES TO CREATE

1. src/measurement-validator/types.ts

Complete type definitions for the validator module.

2. src/measurement-validator/dom-adapter.ts

Measures text using actual browser DOM rendering (ground truth).

3. src/measurement-validator/comparator.ts

Core comparison engine - compares Pretext measurements against DOM.

4. src/measurement-validator/report-generator.ts

Formats results into JSON, console summaries, and detailed reports.

5. src/measurement-validator/index.ts

Public API exports.

6. test/measurement-validator.test.ts

Integration tests covering all major flows.

7. test/fixtures/english-samples.json

10 English test cases with varying widths and fonts.

8. docs/measurement-validator.md

Getting started guide with examples and API reference.

IMPLEMENTATION NOTES

Design Decisions

• DOM as ground truth: We compare Pretext against actual browser rendering
• Range API for measurement: Reliable cross-browser approach
• Severity thresholds: exact (<0.1px), minor (0.1-0.5px), major (0.5-2px), critical (>2px)
• English-first: Phase 1 focuses on LTR English text, RTL/CJK in Phase 2
• Async design: DOM measurements require font loading, so everything is async

Performance Target

• Single sample: <100ms
• Full 10-sample corpus: <2 seconds
• Memory: <50MB

Testing Strategy

• Unit tests for each component
• Integration test with real Pretext layouts
• Fixture-based testing with 10 English samples
• Browser environment required (JSDOM in vitest)

SUCCESS CRITERIA

✅ All files created and compile without errors
✅ Tests pass locally
✅ Can measure and compare Pretext vs DOM
✅ All 10 fixtures pass (>99% accuracy within 0.5px)
✅ No TypeScript errors
✅ Ready for code review and PR creation

The following is the prior conversation context from the user's chat exploration (may be truncated):

Assistant: JACKPOT. Let me map this ecosystem map more carefully:

PRETEXT ECOSYSTEM: ACTUAL SHIPPING PRODUCTS

Looking at the @chenglou/pretext usage across GitHub (10+ results shown, likely 50+):

Production Apps Already Using Pretext:

1. fastrepl/char — Code collaboration platform (HYPR web)

• @chenglou/pretext: ^0.0.4
• Using for real-time code layout in editor
• This is shipping to production

2. vectorize-io/hindsight — Semantic memory/AI system (Control plane)

• @chenglou/pretext: ^0.0.3
• Using for text measurement in semantic UI

3. mayneyao/eidos — Database/spreadsheet app

• @chenglou/pretext: ^0.0.3
• Using for table cell layout without DOM measurement

4. liyown/marknative — Markdown → PNG/SVG rendering

• @chenglou/pretext: ^0.0.3
• Server-side Markdown rendering (the real game changer)
• Uses skia-canvas for drawing
• This is the SSR killer app

5. Simon-He95/markstream-vue — Rich markdown editor

• @chenglou/pretext: ^0.0.3
• Using for editor layout without reflow

6. xiaoiver/infinite-canvas-tutorial — Infinite whiteboard/canvas

• @chenglou/pretext: ^0.0.3
• Using for text rendering on WebGL canvas
• This is creative pro software

7. guangzan/tona — Blog engine/CMS

• @chenglou/pretext: catalog:
• Using in theme system for typography

8. KashyapTan/Xpdite — AI/ML desktop application

• @chenglou/pretext: ^0.0.4
• Using in terminal UI for text layout

9. zuoban/zb-reader — EPUB reader

• @chenglou/pretext: ^0.0.3
• Using for ebook layout without DOM

---

CRITICAL INSIGHT: The Real Problem

These apps all have the same issue:

1. ✅ They got Pretext working (measure text)
2. ✅ They're shipping products (chat, reader, editor, whiteboard)
3. ❌ They're ALL rebuilding the same selection/interaction layer
4. ❌ They're ALL rebuilding the same caching
5. ❌ They're ALL fighting the same bugs (bidi, font fallback, etc.)

---

What They ACTUALLY Need

Based on real shipped products:

TIER 0: BLOCKING EVERYONE (Months of wasted dev time)

**GEM #...

This pull request was created from Copilot chat.