styleproof 3.1.5 → 3.3.0

package/bin/styleproof-map.mjs

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   isHelpArg,
   missingSpecMessage,
@@ -34,6 +35,8 @@ import {
   writeMapManifest,
 } from '../dist/map-store.js';
 
+const STYLEPROOF_PLAYWRIGHT_CONFIG = 'playwright.styleproof.config.ts';
+const STYLEPROOF_VARIANTS_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'styleproof-variants.mjs');
 const HELP = `styleproof-map — capture this branch's computed-style map
 
 usage: styleproof-map [options] [-- <playwright args>]
@@ -49,12 +52,28 @@ options:
   --upload            require upload to the map store branch after capture
   --no-upload         capture locally only (default in CI)
   --restore           restore a map from the map store instead of capturing
+  --crawl-base-url <url>
+                      run styleproof-variants before capture against this app URL
+  --crawl-route <r>   route path or key=path for the pre-map variant crawl; repeatable
+  --crawl-out <file>  variant crawl manifest (default: styleproof.variants.generated.json)
+  --crawl-max-actions <n>
+                      max attempted variant actions per route (default: 40)
+  --crawl-width <px>  pre-map crawl viewport width (default: 1280)
+  --crawl-height <px> pre-map crawl viewport height (default: 800)
+  --crawl-strict      fail if live-state fixtures or skipped candidates remain
   --cache-branch <b>  map store branch (default: ${DEFAULT_MAP_STORE_BRANCH})
   --remote <name>     git remote for the map store (default: ${DEFAULT_REMOTE})
   -h, --help          show this help
 
+If playwright.styleproof.config.ts exists, styleproof-map passes it to Playwright
+by default. Override with: styleproof-map -- --config playwright.config.ts
+
+Set STYLEPROOF_CRAWL_BASE_URL and STYLEPROOF_CRAWL_ROUTES (comma-separated) to
+run the same pre-map crawl from automation.
+
 Examples:
   styleproof-map
+  styleproof-map --crawl-base-url http://localhost:3000 --crawl-route / --crawl-route settings=/settings
   styleproof-map --upload
   styleproof-map --restore --sha 0123abcd --dir head --base-dir __stylemaps__
   styleproof-map --spec e2e/styleproof.spec.ts
@@ -73,6 +92,16 @@ let cacheBranch = process.env.STYLEPROOF_CACHE_BRANCH ?? DEFAULT_MAP_STORE_BRANC
 let remote = process.env.STYLEPROOF_REMOTE ?? DEFAULT_REMOTE;
 let uploadMode =
   process.env.STYLEPROOF_UPLOAD === '1' ? 'required' : process.env.STYLEPROOF_UPLOAD === '0' ? 'off' : 'auto';
+let crawlBaseUrl = process.env.STYLEPROOF_CRAWL_BASE_URL ?? '';
+const crawlRoutes = (process.env.STYLEPROOF_CRAWL_ROUTES ?? '')
+  .split(',')
+  .map((route) => route.trim())
+  .filter(Boolean);
+let crawlOut = process.env.STYLEPROOF_CRAWL_OUT ?? 'styleproof.variants.generated.json';
+let crawlMaxActions = process.env.STYLEPROOF_CRAWL_MAX_ACTIONS ?? '';
+let crawlWidth = process.env.STYLEPROOF_CRAWL_WIDTH ?? '';
+let crawlHeight = process.env.STYLEPROOF_CRAWL_HEIGHT ?? '';
+let crawlStrict = process.env.STYLEPROOF_CRAWL_STRICT === '1';
 const playwrightArgs = [];
 
 for (let i = 0; i < argv.length; i++) {
@@ -95,9 +124,24 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === '--upload') uploadMode = 'required';
   else if (a === '--no-upload') uploadMode = 'off';
   else if (a === '--restore') restore = true;
-  else if (a === '--cache-branch') cacheBranch = argv[++i];
-  else if (a.startsWith('--cache-branch=')) cacheBranch = a.slice(15);
-  else if (a === '--remote') remote = argv[++i];
+  else if (a === '--crawl-base-url') crawlBaseUrl = argv[++i];
+  else if (a.startsWith('--crawl-base-url=')) crawlBaseUrl = a.slice(17);
+  else if (a === '--crawl-route') crawlRoutes.push(argv[++i]);
+  else if (a.startsWith('--crawl-route=')) crawlRoutes.push(a.slice(14));
+  else if (a === '--crawl-out') crawlOut = argv[++i];
+  else if (a.startsWith('--crawl-out=')) crawlOut = a.slice(12);
+  else if (a === '--crawl-max-actions') crawlMaxActions = argv[++i];
+  else if (a.startsWith('--crawl-max-actions=')) crawlMaxActions = a.slice(20);
+  else if (a === '--crawl-width') crawlWidth = argv[++i];
+  else if (a.startsWith('--crawl-width=')) crawlWidth = a.slice(14);
+  else if (a === '--crawl-height') crawlHeight = argv[++i];
+  else if (a.startsWith('--crawl-height=')) crawlHeight = a.slice(15);
+  else if (a === '--crawl-strict') crawlStrict = true;
+  else if (a === '--cache-branch' || a === '--remote') {
+    const value = argv[++i];
+    if (a === '--cache-branch') cacheBranch = value;
+    else remote = value;
+  } else if (a.startsWith('--cache-branch=')) cacheBranch = a.slice(15);
   else if (a.startsWith('--remote=')) remote = a.slice(9);
   else if (a.startsWith('--')) {
     console.error(unknownFlagMessage('styleproof-map', a));
@@ -123,6 +167,15 @@ if (!fs.existsSync(spec)) {
   console.error(missingSpecMessage(spec));
   process.exit(2);
 }
+const crawlEnabled = Boolean(crawlBaseUrl || crawlRoutes.length);
+if (crawlEnabled && !crawlBaseUrl) {
+  console.error('styleproof-map: --crawl-base-url is required when --crawl-route is set');
+  process.exit(2);
+}
+if (crawlEnabled && !crawlRoutes.length) {
+  console.error('styleproof-map: at least one --crawl-route is required when --crawl-base-url is set');
+  process.exit(2);
+}
 if (restore && !sha) {
   try {
     sha = currentGitSha(process.cwd());
@@ -165,6 +218,39 @@ function upload(dirPath) {
   }
 }
 
+function hasPlaywrightConfigArg(args) {
+  return args.some((arg) => arg === '--config' || arg === '-c' || arg.startsWith('--config='));
+}
+
+function variantCrawlArgs() {
+  const args = ['--base-url', crawlBaseUrl, '--out', crawlOut];
+  for (const route of crawlRoutes) args.push('--route', route);
+  if (crawlMaxActions) args.push('--max-actions', crawlMaxActions);
+  if (crawlWidth) args.push('--width', crawlWidth);
+  if (crawlHeight) args.push('--height', crawlHeight);
+  if (crawlStrict) args.push('--strict');
+  return args;
+}
+
+function runVariantCrawl(env) {
+  if (!crawlEnabled) return;
+  console.error('styleproof-map: crawling UI variants before capture');
+  const command = process.platform === 'win32' ? 'styleproof-variants.cmd' : 'styleproof-variants';
+  let result = spawnSync(command, variantCrawlArgs(), { stdio: 'inherit', env });
+  if (result.error?.code === 'ENOENT') {
+    result = spawnSync(process.execPath, [STYLEPROOF_VARIANTS_SCRIPT, ...variantCrawlArgs()], {
+      stdio: 'inherit',
+      env,
+    });
+  }
+  if (result.error) {
+    console.error(`styleproof-map: could not run styleproof-variants\n${result.error.message}`);
+    process.exit(2);
+  }
+  const status = result.status ?? 1;
+  if (status !== 0) process.exit(status);
+}
+
 const targetDir = path.join(baseDir, dir);
 let dirtyBeforeCapture;
 try {
@@ -199,13 +285,18 @@ if (restore) {
 }
 
 const command = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
+const configArgs =
+  fs.existsSync(STYLEPROOF_PLAYWRIGHT_CONFIG) && !hasPlaywrightConfigArg(playwrightArgs)
+    ? ['--config', STYLEPROOF_PLAYWRIGHT_CONFIG]
+    : [];
 const env = {
   ...process.env,
   STYLEMAP_DIR: dir,
   STYLEPROOF_BASEDIR: baseDir,
   STYLEPROOF_SCREENSHOTS: screenshots,
 };
-const result = spawnSync(command, ['test', '--grep', 'styleproof capture', ...playwrightArgs], {
+runVariantCrawl(env);
+const result = spawnSync(command, ['test', '--grep', 'styleproof capture', ...configArgs, ...playwrightArgs], {
   stdio: 'inherit',
   env,
 });

package/bin/styleproof-report.mjs

@@ -36,8 +36,8 @@ options:
   --remote <name>            git remote for the map store (default: ${DEFAULT_REMOTE})
   --out <dir>               output directory (default: styleproof-report)
   --image-base-url <url>    prefix for image URLs in report.md (default: relative)
-  --pad <px>                padding around changed rects when cropping (default: 24)
-  --max-crops <n>           max crop regions per surface before collapsing (default: 6)
+  --pad <px>                padding around changed rects when cropping (default: 12)
+  --max-crops <n>           max crop regions per surface before collapsing (default: 8)
   --fold-details-at <n>     row count at which a crop's property tables fold under a
                             <details> toggle (default: 0 = always; 'Infinity' = never)
   --min-width <px>          minimum crop width, for context (default: 320)
@@ -178,7 +178,7 @@ console.log(
   result.changedSurfaces === 0
     ? result.newSurfaces === 0
       ? '✓ no changes — empty report written'
-      : `ℹ ${result.newSurfaces} new surface(s) with no baseline — report written for reference`
+      : `ℹ ${result.newSurfaces} new surface(s) with no baseline — report written for review`
     : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)${newNote}`,
 );
 console.log(`report: ${result.reportMdPath}`);

package/dist/capture-url.d.ts

@@ -0,0 +1,80 @@
+import type { Browser, Page } from '@playwright/test';
+/**
+ * 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
+ * your own app and you want the coverage guard, the map store, and record/replay.
+ * This is the tool for a page you just want to point at: a deployed URL, a
+ * static export, or a standalone HTML mockup. Capture it into a directory of
+ * `<key>@<width>.json.gz` maps (+ `.png`) that {@link diffStyleMapDirs} — i.e.
+ * `styleproof-diff <a> <b>` — compares like any other capture.
+ *
+ * The output is deliberately the same shape a surface capture writes, so a
+ * mockup's map and your app's committed map are directly diffable: capture the
+ * design once, then diff each build against it to measure how close the
+ * implementation is (a diff that shrinks toward zero as it converges).
+ */
+/** Raised for bad CLI usage so the bin can print help and exit 2. */
+export declare class UsageError extends Error {
+}
+export type CaptureUrlOptions = {
+    /** Page to capture. */
+    url: string;
+    /** Capture file name prefix (`<key>@<width>.json.gz`); default `page`. */
+    key: string;
+    /**
+     * Viewport widths to sweep, one per @media band. Empty = auto-detect from the
+     * loaded CSSOM (fails loudly on a cross-origin/unreadable stylesheet — pass
+     * widths explicitly for a page whose CSS can't be read, e.g. a cross-origin
+     * font stylesheet).
+     */
+    widths: number[];
+    /** Output directory for the maps (+ screenshots). */
+    out: string;
+    /** Selectors for nondeterministic regions to skip (passed through to capture). */
+    ignore: string[];
+    /** Wait for this selector to be visible before capturing (reach the intended state). */
+    waitSelector?: string;
+    /** Viewport height (default 800). */
+    height: number;
+    /** Also write a full-page `.png` per capture (default true). */
+    screenshots: boolean;
+    /**
+     * Crawl the URL's whole interactive surface instead of capturing one state:
+     * drive every non-destructive control, recurse into what opens, capture each
+     * discovered surface under a derived key. See {@link crawlAndCapture}.
+     */
+    crawl: boolean;
+    /** crawl: recursion depth into opened surfaces (default 3). */
+    maxDepth: number;
+    /** crawl: fresh controls driven per state (default: unbounded — try them all). */
+    maxActionsPerState: number;
+    /** crawl: safety backstop on total surfaces (default: unbounded — exhaustive). */
+    maxStates: number;
+    /** crawl: clear storage on each reset so replay is deterministic (default true). */
+    resetStorage: boolean;
+    /** 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;
+};
+/**
+ * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI
+ * flow (help/exit codes) and this parse are testable without a browser.
+ */
+export declare function parseCaptureUrlArgs(argv: string[]): CaptureUrlOptions;
+/** Written artifacts for one width. */
+export type CaptureUrlResult = {
+    width: number;
+    map: string;
+    screenshot?: string;
+};
+/**
+ * Capture `opts.url` at each width using an already-open {@link Page}, writing
+ * `<out>/<key>@<width>.json.gz` (+ `.png`). Re-navigates per width so
+ * width-dependent rendering (media queries, `matchMedia`) is captured fresh, and
+ * arms the in-flight request tracker before each navigation so the page's own
+ * load fetches count toward the network-aware settle — same contract as a
+ * surface capture. Returns the files written.
+ */
+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[]>;

package/dist/capture-url.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
+import { detectViewportWidths } from './breakpoints.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
+ * your own app and you want the coverage guard, the map store, and record/replay.
+ * This is the tool for a page you just want to point at: a deployed URL, a
+ * static export, or a standalone HTML mockup. Capture it into a directory of
+ * `<key>@<width>.json.gz` maps (+ `.png`) that {@link diffStyleMapDirs} — i.e.
+ * `styleproof-diff <a> <b>` — compares like any other capture.
+ *
+ * The output is deliberately the same shape a surface capture writes, so a
+ * mockup's map and your app's committed map are directly diffable: capture the
+ * design once, then diff each build against it to measure how close the
+ * implementation is (a diff that shrinks toward zero as it converges).
+ */
+/** Raised for bad CLI usage so the bin can print help and exit 2. */
+export class UsageError extends Error {
+}
+const DEFAULTS = {
+    key: 'page',
+    height: 800,
+    screenshots: true,
+    crawl: false,
+    // Exhaustive by default — these are safety backstops, not budgets.
+    maxDepth: 1000,
+    maxActionsPerState: 100000,
+    maxStates: 100000,
+    resetStorage: true,
+    requireFullCoverage: false,
+};
+function positiveNumber(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new UsageError(`${flag}: not a positive number: ${raw}`);
+    return n;
+}
+function parseWidths(raw) {
+    const widths = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => positiveNumber(s, '--widths'));
+    if (widths.length === 0)
+        throw new UsageError('--widths: no widths given');
+    return widths;
+}
+// Table-driven so adding a flag is one entry, not another branch in the loop.
+// value flags mutate the accumulator with their argument; bool flags take none.
+const VALUE_FLAGS = {
+    '--key': (o, v) => (o.key = v),
+    '--widths': (o, v) => (o.widths = parseWidths(v)),
+    '--out': (o, v) => (o.out = v),
+    '--ignore': (o, v) => o.ignore.push(v),
+    '--wait': (o, v) => (o.waitSelector = v),
+    '--height': (o, v) => (o.height = positiveNumber(v, '--height')),
+    '--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')),
+};
+const BOOL_FLAGS = {
+    '--screenshots': (o) => (o.screenshots = true),
+    '--no-screenshots': (o) => (o.screenshots = false),
+    '--crawl': (o) => (o.crawl = true),
+    '--no-reset-storage': (o) => (o.resetStorage = false),
+    '--require-full-coverage': (o) => (o.requireFullCoverage = true),
+};
+// 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
+// parse loop stays trivial. Supports `--flag value` and `--flag=value`.
+function applyArg(o, argv, i, positional) {
+    const a = argv[i];
+    const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+    const name = eq === -1 ? a : a.slice(0, eq);
+    const bool = BOOL_FLAGS[name];
+    if (bool) {
+        bool(o);
+        return i;
+    }
+    const apply = VALUE_FLAGS[name];
+    if (apply) {
+        const v = eq === -1 ? argv[i + 1] : a.slice(eq + 1);
+        if (v === undefined)
+            throw new UsageError(`${name}: missing value`);
+        apply(o, v);
+        return eq === -1 ? i + 1 : i;
+    }
+    if (a.startsWith('--'))
+        throw new UsageError(`unknown flag: ${a}`);
+    positional.push(a);
+    return i;
+}
+/**
+ * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI
+ * flow (help/exit codes) and this parse are testable without a browser.
+ */
+export function parseCaptureUrlArgs(argv) {
+    const o = {
+        url: '',
+        key: DEFAULTS.key,
+        widths: [],
+        out: 'styleproof-capture',
+        ignore: [],
+        waitSelector: undefined,
+        height: DEFAULTS.height,
+        screenshots: DEFAULTS.screenshots,
+        crawl: DEFAULTS.crawl,
+        maxDepth: DEFAULTS.maxDepth,
+        maxActionsPerState: DEFAULTS.maxActionsPerState,
+        maxStates: DEFAULTS.maxStates,
+        resetStorage: DEFAULTS.resetStorage,
+        requireFullCoverage: DEFAULTS.requireFullCoverage,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++)
+        i = applyArg(o, argv, i, positional);
+    if (positional.length === 0)
+        throw new UsageError('missing <url>');
+    if (positional.length > 1)
+        throw new UsageError(`expected one <url>, got ${positional.length}`);
+    o.url = positional[0];
+    return o;
+}
+/**
+ * Capture `opts.url` at each width using an already-open {@link Page}, writing
+ * `<out>/<key>@<width>.json.gz` (+ `.png`). Re-navigates per width so
+ * width-dependent rendering (media queries, `matchMedia`) is captured fresh, and
+ * arms the in-flight request tracker before each navigation so the page's own
+ * load fetches count toward the network-aware settle — same contract as a
+ * surface capture. Returns the files written.
+ */
+export async function captureUrlToDir(page, opts) {
+    fs.mkdirSync(opts.out, { recursive: true });
+    let widths = opts.widths;
+    if (widths.length === 0) {
+        await page.setViewportSize({ width: 1280, height: opts.height });
+        await page.goto(opts.url, { waitUntil: 'load' });
+        if (opts.waitSelector)
+            await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+        widths = await detectViewportWidths(page);
+    }
+    const results = [];
+    for (const width of widths) {
+        await page.setViewportSize({ width, height: opts.height });
+        const requests = trackInflightRequests(page);
+        try {
+            await page.goto(opts.url, { waitUntil: 'load' });
+            if (opts.waitSelector)
+                await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+            const map = await captureStyleMap(page, {
+                ignore: opts.ignore,
+                pendingRequests: requests.pending,
+                metadata: { surfaceKey: opts.key },
+            });
+            const stem = path.join(opts.out, `${opts.key}@${width}`);
+            const mapPath = `${stem}.json.gz`;
+            saveStyleMap(mapPath, map);
+            const result = { width, map: mapPath };
+            if (opts.screenshots) {
+                const shot = `${stem}.png`;
+                // captureStyleMap froze animations, so the shot matches the mapped state.
+                await page.screenshot({ path: shot, fullPage: true, animations: 'disabled' });
+                result.screenshot = shot;
+            }
+            results.push(result);
+        }
+        finally {
+            requests.dispose();
+        }
+    }
+    return results;
+}
+/** Launch Chromium, capture the URL, and close — the whole bin body given parsed options. */
+export async function runCaptureUrl(opts, launch) {
+    const browser = await launch();
+    try {
+        const page = await browser.newPage();
+        return await captureUrlToDir(page, opts);
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/crawl-surfaces.d.ts

@@ -0,0 +1,96 @@
+import type { Page } from '@playwright/test';
+/**
+ * Surface crawler: deterministically map a single URL's WHOLE interactive
+ * surface — not just the state it loads in — and run to natural termination.
+ *
+ * A one-shot capture records the page as it lands, so a design that's mostly
+ * modals, drawers, and popovers has most of its surface behind clicks it never
+ * reaches. This crawls it instead: from the base state it finds every visible,
+ * non-destructive control (semantic controls AND anything the page styles as
+ * clickable — `cursor: pointer`) and drives each one, keeping whatever opens a
+ * structurally new surface. It then recurses depth-first into each new surface,
+ * so a modal's tabs, a drawer's sub-views, and a popover's panels are all mapped.
+ *
+ * EXHAUSTIVE by default: the crawl stops when the queue drains and every control
+ * has been driven once — not at a budget. Termination is guaranteed by dedup
+ * (a control is driven once by selector; a structural surface is captured once;
+ * both sets are finite). The `--max-*` options exist only as throttles.
+ *
+ * The sweep is IN-PLACE with lazy resets, which is what makes exhaustive
+ * affordable: standing in a state, each candidate is clicked where the page
+ * already is, and a cheap DOM fingerprint (tag+class in document order — no
+ * computed styles) decides what happened. A no-op click costs nothing; only a
+ * state-changing click pays a reset (fresh navigation + path replay), and every
+ * reset is VERIFIED against the state's fingerprint before the sweep continues,
+ * so children are never attributed to the wrong parent. New surfaces are
+ * captured in place 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.
+ *
+ * Destructive-looking controls (delete, deploy, pay, revoke…) are never clicked —
+ * mapping must not mutate. States gated behind such an action need a spec.
+ */
+export type CrawlStep = {
+    action: 'click' | 'select-option';
+    selector: string;
+    label: string;
+    reason: string;
+    value?: string;
+};
+export type CrawledSurface = {
+    key: string;
+    depth: number;
+    path: CrawlStep[];
+    elements: number;
+};
+/** Did the crawl SEE everything the design styles? `missing` lists classes the
+ *  page's own stylesheets select on that never appeared in any captured surface —
+ *  dead CSS, or a state the crawl could not reach. Empty missing = full coverage. */
+export type CrawlCoverage = {
+    defined: number;
+    rendered: number;
+    missing: string[];
+};
+export type CrawlReport = {
+    surfaces: CrawledSurface[];
+    actionsTried: number;
+    skipped: number;
+    /** Surfaces successfully captured to disk at every width. */
+    captured: number;
+    /** Keys of surfaces discovered but whose full capture failed. */
+    failed: string[];
+    coverage: CrawlCoverage;
+};
+export type SurfaceCrawlOptions = {
+    url: string;
+    out: string;
+    widths: number[];
+    ignore: string[];
+    height: number;
+    screenshots: boolean;
+    waitSelector?: string;
+    /** Throttle: recursion depth into opened surfaces (base = 0). Default: unbounded. */
+    maxDepth: number;
+    /** Throttle: fresh controls driven per state. Default: unbounded — try them all. */
+    maxActionsPerState: number;
+    /** Throttle: total surfaces. Default: unbounded — run to natural termination. */
+    maxStates: number;
+    /** Clear localStorage/sessionStorage on each reset so replay is deterministic. Default true. */
+    resetStorage: boolean;
+    /** 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;
+};
+export declare const CRAWL_DEFAULTS: {
+    height: number;
+    screenshots: boolean;
+    maxDepth: number;
+    maxActionsPerState: number;
+    maxStates: number;
+    resetStorage: boolean;
+};
+/**
+ * Crawl `opts.url` and capture every reachable surface at every width — runs to
+ * natural termination by default. Returns the surfaces mapped (with the click-path
+ * that reached each), how many actions were tried/skipped, and captured/failed.
+ */
+export declare function crawlAndCapture(page: Page, opts: SurfaceCrawlOptions): Promise<CrawlReport>;