styleproof 3.19.0 → 3.20.0

package/CHANGELOG.md

@@ -7,6 +7,83 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.20.0] - 2026-07-07
+
+### Fixed
+
+- **Crawl no longer double-captures `/` and `/index.html` as two surfaces.** On a
+  static multi-page site whose nav links the `.html` files, `/` and `/index.html`
+  (and `/dir/` vs `/dir/index.html`) are the same route but were captured twice as
+  byte-near-identical maps — doubling the capture work and duplicating every finding
+  in the diff. The crawl's dedup identity now normalizes a trailing `index.html` to
+  its directory path, so they collapse to one surface (first-seen href keeps its
+  original navigable form). Only the literal `index.html` filename normalizes — a
+  genuine `about.html` stays a distinct surface from `about`.
+- **`styleproof-init` now states exactly which files it wrote — and that it did NOT
+  touch `package.json` or your lockfile.** Adopters attributed the `styleproof`
+  dependency entry (added by their package manager's `install`) to init; init only
+  ever reads `package.json` and writes the spec, the dedicated Playwright config,
+  `.gitignore` lines, and the CI workflow. The summary now enumerates those files and
+  says plainly that the manifest and lockfile were left untouched.
+- **The no-comparison outcome of `styleproof-diff` / `styleproof-report` names both
+  ways forward.** When the no-args (inferred-base) path can restore no base map — no
+  map-store remote, no cached bundle — nothing is compared. That already exits `2`
+  (never a soft `0` a newcomer could read as "certified clean"); the message now says
+  "nothing was compared" and names the two working alternatives: run in CI (or a repo
+  with the `origin` remote) where the base is restorable, or the two-directory form
+  `styleproof-diff <beforeDir> <afterDir>`. A regression test pins the exit-2 contract
+  in a remote-less repo for both commands.
+- **README: the Next.js coverage guard is described accurately.** The docs conflated
+  two behaviors. With the auto-wired spec, `surfaces` and `expected` both derive from
+  the same `discoverNextRoutes()` call, so a new static route is captured and expected
+  together — **auto-covered, never a guard failure**. The guard **fails** only on
+  genuine divergence (a dynamic route, a hand-maintained registry, or a route dropped
+  from `surfaces` while still `expected`). Rewrote the overclaiming passages and the
+  generated-spec comments to state both behaviors.
+- **Layout-equivalent margin suppression no longer drops a real one-sided margin
+  change.** `dropLayoutEquivalentMarginProps` suppressed any horizontal
+  `margin-left/right/inline-start/inline-end` change whenever the element's rect
+  was unchanged — reasoning that a margin that doesn't move the box is cosmetic
+  drift. But a one-sided change (e.g. `margin-left: 0 → 40px` with `margin-right`
+  untouched) that leaves the rect identical only stayed put because _something
+  else compensated_; that is a genuine restyle, and it was silently dropped. The
+  suppression now fires only when there is no **demonstrable px imbalance**
+  between a side and its opposite — balanced drift (both sides move together) and
+  forced-state deltas are still suppressed exactly as before, but a one-sided
+  real change surfaces. A residual, consciously-deferred corner remains (a
+  perfectly _balanced_ change held in place by external compensation), documented
+  inline; closing it needs cross-element layout reasoning.
+- **`styleproof-init` no longer imports the whole library barrel (fixes a CI
+  flake).** The scaffolder only needs `discoverNextRoutes`, but it imported it
+  from `dist/index.js` — dragging capture, the crawler, the report renderer, and
+  six Playwright-importing modules into a tool that writes files and captures
+  nothing. Loading that oversized module graph concurrently (init's own suite
+  spawns the CLI many times, alongside the rest of `node --test`) is what made
+  init's tests flake in CI, red-flagging releases with no code cause. It now
+  imports from the `dist/routes.js` leaf (`fs` + `path` only): init's transitive
+  module graph drops from 21 dist modules to 1, with zero Playwright modules on
+  its load path. Behaviour is unchanged; a regression test pins the leaf import.
+- **Popup capture: verified reset + identity-bound triggers (no leaked-overlay
+  contamination, no wrong-trigger keying).** On a surface whose `go()` doesn't
+  navigate (SPA variants), the between-popups reset was Escape-only and assumed:
+  a toast or `[role="status"]` overlay Escape can't dismiss leaked into the next
+  popup's capture, and each reopen re-enumerated triggers positionally, so a
+  shifted trigger set (e.g. a click that adds a button) could key a popup under a
+  different trigger than the one originally enumerated. Triggers are now re-bound
+  by the DOM identity recorded at first enumeration, and the reset is verified
+  against the surface's pristine overlay set; a candidate that can't be opened
+  safely is skipped loudly (a `styleproof:` warning naming the popup and the
+  leaked overlay or missing trigger) instead of being captured contaminated,
+  mis-keyed, or — with self-check on — saved unproven. That identity is the
+  trigger's DOM path **and** its accessible label, not the path alone: for an
+  id-less trigger the path ends in `:nth-of-type`, which is still position within
+  a parent, so a same-tag same-parent sibling injected earlier in DOM order
+  between enumeration and reopen would slide the recorded path onto a different
+  trigger and key its popup under the wrong one — silently. Requiring the label
+  (the same aria-label/name/text/title accessible name the crawler reads) to match
+  too turns that mismatch into the same loud skip. Navigating surfaces are
+  unaffected.
+
 ## [3.19.0] - 2026-07-06
 
 ### Added

package/README.md

@@ -57,8 +57,12 @@ surface. `expected` turns that inventory into a guard: a key it lists that is
 neither captured nor excluded fails as missing coverage instead of silently
 passing. What's guarded depends on how `expected` is fed —
 
-- **Next.js:** auto-guarded. `styleproof-init` wires `expected` to the routes it
-  discovers, so a new page fails the guard with nothing to keep in sync.
+- **Next.js:** auto-covered. `styleproof-init` derives both `surfaces` and
+  `expected` from the same `discoverNextRoutes()` call, so a new static route lands
+  in both at once — captured and expected together, with nothing to keep in sync.
+  The guard then fails only on genuine divergence between the two: a dynamic route
+  (pre-excluded, so its reason surfaces), a hand-maintained registry, or a route
+  dropped from `surfaces` while still in `expected`.
 - **Link-crawled SPAs:** pass `expected` to `defineCrawlCapture` and the crawl
   reconciles it against the _rendered nav_ (the route universe for such an app),
   both directions — a new linked route with no `expected` entry fails, and an
@@ -152,7 +156,7 @@ _and_ no head capture, so it never appears in any diff, and the status goes
 green having never looked at it. This is the one thing the captures can't catch
 on their own: a capture that was never taken.
 
-Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails the moment a route exists with no surface, so a new page can't ship uncaptured:
+Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails when `expected` and your captured surfaces diverge — a route you listed in `expected` with no surface and no `exclude` entry fails as missing coverage, so a registry entry can't quietly ship uncaptured:
 
 ```ts
 import { defineStyleMapCapture } from 'styleproof';
@@ -168,7 +172,7 @@ defineStyleMapCapture({
 
 A route that's neither a captured surface nor an `exclude` entry fails the guard; an `exclude` key that isn't in `expected` (a renamed/removed route) fails too, so the opt-out ledger can't quietly rot. Captured surfaces beyond `expected` are fine — one route can have several states (`landing`, `landing-nav-open`). Omit `expected` and behaviour is unchanged.
 
-**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and wires both the surfaces and `expected` to them — so it's protected out of the box, and a page you add later is covered automatically with nothing to keep in sync:
+**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and derives **both** the surfaces and `expected` from that same `discoverNextRoutes()` call. Because they share one source, a static route you add later is captured and expected in the same step — auto-covered, never a guard failure, with nothing to keep in sync. The guard exists for the cases where the two genuinely diverge: a dynamic `[param]` route (it can't be navigated without a value, so it's placed in `exclude` with a reason rather than captured), a registry you hand-maintain instead of the live call, or a route you drop from `surfaces` while it's still `expected`:
 
 ```ts
 import { defineStyleMapCapture, discoverNextRoutes } from 'styleproof';
@@ -292,6 +296,17 @@ semantic roots that were actually present in the computed-style map, so tests ca
 assert a capture reached `role="dialog"`, `aria-modal`, `role="menu"`,
 `role="listbox"`, or hot-toast text.
 
+Triggers are enumerated once per surface and every reopen re-binds to that same
+element by identity — its DOM path **and** its accessible label — never by
+position. Between popups the surface is reset (Escape + `go()`) and the reset is
+verified: if an overlay a previous popup left behind is still visible (Escape
+closes dialogs, not toasts or status regions), or an enumerated trigger
+disappeared or changed identity (e.g. a same-tag sibling shifted in earlier),
+that candidate is **skipped loudly** — a `styleproof:` warning names the popup and
+why — instead of capturing contaminated state or keying a popup under the wrong
+trigger. Dismiss the leaking overlay in the surface's `go()`, or capture it as an
+explicit variant.
+
 **Harvest one-step variants.** Routes are not the whole UI: drawers, tabs,
 dialogs, empty form errors, selects, and other one-step states need their own
 captures. `styleproof-variants` opens a running app, tries semantic controls
@@ -851,7 +866,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 - `styleproof-init` — scaffold the gate: the capture spec, a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
 - `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--crawl-base-url` plus repeated `--crawl-route` to run `styleproof-variants` before capture, `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
-- `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical); `1` on a reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new); `3` when only new surfaces are present (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no manifest at all, meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
+- `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical); `1` on a reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new — **and** the no-args case where the cached base map can't be restored at all: no map-store remote, no cached bundle, nothing to compare. A "nothing was compared" outcome always exits `2`, never a soft `0` that would read as certified; the error names the two ways forward — run in CI where the base is restorable, or use the two-directory form); `3` when only new surfaces are present (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no manifest at all, meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
 - `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports cached maps for the current commit against the inferred base; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).
 - `styleproof-variants` — crawl a running app for one-step state variants and write `styleproof.variants.generated.json`. Pass `--base-url`, repeat `--route`, and use `--strict` when unresolved skipped/live candidates should fail automation.
 

package/bin/styleproof-init.mjs

@@ -7,10 +7,13 @@
  * Writes:
  *   - <dir> (default e2e/styleproof.spec.ts): a starter capture spec with a
  *     minimal settle() helper (triggers scroll-reveal content; StyleProof itself
- *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives surfaces AND
- *     the `expected` coverage guard from the app's routes at run time, so a page
- *     added later can't ship without a surface; otherwise it writes one sample
- *     surface plus a commented guard block to wire to your own route registry.
+ *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives BOTH the
+ *     surfaces AND the `expected` coverage guard from the same `discoverNextRoutes()`
+ *     call, so a static route added later is captured and expected together —
+ *     auto-covered, never a guard failure; the guard fails only on genuine
+ *     divergence (a dynamic route, a hand-maintained registry, or a route dropped
+ *     from surfaces but still expected). Otherwise it writes one sample surface
+ *     plus a commented guard block to wire to your own route registry.
  *   - playwright.styleproof.config.ts: a dedicated production-build Playwright
  *     config for StyleProof captures, so an existing app Playwright config is
  *     never disturbed or accidentally reused.
@@ -23,7 +26,12 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { discoverNextRoutes } from '../dist/index.js';
+// Import from the leaf module, not the barrel: styleproof-init only scaffolds
+// files and never captures. Pulling `../dist/index.js` here dragged the whole
+// library — capture, crawler, report, and six Playwright-importing modules —
+// into a tiny scaffolder's load path, and that oversized concurrent module
+// graph is what made init's tests flake in CI. routes.js needs only fs + path.
+import { discoverNextRoutes } from '../dist/routes.js';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
@@ -39,9 +47,10 @@ options:
 
 What it writes:
   - the spec at --dir, with a minimal settle() helper (scroll-reveal only).
-    In a Next.js app it discovers your routes at run time and wires both the
-    surfaces and the \`expected\` coverage guard to them, so a new page can't ship
-    uncaptured. Otherwise it writes one sample surface + a commented guard block.
+    In a Next.js app it discovers your routes at run time and derives both the
+    surfaces and the \`expected\` coverage guard from that one call, so a new static
+    route is auto-covered (captured + expected together); the guard fails only when
+    the two diverge. Otherwise it writes one sample surface + a commented guard block.
   - playwright.styleproof.config.ts, a dedicated production-build Playwright config
   - .github/workflows/styleproof.yml, a cache-first PR report workflow
 
@@ -114,9 +123,12 @@ const HEADER = `/**
  *   npx styleproof-diff  # compare cached base/head maps by commit SHA
  */`;
 
-// Next.js detected: derive both surfaces and the coverage guard from the app's
-// routes AT RUN TIME, so a page added later is in `expected` automatically and
-// fails the guard until it has a surface — no static list to drift.
+// Next.js detected: derive BOTH surfaces and the coverage guard from the app's
+// routes AT RUN TIME, from one `discoverNextRoutes()` call — so a static page added
+// later is a captured surface AND `expected` in the same step (auto-covered, never a
+// guard failure), with no static list to drift. The guard fires only when the two
+// diverge (a dynamic route, a hand-maintained registry, or a route dropped from
+// surfaces but still expected).
 const NEXT_SPEC = `import type { Page } from '@playwright/test';
 import { defineStyleMapCapture, discoverNextRoutes, type Surface } from 'styleproof';
 
@@ -124,12 +136,12 @@ ${HEADER}
 
 ${SETTLE}
 
-// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME — so a page
-// you add later is covered automatically, with no surface list to keep in sync
-// (that drift is exactly what lets a new page ship unverified). Edit freely; this
-// is your spec. Static routes each get a capture; dynamic [param] routes can't be
-// navigated without a value, so they're listed in \`exclude\` until you add a
-// surface with a concrete param.
+// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME. Both SURFACES
+// and \`expected\` below come from this one list, so a static route you add later is
+// captured and expected together — covered automatically, with no surface list to
+// keep in sync. Edit freely; this is your spec. Static routes each get a capture;
+// dynamic [param] routes can't be navigated without a value, so they're listed in
+// \`exclude\` until you add a surface with a concrete param.
 const ROUTES = discoverNextRoutes();
 
 const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
@@ -146,9 +158,10 @@ const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
 
 defineStyleMapCapture({
   surfaces: SURFACES,
-  // Coverage guard: every known route must be a captured surface or excluded, or
-  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser).
-  // A new page with no surface can't slip through the gate unseen.
+  // Coverage guard: every \`expected\` route must be a captured surface or excluded, or
+  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser). Since
+  // both sides come from ROUTES, static routes never trip it; it fires when they
+  // diverge — a dynamic route (excluded below), or a route you drop from SURFACES.
   expected: ROUTES.map((r) => r.key),
   exclude: Object.fromEntries(
     ROUTES.filter((r) => r.dynamic).map((r) => [r.key, \`dynamic route (\${r.path}) — add a surface with a concrete param\`]),
@@ -480,9 +493,14 @@ const isNext = routes.length > 0;
 const SPEC = isNext ? NEXT_SPEC : GENERIC_SPEC;
 
 let wroteSomething = false;
+// Every path init created or modified this run, so the summary can name exactly what
+// it touched — and, by omission, what it did NOT (init never writes package.json or a
+// lockfile; that's the package manager's `install`, not this scaffolder).
+const touched = [];
 
 const spec = writeFileSafe(specPath, SPEC, { force });
 if (spec.wrote) {
+  touched.push(specPath);
   console.log(`${spec.exists ? 'overwrote' : 'created'} ${specPath}`);
   if (isNext) {
     const dynamic = routes.filter((r) => r.dynamic).length;
@@ -502,6 +520,7 @@ if (spec.wrote) {
 const configPath = 'playwright.styleproof.config.ts';
 const config = writeFileSafe(configPath, CONFIG, { force });
 if (config.wrote) {
+  touched.push(configPath);
   console.log(`${config.exists ? 'overwrote' : 'created'} ${configPath} (dedicated StyleProof capture config)`);
   wroteSomething = true;
 } else {
@@ -515,6 +534,7 @@ if (fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js
 
 const ignored = ['.styleproof/', 'test-results/', 'playwright-report/'].filter((line) => ensureGitignoreLine(line));
 if (ignored.length) {
+  touched.push('.gitignore');
   console.log(`updated .gitignore (${ignored.join(', ')})`);
   wroteSomething = true;
 }
@@ -522,12 +542,21 @@ if (ignored.length) {
 // Cache-first CI report — never overwrite an existing workflow.
 const ci = writeFileSafe(CI_PATH, CI_WORKFLOW);
 if (ci.wrote) {
+  touched.push(CI_PATH);
   console.log(`created ${CI_PATH} (cache-first StyleProof report)`);
   wroteSomething = true;
 } else {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
+if (touched.length) {
+  // State exactly what init wrote, and — because adopters have blamed init for the
+  // `styleproof` entry their package manager's `install` added — say plainly that it
+  // did NOT touch package.json or the lockfile. Truth over assumption.
+  console.log(`\nstyleproof-init wrote only: ${touched.join(', ')}`);
+  console.log('It did NOT modify package.json or your lockfile (that was your package manager’s install).');
+}
+
 console.log('\nHow the gate works — it runs on your first PR with no extra steps:');
 console.log('  1. Commit and open a PR. CI captures the base and head surfaces in one pinned');
 console.log('     environment and posts the StyleProof report — no local step required.');

package/dist/cli-errors.js

@@ -14,9 +14,14 @@ export function cliErrorMessage(error) {
  */
 export function cachedMapsUnavailableMessage(command, purpose, error) {
     return [
-        `${command}: cached maps are not available for this ${purpose}`,
+        `${command}: cached maps are not available for this ${purpose} — nothing was compared`,
         cliErrorMessage(error),
-        'Next: run styleproof-map on the base and head commits to upload maps, or let CI recapture both sides.',
+        // Name the two ways forward explicitly so a newcomer never reads "nothing compared"
+        // as "certified clean": the cached-map path only works where the base is restorable
+        // (CI, or a repo with the map-store remote), and the two-directory form always works
+        // off already-captured maps with no git remote at all.
+        `Next: run this in CI (or a repo with the 'origin' remote) where the base map is restorable, ` +
+            `or capture both sides and compare them directly: ${command} <beforeDir> <afterDir>.`,
     ].join('\n');
 }
 export function unknownFlagMessage(command, flag) {

package/dist/crawl.js

@@ -80,9 +80,18 @@ function toLink(href, base, keyFor, match) {
     return { key: keyFor(url), url: path };
 }
 /**
- * Dedup identity for a navigable path+query: a trailing slash on the path is not a
- * distinct surface (`/about` and `/about/` render the same route), so it's stripped
- * from the identity — but never from the root `/` itself, and never from the query.
+ * Dedup identity for a navigable path+query. Two forms of the same route must share
+ * one identity, or a static multi-page site (whose nav links the `.html` files) gets
+ * captured twice as byte-near-identical maps, doubling the work and duplicating every
+ * finding in the diff:
+ *
+ * - A trailing slash isn't a distinct surface (`/about` and `/about/` render the same
+ *   route), so it's stripped — but never from the root `/` itself, nor from the query.
+ * - A trailing `index.html` is the directory's index (`/index.html` IS `/`, and
+ *   `/docs/index.html` IS `/docs/`), so it collapses to the directory path. Only the
+ *   literal `index.html` filename normalizes — a real `about.html` is left untouched
+ *   and stays a distinct surface from `about`.
+ *
  * The navigable url the caller returns keeps its original form; only the SET
  * membership test is normalized, so the first-seen href still wins.
  */
@@ -90,7 +99,10 @@ function dedupIdentity(pathAndSearch) {
     const q = pathAndSearch.indexOf('?');
     const path = q === -1 ? pathAndSearch : pathAndSearch.slice(0, q);
     const search = q === -1 ? '' : pathAndSearch.slice(q);
-    const normPath = path.length > 1 ? path.replace(/\/+$/, '') || '/' : path;
+    // `/index.html` → `/`, `/docs/index.html` → `/docs/` (the preceding slash stays so
+    // the trailing-slash step below folds it into the same identity as `/docs` / `/docs/`).
+    const withoutIndex = path.replace(/(^|\/)index\.html$/, '$1');
+    const normPath = withoutIndex.length > 1 ? withoutIndex.replace(/\/+$/, '') || '/' : withoutIndex;
     return normPath + search;
 }
 /**

package/dist/diff.js

@@ -63,9 +63,44 @@ const ORIGIN_EPSILON_PX = 0.05;
 function sameRect(a, b) {
     return !!a && !!b && a.every((v, i) => v === b[i]);
 }
+const HORIZONTAL_MARGIN_PAIRS = [
+    ['margin-left', 'margin-right'],
+    ['margin-inline-start', 'margin-inline-end'],
+];
+function marginPxDelta(p) {
+    const before = pxParts(p.before);
+    const after = pxParts(p.after);
+    return before?.length === 1 && after?.length === 1 ? after[0] - before[0] : null;
+}
+// True when one horizontal side moved by a different px amount than its
+// opposite. Such a change would shift the box on its own, so an *identical*
+// rect means something else compensated — a real restyle, not layout-equivalent
+// drift. Non-px or state-sentinel values (`(state no longer changes it)`) aren't
+// demonstrable, so they fall through to the balanced (drop) path unchanged.
+function marginChangeHasPxImbalance(props) {
+    const delta = new Map();
+    for (const p of props) {
+        if (LAYOUT_EQUIVALENT_MARGIN_PROPS.has(p.prop))
+            delta.set(p.prop, marginPxDelta(p));
+    }
+    for (const [start, end] of HORIZONTAL_MARGIN_PAIRS) {
+        const ds = delta.has(start) ? delta.get(start) : 0;
+        const de = delta.has(end) ? delta.get(end) : 0;
+        if (ds !== null && de !== null && ds !== de)
+            return true;
+    }
+    return false;
+}
 function dropLayoutEquivalentMarginProps(props, a, b) {
     if (!sameRect(a?.rect, b?.rect))
         return props;
+    // ponytail: a balanced margin change with an unchanged rect is treated as
+    // layout-equivalent from computed style alone. That still drops the rare case
+    // where a *balanced* change was held in place by external compensation — a
+    // consciously-deferred, low-reach soundness corner; closing it needs
+    // cross-element layout reasoning. The common one-sided case is caught here.
+    if (marginChangeHasPxImbalance(props))
+        return props;
     return props.filter((p) => !LAYOUT_EQUIVALENT_MARGIN_PROPS.has(p.prop));
 }
 function pxParts(value) {

package/dist/runner.js

@@ -104,7 +104,7 @@ export function resolvePopupCaptureOptions(input) {
     };
 }
 async function popupDomSnapshot(page, options) {
-    return page.evaluate(({ popupSelector, triggerSelector, attr, max = 0 }) => {
+    return page.evaluate(({ popupSelector, triggerSelector, attr, max = 0, relocatePath, relocateLabel }) => {
         const qsa = (sel) => {
             try {
                 return [...document.querySelectorAll(sel)];
@@ -133,6 +133,13 @@ async function popupDomSnapshot(page, options) {
             }
             return parts.join(' > ');
         };
+        // The trigger's accessible name — mirrors crawl-surfaces' labelFor (aria-label
+        // || name || textContent || title). `path` is positional for an id-less trigger;
+        // this pins identity so a shifted same-tag sibling can't silently steal the bind.
+        const labelOf = (el) => (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || el.getAttribute('title') || '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 80) || el.tagName.toLowerCase();
         const popupKey = (el) => {
             const text = (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 120);
             return [
@@ -150,7 +157,15 @@ async function popupDomSnapshot(page, options) {
         const popups = qsa(popupSelector).filter(visible);
         const keys = popups.map(popupKey);
         if (!triggerSelector || !attr)
-            return { keys, indexes: [] };
+            return { keys, candidates: [], found: false };
+        for (const el of qsa(`[${attr}]`))
+            el.removeAttribute(attr);
+        if (relocatePath) {
+            const target = qsa(triggerSelector).find((el) => pathOf(el) === relocatePath && labelOf(el) === relocateLabel);
+            if (target)
+                target.setAttribute(attr, 'target');
+            return { keys, candidates: [], found: Boolean(target) };
+        }
         const safeTrigger = (el) => {
             const tag = el.tagName.toLowerCase();
             if (el.matches(':disabled, [aria-disabled="true"]'))
@@ -161,24 +176,30 @@ async function popupDomSnapshot(page, options) {
                 return el.getAttribute('href')?.startsWith('#') ?? false;
             return true;
         };
-        for (const el of qsa(`[${attr}]`))
-            el.removeAttribute(attr);
-        const candidates = qsa(triggerSelector).filter((el) => visible(el) && !popups.some((popup) => popup !== el && popup.contains(el)) && safeTrigger(el));
-        candidates.slice(0, max).forEach((el, index) => el.setAttribute(attr, String(index)));
-        return { keys, indexes: candidates.slice(0, max).map((_, index) => index) };
+        const candidates = qsa(triggerSelector)
+            .filter((el) => visible(el) && !popups.some((popup) => popup !== el && popup.contains(el)) && safeTrigger(el))
+            .slice(0, max);
+        candidates.forEach((el, index) => el.setAttribute(attr, String(index)));
+        return {
+            keys,
+            candidates: candidates.map((el, index) => ({ index, path: pathOf(el), label: labelOf(el) })),
+            found: false,
+        };
     }, options);
 }
 async function visiblePopupKeys(page, selector) {
     return (await popupDomSnapshot(page, { popupSelector: selector })).keys;
 }
+/** Enumerate + mark the surface's popup triggers ONCE, and record the pristine
+ *  overlay keys in the same DOM snapshot — the reset baseline every reopen is
+ *  verified against. */
 async function markPopupCandidates(page, options) {
-    const snapshot = await popupDomSnapshot(page, {
+    return popupDomSnapshot(page, {
         triggerSelector: options.triggers,
         popupSelector: options.overlays,
         attr: POPUP_TRIGGER_ATTR,
         max: options.max,
     });
-    return snapshot.indexes.map((index) => ({ index }));
 }
 function expandOne(surface, variant, variantKind) {
     return {
@@ -308,16 +329,37 @@ async function assertDeterministic(page, surface, first, captureText, pending) {
         throw new Error(selfCheckErrorMessage(surface.key, drift, [...new Set([...(first.volatile ?? []), ...(again.volatile ?? [])])], liveCandidates));
     }
 }
-async function openPopupCandidate(page, surface, width, height, options, candidate) {
+/**
+ * Reset the surface (Escape + `go()`), then open ONE candidate's popup.
+ *
+ * Two guarantees the naive open loop lacked:
+ * - the reset is VERIFIED against the pristine overlay keys, not assumed —
+ *   Escape is not a universal close, and a non-navigating `go()` clears nothing;
+ * - the trigger is re-bound by the (path, label) identity recorded at first
+ *   enumeration, never by its position in a fresh enumeration (the trigger set can
+ *   shift between opens and silently key the popup under a different trigger; the
+ *   label pins identity where the path alone is still positional for id-less triggers).
+ * Either check failing is reported for the caller to skip loudly.
+ */
+async function openPopupCandidate(page, surface, width, height, options, candidate, pristine) {
     await page.setViewportSize({ width, height });
     await page.keyboard.press('Escape').catch(() => { });
     await surface.go(page);
-    const before = new Set(await visiblePopupKeys(page, options.overlays));
-    const candidates = await markPopupCandidates(page, options);
-    if (!candidates.some((c) => c.index === candidate.index))
-        return undefined;
+    const snapshot = await popupDomSnapshot(page, {
+        popupSelector: options.overlays,
+        triggerSelector: options.triggers,
+        attr: POPUP_TRIGGER_ATTR,
+        relocatePath: candidate.path,
+        relocateLabel: candidate.label,
+    });
+    const leaked = snapshot.keys.filter((key) => !pristine.has(key));
+    if (leaked.length)
+        return { status: 'leaked', leaked };
+    if (!snapshot.found)
+        return { status: 'missing' };
+    const before = new Set(snapshot.keys);
     await page
-        .locator(`[${POPUP_TRIGGER_ATTR}="${candidate.index}"]`)
+        .locator(`[${POPUP_TRIGGER_ATTR}="target"]`)
         .first()
         .click({ timeout: Math.max(500, options.timeoutMs), noWaitAfter: true })
         .catch(() => undefined);
@@ -325,10 +367,19 @@ async function openPopupCandidate(page, surface, width, height, options, candida
     do {
         const opened = (await visiblePopupKeys(page, options.overlays)).find((key) => !before.has(key));
         if (opened)
-            return opened;
+            return { status: 'opened', key: opened };
         await page.waitForTimeout(50);
     } while (Date.now() < deadline);
-    return undefined;
+    return { status: 'none' };
+}
+/** A popup candidate skipped instead of captured wrong must be NAMED — a silent
+ *  skip reads as "nothing to capture" when the truth is "couldn't capture safely". */
+function warnPopupSkipped(surface, popupId, width, reason) {
+    // eslint-disable-next-line no-console
+    console.warn(`styleproof: skipped ${surface.key}-${popupId}@${width} — ${reason}`);
+}
+function leakedOverlaysDesc(leaked) {
+    return `overlay(s) the reset (Escape + go()) could not clear: ${leaked.join('; ')}`;
 }
 function popupMetadata(surface, popupId) {
     return {
@@ -346,26 +397,52 @@ async function captureOpenedPopupMap(page, surface, s, pending, popupId) {
         metadata: popupMetadata(surface, popupId),
     });
 }
-async function assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, first, s, pending) {
-    const againKey = await openPopupCandidate(page, surface, width, height, options, candidate);
-    if (!againKey)
-        throw new Error(`styleproof self-check failed: ${surface.key}-${popupId} popup did not reopen`);
+/** Reopen the popup and throw on drift/no-reopen. Returns the leaked overlay keys
+ *  instead when the popup itself defeats the reset (e.g. it IS a toast Escape can't
+ *  dismiss) — the reopen can't run, so the caller discards the capture loudly
+ *  rather than saving a map whose determinism was never proven. */
+async function assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, first, s, pending, pristine) {
+    const reopened = await openPopupCandidate(page, surface, width, height, options, candidate, pristine);
+    if (reopened.status === 'leaked')
+        return reopened.leaked;
+    if (reopened.status !== 'opened') {
+        throw new Error(`styleproof self-check failed: ${surface.key}-${popupId} popup did not reopen` +
+            (reopened.status === 'missing' ? ' (its trigger disappeared from the DOM or changed identity)' : ''));
+    }
     const again = await captureOpenedPopupMap(page, surface, s, pending, popupId);
     const drift = diffStyleMaps(first, again);
     if (drift.length) {
         throw new Error(selfCheckErrorMessage(`${surface.key}-${popupId}`, drift, first.volatile, first.liveCandidates));
     }
+    return undefined;
 }
-async function capturePopupCandidate(page, surface, width, height, s, options, candidate) {
+async function capturePopupCandidate(page, surface, width, height, s, options, candidate, pristine) {
     const requests = trackInflightRequests(page);
+    const popupId = `popup-${String(candidate.index + 1).padStart(2, '0')}`;
     try {
-        const popupKey = await openPopupCandidate(page, surface, width, height, options, candidate);
-        if (!popupKey)
+        const opened = await openPopupCandidate(page, surface, width, height, options, candidate, pristine);
+        if (opened.status === 'none')
             return;
-        const popupId = `popup-${String(candidate.index + 1).padStart(2, '0')}`;
+        if (opened.status === 'leaked') {
+            warnPopupSkipped(surface, popupId, width, `${leakedOverlaysDesc(opened.leaked)} — capturing now would include the previous ` +
+                `popup's residue. Dismiss it in the surface's go(), or capture it as an explicit variant.`);
+            return;
+        }
+        if (opened.status === 'missing') {
+            warnPopupSkipped(surface, popupId, width, `its originally-enumerated trigger is no longer identifiable after the reset (Escape + go()) — ` +
+                `gone from the DOM, or a shifted same-tag sibling no longer matches its recorded label; ` +
+                `skipping rather than re-binding to a different trigger.`);
+            return;
+        }
         const map = await captureOpenedPopupMap(page, surface, s, requests.pending, popupId);
-        if (s.selfCheck)
-            await assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, map, s, requests.pending);
+        if (s.selfCheck) {
+            const leaked = await assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, map, s, requests.pending, pristine);
+            if (leaked) {
+                warnPopupSkipped(surface, popupId, width, `reopening for the self-check found ${leakedOverlaysDesc(leaked)} — the popup itself ` +
+                    `defeats the reset, so its determinism can't be verified and the capture is discarded.`);
+                return;
+            }
+        }
         const stem = path.join(s.baseDir, s.dir, `${surface.key}-${popupId}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots)
@@ -380,9 +457,12 @@ async function capturePopupSurfaces(page, surface, width, height, s) {
     if (!options.enabled || options.max === 0)
         return;
     await surface.go(page);
-    const candidates = await markPopupCandidates(page, options);
+    const { keys, candidates } = await markPopupCandidates(page, options);
+    // Overlays legitimately visible in the surface's settled state (e.g. a permanent
+    // status region) — every reopen is verified back to this baseline before capture.
+    const pristine = new Set(keys);
     for (const candidate of candidates) {
-        await capturePopupCandidate(page, surface, width, height, s, options, candidate);
+        await capturePopupCandidate(page, surface, width, height, s, options, candidate, pristine);
     }
 }
 /** Drive one surface at one width to a settled state and save its style map (+ screenshot).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.19.0",
+  "version": "3.20.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",
@@ -90,6 +90,6 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.18.0",
     "husky": "^9.1.7",
-    "fallow": "^2.96.0"
+    "fallow": "^3.2.0"
   }
 }