game-harness 1.1.1 → 1.2.0

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.2.0](https://github.com/jbcom/game-harness/compare/game-harness-v1.1.2...game-harness-v1.2.0) (2026-10-10)
+
+
+### Features
+
+* **vitest:** pass the browser server's api, custom commands, failure screenshots and isolation through ([29c6d2d](https://github.com/jbcom/game-harness/commit/29c6d2dbaf099b7dcdf8a9cd2b1ffa621e9d9059))
+
+## [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)
 
 

package/README.md

@@ -41,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
@@ -123,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
@@ -313,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.
@@ -526,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/browser-config.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineBrowserTestConfig = defineBrowserTestConfig;
 const browser_playwright_1 = require("@vitest/browser-playwright");
 const chromium_launch_js_1 = require("./chromium-launch.js");
+const vitest_major_js_1 = require("./vitest-major.js");
 function resolveHeadless(headless) {
     if (typeof headless === 'boolean')
         return headless;
@@ -40,7 +41,7 @@ function resolveHeadless(headless) {
  * one, wrap the test command in `xvfb-run` rather than forcing headless here.
  */
 function defineBrowserTestConfig(opts = {}) {
-    const { contextOptions = {}, gpuArgs = [], gpuMode = 'auto', headless = false, ui = false, instances = [{ browser: 'chromium' }], optimizeDeps = [], setupFiles, name = 'browser', include = ['tests/browser/**/*.browser.test.{ts,tsx}'], fileParallelism = false, } = opts;
+    const { contextOptions = {}, gpuArgs = [], gpuMode = 'auto', headless = false, ui = false, instances = [{ browser: 'chromium' }], optimizeDeps = [], setupFiles, name = 'browser', include = ['tests/browser/**/*.browser.test.{ts,tsx}'], fileParallelism = false, api, commands, screenshotFailures, isolate, } = opts;
     if (!name.trim())
         throw new TypeError('browser project name must not be empty');
     if (instances.length === 0) {
@@ -73,6 +74,19 @@ function defineBrowserTestConfig(opts = {}) {
     if (setupFiles) {
         test.setupFiles = [...setupFiles];
     }
+    if (api) {
+        if ((0, vitest_major_js_1.vitestMajor)() >= 5)
+            test.api = { ...api };
+        // Vitest 4's browser server reads its own `api`; Vitest 5's types no longer carry it.
+        else
+            test.browser.api = { ...api };
+    }
+    if (commands)
+        test.browser = { ...test.browser, commands: { ...commands } };
+    if (screenshotFailures !== undefined)
+        test.browser = { ...test.browser, screenshotFailures };
+    if (isolate !== undefined)
+        test.isolate = isolate;
     if (optimizeDeps.length > 0) {
         // Vitest's `test` fragment has no `optimizeDeps` field (that lives at
         // the top-level Vite config) — surface the caller's list here so a

package/dist/cjs/vitest-major.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vitestMajor = vitestMajor;
+const node_1 = require("vitest/node");
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+function vitestMajor() {
+    const major = Number.parseInt(node_1.version, 10);
+    if (!Number.isFinite(major))
+        throw new Error(`unrecognised Vitest version: ${node_1.version}`);
+    return major;
+}

package/dist/esm/browser-config.js

@@ -1,5 +1,6 @@
 import { playwright } from '@vitest/browser-playwright';
 import { createChromiumLaunchProfile } from './chromium-launch.js';
+import { vitestMajor } from './vitest-major.js';
 function resolveHeadless(headless) {
     if (typeof headless === 'boolean')
         return headless;
@@ -37,7 +38,7 @@ function resolveHeadless(headless) {
  * one, wrap the test command in `xvfb-run` rather than forcing headless here.
  */
 export function defineBrowserTestConfig(opts = {}) {
-    const { contextOptions = {}, gpuArgs = [], gpuMode = 'auto', headless = false, ui = false, instances = [{ browser: 'chromium' }], optimizeDeps = [], setupFiles, name = 'browser', include = ['tests/browser/**/*.browser.test.{ts,tsx}'], fileParallelism = false, } = opts;
+    const { contextOptions = {}, gpuArgs = [], gpuMode = 'auto', headless = false, ui = false, instances = [{ browser: 'chromium' }], optimizeDeps = [], setupFiles, name = 'browser', include = ['tests/browser/**/*.browser.test.{ts,tsx}'], fileParallelism = false, api, commands, screenshotFailures, isolate, } = opts;
     if (!name.trim())
         throw new TypeError('browser project name must not be empty');
     if (instances.length === 0) {
@@ -70,6 +71,19 @@ export function defineBrowserTestConfig(opts = {}) {
     if (setupFiles) {
         test.setupFiles = [...setupFiles];
     }
+    if (api) {
+        if (vitestMajor() >= 5)
+            test.api = { ...api };
+        // Vitest 4's browser server reads its own `api`; Vitest 5's types no longer carry it.
+        else
+            test.browser.api = { ...api };
+    }
+    if (commands)
+        test.browser = { ...test.browser, commands: { ...commands } };
+    if (screenshotFailures !== undefined)
+        test.browser = { ...test.browser, screenshotFailures };
+    if (isolate !== undefined)
+        test.isolate = isolate;
     if (optimizeDeps.length > 0) {
         // Vitest's `test` fragment has no `optimizeDeps` field (that lives at
         // the top-level Vite config) — surface the caller's list here so a

package/dist/esm/vitest-major.js

@@ -0,0 +1,13 @@
+import { version } from 'vitest/node';
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+export function vitestMajor() {
+    const major = Number.parseInt(version, 10);
+    if (!Number.isFinite(major))
+        throw new Error(`unrecognised Vitest version: ${version}`);
+    return major;
+}

package/dist/types/browser-config.d.cts

@@ -1,5 +1,5 @@
 import { type PlaywrightProviderOptions } from '@vitest/browser-playwright';
-import type { TestUserConfig } from 'vitest/node';
+import type { BrowserConfigOptions, TestUserConfig } from 'vitest/node';
 import { type ChromiumGpuMode } from './chromium-launch.js';
 /**
  * A single browser instance entry, as accepted by Vitest Browser Mode's
@@ -64,6 +64,25 @@ export interface BrowserTestConfigOptions {
      * verified your suite tolerates concurrent browser contexts.
      */
     fileParallelism?: boolean;
+    /**
+     * The browser server's address, such as the port a CI slot or a local
+     * port allocator assigned (`{ port, strictPort: true }`). Placed where the
+     * installed Vitest reads it: the top-level `api` on Vitest 5, `browser.api`
+     * on Vitest 4. Omitted, Vitest's default port is used.
+     */
+    api?: BrowserApiConfig;
+    /** Custom browser commands (`browser.commands`), e.g. a pointer drawn along a path. */
+    commands?: NonNullable<BrowserConfigOptions['commands']>;
+    /** `browser.screenshotFailures`. Omitted, Vitest's default applies. */
+    screenshotFailures?: boolean;
+    /** The top-level `isolate` (Vitest 5 retired `browser.isolate` for it). Omitted, Vitest's default applies. */
+    isolate?: boolean;
+}
+/** The browser server's address options: the subset Vitest 4's `browser.api` and Vitest 5's `api` share. */
+export interface BrowserApiConfig {
+    port?: number;
+    strictPort?: boolean;
+    host?: string;
 }
 /**
  * Builds a `test` fragment for a Vitest Browser Mode project, wired for

package/dist/types/browser-config.d.ts

@@ -1,5 +1,5 @@
 import { type PlaywrightProviderOptions } from '@vitest/browser-playwright';
-import type { TestUserConfig } from 'vitest/node';
+import type { BrowserConfigOptions, TestUserConfig } from 'vitest/node';
 import { type ChromiumGpuMode } from './chromium-launch.js';
 /**
  * A single browser instance entry, as accepted by Vitest Browser Mode's
@@ -64,6 +64,25 @@ export interface BrowserTestConfigOptions {
      * verified your suite tolerates concurrent browser contexts.
      */
     fileParallelism?: boolean;
+    /**
+     * The browser server's address, such as the port a CI slot or a local
+     * port allocator assigned (`{ port, strictPort: true }`). Placed where the
+     * installed Vitest reads it: the top-level `api` on Vitest 5, `browser.api`
+     * on Vitest 4. Omitted, Vitest's default port is used.
+     */
+    api?: BrowserApiConfig;
+    /** Custom browser commands (`browser.commands`), e.g. a pointer drawn along a path. */
+    commands?: NonNullable<BrowserConfigOptions['commands']>;
+    /** `browser.screenshotFailures`. Omitted, Vitest's default applies. */
+    screenshotFailures?: boolean;
+    /** The top-level `isolate` (Vitest 5 retired `browser.isolate` for it). Omitted, Vitest's default applies. */
+    isolate?: boolean;
+}
+/** The browser server's address options: the subset Vitest 4's `browser.api` and Vitest 5's `api` share. */
+export interface BrowserApiConfig {
+    port?: number;
+    strictPort?: boolean;
+    host?: string;
 }
 /**
  * Builds a `test` fragment for a Vitest Browser Mode project, wired for

package/dist/types/vitest-major.d.cts

@@ -0,0 +1,7 @@
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+export declare function vitestMajor(): number;

package/dist/types/vitest-major.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The major version of the Vitest the consumer installed. The peer range spans
+ * Vitest 4 and 5, which disagree about where some browser-mode options live
+ * (Vitest 5 moved the browser server's port from `browser.api` to the
+ * top-level `api`, and ignores the old one).
+ */
+export declare function vitestMajor(): number;

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,20 @@ 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

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

@@ -39,3 +39,18 @@ discover on its own) that must also be merged into your top-level
 `vite.config.ts`'s `optimizeDeps.include` — read them off the returned
 fragment's `__optimizeDepsInclude` field, since Vitest's `test` block has no
 `optimizeDeps` field of its own.
+
+A game whose suite needs more of Vitest's browser options passes them through
+rather than spreading over the fragment:
+
+- `api` is the browser server's address, such as the port a CI slot or a
+  local port allocator assigned, with `strictPort: true` so a taken port
+  fails rather than drifting. It is placed where the installed Vitest reads
+  it: the top-level `api` on Vitest 5 (which ignores `browser.api`),
+  `browser.api` on Vitest 4.
+- `commands` registers custom browser commands (`browser.commands`), such as
+  a pointer drawn along a path that `userEvent` cannot draw.
+- `screenshotFailures` sets `browser.screenshotFailures`.
+- `isolate` sets the top-level `isolate`, which replaced `browser.isolate`.
+
+Each is left to Vitest's default when it is not given.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-harness",
-  "version": "1.1.1",
+  "version": "1.2.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",