Add rendering-verification design spec: LOD invariants and a visual-regression corpus

[Alek99]

Summary

Adds spec/process/rendering-verification.md (plus the spec/README.md index entry): the design for the two test surfaces that make constant renderer churn safe during the refine-and-optimize phase. Design only — no implementation in this PR.

The motivating pattern: the recent regression run — density flicker on pan/zoom-out (#118), scatter collapse after repeated box-zoom (#87), dense scatter blanking on double-click (#79), example-asset styling drift (#60) — is all one bug class: pixels went wrong silently, past gates that check "did it render something" rather than "is it still right".

Workstream A — LOD invariant property tests

Hypothesis-driven (already a dev dependency, pattern proven in tests/test_framing_property.py), exercising the native kernels through the real ctypes ABI against O(n) NumPy oracles — no new Rust crates, so no vendoring problem. Ten invariants specified as a contract table, including:

• M4 extrema-exactness per pixel column (the Tier-1 truthfulness claim)
• density/hexbin count fidelity + the occupied-bins-only wire contract
• standalone worker re-bin ≡ kernel re-bin (the Fix standalone density flicker on pan/zoom-out #118 shape)
• re-bin mass conservation for histogram/bar
• NaN containment (dossier §19) and f32 offset-encoding error bounds (§4)
• f64 view round-trips and tier-decision/hysteresis consistency (L1/L2/L3)

Runs inside the existing pytest -q gate with a bounded CI Hypothesis profile (≤ 60 s added).

Workstream B — golden visual-regression corpus

Canvas-readback goldens per chart family × interaction state — first paint is the least interesting entry; the states are where the shipped bugs lived (repeated box-zoom + zoom-out, double-click reset, pan-then-zoom-out-past-home, drill in/out, kernel-less worker re-bin). Gestures driven over CDP with settled-signal waits. Determinism contract: one pinned Chromium, DPR 1, canvas pixels only — DOM chrome stays under the existing conformance layout-box approach; Firefox/WebKit keep the tolerant signature. The repo stays binary-free — no committed PNGs and no Git LFS: the committed baseline is a small text manifest of per-tile signatures and thresholds; images exist only as on-demand CI artifacts (expected/actual/diff triptychs rendered from the PR merge-base); manifest updates ship in the same PR as the rendering change.

Discipline

• Fail-first calibration: revert the Fix standalone density flicker on pan/zoom-out #118/Scatter view collapses to a horizontal line after repeated box-zoom + zoom-out #87/Double-clicking a dense Reflex scatter chart can blank the plot #79 fixes in scratch branches and inject deliberate M4/hexbin off-by-ones — the suite must catch each, or strategies/states are sharpened until it does.
• Rollout: properties are hard-gated from day one (they're just pytest); the corpus starts advisory and is promoted after two weeks green, then lands in the production-readiness release-blocking table. Explicit non-goals: cross-OS pixel identity, full-page glyph goldens, perf detection (CodSpeed owns it).

Related direction: follows the refine-and-optimize focus alongside #129 (view-state layer); the corpus's interaction states are also the safety net for implementing that spec.

Validation

• uv run ruff check . / targeted pre-commit on the changed files — clean
• codespell — clean (repo's own "LOD" terminology excepted)

[codspeed-hq]

Merging this PR will not alter performance

✅ 94 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing alek/spec-rendering-verification (2fbcfc9) with main (79b0a3f)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR defines two test surfaces for catching silent rendering regressions. The main changes are:

• Property-based checks for LOD kernels and rendering invariants.
• A manifest-based visual corpus covering chart families and interaction states.
• A client settle counter for deterministic browser captures.
• CI rollout, calibration, runtime budgets, and baseline regeneration rules.
• An index entry for the new design document.

Confidence Score: 5/5

This looks safe to merge.

The histogram conservation rule limits cross-resolution checks to nested subdivisions. The offset-encoding invariant defines a measurable error bound. The visual harness makes the settle counter an explicit client deliverable. No blocking issues remain in the changed specification.

T-Rex Logs

What T-Rex did

• The pre-validation state shows that the codespell module was missing, as documented in docs-validation-01-before.log.
• The post-validation state shows Ruff success and that the repository-configured codespell blocker is active, as documented in docs-validation-02-after.log, including the commands run, the working directory, outputs, and exit codes.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
spec/process/rendering-verification.md	Defines the LOD property suite, visual corpus, deterministic capture contract, and phased CI rollout.
spec/README.md	Adds the rendering-verification design to the specification index.

_{Reviews (2): Last reviewed commit: "Keep the visual corpus binary-free: mani..." | Re-trigger Greptile}