game-harness 1.0.0 → 1.1.1

package/dist/esm/visual-battery.js

@@ -1,7 +1,9 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 import spawn from 'cross-spawn';
+import { PNG } from 'pngjs';
+import which from 'which';
 /**
  * Thrown by every `runVisualBattery()` failure path — a missing harness dir,
  * no discovered `.browser.test.ts(x)` files, a misplaced `__screenshots__`
@@ -51,9 +53,9 @@ function canonicalizePath(target) {
  *
  * 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.
+ * committed in git. Modified PNGs tolerate RGBA channel deltas up to 2 by
+ * default; any pixel beyond that precise tolerance is drift. Noise-only
+ * renders are restored to committed bytes. New/deleted baselines always drift.
  *
  * - Update mode (`ci: false`, the default): runs the harnesses, lets new
  *   baselines land on disk, reports what changed so a human can review
@@ -68,11 +70,19 @@ function canonicalizePath(target) {
  * 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 { ci = false, cwd = process.cwd(), testCommand = 'pnpm test:browser', baselineProfile, isolatedHarnessFiles = [], log = defaultLog, error = defaultError, maxChannelDelta = 2, maxDifferentPixelRatio = 0, } = options;
     const die = (msg) => {
         error(msg);
         throw new VisualBatteryError(msg);
     };
+    if (!Number.isInteger(maxChannelDelta) || maxChannelDelta < 0 || maxChannelDelta > 255) {
+        die('maxChannelDelta must be an integer between 0 and 255');
+    }
+    if (!Number.isFinite(maxDifferentPixelRatio) ||
+        maxDifferentPixelRatio < 0 ||
+        maxDifferentPixelRatio > 1) {
+        die('maxDifferentPixelRatio must be between 0 and 1');
+    }
     const resolvedCwd = resolve(cwd);
     const canonicalCwd = (() => {
         try {
@@ -133,10 +143,20 @@ export function runVisualBattery(harnessDir, options = {}) {
     log(`running ${harnessFiles.length} harness file(s):`);
     for (const f of harnessFiles)
         log(`  - ${f}`);
+    // Resolve the consumer's Git installation once, including PATHEXT on Windows.
+    // All Git subprocesses use the resulting absolute executable path.
+    const gitExecutable = (() => {
+        try {
+            return resolve(which.sync('git'));
+        }
+        catch (err) {
+            return die(`git executable not found: ${err}`);
+        }
+    })();
     if (ci) {
         let beforeStatus = '';
         try {
-            beforeStatus = execFileSync('git', ['status', '--porcelain', '--', relativeBaselinesDir], {
+            beforeStatus = execFileSync(gitExecutable, ['status', '--porcelain', '--', relativeBaselinesDir], {
                 cwd,
                 encoding: 'utf-8',
             });
@@ -206,7 +226,7 @@ export function runVisualBattery(harnessDir, options = {}) {
     log(`baseline screenshots produced: ${baselineCount}`);
     let afterStatus = '';
     try {
-        afterStatus = execFileSync('git', ['status', '--porcelain', '--', relativeBaselinesDir], {
+        afterStatus = execFileSync(gitExecutable, ['status', '--porcelain', '-z', '--untracked-files=all', '--', relativeBaselinesDir], {
             cwd,
             encoding: 'utf-8',
         });
@@ -214,6 +234,50 @@ export function runVisualBattery(harnessDir, options = {}) {
     catch (err) {
         die(`git status failed after harness run: ${err}`);
     }
+    const drift = [];
+    const entries = afterStatus.split('\0').filter(Boolean);
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        const status = entry.slice(0, 2);
+        const path = entry.slice(3);
+        // Renames/copies have a second NUL-delimited path; neither is noise.
+        if (/[RC]/.test(status))
+            index += 1;
+        if (status !== ' M' || !path.endsWith('.png')) {
+            drift.push(entry);
+            continue;
+        }
+        try {
+            const committed = PNG.sync.read(execFileSync(gitExecutable, ['show', `HEAD:./${path}`], { cwd }));
+            const current = PNG.sync.read(readFileSync(resolve(cwd, path)));
+            if (committed.width !== current.width || committed.height !== current.height) {
+                drift.push(entry);
+                continue;
+            }
+            let changed = 0;
+            let beyond = 0;
+            for (let offset = 0; offset < current.data.length; offset += 4) {
+                const delta = Math.max(Math.abs(current.data[offset] - committed.data[offset]), Math.abs(current.data[offset + 1] - committed.data[offset + 1]), Math.abs(current.data[offset + 2] - committed.data[offset + 2]), Math.abs(current.data[offset + 3] - committed.data[offset + 3]));
+                if (delta > 0)
+                    changed += 1;
+                if (delta > maxChannelDelta)
+                    beyond += 1;
+            }
+            if (beyond / (current.width * current.height) > maxDifferentPixelRatio) {
+                drift.push(entry);
+                continue;
+            }
+            execFileSync(gitExecutable, ['checkout', '--', path], { cwd });
+            log(beyond === 0
+                ? `${path}: rasterization noise (${changed} px within ±${maxChannelDelta})`
+                : `${path}: accepted pixel tolerance (${beyond} px beyond ±${maxChannelDelta})`);
+        }
+        catch {
+            // Missing/unreadable committed PNGs or failed restoration must fail closed.
+            drift.push(entry);
+        }
+    }
+    afterStatus = drift.join('\n');
     if (afterStatus.trim().length === 0) {
         log('baselines clean — no visual drift detected.');
         return;

package/dist/types/chromium-launch.d.cts

@@ -15,13 +15,27 @@ export interface ChromiumLaunchProfileOptions {
     env?: Readonly<ChromiumEnvironment>;
 }
 export interface ChromiumLaunchProfile {
-    /** De-duplicated Chromium launch arguments for the selected `gpuMode`, always ending in `--mute-audio`. */
+    /**
+     * De-duplicated Chromium launch arguments: the `gpuMode` renderer flags, the
+     * {@link CHROMIUM_ANTI_THROTTLING_ARGS}, any caller `args`, and always
+     * `--mute-audio` last.
+     */
     args: string[];
     /** Present when `env` overrides were supplied or `gpuMode` is `linux-hardware-vulkan` (which also sets `EGL_PLATFORM`); merged on top of `process.env`. */
     env?: ChromiumEnvironment;
 }
 /**
- * Builds the shared Chromium renderer and silence profile without deciding
- * whether the browser is headed. Callers own that explicit choice.
+ * Keeps timers and rendering on schedule in pages Chromium considers
+ * backgrounded. Several headed windows commonly run at once during a test
+ * suite; without these switches a background tab's timers are coalesced to
+ * one wake-up per second, and an occluded window or backgrounded renderer is
+ * deprioritised, so suites time out for reasons unrelated to the game.
+ * Page Visibility still reports `hidden`, so visibility handling stays
+ * testable.
+ */
+export declare const CHROMIUM_ANTI_THROTTLING_ARGS: readonly string[];
+/**
+ * Builds the shared Chromium renderer, scheduling and silence profile without
+ * deciding whether the browser is headed. Callers own that explicit choice.
  */
 export declare function createChromiumLaunchProfile(options?: ChromiumLaunchProfileOptions): ChromiumLaunchProfile;

package/dist/types/chromium-launch.d.ts

@@ -15,13 +15,27 @@ export interface ChromiumLaunchProfileOptions {
     env?: Readonly<ChromiumEnvironment>;
 }
 export interface ChromiumLaunchProfile {
-    /** De-duplicated Chromium launch arguments for the selected `gpuMode`, always ending in `--mute-audio`. */
+    /**
+     * De-duplicated Chromium launch arguments: the `gpuMode` renderer flags, the
+     * {@link CHROMIUM_ANTI_THROTTLING_ARGS}, any caller `args`, and always
+     * `--mute-audio` last.
+     */
     args: string[];
     /** Present when `env` overrides were supplied or `gpuMode` is `linux-hardware-vulkan` (which also sets `EGL_PLATFORM`); merged on top of `process.env`. */
     env?: ChromiumEnvironment;
 }
 /**
- * Builds the shared Chromium renderer and silence profile without deciding
- * whether the browser is headed. Callers own that explicit choice.
+ * Keeps timers and rendering on schedule in pages Chromium considers
+ * backgrounded. Several headed windows commonly run at once during a test
+ * suite; without these switches a background tab's timers are coalesced to
+ * one wake-up per second, and an occluded window or backgrounded renderer is
+ * deprioritised, so suites time out for reasons unrelated to the game.
+ * Page Visibility still reports `hidden`, so visibility handling stays
+ * testable.
+ */
+export declare const CHROMIUM_ANTI_THROTTLING_ARGS: readonly string[];
+/**
+ * Builds the shared Chromium renderer, scheduling and silence profile without
+ * deciding whether the browser is headed. Callers own that explicit choice.
  */
 export declare function createChromiumLaunchProfile(options?: ChromiumLaunchProfileOptions): ChromiumLaunchProfile;

package/dist/types/index.d.cts

@@ -1,3 +1,3 @@
 export { type LighthouseAssertionsOverrides, type LighthouseCiConfig, lighthouseAssertions, } from './lighthouse.js';
 export { type ReleaseLadderResult, type ReleaseLadderStep, type VerifyReleaseLadderOptions, verifyReleaseLadder, } from './release-ladder.js';
-export { runVisualBattery, VisualBatteryError, type VisualBatteryOptions, } from './visual-battery.js';
+export { runVisualBattery, type VisualBatteryCommand, VisualBatteryError, type VisualBatteryOptions, } from './visual-battery.js';

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
 export { type LighthouseAssertionsOverrides, type LighthouseCiConfig, lighthouseAssertions, } from './lighthouse.js';
 export { type ReleaseLadderResult, type ReleaseLadderStep, type VerifyReleaseLadderOptions, verifyReleaseLadder, } from './release-ladder.js';
-export { runVisualBattery, VisualBatteryError, type VisualBatteryOptions, } from './visual-battery.js';
+export { runVisualBattery, type VisualBatteryCommand, VisualBatteryError, type VisualBatteryOptions, } from './visual-battery.js';

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

@@ -26,7 +26,7 @@ export interface VerifyReleaseLadderOptions {
  * 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
+ * Generalizes the common pattern of many 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

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

@@ -26,7 +26,7 @@ export interface VerifyReleaseLadderOptions {
  * 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
+ * Generalizes the common pattern of many 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

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

@@ -5,6 +5,10 @@ export interface VisualBatteryCommand {
     args?: readonly string[];
 }
 export interface VisualBatteryOptions {
+    /** Maximum absolute RGBA channel delta per pixel (0–255 integer). Defaults to 2. */
+    maxChannelDelta?: number;
+    /** Allowed fraction of pixels beyond the channel tolerance (0–1). Defaults to 0. */
+    maxDifferentPixelRatio?: number;
     /** 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()`. */
@@ -21,8 +25,7 @@ export interface VisualBatteryOptions {
     /**
      * 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.
+     * `VITE_VISUAL_BASELINE_PROFILE`, keeping distinct renderer baselines separate.
      */
     baselineProfile?: string;
     /**
@@ -50,9 +53,9 @@ export declare class VisualBatteryError extends Error {
  *
  * 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.
+ * committed in git. Modified PNGs tolerate RGBA channel deltas up to 2 by
+ * default; any pixel beyond that precise tolerance is drift. Noise-only
+ * renders are restored to committed bytes. New/deleted baselines always drift.
  *
  * - Update mode (`ci: false`, the default): runs the harnesses, lets new
  *   baselines land on disk, reports what changed so a human can review

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

@@ -5,6 +5,10 @@ export interface VisualBatteryCommand {
     args?: readonly string[];
 }
 export interface VisualBatteryOptions {
+    /** Maximum absolute RGBA channel delta per pixel (0–255 integer). Defaults to 2. */
+    maxChannelDelta?: number;
+    /** Allowed fraction of pixels beyond the channel tolerance (0–1). Defaults to 0. */
+    maxDifferentPixelRatio?: number;
     /** 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()`. */
@@ -21,8 +25,7 @@ export interface VisualBatteryOptions {
     /**
      * 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.
+     * `VITE_VISUAL_BASELINE_PROFILE`, keeping distinct renderer baselines separate.
      */
     baselineProfile?: string;
     /**
@@ -50,9 +53,9 @@ export declare class VisualBatteryError extends Error {
  *
  * 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.
+ * committed in git. Modified PNGs tolerate RGBA channel deltas up to 2 by
+ * default; any pixel beyond that precise tolerance is drift. Noise-only
+ * renders are restored to committed bytes. New/deleted baselines always drift.
  *
  * - Update mode (`ci: false`, the default): runs the harnesses, lets new
  *   baselines land on disk, reports what changed so a human can review

package/docs/architecture.md

@@ -29,8 +29,8 @@ either framework.
 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.
+3. A fresh browser launches with the selected renderer profile, the
+   anti-throttling switches, 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.
@@ -52,8 +52,12 @@ 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.
+state and fails on any resulting drift. Modified PNGs are decoded with pngjs;
+dimensions must match, and every pixel whose maximum RGBA channel delta exceeds
+`maxChannelDelta` (default 2) counts toward `maxDifferentPixelRatio` (default 0).
+Accepted renders are restored to committed bytes. New/deleted or unreadable
+baselines remain drift. Renderer-specific output belongs in a separate profile
+when the difference exceeds rasterization noise.
 
 ## Configuration philosophy
 

package/docs/decisions.md

@@ -0,0 +1,165 @@
+---
+title: Decisions
+description: Why the package is shaped the way it is, and how a predecessor harness converged into it.
+---
+
+Each entry records a decision, the reason for it, and what it means for a
+consumer. Newest first.
+
+## Pixel tolerance for screenshot baselines
+
+Byte equality is not stable across renders, even on the same machine. Decode
+modified PNGs with pngjs and compare the maximum absolute RGBA channel delta
+per pixel. `maxChannelDelta` defaults to 2 (out of 255), and
+`maxDifferentPixelRatio` defaults to 0: any pixel beyond that tolerance is
+drift. Dimension changes, new/deleted files, and unreadable PNGs remain drift.
+Noise-only files are restored to committed bytes, keeping the Git diff clean.
+Both thresholds are configurable; raising the ratio explicitly permits real
+changes and should be a deliberate consumer decision.
+
+## Converging a predecessor `test-harness` package
+
+This entry compares the supported migration paths export by export so that
+consumers of an earlier `test-harness` package can move to Game Harness. The step-by-step
+consumer mapping is in [MIGRATION.md](https://github.com/jbcom/game-harness/blob/main/MIGRATION.md).
+
+**Decision:** Game Harness is the one canonical harness. Where both packages
+implement the same thing, Game Harness keeps its own public shape; anything the
+predecessor did that Game Harness did not is added here, with tests.
+
+### Method
+
+1. Diffed every source file of the predecessor's last release against this
+   repository's `main`.
+2. Ran the predecessor's own unit suite against Game Harness's source. Every
+   behavioural test passed (97 of 107). The ten failures were all in the
+   visual battery and mocked `execSync`, an implementation detail Game Harness
+   replaced with shell-free `execFileSync`; the behaviour those tests describe
+   is covered by Game Harness's own suite. The predecessor's package-contract
+   test checks its own package name and is not applicable.
+
+### Entry points
+
+| Subpath               | Predecessor | Game Harness | Notes                                                       |
+| --------------------- | ----------- | ------------ | ----------------------------------------------------------- |
+| `.` (root)            | yes         | yes          | Same re-exports: Lighthouse, release ladder, visual battery |
+| `/vitest`             | yes         | yes          | Same function; Game Harness validates its inputs            |
+| `/playwright`         | yes         | yes          | Same functions; Game Harness validates and normalizes       |
+| `/silent-qa`          | yes         | yes          | Game Harness adds `activateSilentQaAsync`                   |
+| `/production-runtime` | yes         | yes          | Same functions; Game Harness validates URLs and durations   |
+| `/chromium`           | yes         | yes          | Game Harness adds `CHROMIUM_ANTI_THROTTLING_ARGS`           |
+| `/lighthouse`         | yes         | yes          | Same function; result type always carries `staticDistDir`   |
+| `/release-ladder`     | yes         | yes          | Identical behaviour                                         |
+| `/visual-battery`     | yes         | yes          | Game Harness adds `VisualBatteryCommand` and path checks    |
+| `/package.json`       | yes         | yes          |                                                             |
+
+Both packages ship ESM and CommonJS builds. Game Harness additionally ships
+separate `.d.cts` declarations for `require` consumers.
+
+### Exports
+
+Every named export of the predecessor exists in Game Harness under the same
+name and subpath. Game Harness adds three:
+
+| Export                          | Subpath                 | Why                                                                  |
+| ------------------------------- | ----------------------- | -------------------------------------------------------------------- |
+| `activateSilentQaAsync`         | `/silent-qa`            | Publishes the readiness marker only after an async mute resolves     |
+| `VisualBatteryCommand`          | `/visual-battery`, root | Runs the browser suite without a shell                               |
+| `CHROMIUM_ANTI_THROTTLING_ARGS` | `/chromium`             | The scheduling switches every launch profile now carries (see below) |
+
+### Bins
+
+| Predecessor                   | Game Harness                                                |
+| ----------------------------- | ----------------------------------------------------------- |
+| `test-harness-visual-battery` | `game-harness-visual-battery`, and the old name as an alias |
+
+Game Harness's CLI also rejects unknown flags and more than one positional
+directory (exit code 2) instead of silently ignoring them.
+
+### Peers
+
+| Peer                         | Predecessor   | Game Harness  |
+| ---------------------------- | ------------- | ------------- |
+| `@playwright/test`           | `>=1.62.1 <2` | `>=1.62.1 <2` |
+| `vitest`                     | `>=4.1.10 <5` | `>=4.1.10 <6` |
+| `@vitest/browser-playwright` | `>=4.1.10 <5` | `>=4.1.10 <6` |
+| Node (`engines`)             | `>=24.19.0`   | `>=22`        |
+
+All framework peers stay optional; the root never loads them. CI proves the
+packed tarball against Vitest 4.1.10 and 5.0.3.
+
+### Where the shapes differ
+
+Game Harness's shape wins in each case. The consumer-facing consequence is
+listed in MIGRATION.md.
+
+- **Visual battery `testCommand`.** The predecessor passed a string to a
+  shell, so shell syntax (`FOO=1 pnpm …`, `&&`, quoting) worked by accident.
+  Game Harness never starts a shell: a string is split on whitespace, or a
+  `{ command, args }` object is executed directly. Kept because a shell turns
+  a configuration value into a command-injection surface and behaves
+  differently on Windows.
+- **Strict input validation.** Game Harness throws a `TypeError` for an
+  invalid `PLAYWRIGHT_PORT`/`PW_PORT` (the predecessor silently fell back to
+  the derived port), an empty or unknown `deviceTiers` list, a non-positive
+  `ciTimeoutMultiplier`, a `basePath` with a query, fragment or traversal, an
+  empty Vitest project name, `instances` or `include`, and empty or invalid
+  Lighthouse overrides. Kept because a misconfigured gate that silently
+  "passes" is not release evidence.
+- **Async mute callbacks.** The predecessor's `activateSilentQa` accepted a
+  promise-returning callback and published the readiness marker before the
+  mute finished. Game Harness throws and points to `activateSilentQaAsync`.
+- **`LighthouseCiConfig.ci.collect.staticDistDir`** is required in the result
+  type. Every preset already sets it, so only code that builds the type by
+  hand without it is affected.
+- **Visual battery paths.** Game Harness requires the harness and baseline
+  directories to stay inside `cwd`, sorts harness files for a deterministic
+  run order, and fails when a run produces no PNG baselines.
+
+### Deliberately not carried over
+
+- **The predecessor's repository tooling:** its Gitea release workflow,
+  release-label script, anonymous-registry environment helper and the test
+  that pinned that workflow. Game Harness publishes from GitHub with npm
+  trusted publishing and provenance, so none of it applies.
+- **Shell execution for `testCommand`**, for the reason above. A consumer
+  that needs environment variables or chained commands puts them in a
+  package script and passes that script's name.
+
+## Every launch profile disables background throttling
+
+**Decision:** `createChromiumLaunchProfile()` always adds
+`--disable-background-timer-throttling`, `--disable-renderer-backgrounding`
+and `--disable-backgrounding-occluded-windows`, exported as
+`CHROMIUM_ANTI_THROTTLING_ARGS`. Every Playwright project, Vitest Browser
+instance and production-runtime launch inherits them.
+
+**Why:** a browser suite commonly runs several headed windows at once. A tab
+Chromium considers backgrounded has its timers coalesced to one wake-up per
+second, and an occluded window or backgrounded renderer is deprioritised, so
+suites time out for reasons that have nothing to do with the game.
+
+Playwright adds the same switches to its own default arguments today, but the
+profile is the package's contract with every launcher it serves: a custom
+script, a launcher that does not use Playwright, or a caller that passes
+`ignoreDefaultArgs`. Making the switches explicit keeps the guarantee from
+depending on another tool's defaults. They do not change Page Visibility: a
+backgrounded page still reports `hidden`, so a game's pause-on-hide logic
+remains testable.
+
+**Evidence:** `pnpm test:chromium` launches headed Chromium over the raw
+DevTools protocol (Playwright's own switches and focus emulation would mask
+the effect), opens a 50 ms timer in one tab and a second tab in front of it,
+and samples the background tab for three seconds. With the profile the timer
+keeps its schedule; a control case without the switches shows the one-second
+throttling, which proves the scenario really backgrounds the tab.
+
+## Vitest 4 and 5
+
+**Decision:** the `vitest` and `@vitest/browser-playwright` peers accept
+`>=4.1.10 <6`. Development runs on Vitest 5, and the packed-consumer smoke
+runs once against 4.1.10 (the floor) and once against 5.0.3.
+
+**Why:** consumers are moving to Vitest 5, and the config fragment
+`defineBrowserTestConfig()` emits is valid for both majors without a code
+change.

package/docs/getting-started.md

@@ -31,7 +31,7 @@ supported. CI pins the primary gate to the version in `.nvmrc` (currently
 24.19.0, the latest Node 24 LTS patch) and additionally runs the full test
 and build suite against Node 22 on Linux to prove the floor of that range,
 alongside macOS and Windows portability on the pinned version. The current
-conformance matrix is Playwright 1.62.1 and Vitest Browser 4.1.10.
+conformance matrix is Playwright 1.62.1 and Vitest Browser 4.1.10 and 5.0.3.
 Package-boundary consumers run with a credential-free home directory and npm
 configuration, install only the peer family needed by each entry point, and
 exercise ESM, CommonJS, the CLI, silent runtime markers, and Chromium launch

package/docs/guides/chromium-and-silent-qa.md

@@ -24,6 +24,15 @@ exposing `/dev/dri/renderD128`) and always de-duplicates and appends
 `--mute-audio` last, so a caller-supplied arg list can never accidentally
 drop the silence guard.
 
+Every profile also carries `CHROMIUM_ANTI_THROTTLING_ARGS`:
+`--disable-background-timer-throttling`, `--disable-renderer-backgrounding`
+and `--disable-backgrounding-occluded-windows`. When several headed windows
+run at once, Chromium would otherwise coalesce a background tab's timers to
+one wake-up per second and deprioritise occluded windows, and suites time out
+for reasons unrelated to the game. Page Visibility is unaffected: a
+backgrounded page still reports `hidden`, so pause-on-hide logic stays
+testable.
+
 Every browser launched by `definePlaywrightConfig()` or
 `defineBrowserTestConfig()` receives Chromium's `--mute-audio` argument as a
 defense-in-depth guard, including projects with custom launch options. The

package/docs/guides/visual-battery.md

@@ -3,6 +3,27 @@ title: Visual battery
 description: Deterministic, fail-closed screenshot baseline orchestration.
 ---
 
+Modified PNGs are decoded and compared against `HEAD` pixel by pixel.
+`maxChannelDelta` defaults to 2 (integer 0–255): a pixel differs only when
+its maximum absolute RGBA channel delta exceeds this tolerance.
+`maxDifferentPixelRatio` defaults to 0 (range 0–1): any pixel beyond the
+channel tolerance is drift. Dimension changes, new/deleted baselines, and
+unreadable PNGs always count as drift. Accepted renders are restored to
+committed bytes; noise-only files log `rasterization noise (N px within ±2)`.
+The CI dirty-start check still rejects all uncommitted baseline changes.
+
+```ts
+runVisualBattery('tests/harness', {
+  ci: true,
+  maxChannelDelta: 2,
+  maxDifferentPixelRatio: 0,
+});
+```
+
+CLI equivalents: `--max-channel-delta 2 --max-different-pixel-ratio 0`.
+Use a channel delta of 0 for exact decoded pixels. Raising the ratio explicitly
+permits some pixels beyond the tolerance; do so deliberately.
+
 Run the default harness directory in update mode, or enforce committed
 baselines in CI:
 
@@ -24,8 +45,8 @@ The battery rejects any second `__screenshots__` directory nested elsewhere
 under the harness tree; otherwise an apparently green run could leave an
 important screenshot outside the Git diff gate.
 
-When two renderers cannot produce byte-identical PNGs, keep strict profiles
-instead of adding a pixel threshold. Pass `baselineProfile: 'linux'`; the
+When renderers produce genuinely different pixels, keep separate profiles.
+Pass `baselineProfile: 'linux'`; the
 battery compares `__screenshots__/linux/` and exposes the same value to Vite
 as `VITE_VISUAL_BASELINE_PROFILE`. Screenshot helpers should include that
 optional directory in their path:

package/docs/introduction.md

@@ -4,7 +4,7 @@ description: Release-grade browser QA primitives for TypeScript games.
 ---
 
 Game Harness turns a successful build into evidence: silent browser sessions,
-deterministic device tiers, byte-exact screenshots, production-runtime proof,
+deterministic device tiers, pixel-tolerant screenshot gates, production-runtime proof,
 and Lighthouse gates.
 
 It is intentionally a focused library rather than a test framework. Your game

package/docs/reference/troubleshooting.md

@@ -23,8 +23,9 @@ description: Common failure modes and their causes.
 ## Releases and support
 
 Conventional commits on `main` are collected into a release pull request by
-release-please. Merging that pull request creates the GitHub release and
-publishes the exact tag to npm with provenance after `pnpm verify` passes.
+release-please. Merging that pull request creates the GitHub release; its
+published-release event starts `cd.yml`, which verifies and publishes the exact
+tag to npm through OIDC with provenance.
 Changes are recorded in the [CHANGELOG](https://github.com/jbcom/game-harness/blob/main/CHANGELOG.md).
 
 Report defects and feature requests through the

package/docs/sourcey.config.ts

@@ -65,7 +65,7 @@ export default defineConfig({
             },
             {
               group: 'Reference',
-              pages: ['architecture', 'reference/troubleshooting'],
+              pages: ['architecture', 'decisions', 'reference/troubleshooting'],
             },
             {
               group: 'Project',

package/llms.txt

@@ -23,6 +23,7 @@ agent-oriented quick reference before writing code against this package.
 - [Visual battery guide](https://jonbogaty.com/game-harness/guides/visual-battery/): Deterministic screenshot baseline orchestration.
 - [Lighthouse presets & release ladder guide](https://jonbogaty.com/game-harness/guides/lighthouse-and-release-ladder/): CI Lighthouse assertions and the release-step orchestrator.
 - [Architecture reference](https://jonbogaty.com/game-harness/reference/architecture/): Module boundaries, runtime evidence flow, build/distribution guarantees.
+- [Decisions reference](https://jonbogaty.com/game-harness/decisions/): Migration and compatibility decisions and their rationale.
 - [Troubleshooting reference](https://jonbogaty.com/game-harness/reference/troubleshooting/): Common failure modes and releases/support.
 
 ## Optional

package/maestro/smoke.template.yaml

@@ -3,7 +3,7 @@
 # render its first screen" flow; add game-specific flows alongside it as
 # separate .maestro/*.yaml files (they're app-specific user journeys, not
 # shareable config — see game-harness's package notes).
-appId: __APP_ID__ # e.g. com.jbcom.kuroga — must match capacitor.config.ts's appId
+appId: __APP_ID__ # e.g. com.example.game — must match capacitor.config.ts's appId
 ---
 - launchApp
 - assertVisible: