styleproof 3.15.0 → 3.17.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.17.0] - 2026-07-05
+
+### Changed
+
+- **`report.md` is bounded so GitHub can always render it.** A large redesign used to
+  produce a `report.md` too big for GitHub's markdown viewer (it refuses to render past
+  ~512 KB) — the reviewer clicked through and got _"we can't show files this big"_, so the
+  report was useless exactly when the change was biggest. The generator now holds
+  `report.md` to a byte budget (`maxReportBytes`, default ~400 KB): it emits full property
+  tables greedily, then lists any remaining changed surfaces as one-liners (name · change
+  count · crop link) under an announced banner. The exhaustive per-row detail is always in
+  `report.json` and every crop in `crops/`, so nothing is dropped from the certification —
+  only the inline detail is capped. A report a reviewer can't open isn't a source of truth.
+
+### Added
+
+- **`affectedSurfaces` — selective-remap core (opt-in, advisory).** Given the files a
+  change touched, a declared surface→entry map, and a module graph (any tool's output
+  in `{ from, to }` shape — dependency-cruiser maps directly), returns exactly the
+  surfaces that could have rendered differently, or the sentinel `'all'`. Sound by
+  construction: it over-approximates and resolves every uncertainty to `'all'` — global
+  stylesheets/tokens, vanilla (unscoped) stylesheets, `createGlobalStyle`, design-system
+  configs, unbounded `import(x)`, and unplaceable files all force a full re-capture;
+  computed `import(`../dir/${x}`)` is recovered as a bundler context module (directory-
+  level, never a miss). Ships with `classifyStyleChange`. Purely additive, adds no
+  dependency, and never touches the default gate — the gate still captures every surface
+  and lets the map be the oracle. New export; existing specs unaffected.
+
+## [3.16.0] - 2026-07-05
+
+### Added
+
+- **The scaffolded PR workflow prunes its own report branch, out of the box.**
+  `styleproof-init`'s `.github/workflows/styleproof.yml` now also runs on
+  `pull_request: closed`: when a PR closes, a `prune` job removes that PR's `pr-<n>/`
+  folder from the report branch (`styleproof-reports`), so the branch no longer grows
+  without bound as PRs come and go — no adopter has to remember to garbage-collect it.
+  The report job is unchanged, only guarded to skip the close event. Covered by the
+  `styleproof-init` workflow test.
+
 ## [3.15.0] - 2026-07-05
 
 ### Changed

package/README.md

@@ -27,6 +27,7 @@ report. Intentional visual changes get approved; unexpected ones block or fail.
 - [Forks and Dependabot](#forks-and-dependabot)
 - [Optional: content layer](#optional-content-layer-advisory)
 - [Optional: React component layer](#optional-react-component-layer-advisory)
+- [Optional: selective remap](#optional-selective-remap-advisory)
 - [Newly-added elements show their full style](#newly-added-elements-show-their-full-style)
 - [Reference](#reference)
   - [Blocking without branch protection](#blocking-without-branch-protection)
@@ -679,6 +680,37 @@ Capture reads the React fiber in-page (`__reactFiber$*`/`__reactProps$*` on Reac
 
 Like the content layer it is **advisory**: never fed to the certification diff or the gate, so captures stay deterministic. Component names are mangled in minified production builds, so it's most useful against a dev / non-minified target; on a non-React page the fiber keys are absent and the field is simply omitted.
 
+## Optional: selective remap (advisory)
+
+On a large app, capturing every surface on every PR is the slow part. `affectedSurfaces` answers the question that lets you skip most of it: **given the files a change touched, which declared surfaces could have rendered differently?** Everything it doesn't return can reuse its committed base map.
+
+It is **opt-in and never part of the default gate** — the gate still captures every surface and lets the map be the oracle. This is a helper for wiring a faster pre-push/CI path yourself, and it is built to be wrong only in the safe direction: when it cannot _prove_ a surface is unaffected, it returns the sentinel `'all'` (re-capture everything). A global stylesheet or token, a vanilla (unscoped) stylesheet, a `createGlobalStyle`, a design-system config, an unbounded `import(x)`, or a file it can't place — all resolve to `'all'`.
+
+The module graph is an **input**, so StyleProof stays framework-agnostic and adds no dependency. Produce it with any tool whose output you can shape into `{ from, to }` edges — [dependency-cruiser](https://www.npmjs.com/package/dependency-cruiser)'s `modules[].dependencies[]` maps directly:
+
+```ts
+import { affectedSurfaces } from 'styleproof';
+import { readFileSync } from 'node:fs';
+
+// A dependency-cruiser run: `depcruise src --no-config --output-type json`
+const cruise = JSON.parse(readFileSync('dc.json', 'utf8'));
+const graph = cruise.modules.flatMap((m) =>
+  (m.dependencies ?? []).map((d) => ({ from: m.source, to: d.resolved, dynamic: d.dynamic })),
+);
+
+const result = affectedSurfaces({
+  changedFiles: ['src/components/PriceTable.tsx'], // e.g. `git diff --name-only origin/main`
+  surfaces: { home: 'src/pages/Home.tsx', pricing: 'src/pages/Pricing.tsx' },
+  graph,
+  files: cruise.modules.map((m) => m.source),
+  readFile: (p) => readFileSync(p, 'utf8'),
+});
+// → Set { 'pricing' }  (capture only these; reuse the base map for the rest)
+// → 'all'              (some change couldn't be bounded — capture everything)
+```
+
+Two honest limits, both resolving to `'all'`: a computed `import(`../dir/${x}`)` is treated as a bundler **context module** (every file under that dir is a possible target, so precision there is directory-level, never a miss); and the CSS-in-JS global list (`createGlobalStyle`, `injectGlobal`, `globalStyle`, …) must match the libraries you use — an unrecognized global API is the one way a scoped verdict could be unsound, so treat an unsupported styling system as a reason to skip selective remap. Because a PR-time miss would be silent, always let `main` (or a scheduled run) capture **all** surfaces as the trust-but-verify net.
+
 ## Newly-added elements show their full style
 
 When a PR **adds** an element, StyleProof now reports its **full resting computed style** (background, padding, font, radius, …), value-only, in addition to any interaction-state deltas — previously an added element surfaced only its `:hover`/`:focus` changes. The new element already gates via its `added` finding; this only enriches what you see, in both the report and the `styleproof-diff` CLI.

package/bin/styleproof-init.mjs

@@ -345,7 +345,9 @@ const CI_WORKFLOW = `name: StyleProof
 #   report without a browser;
 # - on cache miss, CI recaptures both sides in one pinned environment so the
 #   comparison stays valid.
-on: pull_request
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
 
 permissions:
   contents: write
@@ -355,6 +357,8 @@ permissions:
 
 jobs:
   styleproof:
+    # Report on open/update; the prune job below handles close.
+    if: github.event.action != 'closed'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -408,6 +412,41 @@ ${PM.setup}
           baseline-dir: __stylemaps__/base
           fresh-dir: __stylemaps__/head
           require-approval: true
+
+  prune:
+    # PR closed: drop its pr-<n>/ folder from the report branch so the branch
+    # never grows without bound. Keep BRANCH in sync with the report-branch
+    # input above (default: styleproof-reports).
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Prune this PR's report folder
+        shell: bash
+        env:
+          GH_TOKEN: \${{ github.token }}
+          BRANCH: styleproof-reports
+          PR: \${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          REMOTE="https://x-access-token:\${GH_TOKEN}@github.com/\${{ github.repository }}.git"
+          if ! git ls-remote --exit-code "$REMOTE" "refs/heads/$BRANCH" >/dev/null 2>&1; then
+            echo "No $BRANCH branch yet — nothing to prune."; exit 0
+          fi
+          TMP="$(mktemp -d)"
+          # Blobless clone keeps this fast; a very large report branch may prefer
+          # a --no-checkout plumbing rewrite instead.
+          git clone --filter=blob:none --single-branch --branch "$BRANCH" "$REMOTE" "$TMP"
+          cd "$TMP"
+          if [ ! -d "pr-$PR" ]; then
+            echo "No pr-$PR/ folder — nothing to prune."; exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git rm -r --quiet "pr-$PR"
+          git commit -m "chore(styleproof): prune report for closed PR #$PR"
+          git push origin "$BRANCH"
 `;
 
 function writeFileSafe(file, contents, { force: f } = {}) {

package/dist/affected-surfaces.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+/** One resolved import edge: `from` imports `to`. Mirrors a dependency-cruiser
+ *  `modules[].dependencies[]` entry (use `module.source` as `from`, dependency
+ *  `resolved` as `to`). `dynamic` is informational; resolution already happened. */
+export type ModuleEdge = {
+    from: string;
+    to: string;
+    dynamic?: boolean;
+};
+export type AffectedSurfacesInput = {
+    /** Repo-relative paths the change touched (as they appear in the graph). */
+    changedFiles: Iterable<string>;
+    /** Declared surfaces: capture key → the surface's entry module path. */
+    surfaces: Record<string, string>;
+    /** Resolved import edges for the source tree (node_modules edges are ignored). */
+    graph: Iterable<ModuleEdge>;
+    /** Every candidate source file path — the universe a context-module glob can
+     *  resolve within. Typically the graph's node set. */
+    files: Iterable<string>;
+    /** Read a source file's text (for style classification and dynamic-import
+     *  recovery). Throwing/returning nothing is treated as "unknown" → `'all'`. */
+    readFile: (path: string) => string;
+};
+/** `'all'` means "re-capture everything" (some change could not be bounded). A
+ *  `Set` of surface keys means exactly those surfaces can be affected; any not
+ *  listed are provably unaffected and may reuse their committed base map. */
+export type AffectedSurfaces = Set<string> | 'all';
+/**
+ * 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 declare function classifyStyleChange(file: string, readFile: (p: string) => string): 'scope' | 'all';
+/**
+ * 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 declare function affectedSurfaces(input: AffectedSurfacesInput): AffectedSurfaces;

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/index.d.ts

@@ -23,3 +23,5 @@ export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, find
 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

@@ -12,3 +12,4 @@ export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
 export { harvestStyleVariants } from './variant-crawler.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';
+export { affectedSurfaces, classifyStyleChange } from './affected-surfaces.js';

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). */

package/dist/report.js

@@ -1196,6 +1196,31 @@ function renderNewSurface(p, ctx, cropSeq) {
     md.push('', `_No baseline to compare against — this surface is new. Review and approve it before it becomes part of the baseline._`);
     return { md, json, cropSeq };
 }
+/** The one-time banner where report.md switches from full detail to one-line
+ *  summaries, so the reader knows nothing is missing — only relocated to report.json. */
+function cappedNoticeLines(budget) {
+    return [
+        '',
+        '## … more changed surfaces (summarized to keep this report renderable)',
+        '',
+        `_This report reached its ~${Math.round(budget / 1000)} KB display budget (GitHub does not render ` +
+            `markdown past ~512 KB), so the surfaces below are listed as one-liners. Their full property ` +
+            `tables are in \`report.json\` and their crops in \`crops/\` — the certification above covers every ` +
+            `surface; only the inline detail is capped._`,
+        '',
+    ];
+}
+/** One-line summary for a changed surface whose full detail was budget-capped: its
+ *  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 more = cg.surfaces.length > 1 ? ` (+${cg.surfaces.length - 1} more)` : '';
+    const regions = json.regions ?? [];
+    const composite = regions[0]?.images?.composite;
+    const link = composite ? ` — [crop](${img(composite)})` : '';
+    return `- \`${surface}\`${more} · ${cg.rep.findings.length} change(s)${link}`;
+}
 export function generateStyleMapReport(opts) {
     const { beforeDir, afterDir, outDir, imageBaseUrl = '', 
     // Tighter than before (was 24) so the change fills the frame — the annotation
@@ -1203,7 +1228,7 @@ export function generateStyleMapReport(opts) {
     pad: padBy = 12, minWidth = 320, minHeight = 180, maxHeight = 1600, zoomBelow = 64, 
     // More, smaller crops before collapsing (was 6), so distinct changes get their
     // own focused frame rather than one wide merged one.
-    maxCrops = 8, foldDetailsAt = 0, } = opts;
+    maxCrops = 8, foldDetailsAt = 0, maxReportBytes = 400_000, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
     const includeContent = opts.includeContent ?? false;
     const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
@@ -1261,18 +1286,38 @@ export function generateStyleMapReport(opts) {
     }));
     let totalFindings = 0;
     let cropSeq = 0;
+    // report.md must stay renderable — GitHub refuses to render markdown past ~512 KB.
+    // Emit full detail greedily until the byte budget is reached, then list any remaining
+    // surfaces as one-liners. The exhaustive per-row detail is always in report.json and
+    // every crop in crops/, so the cap changes what's shown inline, never what's certified.
+    let reportBytes = md.join('\n').length;
+    let capped = false;
+    const emitDetail = (detail, summary) => {
+        const cost = detail.join('\n').length + 1;
+        if (!capped && reportBytes + cost <= maxReportBytes) {
+            md.push(...detail);
+            reportBytes += cost;
+            return;
+        }
+        if (!capped) {
+            md.push(...cappedNoticeLines(maxReportBytes));
+            capped = true;
+        }
+        md.push(summary);
+        reportBytes += summary.length + 1;
+    };
     for (const cg of changeGroups) {
         const r = renderChangeGroup(cg, ctx, maxCrops, cropSeq);
-        md.push(...r.md);
         json.push(r.json);
         totalFindings += r.findingCount;
         cropSeq = r.cropSeq;
+        emitDetail(r.md, compactChangeSummary(cg, r.json, img));
     }
     for (const p of missing) {
         const r = renderNewSurface(p, ctx, cropSeq);
-        md.push(...r.md);
         json.push(r.json);
         cropSeq = r.cropSeq;
+        emitDetail(r.md, `- \`${p.sd.surface}\` · new surface`);
     }
     md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.15.0",
+  "version": "3.17.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",