craftdriver 1.6.0 → 1.8.0

package/dist/lib/visual/expectScreenshot.js

@@ -0,0 +1,287 @@
+/**
+ * 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 { readFile as fsReadFile, writeFile as fsWriteFile, mkdir as fsMkdir, rename as fsRename, unlink as fsUnlink, } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+import { By } from '../by.js';
+import { CraftdriverError, ErrorCode } from '../errors.js';
+import { VISUAL_RETRY_INTERVAL_MS } from '../timing.js';
+import { pngjsCodec } from './pngjsCodec.js';
+import { validatePngHeaderAndSize } from './pngHeader.js';
+import { compareDecoded, resolveCompareOptions } from './compare.js';
+import { createDiff } from './diff.js';
+import { VisualMismatchError } from './visualError.js';
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const defaultReport = (message) => {
+    process.stderr.write(`[craftdriver] ${message}\n`);
+};
+function invalid(message, detail) {
+    throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, message, detail ? { detail } : undefined);
+}
+function isFileNotFound(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'code' in err &&
+        err.code === 'ENOENT');
+}
+/**
+ * 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 function shouldUpdateVisualBaselines(raw) {
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    if (value === '' || value === 'false')
+        return false;
+    if (value === 'true')
+        return true;
+    invalid(`CRAFTDRIVER_UPDATE_VISUAL_BASELINES must be "true" or "false" (or unset), got ${JSON.stringify(raw)}.`, { value: raw });
+}
+/** Validate the retry-specific options (compare options are validated separately). */
+function resolveRetryOptions(options, defaultTimeout) {
+    const timeout = options.timeout ?? defaultTimeout;
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        invalid(`timeout must be a finite number >= 0, got ${timeout}.`, { timeout });
+    }
+    const interval = options.interval ?? VISUAL_RETRY_INTERVAL_MS;
+    if (!Number.isInteger(interval) || interval < 10) {
+        invalid(`interval must be an integer >= 10 ms, got ${interval}.`, { interval });
+    }
+    // Validate the capture scope's shape for JavaScript callers (TS already
+    // constrains it): correct field types, then the fullPage/selector exclusion.
+    const scope = options.screenshot;
+    if (scope !== undefined) {
+        if (typeof scope !== 'object' || scope === null) {
+            invalid('screenshot must be an object with { fullPage } or { selector }.');
+        }
+        const hasFullPage = 'fullPage' in scope && scope.fullPage !== undefined;
+        const hasSelector = 'selector' in scope && scope.selector !== undefined;
+        if (hasFullPage && typeof scope.fullPage !== 'boolean') {
+            invalid('screenshot.fullPage must be a boolean.');
+        }
+        if (hasSelector) {
+            const selector = scope.selector;
+            if (typeof selector !== 'string' && !(selector instanceof By)) {
+                invalid('screenshot.selector must be a string or a By locator.');
+            }
+        }
+        if (hasFullPage && scope.fullPage === true && hasSelector) {
+            invalid('screenshot.fullPage and screenshot.selector are mutually exclusive.');
+        }
+    }
+    return { timeout, interval };
+}
+/** A monotonic deadline built once, queried throughout a run. */
+function makeClock(now, timeout) {
+    const start = now();
+    const deadline = start + timeout;
+    return {
+        elapsed: () => now() - start,
+        remaining: () => Math.max(0, deadline - now()),
+        expired: () => now() >= deadline,
+    };
+}
+export async function runExpectScreenshot(deps) {
+    const { expectedPath, options, defaultTimeout, capture } = deps;
+    const update = deps.update ?? false;
+    const readFile = deps.readFile ?? fsReadFile;
+    const writeFile = deps.writeFile ?? fsWriteFile;
+    const rename = deps.rename ?? fsRename;
+    const unlink = deps.unlink ?? fsUnlink;
+    const mkdir = deps.mkdir ?? fsMkdir;
+    const report = deps.report ?? defaultReport;
+    const now = deps.now ?? (() => performance.now());
+    const sleep = deps.sleep ?? realSleep;
+    const codec = deps.codec ?? pngjsCodec;
+    const compareOpts = resolveCompareOptions(options);
+    const { timeout, interval } = resolveRetryOptions(options, defaultTimeout);
+    const limits = { maxImagePixels: compareOpts.maxImagePixels, maxInputBytes: compareOpts.maxInputBytes };
+    /**
+     * Write a baseline atomically: the PNG is written in full to a uniquely-named
+     * temporary file in the destination's own directory, then renamed over the
+     * destination. A crash, disk error, or partial write therefore never leaves a
+     * truncated or half-updated committed baseline — the old file survives intact.
+     * On any failure the temp file is best-effort removed and the error rethrown.
+     */
+    const writeBaselineAtomically = async (destination, data) => {
+        const tmp = `${destination}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+        try {
+            await writeFile(tmp, data);
+            await rename(tmp, destination);
+        }
+        catch (err) {
+            await unlink(tmp).catch(() => { });
+            throw err;
+        }
+    };
+    /**
+     * No baseline on disk yet: capture until two consecutive frames are
+     * byte-identical (or the timeout elapses) so we don't enshrine a mid-animation
+     * frame, then write that settled capture as the new baseline and pass.
+     */
+    const createMissingBaseline = async () => {
+        const clock = makeClock(now, timeout);
+        let settled;
+        let settledDims;
+        let attempts = 0;
+        let didSettle = false;
+        for (;;) {
+            const buffer = await capture(clock.remaining());
+            attempts++;
+            const dims = validatePngHeaderAndSize(buffer, limits, 'screenshot');
+            const isSettled = settled !== undefined && settled.equals(buffer);
+            settled = buffer;
+            settledDims = dims;
+            if (isSettled) {
+                didSettle = true;
+                break;
+            }
+            if (clock.expired())
+                break;
+            await sleep(Math.min(interval, clock.remaining()));
+        }
+        await mkdir(dirname(expectedPath), { recursive: true });
+        await writeBaselineAtomically(expectedPath, settled);
+        // Warn on every unsettled write — including `timeout: 0`, which deliberately
+        // takes a single capture — so an arbitrary frame is never written silently.
+        // We still create the baseline (a page with a live region would otherwise be
+        // impossible to baseline); the message just flags the frame for review.
+        report(didSettle
+            ? `Created visual baseline: ${expectedPath}`
+            : `Created visual baseline (page did not settle within ${timeout}ms — review it before committing): ${expectedPath}`);
+        return {
+            matches: true,
+            diffPixels: 0,
+            diffPercentage: 0,
+            ignoredAntialiasPixels: 0,
+            expectedWidth: settledDims.width,
+            expectedHeight: settledDims.height,
+            actualWidth: settledDims.width,
+            actualHeight: settledDims.height,
+            dimensionMismatch: false,
+            attempts,
+            elapsedMs: clock.elapsed(),
+            baseline: 'created',
+        };
+    };
+    // Read + validate the baseline once, before the deadline starts, so `timeout`
+    // measures browser stabilization time rather than disk latency. A missing file
+    // is the create signal; any other read error stays a caller-facing failure.
+    let expectedBuffer;
+    try {
+        expectedBuffer = await readFile(expectedPath);
+    }
+    catch (err) {
+        if (!isFileNotFound(err))
+            throw err;
+        return createMissingBaseline();
+    }
+    const expectedDims = validatePngHeaderAndSize(expectedBuffer, limits, 'baseline');
+    const clock = makeClock(now, timeout);
+    let expectedImage;
+    let previousActualBuffer;
+    let previousActualImage;
+    let previousComparison;
+    let attempts = 0;
+    for (;;) {
+        const actualBuffer = await capture(clock.remaining());
+        attempts++;
+        // Fast path 1: identical PNG bytes necessarily means identical pixels.
+        if (expectedBuffer.length === actualBuffer.length && expectedBuffer.equals(actualBuffer)) {
+            return {
+                matches: true,
+                diffPixels: 0,
+                diffPercentage: 0,
+                ignoredAntialiasPixels: 0,
+                expectedWidth: expectedDims.width,
+                expectedHeight: expectedDims.height,
+                actualWidth: expectedDims.width,
+                actualHeight: expectedDims.height,
+                dimensionMismatch: false,
+                attempts,
+                elapsedMs: clock.elapsed(),
+                baseline: 'matched',
+            };
+        }
+        // Fast path 2: an unchanged failed screenshot has the same comparison result.
+        if (previousActualBuffer?.equals(actualBuffer)) {
+            if (clock.expired())
+                break;
+            await sleep(Math.min(interval, clock.remaining()));
+            continue;
+        }
+        validatePngHeaderAndSize(actualBuffer, limits, 'screenshot');
+        expectedImage ??= await codec.decode(expectedBuffer);
+        const actualImage = await codec.decode(actualBuffer);
+        const comparison = compareDecoded(actualImage, expectedImage, compareOpts);
+        if (comparison.matches) {
+            return { ...comparison, attempts, elapsedMs: clock.elapsed(), baseline: 'matched' };
+        }
+        // Retain only the most recent failed attempt — never every retry image.
+        previousActualBuffer = actualBuffer;
+        previousActualImage = actualImage;
+        previousComparison = { ...comparison, attempts, elapsedMs: clock.elapsed(), baseline: 'matched' };
+        if (clock.expired())
+            break;
+        await sleep(Math.min(interval, clock.remaining()));
+    }
+    // The page never settled into a match. Either accept the new rendering by
+    // overwriting the baseline (update mode), or fail with the diff.
+    if (update) {
+        await writeBaselineAtomically(expectedPath, previousActualBuffer);
+        report(`Updated visual baseline: ${expectedPath} ` +
+            `(${previousComparison.diffPixels} px, ${previousComparison.diffPercentage.toFixed(2)}% changed)`);
+        return {
+            matches: true,
+            diffPixels: 0,
+            diffPercentage: 0,
+            ignoredAntialiasPixels: 0,
+            expectedWidth: previousComparison.actualWidth,
+            expectedHeight: previousComparison.actualHeight,
+            actualWidth: previousComparison.actualWidth,
+            actualHeight: previousComparison.actualHeight,
+            dimensionMismatch: false,
+            attempts,
+            elapsedMs: clock.elapsed(),
+            baseline: 'updated',
+        };
+    }
+    // Final failure: reuse the retained decoded images, paint the diff once, encode once.
+    const rawDiff = createDiff(previousActualImage, expectedImage, compareOpts);
+    const diff = await codec.encode(rawDiff);
+    throw new VisualMismatchError(previousActualBuffer, diff, {
+        expectedPath,
+        timeout,
+        attempts,
+        elapsedMs: clock.elapsed(),
+        comparison: previousComparison,
+    });
+}
+//# sourceMappingURL=expectScreenshot.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expectScreenshot.js","sourceRoot":"","sources":["../../../src/lib/visual/expectScreenshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,QAAQ,IAAI,UAAU,EACtB,SAAS,IAAI,WAAW,EACxB,KAAK,IAAI,OAAO,EAChB,MAAM,IAAI,QAAQ,EAClB,MAAM,IAAI,QAAQ,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAgCvD,MAAM,SAAS,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEvF,MAAM,aAAa,GAAG,CAAC,OAAe,EAAQ,EAAE;IAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,OAAO,IAAI,CAAC,CAAC;AACrD,CAAC,CAAC;AAEF,SAAS,OAAO,CAAC,OAAe,EAAE,MAAgC;IAChE,MAAM,IAAI,gBAAgB,CAAC,SAAS,CAAC,gBAAgB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAClC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACZ,GAA0B,CAAC,IAAI,KAAK,QAAQ,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAuB;IACjE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,CACL,iFAAiF,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EACvG,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,SAAS,mBAAmB,CAC1B,OAAgC,EAChC,cAAsB;IAEtB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO,CAAC,6CAA6C,OAAO,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,wBAAwB,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,EAAE,EAAE,CAAC;QACjD,OAAO,CAAC,6CAA6C,QAAQ,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,wEAAwE;IACxE,6EAA6E;IAC7E,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,OAAO,CAAC,iEAAiE,CAAC,CAAC;QAC7E,CAAC;QACD,MAAM,WAAW,GAAG,UAAU,IAAI,KAAK,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC;QACxE,MAAM,WAAW,GAAG,UAAU,IAAI,KAAK,IAAK,KAAgC,CAAC,QAAQ,KAAK,SAAS,CAAC;QACpG,IAAI,WAAW,IAAI,OAAQ,KAAgC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnF,OAAO,CAAC,wCAAwC,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,QAAQ,GAAI,KAAgC,CAAC,QAAQ,CAAC;YAC5D,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,YAAY,EAAE,CAAC,EAAE,CAAC;gBAC9D,OAAO,CAAC,uDAAuD,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;QACD,IAAI,WAAW,IAAK,KAAgC,CAAC,QAAQ,KAAK,IAAI,IAAI,WAAW,EAAE,CAAC;YACtF,OAAO,CAAC,qEAAqE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,iEAAiE;AACjE,SAAS,SAAS,CAAC,GAAiB,EAAE,OAAe;IACnD,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC;IACpB,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;IACjC,OAAO;QACL,OAAO,EAAE,GAAW,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK;QACpC,SAAS,EAAE,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,GAAG,EAAE,CAAC;QACtD,OAAO,EAAE,GAAY,EAAE,CAAC,GAAG,EAAE,IAAI,QAAQ;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAA6B;IACrE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC;IAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,WAAW,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC;IAEvC,MAAM,WAAW,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,EAAE,cAAc,EAAE,WAAW,CAAC,cAAc,EAAE,aAAa,EAAE,WAAW,CAAC,aAAa,EAAE,CAAC;IAExG;;;;;;OAMG;IACH,MAAM,uBAAuB,GAAG,KAAK,EAAE,WAAmB,EAAE,IAAY,EAAiB,EAAE;QACzF,MAAM,GAAG,GAAG,GAAG,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QAClF,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC3B,MAAM,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAClC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,qBAAqB,GAAG,KAAK,IAAoC,EAAE;QACvE,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,OAA2B,CAAC;QAChC,IAAI,WAA0D,CAAC;QAC/D,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,SAAS,CAAC;YACR,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAChD,QAAQ,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;YACpE,MAAM,SAAS,GAAG,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAClE,OAAO,GAAG,MAAM,CAAC;YACjB,WAAW,GAAG,IAAI,CAAC;YACnB,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,GAAG,IAAI,CAAC;gBACjB,MAAM;YACR,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,EAAE;gBAAE,MAAM;YAC3B,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC;QAED,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,uBAAuB,CAAC,YAAY,EAAE,OAAQ,CAAC,CAAC;QACtD,6EAA6E;QAC7E,4EAA4E;QAC5E,6EAA6E;QAC7E,wEAAwE;QACxE,MAAM,CACJ,SAAS;YACP,CAAC,CAAC,4BAA4B,YAAY,EAAE;YAC5C,CAAC,CAAC,uDAAuD,OAAO,sCAAsC,YAAY,EAAE,CACvH,CAAC;QACF,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,CAAC;YACb,cAAc,EAAE,CAAC;YACjB,sBAAsB,EAAE,CAAC;YACzB,aAAa,EAAE,WAAY,CAAC,KAAK;YACjC,cAAc,EAAE,WAAY,CAAC,MAAM;YACnC,WAAW,EAAE,WAAY,CAAC,KAAK;YAC/B,YAAY,EAAE,WAAY,CAAC,MAAM;YACjC,iBAAiB,EAAE,KAAK;YACxB,QAAQ;YACR,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE;YAC1B,QAAQ,EAAE,SAAS;SACpB,CAAC;IACJ,CAAC,CAAC;IAEF,8EAA8E;IAC9E,+EAA+E;IAC/E,4EAA4E;IAC5E,IAAI,cAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,cAAc,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;QACpC,OAAO,qBAAqB,EAAE,CAAC;IACjC,CAAC;IACD,MAAM,YAAY,GAAG,wBAAwB,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAElF,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAEtC,IAAI,aAAuC,CAAC;IAC5C,IAAI,oBAAwC,CAAC;IAC7C,IAAI,mBAA6C,CAAC;IAClD,IAAI,kBAAqD,CAAC;IAC1D,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,SAAS,CAAC;QACR,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QACtD,QAAQ,EAAE,CAAC;QAEX,uEAAuE;QACvE,IAAI,cAAc,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;YACzF,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,UAAU,EAAE,CAAC;gBACb,cAAc,EAAE,CAAC;gBACjB,sBAAsB,EAAE,CAAC;gBACzB,aAAa,EAAE,YAAY,CAAC,KAAK;gBACjC,cAAc,EAAE,YAAY,CAAC,MAAM;gBACnC,WAAW,EAAE,YAAY,CAAC,KAAK;gBAC/B,YAAY,EAAE,YAAY,CAAC,MAAM;gBACjC,iBAAiB,EAAE,KAAK;gBACxB,QAAQ;gBACR,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE;gBAC1B,QAAQ,EAAE,SAAS;aACpB,CAAC;QACJ,CAAC;QAED,8EAA8E;QAC9E,IAAI,oBAAoB,EAAE,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/C,IAAI,KAAK,CAAC,OAAO,EAAE;gBAAE,MAAM;YAC3B,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;YACnD,SAAS;QACX,CAAC;QAED,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;QAC7D,aAAa,KAAK,MAAM,KAAK,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACrD,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACrD,MAAM,UAAU,GAAG,cAAc,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;QAE3E,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;YACvB,OAAO,EAAE,GAAG,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QACtF,CAAC;QAED,wEAAwE;QACxE,oBAAoB,GAAG,YAAY,CAAC;QACpC,mBAAmB,GAAG,WAAW,CAAC;QAClC,kBAAkB,GAAG,EAAE,GAAG,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QAElG,IAAI,KAAK,CAAC,OAAO,EAAE;YAAE,MAAM;QAC3B,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,0EAA0E;IAC1E,iEAAiE;IACjE,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,uBAAuB,CAAC,YAAY,EAAE,oBAAqB,CAAC,CAAC;QACnE,MAAM,CACJ,4BAA4B,YAAY,GAAG;YACzC,IAAI,kBAAmB,CAAC,UAAU,QAAQ,kBAAmB,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CACtG,CAAC;QACF,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,CAAC;YACb,cAAc,EAAE,CAAC;YACjB,sBAAsB,EAAE,CAAC;YACzB,aAAa,EAAE,kBAAmB,CAAC,WAAW;YAC9C,cAAc,EAAE,kBAAmB,CAAC,YAAY;YAChD,WAAW,EAAE,kBAAmB,CAAC,WAAW;YAC5C,YAAY,EAAE,kBAAmB,CAAC,YAAY;YAC9C,iBAAiB,EAAE,KAAK;YACxB,QAAQ;YACR,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE;YAC1B,QAAQ,EAAE,SAAS;SACpB,CAAC;IACJ,CAAC;IAED,sFAAsF;IACtF,MAAM,OAAO,GAAG,UAAU,CAAC,mBAAoB,EAAE,aAAc,EAAE,WAAW,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,IAAI,mBAAmB,CAAC,oBAAqB,EAAE,IAAI,EAAE;QACzD,YAAY;QACZ,OAAO;QACP,QAAQ;QACR,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE;QAC1B,UAAU,EAAE,kBAAmB;KAChC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Controlled exports for the visual-testing feature. The public entrypoint
+ * (`src/index.ts`) re-exports from here; pngjs and other codec internals are
+ * never surfaced.
+ */
+export { compareScreenshots } from './compare.js';
+export { VisualMismatchError } from './visualError.js';
+export { runExpectScreenshot, shouldUpdateVisualBaselines, type CaptureFn, } from './expectScreenshot.js';
+export type { ScreenshotCompareOptions, ExpectScreenshotOptions, VisualScreenshotOptions, VisualComparisonResult, ScreenshotMatchResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,KAAK,SAAS,GACf,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/lib/visual/index.js

@@ -0,0 +1,9 @@
+/**
+ * Controlled exports for the visual-testing feature. The public entrypoint
+ * (`src/index.ts`) re-exports from here; pngjs and other codec internals are
+ * never surfaced.
+ */
+export { compareScreenshots } from './compare.js';
+export { VisualMismatchError } from './visualError.js';
+export { runExpectScreenshot, shouldUpdateVisualBaselines, } from './expectScreenshot.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/visual/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,2BAA2B,GAE5B,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * Low-level per-pixel math shared by the comparison loop and the anti-alias
+ * detector. Kept in its own module so `compare.ts` and `antialias.ts` can both
+ * use it without an import cycle.
+ *
+ * Every visible-colour computation composites over a **white** background. Two
+ * fully transparent pixels therefore composite to white and compare equal, and
+ * hidden RGB bytes under alpha zero never influence the result. This is the
+ * single documented background used everywhere: ordinary comparison, sibling
+ * equality, and the anti-alias brightness heuristic. If any of them used a
+ * different background they would disagree about transparent pixels.
+ */
+/** Composite one 0..255 channel with 0..255 alpha over a white background. */
+export declare function blendOverWhite(channel: number, alpha: number): number;
+/** ITU-R BT.601 luma of an already-composited RGB triple. */
+export declare function rgb2y(r: number, g: number, b: number): number;
+/** Read a pixel's white-composited visible RGB into `out` (length ≥ 3). */
+export declare function visibleRgb(data: Uint8Array, pos: number, out: number[]): void;
+/**
+ * Brightness (luma) delta between two pixels of the same image, both composited
+ * over white. This is Pixelmatch's `colorDelta(..., yOnly=true)` with
+ * `checkerboard: false`, i.e. white compositing to match craftdriver's contract.
+ */
+export declare function brightnessDelta(data: Uint8Array, pos1: number, pos2: number): number;
+/**
+ * Whether two pixels have the same white-composited visible colour. Used for
+ * sibling counting in the AA heuristic — deliberately compares visible colour,
+ * not the raw RGBA bytes, so transparent pixels with differing hidden RGB still
+ * count as identical siblings.
+ */
+export declare function visibleEqual(data: Uint8Array, pos1: number, pos2: number): boolean;
+//# sourceMappingURL=pixelMath.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pixelMath.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/pixelMath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,6DAA6D;AAC7D,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAW7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAUpF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAelF"}

package/dist/lib/visual/pixelMath.js

@@ -0,0 +1,70 @@
+/**
+ * Low-level per-pixel math shared by the comparison loop and the anti-alias
+ * detector. Kept in its own module so `compare.ts` and `antialias.ts` can both
+ * use it without an import cycle.
+ *
+ * Every visible-colour computation composites over a **white** background. Two
+ * fully transparent pixels therefore composite to white and compare equal, and
+ * hidden RGB bytes under alpha zero never influence the result. This is the
+ * single documented background used everywhere: ordinary comparison, sibling
+ * equality, and the anti-alias brightness heuristic. If any of them used a
+ * different background they would disagree about transparent pixels.
+ */
+/** Composite one 0..255 channel with 0..255 alpha over a white background. */
+export function blendOverWhite(channel, alpha) {
+    // 255 + (channel - 255) * (alpha / 255): alpha 255 → channel, alpha 0 → white.
+    return 255 + ((channel - 255) * alpha) / 255;
+}
+/** ITU-R BT.601 luma of an already-composited RGB triple. */
+export function rgb2y(r, g, b) {
+    return r * 0.29889531 + g * 0.58662247 + b * 0.11448223;
+}
+/** Read a pixel's white-composited visible RGB into `out` (length ≥ 3). */
+export function visibleRgb(data, pos, out) {
+    const a = data[pos + 3];
+    if (a === 255) {
+        out[0] = data[pos];
+        out[1] = data[pos + 1];
+        out[2] = data[pos + 2];
+    }
+    else {
+        out[0] = blendOverWhite(data[pos], a);
+        out[1] = blendOverWhite(data[pos + 1], a);
+        out[2] = blendOverWhite(data[pos + 2], a);
+    }
+}
+/**
+ * Brightness (luma) delta between two pixels of the same image, both composited
+ * over white. This is Pixelmatch's `colorDelta(..., yOnly=true)` with
+ * `checkerboard: false`, i.e. white compositing to match craftdriver's contract.
+ */
+export function brightnessDelta(data, pos1, pos2) {
+    const a1 = data[pos1 + 3];
+    const a2 = data[pos2 + 3];
+    const r1 = a1 === 255 ? data[pos1] : blendOverWhite(data[pos1], a1);
+    const g1 = a1 === 255 ? data[pos1 + 1] : blendOverWhite(data[pos1 + 1], a1);
+    const b1 = a1 === 255 ? data[pos1 + 2] : blendOverWhite(data[pos1 + 2], a1);
+    const r2 = a2 === 255 ? data[pos2] : blendOverWhite(data[pos2], a2);
+    const g2 = a2 === 255 ? data[pos2 + 1] : blendOverWhite(data[pos2 + 1], a2);
+    const b2 = a2 === 255 ? data[pos2 + 2] : blendOverWhite(data[pos2 + 2], a2);
+    return rgb2y(r1, g1, b1) - rgb2y(r2, g2, b2);
+}
+/**
+ * Whether two pixels have the same white-composited visible colour. Used for
+ * sibling counting in the AA heuristic — deliberately compares visible colour,
+ * not the raw RGBA bytes, so transparent pixels with differing hidden RGB still
+ * count as identical siblings.
+ */
+export function visibleEqual(data, pos1, pos2) {
+    const a1 = data[pos1 + 3];
+    const a2 = data[pos2 + 3];
+    if (a1 === 255 && a2 === 255) {
+        return (data[pos1] === data[pos2] &&
+            data[pos1 + 1] === data[pos2 + 1] &&
+            data[pos1 + 2] === data[pos2 + 2]);
+    }
+    return (blendOverWhite(data[pos1], a1) === blendOverWhite(data[pos2], a2) &&
+        blendOverWhite(data[pos1 + 1], a1) === blendOverWhite(data[pos2 + 1], a2) &&
+        blendOverWhite(data[pos1 + 2], a1) === blendOverWhite(data[pos2 + 2], a2));
+}
+//# sourceMappingURL=pixelMath.js.map

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * Cheap, allocation-bounding PNG validation performed *before* a buffer is
+ * handed to pngjs.
+ *
+ * This is deliberately not a decoder. It reads only the 8-byte signature and
+ * the fixed-layout IHDR chunk to learn the declared dimensions, so a
+ * hostile/corrupt header cannot make the decoder allocate a huge RGBA array
+ * before the real (CRC-checked) decode runs. Both limits are enforced with
+ * overflow-safe arithmetic. The same checks apply to the baseline and to every
+ * unique actual screenshot.
+ */
+export interface PngSizeLimits {
+    maxImagePixels: number;
+    maxInputBytes: number;
+}
+/** Where this buffer came from, for a clearer error message. */
+export type PngSource = 'baseline' | 'screenshot';
+/**
+ * Validate a compressed PNG's signature, IHDR, declared dimensions, and both
+ * size limits. Returns the parsed dimensions so callers can reuse them. Throws
+ * {@link CraftdriverError} with `INVALID_ARGUMENT` on any violation.
+ */
+export declare function validatePngHeaderAndSize(buffer: Uint8Array, limits: PngSizeLimits, source: PngSource): {
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=pngHeader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pngHeader.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/pngHeader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC;AAQlD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,SAAS,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA2CnC"}

package/dist/lib/visual/pngHeader.js

@@ -0,0 +1,63 @@
+/**
+ * Cheap, allocation-bounding PNG validation performed *before* a buffer is
+ * handed to pngjs.
+ *
+ * This is deliberately not a decoder. It reads only the 8-byte signature and
+ * the fixed-layout IHDR chunk to learn the declared dimensions, so a
+ * hostile/corrupt header cannot make the decoder allocate a huge RGBA array
+ * before the real (CRC-checked) decode runs. Both limits are enforced with
+ * overflow-safe arithmetic. The same checks apply to the baseline and to every
+ * unique actual screenshot.
+ */
+import { CraftdriverError, ErrorCode } from '../errors.js';
+/** 8-byte PNG magic signature. */
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Byte offset of the IHDR chunk's length field (immediately after the signature). */
+const IHDR_LENGTH_OFFSET = 8;
+/** IHDR chunk data is a fixed 13 bytes. */
+const IHDR_DATA_LENGTH = 13;
+/** Minimum bytes we must see to read the full IHDR: sig + len(4) + type(4) + data(13) + crc(4). */
+const MIN_HEADER_BYTES = IHDR_LENGTH_OFFSET + 4 + 4 + IHDR_DATA_LENGTH + 4;
+function fail(source, message, detail) {
+    throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `${source} ${message}`, {
+        detail: { source, ...detail },
+    });
+}
+/**
+ * Validate a compressed PNG's signature, IHDR, declared dimensions, and both
+ * size limits. Returns the parsed dimensions so callers can reuse them. Throws
+ * {@link CraftdriverError} with `INVALID_ARGUMENT` on any violation.
+ */
+export function validatePngHeaderAndSize(buffer, limits, source) {
+    if (buffer.length > limits.maxInputBytes) {
+        fail(source, `PNG is ${buffer.length} bytes, exceeding the ${limits.maxInputBytes}-byte limit.`, {
+            inputBytes: buffer.length,
+            maxInputBytes: limits.maxInputBytes,
+        });
+    }
+    if (buffer.length < MIN_HEADER_BYTES) {
+        fail(source, 'PNG is too small to contain a valid header.', { inputBytes: buffer.length });
+    }
+    const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    if (!buf.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        fail(source, 'buffer is not a PNG (bad signature).');
+    }
+    const ihdrLength = buf.readUInt32BE(IHDR_LENGTH_OFFSET);
+    const ihdrType = buf.toString('ascii', IHDR_LENGTH_OFFSET + 4, IHDR_LENGTH_OFFSET + 8);
+    if (ihdrType !== 'IHDR' || ihdrLength !== IHDR_DATA_LENGTH) {
+        fail(source, 'PNG has an invalid IHDR chunk.', { ihdrType, ihdrLength });
+    }
+    const dataOffset = IHDR_LENGTH_OFFSET + 8;
+    const width = buf.readUInt32BE(dataOffset);
+    const height = buf.readUInt32BE(dataOffset + 4);
+    if (width === 0 || height === 0) {
+        fail(source, `PNG has zero dimension (${width}x${height}).`, { width, height });
+    }
+    // Overflow-safe: compare against the limit using division so width*height
+    // never overflows a JS safe integer for adversarial 2^32-scale dimensions.
+    if (width > limits.maxImagePixels || height > limits.maxImagePixels / width) {
+        fail(source, `PNG is ${width}x${height} pixels, exceeding the ${limits.maxImagePixels}-pixel limit.`, { width, height, pixels: width * height, maxImagePixels: limits.maxImagePixels });
+    }
+    return { width, height };
+}
+//# sourceMappingURL=pngHeader.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * 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 type { PngCodec } from './codec.js';
+export declare const pngjsCodec: PngCodec;
+//# sourceMappingURL=pngjsCodec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pngjsCodec.d.ts","sourceRoot":"","sources":["../../../src/lib/visual/pngjsCodec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAwDzD,eAAO,MAAM,UAAU,EAAE,QAA6B,CAAC"}