tuffgal 0.1.0-alpha.9 → 0.2.0-alpha.2

package/dist/runner/orphanScan.js

@@ -0,0 +1,150 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * A11y companion suffix for a breakpoint-keyed baseline PNG. `<action>/<bp>.png`
+ * carries `<action>/<bp>.a11y.yaml` beside it (see `baselineStore.pathsFor`).
+ * Exported so `approve --from` derives the same companion filename from the
+ * shared constant instead of re-literalling the suffix at its own producer/
+ * consumer boundary.
+ */
+export const A11Y_SUFFIX = '.a11y.yaml';
+/**
+ * Pre-breakpoint (legacy) baseline files: a project baselined before the
+ * per-breakpoint layout committed `<action>/0.png` + `<action>/a11y.yaml`. The
+ * scan keys these under the synthetic breakpoint name `'legacy'` so a prune step
+ * can delete them without re-deriving the layout. Exported so `approve --from`
+ * shares the same legacy-layout literals rather than re-declaring them.
+ */
+export const LEGACY_PNG = '0.png';
+export const LEGACY_A11Y = 'a11y.yaml';
+export const LEGACY_BREAKPOINT = 'legacy';
+/**
+ * Non-action files that may sit at the baselines root and must never be treated
+ * as orphan candidates. `manifest.json` (the environment manifest, wave 6) is
+ * the known one; it is a file, not an action directory, so the readdir walk
+ * already skips it by virtue of only descending into directories — this set is a
+ * belt-and-suspenders guard for any future flat file a sibling wave drops here.
+ */
+const NON_ACTION_ENTRIES = new Set(['manifest.json']);
+/**
+ * Whether the orphan scan should run for this invocation. Two gates, both
+ * must hold:
+ *   - CI mode only. Local runs never read `paths.baselines` (they self-diff
+ *     against the per-machine cache), so there is no committed set to orphan.
+ *   - Unfiltered runs only. A `--story` filter runs a deliberate subset, so
+ *     every unselected story's baseline would look orphaned when it is merely
+ *     unvisited; a filtered run must never mark a live baseline `deleted`.
+ *
+ * Kept pure and separate from `run.ts` so the CI/local × filtered/unfiltered
+ * matrix is unit-testable without launching a browser.
+ */
+export function shouldScanForOrphans(mode, storyFilter) {
+    return mode === 'ci' && storyFilter === undefined;
+}
+/**
+ * The distinct set of action names that ran at least one result this run. An
+ * action directory under `paths.baselines` whose name is absent from this set
+ * had no story compare against it — it is a candidate orphan. Derived from the
+ * flat `stories[].actions[]` walk so `skipped` entries (an earlier step failed)
+ * still count the action as executed: the baseline was reachable this run, the
+ * story simply broke before reaching it, which is a failure to surface — not a
+ * baseline to retire.
+ */
+export function executedActionNames(stories) {
+    const names = new Set();
+    for (const story of stories) {
+        for (const action of story.actions) {
+            names.add(action.action);
+        }
+    }
+    return names;
+}
+/**
+ * Scans `baselinesDir` for orphaned committed baselines: action directories no
+ * story executed this run. Detection only — the returned entries carry the
+ * absolute paths a later `approve --prune` deletes; this function never touches
+ * the filesystem beyond reading directory listings.
+ *
+ * Caller contract (enforced in `run.ts`, documented here so the module reads
+ * standalone): only meaningful for an UNFILTERED CI run. A `--story`-filtered run
+ * executes a deliberate subset, so every unselected story's baseline would look
+ * orphaned; the caller skips the scan entirely on a filtered run rather than
+ * mark live baselines `deleted`. Local mode never reads `paths.baselines` at all,
+ * so it never calls this.
+ *
+ * Layout handled (mirrors `baselineStore.pathsFor`):
+ *   - breakpoint-keyed  `<action>/<breakpoint>.png` (+ `.a11y.yaml` companion)
+ *   - legacy            `<action>/0.png` (+ `a11y.yaml` companion)
+ *
+ * One {@link DeletedBaseline} per orphaned breakpoint (or the single `'legacy'`
+ * group), each bundling the PNG with its a11y companion when present. Files that
+ * are neither a recognised PNG nor a matching companion are ignored, so a stray
+ * file in an orphaned dir neither crashes the scan nor smuggles an untracked
+ * path into the prune list.
+ */
+export async function scanOrphanedBaselines(baselinesDir, executed) {
+    let entries;
+    try {
+        const dirents = await readdir(baselinesDir, { withFileTypes: true });
+        entries = dirents.map((dirent) => ({
+            name: dirent.name,
+            isDir: dirent.isDirectory(),
+        }));
+    }
+    catch {
+        // No baselines directory yet (a never-approved project) — nothing to orphan.
+        return [];
+    }
+    const orphans = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDir)
+            continue;
+        if (NON_ACTION_ENTRIES.has(entry.name))
+            continue;
+        if (executed.has(entry.name))
+            continue;
+        const actionDir = join(baselinesDir, entry.name);
+        orphans.push(...(await scanOrphanedActionDir(entry.name, actionDir)));
+    }
+    return orphans;
+}
+/**
+ * Groups one orphaned action directory's baseline files into per-breakpoint
+ * {@link DeletedBaseline} entries. Each PNG anchors a group; its a11y companion
+ * (breakpoint-keyed `<bp>.a11y.yaml`, or legacy `a11y.yaml`) joins the same group
+ * when it exists on disk. Files matching neither shape are skipped.
+ */
+async function scanOrphanedActionDir(action, actionDir) {
+    let files;
+    try {
+        files = await readdir(actionDir);
+    }
+    catch {
+        return [];
+    }
+    const present = new Set(files);
+    const groups = [];
+    for (const file of files.slice().sort()) {
+        if (file === LEGACY_PNG) {
+            const paths = [join(actionDir, LEGACY_PNG)];
+            if (present.has(LEGACY_A11Y))
+                paths.push(join(actionDir, LEGACY_A11Y));
+            groups.push({
+                action,
+                breakpoint: LEGACY_BREAKPOINT,
+                baselinePaths: paths,
+            });
+            continue;
+        }
+        if (file.endsWith('.png')) {
+            const breakpoint = file.slice(0, -'.png'.length);
+            const companion = `${breakpoint}${A11Y_SUFFIX}`;
+            const paths = [join(actionDir, file)];
+            if (present.has(companion))
+                paths.push(join(actionDir, companion));
+            groups.push({ action, breakpoint, baselinePaths: paths });
+        }
+    }
+    return groups;
+}
+//# sourceMappingURL=orphanScan.js.map

package/dist/runner/orphanScan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphanScan.js","sourceRoot":"","sources":["../../src/runner/orphanScan.ts"],"names":[],"mappings":"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"}

package/dist/runner/run.d.ts

@@ -1,11 +1,21 @@
 import type { ResolvedConfig } from '../config.ts';
-import type { RunResult } from '../schema/result.ts';
+import type { EnvironmentReport, RunResult, StoryResult, StoryStatus } from '../schema/result.ts';
+import { type RunMode } from './mode.ts';
+import { type CapturedBrowser } from './manifest.ts';
 export interface RunCliOptions {
     storyFilter?: string;
     headed: boolean;
     workers?: number;
     manageServers?: boolean;
     coverage?: boolean;
+    /**
+     * Resolved comparison contract (see {@link RunMode}). Governs baseline-write
+     * vs candidate-write in `runAction` and the run's exit-code derivation. The
+     * CLI always supplies it (resolved from `--ci`/`--local`/`$CI`); it stays
+     * optional so existing programmatic callers keep compiling, defaulting to
+     * `local` (the legacy auto-write behaviour) when omitted.
+     */
+    mode?: RunMode;
 }
 /**
  * Loads every action and story from the configured paths, resets the
@@ -15,4 +25,78 @@ export interface RunCliOptions {
  * code.
  */
 export declare function runAll(config: ResolvedConfig, options: RunCliOptions): Promise<RunResult>;
+/**
+ * Copies the just-written `results.json` into `<report>/candidates/` so the
+ * candidate tree is a self-contained approval artifact. `writeReport` has
+ * already written `<report>/results.json`; this places a sibling copy under
+ * candidates. The candidates dir may not exist yet (a run where every action
+ * passed writes no candidate renders), so it is created first — an empty
+ * `candidates/` carrying only `results.json` still correctly describes "nothing
+ * to approve".
+ */
+export declare function copyResultsIntoCandidates(reportDir: string): Promise<void>;
+/**
+ * The baseline root the screen-coverage metric measures against: committed
+ * `paths.baselines` in CI mode, per-machine `paths.localCache` in local mode.
+ * A thin, coverage-named alias over the shared {@link comparisonRootFor} so the
+ * metric counts screens against the SAME set the run (via `runAction`) diffed
+ * against — the mode→root mapping now lives once, in `mode.ts`. Preserved as a
+ * named export because the coverage metric's PRD invariant (a local run never
+ * reads `paths.baselines`) reads most clearly against a coverage-specific name.
+ */
+export declare function coverageComparisonRoot(config: ResolvedConfig, mode: RunMode): string;
+/**
+ * Builds the run's {@link EnvironmentReport}: the environment this run captured
+ * under (`actual`), and — in CI mode — the committed `<baselines>/manifest.json`
+ * (`expected`) plus whether their pixel-affecting keys diverge.
+ *
+ * The live browser-version probe ({@link captureBrowserIdentity}) runs in CI
+ * mode ONLY. Local mode never reads `paths.baselines`, so `expected` is always
+ * `null` and `browserVersion` is never compared against anything — launching a
+ * throwaway chromium just to stamp a value nothing reads is pure cost, so local
+ * mode fills the browser identity with an empty sentinel and skips the probe.
+ *
+ * In CI mode a missing manifest is the bootstrap case (no expectation yet, no
+ * mismatch); a malformed one surfaces as a mismatch note (see
+ * {@link compareEnvironment}). `expected` carries the parsed manifest only when
+ * it read cleanly, so a malformed file reports `null` here while still driving a
+ * mismatch.
+ *
+ * `probe` is the live browser-identity reader, injected (defaulting to the real
+ * {@link captureBrowserIdentity}) so a test can assert it is invoked in CI mode
+ * and NEVER invoked in local mode without launching a real chromium.
+ */
+export declare function resolveEnvironmentReport(config: ResolvedConfig, mode: RunMode, probe?: () => Promise<CapturedBrowser>): Promise<EnvironmentReport>;
+/**
+ * Rolls a set of story results into the outcome counts. `deleted` counts
+ * orphaned baselines, which are a run-level detection (not a per-story outcome),
+ * so it always seeds `0` here; `runAll` overwrites the run-total `deleted` from
+ * the orphan scan. Per-breakpoint pass summaries keep `0`, which is correct —
+ * an orphan is not attributable to a single breakpoint pass.
+ */
+export declare function summarise(results: StoryResult[]): RunResult['totals'];
+/**
+ * One streaming finish line: `<symbol> <actionCount> <elapsed>s <stem>`. The
+ * count is how many steps the story ran, the elapsed time is wall-clock
+ * duration to hundredths of a second, and the stem is the story file without
+ * its `.json` extension.
+ */
+export declare function formatResultLine(status: StoryStatus, actionCount: number, durationMs: number, file: string): string;
+/**
+ * One Summary bullet for a breakpoint pass: `• <parts> on "<name>" breakpoint`,
+ * where `<parts>` joins only the nonzero outcome categories in a fixed order
+ * (passed, new, changed, failed) — e.g. `2 passed, 1 changed`. Falls back to
+ * `0 passed` for the degenerate all-zero pass the run loop never actually
+ * emits (it `continue`s past a pass with no participating stories).
+ */
+export declare function formatSummaryBullet(name: string, counts: RunResult['totals']): string;
+/**
+ * The breakpoint names that drove a merged story to its status — the modes the
+ * reader actually needs to inspect. A `changed` story that drifted only at
+ * `desktop` tags `[desktop]`, not the `mobile` pass that stayed clean. Returns
+ * empty (no tag) when the story spans a single breakpoint, since there is
+ * nothing to disambiguate. The merged actions still carry their `breakpoint`
+ * tag, so this is derived, not separately tracked.
+ */
+export declare function drivingBreakpoints(result: StoryResult): string[];
 //# sourceMappingURL=run.d.ts.map

package/dist/runner/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/runner/run.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,qBAAqB,CAAC;AAmBlE,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,SAAS,CAAC,CAsEpB"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/runner/run.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAsB,cAAc,EAAE,MAAM,cAAc,CAAC;AAEvE,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,WAAW,EACZ,MAAM,qBAAqB,CAAC;AA8B7B,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAUD;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,SAAS,CAAC,CA0KpB;AA4DD;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,OAAO,GACZ,MAAM,CAER;AA6BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,OAAO,EACb,KAAK,GAAE,MAAM,OAAO,CAAC,eAAe,CAA0B,GAC7D,OAAO,CAAC,iBAAiB,CAAC,CAe5B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,CASrE;AAUD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,GAC1B,MAAM,CAQR;AAoBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAuBhE"}

package/dist/runner/run.js

@@ -1,7 +1,8 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
 import { cpus } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright';
 import { loadActions, loadStories } from "../schema/load.js";
 import { writeReport } from "../reporter/writeReport.js";
 import { computeFlowCoverage } from "../coverage/flows.js";
@@ -9,9 +10,14 @@ import { computeScreenCoverage } from "../coverage/screens.js";
 import { resetDatabase } from "./bridges/database.js";
 import { startManagedDevServers, } from "./bridges/devServers.js";
 import { CoverageCollector } from "./coverage.js";
-import { runStory } from "./runStory.js";
+import { mergeStoryStatus, runStory } from "./runStory.js";
 import { buildSchedule, drainSchedule, } from "./scheduler.js";
+import { adaptNeedsForPass, mergeStoryResults, resolveBreakpointPasses, storyRendersAt, } from "./breakpointPasses.js";
 import { storyMatchesFilter } from "./storyFilter.js";
+import { candidatesDir } from "../screenshots/baselineStore.js";
+import { executedActionNames, scanOrphanedBaselines, shouldScanForOrphans, } from "./orphanScan.js";
+import { comparisonRootFor } from "./mode.js";
+import { captureEnvironment, compareEnvironment, readManifest, } from "./manifest.js";
 const HEARTBEAT_FILE = '.heartbeat';
 /**
  * Loads every action and story from the configured paths, resets the
@@ -22,6 +28,7 @@ const HEARTBEAT_FILE = '.heartbeat';
  */
 export async function runAll(config, options) {
     const startedAt = new Date();
+    const mode = options.mode ?? 'local';
     let managedServers;
     if (options.manageServers) {
         managedServers = await startManagedDevServers(config);
@@ -33,10 +40,6 @@ export async function runAll(config, options) {
         ? new CoverageCollector(config.paths.report)
         : undefined;
     try {
-        if (config.database?.reset) {
-            process.stdout.write('Resetting test database…\n');
-            await resetDatabase(config);
-        }
         const actions = await loadActions(config.paths.actions);
         const allStories = await loadStories(config.paths.stories);
         const scheduled = buildSchedule(allStories);
@@ -47,23 +50,100 @@ export async function runAll(config, options) {
             throw new Error(`No story matched filter "${options.storyFilter}"`);
         }
         const workerCount = resolveWorkerCount(config, options.workers);
-        process.stdout.write(`Scheduling ${subset.length} stories on ${workerCount} worker${workerCount === 1 ? '' : 's'}.\n`);
-        const results = await drainSchedule(subset, workerCount, (item) => runScheduledStory(item, actions, config, options.headed, coverage), (item) => process.stdout.write(`▶ ${item.file}\n`), (item, result) => process.stdout.write(`  ${result.status.toUpperCase()} ${item.file} (${result.actions.length} actions, ${result.durationMs} ms)\n`));
+        const passes = resolveBreakpointPasses(subset, config);
+        const multiPass = passes.length > 1;
+        process.stdout.write(`Scheduling ${subset.length} stories on ${workerCount} worker${workerCount === 1 ? '' : 's'}` +
+            (multiPass ? ` across ${passes.length} breakpoint passes` : '') +
+            '.\n');
+        // Run each breakpoint as its own pass: a full reset/seed, then the whole
+        // schedule rendered at that one breakpoint. This is what keeps breakpoints
+        // isolated — a destructive story can mutate the seeded database in the
+        // `mobile` pass without the `desktop` pass ever seeing it, because the next
+        // pass starts from a fresh reset. Results are merged back per story below.
+        const partsByFile = new Map();
+        const order = [];
+        const passSummaries = [];
+        for (const breakpoint of passes) {
+            const participating = subset.filter((item) => storyRendersAt(item, config, breakpoint));
+            if (participating.length === 0)
+                continue;
+            // Header for every pass — single- and multi-breakpoint alike. The reset
+            // sits beneath the header so the "fresh database" line reads as part of
+            // this pass's setup; a trailing blank line then separates setup from the
+            // streaming result lines.
+            process.stdout.write(`\nStarting "${breakpoint.name}" breakpoint pass at ${breakpoint.width}x${breakpoint.height}\n`);
+            if (config.database?.reset) {
+                process.stdout.write('Resetting test database…\n');
+                await resetDatabase(config);
+            }
+            process.stdout.write('\n');
+            const passResults = await drainSchedule(adaptNeedsForPass(participating), workerCount, (item) => runScheduledStory(item, actions, config, options.headed, coverage, breakpoint, mode), () => { }, (_item, result) => process.stdout.write(`${formatResultLine(result.status, result.actions.length, result.durationMs, result.file)}\n`));
+            passSummaries.push({
+                name: breakpoint.name,
+                counts: summarise(passResults),
+            });
+            for (const result of passResults) {
+                let parts = partsByFile.get(result.file);
+                if (!parts) {
+                    parts = [];
+                    partsByFile.set(result.file, parts);
+                    order.push(result.file);
+                }
+                parts.push(result);
+            }
+        }
+        const results = order.map((file) => mergeStoryResults(partsByFile.get(file)));
         const finishedAt = new Date();
+        // Screen coverage measures how many screens have a baseline in the set this
+        // run compares against — the committed `paths.baselines` in CI mode, the
+        // per-machine `paths.localCache` in local mode. Local runs never read
+        // `paths.baselines` (PRD invariant). Both the metric and `runAction` pick
+        // their root through the shared `comparisonRootFor`, so the metric measures
+        // against the exact set the run diffed against; its meaning ("screens with a
+        // baseline to diff against") is preserved rather than blanked.
         const [screens, flows] = await Promise.all([
-            computeScreenCoverage(config.paths.actions, config.paths.baselines),
+            computeScreenCoverage(config.paths.actions, coverageComparisonRoot(config, mode)),
             computeFlowCoverage(config.flowInventory, allStories),
         ]);
+        // Orphan scan: committed baselines whose action ran no story this run are
+        // retired candidates (status `deleted`). Only meaningful for an UNFILTERED
+        // CI run — a `--story` filter runs a deliberate subset, so unselected
+        // stories' baselines would look orphaned when they are merely unvisited; we
+        // skip the scan rather than mark live baselines deleted. Local mode never
+        // reads `paths.baselines`, so it never scans. Detection only — pruning is a
+        // later wave, so the baselines directory stays untouched here.
+        const deleted = shouldScanForOrphans(mode, options.storyFilter)
+            ? await scanOrphanedBaselines(config.paths.baselines, executedActionNames(results))
+            : [];
+        const totals = summarise(results);
+        totals.deleted = deleted.length;
+        // Capture-environment provenance: what this run rendered under, and — in CI
+        // mode — whether it drifted from the committed baselines' manifest. Local
+        // mode never reads `paths.baselines`, so `expected` stays null and mismatch
+        // is always false (see resolveEnvironmentReport).
+        const environment = await resolveEnvironmentReport(config, mode);
         const runResult = {
             startedAt: startedAt.toISOString(),
             finishedAt: finishedAt.toISOString(),
             durationMs: finishedAt.getTime() - startedAt.getTime(),
-            totals: summarise(results),
+            mode,
+            totals,
+            environment,
             customCoverage: { screens, flows },
+            deleted,
             stories: results,
         };
-        const reportPath = await writeReport(config.paths.report, runResult);
-        writeRunSummary(results, runResult.totals, reportPath);
+        const reportPath = await writeReport(config.paths.report, runResult, config.interactiveMode);
+        // In CI mode the `<report>/candidates/` tree is the self-contained approval
+        // artifact — copy the run's `results.json` beside the candidate renders so a
+        // downstream `approve --from <candidates>` has the outcome data (which
+        // actions are new/changed, and later the environment/deleted blocks) without
+        // needing the rest of the report dir. Only meaningful in CI mode, where the
+        // candidate tree exists.
+        if (mode === 'ci') {
+            await copyResultsIntoCandidates(config.paths.report);
+        }
+        writeRunSummary(passSummaries, reportPath);
         if (coverage) {
             const coveragePath = await coverage.generate();
             process.stdout.write(`Coverage: ${coveragePath}\n`);
@@ -76,7 +156,7 @@ export async function runAll(config, options) {
         }
     }
 }
-function runScheduledStory(item, actions, config, headed, coverage) {
+function runScheduledStory(item, actions, config, headed, coverage, breakpoint, mode) {
     return runStory({
         story: item.story,
         file: item.file,
@@ -86,6 +166,8 @@ function runScheduledStory(item, actions, config, headed, coverage) {
         config,
         headed,
         coverage,
+        breakpoint,
+        mode,
     });
 }
 function matchesFilter(item, filter) {
@@ -111,44 +193,188 @@ async function touchHeartbeat(config) {
         // hiccup should not fail the entire run.
     }
 }
-function summarise(results) {
+/**
+ * Copies the just-written `results.json` into `<report>/candidates/` so the
+ * candidate tree is a self-contained approval artifact. `writeReport` has
+ * already written `<report>/results.json`; this places a sibling copy under
+ * candidates. The candidates dir may not exist yet (a run where every action
+ * passed writes no candidate renders), so it is created first — an empty
+ * `candidates/` carrying only `results.json` still correctly describes "nothing
+ * to approve".
+ */
+export async function copyResultsIntoCandidates(reportDir) {
+    const dir = candidatesDir(reportDir);
+    await mkdir(dir, { recursive: true });
+    await copyFile(join(reportDir, 'results.json'), join(dir, 'results.json'));
+}
+/**
+ * The baseline root the screen-coverage metric measures against: committed
+ * `paths.baselines` in CI mode, per-machine `paths.localCache` in local mode.
+ * A thin, coverage-named alias over the shared {@link comparisonRootFor} so the
+ * metric counts screens against the SAME set the run (via `runAction`) diffed
+ * against — the mode→root mapping now lives once, in `mode.ts`. Preserved as a
+ * named export because the coverage metric's PRD invariant (a local run never
+ * reads `paths.baselines`) reads most clearly against a coverage-specific name.
+ */
+export function coverageComparisonRoot(config, mode) {
+    return comparisonRootFor(config, mode);
+}
+/**
+ * Reads the launched Chromium's `browser.version()` so the run's environment
+ * manifest records the exact browser build the baselines were rendered against —
+ * the single pixel-affecting fact that only a live browser can report. Launched
+ * throwaway (not the per-story browsers, which spin up and tear down inside the
+ * schedule) because the version is invariant across stories, so one probe covers
+ * the whole run. Kept narrow: launch, read, close.
+ */
+async function captureBrowserIdentity() {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        return { name: 'chromium', version: browser.version() };
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * The browser identity stamped into a LOCAL run's environment block. Local mode
+ * skips the live probe (see {@link resolveEnvironmentReport}), so `version` is an
+ * empty sentinel: it is shape-valid for the manifest, never compared (local
+ * `expected` is always null), and never promoted (local candidates are refused
+ * by `approve --from`). Kept as chromium's name for provenance, since that is
+ * still the browser a local run renders under.
+ */
+const LOCAL_BROWSER_IDENTITY = { name: 'chromium', version: '' };
+/**
+ * Builds the run's {@link EnvironmentReport}: the environment this run captured
+ * under (`actual`), and — in CI mode — the committed `<baselines>/manifest.json`
+ * (`expected`) plus whether their pixel-affecting keys diverge.
+ *
+ * The live browser-version probe ({@link captureBrowserIdentity}) runs in CI
+ * mode ONLY. Local mode never reads `paths.baselines`, so `expected` is always
+ * `null` and `browserVersion` is never compared against anything — launching a
+ * throwaway chromium just to stamp a value nothing reads is pure cost, so local
+ * mode fills the browser identity with an empty sentinel and skips the probe.
+ *
+ * In CI mode a missing manifest is the bootstrap case (no expectation yet, no
+ * mismatch); a malformed one surfaces as a mismatch note (see
+ * {@link compareEnvironment}). `expected` carries the parsed manifest only when
+ * it read cleanly, so a malformed file reports `null` here while still driving a
+ * mismatch.
+ *
+ * `probe` is the live browser-identity reader, injected (defaulting to the real
+ * {@link captureBrowserIdentity}) so a test can assert it is invoked in CI mode
+ * and NEVER invoked in local mode without launching a real chromium.
+ */
+export async function resolveEnvironmentReport(config, mode, probe = captureBrowserIdentity) {
+    if (mode !== 'ci') {
+        // Local mode never gates on `browserVersion` (expected is always null), so
+        // skip the browser launch entirely. The empty sentinel is shape-valid and
+        // never promoted — a local run writes no candidate tree, and `approve --from`
+        // refuses non-ci candidates outright.
+        const actual = captureEnvironment(config, LOCAL_BROWSER_IDENTITY);
+        return { expected: null, actual, mismatch: false, mismatchKeys: [] };
+    }
+    const actual = captureEnvironment(config, await probe());
+    const read = await readManifest(config.paths.baselines);
+    const { mismatch, mismatchKeys } = compareEnvironment(read, actual);
+    const expected = read.status === 'ok' ? read.manifest : null;
+    return { expected, actual, mismatch, mismatchKeys };
+}
+/**
+ * Rolls a set of story results into the outcome counts. `deleted` counts
+ * orphaned baselines, which are a run-level detection (not a per-story outcome),
+ * so it always seeds `0` here; `runAll` overwrites the run-total `deleted` from
+ * the orphan scan. Per-breakpoint pass summaries keep `0`, which is correct —
+ * an orphan is not attributable to a single breakpoint pass.
+ */
+export function summarise(results) {
     return {
         stories: results.length,
         passed: results.filter((result) => result.status === 'pass').length,
         changed: results.filter((result) => result.status === 'changed').length,
         failed: results.filter((result) => result.status === 'failed').length,
+        new: results.filter((result) => result.status === 'new').length,
+        deleted: 0,
     };
 }
+/** Status → leading glyph for a streaming result line. */
+const STATUS_SYMBOL = {
+    pass: '✓',
+    changed: '~',
+    new: '+',
+    failed: '✗',
+};
 /**
- * Emits the end-of-run tail. The streaming `▶`/`PASS|CHANGED|FAILED` lines
- * already cover the heartbeat; this groups the noteworthy stories
- * (changed + failed) in finish order so a user scanning the terminal lands
- * on the actionable list directly above the totals. The `Report:` line is
- * a `file://` URL so terminals that recognise file URIs (iTerm2, Warp, VS
- * Code) render it as a clickable link.
+ * One streaming finish line: `<symbol> <actionCount> <elapsed>s <stem>`. The
+ * count is how many steps the story ran, the elapsed time is wall-clock
+ * duration to hundredths of a second, and the stem is the story file without
+ * its `.json` extension.
  */
-function writeRunSummary(results, totals, reportPath) {
-    const changed = results.filter((result) => result.status === 'changed');
-    const failed = results.filter((result) => result.status === 'failed');
-    if (changed.length > 0 || failed.length > 0) {
-        process.stdout.write('\n');
-        if (changed.length > 0) {
-            process.stdout.write('Changed:\n');
-            for (const result of changed) {
-                process.stdout.write(`  ${formatSummaryLine(result)}\n`);
-            }
-        }
-        if (failed.length > 0) {
-            process.stdout.write('Failed:\n');
-            for (const result of failed) {
-                process.stdout.write(`  ${formatSummaryLine(result)}\n`);
-            }
-        }
+export function formatResultLine(status, actionCount, durationMs, file) {
+    const elapsed = (durationMs / 1000).toFixed(2);
+    const stem = file.replace(/\.json$/, '');
+    return `${STATUS_SYMBOL[status]} ${actionCount} ${elapsed}s ${stem}`;
+}
+/**
+ * One Summary bullet for a breakpoint pass: `• <parts> on "<name>" breakpoint`,
+ * where `<parts>` joins only the nonzero outcome categories in a fixed order
+ * (passed, new, changed, failed) — e.g. `2 passed, 1 changed`. Falls back to
+ * `0 passed` for the degenerate all-zero pass the run loop never actually
+ * emits (it `continue`s past a pass with no participating stories).
+ */
+export function formatSummaryBullet(name, counts) {
+    const parts = [];
+    if (counts.passed > 0)
+        parts.push(`${counts.passed} passed`);
+    if (counts.new > 0)
+        parts.push(`${counts.new} new`);
+    if (counts.changed > 0)
+        parts.push(`${counts.changed} changed`);
+    if (counts.failed > 0)
+        parts.push(`${counts.failed} failed`);
+    const summary = parts.length > 0 ? parts.join(', ') : '0 passed';
+    return `• ${summary} on "${name}" breakpoint`;
+}
+/**
+ * Emits the end-of-run tail: a `Summary` section with one bullet per breakpoint
+ * pass — counted from that pass's own results, not the merged-across-passes
+ * rollup — then the `Report:` line. The report link is a `file://` URL so
+ * terminals that recognise file URIs (iTerm2, Warp, VS Code) render it as a
+ * clickable link.
+ */
+function writeRunSummary(passSummaries, reportPath) {
+    process.stdout.write('\nSummary\n');
+    for (const pass of passSummaries) {
+        process.stdout.write(`${formatSummaryBullet(pass.name, pass.counts)}\n`);
     }
-    process.stdout.write(`\nTotals: ${totals.passed} pass · ${totals.changed} changed · ${totals.failed} failed\n`);
-    process.stdout.write(`Report: ${pathToFileURL(reportPath).href}\n`);
+    process.stdout.write(`\nReport: ${pathToFileURL(reportPath).href}\n`);
 }
-function formatSummaryLine(result) {
-    return `${result.status.toUpperCase()} ${result.file} — ${result.story} (${result.actions.length} actions, ${result.durationMs} ms)`;
+/**
+ * The breakpoint names that drove a merged story to its status — the modes the
+ * reader actually needs to inspect. A `changed` story that drifted only at
+ * `desktop` tags `[desktop]`, not the `mobile` pass that stayed clean. Returns
+ * empty (no tag) when the story spans a single breakpoint, since there is
+ * nothing to disambiguate. The merged actions still carry their `breakpoint`
+ * tag, so this is derived, not separately tracked.
+ */
+export function drivingBreakpoints(result) {
+    const order = [];
+    const perBreakpoint = new Map();
+    for (const action of result.actions) {
+        const breakpoint = action.breakpoint;
+        if (!breakpoint)
+            continue;
+        if (!perBreakpoint.has(breakpoint)) {
+            perBreakpoint.set(breakpoint, 'pass');
+            order.push(breakpoint);
+        }
+        perBreakpoint.set(breakpoint, mergeStoryStatus(perBreakpoint.get(breakpoint), 
+        // A skipped action means an earlier action in that breakpoint failed.
+        action.status === 'skipped' ? 'failed' : action.status));
+    }
+    if (order.length <= 1)
+        return [];
+    return order.filter((breakpoint) => perBreakpoint.get(breakpoint) === result.status);
 }
 //# sourceMappingURL=run.js.map