game-harness 1.1.0 → 1.1.2

package/AGENTS.md

@@ -33,7 +33,8 @@ pnpm exec playwright install chromium
 pnpm add -D game-harness
 ```
 
-Node 22 or newer is required.
+Node.js 22, 24 and 26 are supported (`engines.node: >=22`). This maintained-line
+policy does not require equality to a patch release.
 
 ### Entry points
 
@@ -105,8 +106,9 @@ pnpm install --frozen-lockfile
 pnpm verify
 ```
 
-`mise.toml` is local-only. CI reads the Node version from `.nvmrc` and the
-pnpm version from `package.json`'s `packageManager` field via the official
+`mise.toml` is local-only. CI verifies Node majors 22, 24 and 26; `.nvmrc`
+selects major 26 for local development. Release and docs jobs select `lts/*`.
+CI reads the pnpm version from `package.json`'s `packageManager` field via the official
 `actions/setup-node` and `pnpm/action-setup` actions — never edit a
 hardcoded version string into a workflow file.
 

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes are recorded here. Releases follow
 [Semantic Versioning](https://semver.org/) and are generated from Conventional
 Commits by release-please.
 
+## [1.1.2](https://github.com/jbcom/game-harness/compare/game-harness-v1.1.1...game-harness-v1.1.2) (2026-10-07)
+
+
+### Bug Fixes
+
+* declare maintained Node support and standardize CI gates ([86b5dae](https://github.com/jbcom/game-harness/commit/86b5daea84d5680b2a1252e4f4d3dfbccb2754db))
+* declare the supported Node lines and test each in CI ([3454eb6](https://github.com/jbcom/game-harness/commit/3454eb6b13c55593ff12eba1f4ff78edaf51f8f6))
+
+## [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)
 
 

package/MIGRATION.md

@@ -64,6 +64,13 @@ 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:
@@ -79,7 +86,7 @@ Every option keeps its name and meaning:
 | `ProductionRuntimeServerOptions` | `command`, `args`, `cwd`, `env`, `readyUrl`, `startupTimeoutMs`, `shutdownTimeoutMs`                                                                                                |
 | `AvailableProductionPortOptions` | `host`                                                                                                                                                                              |
 | `ActivateSilentQaOptions`        | `search`, `queryParameter`, `markerTarget`, `markerAttribute`, `markerValue`                                                                                                        |
-| `VisualBatteryOptions`           | `ci`, `cwd`, `testCommand`, `baselinesDir`, `baselineProfile`, `isolatedHarnessFiles`, `log`, `error`                                                                               |
+| `VisualBatteryOptions`           | `ci`, `cwd`, `testCommand`, `baselinesDir`, `baselineProfile`, `isolatedHarnessFiles`, `maxChannelDelta`, `maxDifferentPixelRatio`, `log`, `error`                                  |
 | `LighthouseAssertionsOverrides`  | `staticDistDir`, `url`, `numberOfRuns`, `assertions`                                                                                                                                |
 | `ChromiumLaunchProfileOptions`   | `gpuMode`, `args`, `env`                                                                                                                                                            |
 | `VerifyReleaseLadderOptions`     | `log`, `error`                                                                                                                                                                      |

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.
@@ -40,7 +41,7 @@ and Vitest Browser Mode.
 `@jbdevprimary/game-harness` package is a personal-user scope and is being
 retired; update existing dependency declarations and imports to `game-harness`.
 
-Node 22 or newer is required. Install the package plus only the peer family for
+Node.js 22, 24 and 26 are supported. Install the package plus only the peer family for
 the integration you use:
 
 ```sh
@@ -122,11 +123,11 @@ framework entry point it imports. A Playwright-only game, for example, installs
 
 ## Current release matrix
 
-`engines.node` declares `>=22`, the earliest Node LTS line still actively
-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
+`engines.node` declares `>=22`. Supported maintained lines are Node.js 22,
+24 and 26; CI runs the full verification and packed-consumer smoke on each
+line on Linux, plus Node 26 portability on macOS and Windows. `.nvmrc`
+selects major 26 without requiring an exact patch. This is a maintained-line
+policy, not a promise about every historical patch. The current
 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
@@ -312,7 +313,7 @@ Keep `reuseExistingServer` false for release evidence and assert the game
 identity before exercising a journey. A process from another repository on a
 familiar port must never be accepted as proof.
 
-Before publishing, run `pnpm verify` under the pinned release toolchain. The
+Before publishing, run `pnpm verify` under a supported Node line. 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.
@@ -377,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:
 
@@ -397,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:
@@ -505,7 +526,9 @@ An agent integrating this package should read [AGENTS.md](AGENTS.md) first;
 
 ## Development
 
-Use the pinned Node and pnpm versions so the local gate matches CI. With
+Use Node.js 22, 24 or 26, npm 11 for packed-consumer verification, and the
+package's declared pnpm version. On Node 22, install npm 11 with
+`npm install --global npm@11` to avoid npm 10's optional-peer resolver crash. With
 [mise](https://mise.jdx.dev) (recommended — it also reads `.nvmrc` and keeps
 pnpm current via `mise.toml`):
 

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/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/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/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

@@ -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/contributing.md

@@ -3,7 +3,10 @@ title: Contributing
 description: Development, validation, and pull-request expectations.
 ---
 
-Game Harness uses pnpm and Node from `.nvmrc` (Node 22 or newer).
+Game Harness uses pnpm and supports Node.js 22, 24 and 26. `.nvmrc` selects
+major 26 for local development; no exact patch is required.
+Use npm 11 for packed-consumer verification (`npm install --global npm@11`);
+Node 22's bundled npm 10 has an optional-peer resolver crash in that smoke test.
 
 ```sh
 mise install # or: nvm use && corepack enable

package/docs/decisions.md

@@ -6,6 +6,31 @@ description: Why the package is shaped the way it is, and how a predecessor harn
 Each entry records a decision, the reason for it, and what it means for a
 consumer. Newest first.
 
+## Maintained Node lines
+
+Keep `engines.node: >=22`: Node.js 22, 24 and 26 are the supported maintained
+lines. Linux CI runs full verification and packed-consumer smoke on all three;
+local verification covers Node 22 and 26. `.nvmrc` selects major 26, and release
+and documentation jobs use `lts/*`. No hook or script requires an exact patch.
+This policy covers maintained lines rather than every historical patch, and
+does not change runtime behavior or the public API.
+
+Packed-consumer verification uses npm 11 on every CI verification leg. The
+Node 22 bundled npm 10.9.9 crashes in its optional-peer resolver (`edgesOut`)
+when installing the Vitest consumer; npm 11 handles the same tarball and peer
+set. This is verification tooling, not an additional runtime requirement.
+
+## 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

package/docs/getting-started.md

@@ -3,7 +3,7 @@ title: Getting started
 description: Install Game Harness and pick the entry points your game needs.
 ---
 
-Node 22 or newer is required. Install the package plus only the peer family
+Node.js 22, 24 and 26 are supported. Install the package plus only the peer family
 for the integration you use:
 
 ```sh
@@ -26,11 +26,11 @@ the framework entry point it imports — a Playwright-only game installs
 
 ## Current release matrix
 
-`engines.node` declares `>=22`, the earliest Node LTS line still actively
-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
+`engines.node` declares `>=22`. Supported maintained lines are Node.js 22,
+24 and 26; CI runs the full verification and packed-consumer smoke on each
+line on Linux, plus Node 26 portability on macOS and Windows. `.nvmrc`
+selects major 26 without requiring an exact patch. This is a maintained-line
+policy, not a promise about every historical patch. The current
 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-harness",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Release-grade browser QA primitives for TypeScript games: silent Playwright/Vitest sessions, deterministic screenshots, runtime proof, and Lighthouse gates.",
   "type": "module",
   "license": "MIT",
@@ -122,7 +122,9 @@
   "types": "./dist/types/index.d.ts",
   "dependencies": {
     "cross-spawn": "7.0.6",
-    "get-port": "7.2.0"
+    "get-port": "7.2.0",
+    "pngjs": "^7.0.0",
+    "which": "^5.0.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.62.1 <2",
@@ -145,6 +147,8 @@
     "@playwright/test": "1.62.1",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.13.3",
+    "@types/pngjs": "^6.0.5",
+    "@types/which": "^3.0.4",
     "@vitest/browser-playwright": "5.0.3",
     "@vitest/coverage-v8": "5.0.3",
     "oxlint": "1.79.0",