styleproof 3.19.0 → 3.21.0

package/CHANGELOG.md

@@ -7,6 +7,137 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.21.0] - 2026-07-07
+
+### Added
+
+- **Shared-chrome tier in the report and the `styleproof-diff` CLI.** When one
+  change rides the frame every view draws — a persistent nav rail, header, or
+  footer that moved on every surface that renders it — it is promoted to a single
+  "🧱 Global chrome change" callout at the top, with the detail folded beneath,
+  instead of repeating across a long surface list on several entries. The reviewer
+  reads "the nav changed everywhere" once. The threshold is **structural, not a
+  tunable knob**: an element path is chrome only when it is hosted on more than one
+  surface base and changed on _every_ base that hosts it (full coverage of its
+  hosting surfaces). A change on merely some surfaces, or a view's own content
+  change entangled with the frame change, is never promoted — the view-specific
+  detail always stays visible. Purely presentational: grouping keys, findings,
+  counts, exit codes, and `--json` are unchanged.
+
+### Changed
+
+- **`styleproof-diff` human output now reuses the report's grouping.** One real
+  change no longer prints once per surface with its derived-longhand echo: the CLI
+  groups surfaces that changed identically into one finding (with the per-surface
+  count on the header line), summarises longhands into shorthands, and folds the
+  size/position-derived longhands (`transform-origin`, `width`/`height`, cascaded
+  ancestor heights…) behind a `(+N derived longhands)` count. A one-view button
+  restyle at one width that used to fill dozens of raw lines now reads as a single
+  grouped finding. `--json` stays the complete, byte-stable machine contract (every
+  surface, every raw longhand); exit codes are unchanged.
+
+### Fixed
+
+- **The report's certification block no longer contradicts the diff on inventory
+  additions.** For the same capture pair, `styleproof-diff` correctly prints a
+  navigable addition (additive, non-gating), but `styleproof-report`'s certification
+  block still read `Inventory — ✓ navigable set unchanged` — telling a reviewer the
+  navigable set didn't change when it did. The inventory line now echoes additions as
+  an informational, still-✓-class clause (`✓ N navigable affordance(s) added: <keys>
+(additions don't gate)`), with the same truncation and key-escaping discipline as
+  the removals line. Removals still drive the ⚠/✗ gate semantics; additions are
+  appended. The diff and the report can no longer disagree about the navigable delta.
+- **The unit suite no longer flakes on spawned-CLI tests (test-infra only, no
+  consumer-visible change).** The package-smoke test packed the live checkout with
+  `npm pack`, which runs the `prepare` lifecycle (`tsc`) even under `--ignore-scripts`.
+  `tsc` truncates each `dist/*.js` to zero bytes before rewriting it, so a CLI spawned
+  by a _different_ test running concurrently under `node --test` could read a
+  half-written `dist` module and die with a static ESM link error
+  (`does not provide an export named …`) — surfacing as an "impossible" exit code (a
+  flag-rejection test that pins exit `2` seeing exit `1`, or a spawned bin printing a
+  missing-export `SyntaxError`). The smoke test now packs a staged copy of the package
+  whose manifest carries no lifecycle scripts, so pack can never rebuild — the shared
+  `dist` is never mutated mid-suite. Same coverage (the packed tarball is still
+  installed and its API + every bin's `--help` exercised); the packed artifact is
+  identical.
+
+## [3.20.0] - 2026-07-07
+
+### Fixed
+
+- **Crawl no longer double-captures `/` and `/index.html` as two surfaces.** On a
+  static multi-page site whose nav links the `.html` files, `/` and `/index.html`
+  (and `/dir/` vs `/dir/index.html`) are the same route but were captured twice as
+  byte-near-identical maps — doubling the capture work and duplicating every finding
+  in the diff. The crawl's dedup identity now normalizes a trailing `index.html` to
+  its directory path, so they collapse to one surface (first-seen href keeps its
+  original navigable form). Only the literal `index.html` filename normalizes — a
+  genuine `about.html` stays a distinct surface from `about`.
+- **`styleproof-init` now states exactly which files it wrote — and that it did NOT
+  touch `package.json` or your lockfile.** Adopters attributed the `styleproof`
+  dependency entry (added by their package manager's `install`) to init; init only
+  ever reads `package.json` and writes the spec, the dedicated Playwright config,
+  `.gitignore` lines, and the CI workflow. The summary now enumerates those files and
+  says plainly that the manifest and lockfile were left untouched.
+- **The no-comparison outcome of `styleproof-diff` / `styleproof-report` names both
+  ways forward.** When the no-args (inferred-base) path can restore no base map — no
+  map-store remote, no cached bundle — nothing is compared. That already exits `2`
+  (never a soft `0` a newcomer could read as "certified clean"); the message now says
+  "nothing was compared" and names the two working alternatives: run in CI (or a repo
+  with the `origin` remote) where the base is restorable, or the two-directory form
+  `styleproof-diff <beforeDir> <afterDir>`. A regression test pins the exit-2 contract
+  in a remote-less repo for both commands.
+- **README: the Next.js coverage guard is described accurately.** The docs conflated
+  two behaviors. With the auto-wired spec, `surfaces` and `expected` both derive from
+  the same `discoverNextRoutes()` call, so a new static route is captured and expected
+  together — **auto-covered, never a guard failure**. The guard **fails** only on
+  genuine divergence (a dynamic route, a hand-maintained registry, or a route dropped
+  from `surfaces` while still `expected`). Rewrote the overclaiming passages and the
+  generated-spec comments to state both behaviors.
+- **Layout-equivalent margin suppression no longer drops a real one-sided margin
+  change.** `dropLayoutEquivalentMarginProps` suppressed any horizontal
+  `margin-left/right/inline-start/inline-end` change whenever the element's rect
+  was unchanged — reasoning that a margin that doesn't move the box is cosmetic
+  drift. But a one-sided change (e.g. `margin-left: 0 → 40px` with `margin-right`
+  untouched) that leaves the rect identical only stayed put because _something
+  else compensated_; that is a genuine restyle, and it was silently dropped. The
+  suppression now fires only when there is no **demonstrable px imbalance**
+  between a side and its opposite — balanced drift (both sides move together) and
+  forced-state deltas are still suppressed exactly as before, but a one-sided
+  real change surfaces. A residual, consciously-deferred corner remains (a
+  perfectly _balanced_ change held in place by external compensation), documented
+  inline; closing it needs cross-element layout reasoning.
+- **`styleproof-init` no longer imports the whole library barrel (fixes a CI
+  flake).** The scaffolder only needs `discoverNextRoutes`, but it imported it
+  from `dist/index.js` — dragging capture, the crawler, the report renderer, and
+  six Playwright-importing modules into a tool that writes files and captures
+  nothing. Loading that oversized module graph concurrently (init's own suite
+  spawns the CLI many times, alongside the rest of `node --test`) is what made
+  init's tests flake in CI, red-flagging releases with no code cause. It now
+  imports from the `dist/routes.js` leaf (`fs` + `path` only): init's transitive
+  module graph drops from 21 dist modules to 1, with zero Playwright modules on
+  its load path. Behaviour is unchanged; a regression test pins the leaf import.
+- **Popup capture: verified reset + identity-bound triggers (no leaked-overlay
+  contamination, no wrong-trigger keying).** On a surface whose `go()` doesn't
+  navigate (SPA variants), the between-popups reset was Escape-only and assumed:
+  a toast or `[role="status"]` overlay Escape can't dismiss leaked into the next
+  popup's capture, and each reopen re-enumerated triggers positionally, so a
+  shifted trigger set (e.g. a click that adds a button) could key a popup under a
+  different trigger than the one originally enumerated. Triggers are now re-bound
+  by the DOM identity recorded at first enumeration, and the reset is verified
+  against the surface's pristine overlay set; a candidate that can't be opened
+  safely is skipped loudly (a `styleproof:` warning naming the popup and the
+  leaked overlay or missing trigger) instead of being captured contaminated,
+  mis-keyed, or — with self-check on — saved unproven. That identity is the
+  trigger's DOM path **and** its accessible label, not the path alone: for an
+  id-less trigger the path ends in `:nth-of-type`, which is still position within
+  a parent, so a same-tag same-parent sibling injected earlier in DOM order
+  between enumeration and reopen would slide the recorded path onto a different
+  trigger and key its popup under the wrong one — silently. Requiring the label
+  (the same aria-label/name/text/title accessible name the crawler reads) to match
+  too turns that mismatch into the same loud skip. Navigating surfaces are
+  unaffected.
+
 ## [3.19.0] - 2026-07-06
 
 ### Added

package/README.md

@@ -57,8 +57,12 @@ surface. `expected` turns that inventory into a guard: a key it lists that is
 neither captured nor excluded fails as missing coverage instead of silently
 passing. What's guarded depends on how `expected` is fed —
 
-- **Next.js:** auto-guarded. `styleproof-init` wires `expected` to the routes it
-  discovers, so a new page fails the guard with nothing to keep in sync.
+- **Next.js:** auto-covered. `styleproof-init` derives both `surfaces` and
+  `expected` from the same `discoverNextRoutes()` call, so a new static route lands
+  in both at once — captured and expected together, with nothing to keep in sync.
+  The guard then fails only on genuine divergence between the two: a dynamic route
+  (pre-excluded, so its reason surfaces), a hand-maintained registry, or a route
+  dropped from `surfaces` while still in `expected`.
 - **Link-crawled SPAs:** pass `expected` to `defineCrawlCapture` and the crawl
   reconciles it against the _rendered nav_ (the route universe for such an app),
   both directions — a new linked route with no `expected` entry fails, and an
@@ -152,7 +156,7 @@ _and_ no head capture, so it never appears in any diff, and the status goes
 green having never looked at it. This is the one thing the captures can't catch
 on their own: a capture that was never taken.
 
-Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails the moment a route exists with no surface, so a new page can't ship uncaptured:
+Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails when `expected` and your captured surfaces diverge — a route you listed in `expected` with no surface and no `exclude` entry fails as missing coverage, so a registry entry can't quietly ship uncaptured:
 
 ```ts
 import { defineStyleMapCapture } from 'styleproof';
@@ -168,7 +172,7 @@ defineStyleMapCapture({
 
 A route that's neither a captured surface nor an `exclude` entry fails the guard; an `exclude` key that isn't in `expected` (a renamed/removed route) fails too, so the opt-out ledger can't quietly rot. Captured surfaces beyond `expected` are fine — one route can have several states (`landing`, `landing-nav-open`). Omit `expected` and behaviour is unchanged.
 
-**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and wires both the surfaces and `expected` to them — so it's protected out of the box, and a page you add later is covered automatically with nothing to keep in sync:
+**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and derives **both** the surfaces and `expected` from that same `discoverNextRoutes()` call. Because they share one source, a static route you add later is captured and expected in the same step — auto-covered, never a guard failure, with nothing to keep in sync. The guard exists for the cases where the two genuinely diverge: a dynamic `[param]` route (it can't be navigated without a value, so it's placed in `exclude` with a reason rather than captured), a registry you hand-maintain instead of the live call, or a route you drop from `surfaces` while it's still `expected`:
 
 ```ts
 import { defineStyleMapCapture, discoverNextRoutes } from 'styleproof';
@@ -292,6 +296,17 @@ semantic roots that were actually present in the computed-style map, so tests ca
 assert a capture reached `role="dialog"`, `aria-modal`, `role="menu"`,
 `role="listbox"`, or hot-toast text.
 
+Triggers are enumerated once per surface and every reopen re-binds to that same
+element by identity — its DOM path **and** its accessible label — never by
+position. Between popups the surface is reset (Escape + `go()`) and the reset is
+verified: if an overlay a previous popup left behind is still visible (Escape
+closes dialogs, not toasts or status regions), or an enumerated trigger
+disappeared or changed identity (e.g. a same-tag sibling shifted in earlier),
+that candidate is **skipped loudly** — a `styleproof:` warning names the popup and
+why — instead of capturing contaminated state or keying a popup under the wrong
+trigger. Dismiss the leaking overlay in the surface's `go()`, or capture it as an
+explicit variant.
+
 **Harvest one-step variants.** Routes are not the whole UI: drawers, tabs,
 dialogs, empty form errors, selects, and other one-step states need their own
 captures. `styleproof-variants` opens a running app, tries semantic controls
@@ -851,7 +866,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 - `styleproof-init` — scaffold the gate: the capture spec, a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. 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 incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including 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); `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 manifest at all, 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`.
+- `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 incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including 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 manifest at all, 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-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-diff.mjs

@@ -25,6 +25,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
+// The shared grouping brain (leaf — no Playwright-adjacent imports) that already
+// dedupes the report: group identical change-sets across surfaces and fold derived
+// longhands. Used for the HUMAN output only; --json stays the raw machine contract.
+import {
+  cleanFindings,
+  groupBySignature,
+  groupByPath,
+  groupTitle,
+  summarizeProps,
+  derivedLonghandCount,
+  formatSurfaceList,
+  classifyChrome,
+  surfaceBase,
+} from '../dist/change-groups.js';
 import {
   DEFAULT_MAP_STORE_BRANCH,
   DEFAULT_REMOTE,
@@ -39,7 +53,7 @@ import {
   showHelpAndExit,
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
-import { readInventories } from '../dist/capture.js';
+import { readInventories, surfaceElementPaths } from '../dist/capture.js';
 import { auditRunInventory, readAckFile } from '../dist/inventory.js';
 import { auditCoverage, auditDeterminism, COVERAGE_LEDGER } from '../dist/coverage.js';
 import { isMapFile } from '../dist/map-store.js';
@@ -254,6 +268,7 @@ let result;
 let inventoryAudit = null;
 let coverageVerdict = null;
 let determinismVerdict = null;
+let surfacePaths = new Map();
 try {
   assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
@@ -264,6 +279,9 @@ try {
   const headLedger = readLedger(dirB);
   coverageVerdict = auditCoverage(capturedSurfaceKeys(dirB), headLedger);
   determinismVerdict = auditDeterminism(readLedger(dirA), headLedger);
+  // 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);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -272,33 +290,90 @@ try {
 }
 const { surfaces, counts, compared } = result;
 
-for (const sd of surfaces) {
-  if (sd.missing) {
-    const side = sd.missing === 'before' ? 'after' : 'before';
-    console.log(`\n${sd.surface}: new surface — captured only in the ${side} set, no baseline to compare`);
-    continue;
-  }
+// ── grouped human output ─────────────────────────────────────────────────────
+// Reuse the report's dedup so one real change doesn't print once per surface with
+// its derived-longhand echo: group surfaces that changed identically, fold the
+// size/position-derived longhands behind a count, and keep the per-surface tally
+// in each group's header line. --json below is untouched (the raw machine feed).
+
+// One finding's lines: a heading, then its summarised property deltas (the same
+// dedupe the report shows). Returns [] for a DOM finding (handled separately) or a
+// finding whose props all summarised away.
+function findingLines(f) {
+  if (f.kind === 'dom') return [];
+  const rows = summarizeProps(f.props);
+  if (!rows.length) return [];
+  const head =
+    f.kind === 'state'
+      ? `  [:${f.state}] ${findingLabel(f.path, f.cls)}${f.sub !== f.path ? ` ⇒ ${f.sub}` : ''}`
+      : `  ${findingLabel(f.path, f.cls)}${f.pseudo || ''}`;
+  return [head, ...rows.map((p) => `    ${p.prop}: ${p.before} → ${p.after}`)];
+}
+
+// A DOM finding's one-line heading (added/removed/retagged).
+function domLine(dom) {
+  return dom.change === 'retagged'
+    ? `  DOM retagged: ${dom.path} ${dom.detail ?? ''}`
+    : `  DOM ${dom.change}: ${findingLabel(dom.path, dom.cls)}`;
+}
+
+// The element lines for one change group, from its representative's cleaned
+// findings: one heading per element, then its summarised property deltas.
+function elementLines(findings) {
   const lines = [];
-  for (const f of sd.findings) {
-    if (f.kind === 'dom') {
-      lines.push(
-        f.change === 'retagged'
-          ? `  DOM retagged: ${f.path} ${f.detail}`
-          : `  DOM ${f.change}: ${findingLabel(f.path, f.cls)}`,
-      );
-    } else if (f.kind === 'style') {
-      lines.push(`  ${findingLabel(f.path, f.cls)}${f.pseudo || ''}`);
-      for (const p of f.props) lines.push(`    ${p.prop}: ${p.before} → ${p.after}`);
-    } else {
-      lines.push(`  [:${f.state}] ${findingLabel(f.path, f.cls)}${f.sub !== f.path ? ` ⇒ ${f.sub}` : ''}`);
-      for (const p of f.props) lines.push(`    ${p.prop}: ${p.before} → ${p.after}`);
-    }
+  for (const group of groupByPath(findings)) {
+    const dom = group.find((f) => f.kind === 'dom');
+    if (dom) lines.push(domLine(dom));
+    for (const f of group) lines.push(...findingLines(f));
   }
-  console.log(`\n${sd.surface}: ${lines.filter((l) => !l.startsWith('    ')).length} element(s) differ`);
+  return lines;
+}
+
+// New (one-sided) surfaces keep their own line, unchanged.
+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`);
+}
+
+// Group the changed surfaces the way the report does, so an identical change
+// across N surfaces prints once (with the count), not N times.
+const preparedForGrouping = surfaces
+  .filter((sd) => !sd.missing)
+  // Carry the RAW findings too, so we can report how many derived longhands the
+  // grouped view folded (the cleaned findings have them already removed).
+  .map((sd) => ({ surface: sd.surface, findings: cleanFindings(sd.findings), raw: sd.findings }))
+  .filter((p) => p.findings.length > 0);
+
+function printGroup(cg) {
+  const lines = elementLines(cg.findings);
+  const derived = derivedLonghandCount(cg.rep.raw);
+  const foldNote = derived > 0 ? ` (+${derived} derived longhand${derived === 1 ? '' : 's'})` : '';
+  const others = cg.surfaces.length - 1;
+  const scope =
+    others > 0
+      ? `${cg.rep.surface} (+${others} more surface${others === 1 ? '' : 's'}: ${formatSurfaceList(cg.surfaces)})`
+      : cg.rep.surface;
+  console.log(`\n${scope}: ${groupTitle(cg.findings)}${foldNote}`);
   for (const line of lines.slice(0, MAX)) console.log(line);
   if (lines.length > MAX) console.log(`  ... and ${lines.length - MAX} more lines (re-run with --max ${lines.length})`);
 }
 
+// Shared-chrome tier: a change that rode the frame every view draws (nav/header)
+// gets one banner up top, then its detail — so the reviewer reads "the nav changed
+// everywhere" once, not once per surface entry. Presentational only.
+const grouped = groupBySignature(preparedForGrouping);
+const { chrome, rest } = classifyChrome(grouped, surfacePaths);
+if (chrome.length) {
+  // Base count from the pre-cleanup surface set (dirB may be deleted by now).
+  const bases = new Set([...surfacePaths.keys()].map(surfaceBase)).size;
+  console.log(
+    `\n🧱 Global chrome change(s) — across all ${bases} surface(s): ${chrome.length} change(s) rode the shared frame every view draws (a persistent nav, header, or footer).`,
+  );
+  for (const cg of chrome) printGroup(cg);
+}
+for (const cg of rest) printGroup(cg);
+
 const invRemovals = printInventoryAudit(inventoryAudit);
 const coverageFails = printCoverageVerdict(coverageVerdict);
 const determinismFails = printDeterminismVerdict(determinismVerdict);

package/bin/styleproof-init.mjs

@@ -7,10 +7,13 @@
  * Writes:
  *   - <dir> (default e2e/styleproof.spec.ts): a starter capture spec with a
  *     minimal settle() helper (triggers scroll-reveal content; StyleProof itself
- *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives surfaces AND
- *     the `expected` coverage guard from the app's routes at run time, so a page
- *     added later can't ship without a surface; otherwise it writes one sample
- *     surface plus a commented guard block to wire to your own route registry.
+ *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives BOTH the
+ *     surfaces AND the `expected` coverage guard from the same `discoverNextRoutes()`
+ *     call, so a static route added later is captured and expected together —
+ *     auto-covered, never a guard failure; the guard fails only on genuine
+ *     divergence (a dynamic route, a hand-maintained registry, or a route dropped
+ *     from surfaces but still expected). Otherwise it writes one sample surface
+ *     plus a commented guard block to wire to your own route registry.
  *   - playwright.styleproof.config.ts: a dedicated production-build Playwright
  *     config for StyleProof captures, so an existing app Playwright config is
  *     never disturbed or accidentally reused.
@@ -23,7 +26,12 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { discoverNextRoutes } from '../dist/index.js';
+// Import from the leaf module, not the barrel: styleproof-init only scaffolds
+// files and never captures. Pulling `../dist/index.js` here dragged the whole
+// library — capture, crawler, report, and six Playwright-importing modules —
+// into a tiny scaffolder's load path, and that oversized concurrent module
+// graph is what made init's tests flake in CI. routes.js needs only fs + path.
+import { discoverNextRoutes } from '../dist/routes.js';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
@@ -39,9 +47,10 @@ options:
 
 What it writes:
   - the spec at --dir, with a minimal settle() helper (scroll-reveal only).
-    In a Next.js app it discovers your routes at run time and wires both the
-    surfaces and the \`expected\` coverage guard to them, so a new page can't ship
-    uncaptured. Otherwise it writes one sample surface + a commented guard block.
+    In a Next.js app it discovers your routes at run time and derives both the
+    surfaces and the \`expected\` coverage guard from that one call, so a new static
+    route is auto-covered (captured + expected together); the guard fails only when
+    the two diverge. Otherwise it writes one sample surface + a commented guard block.
   - playwright.styleproof.config.ts, a dedicated production-build Playwright config
   - .github/workflows/styleproof.yml, a cache-first PR report workflow
 
@@ -114,9 +123,12 @@ const HEADER = `/**
  *   npx styleproof-diff  # compare cached base/head maps by commit SHA
  */`;
 
-// Next.js detected: derive both surfaces and the coverage guard from the app's
-// routes AT RUN TIME, so a page added later is in `expected` automatically and
-// fails the guard until it has a surface — no static list to drift.
+// Next.js detected: derive BOTH surfaces and the coverage guard from the app's
+// routes AT RUN TIME, from one `discoverNextRoutes()` call — so a static page added
+// later is a captured surface AND `expected` in the same step (auto-covered, never a
+// guard failure), with no static list to drift. The guard fires only when the two
+// diverge (a dynamic route, a hand-maintained registry, or a route dropped from
+// surfaces but still expected).
 const NEXT_SPEC = `import type { Page } from '@playwright/test';
 import { defineStyleMapCapture, discoverNextRoutes, type Surface } from 'styleproof';
 
@@ -124,12 +136,12 @@ ${HEADER}
 
 ${SETTLE}
 
-// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME — so a page
-// you add later is covered automatically, with no surface list to keep in sync
-// (that drift is exactly what lets a new page ship unverified). Edit freely; this
-// is your spec. Static routes each get a capture; dynamic [param] routes can't be
-// navigated without a value, so they're listed in \`exclude\` until you add a
-// surface with a concrete param.
+// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME. Both SURFACES
+// and \`expected\` below come from this one list, so a static route you add later is
+// captured and expected together — covered automatically, with no surface list to
+// keep in sync. Edit freely; this is your spec. Static routes each get a capture;
+// dynamic [param] routes can't be navigated without a value, so they're listed in
+// \`exclude\` until you add a surface with a concrete param.
 const ROUTES = discoverNextRoutes();
 
 const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
@@ -146,9 +158,10 @@ const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
 
 defineStyleMapCapture({
   surfaces: SURFACES,
-  // Coverage guard: every known route must be a captured surface or excluded, or
-  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser).
-  // A new page with no surface can't slip through the gate unseen.
+  // Coverage guard: every \`expected\` route must be a captured surface or excluded, or
+  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser). Since
+  // both sides come from ROUTES, static routes never trip it; it fires when they
+  // diverge — a dynamic route (excluded below), or a route you drop from SURFACES.
   expected: ROUTES.map((r) => r.key),
   exclude: Object.fromEntries(
     ROUTES.filter((r) => r.dynamic).map((r) => [r.key, \`dynamic route (\${r.path}) — add a surface with a concrete param\`]),
@@ -480,9 +493,14 @@ const isNext = routes.length > 0;
 const SPEC = isNext ? NEXT_SPEC : GENERIC_SPEC;
 
 let wroteSomething = false;
+// Every path init created or modified this run, so the summary can name exactly what
+// it touched — and, by omission, what it did NOT (init never writes package.json or a
+// lockfile; that's the package manager's `install`, not this scaffolder).
+const touched = [];
 
 const spec = writeFileSafe(specPath, SPEC, { force });
 if (spec.wrote) {
+  touched.push(specPath);
   console.log(`${spec.exists ? 'overwrote' : 'created'} ${specPath}`);
   if (isNext) {
     const dynamic = routes.filter((r) => r.dynamic).length;
@@ -502,6 +520,7 @@ if (spec.wrote) {
 const configPath = 'playwright.styleproof.config.ts';
 const config = writeFileSafe(configPath, CONFIG, { force });
 if (config.wrote) {
+  touched.push(configPath);
   console.log(`${config.exists ? 'overwrote' : 'created'} ${configPath} (dedicated StyleProof capture config)`);
   wroteSomething = true;
 } else {
@@ -515,6 +534,7 @@ if (fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js
 
 const ignored = ['.styleproof/', 'test-results/', 'playwright-report/'].filter((line) => ensureGitignoreLine(line));
 if (ignored.length) {
+  touched.push('.gitignore');
   console.log(`updated .gitignore (${ignored.join(', ')})`);
   wroteSomething = true;
 }
@@ -522,12 +542,21 @@ if (ignored.length) {
 // Cache-first CI report — never overwrite an existing workflow.
 const ci = writeFileSafe(CI_PATH, CI_WORKFLOW);
 if (ci.wrote) {
+  touched.push(CI_PATH);
   console.log(`created ${CI_PATH} (cache-first StyleProof report)`);
   wroteSomething = true;
 } else {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
+if (touched.length) {
+  // State exactly what init wrote, and — because adopters have blamed init for the
+  // `styleproof` entry their package manager's `install` added — say plainly that it
+  // did NOT touch package.json or the lockfile. Truth over assumption.
+  console.log(`\nstyleproof-init wrote only: ${touched.join(', ')}`);
+  console.log('It did NOT modify package.json or your lockfile (that was your package manager’s install).');
+}
+
 console.log('\nHow the gate works — it runs on your first PR with no extra steps:');
 console.log('  1. Commit and open a PR. CI captures the base and head surfaces in one pinned');
 console.log('     environment and posts the StyleProof report — no local step required.');

package/dist/capture.d.ts

@@ -261,4 +261,12 @@ export declare function loadStyleMap(filePath: string): StyleMap;
 export declare function readInventories(dir: string): Array<{
     inventory?: NavigableItem[];
 }>;
+/**
+ * Each captured surface key → the set of element paths it renders, unioned across
+ * the given dirs (so an element present on only one side still "belongs" to the
+ * surface). Feeds the shared-chrome tier, which needs to know, per surface, which
+ * paths exist to tell a frame-wide change from one view's content. Shared by the
+ * report and the diff CLI (both already read maps this way).
+ */
+export declare function surfaceElementPaths(...dirs: string[]): Map<string, Set<string>>;
 export {};

package/dist/capture.js

@@ -805,3 +805,25 @@ export function readInventories(dir) {
         .map((f) => loadStyleMap(path.join(dir, f)))
         .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
 }
+/**
+ * Each captured surface key → the set of element paths it renders, unioned across
+ * the given dirs (so an element present on only one side still "belongs" to the
+ * surface). Feeds the shared-chrome tier, which needs to know, per surface, which
+ * paths exist to tell a frame-wide change from one view's content. Shared by the
+ * report and the diff CLI (both already read maps this way).
+ */
+export function surfaceElementPaths(...dirs) {
+    const bySurface = new Map();
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const file of fs.readdirSync(dir).filter(isMapFile)) {
+            const surface = file.replace(/\.json(\.gz)?$/, '');
+            const set = bySurface.get(surface) ?? new Set();
+            for (const p of Object.keys(loadStyleMap(path.join(dir, file)).elements))
+                set.add(p);
+            bySurface.set(surface, set);
+        }
+    }
+    return bySurface;
+}