styleproof 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ 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

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.

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/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/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
@@ -128,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
@@ -141,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, captureComponent, }: 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 });
@@ -123,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
@@ -136,19 +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, captureComponent = false, }) {
-    const settings = {
-        dir: dir,
-        baseDir,
-        screenshots,
-        replayFrom,
-        replayUrl,
-        freezeClock,
-        clockTime,
-        selfCheck,
-        captureText,
-        captureComponent,
-    };
+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
@@ -170,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.2.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",