styleproof 2.0.0 → 2.2.0

package/dist/runner.d.ts

@@ -7,7 +7,11 @@ import type { Page } from '@playwright/test';
 export type Surface = {
     /** Capture file name prefix; must be unique. */
     key: string;
-    /** Navigate and drive the page to the state, ending settled (fonts loaded, entrance animations done). */
+    /**
+     * Navigate and drive the page to the state. Only reach the state — StyleProof
+     * settles it for you (waits out in-flight data and fonts, freezes animations)
+     * before reading, so you don't hand-roll `networkidle`/`fonts.ready` waits here.
+     */
     go: (page: Page) => Promise<void>;
     /** Selectors for nondeterministic regions (live data, third-party embeds); skipped entirely. */
     ignore?: string[];
@@ -18,6 +22,23 @@ export type Surface = {
 };
 export type DefineOptions = {
     surfaces: Surface[];
+    /**
+     * The full set of surface keys the app knows it has — its route/view universe,
+     * typically derived from a registry (e.g. an app's list of routes or view ids).
+     * When set, StyleProof emits a coverage-guard test (in the NORMAL suite, not
+     * gated on a capture dir) that fails if any expected key is neither captured (a
+     * surface) nor in `exclude`. This is what stops a newly added route from
+     * shipping uncaptured: the gate can only diff what a spec lists, so without this
+     * a forgotten surface is silently invisible. Omit to opt out (no guard).
+     */
+    expected?: string[];
+    /**
+     * Expected keys deliberately NOT captured, each mapped to the reason — a visible,
+     * reviewed opt-out ledger. Keeps the coverage guard green for known gaps without
+     * letting them hide: an entry whose key isn't in `expected` (a renamed/removed
+     * route) also fails the guard, so the ledger can't rot.
+     */
+    exclude?: Record<string, string>;
     /**
      * Output directory label. Convention: drive it from an env var so the same
      * spec captures `before`, `after`, or a CI label — and skips entirely when
@@ -58,10 +79,16 @@ export type DefineOptions = {
     /** 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.
+     * 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.
+     *
+     * Defaults ON for the RECORDING run and OFF for the REPLAY run: live nondeterminism
+     * surfaces while recording against the real backend, whereas the replay run renders
+     * against the recorded HAR and is deterministic by construction — so self-checking it
+     * just doubles the work. `STYLEPROOF_SELFCHECK=1` forces it on for both; pass
+     * `selfCheck` explicitly to override.
      */
     selfCheck?: boolean;
     /**
@@ -71,6 +98,12 @@ export type DefineOptions = {
      * `CaptureOptions.captureText` and the README's "Optional: content layer".
      */
     captureText?: boolean;
+    /**
+     * Opt-in React layer (default OFF). Record the component + sanitized props that
+     * rendered each element so the report can name `Button (variant=primary)`.
+     * Advisory only — never gates. See `CaptureOptions.captureComponent`.
+     */
+    captureComponent?: boolean;
 };
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
@@ -87,6 +120,14 @@ export type DefineOptions = {
  * recently added route first); non-stream requests `fallback()` to the HAR.
  */
 export declare function passLiveStreams(page: Page, url: string): Promise<void>;
+/**
+ * Default for `selfCheck` when the consumer didn't set it: ON when RECORDING (no
+ * `replayFrom`) — that's where live nondeterminism surfaces — and OFF when REPLAYING,
+ * since the replay run renders against the recorded HAR and is deterministic by
+ * construction, so self-checking it just doubles the work. `STYLEPROOF_SELFCHECK=1`
+ * forces it on either way.
+ */
+export declare function defaultSelfCheck(replayFrom: string | undefined, env?: string | undefined): boolean;
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -100,4 +141,4 @@ export declare function passLiveStreams(page: Page, url: string): Promise<void>;
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export declare function defineStyleMapCapture({ surfaces, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, }: DefineOptions): void;
+export declare function defineStyleMapCapture({ surfaces, expected, exclude, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, captureComponent, }: DefineOptions): void;

package/dist/runner.js

@@ -1,8 +1,9 @@
-import { test } from '@playwright/test';
+import { test, expect } from '@playwright/test';
 import fs from 'node:fs';
 import path from 'node:path';
-import { captureStyleMap, saveStyleMap } from './capture.js';
+import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { diffStyleMaps } from './diff.js';
+import { coverageGaps } from './coverage.js';
 /** One-line description of the first drift finding, for the self-check error. */
 function driftDesc(f) {
     if (f.kind === 'dom')
@@ -69,9 +70,9 @@ async function pinInputs(page, harName, s) {
         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, captureText) {
+async function assertDeterministic(page, surface, first, captureText, pending) {
     await surface.go(page);
-    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText });
+    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText, pendingRequests: pending });
     const drift = diffStyleMaps(first, again);
     if (drift.length) {
         throw new Error(`styleproof self-check failed: ${surface.key} is non-deterministic — ` +
@@ -86,18 +87,42 @@ async function captureSurface(page, surface, width, s) {
     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 ?? [], captureText: s.captureText });
-    if (s.selfCheck)
-        await assertDeterministic(page, surface, map, s.captureText);
-    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' });
+    // Arm the in-flight request tracker BEFORE go() so the surface's own load fetches
+    // count toward the network-aware settle — a request that starts during navigation
+    // fired its event before captureStyleMap could attach a listener of its own.
+    const requests = trackInflightRequests(page);
+    try {
+        await surface.go(page);
+        const map = await captureStyleMap(page, {
+            ignore: surface.ignore ?? [],
+            captureText: s.captureText,
+            captureComponent: s.captureComponent,
+            pendingRequests: requests.pending,
+        });
+        if (s.selfCheck)
+            await assertDeterministic(page, surface, map, s.captureText, requests.pending);
+        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' });
+        }
+    }
+    finally {
+        requests.dispose();
     }
 }
+/**
+ * Default for `selfCheck` when the consumer didn't set it: ON when RECORDING (no
+ * `replayFrom`) — that's where live nondeterminism surfaces — and OFF when REPLAYING,
+ * since the replay run renders against the recorded HAR and is deterministic by
+ * construction, so self-checking it just doubles the work. `STYLEPROOF_SELFCHECK=1`
+ * forces it on either way.
+ */
+export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCHECK) {
+    return env === '1' || !replayFrom;
+}
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -111,8 +136,7 @@ async function captureSurface(page, surface, width, s) {
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-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', captureText = false, }) {
-    test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
+export function defineStyleMapCapture({ surfaces, expected, exclude = {}, 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 = defaultSelfCheck(replayFrom), captureText = false, captureComponent = false, }) {
     const settings = {
         dir: dir,
         baseDir,
@@ -123,8 +147,27 @@ export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__'
         clockTime,
         selfCheck,
         captureText,
+        captureComponent,
     };
+    // Coverage guard. Runs in the NORMAL test suite (NOT gated on a capture dir), so
+    // a route added without a surface fails the app's own tests — long before, and
+    // independent of, a capture run. This is the one gap captures can't catch: a
+    // surface never taken can't be diffed. Only emitted when the spec declares its
+    // `expected` universe; otherwise StyleProof keeps its prior behaviour exactly.
+    if (expected) {
+        test.describe('styleproof coverage', () => {
+            test('every expected surface is captured or explicitly excluded', () => {
+                const { uncovered, staleExclusions } = coverageGaps(surfaces.map((s) => s.key), expected, exclude);
+                expect(uncovered, `StyleProof coverage gap: ${uncovered.length} expected surface(s) are neither captured ` +
+                    `nor excluded — add each to \`surfaces\`, or to \`exclude\` with a reason. ` +
+                    `Missing: ${uncovered.join(', ')}`).toEqual([]);
+                expect(staleExclusions, `StyleProof: \`exclude\` lists surface(s) absent from \`expected\` ` +
+                    `(renamed or removed?): ${staleExclusions.join(', ')}`).toEqual([]);
+            });
+        });
+    }
     test.describe('styleproof capture', () => {
+        test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         for (const surface of surfaces) {
             for (const width of surface.widths) {
                 test(`${surface.key} @ ${width}`, ({ page }) => captureSurface(page, surface, width, settings));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.0.0",
+  "version": "2.2.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",
@@ -75,7 +75,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/pngjs": "^6.0.5",
     "eslint": "^10.5.0",
     "globals": "^17.6.0",