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

package/dist/runner/exitCode.js

@@ -0,0 +1,41 @@
+/**
+ * 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 function deriveExitCode(mode, totals, mismatch) {
+    if (totals.failed > 0)
+        return 1;
+    if (mode === 'ci' && mismatch)
+        return 3;
+    if (mode === 'ci' && totals.changed + totals.new + totals.deleted > 0) {
+        return 2;
+    }
+    return 0;
+}
+//# sourceMappingURL=exitCode.js.map

package/dist/runner/exitCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exitCode.js","sourceRoot":"","sources":["../../src/runner/exitCode.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAa,EACb,MAA2B,EAC3B,QAAiB;IAEjB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,IAAI,IAAI,KAAK,IAAI,IAAI,QAAQ;QAAE,OAAO,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACtE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/runner/manifest.d.ts

@@ -0,0 +1,149 @@
+import type { ResolvedConfig } from '../config.ts';
+/**
+ * Bump when the capture pipeline changes behaviour in a way that shifts pixels
+ * for the same input UI — a new default screenshot option, a change to how the
+ * clock is frozen, a mask-application tweak, etc. A committed baseline set was
+ * rendered under one `CAPTURE_SCHEMA`; a run under a higher value is a pixel-
+ * affecting mismatch (see {@link PIXEL_AFFECTING_KEYS}) that prompts re-approve.
+ *
+ * This is deliberately separate from `schemaVersion` (the manifest *file*
+ * format): the file shape can stay stable while capture behaviour evolves, and
+ * vice versa.
+ */
+export declare const CAPTURE_SCHEMA = 1;
+/** Manifest file-format version. Bumped only when this JSON shape changes. */
+export declare const SCHEMA_VERSION = 1;
+/** One breakpoint's identity as recorded in the manifest. */
+export interface ManifestBreakpoint {
+    name: string;
+    width: number;
+    height: number;
+}
+/**
+ * The environment manifest committed beside the baselines (`<baselines>/
+ * manifest.json`). Written only by `approve --from` (a later wave) from the
+ * environment block of the candidate run's `results.json`; read by `run --ci`
+ * to detect when the current capture environment has drifted from the one the
+ * committed baselines were rendered under.
+ *
+ * `tuffgalVersion` and `playwrightVersion` are informational only — they are
+ * recorded for debugging but never contribute to a mismatch (a tuffgal patch
+ * release or a Playwright bump that does not move the bundled browser leaves
+ * pixels untouched). Every other field is pixel-affecting; see
+ * {@link PIXEL_AFFECTING_KEYS}.
+ */
+export interface EnvironmentManifest {
+    schemaVersion: number;
+    captureSchema: number;
+    /** Informational: the tuffgal release that captured the baselines. */
+    tuffgalVersion: string;
+    /** Informational: the Playwright release used. */
+    playwrightVersion: string;
+    browser: string;
+    browserVersion: string;
+    platform: string;
+    captureMode: string;
+    breakpoints: ManifestBreakpoint[];
+    deviceScaleFactor: number;
+    frozenTime: string;
+}
+/**
+ * The manifest keys whose divergence between the committed manifest and the
+ * current run shifts rendered pixels, so a difference must gate the run (exit
+ * 3) and prompt a re-approve. `schemaVersion` is excluded (it versions the file
+ * shape, not the pixels); `tuffgalVersion`/`playwrightVersion` are excluded as
+ * informational. `browser` is excluded because a browser-*name* change is
+ * already implied by `browserVersion` (which carries the vendor+version string)
+ * and the runner only launches chromium today — comparing the name would add a
+ * redundant key with no independent signal.
+ */
+export declare const PIXEL_AFFECTING_KEYS: readonly ["captureSchema", "browserVersion", "platform", "captureMode", "breakpoints", "deviceScaleFactor", "frozenTime"];
+export type PixelAffectingKey = (typeof PIXEL_AFFECTING_KEYS)[number];
+/**
+ * Result of reading `<baselines>/manifest.json`. Three outcomes the caller must
+ * distinguish, because they gate differently:
+ *   - `ok` — a well-formed manifest was read; compare it against the run.
+ *   - `missing` — no file on disk. The bootstrap case: the first `approve
+ *     --from` has not written a manifest yet, so `run --ci` treats it as "no
+ *     expectation to violate" — `environment.expected: null`, no mismatch, no
+ *     exit 3. Never gate a project that has simply not been approved once.
+ *   - `malformed` — a file exists but is not valid JSON or fails shape checks.
+ *     A committed manifest that cannot be parsed is a real problem the run
+ *     should surface, but crashing the whole comparison is too blunt. Treated
+ *     as a mismatch-with-note: `expected: null`, `mismatch: true`, and
+ *     `mismatchKeys: ['manifest']` so the report/comment can say "the committed
+ *     manifest is unreadable — re-approve to rewrite it" without aborting.
+ */
+export type ManifestReadResult = {
+    status: 'ok';
+    manifest: EnvironmentManifest;
+} | {
+    status: 'missing';
+} | {
+    status: 'malformed';
+    reason: string;
+};
+/** The sentinel `mismatchKeys` entry for an unreadable committed manifest. */
+export declare const MALFORMED_MANIFEST_KEY = "manifest";
+/** The filename of the environment manifest inside `paths.baselines`. */
+export declare const MANIFEST_FILENAME = "manifest.json";
+/**
+ * Reads and shape-checks `<baselinesDir>/manifest.json`. Tolerant by design
+ * (see {@link ManifestReadResult}): a missing file is the bootstrap case, a
+ * malformed one is surfaced as a note rather than a crash. Shape validation is
+ * intentionally shallow — enough to trust the field reads in {@link
+ * compareEnvironment}, not a full structural mirror.
+ */
+export declare function readManifest(baselinesDir: string): Promise<ManifestReadResult>;
+/**
+ * Returns a human-readable reason string when `value` is not a well-formed
+ * {@link EnvironmentManifest}, or `undefined` when it passes. Checks every key
+ * the comparison reads so a truncated or wrong-typed manifest is caught here
+ * (surfaced as `malformed`) rather than producing a garbage per-key delta.
+ *
+ * Exported so `approve --from` can run the same shape check against a candidate
+ * artifact's `environment.actual` before promoting it into the committed
+ * manifest — a well-formed-but-wrong-shaped environment block must fail closed,
+ * not slip into `manifest.json` and silently defeat the drift gate.
+ */
+export declare function validateManifestShape(value: unknown): string | undefined;
+/** Outcome of comparing the committed manifest against the current run's env. */
+export interface EnvironmentComparison {
+    mismatch: boolean;
+    mismatchKeys: string[];
+}
+/**
+ * Compares a committed manifest read result against the environment captured
+ * this run, returning which pixel-affecting keys diverged.
+ *
+ *   - `missing` — bootstrap: nothing to violate. `{ mismatch: false }`.
+ *   - `malformed` — unreadable committed manifest: mismatch-with-note,
+ *     `mismatchKeys: ['manifest']` (see {@link MALFORMED_MANIFEST_KEY}).
+ *   - `ok` — diff each {@link PIXEL_AFFECTING_KEYS}. `breakpoints` compares deep
+ *     and order-sensitively: the manifest records an ordered list, and a
+ *     reorder (even at identical dimensions) is treated as a change worth a
+ *     re-approve prompt rather than silently equal — order-sensitivity is the
+ *     conservative pixel-safety choice. Informational keys
+ *     (`tuffgalVersion`/`playwrightVersion`) are never compared.
+ */
+export declare function compareEnvironment(expected: ManifestReadResult, actual: EnvironmentManifest): EnvironmentComparison;
+/** The captured browser identity for one run. */
+export interface CapturedBrowser {
+    name: string;
+    version: string;
+}
+/**
+ * Builds the environment manifest describing THIS run — the "actual" side of
+ * the comparison and the block a later `approve --from` promotes into the
+ * committed manifest. Everything except the live browser version is derived
+ * from the resolved config and the host, so the caller only supplies the
+ * browser identity it read from the launched Playwright browser.
+ *
+ * `deviceScaleFactor` is hardcoded `1`: the runner never sets `deviceScaleFactor`
+ * on `browser.newContext` (see `runStory.ts`), so Playwright's default of `1`
+ * applies. If a future wave makes the scale factor configurable, thread it here
+ * and this constant must track it — the manifest's whole job is to notice a DSF
+ * change, so a stale hardcode here would silently defeat that.
+ */
+export declare function captureEnvironment(config: ResolvedConfig, browser: CapturedBrowser): EnvironmentManifest;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/runner/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,8EAA8E;AAC9E,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,2HAQvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAmB7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CA8CxE;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,mBAAmB,GAC1B,qBAAqB,CAqBvB;AA6CD,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,eAAe,GACvB,mBAAmB,CAkBrB"}

package/dist/runner/manifest.js

@@ -0,0 +1,229 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+/**
+ * Bump when the capture pipeline changes behaviour in a way that shifts pixels
+ * for the same input UI — a new default screenshot option, a change to how the
+ * clock is frozen, a mask-application tweak, etc. A committed baseline set was
+ * rendered under one `CAPTURE_SCHEMA`; a run under a higher value is a pixel-
+ * affecting mismatch (see {@link PIXEL_AFFECTING_KEYS}) that prompts re-approve.
+ *
+ * This is deliberately separate from `schemaVersion` (the manifest *file*
+ * format): the file shape can stay stable while capture behaviour evolves, and
+ * vice versa.
+ */
+export const CAPTURE_SCHEMA = 1;
+/** Manifest file-format version. Bumped only when this JSON shape changes. */
+export const SCHEMA_VERSION = 1;
+/**
+ * The manifest keys whose divergence between the committed manifest and the
+ * current run shifts rendered pixels, so a difference must gate the run (exit
+ * 3) and prompt a re-approve. `schemaVersion` is excluded (it versions the file
+ * shape, not the pixels); `tuffgalVersion`/`playwrightVersion` are excluded as
+ * informational. `browser` is excluded because a browser-*name* change is
+ * already implied by `browserVersion` (which carries the vendor+version string)
+ * and the runner only launches chromium today — comparing the name would add a
+ * redundant key with no independent signal.
+ */
+export const PIXEL_AFFECTING_KEYS = [
+    'captureSchema',
+    'browserVersion',
+    'platform',
+    'captureMode',
+    'breakpoints',
+    'deviceScaleFactor',
+    'frozenTime',
+];
+/** The sentinel `mismatchKeys` entry for an unreadable committed manifest. */
+export const MALFORMED_MANIFEST_KEY = 'manifest';
+/** The filename of the environment manifest inside `paths.baselines`. */
+export const MANIFEST_FILENAME = 'manifest.json';
+/**
+ * Reads and shape-checks `<baselinesDir>/manifest.json`. Tolerant by design
+ * (see {@link ManifestReadResult}): a missing file is the bootstrap case, a
+ * malformed one is surfaced as a note rather than a crash. Shape validation is
+ * intentionally shallow — enough to trust the field reads in {@link
+ * compareEnvironment}, not a full structural mirror.
+ */
+export async function readManifest(baselinesDir) {
+    let raw;
+    try {
+        raw = await readFile(join(baselinesDir, MANIFEST_FILENAME), 'utf8');
+    }
+    catch {
+        return { status: 'missing' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : 'invalid JSON';
+        return { status: 'malformed', reason };
+    }
+    const validation = validateManifestShape(parsed);
+    if (validation) {
+        return { status: 'malformed', reason: validation };
+    }
+    return { status: 'ok', manifest: parsed };
+}
+/**
+ * Returns a human-readable reason string when `value` is not a well-formed
+ * {@link EnvironmentManifest}, or `undefined` when it passes. Checks every key
+ * the comparison reads so a truncated or wrong-typed manifest is caught here
+ * (surfaced as `malformed`) rather than producing a garbage per-key delta.
+ *
+ * Exported so `approve --from` can run the same shape check against a candidate
+ * artifact's `environment.actual` before promoting it into the committed
+ * manifest — a well-formed-but-wrong-shaped environment block must fail closed,
+ * not slip into `manifest.json` and silently defeat the drift gate.
+ */
+export function validateManifestShape(value) {
+    if (typeof value !== 'object' || value === null) {
+        return 'manifest is not an object';
+    }
+    const manifest = value;
+    for (const key of [
+        'schemaVersion',
+        'captureSchema',
+        'deviceScaleFactor',
+    ]) {
+        if (typeof manifest[key] !== 'number') {
+            return `\`${key}\` must be a number`;
+        }
+    }
+    for (const key of [
+        'tuffgalVersion',
+        'playwrightVersion',
+        'browser',
+        'browserVersion',
+        'platform',
+        'captureMode',
+        'frozenTime',
+    ]) {
+        if (typeof manifest[key] !== 'string') {
+            return `\`${key}\` must be a string`;
+        }
+    }
+    if (!Array.isArray(manifest.breakpoints)) {
+        return '`breakpoints` must be an array';
+    }
+    for (const entry of manifest.breakpoints) {
+        if (typeof entry !== 'object' || entry === null) {
+            return '`breakpoints[]` must be objects';
+        }
+        const breakpoint = entry;
+        if (typeof breakpoint.name !== 'string') {
+            return '`breakpoints[].name` must be a string';
+        }
+        if (typeof breakpoint.width !== 'number' ||
+            typeof breakpoint.height !== 'number') {
+            return '`breakpoints[].width`/`height` must be numbers';
+        }
+    }
+    return undefined;
+}
+/**
+ * Compares a committed manifest read result against the environment captured
+ * this run, returning which pixel-affecting keys diverged.
+ *
+ *   - `missing` — bootstrap: nothing to violate. `{ mismatch: false }`.
+ *   - `malformed` — unreadable committed manifest: mismatch-with-note,
+ *     `mismatchKeys: ['manifest']` (see {@link MALFORMED_MANIFEST_KEY}).
+ *   - `ok` — diff each {@link PIXEL_AFFECTING_KEYS}. `breakpoints` compares deep
+ *     and order-sensitively: the manifest records an ordered list, and a
+ *     reorder (even at identical dimensions) is treated as a change worth a
+ *     re-approve prompt rather than silently equal — order-sensitivity is the
+ *     conservative pixel-safety choice. Informational keys
+ *     (`tuffgalVersion`/`playwrightVersion`) are never compared.
+ */
+export function compareEnvironment(expected, actual) {
+    if (expected.status === 'missing') {
+        return { mismatch: false, mismatchKeys: [] };
+    }
+    if (expected.status === 'malformed') {
+        return { mismatch: true, mismatchKeys: [MALFORMED_MANIFEST_KEY] };
+    }
+    const manifest = expected.manifest;
+    const mismatchKeys = [];
+    for (const key of PIXEL_AFFECTING_KEYS) {
+        if (key === 'breakpoints') {
+            if (!breakpointsEqual(manifest.breakpoints, actual.breakpoints)) {
+                mismatchKeys.push(key);
+            }
+            continue;
+        }
+        if (manifest[key] !== actual[key]) {
+            mismatchKeys.push(key);
+        }
+    }
+    return { mismatch: mismatchKeys.length > 0, mismatchKeys };
+}
+/**
+ * Deep, order-sensitive equality of two breakpoint lists: same length, and each
+ * position matches on `name`/`width`/`height`. Order-sensitive on purpose — see
+ * {@link compareEnvironment}.
+ */
+function breakpointsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((entry, index) => {
+        const other = b[index];
+        return (other !== undefined &&
+            entry.name === other.name &&
+            entry.width === other.width &&
+            entry.height === other.height);
+    });
+}
+const requirePackage = createRequire(import.meta.url);
+/**
+ * Reads tuffgal's own version from its `package.json`. Resolved relative to this
+ * module so it works from both `src/` (dev/test) and the built `dist/` tree —
+ * `../../package.json` is the package root in both layouts. Informational only.
+ */
+function readTuffgalVersion() {
+    const pkg = requirePackage('../../package.json');
+    return pkg.version;
+}
+/**
+ * Reads the installed Playwright version from its `package.json` via module
+ * resolution (not a hardcoded string), so a dependency bump is reflected
+ * automatically. Informational only.
+ */
+function readPlaywrightVersion() {
+    const pkg = requirePackage('playwright/package.json');
+    return pkg.version;
+}
+/**
+ * Builds the environment manifest describing THIS run — the "actual" side of
+ * the comparison and the block a later `approve --from` promotes into the
+ * committed manifest. Everything except the live browser version is derived
+ * from the resolved config and the host, so the caller only supplies the
+ * browser identity it read from the launched Playwright browser.
+ *
+ * `deviceScaleFactor` is hardcoded `1`: the runner never sets `deviceScaleFactor`
+ * on `browser.newContext` (see `runStory.ts`), so Playwright's default of `1`
+ * applies. If a future wave makes the scale factor configurable, thread it here
+ * and this constant must track it — the manifest's whole job is to notice a DSF
+ * change, so a stale hardcode here would silently defeat that.
+ */
+export function captureEnvironment(config, browser) {
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        captureSchema: CAPTURE_SCHEMA,
+        tuffgalVersion: readTuffgalVersion(),
+        playwrightVersion: readPlaywrightVersion(),
+        browser: browser.name,
+        browserVersion: browser.version,
+        platform: process.platform,
+        captureMode: config.captureMode,
+        breakpoints: config.breakpoints.map((breakpoint) => ({
+            name: breakpoint.name,
+            width: breakpoint.width,
+            height: breakpoint.height,
+        })),
+        deviceScaleFactor: 1,
+        frozenTime: config.frozenTime,
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/runner/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/runner/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAsChC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,eAAe;IACf,gBAAgB;IAChB,UAAU;IACV,aAAa;IACb,aAAa;IACb,mBAAmB;IACnB,YAAY;CACJ,CAAC;AAwBX,8EAA8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,UAAU,CAAC;AAEjD,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,YAAoB;IAEpB,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC;QACvE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAA6B,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,MAAM,QAAQ,GAAG,KAAgC,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI;QAChB,eAAe;QACf,eAAe;QACf,mBAAmB;KACX,EAAE,CAAC;QACX,IAAI,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YACtC,OAAO,KAAK,GAAG,qBAAqB,CAAC;QACvC,CAAC;IACH,CAAC;IACD,KAAK,MAAM,GAAG,IAAI;QAChB,gBAAgB;QAChB,mBAAmB;QACnB,SAAS;QACT,gBAAgB;QAChB,UAAU;QACV,aAAa;QACb,YAAY;KACJ,EAAE,CAAC;QACX,IAAI,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YACtC,OAAO,KAAK,GAAG,qBAAqB,CAAC;QACvC,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACzC,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,OAAO,iCAAiC,CAAC;QAC3C,CAAC;QACD,MAAM,UAAU,GAAG,KAAgC,CAAC;QACpD,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxC,OAAO,uCAAuC,CAAC;QACjD,CAAC;QACD,IACE,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ;YACpC,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ,EACrC,CAAC;YACD,OAAO,gDAAgD,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAQD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA4B,EAC5B,MAA2B;IAE3B,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,sBAAsB,CAAC,EAAE,CAAC;IACpE,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACnC,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACvC,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YAC1B,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;gBAChE,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,CAAuB,EACvB,CAAuB;IAEvB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,CACL,KAAK,KAAK,SAAS;YACnB,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;YACzB,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;YAC3B,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAC9B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEtD;;;;GAIG;AACH,SAAS,kBAAkB;IACzB,MAAM,GAAG,GAAG,cAAc,CAAC,oBAAoB,CAAwB,CAAC;IACxE,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB;IAC5B,MAAM,GAAG,GAAG,cAAc,CAAC,yBAAyB,CAAwB,CAAC;IAC7E,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAQD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAsB,EACtB,OAAwB;IAExB,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,aAAa,EAAE,cAAc;QAC7B,cAAc,EAAE,kBAAkB,EAAE;QACpC,iBAAiB,EAAE,qBAAqB,EAAE;QAC1C,OAAO,EAAE,OAAO,CAAC,IAAI;QACrB,cAAc,EAAE,OAAO,CAAC,OAAO;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YACnD,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,iBAAiB,EAAE,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC;AACJ,CAAC"}

package/dist/runner/mode.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedConfig } from '../config.ts';
+/**
+ * Which comparison contract a `tuffgal run` executes under. Foundation for the
+ * CI-owned-baselines model: `ci` compares actuals against the committed
+ * `paths.baselines` set (the source of truth, written only via approval flows),
+ * while `local` compares against a per-machine gitignored cache for advisory
+ * self-diffing. This wave only resolves + threads the mode; downstream branching
+ * on it arrives in later waves.
+ */
+export type RunMode = 'ci' | 'local';
+export interface RunModeInputs {
+    /** `--ci` flag was passed. */
+    ci: boolean;
+    /** `--local` flag was passed. */
+    local: boolean;
+    /**
+     * Environment to read the `CI` default from. Injected (rather than reading
+     * `process.env` directly) so the resolution matrix is unit-testable without
+     * mutating global process state.
+     */
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Resolves the run mode from the two mutually-exclusive flags and the `CI`
+ * environment variable:
+ *   - `--ci` and `--local` are mutually exclusive; passing both throws.
+ *   - An explicit flag always wins over the environment.
+ *   - With no flag, default to `ci` when `CI` is truthy (non-empty and not an
+ *     explicit negation — see {@link FALSY_CI}), else `local`.
+ */
+export declare function resolveRunMode(inputs: RunModeInputs): RunMode;
+/**
+ * The baseline root a run compares against for the given mode: the committed
+ * `paths.baselines` set in CI mode, the per-machine gitignored `paths.localCache`
+ * in local mode. This is the single source of the mode→root mapping — both the
+ * per-action comparison in `runAction` and the screen-coverage metric in `run`
+ * select their root through here, so the two can never drift. Encodes the PRD
+ * invariant that a local run never reads `paths.baselines`.
+ */
+export declare function comparisonRootFor(config: ResolvedConfig, mode: RunMode): string;
+//# sourceMappingURL=mode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/runner/mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAErC,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAYD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAW7D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,OAAO,GACZ,MAAM,CAER"}

package/dist/runner/mode.js

@@ -0,0 +1,43 @@
+/**
+ * Strings a CI system might export to explicitly opt OUT of CI behaviour. Most
+ * CI providers (GitHub Actions, Travis, CircleCI, GitLab, …) set `CI=true`, but
+ * the de-facto convention — as codified by the widely-used `ci-info`/`is-ci`
+ * packages — is that any non-empty `CI` value counts as "in CI" unless it is one
+ * of these explicit negations. We mirror that so a developer who exports
+ * `CI=false` locally still gets local mode.
+ */
+const FALSY_CI = new Set(['', '0', 'false']);
+/**
+ * Resolves the run mode from the two mutually-exclusive flags and the `CI`
+ * environment variable:
+ *   - `--ci` and `--local` are mutually exclusive; passing both throws.
+ *   - An explicit flag always wins over the environment.
+ *   - With no flag, default to `ci` when `CI` is truthy (non-empty and not an
+ *     explicit negation — see {@link FALSY_CI}), else `local`.
+ */
+export function resolveRunMode(inputs) {
+    if (inputs.ci && inputs.local) {
+        throw new Error('Cannot pass both --ci and --local; choose one.');
+    }
+    if (inputs.ci)
+        return 'ci';
+    if (inputs.local)
+        return 'local';
+    const raw = inputs.env.CI;
+    if (raw !== undefined && !FALSY_CI.has(raw.toLowerCase())) {
+        return 'ci';
+    }
+    return 'local';
+}
+/**
+ * The baseline root a run compares against for the given mode: the committed
+ * `paths.baselines` set in CI mode, the per-machine gitignored `paths.localCache`
+ * in local mode. This is the single source of the mode→root mapping — both the
+ * per-action comparison in `runAction` and the screen-coverage metric in `run`
+ * select their root through here, so the two can never drift. Encodes the PRD
+ * invariant that a local run never reads `paths.baselines`.
+ */
+export function comparisonRootFor(config, mode) {
+    return mode === 'ci' ? config.paths.baselines : config.paths.localCache;
+}
+//# sourceMappingURL=mode.js.map

package/dist/runner/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/runner/mode.ts"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1B,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAsB,EACtB,IAAa;IAEb,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;AAC1E,CAAC"}

package/dist/runner/orphanScan.d.ts

@@ -0,0 +1,68 @@
+import type { RunMode } from './mode.ts';
+import type { DeletedBaseline, RunResult } from '../schema/result.ts';
+/**
+ * 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 declare 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 declare const LEGACY_PNG = "0.png";
+export declare const LEGACY_A11Y = "a11y.yaml";
+export declare const LEGACY_BREAKPOINT = "legacy";
+/**
+ * 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 declare function shouldScanForOrphans(mode: RunMode, storyFilter: string | undefined): boolean;
+/**
+ * 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 declare function executedActionNames(stories: RunResult['stories']): Set<string>;
+/**
+ * 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 declare function scanOrphanedBaselines(baselinesDir: string, executed: Set<string>): Promise<DeletedBaseline[]>;
+//# sourceMappingURL=orphanScan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orphanScan.d.ts","sourceRoot":"","sources":["../../src/runner/orphanScan.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,UAAU,CAAC;AAClC,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAW1C;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,GAC5B,GAAG,CAAC,MAAM,CAAC,CAQb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAuB5B"}