styleproof 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,112 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.6.0] - 2026-07-03
+
+### Changed
+
+- Crawl candidate collection collapses inherited-cursor subtrees to their
+  OUTERMOST clickable. `cursor` is an inherited CSS property, so a clickable card
+  makes every descendant compute `cursor: pointer`; each became its own candidate
+  even though clicking any of them just bubbles to the card's handler (the same
+  surface). Each redundant candidate paid a drive + verified reset — the dominant
+  cost of a large crawl. Measured on a 241-class design: base candidates 557 → 22,
+  whole coverage crawl ~40min → ~6min (240/241, unchanged). Semantic controls
+  nested in a clickable container are still kept.
+- `--until-covered` reaches deep coverage: it now terminates on the queue
+  draining (or full coverage), not a fixed "N surfaces without a new class"
+  plateau — a plateau cut the crawl off before a productive deep state (an
+  automation whose expandable run row is its last candidate) was ever swept.
+  Coverage mode also (a) prunes the queue to surfaces that add new render
+  vocabulary — a structural repeat like the ninth agent's identical dossier is
+  captured once but not re-drilled — and (b) uses the breadth-first queue rather
+  than the depth-first in-place descent, so distinct components are reached fast
+  and each drilled once via now-reliable resets. Measured on a 241-class design:
+  240/241 (the one gap a post-decision state reachable only with a setup step),
+  where a plateau-stopped crawl left the deep automation run-detail unmapped.
+
+### Fixed
+
+- Reset-replay to depth >= 2 no longer fails: the crawler's structural
+  fingerprint counted StyleProof's OWN injected hover-sink `<div>` (added during
+  a capture, so present when a state is captured in place but absent on a fresh
+  reset+replay). Every such reset failed its fingerprint verification, so any
+  surface reachable ONLY by re-driving from a deep state — a pairwise mode
+  combination like a tab's edit view — was silently lost. The fingerprint now
+  excludes the sink (and framework route-announcers). Measured: depth-2..5
+  resets went from all-fail to all-pass.
+
+### Fixed
+
+- Report tables never show an equal-looking Before/After pair for a real diff.
+  A colour embedded in a compound value (gradient, shadow) no longer stands in
+  for the whole value — `toHex` only converts values that ARE a colour — and
+  long value pairs (gradients, data URIs) are excerpted around the differing
+  substring with a little shared context on each side.
+- Report values render verbatim: display rounding of decimals is gone (alpha
+  `0.18` was shown as `0.2`, and a real `0.18 → 0.2` change could be dropped
+  as a no-op after rounding).
+
+### Changed
+
+- Crawl reset settle no longer waits on `networkidle`: it polls DOM-growth to
+  detect the mounted app (unchanged) and then waits for `document.fonts.ready`
+  specifically (fonts are part of the computed style the diff compares, so they
+  must be loaded — but that is the deterministic signal, cache-warm on repeat
+  loads). networkidle waited a 500ms idle window ON TOP of a cross-origin font
+  sheet that lingered ~1s per load with no bearing on readiness; since every
+  state reset re-navigates, that dominated crawl time. Measured: settle 911ms →
+  105ms per reset (~8.7x), whole-crawl surface rate ~5/min → ~17/min.
+
+- Crawl is now breadth-first (was depth-first): every shallow surface — nav
+  tabs, opened panels, the tabs inside a dossier — is exhausted before drilling
+  deeper. Depth-first starved breadth: one append-generator branch drilled past
+  depth 20 while sibling tabs sat unvisited, so real surfaces (an OAuth card, a
+  skills grid, a markdown editor) went uncaptured — measured live as 48 defined
+  classes never rendered across ~12 surfaces. Dedup is set-based, so order
+  changes only WHICH surface is found first, never the final set.
+- `maxDepth` default 1000 -> 16: exhaustive for real UI (nothing human-navigable
+  is 16 clicks from load) while terminating append-generator chains, whose every
+  appended node is a fresh tag-path identity. The coverage verifier still names
+  any class left unrendered, so a too-low cap fails loudly rather than lying.
+
+- The never-click guard now also covers state-mutating verbs (rotate,
+  provision, seal, regenerate, renew): mapping must not mutate, and a mutating
+  control that persists after its click re-labels its surroundings with fresh
+  data on every press — an unbounded mutation farm a crawl must not walk.
+  Observed live: credential-rotation cells minted new identities per press,
+  inflating a crawl past 470 surfaces at depth 23. Their render states are
+  seed-data territory (and anything unreached is named by the verifier).
+- Freshly-opened surfaces are swept IN PLACE (forward-drive), not only queued
+  for a later reset+replay. Reaching a surface by a forward click is reliable;
+  re-reaching it by reset is slow (a reset per candidate) and, at depth, starved
+  — a dossier's many filter combinations flood the queue and bury the deep
+  sweep, so an expanded run row inside an expanded job was captured 0 times
+  despite being reachable (now 29). The descent drives only fresh controls new
+  to the surface (excludes parent-present mode-switchers), so pairwise mode
+  coverage is unchanged and the lattice stays pairwise.
+
+### Added
+
+- `--until-covered`: stop the crawl as soon as every class the page's
+  stylesheets define has rendered (full coverage) or coverage stops improving
+  (no new class for a plateau of surfaces). Turns an exhaustive crawl into a
+  fast coverage check that stops once it has SEEN everything, instead of
+  enumerating every combinatorial surface that adds no new vocabulary. Opt-in;
+  exhaustive remains the default.
+
+## [3.5.0] - 2026-07-02
+
+### Added
+
+- Parallel crawl: `--workers <n>` (default 4) sweeps queued states concurrently,
+  each worker on its own browser context. The surface set is identical to a
+  serial crawl — dedup sets are shared, and a state's children only join the
+  queue when its sweep completes, so family retry never reads a half-built
+  changer registry. Only dup-key suffix attribution can vary with timing; pass
+  `--workers 1` for byte-stable keys. Exhaustive runs drop from hours to
+  minutes on lattice-heavy designs.
+
 ## [3.4.0] - 2026-07-02
 
 ### Fixed

package/README.md

@@ -424,7 +424,7 @@ styleproof-diff design .styleproof/maps/current                # diff the whole
 
 It's **exhaustive by default**: the crawl stops when there is nothing left to drive — every control tried once, every structurally new surface captured — not at a budget. Termination is guaranteed by dedup (controls dedup by selector, surfaces by a structural fingerprint), and the `--max-depth` / `--max-actions` / `--max-states` flags exist only as deliberate throttles. It's deterministic (document order; the same surface reached two ways is captured once) and self-settling — it waits for an async app (React/Vue/Babel that boots after `load`) to mount before reading, so a bare crawl of a client-rendered page still captures the mounted UI.
 
-What makes exhaustive affordable is that the sweep works **in place**: standing in a state, each control is clicked right where the page is, and a cheap DOM fingerprint decides what happened — a no-op click costs nothing, and only a state-changing click pays a reset (fresh navigation + replay of the click-path), which is then **verified by fingerprint** so children are never attributed to the wrong parent. New surfaces are captured at every width the moment they're reached — a deep or animated click-path is never re-driven to capture, so it can't be the thing that drops a surface. Progress streams as it goes, one line per captured surface.
+What makes exhaustive affordable is that the sweep works **in place**: standing in a state, each control is clicked right where the page is, and a cheap DOM fingerprint decides what happened — a no-op click costs nothing, and only a state-changing click pays a reset (fresh navigation + replay of the click-path), which is then **verified by fingerprint** so children are never attributed to the wrong parent. New surfaces are captured at every width the moment they're reached — a deep or animated click-path is never re-driven to capture, so it can't be the thing that drops a surface. Progress streams as it goes, one line per captured surface. And it's **parallel by default** — `--workers <n>` (default 4) sweeps states concurrently on isolated browser contexts with the exact same surface set as a serial crawl (dedup is shared; children only enter the queue when their parent's sweep completes); `--workers 1` if you want byte-stable dup-key attribution.
 
 **And it proves nothing was missed.** After the crawl, StyleProof compares every class the page's own stylesheets define (read from the parsed CSSOM) against the classes actually rendered across the captured surfaces, and prints what — if anything — was never seen. `--require-full-coverage` turns any residue into exit code 4, so "the design is fully covered" is a CI-checkable property, not a judgement call. What's left is either dead CSS (delete it) or a state the crawl couldn't reach (drive it with a spec, or file the gap).
 

package/bin/styleproof-capture.mjs

@@ -51,6 +51,8 @@ whole surface: --crawl
   --no-data-states  skip the automatic loading/error captures of the entry page
                     (on by default: data requests stalled → loading skeleton;
                     fulfilled with 500 → error render)
+  --workers <n>     concurrent sweep workers (default 4); same surface set as a
+                    serial crawl — pass 1 for byte-stable key attribution
   --max-depth <n>   throttle recursion depth (default: unbounded)
   --max-actions <n> throttle controls tried per state (default: unbounded)
   --max-states <n>  throttle total surfaces (default: unbounded)
@@ -105,6 +107,10 @@ async function runCrawl() {
       resetStorage: opts.resetStorage,
       setup: setupSteps,
       dataStates: opts.dataStates,
+      stopWhenCovered: opts.untilCovered,
+      workers: opts.workers,
+      // each worker page in its OWN context, so storage resets can't interfere
+      newPage: async () => (await browser.newContext()).newPage(),
       // Stream each surface as it is captured, so progress is visible live and an
       // interrupted run still shows exactly what it mapped.
       onSurface: (s, ok) =>

package/dist/capture-url.d.ts

@@ -56,6 +56,11 @@ export type CaptureUrlOptions = {
     /** crawl: exit non-zero unless every class the page's stylesheets define was
      *  rendered in at least one captured surface (default false — report only). */
     requireFullCoverage: boolean;
+    /** crawl: stop as soon as coverage is complete (every defined class seen) or
+     *  has converged (no new class for a plateau of surfaces). Turns the crawl
+     *  into a FAST coverage check that stops once it has seen everything, instead
+     *  of enumerating every combinatorial surface. Default false (exhaustive). */
+    untilCovered: boolean;
     /** crawl: JSON file of deterministic setup steps (login, unlock, seed input)
      *  run after every fresh navigation. See {@link loadSetupSteps}. */
     setupFile?: string;
@@ -65,6 +70,8 @@ export type CaptureUrlOptions = {
     /** crawl: also capture automatic `loading`/`error` data states of the entry
      *  page (default true). */
     dataStates: boolean;
+    /** crawl: concurrent sweep workers (default 4). 1 = byte-stable key attribution. */
+    workers: number;
 };
 /**
  * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI

package/dist/capture-url.js

@@ -31,7 +31,9 @@ const DEFAULTS = {
     maxStates: 100000,
     resetStorage: true,
     requireFullCoverage: false,
+    untilCovered: false,
     dataStates: true,
+    workers: 4,
 };
 function positiveNumber(raw, flag) {
     const n = Number(raw);
@@ -62,6 +64,7 @@ const VALUE_FLAGS = {
     '--max-actions': (o, v) => (o.maxActionsPerState = positiveNumber(v, '--max-actions')),
     '--max-states': (o, v) => (o.maxStates = positiveNumber(v, '--max-states')),
     '--setup': (o, v) => (o.setupFile = v),
+    '--workers': (o, v) => (o.workers = positiveNumber(v, '--workers')),
 };
 const BOOL_FLAGS = {
     '--screenshots': (o) => (o.screenshots = true),
@@ -69,6 +72,7 @@ const BOOL_FLAGS = {
     '--crawl': (o) => (o.crawl = true),
     '--no-reset-storage': (o) => (o.resetStorage = false),
     '--require-full-coverage': (o) => (o.requireFullCoverage = true),
+    '--until-covered': (o) => (o.untilCovered = true),
     '--data-states': (o) => (o.dataStates = true),
     '--no-data-states': (o) => (o.dataStates = false),
 };
@@ -117,8 +121,10 @@ export function parseCaptureUrlArgs(argv) {
         maxStates: DEFAULTS.maxStates,
         resetStorage: DEFAULTS.resetStorage,
         requireFullCoverage: DEFAULTS.requireFullCoverage,
+        untilCovered: DEFAULTS.untilCovered,
         setupFile: undefined,
         dataStates: DEFAULTS.dataStates,
+        workers: DEFAULTS.workers,
     };
     const positional = [];
     for (let i = 0; i < argv.length; i++)

package/dist/crawl-surfaces.d.ts

@@ -90,6 +90,14 @@ export type SurfaceCrawlOptions = {
      *  requests stalled — the skeleton) and `error` (data requests fulfilled with
      *  a 500). Default true; states that render identically to base are skipped. */
     dataStates?: boolean;
+    /** Coverage-oriented termination: stop as soon as every class the page's
+     *  stylesheets define has been rendered (full coverage) OR coverage stops
+     *  improving (no new class for a plateau of surfaces — it has converged short
+     *  of full, and the rest is dead CSS or a genuinely-gated state). Off by
+     *  default (exhaustive: map every surface). On, the crawl is a fast coverage
+     *  check — it stops the moment it has SEEN everything, instead of enumerating
+     *  every combinatorial surface that adds no new vocabulary. */
+    stopWhenCovered?: boolean;
     /** Throttle: recursion depth into opened surfaces (base = 0). Default: unbounded. */
     maxDepth: number;
     /** Throttle: fresh controls driven per state. Default: unbounded — try them all. */
@@ -101,6 +109,15 @@ export type SurfaceCrawlOptions = {
     /** Called as each surface is recorded (captured=false when its full capture failed).
      *  Lets CLIs stream progress instead of reporting only at the end. */
     onSurface?: (surface: CrawledSurface, captured: boolean) => void;
+    /** Concurrent sweep workers (default 4). Each worker gets its own page from
+     *  `newPage`; without a factory the crawl runs single-page regardless. The
+     *  surface SET is identical to a serial crawl (same dedup sets); only which
+     *  path first claims a shape — and so dup-key suffixes — can vary run to run.
+     *  Use workers: 1 for byte-stable key attribution. */
+    workers?: number;
+    /** Factory for worker pages — create each in its OWN browser context so
+     *  storage resets cannot interfere across concurrent sweeps. */
+    newPage?: () => Promise<Page>;
 };
 export declare const CRAWL_DEFAULTS: {
     height: number;
@@ -109,14 +126,10 @@ export declare const CRAWL_DEFAULTS: {
     maxActionsPerState: number;
     maxStates: number;
     resetStorage: boolean;
+    workers: number;
 };
 /** Run the caller's deterministic setup steps (login, unlock, seed input). A
  *  non-optional step that fails throws loudly — a half-established gate must
  *  never silently crawl the ungated page instead. */
 export declare function runSetup(page: Page, steps: SetupStep[]): Promise<void>;
-/**
- * Crawl `opts.url` and capture every reachable surface at every width — runs to
- * natural termination by default. Returns the surfaces mapped (with the click-path
- * that reached each), how many actions were tried/skipped, and captured/failed.
- */
 export declare function crawlAndCapture(page: Page, opts: SurfaceCrawlOptions): Promise<CrawlReport>;

package/dist/crawl-surfaces.js

@@ -7,10 +7,18 @@ import { detectViewportWidths } from './breakpoints.js';
 export const CRAWL_DEFAULTS = {
     height: 900,
     screenshots: true,
-    maxDepth: 1000,
+    // ponytail: depth 16 is exhaustive for real UI — no human-navigable surface
+    // is 16 clicks from load. Past that you're not finding surfaces, you're
+    // riding an append-generator (a composer that adds a row per click) whose
+    // every appended node is a fresh tag-path identity, so it recurses forever.
+    // The cap terminates those chains; the coverage verifier still NAMES any
+    // class left unrendered, so a too-low cap fails loudly rather than lying.
+    // Raise with --max-depth if a design genuinely nests deeper.
+    maxDepth: 16,
     maxActionsPerState: 100000,
     maxStates: 100000,
     resetStorage: true,
+    workers: 4,
 };
 function slug(value) {
     return (value
@@ -40,7 +48,7 @@ function deriveKey(steps, used) {
 /* c8 ignore start */ // fallow-ignore-next-line complexity
 function collectClickable() {
     const SEMANTIC = 'button,summary,[role="button"],[role="tab"],[role="menuitem"],[role="combobox"],select,form';
-    const DANGER = /\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop)\b/i;
+    const DANGER = /\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\b/i;
     const esc = (v) => CSS.escape(v);
     const quote = (v) => JSON.stringify(v);
     const visible = (el) => {
@@ -77,6 +85,19 @@ function collectClickable() {
         .replace(/\s+/g, ' ')
         .trim()
         .slice(0, 80) || el.tagName.toLowerCase();
+    const identityFor = (el) => {
+        // Tag-path only — NO classes and NO indices: classes carry state (body.alt,
+        // .on) and would re-contextualize the same control per mode; indices carry
+        // position and drift on re-render. Tag ancestry + label is what stays
+        // stable across every context the same logical control appears in.
+        const parts = [];
+        let cur = el;
+        while (cur && cur !== document.documentElement) {
+            parts.unshift(cur.tagName.toLowerCase());
+            cur = cur.parentElement;
+        }
+        return `${parts.join('>')}|${labelFor(el)}|${el.getAttribute('role') ?? ''}`;
+    };
     // Semantic controls first (stable, meaningful), then anything styled clickable.
     // `grab` counts too: a draggable card is routinely ALSO a click target (open on
     // click, drag to move), and we never drag — el.click() fires no drag gesture.
@@ -85,7 +106,28 @@ function collectClickable() {
         if (pool.has(el))
             continue;
         const cursor = getComputedStyle(el).cursor;
-        if (cursor === 'pointer' || cursor === 'grab')
+        if (cursor !== 'pointer' && cursor !== 'grab')
+            continue;
+        // `cursor` is an INHERITED property: a clickable card makes every descendant
+        // compute cursor:pointer, and clicking any descendant just bubbles to the
+        // card's own handler — the SAME surface. Left unchecked, a card with N
+        // children becomes N+1 candidates, each paying a drive + verified reset to
+        // map one surface (the dominant cost of a large crawl). Add only the
+        // OUTERMOST clickable in an inherited-cursor subtree: skip when an ancestor
+        // is already a candidate. Semantic controls (button, a, [role]) are seeded
+        // above and skipped by the guard at the top of the loop, so a real button
+        // nested inside a clickable card is never dropped. (querySelectorAll walks
+        // document order, so an ancestor is always pooled before its descendants.)
+        let anc = el.parentElement;
+        let nested = false;
+        while (anc && anc !== document.body) {
+            if (pool.has(anc)) {
+                nested = true;
+                break;
+            }
+            anc = anc.parentElement;
+        }
+        if (!nested)
             pool.add(el);
     }
     // Neutral text inputs are typed automatically with a deterministic value —
@@ -117,6 +159,7 @@ function collectClickable() {
         out.push({
             action: 'fill-input',
             selector,
+            identity: identityFor(el),
             label: labelFor(el) === el.tagName.toLowerCase() ? (el.getAttribute('placeholder') ?? 'input') : labelFor(el),
             reason: 'auto-fill',
             value: AUTO_VALUE[kind] ?? 'sample text',
@@ -139,12 +182,21 @@ function collectClickable() {
         if (el instanceof HTMLSelectElement) {
             const next = [...el.options].find((o) => !o.disabled && o.value !== el.value);
             if (next)
-                out.push({ action: 'select-option', selector, label, reason: 'select-option', value: next.value, unsafe });
+                out.push({
+                    action: 'select-option',
+                    selector,
+                    identity: identityFor(el),
+                    label,
+                    reason: 'select-option',
+                    value: next.value,
+                    unsafe,
+                });
         }
         else {
             out.push({
                 action: 'click',
                 selector,
+                identity: identityFor(el),
                 label,
                 reason: el.getAttribute('role') === 'tab' ? 'tab' : 'click',
                 unsafe,
@@ -179,6 +231,17 @@ function domShape() {
     for (const el of document.body.getElementsByTagName('*')) {
         if (SKIP.has(el.tagName))
             continue;
+        // Skip non-page artifacts that pollute the fingerprint: StyleProof's own
+        // injected hover-sink (added by a capture, so present when a state is
+        // captured in place but NOT on a fresh load) and framework route-announcers.
+        // Counting them made a state's in-place fingerprint differ from its
+        // reset+replay fingerprint, so every reset to depth >= 2 failed verification
+        // (and the same pollution split dedup, capturing one surface as two). They
+        // are not part of the page.
+        if (el.hasAttribute('data-styleproof-hover-sink'))
+            continue;
+        if (el.tagName === 'NEXT-ROUTE-ANNOUNCER' || el.id === '__next-route-announcer__')
+            continue;
         add(el);
     }
     return { shape: parts.join('\n'), elements: parts.length, classes: [...classes] };
@@ -243,15 +306,27 @@ async function settleDom(page, maxMs = 1200) {
  *  non-trivial. Generic — no app-specific selector needed, so a bare crawl of a
  *  Babel/React/Vue page that boots after `load` still captures the mounted UI. */
 async function waitSettled(page) {
-    await page.waitForLoadState('networkidle').catch(() => { });
+    // DOM-growth settle is the PRIMARY readiness signal — it detects an
+    // async-mounted app (the DOM stops growing and is non-trivial) without an
+    // app-specific selector, and it also catches fetch-painted content (that
+    // grows the DOM). We deliberately do NOT gate on networkidle: it waits a
+    // 500ms idle window ON TOP of any lingering request, and a single cross-origin
+    // asset — a Google-Fonts stylesheet — keeps the network "busy" ~1s per load
+    // with no bearing on readiness. gotoFresh runs once per state (plus per
+    // retry), so that dominated crawl time (measured: ~995ms of every ~1531ms
+    // reset). Instead we wait for FONTS specifically — they ARE part of the
+    // computed style the diff compares, so they must be loaded before capture,
+    // but document.fonts.ready is the deterministic signal (and resolves from the
+    // page's cache on repeat loads, so it's ~free after the first).
     let prev = -1;
     for (let i = 0; i < 40; i++) {
         const n = await page.evaluate(() => document.body.getElementsByTagName('*').length);
         if (n > 5 && n === prev)
-            return;
+            break;
         prev = n;
         await page.waitForTimeout(100);
     }
+    await page.evaluate(() => document.fonts.ready.then(() => true)).catch(() => { });
 }
 /**
  * Load the URL from a clean slate (storage cleared by the init script armed in
@@ -412,14 +487,43 @@ function stateKey(steps) {
 }
 /** Record a newly-found surface, capture it in place (page is already there), and
  *  queue it for its own sweep. Streams progress via onSurface. */
-async function record(page, opts, newPath, depth, fp, st, retryOnly = false) {
+async function record(page, opts, newPath, depth, fp, st, sink, retryOnly = false, viaRetry = false) {
     const key = deriveKey(newPath, st.used);
     const surface = { key, depth, path: newPath, elements: fp.elements };
     st.surfaces.push(surface);
-    st.queue.push({ path: newPath, depth, sig: fp.sig, retryOnly });
+    let addsVocab = false;
     for (const c of fp.classes)
-        st.classes.add(c);
-    await captureAndReport(page, opts, surface, st);
+        if (!st.classes.has(c)) {
+            st.classes.add(c);
+            addsVocab = true;
+        }
+    // Children buffer in the sweep's sink and enter the shared queue only when the
+    // parent's sweep completes — family retry reads the parent's changer registry,
+    // which is only complete then. (Serial mode passes st.queue directly.)
+    //
+    // COVERAGE-GUIDED QUEUE PRUNING: in --until-covered mode, a surface that adds
+    // NO new render vocabulary is a structural repeat (the ninth agent's dossier,
+    // identical to the first) — don't queue it for a sweep, because its subtree is
+    // the same repeats and contributes nothing to coverage. This is what turns the
+    // exhaustive breadth-first crawl into a FAST coverage check: the queue drains
+    // to the few distinct components, each still drilled to depth (its own new
+    // vocabulary keeps it queued) via now-reliable resets. Base (depth 0) always
+    // seeds. Exhaustive mode (default) queues everything, so the surface-by-surface
+    // diff still sees every state.
+    const keep = !opts.stopWhenCovered || addsVocab || depth === 0;
+    if (keep) {
+        sink.push({ path: newPath, depth, sig: fp.sig, retryOnly, viaRetry });
+    }
+    // Skip the expensive style-map capture (getComputedStyle over every element,
+    // per width) for coverage-redundant surfaces: in --until-covered mode a surface
+    // that adds no vocabulary needs no map — its classes were already counted from
+    // the fingerprint above — so paying the capture is pure waste. This is the
+    // difference between a fast coverage check and re-capturing hundreds of
+    // structural repeats. Distinct (vocab-adding) surfaces are still captured, so
+    // the run leaves a usable map set behind.
+    if (keep) {
+        await captureAndReport(page, opts, surface, st);
+    }
 }
 /** Capture the current page as `surface` at every width and report the outcome. */
 async function captureAndReport(page, opts, surface, st) {
@@ -451,7 +555,7 @@ async function tryInPlace(page, c) {
 }
 /** Drive one candidate from where the page stands. Returns whether the page is
  *  still in the swept state (no-op click) and whether the action was a skip. */
-async function driveCandidate(page, opts, entry, c, st) {
+async function driveCandidate(page, opts, entry, c, st, sink, viaRetry, presentIds = new Set()) {
     // (retry-only lineage is inherited: a consumed state's descendants can also
     // only be mode-switch views, never fresh-candidate exploration.)
     const outcome = await tryInPlace(page, c);
@@ -468,7 +572,7 @@ async function driveCandidate(page, opts, entry, c, st) {
         .catch(() => false);
     const from = stateKey(entry.path);
     const list = st.changersFrom.get(from) ?? [];
-    if (!list.some((x) => x.c.selector === c.selector))
+    if (!list.some((x) => x.c.identity === c.identity))
         list.push({ c, persists });
     st.changersFrom.set(from, list);
     const fp = await fingerprint(page);
@@ -482,7 +586,41 @@ async function driveCandidate(page, opts, entry, c, st) {
         reason: c.reason,
         ...(c.value ? { value: c.value } : {}),
     };
-    await record(page, opts, [...entry.path, step], entry.depth + 1, fp, st, entry.retryOnly || !persists);
+    const childPath = [...entry.path, step];
+    const childRetryOnly = entry.retryOnly || !persists;
+    await record(page, opts, childPath, entry.depth + 1, fp, st, sink, childRetryOnly, viaRetry);
+    // DESCEND IN PLACE. We are standing in the surface this click just opened,
+    // reached by a reliable forward click. Sweep its OWN fresh controls now, while
+    // we are here, rather than leaving it for the queued entry to re-reach by
+    // reset+replay. In EXHAUSTIVE mode this is the win: it maps a deep branch (an
+    // expanded run inside an expanded automation) while the page is already there,
+    // instead of via a fragile deep replay. The queued entry still executes for
+    // family-retry (pairwise) coverage; global `tried` means its fresh list is
+    // already empty here, so this does not double-drive.
+    //
+    // But descent is DEPTH-FIRST: it drills the first candidate's whole subtree
+    // before the base sweep reaches the next candidate, so a page whose distinct
+    // vocabulary lives across many components (a roster of dossiers) covers slowly.
+    // In --until-covered mode we therefore SKIP the in-place descent and let the
+    // breadth-first queue + coverage-guided pruning reach every component fast and
+    // drill each once — now that resets are reliable, the queue reaches depth too.
+    if (!opts.stopWhenCovered && persists && entry.depth + 1 < opts.maxDepth) {
+        const child = {
+            path: childPath,
+            depth: entry.depth + 1,
+            sig: fp.sig,
+            retryOnly: childRetryOnly,
+            viaRetry,
+        };
+        // Exclude controls that were ALSO present in the parent (mode-switchers,
+        // shared chrome): those are breadth, owned by the queued family-retry.
+        // Descend only into controls genuinely NEW to this surface — a run row that
+        // exists only after the job expanded — which is exactly the deep nested UI
+        // the reset-replay path starves.
+        await sweepCandidatesHere(page, opts, child, st, sink, /* freshOnly */ true, presentIds).catch(() => {
+            /* fail-soft: the surface was already captured; deeper descent is best-effort */
+        });
+    }
     return { inState: false, skipped: false };
 }
 /**
@@ -494,32 +632,61 @@ async function driveCandidate(page, opts, entry, c, st) {
 /** The family-retry list for a state: its parent's persistent mode-switchers that
  *  are visible right now — minus the step that created this state itself. */
 function familyRetries(entry, all, st) {
+    // RETRIES DO NOT COMPOUND: a state reached via a family retry still explores
+    // its genuinely-new UI (fresh selectors), but never re-retries mode-switchers.
+    // Every PAIRWISE mode combination is captured; N-way products of independent
+    // toggles are not walked — they multiply states without new render vocabulary,
+    // and anything class-visible only at 3-way depth is still NAMED by the
+    // coverage verifier.
+    if (entry.viaRetry)
+        return [];
     if (entry.path.length === 0)
         return [];
     const parentKey = stateKey(entry.path.slice(0, -1));
     const ownSelector = entry.path[entry.path.length - 1].selector;
-    const visibleNow = new Set(all.map((c) => c.selector));
+    // Match registered changers to THIS state's candidates by semantic identity —
+    // the mode switch re-rendered the subtree, so positional selectors drifted;
+    // the current candidate carries the right selector for this state.
+    const byIdentity = new Map(all.map((c) => [c.identity, c]));
     return (st.changersFrom.get(parentKey) ?? [])
-        .filter((x) => x.persists && x.c.selector !== ownSelector && visibleNow.has(x.c.selector))
-        .map((x) => x.c);
+        .filter((x) => x.persists && x.c.selector !== ownSelector)
+        .map((x) => byIdentity.get(x.c.identity))
+        .filter((c) => Boolean(c));
 }
 /** The work list for one state's sweep: fresh controls first (already-driven
  *  global chrome would otherwise starve a deep surface's own controls; the
  *  throttle applies to fresh ones), then the parent's persistent mode-switchers
  *  re-tried in THIS sibling mode. A state reached through a consuming action
- *  collects NO fresh candidates — see QueueEntry.retryOnly. */
-function sweepWorkList(entry, all, opts, st) {
-    const fresh = entry.retryOnly ? [] : all.filter((c) => !st.tried.has(c.selector)).slice(0, opts.maxActionsPerState);
+ *  collects NO fresh candidates — see QueueEntry.retryOnly.
+ *
+ *  `freshOnly` drops the family-retries: the in-place descent of a
+ *  freshly-opened surface explores its own new UI (DEPTH), but must NOT re-apply
+ *  the parent's mode-switchers — that is the pairwise BREADTH, owned by the
+ *  queued sweep. Re-applying them while descending would compound modes into
+ *  N-way products (the very thing "retries don't compound" prevents). */
+function sweepWorkList(entry, all, opts, st, freshOnly = false, excludeIds = new Set()) {
+    const fresh = entry.retryOnly
+        ? []
+        : all.filter((c) => !st.tried.has(c.identity) && !excludeIds.has(c.identity)).slice(0, opts.maxActionsPerState);
     return [
         ...fresh.map((c) => ({ c, retry: false })),
-        ...familyRetries(entry, all, st).map((c) => ({ c, retry: true })),
+        ...(freshOnly ? [] : familyRetries(entry, all, st).map((c) => ({ c, retry: true }))),
     ];
 }
-async function sweepState(page, opts, entry, st) {
-    if (!(await resetToState(page, opts, entry.path, entry.sig)))
-        return { tried: 0, skipped: 0 };
+/** Drive one state's work list from where the page ALREADY stands (no reset). A
+ *  no-op click leaves the page in the state and the loop continues; a
+ *  state-changing click drives the child in place (see driveCandidate) and then
+ *  a verified reset returns here before the next candidate. Split out from
+ *  sweepState so driveCandidate can call it to DESCEND a freshly-opened surface
+ *  in place — reaching that surface via a forward click is reliable, so its deep
+ *  descendants are captured on the first visit instead of via a later reset. */
+async function sweepCandidatesHere(page, opts, entry, st, sink, freshOnly = false, excludeIds = new Set()) {
     const all = await page.evaluate(collectClickable).catch(() => []);
-    const work = sweepWorkList(entry, all, opts, st);
+    const work = sweepWorkList(entry, all, opts, st, freshOnly, excludeIds);
+    // Controls present HERE — passed to each child's in-place descent as its
+    // exclude set, so the descent skips this surface's mode-switchers/chrome and
+    // only drills genuinely new nested UI.
+    const presentIds = new Set(all.map((c) => c.identity));
     let tried = 0;
     let skipped = 0;
     let inState = true;
@@ -532,19 +699,24 @@ async function sweepState(page, opts, entry, st) {
             inState = true;
         }
         if (!retry)
-            st.tried.add(c.selector);
+            st.tried.add(c.identity);
         if (c.unsafe) {
             skipped++;
             continue;
         }
         tried++;
-        const r = await driveCandidate(page, opts, entry, c, st);
+        const r = await driveCandidate(page, opts, entry, c, st, sink, retry, presentIds);
         inState = r.inState;
         if (r.skipped)
             skipped++;
     }
     return { tried, skipped };
 }
+async function sweepState(page, opts, entry, st, sink) {
+    if (!(await resetToState(page, opts, entry.path, entry.sig)))
+        return { tried: 0, skipped: 0 };
+    return sweepCandidatesHere(page, opts, entry, st, sink);
+}
 /** Capture one synthetic data state of the entry page (its data requests stalled
  *  or failed) in place, deduped and coverage-counted like any surface — but never
  *  queued: a stalled app is not a state to crawl deeper from. */
@@ -578,6 +750,81 @@ async function recordDataState(page, opts, mode, st) {
         await page.unroute('**/*');
     }
 }
+/**
+ * Sweep the queue with N concurrent workers, each on its own page. LIFO keeps
+ * the depth-first bias; a worker's discovered children enter the shared queue
+ * only when its sweep completes (see record). The surface SET matches a serial
+ * crawl — dedup sets are shared and mutated synchronously — only dup-key
+ * suffix attribution can vary with timing.
+ */
+async function runPool(primary, opts, st, counters, defined = []) {
+    const target = Math.max(1, opts.workers ?? 1);
+    const pages = [primary];
+    while (opts.newPage && pages.length < target) {
+        const extra = await opts.newPage();
+        if (opts.resetStorage)
+            await armResetStorage(extra);
+        pages.push(extra);
+    }
+    // Coverage-oriented early stop (opt-in): the moment every defined class has
+    // been SEEN, stop — the rest of the queue is redundant for a coverage check.
+    // We do NOT plateau-stop on "N surfaces without a new class": a productive
+    // deep state (an automation whose expandable run row is its last candidate)
+    // adds its vocabulary only after many no-new siblings, so a plateau cuts the
+    // crawl off before that state's sweep even starts. Termination instead comes
+    // from the queue draining — and it drains fast because coverage-guided pruning
+    // (see record) never queues a structural repeat. `cover.every` runs only when
+    // the class count actually grows, so this is cheap.
+    const cover = opts.stopWhenCovered && defined.length > 0 ? defined : null;
+    let prevSize = st.classes.size;
+    let covered = false;
+    const converged = () => {
+        if (!cover)
+            return false;
+        if (!covered && st.classes.size > prevSize) {
+            prevSize = st.classes.size;
+            if (cover.every((c) => st.classes.has(c)))
+                covered = true;
+        }
+        return covered;
+    };
+    let active = 0;
+    await new Promise((resolve) => {
+        const pump = () => {
+            while (pages.length > 0 && st.queue.length > 0 && st.surfaces.length < opts.maxStates && !converged()) {
+                const entry = st.queue.shift(); // FIFO → breadth-first: exhaust every
+                // shallow surface (nav tabs, opened panels — where distinct UI lives)
+                // before drilling. Depth-first starves breadth: one append-generator
+                // branch drills to depth 20+ while sibling tabs sit unpopped, so real
+                // surfaces (an OAuth card, a skills grid) go uncaptured. Dedup is
+                // set-based, so order never changes WHAT is found — only that shallow
+                // is found first, which is what full coverage needs.
+                if (entry.depth >= opts.maxDepth)
+                    continue;
+                const worker = pages.pop();
+                active++;
+                const sink = [];
+                sweepState(worker, opts, entry, st, sink)
+                    .then((r) => {
+                    counters.tried += r.tried;
+                    counters.skipped += r.skipped;
+                })
+                    .catch(() => {
+                    /* fail-soft: the state's surface was already captured in place */
+                })
+                    .finally(() => {
+                    st.queue.push(...sink);
+                    pages.push(worker);
+                    active--;
+                    pump();
+                });
+            }
+            if (active === 0 && (st.queue.length === 0 || st.surfaces.length >= opts.maxStates || converged()))
+                resolve();
+        };
+        pump();
+    });
+}
 /** Depth-first discovery + in-place capture of every reachable surface. Depth-first
  *  so a surface's OWN sub-states (a modal's tab → its toggles) are mapped while the
  *  branch is fresh; with no budget, order affects time-to-depth, not coverage. */
@@ -617,7 +864,7 @@ async function discover(page, opts) {
         captured: 0,
         failed: [],
     };
-    await record(page, opts, [], 0, fp, st, false);
+    await record(page, opts, [], 0, fp, st, st.queue, false, false);
     // Automatic data states of the entry page — the loading skeleton and the
     // error render exist in every data-driven app but almost never in a click
     // path. Captured out of the box; identical-to-base renders dedup away.
@@ -625,21 +872,13 @@ async function discover(page, opts) {
         await recordDataState(page, opts, 'loading', st);
         await recordDataState(page, opts, 'error', st);
     }
-    let actionsTried = 0;
-    let skipped = 0;
-    while (st.queue.length > 0 && st.surfaces.length < opts.maxStates) {
-        const entry = st.queue.pop(); // LIFO → depth-first
-        if (entry.depth >= opts.maxDepth)
-            continue;
-        const r = await sweepState(page, opts, entry, st);
-        actionsTried += r.tried;
-        skipped += r.skipped;
-    }
+    const counters = { tried: 0, skipped: 0 };
+    await runPool(page, opts, st, counters, defined);
     const missing = defined.filter((c) => !st.classes.has(c)).sort();
     return {
         surfaces: st.surfaces,
-        actionsTried,
-        skipped,
+        actionsTried: counters.tried,
+        skipped: counters.skipped,
         captured: st.captured,
         failed: st.failed,
         coverage: { defined: defined.length, rendered: defined.length - missing.length, missing },
@@ -650,19 +889,21 @@ async function discover(page, opts) {
  * natural termination by default. Returns the surfaces mapped (with the click-path
  * that reached each), how many actions were tried/skipped, and captured/failed.
  */
+/** Clear storage before the app's code runs on EVERY load, so each gotoFresh is
+ *  a clean slate in one navigation (no clear-then-reload round trip). */
+async function armResetStorage(page) {
+    await page.addInitScript(() => {
+        try {
+            localStorage.clear();
+            sessionStorage.clear();
+        }
+        catch {
+            /* storage unavailable (e.g. file://) — ignore */
+        }
+    });
+}
 export async function crawlAndCapture(page, opts) {
-    if (opts.resetStorage) {
-        // Clear storage before the app's code runs on EVERY load, so each gotoFresh is
-        // a clean slate in one navigation (no clear-then-reload round trip).
-        await page.addInitScript(() => {
-            try {
-                localStorage.clear();
-                sessionStorage.clear();
-            }
-            catch {
-                /* storage unavailable (e.g. file://) — ignore */
-            }
-        });
-    }
+    if (opts.resetStorage)
+        await armResetStorage(page);
     return discover(page, opts);
 }

package/dist/describe.js

@@ -18,7 +18,10 @@ const PALETTE = [
     ['pink', [236, 64, 122]],
 ];
 function parseColor(v) {
-    const m = v.match(/rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)(?:[,/\s]+([\d.]+))?\s*\)/i);
+    // Anchored: only a value that IS a colour parses. An embedded colour inside a
+    // gradient/shadow/url must not stand in for the whole value — that once made a
+    // report show the same "representative" rgba on both sides of a real diff.
+    const m = v.match(/^rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)(?:[,/\s]+([\d.]+))?\s*\)$/i);
     if (!m)
         return null;
     return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] === undefined ? 1 : Number(m[4])];

package/dist/report.d.ts

@@ -71,4 +71,5 @@ export type ReportResult = {
 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 function excerptPair(before: string, after: string): [string, string];
 export declare function generateStyleMapReport(opts: ReportOptions): ReportResult;

package/dist/report.js

@@ -292,7 +292,9 @@ const orderIdx = (p) => {
     return i === -1 ? PROP_ORDER.length : i;
 };
 function cleanVal(v) {
-    let s = v.replace(/-?\d+\.\d+/g, (m) => String(Math.round(parseFloat(m) * 10) / 10));
+    // Verbatim by design: no rounding. Rounding once showed alpha 0.18 as 0.2 —
+    // and could erase a real 0.18→0.2 diff entirely via the no-op filter below.
+    let s = v;
     if (!s.includes('(')) {
         const toks = s.split(' ');
         if (toks.length > 1 && new Set(toks).size === 1)
@@ -512,11 +514,48 @@ function regionHeading(regionPaths, findings) {
 // A "no value here" marker renders as an em dash; colours render as `#hex` so the
 // table cell shows GitHub's live swatch.
 const cell = (v) => (isNonValue(v) ? '—' : `\`${toHex(v)}\``);
+// Long values (gradients, data URIs) would swamp the table, but truncating each
+// side independently can show two IDENTICAL cells for a real diff: both
+// sides of a gradient rendered as the same rgba while the actual change — a
+// dropped `0px` stop — was elsewhere in the string. Instead, trim the shared
+// prefix/suffix and show each side's differing substring with a little context.
+const EXCERPT_AT = 64; // both sides at or under this → show whole values
+const EXCERPT_CTX = 12; // chars of shared context kept around the diff
+const EXCERPT_MAX = 96; // hard cap per excerpt; the diff itself may be huge
+export function excerptPair(before, after) {
+    if (before.length <= EXCERPT_AT && after.length <= EXCERPT_AT)
+        return [before, after];
+    let p = 0;
+    while (p < before.length && p < after.length && before[p] === after[p])
+        p++;
+    let s = 0;
+    const maxS = Math.min(before.length, after.length) - p;
+    while (s < maxS && before[before.length - 1 - s] === after[after.length - 1 - s])
+        s++;
+    const cut = (v) => {
+        const start = Math.max(0, p - EXCERPT_CTX);
+        let end = Math.min(v.length, v.length - s + EXCERPT_CTX);
+        if (end - start > EXCERPT_MAX)
+            end = start + EXCERPT_MAX;
+        return (start > 0 ? '…' : '') + v.slice(start, end) + (end < v.length ? '…' : '');
+    };
+    return [cut(before), cut(after)];
+}
+/** Before/After cells as a pair, so long values excerpt around their actual diff. */
+function cellPair(before, after) {
+    if (isNonValue(before) || isNonValue(after))
+        return [cell(before), cell(after)];
+    const [b, a] = excerptPair(before, after);
+    return [`\`${toHex(b)}\``, `\`${toHex(a)}\``];
+}
 function beforeAfterTable(rows) {
     return [
         '| Property | Before | After |',
         '| --- | --- | --- |',
-        ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.before)} | ${cell(r.after)} |`),
+        ...rows.map((r) => {
+            const [b, a] = cellPair(r.before, r.after);
+            return `| \`${r.prop}\` | ${b} | ${a} |`;
+        }),
     ];
 }
 // A brand-new element has no meaningful "before", so its resting style renders
@@ -546,10 +585,12 @@ function styleSection(styles, added) {
 function statesSection(states, added) {
     const rows = [];
     for (const st of states)
-        for (const c of summarizeProps(st.props))
+        for (const c of summarizeProps(st.props)) {
+            const [b, a] = cellPair(c.before, c.after);
             rows.push(added
                 ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
-                : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
+                : `| \`:${st.state}\` | \`${c.prop}\` | ${b} → ${a} |`);
+        }
     if (!rows.length)
         return [];
     return [

package/package.json

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