styleproof 3.1.5 → 3.2.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-06-30
+
+### Added
+
+- Added optional `styleproof-map --crawl-base-url ... --crawl-route ...` pre-map
+  variant crawling, so automation can refresh the generated variant manifest
+  immediately before map capture.
+
+### Changed
+
+- `styleproof-init` now writes a dedicated `playwright.styleproof.config.ts`,
+  scopes discovery to the StyleProof spec, detects Vite/Next production preview
+  commands, and respects pnpm/Corepack pins in generated commands.
+- Map upload dirty-tree detection now ignores Next's generated `next-env.d.ts`
+  shim, while normal source edits still block upload.
+
 ## [3.1.5] - 2026-06-29
 
 ### Added
@@ -1058,7 +1074,8 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.5...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.5...v3.2.0
 [3.1.5]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.4...v3.1.5
 [3.1.4]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.3...v3.1.4
 [3.1.3]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.2...v3.1.3

package/README.md

@@ -16,7 +16,7 @@ report. Intentional visual changes get approved; unexpected ones block or fail.
 - [What it catches](#what-it-catches)
 - [What you own](#what-you-own)
 - [What the PR gets](#what-the-pr-gets)
-- [Don't let a new page ship uncaptured](#dont-let-a-new-page-ship-uncaptured)
+- [Auto-discovery](#auto-discovery)
 - [What a report looks like](#what-a-report-looks-like)
 - [Works with any styling system](#works-with-any-styling-system)
 - [Breakpoints, detected automatically](#breakpoints-detected-automatically)
@@ -58,7 +58,7 @@ silently passing.
 
 1. A **surface** is one UI state to certify: a route, tab, modal-open state,
    dropdown-open state, toast-visible state, loading state, etc.
-2. You list surfaces in a Playwright-style spec.
+2. You list or auto-discover surfaces in a Playwright-style spec.
 3. StyleProof opens each surface at real breakpoint widths and records computed
    styles for every captured element.
 4. On a PR, it compares base vs head and reports exactly which rendered styles
@@ -94,6 +94,12 @@ states that matter:
 - required-but-not-yet-captured states belong in `expected`, where the coverage
   guard fails until they are captured or explicitly excluded with a reason.
 
+Auto-discovery is a key feature, not a side path: StyleProof can discover
+Next.js routes, crawl real nav links, inventory component files, harvest
+one-step variants, click safe popups, detect breakpoints, and flag live or
+volatile regions. You review the app-specific leftovers; StyleProof keeps the
+mechanical inventory from drifting.
+
 That boundary is deliberate. StyleProof should not guess destructive flows,
 auth-only fixtures, or which product state your component needs. It should make
 missing coverage loud.
@@ -114,9 +120,19 @@ status green for that commit. Clean runs still leave a receipt: `No visual
 changes detected.` New surfaces are shown as new baselines; coverage gaps are
 handled by `expected`.
 
-## Don't let a new page ship uncaptured
+## Auto-discovery
+
+StyleProof's auto-discovery keeps the boring inventory out of your hands where it
+can be inferred safely: Next.js routes, crawlable links, component files,
+semantic popups, one-step variants, breakpoints, and volatile/live candidates.
+The key loop is simple: discover what the app exposes, capture what is safe, and
+fail loudly for anything that still needs an owner.
 
-StyleProof diffs the surfaces your spec lists — so a page nobody added to the list is invisible to the gate. Its change has no base capture _and_ no head capture, so it never appears in any diff, and the status goes green having never looked at it. This is the one thing the captures can't catch on their own: a capture that was never taken.
+StyleProof diffs the surfaces your spec lists or discovers — so a page nobody
+added to either set is invisible to the gate. Its change has no base capture
+_and_ no head capture, so it never appears in any diff, and the status goes
+green having never looked at it. This is the one thing the captures can't catch
+on their own: a capture that was never taken.
 
 Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails the moment a route exists with no surface, so a new page can't ship uncaptured:
 
@@ -258,9 +274,17 @@ styles. It also reports live-state candidates that need fixtures or opt-outs.
 styleproof-variants --base-url http://localhost:3000 --route / --route settings=/settings
 ```
 
-Use it as a manifest generator, not a replacement for review. The generated JSON
-is deliberately not read by `styleproof-map`; approve the states you want, then
-copy them into your capture spec as ordinary `variants` / `liveStates`.
+Use it as a manifest generator, not a replacement for review. To refresh that
+manifest as part of the map loop, pass the same crawl inputs to `styleproof-map`;
+it runs the crawler before Playwright captures the maps:
+
+```bash
+styleproof-map --crawl-base-url http://localhost:3000 --crawl-route / --crawl-route settings=/settings
+```
+
+The app must already be reachable at `--crawl-base-url`. If Playwright's
+`webServer` is the thing starting the app, keep route-link crawling inside the
+capture run with `defineCrawlCapture`.
 
 ```json
 {
@@ -393,7 +417,7 @@ npx styleproof-init
 It scaffolds:
 
 - a **capture spec** (`e2e/styleproof.spec.ts`) describing your surfaces (a Next.js app gets its routes _and_ the coverage guard wired automatically — see below);
-- a **`playwright.config.ts`** that builds and serves a **production build** (never a flaky dev server) and captures surfaces **in parallel** (`fullyParallel`);
+- a dedicated **`playwright.styleproof.config.ts`** that builds and serves a **production build** (never a flaky dev server), scopes discovery to the StyleProof spec, and captures surfaces **in parallel** (`fullyParallel`) without disturbing your app's existing Playwright config;
 - `.gitignore` entries for `.styleproof/`, `test-results/`, and `playwright-report/`;
 - a **cache-first CI workflow** that restores reusable maps from the `styleproof-maps` branch and generates the report without a browser when both maps are already built.
 
@@ -637,21 +661,24 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 **Capture env vars** (wire CI without editing the spec):
 
-| Env                       | Purpose                                                                                                               |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `STYLEMAP_DIR`            | Output label; the capture is skipped entirely when unset.                                                             |
-| `STYLEPROOF_BASEDIR`      | Output root dir (runner default `__stylemaps__`; `styleproof-map` CLI default `.styleproof/maps`).                    |
-| `STYLEPROOF_SCREENSHOTS`  | `0` to skip full-page screenshots. The CLI keeps screenshots by default so reports can crop maps restored from cache. |
-| `STYLEPROOF_REPLAY_FROM`  | Baseline dir to replay recorded data from — set this on the **head** capture.                                         |
-| `STYLEPROOF_REPLAY_URL`   | Override the `**/api/**` data-boundary glob.                                                                          |
-| `STYLEPROOF_SELFCHECK`    | `1` to capture each surface twice and fail if the two differ.                                                         |
-| `STYLEPROOF_UPLOAD`       | `1` to require map-store upload; `0` to capture locally only.                                                         |
-| `STYLEPROOF_CACHE_BRANCH` | Map store branch (default `styleproof-maps`).                                                                         |
+| Env                         | Purpose                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `STYLEMAP_DIR`              | Output label; the capture is skipped entirely when unset.                                                             |
+| `STYLEPROOF_BASEDIR`        | Output root dir (runner default `__stylemaps__`; `styleproof-map` CLI default `.styleproof/maps`).                    |
+| `STYLEPROOF_SCREENSHOTS`    | `0` to skip full-page screenshots. The CLI keeps screenshots by default so reports can crop maps restored from cache. |
+| `STYLEPROOF_REPLAY_FROM`    | Baseline dir to replay recorded data from — set this on the **head** capture.                                         |
+| `STYLEPROOF_REPLAY_URL`     | Override the `**/api/**` data-boundary glob.                                                                          |
+| `STYLEPROOF_SELFCHECK`      | `1` to capture each surface twice and fail if the two differ.                                                         |
+| `STYLEPROOF_UPLOAD`         | `1` to require map-store upload; `0` to capture locally only.                                                         |
+| `STYLEPROOF_CACHE_BRANCH`   | Map store branch (default `styleproof-maps`).                                                                         |
+| `STYLEPROOF_CRAWL_BASE_URL` | App URL for the optional pre-map `styleproof-variants` crawl.                                                         |
+| `STYLEPROOF_CRAWL_ROUTES`   | Comma-separated routes for the optional pre-map crawl, e.g. `/,settings=/settings`.                                   |
+| `STYLEPROOF_CRAWL_STRICT`   | `1` to fail the optional pre-map crawl on live-state fixtures or skipped candidates.                                  |
 
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
-- `styleproof-init` — scaffold the gate: the capture spec, a `playwright.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default) instead of assuming npm.
-- `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
+- `styleproof-init` — scaffold the gate: the capture spec, a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
+- `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--crawl-base-url` plus repeated `--crawl-route` to run `styleproof-variants` before capture, `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
 - `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical), `1` on a diff, `2` on a usage/capture error, `3` when only new surfaces are present (no baseline to diff against). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
 - `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports cached maps for the current commit against the inferred base; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).
 - `styleproof-variants` — crawl a running app for one-step state variants and write `styleproof.variants.generated.json`. Pass `--base-url`, repeat `--route`, and use `--strict` when unresolved skipped/live candidates should fail automation.

package/bin/styleproof-init.mjs

@@ -11,14 +11,15 @@
  *     the `expected` coverage guard from the app's routes at run time, so a page
  *     added later can't ship without a surface; otherwise it writes one sample
  *     surface plus a commented guard block to wire to your own route registry.
- *   - playwright.config.ts: only if one does not already exist, so an existing
- *     Playwright project is never disturbed.
+ *   - playwright.styleproof.config.ts: a dedicated production-build Playwright
+ *     config for StyleProof captures, so an existing app Playwright config is
+ *     never disturbed or accidentally reused.
  *   - .github/workflows/styleproof.yml: restores reusable maps from the
  *     styleproof-maps branch and only captures in CI when the maps are missing.
  *
  * Idempotent: re-running never overwrites an existing spec (use --force) and
- * never touches an existing playwright.config.ts. Exit 0 = done (or nothing to
- * do), 2 = usage error.
+ * never touches an existing app playwright.config.ts. Exit 0 = done (or nothing
+ * to do), 2 = usage error.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -31,7 +32,7 @@ usage: styleproof-init [options]
 
 options:
   --dir <path>        spec output path (default: e2e/styleproof.spec.ts)
-  --base-url <url>    baseURL for a generated playwright.config.ts
+  --base-url <url>    baseURL for a generated playwright.styleproof.config.ts
                       (default: http://localhost:3000)
   --force             overwrite the spec if it already exists
   -h, --help          show this help
@@ -41,7 +42,7 @@ What it writes:
     In a Next.js app it discovers your routes at run time and wires both the
     surfaces and the \`expected\` coverage guard to them, so a new page can't ship
     uncaptured. Otherwise it writes one sample surface + a commented guard block.
-  - playwright.config.ts, only if absent (an existing one is left untouched)
+  - playwright.styleproof.config.ts, a dedicated production-build Playwright config
   - .github/workflows/styleproof.yml, a cache-first PR report workflow
 
 After running, build and upload this commit's map outside CI when possible:
@@ -237,14 +238,15 @@ const PACKAGE_MANAGERS = {
   },
   pnpm: {
     label: 'pnpm',
-    run: (script) => `npx -y pnpm ${script}`,
-    exec: (command) => `npx -y pnpm exec ${command}`,
-    install: 'npx -y pnpm install --frozen-lockfile',
+    run: (script) => `pnpm run ${script}`,
+    exec: (command) => `pnpm exec ${command}`,
+    install: 'pnpm install --frozen-lockfile',
     setup: `      - uses: actions/setup-node@v4
         with:
           node-version: '20'
           cache: pnpm
-          cache-dependency-path: pnpm-lock.yaml`,
+          cache-dependency-path: pnpm-lock.yaml
+      - run: corepack enable`,
   },
   bun: {
     label: 'Bun',
@@ -269,6 +271,57 @@ function detectPackageManager(root) {
 
 const PM = detectPackageManager(process.cwd());
 
+function readPackageJson(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function hasDep(pkg, name) {
+  return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+
+function scriptIncludes(pkg, script, text) {
+  return typeof pkg.scripts?.[script] === 'string' && pkg.scripts[script].includes(text);
+}
+
+function portFromBaseUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.port) return parsed.port;
+    return parsed.protocol === 'https:' ? '443' : '80';
+  } catch {
+    return '3000';
+  }
+}
+
+function productionServerCommand(root, base) {
+  const pkg = readPackageJson(root);
+  const port = portFromBaseUrl(base);
+  const build = pkg.scripts?.build ? `${PM.run('build')} && ` : '';
+  const looksLikeVite =
+    hasDep(pkg, 'vite') || scriptIncludes(pkg, 'dev', 'vite') || scriptIncludes(pkg, 'build', 'vite');
+  const looksLikeNext =
+    hasDep(pkg, 'next') || scriptIncludes(pkg, 'dev', 'next') || scriptIncludes(pkg, 'build', 'next');
+
+  if (looksLikeVite) return `${build}${PM.exec(`vite preview --host 127.0.0.1 --port ${port}`)}`;
+  if (looksLikeNext) {
+    const start = pkg.scripts?.start ? PM.run('start') : PM.exec(`next start -p ${port}`);
+    return `${build}${start}`;
+  }
+  if (pkg.scripts?.start) return `${build}${PM.run('start')}`;
+  if (pkg.scripts?.preview) return `${build}${PM.run('preview')}`;
+  return `${PM.run('build')} && ${PM.run('start')}`;
+}
+
+function configTestDir(spec) {
+  const dir = path.dirname(path.resolve(process.cwd(), spec));
+  const rel = path.relative(process.cwd(), dir).replace(/\\/g, '/');
+  return rel ? `./${rel}` : '.';
+}
+
 const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 
 // Generated by styleproof-init.
@@ -280,6 +333,8 @@ const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 // app serves precompiled routes at consistent timing. (StyleProof's settle waits for
 // in-flight data either way, but a production build removes the variance at the source.)
 export default defineConfig({
+  testDir: ${JSON.stringify(configTestDir(specPath))},
+  testMatch: ${JSON.stringify(path.basename(specPath))},
   timeout: 120_000,
   // Capture surfaces in PARALLEL. StyleProof generates one test per surface × width,
   // each an isolated page writing a uniquely-keyed file (\`<key>@<width>.json.gz\`), with
@@ -293,11 +348,13 @@ export default defineConfig({
     baseURL: process.env.BASE_URL || '${baseUrl}',
   },
   // Build once, then serve THAT production build for the captures — so you can't
-  // accidentally capture a dev server. Adjust the command to your framework (e.g.
-  // \`vite build && vite preview\`); a server already running locally is reused.
+  // accidentally capture a dev server. styleproof-init detected the production
+  // serve command from your package scripts/dependencies; tune it here if your
+  // framework needs a custom preview command.
   webServer: {
-    command: '${PM.run('build')} && ${PM.run('start')}',
+    command: '${productionServerCommand(process.cwd(), baseUrl)}',
     url: process.env.BASE_URL || '${baseUrl}',
+    env: { PORT: '${portFromBaseUrl(baseUrl)}' },
     reuseExistingServer: !process.env.CI,
     timeout: 600_000, // a cold production build can take a few minutes
   },
@@ -422,13 +479,18 @@ if (spec.wrote) {
   console.log(`${specPath} already exists — left untouched (use --force to overwrite)`);
 }
 
-const configPath = 'playwright.config.ts';
-if (fs.existsSync(configPath) || fs.existsSync('playwright.config.js')) {
-  console.log('playwright.config exists — left untouched; ensure its baseURL points at a production build');
-} else {
-  fs.writeFileSync(configPath, CONFIG);
-  console.log(`created ${configPath} (baseURL ${baseUrl})`);
+const configPath = 'playwright.styleproof.config.ts';
+const config = writeFileSafe(configPath, CONFIG, { force });
+if (config.wrote) {
+  console.log(`${config.exists ? 'overwrote' : 'created'} ${configPath} (dedicated StyleProof capture config)`);
   wroteSomething = true;
+} else {
+  console.log(`${configPath} already exists — left untouched (use --force to overwrite)`);
+}
+if (fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js')) {
+  console.log(
+    'app playwright.config exists — left untouched; styleproof-map uses playwright.styleproof.config.ts by default',
+  );
 }
 
 const ignored = ['.styleproof/', 'test-results/', 'playwright-report/'].filter((line) => ensureGitignoreLine(line));

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/dist/map-store.js

@@ -10,6 +10,7 @@ export const DEFAULT_MAP_LABEL = 'current';
 export const DEFAULT_MAP_STORE_BRANCH = 'styleproof-maps';
 export const DEFAULT_REMOTE = 'origin';
 export const MAP_MANIFEST = 'styleproof-manifest.json';
+const GENERATED_DIRTY_ALLOWLIST = new Set(['next-env.d.ts']);
 export class MapStoreError extends Error {
 }
 function runGit(cwd, args, maxBuffer = 1 << 28) {
@@ -112,7 +113,14 @@ export function refSha(ref, cwd = process.cwd()) {
     return sha;
 }
 export function workingTreeDirty(cwd = process.cwd()) {
-    return gitOutput(cwd, ['status', '--porcelain']) !== '';
+    const r = runGit(cwd, ['status', '--porcelain']);
+    const status = r.status === 0 ? r.stdout.trimEnd() : '';
+    if (!status)
+        return false;
+    return status.split(/\r?\n/).some((line) => {
+        const file = line.slice(3).trim();
+        return file && !GENERATED_DIRTY_ALLOWLIST.has(file);
+    });
 }
 export function remoteExists(remote = DEFAULT_REMOTE, cwd = process.cwd()) {
     return runGit(cwd, ['remote', 'get-url', remote], 1 << 20).status === 0;

package/package.json

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