styleproof 3.17.0 → 3.19.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-url.js

@@ -26,7 +26,12 @@ const DEFAULTS = {
     screenshots: true,
     crawl: false,
     // Exhaustive by default — these are safety backstops, not budgets.
-    maxDepth: 1000,
+    // maxDepth mirrors CRAWL_DEFAULTS.maxDepth (crawl-surfaces.ts): 16 is
+    // exhaustive for real UI — no human-navigable surface is 16 clicks from load.
+    // The cap exists to bound append-generator UIs (a composer that appends a
+    // fresh-identity node per click, which dedup can't terminate); a higher value
+    // would make it decorative. Raise with --max-depth for a genuinely deeper nest.
+    maxDepth: 16,
     maxActionsPerState: 100000,
     maxStates: 100000,
     resetStorage: true,

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

@@ -44,11 +44,15 @@ export type CrawledSurface = {
 };
 /** Did the crawl SEE everything the design styles? `missing` lists classes the
  *  page's own stylesheets select on that never appeared in any captured surface —
- *  dead CSS, or a state the crawl could not reach. Empty missing = full coverage. */
+ *  dead CSS, or a state the crawl could not reach. `unreadable` names stylesheets
+ *  the browser could not parse (cross-origin, no CORS): their class vocabulary is
+ *  invisible, so coverage cannot be PROVEN against them. Full coverage = empty
+ *  `missing` AND empty `unreadable`. */
 export type CrawlCoverage = {
     defined: number;
     rendered: number;
     missing: string[];
+    unreadable: string[];
 };
 export type CrawlReport = {
     surfaces: CrawledSurface[];

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();
@@ -249,12 +258,15 @@ function domShape() {
 /* c8 ignore stop */
 /** Runs in the browser: every class name the page's OWN stylesheets select on —
  *  the design's defined vocabulary, read from the parsed CSSOM (inline and
- *  same-origin sheets; unreadable cross-origin sheets are skipped). Coverage is
- *  checked against this, so "fully covered" means every class the design styles
- *  was seen rendered in at least one captured surface. */
+ *  same-origin sheets). Coverage is checked against this, so "fully covered" means
+ *  every class the design styles was seen rendered in at least one captured
+ *  surface. A cross-origin sheet the browser can't parse is NOT silently skipped:
+ *  its href is returned in `unreadable` so coverage names it as residue rather than
+ *  certifying completeness while blind to it. */
 /* c8 ignore start */
 function collectDefinedClasses() {
     const out = new Set();
+    const unreadable = [];
     const scan = (rules) => {
         if (!rules)
             return;
@@ -271,13 +283,13 @@ function collectDefinedClasses() {
     };
     for (const sheet of document.styleSheets) {
         try {
-            scan(sheet.cssRules);
+            scan(sheet.cssRules); // throws for a cross-origin sheet with no CORS
         }
         catch {
-            /* cross-origin sheet — not the design's own vocabulary */
+            unreadable.push(sheet.href ?? '<inline>');
         }
     }
-    return [...out];
+    return { classes: [...out], unreadable };
 }
 /* c8 ignore stop */
 /** Structural fingerprint of the page's CURRENT state. Dedup key for surfaces. */
@@ -681,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
@@ -842,16 +854,17 @@ async function discover(page, opts) {
     await gotoFresh(page, opts);
     // No widths given? Detect the page's real @media breakpoints (like the
     // one-shot path does) and sweep one width per band — automatically. Detection
-    // reads every stylesheet; if one is cross-origin/unreadable it falls back to
-    // the single default width rather than dying.
+    // reads every stylesheet and THROWS if one is cross-origin/unreadable: it never
+    // silently sweeps a single width, which would certify every other band
+    // unchanged without looking at it. Pin `--widths` for a cross-origin-CSS page.
     if (opts.widths.length === 0) {
-        const widths = await detectViewportWidths(page).catch(() => [1280]);
+        const widths = await detectViewportWidths(page);
         opts = { ...opts, widths };
         if ((widths[0] ?? 1280) !== 1280)
             await gotoFresh(page, opts); // re-pin discovery width BEFORE the base fingerprint
     }
     page.off('request', onRequest);
-    const defined = await page.evaluate(collectDefinedClasses).catch(() => []);
+    const { classes: defined, unreadable } = await page.evaluate(collectDefinedClasses);
     const fp = await fingerprint(page);
     const st = {
         seen: new Set([fp.sig]),
@@ -881,7 +894,7 @@ async function discover(page, opts) {
         skipped: counters.skipped,
         captured: st.captured,
         failed: st.failed,
-        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing },
+        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing, unreadable },
     };
 }
 /**

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,7 +62,51 @@ 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[];
+/**
+ * The reconciliation of a rendered nav (the crawl's discovered link keys) against a
+ * declared `expected` universe, both directions. Where the spec guard treats the
+ * hand-listed `surfaces` as what's captured, here the crawl's DISCOVERED links are —
+ * the nav is the route universe for a link-crawled SPA, so it is the source of truth.
+ *
+ * - `missing`: an `expected` key with no rendered link and no `exclude` entry — a
+ *   nav-regression (a route the app promised is no longer linked).
+ * - `unexpected`: a rendered link with no `expected` entry and no `exclude` entry — a
+ *   new route/view with no owner in the registry.
+ * - `staleExclusions`: an `exclude` key absent from BOTH `expected` and the rendered
+ *   set — a rotted opt-out.
+ *
+ * Unlike {@link CoverageGaps} (which permits captured-not-expected so a spec can
+ * tighten its registry over time), the crawl asserts BOTH directions strictly: the
+ * rendered link set is complete by construction, so an unowned link is a real gap.
+ * Pure and browser-free so it's unit-testable; {@link import('./runner.js')} wraps it
+ * in the crawl capture test, where the link set is finally known.
+ */
+export type CrawlCoverageGaps = {
+    /** Expected keys with no rendered link and no `exclude` — a nav regression. */
+    missing: string[];
+    /** Rendered link keys absent from `expected` and `exclude` — a route with no owner. */
+    unexpected: string[];
+    /** `exclude` keys in neither `expected` nor the rendered set — a rotted opt-out. */
+    staleExclusions: string[];
+};
+export declare function crawlCoverageGaps(discoveredKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CrawlCoverageGaps;
+/**
+ * Reconcile the crawled link set against `expected` (via {@link crawlCoverageGaps}) and
+ * render the failure message, or `null` when the nav reconciles. `from` names the crawl
+ * root in the message. Kept pure and out of the capture test so the wording is
+ * unit-testable and {@link defineCrawlCapture} just throws what this returns.
+ */
+export declare function crawlCoverageError(from: string, discoveredKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): string | null;