styleproof 3.16.0 → 3.18.0

package/dist/affected-surfaces.js

@@ -0,0 +1,220 @@
+/**
+ * Selective remap: given the files a change touched, which declared surfaces
+ * could have rendered differently?
+ *
+ * This is the sound core behind "capture only what a PR can affect, reuse the
+ * committed base map for the rest" — an OPT-IN speed-up, never the default gate.
+ * The default gate captures every surface and lets the map be the oracle; this
+ * function only decides which surfaces a caller *may* skip, and it is built to
+ * be wrong only in the safe direction.
+ *
+ * The hard constraint: in the committed-map model a wrong "unaffected" is silent
+ * and fatal — a stale committed map matches the base, the diff is empty, and the
+ * regression ships green. So this function OVER-APPROXIMATES. When it cannot
+ * prove a surface is unaffected, it returns the sentinel `'all'`, meaning
+ * "re-capture everything." Every uncertainty resolves to `'all'`:
+ *
+ *   - a global style change (a reset, `:root`/theme token, `@tailwind`, a
+ *     `createGlobalStyle`, a design-system config) cascades everywhere → `'all'`;
+ *   - a vanilla (non-module) stylesheet has a global class namespace the import
+ *     graph cannot bound → `'all'`;
+ *   - a computed dynamic `import(x)` with no static prefix could load anything
+ *     → `'all'`; with a static prefix (`import(`../dir/${x}`)`) it is treated as
+ *     a bundler context module — every file under that dir is a possible target;
+ *   - a changed file the graph cannot place at all → `'all'`.
+ *
+ * The module graph is an INPUT, not a dependency: pass any tool's output in the
+ * {@link ModuleEdge} shape (dependency-cruiser's `modules[].dependencies[]` maps
+ * directly). StyleProof stays framework-agnostic and adds no dependency; the
+ * caller owns graph production, which is where framework-specific resolution
+ * lives.
+ *
+ * Pure and side-effect-free (I/O is injected via `readFile`) so it is fully
+ * unit-testable and deterministic.
+ */
+// A stylesheet whose scope escapes the file that imports it. Any of these means
+// a change cascades beyond the import graph's reach.
+const GLOBAL_CSS = /(^|\})\s*(:root|html|body|\*)[\s,{]|@tailwind\b|@layer\s+base\b|@theme\b|@font-face\b/;
+// CSS-in-JS global APIs. NOTE: soundness depends on this list being complete for
+// the libraries in use — an unlisted global API in a .tsx would be misread as a
+// scoped (local) change. Extend deliberately; when unsure, the caller should
+// treat the styling system as unsupported and skip selective remap.
+const CSSJS_GLOBAL = /\b(createGlobalStyle|injectGlobal|globalStyle|globalCss|createGlobalTheme)\b/;
+// `:global(...)` escape hatch or cross-module composition pulls in outside scope.
+const MODULE_ESCAPES = /:global\b|\bcompose[sd]?\b[^;]*\bfrom\b/;
+const isConfig = (f) => /(?:^|\/)(?:tailwind|postcss|theme|tokens?|panda|uno)\.config\.[cm]?[jt]s$/.test(f) ||
+    /(?:^|\/)theme\.[cm]?[jt]s$/.test(f);
+const isStyleSheet = (f) => /\.(css|scss|sass|less|styl)$/.test(f);
+const isCssModule = (f) => /\.module\.(css|scss|sass|less|styl)$/.test(f);
+const isCode = (f) => /\.[cm]?[jt]sx?$/.test(f);
+/**
+ * Decide whether a single changed file's style scope is bounded to the files
+ * that import it (`'scope'` → follow the import graph) or escapes them
+ * (`'all'` → re-capture everything). Sound by construction: `'scope'` is
+ * returned only for provably-scoped changes (a CSS Module without escapes, or
+ * colocated CSS-in-JS with no global API); everything else, including anything
+ * unrecognized, is `'all'`.
+ */
+export function classifyStyleChange(file, readFile) {
+    if (isConfig(file))
+        return 'all'; // design-system config cascades to every surface
+    let src;
+    try {
+        src = readFile(file);
+    }
+    catch {
+        return 'all'; // cannot read → cannot prove local
+    }
+    if (src == null)
+        return 'all';
+    if (isCode(file))
+        return CSSJS_GLOBAL.test(src) ? 'all' : 'scope'; // .tsx: global CSS-in-JS or colocated scope
+    if (isStyleSheet(file)) {
+        if (isCssModule(file)) {
+            // Hashed per-file scope — but `:global`, cross-module `composes … from`, and
+            // genuinely global selectors (`:root`, `html`, `@font-face`, …) all escape it.
+            return MODULE_ESCAPES.test(src) || GLOBAL_CSS.test(src) ? 'all' : 'scope';
+        }
+        return 'all'; // vanilla stylesheet: global class namespace, import graph can't bound it
+    }
+    return 'all'; // unknown file kind → fail closed
+}
+// `import(` with a non-string-literal argument, capturing the argument text.
+const DYNAMIC_IMPORT = /import\(\s*([^)]+?)\s*\)/g;
+const dirOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '');
+const isSource = (p) => !p.includes('node_modules');
+function link(rev, to, from) {
+    let s = rev.get(to);
+    if (!s)
+        rev.set(to, (s = new Set()));
+    s.add(from);
+}
+/** Read a source file, mapping any throw/nullish result to `undefined`. */
+function safeRead(readFile, path) {
+    try {
+        return readFile(path) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one computed `import()` argument to the directory its bundler context
+ * module is rooted at: `null` for a plain string literal (the resolver already
+ * captured it), `'unbounded'` when there is no static directory prefix (target
+ * could be any file), else the normalized directory.
+ */
+function contextDir(arg, fromDir) {
+    if (/^['"]/.test(arg))
+        return null; // plain string literal
+    const prefix = arg.match(/^`([^$`]*)/)?.[1]; // static head of a template literal
+    if (!prefix || !prefix.includes('/'))
+        return 'unbounded'; // e.g. import(name)
+    return normalizeDir(fromDir, prefix);
+}
+/**
+ * Recover computed `import()`s the graph resolver dropped, as bundler context
+ * modules. Returns extra edges to add, or `'unbounded'` if any dynamic import
+ * has no static directory prefix (its target could be any file → the whole
+ * reachability is untrustworthy → caller must return `'all'`).
+ */
+function recoverContextEdges(from, src, files) {
+    const edges = [];
+    const fromDir = dirOf(from);
+    for (const m of src.matchAll(DYNAMIC_IMPORT)) {
+        const base = contextDir(m[1], fromDir);
+        if (base === 'unbounded')
+            return 'unbounded';
+        if (base === null)
+            continue;
+        for (const f of files)
+            if (dirOf(f) === base && isCode(f))
+                edges.push({ from, to: f, dynamic: true });
+    }
+    return edges;
+}
+// Resolve a `../a/b/` style prefix against a source file's directory, without fs.
+function normalizeDir(fromDir, prefix) {
+    const parts = (fromDir ? fromDir.split('/') : []).concat(prefix.split('/'));
+    const out = [];
+    for (const p of parts) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..')
+            out.pop();
+        else
+            out.push(p);
+    }
+    return out.join('/');
+}
+/** True if any changed file is a style change that escapes its importers. */
+function anyGlobalStyleChange(changed, readFile) {
+    return changed.some((f) => (isStyleSheet(f) || isCode(f) || isConfig(f)) && classifyStyleChange(f, readFile) === 'all');
+}
+/**
+ * Build the reverse-import adjacency (`imported → importers`) from the graph plus
+ * recovered context-module edges. `'all'` when an unbounded dynamic import makes
+ * the whole reachability untrustworthy.
+ */
+function buildReverseGraph(input, files) {
+    const rev = new Map();
+    for (const e of input.graph)
+        if (isSource(e.from) && isSource(e.to))
+            link(rev, e.to, e.from);
+    for (const f of files) {
+        const src = isCode(f) ? safeRead(input.readFile, f) : undefined;
+        if (src === undefined)
+            continue;
+        const extra = recoverContextEdges(f, src, files);
+        if (extra === 'unbounded')
+            return 'all';
+        for (const e of extra)
+            link(rev, e.to, e.from);
+    }
+    return rev;
+}
+/**
+ * Compute the set of declared surfaces a change could have altered, or `'all'`.
+ * See the module doc for the soundness contract. Any not in the returned set are
+ * provably unaffected and may reuse their committed base map.
+ */
+export function affectedSurfaces(input) {
+    const changed = [...input.changedFiles];
+    const files = [...input.files];
+    // 1. A style change that escapes its importers forces a full re-capture.
+    if (anyGlobalStyleChange(changed, input.readFile))
+        return 'all';
+    // 2. Reverse reachability (+ recovered context edges; unbounded dynamic → all).
+    const rev = buildReverseGraph(input, files);
+    if (rev === 'all')
+        return 'all';
+    // 3. Map each changed file to the surfaces that transitively import it. A file
+    //    the graph can't place (no importers, not a surface entry) → 'all'.
+    const entryToKey = new Map(Object.entries(input.surfaces).map(([k, f]) => [f, k]));
+    const hit = new Set();
+    for (const f of changed) {
+        const reach = reverseReach(f, rev);
+        if (reach.size === 0 && !entryToKey.has(f))
+            return 'all';
+        for (const src of [f, ...reach]) {
+            const key = entryToKey.get(src);
+            if (key)
+                hit.add(key);
+        }
+    }
+    return hit;
+}
+function reverseReach(file, rev) {
+    const seen = new Set();
+    const stack = [file];
+    while (stack.length) {
+        const cur = stack.pop();
+        for (const importer of rev.get(cur) ?? []) {
+            if (!seen.has(importer)) {
+                seen.add(importer);
+                stack.push(importer);
+            }
+        }
+    }
+    return seen;
+}

package/dist/capture-url.js

@@ -26,7 +26,12 @@ const DEFAULTS = {
     screenshots: true,
     crawl: false,
     // Exhaustive by default — these are safety backstops, not budgets.
-    maxDepth: 1000,
+    // maxDepth mirrors CRAWL_DEFAULTS.maxDepth (crawl-surfaces.ts): 16 is
+    // exhaustive for real UI — no human-navigable surface is 16 clicks from load.
+    // The cap exists to bound append-generator UIs (a composer that appends a
+    // fresh-identity node per click, which dedup can't terminate); a higher value
+    // would make it decorative. Raise with --max-depth for a genuinely deeper nest.
+    maxDepth: 16,
     maxActionsPerState: 100000,
     maxStates: 100000,
     resetStorage: true,

package/dist/crawl-surfaces.d.ts

@@ -44,11 +44,15 @@ export type CrawledSurface = {
 };
 /** Did the crawl SEE everything the design styles? `missing` lists classes the
  *  page's own stylesheets select on that never appeared in any captured surface —
- *  dead CSS, or a state the crawl could not reach. Empty missing = full coverage. */
+ *  dead CSS, or a state the crawl could not reach. `unreadable` names stylesheets
+ *  the browser could not parse (cross-origin, no CORS): their class vocabulary is
+ *  invisible, so coverage cannot be PROVEN against them. Full coverage = empty
+ *  `missing` AND empty `unreadable`. */
 export type CrawlCoverage = {
     defined: number;
     rendered: number;
     missing: string[];
+    unreadable: string[];
 };
 export type CrawlReport = {
     surfaces: CrawledSurface[];

package/dist/crawl-surfaces.js

@@ -249,12 +249,15 @@ function domShape() {
 /* c8 ignore stop */
 /** Runs in the browser: every class name the page's OWN stylesheets select on —
  *  the design's defined vocabulary, read from the parsed CSSOM (inline and
- *  same-origin sheets; unreadable cross-origin sheets are skipped). Coverage is
- *  checked against this, so "fully covered" means every class the design styles
- *  was seen rendered in at least one captured surface. */
+ *  same-origin sheets). Coverage is checked against this, so "fully covered" means
+ *  every class the design styles was seen rendered in at least one captured
+ *  surface. A cross-origin sheet the browser can't parse is NOT silently skipped:
+ *  its href is returned in `unreadable` so coverage names it as residue rather than
+ *  certifying completeness while blind to it. */
 /* c8 ignore start */
 function collectDefinedClasses() {
     const out = new Set();
+    const unreadable = [];
     const scan = (rules) => {
         if (!rules)
             return;
@@ -271,13 +274,13 @@ function collectDefinedClasses() {
     };
     for (const sheet of document.styleSheets) {
         try {
-            scan(sheet.cssRules);
+            scan(sheet.cssRules); // throws for a cross-origin sheet with no CORS
         }
         catch {
-            /* cross-origin sheet — not the design's own vocabulary */
+            unreadable.push(sheet.href ?? '<inline>');
         }
     }
-    return [...out];
+    return { classes: [...out], unreadable };
 }
 /* c8 ignore stop */
 /** Structural fingerprint of the page's CURRENT state. Dedup key for surfaces. */
@@ -842,16 +845,17 @@ async function discover(page, opts) {
     await gotoFresh(page, opts);
     // No widths given? Detect the page's real @media breakpoints (like the
     // one-shot path does) and sweep one width per band — automatically. Detection
-    // reads every stylesheet; if one is cross-origin/unreadable it falls back to
-    // the single default width rather than dying.
+    // reads every stylesheet and THROWS if one is cross-origin/unreadable: it never
+    // silently sweeps a single width, which would certify every other band
+    // unchanged without looking at it. Pin `--widths` for a cross-origin-CSS page.
     if (opts.widths.length === 0) {
-        const widths = await detectViewportWidths(page).catch(() => [1280]);
+        const widths = await detectViewportWidths(page);
         opts = { ...opts, widths };
         if ((widths[0] ?? 1280) !== 1280)
             await gotoFresh(page, opts); // re-pin discovery width BEFORE the base fingerprint
     }
     page.off('request', onRequest);
-    const defined = await page.evaluate(collectDefinedClasses).catch(() => []);
+    const { classes: defined, unreadable } = await page.evaluate(collectDefinedClasses);
     const fp = await fingerprint(page);
     const st = {
         seen: new Set([fp.sig]),
@@ -881,7 +885,7 @@ async function discover(page, opts) {
         skipped: counters.skipped,
         captured: st.captured,
         failed: st.failed,
-        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing },
+        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing, unreadable },
     };
 }
 /**

package/dist/crawl.d.ts

@@ -60,3 +60,38 @@ export declare function defaultLinkKey(url: URL): string;
  * the capture order is the nav's order — stable across runs.
  */
 export declare function selectCrawlLinks(hrefs: Iterable<string | null | undefined>, opts: SelectLinksOptions): CrawlLink[];
+/**
+ * The reconciliation of a rendered nav (the crawl's discovered link keys) against a
+ * declared `expected` universe, both directions. Where the spec guard treats the
+ * hand-listed `surfaces` as what's captured, here the crawl's DISCOVERED links are —
+ * the nav is the route universe for a link-crawled SPA, so it is the source of truth.
+ *
+ * - `missing`: an `expected` key with no rendered link and no `exclude` entry — a
+ *   nav-regression (a route the app promised is no longer linked).
+ * - `unexpected`: a rendered link with no `expected` entry and no `exclude` entry — a
+ *   new route/view with no owner in the registry.
+ * - `staleExclusions`: an `exclude` key absent from BOTH `expected` and the rendered
+ *   set — a rotted opt-out.
+ *
+ * Unlike {@link CoverageGaps} (which permits captured-not-expected so a spec can
+ * tighten its registry over time), the crawl asserts BOTH directions strictly: the
+ * rendered link set is complete by construction, so an unowned link is a real gap.
+ * Pure and browser-free so it's unit-testable; {@link import('./runner.js')} wraps it
+ * in the crawl capture test, where the link set is finally known.
+ */
+export type CrawlCoverageGaps = {
+    /** Expected keys with no rendered link and no `exclude` — a nav regression. */
+    missing: string[];
+    /** Rendered link keys absent from `expected` and `exclude` — a route with no owner. */
+    unexpected: string[];
+    /** `exclude` keys in neither `expected` nor the rendered set — a rotted opt-out. */
+    staleExclusions: string[];
+};
+export declare function crawlCoverageGaps(discoveredKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CrawlCoverageGaps;
+/**
+ * Reconcile the crawled link set against `expected` (via {@link crawlCoverageGaps}) and
+ * render the failure message, or `null` when the nav reconciles. `from` names the crawl
+ * root in the message. Kept pure and out of the capture test so the wording is
+ * unit-testable and {@link defineCrawlCapture} just throws what this returns.
+ */
+export declare function crawlCoverageError(from: string, discoveredKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): string | null;

package/dist/crawl.js

@@ -97,3 +97,31 @@ export function selectCrawlLinks(hrefs, opts) {
     }
     return out;
 }
+export function crawlCoverageGaps(discoveredKeys, expected, exclude = {}) {
+    const discovered = new Set(discoveredKeys);
+    const expectedSet = new Set(expected);
+    const missing = [...expectedSet].filter((k) => !discovered.has(k) && !(k in exclude));
+    const unexpected = [...discovered].filter((k) => !expectedSet.has(k) && !(k in exclude));
+    const staleExclusions = Object.keys(exclude).filter((k) => !expectedSet.has(k) && !discovered.has(k));
+    return { missing, unexpected, staleExclusions };
+}
+/**
+ * Reconcile the crawled link set against `expected` (via {@link crawlCoverageGaps}) and
+ * render the failure message, or `null` when the nav reconciles. `from` names the crawl
+ * root in the message. Kept pure and out of the capture test so the wording is
+ * unit-testable and {@link defineCrawlCapture} just throws what this returns.
+ */
+export function crawlCoverageError(from, discoveredKeys, expected, exclude = {}) {
+    const { missing, unexpected, staleExclusions } = crawlCoverageGaps(discoveredKeys, expected, exclude);
+    const problems = [];
+    if (missing.length)
+        problems.push(`nav regression — expected route(s) no longer linked from ${from}: ${missing.join(', ')}. ` +
+            `Restore the link, or move the key to \`exclude\` with a reason.`);
+    if (unexpected.length)
+        problems.push(`new route(s) with no owner — link(s) rendered at ${from} but absent from \`expected\`: ` +
+            `${unexpected.join(', ')}. Add each to \`expected\`, or to \`exclude\` with a reason.`);
+    if (staleExclusions.length)
+        problems.push(`stale \`exclude\` — key(s) in neither \`expected\` nor the rendered nav ` +
+            `(renamed or removed?): ${staleExclusions.join(', ')}.`);
+    return problems.length ? `styleproof crawl coverage gap:\n${problems.join('\n')}` : null;
+}

package/dist/diff.d.ts

@@ -9,6 +9,32 @@ export type PropChange = {
     before: string;
     after: string;
 };
+/**
+ * The before dir carries a bundle MANIFEST but ZERO captures while the after dir
+ * held some — a restore or capture that claims success yet delivered no maps (a
+ * corrupt bundle, a wrong --base-dir pointed at a manifest-only dir). Without
+ * this guard every after surface diffs as `missing: 'before'` (exit 3, "only new
+ * surfaces") and a whole app of regressions becomes one approvable "🆕 all new"
+ * report. The CLIs map this to exit 2 — a hard error, never the rubber-stampable
+ * exit 3. A truly BARE base dir (no manifest, no maps) is different: it means
+ * "never captured — no baseline exists yet", the first-adoption flow where the
+ * base commit predates the capture spec, and it keeps the exit-3 review path.
+ * (Both dirs empty stays the plain "no captures found" throw.)
+ */
+export declare class MissingBaseMapError extends Error {
+    constructor();
+}
+/**
+ * The mirror case: the AFTER (head) dir held ZERO captures while the before dir
+ * held some — a head capture or restore that produced nothing. Without this
+ * guard every base surface marks `missing: 'after'`, the CLI's new-surface count
+ * (which tallies BOTH directions) exits 3, and a head that rendered nothing
+ * becomes an approvable "all new surfaces" report — and, once approved, the
+ * next base. Same exit-2 path via the CLIs' existing catch.
+ */
+export declare class MissingHeadMapError extends Error {
+    constructor();
+}
 export type Finding = {
     kind: 'dom';
     path: string;

package/dist/diff.js

@@ -1,8 +1,42 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadStyleMap, isUnder } from './capture.js';
-import { isMapFile } from './map-store.js';
+import { isMapFile, MAP_MANIFEST } from './map-store.js';
 import { styleValuesEqual } from './canonicalize.js';
+/**
+ * The before dir carries a bundle MANIFEST but ZERO captures while the after dir
+ * held some — a restore or capture that claims success yet delivered no maps (a
+ * corrupt bundle, a wrong --base-dir pointed at a manifest-only dir). Without
+ * this guard every after surface diffs as `missing: 'before'` (exit 3, "only new
+ * surfaces") and a whole app of regressions becomes one approvable "🆕 all new"
+ * report. The CLIs map this to exit 2 — a hard error, never the rubber-stampable
+ * exit 3. A truly BARE base dir (no manifest, no maps) is different: it means
+ * "never captured — no baseline exists yet", the first-adoption flow where the
+ * base commit predates the capture spec, and it keeps the exit-3 review path.
+ * (Both dirs empty stays the plain "no captures found" throw.)
+ */
+export class MissingBaseMapError extends Error {
+    constructor() {
+        super('base map missing: restore it from the map store or recapture both sides — refusing to treat every surface as new. ' +
+            'Next: run styleproof-map --restore --sha <base>, or let CI recapture both sides.');
+        this.name = 'MissingBaseMapError';
+    }
+}
+/**
+ * The mirror case: the AFTER (head) dir held ZERO captures while the before dir
+ * held some — a head capture or restore that produced nothing. Without this
+ * guard every base surface marks `missing: 'after'`, the CLI's new-surface count
+ * (which tallies BOTH directions) exits 3, and a head that rendered nothing
+ * becomes an approvable "all new surfaces" report — and, once approved, the
+ * next base. Same exit-2 path via the CLIs' existing catch.
+ */
+export class MissingHeadMapError extends Error {
+    constructor() {
+        super('head map missing: the head capture produced zero surfaces — recapture the head side; refusing to treat every surface as removed/new. ' +
+            'Next: re-run styleproof-map on the head commit, or let CI recapture both sides.');
+        this.name = 'MissingHeadMapError';
+    }
+}
 function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     const changed = [];
     for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
@@ -189,6 +223,25 @@ export function diffStyleMapDirs(dirA, dirB) {
     const names = [...new Set([...Object.keys(indexA), ...Object.keys(indexB)])].sort();
     if (names.length === 0)
         throw new Error(`no .json(.gz) captures found in ${dirA} or ${dirB}`);
+    // A whole side with zero captures is a missing MAP, not a set of genuinely
+    // new/removed surfaces — either way every surface would carry a `missing`
+    // marker and the run would read as "all new" (exit 3, approvable). Refuse
+    // each direction loudly with its own named cause — with one exception:
+    //
+    // Base side: only when the dir carries a bundle manifest. Manifest + zero maps
+    // means a restore/capture that claims success yet delivered nothing (a corrupt
+    // bundle) — breakage. A BARE dir (no manifest either) means no baseline was
+    // ever captured — the first-adoption flow, where the recapture fallback checks
+    // out a base commit that predates the capture spec. That legitimately yields
+    // zero surfaces and must keep the exit-3 "new surfaces, review before
+    // baselining" onboarding path, so it falls through.
+    if (Object.keys(indexA).length === 0 && fs.existsSync(path.join(dirA, MAP_MANIFEST)))
+        throw new MissingBaseMapError();
+    // Head side: UNCONDITIONAL (bare or manifest-present). The onboarding
+    // asymmetry only exists on the base side — the head is the commit under test,
+    // so a head that produced zero captures is always breakage, never a review flow.
+    if (Object.keys(indexB).length === 0)
+        throw new MissingHeadMapError();
     const surfaces = [];
     const counts = { dom: 0, style: 0, state: 0 };
     let volatile = 0;

package/dist/index.d.ts

@@ -15,11 +15,13 @@ 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 { selectCrawlLinks, defaultLinkKey, crawlCoverageGaps, crawlCoverageError } from './crawl.js';
+export type { CrawlLink, LinkMatch, SelectLinksOptions, CrawlCoverageGaps } 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';
 export type { ReportOptions, ReportResult } from './report.js';
+export { affectedSurfaces, classifyStyleChange } from './affected-surfaces.js';
+export type { ModuleEdge, AffectedSurfacesInput, AffectedSurfaces } from './affected-surfaces.js';

package/dist/index.js

@@ -8,7 +8,8 @@ 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 { selectCrawlLinks, defaultLinkKey, crawlCoverageGaps, crawlCoverageError } 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';
+export { affectedSurfaces, classifyStyleChange } from './affected-surfaces.js';

package/dist/map-store.d.ts

@@ -3,6 +3,10 @@ export declare const DEFAULT_MAP_LABEL = "current";
 export declare const DEFAULT_MAP_STORE_BRANCH = "styleproof-maps";
 export declare const DEFAULT_REMOTE = "origin";
 export declare const MAP_MANIFEST = "styleproof-manifest.json";
+/** Sidecar written during a capture run (where a browser handle is in scope) recording
+ *  the real browser build (`browser().version()`). `writeMapManifest` runs after Playwright
+ *  has exited — no browser — so it reads the build back from here. Not a surface map. */
+export declare const BROWSER_BUILD_SIDECAR = "styleproof-browser.json";
 /** Bundle files that sit alongside the maps but are NOT surfaces (manifest, coverage
  *  ledger, and any future sidecar). Every place that enumerates surface maps must skip
  *  these, or a sidecar reads as a phantom "new surface". */
@@ -21,6 +25,10 @@ export interface MapManifest {
     lockfile?: string;
     lockfileHash?: string;
     playwrightVersion?: string;
+    /** Real browser build (`browser().version()`), recorded at capture time. The npm
+     *  `@playwright/test` version can hold constant while this changes (re-download, a
+     *  different browser store, a CI image bump), so this is what actually gates a compare. */
+    browserVersion?: string;
     platform: string;
     arch: string;
     nodeMajor: string;
@@ -39,6 +47,9 @@ export interface CachedCaptureDirs {
     compatibilityKey: string;
     tmpRoot: string;
 }
+/** Record the real browser build into the capture dir. Called from a capture run, where a
+ *  Playwright browser handle is in scope. Best-effort: a missing version is simply not written. */
+export declare function writeBrowserBuildSidecar(dir: string, browserVersion: string | undefined): void;
 export declare function expectedCompatibilityKey(options?: {
     cwd?: string;
     spec?: string;

package/dist/map-store.js

@@ -11,11 +11,19 @@ export const DEFAULT_MAP_LABEL = 'current';
 export const DEFAULT_MAP_STORE_BRANCH = 'styleproof-maps';
 export const DEFAULT_REMOTE = 'origin';
 export const MAP_MANIFEST = 'styleproof-manifest.json';
+/** Sidecar written during a capture run (where a browser handle is in scope) recording
+ *  the real browser build (`browser().version()`). `writeMapManifest` runs after Playwright
+ *  has exited — no browser — so it reads the build back from here. Not a surface map. */
+export const BROWSER_BUILD_SIDECAR = 'styleproof-browser.json';
 const GENERATED_DIRTY_ALLOWLIST = new Set(['next-env.d.ts']);
 /** Bundle files that sit alongside the maps but are NOT surfaces (manifest, coverage
  *  ledger, and any future sidecar). Every place that enumerates surface maps must skip
  *  these, or a sidecar reads as a phantom "new surface". */
-export const RESERVED_BUNDLE_FILES = new Set([MAP_MANIFEST, COVERAGE_LEDGER]);
+export const RESERVED_BUNDLE_FILES = new Set([
+    MAP_MANIFEST,
+    COVERAGE_LEDGER,
+    BROWSER_BUILD_SIDECAR,
+]);
 /** True for a captured surface map (`<key>@<width>.json[.gz]`), false for metadata. */
 export function isMapFile(name) {
     return !RESERVED_BUNDLE_FILES.has(name) && /\.json(\.gz)?$/.test(name);
@@ -71,6 +79,23 @@ function detectLockfile(cwd) {
     }
     return {};
 }
+/** Record the real browser build into the capture dir. Called from a capture run, where a
+ *  Playwright browser handle is in scope. Best-effort: a missing version is simply not written. */
+export function writeBrowserBuildSidecar(dir, browserVersion) {
+    if (!browserVersion)
+        return;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, BROWSER_BUILD_SIDECAR), JSON.stringify({ browserVersion }, null, 2));
+}
+function readBrowserBuildSidecar(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, BROWSER_BUILD_SIDECAR), 'utf8'));
+        return parsed.browserVersion;
+    }
+    catch {
+        return undefined;
+    }
+}
 function hasHar(dir) {
     if (!fs.existsSync(dir))
         return false;
@@ -137,6 +162,7 @@ export function remoteExists(remote = DEFAULT_REMOTE, cwd = process.cwd()) {
 export function writeMapManifest(options) {
     const cwd = options.cwd ?? process.cwd();
     const input = compatibilityInput({ cwd, spec: options.spec, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
+    const browserVersion = readBrowserBuildSidecar(options.dir);
     const manifest = {
         version: 1,
         packageVersion: input.packageVersion,
@@ -147,6 +173,7 @@ export function writeMapManifest(options) {
         ...(input.lockfile ? { lockfile: input.lockfile } : {}),
         ...(input.lockfileHash ? { lockfileHash: input.lockfileHash } : {}),
         ...(input.playwrightVersion ? { playwrightVersion: input.playwrightVersion } : {}),
+        ...(browserVersion ? { browserVersion } : {}),
         platform: input.platform,
         arch: input.arch,
         nodeMajor: input.nodeMajor,
@@ -186,12 +213,20 @@ export function assertCompatibleMapDirs(beforeDir, afterDir) {
         playwrightVersion: after.playwrightVersion ?? '',
         baseUrl: after.baseUrl ?? '',
     };
+    // Browser build is the actual renderer, but it's optional: only compare when BOTH sides
+    // carry it, so bundles cached before this field existed stay comparable to each other.
+    // A field on one side only can't be a proven mismatch.
+    if (before.browserVersion && after.browserVersion) {
+        beforeRuntime.browserVersion = before.browserVersion;
+        afterRuntime.browserVersion = after.browserVersion;
+    }
     if (JSON.stringify(beforeRuntime) === JSON.stringify(afterRuntime))
         return;
+    const build = (m) => (m.browserVersion ? `, browser ${m.browserVersion}` : '');
     throw new MapStoreError([
         'maps were captured in different runtime environments',
-        `before ${before.sha.slice(0, 12)}: ${before.compatibilityKey} (${before.platform}/${before.arch}, Playwright ${before.playwrightVersion ?? 'unknown'})`,
-        `after  ${after.sha.slice(0, 12)}: ${after.compatibilityKey} (${after.platform}/${after.arch}, Playwright ${after.playwrightVersion ?? 'unknown'})`,
+        `before ${before.sha.slice(0, 12)}: ${before.compatibilityKey} (${before.platform}/${before.arch}, Playwright ${before.playwrightVersion ?? 'unknown'}${build(before)})`,
+        `after  ${after.sha.slice(0, 12)}: ${after.compatibilityKey} (${after.platform}/${after.arch}, Playwright ${after.playwrightVersion ?? 'unknown'}${build(after)})`,
         'Next: rebuild one side with styleproof-map in the same environment, or let CI recapture both maps.',
     ].join('\n'));
 }

package/dist/report.d.ts

@@ -56,6 +56,15 @@ export type ReportOptions = {
      * cause) for the reviewer's eye.
      */
     includeContent?: boolean;
+    /**
+     * Byte ceiling for report.md so GitHub can always render it (its markdown viewer
+     * refuses to render files past ~512 KB). Once the accumulated report would exceed
+     * this, the remaining changed surfaces are listed as one-liners (name · change
+     * count · crop link) instead of full property tables — the exhaustive per-row
+     * detail is always kept in report.json and every crop in crops/, so nothing is
+     * lost, just relocated. Default 400_000 (~0.4 MB). Set to Infinity to never cap.
+     */
+    maxReportBytes?: number;
 };
 export type ReportResult = {
     /** Surfaces carrying a reviewable change (excludes new, one-sided surfaces). */