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

package/dist/screenshots/baselineStore.js

@@ -1,5 +1,6 @@
 import { access, copyFile, mkdir, readFile, rm, writeFile, } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
+import { PNG } from 'pngjs';
 /**
  * Reduces an arbitrary breakpoint name to a filesystem-safe path segment.
  * Breakpoint names are simple lowercase identifiers today (`mobile`, `tablet`,
@@ -12,33 +13,69 @@ function breakpointSegment(breakpoint) {
     return breakpoint.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
 }
 /**
- * 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 function candidatesDir(reportDir) {
+    return join(reportDir, 'candidates');
+}
+/**
+ * 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 const ACTION_NAME_PATTERN = /^[a-z0-9-]+$/;
+/**
+ * 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 const BREAKPOINT_SEGMENT_PATTERN = /^[a-z0-9_-]+$/;
+/**
+ * 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 function pathsFor(options) {
     const storySlug = options.storyFile.replace(/\.json$/i, '');
     const bp = breakpointSegment(options.breakpoint);
+    const comparisonRoot = options.comparisonRoot ?? options.baselinesDir;
     return {
-        baseline: join(options.baselinesDir, options.actionName, `${bp}.png`),
+        baseline: join(comparisonRoot, options.actionName, `${bp}.png`),
         actual: join(options.reportDir, 'screenshots', storySlug, `${options.actionName}.${bp}.actual.png`),
         diff: join(options.reportDir, 'screenshots', storySlug, `${options.actionName}.${bp}.diff.png`),
-        a11yBaseline: join(options.baselinesDir, options.actionName, `${bp}.a11y.yaml`),
+        a11yBaseline: join(comparisonRoot, options.actionName, `${bp}.a11y.yaml`),
         a11yActual: join(options.reportDir, 'screenshots', storySlug, `${options.actionName}.${bp}.a11y.yaml`),
+        // Candidate tree mirrors the baseline layout under the report so a CI
+        // approval is a plain copy of `<report>/candidates/` into `paths.baselines`.
+        candidate: join(candidatesDir(options.reportDir), options.actionName, `${bp}.png`),
+        a11yCandidate: join(candidatesDir(options.reportDir), options.actionName, `${bp}.a11y.yaml`),
         // Pre-breakpoint locations. A project baselined before this feature has
         // its only committed snapshot here; the runner reads `baseline` first and
         // falls back to these when the breakpoint-keyed file is absent, so existing
-        // baselines keep matching instead of all reading as `new`.
-        legacyBaseline: join(options.baselinesDir, options.actionName, '0.png'),
-        legacyA11yBaseline: join(options.baselinesDir, options.actionName, 'a11y.yaml'),
+        // baselines keep matching instead of all reading as `new`. Rooted at the
+        // comparison root like the breakpoint-keyed baseline above.
+        legacyBaseline: join(comparisonRoot, options.actionName, '0.png'),
+        legacyA11yBaseline: join(comparisonRoot, options.actionName, 'a11y.yaml'),
     };
 }
 /**
@@ -86,9 +123,47 @@ export async function writeText(path, content) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
 }
+/**
+ * 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 function recompressPng(png) {
+    let recompressed;
+    try {
+        recompressed = PNG.sync.write(PNG.sync.read(png));
+    }
+    catch {
+        // 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.
+    return recompressed.length < png.length ? recompressed : png;
+}
 export async function writePng(path, png) {
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, png);
+    await writeFile(path, recompressPng(png));
 }
 export async function deleteIfExists(path) {
     try {
@@ -98,9 +173,18 @@ export async function deleteIfExists(path) {
         // file was not there; nothing to do
     }
 }
-export async function copyToBaseline(actualPath, baselinePath) {
-    await mkdir(dirname(baselinePath), { recursive: true });
-    await copyFile(actualPath, baselinePath);
+/**
+ * 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 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

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,9 +1,14 @@
 import type { Locator, Page } from 'playwright';
+import type { CaptureMode } from '../config.ts';
 /**
- * Full-page 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.
+ * 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.
+ *
+ * `mode` controls scope: `viewport` (default) captures only the page's current
+ * viewport box — what the user sees above the fold — while `fullPage`
+ * composites the entire scrollable document however tall.
  */
-export declare function capturePage(page: Page, masks?: Locator[]): Promise<Buffer>;
+export declare function capturePage(page: Page, masks?: Locator[], mode?: CaptureMode): 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;AAEhD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,OAAO,EAAO,GACpB,OAAO,CAAC,MAAM,CAAC,CAqBjB"}
+{"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"}

package/dist/screenshots/capture.js

@@ -1,24 +1,37 @@
 /**
- * Full-page 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.
+ * 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.
+ *
+ * `mode` controls scope: `viewport` (default) captures only the page's current
+ * viewport box — what the user sees above the fold — while `fullPage`
+ * composites the entire scrollable document however tall.
  */
-export async function capturePage(page, masks = []) {
-    // A `fullPage` screenshot composites the whole document, but it does so at
-    // the page's current scroll offset. `position: sticky` / `fixed` elements
-    // resolve their offset against that scroll position, so a page captured
-    // mid-scroll renders its sticky chrome (sidebars, headers) shifted down by
-    // `scrollY` — 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: smooth` the page
-    // sets, which would otherwise animate and reintroduce a timing race.
-    // String form so the snippet runs in the page (DOM) context without
-    // pulling the DOM lib into this Node-side module's type environment.
-    await page.evaluate(`window.scrollTo({ top: 0, left: 0, behavior: 'instant' })`);
+export async function capturePage(page, masks = [], mode = 'viewport') {
+    // `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
+    // 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:
+    // smooth` the page sets, which would otherwise animate and reintroduce a
+    // 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
+    // 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.
+    if (mode === 'fullPage') {
+        await page.evaluate(`window.scrollTo({ top: 0, left: 0, behavior: 'instant' })`);
+    }
     return page.screenshot({
-        fullPage: true,
+        fullPage: mode === 'fullPage',
         animations: 'disabled',
         caret: 'hide',
         mask: masks,

package/dist/screenshots/capture.js.map

@@ -1 +1 @@
-{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/screenshots/capture.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAU,EACV,QAAmB,EAAE;IAErB,2EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,2EAA2E;IAC3E,uEAAuE;IACvE,yEAAyE;IACzE,0EAA0E;IAC1E,0EAA0E;IAC1E,qEAAqE;IACrE,oEAAoE;IACpE,qEAAqE;IACrE,MAAM,IAAI,CAAC,QAAQ,CACjB,2DAA2D,CAC5D,CAAC;IACF,OAAO,IAAI,CAAC,UAAU,CAAC;QACrB,QAAQ,EAAE,IAAI;QACd,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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuffgal",
-  "version": "0.1.0-alpha.9",
+  "version": "0.2.0-alpha.2",
   "description": "JSON-driven visual regression for web apps.",
   "license": "MIT",
   "author": "Nick Schneble",