styleproof 3.18.0 → 3.20.0

package/dist/affected-surfaces.js

@@ -42,6 +42,15 @@ const GLOBAL_CSS = /(^|\})\s*(:root|html|body|\*)[\s,{]|@tailwind\b|@layer\s+bas
 const CSSJS_GLOBAL = /\b(createGlobalStyle|injectGlobal|globalStyle|globalCss|createGlobalTheme)\b/;
 // `:global(...)` escape hatch or cross-module composition pulls in outside scope.
 const MODULE_ESCAPES = /:global\b|\bcompose[sd]?\b[^;]*\bfrom\b/;
+// Sass `@use`/`@forward`/`@import` pull another sheet's members into a CSS-module
+// file. dependency-cruiser parses JS imports, not Sass loads, so the import graph
+// can't bound them — fail closed on any occurrence. `@import` covers both the Sass
+// partial load (`@import "vars"`, whose members — possibly global rules — merge in
+// exactly like `@use`) and the plain-CSS pass-through form (`@import url(x.css)`,
+// `@import "sheet.css"`): a CSS `@import` composes an external sheet whose selectors
+// are NOT hashed into the module's per-file scope, so it escapes the module too.
+// Either way the change is unbounded → 'all'. Only widen; never narrows a verdict.
+const SASS_LOAD = /@(?:use|forward|import)\b/;
 const isConfig = (f) => /(?:^|\/)(?:tailwind|postcss|theme|tokens?|panda|uno)\.config\.[cm]?[jt]s$/.test(f) ||
     /(?:^|\/)theme\.[cm]?[jt]s$/.test(f);
 const isStyleSheet = (f) => /\.(css|scss|sass|less|styl)$/.test(f);
@@ -71,9 +80,10 @@ export function classifyStyleChange(file, readFile) {
         return CSSJS_GLOBAL.test(src) ? 'all' : 'scope'; // .tsx: global CSS-in-JS or colocated scope
     if (isStyleSheet(file)) {
         if (isCssModule(file)) {
-            // Hashed per-file scope — but `:global`, cross-module `composes … from`, and
-            // genuinely global selectors (`:root`, `html`, `@font-face`, …) all escape it.
-            return MODULE_ESCAPES.test(src) || GLOBAL_CSS.test(src) ? 'all' : 'scope';
+            // Hashed per-file scope — but `:global`, cross-module `composes … from`,
+            // genuinely global selectors (`:root`, `html`, `@font-face`, …), and any
+            // `@use`/`@forward`/`@import` load (Sass partial or plain-CSS sheet) escape it.
+            return MODULE_ESCAPES.test(src) || GLOBAL_CSS.test(src) || SASS_LOAD.test(src) ? 'all' : 'scope';
         }
         return 'all'; // vanilla stylesheet: global class namespace, import graph can't bound it
     }
@@ -83,6 +93,26 @@ export function classifyStyleChange(file, readFile) {
 const DYNAMIC_IMPORT = /import\(\s*([^)]+?)\s*\)/g;
 const dirOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '');
 const isSource = (p) => !p.includes('node_modules');
+/**
+ * Canonicalize a repo-relative path so the same file spells the same regardless
+ * of source (a `surfaces` value, a `changedFiles` entry, or a graph edge). Two
+ * tools disagree on `./pages/Home.tsx` vs `pages/Home.tsx` vs `pages//Home.tsx`;
+ * without one spelling, a reverse-reachability hit can silently miss the surface
+ * whose entry key was spelled differently, dropping it from the affected set —
+ * an unsound skip. Byte-cheap and fs-free: strip a leading `./`, collapse `//`,
+ * and drop `.`/`..` segments as pure string math (no realpath, no resolution). */
+export function canonicalPath(p) {
+    const out = [];
+    for (const seg of p.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            out.pop();
+        else
+            out.push(seg);
+    }
+    return out.join('/');
+}
 function link(rev, to, from) {
     let s = rev.get(to);
     if (!s)
@@ -147,22 +177,19 @@ function normalizeDir(fromDir, prefix) {
     }
     return out.join('/');
 }
-/** True if any changed file is a style change that escapes its importers. */
-function anyGlobalStyleChange(changed, readFile) {
-    return changed.some((f) => (isStyleSheet(f) || isCode(f) || isConfig(f)) && classifyStyleChange(f, readFile) === 'all');
-}
 /**
  * Build the reverse-import adjacency (`imported → importers`) from the graph plus
  * recovered context-module edges. `'all'` when an unbounded dynamic import makes
- * the whole reachability untrustworthy.
+ * the whole reachability untrustworthy. Paths are already canonical; `read`
+ * resolves a canonical path back to the caller's spelling before reading.
  */
-function buildReverseGraph(input, files) {
+function buildReverseGraph(graph, files, read) {
     const rev = new Map();
-    for (const e of input.graph)
+    for (const e of graph)
         if (isSource(e.from) && isSource(e.to))
             link(rev, e.to, e.from);
     for (const f of files) {
-        const src = isCode(f) ? safeRead(input.readFile, f) : undefined;
+        const src = isCode(f) ? read(f) : undefined;
         if (src === undefined)
             continue;
         const extra = recoverContextEdges(f, src, files);
@@ -179,18 +206,45 @@ function buildReverseGraph(input, files) {
  * provably unaffected and may reuse their committed base map.
  */
 export function affectedSurfaces(input) {
-    const changed = [...input.changedFiles];
+    // Canonicalize every path (surfaces values, changedFiles, graph from/to, files)
+    // through one spelling up front, so a `./`-prefixed or `//`-collapsed path from
+    // one source can't silently miss a match against another source's spelling.
+    // `readFile` is keyed on the caller's ORIGINAL spellings, so wrap it to resolve
+    // a canonical path back to the original it came from before reading.
+    const changed = [...input.changedFiles].map((f) => canonicalPath(f));
     const files = [...input.files];
+    const canonFiles = files.map((f) => canonicalPath(f));
+    const originalByCanon = new Map();
+    files.forEach((orig, i) => originalByCanon.set(canonFiles[i], orig));
+    [...input.changedFiles].forEach((orig) => {
+        const c = canonicalPath(orig);
+        if (!originalByCanon.has(c))
+            originalByCanon.set(c, orig);
+    });
+    const surfaces = Object.fromEntries(Object.entries(input.surfaces).map(([k, f]) => [k, canonicalPath(f)]));
+    const graph = [...input.graph].map((e) => ({ ...e, from: canonicalPath(e.from), to: canonicalPath(e.to) }));
+    const read = (canon) => safeRead(input.readFile, originalByCanon.get(canon) ?? canon);
     // 1. A style change that escapes its importers forces a full re-capture.
-    if (anyGlobalStyleChange(changed, input.readFile))
+    if (changed.some((f) => isStyleOrCode(f) && classifyCanon(f, read) === 'all'))
         return 'all';
     // 2. Reverse reachability (+ recovered context edges; unbounded dynamic → all).
-    const rev = buildReverseGraph(input, files);
+    const rev = buildReverseGraph(graph, canonFiles, read);
     if (rev === 'all')
         return 'all';
-    // 3. Map each changed file to the surfaces that transitively import it. A file
-    //    the graph can't place (no importers, not a surface entry) → 'all'.
-    const entryToKey = new Map(Object.entries(input.surfaces).map(([k, f]) => [f, k]));
+    // 3. Map each changed file to the surfaces that transitively import it.
+    const entryToKey = new Map(Object.entries(surfaces).map(([k, f]) => [f, k]));
+    // A surface whose entry path appears in neither `files` nor any graph edge is
+    // unplaceable: reverse reachability can never route a change to it, so a genuine
+    // hit would be dropped silently. Same fail-closed rule as an unplaceable changed
+    // file → 'all'.
+    const placeable = new Set(canonFiles);
+    for (const e of graph) {
+        placeable.add(e.from);
+        placeable.add(e.to);
+    }
+    for (const f of Object.values(surfaces))
+        if (!placeable.has(f))
+            return 'all';
     const hit = new Set();
     for (const f of changed) {
         const reach = reverseReach(f, rev);
@@ -204,6 +258,18 @@ export function affectedSurfaces(input) {
     }
     return hit;
 }
+/** A changed file whose kind participates in style scope (stylesheet, code, or config). */
+const isStyleOrCode = (f) => isStyleSheet(f) || isCode(f) || isConfig(f);
+/** {@link classifyStyleChange} against a reader that returns `undefined` for a missing
+ *  file (rather than throwing), matching the reverse-graph reader shape. */
+function classifyCanon(file, read) {
+    return classifyStyleChange(file, (p) => {
+        const src = read(p);
+        if (src == null)
+            throw new Error('unreadable');
+        return src;
+    });
+}
 function reverseReach(file, rev) {
     const seen = new Set();
     const stack = [file];
@@ -218,3 +284,35 @@ function reverseReach(file, rev) {
     }
     return seen;
 }
+/**
+ * Render an {@link affectedSurfaces} verdict as human-readable lines a pre-push
+ * hook (or CI log) can print, so a reviewer can sanity-check the skip list before
+ * trusting it. Pure formatter — no I/O, no graph work.
+ *
+ * @param result       the value {@link affectedSurfaces} returned.
+ * @param allSurfaces  every declared surface key (e.g. `Object.keys(surfaces)`),
+ *                     so the helper can name what is *reused from base* — the ones
+ *                     the verdict skips — not just what re-captures.
+ * @param reason       optional one-line explanation for an `'all'` verdict (e.g.
+ *                     the classifying file, from {@link classifyStyleChange}). The
+ *                     library doesn't attach a reason to the sentinel, so pass it
+ *                     if the caller knows why; omitted, the `'all'` line stands alone.
+ */
+export function explainAffectedSurfaces(result, allSurfaces, reason) {
+    const all = [...allSurfaces].sort();
+    if (result === 'all') {
+        const why = reason ? ` — ${reason}` : '';
+        return [
+            `selective remap: OFF → re-capture all ${all.length} surface(s)${why}`,
+            ...all.map((k) => `  ↻ ${k} (re-capture)`),
+        ].join('\n');
+    }
+    const recapture = [...result].sort();
+    const hit = new Set(recapture);
+    const reused = all.filter((k) => !hit.has(k));
+    return [
+        `selective remap: ON → re-capture ${recapture.length}, reuse ${reused.length} from base`,
+        ...recapture.map((k) => `  ↻ ${k} (re-capture — a changed file reaches it)`),
+        ...reused.map((k) => `  ✓ ${k} (reuse base map — no changed file reaches it)`),
+    ].join('\n');
+}

package/dist/capture-url.d.ts

@@ -45,7 +45,7 @@ export type CaptureUrlOptions = {
      * discovered surface under a derived key. See {@link crawlAndCapture}.
      */
     crawl: boolean;
-    /** crawl: recursion depth into opened surfaces (default 3). */
+    /** crawl: recursion depth into opened surfaces (default 16). */
     maxDepth: number;
     /** crawl: fresh controls driven per state (default: unbounded — try them all). */
     maxActionsPerState: number;

package/dist/capture.js

@@ -727,33 +727,47 @@ export async function captureStyleMap(page, options = {}) {
     // nulls motion to 0s), then re-apply it before reading everything else.
     await freezeTag.evaluate((el) => el.remove());
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
-    await page.addStyleTag({ content: FREEZE_CSS });
-    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
-    dropVolatile(base.elements, volatile);
-    const overlays = (await page.evaluate(detectOverlayCandidates, { ignore })).filter((overlay) => base.elements[overlay.path]);
-    warnUntraversed(base.shadowHosts, base.sameOriginFrames);
-    mergeMotion(base.elements, motion.elements);
-    let states = {};
-    let statesSkipped = false;
-    if (captureStates) {
-        const forced = await captureForcedStates(page, ignore, maxInteractive, volatile);
-        states = forced.states;
-        statesSkipped = forced.skipped;
+    // Re-apply the freeze for the base + forced-state reads (both must see motion
+    // nulled). This tag is KEEP-a-handle: unlike the pre-motion tag above (which was
+    // explicitly removed), an un-tracked tag would accumulate on any page reused without
+    // a reload — a second capture on the same page (SPA go() that doesn't navigate,
+    // multi-surface reuse, the self-check's re-run) would then read this run's frozen
+    // motion (`none`/`0s`) as its baseline and report phantom drift. Remove it in a
+    // `finally` so throw paths (a settle timeout, a forced-state error) also leave the
+    // page clean, not just the happy path.
+    const refreezeTag = await page.addStyleTag({ content: FREEZE_CSS });
+    try {
+        const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
+        dropVolatile(base.elements, volatile);
+        const overlays = (await page.evaluate(detectOverlayCandidates, { ignore })).filter((overlay) => base.elements[overlay.path]);
+        warnUntraversed(base.shadowHosts, base.sameOriginFrames);
+        mergeMotion(base.elements, motion.elements);
+        let states = {};
+        let statesSkipped = false;
+        if (captureStates) {
+            const forced = await captureForcedStates(page, ignore, maxInteractive, volatile);
+            states = forced.states;
+            statesSkipped = forced.skipped;
+        }
+        const tokens = await page.evaluate(capturePageTokens);
+        const inventory = await harvestInventoryFor(page, options.inventory);
+        return {
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            defaults: base.defaults,
+            elements: base.elements,
+            states,
+            ...(statesSkipped ? { statesSkipped: true } : {}),
+            ...(volatile.length ? { volatile } : {}),
+            ...(liveCandidates.length ? { liveCandidates } : {}),
+            ...(overlays.length ? { overlays } : {}),
+            ...(Object.keys(tokens).length ? { tokens } : {}),
+            ...(inventory.length ? { inventory } : {}),
+        };
+    }
+    finally {
+        // Best-effort: the page may already be closing on a throw path.
+        await refreezeTag.evaluate((el) => el.remove()).catch(() => { });
     }
-    const tokens = await page.evaluate(capturePageTokens);
-    const inventory = await harvestInventoryFor(page, options.inventory);
-    return {
-        ...(options.metadata ? { metadata: options.metadata } : {}),
-        defaults: base.defaults,
-        elements: base.elements,
-        states,
-        ...(statesSkipped ? { statesSkipped: true } : {}),
-        ...(volatile.length ? { volatile } : {}),
-        ...(liveCandidates.length ? { liveCandidates } : {}),
-        ...(overlays.length ? { overlays } : {}),
-        ...(Object.keys(tokens).length ? { tokens } : {}),
-        ...(inventory.length ? { inventory } : {}),
-    };
 }
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */
 export function saveStyleMap(filePath, map) {

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/coverage.d.ts

@@ -34,6 +34,41 @@ export type CoverageGaps = {
  * dir), and it's exported so a consumer can assert coverage however it likes.
  */
 export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;
+/**
+ * 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 declare function coverageKeys(captured: Iterable<{
+    key: string;
+    metadata?: {
+        surfaceKey?: string;
+    };
+}>): string[];
+/**
+ * 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 declare function translateExpected(expected: readonly string[], captured: Iterable<{
+    key: string;
+    metadata?: {
+        surfaceKey?: string;
+    };
+}>): string[];
 /** Bundled next to the maps, so the completeness basis travels with the capture. */
 export declare const COVERAGE_LEDGER = "styleproof-coverage.json";
 /**

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,81 @@ 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. 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.
+ */
+function dedupIdentity(pathAndSearch) {
+    const q = pathAndSearch.indexOf('?');
+    const path = q === -1 ? pathAndSearch : pathAndSearch.slice(0, q);
+    const search = q === -1 ? '' : pathAndSearch.slice(q);
+    // `/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;
+}
 /**
  * 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';