styleproof 4.3.0 → 4.4.1

package/CHANGELOG.md

@@ -7,6 +7,43 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [4.4.1] - 2026-07-13
+
+### Changed
+
+- **`styleproof-init` now scaffolds the least-work v4 map loop.** Pull-request
+  CI restores exact base/head bundles from `styleproof-maps`; a compatible base
+  hit plus head miss captures only the head, while a base miss rebuilds the
+  pair. Every fallback capture is bound to its explicit commit SHA and
+  published, so the same cold work is not repeated on later pull requests.
+  Temporary CI maps live under `runner.temp`, outside the checkout, and the
+  fallback installs Chromium before capture. The generated Action pin is `v4`.
+- **The generated pre-push hook is restore-first too.** Re-pushing an already
+  published commit restores its exact bundle and skips the browser; a real miss
+  captures once and requires a clean SHA-keyed upload before the push proceeds.
+
+## [4.4.0] - 2026-07-13
+
+### Changed
+
+- **Spec-driven captures now run in parallel across Playwright workers.** The
+  capture describe declares `parallel` mode itself, so surface×width tests fan
+  out over the consumer's `workers` even when the project pins
+  `fullyParallel: false` for its behaviour suite. Every generated test was
+  already independent (own page, own map/HAR files, own self-check; ledger and
+  manifest tests mkdir and tolerate any order), so the maps are byte-identical —
+  a real consumer's 150-capture run dropped from 24.5 to 6.0 minutes at 4
+  workers on the same box. A spec file whose OWN sibling tests read the captured
+  maps in file order can opt out with `parallel: false`. Found while
+  dogfooding against a large single-route consumer app.
+
+### Fixed
+
+- **An absolute `STYLEMAP_DIR` (or `--dir`) is respected as-is.** It was joined
+  under `baseDir`, so `STYLEMAP_DIR=/abs/path styleproof-map` stranded the maps
+  at `.styleproof/maps/abs/path` where no consumer looks. Relative dirs nest
+  under `baseDir` unchanged. Also found dogfooding against a consumer app.
+
 ## [4.3.0] - 2026-07-13
 
 ### Changed

package/README.md

@@ -104,8 +104,8 @@ Either way the generated spec runs as-is. It also wires everything around it so
 - widths you never set — **omit `widths`** and StyleProof sweeps your app's real `@media` breakpoints automatically;
 - determinism you never set up — network settle, frozen clock, animation freeze, and framework-noise filtering are all on by default (see [Deterministic by default](#deterministic-by-default));
 - `.gitignore` entries for `.styleproof/`, `test-results/`, and `playwright-report/`;
-- a **cache-first CI workflow** that restores reusable maps from the `styleproof-maps` branch and generates the report without a browser when both maps are already built;
-- a **pre-push hook** (`.husky/` if present, else `.githooks/`) that captures each pushed commit and publishes the bundle to the `styleproof-maps` branch — CI's hot path stays report-only, and maps never get committed to the PR branch;
+- a **cache-first CI workflow** that restores reusable maps from the `styleproof-maps` branch, captures only a missing head when the base is compatible, and publishes every cold fallback so later runs stay browserless;
+- a **pre-push hook** (`.husky/` if present, else `.githooks/`) that restores an already-published commit or captures and publishes it once — CI's hot path stays report-only, repeated pushes do no browser work, and maps never get committed to the PR branch;
 - the **approval workflow** (`styleproof-approve.yml`) that turns the `StyleProof` status green when a reviewer ticks **Approve all changes** — so the review gate is complete, not half-wired (it activates once the init PR merges, since GitHub runs `issue_comment` workflows only from your default branch).
 
 ### 2. Capture, then diff
@@ -133,9 +133,12 @@ automatically: in GitHub Actions it uses the PR base/head SHAs; locally it check
 pre-push hook `styleproof-init` installs runs `styleproof-map` on every push
 that can affect render (skip one with `STYLEPROOF_SKIP_CAPTURE=1 git push`).
 On the PR, CI first restores the base/head bundles and only generates the
-report — no build, no browser. If either bundle is missing or incompatible,
-CI recaptures both sides in the same pinned environment before reporting.
-Correctness wins over a stale cache, but the hot path is report-only.
+report — no build, no browser. If only the head bundle is missing, CI keeps the
+compatible restored base and captures/publishes only the head. If the base
+bundle is missing or incompatible, CI recaptures and publishes both sides in
+the same pinned environment before reporting. Cold fallback work therefore
+becomes reusable instead of recurring on the next PR. Correctness wins over a
+stale cache, but the hot path is report-only.
 
 > **Same-environment note.** Computed styles depend on the browser build and installed fonts, so maps are only comparable when captured in the same runtime environment. StyleProof records a compatibility key to select the right cached bundle and refuses to compare maps captured under different browser/platform settings; CI then recaptures both sides instead of producing a bogus report. Each capture also records the **real browser build** (`browser().version()`) in its manifest — the npm `@playwright/test` version is only a proxy, and the actual Chromium binary can change while it holds constant (a `playwright install` re-download, a different `PLAYWRIGHT_BROWSERS_PATH`, a CI image bump). When both sides carry it, a differing build refuses to compare (exit 2, both builds named) instead of walling the PR with false diffs. This guard needs a `styleproof-manifest.json` on **both** sides. Since **v4** a two-directory `styleproof-diff`/`styleproof-report` where a side ships maps but no manifest **refuses to compare**: it exits `2` (usage/capture error) naming the bare side(s), because the environment can't be verified and captures from different browser builds or platforms would diff as false changes. Re-capture with current StyleProof — `styleproof-map`, or `styleproof-capture` for a one-shot design diff (both write a manifest); maps without one are unsupported. (A dir with _no maps at all_ is "no baseline yet", not a bare bundle — that stays the first-adoption review path, exit `3`.) **Installed fonts are your responsibility:** they are noisy across machines (user-installed families, OS updates, and no cheap cross-platform enumeration), so StyleProof does not fingerprint them — capture both sides on the same fonts, which is what CI's pinned image already gives you.
 
@@ -986,6 +989,7 @@ It's **asynchronous by design**: approval is a checkbox tick handled by a separa
 | `dataResidue` | `'gate'`                    | Name data-boundary (`replayUrl`) requests that **fail** during capture (network error / 4xx/5xx — the fallback branch got captured). Always warned + recorded; `'gate'` (the default) also blocks the diff on an unacknowledged one, `'warn'` is the opt-out that records + warns without gating. See [Data residue](#data-residue-a-failed-data-request-is-named-not-swallowed). |
 | `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.                                                                                                                                                                                                                                                                   |
 | `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                                                                                                                                                                                                                                                                                               |
+| `parallel`    | `true`                      | Run the generated capture tests across Playwright workers, even when the project config pins `fullyParallel: false` — every capture test is independent, so a multi-surface spec speeds up ~workers×. Set `false` only for a spec file whose own sibling tests read the captured maps in file order.                                                                              |
 | `selfCheck`   | on while recording          | Capture each surface twice and fail on any difference — proves the capture is deterministic. Off on the replay run; `STYLEPROOF_SELFCHECK=1` forces both.                                                                                                                                                                                                                         |
 | `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                                                                                                                                                                                                                                                                                   |
 | `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                                                                                                                                                                                                                                                                                            |
@@ -1011,7 +1015,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
-- `styleproof-init` — scaffold the gate: the capture spec (inventory guard on; Next.js repos get route discovery + the coverage guard, others a crawl-by-default spec), a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, the cache-first report workflow, the approval workflow, and the pre-push publish hook. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
+- `styleproof-init` — scaffold the gate: the capture spec (inventory guard on; Next.js repos get route discovery + the coverage guard, others a crawl-by-default spec), a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, the restore-first report workflow, the approval workflow, and the restore-or-publish pre-push hook. One command. The CI hot path restores exact-SHA maps and runs no browser; a compatible base hit plus head miss captures only the head; a base miss captures the pair; every fallback is published for reuse. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
 - `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--crawl-base-url` plus repeated `--crawl-route` to run `styleproof-variants` before capture, `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
 - `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical); `1` on a reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an unacknowledged failing data endpoint under an armed `dataResidue: 'gate'`, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **manifest-less side** — since **v4**, a two-directory compare where a side ships maps but no `styleproof-manifest.json` is refused loudly, naming the bare side(s), because the same-environment guard can't be enforced without one; re-capture with current StyleProof; **and** a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new — **and** the no-args case where the cached base map can't be restored at all: no map-store remote, no cached bundle, nothing to compare. A "nothing was compared" outcome always exits `2`, never a soft `0` that would read as certified; the error names the two ways forward — run in CI where the base is restorable, or use the two-directory form); `3` when only new surfaces are present — surfaces captured only on the **head** side (a surface present only on the **base** side is a **removed** surface, a reviewable change: exit `1`) — (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no maps at all (and hence no manifest), meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`. The human output **groups the same way the report does**: surfaces that changed identically collapse into one finding (with the per-surface count on its header), longhands fold into shorthands, and size/position-derived longhands fold behind a `(+N derived longhands)` count — so one real change reads as one entry, not dozens of raw lines. A change that rode the shared frame every view draws (a persistent nav/header/footer) is promoted to a "🧱 Global chrome change" callout up top. `--json` stays the complete, unchanged machine contract — every surface and every raw longhand — regardless of the human grouping.
 - `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports cached maps for the current commit against the inferred base; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).

package/bin/styleproof-init.mjs

@@ -366,13 +366,13 @@ export default defineConfig({
 const CI_PATH = '.github/workflows/styleproof.yml';
 const CI_WORKFLOW = `name: StyleProof
 
-# Cache-first v3 flow:
+# Cache-first v4 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 a head-only miss, CI captures/publishes only the head; on a base miss it
+#   recaptures/publishes the pair in one pinned environment.
 on:
   pull_request:
     types: [opened, synchronize, reopened, closed]
@@ -400,13 +400,16 @@ ${PM.setup}
         run: |
           BASE_SHA="\${{ github.event.pull_request.base.sha }}"
           HEAD_SHA="\${{ github.event.pull_request.head.sha }}"
-          rm -rf __stylemaps__
+          MAP_ROOT="\${{ runner.temp }}/styleproof-maps"
+          rm -rf "$MAP_ROOT"
           set +e
-          ${PM.exec(`styleproof-map --restore --sha "$BASE_SHA" --dir base --base-dir __stylemaps__ --spec ${specPath}`)}
+          ${PM.exec(`styleproof-map --restore --sha "$BASE_SHA" --dir base --base-dir "$MAP_ROOT" --spec ${specPath}`)}
           base_code=$?
-          ${PM.exec(`styleproof-map --restore --sha "$HEAD_SHA" --dir head --base-dir __stylemaps__ --spec ${specPath}`)}
+          ${PM.exec(`styleproof-map --restore --sha "$HEAD_SHA" --dir head --base-dir "$MAP_ROOT" --spec ${specPath}`)}
           head_code=$?
           set -e
+          echo "base-hit=$([ "$base_code" -eq 0 ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          echo "head-hit=$([ "$head_code" -eq 0 ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
           if [ "$base_code" -eq 0 ] && [ "$head_code" -eq 0 ]; then
             echo "capture-needed=false" >> "$GITHUB_OUTPUT"
           else
@@ -418,27 +421,40 @@ ${PM.setup}
         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`)}
+          MAP_ROOT="\${{ runner.temp }}/styleproof-maps"
+
+          if [ "\${{ steps.maps.outputs.base-hit }}" != 'true' ]; then
+            # Without a compatible base bundle, rebuild and publish the pair in
+            # one pinned environment. This is the expensive cold path.
+            rm -rf "$MAP_ROOT"
+            git checkout "$BASE_SHA"
+            ${PM.install}
+            ${PM.exec('playwright install --with-deps chromium')}
+            if [ -f "${specPath}" ]; then
+              ${PM.exec(`styleproof-map --spec ${specPath} --dir base --base-dir "$MAP_ROOT" --keep-har --sha "$BASE_SHA" --upload`)}
+            else
+              mkdir -p "$MAP_ROOT/base"
+            fi
+
+            git checkout "$HEAD_SHA"
+            ${PM.install}
+            ${PM.exec('playwright install --with-deps chromium')}
           else
-            mkdir -p __stylemaps__/base
+            # A compatible base hit proves the current head environment. Keep
+            # that restored base and capture only the missing head.
+            rm -rf "$MAP_ROOT/head"
+            ${PM.exec('playwright install --with-deps chromium')}
           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`)}
+          if find "$MAP_ROOT/base" -name '*.har' -print -quit | grep -q .; then
+            STYLEPROOF_REPLAY_FROM="$MAP_ROOT/base" ${PM.exec(`styleproof-map --spec ${specPath} --dir head --base-dir "$MAP_ROOT" --sha "$HEAD_SHA" --upload`)}
           else
-            ${PM.exec(`styleproof-map --spec ${specPath} --dir head --base-dir __stylemaps__ --no-upload`)}
+            ${PM.exec(`styleproof-map --spec ${specPath} --dir head --base-dir "$MAP_ROOT" --sha "$HEAD_SHA" --upload`)}
           fi
-      - uses: BenSheridanEdwards/StyleProof@v3
+      - uses: BenSheridanEdwards/StyleProof@v4
         with:
-          baseline-dir: __stylemaps__/base
-          fresh-dir: __stylemaps__/head
+          baseline-dir: \${{ runner.temp }}/styleproof-maps/base
+          fresh-dir: \${{ runner.temp }}/styleproof-maps/head
           require-approval: true
 
   prune:
@@ -600,7 +616,10 @@ const HOOK = `#!/bin/sh
 # Skip (e.g. a docs-only push): STYLEPROOF_SKIP_CAPTURE=1 git push
 set -e
 [ "\${STYLEPROOF_SKIP_CAPTURE:-}" = "1" ] && exit 0
-${PM.exec(`styleproof-map --spec ${specPath}`)}
+head_sha="$(git rev-parse HEAD)"
+if ! ${PM.exec(`styleproof-map --restore --sha "$head_sha" --dir current --base-dir .styleproof/maps --spec ${specPath}`)}; then
+  ${PM.exec(`styleproof-map --spec ${specPath} --sha "$head_sha" --upload`)}
+fi
 ${PM.exec('styleproof-diff')} || true # advisory: show drift before CI does
 `;
 const hookDir = fs.existsSync('.husky') ? '.husky' : '.githooks';
@@ -627,8 +646,8 @@ if (touched.length) {
 console.log('\nHow the gate works — it runs on your first PR with no extra steps:');
 console.log('  1. Commit and open a PR. CI captures the base and head surfaces in one pinned');
 console.log('     environment and posts the StyleProof report — no local step required.');
-console.log('  2. The pre-push hook captures each pushed commit into .styleproof/ and publishes');
-console.log('     the bundle to the styleproof-maps branch; CI restores it by SHA and generates');
+console.log('  2. The pre-push hook restores an existing exact-SHA map or captures once and');
+console.log('     publishes it to styleproof-maps; CI restores by SHA and generates');
 console.log('     the report without a browser. Maps never get committed to the PR branch.');
 console.log('     Skip a push that cannot affect render: STYLEPROOF_SKIP_CAPTURE=1 git push');
 console.log('  3. Merge this PR. The approval workflow only runs from your default branch, so');

package/bin/styleproof-map.mjs

@@ -253,7 +253,9 @@ function runVariantCrawl(env) {
   if (status !== 0) process.exit(status);
 }
 
-const targetDir = path.join(baseDir, dir);
+// An ABSOLUTE STYLEMAP_DIR/--dir is respected as-is; a relative one nests under
+// baseDir (.styleproof/maps by default) — mirrors the runner's resolveOutputDir.
+const targetDir = path.isAbsolute(dir) ? dir : path.join(baseDir, dir);
 // Sample the tree state the capture is ABOUT to render, so the manifest can bind the
 // map to it. A capture runs for minutes; if the source is edited or HEAD moves in that
 // window, the map renders one state but would otherwise be stamped clean@post-HEAD and

package/dist/runner.d.ts

@@ -150,6 +150,14 @@ export type DefineOptions = {
      * `selfCheck` explicitly to override.
      */
     selfCheck?: boolean;
+    /**
+     * Run the generated capture tests in PARALLEL across Playwright workers
+     * (default true). Every capture test is independent, so parallel is safe and
+     * ~workers× faster on a multi-surface spec — even when the project config
+     * pins `fullyParallel: false`. Set false ONLY for a spec file whose OTHER
+     * tests read the captured maps in file order (an in-file assertion suite).
+     */
+    parallel?: boolean;
     /**
      * Opt-in content layer (default OFF). Record each element's own rendered text
      * so the report's optional content section can surface copy changes (run
@@ -239,6 +247,10 @@ export declare function passLiveStreams(page: Page, url: string): Promise<void>;
  * forces it on either way.
  */
 export declare function defaultSelfCheck(replayFrom: string | undefined, env?: string | undefined): boolean;
+/** Resolve a capture output dir: an ABSOLUTE `dir` is respected as-is (a user's
+ *  `STYLEMAP_DIR=/abs/path` must not be buried under `baseDir`); a relative one
+ *  nests under `baseDir` as before. */
+export declare function resolveOutputDir(baseDir: string, dir: string): string;
 /**
  * Output base dir: explicit `baseDir` wins, then `STYLEPROOF_BASEDIR`, then the
  * default. Lets CLIs and CI redirect capture into cache/fallback dirs without

package/dist/runner.js

@@ -304,7 +304,7 @@ async function pinInputs(page, harName, s) {
         }
     }
     else {
-        await page.routeFromHAR(path.join(s.baseDir, s.dir, harName), {
+        await page.routeFromHAR(path.join(resolveOutputDir(s.baseDir, s.dir), harName), {
             url: s.replayUrl,
             update: true,
             updateContent: 'embed', // single portable file, no sidecar resources
@@ -443,7 +443,7 @@ async function capturePopupCandidate(page, surface, width, height, s, options, c
                 return;
             }
         }
-        const stem = path.join(s.baseDir, s.dir, `${surface.key}-${popupId}@${width}`);
+        const stem = path.join(resolveOutputDir(s.baseDir, s.dir), `${surface.key}-${popupId}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots)
             await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
@@ -495,7 +495,7 @@ async function captureSurface(page, surface, width, s) {
         // Attach data-residue AFTER the self-check re-run so both runs' failures are folded
         // (deduped in the watcher). Warn always; the recorded residue is what the gate reads.
         attachDataResidue(map, residue.residue());
-        const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
+        const stem = path.join(resolveOutputDir(s.baseDir, s.dir), `${surface.key}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots) {
             // captureStyleMap froze animations/transitions, so this is the same settled
@@ -533,6 +533,12 @@ function attachDataResidue(map, residue) {
 export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCHECK) {
     return env === '1' || !replayFrom;
 }
+/** Resolve a capture output dir: an ABSOLUTE `dir` is respected as-is (a user's
+ *  `STYLEMAP_DIR=/abs/path` must not be buried under `baseDir`); a relative one
+ *  nests under `baseDir` as before. */
+export function resolveOutputDir(baseDir, dir) {
+    return path.isAbsolute(dir) ? dir : path.join(baseDir, dir);
+}
 /**
  * Output base dir: explicit `baseDir` wins, then `STYLEPROOF_BASEDIR`, then the
  * default. Lets CLIs and CI redirect capture into cache/fallback dirs without
@@ -602,7 +608,7 @@ function resolveSettings(c) {
  */
 function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfaces) {
     test('styleproof coverage ledger', () => {
-        const outDir = path.join(settings.baseDir, dir);
+        const outDir = resolveOutputDir(settings.baseDir, dir);
         fs.mkdirSync(outDir, { recursive: true });
         // Determinism basis: self-check ON proves it (a drift would have failed the capture);
         // else a replay run is deterministic by construction; else it's unproven.
@@ -648,7 +654,7 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfac
 function writeBrowserBuildTest(settings, dir) {
     test('styleproof browser build', ({ page }) => {
         const version = page.context().browser()?.version();
-        const outDir = path.join(settings.baseDir, dir);
+        const outDir = resolveOutputDir(settings.baseDir, dir);
         writeBrowserBuildSidecar(outDir, version);
         writeCaptureManifest({ dir: outDir, screenshots: settings.screenshots });
     });
@@ -681,6 +687,16 @@ export function defineStyleMapCapture(options) {
         return;
     const settings = resolveSettings(options);
     test.describe('styleproof capture', () => {
+        // Every generated test is independent — its own page, its own map/HAR files,
+        // its own self-check; the ledger/manifest tests mkdir and tolerate any order.
+        // Declare the block PARALLEL so captures fan out across the consumer's
+        // Playwright workers even when the project pins `fullyParallel: false` for
+        // its behaviour suite (150 serial surface×width captures is a ~25-minute CI
+        // step; 4 workers make it ~4x faster with byte-identical maps).
+        // `parallel: false` keeps file order for specs whose own sibling tests read
+        // the captured maps.
+        if (options.parallel !== false)
+            test.describe.configure({ mode: 'parallel' });
         writeCoverageLedgerTest(settings, dir, expected ?? null, exclude, captureSurfaces);
         writeBrowserBuildTest(settings, dir);
         for (const surface of captureSurfaces) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "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",