game-harness 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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)
 
 

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.
@@ -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:

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/decisions.md

@@ -6,6 +6,17 @@ 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.
 
+## 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/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.1",
   "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",