styleproof 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-06-23
+
+### Added
+
+- **`defineCrawlCapture` — discover surfaces by crawling rendered links.**
+  `discoverNextRoutes` reads the filesystem, so it only sees one surface per
+  `app/**` page — blind to a single-route SPA whose views are query params
+  (`/?tab=overview`) or client-routed, which exist only in the rendered nav as its
+  links. `defineCrawlCapture({ from, match, widths, dir })` loads a root URL, reads
+  its same-origin `<a href>`s (filtered by `match`), and captures each as a surface
+  keyed from its URL (`/?tab=overview` → `overview`; override with `key`). The
+  surface set _is_ the nav, so there's no hand-maintained `surfaces` list to drift
+  out of sync. The app just has to render its nav as real links — a button-only nav
+  exposes nothing to crawl. Replay, self-check and clock-freeze behave exactly as
+  for explicit surfaces. Also exported: `selectCrawlLinks` / `defaultLinkKey` (the
+  pure link-selection helpers) and the `CrawlOptions` / `CrawlLink` / `LinkMatch`
+  types.
+
+## [2.2.0] - 2026-06-23
+
+### Added
+
+- **Newly-added elements now report their full resting computed style**, not just
+  interaction-state deltas. Previously an added element surfaced only its
+  `:hover`/`:focus` changes (the diff short-circuited added elements before the
+  style loop); its background, padding, font, radius, etc. were captured but never
+  shown. The diff now emits the new element's full style as `(unset) → value`
+  findings and the report renders them value-only (no bogus "Before" column), in
+  both the PR report and the `styleproof-diff` CLI. The element already gated via
+  its `added` finding, so this enriches detail without changing what gates.
+- **`captureComponent` (opt-in, default off): surface the React component + props**
+  behind each element. With it on, capture reads the React fiber in-page
+  (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*` on
+  ≤16) to record the component display name and a sanitized subset of its props
+  (primitives only; `children`/handlers/objects dropped) on `ElementEntry.component`.
+  The report names it — `React component: Button (variant=primary, size=sm)` —
+  instead of a bare `<button>`. **Advisory only**, exactly like the content layer:
+  never fed to the certification diff or its blocking counts, so captures stay
+  deterministic. Names are mangled in minified prod builds, so it's most useful
+  against dev/non-minified output; a no-op on non-React pages.
+
 ## [2.1.0] - 2026-06-23
 
 ### Added

package/README.md

@@ -64,6 +64,21 @@ defineStyleMapCapture({
 
 `discoverNextRoutes(cwd?)` reads the filesystem only (route groups `(group)` and `@slots` stripped, `[param]`/`[...catchall]` flagged `dynamic`) — a heuristic, not a router; edit the generated spec for exotic routing. For any other framework, point `expected` at your own route registry as above.
 
+**Single-route SPAs: crawl the nav instead.** Filesystem discovery can't see a surface that isn't a page — a tab SPA where every view is `/?tab=overview` on one `app/page.tsx`, or anything client-routed. There the surfaces exist only in the rendered nav, as its links. `defineCrawlCapture` discovers them at run time: it loads a root URL, reads its same-origin `<a href>`s, and captures each — so the surface set _is_ the nav, with no list to hand-maintain (and so none to drift).
+
+```ts
+import { defineCrawlCapture } from 'styleproof';
+
+defineCrawlCapture({
+  from: '/', // crawl the app root for links
+  match: /\?tab=/, // keep just the tab views (omit to take every same-origin link)
+  widths: [1440, 1024, 768],
+  dir: process.env.STYLEMAP_DIR,
+});
+```
+
+Each discovered link becomes a surface keyed by its URL (`/?tab=overview` → `overview`; pass `key` for a different scheme). The app only has to render its nav as real `<a href>` links — a button-only nav (`<button onClick>`) exposes nothing to crawl. Replay, self-check and clock-freeze behave exactly as for explicit surfaces; one Playwright test runs the whole sweep (the link set isn't known until the page renders).
+
 ## What a report looks like
 
 One change — the hero CTA recoloured cyan → amber — appears as a single section in the report: a side-by-side before/after cropped screenshot, a one-line summary, then the exact property change folded under a toggle.
@@ -228,6 +243,23 @@ The report then carries a separate **📝 Content changes (advisory)** section:
 
 Notes: only an element's _own_ text is recorded (so a parent and child never double-report the same string); text churn in a live region is auto-excluded by the same settle pass that guards styles; and the certification CLI (`styleproof-diff`) is deliberately left content-blind.
 
+## Optional: React component layer (advisory)
+
+For a React app, knowing _which component_ rendered an element is often the fastest way to read a change. Off by default, opt in with `captureComponent`:
+
+```ts
+// styleproof.spec.ts — record the React component + props behind each element
+defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR, captureComponent: true });
+```
+
+Capture reads the React fiber in-page (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*` on ≤16) and records the component display name plus a **sanitized** subset of its props (primitives only — `children`, handlers, and objects are dropped) on `ElementEntry.component`. The report then names the element — **`React component: Button (variant=primary, size=sm)`** — instead of showing a bare `<button>`.
+
+Like the content layer it is **advisory**: never fed to the certification diff or the gate, so captures stay deterministic. Component names are mangled in minified production builds, so it's most useful against a dev / non-minified target; on a non-React page the fiber keys are absent and the field is simply omitted.
+
+## Newly-added elements show their full style
+
+When a PR **adds** an element, StyleProof now reports its **full resting computed style** (background, padding, font, radius, …), value-only, in addition to any interaction-state deltas — previously an added element surfaced only its `:hover`/`:focus` changes. The new element already gates via its `added` finding; this only enriches what you see, in both the report and the `styleproof-diff` CLI.
+
 ## Reference
 
 **Action `BenSheridanEdwards/StyleProof@v2`** — key inputs:

package/dist/capture.d.ts

@@ -42,6 +42,18 @@ export type ElementEntry = {
      * advisory, not a computed-style outcome. See README "Optional: content layer".
      */
     text?: string;
+    /**
+     * The React component that rendered this element, and a sanitized subset of its
+     * props — present only when capture ran with `captureComponent: true` (opt-in,
+     * off by default). Extracted in-page from the React fiber. ADVISORY: never fed
+     * to the certification diff or its counts (like {@link ElementEntry.text}); it
+     * only enriches the report so a reviewer sees `Button (variant=primary)` rather
+     * than a bare `<button>`. Best in dev/non-minified builds (prod mangles names).
+     */
+    component?: {
+        name: string;
+        props?: Record<string, string>;
+    };
 };
 export type StyleMap = {
     defaults: Record<string, Props>;
@@ -137,6 +149,19 @@ export type CaptureOptions = {
      * guards styles, since text now participates in change detection.
      */
     captureText?: boolean;
+    /**
+     * Opt-in React layer (default OFF). When true, each element records the React
+     * component that rendered it (display name) and a sanitized subset of its props
+     * on {@link ElementEntry.component}, read in-page from the React fiber
+     * (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*`
+     * on ≤16). Lets the report name `Button (variant=primary)` instead of a bare
+     * `<button>`. ADVISORY — like `captureText` it never feeds the certification
+     * diff or its blocking counts. Only primitive props (string/number/boolean) are
+     * kept (children/handlers/objects dropped); names are mangled in minified prod
+     * builds, so this is most useful against dev/non-minified output. No-op on
+     * non-React pages (fiber keys absent → field omitted).
+     */
+    captureComponent?: boolean;
     /**
      * Advanced/internal: a getter for the count of in-flight data requests, supplied by
      * a tracker ({@link trackInflightRequests}) armed BEFORE navigation so the page's own

package/dist/capture.js

@@ -30,15 +30,12 @@ const FRAMEWORK_IGNORE = [
 export function isUnder(path, roots) {
     return roots.some((r) => path === r || path.startsWith(r + ' > '));
 }
-// Serialized into the browser by page.evaluate; cannot call module helpers.
-// Pre-existing, grandfathered in the health baseline; the content layer adds
-// one small captureText block, not new structure.
-// fallow-ignore-next-line complexity
-function capturePage({ ignore, motionOnly, captureText }) {
-    const MOTION = /^(transition|animation)/;
-    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
-    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
-    const pathOf = (el) => {
+// Defines the structural-path helper on `window` once so the two functions
+// serialized into the page (capturePage, markInteractiveElements) share ONE
+// implementation — page.evaluate can't reference a module-scope helper, so the
+// alternative is an identical copy in each. Injected at the top of captureStyleMap.
+function injectPathOf() {
+    window.__spPathOf = (el) => {
         if (el === document.documentElement)
             return 'html';
         if (el === document.body)
@@ -54,6 +51,16 @@ function capturePage({ ignore, motionOnly, captureText }) {
         }
         return 'body > ' + parts.join(' > ');
     };
+}
+// Serialized into the browser by page.evaluate; cannot call module helpers.
+// Pre-existing, grandfathered in the health baseline; the content layer adds
+// one small captureText block, not new structure.
+// fallow-ignore-next-line complexity
+function capturePage({ ignore, motionOnly, captureText, captureComponent }) {
+    const MOTION = /^(transition|animation)/;
+    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    const pathOf = window.__spPathOf;
     // Per-tag (and per-tag-per-pseudo) UA defaults from a stylesheet-free iframe,
     // used to prune the maps. A pseudo-element's UA defaults are NOT the host
     // element's defaults, so they are measured and cached separately under a
@@ -96,6 +103,53 @@ function capturePage({ ignore, motionOnly, captureText }) {
         }
         return o;
     };
+    // Display name from a fiber `type`: function/class, or a forwardRef/memo wrapper
+    // object; '' for host fibers (string type), which keeps the walk going upward.
+    const nameOfType = (t) => {
+        if (typeof t === 'function') {
+            const f = t;
+            return f.displayName || f.name || '';
+        }
+        if (t && typeof t === 'object') {
+            const w = t;
+            const inner = w.render || w.type;
+            return w.displayName || inner?.displayName || inner?.name || '';
+        }
+        return '';
+    };
+    // Keep only primitive props (drop children/className/style/handlers/objects),
+    // capped — advisory, so never anything that could be huge or non-serializable.
+    const sanitizeProps = (mp) => {
+        const props = {};
+        for (const k of Object.keys(mp)) {
+            if (k === 'children' || k === 'className' || k === 'style')
+                continue;
+            const ty = typeof mp[k];
+            if (ty === 'string' || ty === 'number' || ty === 'boolean')
+                props[k] = String(mp[k]).slice(0, 80);
+        }
+        return props;
+    };
+    const reactComponent = (el) => {
+        const fiberKey = Object.keys(el).find((k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'));
+        if (!fiberKey)
+            return undefined;
+        let fiber = el[fiberKey] ?? null;
+        for (let hops = 0; fiber && hops < 30; fiber = fiber.return, hops++) {
+            const name = nameOfType(fiber.type);
+            if (!name || name === 'Symbol(react.fragment)')
+                continue;
+            const out = { name };
+            const mp = fiber.memoizedProps;
+            if (mp && typeof mp === 'object') {
+                const props = sanitizeProps(mp);
+                if (Object.keys(props).length)
+                    out.props = props;
+            }
+            return out;
+        }
+        return undefined;
+    };
     const elements = {};
     const all = [document.documentElement, document.body, ...document.querySelectorAll('body *')];
     // Surface untraversed shadow roots and same-origin iframes so a refactor
@@ -147,6 +201,16 @@ function capturePage({ ignore, motionOnly, captureText }) {
                 if (t)
                     entry.text = t;
             }
+            if (captureComponent) {
+                try {
+                    const comp = reactComponent(el);
+                    if (comp)
+                        entry.component = comp;
+                }
+                catch {
+                    // non-React node or inaccessible fiber — component stays absent
+                }
+            }
         }
         for (const ps of PSEUDOS) {
             if (ps === '::marker' && getComputedStyle(el).display !== 'list-item')
@@ -233,22 +297,7 @@ const STATE_ID_ATTR = 'data-styleproof-state-id';
  * but different ordering, which produces phantom forced-state diffs.
  */
 function markInteractiveElements({ selector, skipSel, attr }) {
-    const pathOf = (el) => {
-        if (el === document.documentElement)
-            return 'html';
-        if (el === document.body)
-            return 'body';
-        const parts = [];
-        let n = el;
-        while (n && n !== document.body) {
-            const parent = n.parentElement;
-            if (!parent)
-                break;
-            parts.unshift(`${n.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, n) + 1})`);
-            n = parent;
-        }
-        return 'body > ' + parts.join(' > ');
-    };
+    const pathOf = window.__spPathOf;
     let i = 0;
     return [...document.querySelectorAll(selector)].flatMap((el) => {
         if (skipSel && el.matches(skipSel))
@@ -497,6 +546,7 @@ export async function captureStyleMap(page, options = {}) {
     const maxInteractive = options.maxInteractive ?? 800;
     const stabilize = options.stabilize ?? true;
     const captureText = options.captureText ?? false;
+    const captureComponent = options.captureComponent ?? false;
     // Neutralise real focus the same way FREEZE_CSS neutralises motion: blur
     // whatever element holds focus so every read below is the no-interaction
     // resting state. Real :focus is nondeterministic across runs (autofocus, late
@@ -507,6 +557,11 @@ export async function captureStyleMap(page, options = {}) {
     // deterministic" failure). Interaction states are certified deterministically
     // via CDP forcePseudoState below, never via whatever happened to be focused.
     await page.evaluate(() => document.activeElement?.blur?.());
+    // Inject the structural-path helper once so both capturePage and
+    // markInteractiveElements (each serialized into the page by page.evaluate, which
+    // can't share a module-scope function) call ONE definition — no duplicated source.
+    // It persists on `window` for every evaluate below (no navigation between them).
+    await page.evaluate(injectPathOf);
     // Motion longhands first (FREEZE_CSS would null them), then everything else.
     // Motion never carries text — it's a settled end state of declared motion.
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
@@ -516,7 +571,7 @@ export async function captureStyleMap(page, options = {}) {
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
     const volatile = await detectVolatile(page, ignore, stabilize, captureText, options.pendingRequests);
-    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText });
+    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
     dropVolatile(base.elements, volatile);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);
     mergeMotion(base.elements, motion.elements);

package/dist/crawl.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Link-crawl surface discovery, for apps whose surfaces aren't filesystem routes.
+ *
+ * {@link discoverNextRoutes} reads the filesystem, so it sees one route per
+ * `app/.../page.*` — perfect for multi-page apps, blind to a single-route SPA that
+ * expresses every view as a query param (`/?tab=overview`) or client-side push.
+ * Those surfaces only exist in the *rendered* DOM, as the nav's links. This module
+ * turns that rendered link set into a surface list: navigate the app's root, read
+ * its `<a href>`s, and capture each — no hand-maintained `surfaces` array to drift
+ * out of sync with the nav (the same drift the coverage guard exists to catch,
+ * removed at the source).
+ *
+ * The DOM read happens at run time inside a Playwright test (a browser is needed to
+ * see hydrated links), so this file holds only the PURE part — turning a list of
+ * raw href strings into deduped, keyed, navigable surfaces — which is unit-testable
+ * with no browser. {@link defineCrawlCapture} in `runner.ts` does the navigation and
+ * feeds the hrefs here.
+ */
+/** A discovered surface: a filename-safe key and the same-origin path to navigate. */
+export type CrawlLink = {
+    /** Capture file-name prefix, derived from the URL (see {@link defaultLinkKey}). */
+    key: string;
+    /** Root-relative path+query to navigate (`/?tab=overview`, `/about`). */
+    url: string;
+};
+/**
+ * Keep only links whose resolved URL matches: a substring tested against the full
+ * href, a RegExp tested against it, or a predicate over the parsed URL. Omit to keep
+ * every same-origin link.
+ */
+export type LinkMatch = string | RegExp | ((url: URL) => boolean);
+export type SelectLinksOptions = {
+    /** Absolute URL of the crawled page. Relative hrefs resolve against it and only
+     *  same-origin links are kept (external nav, mailto:, tel:, javascript: dropped). */
+    base: string;
+    /** Narrow the kept links. Default: every same-origin link. */
+    match?: LinkMatch;
+    /** Derive the surface key from a link URL. Default: {@link defaultLinkKey}. */
+    key?: (url: URL) => string;
+};
+/**
+ * Filename-safe, readable key from a link URL. Joins the path segments and the
+ * query-param *values* (the discriminator for a tab SPA — `/?tab=overview` →
+ * `overview`), so the common single-route-with-`?tab=` case reads cleanly while a
+ * multi-segment route (`/blog/post`) still keys as `blog-post`. Param names are
+ * dropped (values carry the meaning); pass `key` to {@link selectCrawlLinks} when a
+ * project needs a different scheme.
+ */
+export declare function defaultLinkKey(url: URL): string;
+/**
+ * Turn a page's raw `<a href>` values into a deduped, keyed surface list.
+ *
+ * Each href is classified by {@link toLink} (resolve against `base`, keep http(s)
+ * same-origin, drop a bare in-page fragment of the crawl root, apply `match`); the
+ * survivors are deduped by path+query. Order follows first appearance in `hrefs`, so
+ * the capture order is the nav's order — stable across runs.
+ */
+export declare function selectCrawlLinks(hrefs: Iterable<string | null | undefined>, opts: SelectLinksOptions): CrawlLink[];

package/dist/crawl.js

@@ -0,0 +1,94 @@
+/**
+ * Link-crawl surface discovery, for apps whose surfaces aren't filesystem routes.
+ *
+ * {@link discoverNextRoutes} reads the filesystem, so it sees one route per
+ * `app/.../page.*` — perfect for multi-page apps, blind to a single-route SPA that
+ * expresses every view as a query param (`/?tab=overview`) or client-side push.
+ * Those surfaces only exist in the *rendered* DOM, as the nav's links. This module
+ * turns that rendered link set into a surface list: navigate the app's root, read
+ * its `<a href>`s, and capture each — no hand-maintained `surfaces` array to drift
+ * out of sync with the nav (the same drift the coverage guard exists to catch,
+ * removed at the source).
+ *
+ * The DOM read happens at run time inside a Playwright test (a browser is needed to
+ * see hydrated links), so this file holds only the PURE part — turning a list of
+ * raw href strings into deduped, keyed, navigable surfaces — which is unit-testable
+ * with no browser. {@link defineCrawlCapture} in `runner.ts` does the navigation and
+ * feeds the hrefs here.
+ */
+/**
+ * Filename-safe, readable key from a link URL. Joins the path segments and the
+ * query-param *values* (the discriminator for a tab SPA — `/?tab=overview` →
+ * `overview`), so the common single-route-with-`?tab=` case reads cleanly while a
+ * multi-segment route (`/blog/post`) still keys as `blog-post`. Param names are
+ * dropped (values carry the meaning); pass `key` to {@link selectCrawlLinks} when a
+ * project needs a different scheme.
+ */
+export function defaultLinkKey(url) {
+    const segs = url.pathname.split('/').filter(Boolean);
+    const values = [...url.searchParams].map(([, v]) => v).filter(Boolean);
+    const slug = [...segs, ...values]
+        .join('-')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return slug || 'index';
+}
+function matches(url, match) {
+    if (match === undefined)
+        return true;
+    if (typeof match === 'string')
+        return url.href.includes(match);
+    if (match instanceof RegExp)
+        return match.test(url.href);
+    return match(url);
+}
+/**
+ * Resolve one raw href to a navigable same-origin surface, or `null` to skip it
+ * (malformed, mailto:/tel:/javascript:, external, a bare fragment of the crawl root,
+ * or filtered out by `match`). Pure per-href classification — the loop in
+ * {@link selectCrawlLinks} only has to dedupe what this keeps.
+ */
+function toLink(href, base, keyFor, match) {
+    let url;
+    try {
+        url = new URL(href, base);
+    }
+    catch {
+        return null; // malformed href — skip, never throw into a spec
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null; // mailto:/tel:/javascript:
+    if (url.origin !== base.origin)
+        return null; // external link
+    const path = url.pathname + url.search;
+    // A pure fragment of the crawl root isn't a new surface (it's the same page).
+    if (url.hash && path === base.pathname + base.search)
+        return null;
+    if (!matches(url, match))
+        return null;
+    url.hash = ''; // navigate the surface, not a scroll anchor within it
+    return { key: keyFor(url), url: path };
+}
+/**
+ * Turn a page's raw `<a href>` values into a deduped, keyed surface list.
+ *
+ * Each href is classified by {@link toLink} (resolve against `base`, keep http(s)
+ * same-origin, drop a bare in-page fragment of the crawl root, apply `match`); the
+ * survivors are deduped by path+query. Order follows first appearance in `hrefs`, so
+ * the capture order is the nav's order — stable across runs.
+ */
+export function selectCrawlLinks(hrefs, opts) {
+    const base = new URL(opts.base);
+    const keyFor = opts.key ?? defaultLinkKey;
+    const seen = new Set();
+    const out = [];
+    for (const href of hrefs) {
+        const link = href ? toLink(href, base, keyFor, opts.match) : null;
+        if (!link || seen.has(link.url))
+            continue;
+        seen.add(link.url);
+        out.push(link);
+    }
+    return out;
+}

package/dist/diff.d.ts

@@ -15,6 +15,10 @@ export type Finding = {
     cls: string;
     change: 'added' | 'removed' | 'retagged';
     detail?: string;
+    component?: {
+        name: string;
+        props?: Record<string, string>;
+    };
 } | {
     kind: 'style';
     path: string;

package/dist/diff.js

@@ -35,11 +35,39 @@ export function diffStyleMaps(a, b) {
         const ea = a.elements[p];
         const eb = b.elements[p];
         if (!ea || !eb) {
-            findings.push({ kind: 'dom', path: p, cls: (ea ?? eb).cls, change: !ea ? 'added' : 'removed' });
+            const present = (ea ?? eb);
+            findings.push({
+                kind: 'dom',
+                path: p,
+                cls: present.cls,
+                change: !ea ? 'added' : 'removed',
+                ...(!ea && eb.component ? { component: eb.component } : {}),
+            });
+            // An added element has no "before", so the style loop below is skipped —
+            // surface its full resting computed style (+ pseudos) as (unset)→value so a
+            // new element's styling is reviewable, not just its interaction-state
+            // deltas. Removed elements get none (there is no "after" to show).
+            if (!ea && eb) {
+                const defsB = b.defaults[eb.tag] ?? {};
+                for (const pseudo of [null, ...Object.keys(eb.pseudo ?? {})]) {
+                    const propsB = pseudo ? (eb.pseudo?.[pseudo] ?? {}) : eb.style;
+                    const pdefsB = pseudo ? (b.defaults[eb.tag + pseudo] ?? defsB) : defsB;
+                    const props = diffProps({}, propsB, {}, pdefsB, '(unset)', '(unset)');
+                    if (props.length)
+                        findings.push({ kind: 'style', path: p, cls: eb.cls, pseudo, props });
+                }
+            }
             continue;
         }
         if (ea.tag !== eb.tag) {
-            findings.push({ kind: 'dom', path: p, cls: ea.cls, change: 'retagged', detail: `<${ea.tag}> → <${eb.tag}>` });
+            findings.push({
+                kind: 'dom',
+                path: p,
+                cls: ea.cls,
+                change: 'retagged',
+                detail: `<${ea.tag}> → <${eb.tag}>`,
+                ...(eb.component ? { component: eb.component } : {}),
+            });
             continue;
         }
         const defsA = a.defaults[ea.tag] ?? {};

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export type { StyleMap, CaptureOptions, ElementEntry, Rect } from './capture.js';
-export { defineStyleMapCapture } from './runner.js';
-export type { Surface, DefineOptions } from './runner.js';
+export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
+export type { Surface, DefineOptions, CrawlOptions } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export type { CoverageGaps } from './coverage.js';
 export { discoverNextRoutes } from './routes.js';
 export type { DiscoveredRoute } from './routes.js';
+export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
+export type { CrawlLink, LinkMatch, SelectLinksOptions } from './crawl.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

@@ -1,6 +1,7 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
-export { defineStyleMapCapture } from './runner.js';
+export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export { discoverNextRoutes } from './routes.js';
+export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/report.js

@@ -432,12 +432,51 @@ function beforeAfterTable(rows) {
         ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.before)} | ${cell(r.after)} |`),
     ];
 }
+// A brand-new element has no meaningful "before", so its resting style renders
+// value-only (the After column), mirroring the added-element interaction-states table.
+function valueTable(rows) {
+    return ['| Property | Value |', '| --- | --- |', ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.after)} |`)];
+}
+/** `Button (variant=primary, size=sm)` — the React component + sanitized props
+ *  the element captured (advisory; present only with captureComponent). */
+function renderComponent(c) {
+    const entries = Object.entries(c.props ?? {});
+    const props = entries.length ? ` (${entries.map(([k, v]) => `${k}=${v}`).join(', ')})` : '';
+    return `\`${c.name}\`${props}`;
+}
 /** One element's heading + body lines (no leading blank, no ×N suffix). */
+// Base/pseudo style rows. Added elements render value-only (no meaningful before).
+function styleSection(styles, added) {
+    const out = [];
+    for (const s of styles) {
+        const rows = summarizeProps(s.props);
+        if (rows.length)
+            out.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...(added ? valueTable(rows) : beforeAfterTable(rows)));
+    }
+    return out;
+}
+// Forced :hover/:focus/:active rows. Added: value-only; changed: before → after.
+function statesSection(states, added) {
+    const rows = [];
+    for (const st of states)
+        for (const c of summarizeProps(st.props))
+            rows.push(added
+                ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
+                : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
+    if (!rows.length)
+        return [];
+    return [
+        '',
+        added ? 'Interactive states:' : 'Interactive-state changes:',
+        '',
+        added ? '| State | Property | Value |' : '| State | Property | Before → After |',
+        '| --- | --- | --- |',
+        ...rows,
+    ];
+}
 function renderOneElement(group) {
     const label = prettyLabel(group[0].path, group[0].cls);
     const dom = group.find((f) => f.kind === 'dom');
-    const styles = group.filter((f) => f.kind === 'style');
-    const states = group.filter((f) => f.kind === 'state');
     if (dom?.change === 'removed')
         return { head: `**Removed** \`${label}\``, body: [] };
     const added = dom?.change === 'added';
@@ -447,21 +486,12 @@ function renderOneElement(group) {
             ? `**Retagged** \`${label}\` ${dom.detail ?? ''}`
             : `**\`${label}\`**`;
     const body = [];
-    for (const s of styles) {
-        const rows = summarizeProps(s.props);
-        if (rows.length)
-            body.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...beforeAfterTable(rows));
-    }
-    if (states.length) {
-        const rows = [];
-        for (const st of states)
-            for (const c of summarizeProps(st.props))
-                rows.push(added
-                    ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
-                    : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
-        if (rows.length)
-            body.push('', added ? 'Interactive states:' : 'Interactive-state changes:', '', added ? '| State | Property | Value |' : '| State | Property | Before → After |', '| --- | --- | --- |', ...rows);
-    }
+    // React component that rendered the element (added/retagged carry it on the dom
+    // finding) — surfaced first so a reviewer sees `Button (variant=primary)`.
+    if (dom?.component)
+        body.push('', `React component: ${renderComponent(dom.component)}`);
+    body.push(...styleSection(group.filter((f) => f.kind === 'style'), added));
+    body.push(...statesSection(group.filter((f) => f.kind === 'state'), added));
     // Existing element with nothing left to show (all derived) → skip; an
     // added/removed/retagged element always renders its heading.
     if (!dom && !body.length)
@@ -584,6 +614,10 @@ function cleanFindings(findings) {
     for (const group of groupByPath(findings)) {
         const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
         const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
+        // For an ADDED element the base style is a full (unset)→value snapshot, not a
+        // delta — so a forced-state value is never an "echo" of a base *change*; keep
+        // every state row (suppressing them would drop a real :hover/:focus value).
+        const isAdded = group.some((f) => f.kind === 'dom' && f.change === 'added');
         for (const f of group) {
             if (f.kind === 'dom') {
                 out.push(f);
@@ -591,7 +625,9 @@ function cleanFindings(findings) {
             }
             const props = f.kind === 'style'
                 ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
-                : f.props.filter((p) => !STATE_STRIP.has(p.prop) && !baseChanged.has(p.prop) && !(isNonValue(p.before) && isNonValue(p.after)));
+                : f.props.filter((p) => !STATE_STRIP.has(p.prop) &&
+                    (isAdded || !baseChanged.has(p.prop)) &&
+                    !(isNonValue(p.before) && isNonValue(p.after)));
             if (props.length)
                 out.push({ ...f, props });
         }

package/dist/runner.d.ts

@@ -1,3 +1,4 @@
+import { type LinkMatch } from './crawl.js';
 import type { Page } from '@playwright/test';
 /**
  * A surface is one deterministic page state worth certifying: a route plus
@@ -98,6 +99,12 @@ export type DefineOptions = {
      * `CaptureOptions.captureText` and the README's "Optional: content layer".
      */
     captureText?: boolean;
+    /**
+     * Opt-in React layer (default OFF). Record the component + sanitized props that
+     * rendered each element so the report can name `Button (variant=primary)`.
+     * Advisory only — never gates. See `CaptureOptions.captureComponent`.
+     */
+    captureComponent?: boolean;
 };
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
@@ -122,6 +129,8 @@ export declare function passLiveStreams(page: Page, url: string): Promise<void>;
  * forces it on either way.
  */
 export declare function defaultSelfCheck(replayFrom: string | undefined, env?: string | undefined): boolean;
+/** The capture settings every capturer shares (everything bar the surface set). */
+type CaptureConfig = Omit<DefineOptions, 'surfaces' | 'expected' | 'exclude'>;
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -135,4 +144,46 @@ export declare function defaultSelfCheck(replayFrom: string | undefined, env?: s
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export declare function defineStyleMapCapture({ surfaces, expected, exclude, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, }: DefineOptions): void;
+export declare function defineStyleMapCapture(options: DefineOptions): void;
+/** Options for {@link defineCrawlCapture}: where to crawl, how to filter/key the
+ *  links, and the viewport sweep — plus the shared capture settings. */
+export type CrawlOptions = CaptureConfig & {
+    /** URL to crawl for surface links (e.g. `/`). Its same-origin `<a href>`s become
+     *  the surface set. */
+    from: string;
+    /** Narrow the discovered links — substring, RegExp, or predicate over the URL
+     *  (e.g. `/\?tab=/` to capture only the tab views). Default: every same-origin link. */
+    match?: LinkMatch;
+    /** Derive a surface key from a link URL. Default: path+query slug (`/?tab=x` → `x`). */
+    key?: (url: URL) => string;
+    /** Viewport widths swept for every discovered surface — one per @media band. */
+    widths: number[];
+    /** Viewport height per width (default 800). */
+    height?: number | ((width: number) => number);
+    /** Selectors skipped on every surface (live regions, third-party embeds). */
+    ignore?: string[];
+    /** Max ms to wait for the crawl root's links to render before reading them
+     *  (an SPA hydrates its nav client-side). Default 15000. */
+    linkTimeout?: number;
+};
+/**
+ * Like {@link defineStyleMapCapture}, but the surface set is DISCOVERED at run time
+ * by crawling a page's links instead of being hand-listed — for a single-route SPA
+ * whose views are `?tab=`/client-routed and so invisible to the filesystem
+ * {@link discoverNextRoutes}. It navigates `from`, reads its same-origin `<a href>`s
+ * (filtered by `match`), and captures each as a surface keyed by `key`. The app just
+ * has to render its nav as real links; nothing to hand-maintain, so the surface list
+ * can't drift from the nav.
+ *
+ * One Playwright test does the whole sweep (the link set isn't known until a browser
+ * has rendered the page, so per-surface tests can't be generated at collection time).
+ * Per-surface failures are aggregated — one bad surface reports without hiding the
+ * rest. Replay/self-check/clock-freeze behave exactly as for explicit surfaces.
+ *
+ * ```ts
+ * // styleproof.spec.ts — capture every tab the nav links to
+ * defineCrawlCapture({ from: '/', match: /\?tab=/, widths: [1440, 1024, 768], dir: process.env.STYLEMAP_DIR });
+ * ```
+ */
+export declare function defineCrawlCapture(options: CrawlOptions): void;
+export {};

package/dist/runner.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { diffStyleMaps } from './diff.js';
 import { coverageGaps } from './coverage.js';
+import { selectCrawlLinks } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
 function driftDesc(f) {
     if (f.kind === 'dom')
@@ -81,9 +82,10 @@ async function assertDeterministic(page, surface, first, captureText, pending) {
             `First: ${driftDesc(drift[0])}`);
     }
 }
-/** Drive one surface at one width to a settled state and save its style map (+ screenshot). */
+/** Drive one surface at one width to a settled state and save its style map (+ screenshot).
+ *  The caller owns the test timeout (one-per-test for explicit surfaces, one budget for
+ *  the whole crawl) so a multi-surface crawl can't reset its own deadline mid-loop. */
 async function captureSurface(page, surface, width, s) {
-    test.setTimeout(180_000);
     await pinInputs(page, `${surface.key}@${width}.har`, s);
     const height = typeof surface.height === 'function' ? surface.height(width) : (surface.height ?? 800);
     await page.setViewportSize({ width, height });
@@ -96,6 +98,7 @@ async function captureSurface(page, surface, width, s) {
         const map = await captureStyleMap(page, {
             ignore: surface.ignore ?? [],
             captureText: s.captureText,
+            captureComponent: s.captureComponent,
             pendingRequests: requests.pending,
         });
         if (s.selfCheck)
@@ -122,6 +125,27 @@ async function captureSurface(page, surface, width, s) {
 export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCHECK) {
     return env === '1' || !replayFrom;
 }
+/**
+ * Apply the capture defaults once, so explicit-surface and crawl capture can't
+ * drift — the replay boundary, frozen clock and self-check policy resolve to the
+ * same thing whichever entry point you use. Env fallbacks (`STYLEPROOF_REPLAY_*`)
+ * live here too, so a single spec line keeps the documented behaviour.
+ */
+function resolveSettings(c) {
+    const replayFrom = c.replayFrom ?? process.env.STYLEPROOF_REPLAY_FROM;
+    return {
+        dir: c.dir,
+        baseDir: c.baseDir ?? '__stylemaps__',
+        screenshots: c.screenshots ?? true,
+        replayFrom,
+        replayUrl: c.replayUrl ?? process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**',
+        freezeClock: c.freezeClock ?? true,
+        clockTime: c.clockTime ?? '2025-01-01T00:00:00Z',
+        selfCheck: c.selfCheck ?? defaultSelfCheck(replayFrom),
+        captureText: c.captureText ?? false,
+        captureComponent: c.captureComponent ?? false,
+    };
+}
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -135,18 +159,9 @@ export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCH
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export function defineStyleMapCapture({ surfaces, expected, exclude = {}, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = defaultSelfCheck(replayFrom), captureText = false, }) {
-    const settings = {
-        dir: dir,
-        baseDir,
-        screenshots,
-        replayFrom,
-        replayUrl,
-        freezeClock,
-        clockTime,
-        selfCheck,
-        captureText,
-    };
+export function defineStyleMapCapture(options) {
+    const { surfaces, expected, exclude = {}, dir } = options;
+    const settings = resolveSettings(options);
     // Coverage guard. Runs in the NORMAL test suite (NOT gated on a capture dir), so
     // a route added without a surface fails the app's own tests — long before, and
     // independent of, a capture run. This is the one gap captures can't catch: a
@@ -168,8 +183,77 @@ export function defineStyleMapCapture({ surfaces, expected, exclude = {}, dir, b
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         for (const surface of surfaces) {
             for (const width of surface.widths) {
-                test(`${surface.key} @ ${width}`, ({ page }) => captureSurface(page, surface, width, settings));
+                test(`${surface.key} @ ${width}`, ({ page }) => {
+                    test.setTimeout(180_000);
+                    return captureSurface(page, surface, width, settings);
+                });
             }
         }
     });
 }
+/**
+ * Like {@link defineStyleMapCapture}, but the surface set is DISCOVERED at run time
+ * by crawling a page's links instead of being hand-listed — for a single-route SPA
+ * whose views are `?tab=`/client-routed and so invisible to the filesystem
+ * {@link discoverNextRoutes}. It navigates `from`, reads its same-origin `<a href>`s
+ * (filtered by `match`), and captures each as a surface keyed by `key`. The app just
+ * has to render its nav as real links; nothing to hand-maintain, so the surface list
+ * can't drift from the nav.
+ *
+ * One Playwright test does the whole sweep (the link set isn't known until a browser
+ * has rendered the page, so per-surface tests can't be generated at collection time).
+ * Per-surface failures are aggregated — one bad surface reports without hiding the
+ * rest. Replay/self-check/clock-freeze behave exactly as for explicit surfaces.
+ *
+ * ```ts
+ * // styleproof.spec.ts — capture every tab the nav links to
+ * defineCrawlCapture({ from: '/', match: /\?tab=/, widths: [1440, 1024, 768], dir: process.env.STYLEMAP_DIR });
+ * ```
+ */
+export function defineCrawlCapture(options) {
+    const { from, match, key, widths, height, ignore, linkTimeout = 15_000, dir } = options;
+    const settings = resolveSettings(options);
+    test.describe('styleproof crawl-capture', () => {
+        test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
+        test('discover surfaces by crawling links, then capture each', async ({ page }) => {
+            // 1. Load the root and wait for its nav links to hydrate — an SPA renders them
+            //    client-side, so they aren't in the initial HTML.
+            await page.goto(from, { waitUntil: 'load' });
+            await page.waitForSelector('a[href]', { timeout: linkTimeout });
+            const hrefs = await page.$$eval('a[href]', (els) => els.map((e) => e.getAttribute('href')));
+            const links = selectCrawlLinks(hrefs, { base: page.url(), match, key });
+            if (links.length === 0) {
+                throw new Error(`styleproof crawl: no links matched at ${from}. The nav must render same-origin ` +
+                    `<a href> links (a button-only nav exposes nothing to crawl), and \`match\` must keep them.`);
+            }
+            // Budget the whole sweep up front: one test captures every surface, and
+            // captureSurface no longer sets its own timeout, so size it to the work found.
+            test.setTimeout(Math.max(180_000, links.length * widths.length * 60_000));
+            // 2. Capture each discovered surface. Aggregate failures so one bad surface
+            //    reports without skipping the rest — they're an independent set, not a chain.
+            const failures = [];
+            for (const link of links) {
+                for (const width of widths) {
+                    const surface = {
+                        key: link.key,
+                        go: async (p) => {
+                            await p.goto(link.url, { waitUntil: 'load' });
+                        },
+                        widths: [width],
+                        ignore,
+                        height,
+                    };
+                    try {
+                        await captureSurface(page, surface, width, settings);
+                    }
+                    catch (e) {
+                        failures.push(`${link.key} @ ${width}: ${e.message}`);
+                    }
+                }
+            }
+            if (failures.length) {
+                throw new Error(`styleproof crawl-capture: ${failures.length} surface(s) failed:\n${failures.join('\n')}`);
+            }
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.1.0",
+  "version": "2.3.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",
@@ -75,7 +75,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/pngjs": "^6.0.5",
     "eslint": "^10.5.0",
     "globals": "^17.6.0",