game-harness 1.0.0 → 1.1.0

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,23 @@ All notable changes are recorded here. Releases follow
 [Semantic Versioning](https://semver.org/) and are generated from Conventional
 Commits by release-please.
 
+## [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 +79,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,137 @@
+# 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`).
+
+## 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`, `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

@@ -127,7 +127,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 +257,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 +316,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
 
@@ -556,8 +563,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/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/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

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

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

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

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

package/dist/types/index.d.cts

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

package/dist/types/index.d.ts

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

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

@@ -26,7 +26,7 @@ export interface VerifyReleaseLadderOptions {
  * screenshots → native sync, or whatever a given repo's ladder is), run in
  * sequence and stopped at the first failure with a labeled summary.
  *
- * Generalizes the reach-for-the-sky pattern of ~17 discrete
+ * Generalizes the common pattern of many discrete
  * `node scripts/verify-X.mjs` files composed via a shell `&&` chain into a
  * single reusable primitive: each step is a plain function (sync or async),
  * so a repo can inline its logic or delegate to existing scripts via

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

@@ -26,7 +26,7 @@ export interface VerifyReleaseLadderOptions {
  * screenshots → native sync, or whatever a given repo's ladder is), run in
  * sequence and stopped at the first failure with a labeled summary.
  *
- * Generalizes the reach-for-the-sky pattern of ~17 discrete
+ * Generalizes the common pattern of many discrete
  * `node scripts/verify-X.mjs` files composed via a shell `&&` chain into a
  * single reusable primitive: each step is a plain function (sync or async),
  * so a repo can inline its logic or delegate to existing scripts via

package/docs/architecture.md

@@ -29,8 +29,8 @@ either framework.
 2. When a server is configured, its readiness URL must be unreachable first.
    The command is spawned directly with an argument array and must bind with
    strict-port behavior.
-3. A fresh browser launches with the selected renderer profile and exactly one
-   final `--mute-audio` argument.
+3. A fresh browser launches with the selected renderer profile, the
+   anti-throttling switches, and exactly one final `--mute-audio` argument.
 4. Local-storage sentinels are installed before application code.
 5. `openSilentGame()` adds the runtime-only mute query and waits for the
    application readiness marker.

package/docs/decisions.md

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

package/docs/getting-started.md

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

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

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

package/docs/reference/troubleshooting.md

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

package/docs/sourcey.config.ts

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

package/llms.txt

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

package/maestro/smoke.template.yaml

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-harness",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Release-grade browser QA primitives for TypeScript games: silent Playwright/Vitest sessions, deterministic screenshots, runtime proof, and Lighthouse gates.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "docs",
     "llms.txt",
     "maestro",
+    "MIGRATION.md",
     "LICENSE",
     "README.md"
   ],
@@ -125,8 +126,8 @@
   },
   "peerDependencies": {
     "@playwright/test": ">=1.62.1 <2",
-    "@vitest/browser-playwright": ">=4.1.10 <5",
-    "vitest": ">=4.1.10 <5"
+    "@vitest/browser-playwright": ">=4.1.10 <6",
+    "vitest": ">=4.1.10 <6"
   },
   "peerDependenciesMeta": {
     "@playwright/test": {
@@ -144,14 +145,14 @@
     "@playwright/test": "1.62.1",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.13.3",
-    "@vitest/browser-playwright": "4.1.10",
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/coverage-v8": "5.0.3",
     "oxlint": "1.79.0",
     "prettier": "3.9.6",
     "publint": "0.3.24",
     "rimraf": "6.1.3",
     "typescript": "7.0.2",
-    "vitest": "4.1.10"
+    "vitest": "5.0.3"
   },
   "engines": {
     "node": ">=22"
@@ -189,6 +190,7 @@
     "lint": "oxlint --deny-warnings src tests scripts",
     "package:check": "publint && attw --pack . --profile node16",
     "test": "vitest run",
+    "test:chromium": "vitest run --config vitest.chromium.config.ts",
     "test:package": "node scripts/verify-package-boundaries.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run coverage && pnpm run build && pnpm run package:check && pnpm run test:package"