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

package/dist/schema/action.d.ts

@@ -9,6 +9,7 @@ export declare const hintSchema: z.ZodObject<{
     text: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodEnum<{
         link: "link";
+        status: "status";
         alert: "alert";
         banner: "banner";
         button: "button";
@@ -29,7 +30,6 @@ export declare const hintSchema: z.ZodObject<{
         region: "region";
         row: "row";
         searchbox: "searchbox";
-        status: "status";
         switch: "switch";
         tab: "tab";
         table: "table";
@@ -59,6 +59,7 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         text: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodEnum<{
             link: "link";
+            status: "status";
             alert: "alert";
             banner: "banner";
             button: "button";
@@ -79,7 +80,6 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             region: "region";
             row: "row";
             searchbox: "searchbox";
-            status: "status";
             switch: "switch";
             tab: "tab";
             table: "table";
@@ -99,6 +99,7 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         text: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodEnum<{
             link: "link";
+            status: "status";
             alert: "alert";
             banner: "banner";
             button: "button";
@@ -119,7 +120,6 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             region: "region";
             row: "row";
             searchbox: "searchbox";
-            status: "status";
             switch: "switch";
             tab: "tab";
             table: "table";
@@ -161,6 +161,7 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         text: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodEnum<{
             link: "link";
+            status: "status";
             alert: "alert";
             banner: "banner";
             button: "button";
@@ -181,7 +182,6 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             region: "region";
             row: "row";
             searchbox: "searchbox";
-            status: "status";
             switch: "switch";
             tab: "tab";
             table: "table";
@@ -201,6 +201,7 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         text: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodEnum<{
             link: "link";
+            status: "status";
             alert: "alert";
             banner: "banner";
             button: "button";
@@ -221,7 +222,6 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             region: "region";
             row: "row";
             searchbox: "searchbox";
-            status: "status";
             switch: "switch";
             tab: "tab";
             table: "table";
@@ -261,6 +261,7 @@ export declare const actionSchema: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             role: z.ZodOptional<z.ZodEnum<{
                 link: "link";
+                status: "status";
                 alert: "alert";
                 banner: "banner";
                 button: "button";
@@ -281,7 +282,6 @@ export declare const actionSchema: z.ZodObject<{
                 region: "region";
                 row: "row";
                 searchbox: "searchbox";
-                status: "status";
                 switch: "switch";
                 tab: "tab";
                 table: "table";
@@ -301,6 +301,7 @@ export declare const actionSchema: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             role: z.ZodOptional<z.ZodEnum<{
                 link: "link";
+                status: "status";
                 alert: "alert";
                 banner: "banner";
                 button: "button";
@@ -321,7 +322,6 @@ export declare const actionSchema: z.ZodObject<{
                 region: "region";
                 row: "row";
                 searchbox: "searchbox";
-                status: "status";
                 switch: "switch";
                 tab: "tab";
                 table: "table";
@@ -363,6 +363,7 @@ export declare const actionSchema: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             role: z.ZodOptional<z.ZodEnum<{
                 link: "link";
+                status: "status";
                 alert: "alert";
                 banner: "banner";
                 button: "button";
@@ -383,7 +384,6 @@ export declare const actionSchema: z.ZodObject<{
                 region: "region";
                 row: "row";
                 searchbox: "searchbox";
-                status: "status";
                 switch: "switch";
                 tab: "tab";
                 table: "table";
@@ -403,6 +403,7 @@ export declare const actionSchema: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             role: z.ZodOptional<z.ZodEnum<{
                 link: "link";
+                status: "status";
                 alert: "alert";
                 banner: "banner";
                 button: "button";
@@ -423,7 +424,6 @@ export declare const actionSchema: z.ZodObject<{
                 region: "region";
                 row: "row";
                 searchbox: "searchbox";
-                status: "status";
                 switch: "switch";
                 tab: "tab";
                 table: "table";
@@ -449,6 +449,7 @@ export declare const actionSchema: z.ZodObject<{
         text: z.ZodOptional<z.ZodString>;
         role: z.ZodOptional<z.ZodEnum<{
             link: "link";
+            status: "status";
             alert: "alert";
             banner: "banner";
             button: "button";
@@ -469,7 +470,6 @@ export declare const actionSchema: z.ZodObject<{
             region: "region";
             row: "row";
             searchbox: "searchbox";
-            status: "status";
             switch: "switch";
             tab: "tab";
             table: "table";
@@ -488,6 +488,7 @@ export declare const actionSchema: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             role: z.ZodOptional<z.ZodEnum<{
                 link: "link";
+                status: "status";
                 alert: "alert";
                 banner: "banner";
                 button: "button";
@@ -508,7 +509,6 @@ export declare const actionSchema: z.ZodObject<{
                 region: "region";
                 row: "row";
                 searchbox: "searchbox";
-                status: "status";
                 switch: "switch";
                 tab: "tab";
                 table: "table";

package/dist/schema/result.d.ts

@@ -1,12 +1,17 @@
+import type { RunMode } from '../runner/mode.ts';
+import type { EnvironmentManifest } from '../runner/manifest.ts';
 /**
  * Outcome model. The runner emits a `RunResult` per invocation; the reporter
  * consumes it to render the HTML report. Status values map onto the three
  * outcomes the framework distinguishes:
  *
  * - `pass`  — action succeeded and screenshot matched baseline (or no baseline).
- * - `changed` — action succeeded but screenshot drifted past the threshold.
- *   The story does not fail. The user reviews and either approves the new
- *   baseline or files a bug.
+ * - `changed` — action succeeded but the baseline drifted: the screenshot moved
+ *   past the threshold, or (CI mode) pixels matched while the accessibility-tree
+ *   snapshot drifted. The story does not fail. The user reviews and either
+ *   approves the new baseline or files a bug.
+ * - `new` — no baseline existed; one was written this run. Informational, not a
+ *   regression — there is nothing to compare against yet.
  * - `failed` — a step threw. The story fails fast and skips any later actions.
  */
 export type ActionStatus = 'pass' | 'changed' | 'failed' | 'skipped' | 'new';
@@ -41,6 +46,25 @@ export interface ActionResult {
      */
     failedStepIndex?: number;
     failureMessage?: string;
+    /**
+     * Structured baseline/actual dimensions for the size-mismatch `changed` branch
+     * (a screenshot whose baseline and actual differ in size, so no pixel diff can
+     * be computed). Carried alongside `failureMessage` — which holds the same fact
+     * as prose — so the reporter can render the dimensions in an accessible split
+     * idiom (a spoken "W by H pixels" longhand) instead of string-parsing the
+     * message. Set ONLY by the size-mismatch branch of `runAction`; absent on every
+     * other result, in which case the reporter falls back to `failureMessage`.
+     */
+    sizeMismatch?: {
+        baseline: {
+            width: number;
+            height: number;
+        };
+        actual: {
+            width: number;
+            height: number;
+        };
+    };
     baselinePath?: string;
     actualPath?: string;
     diffPath?: string;
@@ -50,8 +74,21 @@ export interface ActionResult {
     ssimScore?: number;
     /**
      * `true` when the captured page accessibility tree differs from the
-     * baseline tree. Informational only — does not gate pass/changed by
-     * itself; pixel/SSIM still drives the status.
+     * baseline tree. Advisory in local mode (flagged, never gates status). In CI
+     * mode it DOES gate: when pixels pass but the aria snapshot drifts, the status
+     * becomes `changed` and a candidate pair is written, so a drifted committed
+     * `a11y.yaml` stays re-approvable under the sole-writer model.
+     *
+     * DISCRIMINATOR CONTRACT. A11y-only drift is identified POSITIVELY by
+     * `a11yChanged === true`, never by the absence of `diffPath` alone. Both
+     * pixel-drift branches (SSIM-fail and size-mismatch) carry a `diffPath` /
+     * `failureMessage` and deliberately leave `a11yChanged` unset, so the two
+     * classes never collide — but the size-mismatch branch's omission of
+     * `a11yChanged` is the load-bearing half of that guarantee and is locked by
+     * runAction's `never carries a11yChanged` test. Consumers MUST branch on
+     * `a11yChanged === true`; a `!diffPath` heuristic would misread a future
+     * result that carries neither, or a size-mismatch result if that omission
+     * ever regressed.
      */
     a11yChanged?: boolean;
     /**
@@ -63,7 +100,13 @@ export interface ActionResult {
     /** Path to the accessibility-tree snapshot captured during this run. */
     a11yActualPath?: string;
 }
-export type StoryStatus = 'pass' | 'changed' | 'failed';
+/**
+ * Story-wide rollup of its action results. Precedence (worst wins):
+ * `failed` > `changed` > `new` > `pass`. A story is `new` only when it wrote at
+ * least one fresh baseline and had no `changed`/`failed` action — so a run of
+ * first-time stories no longer masquerades as `changed`.
+ */
+export type StoryStatus = 'pass' | 'changed' | 'failed' | 'new';
 export interface StoryResult {
     story: string;
     file: string;
@@ -81,6 +124,26 @@ export interface CoverageMetric {
     ratio: number;
     missing: string[];
 }
+/**
+ * One orphaned committed baseline: an entry under `paths.baselines` whose action
+ * ran no story this run, so nothing compared against it. Recorded (CI mode,
+ * unfiltered runs only) so the report can surface it and a later `approve
+ * --prune` can delete it — this wave detects, it never removes.
+ *
+ * Keyed per breakpoint rather than per action so a partially-orphaned action
+ * (some breakpoints retired, others still live) could in principle be expressed;
+ * today an orphan action is retired wholesale, one entry per baseline file group
+ * it left behind. `breakpoint` is the mode name (`mobile`/`desktop`/…) for the
+ * breakpoint-keyed `<action>/<breakpoint>.png` layout, or `'legacy'` for the
+ * pre-breakpoint `<action>/0.png` layout. `baselinePaths` are the absolute paths
+ * the prune step deletes — the PNG plus its a11y companion when one exists — so
+ * wave 7 prunes a flat path list without re-deriving layout.
+ */
+export interface DeletedBaseline {
+    action: string;
+    breakpoint: string;
+    baselinePaths: string[];
+}
 /**
  * Parses and shape-checks a `results.json` blob. `approve` re-reads the run's
  * own output, the one JSON re-entry point that skips the zod validation every
@@ -90,16 +153,72 @@ export interface CoverageMetric {
  * `stories[].actions[]` walk, not a full structural mirror.
  */
 export declare function parseRunResult(raw: string, sourcePath: string): RunResult;
+/**
+ * The capture-environment block recorded on every run. Lets the report, the
+ * Action, and a human diagnose an environment drift between the committed
+ * baselines and the run that compared against them.
+ *
+ * - `expected` — the committed `<baselines>/manifest.json` when one exists and
+ *   parses, else `null`. `null` covers both the bootstrap case (no manifest
+ *   written yet — the first `approve --from` creates it) and local mode, which
+ *   never reads `paths.baselines` at all.
+ * - `actual` — the environment this run actually captured under.
+ * - `mismatch` — `true` when a pixel-affecting key diverged (CI mode with a
+ *   present manifest), or when the committed manifest was unreadable. Always
+ *   `false` in local mode and on the bootstrap (missing-manifest) case.
+ * - `mismatchKeys` — the specific diverging keys (see `PIXEL_AFFECTING_KEYS`),
+ *   or `['manifest']` when the committed manifest could not be parsed. Empty
+ *   when `mismatch` is `false`.
+ */
+export interface EnvironmentReport {
+    expected: EnvironmentManifest | null;
+    actual: EnvironmentManifest;
+    mismatch: boolean;
+    mismatchKeys: string[];
+}
 export interface RunResult {
     startedAt: string;
     finishedAt: string;
     durationMs: number;
+    /**
+     * Comparison contract the run executed under (`'ci' | 'local'`). Recorded so
+     * the report, the Action, and `approve --from` can distinguish a committed-
+     * baseline gate run from an advisory local self-diff. Optional in the type
+     * only as a defensive parse guard for older `results.json` artifacts that
+     * predate this field; every result the current runner emits carries it.
+     */
+    mode?: RunMode;
     totals: {
         stories: number;
         passed: number;
         changed: number;
         failed: number;
+        /** Stories whose rollup status is `new` (wrote a fresh baseline, no drift). */
+        new: number;
+        /**
+         * Orphaned committed baselines detected this run — the length of `deleted`.
+         * CI mode + unfiltered runs only; `0` in local mode and on any filtered run
+         * (where unselected stories' baselines are not orphans, merely unvisited).
+         */
+        deleted: number;
     };
+    /**
+     * Orphaned committed baselines: entries under `paths.baselines` whose action
+     * ran no story this run. Populated only for an unfiltered CI run (see
+     * {@link DeletedBaseline}); empty in local mode and on filtered runs, where a
+     * baseline going unvisited says nothing about whether its story still exists.
+     * Detection only — pruning is a later wave.
+     */
+    deleted: DeletedBaseline[];
+    /**
+     * Capture-environment provenance for this run (see {@link EnvironmentReport}).
+     * `expected` is the committed manifest (null in local mode / bootstrap),
+     * `actual` is what this run captured under, and `mismatch`/`mismatchKeys`
+     * drive the report banner and the `3` exit code. Optional in the type only as
+     * a defensive parse guard for older `results.json` artifacts that predate this
+     * block; every result the current runner emits carries it.
+     */
+    environment?: EnvironmentReport;
     /**
      * Custom coverage metrics layered on top of V8 line coverage:
      * `screens` = baselined visit-* actions / declared screens,

package/dist/schema/result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/schema/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAmBzE;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;OAIG;IACH,cAAc,EAAE;QACd,OAAO,EAAE,cAAc,CAAC;QACxB,KAAK,EAAE,cAAc,CAAC;KACvB,CAAC;IACF,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB"}
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/schema/result.ts"],"names":[],"mappings":"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"}

package/dist/schema/result.js.map

@@ -1 +1 @@
-{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/schema/result.ts"],"names":[],"mappings":"AAwFA;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,UAAkB;IAC5D,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,MAAM,IAAI,KAAK,CAAC,0BAA0B,UAAU,KAAK,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,KAAK,CAAC,OAAO,CAAE,MAAgC,CAAC,OAAO,CAAC,EACzD,CAAC;QACD,MAAM,IAAI,KAAK,CACb,2BAA2B,UAAU,+BAA+B;YAClE,0CAA0C,CAC7C,CAAC;IACJ,CAAC;IACD,OAAO,MAAmB,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/schema/result.ts"],"names":[],"mappings":"AAmJA;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,UAAkB;IAC5D,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,MAAM,IAAI,KAAK,CAAC,0BAA0B,UAAU,KAAK,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,KAAK,CAAC,OAAO,CAAE,MAAgC,CAAC,OAAO,CAAC,EACzD,CAAC;QACD,MAAM,IAAI,KAAK,CACb,2BAA2B,UAAU,+BAA+B;YAClE,0CAA0C,CAC7C,CAAC;IACJ,CAAC;IACD,OAAO,MAAmB,CAAC;AAC7B,CAAC"}

package/dist/screenshots/baselineStore.d.ts

@@ -15,9 +15,28 @@ export interface BaselinePaths {
     legacyBaseline: string;
     /** Pre-breakpoint a11y baseline (`<action>/a11y.yaml`); see `legacyBaseline`. */
     legacyA11yBaseline: string;
+    /**
+     * Proposed-new-baseline PNG for CI mode, under
+     * `<report>/candidates/<action>/<breakpoint>.png`. Mirrors the `baseline`
+     * layout exactly (action dir + breakpoint filename) so approving a candidate
+     * set is a plain tree copy into `paths.baselines`. Always report-rooted —
+     * never affected by the comparison root, which only moves the baseline side.
+     */
+    candidate: string;
+    /** Candidate a11y snapshot (`<report>/candidates/<action>/<breakpoint>.a11y.yaml`). */
+    a11yCandidate: string;
 }
 export interface StoreOptions {
     baselinesDir: string;
+    /**
+     * Root the baseline-side paths (`baseline`, `a11yBaseline`, and the two
+     * `legacy*` fallbacks) resolve under. Defaults to `baselinesDir`, so an
+     * omitted root reproduces the committed-baselines layout byte-for-byte — the
+     * zero-behaviour-change default. Local mode passes the per-machine cache dir
+     * here to self-diff against it instead. Report-side artifacts (actual, diff,
+     * candidate, a11yActual, a11yCandidate) ignore this and stay report-rooted.
+     */
+    comparisonRoot?: string;
     reportDir: string;
     storyFile: string;
     actionName: string;
@@ -29,26 +48,89 @@ export interface StoreOptions {
     breakpoint: string;
 }
 /**
- * Computes deterministic paths for the baseline (committed), actual
- * (regenerated each run), and diff (regenerated when a baseline existed and
- * the diff was non-zero) PNGs. Centralised so the runner and the CLI's
- * `approve` command agree on layout.
+ * The single owner of the `<report>/candidates/` path. The runner writes the
+ * candidate tree + a `results.json` copy here, and `approve --from` reads that
+ * same tree back. Centralised so the literal `'candidates'` segment has one
+ * definition instead of drifting across the runner, the store, and approve.
+ */
+export declare function candidatesDir(reportDir: string): string;
+/**
+ * The action-name shape the action schema enforces (`/^[a-z0-9-]+$/`,
+ * lowercase-kebab). Re-exported here so the trust boundary in `approve --from`
+ * can reject a directory name from an untrusted candidate artifact against the
+ * exact same invariant the runner produced its layout under, without importing
+ * the zod schema. Kept in lock-step with `schema/action.ts` by intent.
+ */
+export declare const ACTION_NAME_PATTERN: RegExp;
+/**
+ * The filesystem-safe breakpoint segment shape (`/^[a-z0-9_-]+$/`) that {@link
+ * breakpointSegment} emits. `approve --from` validates a candidate PNG's
+ * breakpoint stem against this so a name outside the runner's own output shape
+ * (path separators, dots, traversal) can never reach a write.
+ */
+export declare const BREAKPOINT_SEGMENT_PATTERN: RegExp;
+/**
+ * Computes deterministic paths for the baseline (the comparison target —
+ * committed baselines by default, or the local cache when `comparisonRoot` is
+ * supplied), actual (regenerated each run), diff (regenerated when a baseline
+ * existed and the diff was non-zero), and candidate (proposed-new-baseline for
+ * CI approval) PNGs. Centralised so the runner and the CLI's `approve` command
+ * agree on layout.
  *
  * Every path is keyed by both action name and breakpoint so per-breakpoint
- * captures of the same action stay isolated: baselines nest the breakpoint as a
- * filename under the action directory (`<action>/<breakpoint>.png`), while
- * report-side artifacts splice it into the filename
- * (`<action>.<breakpoint>.actual.png`) since they already share one per-story
- * directory.
+ * captures of the same action stay isolated: baseline- and candidate-side paths
+ * nest the breakpoint as a filename under the action directory
+ * (`<action>/<breakpoint>.png`), while report-side actual/diff artifacts splice
+ * it into the filename (`<action>.<breakpoint>.actual.png`) since they already
+ * share one per-story directory.
+ *
+ * The baseline side resolves under `comparisonRoot` (default `baselinesDir`), so
+ * omitting the root reproduces the committed-baselines layout unchanged; the
+ * candidate and report-side paths are always report-rooted and ignore it.
  */
 export declare function pathsFor(options: StoreOptions): BaselinePaths;
 export declare function withBaselineLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
 export declare function readBaseline(path: string): Promise<Buffer | undefined>;
 export declare function readJsonBaseline(path: string): Promise<string | undefined>;
 export declare function writeText(path: string, content: string): Promise<void>;
+/**
+ * Losslessly recompresses a PNG buffer. Playwright emits PNGs tuned for capture
+ * speed, not size; re-encoding through pngjs applies its default
+ * `deflateLevel: 9` plus adaptive per-scanline filtering (filter type chosen per
+ * row from the full `[0..4]` set), which typically shrinks the file with zero
+ * pixel change. The decode→re-encode round-trip is lossless: pngjs reads and
+ * writes 8-bit RGBA, so the recompressed buffer decodes to a byte-identical
+ * pixel array (`recompress.test.ts` asserts this).
+ *
+ * Two safety guarantees:
+ *   - Never grows a file. A source that is already densely packed (e.g. a
+ *     future oxipng-optimised baseline flowing through `approve --from`) can
+ *     re-encode *larger*; in that case the original buffer is returned unchanged.
+ *   - Never corrupts. Any decode/encode failure (a non-PNG buffer, a codec edge
+ *     case) is swallowed and the original buffer is returned, so a recompress
+ *     miss degrades to "write the bytes we were given" rather than a torn file.
+ *
+ * This is the single lossless-recompress seam for every PNG the tool writes:
+ * `writePng` routes through it, so baseline, candidate, cache, actual, and diff
+ * writes all inherit it without per-callsite wiring. Deterministic — pngjs's
+ * encoder is a pure function of the pixel data and the fixed options above.
+ *
+ * Deliberately NOT palette-quantised and never lossy: colour type and bit depth
+ * are preserved by the RGBA round-trip.
+ */
+export declare function recompressPng(png: Buffer): Buffer;
 export declare function writePng(path: string, png: Buffer): Promise<void>;
 export declare function deleteIfExists(path: string): Promise<void>;
-export declare function copyToBaseline(actualPath: string, baselinePath: string): Promise<void>;
+/**
+ * Copies an already-written PNG (the run's `actual`, or a `candidate`) to a new
+ * destination verbatim. No recompress here on purpose: the source was produced
+ * by `writePng`, which already ran `recompressPng`, so the bytes on disk are the
+ * recompressed ones. Copying them forward keeps the destination losslessly
+ * recompressed for free. The only non-test caller is `approve` refreshing the
+ * per-machine cache; `approve --from` does NOT use this — it reads each source
+ * once during validation and writes the retained buffer through {@link writePng}.
+ */
+export declare function copyRecompressedPng(actualPath: string, destinationPath: string): Promise<void>;
 /**
  * Turns an absolute screenshot path into a path that is relative to the
  * generated report directory so the HTML report can reference it with a

package/dist/screenshots/baselineStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baselineStore.d.ts","sourceRoot":"","sources":["../../src/screenshots/baselineStore.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAuC7D;AAiBD,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO5E;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER"}
+{"version":3,"file":"baselineStore.d.ts","sourceRoot":"","sources":["../../src/screenshots/baselineStore.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CA6C7D;AAiBD,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO5E;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER"}