tuffgal 0.2.0-alpha.2 → 0.2.0-alpha.4

package/dist/screenshots/baselineStore.d.ts

@@ -8,7 +8,7 @@ export interface BaselinePaths {
      * Pre-breakpoint baseline location (`<action>/0.png`). Populated so a caller
      * that finds no breakpoint-keyed baseline can fall back to a project's
      * legacy committed baseline instead of declaring every action `new`. Read
-     * fallback only — the runner reads `baseline` first, then `legacyBaseline`;
+     * fallback only. The runner reads `baseline` first, then `legacyBaseline`;
      * promotion always writes the breakpoint-keyed `baseline`, never this. See
      * the read-order note below.
      */
@@ -19,7 +19,7 @@ export interface BaselinePaths {
      * 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 —
+     * 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;
@@ -31,7 +31,7 @@ export interface StoreOptions {
     /**
      * 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
+     * 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.
@@ -70,7 +70,7 @@ export declare const ACTION_NAME_PATTERN: RegExp;
  */
 export declare const BREAKPOINT_SEGMENT_PATTERN: RegExp;
 /**
- * Computes deterministic paths for the baseline (the comparison target —
+ * 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
@@ -110,31 +110,54 @@ export declare function writeText(path: string, content: string): Promise<void>;
  *     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.
+ * This is the lossless-recompress seam for the tool's DURABLE PNG writes:
+ * {@link writeDurablePng} routes through it, so baseline, candidate, cache, and
+ * promoted-baseline writes inherit it without per-callsite wiring. Transient
+ * report artifacts (`actual`, `diff`) deliberately skip it via
+ * {@link writeTransientPng}. The max-effort encode is wasted on a file that is
+ * overwritten or deleted next run. 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>;
+/**
+ * Writes a DURABLE PNG (a baseline, a candidate, or a promoted baseline) that
+ * outlives the run and is re-read on every later comparison. These earn the
+ * max-effort lossless recompress (see {@link recompressPng}): the level-9
+ * deflate + adaptive per-scanline filtering is paid once at write, and every
+ * subsequent read of the smaller file benefits.
+ *
+ * Transient report artifacts (the run's `actual`, the `diff` overlay) are
+ * overwritten or deleted next run and must NOT pay this cost. They route
+ * through {@link writeTransientPng}, which skips recompress entirely.
+ */
+export declare function writeDurablePng(path: string, png: Buffer): Promise<void>;
+/**
+ * Writes a TRANSIENT PNG (the run's `actual` capture or the `diff` overlay)
+ * verbatim, with NO recompress pass. These artifacts live only for the current
+ * report: an `actual` is overwritten on the next run and a `diff` is deleted the
+ * moment a comparison passes, so shrinking them with the expensive level-9
+ * encode is wasted work. The `diff` overlay in particular arrives already
+ * deflate-encoded by {@link renderDiffOverlay}'s `PNG.sync.write`, so a
+ * recompress round-trip would only decode and re-encode it back to
+ * near-identical bytes.
+ *
+ * Durable artifacts (baselines, candidates, promoted baselines) DO earn the
+ * recompress and use {@link writeDurablePng}.
+ */
+export declare function writeTransientPng(path: string, png: Buffer): Promise<void>;
 export declare function deleteIfExists(path: 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}.
+ * destination verbatim. No recompress here on purpose: the source is a durable
+ * baseline produced by {@link writeDurablePng}, 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 writeDurablePng}.
  */
 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
- * portable `src` attribute.
- */
-export declare function pathRelativeToReport(reportDir: string, absolute: string): string;
 //# sourceMappingURL=baselineStore.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWjD;AAYD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/screenshots/baselineStore.js

@@ -1,5 +1,5 @@
 import { access, copyFile, mkdir, readFile, rm, writeFile, } from 'node:fs/promises';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join } from 'node:path';
 import { PNG } from 'pngjs';
 /**
  * Reduces an arbitrary breakpoint name to a filesystem-safe path segment.
@@ -37,7 +37,7 @@ export const ACTION_NAME_PATTERN = /^[a-z0-9-]+$/;
  */
 export const BREAKPOINT_SEGMENT_PATTERN = /^[a-z0-9_-]+$/;
 /**
- * Computes deterministic paths for the baseline (the comparison target —
+ * 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
@@ -80,15 +80,15 @@ export function pathsFor(options) {
 }
 /**
  * Per-path serialization for baseline creation. A baseline is keyed on action
- * name *and* breakpoint (see `pathsFor` — the breakpoint is part of the
+ * name *and* breakpoint (see `pathsFor`, the breakpoint is part of the
  * filename), so when the same action+breakpoint runs in two stories
  * concurrently (`workers > 1`, fresh run), both would otherwise read "no
- * baseline" and race to write the same `<breakpoint>.png` — a torn or
+ * baseline" and race to write the same `<breakpoint>.png`, a torn or
  * last-writer-wins file. Callers wrap their read-then-maybe-write critical
  * section in this lock so exactly one writer per baseline path runs at a time;
  * later callers see the baseline the first writer produced. The map is keyed by
- * path, so distinct actions — and now distinct breakpoints of the same action,
- * whose baseline paths differ — never block each other; entries are bounded by
+ * path, so distinct actions (and now distinct breakpoints of the same action,
+ * whose baseline paths differ) never block each other; entries are bounded by
  * action count times breakpoint count.
  */
 const baselineLocks = new Map();
@@ -140,10 +140,13 @@ export async function writeText(path, content) {
  *     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.
+ * This is the lossless-recompress seam for the tool's DURABLE PNG writes:
+ * {@link writeDurablePng} routes through it, so baseline, candidate, cache, and
+ * promoted-baseline writes inherit it without per-callsite wiring. Transient
+ * report artifacts (`actual`, `diff`) deliberately skip it via
+ * {@link writeTransientPng}. The max-effort encode is wasted on a file that is
+ * overwritten or deleted next run. 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.
@@ -154,16 +157,51 @@ export function recompressPng(png) {
         recompressed = PNG.sync.write(PNG.sync.read(png));
     }
     catch {
-        // Not a decodable PNG, or an encoder edge case — write what we were given
+        // Not a decodable PNG, or an encoder edge case. Write what we were given
         // rather than risk emitting a corrupt or truncated file.
         return png;
     }
-    // A recompress that grows the file is a loss, not a win — keep the smaller.
+    // A recompress that grows the file is a loss, not a win. Keep the smaller.
     return recompressed.length < png.length ? recompressed : png;
 }
-export async function writePng(path, png) {
+/**
+ * Shared write core: ensure the parent directory exists, then write the bytes
+ * verbatim. The durable/transient split lives one level up. This only handles
+ * the mkdir + write both share.
+ */
+async function writePngBytes(path, bytes) {
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, recompressPng(png));
+    await writeFile(path, bytes);
+}
+/**
+ * Writes a DURABLE PNG (a baseline, a candidate, or a promoted baseline) that
+ * outlives the run and is re-read on every later comparison. These earn the
+ * max-effort lossless recompress (see {@link recompressPng}): the level-9
+ * deflate + adaptive per-scanline filtering is paid once at write, and every
+ * subsequent read of the smaller file benefits.
+ *
+ * Transient report artifacts (the run's `actual`, the `diff` overlay) are
+ * overwritten or deleted next run and must NOT pay this cost. They route
+ * through {@link writeTransientPng}, which skips recompress entirely.
+ */
+export async function writeDurablePng(path, png) {
+    await writePngBytes(path, recompressPng(png));
+}
+/**
+ * Writes a TRANSIENT PNG (the run's `actual` capture or the `diff` overlay)
+ * verbatim, with NO recompress pass. These artifacts live only for the current
+ * report: an `actual` is overwritten on the next run and a `diff` is deleted the
+ * moment a comparison passes, so shrinking them with the expensive level-9
+ * encode is wasted work. The `diff` overlay in particular arrives already
+ * deflate-encoded by {@link renderDiffOverlay}'s `PNG.sync.write`, so a
+ * recompress round-trip would only decode and re-encode it back to
+ * near-identical bytes.
+ *
+ * Durable artifacts (baselines, candidates, promoted baselines) DO earn the
+ * recompress and use {@link writeDurablePng}.
+ */
+export async function writeTransientPng(path, png) {
+    await writePngBytes(path, png);
 }
 export async function deleteIfExists(path) {
     try {
@@ -175,23 +213,16 @@ export async function deleteIfExists(path) {
 }
 /**
  * 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}.
+ * destination verbatim. No recompress here on purpose: the source is a durable
+ * baseline produced by {@link writeDurablePng}, 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 writeDurablePng}.
  */
 export async function copyRecompressedPng(actualPath, destinationPath) {
     await mkdir(dirname(destinationPath), { recursive: true });
     await copyFile(actualPath, destinationPath);
 }
-/**
- * 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
- * portable `src` attribute.
- */
-export function pathRelativeToReport(reportDir, absolute) {
-    return relative(reportDir, absolute);
-}
 //# sourceMappingURL=baselineStore.js.map

package/dist/screenshots/baselineStore.js.map

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

package/dist/screenshots/capture.d.ts

@@ -1,14 +1,45 @@
 import type { Locator, Page } from 'playwright';
 import type { CaptureMode } from '../config.ts';
+/**
+ * Safety bound for a `fullPage` capture. `maxPixels` caps the composited image's
+ * total area (width × height); `label` identifies the capture in the error the
+ * guard throws so the operator knows exactly which story/action to fix.
+ */
+export interface FullPageGuard {
+    maxPixels: number;
+    label: string;
+}
+/**
+ * Thrown when a `fullPage` capture's measured layout area exceeds its
+ * {@link FullPageGuard} cap. Carries the offending dimensions and the cap so
+ * callers (and the message) can report precisely. Failing here is deliberate:
+ * compositing and decoding a runaway-tall page to an RGBA array risks exhausting
+ * memory, so a loud, actionable error beats an OOM crash.
+ */
+export declare class FullPageTooLargeError extends Error {
+    readonly width: number;
+    readonly height: number;
+    readonly maxPixels: number;
+    constructor(label: string, dimensions: {
+        width: number;
+        height: number;
+    }, maxPixels: number);
+}
 /**
  * Screenshot with animations disabled, caret hidden, and any masks applied so
  * the same UI renders to bit-identical pixels across runs. Masks are Playwright
- * locators whose bounding boxes are blacked out before the image is encoded —
- * use them to neutralise randomised or time-based regions.
+ * locators whose bounding boxes are blacked out before the image is encoded.
+ * Use them to neutralise randomised or time-based regions.
  *
  * `mode` controls scope: `viewport` (default) captures only the page's current
- * viewport box — what the user sees above the fold — while `fullPage`
+ * viewport box (what the user sees above the fold) while `fullPage`
  * composites the entire scrollable document however tall.
+ *
+ * `fullPageGuard`, when supplied, bounds a `fullPage` capture's area: the page's
+ * measured layout dimensions are checked against the cap before the shutter
+ * fires, and an over-cap page throws {@link FullPageTooLargeError} rather than
+ * compositing an array large enough to risk an OOM. It is ignored for `viewport`
+ * captures (already bounded by the breakpoint) and when omitted.
  */
-export declare function capturePage(page: Page, masks?: Locator[], mode?: CaptureMode): Promise<Buffer>;
+export declare function capturePage(page: Page, masks?: Locator[], mode?: CaptureMode, fullPageGuard?: FullPageGuard): Promise<Buffer>;
 //# sourceMappingURL=capture.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/screenshots/capture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,OAAO,EAAO,EACrB,IAAI,GAAE,WAAwB,GAC7B,OAAO,CAAC,MAAM,CAAC,CA8BjB"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/screenshots/capture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEzB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC7C,SAAS,EAAE,MAAM;CAkBpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,OAAO,EAAO,EACrB,IAAI,GAAE,WAAwB,EAC9B,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,MAAM,CAAC,CAuDjB"}

package/dist/screenshots/capture.js

@@ -1,18 +1,51 @@
+/**
+ * Thrown when a `fullPage` capture's measured layout area exceeds its
+ * {@link FullPageGuard} cap. Carries the offending dimensions and the cap so
+ * callers (and the message) can report precisely. Failing here is deliberate:
+ * compositing and decoding a runaway-tall page to an RGBA array risks exhausting
+ * memory, so a loud, actionable error beats an OOM crash.
+ */
+export class FullPageTooLargeError extends Error {
+    width;
+    height;
+    maxPixels;
+    constructor(label, dimensions, maxPixels) {
+        const area = dimensions.width * dimensions.height;
+        super(`Full-page screenshot for ${label} would composite a ` +
+            `${dimensions.width}x${dimensions.height} image ` +
+            `(${area.toLocaleString('en-US')} pixels), exceeding the ` +
+            `${maxPixels.toLocaleString('en-US')}-pixel safety cap. A page this ` +
+            `tall decodes to a huge RGBA array and risks exhausting memory. Bound ` +
+            `the page height (e.g. cap infinite-scroll content), switch this story ` +
+            `to captureMode 'viewport', or raise maxFullPagePixels in your tuffgal ` +
+            `config.`);
+        this.name = 'FullPageTooLargeError';
+        this.width = dimensions.width;
+        this.height = dimensions.height;
+        this.maxPixels = maxPixels;
+    }
+}
 /**
  * Screenshot with animations disabled, caret hidden, and any masks applied so
  * the same UI renders to bit-identical pixels across runs. Masks are Playwright
- * locators whose bounding boxes are blacked out before the image is encoded —
- * use them to neutralise randomised or time-based regions.
+ * locators whose bounding boxes are blacked out before the image is encoded.
+ * Use them to neutralise randomised or time-based regions.
  *
  * `mode` controls scope: `viewport` (default) captures only the page's current
- * viewport box — what the user sees above the fold — while `fullPage`
+ * viewport box (what the user sees above the fold) while `fullPage`
  * composites the entire scrollable document however tall.
+ *
+ * `fullPageGuard`, when supplied, bounds a `fullPage` capture's area: the page's
+ * measured layout dimensions are checked against the cap before the shutter
+ * fires, and an over-cap page throws {@link FullPageTooLargeError} rather than
+ * compositing an array large enough to risk an OOM. It is ignored for `viewport`
+ * captures (already bounded by the breakpoint) and when omitted.
  */
-export async function capturePage(page, masks = [], mode = 'viewport') {
+export async function capturePage(page, masks = [], mode = 'viewport', fullPageGuard) {
     // `fullPage` composites the whole scrollable document into one image. When
     // the document is captured at a non-zero offset, `position: sticky` / `fixed`
     // chrome (sidebars, headers) resolves against that scroll position and lands
-    // shifted down by `scrollY` in the stitch — the same UI produces a different
+    // shifted down by `scrollY` in the stitch. The same UI produces a different
     // image purely because an earlier step left the viewport scrolled. Resetting
     // to the origin first pins those elements to their static-baseline position
     // so the capture is deterministic. `instant` defeats any `scroll-behavior:
@@ -20,15 +53,34 @@ export async function capturePage(page, masks = [], mode = 'viewport') {
     // timing race.
     //
     // A `viewport` shot captures exactly the box the flow scrolled to, so it must
-    // NOT reset — a story that scrolls to a below-the-fold section (a Settings
+    // NOT reset. A story that scrolls to a below-the-fold section (a Settings
     // panel, a success banner) would otherwise capture the top of the page
     // instead of the region it navigated to. The flow lands at a deterministic
     // offset, so the viewport shot is deterministic without any reset.
     //
-    // String form so the snippet runs in the page (DOM) context without pulling
-    // the DOM lib into this Node-side module's type environment.
+    // The same page-context call that resets scroll also returns the document's
+    // layout dimensions, so the guard measures the true (unclipped) full-page size
+    // (Chromium may clip the actual screenshot, but the layout height reflects the
+    // real pathology) in one round-trip, with no extra evaluate. String form so
+    // the snippet runs in the page (DOM) context without pulling the DOM lib into
+    // this Node-side module's type environment.
     if (mode === 'fullPage') {
-        await page.evaluate(`window.scrollTo({ top: 0, left: 0, behavior: 'instant' })`);
+        const dimensions = (await page.evaluate(`(() => {
+        window.scrollTo({ top: 0, left: 0, behavior: 'instant' });
+        const el = document.documentElement;
+        const body = document.body;
+        return {
+          width: Math.max(el.scrollWidth, el.clientWidth, body ? body.scrollWidth : 0),
+          height: Math.max(el.scrollHeight, el.clientHeight, body ? body.scrollHeight : 0),
+        };
+      })()`));
+        // Guard only when a cap is supplied. The measurement above always runs (it
+        // is also the scroll reset), but an unbounded caller (e.g. a test) simply
+        // ignores the returned dimensions.
+        if (fullPageGuard &&
+            dimensions.width * dimensions.height > fullPageGuard.maxPixels) {
+            throw new FullPageTooLargeError(fullPageGuard.label, dimensions, fullPageGuard.maxPixels);
+        }
     }
     return page.screenshot({
         fullPage: mode === 'fullPage',

package/dist/screenshots/capture.js.map

@@ -1 +1 @@
-{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/screenshots/capture.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAU,EACV,QAAmB,EAAE,EACrB,OAAoB,UAAU;IAE9B,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,eAAe;IACf,EAAE;IACF,8EAA8E;IAC9E,2EAA2E;IAC3E,uEAAuE;IACvE,2EAA2E;IAC3E,mEAAmE;IACnE,EAAE;IACF,4EAA4E;IAC5E,6DAA6D;IAC7D,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,QAAQ,CACjB,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,UAAU,CAAC;QACrB,QAAQ,EAAE,IAAI,KAAK,UAAU;QAC7B,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,MAAM;QACb,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/screenshots/capture.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,KAAK,CAAS;IACd,MAAM,CAAS;IACf,SAAS,CAAS;IAC3B,YACE,KAAa,EACb,UAA6C,EAC7C,SAAiB;QAEjB,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC;QAClD,KAAK,CACH,4BAA4B,KAAK,qBAAqB;YACpD,GAAG,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,MAAM,SAAS;YACjD,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,0BAA0B;YAC1D,GAAG,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,iCAAiC;YACrE,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,SAAS,CACZ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAU,EACV,QAAmB,EAAE,EACrB,OAAoB,UAAU,EAC9B,aAA6B;IAE7B,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,eAAe;IACf,EAAE;IACF,8EAA8E;IAC9E,0EAA0E;IAC1E,uEAAuE;IACvE,2EAA2E;IAC3E,mEAAmE;IACnE,EAAE;IACF,4EAA4E;IAC5E,+EAA+E;IAC/E,+EAA+E;IAC/E,4EAA4E;IAC5E,8EAA8E;IAC9E,4CAA4C;IAC5C,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,QAAQ,CACrC;;;;;;;;WAQK,CACN,CAAsC,CAAC;QACxC,2EAA2E;QAC3E,0EAA0E;QAC1E,mCAAmC;QACnC,IACE,aAAa;YACb,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,aAAa,CAAC,SAAS,EAC9D,CAAC;YACD,MAAM,IAAI,qBAAqB,CAC7B,aAAa,CAAC,KAAK,EACnB,UAAU,EACV,aAAa,CAAC,SAAS,CACxB,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,UAAU,CAAC;QACrB,QAAQ,EAAE,IAAI,KAAK,UAAU;QAC7B,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,MAAM;QACb,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;AACL,CAAC"}

package/dist/screenshots/diff.d.ts

@@ -1,5 +1,5 @@
-export interface DiffOutcome {
-    diffPng: Buffer;
+import { PNG } from 'pngjs';
+export interface DiffScore {
     diffPixels: number;
     totalPixels: number;
     diffRatio: number;
@@ -13,14 +13,63 @@ export interface DiffOutcome {
     ssimScore: number;
 }
 /**
- * Compares two PNG buffers. Computes SSIM (the perceptual gate) and a
- * pixelmatch overlay (the visualisation). Both are returned so the
- * runner can use SSIM for pass/changed decisions while the reporter
- * still has a red-highlight diff image to show the human.
+ * The decoded PNG pair, carried out of {@link scoreDiff} so the changed branch
+ * can render its overlay from the SAME decode rather than reading the two
+ * buffers a second time. Both PNGs are validated (matching dimensions, packed
+ * RGBA) by {@link decodePair} before they reach here.
+ */
+export interface DecodedPair {
+    baselinePng: PNG;
+    actualPng: PNG;
+}
+/** {@link scoreDiff}'s result: the reported metrics plus the decode to reuse. */
+export interface ScoredDiff {
+    score: DiffScore;
+    /**
+     * The decoded pair {@link scoreDiff} already produced. On the changed branch
+     * the caller threads this straight into {@link renderDiffOverlay}, so the
+     * failing comparison decodes the image pair exactly once instead of twice.
+     */
+    decoded: DecodedPair;
+}
+/**
+ * Diffing is split into two phases so the common case stays cheap:
+ *
+ *   1. {@link scoreDiff}: the gate. Computes SSIM (the pass/changed
+ *      decision) plus the pixel metrics reported on every outcome
+ *      (`diffPixels`, `diffRatio`). It runs pixelmatch in count-only mode
+ *      (no output buffer) and never encodes a diff image. It also returns the
+ *      {@link DecodedPair} it read, so the changed branch can render its
+ *      overlay without a second decode.
+ *   2. {@link renderDiffOverlay}: the visualisation. Takes that same decoded
+ *      pair, runs pixelmatch with an output buffer, and deflate-encodes the
+ *      red-highlight overlay PNG for the human-facing report.
+ *
+ * The overlay is only kept when a comparison FAILS; a passing comparison
+ * deletes it. Because passing is the common case in a healthy suite,
+ * encoding the overlay on every comparison was pure waste, so the caller
+ * runs {@link scoreDiff} unconditionally and reaches for
+ * {@link renderDiffOverlay} only on the changed branch, where the image is
+ * actually written. The decode is shared across both, so the changed branch
+ * pays for exactly one `PNG.sync.read` pair; the pass branch keeps its
+ * no-allocate, no-encode shape (the overlay is never filled on a pass).
+ */
+export declare function scoreDiff(baseline: Buffer, actual: Buffer, pixelThreshold: number): ScoredDiff;
+/**
+ * Renders the red-highlight overlay PNG for the report from the already-decoded
+ * pair {@link scoreDiff} produced. This is the expensive half (pixelmatch
+ * fills an output buffer and `PNG.sync.write` deflate-encodes it) so it runs
+ * only on the changed/failed branch where the diff image is actually written to
+ * disk.
  *
- * Dimension mismatch is a regression on its own — fail loudly.
+ * Takes the {@link DecodedPair} rather than raw buffers so it reuses
+ * {@link scoreDiff}'s decode: the changed branch reads the image pair once, not
+ * twice. The dimensions/packing invariants were already enforced by
+ * {@link decodePair} when the pair was decoded, so no re-validation is needed
+ * here. pixelmatch's count is output-independent, so filling the overlay here
+ * cannot disturb the `diffPixels` {@link scoreDiff} already reported.
  */
-export declare function diffPngs(baseline: Buffer, actual: Buffer, pixelThreshold: number): DiffOutcome;
+export declare function renderDiffOverlay(decoded: DecodedPair, pixelThreshold: number): Buffer;
 export declare class ScreenshotSizeMismatchError extends Error {
     readonly baseline: {
         width: number;

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

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/screenshots/diff.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,WAAW,CA2Db;AAWD,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;gBAEjD,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC3C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAS5C"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/screenshots/diff.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAG5B,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,GAAG,CAAC;IACjB,SAAS,EAAE,GAAG,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,UAAU,CA6CZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,MAAM,GACrB,MAAM,CAeR;AAuCD,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;gBAEjD,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC3C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAS5C"}