styleproof 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [4.3.0] - 2026-07-13
+
+### Changed
+
+- **A removed surface now blocks (exit 1) instead of riding the exit-3 "only new
+  surfaces" path.** A surface captured only on the base side is a deleted route
+  or a dropped width — a reviewable change, printed as `✗ REMOVED surface` —
+  never an onboarding case the approve-all box waves through under a "new
+  surfaces" banner. Exit 3 now means only NEW (head-side-only) surfaces.
+- **Stale acknowledgements gate everywhere.** A stale `allowRemoved` entry in
+  `styleproof.inventory.json` now blocks like a stale data-residue
+  acknowledgement (and the Action's inventory hard-gate counts both), so a
+  ledger entry left behind cannot pre-acknowledge the next removal of that key.
+
+### Fixed
+
+- **Crawls never capture an off-origin redirect target.** A same-origin link
+  that 302s to another origin (SSO, `/out?url=…`) previously entered the map as
+  a surface — third-party, nondeterministic content. The CLI sweep now skips the
+  page loudly and continues; a spec-driven capture fails naming the surface; an
+  entry URL that redirects off-origin is a hard error.
+- **The gate now surfaces what it did NOT compare.** The diff prints (and
+  `--json` carries) the count of auto-detected volatile subtrees excluded from
+  the comparison, and warns when the forced-state layer was skipped on BOTH
+  sides — previously a head-side volatile region or a twice-skipped state layer
+  could hide a real change with zero trace in the output.
+- **A corrupt coverage ledger is a hard error (exit 2), not a silent disarm.**
+  Unparseable `styleproof-coverage.json` used to read as "no registry", quietly
+  turning the coverage, determinism, and residue gates into warnings at once.
+  The residue footer also no longer misattributes a ledger-less bundle to the
+  `dataResidue: "warn"` opt-out.
+- **The Action fails closed on unexpected diff exit codes.** A node crash, OOM
+  kill, or missing file (127/137/143/…) previously fell through to
+  `changed=false` — a green "No visual changes" status for a run that never
+  compared anything.
+- **Approval can no longer wave through certification failures.** The Action
+  gained a post-approval hard gate (like the inventory gate) for incomplete
+  coverage, unproven determinism, and armed data-residue failures — none of
+  which are restyles the approve-all checkbox should clear.
+- Stale `exclude` entries are printed with the coverage verdict, and "coverage
+  complete" now says "captured or explicitly excluded".
+
+## [4.2.0] - 2026-07-13
+
+### Changed
+
+- **`styleproof-capture --crawl` now follows same-origin nav links.** Every
+  page the site links to is crawled like the entry page, keyed by its route
+  (`about`, `pricing`, …), with class coverage aggregated across the pages that
+  share stylesheets. Previously the CLI crawl drove controls but silently
+  dropped links, so a multi-page site reported "1/1 surfaces, coverage ✓" while
+  losing every other page. `--no-follow-links` restores the entry-page-only
+  sweep.
+
+### Fixed
+
+- **A non-head checkout in CI is no longer stamped with the pull request's head
+  SHA.** `currentGitSha` now trusts `git rev-parse HEAD` and relabels only a
+  checkout of the synthetic `GITHUB_SHA` merge commit, so a base-branch capture
+  (the scaffolded cache-miss job) can never publish a base-tree map under the
+  head's store key — a store poisoning that made later restores diff
+  base-vs-base and report a false green. `pull_request_target` payloads are no
+  longer trusted for relabeling at all, and a malformed `STYLEPROOF_SHA`
+  override now errors instead of silently falling back.
+- **Annotation move-suppression now requires provable displacement.** A
+  cross-path annotation match may suppress its magenta boxes only when the
+  container where the two paths diverge gained or lost captured children, or
+  when the element slid into a vacated slot in its own container. This fixes
+  three truthfulness bugs at once: a size-changing duplicate restyle swap no
+  longer loses all visual proof, a sibling insertion into a uniform-shell list
+  (menus, navs) no longer re-boxes every unchanged displaced item, and an
+  independent removal + identical addition in different containers no longer
+  cancel each other's annotations to zero.
+- **`styleproof-diff` no longer misreports fresh ad-hoc captures as predating
+  the determinism ledger.** The unknown-basis warning now names the real cause:
+  ad-hoc `styleproof-capture` output records no ledger; spec-driven captures
+  self-check and do.
+
 ## [4.1.0] - 2026-07-12
 
 ### Fixed
@@ -21,6 +99,11 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   and published report links point to the immutable report commit.
 - **Certify-mode report comments now carry their source head marker**, so stale
   comments can be distinguished from the current PR head.
+- **Annotation reconciliation preserves duplicate additions, removals, and
+  forced-state changes.** Matching is one-to-one within a structural
+  neighborhood, and indistinguishable duplicate provenance is reported as a
+  deterministic unmatched occurrence rather than guessed. Ambiguous duplicate
+  restyle swaps retain visual proof on both sides.
 
 ## [4.0.2] - 2026-07-11
 

package/README.md

@@ -217,11 +217,15 @@ summary, and the exact property change folded under a toggle. A change too small
 to see at 1:1 (say a 2px icon tweak) also gets a magnified zoom crop, so a
 sub-pixel change can't slip past a reviewer.
 
-Annotation boxes reconcile exact-equivalent elements that moved to a different
-structural path. When an unkeyed sibling insertion shifts unchanged descendants,
-the clean comparison still shows the complete rendered result and the audit keeps
-every structural finding, but magenta boxes mark only unmatched additions,
-removals, and restyles instead of painting the displaced subtree as changed.
+Annotation boxes reconcile exact-equivalent elements one-to-one within a structural
+neighborhood. When an unkeyed sibling insertion shifts unchanged descendants, the
+clean comparison still shows the complete rendered result and the audit keeps every
+structural finding, but magenta boxes mark only unmatched additions, removals, and
+restyles instead of painting the displaced subtree as changed. Visually identical
+duplicates have no provable physical provenance, so the report marks a deterministic
+unmatched occurrence rather than claiming which duplicate moved. When duplicate
+restyles could also be explained as a swap, the report keeps both sides annotated
+because the captured data cannot prove a move.
 
 When one change appears both on an ordinary page and in an open popup, the report
 chooses a representative where the changed element is visibly exposed, then prefers
@@ -757,6 +761,8 @@ You watch one number as you implement: the diff starts large and shrinks toward
 
 A design is mostly _behind clicks_ — modals, drawers, popovers, tabs that don't exist in the DOM until you open them. A single capture sees only the landing state. `--crawl` maps the rest for you: point it at the URL and it drives every non-destructive control, keeps whatever opens a structurally new surface, and recurses into it — a modal's tabs, a drawer's sub-views, a popover's panels — capturing each under a derived key. No spec, no selectors, no hand-holding.
 
+It follows the nav too: every same-origin page the site links to is crawled the same way, keyed by its route (`about`, `pricing`, `blog-post`, …), with class coverage aggregated across the pages that share stylesheets. `--no-follow-links` keeps the sweep to the entry page's interactive surface only.
+
 ```bash
 styleproof-capture https://example.com --crawl --out design    # maps every reachable surface
 styleproof-diff design .styleproof/maps/current                # diff the whole surface vs your build
@@ -1007,7 +1013,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 - `styleproof-init` — scaffold the gate: the capture spec (inventory guard on; Next.js repos get route discovery + the coverage guard, others a crawl-by-default spec), a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, the cache-first report workflow, the approval workflow, and the pre-push publish hook. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
 - `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--crawl-base-url` plus repeated `--crawl-route` to run `styleproof-variants` before capture, `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
-- `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical); `1` on a reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an unacknowledged failing data endpoint under an armed `dataResidue: 'gate'`, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **manifest-less side** — since **v4**, a two-directory compare where a side ships maps but no `styleproof-manifest.json` is refused loudly, naming the bare side(s), because the same-environment guard can't be enforced without one; re-capture with current StyleProof; **and** a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new — **and** the no-args case where the cached base map can't be restored at all: no map-store remote, no cached bundle, nothing to compare. A "nothing was compared" outcome always exits `2`, never a soft `0` that would read as certified; the error names the two ways forward — run in CI where the base is restorable, or use the two-directory form); `3` when only new surfaces are present (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no maps at all (and hence no manifest), meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`. The human output **groups the same way the report does**: surfaces that changed identically collapse into one finding (with the per-surface count on its header), longhands fold into shorthands, and size/position-derived longhands fold behind a `(+N derived longhands)` count — so one real change reads as one entry, not dozens of raw lines. A change that rode the shared frame every view draws (a persistent nav/header/footer) is promoted to a "🧱 Global chrome change" callout up top. `--json` stays the complete, unchanged machine contract — every surface and every raw longhand — regardless of the human grouping.
+- `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical); `1` on a reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an unacknowledged failing data endpoint under an armed `dataResidue: 'gate'`, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **manifest-less side** — since **v4**, a two-directory compare where a side ships maps but no `styleproof-manifest.json` is refused loudly, naming the bare side(s), because the same-environment guard can't be enforced without one; re-capture with current StyleProof; **and** a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new — **and** the no-args case where the cached base map can't be restored at all: no map-store remote, no cached bundle, nothing to compare. A "nothing was compared" outcome always exits `2`, never a soft `0` that would read as certified; the error names the two ways forward — run in CI where the base is restorable, or use the two-directory form); `3` when only new surfaces are present — surfaces captured only on the **head** side (a surface present only on the **base** side is a **removed** surface, a reviewable change: exit `1`) — (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no maps at all (and hence no manifest), meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`. The human output **groups the same way the report does**: surfaces that changed identically collapse into one finding (with the per-surface count on its header), longhands fold into shorthands, and size/position-derived longhands fold behind a `(+N derived longhands)` count — so one real change reads as one entry, not dozens of raw lines. A change that rode the shared frame every view draws (a persistent nav/header/footer) is promoted to a "🧱 Global chrome change" callout up top. `--json` stays the complete, unchanged machine contract — every surface and every raw longhand — regardless of the human grouping.
 - `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports cached maps for the current commit against the inferred base; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).
 - `styleproof-capture` — one-shot capture of any URL (no spec): `styleproof-capture <url> --key <name> --out <dir>`, with `--widths` (omit to auto-detect `@media` bands), `--wait <selector>`, `--ignore <selector>`, `--no-screenshots`, and the crawler flags (`--crawl`, `--setup <file>`, `--require-full-coverage` → exit 4 on residue, `--until-covered`, `--workers <n>`, `--no-data-states`) described in [Match a design pixel-for-pixel](#match-a-design-pixel-for-pixel).
 - `styleproof-variants` — crawl a running app for one-step state variants and write `styleproof.variants.generated.json`. Pass `--base-url`, repeat `--route`, and use `--strict` when unresolved skipped/live candidates should fail automation.

package/bin/styleproof-capture.mjs

@@ -20,6 +20,7 @@ import { chromium } from '@playwright/test';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 import { UsageError, parseCaptureUrlArgs, runCaptureUrl, loadSetupSteps } from '../dist/capture-url.js';
 import { crawlAndCapture } from '../dist/crawl-surfaces.js';
+import { selectCrawlLinks, dedupIdentity } from '../dist/crawl.js';
 import { writeCaptureManifest } from '../dist/map-store.js';
 
 const COMMAND = 'styleproof-capture';
@@ -56,6 +57,9 @@ whole surface: --crawl
                     fulfilled with 500 → error render)
   --workers <n>     concurrent sweep workers (default 4); same surface set as a
                     serial crawl — pass 1 for byte-stable key attribution
+  --no-follow-links crawl the entry page's interactive surface only. By default
+                    every same-origin page the nav links to is crawled too,
+                    each keyed by its route (about, pricing, blog-post, ...)
   --until-covered   stop the crawl early the moment every stylesheet class has
                     been rendered — a coverage-oriented sweep for design mockups
   --max-depth <n>   throttle recursion depth (default: 16 — backstop for
@@ -95,61 +99,147 @@ try {
   throw e;
 }
 
+// Read the freshly-loaded page's same-origin nav links, keyed by route.
+async function harvestPageLinks(page, url) {
+  await page.goto(url, { waitUntil: 'load' });
+  const hrefs = await page.$$eval('a[href]', (els) => els.map((e) => e.getAttribute('href'))).catch(() => []);
+  return selectCrawlLinks(hrefs, { base: page.url() });
+}
+
+function printCoverage(cov, label) {
+  const unreadable = cov.unreadable ?? [];
+  if (unreadable.length > 0) {
+    console.log(
+      `⚠ coverage${label}: ${unreadable.length} stylesheet(s) unreadable — class coverage not provable against them ` +
+        `(cross-origin, no CORS; make them same-origin / CORS-readable, or pin --widths):\n    ${unreadable.join(' ')}`,
+    );
+  }
+  if (cov.missing.length === 0) {
+    if (unreadable.length === 0)
+      console.log(
+        `✓ coverage${label}: all ${cov.defined} stylesheet classes rendered in at least one captured surface`,
+      );
+  } else {
+    console.log(
+      `⚠ coverage${label}: ${cov.rendered}/${cov.defined} stylesheet classes rendered — ${cov.missing.length} never seen ` +
+        `(dead CSS, or a state the crawl could not reach):\n    ${cov.missing.join(' ')}`,
+    );
+  }
+}
+
+function pageCrawlOptions(browser, url, prefix, statesLeft) {
+  return {
+    url,
+    out: opts.out,
+    widths: opts.widths, // empty = auto-detect the page's real breakpoints
+    ignore: opts.ignore,
+    height: opts.height,
+    screenshots: opts.screenshots,
+    waitSelector: opts.waitSelector,
+    maxDepth: opts.maxDepth,
+    maxActionsPerState: opts.maxActionsPerState,
+    maxStates: statesLeft,
+    resetStorage: opts.resetStorage,
+    setup: setupSteps,
+    dataStates: opts.dataStates,
+    stopWhenCovered: opts.untilCovered,
+    workers: opts.workers,
+    keyPrefix: prefix,
+    // each worker page in its OWN context, so storage resets can't interfere
+    newPage: async () => (await browser.newContext()).newPage(),
+    // Stream each surface as it is captured, so progress is visible live and an
+    // interrupted run still shows exactly what it mapped.
+    onSurface: (s, ok) =>
+      console.log(`  ${'·'.repeat(s.depth)}${s.key} (${s.elements} elements)${ok ? '' : ' — CAPTURE FAILED'}`),
+  };
+}
+
+// Aggregate coverage: pages share stylesheets, so a class unrendered on one
+// page but rendered on another IS covered. defined = rendered ∪ missing.
+function aggregateCoverage(reports) {
+  const rendered = new Set(reports.flatMap((r) => r.coverage.renderedClasses));
+  const missing = [...new Set(reports.flatMap((r) => r.coverage.missing))].filter((c) => !rendered.has(c)).sort();
+  const unreadable = [...new Set(reports.flatMap((r) => r.coverage.unreadable ?? []))];
+  return { defined: rendered.size + missing.length, rendered: rendered.size, missing, unreadable };
+}
+
+function printCrawlSummary(reports) {
+  const surfaces = reports.reduce((n, r) => n + r.surfaces.length, 0);
+  const captured = reports.reduce((n, r) => n + r.captured, 0);
+  const tried = reports.reduce((n, r) => n + r.actionsTried, 0);
+  const skipped = reports.reduce((n, r) => n + r.skipped, 0);
+  const failed = reports.flatMap((r) => r.failed);
+  const widths = opts.widths.length ? `${opts.widths.length} width(s)` : 'auto widths';
+  console.log(
+    `✓ ${captured}/${surfaces} surface(s) across ${reports.length} page(s) × ${widths} → ${opts.out}  ` +
+      `(${tried} actions tried, ${skipped} skipped${failed.length ? `, ${failed.length} capture-failed` : ''})`,
+  );
+}
+
+// Enqueue every not-yet-seen page the just-crawled page links to, giving each a
+// unique route-key prefix ('base' is reserved for the entry crawl's root).
+function enqueueLinkedPages(links, sweep) {
+  for (const link of links) {
+    const id = dedupIdentity(link.url);
+    if (sweep.seenPages.has(id)) continue;
+    sweep.seenPages.add(id);
+    let prefix = link.key;
+    for (let i = 2; sweep.usedPrefixes.has(prefix); i++) prefix = `${link.key}-${i}`;
+    sweep.usedPrefixes.add(prefix);
+    sweep.queue.push({ url: new URL(link.url, sweep.entry).href, prefix });
+  }
+}
+
+// Crawl one page of the sweep. The entry page failing is a broken run (rethrow);
+// a LINKED page failing (e.g. an off-origin redirect) returns null after warning,
+// and the sweep continues.
+async function crawlPage(browser, page, url, prefix, statesLeft) {
+  try {
+    return await crawlAndCapture(page, pageCrawlOptions(browser, url, prefix, statesLeft));
+  } catch (e) {
+    if (prefix === '') throw e;
+    console.log(`⚠ ${url}: ${e instanceof Error ? e.message : String(e)} — page skipped`);
+    return null;
+  }
+}
+
 async function runCrawl() {
   const browser = await chromium.launch();
   try {
     const page = await browser.newPage();
-    const crawlOpts = {
-      url: opts.url,
-      out: opts.out,
-      widths: opts.widths, // empty = auto-detect the page's real breakpoints
-      ignore: opts.ignore,
-      height: opts.height,
-      screenshots: opts.screenshots,
-      waitSelector: opts.waitSelector,
-      maxDepth: opts.maxDepth,
-      maxActionsPerState: opts.maxActionsPerState,
-      maxStates: opts.maxStates,
-      resetStorage: opts.resetStorage,
-      setup: setupSteps,
-      dataStates: opts.dataStates,
-      stopWhenCovered: opts.untilCovered,
-      workers: opts.workers,
-      // each worker page in its OWN context, so storage resets can't interfere
-      newPage: async () => (await browser.newContext()).newPage(),
-      // Stream each surface as it is captured, so progress is visible live and an
-      // interrupted run still shows exactly what it mapped.
-      onSurface: (s, ok) =>
-        console.log(`  ${'·'.repeat(s.depth)}${s.key} (${s.elements} elements)${ok ? '' : ' — CAPTURE FAILED'}`),
+    // Page-level breadth-first sweep: crawl the entry page's whole interactive
+    // surface, then every same-origin page its nav links to (and theirs), each
+    // namespaced by its route key so a shared --out directory never collides.
+    const entry = new URL(opts.url);
+    const sweep = {
+      entry,
+      queue: [{ url: opts.url, prefix: '' }],
+      seenPages: new Set([dedupIdentity(entry.pathname + entry.search)]),
+      usedPrefixes: new Set(['base']), // 'base' is the entry crawl's root key
     };
-    const report = await crawlAndCapture(page, crawlOpts);
+    const reports = [];
+    let statesLeft = opts.maxStates;
+
+    while (sweep.queue.length > 0 && statesLeft > 0) {
+      const { url, prefix } = sweep.queue.shift();
+      const report = await crawlPage(browser, page, url, prefix, statesLeft);
+      if (!report) continue; // linked page skipped loudly (e.g. off-origin redirect)
+      reports.push(report);
+      statesLeft -= report.surfaces.length;
+      if (opts.followLinks) enqueueLinkedPages(await harvestPageLinks(page, url), sweep);
+    }
+    if (sweep.queue.length > 0)
+      console.log(`⚠ --max-states reached: ${sweep.queue.length} linked page(s) left uncrawled — raise --max-states`);
+
     // Stamp a manifest so a two-directory diff against this crawl output has the
     // same-environment guard on both sides (v4 refuses a manifest-less side).
     writeCaptureManifest({ dir: opts.out, screenshots: opts.screenshots });
-    console.log(
-      `✓ ${report.captured}/${report.surfaces.length} surface(s) × ${crawlOpts.widths.length} width(s) → ${opts.out}  ` +
-        `(${report.actionsTried} actions tried, ${report.skipped} skipped${report.failed.length ? `, ${report.failed.length} capture-failed` : ''})`,
-    );
-    const cov = report.coverage;
-    const unreadable = cov.unreadable ?? [];
-    if (unreadable.length > 0) {
-      console.log(
-        `⚠ coverage: ${unreadable.length} stylesheet(s) unreadable — class coverage not provable against them ` +
-          `(cross-origin, no CORS; make them same-origin / CORS-readable, or pin --widths):\n    ${unreadable.join(' ')}`,
-      );
-    }
-    if (cov.missing.length === 0) {
-      if (unreadable.length === 0)
-        console.log(`✓ coverage: all ${cov.defined} stylesheet classes rendered in at least one captured surface`);
-    } else {
-      console.log(
-        `⚠ coverage: ${cov.rendered}/${cov.defined} stylesheet classes rendered — ${cov.missing.length} never seen ` +
-          `(dead CSS, or a state the crawl could not reach):\n    ${cov.missing.join(' ')}`,
-      );
-    }
+    printCrawlSummary(reports);
+    const cov = aggregateCoverage(reports);
+    printCoverage(cov, reports.length > 1 ? ` (${reports.length} pages)` : '');
     // Residue under --require-full-coverage → exit 4: a never-seen class OR an
     // unreadable sheet (whose vocabulary can't be proven covered at all).
-    if (opts.requireFullCoverage && (cov.missing.length > 0 || unreadable.length > 0)) process.exit(4);
+    if (opts.requireFullCoverage && (cov.missing.length > 0 || cov.unreadable.length > 0)) process.exit(4);
   } finally {
     await browser.close();
   }

package/bin/styleproof-diff.mjs

@@ -20,7 +20,8 @@
  *
  * Custom properties (--*) are ignored: they are inputs, not outcomes (see
  * README). Exit code 0 = identical, 1 = reviewable differences, 2 = usage/capture
- * error, 3 = only new surfaces (present on one side, no baseline to diff against).
+ * error, 3 = only NEW surfaces (present only on the head side, no baseline to diff
+ * against). A REMOVED surface (present only on the base side) is a change: exit 1.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -109,12 +110,15 @@ function printInventoryAudit(audit) {
     );
   }
   for (const it of delta.added) console.log(`  + added: ${it.key} ("${it.label}")`);
-  for (const k of staleAllowances) console.log(`  ⚠ stale allowRemoved (key is not actually removed): ${k}`);
+  for (const k of staleAllowances)
+    console.log(`  ✗ stale allowRemoved (key is not actually removed): ${k} — prune it from styleproof.inventory.json`);
   if (unexplained.length)
     console.log(
       `  → ${unexplained.length} unacknowledged removal(s): restore the affordance, or record the decision in styleproof.inventory.json {"<key>":"<why>"}.`,
     );
-  return unexplained.length;
+  // A stale allowance BLOCKS like a stale residue acknowledgement: left in place it
+  // pre-acknowledges the NEXT removal of that key, so the ledger must not rot.
+  return unexplained.length + staleAllowances.length;
 }
 
 // ── data-residue guard (gate by default) ─────────────────────────────────────────
@@ -139,11 +143,11 @@ function loadAcknowledgedResidue() {
 // Audit the HEAD bundle's residue against the ack ledger, carrying whether the head
 // ledger armed the gate. Returns null when no captured map carried residue AND the
 // gate wasn't armed — so a clean healthy run prints/gates nothing (byte-identical).
-function readResidueAudit(dirB, armed) {
+function readResidueAudit(dirB, armed, hasLedger) {
   const headResidue = readResidue(dirB);
   if (!armed && !headResidue.some((m) => m.dataResidue?.length)) return null;
   const acknowledged = loadAcknowledgedResidue();
-  return { acknowledged, ...auditRunResidue(headResidue, acknowledged, armed) };
+  return { acknowledged, hasLedger, ...auditRunResidue(headResidue, acknowledged, armed) };
 }
 
 // Print the Data-residue section; return the count of UNACKNOWLEDGED failing endpoints
@@ -155,17 +159,20 @@ function residueLine(r, ackReason, armed) {
   return `  ${armed ? '✗ ' : '⚠ '}${r.surface} · ${r.endpoint} (${r.reason})${armed ? ', unacknowledged' : ''}`;
 }
 
-/** The action footer: the gate (default) names the remedy; warn mode is the opt-out. */
-function residueFooter(armed, unacknowledgedCount) {
+/** The action footer: the gate (default) names the remedy; warn mode is the opt-out.
+ *  A bundle with NO ledger at all is named as such — not misattributed to the opt-out. */
+function residueFooter(armed, unacknowledgedCount, hasLedger) {
   if (!unacknowledgedCount) return null;
-  return armed
-    ? `  → ${unacknowledgedCount} unacknowledged failing endpoint(s): fixture each (page.route / liveStates), acknowledge intentional ones in styleproof.data-residue.json {"<key>":"<why>"}, or opt down with \`dataResidue: "warn"\` in the capture spec.`
-    : '  → recorded and warned (dataResidue: "warn" — the opt-out). Remove it to restore the default gate that BLOCKS on these.';
+  if (armed)
+    return `  → ${unacknowledgedCount} unacknowledged failing endpoint(s): fixture each (page.route / liveStates), acknowledge intentional ones in styleproof.data-residue.json {"<key>":"<why>"}, or opt down with \`dataResidue: "warn"\` in the capture spec.`;
+  if (!hasLedger)
+    return '  → recorded and warned — the head bundle carries no coverage ledger (ad-hoc or pre-3.10 capture), so the residue gate cannot arm. A spec-driven capture records the ledger and gates by default.';
+  return '  → recorded and warned (dataResidue: "warn" — the opt-out). Remove it to restore the default gate that BLOCKS on these.';
 }
 
 function printResidueAudit(audit) {
   if (!audit) return 0;
-  const { residue, unacknowledged, staleAcknowledgements, armed } = audit;
+  const { residue, unacknowledged, staleAcknowledgements, armed, hasLedger } = audit;
   if (!residue.length && !staleAcknowledgements.length) {
     console.log('\n🩹 Data residue: no failing data-boundary request during capture');
     return 0;
@@ -174,7 +181,7 @@ function printResidueAudit(audit) {
   for (const r of residue) console.log(residueLine(r, audit.acknowledged[r.key], armed));
   for (const k of staleAcknowledgements)
     console.log(`  ⚠ stale acknowledgement (endpoint no longer failing/present): ${k}`);
-  const footer = residueFooter(armed, unacknowledged.length);
+  const footer = residueFooter(armed, unacknowledged.length, hasLedger);
   if (footer) console.log(footer);
   // Only an ARMED gate blocks; warn-mode surfaces without gating. A stale acknowledgement
   // always blocks when armed, so the ledger can't rot (mirrors the `exclude` guard).
@@ -204,14 +211,22 @@ function readLedger(dir) {
   try {
     return JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch {
-    return null; // a corrupt ledger reads as no registry → "not asserted", never a false green
+    // A ledger that EXISTS but cannot be parsed is tampering or truncation, and
+    // reading it as "no registry" would silently disarm the coverage,
+    // determinism, AND residue gates at once. Fail loud instead.
+    console.error(
+      `${COMMAND}: corrupt coverage ledger: ${p} — recapture the bundle; refusing to compare with disarmed gates.`,
+    );
+    process.exit(2);
   }
 }
 
 // Print the completeness verdict; return true if it BLOCKS (a registered surface is missing).
 function printCoverageVerdict(v) {
   if (v.basis === 'complete') {
-    console.log(`\n✓ coverage complete — all ${v.registrySize} registered surface(s) captured`);
+    console.log(`\n✓ coverage complete — all ${v.registrySize} registered surface(s) captured or explicitly excluded`);
+    for (const k of v.staleExclusions ?? [])
+      console.log(`  ⚠ stale exclude (not in the registry): ${k} — prune it from the spec`);
     return false;
   }
   if (v.basis === 'unasserted') {
@@ -238,7 +253,13 @@ function printDeterminismVerdict(v) {
     return false;
   }
   if (v.status === 'unknown') {
-    console.log('\n⚠ determinism basis unknown — a capture predates the determinism ledger; recapture to certify it.');
+    // No ledger at all = an ad-hoc `styleproof-capture` output (which doesn't
+    // self-check) or a pre-3.10 bundle; a spec capture records the basis.
+    console.log(
+      '\n⚠ determinism basis unknown — a side carries no determinism ledger (an ad-hoc styleproof-capture\n' +
+        '  output, or a capture from before the ledger existed). A spec-driven capture (styleproof-map)\n' +
+        '  self-checks and records it; ad-hoc captures are compared as-is.',
+    );
     return false;
   }
   console.log(
@@ -265,7 +286,8 @@ options:
   -h, --help       show this help
 
 exit: 0 identical (certified), 1 differences found, 2 usage/capture error,
-      3 only new surfaces (present on one side, no baseline to diff against).
+      3 only NEW surfaces (present only on the head side, no baseline to diff
+      against); a REMOVED surface (present only on the base side) exits 1
 `;
 
 const argv = process.argv.slice(2);
@@ -353,7 +375,7 @@ try {
   determinismVerdict = auditDeterminism(readLedger(dirA), headLedger);
   // Data-residue: the head bundle's failing data endpoints, gated only if its ledger
   // armed `dataResidue: 'gate'`. Same "read while the dirs exist" rule as the ledgers.
-  residueAudit = readResidueAudit(dirB, headLedger?.dataResidue === 'gate');
+  residueAudit = readResidueAudit(dirB, headLedger?.dataResidue === 'gate', headLedger != null);
   // Element-path sets per surface, for the shared-chrome tier — same "read while
   // the dirs exist" rule as the ledgers above.
   surfacePaths = surfaceElementPaths(dirA, dirB);
@@ -363,7 +385,7 @@ try {
 } finally {
   cleanupCachedCaptureDirs(cacheCapture);
 }
-const { surfaces, counts, compared } = result;
+const { surfaces, counts, compared, volatile, statesUncertified } = result;
 
 // ── grouped human output ─────────────────────────────────────────────────────
 // Reuse the report's dedup so one real change doesn't print once per surface with
@@ -404,11 +426,17 @@ function elementLines(findings) {
   return lines;
 }
 
-// New (one-sided) surfaces keep their own line, unchanged.
+// One-sided surfaces keep their own line. The two directions are NOT the same
+// verdict: only-in-after is a NEW surface (no baseline, review before
+// baselining); only-in-before is a REMOVED surface — a route or width that
+// existed and is gone, which is a change, never an onboarding case.
 for (const sd of surfaces) {
   if (!sd.missing) continue;
-  const side = sd.missing === 'before' ? 'after' : 'before';
-  console.log(`\n${sd.surface}: new surface — captured only in the ${side} set, no baseline to compare`);
+  console.log(
+    sd.missing === 'before'
+      ? `\n${sd.surface}: new surface — captured only in the after set, no baseline to compare`
+      : `\n${sd.surface}: ✗ REMOVED surface — captured only in the before set; the head no longer renders it`,
+  );
 }
 
 // Group the changed surfaces the way the report does, so an identical change
@@ -466,6 +494,13 @@ if (jsonOut) {
           counts,
           surfaces,
           compared,
+          // Subtrees excluded from every layer of the comparison because a side
+          // auto-detected them as volatile (still mutating at capture settle).
+          // Changes inside them are NOT certified by this diff.
+          volatileExcluded: volatile,
+          // Surfaces whose forced-state layer was skipped on BOTH sides — the
+          // :hover/:focus/:active layer compared {} vs {} and certifies nothing.
+          statesUncertified,
           coverage: coverageVerdict,
           determinism: determinismVerdict,
           // The inventory verdict, machine-readable — parallel to coverage/determinism and
@@ -508,26 +543,48 @@ if (jsonOut) {
 }
 
 const total = counts.dom + counts.style + counts.state;
-const newSurfaces = surfaces.filter((s) => s.missing).length;
+const newSurfaces = surfaces.filter((s) => s.missing === 'before').length;
+const removedSurfaces = surfaces.filter((s) => s.missing === 'after').length;
 // One SurfaceDiff per distinct surface across both sides (incl. missing-on-one-side).
 const surfaceCount = surfaces.length;
+if (volatile > 0)
+  console.log(
+    `\n⚠ ${volatile} auto-detected volatile subtree(s) excluded from the comparison (still mutating at capture\n` +
+      '  settle) — changes inside them are NOT certified. Fixture the region, or `ignore` it deliberately.',
+  );
+if (statesUncertified > 0)
+  console.log(
+    `\n⚠ forced-state layer uncertified on ${statesUncertified} surface(s): BOTH captures skipped it, so\n` +
+      '  :hover/:focus/:active differences there were never compared.',
+  );
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
-const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
+const removedNote = removedSurfaces ? ` + ${removedSurfaces} REMOVED surface(s)` : '';
+const invNote = invRemovals ? ` + ${invRemovals} inventory gate failure(s) (unacknowledged or stale)` : '';
 // residueFails counts unacknowledged failing endpoints AND stale acknowledgements (both gate).
 const resNote = residueFails ? ` + ${residueFails} data-residue gate failure(s) (unacknowledged or stale)` : '';
 const covNote = coverageFails ? ` + ${coverageVerdict.uncovered.length} uncaptured registered surface(s)` : '';
 const detNote = determinismFails ? ' + determinism unproven' : '';
-const clean = total === 0 && invRemovals === 0 && residueFails === 0 && !coverageFails && !determinismFails;
+const clean =
+  total === 0 &&
+  removedSurfaces === 0 &&
+  invRemovals === 0 &&
+  residueFails === 0 &&
+  !coverageFails &&
+  !determinismFails;
 console.log(
   clean
     ? newSurfaces === 0
       ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
       : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — review before baselining`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${resNote}${covNote}${detNote}`,
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${removedNote}${invNote}${resNote}${covNote}${detNote}`,
 );
-// 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals, an
-// unacknowledged failing data endpoint under an armed residue gate, an incomplete coverage
-// registry, or an unproven-determinism capture), 3 = only new surfaces (no baseline). 2 = usage.
+// 0 = identical, 1 = reviewable differences (incl. a REMOVED surface, inventory/residue gate
+// failures — unacknowledged or stale — an incomplete coverage registry, or an
+// unproven-determinism capture), 3 = ONLY new surfaces (no baseline). 2 = usage.
 process.exit(
-  total > 0 || invRemovals > 0 || residueFails > 0 || coverageFails || determinismFails ? 1 : newSurfaces > 0 ? 3 : 0,
+  total > 0 || removedSurfaces > 0 || invRemovals > 0 || residueFails > 0 || coverageFails || determinismFails
+    ? 1
+    : newSurfaces > 0
+      ? 3
+      : 0,
 );

package/dist/capture-url.d.ts

@@ -72,6 +72,9 @@ export type CaptureUrlOptions = {
     dataStates: boolean;
     /** crawl: concurrent sweep workers (default 4). 1 = byte-stable key attribution. */
     workers: number;
+    /** crawl: also crawl every same-origin page the nav links to (default true).
+     *  Off = the entry page's interactive surface only. */
+    followLinks: boolean;
 };
 /**
  * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI

package/dist/capture-url.js

@@ -40,6 +40,7 @@ const DEFAULTS = {
     untilCovered: false,
     dataStates: true,
     workers: 4,
+    followLinks: true,
 };
 function positiveNumber(raw, flag) {
     const n = Number(raw);
@@ -81,6 +82,8 @@ const BOOL_FLAGS = {
     '--until-covered': (o) => (o.untilCovered = true),
     '--data-states': (o) => (o.dataStates = true),
     '--no-data-states': (o) => (o.dataStates = false),
+    '--follow-links': (o) => (o.followLinks = true),
+    '--no-follow-links': (o) => (o.followLinks = false),
 };
 // Apply one argv token to the accumulator; returns the index to resume from
 // (advanced past a consumed `--flag value` pair). Flat early-returns so the
@@ -131,6 +134,7 @@ export function parseCaptureUrlArgs(argv) {
         setupFile: undefined,
         dataStates: DEFAULTS.dataStates,
         workers: DEFAULTS.workers,
+        followLinks: DEFAULTS.followLinks,
     };
     const positional = [];
     for (let i = 0; i < argv.length; i++)

package/dist/crawl-surfaces.d.ts

@@ -53,6 +53,9 @@ export type CrawlCoverage = {
     rendered: number;
     missing: string[];
     unreadable: string[];
+    /** The class names that WERE rendered — so a multi-page caller can aggregate
+     *  coverage across crawls sharing stylesheets (defined = rendered ∪ missing). */
+    renderedClasses: string[];
 };
 export type CrawlReport = {
     surfaces: CrawledSurface[];
@@ -122,6 +125,9 @@ export type SurfaceCrawlOptions = {
     /** Factory for worker pages — create each in its OWN browser context so
      *  storage resets cannot interfere across concurrent sweeps. */
     newPage?: () => Promise<Page>;
+    /** Namespace for every derived surface key (multi-page sweeps): the root
+     *  surface keys as the prefix itself, sub-states as `<prefix>-<label>`. */
+    keyPrefix?: string;
 };
 export declare const CRAWL_DEFAULTS: {
     height: number;

package/dist/crawl-surfaces.js

@@ -37,8 +37,12 @@ function pathAndSearch(url) {
         return url;
     }
 }
-function deriveKey(steps, used) {
-    const base = steps.length === 0 ? 'base' : slug(steps[steps.length - 1].label);
+function deriveKey(steps, used, prefix = '') {
+    const bare = steps.length === 0 ? 'base' : slug(steps[steps.length - 1].label);
+    // A prefixed crawl (one page of a multi-page sweep) keys its root surface as
+    // the prefix itself and namespaces every sub-state under it, so two pages'
+    // surfaces can never overwrite each other in a shared --out directory.
+    const base = prefix === '' ? bare : bare === 'base' ? prefix : `${prefix}-${bare}`;
     let key = base;
     for (let i = 2; used.has(key); i++)
         key = `${base}-${i}`;
@@ -404,6 +408,14 @@ async function scrollReveal(page) {
 async function gotoFresh(page, opts) {
     await page.setViewportSize({ width: opts.widths[0] ?? 1280, height: opts.height });
     await page.goto(opts.url, { waitUntil: 'load' });
+    // A same-origin URL can still 302 off-origin (SSO, /out?url=…). External
+    // content is nondeterministic and never belongs in a map — abort the crawl of
+    // this page rather than capture a third-party render as if it were the app.
+    const wanted = URL.canParse(opts.url) ? new URL(opts.url).origin : null; // relative url → origin unknowable
+    const landed = new URL(page.url()).origin;
+    if (wanted && landed !== wanted) {
+        throw new Error(`styleproof crawl: ${opts.url} redirected off-origin to ${landed} — external content is never captured`);
+    }
     // Tolerant wait: the generic settle below is the real readiness signal; an
     // optional waitSelector just accelerates it and must not fail the crawl.
     const ready = opts.waitSelector ? page.locator(opts.waitSelector).first() : null;
@@ -500,7 +512,7 @@ function stateKey(steps) {
 /** Record a newly-found surface, capture it in place (page is already there), and
  *  queue it for its own sweep. Streams progress via onSurface. */
 async function record(page, opts, newPath, depth, fp, st, sink, retryOnly = false, viaRetry = false) {
-    const key = deriveKey(newPath, st.used);
+    const key = deriveKey(newPath, st.used, opts.keyPrefix ?? '');
     const surface = { key, depth, path: newPath, elements: fp.elements };
     st.surfaces.push(surface);
     let addsVocab = false;
@@ -753,7 +765,7 @@ async function recordDataState(page, opts, mode, st) {
         st.seen.add(fp.sig);
         for (const c of fp.classes)
             st.classes.add(c);
-        const key = deriveKey([{ action: 'click', selector: `(data:${mode})`, label: mode, reason: 'data-state' }], st.used);
+        const key = deriveKey([{ action: 'click', selector: `(data:${mode})`, label: mode, reason: 'data-state' }], st.used, opts.keyPrefix ?? '');
         const surface = { key, depth: 0, path: [], elements: fp.elements };
         st.surfaces.push(surface);
         await captureAndReport(page, opts, surface, st);
@@ -894,7 +906,13 @@ async function discover(page, opts) {
         skipped: counters.skipped,
         captured: st.captured,
         failed: st.failed,
-        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing, unreadable },
+        coverage: {
+            defined: defined.length,
+            rendered: defined.length - missing.length,
+            missing,
+            unreadable,
+            renderedClasses: defined.filter((c) => st.classes.has(c)).sort(),
+        },
     };
 }
 /**

package/dist/crawl.d.ts

@@ -57,6 +57,23 @@ export type SelectLinksOptions = {
  * nav-regressions / unowned routes for a route that never changed.
  */
 export declare function defaultLinkKey(url: URL): string;
+/**
+ * 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.
+ */
+export declare function dedupIdentity(pathAndSearch: string): string;
 /**
  * Turn a page's raw `<a href>` values into a deduped, keyed surface list.
  *

package/dist/crawl.js

@@ -95,7 +95,7 @@ function toLink(href, base, keyFor, match) {
  * 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) {
+export function dedupIdentity(pathAndSearch) {
     const q = pathAndSearch.indexOf('?');
     const path = q === -1 ? pathAndSearch : pathAndSearch.slice(0, q);
     const search = q === -1 ? '' : pathAndSearch.slice(q);

package/dist/diff.d.ts

@@ -87,6 +87,7 @@ export declare function diffStyleMapDirs(dirA: string, dirB: string): {
     surfaces: SurfaceDiff[];
     counts: DiffCounts;
     volatile: number;
+    statesUncertified: number;
     compared: number;
 };
 export declare function diffContentMaps(a: StyleMap, b: StyleMap): ContentChange[];

package/dist/diff.js

@@ -281,7 +281,7 @@ export function diffStyleMapDirs(dirA, dirB) {
         throw new MissingHeadMapError();
     const surfaces = [];
     const counts = { dom: 0, style: 0, state: 0 };
-    let volatile = 0;
+    const uncompared = { volatile: 0, statesUncertified: 0 };
     for (const surface of names) {
         if (!indexA[surface] || !indexB[surface]) {
             // A surface present on only one side has no baseline to diff against — it's
@@ -291,15 +291,22 @@ export function diffStyleMapDirs(dirA, dirB) {
             surfaces.push({ surface, missing: indexA[surface] ? 'after' : 'before', findings: [] });
             continue;
         }
-        const mapA = loadStyleMap(indexA[surface]);
-        const mapB = loadStyleMap(indexB[surface]);
-        volatile += new Set([...(mapA.volatile ?? []), ...(mapB.volatile ?? [])]).size;
-        const findings = diffStyleMaps(mapA, mapB);
+        const findings = diffSurfacePair(indexA[surface], indexB[surface], uncompared);
         tallyCounts(findings, counts);
         if (findings.length)
             surfaces.push({ surface, findings });
     }
-    return { surfaces, counts, volatile, compared: names.length };
+    return { surfaces, counts, ...uncompared, compared: names.length };
+}
+/** Diff one paired surface, tallying what was NOT compared (volatile subtrees;
+ *  a forced-state layer skipped on BOTH sides — {} vs {} certifies nothing). */
+function diffSurfacePair(fileA, fileB, uncompared) {
+    const mapA = loadStyleMap(fileA);
+    const mapB = loadStyleMap(fileB);
+    uncompared.volatile += new Set([...(mapA.volatile ?? []), ...(mapB.volatile ?? [])]).size;
+    if (mapA.statesSkipped && mapB.statesSkipped)
+        uncompared.statesUncertified++;
+    return diffStyleMaps(mapA, mapB);
 }
 /**
  * Diff the OPT-IN content layer: elements whose own rendered text changed.

package/dist/map-store.js

@@ -140,8 +140,11 @@ export function expectedCompatibilityKey(options = {}) {
 }
 export function currentGitSha(cwd = process.cwd(), env = process.env) {
     const fromEvent = (() => {
-        if (!env.GITHUB_EVENT_PATH ||
-            !['pull_request', 'pull_request_target', 'workflow_run'].includes(env.GITHUB_EVENT_NAME ?? '')) {
+        // pull_request_target is deliberately absent: there GITHUB_SHA *is* the base
+        // tip, so its default checkout would be relabeled to the fork's (attacker-
+        // chosen) head. A pull_request_target job that really checks out the head
+        // gets the right SHA from `git rev-parse HEAD` with no relabel needed.
+        if (!env.GITHUB_EVENT_PATH || !['pull_request', 'workflow_run'].includes(env.GITHUB_EVENT_NAME ?? '')) {
             return undefined;
         }
         try {
@@ -152,16 +155,31 @@ export function currentGitSha(cwd = process.cwd(), env = process.env) {
             return undefined;
         }
     })();
-    // STYLEPROOF_SHA/GITHUB_HEAD_SHA are explicit overrides. On a pull_request
-    // run, GITHUB_SHA is the synthetic merge commit, so consult the trusted event
-    // payload before falling back to it.
-    const fromEnv = env.STYLEPROOF_SHA || env.GITHUB_HEAD_SHA || fromEvent || env.GITHUB_SHA;
-    if (fromEnv && /^[0-9a-f]{7,40}$/i.test(fromEnv))
-        return fromEnv;
-    const sha = gitOutput(cwd, ['rev-parse', 'HEAD']);
-    if (!sha)
-        throw new MapStoreError('must run inside a git repository, or pass --sha <commit>');
-    return sha;
+    // STYLEPROOF_SHA/GITHUB_HEAD_SHA are explicit overrides: they always win, and
+    // a malformed value errors instead of silently falling through to a wrong label.
+    const explicit = env.STYLEPROOF_SHA || env.GITHUB_HEAD_SHA;
+    if (explicit) {
+        if (!/^[0-9a-f]{7,40}$/i.test(explicit)) {
+            throw new MapStoreError(`STYLEPROOF_SHA/GITHUB_HEAD_SHA is not a commit SHA: ${explicit}`);
+        }
+        return explicit;
+    }
+    const head = gitOutput(cwd, ['rev-parse', 'HEAD']);
+    if (head) {
+        // The checked-out tree is the truth. The one exception: a checkout of the
+        // synthetic GITHUB_SHA commit (pull_request merge commit / workflow_run
+        // default tip) is labeled with the event's real head, because nothing ever
+        // restores by the synthetic SHA. A checkout of anything else — e.g. the
+        // base branch in a cache-miss job — keeps its own SHA, so a base-tree map
+        // is never published under the head's store key (a false-green poisoning).
+        if (fromEvent && head === env.GITHUB_SHA)
+            return fromEvent;
+        return head;
+    }
+    const fallback = fromEvent ?? env.GITHUB_SHA;
+    if (fallback && /^[0-9a-f]{7,40}$/i.test(fallback))
+        return fallback;
+    throw new MapStoreError('must run inside a git repository, or pass --sha <commit>');
 }
 export function refSha(ref, cwd = process.cwd()) {
     const sha = gitOutput(cwd, ['rev-parse', `${ref}^{commit}`]);

package/dist/report.js

@@ -48,47 +48,172 @@ function outermost(paths) {
 function innermost(paths) {
     return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(p + ' > ')));
 }
-function annotationIdentity(entry) {
+function sortedProperties(props) {
+    return Object.entries(props).sort(([left], [right]) => left.localeCompare(right, 'en'));
+}
+function restingAnnotationIdentity(entry) {
+    if (!entry)
+        return null;
     const sortedPseudo = Object.fromEntries(Object.entries(entry.pseudo ?? {})
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([pseudo, properties]) => [
-        pseudo,
-        Object.entries(properties).sort(([left], [right]) => left.localeCompare(right)),
-    ]));
-    return JSON.stringify([
+        .sort(([left], [right]) => left.localeCompare(right, 'en'))
+        .map(([pseudo, properties]) => [pseudo, sortedProperties(properties)]));
+    return [
         entry.tag,
         entry.cls,
         entry.rect?.[2] ?? null,
         entry.rect?.[3] ?? null,
-        Object.entries(entry.style).sort(([left], [right]) => left.localeCompare(right)),
+        sortedProperties(entry.style),
         sortedPseudo,
+    ];
+}
+function normalizeStructuralPath(elementPath) {
+    return elementPath.replace(/:nth-(?:child|of-type)\(\d+\)/g, (selector) => selector.replace(/\d+/, '*'));
+}
+function annotationScope(elementPath) {
+    const parentSeparator = elementPath.lastIndexOf(' > ');
+    return normalizeStructuralPath(parentSeparator === -1 ? '' : elementPath.slice(0, parentSeparator));
+}
+function relativeStateTarget(ownerPath, targetPath) {
+    if (targetPath === ownerPath)
+        return '';
+    const ownerPseudoPrefix = `${ownerPath}::`;
+    if (targetPath.startsWith(ownerPseudoPrefix))
+        return targetPath.slice(ownerPath.length);
+    const descendantPrefix = `${ownerPath} > `;
+    const relativePath = targetPath.startsWith(descendantPrefix) ? targetPath.slice(descendantPrefix.length) : targetPath;
+    return normalizeStructuralPath(relativePath);
+}
+function canonicalForcedStates(map, ownerPath) {
+    return Object.entries(map.states?.[ownerPath] ?? {})
+        .sort(([left], [right]) => left.localeCompare(right, 'en'))
+        .map(([stateName, deltas]) => [
+        stateName,
+        Object.entries(deltas)
+            .map(([targetPath, properties]) => [
+            relativeStateTarget(ownerPath, targetPath),
+            restingAnnotationIdentity(map.elements[targetPath]),
+            sortedProperties(properties),
+        ])
+            .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right), 'en')),
     ]);
 }
+function annotationIdentity(map, elementPath, entry) {
+    return JSON.stringify([restingAnnotationIdentity(entry), canonicalForcedStates(map, elementPath)]);
+}
+function sortedAnnotationPaths(paths) {
+    return [...paths].sort((left, right) => left.localeCompare(right, 'en', { numeric: true }));
+}
 function indexAnnotationIdentities(map) {
     const pathsByIdentity = new Map();
     for (const [elementPath, entry] of Object.entries(map.elements)) {
-        const identity = annotationIdentity(entry);
+        const identity = annotationIdentity(map, elementPath, entry);
         pathsByIdentity.set(identity, [...(pathsByIdentity.get(identity) ?? []), elementPath]);
     }
     return pathsByIdentity;
 }
-function hasEquivalentEntryAtAnotherPath(elementPath, entry, samePathsByIdentity, otherPathsByIdentity) {
-    if (!entry)
+function pathsByAnnotationScope(paths) {
+    const pathsByScope = new Map();
+    for (const elementPath of paths) {
+        const scope = annotationScope(elementPath);
+        pathsByScope.set(scope, [...(pathsByScope.get(scope) ?? []), elementPath]);
+    }
+    for (const scopedPaths of pathsByScope.values())
+        scopedPaths.sort((left, right) => left.localeCompare(right, 'en', { numeric: true }));
+    return pathsByScope;
+}
+/** Captured children per concrete container path, for the displacement proof. */
+function containerChildCounts(map) {
+    const counts = new Map();
+    for (const elementPath of Object.keys(map.elements)) {
+        const separator = elementPath.lastIndexOf(' > ');
+        const container = separator === -1 ? '' : elementPath.slice(0, separator);
+        counts.set(container, (counts.get(container) ?? 0) + 1);
+    }
+    return counts;
+}
+/** The concrete container where two element paths diverge (never the leaf itself). */
+function deepestCommonContainer(beforePath, afterPath) {
+    const beforeSegments = beforePath.split(' > ');
+    const afterSegments = afterPath.split(' > ');
+    const shared = [];
+    const limit = Math.min(beforeSegments.length, afterSegments.length) - 1;
+    for (let i = 0; i < limit && beforeSegments[i] === afterSegments[i]; i++)
+        shared.push(beforeSegments[i]);
+    return shared.join(' > ');
+}
+function containerOf(elementPath) {
+    const separator = elementPath.lastIndexOf(' > ');
+    return separator === -1 ? '' : elementPath.slice(0, separator);
+}
+/**
+ * A cross-path match is a MOVE claim, and a matched pair's annotations are
+ * suppressed — so the move must be PROVABLE from the captured data, one of:
+ *
+ * - the container where the two paths diverge gained or lost captured children
+ *   (a sibling insertion/removal displaced everything after it), or
+ * - a same-container slide into a vacated slot: the source slot emptied and the
+ *   destination slot is new. That is displacement by an UNCAPTURED sibling — an
+ *   injected `<style>`/`<script>` shifts `nth-child` without entering the census.
+ *
+ * A pair with neither proof — a style swap between siblings, a pure reorder of
+ * occupied slots, or a coincidental twin in a cousin container — stays
+ * annotated, because the data cannot prove nothing changed there.
+ */
+function canReconcileAnnotationPair(beforeMap, afterMap, beforeCounts, afterCounts, beforePath, afterPath, remainingAfter) {
+    if (!remainingAfter.has(afterPath))
         return false;
-    const identity = annotationIdentity(entry);
-    const samePaths = samePathsByIdentity.get(identity) ?? [];
-    const otherPaths = otherPathsByIdentity.get(identity) ?? [];
-    // Reconcile only an unambiguous one-to-one move. If an identity is duplicated
-    // on either side, an arbitrary cross-path match can hide a real restyle or an
-    // inserted/removed sibling from the annotated proof.
-    return samePaths.length === 1 && otherPaths.length === 1 && otherPaths[0] !== elementPath;
-}
-function annotationSides(finding, beforeMoved, afterMoved, reconcileMoved) {
-    // A style/state finding already proves that the element at this path changed.
-    // Only reconcile it when the same surface also has structural churn; without a
-    // DOM finding, cross-path identity matching can erase a real style swap.
+    const divergence = deepestCommonContainer(beforePath, afterPath);
+    if ((beforeCounts.get(divergence) ?? 0) !== (afterCounts.get(divergence) ?? 0))
+        return true;
+    if (containerOf(beforePath) !== containerOf(afterPath))
+        return false;
+    return !beforeMap.elements[afterPath] && !afterMap.elements[beforePath];
+}
+function reconcileIdentityPaths(beforeMap, afterMap, beforeCounts, afterCounts, beforePaths, afterPaths, matches) {
+    const remainingBefore = new Set(beforePaths);
+    const remainingAfter = new Set(afterPaths);
+    // Preserve stable paths first. This keeps duplicate occurrences deterministic
+    // without claiming which indistinguishable physical node was inserted.
+    for (const beforePath of beforePaths) {
+        if (!remainingAfter.has(beforePath))
+            continue;
+        matches.beforeToAfter.set(beforePath, beforePath);
+        matches.afterToBefore.set(beforePath, beforePath);
+        remainingBefore.delete(beforePath);
+        remainingAfter.delete(beforePath);
+    }
+    const remainingAfterPathsByScope = pathsByAnnotationScope(remainingAfter);
+    // Reconcile only within the same normalized structural neighborhood. Any
+    // excess occurrence remains unmatched and is annotated as an addition/removal.
+    for (const beforePath of sortedAnnotationPaths([...remainingBefore])) {
+        const candidates = remainingAfterPathsByScope.get(annotationScope(beforePath)) ?? [];
+        const afterPath = candidates.find((candidate) => canReconcileAnnotationPair(beforeMap, afterMap, beforeCounts, afterCounts, beforePath, candidate, remainingAfter));
+        if (!afterPath)
+            continue;
+        matches.beforeToAfter.set(beforePath, afterPath);
+        matches.afterToBefore.set(afterPath, beforePath);
+        remainingBefore.delete(beforePath);
+        remainingAfter.delete(afterPath);
+    }
+}
+function reconcileAnnotationPaths(beforeMap, afterMap) {
+    const beforePathsByIdentity = indexAnnotationIdentities(beforeMap);
+    const afterPathsByIdentity = indexAnnotationIdentities(afterMap);
+    const beforeCounts = containerChildCounts(beforeMap);
+    const afterCounts = containerChildCounts(afterMap);
+    const matches = {
+        beforeToAfter: new Map(),
+        afterToBefore: new Map(),
+    };
+    const identities = new Set([...beforePathsByIdentity.keys(), ...afterPathsByIdentity.keys()]);
+    for (const identity of identities) {
+        reconcileIdentityPaths(beforeMap, afterMap, beforeCounts, afterCounts, sortedAnnotationPaths(beforePathsByIdentity.get(identity) ?? []), sortedAnnotationPaths(afterPathsByIdentity.get(identity) ?? []), matches);
+    }
+    return matches;
+}
+function annotationSides(finding, beforeMoved, afterMoved) {
     if (finding.kind !== 'dom')
-        return reconcileMoved ? { before: !beforeMoved, after: !afterMoved } : { before: true, after: true };
+        return { before: !beforeMoved, after: !afterMoved };
     if (finding.change === 'removed')
         return { before: !beforeMoved, after: false };
     if (finding.change === 'added')
@@ -96,17 +221,15 @@ function annotationSides(finding, beforeMoved, afterMoved, reconcileMoved) {
     return { before: true, after: true };
 }
 function annotationPaths(findings, beforeMap, afterMap) {
-    const beforePathsByIdentity = indexAnnotationIdentities(beforeMap);
-    const afterPathsByIdentity = indexAnnotationIdentities(afterMap);
-    const reconcileMoved = findings.some((finding) => finding.kind === 'dom');
+    const matches = reconcileAnnotationPaths(beforeMap, afterMap);
     const beforePaths = new Set();
     const afterPaths = new Set();
     for (const finding of findings) {
-        const beforeEntry = beforeMap.elements[finding.path];
-        const afterEntry = afterMap.elements[finding.path];
-        const beforeMoved = hasEquivalentEntryAtAnotherPath(finding.path, beforeEntry, beforePathsByIdentity, afterPathsByIdentity);
-        const afterMoved = hasEquivalentEntryAtAnotherPath(finding.path, afterEntry, afterPathsByIdentity, beforePathsByIdentity);
-        const sides = annotationSides(finding, beforeMoved, afterMoved, reconcileMoved);
+        const beforeMatch = matches.beforeToAfter.get(finding.path);
+        const afterMatch = matches.afterToBefore.get(finding.path);
+        const beforeMoved = beforeMatch !== undefined && beforeMatch !== finding.path;
+        const afterMoved = afterMatch !== undefined && afterMatch !== finding.path;
+        const sides = annotationSides(finding, beforeMoved, afterMoved);
         if (sides.before)
             beforePaths.add(finding.path);
         if (sides.after)
@@ -877,7 +1000,7 @@ function reportHeadline(args) {
         const candidates = liveCandidateLabels.length
             ? ` Auto-detected live-state candidate(s): ${liveCandidateLabels.slice(0, 5).join('; ')}.`
             : '';
-        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check.${candidates}_`);
+        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — changes inside them are NOT certified by this check.${candidates}_`);
     }
     if (contentCount > 0 && (changeGroups.length > 0 || missing.length > 0)) {
         md.push('', `📝 _${contentCount} advisory content change(s) below — they don't affect the check._`);

package/dist/runner.js

@@ -815,10 +815,18 @@ export function defineCrawlCapture(options) {
                 : null;
             if (gap)
                 throw new Error(gap);
+            // The nav's hrefs are same-origin by selection, but a link can still 302
+            // off-origin (SSO, /out?url=…). External content is nondeterministic and
+            // never belongs in a map, so the landing origin is verified per surface.
+            const entryOrigin = new URL(page.url()).origin;
             const captureSurfaces = links.flatMap((link) => expandSurfaceVariants({
                 key: link.key,
                 go: async (p) => {
                     await p.goto(link.url, { waitUntil: 'load' });
+                    const landed = new URL(p.url()).origin;
+                    if (landed !== entryOrigin) {
+                        throw new Error(`styleproof crawl: ${link.url} redirected off-origin to ${landed} — external content is never captured`);
+                    }
                     if (settle)
                         await settle(p);
                 },

package/package.json

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