styleproof 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -7,6 +7,71 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.1.2] - 2026-06-28
+
+### Added
+
+- Documented the sound way to skip StyleProof work: skip the **entire** CI
+  workflow for docs-only / non-rendered paths with native path filters, but do
+  not skip individual surfaces based on changed-file guesses.
+
+### Fixed
+
+- **Live-region detection now respects the surface's `ignore` list.** A region
+  the caller ignored was still scanned for `aria-live`/`role` and surfaced (and
+  persisted into the committed map) as a live-state candidate, unlike every other
+  capture pass which honours the merged `ignore`. Ignored regions are now excluded
+  from `liveCandidates` too.
+- **The scaffolded CI workflow no longer blocks PRs that only add new surfaces.**
+  `styleproof init` generated a workflow that failed on any non-zero diff exit
+  code, so a new-surface-only diff (exit `3`) held the check red and the PR
+  receipt claimed "Visual changes detected" — contradicting the documented
+  contract that new surfaces never block. The gate now fails only on reviewable
+  diffs (exit `1`) and errors (exit `2`), matching `action.yml`, and the receipt
+  reports new surfaces explicitly.
+- **A truncated forced-state layer is no longer silently certified as
+  identical.** When a surface had more interactive elements than
+  `maxInteractive`, capture truncated the `:hover/:focus/:active` layer but left
+  `statesSkipped` unset, so the uncaptured states read as "identical" against a
+  fully-captured side — the exact false-certification the flag exists to prevent.
+  Truncation now sets `statesSkipped`, and the diff reports the layer as "not
+  fully captured" on the affected side.
+- **Release workflow no longer passes an empty `body_path` to the GitHub Release
+  step.** Previously a release whose CHANGELOG version section was absent (e.g. a
+  hotfix tag with no entry) passed `body_path: ''`, which `softprops/action-gh-release`
+  treats as a file to read and fails with ENOENT instead of auto-generating notes.
+  The step is now split into two mutually-exclusive steps: one with
+  `body_path: notes.md`, one with `generate_release_notes: true`.
+
+## [3.1.1] - 2026-06-27
+
+### Changed
+
+- **Release workflow now verifies npm publication before tagging.** A release
+  fails before creating tags or GitHub Releases if `NPM_TOKEN` is missing, and
+  it verifies `styleproof@<version>` on npm after publishing or detecting an
+  already-published version.
+- **Generated pre-push hooks now restore no-op map churn before committing.** The
+  hook captures through `styleproof-map`, runs a semantic diff against `HEAD`, and
+  restores `stylemaps/` when the refreshed map is identical. When the map really
+  changes, the hook prints the diff plus a concrete live-state/replay hint before
+  creating the map commit.
+
+### Fixed
+
+- **Real cursor hover no longer contaminates the resting style map.** Capture now
+  parks the mouse over an ignored 1px hover sink before reading, matching the
+  existing focus blur behavior. The canonical resting map stays unhovered while
+  the forced `:hover` layer still records the hover delta.
+- **`styleproof-map` now writes lean committed maps by default.** Recorded HAR
+  files are removed after successful capture so private API responses are not
+  accidentally committed by the default pre-push flow. Use `--keep-har` or
+  `STYLEPROOF_KEEP_HAR=1` for explicit record/replay workflows.
+- **Generated pre-push hooks now clean untracked no-op artifacts.** When the
+  refreshed map is semantically identical to `HEAD`, the hook restores tracked
+  `stylemaps/` files and removes untracked files under `stylemaps/current`, so a
+  clean push leaves no generated capture debris behind.
+
 ## [3.1.0] - 2026-06-27
 
 ### Changed
@@ -47,6 +112,10 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   generated tests are registered through the package runner. It now targets the
   capture suite with Playwright's grep path, matching the public
   `styleproof-init` → `styleproof-map` → `styleproof-diff` flow.
+- **Clean StyleProof PR runs now leave a visible receipt.** The Action creates or
+  updates its PR comment with `No visual changes detected.` even when there is no
+  existing report comment yet, and `styleproof-init` scaffolds the same
+  no-change PR comment for the browser-less committed-map workflow.
 - **Layout-equivalent auto-margin drift no longer creates phantom diffs.** Some
   browser/forced-state combinations can report horizontal `margin-left` /
   `margin-right` / logical margin equivalents differently even when the captured
@@ -889,7 +958,9 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.0...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.2...HEAD
+[3.1.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.1...v3.1.2
+[3.1.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.0...v3.1.1
 [3.1.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.0...v3.0.1

package/README.md

@@ -16,6 +16,7 @@ On every PR, StyleProof diffs the PR head's computed-style map against the base
 
 - A **lean summary comment** linking to a committed side-by-side report — the report is the complete source of truth (**one section per distinct change**, with a before/after cropped screenshot cropped from the same rectangle so the two sides line up exactly, **plain-English bullets that tell you what to look for** — `columns: 2 → 3`, `recoloured cyan → amber` — and the exact property changes). The comment never duplicates the report, so the two can't drift, and it renders identically on public and private repos.
 - A single **Approve all changes** checkbox in the comment, driving a `StyleProof` commit status: red until one tick signs off every change, green when there are none. The reviewer who ticks it is recorded inline (_approved by @them_), sourced from the commit status so it survives a report re-run.
+- **Clean runs leave a receipt too.** When no visual changes are detected, StyleProof still creates or updates the PR comment with `✓ No visual changes detected.`, so a green status has a visible record instead of only a silent check.
 - **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 in the report under a `🆕 new surface` heading but never holds the status red and needs no sign-off. It becomes part of the baseline once merged.
 - The diff is always **head-vs-base**, so the report is _exactly what this PR changes_ — whether the maps are captured fresh in CI or (by default) committed pre-push and diffed browser-free in CI. See [Quickstart](#quickstart).
 
@@ -167,7 +168,7 @@ It scaffolds:
 
 - a **capture spec** (`e2e/styleproof.spec.ts`) describing your surfaces (a Next.js app gets its routes _and_ the coverage guard wired automatically — see below);
 - a **`playwright.config.ts`** that builds and serves a **production build** (never a flaky dev server) and captures surfaces **in parallel** (`fullyParallel`);
-- a **pre-push hook** (`.githooks/pre-push`, activated for you via `core.hooksPath` — it won't clobber an existing husky setup) that captures the map, commits it as a lean `.json.gz` under `stylemaps/`, and **pushes it with your branch — one `git push`, never two**;
+- a **pre-push hook** (`.githooks/pre-push`, activated for you via `core.hooksPath` — it won't clobber an existing husky setup) that captures the map, restores no-op map churn, commits real map changes as lean `.json.gz` files under `stylemaps/`, and **pushes them with your branch — one `git push`, never two**;
 - a **browser-less CI workflow** that diffs your committed map against the base branch.
 
 Describe your surfaces — **omit `widths`** and StyleProof sweeps your real `@media` breakpoints automatically:
@@ -195,15 +196,18 @@ npx styleproof-map
 npx styleproof-diff
 ```
 
-`styleproof-map` captures this branch into `stylemaps/current`. `styleproof-diff`
-then compares that committed map against the base branch automatically: in GitHub
-Actions it uses the PR base; locally it checks `branch.<name>.gh-merge-base`, then
-the current GitHub PR base via `gh pr view` (handy for stacked PRs), then
+`styleproof-map` captures this branch into `stylemaps/current` as lean committed
+maps: HAR recordings are removed by default so private API responses do not land
+in git. Keep them only for an explicit record/replay workflow with
+`styleproof-map --keep-har` (or `STYLEPROOF_KEEP_HAR=1`). `styleproof-diff` then
+compares the committed map against the base branch automatically: in GitHub
+Actions it uses the PR base; locally it checks `branch.<name>.gh-merge-base`,
+then the current GitHub PR base via `gh pr view` (handy for stacked PRs), then
 `origin/main`, `origin/master`, `main`, and `master`. Pin it when needed with
 `styleproof-diff main`, `styleproof-diff master`, or `styleproof-diff --base-ref
 origin/my-base`.
 
-**That's the whole loop.** Capture happens **pre-push on your machine** (where the app already builds and serves); the lean map is committed and pushed; and **CI is a browser-less diff of two precomputed maps** — no build, no browser, just a fast comparison (~5400× cheaper on the compare step than re-capturing both sides in CI). `main` always carries a base map, so every PR is _your code vs the committed base_. Require the `StyleProof` status in branch protection and an unverified visual change can't merge.
+**That's the whole loop.** Capture happens **pre-push on your machine** (where the app already builds and serves); the hook first diffs the refreshed map against `HEAD` and restores it when the semantic map is unchanged, otherwise it commits and pushes the lean map; and **CI is a browser-less diff of two precomputed maps** — no build, no browser, just a fast comparison (~5400× cheaper on the compare step than re-capturing both sides in CI). `main` always carries a base map, so every PR is _your code vs the committed base_. Require the `StyleProof` status in branch protection and an unverified visual change can't merge.
 
 > **Same-environment note.** Computed styles depend on the browser build and installed fonts, so maps are only comparable when captured in the same environment (your machine, or a pinned container). The self-check fails loudly on a non-deterministic capture, so drift never passes silently.
 
@@ -230,6 +234,24 @@ Then copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwar
 
 **Prefer to capture in CI instead of committing maps?** For a repo with many outside contributors on different machines, StyleProof can capture **both** base and head in CI and diff them there — no committed maps. See **[Forks and Dependabot](#forks-and-dependabot)** for that flow (it's also the fork-safe split). The committed-map flow above is the default because it's far faster and simpler for a single team.
 
+**Want to skip work safely?** Skip the **whole** StyleProof workflow only for
+changes that cannot affect rendered output, such as docs-only edits, using your
+CI provider's native path filters. Do not skip individual surfaces from a
+StyleProof run based on a changed-file guess: shared CSS, tokens, resets,
+themes, layout primitives, and runtime styling can repaint any surface, and a
+missed surface would certify green without being measured. If you want faster
+feedback, order the highest-signal surfaces first in your spec, but still let
+the full sweep finish before treating the gate as passed.
+
+```yaml
+on:
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - '.github/ISSUE_TEMPLATE/**'
+```
+
 ## Forks and Dependabot
 
 If you **capture in CI** rather than committing maps (the alternative noted at the end of the Quickstart — a better fit when many outside contributors push from different machines), the simplest setup runs the whole gate in one `pull_request` job that captures base + head and diffs them. That job needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.
@@ -269,7 +291,7 @@ Anything still moving on its own after that is detected as a volatile region and
 | Handled for you — zero config                               | How                                                                                      |
 | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | In-flight data, fonts, late layout                          | network-aware settle holds until requests finish _and_ the computed styles stop changing |
-| Animations, transitions, focus ring, caret                  | frozen / blurred before the map is read                                                  |
+| Animations, transitions, real hover/focus, caret            | frozen / neutralised before the map is read; forced states are captured separately       |
 | Clock-derived styling (`stale > 1h → red`)                  | `Date.now()` / `new Date()` frozen to a fixed instant                                    |
 | Framework & non-visual noise (`<script>`, route announcers) | skipped by default                                                                       |
 | Layout-equivalent horizontal auto margins                   | ignored only when the captured element rectangle is unchanged                            |

package/bin/styleproof-init.mjs

@@ -309,6 +309,31 @@ remote="$1"
 
 ${PM.exec(`styleproof-map --spec ${specPath}`)}
 
+if git cat-file -e HEAD:stylemaps/current 2>/dev/null; then
+  tmp="\${TMPDIR:-/tmp}/styleproof-pre-push-diff.$$"
+  set +e
+  ${PM.exec('styleproof-diff --base-ref HEAD --max=20')} > "$tmp"
+  code=$?
+  set -e
+
+  if [ "$code" -eq 2 ]; then
+    cat "$tmp" >&2
+    rm -f "$tmp"
+    exit 2
+  fi
+
+  if [ "$code" -eq 0 ]; then
+    rm -f "$tmp"
+    git restore --source=HEAD -- stylemaps
+    git clean -fdq -- stylemaps/current
+    exit 0
+  fi
+
+  cat "$tmp" >&2
+  rm -f "$tmp"
+  echo "StyleProof: style map changed. If this was not an intended visual change, pin live states or replay/fixture the data boundary before pushing." >&2
+fi
+
 git add stylemaps
 git diff --cached --quiet -- stylemaps && exit 0  # map unchanged — let the push proceed
 
@@ -333,6 +358,8 @@ on: pull_request
 
 permissions:
   contents: read
+  issues: write
+  pull-requests: write
 
 jobs:
   styleproof:
@@ -343,8 +370,59 @@ jobs:
           fetch-depth: 0 # need the base ref to read its committed map
 ${PM.setup}
       - run: ${PM.install}
-      - name: Diff this branch's committed map against the base
-        run: ${PM.exec(`styleproof-diff --base-ref "origin/\${{ github.event.pull_request.base.ref }}"`)}
+      - id: diff
+        name: Diff this branch's committed map against the base
+        shell: bash
+        run: |
+          set +e
+          ${PM.exec(`styleproof-diff --base-ref "origin/\${{ github.event.pull_request.base.ref }}"`)} | tee styleproof-diff.txt
+          code=\${PIPESTATUS[0]}
+          set -e
+          echo "exit-code=\${code}" >> "$GITHUB_OUTPUT"
+          if [ "$code" -eq 0 ]; then
+            echo "result=clean" >> "$GITHUB_OUTPUT"
+          elif [ "$code" -eq 1 ]; then
+            echo "result=changed" >> "$GITHUB_OUTPUT"
+          elif [ "$code" -eq 3 ]; then
+            echo "result=new" >> "$GITHUB_OUTPUT"
+          else
+            echo "result=error" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Comment StyleProof result
+        if: >-
+          always() &&
+          github.event_name == 'pull_request' &&
+          steps.diff.outputs.result != '' &&
+          steps.diff.outputs.result != 'error'
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const issue_number = context.payload.pull_request.number;
+            const marker = '<!-- styleproof-report -->';
+            const result = '\${{ steps.diff.outputs.result }}';
+            const bodies = {
+              clean: '✓ No visual changes detected.',
+              new: '🆕 New surface(s) detected — no committed baseline to diff against yet, so nothing to approve. They will be certified once their map is committed.',
+              changed: 'Visual changes detected. See the StyleProof check logs for the computed-style diff.',
+            };
+            const body = marker + '\\n## 🗺️ StyleProof report\\n\\n' + (bodies[result] || bodies.changed);
+            const { data: comments } = await github.rest.issues.listComments({
+              ...context.repo,
+              issue_number,
+              per_page: 100,
+            });
+            const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ ...context.repo, issue_number, body });
+            }
+      - name: Fail on StyleProof diff
+        # Exit 1 = reviewable diffs (gate red); 2 = error. Exit 3 (new surface,
+        # no baseline) never blocks — it has nothing to approve yet.
+        if: steps.diff.outputs.exit-code != '0' && steps.diff.outputs.exit-code != '3'
+        shell: bash
+        run: exit \${{ steps.diff.outputs.exit-code }}
 `;
 
 function writeFileSafe(file, contents, { force: f } = {}) {

package/bin/styleproof-map.mjs

@@ -30,12 +30,13 @@ options:
   --base-dir <path>   output root directory (default: stylemaps)
   --screenshots       keep screenshots for reports (default: off for committed maps)
   --no-screenshots    write lean .json.gz maps only (default)
+  --keep-har          keep recorded HAR files for advanced replay workflows
   -h, --help          show this help
 
 Examples:
   styleproof-map
   styleproof-map --spec e2e/styleproof.spec.ts
-  styleproof-map --dir review --base-dir __stylemaps__ --screenshots
+  styleproof-map --dir review --base-dir __stylemaps__ --screenshots --keep-har
 `;
 
 const argv = process.argv.slice(2);
@@ -43,6 +44,7 @@ let spec = 'e2e/styleproof.spec.ts';
 let dir = process.env.STYLEMAP_DIR ?? 'current';
 let baseDir = process.env.STYLEPROOF_BASEDIR ?? 'stylemaps';
 let screenshots = process.env.STYLEPROOF_SCREENSHOTS ?? '0';
+let keepHar = process.env.STYLEPROOF_KEEP_HAR === '1';
 const playwrightArgs = [];
 
 for (let i = 0; i < argv.length; i++) {
@@ -59,6 +61,7 @@ for (let i = 0; i < argv.length; i++) {
   else if (a.startsWith('--base-dir=')) baseDir = a.slice(11);
   else if (a === '--screenshots') screenshots = '1';
   else if (a === '--no-screenshots') screenshots = '0';
+  else if (a === '--keep-har') keepHar = true;
   else if (a.startsWith('--')) {
     console.error(unknownFlagMessage('styleproof-map', a));
     process.exit(2);
@@ -84,6 +87,15 @@ if (!fs.existsSync(spec)) {
   process.exit(2);
 }
 
+function removeHarFiles(root) {
+  if (!fs.existsSync(root)) return;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const full = `${root}/${entry.name}`;
+    if (entry.isDirectory()) removeHarFiles(full);
+    else if (entry.isFile() && entry.name.endsWith('.har')) fs.rmSync(full, { force: true });
+  }
+}
+
 const command = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
 const env = {
   ...process.env,
@@ -99,4 +111,6 @@ if (result.error) {
   console.error(playwrightMissingMessage(result.error.message));
   process.exit(2);
 }
-process.exit(result.status ?? 1);
+const status = result.status ?? 1;
+if (status === 0 && !keepHar) removeHarFiles(`${baseDir}/${dir}`);
+process.exit(status);

package/dist/capture.d.ts

@@ -76,10 +76,11 @@ export type StyleMap = {
     elements: Record<string, ElementEntry>;
     states: Record<string, Record<string, Record<string, Props>>>;
     /**
-     * True when the forced :hover/:focus/:active layer was skipped for this
-     * capture because of CDP/page interactive-element count skew. Persisted so a
-     * diff against a fully-captured side flags that the state layer wasn't
-     * certified, instead of silently reading as "identical".
+     * True when the forced :hover/:focus/:active layer was not fully captured for
+     * this capture — either CDP/page interactive-element count skew, or because the
+     * interactive-element count exceeded `maxInteractive` and capture was truncated.
+     * Persisted so a diff against a fully-captured side flags that the state layer
+     * wasn't certified, instead of silently reading as "identical".
      */
     statesSkipped?: boolean;
     /**

package/dist/capture.js

@@ -24,7 +24,26 @@ const FRAMEWORK_IGNORE = [
     'template',
     'next-route-announcer',
     '[id="__next-route-announcer__"]',
+    '[data-styleproof-hover-sink]',
 ];
+function installHoverSink() {
+    let sink = document.querySelector('[data-styleproof-hover-sink]');
+    if (!sink) {
+        sink = document.createElement('div');
+        sink.setAttribute('data-styleproof-hover-sink', '');
+        document.body.appendChild(sink);
+    }
+    sink.setAttribute('style', [
+        'position:fixed',
+        'left:0',
+        'top:0',
+        'width:1px',
+        'height:1px',
+        'z-index:2147483647',
+        'pointer-events:auto',
+        'opacity:0',
+    ].join(';'));
+}
 /** 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) {
@@ -356,7 +375,8 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
     const marked = (await page.evaluate(markInteractiveElements, { selector: INTERACTIVE, skipSel, attr: STATE_ID_ATTR })).filter((m) => !(skipPaths.length && isUnder(m.path, skipPaths)));
     const limit = Math.min(marked.length, maxInteractive);
-    if (marked.length > maxInteractive) {
+    const truncated = marked.length > maxInteractive;
+    if (truncated) {
         // eslint-disable-next-line no-console
         console.warn(`styleproof: ${marked.length} interactive elements exceeds maxInteractive=${maxInteractive}; ` +
             `forced-state capture truncated to the first ${maxInteractive}. Raise maxInteractive to cover them all.`);
@@ -386,7 +406,10 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
         await page.evaluate(clearInteractiveMarks, STATE_ID_ATTR).catch(() => undefined);
         await client.detach();
     }
-    return { states, skipped: false };
+    // When truncated, the elements past the limit have no forced-state delta —
+    // flag the layer so the diff reports it as uncertified instead of letting the
+    // missing states read as "identical" against a fully-captured side.
+    return { states, skipped: truncated };
 }
 /** Element paths that differ between two captures (added, removed, or restyled). */
 function changedElementPaths(a, b) {
@@ -582,15 +605,17 @@ export async function captureStyleMap(page, options = {}) {
     const stabilize = options.stabilize ?? true;
     const captureText = options.captureText ?? false;
     const captureComponent = options.captureComponent ?? false;
-    // Neutralise real focus the same way FREEZE_CSS neutralises motion: blur
-    // whatever element holds focus so every read below is the no-interaction
-    // resting state. Real :focus is nondeterministic across runs (autofocus, late
-    // hydration, a stray prior action) and contaminates BOTH layers — it bakes a
-    // focus ring into the resting map, AND it cancels the forced-state :focus delta
-    // (forcing :focus on an already-focused element changes nothing, so the ring
-    // shows up as a delta on some runs but not others — a self-check "non-
-    // deterministic" failure). Interaction states are certified deterministically
-    // via CDP forcePseudoState below, never via whatever happened to be focused.
+    // Neutralise real hover/focus the same way FREEZE_CSS neutralises motion: park
+    // the pointer over an ignored 1px sink and blur whatever element holds focus so
+    // every read below is the no-interaction resting state. Real :hover/:focus is
+    // nondeterministic across runs (the last Playwright action, autofocus, late
+    // hydration, a stray prior action) and contaminates BOTH layers — it bakes an
+    // interaction style into the resting map, AND it cancels that forced-state
+    // delta (forcing :focus on an already-focused element changes nothing). States
+    // are certified deterministically via CDP forcePseudoState below, never via
+    // whatever happened to be hovered or focused.
+    await page.evaluate(installHoverSink);
+    await page.mouse.move(0, 0);
     await page.evaluate(() => document.activeElement?.blur?.());
     // Inject the structural-path helper once so both capturePage and
     // markInteractiveElements (each serialized into the page by page.evaluate, which
@@ -609,7 +634,9 @@ export async function captureStyleMap(page, options = {}) {
     // Detect semantic live-state candidates automatically, but don't exclude them
     // merely for being live regions. Stable status/alert/log UI is product UI and
     // should still be captured; this metadata only improves reports and diagnostics.
-    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore: FRAMEWORK_IGNORE });
+    // Honour the caller's `ignore` too: a region the user excluded shouldn't be
+    // surfaced (or persisted) as a live candidate, matching every other capture pass.
+    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore });
     // Motion longhands (transition/animation) are read separately so declared
     // motion is verified even though every other value is a frozen end state.
     // Read them on the SETTLED DOM, not before it: capturing pre-settle missed any

package/dist/diff.js

@@ -101,8 +101,9 @@ export function diffStyleMaps(a, b) {
         }
     }
     // If the forced-state layer was skipped on exactly one side (CDP skew during
-    // that capture), the :hover/:focus/:active layer was not compared — flag it
-    // loudly rather than letting {} vs {} read as "identical".
+    // capture, or truncation past maxInteractive), the :hover/:focus/:active layer
+    // was not fully compared — flag it loudly rather than letting {} vs {} read as
+    // "identical".
     if (!!a.statesSkipped !== !!b.statesSkipped) {
         findings.push({
             kind: 'state',
@@ -113,8 +114,8 @@ export function diffStyleMaps(a, b) {
             props: [
                 {
                     prop: 'forced :hover/:focus/:active layer',
-                    before: a.statesSkipped ? 'skipped (CDP skew)' : 'captured',
-                    after: b.statesSkipped ? 'skipped (CDP skew)' : 'captured',
+                    before: a.statesSkipped ? 'not fully captured' : 'captured',
+                    after: b.statesSkipped ? 'not fully captured' : 'captured',
                 },
             ],
         });

package/package.json

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