styleproof 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-07-02
+
+### Fixed
+
+- Consuming actions (controls that disappear when used — resolve/approve/dismiss
+  rows) no longer spawn a combinatorial decision lattice. Their result-states are
+  captured and swept RETRY-ONLY: the parent's persistent mode-switchers still
+  apply (a resolved list's tab view stays reachable), but no fresh candidates are
+  collected there — removed rows shift sibling nth-of-type selectors, which made
+  the same logical controls look "fresh" in every decided subset and could stall
+  an exhaustive crawl for hours adding zero coverage. Found live, on a
+  decision-heavy page whose crawl went 449 surfaces / 6 new classes before the
+  rule; with it, the same shape converges in single digits with full coverage.
+
+### Added
+
+- `styleproof-capture --setup <file>`: deterministic steps (goto/fill/click/
+  waitFor) run after every fresh navigation, so input-gated states — a login,
+  an unlock code, seeded input — become crawlable. `${ENV_VAR}` in values is
+  interpolated from the environment at load time, so credentials never live in
+  the file or the maps; a failed non-optional step aborts loudly.
+- Automatic data states: the crawl watches the entry page's data requests and
+  additionally captures `loading` (requests stalled — the skeleton) and `error`
+  (requests fulfilled with 500) out of the box. Identical-to-base renders dedup
+  away; `--no-data-states` to skip.
+- README: "What the crawler can and cannot reach — honestly" — the crawl
+  vocabulary, what each state class is reached by, and the verifier contract
+  that anything unreached is named, never silently missed.
+- Automatic neutral-input fill: text/search/email/tel/url/number inputs and
+  textareas are typed with a deterministic value, so input-driven states (a
+  search's results, a filter's rendering) are crawled with no config.
+  Credential-semantic fields (type=password, autocomplete username/
+  current-password/new-password/one-time-code) are never auto-filled — that is
+  `--setup` territory, the only input the tool cannot derive.
+- Automatic scroll reveal: a bounded, deterministic scroll pass on every load
+  mounts IntersectionObserver/lazy content before discovery, so scroll-gated
+  sections are part of the mapped surface.
+- The crawl now auto-detects the page's real `@media` breakpoints when no
+  `--widths` are given (like the one-shot path), sweeping one width per band.
+- `--setup` steps are honoured by the one-shot (non-crawl) capture too, so a
+  gated page's single state is capturable directly.
+
+### Fixed
+
+- Automatic data states now intercept by resource type (fetch/XHR) instead of
+  exact URL — apps that cache-bust their requests (`?t=...`) previously
+  slipped past the stall and produced no `loading` capture.
+
 ## [3.3.0] - 2026-07-02
 
 ### Added

package/README.md

@@ -430,6 +430,47 @@ What makes exhaustive affordable is that the sweep works **in place**: standing
 
 **Destructive-looking controls (delete, deploy, pay, revoke…) are never clicked** — mapping must not mutate; states gated behind one of those need a spec. Prefer the spec-driven `defineStyleMapCapture` when you want stable, named keys and the coverage guard; reach for `--crawl` to map a design (or a third-party page) you don't have a spec for.
 
+### Data states, out of the box
+
+Every data-driven page has states that almost never sit on a click path: the **loading skeleton** and the **error render**. The crawl captures both automatically — it watches the entry page's data requests, then re-loads once with them **stalled** (the skeleton is the settled state, captured as `loading`) and once with them **fulfilled as 500** (captured as `error`). States that render identically to the base (e.g. server-rendered pages) dedup away silently. On by default; `--no-data-states` to skip. Deeper data states — a specific empty list, a partial payload — are fixture territory: model them as `liveStates`/`variants` in a spec.
+
+### Input-gated states: `--setup`
+
+A crawler clicks and selects; it does not guess your password. States behind typed input — a login, an unlock code, a seeded search — become crawlable with a deterministic setup file, run after **every** fresh navigation so each reset re-establishes the gate identically:
+
+```json
+[
+  { "action": "fill", "selector": "#user", "value": "${CAPTURE_USER}" },
+  { "action": "fill", "selector": "#pass", "value": "${CAPTURE_PASS}" },
+  { "action": "click", "selector": "#sign-in" },
+  { "action": "waitFor", "selector": ".dashboard" }
+]
+```
+
+```bash
+CAPTURE_USER=demo CAPTURE_PASS=… styleproof-capture https://example.com --crawl --setup login.json --out design
+```
+
+`${ENV_VAR}` in `value`/`url` is interpolated from the environment at load time — **credentials never live in the file, the shell history, or the captured maps.** A non-optional step that fails aborts the crawl loudly (a half-established gate must never silently crawl the ungated page); mark a step `"optional": true` when it legitimately may not apply (a cookie-session app that shows the login form only once).
+
+### What the crawler can and cannot reach — honestly
+
+The crawl's vocabulary is **click, select, neutral typing, scrolling, and your setup steps** — and it sweeps the page's real `@media` breakpoints automatically when you give it none. Within it, mapping is exhaustive. Outside it, states are not reached by crawling — and the coverage verifier is what keeps that honest: anything unreached is _named_, never silently missed.
+
+| State                                                                        | Reached by                                                                                                                                                                            |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Click-opened surfaces (modals, drawers, popovers, tabs, toggles)             | crawl, automatically                                                                                                                                                                  |
+| Mode × sibling combinations (a tab's edit state, a decided list's other tab) | crawl — family retry                                                                                                                                                                  |
+| Loading / error data states of the entry page                                | crawl — automatic data states                                                                                                                                                         |
+| Login / unlock / typed input                                                 | `--setup` steps                                                                                                                                                                       |
+| `:hover` / `:focus` / `:active` styling                                      | the forced-state layer of every capture                                                                                                                                               |
+| Deeper data states (empty, partial, streaming)                               | spec `liveStates` / `variants` with fixtures                                                                                                                                          |
+| States behind destructive actions                                            | a spec, deliberately — the crawl never clicks them                                                                                                                                    |
+| Drag-and-drop, keyboard-shortcut, scroll-triggered states                    | a spec driving them explicitly                                                                                                                                                        |
+| Components not mounted anywhere in the UI                                    | a component catalog page (each component per prop-state is a surface — Storybook/Ladle stories work; `discoverComponentFiles` fails CI when a component file has no captured surface) |
+
+The rule of thumb: **a rendered state is a function of props, data, and input.** Control all three — mock the data, script the input, mount the component — and every state a component can render is a capturable surface. The verifier tells you, by name, which ones you haven't controlled yet.
+
 ## Install
 
 ```bash

package/bin/styleproof-capture.mjs

@@ -18,7 +18,7 @@
  */
 import { chromium } from '@playwright/test';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
-import { UsageError, parseCaptureUrlArgs, runCaptureUrl } from '../dist/capture-url.js';
+import { UsageError, parseCaptureUrlArgs, runCaptureUrl, loadSetupSteps } from '../dist/capture-url.js';
 import { crawlAndCapture } from '../dist/crawl-surfaces.js';
 
 const COMMAND = 'styleproof-capture';
@@ -32,7 +32,7 @@ one state (default): capture the page as it loads
   --wait <selector> wait for this selector to be visible before capturing
   --widths <csv>    viewport widths, e.g. 1440,1024,768. Omit to detect the
                     page's own @media breakpoints (fails on cross-origin CSS —
-                    pass widths for those). Crawl defaults to 1280 when omitted.
+                    pass widths for those). The crawl auto-detects too.
 
 whole surface: --crawl
   --crawl           EXHAUSTIVE: drive every non-destructive control, recurse into
@@ -44,6 +44,13 @@ whole surface: --crawl
                     exit 4 unless every class the page's stylesheets define was
                     rendered in a captured surface — the machine check that
                     NOTHING in the design was missed (coverage is always printed)
+  --setup <file>    JSON steps (goto/fill/click/waitFor) run after EVERY fresh
+                    navigation — how input-gated states (login, unlock) become
+                    crawlable. \${ENV_VAR} in value/url is read from the
+                    environment, so secrets never live in the file or the maps.
+  --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)
   --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)
@@ -67,8 +74,11 @@ const argv = process.argv.slice(2);
 if (isHelpArg(argv[0])) showHelpAndExit(HELP);
 
 let opts;
+let setupSteps;
 try {
   opts = parseCaptureUrlArgs(argv);
+  setupSteps = opts.setupFile ? loadSetupSteps(opts.setupFile) : undefined;
+  opts.setup = setupSteps; // one-shot capture honours setup steps too
 } catch (e) {
   if (e instanceof UsageError) {
     console.error(`${COMMAND}: ${e.message}\nNext: run ${COMMAND} --help to see supported options.`);
@@ -84,7 +94,7 @@ async function runCrawl() {
     const crawlOpts = {
       url: opts.url,
       out: opts.out,
-      widths: opts.widths.length ? opts.widths : [1280],
+      widths: opts.widths, // empty = auto-detect the page's real breakpoints
       ignore: opts.ignore,
       height: opts.height,
       screenshots: opts.screenshots,
@@ -93,6 +103,8 @@ async function runCrawl() {
       maxActionsPerState: opts.maxActionsPerState,
       maxStates: opts.maxStates,
       resetStorage: opts.resetStorage,
+      setup: setupSteps,
+      dataStates: opts.dataStates,
       // 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

@@ -1,4 +1,5 @@
 import type { Browser, Page } from '@playwright/test';
+import { type SetupStep } from './crawl-surfaces.js';
 /**
  * One-shot capture of a single URL's computed-style map — no spec, no config,
  * no git. `defineStyleMapCapture` is the right tool when the surfaces live in
@@ -55,6 +56,15 @@ 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: JSON file of deterministic setup steps (login, unlock, seed input)
+     *  run after every fresh navigation. See {@link loadSetupSteps}. */
+    setupFile?: string;
+    /** Loaded setup steps (set by the CLI from `setupFile`); applied after every
+     *  navigation in BOTH modes, so a gated page's single state is capturable too. */
+    setup?: SetupStep[];
+    /** crawl: also capture automatic `loading`/`error` data states of the entry
+     *  page (default true). */
+    dataStates: boolean;
 };
 /**
  * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI
@@ -78,3 +88,10 @@ export type CaptureUrlResult = {
 export declare function captureUrlToDir(page: Page, opts: CaptureUrlOptions): Promise<CaptureUrlResult[]>;
 /** Launch Chromium, capture the URL, and close — the whole bin body given parsed options. */
 export declare function runCaptureUrl(opts: CaptureUrlOptions, launch: () => Promise<Browser>): Promise<CaptureUrlResult[]>;
+/**
+ * Load and validate a `--setup` steps file, interpolating `${ENV_VAR}` in every
+ * `value` and `url` from the environment — so credentials for an input-gated
+ * page live in env vars, never in the file, the shell history, or the maps.
+ * Throws {@link UsageError} on a malformed file or a missing variable.
+ */
+export declare function loadSetupSteps(file: string, env?: NodeJS.ProcessEnv): SetupStep[];

package/dist/capture-url.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { detectViewportWidths } from './breakpoints.js';
+import { runSetup } from './crawl-surfaces.js';
 /**
  * One-shot capture of a single URL's computed-style map — no spec, no config,
  * no git. `defineStyleMapCapture` is the right tool when the surfaces live in
@@ -30,6 +31,7 @@ const DEFAULTS = {
     maxStates: 100000,
     resetStorage: true,
     requireFullCoverage: false,
+    dataStates: true,
 };
 function positiveNumber(raw, flag) {
     const n = Number(raw);
@@ -59,6 +61,7 @@ const VALUE_FLAGS = {
     '--max-depth': (o, v) => (o.maxDepth = positiveNumber(v, '--max-depth')),
     '--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),
 };
 const BOOL_FLAGS = {
     '--screenshots': (o) => (o.screenshots = true),
@@ -66,6 +69,8 @@ const BOOL_FLAGS = {
     '--crawl': (o) => (o.crawl = true),
     '--no-reset-storage': (o) => (o.resetStorage = false),
     '--require-full-coverage': (o) => (o.requireFullCoverage = true),
+    '--data-states': (o) => (o.dataStates = true),
+    '--no-data-states': (o) => (o.dataStates = false),
 };
 // Apply one argv token to the accumulator; returns the index to resume from
 // (advanced past a consumed `--flag value` pair). Flat early-returns so the
@@ -112,6 +117,8 @@ export function parseCaptureUrlArgs(argv) {
         maxStates: DEFAULTS.maxStates,
         resetStorage: DEFAULTS.resetStorage,
         requireFullCoverage: DEFAULTS.requireFullCoverage,
+        setupFile: undefined,
+        dataStates: DEFAULTS.dataStates,
     };
     const positional = [];
     for (let i = 0; i < argv.length; i++)
@@ -139,6 +146,8 @@ export async function captureUrlToDir(page, opts) {
         await page.goto(opts.url, { waitUntil: 'load' });
         if (opts.waitSelector)
             await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+        if (opts.setup?.length)
+            await runSetup(page, opts.setup);
         widths = await detectViewportWidths(page);
     }
     const results = [];
@@ -149,6 +158,8 @@ export async function captureUrlToDir(page, opts) {
             await page.goto(opts.url, { waitUntil: 'load' });
             if (opts.waitSelector)
                 await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+            if (opts.setup?.length)
+                await runSetup(page, opts.setup);
             const map = await captureStyleMap(page, {
                 ignore: opts.ignore,
                 pendingRequests: requests.pending,
@@ -183,3 +194,41 @@ export async function runCaptureUrl(opts, launch) {
         await browser.close();
     }
 }
+const SETUP_ACTIONS = new Set(['goto', 'fill', 'click', 'waitFor']);
+/**
+ * Load and validate a `--setup` steps file, interpolating `${ENV_VAR}` in every
+ * `value` and `url` from the environment — so credentials for an input-gated
+ * page live in env vars, never in the file, the shell history, or the maps.
+ * Throws {@link UsageError} on a malformed file or a missing variable.
+ */
+export function loadSetupSteps(file, env = process.env) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new UsageError(`--setup: cannot read ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new UsageError('--setup: the file must be a JSON array of steps');
+    const interpolate = (raw) => raw.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+        const v = env[name];
+        if (v === undefined)
+            throw new UsageError(`--setup: environment variable ${name} is not set`);
+        return v;
+    });
+    return parsed.map((raw, i) => {
+        const step = raw;
+        if (!SETUP_ACTIONS.has(step.action))
+            throw new UsageError(`--setup: step ${i} has unknown action "${String(step.action)}"`);
+        if (step.action === 'goto' && !step.url)
+            throw new UsageError(`--setup: step ${i} (goto) needs a url`);
+        if (step.action !== 'goto' && !step.selector)
+            throw new UsageError(`--setup: step ${i} (${step.action}) needs a selector`);
+        return {
+            ...step,
+            ...(step.url ? { url: interpolate(step.url) } : {}),
+            ...(step.value ? { value: interpolate(step.value) } : {}),
+        };
+    });
+}

package/dist/crawl-surfaces.d.ts

@@ -30,7 +30,7 @@ import type { Page } from '@playwright/test';
  * mapping must not mutate. States gated behind such an action need a spec.
  */
 export type CrawlStep = {
-    action: 'click' | 'select-option';
+    action: 'click' | 'select-option' | 'fill-input';
     selector: string;
     label: string;
     reason: string;
@@ -60,6 +60,21 @@ export type CrawlReport = {
     failed: string[];
     coverage: CrawlCoverage;
 };
+/**
+ * One deterministic step run after every fresh navigation, BEFORE the crawl
+ * looks at the page — how input-gated states (a login form, a search box)
+ * become crawlable. Values come from the caller with `${ENV_VAR}` interpolation
+ * done at load time, so secrets live in the environment, never in files or maps.
+ * `optional: true` skips the step silently when its selector isn't present
+ * (e.g. a cookie-session app that only shows the login form once).
+ */
+export type SetupStep = {
+    action: 'goto' | 'fill' | 'click' | 'waitFor';
+    url?: string;
+    selector?: string;
+    value?: string;
+    optional?: boolean;
+};
 export type SurfaceCrawlOptions = {
     url: string;
     out: string;
@@ -68,6 +83,13 @@ export type SurfaceCrawlOptions = {
     height: number;
     screenshots: boolean;
     waitSelector?: string;
+    /** Deterministic steps (login, unlock, seed input) run after EVERY fresh
+     *  navigation, so each reset re-establishes the gated state identically. */
+    setup?: SetupStep[];
+    /** Also capture automatic data states of the entry page: `loading` (data
+     *  requests stalled — the skeleton) and `error` (data requests fulfilled with
+     *  a 500). Default true; states that render identically to base are skipped. */
+    dataStates?: boolean;
     /** Throttle: recursion depth into opened surfaces (base = 0). Default: unbounded. */
     maxDepth: number;
     /** Throttle: fresh controls driven per state. Default: unbounded — try them all. */
@@ -88,6 +110,10 @@ export declare const CRAWL_DEFAULTS: {
     maxStates: number;
     resetStorage: boolean;
 };
+/** 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

package/dist/crawl-surfaces.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
+import { detectViewportWidths } from './breakpoints.js';
 // Exhaustive by default — these ceilings are safety backstops, not budgets.
 export const CRAWL_DEFAULTS = {
     height: 900,
@@ -87,8 +88,41 @@ function collectClickable() {
         if (cursor === 'pointer' || cursor === 'grab')
             pool.add(el);
     }
+    // Neutral text inputs are typed automatically with a deterministic value —
+    // a search box or filter needs no secrets. Credential-semantic fields
+    // (type=password, autocomplete username/current-password/new-password/
+    // one-time-code) are NEVER auto-filled: those are --setup territory.
+    const FILLABLE = 'input:not([type]),input[type="text"],input[type="search"],input[type="email"],input[type="tel"],input[type="url"],input[type="number"],textarea';
+    const CRED_AUTOCOMPLETE = /username|current-password|new-password|one-time-code/i;
+    const AUTO_VALUE = {
+        email: 'sample@example.com',
+        url: 'https://example.com',
+        tel: '5550100',
+        number: '1',
+    };
     const seen = new Set();
     const out = [];
+    for (const el of document.querySelectorAll(FILLABLE)) {
+        if (CRED_AUTOCOMPLETE.test(el.getAttribute('autocomplete') ?? ''))
+            continue;
+        if (el.closest(':disabled,[aria-disabled="true"]') || el.readOnly)
+            continue;
+        if (!visible(el))
+            continue;
+        const selector = selectorFor(el);
+        if (seen.has(selector))
+            continue;
+        seen.add(selector);
+        const kind = el.getAttribute('type') ?? 'text';
+        out.push({
+            action: 'fill-input',
+            selector,
+            label: labelFor(el) === el.tagName.toLowerCase() ? (el.getAttribute('placeholder') ?? 'input') : labelFor(el),
+            reason: 'auto-fill',
+            value: AUTO_VALUE[kind] ?? 'sample text',
+            unsafe: false,
+        });
+    }
     for (const el of pool) {
         if (el instanceof HTMLAnchorElement && el.href)
             continue; // links navigate — handled by link crawl, not here
@@ -227,6 +261,59 @@ async function waitSettled(page) {
  * leave the viewport wherever it finished (e.g. a mobile band where half the
  * controls are hidden).
  */
+/** One runner per setup action — a table, so adding an action is one entry. */
+const SETUP_RUNNERS = {
+    goto: async (page, s) => {
+        await page.goto(s.url ?? '', { waitUntil: 'load' });
+    },
+    fill: async (page, s) => {
+        await page
+            .locator(s.selector ?? '')
+            .first()
+            .fill(s.value ?? '', { timeout: 10000 });
+    },
+    click: async (page, s) => {
+        await perform(page, { action: 'click', selector: s.selector ?? '' });
+    },
+    waitFor: async (page, s) => {
+        await page
+            .locator(s.selector ?? '')
+            .first()
+            .waitFor({ state: 'visible', timeout: 10000 });
+    },
+};
+/** 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 async function runSetup(page, steps) {
+    for (const s of steps) {
+        try {
+            await SETUP_RUNNERS[s.action](page, s);
+        }
+        catch (e) {
+            if (s.optional)
+                continue;
+            throw new Error(`setup step failed (${s.action} ${s.selector ?? s.url ?? ''})`, { cause: e });
+        }
+    }
+}
+/** Reveal scroll-gated content deterministically: IntersectionObserver mounts,
+ *  lazy sections. One bounded pass per load (same scroll every time, so replay
+ *  and fingerprints stay stable); capped so an infinite feed can't spin it. */
+async function scrollReveal(page) {
+    await page
+        .evaluate(async () => {
+        const step = Math.max(200, window.innerHeight);
+        let y = 0;
+        for (let i = 0; i < 20 && y <= document.body.scrollHeight; i++) {
+            window.scrollTo(0, y);
+            y += step;
+            await new Promise((r) => setTimeout(r, 60));
+        }
+        window.scrollTo(0, 0);
+    })
+        .catch(() => { });
+}
 async function gotoFresh(page, opts) {
     await page.setViewportSize({ width: opts.widths[0] ?? 1280, height: opts.height });
     await page.goto(opts.url, { waitUntil: 'load' });
@@ -236,6 +323,12 @@ async function gotoFresh(page, opts) {
     if (ready)
         await ready.waitFor({ state: 'visible' }).catch(() => { });
     await waitSettled(page);
+    if (opts.setup?.length) {
+        await runSetup(page, opts.setup);
+        await settleDom(page); // the steps changed page state — let it land
+    }
+    await scrollReveal(page);
+    await settleDom(page);
 }
 async function perform(page, s) {
     const target = page.locator(s.selector).first();
@@ -243,6 +336,10 @@ async function perform(page, s) {
         await target.selectOption(s.value ?? '');
         return;
     }
+    if (s.action === 'fill-input') {
+        await target.fill(s.value ?? '', { timeout: 5000 });
+        return;
+    }
     await target.waitFor({ state: 'attached', timeout: 5000 });
     await target.scrollIntoViewIfNeeded({ timeout: 3000 }).catch(() => { });
     // Dispatch the click IN-PAGE rather than through Playwright's actionability
@@ -315,20 +412,24 @@ 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) {
+async function record(page, opts, newPath, depth, fp, st, retryOnly = 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 });
+    st.queue.push({ path: newPath, depth, sig: fp.sig, retryOnly });
     for (const c of fp.classes)
         st.classes.add(c);
+    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) {
     let ok = true;
     try {
-        await captureInPlace(page, key, opts);
+        await captureInPlace(page, surface.key, opts);
         st.captured++;
     }
     catch {
-        st.failed.push(key);
+        st.failed.push(surface.key);
         ok = false;
     }
     opts.onSurface?.(surface, ok);
@@ -351,6 +452,8 @@ 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) {
+    // (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);
     if (outcome === 'noop')
         return { inState: true, skipped: false }; // still in the state — no reset needed
@@ -379,7 +482,7 @@ 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);
+    await record(page, opts, [...entry.path, step], entry.depth + 1, fp, st, entry.retryOnly || !persists);
     return { inState: false, skipped: false };
 }
 /**
@@ -400,18 +503,23 @@ function familyRetries(entry, all, st) {
         .filter((x) => x.persists && x.c.selector !== ownSelector && visibleNow.has(x.c.selector))
         .map((x) => x.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);
+    return [
+        ...fresh.map((c) => ({ c, retry: false })),
+        ...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 };
     const all = await page.evaluate(collectClickable).catch(() => []);
-    // 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.
-    const fresh = all.filter((c) => !st.tried.has(c.selector)).slice(0, opts.maxActionsPerState);
-    const work = [
-        ...fresh.map((c) => ({ c, retry: false })),
-        ...familyRetries(entry, all, st).map((c) => ({ c, retry: true })),
-    ];
+    const work = sweepWorkList(entry, all, opts, st);
     let tried = 0;
     let skipped = 0;
     let inState = true;
@@ -437,12 +545,65 @@ async function sweepState(page, opts, entry, st) {
     }
     return { tried, skipped };
 }
+/** 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. */
+async function recordDataState(page, opts, mode, st) {
+    // Match by resource TYPE, not by URL: real apps cache-bust (?t=...), so the
+    // re-load's data URLs never equal the observed ones. Any fetch/xhr is data.
+    await page.route('**/*', async (route) => {
+        const kind = route.request().resourceType();
+        if (kind !== 'fetch' && kind !== 'xhr')
+            return route.continue();
+        if (mode === 'error')
+            return route.fulfill({ status: 500, contentType: 'application/json', body: '{}' });
+        // loading: leave the request pending forever — the skeleton IS the state.
+    });
+    try {
+        await page.setViewportSize({ width: opts.widths[0] ?? 1280, height: opts.height });
+        await page.goto(opts.url, { waitUntil: 'load' });
+        await settleDom(page, 2500); // no networkidle wait — a stalled request never goes idle
+        const fp = await fingerprint(page);
+        if (st.seen.has(fp.sig))
+            return; // renders identically to a captured state (e.g. SSR)
+        st.seen.add(fp.sig);
+        for (const c of fp.classes)
+            st.classes.add(c);
+        const key = deriveKey([{ action: 'click', selector: `(data:${mode})`, label: mode, reason: 'data-state' }], st.used);
+        const surface = { key, depth: 0, path: [], elements: fp.elements };
+        st.surfaces.push(surface);
+        await captureAndReport(page, opts, surface, st);
+    }
+    finally {
+        await page.unroute('**/*');
+    }
+}
 /** 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. */
 async function discover(page, opts) {
     fs.mkdirSync(opts.out, { recursive: true });
+    // Watch the entry load's data requests so the automatic data states know what
+    // to stall/fail. Armed before navigation to see the app's own boot fetches.
+    const dataUrls = new Set();
+    const onRequest = (req) => {
+        const t = req.resourceType();
+        if (t === 'fetch' || t === 'xhr')
+            dataUrls.add(req.url());
+    };
+    page.on('request', onRequest);
     await gotoFresh(page, opts);
+    // No widths given? Detect the page's real @media breakpoints (like the
+    // one-shot path does) and sweep one width per band — automatically. Detection
+    // reads every stylesheet; if one is cross-origin/unreadable it falls back to
+    // the single default width rather than dying.
+    if (opts.widths.length === 0) {
+        const widths = await detectViewportWidths(page).catch(() => [1280]);
+        opts = { ...opts, widths };
+        if ((widths[0] ?? 1280) !== 1280)
+            await gotoFresh(page, opts); // re-pin discovery width BEFORE the base fingerprint
+    }
+    page.off('request', onRequest);
     const defined = await page.evaluate(collectDefinedClasses).catch(() => []);
     const fp = await fingerprint(page);
     const st = {
@@ -456,7 +617,14 @@ async function discover(page, opts) {
         captured: 0,
         failed: [],
     };
-    await record(page, opts, [], 0, fp, st);
+    await record(page, opts, [], 0, fp, st, 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.
+    if (opts.dataStates !== false && dataUrls.size > 0) {
+        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) {

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } fr
 export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
 export type { CaptureUrlOptions, CaptureUrlResult } from './capture-url.js';
 export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';
-export type { SurfaceCrawlOptions, CrawlReport, CrawlCoverage, CrawledSurface, CrawlStep } from './crawl-surfaces.js';
+export type { SurfaceCrawlOptions, CrawlReport, CrawlCoverage, CrawledSurface, CrawlStep, SetupStep, } from './crawl-surfaces.js';
+export { loadSetupSteps } from './capture-url.js';
 export type { StyleMap, CaptureOptions, CaptureMetadata, ElementEntry, LiveRegionCandidate, CapturedOverlay, Rect, } from './capture.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export type { Surface, SurfaceLiveState, SurfaceVariant, PopupCaptureOptions, DefineOptions, CrawlOptions, } from './runner.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
 export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';
+export { loadSetupSteps } from './capture-url.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",