styleproof 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ 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.
@@ -20,23 +55,51 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
-- Control identity is now SEMANTIC, not positional: the driven-once dedup keys
-  on tag ancestry (no indices, no classes) + label + role — what stays stable
-  across every re-render — instead of nth-of-type selectors. Mode switches
-  re-render subtrees and re-mint positional selectors for the same logical
-  controls, which made every combination view refill the fresh-candidate pool
-  (a crawl inflated past 2,500 surfaces through that leak). Positional clones
-  with identical tag-path AND label (a repeated row's expand button) merge —
-  one is explored; distinctly-labeled controls stay distinct; anything hidden
-  behind a merge is still NAMED by the coverage verifier.
-- Family retries no longer compound: a state reached via a retry still explores
-  its genuinely-new UI, but never re-retries mode-switchers. Every PAIRWISE
-  combination of independent modes is captured (a tab's edit state, a decided
-  list's other tab); 3-way-and-deeper toggle products — which multiply surfaces
-  without new render vocabulary — are not walked. Observed live: an exhaustive
-  crawl inflated past 725 surfaces in the N-way product tail; the pairwise walk
-  covers the same vocabulary in a fraction of the states. Anything class-visible
-  only at deeper combination depth is still NAMED by the coverage verifier.
+- 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
 

package/bin/styleproof-capture.mjs

@@ -107,6 +107,7 @@ 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(),

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;

package/dist/capture-url.js

@@ -31,6 +31,7 @@ const DEFAULTS = {
     maxStates: 100000,
     resetStorage: true,
     requireFullCoverage: false,
+    untilCovered: false,
     dataStates: true,
     workers: 4,
 };
@@ -71,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),
 };
@@ -119,6 +121,7 @@ export function parseCaptureUrlArgs(argv) {
         maxStates: DEFAULTS.maxStates,
         resetStorage: DEFAULTS.resetStorage,
         requireFullCoverage: DEFAULTS.requireFullCoverage,
+        untilCovered: DEFAULTS.untilCovered,
         setupFile: undefined,
         dataStates: DEFAULTS.dataStates,
         workers: DEFAULTS.workers,

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. */

package/dist/crawl-surfaces.js

@@ -7,7 +7,14 @@ 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,
@@ -41,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) => {
@@ -99,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 —
@@ -203,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] };
@@ -267,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
@@ -440,13 +491,39 @@ async function record(page, opts, newPath, depth, fp, st, sink, retryOnly = fals
     const key = deriveKey(newPath, st.used);
     const surface = { key, depth, path: newPath, elements: fp.elements };
     st.surfaces.push(surface);
+    let addsVocab = false;
+    for (const c of fp.classes)
+        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.)
-    sink.push({ path: newPath, depth, sig: fp.sig, retryOnly, viaRetry });
-    for (const c of fp.classes)
-        st.classes.add(c);
-    await captureAndReport(page, opts, surface, st);
+    //
+    // 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) {
@@ -478,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, sink, viaRetry) {
+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);
@@ -509,7 +586,41 @@ async function driveCandidate(page, opts, entry, c, st, sink, viaRetry) {
         reason: c.reason,
         ...(c.value ? { value: c.value } : {}),
     };
-    await record(page, opts, [...entry.path, step], entry.depth + 1, fp, st, sink, entry.retryOnly || !persists, viaRetry);
+    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 };
 }
 /**
@@ -546,19 +657,36 @@ function familyRetries(entry, all, st) {
  *  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.identity)).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, sink) {
-    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;
@@ -577,13 +705,18 @@ async function sweepState(page, opts, entry, st, sink) {
             continue;
         }
         tried++;
-        const r = await driveCandidate(page, opts, entry, c, st, sink, retry);
+        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. */
@@ -624,7 +757,7 @@ async function recordDataState(page, opts, mode, st) {
  * crawl — dedup sets are shared and mutated synchronously — only dup-key
  * suffix attribution can vary with timing.
  */
-async function runPool(primary, opts, st, counters) {
+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) {
@@ -633,11 +766,39 @@ async function runPool(primary, opts, st, counters) {
             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) {
-                const entry = st.queue.pop(); // LIFO → depth-first
+            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();
@@ -658,7 +819,7 @@ async function runPool(primary, opts, st, counters) {
                     pump();
                 });
             }
-            if (active === 0 && (st.queue.length === 0 || st.surfaces.length >= opts.maxStates))
+            if (active === 0 && (st.queue.length === 0 || st.surfaces.length >= opts.maxStates || converged()))
                 resolve();
         };
         pump();
@@ -712,7 +873,7 @@ async function discover(page, opts) {
         await recordDataState(page, opts, 'error', st);
     }
     const counters = { tried: 0, skipped: 0 };
-    await runPool(page, opts, st, counters);
+    await runPool(page, opts, st, counters, defined);
     const missing = defined.filter((c) => !st.classes.has(c)).sort();
     return {
         surfaces: st.surfaces,

package/package.json

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