styleproof 3.18.0 → 3.19.0

package/dist/coverage.js

@@ -34,6 +34,60 @@ export function coverageGaps(capturedKeys, expected, exclude = {}) {
     const staleExclusions = Object.keys(exclude).filter((k) => !expectedSet.has(k));
     return { uncovered, staleExclusions };
 }
+/**
+ * Translate captured surface keys into the DECLARED keys they satisfy for coverage.
+ *
+ * `expected` is stated in base surface keys (`home`), but a surface with `liveStates`
+ * is captured ONLY as its split expansions (`home-loading`, `home-loaded`) — the bare
+ * base key is dropped by design (the base live state is fuzzy). Comparing the expanded
+ * keys literally against `expected` would report the declared `home` as uncovered on a
+ * fully-captured app. Each expansion still carries its originating `surfaceKey`, so the
+ * declared base key is exactly recoverable: a capture satisfies its own key AND its
+ * `surfaceKey`. This is precise (it maps only real expansions back to their real base),
+ * not a suffix heuristic — an unrelated `home-banner` never satisfies an uncaptured `home`.
+ */
+export function coverageKeys(captured) {
+    const keys = new Set();
+    for (const c of captured) {
+        keys.add(c.key);
+        if (c.metadata?.surfaceKey)
+            keys.add(c.metadata.surfaceKey);
+    }
+    return [...keys];
+}
+/**
+ * Rewrite a declared `expected` universe (base keys) into the keys that are actually
+ * captured to disk, so the GATE — which reads expanded map filenames (`home-loading`)
+ * and can't see each capture's `surfaceKey` metadata — can compare literally.
+ *
+ * A declared key `K` is replaced by its captured liveState expansions when `K` is NOT
+ * itself a captured key but expansions carrying `surfaceKey === K` exist. A directly
+ * captured `K` is kept; a genuinely uncaptured `K` is kept verbatim so the gate still
+ * flags it. This is the write-time half of {@link coverageKeys}: the ledger travels
+ * pre-translated, so `auditCoverage` needs no metadata at gate time.
+ */
+export function translateExpected(expected, captured) {
+    const capturedKeys = new Set();
+    const expansionsByBase = new Map();
+    for (const c of captured) {
+        capturedKeys.add(c.key);
+        const base = c.metadata?.surfaceKey;
+        if (base && base !== c.key) {
+            const list = expansionsByBase.get(base) ?? [];
+            list.push(c.key);
+            expansionsByBase.set(base, list);
+        }
+    }
+    const out = new Set();
+    for (const k of expected) {
+        if (capturedKeys.has(k) || !expansionsByBase.has(k))
+            out.add(k);
+        else
+            for (const exp of expansionsByBase.get(k))
+                out.add(exp);
+    }
+    return [...out];
+}
 // ── coverage provenance (the gate-level completeness assertion) ──────────────────
 // The guard above runs in the app's SUITE. That fails a build when the spec forgets a
 // route, but the GATE (styleproof-diff, reading captured maps) never learns whether

package/dist/crawl-surfaces.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { detectViewportWidths } from './breakpoints.js';
+import { DANGER_SOURCE } from './danger.js';
 // Exhaustive by default — these ceilings are safety backstops, not budgets.
 export const CRAWL_DEFAULTS = {
     height: 900,
@@ -44,11 +45,14 @@ function deriveKey(steps, used) {
     used.add(key);
     return key;
 }
-/** Runs in the browser: every visible, enabled, non-navigating control worth trying. */
+/** Runs in the browser: every visible, enabled, non-navigating control worth trying.
+ *  `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`. */
 /* c8 ignore start */ // fallow-ignore-next-line complexity
-function collectClickable() {
+function collectClickable(dangerSource) {
     const SEMANTIC = 'button,summary,[role="button"],[role="tab"],[role="menuitem"],[role="combobox"],select,form';
-    const DANGER = /\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\b/i;
+    const DANGER = new RegExp(dangerSource, 'i');
     const esc = (v) => CSS.escape(v);
     const quote = (v) => JSON.stringify(v);
     const visible = (el) => {
@@ -81,7 +85,12 @@ function collectClickable() {
         }
         return pathSelector(el);
     };
-    const labelFor = (el) => (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || '')
+    const labelFor = (el) => 
+    // `title` is included so an icon-only control (no text, no aria-label) that
+    // announces itself via a native tooltip — `<button title="Delete">🗑</button>` —
+    // still yields a meaningful label. Without it such a button labels as "button"
+    // and slips past the destructive guard below, which mapping must never click.
+    (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || el.getAttribute('title') || '')
         .replace(/\s+/g, ' ')
         .trim()
         .slice(0, 80) || el.tagName.toLowerCase();
@@ -684,7 +693,7 @@ function sweepWorkList(entry, all, opts, st, freshOnly = false, excludeIds = new
  *  in place — reaching that surface via a forward click is reliable, so its deep
  *  descendants are captured on the first visit instead of via a later reset. */
 async function sweepCandidatesHere(page, opts, entry, st, sink, freshOnly = false, excludeIds = new Set()) {
-    const all = await page.evaluate(collectClickable).catch(() => []);
+    const all = await page.evaluate(collectClickable, DANGER_SOURCE).catch(() => []);
     const work = sweepWorkList(entry, all, opts, st, freshOnly, excludeIds);
     // Controls present HERE — passed to each child's in-place descent as its
     // exclude set, so the descent skips this surface's mode-switchers/chrome and

package/dist/crawl.d.ts

@@ -49,6 +49,12 @@ export type SelectLinksOptions = {
  * multi-segment route (`/blog/post`) still keys as `blog-post`. Param names are
  * dropped (values carry the meaning); pass `key` to {@link selectCrawlLinks} when a
  * project needs a different scheme.
+ *
+ * Params are sorted by name before their values are joined, so the SAME logical
+ * route keys identically regardless of the order the nav happened to render its
+ * query string (`/?tab=a&x=b` and `/?x=b&tab=a` both → `a-b`). Without this the
+ * key flaps with render order and the coverage guard reports phantom
+ * nav-regressions / unowned routes for a route that never changed.
  */
 export declare function defaultLinkKey(url: URL): string;
 /**
@@ -56,8 +62,17 @@ export declare function defaultLinkKey(url: URL): string;
  *
  * Each href is classified by {@link toLink} (resolve against `base`, keep http(s)
  * same-origin, drop a bare in-page fragment of the crawl root, apply `match`); the
- * survivors are deduped by path+query. Order follows first appearance in `hrefs`, so
+ * survivors are deduped by path+query (trailing slash normalized — `/about` and
+ * `/about/` are one surface, not two). Order follows first appearance in `hrefs`, so
  * the capture order is the nav's order — stable across runs.
+ *
+ * Keys are then disambiguated: two GENUINELY different surfaces whose derived keys
+ * collide (e.g. `/a?tab=x` and `/b?tab=x` both → `x` under {@link defaultLinkKey})
+ * would otherwise both write `<key>@<width>.json.gz` and the second would silently
+ * overwrite the first — a captured surface vanishing without a trace. Instead the
+ * second gets a `-2` suffix (mirroring the surface crawler's `deriveKey`), so both
+ * survive as distinct maps. Trailing-slash duplicates never reach here — they're
+ * already deduped to one surface above — so this only fires on real collisions.
  */
 export declare function selectCrawlLinks(hrefs: Iterable<string | null | undefined>, opts: SelectLinksOptions): CrawlLink[];
 /**

package/dist/crawl.js

@@ -23,10 +23,19 @@
  * multi-segment route (`/blog/post`) still keys as `blog-post`. Param names are
  * dropped (values carry the meaning); pass `key` to {@link selectCrawlLinks} when a
  * project needs a different scheme.
+ *
+ * Params are sorted by name before their values are joined, so the SAME logical
+ * route keys identically regardless of the order the nav happened to render its
+ * query string (`/?tab=a&x=b` and `/?x=b&tab=a` both → `a-b`). Without this the
+ * key flaps with render order and the coverage guard reports phantom
+ * nav-regressions / unowned routes for a route that never changed.
  */
 export function defaultLinkKey(url) {
     const segs = url.pathname.split('/').filter(Boolean);
-    const values = [...url.searchParams].map(([, v]) => v).filter(Boolean);
+    const values = [...url.searchParams]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, v]) => v)
+        .filter(Boolean);
     const slug = [...segs, ...values]
         .join('-')
         .replace(/[^a-zA-Z0-9]+/g, '-')
@@ -70,30 +79,69 @@ function toLink(href, base, keyFor, match) {
     url.hash = ''; // navigate the surface, not a scroll anchor within it
     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.
+ * The navigable url the caller returns keeps its original form; only the SET
+ * membership test is normalized, so the first-seen href still wins.
+ */
+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;
+    return normPath + search;
+}
 /**
  * Turn a page's raw `<a href>` values into a deduped, keyed surface list.
  *
  * Each href is classified by {@link toLink} (resolve against `base`, keep http(s)
  * same-origin, drop a bare in-page fragment of the crawl root, apply `match`); the
- * survivors are deduped by path+query. Order follows first appearance in `hrefs`, so
+ * survivors are deduped by path+query (trailing slash normalized — `/about` and
+ * `/about/` are one surface, not two). Order follows first appearance in `hrefs`, so
  * the capture order is the nav's order — stable across runs.
+ *
+ * Keys are then disambiguated: two GENUINELY different surfaces whose derived keys
+ * collide (e.g. `/a?tab=x` and `/b?tab=x` both → `x` under {@link defaultLinkKey})
+ * would otherwise both write `<key>@<width>.json.gz` and the second would silently
+ * overwrite the first — a captured surface vanishing without a trace. Instead the
+ * second gets a `-2` suffix (mirroring the surface crawler's `deriveKey`), so both
+ * survive as distinct maps. Trailing-slash duplicates never reach here — they're
+ * already deduped to one surface above — so this only fires on real collisions.
  */
 export function selectCrawlLinks(hrefs, opts) {
     const base = new URL(opts.base);
     const keyFor = opts.key ?? defaultLinkKey;
     const seen = new Set();
+    const usedKeys = new Set();
     const out = [];
+    // Disambiguate a key against those already emitted, mirroring deriveKey: first
+    // wins bare, the next collider gets `-2`, `-3`, … — deterministic in nav order.
+    const uniqueKey = (key) => {
+        let k = key;
+        for (let i = 2; usedKeys.has(k); i++)
+            k = `${key}-${i}`;
+        usedKeys.add(k);
+        return k;
+    };
+    const push = (link) => {
+        out.push({ key: uniqueKey(link.key), url: link.url });
+    };
     if (opts.includeSelf) {
         const selfUrl = base.pathname + base.search;
-        seen.add(selfUrl);
-        out.push({ key: keyFor(base), url: selfUrl });
+        seen.add(dedupIdentity(selfUrl));
+        push({ key: keyFor(base), url: selfUrl });
     }
     for (const href of hrefs) {
         const link = href ? toLink(href, base, keyFor, opts.match) : null;
-        if (!link || seen.has(link.url))
+        if (!link)
+            continue;
+        const id = dedupIdentity(link.url);
+        if (seen.has(id))
             continue;
-        seen.add(link.url);
-        out.push(link);
+        seen.add(id);
+        push(link);
     }
     return out;
 }

package/dist/danger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The ONE destructive-action guard, shared by every surface-discovery crawler
+ * (the exhaustive surface crawler in `crawl-surfaces.ts` and the one-step variant
+ * harvester in `variant-crawler.ts`). Mapping must never mutate: a control whose
+ * label matches this pattern is recorded but never clicked.
+ *
+ * Kept as a plain string (not a `RegExp`) because both crawlers build their
+ * candidate list inside `page.evaluate` — the classifier function is serialized
+ * into the browser, so it cannot close over a `RegExp` from Node. The source is
+ * passed in as an argument and recompiled in the browser; this module is the
+ * single source of truth for what "destructive" means.
+ */
+export declare const DANGER_SOURCE = "\\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\\b";

package/dist/danger.js

@@ -0,0 +1,13 @@
+/**
+ * The ONE destructive-action guard, shared by every surface-discovery crawler
+ * (the exhaustive surface crawler in `crawl-surfaces.ts` and the one-step variant
+ * harvester in `variant-crawler.ts`). Mapping must never mutate: a control whose
+ * label matches this pattern is recorded but never clicked.
+ *
+ * Kept as a plain string (not a `RegExp`) because both crawlers build their
+ * candidate list inside `page.evaluate` — the classifier function is serialized
+ * into the browser, so it cannot close over a `RegExp` from Node. The source is
+ * passed in as an argument and recompiled in the browser; this module is the
+ * single source of truth for what "destructive" means.
+ */
+export const DANGER_SOURCE = '\\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\\b';

package/dist/diff.js

@@ -70,7 +70,9 @@ function dropLayoutEquivalentMarginProps(props, a, b) {
 }
 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';
@@ -210,6 +210,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
@@ -459,7 +489,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 +500,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 +523,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 +532,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 +547,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 +661,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 +697,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.19.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",