styleproof 3.1.4 → 3.2.0

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:
@@ -176,9 +177,27 @@ const SURFACES: Surface[] = [
     // No widths → StyleProof detects your @media breakpoints from the loaded CSS and
     // sweeps one viewport per band. Pass an explicit array (e.g. 1280, 768, 390) to pin them (or to
     // cover a JS-only matchMedia breakpoint that has no CSS @media rule).
+    // Non-live UI states belong here as variants, so the base branch's
+    // dialog-open state compares to the head branch's dialog-open state.
+    // variants: [
+    //   {
+    //     key: 'dialog-open',
+    //     go: async (page) => {
+    //       await page.getByRole('button', { name: /open settings/i }).click();
+    //       await page.getByRole('dialog').waitFor();
+    //     },
+    //   },
+    //   {
+    //     key: 'popover-open',
+    //     go: async (page) => {
+    //       await page.getByRole('button', { name: /more/i }).click();
+    //       await page.locator('[popover], [role="menu"]').first().waitFor();
+    //     },
+    //   },
+    // ],
   },
-  // Add one surface per distinct page state: open menus, dialogs, selected
-  // tabs, form errors — anything whose styling you want certified.
+  // Add more surfaces for distinct routes/views; add menus, dialogs, popovers,
+  // selected tabs, and form errors as variants of the route/view that owns them.
 ];
 
 defineStyleMapCapture({
@@ -219,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',
@@ -251,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.
@@ -262,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
@@ -275,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
   },
@@ -404,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/bin/styleproof-variants.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Harvest one-step UI state variants from a running app.
+ *
+ *   styleproof-variants --base-url http://localhost:3000 --route / --route /settings
+ */
+import fs from 'node:fs';
+import { chromium } from '@playwright/test';
+import { harvestStyleVariants } from '../dist/variant-crawler.js';
+import { defaultLinkKey } from '../dist/crawl.js';
+import { isHelpArg, showHelpAndExit, unknownFlagMessage } from '../dist/cli-errors.js';
+
+const HELP = `styleproof-variants — discover one-step UI state variants
+
+usage: styleproof-variants --base-url <url> --route <path-or-key=path> [options]
+
+options:
+  --base-url <url>       running app origin, e.g. http://localhost:3000
+  --route <route>        route path, absolute URL, or key=path. Repeatable.
+  --out <file>           manifest output (default: styleproof.variants.generated.json)
+  --max-actions <n>      max attempted actions per route (default: 40)
+  --width <px>           viewport width (default: 1280)
+  --height <px>          viewport height (default: 800)
+  --strict               exit 1 if live-state fixtures or skipped candidates remain
+  -h, --help             show this help
+`;
+
+const argv = process.argv.slice(2);
+let baseUrl = '';
+let out = 'styleproof.variants.generated.json';
+let maxActions = 40;
+let width = 1280;
+let height = 800;
+let strict = false;
+const routeArgs = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (isHelpArg(a)) showHelpAndExit(HELP);
+  else if (a === '--base-url') baseUrl = argv[++i];
+  else if (a.startsWith('--base-url=')) baseUrl = a.slice(11);
+  else if (a === '--route') routeArgs.push(argv[++i]);
+  else if (a.startsWith('--route=')) routeArgs.push(a.slice(8));
+  else if (a === '--out') out = argv[++i];
+  else if (a.startsWith('--out=')) out = a.slice(6);
+  else if (a === '--max-actions') maxActions = Number(argv[++i]);
+  else if (a.startsWith('--max-actions=')) maxActions = Number(a.slice(14));
+  else if (a === '--width') width = Number(argv[++i]);
+  else if (a.startsWith('--width=')) width = Number(a.slice(8));
+  else if (a === '--height') height = Number(argv[++i]);
+  else if (a.startsWith('--height=')) height = Number(a.slice(9));
+  else if (a === '--strict') strict = true;
+  else if (a.startsWith('--')) {
+    console.error(unknownFlagMessage('styleproof-variants', a));
+    process.exit(2);
+  } else {
+    routeArgs.push(a);
+  }
+}
+
+if (!baseUrl) {
+  console.error('styleproof-variants: --base-url is required');
+  process.exit(2);
+}
+if (!routeArgs.length) {
+  console.error('styleproof-variants: at least one --route is required');
+  process.exit(2);
+}
+if (![maxActions, width, height].every(Number.isFinite)) {
+  console.error('styleproof-variants: --max-actions, --width, and --height must be numbers');
+  process.exit(2);
+}
+
+function parseRoute(input) {
+  const eq = input.indexOf('=');
+  if (eq > 0) return { key: input.slice(0, eq), url: input.slice(eq + 1) };
+  return { key: defaultLinkKey(new URL(input, baseUrl)), url: input };
+}
+
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage({ viewport: { width, height } });
+  const harvest = await harvestStyleVariants(page, {
+    baseUrl,
+    routes: routeArgs.map(parseRoute),
+    maxActionsPerRoute: maxActions,
+  });
+  fs.writeFileSync(out, JSON.stringify(harvest, null, 2) + '\n');
+  const variants = harvest.routes.reduce((sum, route) => sum + route.variants.length, 0);
+  const liveStates = harvest.routes.reduce((sum, route) => sum + route.liveStates.length, 0);
+  const skipped = harvest.routes.reduce((sum, route) => sum + route.skipped.length, 0);
+  console.log(`styleproof-variants: wrote ${out}`);
+  console.log(`${variants} variant(s), ${liveStates} live-state candidate(s), ${skipped} skipped candidate(s)`);
+  if (strict && (liveStates || skipped)) process.exit(1);
+} finally {
+  await browser.close();
+}

package/dist/action-context.d.ts

@@ -0,0 +1,38 @@
+export type ActionContextInput = {
+    eventName: string;
+    payload: {
+        pull_request?: {
+            number?: number;
+            head?: {
+                sha?: string;
+            };
+        };
+        workflow_run?: {
+            head_sha?: string;
+            pull_requests?: {
+                number?: number;
+            }[];
+        };
+    };
+    repo: Record<string, string>;
+    github: {
+        rest: {
+            repos: {
+                listPullRequestsAssociatedWithCommit: (args: Record<string, string>) => Promise<{
+                    data: {
+                        state?: string;
+                        number?: number;
+                        head?: {
+                            sha?: string;
+                        };
+                    }[];
+                }>;
+            };
+        };
+    };
+};
+export type ActionContextResult = {
+    prNumber: string;
+    headSha: string;
+};
+export declare function resolveActionContext({ eventName, payload, repo, github, }: ActionContextInput): Promise<ActionContextResult>;

package/dist/action-context.js

@@ -0,0 +1,17 @@
+export async function resolveActionContext({ eventName, payload, repo, github, }) {
+    let prNumber = payload.pull_request?.number;
+    let headSha = payload.pull_request?.head?.sha;
+    if (eventName === 'workflow_run') {
+        const run = payload.workflow_run;
+        headSha = run?.head_sha;
+        prNumber = run?.pull_requests?.[0]?.number;
+        if (headSha && !prNumber) {
+            const { data } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+                ...repo,
+                commit_sha: headSha,
+            });
+            prNumber = data.find((pr) => pr.state === 'open' && pr.head?.sha === headSha)?.number;
+        }
+    }
+    return prNumber && headSha ? { prNumber: String(prNumber), headSha } : { prNumber: '', headSha: '' };
+}

package/dist/capture.d.ts

@@ -69,6 +69,16 @@ export type LiveRegionCandidate = {
     ariaLive?: string;
     ariaBusy?: string;
 };
+export type CapturedOverlay = {
+    path: string;
+    tag: string;
+    cls: string;
+    reason: string;
+    role?: string;
+    ariaModal?: string;
+    ariaLive?: string;
+    text?: string;
+};
 export type StyleMap = {
     /** Optional runner-supplied context; ignored by the certification diff. */
     metadata?: CaptureMetadata;
@@ -98,6 +108,14 @@ export type StyleMap = {
      * regions that actually keep changing are auto-excluded via `volatile`.
      */
     liveCandidates?: LiveRegionCandidate[];
+    /**
+     * Visible semantic overlay roots that were present in the captured DOM and
+     * whose paths are present in `elements`. This is diagnostic/proof metadata:
+     * dialogs, menus, listboxes, modal roots and toast roots are still certified by
+     * the normal computed-style map, while this list lets tests prove those states
+     * were actually reached and captured.
+     */
+    overlays?: CapturedOverlay[];
     /**
      * Colour-valued `:root` custom properties (design/theme tokens), normalised to
      * the same `rgb(...)` form the longhands resolve to — `{ "--red-200": "rgb(254,

package/dist/capture.js

@@ -283,6 +283,75 @@ function detectLiveCandidates({ ignore }) {
             : [];
     });
 }
+function detectOverlayCandidates({ ignore }) {
+    const pathOf = window.__spPathOf;
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    const visible = (el) => {
+        if (el.hidden || el.getAttribute('aria-hidden') === 'true')
+            return false;
+        const rect = el.getBoundingClientRect();
+        const style = getComputedStyle(el);
+        return rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden';
+    };
+    const textOf = (el) => (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 120);
+    const toastish = (el) => {
+        const haystack = [
+            el.id,
+            el.getAttribute('class'),
+            el.getAttribute('data-testid'),
+            el.getAttribute('data-hot-toast'),
+            el.getAttribute('data-sonner-toast'),
+            el.getAttribute('data-toast'),
+        ]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase();
+        return /\b(toast|hot-toast|sonner)\b/.test(haystack);
+    };
+    const reasonsFor = (el, role, ariaModal) => {
+        const reasons = [];
+        if (el instanceof HTMLDialogElement && el.open)
+            reasons.push('dialog[open]');
+        if (el.hasAttribute('popover'))
+            reasons.push('popover');
+        if (['dialog', 'alertdialog', 'menu', 'listbox', 'tooltip'].includes(role))
+            reasons.push(`role=${role}`);
+        if (ariaModal === 'true')
+            reasons.push('aria-modal=true');
+        if (toastish(el))
+            reasons.push('toast');
+        if (el.hasAttribute('data-hot-toast'))
+            reasons.push('data-hot-toast');
+        if (el.hasAttribute('data-sonner-toast'))
+            reasons.push('data-sonner-toast');
+        if ((role === 'status' || role === 'alert') && toastish(el))
+            reasons.push(`role=${role}`);
+        return [...new Set(reasons)];
+    };
+    return [document.documentElement, document.body, ...document.querySelectorAll('body *')]
+        .filter((el) => (!skipSel || !el.matches(skipSel)) && visible(el))
+        .flatMap((el) => {
+        const role = (el.getAttribute('role') ?? '').trim().toLowerCase();
+        const ariaModal = (el.getAttribute('aria-modal') ?? '').trim().toLowerCase();
+        const ariaLive = (el.getAttribute('aria-live') ?? '').trim().toLowerCase();
+        const reasons = reasonsFor(el, role, ariaModal);
+        if (!reasons.length)
+            return [];
+        const text = textOf(el);
+        return [
+            {
+                path: pathOf(el),
+                tag: el.tagName.toLowerCase(),
+                cls: el.getAttribute('class') || '',
+                reason: reasons.join(', '),
+                ...(role ? { role } : {}),
+                ...(ariaModal ? { ariaModal } : {}),
+                ...(ariaLive ? { ariaLive } : {}),
+                ...(text ? { text } : {}),
+            },
+        ];
+    });
+}
 /** Full (unpruned) computed styles for an element and its descendants, pseudo-elements included. */
 // Serialized into the browser by page.evaluate; cannot call module helpers.
 function snapSubtree({ selector, index }) {
@@ -650,6 +719,7 @@ export async function captureStyleMap(page, options = {}) {
     await page.addStyleTag({ content: FREEZE_CSS });
     const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
     dropVolatile(base.elements, volatile);
+    const overlays = (await page.evaluate(detectOverlayCandidates, { ignore })).filter((overlay) => base.elements[overlay.path]);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);
     mergeMotion(base.elements, motion.elements);
     let states = {};
@@ -668,6 +738,7 @@ export async function captureStyleMap(page, options = {}) {
         ...(statesSkipped ? { statesSkipped: true } : {}),
         ...(volatile.length ? { volatile } : {}),
         ...(liveCandidates.length ? { liveCandidates } : {}),
+        ...(overlays.length ? { overlays } : {}),
         ...(Object.keys(tokens).length ? { tokens } : {}),
     };
 }