craftdriver 1.6.0 → 1.8.0

package/dist/lib/visual/antialias.js

@@ -0,0 +1,126 @@
+/**
+ * Optional anti-aliasing detector.
+ *
+ * The `antialiased()` / `hasManySiblings()` neighbourhood heuristic below is
+ * adapted from Pixelmatch (https://github.com/mapbox/pixelmatch) by Vladimir
+ * Agafonkin, which itself implements the anti-aliasing detection from:
+ *
+ *   V. Vysniauskas, "Anti-aliased pixel and intensity slope detector", 2009.
+ *
+ * Pixelmatch is distributed under the ISC License:
+ *
+ *   Copyright (c) 2019, Mapbox
+ *
+ *   Permission to use, copy, modify, and/or distribute this software for any
+ *   purpose with or without fee is hereby granted, provided that the above
+ *   copyright notice and this permission notice appear in all copies.
+ *
+ *   THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+ *   SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+ *   OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+ *   CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Adaptations from the original: brightness deltas and sibling equality use
+ * white-composited visible colour (see `./pixelMath`) instead of Pixelmatch's
+ * checkerboard blend, and all neighbour reads are byte-indexed so no 4-byte
+ * `Uint32Array` alignment is assumed of the codec output.
+ */
+import { brightnessDelta, visibleEqual } from './pixelMath.js';
+/**
+ * Determine whether the pixel at (x1, y1) in `data` looks like anti-aliasing,
+ * cross-checked against `other`. A pixel is a candidate when it has a bright and
+ * a dark neighbour (an intensity slope) and the extreme neighbour has many
+ * identical siblings in both images.
+ *
+ * `width`/`height` bound the compared region (the overlap of the two images);
+ * `stride`/`otherStride` are the true row widths used to byte-index `data` and
+ * `other` respectively. These differ only on a dimension mismatch — indexing a
+ * buffer at anything but its own row width reads the wrong pixels. For equal
+ * dimensions all three widths coincide and behaviour is unchanged.
+ */
+function antialiased(data, x1, y1, width, height, stride, other, otherStride) {
+    const x0 = Math.max(x1 - 1, 0);
+    const y0 = Math.max(y1 - 1, 0);
+    const x2 = Math.min(x1 + 1, width - 1);
+    const y2 = Math.min(y1 + 1, height - 1);
+    const pos = (y1 * stride + x1) * 4;
+    let zeroes = x1 === x0 || x1 === x2 || y1 === y0 || y1 === y2 ? 1 : 0;
+    let min = 0;
+    let max = 0;
+    let minX = -1;
+    let minY = -1;
+    let maxX = -1;
+    let maxY = -1;
+    for (let x = x0; x <= x2; x++) {
+        for (let y = y0; y <= y2; y++) {
+            if (x === x1 && y === y1)
+                continue;
+            const delta = brightnessDelta(data, pos, (y * stride + x) * 4);
+            if (delta === 0) {
+                zeroes++;
+                // If a pixel has many equal-brightness siblings it is not an edge.
+                if (zeroes > 2)
+                    return false;
+            }
+            else if (delta < min) {
+                min = delta;
+                minX = x;
+                minY = y;
+            }
+            else if (delta > max) {
+                max = delta;
+                maxX = x;
+                maxY = y;
+            }
+        }
+    }
+    // Need both a darker and a brighter neighbour to form an intensity slope.
+    if (min === 0 || max === 0)
+        return false;
+    return ((hasManySiblings(data, minX, minY, width, height, stride) &&
+        hasManySiblings(other, minX, minY, width, height, otherStride)) ||
+        (hasManySiblings(data, maxX, maxY, width, height, stride) &&
+            hasManySiblings(other, maxX, maxY, width, height, otherStride)));
+}
+/**
+ * Whether the pixel at (x1, y1) shares its visible colour with ≥3 neighbours.
+ * `width`/`height` bound the compared region; `stride` is `data`'s true row
+ * width used for byte indexing (see {@link antialiased}).
+ */
+function hasManySiblings(data, x1, y1, width, height, stride) {
+    const x0 = Math.max(x1 - 1, 0);
+    const y0 = Math.max(y1 - 1, 0);
+    const x2 = Math.min(x1 + 1, width - 1);
+    const y2 = Math.min(y1 + 1, height - 1);
+    const pos = (y1 * stride + x1) * 4;
+    let zeroes = x1 === x0 || x1 === x2 || y1 === y0 || y1 === y2 ? 1 : 0;
+    for (let x = x0; x <= x2; x++) {
+        for (let y = y0; y <= y2; y++) {
+            if (x === x1 && y === y1)
+                continue;
+            if (visibleEqual(data, pos, (y * stride + x) * 4)) {
+                zeroes++;
+                if (zeroes > 2)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Whether the pixel at (x, y) is anti-aliasing in either image (Pixelmatch's
+ * symmetric check). Callers should only invoke this for pixels that already
+ * failed the colour-tolerance test.
+ *
+ * `width`/`height` bound the compared region (the overlap); `actualWidth` and
+ * `expectedWidth` are each buffer's own row width for byte indexing, which
+ * differ from the overlap only on a dimension mismatch.
+ */
+export function isAntialiased(actual, expected, x, y, actualWidth, expectedWidth, width, height) {
+    return (antialiased(actual, x, y, width, height, actualWidth, expected, expectedWidth) ||
+        antialiased(expected, x, y, width, height, expectedWidth, actual, actualWidth));
+}
+//# sourceMappingURL=antialias.js.map

package/dist/lib/visual/antialias.js.map

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

package/dist/lib/visual/codec.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal codec boundary for visual testing.
+ *
+ * All PNG-library-specific code lives behind this interface so the rest of the
+ * visual pipeline works on normalized, decoded RGBA pixels and never sees the
+ * concrete codec (currently pngjs). Keeping the seam narrow means a future codec
+ * can be evaluated without touching the comparison, diff, or retry code, and no
+ * codec type is ever exposed on the public API.
+ */
+/** A decoded image normalized to a fresh 8-bit RGBA byte view. */
+export interface DecodedImage {
+    width: number;
+    height: number;
+    /** Row-major RGBA, exactly `width * height * 4` bytes. */
+    data: Uint8Array;
+}
+/** Minimal decode/encode contract implemented by {@link pngjsCodec}. */
+export interface PngCodec {
+    /** Decode a compressed PNG to normalized 8-bit RGBA. */
+    decode(buffer: Uint8Array): Promise<DecodedImage>;
+    /** Encode normalized 8-bit RGBA back to a compressed PNG. */
+    encode(image: DecodedImage): Promise<Buffer>;
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/lib/visual/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,wDAAwD;IACxD,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClD,6DAA6D;IAC7D,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C"}

package/dist/lib/visual/codec.js

@@ -0,0 +1,11 @@
+/**
+ * Internal codec boundary for visual testing.
+ *
+ * All PNG-library-specific code lives behind this interface so the rest of the
+ * visual pipeline works on normalized, decoded RGBA pixels and never sees the
+ * concrete codec (currently pngjs). Keeping the seam narrow means a future codec
+ * can be evaluated without touching the comparison, diff, or retry code, and no
+ * codec type is ever exposed on the public API.
+ */
+export {};
+//# sourceMappingURL=codec.js.map

package/dist/lib/visual/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../../src/lib/visual/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/lib/visual/compare.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-channel comparison and threshold policy over decoded RGBA images.
+ *
+ * This is small, dependency-free code over fixed-length arrays — deliberately
+ * owned rather than delegated, unlike the PNG parser. The same loop both counts
+ * differences (normal retries) and, when handed an optional diff output buffer,
+ * paints the diagnostic image (final failure only), so the two can never
+ * disagree about which pixels differ.
+ */
+import type { DecodedImage } from './codec.js';
+import { type ScreenshotCompareOptions, type VisualComparisonResult } from './types.js';
+/** Options after validation and default resolution. */
+export interface ResolvedCompareOptions {
+    pixelTolerance: number;
+    maxDiffPixels: number | undefined;
+    maxDiffPercentage: number | undefined;
+    ignoreAntialiasing: boolean;
+    maxImagePixels: number;
+    maxInputBytes: number;
+}
+/** Validate and default the comparison options. Never clamps — bad input throws. */
+export declare function resolveCompareOptions(options?: ScreenshotCompareOptions): ResolvedCompareOptions;
+/**
+ * Compare two decoded images. Counts `diffPixels` / `ignoredAntialiasPixels`
+ * and, when `output` (a union-sized RGBA buffer) is supplied, paints the diff.
+ *
+ * Argument order is `(actual, expected)` — see the note in `./types`.
+ */
+export declare function compareDecoded(actual: DecodedImage, expected: DecodedImage, opts: ResolvedCompareOptions, output?: Uint8Array): VisualComparisonResult;
+/**
+ * Compare two compressed PNG buffers without disk access, browser capture,
+ * retries, or throwing on a normal mismatch. Applies the same byte/pixel input
+ * limits as the retrying assertion.
+ *
+ * Argument order is `(actual, expected)` — see the note in `./types`.
+ */
+export declare function compareScreenshots(actual: Buffer, expected: Buffer, options?: ScreenshotCompareOptions): Promise<VisualComparisonResult>;
+//# sourceMappingURL=compare.d.ts.map

package/dist/lib/visual/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC5B,MAAM,YAAY,CAAC;AASpB,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAUD,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,wBAA6B,GAAG,sBAAsB,CAgDpG;AAiBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,sBAAsB,EAC5B,MAAM,CAAC,EAAE,UAAU,GAClB,sBAAsB,CA2FxB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,sBAAsB,CAAC,CA2BjC"}

package/dist/lib/visual/compare.js

@@ -0,0 +1,209 @@
+/**
+ * Per-channel comparison and threshold policy over decoded RGBA images.
+ *
+ * This is small, dependency-free code over fixed-length arrays — deliberately
+ * owned rather than delegated, unlike the PNG parser. The same loop both counts
+ * differences (normal retries) and, when handed an optional diff output buffer,
+ * paints the diagnostic image (final failure only), so the two can never
+ * disagree about which pixels differ.
+ */
+import { CraftdriverError, ErrorCode } from '../errors.js';
+import { pngjsCodec } from './pngjsCodec.js';
+import { validatePngHeaderAndSize } from './pngHeader.js';
+import { isAntialiased } from './antialias.js';
+import { blendOverWhite, rgb2y, visibleRgb } from './pixelMath.js';
+import { DEFAULT_MAX_IMAGE_PIXELS, DEFAULT_MAX_INPUT_BYTES, } from './types.js';
+/** Diagnostic diff colours. */
+const RED = [255, 0, 0, 255];
+const YELLOW = [255, 255, 0, 255];
+const MAGENTA = [255, 0, 255, 255];
+/** How much of the actual image bleeds through as dimmed grayscale context. */
+const GRAY_ALPHA = 0.1;
+function invalid(message, detail) {
+    throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, message, detail ? { detail } : undefined);
+}
+function requireInteger(value, name) {
+    if (!Number.isInteger(value))
+        invalid(`${name} must be an integer, got ${value}.`, { [name]: value });
+}
+/** Validate and default the comparison options. Never clamps — bad input throws. */
+export function resolveCompareOptions(options = {}) {
+    const pixelTolerance = options.pixelTolerance ?? 0;
+    requireInteger(pixelTolerance, 'pixelTolerance');
+    if (pixelTolerance < 0 || pixelTolerance > 255) {
+        invalid(`pixelTolerance must be within 0..255, got ${pixelTolerance}.`, { pixelTolerance });
+    }
+    let maxDiffPixels;
+    if (options.maxDiffPixels !== undefined) {
+        requireInteger(options.maxDiffPixels, 'maxDiffPixels');
+        if (options.maxDiffPixels < 0) {
+            invalid(`maxDiffPixels must be >= 0, got ${options.maxDiffPixels}.`, { maxDiffPixels: options.maxDiffPixels });
+        }
+        maxDiffPixels = options.maxDiffPixels;
+    }
+    let maxDiffPercentage;
+    if (options.maxDiffPercentage !== undefined) {
+        if (!Number.isFinite(options.maxDiffPercentage) || options.maxDiffPercentage < 0 || options.maxDiffPercentage > 100) {
+            invalid(`maxDiffPercentage must be within 0..100, got ${options.maxDiffPercentage}.`, {
+                maxDiffPercentage: options.maxDiffPercentage,
+            });
+        }
+        maxDiffPercentage = options.maxDiffPercentage;
+    }
+    const maxImagePixels = options.maxImagePixels ?? DEFAULT_MAX_IMAGE_PIXELS;
+    requireInteger(maxImagePixels, 'maxImagePixels');
+    if (maxImagePixels < 1)
+        invalid(`maxImagePixels must be >= 1, got ${maxImagePixels}.`, { maxImagePixels });
+    const maxInputBytes = options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES;
+    requireInteger(maxInputBytes, 'maxInputBytes');
+    if (maxInputBytes < 1)
+        invalid(`maxInputBytes must be >= 1, got ${maxInputBytes}.`, { maxInputBytes });
+    if (options.ignoreAntialiasing !== undefined && typeof options.ignoreAntialiasing !== 'boolean') {
+        // A JSON/JavaScript caller passing "false" (a truthy string) must not
+        // silently enable AA ignoring and hide regressions.
+        invalid(`ignoreAntialiasing must be a boolean, got ${typeof options.ignoreAntialiasing}.`);
+    }
+    return {
+        pixelTolerance,
+        maxDiffPixels,
+        maxDiffPercentage,
+        ignoreAntialiasing: options.ignoreAntialiasing ?? false,
+        maxImagePixels,
+        maxInputBytes,
+    };
+}
+function draw(output, pos, rgba) {
+    output[pos] = rgba[0];
+    output[pos + 1] = rgba[1];
+    output[pos + 2] = rgba[2];
+    output[pos + 3] = rgba[3];
+}
+/** Dimmed grayscale of the actual pixel — context in the diff artifact. */
+function drawContext(output, outPos, actual, srcPos) {
+    const a = actual[srcPos + 3];
+    const [r, g, b] = [0, 1, 2].map((i) => actual[srcPos + i]);
+    const val = blendOverWhite(rgb2y(r, g, b), GRAY_ALPHA * a);
+    draw(output, outPos, [val, val, val, 255]);
+}
+/**
+ * Compare two decoded images. Counts `diffPixels` / `ignoredAntialiasPixels`
+ * and, when `output` (a union-sized RGBA buffer) is supplied, paints the diff.
+ *
+ * Argument order is `(actual, expected)` — see the note in `./types`.
+ */
+export function compareDecoded(actual, expected, opts, output) {
+    const dimensionMismatch = actual.width !== expected.width || actual.height !== expected.height;
+    // Diff canvas is the bounding box; both images are anchored at (0, 0).
+    const canvasWidth = Math.max(actual.width, expected.width);
+    const canvasHeight = Math.max(actual.height, expected.height);
+    const overlapWidth = Math.min(actual.width, expected.width);
+    const overlapHeight = Math.min(actual.height, expected.height);
+    // Counts/percentage are over the *union* of the two top-left rectangles —
+    // the bounding-box corner present in neither image is excluded.
+    const totalPixels = actual.width * actual.height +
+        expected.width * expected.height -
+        overlapWidth * overlapHeight;
+    const va = [0, 0, 0];
+    const ve = [0, 0, 0];
+    const tol = opts.pixelTolerance;
+    let diffPixels = 0;
+    let ignoredAntialiasPixels = 0;
+    for (let y = 0; y < canvasHeight; y++) {
+        for (let x = 0; x < canvasWidth; x++) {
+            const outPos = (y * canvasWidth + x) * 4;
+            const inActual = x < actual.width && y < actual.height;
+            const inExpected = x < expected.width && y < expected.height;
+            // Present in neither image (the bounding-box corner): leave it
+            // transparent in the diff and don't count it.
+            if (!inActual && !inExpected)
+                continue;
+            if (!(inActual && inExpected)) {
+                // Present in only one image (dimension mismatch): always a difference.
+                diffPixels++;
+                if (output)
+                    draw(output, outPos, MAGENTA);
+                continue;
+            }
+            const aPos = (y * actual.width + x) * 4;
+            const ePos = (y * expected.width + x) * 4;
+            visibleRgb(actual.data, aPos, va);
+            visibleRgb(expected.data, ePos, ve);
+            const equal = Math.abs(va[0] - ve[0]) <= tol &&
+                Math.abs(va[1] - ve[1]) <= tol &&
+                Math.abs(va[2] - ve[2]) <= tol;
+            if (equal) {
+                if (output)
+                    drawContext(output, outPos, actual.data, aPos);
+                continue;
+            }
+            if (opts.ignoreAntialiasing &&
+                isAntialiased(actual.data, expected.data, x, y, actual.width, expected.width, overlapWidth, overlapHeight)) {
+                ignoredAntialiasPixels++;
+                if (output)
+                    draw(output, outPos, YELLOW);
+                continue;
+            }
+            diffPixels++;
+            if (output)
+                draw(output, outPos, RED);
+        }
+    }
+    const diffPercentage = totalPixels === 0 ? 0 : (diffPixels / totalPixels) * 100;
+    let matches;
+    if (dimensionMismatch) {
+        matches = false;
+    }
+    else if (opts.maxDiffPixels === undefined && opts.maxDiffPercentage === undefined) {
+        matches = diffPixels === 0;
+    }
+    else {
+        matches =
+            (opts.maxDiffPixels === undefined || diffPixels <= opts.maxDiffPixels) &&
+                (opts.maxDiffPercentage === undefined || diffPercentage <= opts.maxDiffPercentage);
+    }
+    return {
+        matches,
+        diffPixels,
+        diffPercentage,
+        ignoredAntialiasPixels,
+        expectedWidth: expected.width,
+        expectedHeight: expected.height,
+        actualWidth: actual.width,
+        actualHeight: actual.height,
+        dimensionMismatch,
+    };
+}
+/**
+ * Compare two compressed PNG buffers without disk access, browser capture,
+ * retries, or throwing on a normal mismatch. Applies the same byte/pixel input
+ * limits as the retrying assertion.
+ *
+ * Argument order is `(actual, expected)` — see the note in `./types`.
+ */
+export async function compareScreenshots(actual, expected, options) {
+    const opts = resolveCompareOptions(options);
+    const limits = { maxImagePixels: opts.maxImagePixels, maxInputBytes: opts.maxInputBytes };
+    const { width, height } = validatePngHeaderAndSize(expected, limits, 'baseline');
+    validatePngHeaderAndSize(actual, limits, 'screenshot');
+    // Fast path: identical compressed bytes necessarily mean identical pixels, so
+    // there is nothing to decode. Mirrors the retrying assertion's fast path.
+    if (actual.length === expected.length && actual.equals(expected)) {
+        return {
+            matches: true,
+            diffPixels: 0,
+            diffPercentage: 0,
+            ignoredAntialiasPixels: 0,
+            expectedWidth: width,
+            expectedHeight: height,
+            actualWidth: width,
+            actualHeight: height,
+            dimensionMismatch: false,
+        };
+    }
+    const [actualImage, expectedImage] = await Promise.all([
+        pngjsCodec.decode(actual),
+        pngjsCodec.decode(expected),
+    ]);
+    return compareDecoded(actualImage, expectedImage, opts);
+}
+//# sourceMappingURL=compare.js.map

package/dist/lib/visual/compare.js.map

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

package/dist/lib/visual/diff.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lazy diff painting. Allocated and run exactly once, only after a visual
+ * assertion has finally failed — never during retries. Reuses the comparison
+ * loop in `./compare` with an output buffer so the painted diff and the counted
+ * result use identical pixel semantics.
+ */
+import type { DecodedImage } from './codec.js';
+import { type ResolvedCompareOptions } from './compare.js';
+/**
+ * Produce a diagnostic diff image sized to the union of both inputs (top-left
+ * aligned). Unchanged pixels appear as dimmed grayscale actual content,
+ * counted differences as red, ignored anti-aliased pixels as yellow, and areas
+ * present in only one image (dimension mismatch) as magenta.
+ *
+ * Argument order is `(actual, expected)` — see the note in `./types`.
+ */
+export declare function createDiff(actual: DecodedImage, expected: DecodedImage, opts: ResolvedCompareOptions): DecodedImage;
+//# sourceMappingURL=diff.d.ts.map

package/dist/lib/visual/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,sBAAsB,GAC3B,YAAY,CAMd"}

package/dist/lib/visual/diff.js

@@ -0,0 +1,23 @@
+/**
+ * Lazy diff painting. Allocated and run exactly once, only after a visual
+ * assertion has finally failed — never during retries. Reuses the comparison
+ * loop in `./compare` with an output buffer so the painted diff and the counted
+ * result use identical pixel semantics.
+ */
+import { compareDecoded } from './compare.js';
+/**
+ * Produce a diagnostic diff image sized to the union of both inputs (top-left
+ * aligned). Unchanged pixels appear as dimmed grayscale actual content,
+ * counted differences as red, ignored anti-aliased pixels as yellow, and areas
+ * present in only one image (dimension mismatch) as magenta.
+ *
+ * Argument order is `(actual, expected)` — see the note in `./types`.
+ */
+export function createDiff(actual, expected, opts) {
+    const width = Math.max(actual.width, expected.width);
+    const height = Math.max(actual.height, expected.height);
+    const data = new Uint8Array(width * height * 4);
+    compareDecoded(actual, expected, opts, data);
+    return { width, height, data };
+}
+//# sourceMappingURL=diff.js.map

package/dist/lib/visual/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/lib/visual/diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAA+B,MAAM,cAAc,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,MAAoB,EACpB,QAAsB,EACtB,IAA4B;IAE5B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC;IAChD,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACjC,CAAC"}

package/dist/lib/visual/expectScreenshot.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The retrying visual assertion: read the baseline once, then poll the browser
+ * until a screenshot matches or the monotonic deadline expires.
+ *
+ * The hot path is deliberately lazy. An exact byte match costs one screenshot
+ * plus a `Buffer.equals` and never decodes. A static mismatch decodes the
+ * expected and actual images once each, then subsequent polls only re-capture
+ * and compare compressed bytes. Only changing content pays a decode per retry.
+ * The diff image is allocated and encoded exactly once, after the final failure.
+ *
+ * Baselines are managed for the caller, WebdriverIO-style:
+ *   - Missing baseline (ENOENT): capture until two consecutive frames settle,
+ *     write it, pass. This is the default — no flag required.
+ *   - Present but differs, with `update`: capture as usual and, only if the page
+ *     never settles into a match, overwrite the baseline with the final actual
+ *     and pass. A page that settles back into a match passes without rewriting.
+ * A present-but-corrupt baseline, and any non-ENOENT read error, stay hard
+ * configuration errors even under `update` — they are never overwritten.
+ *
+ * Every baseline write is atomic — the PNG is written to a temp file in the same
+ * directory and renamed into place — so an interrupted run cannot corrupt a
+ * committed baseline (this matters most under `update`, which replaces one).
+ *
+ * Timing (`now`) and delays (`sleep`) are injectable so retry behaviour can be
+ * driven deterministically in tests without wall-clock waits.
+ */
+import type { PngCodec } from './codec.js';
+import type { ExpectScreenshotOptions, ScreenshotMatchResult } from './types.js';
+/** Capture one screenshot, bounding any internal visibility wait by `remainingMs`. */
+export type CaptureFn = (remainingMs: number) => Promise<Buffer>;
+export interface RunExpectScreenshotDeps {
+    expectedPath: string;
+    options: ExpectScreenshotOptions;
+    /** The browser's live default timeout, used when `options.timeout` is unset. */
+    defaultTimeout: number;
+    capture: CaptureFn;
+    /**
+     * When true, a baseline that is present but never matches is overwritten with
+     * the final actual instead of throwing. Missing-baseline creation is always on
+     * and does not depend on this flag. Driven by
+     * {@link shouldUpdateVisualBaselines} from the environment. Default false.
+     */
+    update?: boolean;
+    readFile?: (path: string) => Promise<Buffer>;
+    writeFile?: (path: string, data: Buffer) => Promise<void>;
+    rename?: (from: string, to: string) => Promise<void>;
+    unlink?: (path: string) => Promise<void>;
+    mkdir?: (dir: string, opts: {
+        recursive: true;
+    }) => Promise<unknown>;
+    /** Human-readable one-liner reported when a baseline is created or updated. */
+    report?: (message: string) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    codec?: PngCodec;
+}
+/**
+ * Strictly interpret the `CRAFTDRIVER_UPDATE_VISUAL_BASELINES` environment
+ * variable. Unset / empty / `false` → off; `true` → on (trimmed,
+ * case-insensitive). Anything else throws `INVALID_ARGUMENT` rather than being
+ * silently coerced — this flag mutates files on disk, so a typo must fail loud.
+ */
+export declare function shouldUpdateVisualBaselines(raw: string | undefined): boolean;
+export declare function runExpectScreenshot(deps: RunExpectScreenshotDeps): Promise<ScreenshotMatchResult>;
+//# sourceMappingURL=expectScreenshot.d.ts.map

package/dist/lib/visual/expectScreenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectScreenshot.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/expectScreenshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAcH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEjF,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEjE,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,uBAAuB,CAAC;IACjC,gFAAgF;IAChF,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,+EAA+E;IAC/E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAqBD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAS5E;AAsDD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA8LvG"}