styleproof 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,70 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [4.4.0] - 2026-07-13
+
+### Changed
+
+- **Spec-driven captures now run in parallel across Playwright workers.** The
+  capture describe declares `parallel` mode itself, so surface×width tests fan
+  out over the consumer's `workers` even when the project pins
+  `fullyParallel: false` for its behaviour suite. Every generated test was
+  already independent (own page, own map/HAR files, own self-check; ledger and
+  manifest tests mkdir and tolerate any order), so the maps are byte-identical —
+  a real consumer's 150-capture run dropped from 24.5 to 6.0 minutes at 4
+  workers on the same box. A spec file whose OWN sibling tests read the captured
+  maps in file order can opt out with `parallel: false`. Found while
+  dogfooding against a large single-route consumer app.
+
+### Fixed
+
+- **An absolute `STYLEMAP_DIR` (or `--dir`) is respected as-is.** It was joined
+  under `baseDir`, so `STYLEMAP_DIR=/abs/path styleproof-map` stranded the maps
+  at `.styleproof/maps/abs/path` where no consumer looks. Relative dirs nest
+  under `baseDir` unchanged. Also found dogfooding against a consumer app.
+
+## [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

package/README.md

@@ -986,6 +986,7 @@ It's **asynchronous by design**: approval is a checkbox tick handled by a separa
 | `dataResidue` | `'gate'`                    | Name data-boundary (`replayUrl`) requests that **fail** during capture (network error / 4xx/5xx — the fallback branch got captured). Always warned + recorded; `'gate'` (the default) also blocks the diff on an unacknowledged one, `'warn'` is the opt-out that records + warns without gating. See [Data residue](#data-residue-a-failed-data-request-is-named-not-swallowed). |
 | `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.                                                                                                                                                                                                                                                                   |
 | `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                                                                                                                                                                                                                                                                                               |
+| `parallel`    | `true`                      | Run the generated capture tests across Playwright workers, even when the project config pins `fullyParallel: false` — every capture test is independent, so a multi-surface spec speeds up ~workers×. Set `false` only for a spec file whose own sibling tests read the captured maps in file order.                                                                              |
 | `selfCheck`   | on while recording          | Capture each surface twice and fail on any difference — proves the capture is deterministic. Off on the replay run; `STYLEPROOF_SELFCHECK=1` forces both.                                                                                                                                                                                                                         |
 | `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                                                                                                                                                                                                                                                                                   |
 | `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                                                                                                                                                                                                                                                                                            |
@@ -1013,7 +1014,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

@@ -190,6 +190,19 @@ function enqueueLinkedPages(links, sweep) {
   }
 }
 
+// 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 {
@@ -209,7 +222,8 @@ async function runCrawl() {
 
     while (sweep.queue.length > 0 && statesLeft > 0) {
       const { url, prefix } = sweep.queue.shift();
-      const report = await crawlAndCapture(page, pageCrawlOptions(browser, url, prefix, statesLeft));
+      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);

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') {
@@ -271,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);
@@ -359,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);
@@ -369,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
@@ -410,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
@@ -472,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
@@ -514,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/bin/styleproof-map.mjs

@@ -253,7 +253,9 @@ function runVariantCrawl(env) {
   if (status !== 0) process.exit(status);
 }
 
-const targetDir = path.join(baseDir, dir);
+// An ABSOLUTE STYLEMAP_DIR/--dir is respected as-is; a relative one nests under
+// baseDir (.styleproof/maps by default) — mirrors the runner's resolveOutputDir.
+const targetDir = path.isAbsolute(dir) ? dir : path.join(baseDir, dir);
 // Sample the tree state the capture is ABOUT to render, so the manifest can bind the
 // map to it. A capture runs for minutes; if the source is edited or HEAD moves in that
 // window, the map renders one state but would otherwise be stamped clean@post-HEAD and

package/dist/crawl-surfaces.js

@@ -408,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;

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/report.js

@@ -1000,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.d.ts

@@ -150,6 +150,14 @@ export type DefineOptions = {
      * `selfCheck` explicitly to override.
      */
     selfCheck?: boolean;
+    /**
+     * Run the generated capture tests in PARALLEL across Playwright workers
+     * (default true). Every capture test is independent, so parallel is safe and
+     * ~workers× faster on a multi-surface spec — even when the project config
+     * pins `fullyParallel: false`. Set false ONLY for a spec file whose OTHER
+     * tests read the captured maps in file order (an in-file assertion suite).
+     */
+    parallel?: boolean;
     /**
      * Opt-in content layer (default OFF). Record each element's own rendered text
      * so the report's optional content section can surface copy changes (run
@@ -239,6 +247,10 @@ export declare function passLiveStreams(page: Page, url: string): Promise<void>;
  * forces it on either way.
  */
 export declare function defaultSelfCheck(replayFrom: string | undefined, env?: string | undefined): boolean;
+/** Resolve a capture output dir: an ABSOLUTE `dir` is respected as-is (a user's
+ *  `STYLEMAP_DIR=/abs/path` must not be buried under `baseDir`); a relative one
+ *  nests under `baseDir` as before. */
+export declare function resolveOutputDir(baseDir: string, dir: string): string;
 /**
  * Output base dir: explicit `baseDir` wins, then `STYLEPROOF_BASEDIR`, then the
  * default. Lets CLIs and CI redirect capture into cache/fallback dirs without

package/dist/runner.js

@@ -304,7 +304,7 @@ async function pinInputs(page, harName, s) {
         }
     }
     else {
-        await page.routeFromHAR(path.join(s.baseDir, s.dir, harName), {
+        await page.routeFromHAR(path.join(resolveOutputDir(s.baseDir, s.dir), harName), {
             url: s.replayUrl,
             update: true,
             updateContent: 'embed', // single portable file, no sidecar resources
@@ -443,7 +443,7 @@ async function capturePopupCandidate(page, surface, width, height, s, options, c
                 return;
             }
         }
-        const stem = path.join(s.baseDir, s.dir, `${surface.key}-${popupId}@${width}`);
+        const stem = path.join(resolveOutputDir(s.baseDir, s.dir), `${surface.key}-${popupId}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots)
             await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
@@ -495,7 +495,7 @@ async function captureSurface(page, surface, width, s) {
         // Attach data-residue AFTER the self-check re-run so both runs' failures are folded
         // (deduped in the watcher). Warn always; the recorded residue is what the gate reads.
         attachDataResidue(map, residue.residue());
-        const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
+        const stem = path.join(resolveOutputDir(s.baseDir, s.dir), `${surface.key}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots) {
             // captureStyleMap froze animations/transitions, so this is the same settled
@@ -533,6 +533,12 @@ function attachDataResidue(map, residue) {
 export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCHECK) {
     return env === '1' || !replayFrom;
 }
+/** Resolve a capture output dir: an ABSOLUTE `dir` is respected as-is (a user's
+ *  `STYLEMAP_DIR=/abs/path` must not be buried under `baseDir`); a relative one
+ *  nests under `baseDir` as before. */
+export function resolveOutputDir(baseDir, dir) {
+    return path.isAbsolute(dir) ? dir : path.join(baseDir, dir);
+}
 /**
  * Output base dir: explicit `baseDir` wins, then `STYLEPROOF_BASEDIR`, then the
  * default. Lets CLIs and CI redirect capture into cache/fallback dirs without
@@ -602,7 +608,7 @@ function resolveSettings(c) {
  */
 function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfaces) {
     test('styleproof coverage ledger', () => {
-        const outDir = path.join(settings.baseDir, dir);
+        const outDir = resolveOutputDir(settings.baseDir, dir);
         fs.mkdirSync(outDir, { recursive: true });
         // Determinism basis: self-check ON proves it (a drift would have failed the capture);
         // else a replay run is deterministic by construction; else it's unproven.
@@ -648,7 +654,7 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfac
 function writeBrowserBuildTest(settings, dir) {
     test('styleproof browser build', ({ page }) => {
         const version = page.context().browser()?.version();
-        const outDir = path.join(settings.baseDir, dir);
+        const outDir = resolveOutputDir(settings.baseDir, dir);
         writeBrowserBuildSidecar(outDir, version);
         writeCaptureManifest({ dir: outDir, screenshots: settings.screenshots });
     });
@@ -681,6 +687,16 @@ export function defineStyleMapCapture(options) {
         return;
     const settings = resolveSettings(options);
     test.describe('styleproof capture', () => {
+        // Every generated test is independent — its own page, its own map/HAR files,
+        // its own self-check; the ledger/manifest tests mkdir and tolerate any order.
+        // Declare the block PARALLEL so captures fan out across the consumer's
+        // Playwright workers even when the project pins `fullyParallel: false` for
+        // its behaviour suite (150 serial surface×width captures is a ~25-minute CI
+        // step; 4 workers make it ~4x faster with byte-identical maps).
+        // `parallel: false` keeps file order for specs whose own sibling tests read
+        // the captured maps.
+        if (options.parallel !== false)
+            test.describe.configure({ mode: 'parallel' });
         writeCoverageLedgerTest(settings, dir, expected ?? null, exclude, captureSurfaces);
         writeBrowserBuildTest(settings, dir);
         for (const surface of captureSurfaces) {
@@ -815,10 +831,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.2.0",
+  "version": "4.4.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",