craftdriver 1.6.0 → 1.8.0

package/dist/lib/visual/pngjsCodec.js

@@ -0,0 +1,70 @@
+/**
+ * Isolated pngjs adapter — the single place that touches the CommonJS-shaped
+ * `pngjs` API. The rest of craftdriver is ESM and works only with the
+ * promise-based {@link PngCodec} and normalized {@link DecodedImage} defined in
+ * `./codec`; pngjs types never leak past this file.
+ *
+ * Decode and encode both use pngjs's asynchronous stream APIs (`parse` /
+ * `pack`) rather than the synchronous variants, so a large image cannot block
+ * the event loop inside a single call. CRC checking is left at pngjs's default
+ * (enabled) so corrupt chunks are rejected rather than silently decoded.
+ *
+ * Maintenance risk (recorded, not hidden): `pngjs@7.0.0` is pinned exactly. It
+ * had no reported npm/OSV advisory as of 2026-07-17, but that is a timestamped
+ * check, not proof of safety — its last release was 2023 and it publishes no
+ * security policy. It relies on Node's built-in `zlib`, so keeping Node patched
+ * is part of the posture. CI runs `npm audit --omit=dev`; this seam is kept
+ * narrow (see `./codec`) so the codec can be replaced without touching callers
+ * if the project goes unmaintained or an advisory lands.
+ */
+import { PNG } from 'pngjs';
+import { CraftdriverError, ErrorCode } from '../errors.js';
+function wrapDecodeError(cause) {
+    return new CraftdriverError(ErrorCode.INVALID_ARGUMENT, 'Failed to decode PNG image.', {
+        cause,
+        hint: 'The buffer is not a valid PNG, or its chunks failed CRC validation.',
+    });
+}
+/**
+ * Decode a compressed PNG buffer to a fresh, tightly-packed 8-bit RGBA view.
+ *
+ * pngjs always normalizes palette/grayscale/16-bit/interlaced inputs to 8-bit
+ * RGBA in `png.data`, but that buffer may be a view into a larger pool. We copy
+ * into a right-sized `Uint8Array` so downstream code can rely on
+ * `data.length === width * height * 4` and on a predictable backing buffer.
+ */
+function decode(buffer) {
+    return new Promise((resolve, reject) => {
+        const png = new PNG();
+        const input = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+        png.parse(input, (err, decoded) => {
+            if (err || !decoded) {
+                reject(wrapDecodeError(err ?? new Error('pngjs produced no image')));
+                return;
+            }
+            const { width, height } = decoded;
+            const expected = width * height * 4;
+            const data = new Uint8Array(expected);
+            data.set(decoded.data.subarray(0, expected));
+            resolve({ width, height, data });
+        });
+    });
+}
+/** Encode normalized 8-bit RGBA back to a compressed PNG buffer. */
+function encode(image) {
+    return new Promise((resolve, reject) => {
+        const png = new PNG({ width: image.width, height: image.height });
+        // pngjs owns a Buffer at png.data of the right length; fill it in place.
+        png.data = Buffer.from(image.data.buffer, image.data.byteOffset, image.data.byteLength);
+        const chunks = [];
+        png
+            .pack()
+            .on('data', (chunk) => chunks.push(chunk))
+            .on('end', () => resolve(Buffer.concat(chunks)))
+            .on('error', (err) => reject(new CraftdriverError(ErrorCode.DRIVER_ERROR, 'Failed to encode diff PNG image.', {
+            cause: err,
+        })));
+    });
+}
+export const pngjsCodec = { decode, encode };
+//# sourceMappingURL=pngjsCodec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pngjsCodec.js","sourceRoot":"","sources":["../../../src/lib/visual/pngjsCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG3D,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,IAAI,gBAAgB,CAAC,SAAS,CAAC,gBAAgB,EAAE,6BAA6B,EAAE;QACrF,KAAK;QACL,IAAI,EAAE,qEAAqE;KAC5E,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,MAAM,CAAC,MAAkB;IAChC,OAAO,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE;YAChC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,eAAe,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;YACD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;YAClC,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC;YACpC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC7C,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,oEAAoE;AACpE,SAAS,MAAM,CAAC,KAAmB;IACjC,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAClE,yEAAyE;QACzE,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxF,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,GAAG;aACA,IAAI,EAAE;aACN,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aACjD,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;aAC/C,EAAE,CAAC,OAAO,EAAE,CAAC,GAAY,EAAE,EAAE,CAC5B,MAAM,CACJ,IAAI,gBAAgB,CAAC,SAAS,CAAC,YAAY,EAAE,kCAAkC,EAAE;YAC/E,KAAK,EAAE,GAAG;SACX,CAAC,CACH,CACF,CAAC;IACN,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAa,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC"}

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

@@ -0,0 +1,89 @@
+/**
+ * Public and internal types for visual screenshot assertions.
+ *
+ * The `(actual, expected)` argument order is used consistently across every
+ * public and internal helper (`compareScreenshots`, `compareDecoded`,
+ * `createDiff`). Both buffers share a type, so reversing the order would be a
+ * silent bug — never deviate from it.
+ */
+import type { By } from '../by.js';
+/**
+ * Default upper bound on decoded image size, in pixels, enforced before RGBA
+ * allocation. RGBA is ≥4 bytes/pixel, so expected + actual + final raw diff is
+ * ~240 MB of raw arrays at this limit before compressed buffers and pngjs
+ * working memory — and parallel assertions multiply that. Raise it explicitly
+ * for unusually long full-page screenshots; lower it when many workers run
+ * concurrently. A 100M default would permit ≥1.2 GB and is not a real guard.
+ */
+export declare const DEFAULT_MAX_IMAGE_PIXELS = 20000000;
+/** Default upper bound on a compressed PNG input buffer, in bytes (50 MiB). */
+export declare const DEFAULT_MAX_INPUT_BYTES: number;
+/**
+ * Mutually exclusive capture scope forwarded to `browser.screenshot()`.
+ * `fullPage` and `selector` cannot be combined (enforced by the union here and
+ * re-checked at runtime for JavaScript callers).
+ */
+export type VisualScreenshotOptions = {
+    fullPage: true;
+    selector?: never;
+} | {
+    selector: string | By;
+    fullPage?: false;
+} | {
+    fullPage?: false;
+    selector?: never;
+};
+/** Policies applied to a single buffer-to-buffer comparison. */
+export interface ScreenshotCompareOptions {
+    /** Inclusive maximum difference for each visible RGB channel. Integer 0..255. Default: 0. */
+    pixelTolerance?: number;
+    /** Maximum counted different pixels. Non-negative integer. */
+    maxDiffPixels?: number;
+    /** Maximum counted different pixels as a percentage of all pixels. 0..100. */
+    maxDiffPercentage?: number;
+    /** Exclude pixels classified as anti-aliasing from diff totals. Default: false. */
+    ignoreAntialiasing?: boolean;
+    /** Reject images above this decoded size before allocation. Default: 20 million pixels. */
+    maxImagePixels?: number;
+    /** Reject compressed PNG input above this size. Default: 50 MiB. */
+    maxInputBytes?: number;
+}
+/** Options for the retrying `browser.expectScreenshot()` assertion. */
+export interface ExpectScreenshotOptions extends ScreenshotCompareOptions {
+    /** Overall retry time in ms. Defaults to the browser's default timeout (5000 ms). */
+    timeout?: number;
+    /** Delay between failed attempts in ms. Integer >= 10. Default: 50. */
+    interval?: number;
+    /** Mutually exclusive capture scope passed to `browser.screenshot()`. */
+    screenshot?: VisualScreenshotOptions;
+}
+/** Result of one buffer-to-buffer comparison. */
+export interface VisualComparisonResult {
+    matches: boolean;
+    diffPixels: number;
+    /** Raw, unrounded value in 0..100. */
+    diffPercentage: number;
+    ignoredAntialiasPixels: number;
+    expectedWidth: number;
+    expectedHeight: number;
+    actualWidth: number;
+    actualHeight: number;
+    dimensionMismatch: boolean;
+}
+/** Result of a successful `browser.expectScreenshot()` assertion. */
+export interface ScreenshotMatchResult extends VisualComparisonResult {
+    attempts: number;
+    elapsedMs: number;
+    /**
+     * How the on-disk baseline was resolved:
+     * - `'matched'` — an existing baseline was compared and passed.
+     * - `'created'` — no baseline existed; the captured screenshot was written as
+     *   the new baseline (always on; the diff fields are zero).
+     * - `'updated'` — an existing baseline differed and was overwritten with the
+     *   captured screenshot (only under `CRAFTDRIVER_UPDATE_VISUAL_BASELINES=true`;
+     *   the diff fields describe state relative to the new baseline, i.e. zero —
+     *   the magnitude of the accepted change is reported to stderr).
+     */
+    baseline: 'matched' | 'created' | 'updated';
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,WAAa,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GACpC;IAAE,QAAQ,EAAE,MAAM,GAAG,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3C;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE3C,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,yEAAyE;IACzE,UAAU,CAAC,EAAE,uBAAuB,CAAC;CACtC;AAED,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;CAC7C"}

package/dist/lib/visual/types.js

@@ -0,0 +1,20 @@
+/**
+ * Public and internal types for visual screenshot assertions.
+ *
+ * The `(actual, expected)` argument order is used consistently across every
+ * public and internal helper (`compareScreenshots`, `compareDecoded`,
+ * `createDiff`). Both buffers share a type, so reversing the order would be a
+ * silent bug — never deviate from it.
+ */
+/**
+ * Default upper bound on decoded image size, in pixels, enforced before RGBA
+ * allocation. RGBA is ≥4 bytes/pixel, so expected + actual + final raw diff is
+ * ~240 MB of raw arrays at this limit before compressed buffers and pngjs
+ * working memory — and parallel assertions multiply that. Raise it explicitly
+ * for unusually long full-page screenshots; lower it when many workers run
+ * concurrently. A 100M default would permit ≥1.2 GB and is not a real guard.
+ */
+export const DEFAULT_MAX_IMAGE_PIXELS = 20_000_000;
+/** Default upper bound on a compressed PNG input buffer, in bytes (50 MiB). */
+export const DEFAULT_MAX_INPUT_BYTES = 50 * 1024 * 1024;
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/visual/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,UAAU,CAAC;AAEnD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * Typed failure for a visual assertion.
+ *
+ * JavaScript cannot both throw and return a normal value, so the final actual
+ * screenshot and generated diff PNG travel on the error as `Buffer`
+ * properties, while a JSON-serializable summary lives in `detail` for agents.
+ */
+import { CraftdriverError } from '../errors.js';
+import type { VisualComparisonResult } from './types.js';
+export interface VisualMismatchInfo {
+    expectedPath: string;
+    timeout: number;
+    attempts: number;
+    elapsedMs: number;
+    comparison: VisualComparisonResult;
+}
+/**
+ * Thrown by `browser.expectScreenshot()` when no screenshot matched the
+ * baseline before the timeout. Carries the final actual and diff PNG buffers
+ * plus the comparison summary; `code` is `VISUAL_MISMATCH`.
+ */
+export declare class VisualMismatchError extends CraftdriverError {
+    /** Final browser screenshot (compressed PNG). */
+    readonly actual: Buffer;
+    /** Final generated diff (compressed PNG). */
+    readonly diff: Buffer;
+    readonly comparison: VisualComparisonResult;
+    readonly attempts: number;
+    readonly elapsedMs: number;
+    constructor(actual: Buffer, diff: Buffer, info: VisualMismatchInfo);
+}
+//# sourceMappingURL=visualError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visualError.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/visualError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAa,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,sBAAsB,CAAC;CACpC;AAgBD;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;IACvD,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB;CAyBnE"}

package/dist/lib/visual/visualError.js

@@ -0,0 +1,59 @@
+/**
+ * Typed failure for a visual assertion.
+ *
+ * JavaScript cannot both throw and return a normal value, so the final actual
+ * screenshot and generated diff PNG travel on the error as `Buffer`
+ * properties, while a JSON-serializable summary lives in `detail` for agents.
+ */
+import { CraftdriverError, ErrorCode } from '../errors.js';
+function buildMessage(info) {
+    const { comparison, timeout, attempts } = info;
+    if (comparison.dimensionMismatch) {
+        return (`Screenshot did not match after ${timeout} ms: dimensions differ ` +
+            `(expected ${comparison.expectedWidth}x${comparison.expectedHeight}, ` +
+            `actual ${comparison.actualWidth}x${comparison.actualHeight}) across ${attempts} attempts`);
+    }
+    const pixels = comparison.diffPixels.toLocaleString('en-US');
+    const pct = comparison.diffPercentage.toFixed(4);
+    return `Screenshot did not match after ${timeout} ms: ${pixels} pixels differed (${pct}%) across ${attempts} attempts`;
+}
+/**
+ * Thrown by `browser.expectScreenshot()` when no screenshot matched the
+ * baseline before the timeout. Carries the final actual and diff PNG buffers
+ * plus the comparison summary; `code` is `VISUAL_MISMATCH`.
+ */
+export class VisualMismatchError extends CraftdriverError {
+    /** Final browser screenshot (compressed PNG). */
+    actual;
+    /** Final generated diff (compressed PNG). */
+    diff;
+    comparison;
+    attempts;
+    elapsedMs;
+    constructor(actual, diff, info) {
+        super(ErrorCode.VISUAL_MISMATCH, buildMessage(info), {
+            detail: {
+                expectedPath: info.expectedPath,
+                timeout: info.timeout,
+                attempts: info.attempts,
+                elapsedMs: info.elapsedMs,
+                diffPixels: info.comparison.diffPixels,
+                diffPercentage: info.comparison.diffPercentage,
+                ignoredAntialiasPixels: info.comparison.ignoredAntialiasPixels,
+                expectedWidth: info.comparison.expectedWidth,
+                expectedHeight: info.comparison.expectedHeight,
+                actualWidth: info.comparison.actualWidth,
+                actualHeight: info.comparison.actualHeight,
+                dimensionMismatch: info.comparison.dimensionMismatch,
+            },
+            hint: 'Inspect error.actual and error.diff (PNG buffers) to see the regression. If the change is intentional, re-run with CRAFTDRIVER_UPDATE_VISUAL_BASELINES=true to overwrite the baseline.',
+        });
+        this.name = 'VisualMismatchError';
+        this.actual = actual;
+        this.diff = diff;
+        this.comparison = info.comparison;
+        this.attempts = info.attempts;
+        this.elapsedMs = info.elapsedMs;
+    }
+}
+//# sourceMappingURL=visualError.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visualError.js","sourceRoot":"","sources":["../../../src/lib/visual/visualError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAW3D,SAAS,YAAY,CAAC,IAAwB;IAC5C,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC/C,IAAI,UAAU,CAAC,iBAAiB,EAAE,CAAC;QACjC,OAAO,CACL,kCAAkC,OAAO,yBAAyB;YAClE,aAAa,UAAU,CAAC,aAAa,IAAI,UAAU,CAAC,cAAc,IAAI;YACtE,UAAU,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC,YAAY,YAAY,QAAQ,WAAW,CAC3F,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,GAAG,GAAG,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,OAAO,kCAAkC,OAAO,QAAQ,MAAM,qBAAqB,GAAG,aAAa,QAAQ,WAAW,CAAC;AACzH,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,gBAAgB;IACvD,iDAAiD;IACxC,MAAM,CAAS;IACxB,6CAA6C;IACpC,IAAI,CAAS;IACb,UAAU,CAAyB;IACnC,QAAQ,CAAS;IACjB,SAAS,CAAS;IAE3B,YAAY,MAAc,EAAE,IAAY,EAAE,IAAwB;QAChE,KAAK,CAAC,SAAS,CAAC,eAAe,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE;YACnD,MAAM,EAAE;gBACN,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,UAAU;gBACtC,cAAc,EAAE,IAAI,CAAC,UAAU,CAAC,cAAc;gBAC9C,sBAAsB,EAAE,IAAI,CAAC,UAAU,CAAC,sBAAsB;gBAC9D,aAAa,EAAE,IAAI,CAAC,UAAU,CAAC,aAAa;gBAC5C,cAAc,EAAE,IAAI,CAAC,UAAU,CAAC,cAAc;gBAC9C,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;gBACxC,YAAY,EAAE,IAAI,CAAC,UAAU,CAAC,YAAY;gBAC1C,iBAAiB,EAAE,IAAI,CAAC,UAAU,CAAC,iBAAiB;aACrD;YACD,IAAI,EAAE,wLAAwL;SAC/L,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;CACF"}

package/dist/lib/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/lib/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI7C,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,EACvC,UAAU,CAAC,EAAE,MAAM;IAYf,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CA8BtE;AAOD,eAAO,MAAM,KAAK;8BACU,EAAE,MAAY,QAAQ,MAAM;6BAI7B,EAAE,MAAY,QAAQ,MAAM;gCASzB,EAAE,MAAY,QAAQ,MAAM;+BAS7B,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;kCAUtC,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;CAaxE,CAAC"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/lib/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI7C,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,EACvC,UAAU,CAAC,EAAE,MAAM;IAYf,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAmCtE;AAOD,eAAO,MAAM,KAAK;8BACU,EAAE,MAAY,QAAQ,MAAM;6BAI7B,EAAE,MAAY,QAAQ,MAAM;gCASzB,EAAE,MAAY,QAAQ,MAAM;+BAS7B,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;kCAUtC,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;CAaxE,CAAC"}

package/dist/lib/wait.js

@@ -27,7 +27,11 @@ export class WebDriverWait {
     async until(condition, message) {
         const deadline = Date.now() + this.timeoutMs;
         let lastErr;
-        while (Date.now() < deadline) {
+        // Check-first: the condition is always evaluated at least once, even with a
+        // zero (or already-elapsed) timeout. A `while (Date.now() < deadline)` loop
+        // would run zero iterations at timeout 0 and report an already-satisfiable
+        // condition as a spurious timeout.
+        for (;;) {
             try {
                 const result = await condition(this.driver);
                 // Resolve on truthy or non-null/undefined result
@@ -38,6 +42,8 @@ export class WebDriverWait {
             catch (e) {
                 lastErr = e;
             }
+            if (Date.now() >= deadline)
+                break;
             await new Promise((r) => setTimeout(r, this.intervalMs));
         }
         const errMsg = message ?? this.timeoutMsg ?? `Wait timed out after ${this.timeoutMs}ms`;

package/dist/lib/wait.js.map

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

package/docs/agents.md

@@ -1,24 +1,37 @@
 # AI Agent Guide
 
-CraftDriver ships agent-facing tooling in the npm package. You can use the library directly, drive the browser from the shell, expose tools through MCP, or drop assistant rules into a project.
+CraftDriver's recommended agent surface is the CLI plus a project-local skill.
+The agent explores the running application, learns its DOM and accessibility
+structure, validates durable selectors, and then writes and runs ordinary
+CraftDriver tests. MCP is optional.
 
-## Which Surface Should I Use?
+## Install safely
 
-| Agent environment          | Best surface       | Why                                                                              |
-| -------------------------- | ------------------ | -------------------------------------------------------------------------------- |
-| Shell-capable coding agent | CLI                | Simple commands, persistent daemon, JSON output when piped.                      |
-| MCP-aware host             | MCP server         | Typed tools, compact accessibility snapshots, artifact spilling for screenshots. |
-| Code-writing assistant     | `craftdriver init` | Project rules teach selector preference, auto-waiting, and error-code handling.  |
-| Custom orchestrator        | Skill pack         | Small always-on `SKILL.md` with deeper references loaded on demand.              |
+From a project that already has a `package.json`:
 
-## CLI
+```bash
+npm install --save-dev craftdriver
+npx craftdriver init codex
+```
+
+This installs `.agents/skills/craftdriver/` with an ownership manifest. It does
+not read or change `AGENTS.md`, `CLAUDE.md`, Copilot instructions, Cursor rules,
+`GEMINI.md`, or `.codex/config.toml`. It refuses user-edited, unowned, extra, or
+symlinked destination content instead of overwriting it.
 
-The CLI is good for agents that can run shell commands.
+Preview without writes:
+
+```bash
+npx craftdriver init codex --dry-run
+```
+
+## Explore, then write the test
 
 ```bash
 npx craftdriver daemon start
 npx craftdriver go http://127.0.0.1:8080/login.html
 npx craftdriver snapshot
+npx craftdriver find 'label=Username' --all
 npx craftdriver fill 'label=Username' alice
 npx craftdriver fill 'label=Password' hunter2
 npx craftdriver click 'role=button[name=Sign in]'
@@ -26,67 +39,49 @@ npx craftdriver text '#result'
 npx craftdriver daemon stop
 ```
 
-State survives between calls while the daemon is running, so an agent can explore, act, inspect, and refine.
-
-Read the full [CLI reference](./cli.md).
-
-## MCP Server
+The daemon keeps the page and cookies between commands. Snapshot refs are
+ephemeral exploration state in the current release: take a fresh snapshot
+immediately before one ref action, and never copy `ref=eN` into a test. Validate
+role/name, label, test ID, text, or stable CSS selectors against the live page,
+then use those durable locators in test source.
 
-MCP-aware hosts can use `craftdriver mcp`.
+The daemon uses a Unix socket and is not available on Windows. Windows agents
+should use the optional MCP server for a persistent session, or run the whole
+flow as one `craftdriver --ephemeral` script.
 
-```bash
-claude mcp add craftdriver -- npx -y craftdriver mcp
-```
-
-```jsonc
-{
-  "mcpServers": {
-    "craftdriver": {
-      "command": "npx",
-      "args": ["-y", "craftdriver", "mcp"],
-    },
-  },
-}
-```
-
-Mutating tools return compact accessibility snapshot diffs, so the agent can see what changed without a separate read. Large artifacts such as screenshots are written to disk instead of inlined into model context.
+The installed `workflow.md` guides the full loop: inspect existing project test
+conventions, explore, validate selectors, write the smallest test, run the
+focused command, and debug from fresh browser evidence.
 
-Read the full [MCP reference](./mcp.md).
+Read the [CLI reference](./cli.md) for all current commands.
 
-## Assistant Bootstrap Files
+## Optional MCP
 
-Use `craftdriver init` inside a project that uses CraftDriver:
+CLI + Skill does not require MCP. For a host that prefers structured tool
+calls, print the local project-pinned configuration:
 
 ```bash
-npx craftdriver init agents
-npx craftdriver init copilot
-npx craftdriver init claude
-npx craftdriver init cursor
-npx craftdriver init gemini
-npx craftdriver init all
+npx craftdriver init codex --mcp
 ```
 
-The generated files tell assistants to:
+The command prints:
 
-- prefer semantic selectors before brittle CSS
-- rely on auto-waiting instead of sleeps
-- inspect stable `CraftdriverError.code` values
-- use the CLI or MCP server for live browser work
-- keep test code aligned with the public TypeScript API
-
-## Skill Pack
-
-The npm tarball includes a tiered skill pack under `skills/craftdriver/`:
+```toml
+[mcp_servers.craftdriver]
+command = "npx"
+args = ["--no-install", "craftdriver", "mcp"]
+```
 
-| File            | Purpose                                                                                |
-| --------------- | -------------------------------------------------------------------------------------- |
-| `SKILL.md`      | Always-on rules and routing, kept small for model context.                             |
-| `cheatsheet.md` | Fast command and API reference for tests.                                              |
-| `patterns.md`   | Worked recipes such as login, uploads, network waits, a11y, tracing, and virtual time. |
-| `cli.md`        | Agent-facing CLI reference.                                                            |
+Add it manually to the host configuration. CraftDriver never reads or writes
+that configuration. See the [MCP reference](./mcp.md) for the current optional
+tool surface and protocol bounds.
 
-Point compatible agents at:
+## Installed skill files
 
-```text
-node_modules/craftdriver/skills/craftdriver/SKILL.md
-```
+| File | Purpose |
+| --- | --- |
+| `SKILL.md` | Short browser-to-test rules and routing. |
+| `workflow.md` | Exploration, selector validation, test authoring, and debugging loop. |
+| `cli.md` | Current shell command reference for agent exploration. |
+| `cheatsheet.md` | Public TypeScript API reference for writing tests. |
+| `patterns.md` | Focused library recipes loaded on demand. |

package/docs/api-reference.md

@@ -124,6 +124,20 @@ Launch packaged Electron applications, drive their renderer, and opt in to main-
 | `ElectronMainLogHandler` | type | — | [electron](electron.md) |
 | `ElectronMainLogLevel` | type | Normalized level for a main-process log entry. | [electron](electron.md) |
 
+## Visual Testing
+
+Assert screenshots against baselines with pixel/percentage tolerances and optional anti-alias handling.
+
+| Symbol | Kind | Summary | Docs |
+|---|---|---|---|
+| `compareScreenshots` | function | 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. | [visual-testing](visual-testing.md) |
+| `VisualMismatchError` | class | Thrown by `browser.expectScreenshot()` when no screenshot matched the baseline before the timeout. Carries the final actual and diff PNG buffers plus the comparison summary; `code` is `VISUAL_MISMATCH`. | [visual-testing](visual-testing.md) |
+| `ScreenshotCompareOptions` | type | Policies applied to a single buffer-to-buffer comparison. | [visual-testing](visual-testing.md) |
+| `ExpectScreenshotOptions` | type | Options for the retrying `browser.expectScreenshot()` assertion. | [visual-testing](visual-testing.md) |
+| `VisualScreenshotOptions` | type | Mutually exclusive capture scope forwarded to `browser.screenshot()`. `fullPage` and `selector` cannot be combined (enforced by the union here and re-checked at runtime for JavaScript callers). | [visual-testing](visual-testing.md) |
+| `VisualComparisonResult` | type | Result of one buffer-to-buffer comparison. | [visual-testing](visual-testing.md) |
+| `ScreenshotMatchResult` | type | Result of a successful `browser.expectScreenshot()` assertion. | [visual-testing](visual-testing.md) |
+
 ## Accessibility
 
 Run axe-core accessibility checks and inspect violation details.
@@ -169,5 +183,6 @@ Exports that are public but not yet assigned to a feature group.
 | `PageMatcher` | type | Selects a top-level page by `url` and/or `title` for {@link Browser.waitForPage}. A string matches as a substring; a `RegExp` is tested. When both fields are given, both must match. | [browser-api](browser-api.md) |
 | `RemoteAuth` | type | — | — |
 | `RemoteWebDriverOptions` | type | Options for connecting to any W3C-compatible remote WebDriver endpoint — a self-hosted Selenium Grid, BrowserStack, or another cloud provider. Provider-specific detail (BrowserStack's `bstack:options`, etc.) is forwarded through `capabilities` without schema conversion. | — |
+| `SessionStateCookie` | type | — | — |
 
-Total exports: **86**.
+Total exports: **94**.

package/docs/browser-api.md

@@ -29,7 +29,7 @@ const browser = await Browser.launch({
 |--------|------|---------|-------------|
 | `browserName` | `'chrome' \| 'chromium' \| 'firefox' \| 'safari'`; any non-empty `string` remotely | `'chrome'` | Local browser to launch or provider-facing remote browser name |
 | `enableBiDi` | `boolean` | browsers: `true`; Electron: `false` | Use WebDriver BiDi. Electron requires an explicit opt-in because negotiation resets its initial renderer to `about:blank`. |
-| `storageState` | `string` | — | Path to a session-state JSON file to load on startup |
+| `storageState` | `string \| SessionState` | — | Native session-state path/object. Full cookies + multi-origin localStorage on supported BiDi; non-empty state is rejected at Classic launch. |
 | `mobileEmulation` | `MobileEmulation \| DeviceName` | — | Mobile device emulation settings (Chrome/Chromium only) |
 | `downloadsDir` | `string` | temp dir | Directory where downloaded files are saved |
 | `browserPath` | `string` | — | Custom browser binary to launch (Chrome/Chromium/Firefox) — see [Driver Configuration → Browser Binary Configuration](./driver-configuration.md#browser-binary-configuration) |
@@ -334,9 +334,20 @@ await popup.waitForLoadState('load');
 const heading = await popup.find('h1').text();
 console.log(heading);
 
-await popup.evaluate(() => {
-  window.close();
-});
+// Close it. Prefer this over `popup.evaluate(() => window.close())`, which
+// leaves no window focused — every later command then fails with
+// "no such window". `close()` switches to a surviving page for you.
+await popup.close();
+```
+
+Use `page.activate()` to make a page the target of browser-level helpers.
+Most page methods switch to their window and switch back, so they never
+disturb `browser.activePage()`; `activate()` is the deliberate exception:
+
+```ts
+const [, second] = await browser.pages();
+await second.activate();
+await browser.click('#confirm');   // acts on the second tab
 ```
 
 > **Note.** `browser.openPage()` requires BiDi (the default). In Classic
@@ -378,8 +389,17 @@ await browser.saveState('./session.json');
 
 // Load session from file
 await browser.loadState('./session.json');
+
+// Or use an in-memory SessionState object
+await browser.loadState(await browser.storage.getState());
 ```
 
+On Chrome/Chromium and Firefox BiDi, launch and `browser.loadState()` restore
+cookies plus multi-origin localStorage before the first real navigation. In
+Classic mode, launch rejects non-empty state; navigate to the sole origin, call
+`browser.loadState()`, then reload. See
+[Session Management](./session-management.md#browser-and-transport-support).
+
 ## Evaluate
 
 Run JavaScript in the page and get the result back. Useful for reading app state,

package/docs/browser-context.md

@@ -120,9 +120,8 @@ Create a new isolated user context. Backed by BiDi
 `browser.createUserContext`. Throws in Classic mode.
 
 - `opts.storageState`: a `SessionState` object **or** a path to a JSON
-  file produced by `BrowserContext.saveStorageState()`. Cookies are
-  applied immediately; localStorage entries land on first navigation to
-  each captured origin via an internal preload script.
+  file produced by `BrowserContext.saveStorageState()`. Cookies and every
+  captured localStorage origin are restored before `newContext()` resolves.
 - `opts.baseURL`: a base URL applied to every relative `url` passed to
   `ctx.newPage()` or `page.navigateTo()` inside the context. Absolute
   URLs pass through unchanged. Lets your tests say `'/login'` instead
@@ -230,11 +229,17 @@ snapshot for inspection. See the auth-fixture example above.
 ### `BrowserContext.loadStorageState(source): Promise<void>`
 
 Apply a previously-captured snapshot. `source` is a `SessionState`
-object or a path to JSON produced by `saveStorageState`. Cookies are
-applied immediately; localStorage entries are installed via a preload
-script that runs on first navigation to each captured origin. Calling
-`loadStorageState` again replaces the previous preload — it does not
-stack.
+object or a path to JSON produced by `saveStorageState`. localStorage is
+seeded once per captured origin through a private, locally fulfilled document;
+cookies are then applied to the same user-context partition. The method resolves
+after hydration and cleanup, so the first real page script sees the state.
+Calling `loadStorageState` again applies another ordered overlay; application
+changes remain owned by the application and survive reload.
+
+Restores in one context are serialized. Different user contexts may restore in
+parallel. A runtime protocol failure on an existing context throws
+`DRIVER_ERROR` with `detail.phase` and `detail.partialApplied`; use a newly
+created context when failure isolation is required.
 
 ### `BrowserContext.close(): Promise<void>`
 
@@ -479,10 +484,11 @@ A default `browser.newContext()` (no options) is always cross-browser.
 
 A few things that aren't bugs but bite if you don't know them:
 
-- **`storageState` covers cookies + localStorage only.** Not
-  sessionStorage, not IndexedDB, not Cache Storage. Apps that put their
-  auth token in sessionStorage (some Auth0 / MSAL fallback configs) will
-  need a custom restore step.
+- **`storageState` covers cookies + localStorage only.** Not reusable
+  sessionStorage, IndexedDB, or Cache Storage. A non-empty sessionStorage
+  section is rejected by context/launch APIs rather than ignored. Use the
+  active-page `browser.loadState()` fallback for one matching sessionStorage
+  origin, or a custom login step.
 - **Browser-level vs context-level emulation race.** `browser.setGeolocation(...)`
   is a session-wide override; `ctx.setGeolocation(...)` is a per-context
   override. If both are set, the context-level one wins inside the