game-harness 1.0.0

package/dist/esm/production-runtime.js

@@ -0,0 +1,304 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { chromium } from '@playwright/test';
+import getPort from 'get-port';
+import { createChromiumLaunchProfile } from './chromium-launch.js';
+import { openSilentGame, } from './playwright-config.js';
+/**
+ * Thrown by every failure path in this module — an unreachable/occupied
+ * readiness URL, a server that never became ready, a masked or
+ * software-rendered WebGL context, a changed localStorage sentinel, or one
+ * or more recorded {@link ProductionRuntimeIssue}s. Callers can inspect
+ * `.issues` for the underlying runtime errors instead of parsing `.message`.
+ */
+export class ProductionRuntimeVerificationError extends Error {
+    /** Runtime issues recorded before this error was thrown, if any. Empty for pure validation failures. */
+    issues;
+    constructor(message, issues = [], cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'ProductionRuntimeVerificationError';
+        this.issues = issues;
+    }
+}
+function validateHttpUrl(label, value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new ProductionRuntimeVerificationError(`${label} must not be empty`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch (error) {
+        throw new ProductionRuntimeVerificationError(`${label} must be a valid absolute URL`, [], error);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new ProductionRuntimeVerificationError(`${label} must use http or https`);
+    }
+    return trimmed;
+}
+function validateDuration(label, value, allowZero) {
+    if (value === undefined)
+        return;
+    if (!Number.isFinite(value) || (allowZero ? value < 0 : value <= 0)) {
+        throw new ProductionRuntimeVerificationError(`${label} must be a ${allowZero ? 'non-negative' : 'positive'} finite number`);
+    }
+}
+/**
+ * Finds and process-reserves an available loopback port for an owned production
+ * preview. The reservation prevents parallel verifier setup in this process
+ * from selecting the same port; the preview must still bind with strict-port
+ * semantics so an external race fails closed.
+ */
+export async function findAvailableProductionPort(options = {}) {
+    return getPort({ host: options.host ?? '127.0.0.1', reserve: true });
+}
+async function probe(url) {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(1_000) });
+        const result = {
+            reachable: true,
+            ok: response.ok,
+            status: response.status,
+        };
+        try {
+            await response.body?.cancel();
+        }
+        catch {
+            // Reachability is already proven. A stream-cleanup failure must not make
+            // an occupied address look free or make a ready server look unreachable.
+        }
+        return result;
+    }
+    catch {
+        return { reachable: false, ok: false };
+    }
+}
+function childExited(child) {
+    return child.exitCode !== null || child.signalCode !== null;
+}
+async function waitForChildExit(child, timeoutMs) {
+    if (childExited(child))
+        return true;
+    return new Promise((resolve) => {
+        const finish = (exited) => {
+            clearTimeout(timer);
+            child.off('exit', onExit);
+            resolve(exited);
+        };
+        const onExit = () => finish(true);
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        child.once('exit', onExit);
+    });
+}
+async function stopServer(child, timeoutMs) {
+    if (childExited(child))
+        return;
+    if (!child.kill('SIGTERM'))
+        return;
+    if (await waitForChildExit(child, timeoutMs))
+        return;
+    if (!child.kill('SIGKILL'))
+        return;
+    await waitForChildExit(child, 1_000);
+}
+async function startServer(options, runtimeUrl) {
+    const readyUrl = options.readyUrl ?? runtimeUrl;
+    const before = await probe(readyUrl);
+    if (before.reachable) {
+        throw new ProductionRuntimeVerificationError(`runtime readiness URL is already reachable; refusing to reuse another process: ${readyUrl}`);
+    }
+    const spawnOptions = {
+        env: { ...process.env, ...options.env },
+        stdio: ['ignore', 'inherit', 'inherit'],
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    };
+    const child = spawn(options.command, [...(options.args ?? [])], spawnOptions);
+    let spawnError;
+    child.once('error', (error) => {
+        spawnError = error;
+    });
+    const timeoutMs = options.startupTimeoutMs ?? 15_000;
+    const deadline = Date.now() + timeoutMs;
+    try {
+        while (Date.now() < deadline) {
+            if (spawnError) {
+                throw new ProductionRuntimeVerificationError(`runtime server failed to start: ${spawnError.message}`, [], spawnError);
+            }
+            if (childExited(child)) {
+                throw new ProductionRuntimeVerificationError(`runtime server exited before readiness (code=${String(child.exitCode)}, signal=${String(child.signalCode)})`);
+            }
+            const result = await probe(readyUrl);
+            if (result.ok)
+                return child;
+            await delay(100);
+        }
+        throw new ProductionRuntimeVerificationError(`runtime server did not become ready within ${timeoutMs} ms: ${readyUrl}`);
+    }
+    catch (error) {
+        await stopServer(child, options.shutdownTimeoutMs ?? 5_000);
+        throw error;
+    }
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const location = issue.url ? ` (${issue.url})` : '';
+        return `[${issue.kind}] ${issue.message}${location}`;
+    })
+        .join('\n');
+}
+function mutedLaunchOptions(options, gpuMode) {
+    const profile = createChromiumLaunchProfile({
+        ...(gpuMode === undefined ? {} : { gpuMode }),
+        ...(options?.args === undefined ? {} : { args: options.args }),
+        ...(options?.env === undefined ? {} : { env: options.env }),
+    });
+    return {
+        ...options,
+        ...profile,
+        headless: options?.headless ?? false,
+    };
+}
+const SOFTWARE_RENDERER_PATTERN = /swiftshader|llvmpipe|software rasterizer|microsoft basic render driver|angle.*(?:warp|software)/i;
+/** Reads the unmasked WebGL renderer already attached to the selected game canvas. */
+export async function readWebGLRenderer(page, canvasSelector = 'canvas') {
+    return page.evaluate((selector) => {
+        const canvas = document.querySelector(selector);
+        if (!(canvas instanceof HTMLCanvasElement)) {
+            throw new Error(`WebGL canvas not found: ${selector}`);
+        }
+        const context = canvas.getContext('webgl2') ?? canvas.getContext('webgl');
+        if (!context)
+            throw new Error(`WebGL context unavailable: ${selector}`);
+        const extension = context.getExtension('WEBGL_debug_renderer_info');
+        const renderer = String(context.getParameter(extension?.UNMASKED_RENDERER_WEBGL ?? context.RENDERER));
+        const vendor = String(context.getParameter(extension?.UNMASKED_VENDOR_WEBGL ?? context.VENDOR));
+        return { renderer, vendor, unmasked: extension !== null };
+    }, canvasSelector);
+}
+/** Requires a real hardware-backed WebGL renderer and returns its identity. */
+export async function requireHardwareWebGL(page, canvasSelector = 'canvas') {
+    const info = await readWebGLRenderer(page, canvasSelector);
+    if (!info.unmasked || !info.renderer.trim() || SOFTWARE_RENDERER_PATTERN.test(info.renderer)) {
+        throw new ProductionRuntimeVerificationError(`hardware WebGL required; received ${info.unmasked ? 'unmasked' : 'masked'} renderer: ${info.renderer || '<empty>'}`);
+    }
+    return info;
+}
+async function seedLocalStorage(page, sentinels) {
+    const entries = Object.entries(sentinels);
+    if (entries.length === 0)
+        return;
+    await page.addInitScript((values) => {
+        const storage = globalThis.localStorage;
+        for (const [key, value] of values) {
+            if (value === null)
+                storage.removeItem(key);
+            else
+                storage.setItem(key, value);
+        }
+    }, entries);
+}
+async function readLocalStorage(page, keys) {
+    if (keys.length === 0)
+        return {};
+    return page.evaluate((sentinelKeys) => {
+        const storage = globalThis.localStorage;
+        return Object.fromEntries(sentinelKeys.map((key) => [key, storage.getItem(key)]));
+    }, [...keys]);
+}
+/**
+ * Boots a built or deployed game in a fresh, fail-closed, silent Chromium and
+ * requires game-specific identity/UI proof before accepting the runtime.
+ */
+export async function verifyProductionRuntime(options) {
+    const runtimeUrl = validateHttpUrl('runtime URL', options.url);
+    if (typeof options.assertReady !== 'function') {
+        throw new ProductionRuntimeVerificationError('assertReady must be a function');
+    }
+    validateDuration('settleTimeMs', options.settleTimeMs, true);
+    if (options.server) {
+        if (!options.server.command.trim()) {
+            throw new ProductionRuntimeVerificationError('runtime server command must not be empty');
+        }
+        if (options.server.readyUrl !== undefined) {
+            validateHttpUrl('runtime readiness URL', options.server.readyUrl);
+        }
+        validateDuration('startupTimeoutMs', options.server.startupTimeoutMs, false);
+        validateDuration('shutdownTimeoutMs', options.server.shutdownTimeoutMs, true);
+    }
+    let child;
+    let browser;
+    const issues = [];
+    try {
+        if (options.server)
+            child = await startServer(options.server, runtimeUrl);
+        browser = await chromium.launch(mutedLaunchOptions(options.browserLaunchOptions, options.gpuMode));
+        const page = options.pageOptions
+            ? await browser.newPage(options.pageOptions)
+            : await browser.newPage();
+        page.on('pageerror', (error) => {
+            issues.push({ kind: 'pageerror', message: error.message });
+        });
+        page.on('console', (message) => {
+            if (message.type() === 'error') {
+                issues.push({ kind: 'console', message: message.text() });
+            }
+        });
+        page.on('requestfailed', (request) => {
+            issues.push({
+                kind: 'requestfailed',
+                message: request.failure()?.errorText ?? 'request failed without an error message',
+                url: request.url(),
+            });
+        });
+        page.on('response', (response) => {
+            if (response.status() >= 400) {
+                issues.push({
+                    kind: 'http',
+                    message: `HTTP ${response.status()}`,
+                    url: response.url(),
+                });
+            }
+        });
+        const sentinels = options.localStorageSentinels ?? {};
+        await seedLocalStorage(page, sentinels);
+        try {
+            await openSilentGame(page, runtimeUrl, options.silentParameters ?? {}, {
+                markerTimeout: 15_000,
+                ...options.silentOptions,
+            });
+            await options.assertReady(page);
+            await options.assertSilentState?.(page);
+            const settleTimeMs = options.settleTimeMs ?? 250;
+            if (settleTimeMs > 0)
+                await page.waitForTimeout(settleTimeMs);
+        }
+        catch (error) {
+            if (issues.length > 0) {
+                throw new ProductionRuntimeVerificationError(`production runtime failed while emitting runtime errors:\n${formatIssues(issues)}`, issues, error);
+            }
+            throw error;
+        }
+        const localStorage = await readLocalStorage(page, Object.keys(sentinels));
+        for (const [key, expected] of Object.entries(sentinels)) {
+            const received = localStorage[key] ?? null;
+            if (received !== expected) {
+                throw new ProductionRuntimeVerificationError(`localStorage sentinel ${key} changed: expected ${String(expected)}, received ${String(received)}`);
+            }
+        }
+        if (issues.length > 0) {
+            throw new ProductionRuntimeVerificationError(`production runtime emitted errors:\n${formatIssues(issues)}`, issues);
+        }
+        return { finalUrl: page.url(), localStorage };
+    }
+    finally {
+        try {
+            await browser?.close();
+        }
+        finally {
+            if (child)
+                await stopServer(child, options.server?.shutdownTimeoutMs ?? 5_000);
+        }
+    }
+}

package/dist/esm/release-ladder.js

@@ -0,0 +1,37 @@
+/**
+ * Thin orchestrator for a `verify:*` release ladder — an ordered list of
+ * named steps (lint → typecheck → test → build → browser verifies →
+ * screenshots → native sync, or whatever a given repo's ladder is), run in
+ * sequence and stopped at the first failure with a labeled summary.
+ *
+ * Generalizes the reach-for-the-sky pattern of ~17 discrete
+ * `node scripts/verify-X.mjs` files composed via a shell `&&` chain into a
+ * single reusable primitive: each step is a plain function (sync or async),
+ * so a repo can inline its logic or delegate to existing scripts via
+ * `execSync`.
+ *
+ * Never throws — returns a result object so callers can decide how to
+ * report/exit. The CLI convention is `process.exit(result.ok ? 0 : 1)`.
+ */
+export async function verifyReleaseLadder(steps, options = {}) {
+    const log = options.log ?? ((msg) => console.log(`[verify] ${msg}`));
+    const error = options.error ?? ((msg) => console.error(`[verify] ${msg}`));
+    const ranSteps = [];
+    for (const step of steps) {
+        log(`▶ ${step.name}`);
+        try {
+            await step.run();
+            ranSteps.push(step.name);
+            log(`✓ ${step.name}`);
+        }
+        catch (err) {
+            error(`✗ ${step.name} failed`);
+            if (err instanceof Error) {
+                error(err.message);
+            }
+            return { ok: false, ranSteps, failedStep: step.name, error: err };
+        }
+    }
+    log(`all ${ranSteps.length} step(s) passed.`);
+    return { ok: true, ranSteps };
+}

package/dist/esm/silent-qa.js

@@ -0,0 +1,67 @@
+export const SILENT_QA_QUERY_PARAMETER = 'muted';
+export const SILENT_QA_QUERY_VALUE = '1';
+export const SILENT_QA_MARKER_ATTRIBUTE = 'data-audio-mode';
+export const SILENT_QA_MARKER_VALUE = 'muted-test';
+let silentQaActive = false;
+function isPromiseLike(value) {
+    return (((typeof value === 'object' && value !== null) || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+function browserSearch() {
+    return typeof window === 'undefined' ? '' : window.location.search;
+}
+function browserMarkerTarget() {
+    return typeof document === 'undefined' ? null : document.documentElement;
+}
+/**
+ * Detects a page-lifetime mute request by parameter presence.
+ *
+ * The value is intentionally ignored so stale links such as `?muted=0` cannot
+ * make an agent-controlled session audible.
+ */
+export function isSilentQaRequested(search = browserSearch(), queryParameter = SILENT_QA_QUERY_PARAMETER) {
+    return new URLSearchParams(search).has(queryParameter);
+}
+/**
+ * Activates runtime-only silent QA through a consumer-owned audio mute callback.
+ *
+ * The package stays audio-engine agnostic: consumers may mute Howler, WebAudio,
+ * HTMLMediaElement, or another engine. The DOM marker is published only after
+ * the callback returns successfully, allowing browser tests to fail closed.
+ * This helper never reads or writes a player's persisted audio preference.
+ */
+export function activateSilentQa(mute, options = {}) {
+    if (!isSilentQaRequested(options.search ?? browserSearch(), options.queryParameter ?? SILENT_QA_QUERY_PARAMETER)) {
+        return false;
+    }
+    const result = mute();
+    if (isPromiseLike(result)) {
+        throw new TypeError('activateSilentQa received an asynchronous mute callback; await activateSilentQaAsync instead');
+    }
+    const markerTarget = options.markerTarget === undefined ? browserMarkerTarget() : options.markerTarget;
+    markerTarget?.setAttribute(options.markerAttribute ?? SILENT_QA_MARKER_ATTRIBUTE, options.markerValue ?? SILENT_QA_MARKER_VALUE);
+    silentQaActive = true;
+    return true;
+}
+/**
+ * Asynchronous counterpart to {@link activateSilentQa}. The readiness marker
+ * is not published until the consumer's mute promise fulfills.
+ */
+export async function activateSilentQaAsync(mute, options = {}) {
+    if (!isSilentQaRequested(options.search ?? browserSearch(), options.queryParameter ?? SILENT_QA_QUERY_PARAMETER)) {
+        return false;
+    }
+    await mute();
+    const markerTarget = options.markerTarget === undefined ? browserMarkerTarget() : options.markerTarget;
+    markerTarget?.setAttribute(options.markerAttribute ?? SILENT_QA_MARKER_ATTRIBUTE, options.markerValue ?? SILENT_QA_MARKER_VALUE);
+    silentQaActive = true;
+    return true;
+}
+/** True after this module has successfully activated the page-lifetime override. */
+export function isSilentQaActive() {
+    return silentQaActive;
+}
+/** Test hook; production code must never disable a page-lifetime override. */
+export function _resetSilentQaForTests() {
+    silentQaActive = false;
+}

package/dist/esm/visual-battery.js

@@ -0,0 +1,239 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import spawn from 'cross-spawn';
+/**
+ * Thrown by every `runVisualBattery()` failure path — a missing harness dir,
+ * no discovered `.browser.test.ts(x)` files, a misplaced `__screenshots__`
+ * directory, a dirty baseline dir in `--ci` mode, a failing harness run, or
+ * detected drift while `ci: true`. Callers (tests, other tooling) can catch
+ * this specific type instead of `process.exit`, which only the CLI entry
+ * point (`bin/test-harness-visual-battery`) calls.
+ */
+export class VisualBatteryError extends Error {
+}
+function findUnexpectedBaselineDirectories(root, canonical) {
+    const unexpected = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const child = resolve(directory, entry.name);
+            if (child === canonical)
+                continue;
+            if (entry.name === '__screenshots__') {
+                unexpected.push(child);
+                continue;
+            }
+            visit(child);
+        }
+    };
+    visit(root);
+    return unexpected;
+}
+function defaultLog(msg) {
+    console.log(`[visual-battery] ${msg}`);
+}
+function defaultError(msg) {
+    console.error(`[visual-battery] ERROR: ${msg}`);
+}
+function canonicalizePath(target) {
+    const missingSegments = [];
+    let existingAncestor = target;
+    while (!existsSync(existingAncestor)) {
+        missingSegments.unshift(basename(existingAncestor));
+        existingAncestor = dirname(existingAncestor);
+    }
+    return resolve(realpathSync(existingAncestor), ...missingSegments);
+}
+/**
+ * Deterministic git-diff-based visual-regression gate.
+ *
+ * Runs every `.browser.test.tsx` harness file under `harnessDir`, then
+ * diffs the resulting `__screenshots__/*.png` baselines against what's
+ * committed in git. No pixel-threshold fuzzing, no flaky perceptual
+ * comparison — a screenshot either byte-matches the committed baseline
+ * (via `git status --porcelain`) or it doesn't.
+ *
+ * - Update mode (`ci: false`, the default): runs the harnesses, lets new
+ *   baselines land on disk, reports what changed so a human can review
+ *   `git diff` and commit intentionally.
+ * - CI mode (`ci: true`): refuses to run at all if the baselines dir has
+ *   uncommitted changes already (an untrusted starting state), then fails
+ *   the process if the run produces any drift from the committed baseline.
+ *
+ * Throws `VisualBatteryError` on any failure condition instead of calling
+ * `process.exit` directly, so callers (tests, other tooling) can catch it;
+ * the CLI entry point (`bin/test-harness-visual-battery`) is the thing that
+ * exits the process.
+ */
+export function runVisualBattery(harnessDir, options = {}) {
+    const { ci = false, cwd = process.cwd(), testCommand = 'pnpm test:browser', baselineProfile, isolatedHarnessFiles = [], log = defaultLog, error = defaultError, } = options;
+    const die = (msg) => {
+        error(msg);
+        throw new VisualBatteryError(msg);
+    };
+    const resolvedCwd = resolve(cwd);
+    const canonicalCwd = (() => {
+        try {
+            return realpathSync(resolvedCwd);
+        }
+        catch {
+            return die(`cwd not found or not reachable: ${cwd}`);
+        }
+    })();
+    const HARNESS_DIR = resolve(canonicalCwd, harnessDir);
+    const relativeHarnessDir = relative(canonicalCwd, HARNESS_DIR).split(sep).join('/') || '.';
+    if (baselineProfile && !/^[a-z0-9][a-z0-9_-]*$/i.test(baselineProfile)) {
+        throw new VisualBatteryError(`invalid baseline profile: ${baselineProfile}`);
+    }
+    if (options.baselinesDir && isAbsolute(options.baselinesDir)) {
+        die(`baselines dir must be relative to cwd: ${options.baselinesDir}`);
+    }
+    const relativeBaselinesRoot = options.baselinesDir ?? `${relativeHarnessDir}/__screenshots__`;
+    const canonicalBaselinesDir = resolve(canonicalCwd, relativeBaselinesRoot);
+    const relativeBaselinesDir = baselineProfile
+        ? `${relativeBaselinesRoot.replace(/\/$/, '')}/${baselineProfile}`
+        : relativeBaselinesRoot;
+    const BASELINES_DIR = resolve(canonicalCwd, relativeBaselinesDir);
+    const assertInsideCwd = (label, target) => {
+        const pathFromCwd = relative(canonicalCwd, canonicalizePath(target));
+        if (pathFromCwd === '..' || pathFromCwd.startsWith(`..${sep}`) || isAbsolute(pathFromCwd)) {
+            die(`${label} must stay inside cwd: ${target}`);
+        }
+    };
+    assertInsideCwd('harness dir', HARNESS_DIR);
+    assertInsideCwd('baselines dir', BASELINES_DIR);
+    if (!existsSync(HARNESS_DIR)) {
+        die(`harness dir not found: ${HARNESS_DIR}`);
+    }
+    if (!statSync(HARNESS_DIR).isDirectory()) {
+        die(`harness path is not a directory: ${HARNESS_DIR}`);
+    }
+    const unexpectedBaselineDirectories = findUnexpectedBaselineDirectories(HARNESS_DIR, canonicalBaselinesDir);
+    if (unexpectedBaselineDirectories.length > 0) {
+        die(`unexpected screenshot director${unexpectedBaselineDirectories.length === 1 ? 'y' : 'ies'} outside ${relativeBaselinesDir}: ${unexpectedBaselineDirectories
+            .map((directory) => relative(cwd, directory))
+            .join(', ')}`);
+    }
+    const harnessFiles = readdirSync(HARNESS_DIR)
+        .filter((f) => /\.browser\.test\.(?:ts|tsx)$/.test(f))
+        .sort()
+        .map((f) => `${relativeHarnessDir}/${f}`);
+    if (harnessFiles.length === 0) {
+        die('no .browser.test.ts or .browser.test.tsx harness files found');
+    }
+    const unknownIsolatedHarnessFiles = isolatedHarnessFiles.filter((file) => !harnessFiles.some((harnessFile) => harnessFile.endsWith(`/${file}`)));
+    if (unknownIsolatedHarnessFiles.length > 0) {
+        die(`isolated harness file(s) not found: ${unknownIsolatedHarnessFiles.join(', ')}`);
+    }
+    const isolatedHarnessSet = new Set(isolatedHarnessFiles);
+    const batchedHarnessFiles = harnessFiles.filter((file) => !isolatedHarnessSet.has(file.slice(file.lastIndexOf('/') + 1)));
+    const isolatedHarnessPaths = harnessFiles.filter((file) => isolatedHarnessSet.has(file.slice(file.lastIndexOf('/') + 1)));
+    log(`running ${harnessFiles.length} harness file(s):`);
+    for (const f of harnessFiles)
+        log(`  - ${f}`);
+    if (ci) {
+        let beforeStatus = '';
+        try {
+            beforeStatus = execFileSync('git', ['status', '--porcelain', '--', relativeBaselinesDir], {
+                cwd,
+                encoding: 'utf-8',
+            });
+        }
+        catch (err) {
+            die(`git status failed: ${err}`);
+        }
+        if (beforeStatus.trim().length > 0) {
+            die(`${relativeBaselinesDir}/ has uncommitted changes before run — commit or reset before --ci mode`);
+        }
+    }
+    const runHarnessFiles = (files, label) => {
+        if (files.length === 0)
+            return;
+        const command = typeof testCommand === 'string'
+            ? (() => {
+                const parts = testCommand.trim().split(/\s+/u);
+                const executable = parts.shift() || die('test command must not be empty');
+                return { command: executable, args: parts };
+            })()
+            : testCommand;
+        if (!command.command.trim())
+            die('test command executable must not be empty');
+        const commandArgs = [...(command.args ?? []), ...files];
+        log(`running ${label}: ${[command.command, ...commandArgs].join(' ')}...`);
+        const environment = {
+            ...process.env,
+            ...(baselineProfile ? { VITE_VISUAL_BASELINE_PROFILE: baselineProfile } : {}),
+        };
+        try {
+            if (process.platform === 'win32') {
+                // Package managers are commonly exposed as .cmd shims on Windows.
+                // cross-spawn resolves those shims without opting into shell: true.
+                const result = spawn.sync(command.command, commandArgs, {
+                    cwd,
+                    stdio: 'inherit',
+                    env: environment,
+                });
+                if (result.error)
+                    throw result.error;
+                if (result.status !== 0)
+                    throw new Error(`test command exited with ${result.status}`);
+            }
+            else {
+                execFileSync(command.command, commandArgs, {
+                    cwd,
+                    stdio: 'inherit',
+                    env: environment,
+                });
+            }
+        }
+        catch {
+            die('one or more harnesses failed — fix the failing test before re-running visual battery');
+        }
+    };
+    runHarnessFiles(batchedHarnessFiles, 'batched harnesses');
+    for (const isolatedHarnessPath of isolatedHarnessPaths) {
+        runHarnessFiles([isolatedHarnessPath], `isolated harness ${isolatedHarnessPath}`);
+    }
+    if (!existsSync(BASELINES_DIR)) {
+        die(`baselines dir not created: ${BASELINES_DIR}`);
+    }
+    const baselineCount = readdirSync(BASELINES_DIR).filter((f) => f.endsWith('.png')).length;
+    if (baselineCount === 0) {
+        die(`no PNG baselines produced in: ${BASELINES_DIR}`);
+    }
+    log(`baseline screenshots produced: ${baselineCount}`);
+    let afterStatus = '';
+    try {
+        afterStatus = execFileSync('git', ['status', '--porcelain', '--', relativeBaselinesDir], {
+            cwd,
+            encoding: 'utf-8',
+        });
+    }
+    catch (err) {
+        die(`git status failed after harness run: ${err}`);
+    }
+    if (afterStatus.trim().length === 0) {
+        log('baselines clean — no visual drift detected.');
+        return;
+    }
+    if (ci) {
+        error('DRIFT DETECTED in CI mode:');
+        error(afterStatus);
+        error(`failing — run visual:battery locally + commit baselines`);
+        throw new VisualBatteryError('visual drift detected in CI mode');
+    }
+    log(`baselines updated — ${afterStatus.split('\n').filter(Boolean).length} file(s) changed:`);
+    log(afterStatus);
+    log(`review the diff with \`git diff ${relativeBaselinesDir}/\` then commit if intended.`);
+    log('CI gate: rerun with `ci: true` will fail until the updated baselines are committed.');
+    log('baseline file sizes:');
+    for (const f of readdirSync(BASELINES_DIR)) {
+        if (!f.endsWith('.png'))
+            continue;
+        const path = resolve(BASELINES_DIR, f);
+        const size = statSync(path).size;
+        log(`  ${f}  ${size} bytes`);
+    }
+}

package/dist/types/bin/visual-battery.d.cts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/bin/visual-battery.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};