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

package/dist/runner/approveFrom.js

@@ -0,0 +1,384 @@
+import { lstat, readFile, readdir, rm } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { PNG } from 'pngjs';
+import { ACTION_NAME_PATTERN, BREAKPOINT_SEGMENT_PATTERN, writePng, writeText, } from "../screenshots/baselineStore.js";
+import { CAPTURE_SCHEMA, MANIFEST_FILENAME, SCHEMA_VERSION, validateManifestShape, } from "./manifest.js";
+import { A11Y_SUFFIX, LEGACY_A11Y, LEGACY_BREAKPOINT, LEGACY_PNG, } from "./orphanScan.js";
+import { parseRunResult } from "../schema/result.js";
+/**
+ * Error thrown when the candidate tree fails a trust-boundary check. Carries no
+ * extra data — the message is the whole contract. Distinct type so the CLI can
+ * present it plainly; every throw here happens BEFORE any write, so the promise
+ * rejecting guarantees `paths.baselines` was not touched.
+ */
+export class ApproveFromError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApproveFromError';
+    }
+}
+/**
+ * Promotes a CI candidate tree (`<dir>/<action>/<breakpoint>.png` + optional
+ * `.a11y.yaml`, plus a top-level `results.json`) into the committed
+ * `paths.baselines` set, and writes `<baselines>/manifest.json` from the
+ * candidate run's captured environment.
+ *
+ * TRUST BOUNDARY. `<dir>` is an untrusted artifact — a human or bot unzipped it
+ * from CI. This is the only path that writes committed baselines, so it is
+ * fail-closed and validate-all-then-write:
+ *   1. `results.json` must parse, describe a clean CI run (`mode: 'ci'` with
+ *      `totals.failed === 0` — never promote a local or broken run's partial
+ *      tree, see {@link assertPromotableRun}), and carry a well-shaped
+ *      `environment.actual` block (validated against the manifest shape, not
+ *      just present).
+ *   2. Every tree entry is validated (allowed shape, safe names, no symlinks, no
+ *      traversal) and every PNG is decoded to prove it is a real PNG.
+ *   3. ONLY after the whole tree passes are any bytes written. A single bad
+ *      entry aborts with {@link ApproveFromError} and zero filesystem changes.
+ *
+ * Every candidate file's bytes are read once during phase 1 and RETAINED for
+ * phase 2, which writes exactly those bytes — the sources are never re-read, so
+ * the committed baseline is provably the payload that passed validation (no
+ * decode-swap / symlink-swap window between the check and the write).
+ *
+ * PNGs are written through {@link writePng} (decode→recompress→encode), so the
+ * promoted baseline is losslessly recompressed and provably decodable in one
+ * step — never a raw `copyFile` of unvalidated artifact bytes.
+ */
+export async function approveFrom(config, options) {
+    const candidateDir = options.from;
+    await assertRealDirectory(candidateDir);
+    // Phase 1 — validate the whole tree and build a write plan. Every source is
+    // read exactly ONCE here and its bytes are retained on the plan; no writes yet.
+    const result = await readCandidateResults(candidateDir);
+    assertPromotableRun(result);
+    const environment = extractEnvironment(result);
+    const plan = await planWrites(candidateDir, config.paths.baselines);
+    await assertAllPngsDecode(plan);
+    const pruneTargets = options.prune
+        ? computePruneTargets(result, config.paths.baselines)
+        : [];
+    // Phase 2 — every check passed; commit the RETAINED bytes. Nothing is re-read
+    // from the candidate tree here, so the bytes committed are exactly the bytes
+    // that were validated (no decode-swap / symlink-swap window).
+    for (const write of plan) {
+        if (write.kind === 'png') {
+            await writePng(write.destination, write.bytes);
+        }
+        else {
+            await writeText(write.destination, write.bytes.toString('utf8'));
+        }
+    }
+    await writeManifest(config.paths.baselines, environment);
+    let pruned = 0;
+    for (const group of pruneTargets) {
+        for (const path of group) {
+            await rm(path, { force: true });
+        }
+        pruned += 1;
+    }
+    return {
+        written: plan.filter((write) => write.kind === 'png').length,
+        pruned,
+    };
+}
+/** Aborts unless `dir` exists and is a real directory (not a symlink). */
+async function assertRealDirectory(dir) {
+    let stats;
+    try {
+        stats = await lstat(dir);
+    }
+    catch {
+        throw new ApproveFromError(`--from directory not found: ${dir}`);
+    }
+    if (stats.isSymbolicLink()) {
+        throw new ApproveFromError(`--from path is a symlink, refusing: ${dir}`);
+    }
+    if (!stats.isDirectory()) {
+        throw new ApproveFromError(`--from path is not a directory: ${dir}`);
+    }
+}
+/**
+ * Reads + parses `<dir>/results.json`. Absence is a hard error: the candidate
+ * artifact is incomplete without it (prune targets and the environment manifest
+ * both come from here).
+ */
+async function readCandidateResults(dir) {
+    const resultsPath = join(dir, 'results.json');
+    let raw;
+    try {
+        raw = await readFile(resultsPath, 'utf8');
+    }
+    catch {
+        throw new ApproveFromError(`Candidate tree is missing results.json at ${resultsPath}`);
+    }
+    try {
+        return parseRunResult(raw, resultsPath);
+    }
+    catch (error) {
+        throw new ApproveFromError(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Refuses to promote a candidate tree that did not come from a clean CI run.
+ * Three fail-closed gates, all derived from the candidate's own `results.json`:
+ *   - `mode !== 'ci'` — a local (advisory) run's candidate tree is rendered
+ *     against the per-machine cache on the developer's own platform, so
+ *     promoting it commits cross-platform pixels the CI gate would immediately
+ *     re-flag. Only a CI-mode run's renders are eligible for the committed set.
+ *   - `totals.failed` is not a number — `parseRunResult` validates only that
+ *     `stories` is an array, so a truncated or foreign artifact can reach here
+ *     with `totals` (or `totals.failed`) missing or non-numeric. Reading it
+ *     unguarded would either throw a raw `TypeError` (not an `ApproveFromError`,
+ *     breaking the trust-boundary contract) or, worse, evaluate `undefined > 0`
+ *     to `false` and SILENTLY pass the gate. A non-numeric `failed` is therefore
+ *     an explicit fail-closed refusal, not an assumed-zero.
+ *   - `totals.failed > 0` — a run with failed stories produced a PARTIAL tree
+ *     (broken stories wrote no candidate, or wrote a candidate mid-failure), so
+ *     promoting it would commit an incomplete baseline set. A broken run is
+ *     never a source of truth.
+ * All abort before any write. `mode` is read defensively (older artifacts may
+ * omit it) — a missing `mode` is treated as non-`ci` and refused, since only a
+ * current CI run stamps `mode: 'ci'`.
+ */
+function assertPromotableRun(result) {
+    if (result.mode !== 'ci') {
+        throw new ApproveFromError(`Candidate results.json was produced by a ${result.mode ?? 'pre-mode'} ` +
+            'run, not a CI run — only `mode: "ci"` candidates may be promoted into ' +
+            'committed baselines. Re-run under `tuffgal run --ci`.');
+    }
+    if (typeof result.totals?.failed !== 'number') {
+        throw new ApproveFromError('Candidate results.json is missing a numeric totals.failed count — the ' +
+            'artifact is truncated or was not produced by tuffgal. Refusing to ' +
+            'promote a run whose pass/fail status cannot be verified.');
+    }
+    if (result.totals.failed > 0) {
+        throw new ApproveFromError(`Candidate results.json reports ${result.totals.failed} failed ` +
+            'story(ies) — a broken run produces a partial candidate tree that must ' +
+            'never be promoted. Fix the failures and re-run before approving.');
+    }
+}
+/**
+ * Pulls the captured environment (`environment.actual`) out of the candidate
+ * run's results and validates its SHAPE before it can be promoted. Two failure
+ * modes, both fail closed:
+ *   - Missing: a candidate artifact produced by a pre-manifest tuffgal cannot
+ *     populate `<baselines>/manifest.json`, and writing baselines without the
+ *     manifest that gates them would silently defeat the environment-drift
+ *     check. The user re-runs with a manifest-aware tuffgal.
+ *   - Present but wrong-shaped: `parseRunResult` only checks that `stories` is
+ *     an array, so a well-formed-but-false `environment.actual` block would
+ *     otherwise flow straight into the committed manifest and defeat the drift
+ *     gate from the inside. It is run through the SAME {@link
+ *     validateManifestShape} check `readManifest` uses (reused, not duplicated),
+ *     so a malformed block aborts before any write.
+ */
+function extractEnvironment(result) {
+    const actual = result.environment?.actual;
+    if (!actual) {
+        throw new ApproveFromError('Candidate results.json has no environment block — it was produced by a ' +
+            'pre-manifest tuffgal. Re-run with a manifest-aware version before ' +
+            'approving, so baselines/manifest.json can be written.');
+    }
+    const invalid = validateManifestShape(actual);
+    if (invalid) {
+        throw new ApproveFromError(`Candidate results.json has a malformed environment block: ${invalid}`);
+    }
+    return actual;
+}
+/**
+ * Walks the candidate tree and returns the validated set of files to write.
+ * Enforces the whole allow-list: top level holds only `results.json` and action
+ * directories; each action directory holds only `<breakpoint>.png` /
+ * `<breakpoint>.a11y.yaml` (or legacy `0.png` / `a11y.yaml`). Every other shape
+ * — stray extensions, nested dirs, dotfiles, symlinks, traversal names — aborts.
+ * Every PNG is decoded here so a corrupt payload fails validation, not a write.
+ */
+async function planWrites(candidateDir, baselinesDir) {
+    const plan = [];
+    const topEntries = await readdir(candidateDir, { withFileTypes: true });
+    for (const entry of topEntries) {
+        assertSafeName(entry.name, candidateDir);
+        const entryPath = join(candidateDir, entry.name);
+        await assertNotSymlink(entryPath);
+        if (entry.name === 'results.json') {
+            continue; // consumed separately; never written into baselines
+        }
+        if (!entry.isDirectory()) {
+            throw new ApproveFromError(`Unexpected top-level file in candidate tree: ${entry.name} ` +
+                '(only results.json and action directories are allowed)');
+        }
+        if (!ACTION_NAME_PATTERN.test(entry.name)) {
+            throw new ApproveFromError(`Invalid action directory name "${entry.name}" — must be ` +
+                'lowercase-kebab ([a-z0-9-]+)');
+        }
+        plan.push(...(await planActionDir(candidateDir, baselinesDir, entry.name)));
+    }
+    return plan;
+}
+/**
+ * Validates one action directory's contents and returns its planned writes. Each
+ * source file is read exactly once here (after its symlink/name checks pass) and
+ * its bytes are retained on the {@link PlannedWrite} for phase 2 — the source is
+ * never re-read, closing the validate-then-swap TOCTOU window.
+ */
+async function planActionDir(candidateDir, baselinesDir, action) {
+    const actionPath = join(candidateDir, action);
+    const files = await readdir(actionPath, { withFileTypes: true });
+    const plan = [];
+    for (const file of files) {
+        assertSafeName(file.name, candidateDir);
+        const source = join(actionPath, file.name);
+        await assertNotSymlink(source);
+        if (!file.isFile()) {
+            throw new ApproveFromError(`Unexpected non-file entry in candidate tree: ${action}/${file.name} ` +
+                '(action directories hold only PNG + a11y.yaml files)');
+        }
+        const kind = classifyCandidateFile(file.name, `${action}/${file.name}`);
+        // Read once, after the symlink check, and retain the bytes — phase 2 writes
+        // exactly these, never re-reading `source`.
+        const bytes = await readFile(source);
+        // The destination is derived purely from validated names — never from any
+        // path string in the artifact — so it always lands inside <baselines>.
+        plan.push({
+            source,
+            destination: join(baselinesDir, action, file.name),
+            kind,
+            bytes,
+        });
+    }
+    return plan;
+}
+/**
+ * Decodes every planned PNG's RETAINED bytes (validation phase) so a corrupt or
+ * non-PNG payload aborts the whole approve with zero writes. Decoding the bytes
+ * already held on the plan (not a fresh read) is what makes the decode-check and
+ * the eventual write see the same payload. `writePng`'s own recompress step
+ * SWALLOWS a decode failure (it falls back to writing the given bytes), which is
+ * the right behaviour for a trusted capture but wrong for an untrusted artifact
+ * — a corrupt candidate PNG must fail closed, not land verbatim as a baseline.
+ */
+async function assertAllPngsDecode(plan) {
+    for (const write of plan) {
+        if (write.kind !== 'png')
+            continue;
+        try {
+            PNG.sync.read(write.bytes);
+        }
+        catch {
+            throw new ApproveFromError(`Candidate PNG is not a decodable PNG: ${write.source}`);
+        }
+    }
+}
+/**
+ * Classifies a candidate file inside an action dir, validating its breakpoint
+ * stem. Accepts breakpoint-keyed `<bp>.png` / `<bp>.a11y.yaml` and the legacy
+ * `0.png` / `a11y.yaml` pair. Anything else aborts.
+ */
+function classifyCandidateFile(name, label) {
+    if (name === LEGACY_A11Y)
+        return 'a11y'; // legacy companion
+    if (name === LEGACY_PNG)
+        return 'png'; // legacy PNG
+    if (name.endsWith(A11Y_SUFFIX)) {
+        assertBreakpointStem(name.slice(0, -A11Y_SUFFIX.length), label);
+        return 'a11y';
+    }
+    if (name.endsWith('.png')) {
+        assertBreakpointStem(name.slice(0, -'.png'.length), label);
+        return 'png';
+    }
+    throw new ApproveFromError(`Unexpected file in candidate tree: ${label} ` +
+        '(only <breakpoint>.png and <breakpoint>.a11y.yaml are allowed)');
+}
+/** Aborts unless `stem` matches the runner's own breakpoint-segment shape. */
+function assertBreakpointStem(stem, label) {
+    if (!BREAKPOINT_SEGMENT_PATTERN.test(stem)) {
+        throw new ApproveFromError(`Invalid breakpoint name in candidate tree: ${label} ` +
+            '(must be [a-z0-9_-]+)');
+    }
+}
+/**
+ * Rejects a filesystem name that is a dotfile or carries a path separator /
+ * traversal segment. `readdir` yields single path segments, so a `..` or a
+ * separator here means a hostile or malformed entry, not normal nesting.
+ */
+function assertSafeName(name, context) {
+    if (name === '' || name === '.' || name === '..') {
+        throw new ApproveFromError(`Unsafe entry name "${name}" in candidate tree under ${context}`);
+    }
+    if (name.startsWith('.')) {
+        throw new ApproveFromError(`Dotfile "${name}" not allowed in candidate tree under ${context}`);
+    }
+    if (name.includes('/') || name.includes('\\') || name.includes(sep)) {
+        throw new ApproveFromError(`Path separator in candidate entry name "${name}" under ${context}`);
+    }
+}
+/** Aborts if `path` is a symlink — never follow a link out of the tree. */
+async function assertNotSymlink(path) {
+    const stats = await lstat(path);
+    if (stats.isSymbolicLink()) {
+        throw new ApproveFromError(`Symlink not allowed in candidate tree: ${path}`);
+    }
+}
+/**
+ * Recomputes the local prune targets for `--prune` from the candidate run's
+ * `results.deleted`, entirely under the resolved `baselinesDir`. The artifact's
+ * own `baselinePaths[]` strings are ignored — they describe the CI machine's
+ * filesystem and could point anywhere. Instead each entry's `action` +
+ * `breakpoint` is re-validated and re-rooted here, so a prune can only ever
+ * delete files inside this repo's baselines directory.
+ */
+function computePruneTargets(result, baselinesDir) {
+    const groups = [];
+    for (const entry of result.deleted ?? []) {
+        if (!ACTION_NAME_PATTERN.test(entry.action)) {
+            throw new ApproveFromError(`results.deleted has an invalid action name "${entry.action}"`);
+        }
+        const actionDir = join(baselinesDir, entry.action);
+        const paths = entry.breakpoint === LEGACY_BREAKPOINT
+            ? [join(actionDir, LEGACY_PNG), join(actionDir, LEGACY_A11Y)]
+            : breakpointKeyedPaths(entry.breakpoint, actionDir);
+        for (const path of paths) {
+            assertInsideBaselines(path, baselinesDir);
+        }
+        groups.push(paths);
+    }
+    return groups;
+}
+/** The PNG + a11y companion paths for a breakpoint-keyed orphan. */
+function breakpointKeyedPaths(breakpoint, actionDir) {
+    if (!BREAKPOINT_SEGMENT_PATTERN.test(breakpoint)) {
+        throw new ApproveFromError(`results.deleted has an invalid breakpoint name "${breakpoint}"`);
+    }
+    return [
+        join(actionDir, `${breakpoint}.png`),
+        join(actionDir, `${breakpoint}${A11Y_SUFFIX}`),
+    ];
+}
+/**
+ * Belt-and-suspenders: even though prune paths are recomputed from validated
+ * names, assert the resolved path stays inside `baselinesDir` before any delete.
+ * A path that escapes (it should be impossible after name validation) aborts.
+ */
+function assertInsideBaselines(path, baselinesDir) {
+    const rel = relative(baselinesDir, path);
+    if (rel === '' || rel.startsWith('..') || rel.includes(`..${sep}`)) {
+        throw new ApproveFromError(`Refusing to prune a path outside the baselines directory: ${path}`);
+    }
+}
+/**
+ * Writes `<baselines>/manifest.json` from the candidate run's captured
+ * environment. `schemaVersion`/`captureSchema` are re-stamped from this
+ * tuffgal's constants (the single source of truth for the file format), so a
+ * candidate carrying a stale schema number is normalised on promotion.
+ */
+async function writeManifest(baselinesDir, environment) {
+    const manifest = {
+        ...environment,
+        schemaVersion: SCHEMA_VERSION,
+        captureSchema: CAPTURE_SCHEMA,
+    };
+    await writeText(join(baselinesDir, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+//# sourceMappingURL=approveFrom.js.map

package/dist/runner/approveFrom.js.map

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

package/dist/runner/breakpointPasses.d.ts

@@ -0,0 +1,39 @@
+import type { ResolvedBreakpoint, ResolvedConfig } from '../config.ts';
+import type { StoryResult } from '../schema/result.ts';
+import type { ScheduledStory } from './scheduler.ts';
+/**
+ * True when `item` renders at `breakpoint` — i.e. its resolved run set (its own
+ * `breakpoints` override, else the project default) contains a breakpoint with
+ * the same name AND dimensions.
+ */
+export declare function storyRendersAt(item: ScheduledStory, config: ResolvedConfig, breakpoint: ResolvedBreakpoint): boolean;
+/**
+ * The ordered list of breakpoint passes a run executes. Multi-breakpoint runs
+ * are driven as one pass per breakpoint — a full reset/seed then the whole
+ * schedule — so each breakpoint sees a pristine database instead of inheriting
+ * the previous breakpoint's mutations (the password a `mobile` pass changed no
+ * longer leaks into the `desktop` pass). Order follows `config.breakpoints`
+ * first so the default run keeps its configured order, then appends any extra
+ * breakpoints that only per-story overrides introduce. Deduped by name+dims.
+ */
+export declare function resolveBreakpointPasses(stories: ScheduledStory[], config: ResolvedConfig): ResolvedBreakpoint[];
+/**
+ * Re-keys a pass's stories so the scheduler only waits on prerequisites that
+ * actually run in THIS pass. A `needs` label whose producer renders at a
+ * different breakpoint than this pass would otherwise never clear and deadlock
+ * the drain; that producer instead persisted its auth state to disk in its own
+ * (earlier) pass, so the dependency is already satisfied off-disk. `produces` is
+ * left intact so failure cascades still propagate within the pass.
+ */
+export declare function adaptNeedsForPass(participating: ScheduledStory[]): ScheduledStory[];
+/**
+ * Folds one story's per-pass results back into the single `StoryResult` the
+ * report expects. Each part is the same story at one breakpoint; their actions
+ * (already tagged with their breakpoint) concatenate in pass order, the status
+ * is the worst across passes, the window spans the earliest start to the latest
+ * finish, and the first trace zip produced wins (mirroring the single-pass
+ * "first failing breakpoint" rule). A single part returns an equivalent result,
+ * so single-breakpoint runs are unchanged.
+ */
+export declare function mergeStoryResults(parts: StoryResult[]): StoryResult;
+//# sourceMappingURL=breakpointPasses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"breakpointPasses.d.ts","sourceRoot":"","sources":["../../src/runner/breakpointPasses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAYrD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAGT;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EAAE,EACzB,MAAM,EAAE,cAAc,GACrB,kBAAkB,EAAE,CActB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,cAAc,EAAE,GAC9B,cAAc,EAAE,CASlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,CA6BnE"}

package/dist/runner/breakpointPasses.js

@@ -0,0 +1,107 @@
+import { mergeStoryStatus, resolveRunSet } from "./runStory.js";
+/**
+ * A breakpoint pass is uniquely a (name, width, height) triple: two stories may
+ * both name `desktop` but override its dimensions differently, and those are
+ * genuinely separate render targets that each want their own clean database.
+ */
+function passKey(breakpoint) {
+    return `${breakpoint.name}@${breakpoint.width}x${breakpoint.height}`;
+}
+/**
+ * True when `item` renders at `breakpoint` — i.e. its resolved run set (its own
+ * `breakpoints` override, else the project default) contains a breakpoint with
+ * the same name AND dimensions.
+ */
+export function storyRendersAt(item, config, breakpoint) {
+    const key = passKey(breakpoint);
+    return resolveRunSet(item.story, config).some((bp) => passKey(bp) === key);
+}
+/**
+ * The ordered list of breakpoint passes a run executes. Multi-breakpoint runs
+ * are driven as one pass per breakpoint — a full reset/seed then the whole
+ * schedule — so each breakpoint sees a pristine database instead of inheriting
+ * the previous breakpoint's mutations (the password a `mobile` pass changed no
+ * longer leaks into the `desktop` pass). Order follows `config.breakpoints`
+ * first so the default run keeps its configured order, then appends any extra
+ * breakpoints that only per-story overrides introduce. Deduped by name+dims.
+ */
+export function resolveBreakpointPasses(stories, config) {
+    const seen = new Set();
+    const passes = [];
+    const add = (bp) => {
+        const key = passKey(bp);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        passes.push(bp);
+    };
+    for (const bp of config.breakpoints)
+        add(bp);
+    for (const item of stories) {
+        for (const bp of resolveRunSet(item.story, config))
+            add(bp);
+    }
+    return passes;
+}
+/**
+ * Re-keys a pass's stories so the scheduler only waits on prerequisites that
+ * actually run in THIS pass. A `needs` label whose producer renders at a
+ * different breakpoint than this pass would otherwise never clear and deadlock
+ * the drain; that producer instead persisted its auth state to disk in its own
+ * (earlier) pass, so the dependency is already satisfied off-disk. `produces` is
+ * left intact so failure cascades still propagate within the pass.
+ */
+export function adaptNeedsForPass(participating) {
+    const producesInPass = new Set();
+    for (const item of participating) {
+        for (const label of item.produces)
+            producesInPass.add(label);
+    }
+    return participating.map((item) => ({
+        ...item,
+        needs: item.needs.filter((label) => producesInPass.has(label)),
+    }));
+}
+/**
+ * Folds one story's per-pass results back into the single `StoryResult` the
+ * report expects. Each part is the same story at one breakpoint; their actions
+ * (already tagged with their breakpoint) concatenate in pass order, the status
+ * is the worst across passes, the window spans the earliest start to the latest
+ * finish, and the first trace zip produced wins (mirroring the single-pass
+ * "first failing breakpoint" rule). A single part returns an equivalent result,
+ * so single-breakpoint runs are unchanged.
+ */
+export function mergeStoryResults(parts) {
+    if (parts.length === 1)
+        return parts[0];
+    const first = parts[0];
+    let status = first.status;
+    let startedAt = first.startedAt;
+    let finishedAt = first.finishedAt;
+    let durationMs = 0;
+    let tracePath;
+    const actions = [];
+    for (const part of parts) {
+        status = mergeStoryStatus(status, part.status);
+        if (part.startedAt < startedAt)
+            startedAt = part.startedAt;
+        if (part.finishedAt > finishedAt)
+            finishedAt = part.finishedAt;
+        durationMs += part.durationMs;
+        if (tracePath === undefined && part.tracePath !== undefined) {
+            tracePath = part.tracePath;
+        }
+        actions.push(...part.actions);
+    }
+    return {
+        story: first.story,
+        file: first.file,
+        status,
+        startedAt,
+        finishedAt,
+        durationMs,
+        actions,
+        tracePath,
+    };
+}
+//# sourceMappingURL=breakpointPasses.js.map

package/dist/runner/breakpointPasses.js.map

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

package/dist/runner/bridges/database.d.ts

@@ -1,8 +1,9 @@
 import type { ResolvedConfig } from '../../config.ts';
 /**
- * Invokes the consumer-supplied database reset. Called once at the start of
- * a run, before any story dispatches. No-op when the consumer did not supply
- * a `database.reset` function (e.g., a static site with no backend).
+ * Invokes the consumer-supplied database reset. Called once per breakpoint
+ * pass, before that pass's stories dispatch, so each breakpoint renders against
+ * a freshly seeded database. No-op when the consumer did not supply a
+ * `database.reset` function (e.g., a static site with no backend).
  */
 export declare function resetDatabase(config: ResolvedConfig): Promise<void>;
 /**

package/dist/runner/bridges/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/runner/bridges/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CASf"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/runner/bridges/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/runner/bridges/database.js

@@ -1,7 +1,8 @@
 /**
- * Invokes the consumer-supplied database reset. Called once at the start of
- * a run, before any story dispatches. No-op when the consumer did not supply
- * a `database.reset` function (e.g., a static site with no backend).
+ * Invokes the consumer-supplied database reset. Called once per breakpoint
+ * pass, before that pass's stories dispatch, so each breakpoint renders against
+ * a freshly seeded database. No-op when the consumer did not supply a
+ * `database.reset` function (e.g., a static site with no backend).
  */
 export async function resetDatabase(config) {
     const reset = config.database?.reset;

package/dist/runner/bridges/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../src/runner/bridges/database.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAsB;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;IACT,CAAC;IACD,MAAM,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAsB,EACtB,IAAY;IAEZ,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC3C,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,2CAA2C,KAAK,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AACzB,CAAC"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../src/runner/bridges/database.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAsB;IACxD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;IACT,CAAC;IACD,MAAM,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAsB,EACtB,IAAY;IAEZ,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC3C,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,2CAA2C,KAAK,EAAE,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;AACzB,CAAC"}

package/dist/runner/exitCode.d.ts

@@ -0,0 +1,34 @@
+import type { RunMode } from './mode.ts';
+import type { RunResult } from '../schema/result.ts';
+/**
+ * The process exit code the CLI reports for a completed run. A small, pure
+ * derivation kept apart from the run driver so its precedence table is
+ * unit-testable in isolation.
+ *
+ * Precedence, highest wins:
+ *   - `1` — one or more stories failed (a step threw / the harness broke).
+ *     Always outranks every other signal: a broken run's failure is the
+ *     headline, not the visual diff it never got to compute cleanly.
+ *   - `3` — CI mode only: the committed environment manifest is present but its
+ *     pixel-affecting keys diverge from this run's capture environment (a
+ *     platform/browser/capture-mode/… drift). The comparison still ran — this
+ *     is not an abort — but the diffs are computed against baselines rendered in
+ *     a different environment, so the signal is "expect a full re-approve",
+ *     distinct from ordinary pending changes. Outranks `2`: an environment
+ *     mismatch subsumes and explains the `new`/`changed` churn it produces.
+ *   - `2` — CI mode only: pending baseline changes a human must approve —
+ *     `new` or `changed` stories, or `deleted` (orphaned committed baselines an
+ *     approve/prune should retire). This is the PR-gate signal — the run itself
+ *     succeeded, but committed baselines don't yet reflect the current UI. A
+ *     deleted-only run still gates: the baseline set has drifted from the story
+ *     set even though nothing rendered differently.
+ *   - `0` — clean: every story passed, the environment matched (or no manifest
+ *     to check), and no baselines were orphaned.
+ *
+ * Local mode never emits `2` or `3`: local runs are advisory and never read
+ * `paths.baselines` at all (no committed manifest to check, no committed set to
+ * gate against), so `new`/`changed`/`deleted`/mismatch there are informational.
+ * It keeps the "fail only on failed" behaviour (`1` or `0`).
+ */
+export declare function deriveExitCode(mode: RunMode, totals: RunResult['totals'], mismatch: boolean): 0 | 1 | 2 | 3;
+//# sourceMappingURL=exitCode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exitCode.d.ts","sourceRoot":"","sources":["../../src/runner/exitCode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,QAAQ,EAAE,OAAO,GAChB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAOf"}