match-page

Why this exists

Reaching design parity by improvising per-section edits is slow, inconsistent, and prone to runaways. The fix is a fixed two-phase shape: measure the whole page once, THEN iterate only the sections that diverge. Phase 1 is cheap (one render + one DOM measurement); it tells you exactly which sections need work and on which axes, so Phase 2 is targeted, not exploratory.

Inputs

outputDir (e.g. ~/Studio/_liberations/example.com), studioSitePath, themeSlug, page slug + sourceUrl, previewUrl (e.g. http://localhost:8881; front page renders at /). Captured specs: outputDir/sections/<slug>.json → sections[] (ordered by top; each carries top, height, backgroundColor, layout.padTopPx/padBottomPx/gap, fullBleed, headingSizes/headingLineHeights/headingFamilies, bodyTextSizes/bodyLineHeights/bodyFamilies, cells, textAlign, plus styledHtml — the computed-style oracle). Source screenshot: outputDir/screenshots/desktop/<slug>.png (read its real width with identify; compare at THAT width).

• replicaShotsDir — the replica screenshots directory holding comparison.json (v2) and the diff/ artifacts; used by the Phase-1 parity gate.

CRITICAL — compare against the SOURCE SCREENSHOT, not the captured numbers. The captured SectionSpec values (headingSizes, padTopPx, height, …) are measured at the 1440px desktop capture; the page renders and is compared at the source screenshot width (often 1008px), and the deterministic emitter scales type/spacing by vw/clamp. So built 26px is a captured 36px scaled at 1008 — NOT a divergence. Diffing built-render against captured-@1440 numbers produces all false positives and causes thrash. The TRUTH for visual parity is built render vs source render at the same width (pixels vs pixels). Use the captured numbers only as the values to APPLY in Phase 2, never as the comparison target.

The parity log — <outputDir>/parity-log.json

A replayable record of the SEMANTIC steps to reach parity. NOT literal markup diffs (those break when a reconstruction changes structure) — each entry is an intent an AI can re-apply by looking at the source. Format + helpers: src/lib/replicate/parity-log.ts (parseParityLog, serializeParityLog, upsertEntry, replayableEntries). One entry per band×axes: