styleproof 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.9.0]
+
+### Added
+
+- **Deterministic captures with no per-repo fixtures.** `defineStyleMapCapture` now records each surface's data responses on the baseline run and replays them on the comparison run, so a diff reflects code, not live-data drift — a backend blip or a flipped status chip no longer reads as a style change on a PR that touched no CSS. Set `STYLEPROOF_REPLAY_FROM=<base dir>` on the head capture; only data URLs (`**/api/**`, configurable via `replayUrl` / `STYLEPROOF_REPLAY_URL`) are intercepted, so the app's own JS/CSS still load live and the captured run runs its own code. If the backend is down during a run, both sides replay the same recording — no phantom diff.
+- **Frozen clock during capture** (`freezeClock`, on by default; `clockTime` to set the instant). Pins `Date.now()` / `new Date()` so time-derived styling (relative-age classes, "stale > 1h" flags) can't drift between runs; timers keep running so settling/polling still work.
+- **Capture self-check** (`STYLEPROOF_SELFCHECK=1` / `selfCheck`). Captures each surface twice and fails with a clear _"non-deterministic capture"_ error (naming the drifting element) if the two differ — so a replay gap or unseeded randomness is caught at setup time instead of surfacing as a phantom change on an unrelated PR.
+
+## [1.8.1]
+
+### Fixed
+
+- The crop annotation now boxes the **innermost** changed elements (the added
+  avatars, the restyled cards) instead of the container the crop anchors on —
+  whose box just traced the whole frame and told you nothing. An element present
+  on only one side (added/removed) is boxed only there.
+
 ## [1.8.0]
 
 The crop now shows you where to look — without painting over the UI.

package/README.md

@@ -103,11 +103,12 @@ jobs:
       - run: npx wait-on http://localhost:3000
       - run: STYLEMAP_DIR=base npx playwright test e2e/styleproof.spec.ts
 
-      # capture the PR head
+      # capture the PR head — replay the base's recorded data so the diff is
+      # code, not live-data drift (see "Deterministic by default" below)
       - run: git checkout ${{ github.event.pull_request.head.sha }}
       - run: npm ci && npm run build && (npm run serve &)
       - run: npx wait-on http://localhost:3000
-      - run: STYLEMAP_DIR=head npx playwright test e2e/styleproof.spec.ts
+      - run: STYLEMAP_DIR=head STYLEPROOF_REPLAY_FROM=__stylemaps__/base npx playwright test e2e/styleproof.spec.ts
 
       # report + gate
       - uses: BenSheridanEdwards/styleproof@v1
@@ -121,7 +122,13 @@ jobs:
 
 **4. Require the `StyleProof` status** in branch protection. Now an unsigned visual change can't merge.
 
-> Capture both sides in the **same environment** (same machine, same env vars): if env vars change _what renders_, base and head will diff on DOM no PR touched.
+**Deterministic by default — no fixtures required.** A style diff only means something if both sides saw the same inputs; otherwise live-data drift (a backend blip, a `5m ago` timestamp, a status chip that flips) reads as a style change on a PR that touched no CSS. StyleProof handles this for you:
+
+- **Record / replay.** The base capture records each surface's data responses (anything matching `**/api/**`) to a HAR; the head capture replays them, so the head renders _its_ code against the _base's_ data — the app's own JS/CSS still load live. Backend down during a run? Both sides replay the same recording, so there's no phantom diff. Point the head capture at the base's recording with `STYLEPROOF_REPLAY_FROM=<base dir>` (see the CI step above); tune the data boundary with `STYLEPROOF_REPLAY_URL` / `replayUrl` if your API isn't under `/api`.
+- **Frozen clock.** `Date.now()` / `new Date()` are pinned to a fixed instant, so time-derived styling (`stale > 1h → red`) can't drift. Timers keep running, so settling still works.
+- **Self-check** (`STYLEPROOF_SELFCHECK=1`). Captures each surface twice and fails if they differ — a replay gap or unseeded randomness surfaces as a clear _"non-deterministic capture"_ error, never as a phantom change on an unrelated PR.
+
+> Replay covers data the page _fetches_. If your app **server-renders** differently per environment (SSR feature flags, locale), still capture both sides with the same server env so the rendered HTML matches.
 
 **Live pages just work.** Before each capture, StyleProof settles the page — it waits until the computed-style map stops changing, so async content (a fetch, an SSE/WebSocket stream backfilling a grid) is captured loaded, not mid-load. Anything still moving on its own after that is detected as a live region and excluded from the diff, so a stream or ticker never reads as a change — no manual `ignore` needed. Disable or tune with `captureStyleMap(page, { stabilize: false })` / `{ stabilize: { quietFor, timeout } }`.
 

package/dist/report.js

@@ -20,10 +20,17 @@ const union = (a, b) => {
 };
 const intersects = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
 const visible = (b) => !!b && b.w > 0 && b.h > 0;
-/** Outermost changed paths: drop any path that has a changed strict ancestor. */
+/** Outermost changed paths: drop any path that has a changed strict ancestor.
+ *  Used to ANCHOR a crop (zoom to the whole changed region, not a leaf). */
 function outermost(paths) {
     return paths.filter((p) => !paths.some((q) => q !== p && p.startsWith(q + ' > ')));
 }
+/** Innermost changed paths: drop any path that has a changed strict descendant.
+ *  Used to ANNOTATE — box the leaf elements that actually changed (the added
+ *  avatars, the restyled cards), not their container, whose box ≈ the whole crop. */
+function innermost(paths) {
+    return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(p + ' > ')));
+}
 /** Headline counts with the zeros dropped — `0 state-delta difference(s)` is noise. */
 function changeCountLabel(shown) {
     const parts = [];
@@ -748,10 +755,13 @@ export function generateStyleMapReport(opts) {
                 const after = cropPng(pngB, cropBox, w, h);
                 const composite = compositePair(before.png, after.png);
                 writePng(path.join(outDir, `${stem}-composite.png`), composite);
-                // Annotated twin: outline each changed element on both sides, so the eye
-                // lands on what the bullet named. The clean image stays the default.
-                const rectsA = g.paths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
-                const rectsB = g.paths.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
+                // Annotated twin: outline the LEAF changed elements (the added avatars, the
+                // restyled cards) on each side — not the merged container the crop anchors
+                // on, whose box would just trace the whole frame. An element present on only
+                // one side (added/removed) is boxed only there.
+                const markPaths = innermost([...new Set(regionFindings.map((f) => f.path))]);
+                const rectsA = markPaths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
+                const rectsB = markPaths.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
                 const annotated = compositePair(annotateCrop(before, rectsA), annotateCrop(after, rectsB));
                 writePng(path.join(outDir, `${stem}-annotated.png`), annotated);
                 images = { composite: `${stem}-composite.png`, annotated: `${stem}-annotated.png` };

package/dist/runner.d.ts

@@ -32,14 +32,50 @@ export type DefineOptions = {
      * without screenshots still diff, but produce text-only reports.
      */
     screenshots?: boolean;
+    /**
+     * Replay a baseline run's recorded responses so a before/after diff reflects
+     * code, not live-data drift. When set (or via STYLEPROOF_REPLAY_FROM), each
+     * surface replays `<replayFrom>/<key>@<width>.har` for requests matching
+     * `replayUrl`; otherwise the run RECORDS that HAR into its own dir for the
+     * comparison run to replay. Only data URLs are intercepted, so the app's own
+     * JS/CSS still load live — the captured run renders ITS code against the
+     * baseline's data. This is what makes captures deterministic with no per-repo
+     * fixtures: record once on the base, replay on the head.
+     */
+    replayFrom?: string;
+    /**
+     * URL glob for the data boundary to record/replay (default `**\/api/**`, or
+     * STYLEPROOF_REPLAY_URL). Requests outside it (JS/CSS/fonts/images) always
+     * load live so the captured code actually runs.
+     */
+    replayUrl?: string;
+    /**
+     * Freeze `Date.now()`/`new Date()` to a fixed instant so time-derived styling
+     * (relative-age classes, "stale > 1h" flags) can't drift between runs. Timers
+     * keep running, so settling/polling still works. Default true.
+     */
+    freezeClock?: boolean;
+    /** Fixed instant for the frozen clock (default `2025-01-01T00:00:00Z`). */
+    clockTime?: string | number | Date;
+    /**
+     * Capture each surface twice and fail if the computed styles differ — proves
+     * the capture is deterministic (catches a replay gap falling through to the
+     * live backend, or unseeded client randomness) instead of letting it surface
+     * as a phantom change on an unrelated diff. Default from STYLEPROOF_SELFCHECK=1.
+     */
+    selfCheck?: boolean;
 };
 /**
  * Generate one Playwright test per surface × width that captures the style
- * map to `<baseDir>/<dir>/<key>@<width>.json.gz`.
+ * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
+ * deterministic with no per-repo fixtures: the baseline run records each
+ * surface's data responses to a HAR, and the comparison run replays them (set
+ * STYLEPROOF_REPLAY_FROM=<baseline dir> on the comparison capture), while the
+ * clock is frozen so time-derived styling is stable.
  *
  * ```ts
  * // styleproof.spec.ts
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export declare function defineStyleMapCapture({ surfaces, dir, baseDir, screenshots, }: DefineOptions): void;
+export declare function defineStyleMapCapture({ surfaces, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, }: DefineOptions): void;

package/dist/runner.js

@@ -1,34 +1,102 @@
 import { test } from '@playwright/test';
+import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap } from './capture.js';
+import { diffStyleMaps } from './diff.js';
+/** One-line description of the first drift finding, for the self-check error. */
+function driftDesc(f) {
+    if (f.kind === 'dom')
+        return `${f.path} ${f.change}`;
+    const p = f.props[0];
+    return p ? `${f.path} ${p.prop}: ${p.before} → ${p.after}` : f.path;
+}
+/**
+ * Pin the surface's inputs: replay the baseline's recorded data (or record ours),
+ * scoped to the data URLs so the app's own JS/CSS still load live, then freeze the
+ * clock so time-derived styling is stable.
+ */
+async function pinInputs(page, harName, s) {
+    if (s.replayFrom) {
+        const har = path.join(s.replayFrom, harName);
+        if (fs.existsSync(har)) {
+            // notFound:'abort' — a request the baseline never recorded fails
+            // deterministically rather than silently hitting the live backend.
+            await page.routeFromHAR(har, { url: s.replayUrl, update: false, notFound: 'abort' });
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(`styleproof: no replay HAR at ${har} — capturing live (NON-deterministic)`);
+        }
+    }
+    else {
+        await page.routeFromHAR(path.join(s.baseDir, s.dir, harName), {
+            url: s.replayUrl,
+            update: true,
+            updateContent: 'embed', // single portable file, no sidecar resources
+        });
+    }
+    if (s.freezeClock)
+        await page.clock.setFixedTime(new Date(s.clockTime));
+}
+/** Capture the surface again and throw if the computed styles drifted from `first`. */
+async function assertDeterministic(page, surface, first) {
+    await surface.go(page);
+    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [] });
+    const drift = diffStyleMaps(first, again);
+    if (drift.length) {
+        throw new Error(`styleproof self-check failed: ${surface.key} is non-deterministic — ` +
+            `${drift.length} computed-style difference(s) between two captures of the same commit. ` +
+            `Likely a replay gap (a request not in the baseline HAR) or unseeded randomness. ` +
+            `First: ${driftDesc(drift[0])}`);
+    }
+}
+/** Drive one surface at one width to a settled state and save its style map (+ screenshot). */
+async function captureSurface(page, surface, width, s) {
+    test.setTimeout(180_000);
+    await pinInputs(page, `${surface.key}@${width}.har`, s);
+    const height = typeof surface.height === 'function' ? surface.height(width) : (surface.height ?? 800);
+    await page.setViewportSize({ width, height });
+    await surface.go(page);
+    const map = await captureStyleMap(page, { ignore: surface.ignore ?? [] });
+    if (s.selfCheck)
+        await assertDeterministic(page, surface, map);
+    const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
+    saveStyleMap(`${stem}.json.gz`, map);
+    if (s.screenshots) {
+        // captureStyleMap froze animations/transitions, so this is the same settled
+        // state the map describes.
+        await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
+    }
+}
 /**
  * Generate one Playwright test per surface × width that captures the style
- * map to `<baseDir>/<dir>/<key>@<width>.json.gz`.
+ * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
+ * deterministic with no per-repo fixtures: the baseline run records each
+ * surface's data responses to a HAR, and the comparison run replays them (set
+ * STYLEPROOF_REPLAY_FROM=<baseline dir> on the comparison capture), while the
+ * clock is frozen so time-derived styling is stable.
  *
  * ```ts
  * // styleproof.spec.ts
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__', screenshots = true, }) {
+export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = process.env.STYLEPROOF_SELFCHECK === '1', }) {
     test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
+    const settings = {
+        dir: dir,
+        baseDir,
+        screenshots,
+        replayFrom,
+        replayUrl,
+        freezeClock,
+        clockTime,
+        selfCheck,
+    };
     test.describe('styleproof capture', () => {
         for (const surface of surfaces) {
             for (const width of surface.widths) {
-                test(`${surface.key} @ ${width}`, async ({ page }) => {
-                    test.setTimeout(180_000);
-                    const height = typeof surface.height === 'function' ? surface.height(width) : (surface.height ?? 800);
-                    await page.setViewportSize({ width, height });
-                    await surface.go(page);
-                    const map = await captureStyleMap(page, { ignore: surface.ignore ?? [] });
-                    const stem = path.join(baseDir, dir, `${surface.key}@${width}`);
-                    saveStyleMap(`${stem}.json.gz`, map);
-                    if (screenshots) {
-                        // captureStyleMap froze animations/transitions, so this is the
-                        // same settled state the map describes.
-                        await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
-                    }
-                });
+                test(`${surface.key} @ ${width}`, ({ page }) => captureSurface(page, surface, width, settings));
             }
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",