styleproof 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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

package/README.md

@@ -123,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/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`. */

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,6 +113,7 @@ 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
@@ -101,19 +123,15 @@ export function diffStyleMapDirs(dirA, dirB) {
             surfaces.push({ surface, missing: indexA[surface] ? 'after' : 'before', findings: [] });
             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.js

@@ -524,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
@@ -590,6 +590,9 @@ export function generateStyleMapReport(opts) {
                 `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;
     for (const cg of changeGroups) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.4.0",
+  "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",