game-harness 1.0.0 → 1.1.1

package/AGENTS.md

@@ -117,6 +117,10 @@ hardcoded version string into a workflow file.
   clean-tarball consumer smoke tests. This is what CI runs; run it before
   every commit.
 - `pnpm test` — unit and contract tests only, for fast iteration.
+- `pnpm test:chromium` — real headed Chromium checks of the launch profile
+  (needs `pnpm exec playwright install chromium`, and `xvfb-run -a` on a
+  Linux host without a display). CI runs it in its own `chromium` job; it is
+  not part of `pnpm verify`, so publishing never depends on a browser.
 - `pnpm --filter game-harness-docs validate` / `pnpm --filter
 game-harness-docs dev` — build or preview the Sourcey docs site in isolation.
 - `pnpm format` — apply Prettier.

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes are recorded here. Releases follow
 [Semantic Versioning](https://semver.org/) and are generated from Conventional
 Commits by release-please.
 
+## [1.1.1](https://github.com/jbcom/game-harness/compare/game-harness-v1.1.0...game-harness-v1.1.1) (2026-10-07)
+
+
+### Bug Fixes
+
+* **visual-battery:** tolerate rasterization noise while failing real drift ([e2ef323](https://github.com/jbcom/game-harness/commit/e2ef323643dc6b09a4991489f579f068c915d078))
+
+## [1.1.0](https://github.com/jbcom/game-harness/compare/game-harness-v1.0.0...game-harness-v1.1.0) (2026-10-07)
+
+
+### Features
+
+* accept Vitest 5 as a peer alongside Vitest 4 ([5d7a86c](https://github.com/jbcom/game-harness/commit/5d7a86c9e0b393e5e00818f89b03160cdd2c7370))
+* **chromium:** keep background and occluded windows on schedule ([ba72078](https://github.com/jbcom/game-harness/commit/ba72078f8d3af5151d63e331eb84253213ac3a08))
+* converge test-harness into game-harness and keep background windows on schedule ([b5295f9](https://github.com/jbcom/game-harness/commit/b5295f9c6fa421198e171b95358f19459a6f5f99))
+* export VisualBatteryCommand from the package root ([ca6dd88](https://github.com/jbcom/game-harness/commit/ca6dd884935bd91ae811168a88e5a8bbbda0629c))
+
+
+### Bug Fixes
+
+* harden release package install ([c74160d](https://github.com/jbcom/game-harness/commit/c74160dc78d43811c94c8249fae40ab9e6bb8632))
+* publish releases from cd workflow ([f6f3b3e](https://github.com/jbcom/game-harness/commit/f6f3b3e5ac1ab8cf3670fb47cb98523f1ce4d1be))
+* publish releases from cd workflow ([c7560ac](https://github.com/jbcom/game-harness/commit/c7560ac921b20ef706f761c14955088bfd07a7f7))
+
 ## [1.0.0](https://github.com/jbcom/game-harness/compare/game-harness-v0.5.0...game-harness-v1.0.0) (2026-08-24)
 
 
@@ -62,8 +86,7 @@ Commits by release-please.
 
 ### Added
 
-- Initial standalone public package extracted from the production browser-game
-  verification harness.
+- Initial standalone public package for browser-game verification.
 - Peer-isolated Playwright and Vitest Browser Mode configuration entry points.
 - Fail-closed silent-QA, production-runtime, visual-regression, Lighthouse, and
   release-ladder primitives.

package/MIGRATION.md

@@ -0,0 +1,144 @@
+# Migrating from a scoped `test-harness` package
+
+Game Harness grew out of a scoped package published privately as
+`@your-scope/test-harness`. Every capability of that package now lives here, under
+the same export names and subpaths. This guide maps each import, option and
+binary, and lists the few places where Game Harness is stricter. The reasoning
+behind each difference is in [docs/decisions.md](docs/decisions.md).
+
+## 1. Swap the dependency
+
+```sh
+pnpm remove @your-scope/test-harness
+pnpm add -D game-harness
+```
+
+Game Harness is on the public npm registry, so a registry mapping for the old
+scope is no longer needed once nothing else uses it. Keep the peers you
+already install: `@playwright/test` for `/playwright` and
+`/production-runtime`, and `vitest` with `@vitest/browser-playwright` for
+`/vitest`. Vitest 4 (from 4.1.10) and Vitest 5 are both supported. Node 22 or
+newer is required.
+
+## 2. Rewrite imports
+
+Only the package name changes. Every subpath and named export is the same.
+
+| Before                                        | After                             |
+| --------------------------------------------- | --------------------------------- |
+| `@your-scope/test-harness`                    | `game-harness`                    |
+| `@your-scope/test-harness/vitest`             | `game-harness/vitest`             |
+| `@your-scope/test-harness/playwright`         | `game-harness/playwright`         |
+| `@your-scope/test-harness/silent-qa`          | `game-harness/silent-qa`          |
+| `@your-scope/test-harness/production-runtime` | `game-harness/production-runtime` |
+| `@your-scope/test-harness/chromium`           | `game-harness/chromium`           |
+| `@your-scope/test-harness/lighthouse`         | `game-harness/lighthouse`         |
+| `@your-scope/test-harness/release-ladder`     | `game-harness/release-ladder`     |
+| `@your-scope/test-harness/visual-battery`     | `game-harness/visual-battery`     |
+| `@your-scope/test-harness/package.json`       | `game-harness/package.json`       |
+
+A single search and replace of the specifier prefix is enough:
+
+```sh
+git grep -lz '@your-scope/test-harness' | xargs -0 perl -pi -e 's#\@your-scope/test-harness#game-harness#g'
+```
+
+Replace `your-scope` in these commands with the scope your project installed
+the package under.
+
+### Export by export
+
+| Subpath               | Exports (identical names)                                                                                                                                                                                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| root                  | `lighthouseAssertions`, `LighthouseAssertionsOverrides`, `LighthouseCiConfig`, `verifyReleaseLadder`, `ReleaseLadderStep`, `ReleaseLadderResult`, `VerifyReleaseLadderOptions`, `runVisualBattery`, `VisualBatteryError`, `VisualBatteryOptions`                                                                      |
+| `/vitest`             | `defineBrowserTestConfig`, `BrowserTestConfigOptions`, `BrowserInstance`                                                                                                                                                                                                                                              |
+| `/playwright`         | `definePlaywrightConfig`, `PlaywrightConfigOptions`, `DeviceTier`, `resolvePlaywrightPort`, `ResolvePlaywrightPortOptions`, `silentTestUrl`, `SilentTestUrlOptions`, `SilentQueryValue`, `openSilentGame`, `OpenSilentGameOptions`                                                                                    |
+| `/silent-qa`          | `activateSilentQa`, `isSilentQaRequested`, `isSilentQaActive`, `_resetSilentQaForTests`, `ActivateSilentQaOptions`, `SilentQaMarkerTarget`, `SILENT_QA_QUERY_PARAMETER`, `SILENT_QA_QUERY_VALUE`, `SILENT_QA_MARKER_ATTRIBUTE`, `SILENT_QA_MARKER_VALUE`                                                              |
+| `/production-runtime` | `verifyProductionRuntime`, `ProductionRuntimeOptions`, `ProductionRuntimeServerOptions`, `ProductionRuntimeResult`, `ProductionRuntimeIssue`, `ProductionRuntimeVerificationError`, `findAvailableProductionPort`, `AvailableProductionPortOptions`, `readWebGLRenderer`, `requireHardwareWebGL`, `WebGLRendererInfo` |
+| `/chromium`           | `createChromiumLaunchProfile`, `ChromiumLaunchProfileOptions`, `ChromiumLaunchProfile`, `ChromiumGpuMode`, `ChromiumEnvironment`                                                                                                                                                                                      |
+| `/lighthouse`         | `lighthouseAssertions`, `LighthouseAssertionsOverrides`, `LighthouseCiConfig`, `LighthousePreset`                                                                                                                                                                                                                     |
+| `/release-ladder`     | `verifyReleaseLadder`, `ReleaseLadderStep`, `ReleaseLadderResult`, `VerifyReleaseLadderOptions`                                                                                                                                                                                                                       |
+| `/visual-battery`     | `runVisualBattery`, `VisualBatteryError`, `VisualBatteryOptions`                                                                                                                                                                                                                                                      |
+
+New in Game Harness: `activateSilentQaAsync` (`/silent-qa`),
+`VisualBatteryCommand` (`/visual-battery` and root) and
+`CHROMIUM_ANTI_THROTTLING_ARGS` (`/chromium`).
+
+Modified PNG baselines now use decoded RGBA comparisons instead of byte equality.
+`maxChannelDelta` defaults to 2 and `maxDifferentPixelRatio` to 0, so every
+pixel beyond ±2 is drift. Noise-only files are restored to committed bytes;
+dimensions and new/deleted files still fail. Use `maxChannelDelta: 0` for exact
+decoded pixels. CLI flags are `--max-channel-delta` and
+`--max-different-pixel-ratio`; see the visual-battery guide for their ranges.
+
+## 3. Options
+
+Every option keeps its name and meaning:
+
+| Options type                     | Options                                                                                                                                                                             |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BrowserTestConfigOptions`       | `contextOptions`, `gpuArgs`, `gpuMode`, `headless`, `ui`, `instances`, `optimizeDeps`, `setupFiles`, `name`, `include`, `fileParallelism`                                           |
+| `PlaywrightConfigOptions`        | `testDir`, `basePath`, `port`, `webServerCommand`, `gpuMode`, `headless`, `deviceTiers`, `extraProjects`, `journeySpecs`, `ciTimeoutMultiplier`, `overrides`                        |
+| `SilentTestUrlOptions`           | `muteQueryParameter`, `muteQueryValue`                                                                                                                                              |
+| `OpenSilentGameOptions`          | `markerSelector`, `markerAttribute`, `markerValue`, `markerTimeout`, `navigationOptions`                                                                                            |
+| `ResolvePlaywrightPortOptions`   | `localPort`, `environment`                                                                                                                                                          |
+| `ProductionRuntimeOptions`       | `url`, `server`, `browserLaunchOptions`, `gpuMode`, `pageOptions`, `silentParameters`, `silentOptions`, `localStorageSentinels`, `assertReady`, `assertSilentState`, `settleTimeMs` |
+| `ProductionRuntimeServerOptions` | `command`, `args`, `cwd`, `env`, `readyUrl`, `startupTimeoutMs`, `shutdownTimeoutMs`                                                                                                |
+| `AvailableProductionPortOptions` | `host`                                                                                                                                                                              |
+| `ActivateSilentQaOptions`        | `search`, `queryParameter`, `markerTarget`, `markerAttribute`, `markerValue`                                                                                                        |
+| `VisualBatteryOptions`           | `ci`, `cwd`, `testCommand`, `baselinesDir`, `baselineProfile`, `isolatedHarnessFiles`, `maxChannelDelta`, `maxDifferentPixelRatio`, `log`, `error`                                  |
+| `LighthouseAssertionsOverrides`  | `staticDistDir`, `url`, `numberOfRuns`, `assertions`                                                                                                                                |
+| `ChromiumLaunchProfileOptions`   | `gpuMode`, `args`, `env`                                                                                                                                                            |
+| `VerifyReleaseLadderOptions`     | `log`, `error`                                                                                                                                                                      |
+
+Environment variables are unchanged: `CI`, `MULTIVIEW`, `VISUAL`, `JOURNEY`,
+`PLAYWRIGHT_PORT`, `PW_PORT`, `PW_HEADLESS`, `PW_REUSE_SERVER`,
+`PW_CHROMIUM_CHANNEL` and `VITE_VISUAL_BASELINE_PROFILE`.
+
+## 4. Binary
+
+| Before                        | After                         |
+| ----------------------------- | ----------------------------- |
+| `test-harness-visual-battery` | `game-harness-visual-battery` |
+
+The old binary name is still installed as an alias, so scripts keep working,
+but new scripts should use `game-harness-visual-battery`. Arguments are the
+same (`[harness-directory] [--ci]`). Unknown flags or a second directory now
+exit with code 2 instead of being ignored.
+
+## 5. Where Game Harness is stricter
+
+These are the only changes that can make a previously passing setup fail.
+Each one fails loudly at configuration time with a message naming the
+problem.
+
+| Situation                                                                                     | What to do                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `testCommand` relies on a shell: `'FOO=1 pnpm test:browser'`, `&&`, pipes or quoted arguments | Move the shell logic into a package script and pass its name (`'pnpm test:visual'`), or pass `{ command: 'pnpm', args: ['test:browser'] }`. No shell is ever started. |
+| `PLAYWRIGHT_PORT` or `PW_PORT` set to a non-port value                                        | Fix or unset it. Game Harness throws instead of falling back to the derived port.                                                                                     |
+| `activateSilentQa` given a callback that returns a promise                                    | Use `await activateSilentQaAsync(mute)`. The readiness marker then appears only after the mute has resolved.                                                          |
+| `basePath` containing `?`, `#`, `.`/`..` segments or encoded slashes                          | Pass a plain pathname. Leading, trailing and repeated slashes are normalized for you.                                                                                 |
+| Empty `deviceTiers`, an unknown tier, or `ciTimeoutMultiplier` that is not positive           | Pass at least one of `desktop`, `mobile`, `tablet`, `foldable`, `ultrawide`, and a positive multiplier.                                                               |
+| Empty Vitest `name`, `instances` or `include`                                                 | Omit the option to get the default, or pass a non-empty value.                                                                                                        |
+| Lighthouse override with an empty `staticDistDir`, an empty `url` list, or `numberOfRuns < 1` | Omit the override or pass a valid value.                                                                                                                              |
+| Code that builds a `LighthouseCiConfig` by hand without `ci.collect.staticDistDir`            | Add it. The result of `lighthouseAssertions()` always includes it.                                                                                                    |
+| `baselinesDir` absolute, or harness or baseline directory outside `cwd`                       | Use a path relative to, and inside, `cwd`.                                                                                                                            |
+| A visual-battery run that writes no PNG baselines                                             | It now fails. Make sure the harness actually takes screenshots.                                                                                                       |
+
+## 6. Behaviour you get for free
+
+- Every launch profile adds `--disable-background-timer-throttling`,
+  `--disable-renderer-backgrounding` and
+  `--disable-backgrounding-occluded-windows`, so background and occluded
+  windows keep their timers on schedule when several headed browsers run at
+  once. If a custom launch passes its own `args`, they are merged with these,
+  and `--mute-audio` is still applied last.
+- Harness files run in a sorted, deterministic order.
+- Visual-battery commands run without a shell, with Windows `.cmd` shims
+  resolved for you.
+
+## 7. Verify
+
+Run the consumer's own full gate (type check, unit tests, browser tests and
+end-to-end tests). A green unit run alone does not prove the browser
+configuration still loads.

package/README.md

@@ -8,7 +8,7 @@
 
 Release-grade browser QA primitives for TypeScript games. Game Harness turns a
 successful build into evidence: fresh silent browser sessions, deterministic
-device tiers, byte-exact screenshot gates, production-runtime assertions,
+device tiers, pixel-tolerant screenshot gates, production-runtime assertions,
 Lighthouse policy, and an ordered release ladder.
 
 It is intentionally a focused library rather than a test framework. Your game
@@ -24,7 +24,8 @@ and Vitest Browser Mode.
   commands use strict-port semantics, and production verification refuses an
   already-reachable readiness URL.
 - **Visual evidence that fails closed.** Screenshot baselines are scoped,
-  profile-aware, and checked through Git without fuzzy thresholds or shell
+  profile-aware, and checked against Git with bounded channel tolerance.
+  Every pixel beyond that tolerance fails by default; commands avoid shell
   interpolation.
 - **Real package boundaries.** Framework peers stay optional and isolated to
   subpath exports, with clean ESM, CommonJS, type, CLI, and install smoke tests.
@@ -127,7 +128,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
@@ -257,7 +258,14 @@ SwiftShader explicitly; `linux-hardware-vulkan` applies the reviewed
 Mesa/ANGLE flags plus `EGL_PLATFORM=surfaceless` for a runner 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.
+guard. Every profile also carries `CHROMIUM_ANTI_THROTTLING_ARGS`
+(`--disable-background-timer-throttling`, `--disable-renderer-backgrounding`,
+`--disable-backgrounding-occluded-windows`), so background and occluded
+windows keep their timers on schedule when several headed browsers run at
+once; Page Visibility still reports `hidden`.
+
+Moving from the scoped `test-harness` package this one grew out of? See
+[MIGRATION.md](MIGRATION.md).
 
 Every browser launched by `definePlaywrightConfig()` or
 `defineBrowserTestConfig()` receives Chromium's `--mute-audio` argument as a
@@ -309,8 +317,8 @@ Before publishing, run `pnpm verify` under the pinned release toolchain. The
 package verifier uses npm 11.17.0 directly from the package directory, packs a
 tarball, and installs it into credential-free temporary consumers for the
 peer-free root, Playwright/production-runtime, and Vitest Browser boundaries.
-The release workflow repeats the full gate before publishing with npm
-provenance.
+The tagged-release job in `cd.yml` repeats the full gate before publishing
+with npm provenance through npm trusted publishing (OIDC).
 
 ## Production runtime verification
 
@@ -370,6 +378,26 @@ server to bind with strict-port semantics so an external race fails closed.
 
 ## Visual battery contract
 
+Modified PNGs are decoded and compared pixel by pixel. `maxChannelDelta`
+(default 2, integer 0–255) tolerates that maximum RGBA channel delta.
+`maxDifferentPixelRatio` (default 0, range 0–1) limits the fraction of pixels
+beyond the channel tolerance: any such pixel fails by default. Dimension
+changes, new/deleted files, and unreadable PNGs always count as drift.
+Accepted renders are restored to committed bytes; noise-only files are logged
+as `rasterization noise (N px within ±2)`. The CI dirty-start check remains strict.
+Use `maxChannelDelta: 0` for exact decoded pixel equality. Raising the ratio
+deliberately permits pixels beyond the channel tolerance.
+
+```ts
+runVisualBattery('tests/harness', {
+  ci: true,
+  maxChannelDelta: 2,
+  maxDifferentPixelRatio: 0,
+});
+```
+
+The CLI exposes `--max-channel-delta 2` and `--max-different-pixel-ratio 0`.
+
 Run the default harness directory in update mode, or enforce committed
 baselines in CI:
 
@@ -390,8 +418,8 @@ 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:
@@ -556,8 +584,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and commit guidance.
 ## 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 [CHANGELOG.md](CHANGELOG.md).
 
 Report defects and feature requests through the repository issue forms. Report

package/dist/cjs/bin/visual-battery.js

@@ -15,11 +15,29 @@ Arguments:
 
 Options:
   --ci                Fail on drift and refuse a dirty starting state
+  --max-channel-delta N  RGBA channel tolerance, integer 0–255 (default: 2)
+  --max-different-pixel-ratio N  Allowed fraction beyond tolerance (default: 0)
   -h, --help          Show this help
 
 The legacy executable name test-harness-visual-battery remains available.`);
     process.exit(0);
 }
+const thresholds = {};
+for (const [flag, key] of [
+    ['--max-channel-delta', 'maxChannelDelta'],
+    ['--max-different-pixel-ratio', 'maxDifferentPixelRatio'],
+]) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        continue;
+    const value = args[index + 1];
+    if (value === undefined || value.trim() === '' || !Number.isFinite(Number(value))) {
+        console.error(`${flag} requires a finite numeric value.`);
+        process.exit(2);
+    }
+    thresholds[key] = Number(value);
+    args.splice(index, 2);
+}
 const unknownFlags = args.filter((argument) => argument.startsWith('-') && argument !== '--ci');
 if (unknownFlags.length > 0) {
     console.error(`Unknown option(s): ${unknownFlags.join(', ')}. Use --help for usage.`);
@@ -33,7 +51,7 @@ if (positionalArgs.length > 1) {
 const ci = args.includes('--ci');
 const harnessDirArg = positionalArgs[0] ?? 'tests/harness';
 try {
-    (0, visual_battery_js_1.runVisualBattery)(harnessDirArg, { ci });
+    (0, visual_battery_js_1.runVisualBattery)(harnessDirArg, { ci, ...thresholds });
 }
 catch (err) {
     if (err instanceof visual_battery_js_1.VisualBatteryError) {

package/dist/cjs/chromium-launch.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHROMIUM_ANTI_THROTTLING_ARGS = void 0;
 exports.createChromiumLaunchProfile = createChromiumLaunchProfile;
 const GPU_ARGS = {
     auto: [],
@@ -12,13 +13,27 @@ const GPU_ARGS = {
     ],
 };
 /**
- * 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.
+ */
+exports.CHROMIUM_ANTI_THROTTLING_ARGS = Object.freeze([
+    '--disable-background-timer-throttling',
+    '--disable-renderer-backgrounding',
+    '--disable-backgrounding-occluded-windows',
+]);
+/**
+ * Builds the shared Chromium renderer, scheduling and silence profile without
+ * deciding whether the browser is headed. Callers own that explicit choice.
  */
 function createChromiumLaunchProfile(options = {}) {
     const gpuMode = options.gpuMode ?? 'auto';
     const args = [
-        ...new Set([...GPU_ARGS[gpuMode], ...(options.args ?? [])].filter((argument) => argument !== '--mute-audio')),
+        ...new Set([...GPU_ARGS[gpuMode], ...exports.CHROMIUM_ANTI_THROTTLING_ARGS, ...(options.args ?? [])].filter((argument) => argument !== '--mute-audio')),
         '--mute-audio',
     ];
     if (gpuMode === 'linux-hardware-vulkan') {

package/dist/cjs/release-ladder.js

@@ -7,7 +7,7 @@ exports.verifyReleaseLadder = verifyReleaseLadder;
  * 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/cjs/visual-battery.js

@@ -9,6 +9,8 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
+const pngjs_1 = require("pngjs");
+const which_1 = __importDefault(require("which"));
 /**
  * Thrown by every `runVisualBattery()` failure path — a missing harness dir,
  * no discovered `.browser.test.ts(x)` files, a misplaced `__screenshots__`
@@ -59,9 +61,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
@@ -76,11 +78,19 @@ function canonicalizePath(target) {
  * exits the process.
  */
 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 = (0, node_path_1.resolve)(cwd);
     const canonicalCwd = (() => {
         try {
@@ -141,10 +151,20 @@ 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 (0, node_path_1.resolve)(which_1.default.sync('git'));
+        }
+        catch (err) {
+            return die(`git executable not found: ${err}`);
+        }
+    })();
     if (ci) {
         let beforeStatus = '';
         try {
-            beforeStatus = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '--', relativeBaselinesDir], {
+            beforeStatus = (0, node_child_process_1.execFileSync)(gitExecutable, ['status', '--porcelain', '--', relativeBaselinesDir], {
                 cwd,
                 encoding: 'utf-8',
             });
@@ -214,7 +234,7 @@ function runVisualBattery(harnessDir, options = {}) {
     log(`baseline screenshots produced: ${baselineCount}`);
     let afterStatus = '';
     try {
-        afterStatus = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '--', relativeBaselinesDir], {
+        afterStatus = (0, node_child_process_1.execFileSync)(gitExecutable, ['status', '--porcelain', '-z', '--untracked-files=all', '--', relativeBaselinesDir], {
             cwd,
             encoding: 'utf-8',
         });
@@ -222,6 +242,50 @@ 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 = pngjs_1.PNG.sync.read((0, node_child_process_1.execFileSync)(gitExecutable, ['show', `HEAD:./${path}`], { cwd }));
+            const current = pngjs_1.PNG.sync.read((0, node_fs_1.readFileSync)((0, node_path_1.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;
+            }
+            (0, node_child_process_1.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/esm/bin/visual-battery.js

@@ -13,11 +13,29 @@ Arguments:
 
 Options:
   --ci                Fail on drift and refuse a dirty starting state
+  --max-channel-delta N  RGBA channel tolerance, integer 0–255 (default: 2)
+  --max-different-pixel-ratio N  Allowed fraction beyond tolerance (default: 0)
   -h, --help          Show this help
 
 The legacy executable name test-harness-visual-battery remains available.`);
     process.exit(0);
 }
+const thresholds = {};
+for (const [flag, key] of [
+    ['--max-channel-delta', 'maxChannelDelta'],
+    ['--max-different-pixel-ratio', 'maxDifferentPixelRatio'],
+]) {
+    const index = args.indexOf(flag);
+    if (index === -1)
+        continue;
+    const value = args[index + 1];
+    if (value === undefined || value.trim() === '' || !Number.isFinite(Number(value))) {
+        console.error(`${flag} requires a finite numeric value.`);
+        process.exit(2);
+    }
+    thresholds[key] = Number(value);
+    args.splice(index, 2);
+}
 const unknownFlags = args.filter((argument) => argument.startsWith('-') && argument !== '--ci');
 if (unknownFlags.length > 0) {
     console.error(`Unknown option(s): ${unknownFlags.join(', ')}. Use --help for usage.`);
@@ -31,7 +49,7 @@ if (positionalArgs.length > 1) {
 const ci = args.includes('--ci');
 const harnessDirArg = positionalArgs[0] ?? 'tests/harness';
 try {
-    runVisualBattery(harnessDirArg, { ci });
+    runVisualBattery(harnessDirArg, { ci, ...thresholds });
 }
 catch (err) {
     if (err instanceof VisualBatteryError) {

package/dist/esm/chromium-launch.js

@@ -9,13 +9,27 @@ const GPU_ARGS = {
     ],
 };
 /**
- * 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 const CHROMIUM_ANTI_THROTTLING_ARGS = Object.freeze([
+    '--disable-background-timer-throttling',
+    '--disable-renderer-backgrounding',
+    '--disable-backgrounding-occluded-windows',
+]);
+/**
+ * Builds the shared Chromium renderer, scheduling and silence profile without
+ * deciding whether the browser is headed. Callers own that explicit choice.
  */
 export function createChromiumLaunchProfile(options = {}) {
     const gpuMode = options.gpuMode ?? 'auto';
     const args = [
-        ...new Set([...GPU_ARGS[gpuMode], ...(options.args ?? [])].filter((argument) => argument !== '--mute-audio')),
+        ...new Set([...GPU_ARGS[gpuMode], ...CHROMIUM_ANTI_THROTTLING_ARGS, ...(options.args ?? [])].filter((argument) => argument !== '--mute-audio')),
         '--mute-audio',
     ];
     if (gpuMode === 'linux-hardware-vulkan') {

package/dist/esm/release-ladder.js

@@ -4,7 +4,7 @@
  * 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