styleproof 3.1.3 → 3.1.5

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 } : {}),
     };
 }

package/dist/components.d.ts

@@ -0,0 +1,41 @@
+import type { Surface } from './runner.js';
+export type DiscoveredComponent = {
+    /** Stable surface key, e.g. `component-dashboard-pr-card`. */
+    key: string;
+    /** Path relative to `cwd`, using `/` separators. */
+    path: string;
+};
+export type DiscoverComponentFilesOptions = {
+    /** Project root. Defaults to the current working directory. */
+    cwd?: string;
+    /** Component roots to scan, relative to `cwd` unless absolute. */
+    roots: string[];
+    /** Capture-key prefix. Defaults to `component`. */
+    prefix?: string;
+    /** File extensions to include. Defaults to common JS + framework component files. */
+    extensions?: string[];
+    /** Extra regexes matched against the cwd-relative path. */
+    ignore?: RegExp[];
+};
+export type ComponentCatalogSurfaceOptions = {
+    /** Map a discovered component to the app-owned catalog URL that renders it. */
+    url?: (component: DiscoveredComponent) => string;
+    /** Viewport widths to apply to every generated component surface. */
+    widths?: number[];
+    /** Viewport height to apply to every generated component surface. */
+    height?: Surface['height'];
+    /** Selectors ignored on every generated component surface. */
+    ignore?: string[];
+};
+/**
+ * Discover component files so apps can make StyleProof coverage explicit:
+ * map these keys to a Storybook/Ladle/custom catalog route, then pass the keys
+ * to `expected`. StyleProof inventories files; the app still owns rendering
+ * because props, providers, data, portals, and framework bootstraps are app-specific.
+ */
+export declare function discoverComponentFiles(options: DiscoverComponentFilesOptions): DiscoveredComponent[];
+/**
+ * Turn discovered components into StyleProof surfaces for an app-owned catalog
+ * route. Default URL: `/styleproof/components/<component.key>`.
+ */
+export declare function componentCatalogSurfaces(components: DiscoveredComponent[], options?: ComponentCatalogSurfaceOptions): Surface[];

package/dist/components.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_EXTENSIONS = ['.jsx', '.tsx', '.vue', '.svelte', '.astro'];
+const DEFAULT_IGNORE = [
+    /(^|\/)__tests__(\/|$)/,
+    /(^|\/)(test|tests|fixtures|mocks)(\/|$)/,
+    /(^|\/)node_modules(\/|$)/,
+    /(^|\/)(dist|build|coverage|\.next|\.nuxt|\.svelte-kit)(\/|$)/,
+    /(^|\/)index\.[^/]+$/,
+    /\.(?:test|spec|stories|story)\.[^/]+$/,
+    /\.d\.ts$/,
+];
+function toSlash(file) {
+    return file.split(path.sep).join('/');
+}
+function componentKey(root, file, prefix) {
+    const rel = toSlash(path.relative(root, file))
+        .replace(/\.[^.]+$/, '')
+        .replace(/\/index$/, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return [prefix, rel].filter(Boolean).join('-');
+}
+function readDir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function assertComponentRoot(root, rootInput) {
+    let stat;
+    try {
+        stat = fs.statSync(root);
+    }
+    catch {
+        throw new Error(`StyleProof component root not found: ${rootInput}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`StyleProof component root is not a directory: ${rootInput}`);
+    }
+}
+/**
+ * Discover component files so apps can make StyleProof coverage explicit:
+ * map these keys to a Storybook/Ladle/custom catalog route, then pass the keys
+ * to `expected`. StyleProof inventories files; the app still owns rendering
+ * because props, providers, data, portals, and framework bootstraps are app-specific.
+ */
+export function discoverComponentFiles(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const prefix = options.prefix ?? 'component';
+    const extensions = new Set(options.extensions ?? DEFAULT_EXTENSIONS);
+    const ignore = [...DEFAULT_IGNORE, ...(options.ignore ?? [])];
+    const components = [];
+    for (const rootInput of options.roots) {
+        const root = path.resolve(cwd, rootInput);
+        assertComponentRoot(root, rootInput);
+        const walk = (dir) => {
+            for (const entry of readDir(dir)) {
+                const file = path.join(dir, entry.name);
+                const rel = toSlash(path.relative(cwd, file));
+                if (ignore.some((pattern) => pattern.test(rel)))
+                    continue;
+                if (entry.isDirectory()) {
+                    walk(file);
+                }
+                else if (entry.isFile() && extensions.has(path.extname(entry.name))) {
+                    components.push({ key: componentKey(root, file, prefix), path: rel });
+                }
+            }
+        };
+        walk(root);
+    }
+    const seen = new Map();
+    for (const component of components) {
+        const previous = seen.get(component.key);
+        if (previous) {
+            throw new Error(`StyleProof component key collision: ${component.key} from ${previous} and ${component.path}`);
+        }
+        seen.set(component.key, component.path);
+    }
+    return components.sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+ * Turn discovered components into StyleProof surfaces for an app-owned catalog
+ * route. Default URL: `/styleproof/components/<component.key>`.
+ */
+export function componentCatalogSurfaces(components, options = {}) {
+    return components.map((component) => ({
+        key: component.key,
+        go: async (page) => {
+            await page.goto(options.url?.(component) ?? `/styleproof/components/${component.key}`);
+        },
+        ...(options.widths ? { widths: options.widths } : {}),
+        ...(options.height ? { height: options.height } : {}),
+        ...(options.ignore ? { ignore: options.ignore } : {}),
+    }));
+}

package/dist/coverage.d.ts

@@ -8,10 +8,10 @@
  * This is the one failure StyleProof can't catch from the captures alone, because
  * it's about a capture that was never taken.
  *
- * `expected` closes the hole: a spec declares its full route/surface universe
- * (e.g. an app's view registry), and the guard fails when that universe drifts
- * from what's actually captured — turning a silent coverage hole into a red test,
- * in the app's own suite, the moment the route is added.
+ * `expected` closes the hole: a spec declares its full route/view/state universe
+ * (e.g. an app's route + overlay-flow registry), and the guard fails when that
+ * universe drifts from what's actually captured — turning a silent coverage hole
+ * into a red test, in the app's own suite, the moment the route or flow is added.
  */
 export type CoverageGaps = {
     /** Expected surfaces that are neither captured nor explicitly excluded. */
@@ -25,8 +25,9 @@ export type CoverageGaps = {
  *
  * A surface is covered if it's captured OR listed in `exclude` (a deliberate,
  * documented opt-out — `key → reason`). Captured surfaces NOT in `expected` are
- * allowed: one route legitimately has several captured states (`landing`,
- * `landing-nav-open`), and only the routes themselves form the universe.
+ * allowed: a project may start by requiring only route keys, then tighten the
+ * universe with explicit state keys such as `landing-nav-open` or
+ * `dashboard-dialog-open`.
  *
  * Pure and side-effect-free so it's unit-testable; `defineStyleMapCapture` wraps
  * it in a Playwright test that runs in the normal suite (not gated on a capture

package/dist/coverage.js

@@ -8,18 +8,19 @@
  * This is the one failure StyleProof can't catch from the captures alone, because
  * it's about a capture that was never taken.
  *
- * `expected` closes the hole: a spec declares its full route/surface universe
- * (e.g. an app's view registry), and the guard fails when that universe drifts
- * from what's actually captured — turning a silent coverage hole into a red test,
- * in the app's own suite, the moment the route is added.
+ * `expected` closes the hole: a spec declares its full route/view/state universe
+ * (e.g. an app's route + overlay-flow registry), and the guard fails when that
+ * universe drifts from what's actually captured — turning a silent coverage hole
+ * into a red test, in the app's own suite, the moment the route or flow is added.
  */
 /**
  * Compare the captured surface keys against a declared `expected` universe.
  *
  * A surface is covered if it's captured OR listed in `exclude` (a deliberate,
  * documented opt-out — `key → reason`). Captured surfaces NOT in `expected` are
- * allowed: one route legitimately has several captured states (`landing`,
- * `landing-nav-open`), and only the routes themselves form the universe.
+ * allowed: a project may start by requiring only route keys, then tighten the
+ * universe with explicit state keys such as `landing-nav-open` or
+ * `dashboard-dialog-open`.
  *
  * Pure and side-effect-free so it's unit-testable; `defineStyleMapCapture` wraps
  * it in a Playwright test that runs in the normal suite (not gated on a capture

package/dist/diff.js

@@ -19,6 +19,8 @@ const LAYOUT_EQUIVALENT_MARGIN_PROPS = new Set([
     'margin-inline-start',
     'margin-inline-end',
 ]);
+const SUBPIXEL_ORIGIN_PROPS = new Set(['perspective-origin', 'transform-origin']);
+const ORIGIN_EPSILON_PX = 0.05;
 function sameRect(a, b) {
     return !!a && !!b && a.every((v, i) => v === b[i]);
 }
@@ -27,6 +29,24 @@ function dropLayoutEquivalentMarginProps(props, a, b) {
         return props;
     return props.filter((p) => !LAYOUT_EQUIVALENT_MARGIN_PROPS.has(p.prop));
 }
+function pxParts(value) {
+    const parts = value.trim().split(/\s+/);
+    if (parts.length < 2 || parts.length > 3)
+        return null;
+    const values = parts.map((part) => {
+        const match = /^(-?\d+(?:\.\d+)?)px$/.exec(part);
+        return match ? Number(match[1]) : Number.NaN;
+    });
+    return values.every(Number.isFinite) ? values : null;
+}
+function sameSubpixelOrigin(before, after) {
+    const a = pxParts(before);
+    const b = pxParts(after);
+    return !!a && !!b && a.length === b.length && a.every((v, i) => Math.abs(v - b[i]) <= ORIGIN_EPSILON_PX);
+}
+function dropSubpixelOriginProps(props) {
+    return props.filter((p) => !SUBPIXEL_ORIGIN_PROPS.has(p.prop) || !sameSubpixelOrigin(p.before, p.after));
+}
 /** Union of both captures' live-region paths — skipped by every diff layer so a
  *  region volatile on either side never reads as a change. */
 function volatilePaths(a, b) {
@@ -95,7 +115,7 @@ export function diffStyleMaps(a, b) {
             const pdefsA = pseudo ? (a.defaults[ea.tag + pseudo] ?? defsA) : defsA;
             const pdefsB = pseudo ? (b.defaults[eb.tag + pseudo] ?? defsB) : defsB;
             const rawProps = diffProps(propsA, propsB, pdefsA, pdefsB, '(unset)', '(unset)');
-            const props = pseudo ? rawProps : dropLayoutEquivalentMarginProps(rawProps, ea, eb);
+            const props = dropSubpixelOriginProps(pseudo ? rawProps : dropLayoutEquivalentMarginProps(rawProps, ea, eb));
             if (props.length)
                 findings.push({ kind: 'style', path: p, cls: ea.cls, pseudo, props });
         }
@@ -131,7 +151,7 @@ export function diffStyleMaps(a, b) {
             const db = sb[state] ?? {};
             for (const sub of new Set([...Object.keys(da), ...Object.keys(db)])) {
                 const props = diffProps(da[sub] ?? {}, db[sub] ?? {}, {}, {}, '(state does not change it)', '(state no longer changes it)');
-                const filtered = dropLayoutEquivalentMarginProps(props, a.elements[sub], b.elements[sub]);
+                const filtered = dropSubpixelOriginProps(dropLayoutEquivalentMarginProps(props, a.elements[sub], b.elements[sub]));
                 if (filtered.length)
                     findings.push({ kind: 'state', path: p, cls, state, sub, props: filtered });
             }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
-export type { StyleMap, CaptureOptions, CaptureMetadata, ElementEntry, LiveRegionCandidate, Rect } from './capture.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';
 export { coverageGaps } from './coverage.js';
@@ -7,8 +7,12 @@ export type { CoverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';
 export { discoverNextRoutes } from './routes.js';
 export type { DiscoveredRoute } from './routes.js';
+export { discoverComponentFiles, componentCatalogSurfaces } from './components.js';
+export type { DiscoveredComponent, DiscoverComponentFilesOptions, ComponentCatalogSurfaceOptions, } from './components.js';
 export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
 export type { CrawlLink, LinkMatch, SelectLinksOptions } from './crawl.js';
+export { harvestStyleVariants } from './variant-crawler.js';
+export type { HarvestAction, HarvestedLiveState, HarvestedRoute, HarvestedVariant, HarvestRoute, HarvestSkip, VariantHarvest, VariantHarvestOptions, } from './variant-crawler.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export type { Finding, PropChange, SurfaceDiff, DiffCounts, ContentChange } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/index.js

@@ -3,6 +3,8 @@ export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';
 export { discoverNextRoutes } from './routes.js';
+export { discoverComponentFiles, componentCatalogSurfaces } from './components.js';
 export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
+export { harvestStyleVariants } from './variant-crawler.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/runner.d.ts

@@ -80,8 +80,10 @@ export type PopupCaptureOptions = {
 export type DefineOptions = {
     surfaces: Surface[];
     /**
-     * The full set of surface keys the app knows it has — its route/view universe,
-     * typically derived from a registry (e.g. an app's list of routes or view ids).
+     * The full set of surface keys the app knows it has — its route/view/state
+     * universe, typically derived from registries (e.g. routes plus modal/menu
+     * flows). Include expanded variant keys such as `dashboard-dialog-open` when
+     * those states must be certified.
      * When set, StyleProof emits a coverage-guard test (in the NORMAL suite, not
      * gated on a capture dir) that fails if any expected key is neither captured (a
      * surface) nor in `exclude`. This is what stops a newly added route from

package/dist/runner.js

@@ -68,11 +68,19 @@ const DEFAULT_POPUP_TRIGGERS = [
 const DEFAULT_POPUP_OVERLAYS = [
     'dialog[open]',
     '[popover]',
+    '[aria-modal="true"]',
     '[role="dialog"]',
     '[role="alertdialog"]',
     '[role="menu"]',
     '[role="listbox"]',
     '[role="tooltip"]',
+    '[data-hot-toast]',
+    '[data-sonner-toast]',
+    '[data-toast]',
+    '.hot-toast',
+    '[class*="toast" i]',
+    '[role="alert"]',
+    '[role="status"]',
     '[data-state="open"]:not(button):not(a):not(summary)',
 ].join(', ');
 export function resolvePopupCaptureOptions(input) {
@@ -124,8 +132,22 @@ async function popupDomSnapshot(page, options) {
             }
             return parts.join(' > ');
         };
+        const popupKey = (el) => {
+            const text = (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 120);
+            return [
+                pathOf(el),
+                el.getAttribute('role') ?? '',
+                el.getAttribute('aria-modal') ?? '',
+                el.getAttribute('aria-live') ?? '',
+                el.getAttribute('data-state') ?? '',
+                el.getAttribute('data-hot-toast') ?? '',
+                el.getAttribute('data-sonner-toast') ?? '',
+                el.getAttribute('data-toast') ?? '',
+                text,
+            ].join('|');
+        };
         const popups = qsa(popupSelector).filter(visible);
-        const keys = popups.map(pathOf);
+        const keys = popups.map(popupKey);
         if (!triggerSelector || !attr)
             return { keys, indexes: [] };
         const safeTrigger = (el) => {
@@ -175,16 +197,17 @@ function expandOne(surface, variant, variantKind) {
 export function expandSurfaceVariants(surface) {
     const variants = surface.variants ?? [];
     const liveStates = surface.liveStates ?? [];
+    const { variants: _variants, liveStates: _liveStates, ...base } = surface;
+    const baseSurface = { ...base, metadata: { surfaceKey: surface.key } };
+    void _variants;
+    void _liveStates;
     if (!variants.length && !liveStates.length) {
-        const { variants: _variants, liveStates: _liveStates, ...base } = surface;
-        void _variants;
-        void _liveStates;
-        return [{ ...base, metadata: { surfaceKey: surface.key } }];
+        return [baseSurface];
     }
-    return [
-        ...variants.map((variant) => expandOne(surface, variant, 'variant')),
-        ...liveStates.map((state) => expandOne(surface, state, 'live-state')),
-    ];
+    const expandedVariants = variants.map((variant) => expandOne(surface, variant, 'variant'));
+    if (!liveStates.length)
+        return [baseSurface, ...expandedVariants];
+    return [...expandedVariants, ...liveStates.map((state) => expandOne(surface, state, 'live-state'))];
 }
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
@@ -302,13 +325,12 @@ async function assertPopupDeterministic(page, surface, width, height, options, c
         throw new Error(selfCheckErrorMessage(`${surface.key}-${popupId}`, drift, first.volatile, first.liveCandidates));
     }
 }
-async function capturePopupCandidate(page, surface, width, height, s, options, candidate, seen) {
+async function capturePopupCandidate(page, surface, width, height, s, options, candidate) {
     const requests = trackInflightRequests(page);
     try {
         const popupKey = await openPopupCandidate(page, surface, width, height, options, candidate);
-        if (!popupKey || seen.has(popupKey))
+        if (!popupKey)
             return;
-        seen.add(popupKey);
         const popupId = `popup-${String(candidate.index + 1).padStart(2, '0')}`;
         const map = await captureOpenedPopupMap(page, surface, s, requests.pending, popupId);
         if (s.selfCheck)
@@ -328,9 +350,8 @@ async function capturePopupSurfaces(page, surface, width, height, s) {
         return;
     await surface.go(page);
     const candidates = await markPopupCandidates(page, options);
-    const seen = new Set();
     for (const candidate of candidates) {
-        await capturePopupCandidate(page, surface, width, height, s, options, candidate, seen);
+        await capturePopupCandidate(page, surface, width, height, s, options, candidate);
     }
 }
 /** Drive one surface at one width to a settled state and save its style map (+ screenshot).
@@ -441,7 +462,7 @@ export function defineStyleMapCapture(options) {
     if (expected) {
         test.describe('styleproof coverage', () => {
             test('every expected surface is captured or explicitly excluded', () => {
-                const { uncovered, staleExclusions } = coverageGaps(surfaces.map((s) => s.key), expected, exclude);
+                const { uncovered, staleExclusions } = coverageGaps(captureSurfaces.map((s) => s.key), expected, exclude);
                 expect(uncovered, `StyleProof coverage gap: ${uncovered.length} expected surface(s) are neither captured ` +
                     `nor excluded — add each to \`surfaces\`, or to \`exclude\` with a reason. ` +
                     `Missing: ${uncovered.join(', ')}`).toEqual([]);

package/dist/variant-crawler.d.ts

@@ -0,0 +1,60 @@
+import type { Page } from '@playwright/test';
+import { type CaptureOptions } from './capture.js';
+export type HarvestRoute = {
+    /** Stable route/surface key in the generated manifest. */
+    key: string;
+    /** Absolute URL or path resolved against `baseUrl`. */
+    url: string;
+};
+export type HarvestAction = 'click' | 'select-option' | 'submit-empty';
+export type HarvestedVariant = {
+    key: string;
+    action: HarvestAction;
+    selector: string;
+    reason: string;
+    label: string;
+    findings: number;
+    diffHash: string;
+    value?: string;
+};
+export type HarvestedLiveState = {
+    key: string;
+    selector: string;
+    reason: string;
+    label: string;
+    fixtureRequired: true;
+    role?: string;
+    ariaLive?: string;
+    ariaBusy?: string;
+};
+export type HarvestSkip = {
+    reason: 'unsafe-label' | 'navigated' | 'action-failed';
+    selector: string;
+    label: string;
+    detail?: string;
+};
+export type HarvestedRoute = {
+    key: string;
+    url: string;
+    variants: HarvestedVariant[];
+    liveStates: HarvestedLiveState[];
+    skipped: HarvestSkip[];
+};
+export type VariantHarvest = {
+    routes: HarvestedRoute[];
+};
+export type VariantHarvestOptions = {
+    baseUrl?: string;
+    routes: HarvestRoute[];
+    /** Max attempted actions per route. Default 40. */
+    maxActionsPerRoute?: number;
+    /** Extra selectors to skip during capture. */
+    ignore?: string[];
+    /** Forwarded to the cheap discovery captures; forced states stay off here. */
+    stabilize?: CaptureOptions['stabilize'];
+};
+/**
+ * Discover one-step UI states by trying semantic controls and keeping only
+ * actions whose rendered computed-style map differs from the route baseline.
+ */
+export declare function harvestStyleVariants(page: Page, options: VariantHarvestOptions): Promise<VariantHarvest>;