styleproof 3.17.0 → 3.19.0

package/dist/crawl.js

@@ -23,10 +23,19 @@
  * 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.
+ *
+ * Params are sorted by name before their values are joined, so the SAME logical
+ * route keys identically regardless of the order the nav happened to render its
+ * query string (`/?tab=a&x=b` and `/?x=b&tab=a` both → `a-b`). Without this the
+ * key flaps with render order and the coverage guard reports phantom
+ * nav-regressions / unowned routes for a route that never changed.
  */
 export function defaultLinkKey(url) {
     const segs = url.pathname.split('/').filter(Boolean);
-    const values = [...url.searchParams].map(([, v]) => v).filter(Boolean);
+    const values = [...url.searchParams]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, v]) => v)
+        .filter(Boolean);
     const slug = [...segs, ...values]
         .join('-')
         .replace(/[^a-zA-Z0-9]+/g, '-')
@@ -70,30 +79,97 @@ function toLink(href, base, keyFor, match) {
     url.hash = ''; // navigate the surface, not a scroll anchor within it
     return { key: keyFor(url), url: path };
 }
+/**
+ * Dedup identity for a navigable path+query: a trailing slash on the path is not a
+ * distinct surface (`/about` and `/about/` render the same route), so it's stripped
+ * from the identity — but never from the root `/` itself, and never from the query.
+ * The navigable url the caller returns keeps its original form; only the SET
+ * membership test is normalized, so the first-seen href still wins.
+ */
+function dedupIdentity(pathAndSearch) {
+    const q = pathAndSearch.indexOf('?');
+    const path = q === -1 ? pathAndSearch : pathAndSearch.slice(0, q);
+    const search = q === -1 ? '' : pathAndSearch.slice(q);
+    const normPath = path.length > 1 ? path.replace(/\/+$/, '') || '/' : path;
+    return normPath + search;
+}
 /**
  * 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
+ * survivors are deduped by path+query (trailing slash normalized — `/about` and
+ * `/about/` are one surface, not two). Order follows first appearance in `hrefs`, so
  * the capture order is the nav's order — stable across runs.
+ *
+ * Keys are then disambiguated: two GENUINELY different surfaces whose derived keys
+ * collide (e.g. `/a?tab=x` and `/b?tab=x` both → `x` under {@link defaultLinkKey})
+ * would otherwise both write `<key>@<width>.json.gz` and the second would silently
+ * overwrite the first — a captured surface vanishing without a trace. Instead the
+ * second gets a `-2` suffix (mirroring the surface crawler's `deriveKey`), so both
+ * survive as distinct maps. Trailing-slash duplicates never reach here — they're
+ * already deduped to one surface above — so this only fires on real collisions.
  */
 export function selectCrawlLinks(hrefs, opts) {
     const base = new URL(opts.base);
     const keyFor = opts.key ?? defaultLinkKey;
     const seen = new Set();
+    const usedKeys = new Set();
     const out = [];
+    // Disambiguate a key against those already emitted, mirroring deriveKey: first
+    // wins bare, the next collider gets `-2`, `-3`, … — deterministic in nav order.
+    const uniqueKey = (key) => {
+        let k = key;
+        for (let i = 2; usedKeys.has(k); i++)
+            k = `${key}-${i}`;
+        usedKeys.add(k);
+        return k;
+    };
+    const push = (link) => {
+        out.push({ key: uniqueKey(link.key), url: link.url });
+    };
     if (opts.includeSelf) {
         const selfUrl = base.pathname + base.search;
-        seen.add(selfUrl);
-        out.push({ key: keyFor(base), url: selfUrl });
+        seen.add(dedupIdentity(selfUrl));
+        push({ key: keyFor(base), url: selfUrl });
     }
     for (const href of hrefs) {
         const link = href ? toLink(href, base, keyFor, opts.match) : null;
-        if (!link || seen.has(link.url))
+        if (!link)
             continue;
-        seen.add(link.url);
-        out.push(link);
+        const id = dedupIdentity(link.url);
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        push(link);
     }
     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/danger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The ONE destructive-action guard, shared by every surface-discovery crawler
+ * (the exhaustive surface crawler in `crawl-surfaces.ts` and the one-step variant
+ * harvester in `variant-crawler.ts`). Mapping must never mutate: a control whose
+ * label matches this pattern is recorded but never clicked.
+ *
+ * Kept as a plain string (not a `RegExp`) because both crawlers build their
+ * candidate list inside `page.evaluate` — the classifier function is serialized
+ * into the browser, so it cannot close over a `RegExp` from Node. The source is
+ * passed in as an argument and recompiled in the browser; this module is the
+ * single source of truth for what "destructive" means.
+ */
+export declare const DANGER_SOURCE = "\\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\\b";

package/dist/danger.js

@@ -0,0 +1,13 @@
+/**
+ * The ONE destructive-action guard, shared by every surface-discovery crawler
+ * (the exhaustive surface crawler in `crawl-surfaces.ts` and the one-step variant
+ * harvester in `variant-crawler.ts`). Mapping must never mutate: a control whose
+ * label matches this pattern is recorded but never clicked.
+ *
+ * Kept as a plain string (not a `RegExp`) because both crawlers build their
+ * candidate list inside `page.evaluate` — the classifier function is serialized
+ * into the browser, so it cannot close over a `RegExp` from Node. The source is
+ * passed in as an argument and recompiled in the browser; this module is the
+ * single source of truth for what "destructive" means.
+ */
+export const DANGER_SOURCE = '\\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\\b';

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)])) {
@@ -36,7 +70,9 @@ function dropLayoutEquivalentMarginProps(props, a, b) {
 }
 function pxParts(value) {
     const parts = value.trim().split(/\s+/);
-    if (parts.length < 2 || parts.length > 3)
+    // 1–3 components: a single-value origin (`50px`) jitters the same way as the
+    // 2/3-component form and must be suppressed identically.
+    if (parts.length < 1 || parts.length > 3)
         return null;
     const values = parts.map((part) => {
         const match = /^(-?\d+(?:\.\d+)?)px$/.exec(part);
@@ -189,6 +225,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,13 +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 { affectedSurfaces, classifyStyleChange, explainAffectedSurfaces } from './affected-surfaces.js';
 export type { ModuleEdge, AffectedSurfacesInput, AffectedSurfaces } from './affected-surfaces.js';

package/dist/index.js

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

package/dist/inventory.js

@@ -50,7 +50,9 @@ export function collectNavAffordances() {
     };
     const nameOf = (el) => (el.getAttribute('aria-label') || el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80);
     const internalPath = (el) => {
-        const raw = (el.getAttribute('href') || '').trim();
+        // SVG anchors carry the target in `xlink:href` (legacy) or `href`; fall back so
+        // an <svg><a> nav link resolves like an HTML one.
+        const raw = (el.getAttribute('href') || el.getAttribute('xlink:href') || '').trim();
         if (!raw || raw.startsWith('#'))
             return null;
         try {
@@ -67,14 +69,18 @@ export function collectNavAffordances() {
     // Erring broad is correct here: a stray non-nav button is harmless noise, but a
     // MISSED nav item defeats the guard. Prefer semantic markup (role=tablist) for
     // fully reliable harvesting; see docs/inventory-guard.md.
-    const SEL = 'a[href], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], nav button, [role="navigation"] button, [role="tablist"] button, [class*="navtab" i] button, [class*="nav-tab" i] button, [class*="subnav" i] button, [class*="subtab" i] button, [class*="tabs" i] button';
+    // `a[*|href]` (any-namespace href) not `a[href]`: an SVG anchor may carry only the
+    // XLink-namespaced `xlink:href`, which `a[href]` never selects — so the xlink:href
+    // fallback in internalPath would be dead without it.
+    const SEL = 'a[*|href], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], nav button, [role="navigation"] button, [role="tablist"] button, [class*="navtab" i] button, [class*="nav-tab" i] button, [class*="subnav" i] button, [class*="subtab" i] button, [class*="tabs" i] button';
     return Array.from(document.querySelectorAll(SEL))
         .filter(visible)
         .map((el) => ({
         tag: el.tagName.toLowerCase(),
         role: (el.getAttribute('role') || '').toLowerCase(),
         name: nameOf(el),
-        internalPath: el.tagName === 'A' ? internalPath(el) : null,
+        // SVG anchors report tagName `a` (lowercase), HTML reports `A` — match either.
+        internalPath: el.tagName.toLowerCase() === 'a' ? internalPath(el) : null,
         testId: el.getAttribute('data-testid'),
         domId: el.getAttribute('id'),
         controls: el.getAttribute('aria-controls'),

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,13 @@ 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. Write-or-CLEAR semantics: an undefined version
+ *  REMOVES any existing sidecar rather than leaving it, so a reused capture dir (e.g. the
+ *  default `.styleproof/maps/current`) can never carry a PRIOR run's build into this run's
+ *  manifest — that would stamp a false browser-build fingerprint the compatibility guard
+ *  then trusts. Best-effort: the delete is forced and ignores a missing file. */
+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,30 @@ 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. Write-or-CLEAR semantics: an undefined version
+ *  REMOVES any existing sidecar rather than leaving it, so a reused capture dir (e.g. the
+ *  default `.styleproof/maps/current`) can never carry a PRIOR run's build into this run's
+ *  manifest — that would stamp a false browser-build fingerprint the compatibility guard
+ *  then trusts. Best-effort: the delete is forced and ignores a missing file. */
+export function writeBrowserBuildSidecar(dir, browserVersion) {
+    const sidecar = path.join(dir, BROWSER_BUILD_SIDECAR);
+    if (!browserVersion) {
+        fs.rmSync(sidecar, { force: true });
+        return;
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(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 +169,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 +180,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 +220,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.js

@@ -385,6 +385,14 @@ export function prettyLabel(p, cls) {
     const first = cls.split(/\s+/)[0] ?? '';
     return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
 }
+// Surface keys originate from artifact filenames — attacker-controlled in the
+// fork capture/report split, and they flow into the PRIVILEGED PR-comment summary
+// (the Action slices report.md above the first `### `). Strip the Markdown/HTML
+// control characters (`` ` ``, [ ] ( ), < >, |) that could inject a link, image,
+// or table into that bot comment. Escaping at the render boundary — the keys stay
+// legible; only the injection surface is removed. (Crop FILENAMES are separately
+// restricted to [a-z0-9-]; this is the display-side equivalent.)
+const safeKey = (s) => s.replace(/[`[\]()<>|]/g, '-');
 const surfaceBase = (s) => s.replace(/@\d+$/, '');
 const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
 function pushSurfaceWidth(byBase, base, surface) {
@@ -396,7 +404,7 @@ function renderSurfaceGroups(byBase) {
     return [...byBase]
         .map(([base, ws]) => {
         const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
-        return widths.length ? `${base} @ ${widths.join(', ')}` : base;
+        return widths.length ? `${safeKey(base)} @ ${widths.join(', ')}` : safeKey(base);
     })
         .join(' · ');
 }
@@ -502,9 +510,26 @@ function regionHeading(regionPaths, findings) {
     const label = anchors.length > 1 ? `\`${head}\` + ${anchors.length - 1} more` : `\`${head}\``;
     return `${label} · ${groupTitle(findings)}`;
 }
+// CSS values are author/attacker-influenced (content:"…", url("…"), font-family
+// strings), so at the render boundary they get their OWN escaper — distinct from
+// safeKey, which strips control chars from surface keys. Values must stay READABLE
+// (a mangled url(…) is useless), so we ESCAPE rather than strip:
+//   • `|` → `\|`   — an unescaped pipe splits the table row (GitHub honours the
+//                     backslash even inside a code span).
+//   • backticks   — a bare backtick would close the code span and leak live
+//                     Markdown; widen the fence to one more backtick than the
+//                     value's longest run, padding a space when it touches an edge
+//                     (GitHub's rule for a code span that starts/ends with a tick).
+function codeValue(v) {
+    const escaped = v.replace(/\|/g, '\\|');
+    const longestRun = Math.max(0, ...(escaped.match(/`+/g) ?? []).map((r) => r.length));
+    const fence = '`'.repeat(longestRun + 1);
+    const pad = /^`|`$/.test(escaped) ? ' ' : '';
+    return `${fence}${pad}${escaped}${pad}${fence}`;
+}
 // A "no value here" marker renders as an em dash; colours render as `#hex` so the
 // table cell shows GitHub's live swatch.
-const cell = (v) => (isNonValue(v) ? '—' : `\`${toHex(v)}\``);
+const cell = (v) => (isNonValue(v) ? '—' : codeValue(toHex(v)));
 // Long values (gradients, data URIs) would swamp the table, but truncating each
 // side independently can show two IDENTICAL cells for a real diff: both
 // sides of a gradient rendered as the same rgba while the actual change — a
@@ -537,7 +562,7 @@ function cellPair(before, after) {
     if (isNonValue(before) || isNonValue(after))
         return [cell(before), cell(after)];
     const [b, a] = excerptPair(before, after);
-    return [`\`${toHex(b)}\``, `\`${toHex(a)}\``];
+    return [codeValue(toHex(b)), codeValue(toHex(a))];
 }
 function beforeAfterTable(rows) {
     return [
@@ -545,14 +570,14 @@ function beforeAfterTable(rows) {
         '| --- | --- | --- |',
         ...rows.map((r) => {
             const [b, a] = cellPair(r.before, r.after);
-            return `| \`${r.prop}\` | ${b} | ${a} |`;
+            return `| ${codeValue(r.prop)} | ${b} | ${a} |`;
         }),
     ];
 }
 // 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)} |`)];
+    return ['| Property | Value |', '| --- | --- |', ...rows.map((r) => `| ${codeValue(r.prop)} | ${cell(r.after)} |`)];
 }
 /** `Button (variant=primary, size=sm)` — the React component + sanitized props
  *  the element captured (advisory; present only with captureComponent). */
@@ -579,8 +604,8 @@ function statesSection(states, added) {
         for (const c of summarizeProps(st.props)) {
             const [b, a] = cellPair(c.before, c.after);
             rows.push(added
-                ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
-                : `| \`:${st.state}\` | \`${c.prop}\` | ${b} → ${a} |`);
+                ? `| ${codeValue(`:${st.state}`)} | ${codeValue(c.prop)} | ${cell(c.after)} |`
+                : `| ${codeValue(`:${st.state}`)} | ${codeValue(c.prop)} | ${b} → ${a} |`);
         }
     if (!rows.length)
         return [];
@@ -821,7 +846,7 @@ function renderContentSurface(ctx, surface, changes, seq) {
     const mapB = loadStyleMap(findCapture(ctx.afterDir, surface));
     const pngA = readPng(path.join(ctx.beforeDir, `${surface}.png`));
     const pngB = readPng(path.join(ctx.afterDir, `${surface}.png`));
-    const md = ['', `### \`${surface}\` · ${changes.length} content change(s)`];
+    const md = ['', `### \`${safeKey(surface)}\` · ${changes.length} content change(s)`];
     for (const c of changes) {
         seq++;
         md.push('', `**\`${prettyLabel(c.path, c.cls)}\`**`, '', `- before: \`${clipText(c.before) || '(empty)'}\``, `- after: \`${clipText(c.after) || '(empty)'}\``, ...contentCropLines(ctx, surface, c, mapA, mapB, pngA, pngB, seq));
@@ -888,7 +913,7 @@ function coverageLine(cov) {
     if (cov.basis === 'complete')
         return `- **Coverage** — ✓ complete (all ${cov.registrySize} registered surface(s) captured)`;
     if (cov.basis === 'incomplete')
-        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.join(', ')})`;
+        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.map(safeKey).join(', ')})`;
     return '- **Coverage** — ⚠ not asserted (no `expected` registry; certifies only the captured surfaces)';
 }
 function determinismLine(det) {
@@ -900,7 +925,7 @@ function determinismLine(det) {
 }
 function inventoryLine(inv) {
     if (inv.unexplained.length > 0) {
-        const keys = inv.unexplained.map((i) => i.key);
+        const keys = inv.unexplained.map((i) => safeKey(i.key));
         return `- **Inventory** — ⚠ ${inv.unexplained.length} navigable affordance(s) removed, unacknowledged: ${keys.slice(0, 8).join(', ')}${keys.length > 8 ? ', …' : ''}`;
     }
     if (inv.delta.removed.length > 0)
@@ -1176,7 +1201,7 @@ function renderNewSurface(p, ctx, cropSeq) {
     const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
     const md = [
         '',
-        `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`,
+        `### \`${safeKey(p.sd.surface)}\` · new surface ${NEW_SURFACE_MARKER}`,
         '',
         `_${formatSurfaceWithContext(p.sd.surface, map)}_`,
     ];
@@ -1214,7 +1239,7 @@ function cappedNoticeLines(budget) {
  *  name (and how many surfaces share the identical change) · change count · a crop
  *  link so the reviewer can still see it without opening report.json. */
 function compactChangeSummary(cg, json, img) {
-    const surface = cg.rep.sd.surface;
+    const surface = safeKey(cg.rep.sd.surface);
     const more = cg.surfaces.length > 1 ? ` (+${cg.surfaces.length - 1} more)` : '';
     const regions = json.regions ?? [];
     const composite = regions[0]?.images?.composite;
@@ -1317,7 +1342,7 @@ export function generateStyleMapReport(opts) {
         const r = renderNewSurface(p, ctx, cropSeq);
         json.push(r.json);
         cropSeq = r.cropSeq;
-        emitDetail(r.md, `- \`${p.sd.surface}\` · new surface`);
+        emitDetail(r.md, `- \`${safeKey(p.sd.surface)}\` · new surface`);
     }
     md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');