styleproof 3.20.0 → 3.21.0

package/CHANGELOG.md

@@ -7,6 +7,60 @@ 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

package/README.md

@@ -866,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 — **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`.
+- `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/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;
+}

package/dist/change-groups.d.ts

@@ -0,0 +1,91 @@
+import { type Finding, type PropChange } from './diff.js';
+export declare const isNonValue: (v: string) => boolean;
+export declare function summarizeProps(props: PropChange[]): PropChange[];
+/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
+export declare function prettyLabel(p: string, cls: string): string;
+export declare const safeKey: (s: string) => string;
+export declare const surfaceBase: (s: string) => string;
+export declare const surfaceWidth: (s: string) => number;
+export declare function pushSurfaceWidth(byBase: Map<string, number[]>, base: string, surface: string): void;
+export declare function renderSurfaceGroups(byBase: Map<string, number[]>): string;
+/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
+export declare function formatSurfaceList(surfaces: string[]): string;
+/** Group findings by their element path (one group per changed element). */
+export declare function groupByPath(findings: Finding[]): Finding[][];
+/** Canonical signature of a surface's findings: surfaces that changed in the
+ *  same way collapse into one section + one image (the rects differ per width;
+ *  the change itself does not). */
+export declare function signatureOf(findings: Finding[]): string;
+/** A one-line heading for a change group: "1 element added", "2 elements restyled". */
+export declare function groupTitle(findings: Finding[]): string;
+/** How many of a surface's summarised props are derived/box longhands — the count
+ *  the CLI folds behind `(+N derived longhands)`. Counts on the RAW finding props
+ *  (before cleaning) so the CLI can advertise exactly what it suppressed. */
+export declare function derivedLonghandCount(findings: Finding[]): number;
+/**
+ * Strip the noise the visual report shouldn't carry, cross-referencing each
+ * element's layers so the forced-state layer stops echoing the base:
+ *   - base/pseudo styles: drop size/position-derived longhands (reflow casualties);
+ *   - forced states: drop derived + grid-track props, drop a delta the BASE
+ *     already changed (a `:hover color` that just follows a recoloured base is an
+ *     echo, not a dropped variant), and drop non-value↔non-value rows;
+ *   - any finding left with no props is removed entirely.
+ */
+export declare function cleanFindings(findings: Finding[]): Finding[];
+/** A surface's diff distilled to just what grouping needs: its key and the
+ *  findings kept after noise-cleaning. */
+export type SurfaceFindings = {
+    surface: string;
+    findings: Finding[];
+};
+/** Surfaces that changed the SAME way, collapsed to one group + a representative. */
+export type SignatureGroup = {
+    surfaces: string[];
+    rep: SurfaceFindings;
+    findings: Finding[];
+};
+/**
+ * Group surfaces that changed identically (same signature) into one group each,
+ * keeping the widest surface as the representative. The rects differ per width;
+ * the change itself does not. Callers pass the already-prepared per-surface
+ * findings (missing/one-sided surfaces excluded upstream).
+ */
+export declare function groupBySignature(prepared: SurfaceFindings[]): SignatureGroup[];
+/**
+ * The set of element paths that changed as SHARED CHROME — a persistent frame
+ * element (nav rail, header, footer) that every view renders and that moved on
+ * every view that renders it.
+ *
+ * The rule is STRUCTURAL, deliberately NOT a tunable percentage. For each changed
+ * path we compare two base-key sets:
+ *   - `hosting`  — the surface bases whose style map contains the path at all;
+ *   - `changed`  — the surface bases where the path appears in a finding.
+ * The path is chrome iff it is hosted on MORE THAN ONE base and it changed on
+ * EVERY base that hosts it (`changed ⊇ hosting`). "Every surface that has this
+ * element changed it" is exactly what shared chrome means; it needs no threshold
+ * to tune or defend. A content element (hosted on one base) fails the >1 guard; a
+ * partial change (some hosting bases unchanged) fails the coverage guard.
+ *
+ * Widths of one base collapse to the base key, so a nav present at @1280 and @390
+ * counts once. `surfacePaths` maps each captured surface key → the element paths
+ * it renders (union of both sides from the caller).
+ */
+export declare function chromePaths(changedOnSurfaces: Array<{
+    path: string;
+    surfaces: string[];
+}>, surfacePaths: Map<string, Set<string>>): Set<string>;
+/**
+ * Split signature groups into the shared-chrome tier and the rest. A group is
+ * promoted only when EVERY one of its affected element paths is a chrome path
+ * (see `chromePaths`) — a group that entangles a frame change with a view's own
+ * content change stays in `rest` and renders in place, so we never hide a
+ * content change under a chrome banner.
+ */
+export declare function classifyChrome<G extends {
+    surfaces: string[];
+    findings: Finding[];
+}>(groups: G[], surfacePaths: Map<string, Set<string>>): {
+    chrome: G[];
+    rest: G[];
+    chromePaths: Set<string>;
+};