styleproof 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -7,6 +7,35 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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 +76,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 +922,8 @@ 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.1...HEAD
+[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.
 
@@ -269,7 +273,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,52 @@ 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 ] || [ "$code" -eq 3 ]; then
+            echo "result=changed" >> "$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 clean = '\${{ steps.diff.outputs.result }}' === 'clean';
+            const body = clean
+              ? marker + '\\n## 🗺️ StyleProof report\\n\\n✓ No visual changes detected.'
+              : marker + '\\n## 🗺️ StyleProof report\\n\\nVisual changes detected. See the StyleProof check logs for the computed-style diff.';
+            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
+        if: steps.diff.outputs.exit-code != '0'
+        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.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) {
@@ -582,15 +601,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

package/package.json

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