styleproof 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,70 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.5.0]
+
+Live regions are handled automatically, so a dashboard with streaming data,
+tickers, or late-loading content no longer produces a false "everything
+changed" report.
+
+### Added
+
+- **Auto-settle before capture (`stabilize`, default on).** The capture now
+  polls the (motion-frozen) page until its computed-style map has been unchanged
+  for a quiet window, so content that paints _after_ `go()` resolves — an async
+  fetch, an SSE/WebSocket stream backfilling a grid — is captured loaded, not
+  mid-load. This is what fixes the most common false positive: base and head
+  racing an async load and diffing empty-state-vs-populated. Requiring a
+  _sustained_ no-change window (not a single quiet sample) is what lets it wait
+  through the gap before late content appears.
+- **Automatic live-region detection.** Anything still changing on its own when
+  the settle budget runs out is, by definition, nondeterministic (it mutates
+  with no code change). Those element paths are recorded in `StyleMap.volatile`
+  and excluded from the diff — unioned across both sides — so a stream or ticker
+  never reads as a change, with no manual `ignore`. The report notes how many
+  live regions were auto-excluded. Tune or disable via
+  `captureStyleMap(page, { stabilize })` (`false`, or `{ interval, quietFor, timeout }`).
+
+### Changed
+
+- `diffStyleMapDirs` now returns a `volatile` count alongside `surfaces`/`counts`.
+- Text-only churn (a clock, "2m ago") still never matters — the diff has always
+  compared computed style, not text; this release adds the structural/layout
+  determinism to match.
+
+## [1.4.0]
+
+New surfaces (present on only one side, no baseline to diff) are shown for
+reference and never block the review gate.
+
+### Fixed
+
+- **A surface captured on only one side is now treated as a _new surface_, not a
+  change.** Previously every one-sided surface counted as a DOM change, so a
+  bootstrap PR (base branch has no capture spec yet → empty baseline) rendered a
+  self-contradicting report — a `0 DOM change(s) · 0 … · 0 … across 0 distinct
+change(s) in N surface(s)` headline sitting above N "re-run both captures"
+  warnings, each with an approval checkbox that could turn the gate green on a
+  capture set that has no baseline at all.
+
+### Changed
+
+- **New surfaces are shown, not blocked.** A surface present on only one side is
+  rendered with its captured-side screenshot under a `🆕 new surface` heading,
+  summarised on its own headline line (`🆕 N new surface(s) … don't block the
+check`), and excluded from the change tallies. In review-gate mode it gets an
+  **optional** `Approve this new surface` checkbox that the approve workflow
+  deliberately ignores — so a new surface never holds the `StyleProof` status red.
+  Real before↔after changes still gate exactly as before.
+- **`styleproof-diff` exit codes:** `0` identical, `1` reviewable differences,
+  `2` usage/capture error (unchanged), and new **`3`** = only new surfaces (no
+  baseline to diff). The Action reports on `1` or `3` but only gates on `1`;
+  certify mode (`fail-on-diff`) still fails on either, since "nothing changed"
+  means the capture set didn't grow either.
+- The Action `changed` output is now `"false"` for a brand-new surface with no
+  baseline (it was a change before). `generateStyleMapReport` returns a new
+  `newSurfaces` count alongside `changedSurfaces`.
+
 ## [1.3.1]
 
 ### Changed

package/README.md

@@ -16,6 +16,7 @@ On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base br
 
 - A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot and the property changes folded under a toggle.
 - An **approval checkbox per change**, driving a `StyleProof` commit status: red until every change is signed off, green when there are none.
+- **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown with its screenshot under a `🆕 new surface` heading and an _optional_ approval box, but it never holds the status red. It becomes part of the baseline once merged.
 - No committed baseline to maintain — the diff is HEAD-vs-base, so the report is _exactly what this PR changes_.
 
 ## What a report looks like
@@ -122,6 +123,8 @@ jobs:
 
 > 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.
 
+**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 } }`.
+
 ## Reference
 
 **Action `BenSheridanEdwards/styleproof@v1`** — key inputs:

package/bin/styleproof-diff.mjs

@@ -14,7 +14,8 @@
  *     `hover:` variant a screenshot can never catch.
  *
  * Custom properties (--*) are ignored: they are inputs, not outcomes (see
- * README). Exit code 0 = identical, 1 = differences, 2 = usage/capture error.
+ * README). Exit code 0 = identical, 1 = reviewable differences, 2 = usage/capture
+ * error, 3 = only new surfaces (present on one side, no baseline to diff against).
  */
 import fs from 'node:fs';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
@@ -28,7 +29,8 @@ options:
   --json <file>    also write the full structured diff to <file>
   -h, --help       show this help
 
-exit: 0 identical (certified), 1 differences found, 2 usage/capture error.
+exit: 0 identical (certified), 1 differences found, 2 usage/capture error,
+      3 only new surfaces (present on one side, no baseline to diff against).
 `;
 
 const argv = process.argv.slice(2);
@@ -71,7 +73,8 @@ const { surfaces, counts } = result;
 
 for (const sd of surfaces) {
   if (sd.missing) {
-    console.log(`\n${sd.surface}: captured in only one set — re-run both captures`);
+    const side = sd.missing === 'before' ? 'after' : 'before';
+    console.log(`\n${sd.surface}: new surface — captured only in the ${side} set, no baseline to compare`);
     continue;
   }
   const lines = [];
@@ -98,13 +101,19 @@ for (const sd of surfaces) {
 if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces }, null, 2));
 
 const total = counts.dom + counts.style + counts.state;
+const newSurfaces = surfaces.filter((s) => s.missing).length;
 const surfaceCount = new Set([
   ...fs.readdirSync(dirA).filter((f) => /\.json(\.gz)?$/.test(f)),
   ...fs.readdirSync(dirB).filter((f) => /\.json(\.gz)?$/.test(f)),
 ]).size;
+const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 console.log(
   total === 0
-    ? `\n✓ ${surfaceCount} surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces`,
+    ? newSurfaces === 0
+      ? `\n✓ ${surfaceCount} surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches`
+      : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — shown for reference, no reviewable change`
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}`,
 );
-process.exit(total === 0 ? 0 : 1);
+// 0 = identical, 1 = reviewable differences, 3 = only new surfaces (no baseline,
+// nothing to review). 2 stays reserved for usage/capture errors.
+process.exit(total > 0 ? 1 : newSurfaces > 0 ? 3 : 0);

package/bin/styleproof-report.mjs

@@ -108,10 +108,13 @@ try {
   process.exit(2);
 }
 
+const newNote = result.newSurfaces ? ` (+${result.newSurfaces} new surface(s) with no baseline)` : '';
 console.log(
   result.changedSurfaces === 0
-    ? '✓ no changes — empty report written'
-    : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)`,
+    ? result.newSurfaces === 0
+      ? '✓ no changes — empty report written'
+      : `ℹ ${result.newSurfaces} new surface(s) with no baseline — report written for reference`
+    : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)${newNote}`,
 );
 console.log(`report: ${result.reportMdPath}`);
-process.exit(result.changedSurfaces === 0 ? 0 : 1);
+process.exit(result.changedSurfaces === 0 && result.newSurfaces === 0 ? 0 : 1);

package/dist/capture.d.ts

@@ -45,13 +45,45 @@ export type StyleMap = {
      * certified, instead of silently reading as "identical".
      */
     statesSkipped?: boolean;
+    /**
+     * Element paths detected as LIVE at capture time — they kept changing on
+     * their own (after motion was frozen) until the settle budget ran out, so
+     * they're nondeterministic. Excluded from `elements`/`states`/`defaults`
+     * here, and skipped by the diff (which unions both sides' volatile sets) so a
+     * stream/ticker never reads as a change. Empty/absent on a fully-settled page.
+     */
+    volatile?: string[];
 };
 export type CaptureOptions = {
     /**
      * Selectors for nondeterministic regions (live data, embeds, ads). The
-     * matching elements and their descendants are skipped entirely.
+     * matching elements and their descendants are skipped entirely. Usually
+     * unnecessary now that `stabilize` auto-detects live regions; use it to skip
+     * a region you know is volatile without paying the settle wait for it.
      */
     ignore?: string[];
+    /**
+     * Settle the page before capturing, and auto-exclude live regions (default
+     * on). StyleProof polls the (motion-frozen) page until its computed-style map
+     * stops changing — so async content that paints AFTER `go()` resolves (a
+     * fetch, an SSE/WebSocket stream) is captured in its loaded state, not
+     * mid-load. Any region still changing when the budget runs out is a live
+     * region by definition (it mutates with no code change); its paths are
+     * recorded in `StyleMap.volatile` and excluded from the diff, so a stream or
+     * ticker never reads as a change — no manual `ignore` needed. Text-only churn
+     * (a clock, "2m ago") never matters: the diff compares computed style, not
+     * text. Pass `false` to capture the exact frame `go()` left, or `{ interval,
+     * quietFor, timeout }` (ms) to tune the poll cadence, the no-change window
+     * that counts as settled, and the budget. Note: content that first paints
+     * after a quiet gap longer than `quietFor` can't be waited for without a
+     * signal — settle that in `go()`; anything still moving at `timeout` is
+     * treated as a live region.
+     */
+    stabilize?: boolean | {
+        interval?: number;
+        quietFor?: number;
+        timeout?: number;
+    };
     /**
      * Capture forced :hover/:focus/:active state deltas (default true). This is
      * the expensive layer — O(interactive elements × 3 states) with a subtree
@@ -66,10 +98,14 @@ export type CaptureOptions = {
      */
     maxInteractive?: number;
 };
+/** True if `path` is one of `roots` or a structural descendant of one. Shared by
+ *  the capture (excluding live regions) and the diff (skipping them). */
+export declare function isUnder(path: string, roots: string[]): boolean;
 /**
- * Capture the page's complete style map. Drive the page to the state you
- * want first (navigate, open menus, settle fonts/animations) — the capture
- * reads whatever is in front of it.
+ * Capture the page's complete style map. Drive the page to the state you want
+ * first (navigate, open menus); by default the capture then auto-settles the
+ * page and excludes live regions (see `stabilize`), so a fetch/stream that
+ * paints after `go()` resolves is captured loaded, not mid-load.
  */
 export declare function captureStyleMap(page: Page, options?: CaptureOptions): Promise<StyleMap>;
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */

package/dist/capture.js

@@ -5,6 +5,11 @@ const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"
 // Freeze motion so every captured value is a settled end state, not a frame
 // of an animation or a mid-flight transition after a forced :hover.
 const FREEZE_CSS = '*,*::before,*::after{animation:none!important;transition:none!important}';
+/** True if `path` is one of `roots` or a structural descendant of one. Shared by
+ *  the capture (excluding live regions) and the diff (skipping them). */
+export function isUnder(path, roots) {
+    return roots.some((r) => path === r || path.startsWith(r + ' > '));
+}
 // Serialized into the browser by page.evaluate; cannot call module helpers.
 function capturePage({ ignore, motionOnly }) {
     const MOTION = /^(transition|animation)/;
@@ -206,14 +211,16 @@ function pathsForSelector({ selector, skipSel }) {
 }
 // Forced pseudo-class states on interactive elements, via CDP so no real
 // mouse or focus is involved and parent-state descendant rules still apply.
-async function captureForcedStates(page, ignore, maxInteractive) {
+async function captureForcedStates(page, ignore, maxInteractive, skipPaths = []) {
     const client = await page.context().newCDPSession(page);
     await client.send('DOM.enable');
     await client.send('CSS.enable');
     const { root } = await client.send('DOM.getDocument');
     const { nodeIds } = await client.send('DOM.querySelectorAll', { nodeId: root.nodeId, selector: INTERACTIVE });
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
-    const paths = await page.evaluate(pathsForSelector, { selector: INTERACTIVE, skipSel });
+    // Null out forced-state work for live (volatile) paths too, so they're not
+    // probed and can't reintroduce the churn the settle pass just excluded.
+    const paths = (await page.evaluate(pathsForSelector, { selector: INTERACTIVE, skipSel })).map((p) => p && skipPaths.length && isUnder(p, skipPaths) ? null : p);
     // The CDP DOM snapshot and the live querySelectorAll are two separate,
     // non-atomic reads. They can legitimately disagree — display:contents,
     // nodes detached or injected between the two calls (next-route-announcer,
@@ -254,19 +261,84 @@ async function captureForcedStates(page, ignore, maxInteractive) {
     await client.detach();
     return { states, skipped: false };
 }
+/** Element paths that differ between two captures (added, removed, or restyled). */
+function changedElementPaths(a, b) {
+    const out = [];
+    for (const p of new Set([...Object.keys(a), ...Object.keys(b)]))
+        if (JSON.stringify(a[p]) !== JSON.stringify(b[p]))
+            out.push(p);
+    return out;
+}
 /**
- * Capture the page's complete style map. Drive the page to the state you
- * want first (navigate, open menus, settle fonts/animations) — the capture
- * reads whatever is in front of it.
+ * Poll the page until its computed-style map has been UNCHANGED for `quietFor`
+ * ms (it settled — async content finished painting) or the budget runs out.
+ * Requiring a sustained quiet window, not a single quiet sample, is what lets it
+ * wait THROUGH the gap before late content paints and through a streaming
+ * backfill instead of settling on the first lull. Returns the paths still
+ * changing at timeout: genuine LIVE regions, to be excluded from the capture.
+ * Reuses `capturePage` (motion already frozen by the caller), so only
+ * content/layout churn — not an animation frame — keeps it from settling.
+ */
+async function stabilizePage(page, ignore, interval, quietFor, timeout) {
+    const snap = async () => (await page.evaluate(capturePage, { ignore, motionOnly: false })).elements;
+    const start = Date.now();
+    let prev = await snap();
+    let lastChangeAt = start;
+    let recent = [];
+    while (Date.now() - start < timeout) {
+        await page.waitForTimeout(interval);
+        const cur = await snap();
+        const changed = changedElementPaths(prev, cur);
+        prev = cur;
+        if (changed.length) {
+            lastChangeAt = Date.now();
+            recent = changed;
+        }
+        else if (Date.now() - lastChangeAt >= quietFor) {
+            return []; // unchanged for the full quiet window → settled
+        }
+    }
+    return recent; // never went quiet for quietFor within budget → still-moving paths are live
+}
+/**
+ * Capture the page's complete style map. Drive the page to the state you want
+ * first (navigate, open menus); by default the capture then auto-settles the
+ * page and excludes live regions (see `stabilize`), so a fetch/stream that
+ * paints after `go()` resolves is captured loaded, not mid-load.
  */
 export async function captureStyleMap(page, options = {}) {
     const ignore = options.ignore ?? [];
     const captureStates = options.captureStates ?? true;
     const maxInteractive = options.maxInteractive ?? 800;
+    const stabilize = options.stabilize ?? true;
     // Motion longhands first (FREEZE_CSS would null them), then everything else.
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true });
     await page.addStyleTag({ content: FREEZE_CSS });
+    // Settle: wait for async content to finish painting so base and head capture
+    // the same loaded state, and collect any region still changing on its own
+    // (a live stream/ticker) to exclude — animations are frozen above, so only
+    // real content/layout churn lands here.
+    let volatile = [];
+    if (stabilize !== false) {
+        const opt = typeof stabilize === 'object' ? stabilize : {};
+        const interval = opt.interval || 150;
+        const quietFor = opt.quietFor || 600;
+        const timeout = opt.timeout || 5000;
+        volatile = await stabilizePage(page, ignore, interval, quietFor, timeout);
+        if (volatile.length) {
+            // eslint-disable-next-line no-console
+            console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
+                'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
+                'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+        }
+    }
     const base = await page.evaluate(capturePage, { ignore, motionOnly: false });
+    // Drop live regions (and their subtrees) detected by the settle pass — done
+    // here, in Node, so the serialized capturePage stays a pure snapshot.
+    if (volatile.length)
+        for (const p of Object.keys(base.elements))
+            if (isUnder(p, volatile))
+                delete base.elements[p];
     if (base.shadowHosts || base.sameOriginFrames) {
         // eslint-disable-next-line no-console
         console.warn(`styleproof: ${base.shadowHosts} shadow host(s) and ${base.sameOriginFrames} same-origin iframe(s) were ` +
@@ -286,7 +358,7 @@ export async function captureStyleMap(page, options = {}) {
     let states = {};
     let statesSkipped = false;
     if (captureStates) {
-        const forced = await captureForcedStates(page, ignore, maxInteractive);
+        const forced = await captureForcedStates(page, ignore, maxInteractive, volatile);
         states = forced.states;
         statesSkipped = forced.skipped;
     }
@@ -295,6 +367,7 @@ export async function captureStyleMap(page, options = {}) {
         elements: base.elements,
         states,
         ...(statesSkipped ? { statesSkipped: true } : {}),
+        ...(volatile.length ? { volatile } : {}),
     };
 }
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */
@@ -310,7 +383,7 @@ export function loadStyleMap(filePath) {
         raw = fs.readFileSync(filePath);
     }
     catch (e) {
-        throw new Error(`styleproof: cannot read capture ${filePath}: ${e.message}`);
+        throw new Error(`styleproof: cannot read capture ${filePath}: ${e.message}`, { cause: e });
     }
     try {
         const text = filePath.endsWith('.gz') ? gunzipSync(raw).toString('utf8') : raw.toString('utf8');
@@ -318,6 +391,6 @@ export function loadStyleMap(filePath) {
     }
     catch (e) {
         throw new Error(`styleproof: capture ${filePath} is corrupt or truncated (${e.message}). ` +
-            'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.');
+            'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.', { cause: e });
     }
 }

package/dist/diff.d.ts

@@ -42,10 +42,12 @@ export type DiffCounts = {
 };
 /** Diff two style maps of the same surface. */
 export declare function diffStyleMaps(a: StyleMap, b: StyleMap): Finding[];
-/** Diff every same-named capture between two directories. */
+/** Diff every same-named capture between two directories. `volatile` is the
+ *  count of live regions auto-excluded across all surfaces (union per surface). */
 export declare function diffStyleMapDirs(dirA: string, dirB: string): {
     surfaces: SurfaceDiff[];
     counts: DiffCounts;
+    volatile: number;
 };
 /** Human label: structural path plus a truncated class hint. */
 export declare function findingLabel(path: string, cls: string): string;

package/dist/diff.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadStyleMap } from './capture.js';
+import { loadStyleMap, isUnder } from './capture.js';
 function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     const changed = [];
     for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
@@ -16,7 +16,14 @@ function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
 /** Diff two style maps of the same surface. */
 export function diffStyleMaps(a, b) {
     const findings = [];
+    // Live regions either capture flagged as nondeterministic (a stream, ticker,
+    // late-loading content): never diff them — their values move with no code
+    // change. Union both sides so a region volatile on only one capture is still
+    // skipped, in every layer (element, pseudo, forced-state).
+    const volatile = [...new Set([...(a.volatile ?? []), ...(b.volatile ?? [])])];
     for (const p of [...new Set([...Object.keys(a.elements), ...Object.keys(b.elements)])].sort()) {
+        if (volatile.length && isUnder(p, volatile))
+            continue;
         const ea = a.elements[p];
         const eb = b.elements[p];
         if (!ea || !eb) {
@@ -62,6 +69,8 @@ export function diffStyleMaps(a, b) {
         });
     }
     for (const p of new Set([...Object.keys(a.states ?? {}), ...Object.keys(b.states ?? {})])) {
+        if (volatile.length && isUnder(p, volatile))
+            continue;
         const sa = a.states?.[p] ?? {};
         const sb = b.states?.[p] ?? {};
         const cls = (a.elements[p] ?? b.elements[p])?.cls ?? '';
@@ -77,13 +86,25 @@ export function diffStyleMaps(a, b) {
     }
     return findings;
 }
+/** Add a surface's findings to the running totals (one DOM/style/state tally). */
+function tallyCounts(findings, counts) {
+    for (const f of findings) {
+        if (f.kind === 'dom')
+            counts.dom++;
+        else if (f.kind === 'style')
+            counts.style += f.props.length;
+        else
+            counts.state += f.props.length;
+    }
+}
 function indexDir(dir) {
     return Object.fromEntries(fs
         .readdirSync(dir)
         .filter((f) => /\.json(\.gz)?$/.test(f))
         .map((f) => [f.replace(/\.json(\.gz)?$/, ''), path.join(dir, f)]));
 }
-/** Diff every same-named capture between two directories. */
+/** Diff every same-named capture between two directories. `volatile` is the
+ *  count of live regions auto-excluded across all surfaces (union per surface). */
 export function diffStyleMapDirs(dirA, dirB) {
     const indexA = indexDir(dirA);
     const indexB = indexDir(dirB);
@@ -92,25 +113,25 @@ export function diffStyleMapDirs(dirA, dirB) {
         throw new Error(`no .json(.gz) captures found in ${dirA} or ${dirB}`);
     const surfaces = [];
     const counts = { dom: 0, style: 0, state: 0 };
+    let volatile = 0;
     for (const surface of names) {
         if (!indexA[surface] || !indexB[surface]) {
+            // A surface present on only one side has no baseline to diff against — it's
+            // a NEW surface, not a style change. It does NOT count toward the change
+            // tallies (those drive the review gate); the consumer flags it separately
+            // off the `missing` marker and shows it for reference without blocking.
             surfaces.push({ surface, missing: indexA[surface] ? 'after' : 'before', findings: [] });
-            counts.dom++;
             continue;
         }
-        const findings = diffStyleMaps(loadStyleMap(indexA[surface]), loadStyleMap(indexB[surface]));
-        for (const f of findings) {
-            if (f.kind === 'dom')
-                counts.dom++;
-            else if (f.kind === 'style')
-                counts.style += f.props.length;
-            else
-                counts.state += f.props.length;
-        }
+        const mapA = loadStyleMap(indexA[surface]);
+        const mapB = loadStyleMap(indexB[surface]);
+        volatile += new Set([...(mapA.volatile ?? []), ...(mapB.volatile ?? [])]).size;
+        const findings = diffStyleMaps(mapA, mapB);
+        tallyCounts(findings, counts);
         if (findings.length)
             surfaces.push({ surface, findings });
     }
-    return { surfaces, counts };
+    return { surfaces, counts, volatile };
 }
 /** Human label: structural path plus a truncated class hint. */
 export function findingLabel(path, cls) {

package/dist/report.d.ts

@@ -41,7 +41,10 @@ export type ReportOptions = {
     includeLayoutNoise?: boolean;
 };
 export type ReportResult = {
+    /** Surfaces carrying a reviewable change (excludes new, one-sided surfaces). */
     changedSurfaces: number;
+    /** New surfaces present on only one side, with no baseline to compare. */
+    newSurfaces: number;
     totalFindings: number;
     reportMdPath: string;
     reportJsonPath: string;

package/dist/report.js

@@ -3,6 +3,10 @@ import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
 import { diffStyleMapDirs } from './diff.js';
+// Hidden marker appended to a new-surface heading. Invisible in rendered
+// markdown; lets the PR-comment layer attach an OPTIONAL "approve" box to a new
+// surface (vs the required box on a real change), so new surfaces never gate.
+const NEW_SURFACE_MARKER = '<!-- styleproof-new -->';
 const rectToBox = (r) => ({ x: r[0], y: r[1], w: r[2], h: r[3] });
 const pad = (b, by) => ({ x: b.x - by, y: b.y - by, w: b.w + 2 * by, h: b.h + 2 * by });
 const union = (a, b) => {
@@ -520,7 +524,7 @@ const stripDerived = (f) => f.kind === 'dom' ? f : { ...f, props: f.props.filter
 export function generateStyleMapReport(opts) {
     const { beforeDir, afterDir, outDir, imageBaseUrl = '', pad: padBy = 24, minWidth = 320, minHeight = 180, maxHeight = 1600, maxCrops = 6, foldDetailsAt = 0, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
-    const { surfaces } = diffStyleMapDirs(beforeDir, afterDir);
+    const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
     fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
     // Focus each surface on styling intent: drop reflow-casualty elements (only
     // size/position-derived changes) and strip those props from the rest, unless
@@ -563,7 +567,10 @@ export function generateStyleMapReport(opts) {
             else
                 shown.state += summarizeProps(f.props).length;
         }
-    const surfaceCount = changeGroups.reduce((acc, g) => acc + g.surfaces.length, 0) + missing.length;
+    // Surfaces carrying a reviewable change — NOT the new (one-sided) ones, which
+    // have no baseline to compare and are summarised on their own line below so the
+    // headline never reads "0 changes" while warnings sit beneath it.
+    const changedSurfaceCount = changeGroups.reduce((acc, g) => acc + g.surfaces.length, 0);
     const md = [];
     const json = [];
     const img = (rel) => (imageBaseUrl ? `${imageBaseUrl.replace(/\/$/, '')}/${rel}` : rel);
@@ -572,8 +579,19 @@ export function generateStyleMapReport(opts) {
         md.push('✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.');
     }
     else {
-        md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** ` +
-            `across ${changeGroups.length} distinct change(s) in ${surfaceCount} surface(s).`);
+        if (changeGroups.length > 0) {
+            md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** ` +
+                `across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} surface(s).`);
+        }
+        if (missing.length > 0) {
+            if (changeGroups.length > 0)
+                md.push('');
+            md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare — shown below for reference. ` +
+                `New surfaces don't block the check.`);
+        }
+    }
+    if (volatileCount > 0) {
+        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check._`);
     }
     let totalFindings = 0;
     let cropSeq = 0;
@@ -646,15 +664,41 @@ export function generateStyleMapReport(opts) {
         surfaceJson.findings = surfaceFindings;
         json.push(surfaceJson);
     }
+    // New surfaces: present on only one side, so there's nothing to diff. Show the
+    // captured side as a single screenshot for reference and mark the heading so the
+    // PR comment can attach an OPTIONAL approval box — these never gate the check.
     for (const p of missing) {
-        md.push('', `### \`${p.sd.surface}\``, '', `⚠️ captured only in the **${p.sd.missing === 'before' ? 'after' : 'before'}** set — re-run both captures.`);
-        json.push({ surface: p.sd.surface, missing: p.sd.missing });
+        const side = p.sd.missing === 'before' ? 'after' : 'before';
+        const srcDir = side === 'after' ? afterDir : beforeDir;
+        const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
+        md.push('', `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`, '', `_${formatSurfaceList([p.sd.surface])}_`);
+        const surfaceJson = { surface: p.sd.surface, missing: p.sd.missing, isNew: true };
+        if (png) {
+            cropSeq++;
+            const h = Math.min(maxHeight, png.height);
+            const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h);
+            const stem = `crops/${p.sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}-new`;
+            writePng(path.join(outDir, `${stem}.png`), crop);
+            md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${p.sd.surface}${png.height > h ? ' (top of page)' : ''}</sub>`);
+            surfaceJson.image = `${stem}.png`;
+        }
+        else {
+            md.push('', `_Captured only in the **${side}** set; no screenshot saved (run captures with \`screenshots: true\`)._`);
+        }
+        md.push('', `_No baseline to compare against — this surface is new, so it doesn't block the check. It becomes part of the baseline once this merges._`);
+        json.push(surfaceJson);
     }
     const reportMdPath = path.join(outDir, 'report.md');
     const reportJsonPath = path.join(outDir, 'report.json');
     fs.writeFileSync(reportMdPath, md.join('\n') + '\n');
     fs.writeFileSync(reportJsonPath, JSON.stringify({ counts: shown, surfaces: json }, null, 2));
-    return { changedSurfaces: prepared.length, totalFindings, reportMdPath, reportJsonPath };
+    return {
+        changedSurfaces: prepared.length - missing.length,
+        newSurfaces: missing.length,
+        totalFindings,
+        reportMdPath,
+        reportJsonPath,
+    };
 }
 function findCapture(dir, surface) {
     for (const ext of ['.json.gz', '.json']) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.3.1",
+  "version": "1.5.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",
@@ -63,7 +63,7 @@
     "test:watch": "node --test --watch test/*.test.mjs",
     "test:e2e": "npm run build && playwright test test/smoke.e2e.spec.ts",
     "init": "node ./bin/styleproof-init.mjs",
-    "prepare": "npm run build",
+    "prepare": "npm run build && husky",
     "prepublishOnly": "npm run clean && npm run build && npm run typecheck"
   },
   "peerDependencies": {
@@ -73,14 +73,16 @@
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
+    "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.9.3",
     "@types/pngjs": "^6.0.5",
-    "eslint": "^9.17.0",
-    "globals": "^15.14.0",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
     "prettier": "^3.4.2",
-    "typescript": "^5.6.2",
-    "typescript-eslint": "^8.18.0"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.18.0",
+    "husky": "^9.1.7",
+    "fallow": "^2.96.0"
   }
 }