styleproof 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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

@@ -986,6 +986,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.                                                                                                                                                                                                                                                                                                                                                            |

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.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",