styleproof 3.1.1 → 3.1.3

package/dist/capture.d.ts

@@ -58,7 +58,7 @@ export type ElementEntry = {
 export type CaptureMetadata = {
     surfaceKey?: string;
     variantKey?: string;
-    variantKind?: 'variant' | 'live-state';
+    variantKind?: 'variant' | 'live-state' | 'popup';
 };
 export type LiveRegionCandidate = {
     path: string;
@@ -76,10 +76,11 @@ export type StyleMap = {
     elements: Record<string, ElementEntry>;
     states: Record<string, Record<string, Record<string, Props>>>;
     /**
-     * True when the forced :hover/:focus/:active layer was skipped for this
-     * capture because of CDP/page interactive-element count skew. Persisted so a
-     * diff against a fully-captured side flags that the state layer wasn't
-     * certified, instead of silently reading as "identical".
+     * True when the forced :hover/:focus/:active layer was not fully captured for
+     * this capture — either CDP/page interactive-element count skew, or because the
+     * interactive-element count exceeded `maxInteractive` and capture was truncated.
+     * Persisted so a diff against a fully-captured side flags that the state layer
+     * wasn't certified, instead of silently reading as "identical".
      */
     statesSkipped?: boolean;
     /**

package/dist/capture.js

@@ -375,7 +375,8 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
     const marked = (await page.evaluate(markInteractiveElements, { selector: INTERACTIVE, skipSel, attr: STATE_ID_ATTR })).filter((m) => !(skipPaths.length && isUnder(m.path, skipPaths)));
     const limit = Math.min(marked.length, maxInteractive);
-    if (marked.length > maxInteractive) {
+    const truncated = marked.length > maxInteractive;
+    if (truncated) {
         // eslint-disable-next-line no-console
         console.warn(`styleproof: ${marked.length} interactive elements exceeds maxInteractive=${maxInteractive}; ` +
             `forced-state capture truncated to the first ${maxInteractive}. Raise maxInteractive to cover them all.`);
@@ -405,7 +406,10 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
         await page.evaluate(clearInteractiveMarks, STATE_ID_ATTR).catch(() => undefined);
         await client.detach();
     }
-    return { states, skipped: false };
+    // When truncated, the elements past the limit have no forced-state delta —
+    // flag the layer so the diff reports it as uncertified instead of letting the
+    // missing states read as "identical" against a fully-captured side.
+    return { states, skipped: truncated };
 }
 /** Element paths that differ between two captures (added, removed, or restyled). */
 function changedElementPaths(a, b) {
@@ -630,7 +634,9 @@ export async function captureStyleMap(page, options = {}) {
     // Detect semantic live-state candidates automatically, but don't exclude them
     // merely for being live regions. Stable status/alert/log UI is product UI and
     // should still be captured; this metadata only improves reports and diagnostics.
-    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore: FRAMEWORK_IGNORE });
+    // Honour the caller's `ignore` too: a region the user excluded shouldn't be
+    // surfaced (or persisted) as a live candidate, matching every other capture pass.
+    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore });
     // Motion longhands (transition/animation) are read separately so declared
     // motion is verified even though every other value is a frozen end state.
     // Read them on the SETTLED DOM, not before it: capturing pre-settle missed any

package/dist/cli-errors.d.ts

@@ -7,4 +7,3 @@ export declare function playwrightMissingMessage(message: string): string;
 export declare function missingWorkingMapsMessage(command: string, dir: string): string;
 export declare function missingManualCaptureMessage(command: string, dir: string): string;
 export declare function baseInferenceMessage(command: string, message: string): string;
-export declare function baseMapsMessage(command: string, message: string, baseRef: string, mapsDir: string): string;

package/dist/cli-errors.js

@@ -26,8 +26,8 @@ export function playwrightMissingMessage(message) {
 export function missingWorkingMapsMessage(command, dir) {
     return [
         `${command}: no capture at ${dir}`,
-        `Next: run styleproof-map to create ${dir}, then commit the updated maps.`,
-        'If your maps live elsewhere, pass --maps-dir <dir>.',
+        `Next: run styleproof-map to create ${dir}, or run styleproof-map --restore --sha <commit> to restore it from the map store.`,
+        'If your maps live elsewhere, pass explicit capture directories.',
     ].join('\n');
 }
 export function missingManualCaptureMessage(command, dir) {
@@ -42,9 +42,3 @@ export function baseInferenceMessage(command, message) {
         `Next: pass a base ref explicitly, e.g. ${command} main, or set git config branch.<name>.gh-merge-base main.`,
     ].join('\n');
 }
-export function baseMapsMessage(command, message, baseRef, mapsDir) {
-    return [
-        `${command}: ${message}`,
-        `Next: make sure ${baseRef} contains committed captures at ${mapsDir}. On the base branch, run styleproof-map and commit ${mapsDir}.`,
-    ].join('\n');
-}

package/dist/diff.js

@@ -101,8 +101,9 @@ export function diffStyleMaps(a, b) {
         }
     }
     // If the forced-state layer was skipped on exactly one side (CDP skew during
-    // that capture), the :hover/:focus/:active layer was not compared — flag it
-    // loudly rather than letting {} vs {} read as "identical".
+    // capture, or truncation past maxInteractive), the :hover/:focus/:active layer
+    // was not fully compared — flag it loudly rather than letting {} vs {} read as
+    // "identical".
     if (!!a.statesSkipped !== !!b.statesSkipped) {
         findings.push({
             kind: 'state',
@@ -113,8 +114,8 @@ export function diffStyleMaps(a, b) {
             props: [
                 {
                     prop: 'forced :hover/:focus/:active layer',
-                    before: a.statesSkipped ? 'skipped (CDP skew)' : 'captured',
-                    after: b.statesSkipped ? 'skipped (CDP skew)' : 'captured',
+                    before: a.statesSkipped ? 'not fully captured' : 'captured',
+                    after: b.statesSkipped ? 'not fully captured' : 'captured',
                 },
             ],
         });
@@ -152,7 +153,7 @@ function tallyCounts(findings, counts) {
 function indexDir(dir) {
     return Object.fromEntries(fs
         .readdirSync(dir)
-        .filter((f) => /\.json(\.gz)?$/.test(f))
+        .filter((f) => f !== 'styleproof-manifest.json' && /\.json(\.gz)?$/.test(f))
         .map((f) => [f.replace(/\.json(\.gz)?$/, ''), path.join(dir, f)]));
 }
 /** Diff every same-named capture between two directories. `volatile` is the

package/dist/gitref.d.ts

@@ -1,15 +1,5 @@
-/** A readable failure materialising a base from git — CLIs map this to exit 2. */
+/** A readable failure inferring a base branch — CLIs map this to exit 2. */
 export declare class GitRefError extends Error {
 }
-/** Infer the committed-map base ref for local and GitHub Actions CLI runs. */
+/** Infer a PR/base ref for local and GitHub Actions CLI runs. */
 export declare function inferBaseRef(env?: NodeJS.ProcessEnv): string;
-/**
- * Materialise the captures committed at `dir` as of `ref` into a fresh temp dir,
- * so a diff/report can use e.g. `main`'s committed map as the base with no checkout
- * and no recapture — the "base map lives on main, CI just diffs" model.
- *
- * Reads purely through git (`ls-tree`/`show`, no `tar`/deps); binary `.json.gz`
- * bytes come straight from `git show`. The caller owns cleanup of the returned dir.
- * Throws {@link GitRefError} (never exits) so it's reusable from any entry point.
- */
-export declare function materializeRef(ref: string, dir: string): string;

package/dist/gitref.js

@@ -1,8 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-/** A readable failure materialising a base from git — CLIs map this to exit 2. */
+/** A readable failure inferring a base branch — CLIs map this to exit 2. */
 export class GitRefError extends Error {
 }
 function git(args) {
@@ -29,7 +26,7 @@ function ghPrBaseRef() {
     });
     return r.status === 0 ? r.stdout.trim() : '';
 }
-/** Infer the committed-map base ref for local and GitHub Actions CLI runs. */
+/** Infer a PR/base ref for local and GitHub Actions CLI runs. */
 export function inferBaseRef(env = process.env) {
     if (env.GITHUB_BASE_REF) {
         return baseRefCandidate(env.GITHUB_BASE_REF);
@@ -49,40 +46,3 @@ export function inferBaseRef(env = process.env) {
         return fallback;
     throw new GitRefError('could not infer a base branch (tried GITHUB_BASE_REF, branch.<name>.gh-merge-base, gh pr view, origin/main, origin/master, main, master)');
 }
-/**
- * Materialise the captures committed at `dir` as of `ref` into a fresh temp dir,
- * so a diff/report can use e.g. `main`'s committed map as the base with no checkout
- * and no recapture — the "base map lives on main, CI just diffs" model.
- *
- * Reads purely through git (`ls-tree`/`show`, no `tar`/deps); binary `.json.gz`
- * bytes come straight from `git show`. The caller owns cleanup of the returned dir.
- * Throws {@link GitRefError} (never exits) so it's reusable from any entry point.
- */
-export function materializeRef(ref, dir) {
-    const top = git(['rev-parse', '--show-toplevel']);
-    if (top.status !== 0)
-        throw new GitRefError('must run inside a git repository');
-    const toplevel = top.stdout.trim();
-    // -z: NUL-separated, unquoted paths (handles spaces/unicode).
-    const ls = spawnSync('git', ['ls-tree', '-r', '-z', '--name-only', ref, '--', dir], {
-        encoding: 'utf8',
-        maxBuffer: 1 << 28,
-    });
-    if (ls.status !== 0)
-        throw new GitRefError(`cannot read ${dir} at ${ref}: ${(ls.stderr || '').trim()}`);
-    const files = ls.stdout.split('\0').filter(Boolean);
-    if (files.length === 0) {
-        throw new GitRefError(`no committed captures at ${dir} in ${ref} — commit the maps so the base lives in git`);
-    }
-    const dirRepoRel = path.relative(toplevel, path.resolve(dir));
-    const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'styleproof-baseref-'));
-    for (const f of files) {
-        const show = spawnSync('git', ['show', `${ref}:${f}`], { maxBuffer: 1 << 28 }); // buffer — preserves .json.gz
-        if (show.status !== 0)
-            throw new GitRefError(`cannot read ${f} at ${ref}`);
-        const out = path.join(dest, path.relative(dirRepoRel, f));
-        fs.mkdirSync(path.dirname(out), { recursive: true });
-        fs.writeFileSync(out, show.stdout);
-    }
-    return dest;
-}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export type { StyleMap, CaptureOptions, CaptureMetadata, ElementEntry, LiveRegionCandidate, Rect } from './capture.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
-export type { Surface, SurfaceLiveState, SurfaceVariant, DefineOptions, CrawlOptions } from './runner.js';
+export type { Surface, SurfaceLiveState, SurfaceVariant, PopupCaptureOptions, DefineOptions, CrawlOptions, } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export type { CoverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';

package/dist/map-store.d.ts

@@ -0,0 +1,85 @@
+export declare const DEFAULT_MAP_DIR = ".styleproof/maps";
+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";
+export declare class MapStoreError extends Error {
+}
+export interface MapManifest {
+    version: 1;
+    packageVersion: string;
+    sha: string;
+    dirty: boolean;
+    spec: string;
+    specHash: string;
+    lockfile?: string;
+    lockfileHash?: string;
+    playwrightVersion?: string;
+    platform: string;
+    arch: string;
+    nodeMajor: string;
+    baseUrl?: string;
+    screenshots: boolean;
+    har: boolean;
+    compatibilityKey: string;
+    createdAt: string;
+}
+export interface CachedCaptureDirs {
+    beforeDir: string;
+    afterDir: string;
+    baseRef: string;
+    baseSha: string;
+    headSha: string;
+    compatibilityKey: string;
+    tmpRoot: string;
+}
+export declare function expectedCompatibilityKey(options?: {
+    cwd?: string;
+    spec?: string;
+    baseUrl?: string;
+}): string;
+export declare function currentGitSha(cwd?: string, env?: NodeJS.ProcessEnv): string;
+export declare function refSha(ref: string, cwd?: string): string;
+export declare function workingTreeDirty(cwd?: string): boolean;
+export declare function remoteExists(remote?: string, cwd?: string): boolean;
+export declare function writeMapManifest(options: {
+    dir: string;
+    spec: string;
+    sha?: string;
+    screenshots: boolean;
+    dirty?: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): MapManifest;
+export declare function readMapManifest(dir: string): MapManifest | null;
+export declare function assertCompatibleMapDirs(beforeDir: string, afterDir: string): void;
+export declare function publishMapBundle(options: {
+    dir: string;
+    branch?: string;
+    remote?: string;
+    cwd?: string;
+    includeHar?: boolean;
+}): {
+    sha: string;
+    compatibilityKey: string;
+    branch: string;
+};
+export declare function restoreMapBundle(options: {
+    sha: string;
+    outDir: string;
+    branch?: string;
+    remote?: string;
+    cwd?: string;
+    compatibilityKey?: string;
+}): MapManifest;
+export declare function resolveCachedCaptureDirs(options: {
+    command: string;
+    args: string[];
+    spec: string;
+    branch?: string;
+    remote?: string;
+    cwd?: string;
+    baseUrl?: string;
+    usage: string;
+}): CachedCaptureDirs;
+export declare function cleanupCachedCaptureDirs(captureDirs: CachedCaptureDirs | null): void;

package/dist/map-store.js

@@ -0,0 +1,342 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { inferBaseRef } from './gitref.js';
+export const DEFAULT_MAP_DIR = '.styleproof/maps';
+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';
+export class MapStoreError extends Error {
+}
+function runGit(cwd, args, maxBuffer = 1 << 28) {
+    return spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer });
+}
+function gitOutput(cwd, args) {
+    const r = runGit(cwd, args);
+    return r.status === 0 ? r.stdout.trim() : '';
+}
+function hash(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+function hashFile(file) {
+    try {
+        return hash(fs.readFileSync(file));
+    }
+    catch {
+        return undefined;
+    }
+}
+function styleProofPackageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function consumerRequire(cwd) {
+    return createRequire(path.join(cwd, 'package.json'));
+}
+function playwrightVersion(cwd) {
+    try {
+        const pkgPath = consumerRequire(cwd).resolve('@playwright/test/package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function detectLockfile(cwd) {
+    for (const file of ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb']) {
+        const full = path.join(cwd, file);
+        const h = hashFile(full);
+        if (h)
+            return { file, hash: h };
+    }
+    return {};
+}
+function hasHar(dir) {
+    if (!fs.existsSync(dir))
+        return false;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory() && hasHar(full))
+            return true;
+        if (entry.isFile() && entry.name.endsWith('.har'))
+            return true;
+    }
+    return false;
+}
+function compatibilityInput(options) {
+    const specPath = path.resolve(options.cwd, options.spec);
+    const lock = detectLockfile(options.cwd);
+    return {
+        packageVersion: styleProofPackageVersion(),
+        spec: path.relative(options.cwd, specPath) || options.spec,
+        specHash: hashFile(specPath) ?? 'missing',
+        lockfile: lock.file,
+        lockfileHash: lock.hash,
+        playwrightVersion: playwrightVersion(options.cwd),
+        platform: process.platform,
+        arch: process.arch,
+        nodeMajor: process.versions.node.split('.')[0] ?? process.versions.node,
+        baseUrl: options.baseUrl,
+    };
+}
+export function expectedCompatibilityKey(options = {}) {
+    return hash(JSON.stringify(compatibilityInput({
+        cwd: options.cwd ?? process.cwd(),
+        spec: options.spec ?? 'e2e/styleproof.spec.ts',
+        baseUrl: options.baseUrl,
+    }))).slice(0, 16);
+}
+export function currentGitSha(cwd = process.cwd(), env = process.env) {
+    const fromEnv = env.GITHUB_SHA || env.GITHUB_HEAD_SHA;
+    if (fromEnv && /^[0-9a-f]{7,40}$/i.test(fromEnv))
+        return fromEnv;
+    const sha = gitOutput(cwd, ['rev-parse', 'HEAD']);
+    if (!sha)
+        throw new MapStoreError('must run inside a git repository, or pass --sha <commit>');
+    return sha;
+}
+export function refSha(ref, cwd = process.cwd()) {
+    const sha = gitOutput(cwd, ['rev-parse', `${ref}^{commit}`]);
+    if (!sha)
+        throw new MapStoreError(`could not resolve ${ref} to a commit`);
+    return sha;
+}
+export function workingTreeDirty(cwd = process.cwd()) {
+    return gitOutput(cwd, ['status', '--porcelain']) !== '';
+}
+export function remoteExists(remote = DEFAULT_REMOTE, cwd = process.cwd()) {
+    return runGit(cwd, ['remote', 'get-url', remote], 1 << 20).status === 0;
+}
+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 manifest = {
+        version: 1,
+        packageVersion: input.packageVersion,
+        sha: options.sha ?? currentGitSha(cwd, options.env),
+        dirty: options.dirty ?? workingTreeDirty(cwd),
+        spec: input.spec,
+        specHash: input.specHash,
+        ...(input.lockfile ? { lockfile: input.lockfile } : {}),
+        ...(input.lockfileHash ? { lockfileHash: input.lockfileHash } : {}),
+        ...(input.playwrightVersion ? { playwrightVersion: input.playwrightVersion } : {}),
+        platform: input.platform,
+        arch: input.arch,
+        nodeMajor: input.nodeMajor,
+        ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
+        screenshots: options.screenshots,
+        har: hasHar(options.dir),
+        compatibilityKey: hash(JSON.stringify(input)).slice(0, 16),
+        createdAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(path.join(options.dir, MAP_MANIFEST), JSON.stringify(manifest, null, 2));
+    return manifest;
+}
+export function readMapManifest(dir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, MAP_MANIFEST), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function assertCompatibleMapDirs(beforeDir, afterDir) {
+    const before = readMapManifest(beforeDir);
+    const after = readMapManifest(afterDir);
+    if (!before || !after)
+        return;
+    const beforeRuntime = {
+        platform: before.platform,
+        arch: before.arch,
+        nodeMajor: before.nodeMajor,
+        playwrightVersion: before.playwrightVersion ?? '',
+        baseUrl: before.baseUrl ?? '',
+    };
+    const afterRuntime = {
+        platform: after.platform,
+        arch: after.arch,
+        nodeMajor: after.nodeMajor,
+        playwrightVersion: after.playwrightVersion ?? '',
+        baseUrl: after.baseUrl ?? '',
+    };
+    if (JSON.stringify(beforeRuntime) === JSON.stringify(afterRuntime))
+        return;
+    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'})`,
+        'Next: rebuild one side with styleproof-map in the same environment, or let CI recapture both maps.',
+    ].join('\n'));
+}
+function safeSegment(value, name) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value))
+        throw new MapStoreError(`${name} contains unsupported characters: ${value}`);
+    return value;
+}
+function copyDir(src, dest, includeHar) {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.cpSync(src, dest, {
+        recursive: true,
+        filter: (source) => includeHar || !source.endsWith('.har'),
+    });
+}
+function checkoutMapStore(cwd, remote, branch) {
+    if (!remoteExists(remote, cwd))
+        throw new MapStoreError(`git remote ${remote} was not found`);
+    const remoteUrl = gitOutput(cwd, ['remote', 'get-url', remote]);
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'styleproof-map-store-'));
+    if (runGit(cwd, ['ls-remote', '--exit-code', '--heads', remote, branch], 1 << 20).status === 0) {
+        const clone = spawnSync('git', ['clone', '-q', '--depth', '1', '--branch', branch, remoteUrl, tmp], {
+            encoding: 'utf8',
+            maxBuffer: 1 << 20,
+        });
+        if (clone.status !== 0) {
+            fs.rmSync(tmp, { recursive: true, force: true });
+            throw new MapStoreError(clone.stderr.trim() || 'could not clone map store branch');
+        }
+    }
+    else {
+        runGit(tmp, ['init', '-q', '-b', branch]);
+        runGit(tmp, ['remote', 'add', 'origin', remoteUrl]);
+    }
+    return tmp;
+}
+export function publishMapBundle(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const branch = options.branch ?? DEFAULT_MAP_STORE_BRANCH;
+    const remote = options.remote ?? DEFAULT_REMOTE;
+    const manifest = readMapManifest(options.dir);
+    if (!manifest)
+        throw new MapStoreError(`no ${MAP_MANIFEST} in ${options.dir}`);
+    if (manifest.dirty) {
+        throw new MapStoreError(`not uploading ${options.dir}: working tree was dirty when the map was captured. Commit first, then rerun styleproof-map.`);
+    }
+    if (!remoteExists(remote, cwd))
+        throw new MapStoreError(`git remote ${remote} was not found`);
+    const sha = safeSegment(manifest.sha, 'sha');
+    const compatibilityKey = safeSegment(manifest.compatibilityKey, 'compatibility key');
+    const target = `${sha}/${compatibilityKey}`;
+    let ok = false;
+    let lastError = '';
+    for (let attempt = 1; attempt <= 5; attempt++) {
+        const tmp = checkoutMapStore(cwd, remote, branch);
+        try {
+            runGit(tmp, ['config', 'user.name', 'github-actions[bot]']);
+            runGit(tmp, ['config', 'user.email', '41898282+github-actions[bot]@users.noreply.github.com']);
+            fs.writeFileSync(path.join(tmp, 'README.md'), '# StyleProof maps\n\nMachine-generated reusable map bundles. Each folder is keyed by commit SHA and capture compatibility.\n');
+            fs.rmSync(path.join(tmp, target), { recursive: true, force: true });
+            copyDir(options.dir, path.join(tmp, target), options.includeHar === true);
+            if (!options.includeHar) {
+                fs.writeFileSync(path.join(tmp, target, MAP_MANIFEST), JSON.stringify({ ...manifest, har: false }, null, 2));
+            }
+            runGit(tmp, ['add', '-A']);
+            runGit(tmp, ['commit', '-q', '-m', `StyleProof map ${sha.slice(0, 12)} ${compatibilityKey}`], 1 << 20);
+            const push = runGit(tmp, ['push', '-q', 'origin', `HEAD:${branch}`], 1 << 20);
+            if (push.status === 0) {
+                ok = true;
+                break;
+            }
+            lastError = push.stderr.trim();
+        }
+        finally {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, attempt * 250);
+    }
+    if (!ok)
+        throw new MapStoreError(lastError || `could not push ${branch}`);
+    return { sha, compatibilityKey, branch };
+}
+export function restoreMapBundle(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const branch = options.branch ?? DEFAULT_MAP_STORE_BRANCH;
+    const remote = options.remote ?? DEFAULT_REMOTE;
+    const sha = safeSegment(options.sha, 'sha');
+    const compatibilityKey = options.compatibilityKey
+        ? safeSegment(options.compatibilityKey, 'compatibility key')
+        : undefined;
+    if (!remoteExists(remote, cwd))
+        throw new MapStoreError(`git remote ${remote} was not found`);
+    if (runGit(cwd, ['ls-remote', '--exit-code', '--heads', remote, branch], 1 << 20).status !== 0) {
+        throw new MapStoreError(`map store branch ${branch} does not exist`);
+    }
+    const tmp = checkoutMapStore(cwd, remote, branch);
+    try {
+        const shaDir = path.join(tmp, sha);
+        if (!fs.existsSync(shaDir))
+            throw new MapStoreError(`no cached map for ${sha} on ${branch}`);
+        const candidates = fs
+            .readdirSync(shaDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .filter((name) => !compatibilityKey || name === compatibilityKey)
+            .sort();
+        if (!candidates.length) {
+            throw new MapStoreError(compatibilityKey
+                ? `no cached map for ${sha} with compatibility ${compatibilityKey} on ${branch}`
+                : `no cached map bundle under ${sha} on ${branch}`);
+        }
+        const src = path.join(shaDir, candidates[0]);
+        fs.rmSync(options.outDir, { recursive: true, force: true });
+        copyDir(src, options.outDir, true);
+        const manifest = readMapManifest(options.outDir);
+        if (!manifest)
+            throw new MapStoreError(`cached map for ${sha} is missing ${MAP_MANIFEST}`);
+        return manifest;
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+export function resolveCachedCaptureDirs(options) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.args.length > 1)
+        throw new MapStoreError(options.usage);
+    if (!fs.existsSync(path.resolve(cwd, options.spec))) {
+        throw new MapStoreError(`${options.command}: no StyleProof spec at ${options.spec}`);
+    }
+    const baseRef = options.args[0] ?? inferBaseRef();
+    const baseSha = refSha(baseRef, cwd);
+    const headSha = currentGitSha(cwd);
+    const compatibilityKey = expectedCompatibilityKey({ cwd, spec: options.spec, baseUrl: options.baseUrl });
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'styleproof-cache-'));
+    const beforeDir = path.join(tmpRoot, 'base');
+    const afterDir = path.join(tmpRoot, 'head');
+    try {
+        restoreMapBundle({
+            sha: baseSha,
+            outDir: beforeDir,
+            branch: options.branch,
+            remote: options.remote,
+            cwd,
+            compatibilityKey,
+        });
+        restoreMapBundle({
+            sha: headSha,
+            outDir: afterDir,
+            branch: options.branch,
+            remote: options.remote,
+            cwd,
+            compatibilityKey,
+        });
+        return { beforeDir, afterDir, baseRef, baseSha, headSha, compatibilityKey, tmpRoot };
+    }
+    catch (e) {
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+        throw e;
+    }
+}
+export function cleanupCachedCaptureDirs(captureDirs) {
+    if (captureDirs)
+        fs.rmSync(captureDirs.tmpRoot, { recursive: true, force: true });
+}

package/dist/report.d.ts

@@ -24,6 +24,12 @@ export type ReportOptions = {
     minHeight?: number;
     /** Crops taller than this are clamped (default 1600px). */
     maxHeight?: number;
+    /**
+     * Changed-element footprint (max of its width/height, in px) at or below which a
+     * magnified zoom crop is added so a sub-pixel change is visible by default
+     * (default 64). Set to 0 to disable zoom crops.
+     */
+    zoomBelow?: number;
     /** Max crop regions per surface before collapsing into one union crop (default 8). */
     maxCrops?: number;
     /**