styleproof 3.18.0 → 3.20.0

package/dist/diff.js

@@ -63,14 +63,51 @@ 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) {
     const parts = value.trim().split(/\s+/);
-    if (parts.length < 2 || parts.length > 3)
+    // 1–3 components: a single-value origin (`50px`) jitters the same way as the
+    // 2/3-component form and must be suppressed identically.
+    if (parts.length < 1 || parts.length > 3)
         return null;
     const values = parts.map((part) => {
         const match = /^(-?\d+(?:\.\d+)?)px$/.exec(part);

package/dist/index.d.ts

@@ -23,5 +23,5 @@ export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, find
 export type { Finding, PropChange, SurfaceDiff, DiffCounts, ContentChange } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';
 export type { ReportOptions, ReportResult } from './report.js';
-export { affectedSurfaces, classifyStyleChange } from './affected-surfaces.js';
+export { affectedSurfaces, classifyStyleChange, explainAffectedSurfaces } from './affected-surfaces.js';
 export type { ModuleEdge, AffectedSurfacesInput, AffectedSurfaces } from './affected-surfaces.js';

package/dist/index.js

@@ -12,4 +12,4 @@ export { selectCrawlLinks, defaultLinkKey, crawlCoverageGaps, crawlCoverageError
 export { harvestStyleVariants } from './variant-crawler.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';
-export { affectedSurfaces, classifyStyleChange } from './affected-surfaces.js';
+export { affectedSurfaces, classifyStyleChange, explainAffectedSurfaces } from './affected-surfaces.js';

package/dist/inventory.js

@@ -50,7 +50,9 @@ export function collectNavAffordances() {
     };
     const nameOf = (el) => (el.getAttribute('aria-label') || el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80);
     const internalPath = (el) => {
-        const raw = (el.getAttribute('href') || '').trim();
+        // SVG anchors carry the target in `xlink:href` (legacy) or `href`; fall back so
+        // an <svg><a> nav link resolves like an HTML one.
+        const raw = (el.getAttribute('href') || el.getAttribute('xlink:href') || '').trim();
         if (!raw || raw.startsWith('#'))
             return null;
         try {
@@ -67,14 +69,18 @@ export function collectNavAffordances() {
     // Erring broad is correct here: a stray non-nav button is harmless noise, but a
     // MISSED nav item defeats the guard. Prefer semantic markup (role=tablist) for
     // fully reliable harvesting; see docs/inventory-guard.md.
-    const SEL = 'a[href], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], nav button, [role="navigation"] button, [role="tablist"] button, [class*="navtab" i] button, [class*="nav-tab" i] button, [class*="subnav" i] button, [class*="subtab" i] button, [class*="tabs" i] button';
+    // `a[*|href]` (any-namespace href) not `a[href]`: an SVG anchor may carry only the
+    // XLink-namespaced `xlink:href`, which `a[href]` never selects — so the xlink:href
+    // fallback in internalPath would be dead without it.
+    const SEL = 'a[*|href], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], nav button, [role="navigation"] button, [role="tablist"] button, [class*="navtab" i] button, [class*="nav-tab" i] button, [class*="subnav" i] button, [class*="subtab" i] button, [class*="tabs" i] button';
     return Array.from(document.querySelectorAll(SEL))
         .filter(visible)
         .map((el) => ({
         tag: el.tagName.toLowerCase(),
         role: (el.getAttribute('role') || '').toLowerCase(),
         name: nameOf(el),
-        internalPath: el.tagName === 'A' ? internalPath(el) : null,
+        // SVG anchors report tagName `a` (lowercase), HTML reports `A` — match either.
+        internalPath: el.tagName.toLowerCase() === 'a' ? internalPath(el) : null,
         testId: el.getAttribute('data-testid'),
         domId: el.getAttribute('id'),
         controls: el.getAttribute('aria-controls'),

package/dist/map-store.d.ts

@@ -48,7 +48,11 @@ export interface CachedCaptureDirs {
     tmpRoot: string;
 }
 /** Record the real browser build into the capture dir. Called from a capture run, where a
- *  Playwright browser handle is in scope. Best-effort: a missing version is simply not written. */
+ *  Playwright browser handle is in scope. Write-or-CLEAR semantics: an undefined version
+ *  REMOVES any existing sidecar rather than leaving it, so a reused capture dir (e.g. the
+ *  default `.styleproof/maps/current`) can never carry a PRIOR run's build into this run's
+ *  manifest — that would stamp a false browser-build fingerprint the compatibility guard
+ *  then trusts. Best-effort: the delete is forced and ignores a missing file. */
 export declare function writeBrowserBuildSidecar(dir: string, browserVersion: string | undefined): void;
 export declare function expectedCompatibilityKey(options?: {
     cwd?: string;

package/dist/map-store.js

@@ -80,12 +80,19 @@ function detectLockfile(cwd) {
     return {};
 }
 /** Record the real browser build into the capture dir. Called from a capture run, where a
- *  Playwright browser handle is in scope. Best-effort: a missing version is simply not written. */
+ *  Playwright browser handle is in scope. Write-or-CLEAR semantics: an undefined version
+ *  REMOVES any existing sidecar rather than leaving it, so a reused capture dir (e.g. the
+ *  default `.styleproof/maps/current`) can never carry a PRIOR run's build into this run's
+ *  manifest — that would stamp a false browser-build fingerprint the compatibility guard
+ *  then trusts. Best-effort: the delete is forced and ignores a missing file. */
 export function writeBrowserBuildSidecar(dir, browserVersion) {
-    if (!browserVersion)
+    const sidecar = path.join(dir, BROWSER_BUILD_SIDECAR);
+    if (!browserVersion) {
+        fs.rmSync(sidecar, { force: true });
         return;
+    }
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, BROWSER_BUILD_SIDECAR), JSON.stringify({ browserVersion }, null, 2));
+    fs.writeFileSync(sidecar, JSON.stringify({ browserVersion }, null, 2));
 }
 function readBrowserBuildSidecar(dir) {
     try {

package/dist/report.js

@@ -510,9 +510,26 @@ function regionHeading(regionPaths, findings) {
     const label = anchors.length > 1 ? `\`${head}\` + ${anchors.length - 1} more` : `\`${head}\``;
     return `${label} · ${groupTitle(findings)}`;
 }
+// CSS values are author/attacker-influenced (content:"…", url("…"), font-family
+// strings), so at the render boundary they get their OWN escaper — distinct from
+// safeKey, which strips control chars from surface keys. Values must stay READABLE
+// (a mangled url(…) is useless), so we ESCAPE rather than strip:
+//   • `|` → `\|`   — an unescaped pipe splits the table row (GitHub honours the
+//                     backslash even inside a code span).
+//   • backticks   — a bare backtick would close the code span and leak live
+//                     Markdown; widen the fence to one more backtick than the
+//                     value's longest run, padding a space when it touches an edge
+//                     (GitHub's rule for a code span that starts/ends with a tick).
+function codeValue(v) {
+    const escaped = v.replace(/\|/g, '\\|');
+    const longestRun = Math.max(0, ...(escaped.match(/`+/g) ?? []).map((r) => r.length));
+    const fence = '`'.repeat(longestRun + 1);
+    const pad = /^`|`$/.test(escaped) ? ' ' : '';
+    return `${fence}${pad}${escaped}${pad}${fence}`;
+}
 // A "no value here" marker renders as an em dash; colours render as `#hex` so the
 // table cell shows GitHub's live swatch.
-const cell = (v) => (isNonValue(v) ? '—' : `\`${toHex(v)}\``);
+const cell = (v) => (isNonValue(v) ? '—' : codeValue(toHex(v)));
 // Long values (gradients, data URIs) would swamp the table, but truncating each
 // side independently can show two IDENTICAL cells for a real diff: both
 // sides of a gradient rendered as the same rgba while the actual change — a
@@ -545,7 +562,7 @@ function cellPair(before, after) {
     if (isNonValue(before) || isNonValue(after))
         return [cell(before), cell(after)];
     const [b, a] = excerptPair(before, after);
-    return [`\`${toHex(b)}\``, `\`${toHex(a)}\``];
+    return [codeValue(toHex(b)), codeValue(toHex(a))];
 }
 function beforeAfterTable(rows) {
     return [
@@ -553,14 +570,14 @@ function beforeAfterTable(rows) {
         '| --- | --- | --- |',
         ...rows.map((r) => {
             const [b, a] = cellPair(r.before, r.after);
-            return `| \`${r.prop}\` | ${b} | ${a} |`;
+            return `| ${codeValue(r.prop)} | ${b} | ${a} |`;
         }),
     ];
 }
 // A brand-new element has no meaningful "before", so its resting style renders
 // value-only (the After column), mirroring the added-element interaction-states table.
 function valueTable(rows) {
-    return ['| Property | Value |', '| --- | --- |', ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.after)} |`)];
+    return ['| Property | Value |', '| --- | --- |', ...rows.map((r) => `| ${codeValue(r.prop)} | ${cell(r.after)} |`)];
 }
 /** `Button (variant=primary, size=sm)` — the React component + sanitized props
  *  the element captured (advisory; present only with captureComponent). */
@@ -587,8 +604,8 @@ function statesSection(states, added) {
         for (const c of summarizeProps(st.props)) {
             const [b, a] = cellPair(c.before, c.after);
             rows.push(added
-                ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
-                : `| \`:${st.state}\` | \`${c.prop}\` | ${b} → ${a} |`);
+                ? `| ${codeValue(`:${st.state}`)} | ${codeValue(c.prop)} | ${cell(c.after)} |`
+                : `| ${codeValue(`:${st.state}`)} | ${codeValue(c.prop)} | ${b} → ${a} |`);
         }
     if (!rows.length)
         return [];

package/dist/runner.d.ts

@@ -185,6 +185,23 @@ type ExpandedSurface = Omit<Surface, 'variants' | 'liveStates'> & {
     metadata?: CaptureMetadata;
 };
 export declare function expandSurfaceVariants(surface: Surface): ExpandedSurface[];
+/** The identity fields of an expanded surface a collision check needs. */
+type ExpandedKeyed = {
+    key: string;
+    metadata?: CaptureMetadata;
+};
+/**
+ * Fail LOUDLY on two expanded surfaces sharing a capture key.
+ *
+ * The expanded key is `surface.key-variant.key`, and that key is the map filename
+ * (`<key>@<width>.json.gz`) and the report identity — so it's public and can't
+ * change without breaking backward compatibility. But the `-` join is ambiguous:
+ * surface `a` + variant `b-c` and surface `a-b` + variant `c` both expand to
+ * `a-b-c`, and the second capture would silently overwrite the first, dropping a
+ * surface with no error. Rather than mangle the public key format, we assert
+ * uniqueness up front and name BOTH origins so the author can rename one.
+ */
+export declare function assertUniqueExpandedKeys(surfaces: ExpandedKeyed[]): void;
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
  * server. A long-lived stream can't round-trip through a HAR entry: recording

package/dist/runner.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
-import { coverageGaps, COVERAGE_LEDGER } from './coverage.js';
+import { coverageGaps, coverageKeys, translateExpected, COVERAGE_LEDGER, } from './coverage.js';
 import { writeBrowserBuildSidecar } from './map-store.js';
 import { detectViewportWidths } from './breakpoints.js';
 import { selectCrawlLinks, crawlCoverageError } from './crawl.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 {
@@ -210,6 +231,36 @@ export function expandSurfaceVariants(surface) {
         return [baseSurface, ...expandedVariants];
     return [...expandedVariants, ...liveStates.map((state) => expandOne(surface, state, 'live-state'))];
 }
+/** Human-readable origin of an expanded surface for a collision message. */
+function expandedOrigin(s) {
+    const surfaceKey = s.metadata?.surfaceKey ?? s.key;
+    const variantKey = s.metadata?.variantKey;
+    return variantKey ? `surface '${surfaceKey}' variant '${variantKey}'` : `surface '${surfaceKey}'`;
+}
+/**
+ * Fail LOUDLY on two expanded surfaces sharing a capture key.
+ *
+ * The expanded key is `surface.key-variant.key`, and that key is the map filename
+ * (`<key>@<width>.json.gz`) and the report identity — so it's public and can't
+ * change without breaking backward compatibility. But the `-` join is ambiguous:
+ * surface `a` + variant `b-c` and surface `a-b` + variant `c` both expand to
+ * `a-b-c`, and the second capture would silently overwrite the first, dropping a
+ * surface with no error. Rather than mangle the public key format, we assert
+ * uniqueness up front and name BOTH origins so the author can rename one.
+ */
+export function assertUniqueExpandedKeys(surfaces) {
+    const byKey = new Map();
+    for (const s of surfaces) {
+        const prior = byKey.get(s.key);
+        if (prior) {
+            throw new Error(`styleproof: capture key '${s.key}' is produced by two surfaces — ` +
+                `${expandedOrigin(prior)} collides with ${expandedOrigin(s)}. ` +
+                `Keys must expand uniquely (they name the map files and report entries); ` +
+                `rename one surface or variant.`);
+        }
+        byKey.set(s.key, s);
+    }
+}
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
  * server. A long-lived stream can't round-trip through a HAR entry: recording
@@ -278,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);
@@ -295,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 {
@@ -316,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;
+        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 popupId = `popup-${String(candidate.index + 1).padStart(2, '0')}`;
+        }
         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)
@@ -350,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).
@@ -459,7 +569,7 @@ function resolveSettings(c) {
  * `expected: null` records that the spec declared no registry, so a green can only
  * certify the captured surfaces. Runs on a capture run (dir set) only.
  */
-function writeCoverageLedgerTest(settings, dir, expected, exclude) {
+function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfaces) {
     test('styleproof coverage ledger', () => {
         const outDir = path.join(settings.baseDir, dir);
         fs.mkdirSync(outDir, { recursive: true });
@@ -470,7 +580,11 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude) {
             : settings.replayFrom
                 ? 'replayed'
                 : 'unproven';
-        const ledger = { version: 1, expected, exclude, determinism };
+        // Pre-translate the declared universe into the keys actually captured to disk, so
+        // the GATE (which reads expanded map filenames and can't see `surfaceKey` metadata)
+        // compares literally — a liveStates surface's `-loading`/`-loaded` splits satisfy it.
+        const ledgerExpected = expected == null ? null : translateExpected(expected, captureSurfaces);
+        const ledger = { version: 1, expected: ledgerExpected, exclude, determinism };
         fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
     });
 }
@@ -489,6 +603,7 @@ export function defineStyleMapCapture(options) {
     const { surfaces, expected, exclude = {}, dir } = options;
     const settings = resolveSettings(options);
     const captureSurfaces = surfaces.flatMap(expandSurfaceVariants);
+    assertUniqueExpandedKeys(captureSurfaces);
     // Coverage guard. Runs in the NORMAL test suite (NOT gated on a capture dir), so
     // a route added without a surface fails the app's own tests — long before, and
     // independent of, a capture run. This is the one gap captures can't catch: a
@@ -497,7 +612,10 @@ export function defineStyleMapCapture(options) {
     if (expected) {
         test.describe('styleproof coverage', () => {
             test('every expected surface is captured or explicitly excluded', () => {
-                const { uncovered, staleExclusions } = coverageGaps(captureSurfaces.map((s) => s.key), expected, exclude);
+                const { uncovered, staleExclusions } = coverageGaps(
+                // A liveStates surface is captured only as its `-loading`/`-loaded` splits;
+                // map each back to the declared base key so the split satisfies `expected`.
+                coverageKeys(captureSurfaces), expected, exclude);
                 expect(uncovered, `StyleProof coverage gap: ${uncovered.length} expected surface(s) are neither captured ` +
                     `nor excluded — add each to \`surfaces\`, or to \`exclude\` with a reason. ` +
                     `Missing: ${uncovered.join(', ')}`).toEqual([]);
@@ -509,7 +627,7 @@ export function defineStyleMapCapture(options) {
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         if (dir)
-            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude, captureSurfaces);
         if (dir)
             writeBrowserBuildTest(settings, dir);
         for (const surface of captureSurfaces) {
@@ -623,8 +741,13 @@ export function defineCrawlCapture(options) {
         // captures what the nav links to, and can't prove that's every route). With
         // `expected` the crawl reconciles the DISCOVERED link set against it below and the
         // ledger travels with the declared universe.
+        // The crawl applies the SAME variants/liveStates to every discovered link, so the
+        // expansion of a declared key is knowable up front (before discovery): expand each
+        // `expected` key with this crawl's variants/liveStates to get the keys captured to
+        // disk, so a liveStates crawl's ledger is pre-translated like the spec-driven one.
+        const ledgerSurfaces = (expected ?? []).flatMap((key) => expandSurfaceVariants({ key, go: async () => { }, variants, liveStates }));
         if (dir)
-            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude, ledgerSurfaces);
         if (dir)
             writeBrowserBuildTest(settings, dir);
         test('discover surfaces by crawling links, then capture each', async ({ page }) => {
@@ -654,6 +777,7 @@ export function defineCrawlCapture(options) {
                 liveStates,
                 popups,
             }));
+            assertUniqueExpandedKeys(captureSurfaces);
             // Budget the whole sweep up front: one test captures every surface, and
             // captureSurface no longer sets its own timeout, so size it to the work found.
             // With auto-width the band count isn't known until each surface renders, so

package/dist/variant-crawler.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { captureStyleMap } from './capture.js';
 import { diffStyleMaps } from './diff.js';
+import { DANGER_SOURCE } from './danger.js';
 function slug(value) {
     return (value
         .toLowerCase()
@@ -39,8 +40,11 @@ function liveKey(candidate) {
 function liveSelector(candidate) {
     return candidate.path;
 }
+// `dangerSource` is the shared destructive-label pattern (see {@link DANGER_SOURCE}),
+// passed in because this function is serialized into the browser and can't close over
+// a Node `RegExp`.
 // fallow-ignore-next-line complexity
-function collectCandidates() {
+function collectCandidates(dangerSource) {
     const controls = [
         '[aria-expanded]',
         '[aria-haspopup]',
@@ -53,7 +57,7 @@ function collectCandidates() {
         'select',
         'form',
     ].join(',');
-    const dangerous = /\b(delete|remove|destroy|logout|log out|sign out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect)\b/i;
+    const dangerous = new RegExp(dangerSource, 'i');
     const esc = (value) => CSS.escape(value);
     const quote = (value) => JSON.stringify(value);
     const visible = (el) => {
@@ -93,7 +97,15 @@ function collectCandidates() {
         return pathSelector(el);
     };
     const labelFor = (el) => {
-        const own = (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || '').trim();
+        // Include `title` so an icon-only control (no text, no aria-label) announcing
+        // itself via a native tooltip — `<button title="Delete">🗑</button>` — still
+        // yields a real label. Without it the label is "button", slipping past the
+        // destructive guard below that this harvester's clicks must respect.
+        const own = (el.getAttribute('aria-label') ||
+            el.getAttribute('name') ||
+            el.textContent ||
+            el.getAttribute('title') ||
+            '').trim();
         return own.replace(/\s+/g, ' ').slice(0, 80) || el.tagName.toLowerCase();
     };
     const reasonFor = (el) => {
@@ -144,7 +156,7 @@ function collectCandidates() {
     return out;
 }
 async function discoverCandidates(page) {
-    return page.evaluate(collectCandidates);
+    return page.evaluate(collectCandidates, DANGER_SOURCE);
 }
 async function perform(page, candidate) {
     const target = page.locator(candidate.selector).first();

package/package.json

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