styleproof 3.1.1 → 3.1.3

package/bin/styleproof-init.mjs

@@ -13,6 +13,8 @@
  *     surface plus a commented guard block to wire to your own route registry.
  *   - playwright.config.ts: only if one does not already exist, so an existing
  *     Playwright project is never disturbed.
+ *   - .github/workflows/styleproof.yml: restores reusable maps from the
+ *     styleproof-maps branch and only captures in CI when the maps are missing.
  *
  * Idempotent: re-running never overwrites an existing spec (use --force) and
  * never touches an existing playwright.config.ts. Exit 0 = done (or nothing to
@@ -20,7 +22,6 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { discoverNextRoutes } from '../dist/index.js';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 
@@ -41,8 +42,9 @@ What it writes:
     surfaces and the \`expected\` coverage guard to them, so a new page can't ship
     uncaptured. Otherwise it writes one sample surface + a commented guard block.
   - playwright.config.ts, only if absent (an existing one is left untouched)
+  - .github/workflows/styleproof.yml, a cache-first PR report workflow
 
-After running, capture a baseline against a PRODUCTION build:
+After running, build and upload this commit's map outside CI when possible:
   npx styleproof-map
 
 To certify a refactor:
@@ -107,8 +109,8 @@ const HEADER = `/**
  * detects your @media breakpoints from the loaded CSS and sweeps one viewport per
  * band — no config. Capture against a PRODUCTION build — dev servers inject styles.
  *
- *   npx styleproof-map   # capture this branch into stylemaps/current
- *   npx styleproof-diff  # compare against the inferred base branch
+ *   npx styleproof-map   # capture this commit into the local cache and map store
+ *   npx styleproof-diff  # compare cached base/head maps by commit SHA
  */`;
 
 // Next.js detected: derive both surfaces and the coverage guard from the app's
@@ -285,81 +287,23 @@ export default defineConfig({
 });
 `;
 
-// The out-of-the-box gate: capture happens PRE-PUSH on your machine (where the app
-// already builds + serves) and the lean computed-style map is committed, so main
-// always carries a base map and CI is a fast, browser-less diff of two precomputed
-// maps. The hook redirects capture into a committed `stylemaps/` dir and drops
-// screenshots via the STYLEPROOF_BASEDIR / STYLEPROOF_SCREENSHOTS env knobs.
-const HOOK_DIR = '.githooks';
-const HOOK_PATH = `${HOOK_DIR}/pre-push`;
-const PREPUSH_HOOK = `#!/bin/sh
-# StyleProof pre-push hook (generated by styleproof-init).
-#
-# Captures this branch's computed-style map, commits it, and pushes it WITH your
-# push — one \`git push\`, never two. So main always carries a base map and CI just
-# diffs two precomputed maps (no browser). Maps are lean .json.gz under stylemaps/.
-# Activate once per clone:  git config core.hooksPath .githooks
-set -e
-
-remote="$1"
-
-# Re-entry guard: the map commit is pushed by this hook (below), which fires the
-# hook a second time — skip the expensive capture on that pass.
-[ "\${STYLEPROOF_SKIP_CAPTURE:-}" = "1" ] && exit 0
-
-${PM.exec(`styleproof-map --spec ${specPath}`)}
-
-if git cat-file -e HEAD:stylemaps/current 2>/dev/null; then
-  tmp="\${TMPDIR:-/tmp}/styleproof-pre-push-diff.$$"
-  set +e
-  ${PM.exec('styleproof-diff --base-ref HEAD --max=20')} > "$tmp"
-  code=$?
-  set -e
-
-  if [ "$code" -eq 2 ]; then
-    cat "$tmp" >&2
-    rm -f "$tmp"
-    exit 2
-  fi
-
-  if [ "$code" -eq 0 ]; then
-    rm -f "$tmp"
-    git restore --source=HEAD -- stylemaps
-    git clean -fdq -- stylemaps/current
-    exit 0
-  fi
-
-  cat "$tmp" >&2
-  rm -f "$tmp"
-  echo "StyleProof: style map changed. If this was not an intended visual change, pin live states or replay/fixture the data boundary before pushing." >&2
-fi
-
-git add stylemaps
-git diff --cached --quiet -- stylemaps && exit 0  # map unchanged — let the push proceed
-
-# Map changed: commit it and push the updated branch ourselves so you never push
-# twice (git pushes the pre-hook commit, so a new commit here wouldn't otherwise go).
-# The re-entry guard stops the inner push from recapturing; then abort this original,
-# now-stale push so nothing is sent twice.
-git commit -m "chore(styleproof): update computed-style map"
-echo "StyleProof: style map changed — committed it and pushing with your branch…" >&2
-STYLEPROOF_SKIP_CAPTURE=1 git push "$remote" HEAD
-echo "StyleProof: ✓ pushed your branch with the updated map — nothing more to do." >&2
-echo "StyleProof: (git's 'failed to push some refs' below is expected; the push above already succeeded.)" >&2
-exit 1
-`;
-
 const CI_PATH = '.github/workflows/styleproof.yml';
 const CI_WORKFLOW = `name: StyleProof
 
-# Maps are captured + committed pre-push (see .githooks/pre-push), so CI runs no
-# browser — it just diffs this branch's committed map against the base branch's.
+# Cache-first v3 flow:
+# - run \`styleproof-map\` locally after committing to build/upload this commit's map
+#   outside CI when possible;
+# - CI restores base/head maps from the styleproof-maps branch and generates the
+#   report without a browser;
+# - on cache miss, CI recaptures both sides in one pinned environment so the
+#   comparison stays valid.
 on: pull_request
 
 permissions:
-  contents: read
+  contents: write
   issues: write
   pull-requests: write
+  statuses: write
 
 jobs:
   styleproof:
@@ -367,55 +311,55 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0 # need the base ref to read its committed map
+          fetch-depth: 0 # need base/head commits for cache fallback capture
 ${PM.setup}
       - run: ${PM.install}
-      - id: diff
-        name: Diff this branch's committed map against the base
+      - id: maps
+        name: Restore cached StyleProof maps
         shell: bash
         run: |
+          BASE_SHA="\${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="\${{ github.event.pull_request.head.sha }}"
+          rm -rf __stylemaps__
           set +e
-          ${PM.exec(`styleproof-diff --base-ref "origin/\${{ github.event.pull_request.base.ref }}"`)} | tee styleproof-diff.txt
-          code=\${PIPESTATUS[0]}
+          ${PM.exec(`styleproof-map --restore --sha "$BASE_SHA" --dir base --base-dir __stylemaps__ --spec ${specPath}`)}
+          base_code=$?
+          ${PM.exec(`styleproof-map --restore --sha "$HEAD_SHA" --dir head --base-dir __stylemaps__ --spec ${specPath}`)}
+          head_code=$?
           set -e
-          echo "exit-code=\${code}" >> "$GITHUB_OUTPUT"
-          if [ "$code" -eq 0 ]; then
-            echo "result=clean" >> "$GITHUB_OUTPUT"
-          elif [ "$code" -eq 1 ] || [ "$code" -eq 3 ]; then
-            echo "result=changed" >> "$GITHUB_OUTPUT"
+          if [ "$base_code" -eq 0 ] && [ "$head_code" -eq 0 ]; then
+            echo "capture-needed=false" >> "$GITHUB_OUTPUT"
           else
-            echo "result=error" >> "$GITHUB_OUTPUT"
+            echo "capture-needed=true" >> "$GITHUB_OUTPUT"
           fi
-      - name: Comment StyleProof result
-        if: >-
-          always() &&
-          github.event_name == 'pull_request' &&
-          steps.diff.outputs.result != '' &&
-          steps.diff.outputs.result != 'error'
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const issue_number = context.payload.pull_request.number;
-            const marker = '<!-- styleproof-report -->';
-            const clean = '\${{ steps.diff.outputs.result }}' === 'clean';
-            const body = clean
-              ? marker + '\\n## 🗺️ StyleProof report\\n\\n✓ No visual changes detected.'
-              : marker + '\\n## 🗺️ StyleProof report\\n\\nVisual changes detected. See the StyleProof check logs for the computed-style diff.';
-            const { data: comments } = await github.rest.issues.listComments({
-              ...context.repo,
-              issue_number,
-              per_page: 100,
-            });
-            const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
-            if (existing) {
-              await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body });
-            } else {
-              await github.rest.issues.createComment({ ...context.repo, issue_number, body });
-            }
-      - name: Fail on StyleProof diff
-        if: steps.diff.outputs.exit-code != '0'
+      - name: Capture maps in CI on cache miss
+        if: steps.maps.outputs.capture-needed == 'true'
         shell: bash
-        run: exit \${{ steps.diff.outputs.exit-code }}
+        run: |
+          BASE_SHA="\${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="\${{ github.event.pull_request.head.sha }}"
+          rm -rf __stylemaps__
+
+          git checkout "$BASE_SHA"
+          ${PM.install}
+          if [ -f "${specPath}" ]; then
+            ${PM.exec(`styleproof-map --spec ${specPath} --dir base --base-dir __stylemaps__ --keep-har --no-upload`)}
+          else
+            mkdir -p __stylemaps__/base
+          fi
+
+          git checkout "$HEAD_SHA"
+          ${PM.install}
+          if find __stylemaps__/base -name '*.har' -print -quit | grep -q .; then
+            STYLEPROOF_REPLAY_FROM=__stylemaps__/base ${PM.exec(`styleproof-map --spec ${specPath} --dir head --base-dir __stylemaps__ --no-upload`)}
+          else
+            ${PM.exec(`styleproof-map --spec ${specPath} --dir head --base-dir __stylemaps__ --no-upload`)}
+          fi
+      - uses: BenSheridanEdwards/StyleProof@v3
+        with:
+          baseline-dir: __stylemaps__/base
+          fresh-dir: __stylemaps__/head
+          require-approval: true
 `;
 
 function writeFileSafe(file, contents, { force: f } = {}) {
@@ -426,6 +370,15 @@ function writeFileSafe(file, contents, { force: f } = {}) {
   return { wrote: true, exists };
 }
 
+function ensureGitignoreLine(line) {
+  const file = '.gitignore';
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (existing.split(/\r?\n/).includes(line)) return false;
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  fs.writeFileSync(file, `${existing}${prefix}${line}\n`);
+  return true;
+}
+
 // Choose the scaffold: routes-aware when this is a Next.js app with discoverable
 // routes, else the generic one-surface starter.
 const routes = discoverNextRoutes(process.cwd());
@@ -460,58 +413,30 @@ if (fs.existsSync(configPath) || fs.existsSync('playwright.config.js')) {
   wroteSomething = true;
 }
 
-// Pre-push capture+commit hook — the out-of-the-box gate (capture local, CI diffs).
-const hook = writeFileSafe(HOOK_PATH, PREPUSH_HOOK, { force });
-if (hook.wrote) {
-  fs.chmodSync(HOOK_PATH, 0o755);
-  console.log(`${hook.exists ? 'overwrote' : 'created'} ${HOOK_PATH} (pre-push capture + commit)`);
+const ignored = ['.styleproof/', 'test-results/', 'playwright-report/'].filter((line) => ensureGitignoreLine(line));
+if (ignored.length) {
+  console.log(`updated .gitignore (${ignored.join(', ')})`);
   wroteSomething = true;
-} else {
-  console.log(`${HOOK_PATH} already exists — left untouched (use --force to overwrite)`);
 }
 
-// Browser-less CI diff — never overwrite an existing workflow.
+// Cache-first CI report — never overwrite an existing workflow.
 const ci = writeFileSafe(CI_PATH, CI_WORKFLOW);
 if (ci.wrote) {
-  console.log(`created ${CI_PATH} (browser-less CI diff)`);
+  console.log(`created ${CI_PATH} (cache-first StyleProof report)`);
   wroteSomething = true;
 } else {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
-// Activate the hook so ONE `styleproof-init` is all it takes — but never clobber a
-// repo that already manages its hooks (husky, or an existing core.hooksPath); there
-// we leave it and print the one-liner instead.
-const git = (a) => spawnSync('git', a, { encoding: 'utf8' });
-const inGitRepo = git(['rev-parse', '--is-inside-work-tree']).status === 0;
-const existingHooksPath = inGitRepo ? git(['config', '--local', '--get', 'core.hooksPath']).stdout.trim() : '';
-const managesHooks = existingHooksPath !== '' || fs.existsSync('.husky');
-let hookActivated = false;
-if (inGitRepo && !managesHooks) {
-  if (git(['config', 'core.hooksPath', HOOK_DIR]).status === 0) {
-    hookActivated = true;
-    console.log(`activated the pre-push hook (core.hooksPath → ${HOOK_DIR})`);
-    wroteSomething = true;
-  }
-}
-
-console.log('\nHow the gate works — capture local, CI just diffs:');
-if (hookActivated) {
-  console.log('  1. ✓ Pre-push hook is active — nothing to do.');
-} else if (managesHooks) {
-  console.log(`  1. Your repo already manages git hooks (${existingHooksPath || '.husky'}), so the hook`);
-  console.log(`     wasn't auto-activated. Point your hook runner at ${HOOK_DIR}/pre-push, or run:`);
-  console.log(`       git config core.hooksPath ${HOOK_DIR}`);
-} else {
-  console.log('  1. Activate the pre-push hook (once per clone):');
-  console.log(`       git config core.hooksPath ${HOOK_DIR}`);
-}
-console.log('  2. Push your branch. The hook captures the computed-style map against a');
-console.log('     PRODUCTION build, commits it (lean .json.gz under stylemaps/), and pushes it');
-console.log('     with your branch — one `git push`, never two.');
-console.log('  3. On the PR, CI diffs your committed map against the base branch — no browser,');
-console.log('     just a fast comparison of precomputed maps. An empty diff certifies no change.');
-console.log('  So main always carries a base map and every PR is a quick diff, not a recapture.');
+console.log('\nHow the gate works — local-first maps, CI report when cached:');
+console.log('  1. Commit your code, then run:');
+console.log('       npx styleproof-map');
+console.log('     It captures a production-build map into .styleproof/ and uploads the bundle');
+console.log('     to the styleproof-maps branch when the git remote is available.');
+console.log('  2. Open the PR. CI restores the base/head bundles and generates the report');
+console.log('     without a browser when both maps are present and compatible.');
+console.log('  3. If a bundle is missing or incompatible, CI recaptures both sides in the same');
+console.log('     environment before generating the report. Correctness beats a stale cache.');
 
 if (!wroteSomething) console.log('\nnothing to write — project already scaffolded.');
 process.exit(0);

package/bin/styleproof-map.mjs

@@ -2,16 +2,17 @@
 /**
  * Capture the current branch's computed-style map.
  *
- * The zero-config path is the committed-map flow scaffolded by styleproof-init:
+ * The zero-config path is the local-first cache flow scaffolded by styleproof-init:
  *   styleproof-map
  *
  * It runs Playwright against e2e/styleproof.spec.ts with:
  *   STYLEMAP_DIR=current
- *   STYLEPROOF_BASEDIR=stylemaps
- *   STYLEPROOF_SCREENSHOTS=0
+ *   STYLEPROOF_BASEDIR=.styleproof/maps
+ *   STYLEPROOF_SCREENSHOTS=1
  */
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import path from 'node:path';
 import {
   isHelpArg,
   missingSpecMessage,
@@ -19,6 +20,19 @@ import {
   showHelpAndExit,
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
+import {
+  DEFAULT_MAP_DIR,
+  DEFAULT_MAP_LABEL,
+  DEFAULT_MAP_STORE_BRANCH,
+  DEFAULT_REMOTE,
+  MapStoreError,
+  currentGitSha,
+  expectedCompatibilityKey,
+  publishMapBundle,
+  restoreMapBundle,
+  workingTreeDirty,
+  writeMapManifest,
+} from '../dist/map-store.js';
 
 const HELP = `styleproof-map — capture this branch's computed-style map
 
@@ -26,25 +40,39 @@ usage: styleproof-map [options] [-- <playwright args>]
 
 options:
   --spec <path>       StyleProof spec that must exist (default: e2e/styleproof.spec.ts)
-  --dir <label>       output label under --base-dir (default: current)
-  --base-dir <path>   output root directory (default: stylemaps)
-  --screenshots       keep screenshots for reports (default: off for committed maps)
-  --no-screenshots    write lean .json.gz maps only (default)
+  --dir <label>       output label under --base-dir (default: ${DEFAULT_MAP_LABEL})
+  --base-dir <path>   output root directory (default: ${DEFAULT_MAP_DIR})
+  --screenshots       keep screenshots for reports (default)
+  --no-screenshots    write lean .json.gz maps only
   --keep-har          keep recorded HAR files for advanced replay workflows
+  --sha <commit>      commit SHA this map belongs to (default: current HEAD)
+  --upload            require upload to the map store branch after capture
+  --no-upload         capture locally only (default in CI)
+  --restore           restore a map from the map store instead of capturing
+  --cache-branch <b>  map store branch (default: ${DEFAULT_MAP_STORE_BRANCH})
+  --remote <name>     git remote for the map store (default: ${DEFAULT_REMOTE})
   -h, --help          show this help
 
 Examples:
   styleproof-map
+  styleproof-map --upload
+  styleproof-map --restore --sha 0123abcd --dir head --base-dir __stylemaps__
   styleproof-map --spec e2e/styleproof.spec.ts
-  styleproof-map --dir review --base-dir __stylemaps__ --screenshots --keep-har
+  styleproof-map --dir review --base-dir __stylemaps__ --keep-har --no-upload
 `;
 
 const argv = process.argv.slice(2);
 let spec = 'e2e/styleproof.spec.ts';
-let dir = process.env.STYLEMAP_DIR ?? 'current';
-let baseDir = process.env.STYLEPROOF_BASEDIR ?? 'stylemaps';
-let screenshots = process.env.STYLEPROOF_SCREENSHOTS ?? '0';
+let dir = process.env.STYLEMAP_DIR ?? DEFAULT_MAP_LABEL;
+let baseDir = process.env.STYLEPROOF_BASEDIR ?? DEFAULT_MAP_DIR;
+let screenshots = process.env.STYLEPROOF_SCREENSHOTS ?? '1';
 let keepHar = process.env.STYLEPROOF_KEEP_HAR === '1';
+let sha = process.env.STYLEPROOF_SHA ?? '';
+let restore = false;
+let cacheBranch = process.env.STYLEPROOF_CACHE_BRANCH ?? DEFAULT_MAP_STORE_BRANCH;
+let remote = process.env.STYLEPROOF_REMOTE ?? DEFAULT_REMOTE;
+let uploadMode =
+  process.env.STYLEPROOF_UPLOAD === '1' ? 'required' : process.env.STYLEPROOF_UPLOAD === '0' ? 'off' : 'auto';
 const playwrightArgs = [];
 
 for (let i = 0; i < argv.length; i++) {
@@ -62,6 +90,15 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === '--screenshots') screenshots = '1';
   else if (a === '--no-screenshots') screenshots = '0';
   else if (a === '--keep-har') keepHar = true;
+  else if (a === '--sha') sha = argv[++i];
+  else if (a.startsWith('--sha=')) sha = a.slice(6);
+  else if (a === '--upload') uploadMode = 'required';
+  else if (a === '--no-upload') uploadMode = 'off';
+  else if (a === '--restore') restore = true;
+  else if (a === '--cache-branch') cacheBranch = argv[++i];
+  else if (a.startsWith('--cache-branch=')) cacheBranch = a.slice(15);
+  else if (a === '--remote') remote = argv[++i];
+  else if (a.startsWith('--remote=')) remote = a.slice(9);
   else if (a.startsWith('--')) {
     console.error(unknownFlagMessage('styleproof-map', a));
     process.exit(2);
@@ -86,6 +123,14 @@ if (!fs.existsSync(spec)) {
   console.error(missingSpecMessage(spec));
   process.exit(2);
 }
+if (restore && !sha) {
+  try {
+    sha = currentGitSha(process.cwd());
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(2);
+  }
+}
 
 function removeHarFiles(root) {
   if (!fs.existsSync(root)) return;
@@ -96,6 +141,63 @@ function removeHarFiles(root) {
   }
 }
 
+function shouldAutoUpload() {
+  return uploadMode === 'auto' && !process.env.CI;
+}
+
+function upload(dirPath) {
+  if (uploadMode === 'off') return;
+  if (!shouldAutoUpload() && uploadMode !== 'required') return;
+  try {
+    const res = publishMapBundle({ dir: dirPath, branch: cacheBranch, remote });
+    console.error(`styleproof-map: uploaded ${res.sha.slice(0, 12)} (${res.compatibilityKey}) to ${res.branch}`);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (uploadMode === 'required') {
+      console.error(`styleproof-map: upload failed\n${message}`);
+      process.exit(2);
+    }
+    if (e instanceof MapStoreError) {
+      console.error(`styleproof-map: map captured locally; upload skipped (${message})`);
+    } else {
+      console.error(`styleproof-map: map captured locally; upload skipped`);
+    }
+  }
+}
+
+const targetDir = path.join(baseDir, dir);
+let dirtyBeforeCapture;
+try {
+  dirtyBeforeCapture = workingTreeDirty(process.cwd());
+} catch {
+  dirtyBeforeCapture = false;
+}
+
+if (restore) {
+  try {
+    const compatibilityKey = expectedCompatibilityKey({ spec });
+    const manifest = restoreMapBundle({
+      sha,
+      outDir: targetDir,
+      branch: cacheBranch,
+      remote,
+      compatibilityKey,
+    });
+    console.log(`styleproof-map: restored ${manifest.sha.slice(0, 12)} (${manifest.compatibilityKey}) to ${targetDir}`);
+    process.exit(0);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(
+      [
+        `styleproof-map: could not restore ${sha} from ${cacheBranch}`,
+        message,
+        `Next: run styleproof-map at that commit to build/upload the map, or let CI recapture both sides.`,
+      ].join('\n'),
+    );
+    process.exit(2);
+  }
+}
+
 const command = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
 const env = {
   ...process.env,
@@ -112,5 +214,30 @@ if (result.error) {
   process.exit(2);
 }
 const status = result.status ?? 1;
-if (status === 0 && !keepHar) removeHarFiles(`${baseDir}/${dir}`);
+if (status === 0) {
+  if (!keepHar) removeHarFiles(targetDir);
+  try {
+    let manifestSha = sha || undefined;
+    if (!manifestSha) {
+      try {
+        manifestSha = currentGitSha(process.cwd(), env);
+      } catch {
+        manifestSha = 'local';
+      }
+    }
+    const manifest = writeMapManifest({
+      dir: targetDir,
+      spec,
+      sha: manifestSha,
+      screenshots: screenshots !== '0',
+      dirty: dirtyBeforeCapture,
+      env,
+    });
+    console.error(`styleproof-map: wrote ${targetDir} for ${manifest.sha.slice(0, 12)} (${manifest.compatibilityKey})`);
+  } catch (e) {
+    console.error(`styleproof-map: could not write map manifest\n${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+  upload(targetDir);
+}
 process.exit(status);

package/bin/styleproof-report.mjs

@@ -4,6 +4,7 @@
  * region, plus the exact property changes, as markdown ready for a PR
  * comment.
  *
+ *   styleproof-report [baseRef] --out <dir> [options]   # cached map store
  *   styleproof-report <beforeDir> <afterDir> --out <dir> [options]
  *
  * Both capture dirs need the .json.gz maps; side-by-side images additionally
@@ -11,23 +12,28 @@
  * Exit code 0 = no changes, 1 = report generated, 2 = usage error.
  */
 import { generateStyleMapReport } from '../dist/report.js';
-import { cleanupBaseRefCaptureDirs, resolveBaseRefCaptureDirs } from '../dist/cli-base-ref.js';
 import { cliErrorMessage, isHelpArg, showHelpAndExit, unknownFlagMessage } from '../dist/cli-errors.js';
+import {
+  DEFAULT_MAP_STORE_BRANCH,
+  DEFAULT_REMOTE,
+  assertCompatibleMapDirs,
+  cleanupCachedCaptureDirs,
+  resolveCachedCaptureDirs,
+} from '../dist/map-store.js';
 
 const COMMAND = 'styleproof-report';
-const DEFAULT_MAPS_DIR = 'stylemaps/current';
 
 const HELP = `${COMMAND} — reviewable before/after report from two captures
 
 usage: ${COMMAND} [baseRef] [options]
-       ${COMMAND} --base-ref <gitref> [mapsDir] [options]
        ${COMMAND} <beforeDir> <afterDir> [options]
 
 options:
-  --base-ref <ref>          report <mapsDir> as committed at <ref> (e.g. main)
-                            against your working <mapsDir> — base from git, no recapture
-  --maps-dir <dir>          committed map dir for the base-ref flow
-                            (default: ${DEFAULT_MAPS_DIR})
+  --spec <path>              StyleProof spec used to select compatible cached maps
+                             (default: e2e/styleproof.spec.ts)
+  --cache-branch <b>         map store branch for default cached-map mode
+                             (default: ${DEFAULT_MAP_STORE_BRANCH})
+  --remote <name>            git remote for the map store (default: ${DEFAULT_REMOTE})
   --out <dir>               output directory (default: styleproof-report)
   --image-base-url <url>    prefix for image URLs in report.md (default: relative)
   --pad <px>                padding around changed rects when cropping (default: 24)
@@ -58,8 +64,9 @@ let minWidth;
 let minHeight;
 let includeLayoutNoise = false;
 let includeContent = false;
-let baseRef = null;
-let mapsDir = DEFAULT_MAPS_DIR;
+let spec = 'e2e/styleproof.spec.ts';
+let cacheBranch = process.env.STYLEPROOF_CACHE_BRANCH ?? DEFAULT_MAP_STORE_BRANCH;
+let remote = process.env.STYLEPROOF_REMOTE ?? DEFAULT_REMOTE;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (isHelpArg(a)) showHelpAndExit(HELP);
@@ -81,10 +88,12 @@ for (let i = 0; i < argv.length; i++) {
   else if (a.startsWith('--include-layout-noise=')) includeLayoutNoise = a.slice(23) !== 'false';
   else if (a === '--include-content') includeContent = true;
   else if (a.startsWith('--include-content=')) includeContent = a.slice(18) !== 'false';
-  else if (a === '--base-ref') baseRef = argv[++i];
-  else if (a.startsWith('--base-ref=')) baseRef = a.slice(11);
-  else if (a === '--maps-dir') mapsDir = argv[++i];
-  else if (a.startsWith('--maps-dir=')) mapsDir = a.slice(11);
+  else if (a === '--spec') spec = argv[++i];
+  else if (a.startsWith('--spec=')) spec = a.slice(7);
+  else if (a === '--cache-branch') cacheBranch = argv[++i];
+  else if (a.startsWith('--cache-branch=')) cacheBranch = a.slice(15);
+  else if (a === '--remote') remote = argv[++i];
+  else if (a.startsWith('--remote=')) remote = a.slice(9);
   else if (a.startsWith('--')) {
     console.error(unknownFlagMessage(COMMAND, a));
     process.exit(2);
@@ -92,22 +101,30 @@ for (let i = 0; i < argv.length; i++) {
 }
 let beforeDir;
 let afterDir;
-let baseCapture = null;
-if (baseRef || args.length <= 1) {
+let cacheCapture = null;
+if (args.length <= 1) {
   try {
-    baseCapture = resolveBaseRefCaptureDirs({
+    cacheCapture = resolveCachedCaptureDirs({
       command: COMMAND,
-      baseRef,
-      mapsDir,
       args,
-      usage: 'usage: styleproof-report --base-ref <gitref> [mapsDir] [--out <dir>] [options]',
+      spec,
+      branch: cacheBranch,
+      remote,
+      baseUrl: process.env.BASE_URL,
+      usage: 'usage: styleproof-report [baseRef] [--out <dir>] [options]',
     });
+    beforeDir = cacheCapture.beforeDir;
+    afterDir = cacheCapture.afterDir;
   } catch (e) {
-    console.error(cliErrorMessage(e));
+    console.error(
+      [
+        `${COMMAND}: cached maps are not available for this report`,
+        cliErrorMessage(e),
+        'Next: run styleproof-map on the base and head commits to upload maps, or let CI recapture both sides.',
+      ].join('\n'),
+    );
     process.exit(2);
   }
-  beforeDir = baseCapture.beforeDir;
-  afterDir = baseCapture.afterDir;
 } else {
   if (args.length !== 2) {
     console.error('usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]  (--help for all options)');
@@ -135,6 +152,7 @@ if (foldDetailsAt !== undefined && Number.isNaN(foldDetailsAt)) {
 
 let result;
 try {
+  assertCompatibleMapDirs(beforeDir, afterDir);
   result = generateStyleMapReport({
     beforeDir,
     afterDir,
@@ -152,7 +170,7 @@ try {
   console.error(e.message);
   process.exit(2);
 } finally {
-  cleanupBaseRefCaptureDirs(baseCapture);
+  cleanupCachedCaptureDirs(cacheCapture);
 }
 
 const newNote = result.newSurfaces ? ` (+${result.newSurfaces} new surface(s) with no baseline)` : '';