styleproof 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -7,6 +7,97 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### 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
+
+- 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.
+
+## [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
+
+- 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

@@ -424,12 +424,53 @@ 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).
 
 **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,15 @@ 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)
+  --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)
@@ -67,8 +76,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 +96,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 +105,11 @@ async function runCrawl() {
       maxActionsPerState: opts.maxActionsPerState,
       maxStates: opts.maxStates,
       resetStorage: opts.resetStorage,
+      setup: setupSteps,
+      dataStates: opts.dataStates,
+      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

@@ -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,17 @@ 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;
+    /** 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
@@ -78,3 +90,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,8 @@ const DEFAULTS = {
     maxStates: 100000,
     resetStorage: true,
     requireFullCoverage: false,
+    dataStates: true,
+    workers: 4,
 };
 function positiveNumber(raw, flag) {
     const n = Number(raw);
@@ -59,6 +62,8 @@ 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),
+    '--workers': (o, v) => (o.workers = positiveNumber(v, '--workers')),
 };
 const BOOL_FLAGS = {
     '--screenshots': (o) => (o.screenshots = true),
@@ -66,6 +71,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 +119,9 @@ export function parseCaptureUrlArgs(argv) {
         maxStates: DEFAULTS.maxStates,
         resetStorage: DEFAULTS.resetStorage,
         requireFullCoverage: DEFAULTS.requireFullCoverage,
+        setupFile: undefined,
+        dataStates: DEFAULTS.dataStates,
+        workers: DEFAULTS.workers,
     };
     const positional = [];
     for (let i = 0; i < argv.length; i++)
@@ -139,6 +149,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 +161,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 +197,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. */
@@ -79,6 +101,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;
@@ -87,10 +118,10 @@ export declare const CRAWL_DEFAULTS: {
     maxActionsPerState: number;
     maxStates: number;
     resetStorage: boolean;
+    workers: number;
 };
-/**
- * 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.
- */
+/** 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>;
 export declare function crawlAndCapture(page: Page, opts: SurfaceCrawlOptions): Promise<CrawlReport>;

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,
@@ -10,6 +11,7 @@ export const CRAWL_DEFAULTS = {
     maxActionsPerState: 100000,
     maxStates: 100000,
     resetStorage: true,
+    workers: 4,
 };
 function slug(value) {
     return (value
@@ -76,6 +78,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.
@@ -87,8 +102,42 @@ 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,
+            identity: identityFor(el),
+            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
@@ -105,12 +154,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,
@@ -227,6 +285,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 +347,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 +360,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 +436,27 @@ 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, 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 });
+    // 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);
+}
+/** 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);
@@ -350,7 +478,9 @@ 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) {
+    // (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
@@ -365,7 +495,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);
@@ -379,7 +509,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, sink, entry.retryOnly || !persists, viaRetry);
     return { inState: false, skipped: false };
 }
 /**
@@ -391,27 +521,44 @@ 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));
 }
-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 = [
+/** 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.identity)).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, sink) {
+    if (!(await resetToState(page, opts, entry.path, entry.sig)))
+        return { tried: 0, skipped: 0 };
+    const all = await page.evaluate(collectClickable).catch(() => []);
+    const work = sweepWorkList(entry, all, opts, st);
     let tried = 0;
     let skipped = 0;
     let inState = true;
@@ -424,25 +571,125 @@ 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);
         inState = r.inState;
         if (r.skipped)
             skipped++;
     }
     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('**/*');
+    }
+}
+/**
+ * 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) {
+    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);
+    }
+    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
+                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))
+                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. */
 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,22 +703,21 @@ async function discover(page, opts) {
         captured: 0,
         failed: [],
     };
-    await record(page, opts, [], 0, fp, 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;
+    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.
+    if (opts.dataStates !== false && dataUrls.size > 0) {
+        await recordDataState(page, opts, 'loading', st);
+        await recordDataState(page, opts, 'error', st);
     }
+    const counters = { tried: 0, skipped: 0 };
+    await runPool(page, opts, st, counters);
     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 },
@@ -482,19 +728,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/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/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.3.0",
+  "version": "3.5.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",