styleproof 1.9.0 → 1.9.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.9.1]
+
+### Fixed
+
+- **Framework / non-visual DOM noise no longer registers as a change.** Capture now skips a built-in default set of selectors — `<meta>`, `<title>`, `<link>`, `<script>`, `<style>`, `<base>`, `<noscript>`, `<template>`, and `next-route-announcer` — merged into (not replaced by) the caller's `ignore`. These are elements frameworks stream into the body and reorder (Next.js app-router injects metadata then hoists it) or inject as live regions (Next's a11y route announcer), with no visual box to diff; their churn was surfacing as phantom DOM-added/removed findings on PRs that changed no CSS. A real stylesheet change still shows up in the affected elements' computed styles, not in the `<style>` tag. _Note: this changes the captured element set slightly — re-baseline once after upgrading._
+
 ## [1.9.0]
 
 ### Added

package/README.md

@@ -127,6 +127,7 @@ jobs:
 - **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.
+- **Framework noise is skipped by default.** Non-visual and framework-injected elements never count as a change — `<meta>`/`<title>`/`<script>`/`<style>`/… (which Next.js streams into the body then hoists) and live regions like Next's `next-route-announcer`. A real stylesheet change still shows up in the affected elements' computed styles, not in the `<style>` tag. Add your own selectors with `ignore` — they extend this default, they don't replace it.
 
 > 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.
 

package/dist/capture.d.ts

@@ -65,9 +65,11 @@ export type StyleMap = {
 export type CaptureOptions = {
     /**
      * Selectors for nondeterministic regions (live data, embeds, ads). The
-     * 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.
+     * matching elements and their descendants are skipped entirely. Added to a
+     * built-in default that skips framework/non-visual noise (`<meta>`/`<title>`/
+     * `<script>`/`<style>`/… and `next-route-announcer`), so you rarely need it —
+     * `stabilize` also auto-detects live regions. Use it to skip a region you know
+     * is volatile without paying the settle wait for it.
      */
     ignore?: string[];
     /**

package/dist/capture.js

@@ -5,6 +5,26 @@ 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}';
+// Always skipped, merged into the caller's `ignore`. Two kinds of noise that
+// are never a visual change worth gating on but churn the DOM between runs:
+//   - non-rendered elements frameworks stream into <body> then hoist (Next.js
+//     app-router injects <meta>/<title>/<link>); they have no box to style, and
+//     their presence/order is nondeterministic. A real stylesheet change still
+//     shows up in the affected elements' computed styles, not in the <style> tag.
+//   - framework-injected live regions / overlays that mount and reorder on their
+//     own (Next.js's a11y route announcer — already a known source of CDP skew).
+const FRAMEWORK_IGNORE = [
+    'meta',
+    'title',
+    'link',
+    'script',
+    'style',
+    'base',
+    'noscript',
+    'template',
+    'next-route-announcer',
+    '[id="__next-route-announcer__"]',
+];
 /** 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) {
@@ -328,6 +348,51 @@ function capturePageTokens() {
     probe.remove();
     return tokens;
 }
+/** Settle the page and return the paths of live regions to exclude. */
+async function detectVolatile(page, ignore, stabilize) {
+    if (stabilize === false)
+        return [];
+    const opt = typeof stabilize === 'object' ? stabilize : {};
+    const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000);
+    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.');
+    }
+    return volatile;
+}
+/** Drop live regions (and their subtrees) from the base capture, in Node so the
+ *  serialized capturePage stays a pure snapshot. */
+function dropVolatile(elements, volatile) {
+    if (!volatile.length)
+        return;
+    for (const p of Object.keys(elements))
+        if (isUnder(p, volatile))
+            delete elements[p];
+}
+/** Warn once when shadow roots / iframes were skipped (their styles aren't captured or diffed). */
+function warnUntraversed(shadowHosts, sameOriginFrames) {
+    if (!shadowHosts && !sameOriginFrames)
+        return;
+    // eslint-disable-next-line no-console
+    console.warn(`styleproof: ${shadowHosts} shadow host(s) and ${sameOriginFrames} same-origin iframe(s) were ` +
+        'NOT traversed — styles inside shadow roots and frames are not captured or diffed. A refactor inside ' +
+        'one would be reported as identical. See README "Limitations".');
+}
+/** Fold the pre-freeze motion longhands back onto the settled base capture. */
+function mergeMotion(elements, motion) {
+    for (const [p, entry] of Object.entries(elements)) {
+        const m = motion[p];
+        if (!m)
+            continue;
+        Object.assign(entry.style, m.style);
+        for (const [ps, props] of Object.entries(m.pseudo ?? {})) {
+            if (entry.pseudo?.[ps])
+                Object.assign(entry.pseudo[ps], props);
+        }
+    }
+}
 /**
  * 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
@@ -335,7 +400,9 @@ function capturePageTokens() {
  * paints after `go()` resolves is captured loaded, not mid-load.
  */
 export async function captureStyleMap(page, options = {}) {
-    const ignore = options.ignore ?? [];
+    // Framework/non-visual noise is always skipped, so it can't read as a DOM
+    // change; the caller's `ignore` adds to it (not replaces it).
+    const ignore = [...FRAMEWORK_IGNORE, ...(options.ignore ?? [])];
     const captureStates = options.captureStates ?? true;
     const maxInteractive = options.maxInteractive ?? 800;
     const stabilize = options.stabilize ?? true;
@@ -346,43 +413,11 @@ export async function captureStyleMap(page, options = {}) {
     // 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 volatile = await detectVolatile(page, ignore, stabilize);
     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 ` +
-            'NOT traversed — styles inside shadow roots and frames are not captured or diffed. A refactor inside ' +
-            'one would be reported as identical. See README "Limitations".');
-    }
-    for (const [p, entry] of Object.entries(base.elements)) {
-        const m = motion.elements[p];
-        if (!m)
-            continue;
-        Object.assign(entry.style, m.style);
-        for (const [ps, props] of Object.entries(m.pseudo ?? {})) {
-            if (entry.pseudo?.[ps])
-                Object.assign(entry.pseudo[ps], props);
-        }
-    }
+    dropVolatile(base.elements, volatile);
+    warnUntraversed(base.shadowHosts, base.sameOriginFrames);
+    mergeMotion(base.elements, motion.elements);
     let states = {};
     let statesSkipped = false;
     if (captureStates) {

package/package.json

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