game-harness 1.0.0

package/dist/types/production-runtime.d.cts

@@ -0,0 +1,105 @@
+import { type Browser, chromium, type Page } from '@playwright/test';
+import { type ChromiumGpuMode } from './chromium-launch.js';
+import { type OpenSilentGameOptions, type SilentQueryValue } from './playwright-config.js';
+type BrowserLaunchOptions = NonNullable<Parameters<typeof chromium.launch>[0]>;
+type BrowserPageOptions = Parameters<Browser['newPage']>[0];
+export interface ProductionRuntimeServerOptions {
+    /** Executable to launch directly. Shell command strings are intentionally unsupported. */
+    command: string;
+    /** Arguments passed directly to `command`. Use the server's strict-port option. */
+    args?: readonly string[];
+    /** Child working directory. Defaults to the current process directory. */
+    cwd?: string;
+    /** Environment additions or overrides for the child process. */
+    env?: Readonly<NodeJS.ProcessEnv>;
+    /** URL polled for readiness. Defaults to the runtime `url`. */
+    readyUrl?: string;
+    /** Maximum startup time. Defaults to 15 seconds. */
+    startupTimeoutMs?: number;
+    /** Graceful shutdown time before SIGKILL. Defaults to 5 seconds. */
+    shutdownTimeoutMs?: number;
+}
+export interface ProductionRuntimeOptions {
+    /** Production artifact or exact-live URL to verify. */
+    url: string;
+    /** Optional owned preview server. Existing processes are never reused. */
+    server?: ProductionRuntimeServerOptions;
+    /** Chromium options. `--mute-audio` is always de-duplicated and applied last. */
+    browserLaunchOptions?: BrowserLaunchOptions;
+    /** Renderer profile. Defaults to native Chromium selection (`auto`). */
+    gpuMode?: ChromiumGpuMode;
+    /** Options for the fresh browser page. */
+    pageOptions?: BrowserPageOptions;
+    /** Extra query parameters composed with the mandatory runtime mute. */
+    silentParameters?: Readonly<Record<string, SilentQueryValue>>;
+    /** Silent marker/query overrides. The marker timeout defaults to 15 seconds here. */
+    silentOptions?: OpenSilentGameOptions;
+    /** Values written before application code and required to remain byte-for-byte unchanged. */
+    localStorageSentinels?: Readonly<Record<string, string | null>>;
+    /** Required game-specific identity plus primary UI/canvas assertions. */
+    assertReady: (page: Page) => Promise<void>;
+    /** Optional engine-specific assertion such as `window.Howler._muted === true`. */
+    assertSilentState?: (page: Page) => Promise<void>;
+    /** Brief post-ready observation window for deferred runtime errors. Defaults to 250 ms. */
+    settleTimeMs?: number;
+}
+/** Evidence returned by a successful `verifyProductionRuntime()` call. */
+export interface ProductionRuntimeResult {
+    /** The page's URL after navigation, including the applied silent-QA query parameters. */
+    finalUrl: string;
+    /** Every requested `localStorageSentinels` key, read back after the boot completed. */
+    localStorage: Record<string, string | null>;
+}
+/**
+ * One runtime failure captured while the game booted: an uncaught page
+ * error, a `console.error` call, a network request that failed outright, or
+ * an HTTP response with a 4xx/5xx status. `verifyProductionRuntime()`
+ * accumulates these and fails closed if any were recorded.
+ */
+export interface ProductionRuntimeIssue {
+    kind: 'console' | 'http' | 'pageerror' | 'requestfailed';
+    message: string;
+    /** The request/response URL, present for `'http'` and `'requestfailed'` issues. */
+    url?: string;
+}
+export interface AvailableProductionPortOptions {
+    /** Loopback interface used by the owned preview server. Defaults to IPv4 localhost. */
+    host?: string;
+}
+/**
+ * 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 declare class ProductionRuntimeVerificationError extends Error {
+    /** Runtime issues recorded before this error was thrown, if any. Empty for pure validation failures. */
+    readonly issues: readonly ProductionRuntimeIssue[];
+    constructor(message: string, issues?: readonly ProductionRuntimeIssue[], cause?: unknown);
+}
+/**
+ * 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 declare function findAvailableProductionPort(options?: AvailableProductionPortOptions): Promise<number>;
+export interface WebGLRendererInfo {
+    /** `UNMASKED_RENDERER_WEBGL` when available, otherwise the generic (often masked) `RENDERER` parameter. */
+    renderer: string;
+    /** `UNMASKED_VENDOR_WEBGL` when available, otherwise the generic (often masked) `VENDOR` parameter. */
+    vendor: string;
+    /** True only when Chromium exposed `WEBGL_debug_renderer_info`. */
+    unmasked: boolean;
+}
+/** Reads the unmasked WebGL renderer already attached to the selected game canvas. */
+export declare function readWebGLRenderer(page: Page, canvasSelector?: string): Promise<WebGLRendererInfo>;
+/** Requires a real hardware-backed WebGL renderer and returns its identity. */
+export declare function requireHardwareWebGL(page: Page, canvasSelector?: string): Promise<WebGLRendererInfo>;
+/**
+ * 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 declare function verifyProductionRuntime(options: ProductionRuntimeOptions): Promise<ProductionRuntimeResult>;
+export {};

package/dist/types/production-runtime.d.ts

@@ -0,0 +1,105 @@
+import { type Browser, chromium, type Page } from '@playwright/test';
+import { type ChromiumGpuMode } from './chromium-launch.js';
+import { type OpenSilentGameOptions, type SilentQueryValue } from './playwright-config.js';
+type BrowserLaunchOptions = NonNullable<Parameters<typeof chromium.launch>[0]>;
+type BrowserPageOptions = Parameters<Browser['newPage']>[0];
+export interface ProductionRuntimeServerOptions {
+    /** Executable to launch directly. Shell command strings are intentionally unsupported. */
+    command: string;
+    /** Arguments passed directly to `command`. Use the server's strict-port option. */
+    args?: readonly string[];
+    /** Child working directory. Defaults to the current process directory. */
+    cwd?: string;
+    /** Environment additions or overrides for the child process. */
+    env?: Readonly<NodeJS.ProcessEnv>;
+    /** URL polled for readiness. Defaults to the runtime `url`. */
+    readyUrl?: string;
+    /** Maximum startup time. Defaults to 15 seconds. */
+    startupTimeoutMs?: number;
+    /** Graceful shutdown time before SIGKILL. Defaults to 5 seconds. */
+    shutdownTimeoutMs?: number;
+}
+export interface ProductionRuntimeOptions {
+    /** Production artifact or exact-live URL to verify. */
+    url: string;
+    /** Optional owned preview server. Existing processes are never reused. */
+    server?: ProductionRuntimeServerOptions;
+    /** Chromium options. `--mute-audio` is always de-duplicated and applied last. */
+    browserLaunchOptions?: BrowserLaunchOptions;
+    /** Renderer profile. Defaults to native Chromium selection (`auto`). */
+    gpuMode?: ChromiumGpuMode;
+    /** Options for the fresh browser page. */
+    pageOptions?: BrowserPageOptions;
+    /** Extra query parameters composed with the mandatory runtime mute. */
+    silentParameters?: Readonly<Record<string, SilentQueryValue>>;
+    /** Silent marker/query overrides. The marker timeout defaults to 15 seconds here. */
+    silentOptions?: OpenSilentGameOptions;
+    /** Values written before application code and required to remain byte-for-byte unchanged. */
+    localStorageSentinels?: Readonly<Record<string, string | null>>;
+    /** Required game-specific identity plus primary UI/canvas assertions. */
+    assertReady: (page: Page) => Promise<void>;
+    /** Optional engine-specific assertion such as `window.Howler._muted === true`. */
+    assertSilentState?: (page: Page) => Promise<void>;
+    /** Brief post-ready observation window for deferred runtime errors. Defaults to 250 ms. */
+    settleTimeMs?: number;
+}
+/** Evidence returned by a successful `verifyProductionRuntime()` call. */
+export interface ProductionRuntimeResult {
+    /** The page's URL after navigation, including the applied silent-QA query parameters. */
+    finalUrl: string;
+    /** Every requested `localStorageSentinels` key, read back after the boot completed. */
+    localStorage: Record<string, string | null>;
+}
+/**
+ * One runtime failure captured while the game booted: an uncaught page
+ * error, a `console.error` call, a network request that failed outright, or
+ * an HTTP response with a 4xx/5xx status. `verifyProductionRuntime()`
+ * accumulates these and fails closed if any were recorded.
+ */
+export interface ProductionRuntimeIssue {
+    kind: 'console' | 'http' | 'pageerror' | 'requestfailed';
+    message: string;
+    /** The request/response URL, present for `'http'` and `'requestfailed'` issues. */
+    url?: string;
+}
+export interface AvailableProductionPortOptions {
+    /** Loopback interface used by the owned preview server. Defaults to IPv4 localhost. */
+    host?: string;
+}
+/**
+ * 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 declare class ProductionRuntimeVerificationError extends Error {
+    /** Runtime issues recorded before this error was thrown, if any. Empty for pure validation failures. */
+    readonly issues: readonly ProductionRuntimeIssue[];
+    constructor(message: string, issues?: readonly ProductionRuntimeIssue[], cause?: unknown);
+}
+/**
+ * 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 declare function findAvailableProductionPort(options?: AvailableProductionPortOptions): Promise<number>;
+export interface WebGLRendererInfo {
+    /** `UNMASKED_RENDERER_WEBGL` when available, otherwise the generic (often masked) `RENDERER` parameter. */
+    renderer: string;
+    /** `UNMASKED_VENDOR_WEBGL` when available, otherwise the generic (often masked) `VENDOR` parameter. */
+    vendor: string;
+    /** True only when Chromium exposed `WEBGL_debug_renderer_info`. */
+    unmasked: boolean;
+}
+/** Reads the unmasked WebGL renderer already attached to the selected game canvas. */
+export declare function readWebGLRenderer(page: Page, canvasSelector?: string): Promise<WebGLRendererInfo>;
+/** Requires a real hardware-backed WebGL renderer and returns its identity. */
+export declare function requireHardwareWebGL(page: Page, canvasSelector?: string): Promise<WebGLRendererInfo>;
+/**
+ * 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 declare function verifyProductionRuntime(options: ProductionRuntimeOptions): Promise<ProductionRuntimeResult>;
+export {};

package/dist/types/release-ladder.d.cts

@@ -0,0 +1,38 @@
+export interface ReleaseLadderStep {
+    /** Label logged before/after the step runs and used to identify it in a failure result. */
+    name: string;
+    /** The step's work. A thrown error or rejected promise stops the ladder at this step. */
+    run: () => void | Promise<void>;
+}
+export interface ReleaseLadderResult {
+    /** True only if every step completed without throwing. */
+    ok: boolean;
+    /** Names of steps that completed successfully, in order, up to (and excluding) any failure. */
+    ranSteps: string[];
+    /** Name of the step that threw, present only when `ok` is false. */
+    failedStep?: string;
+    /** The value thrown by `failedStep`'s `run()`, present only when `ok` is false. */
+    error?: unknown;
+}
+export interface VerifyReleaseLadderOptions {
+    /** Called before and after each step. Defaults to `console.log` prefixed with `[verify]`. */
+    log?: (msg: string) => void;
+    /** Called on step failure, once for the failure message and again with the error's message if it's an `Error`. Defaults to `console.error` prefixed with `[verify]`. */
+    error?: (msg: string) => void;
+}
+/**
+ * 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 declare function verifyReleaseLadder(steps: ReleaseLadderStep[], options?: VerifyReleaseLadderOptions): Promise<ReleaseLadderResult>;

package/dist/types/release-ladder.d.ts

@@ -0,0 +1,38 @@
+export interface ReleaseLadderStep {
+    /** Label logged before/after the step runs and used to identify it in a failure result. */
+    name: string;
+    /** The step's work. A thrown error or rejected promise stops the ladder at this step. */
+    run: () => void | Promise<void>;
+}
+export interface ReleaseLadderResult {
+    /** True only if every step completed without throwing. */
+    ok: boolean;
+    /** Names of steps that completed successfully, in order, up to (and excluding) any failure. */
+    ranSteps: string[];
+    /** Name of the step that threw, present only when `ok` is false. */
+    failedStep?: string;
+    /** The value thrown by `failedStep`'s `run()`, present only when `ok` is false. */
+    error?: unknown;
+}
+export interface VerifyReleaseLadderOptions {
+    /** Called before and after each step. Defaults to `console.log` prefixed with `[verify]`. */
+    log?: (msg: string) => void;
+    /** Called on step failure, once for the failure message and again with the error's message if it's an `Error`. Defaults to `console.error` prefixed with `[verify]`. */
+    error?: (msg: string) => void;
+}
+/**
+ * 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 declare function verifyReleaseLadder(steps: ReleaseLadderStep[], options?: VerifyReleaseLadderOptions): Promise<ReleaseLadderResult>;

package/dist/types/silent-qa.d.cts

@@ -0,0 +1,47 @@
+export declare const SILENT_QA_QUERY_PARAMETER = "muted";
+export declare const SILENT_QA_QUERY_VALUE = "1";
+export declare const SILENT_QA_MARKER_ATTRIBUTE = "data-audio-mode";
+export declare const SILENT_QA_MARKER_VALUE = "muted-test";
+export interface SilentQaMarkerTarget {
+    setAttribute(name: string, value: string): void;
+}
+export interface ActivateSilentQaOptions {
+    /** Query string to inspect. Defaults to `window.location.search` in a browser. */
+    search?: string;
+    /** Runtime-only mute parameter. Defaults to `muted`. */
+    queryParameter?: string;
+    /**
+     * Element that owns the mute-ready marker. Defaults to `document.documentElement`.
+     * Pass `null` for a non-DOM runtime.
+     */
+    markerTarget?: SilentQaMarkerTarget | null;
+    /** Marker attribute set only after the audio engine's mute callback succeeds. */
+    markerAttribute?: string;
+    /** Marker value set only after the audio engine's mute callback succeeds. */
+    markerValue?: string;
+}
+/**
+ * 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 declare function isSilentQaRequested(search?: string, queryParameter?: string): boolean;
+/**
+ * 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 declare function activateSilentQa(mute: () => void, options?: ActivateSilentQaOptions): boolean;
+/**
+ * Asynchronous counterpart to {@link activateSilentQa}. The readiness marker
+ * is not published until the consumer's mute promise fulfills.
+ */
+export declare function activateSilentQaAsync(mute: () => void | PromiseLike<void>, options?: ActivateSilentQaOptions): Promise<boolean>;
+/** True after this module has successfully activated the page-lifetime override. */
+export declare function isSilentQaActive(): boolean;
+/** Test hook; production code must never disable a page-lifetime override. */
+export declare function _resetSilentQaForTests(): void;

package/dist/types/silent-qa.d.ts

@@ -0,0 +1,47 @@
+export declare const SILENT_QA_QUERY_PARAMETER = "muted";
+export declare const SILENT_QA_QUERY_VALUE = "1";
+export declare const SILENT_QA_MARKER_ATTRIBUTE = "data-audio-mode";
+export declare const SILENT_QA_MARKER_VALUE = "muted-test";
+export interface SilentQaMarkerTarget {
+    setAttribute(name: string, value: string): void;
+}
+export interface ActivateSilentQaOptions {
+    /** Query string to inspect. Defaults to `window.location.search` in a browser. */
+    search?: string;
+    /** Runtime-only mute parameter. Defaults to `muted`. */
+    queryParameter?: string;
+    /**
+     * Element that owns the mute-ready marker. Defaults to `document.documentElement`.
+     * Pass `null` for a non-DOM runtime.
+     */
+    markerTarget?: SilentQaMarkerTarget | null;
+    /** Marker attribute set only after the audio engine's mute callback succeeds. */
+    markerAttribute?: string;
+    /** Marker value set only after the audio engine's mute callback succeeds. */
+    markerValue?: string;
+}
+/**
+ * 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 declare function isSilentQaRequested(search?: string, queryParameter?: string): boolean;
+/**
+ * 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 declare function activateSilentQa(mute: () => void, options?: ActivateSilentQaOptions): boolean;
+/**
+ * Asynchronous counterpart to {@link activateSilentQa}. The readiness marker
+ * is not published until the consumer's mute promise fulfills.
+ */
+export declare function activateSilentQaAsync(mute: () => void | PromiseLike<void>, options?: ActivateSilentQaOptions): Promise<boolean>;
+/** True after this module has successfully activated the page-lifetime override. */
+export declare function isSilentQaActive(): boolean;
+/** Test hook; production code must never disable a page-lifetime override. */
+export declare function _resetSilentQaForTests(): void;

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

@@ -0,0 +1,69 @@
+export interface VisualBatteryCommand {
+    /** Executable invoked directly, without a shell. */
+    command: string;
+    /** Fixed arguments inserted before the discovered harness paths. */
+    args?: readonly string[];
+}
+export interface VisualBatteryOptions {
+    /** CI mode: refuses to run with a dirty baseline dir, fails on drift instead of updating. */
+    ci?: boolean;
+    /** Repo root the git commands run relative to. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * The `pnpm test:browser`-equivalent command, without harness paths.
+     * Strings are split on whitespace for backward compatibility; use the
+     * object form when an argument contains spaces. Commands execute directly,
+     * never through a shell. Defaults to `'pnpm test:browser'`.
+     */
+    testCommand?: string | VisualBatteryCommand;
+    /** Baseline root relative to `cwd`. Defaults to `${harnessGlob}/__screenshots__`; `baselineProfile` is appended below it. */
+    baselinesDir?: string;
+    /**
+     * Optional platform/profile directory below the baseline root (for example
+     * `linux`). The profile is also exposed to Vite browser tests as
+     * `VITE_VISUAL_BASELINE_PROFILE`, allowing byte-exact baselines to remain
+     * strict on renderers that cannot produce identical PNGs.
+     */
+    baselineProfile?: string;
+    /**
+     * Harness basenames that each need a fresh browser process. Use this for
+     * WebGL screenshots whose renderer state can drift after earlier canvases
+     * have shared a long-lived Chromium process.
+     */
+    isolatedHarnessFiles?: string[];
+    /** Logger, swappable for tests. Defaults to `console.log`/`console.error`. */
+    log?: (msg: string) => void;
+    error?: (msg: string) => void;
+}
+/**
+ * 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 declare class VisualBatteryError extends Error {
+}
+/**
+ * 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 declare function runVisualBattery(harnessDir: string, options?: VisualBatteryOptions): void;

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

@@ -0,0 +1,69 @@
+export interface VisualBatteryCommand {
+    /** Executable invoked directly, without a shell. */
+    command: string;
+    /** Fixed arguments inserted before the discovered harness paths. */
+    args?: readonly string[];
+}
+export interface VisualBatteryOptions {
+    /** CI mode: refuses to run with a dirty baseline dir, fails on drift instead of updating. */
+    ci?: boolean;
+    /** Repo root the git commands run relative to. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * The `pnpm test:browser`-equivalent command, without harness paths.
+     * Strings are split on whitespace for backward compatibility; use the
+     * object form when an argument contains spaces. Commands execute directly,
+     * never through a shell. Defaults to `'pnpm test:browser'`.
+     */
+    testCommand?: string | VisualBatteryCommand;
+    /** Baseline root relative to `cwd`. Defaults to `${harnessGlob}/__screenshots__`; `baselineProfile` is appended below it. */
+    baselinesDir?: string;
+    /**
+     * Optional platform/profile directory below the baseline root (for example
+     * `linux`). The profile is also exposed to Vite browser tests as
+     * `VITE_VISUAL_BASELINE_PROFILE`, allowing byte-exact baselines to remain
+     * strict on renderers that cannot produce identical PNGs.
+     */
+    baselineProfile?: string;
+    /**
+     * Harness basenames that each need a fresh browser process. Use this for
+     * WebGL screenshots whose renderer state can drift after earlier canvases
+     * have shared a long-lived Chromium process.
+     */
+    isolatedHarnessFiles?: string[];
+    /** Logger, swappable for tests. Defaults to `console.log`/`console.error`. */
+    log?: (msg: string) => void;
+    error?: (msg: string) => void;
+}
+/**
+ * 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 declare class VisualBatteryError extends Error {
+}
+/**
+ * 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 declare function runVisualBattery(harnessDir: string, options?: VisualBatteryOptions): void;

package/docs/404.md

@@ -0,0 +1,17 @@
+---
+title: Page not found
+description: This page does not exist.
+editUrl: false
+head:
+  - tag: meta
+    attrs:
+      property: og:title
+      content: Page not found
+tableOfContents: false
+sidebar:
+  hidden: true
+template: splash
+---
+
+The page you're looking for doesn't exist. Head back to the
+[docs home](/game-harness/) or the [getting started guide](/game-harness/getting-started/).

package/docs/agent-guide.md

@@ -0,0 +1,10 @@
+---
+title: Agent development guide
+description: The safe, policy-compliant workflow for trusted coding agents.
+---
+
+Repository instructions for agents live in [AGENTS.md](https://github.com/jbcom/game-harness/blob/main/AGENTS.md). They cover the public API, silent-browser contract, package boundaries, validation, Sourcey documentation architecture, Conventional Commits, and protected merge workflow.
+
+The repository-root `llms.txt` is a concise agent index. Sourcey generates
+separate `llms.txt` and `llms-full.txt` files in the documentation build; those
+describe this documentation site and are not manually maintained copies.

package/docs/architecture.md

@@ -0,0 +1,81 @@
+# Architecture
+
+Game Harness is a small collection of composable verification primitives. It
+does not own a game's tests or runtime state; it makes the boundaries around
+those tests explicit and fail-closed.
+
+## Package boundaries
+
+| Entry point           | Responsibility                                                  | Required peer                          |
+| --------------------- | --------------------------------------------------------------- | -------------------------------------- |
+| package root          | Lighthouse policy, release ladder, visual battery               | None                                   |
+| `/chromium`           | Renderer and mandatory mute launch profile                      | None                                   |
+| `/silent-qa`          | Application-side runtime mute request and readiness marker      | None                                   |
+| `/playwright`         | Device tiers, isolated ports, preview server, silent navigation | `@playwright/test`                     |
+| `/production-runtime` | Fresh server/browser lifecycle and runtime evidence             | `@playwright/test`                     |
+| `/vitest`             | Vitest Browser Mode configuration                               | `vitest`, `@vitest/browser-playwright` |
+| `/lighthouse`         | Immutable Lighthouse CI presets                                 | None                                   |
+| `/release-ladder`     | Ordered sync/async verification steps                           | None                                   |
+| `/visual-battery`     | Deterministic screenshot baseline orchestration                 | None                                   |
+
+The root deliberately does not re-export Playwright or Vitest integrations. A
+consumer that needs only peer-free utilities therefore never loads or installs
+either framework.
+
+## Runtime evidence flow
+
+1. `verifyProductionRuntime()` validates the URL, callbacks, server identity,
+   and lifecycle limits before starting external work.
+2. When a server is configured, its readiness URL must be unreachable first.
+   The command is spawned directly with an argument array and must bind with
+   strict-port behavior.
+3. A fresh browser launches with the selected renderer profile and exactly one
+   final `--mute-audio` argument.
+4. Local-storage sentinels are installed before application code.
+5. `openSilentGame()` adds the runtime-only mute query and waits for the
+   application readiness marker.
+6. The consumer's `assertReady` proves game identity and primary UI. An optional
+   `assertSilentState` proves engine-specific mute state.
+7. Console errors, page errors, failed requests, HTTP errors, and sentinel
+   mutations fail the verification.
+8. Browser and owned server resources are closed on success or failure.
+
+The browser launch argument is defense in depth. The application marker is the
+primary proof that its own audio graph was muted before test interaction. The
+mute adapter never changes the player's persisted preference.
+
+## Visual baseline ownership
+
+`runVisualBattery()` owns one canonical baseline directory. It discovers
+top-level `*.browser.test.ts` and `*.browser.test.tsx` files deterministically,
+runs selected harnesses in direct child processes, requires at least one PNG,
+and asks Git for scoped status with argument arrays rather than shell commands.
+
+Update mode reports reviewed changes. CI mode also refuses a dirty starting
+state and fails on any resulting drift. Renderer-specific output belongs in an
+explicit profile directory rather than behind a permissive pixel threshold.
+
+## Configuration philosophy
+
+Factories provide production-minded defaults and validate inputs at the public
+boundary. Callers can override Playwright and browser-provider details, but the
+silence guard is re-applied after merges. Values that would produce ambiguous
+or empty verification—invalid ports, missing device tiers, empty browser
+matrices, malformed URLs, zero Lighthouse runs, or zero screenshots—fail early
+with actionable errors.
+
+## Build and distribution
+
+TypeScript emits independent ESM, CommonJS, and declaration trees. A nested
+`dist/cjs/package.json` marks the CommonJS output without changing the package's
+top-level ESM identity. Optional peers keep install boundaries narrow. Release
+validation then checks:
+
+- formatting, linting, strict types, and 100% reusable-library source coverage
+  (the two-line executable adapter is exercised through packed CLI smoke tests);
+- both JavaScript module formats and declarations;
+- package metadata and resolution through `publint` and
+  `@arethetypeswrong/cli`;
+- clean tarball consumers for root, Playwright, production runtime, Vitest, and
+  CLI entry points;
+- Linux, macOS, and Windows build/test portability in CI.

package/docs/changelog.md

@@ -0,0 +1,9 @@
+---
+title: Changelog
+description: Release history generated and maintained by release-please.
+---
+
+Game Harness uses release-please and Conventional Commits to create release
+pull requests, versions, GitHub Releases, and this project's changelog.
+
+Read the current [CHANGELOG.md](https://github.com/jbcom/game-harness/blob/main/CHANGELOG.md).