game-harness 1.2.0 → 1.3.0

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.3.0](https://github.com/jbcom/game-harness/compare/game-harness-v1.2.0...game-harness-v1.3.0) (2026-10-10)
+
+
+### Features
+
+* **chromium:** add the macos-hardware-metal gpu mode ([008f277](https://github.com/jbcom/game-harness/commit/008f2770886e73a2d323b65bb3f6373ea21be426))
+
 ## [1.2.0](https://github.com/jbcom/game-harness/compare/game-harness-v1.1.2...game-harness-v1.2.0) (2026-10-10)
 
 

package/README.md

@@ -180,6 +180,11 @@ make WebGL start. The default `auto` profile lets Chromium select the native
 renderer (including Metal on macOS). `software` is an explicit SwiftShader
 fallback. `linux-hardware-vulkan` applies the reviewed Mesa/ANGLE flags and
 `EGL_PLATFORM=surfaceless` for a runner that exposes `/dev/dri/renderD128`.
+`macos-hardware-metal` asks ANGLE for its Metal backend (`--use-angle=metal
+--ignore-gpu-blocklist`); it is the profile for an Apple Silicon Mac with no
+window session, where `headless: true` still reaches the real GPU (no display
+server or Xvfb is involved), so a render host does not fall back to
+SwiftShader.
 
 Vitest's interactive UI is disabled by default even though the Chromium window
 remains visible. This gives Playwright a fixed viewport and a deterministic
@@ -252,11 +257,12 @@ const browser = await chromium.launch({ args, env, headless: false });
 `createChromiumLaunchProfile()` is the peer-free primitive behind both
 `definePlaywrightConfig()` and `defineBrowserTestConfig()` — use it directly
 when driving Chromium yourself (a custom launch script, `production-runtime`'s
-own internals, or a non-Playwright automation layer). It resolves one of three
+own internals, or a non-Playwright automation layer). It resolves one of four
 renderer policies (`auto` leaves selection to Chromium; `software` opts into
 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`
+`/dev/dri/renderD128`; `macos-hardware-metal` asks ANGLE for its Metal backend
+with `--use-angle=metal --ignore-gpu-blocklist`) 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`,

package/dist/cjs/chromium-launch.js

@@ -11,6 +11,7 @@ const GPU_ARGS = {
         '--use-angle=vulkan',
         '--ignore-gpu-blocklist',
     ],
+    'macos-hardware-metal': ['--use-angle=metal', '--ignore-gpu-blocklist'],
 };
 /**
  * Keeps timers and rendering on schedule in pages Chromium considers

package/dist/esm/chromium-launch.js

@@ -7,6 +7,7 @@ const GPU_ARGS = {
         '--use-angle=vulkan',
         '--ignore-gpu-blocklist',
     ],
+    'macos-hardware-metal': ['--use-angle=metal', '--ignore-gpu-blocklist'],
 };
 /**
  * Keeps timers and rendering on schedule in pages Chromium considers

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

@@ -1,12 +1,16 @@
 /** Browser renderer policy for agent-controlled Chromium sessions. */
-export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan';
+export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan' | 'macos-hardware-metal';
 export type ChromiumEnvironment = Record<string, string | undefined>;
 export interface ChromiumLaunchProfileOptions {
     /**
-     * `auto` leaves renderer selection to Chromium (Metal on macOS, the native
-     * desktop stack elsewhere). `software` opts into SwiftShader explicitly.
+     * `auto` leaves renderer selection to Chromium (Metal on macOS in a headed
+     * window, the native desktop stack elsewhere). `software` opts into
+     * SwiftShader explicitly.
      * `linux-hardware-vulkan` is a proven Mesa/ANGLE profile for a
      * Linux runner with `/dev/dri/renderD128` passed through.
+     * `macos-hardware-metal` asks ANGLE for its Metal backend, which gives a
+     * headless Chromium on an Apple Silicon Mac (no window session needed) the
+     * real GPU instead of SwiftShader.
      */
     gpuMode?: ChromiumGpuMode;
     /** Additional Chromium arguments, de-duplicated ahead of `--mute-audio`. */

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

@@ -1,12 +1,16 @@
 /** Browser renderer policy for agent-controlled Chromium sessions. */
-export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan';
+export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan' | 'macos-hardware-metal';
 export type ChromiumEnvironment = Record<string, string | undefined>;
 export interface ChromiumLaunchProfileOptions {
     /**
-     * `auto` leaves renderer selection to Chromium (Metal on macOS, the native
-     * desktop stack elsewhere). `software` opts into SwiftShader explicitly.
+     * `auto` leaves renderer selection to Chromium (Metal on macOS in a headed
+     * window, the native desktop stack elsewhere). `software` opts into
+     * SwiftShader explicitly.
      * `linux-hardware-vulkan` is a proven Mesa/ANGLE profile for a
      * Linux runner with `/dev/dri/renderD128` passed through.
+     * `macos-hardware-metal` asks ANGLE for its Metal backend, which gives a
+     * headless Chromium on an Apple Silicon Mac (no window session needed) the
+     * real GPU instead of SwiftShader.
      */
     gpuMode?: ChromiumGpuMode;
     /** Additional Chromium arguments, de-duplicated ahead of `--mute-audio`. */

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

@@ -17,10 +17,13 @@ const browser = await chromium.launch({ args, env, headless: false });
 `definePlaywrightConfig()` and `defineBrowserTestConfig()` — use it directly
 when driving Chromium yourself (a custom launch script, `production-runtime`'s
 own internals, or a non-Playwright automation layer). It resolves one of
-three renderer policies (`auto` leaves selection to Chromium; `software`
+four renderer policies (`auto` leaves selection to Chromium; `software`
 opts into 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
+exposing `/dev/dri/renderD128`; `macos-hardware-metal` asks ANGLE for its
+Metal backend with `--use-angle=metal --ignore-gpu-blocklist`, which a
+headless Chromium on an Apple Silicon Mac with no window session honours by
+using the real GPU) and always de-duplicates and appends
 `--mute-audio` last, so a caller-supplied arg list can never accidentally
 drop the silence guard.
 

package/docs/guides/playwright.md

@@ -43,7 +43,11 @@ to make WebGL start. The default `auto` profile lets Chromium select the
 native renderer (including Metal on macOS). `software` is an explicit
 SwiftShader fallback. `linux-hardware-vulkan` applies the reviewed
 Mesa/ANGLE flags and `EGL_PLATFORM=surfaceless` for a runner that exposes
-`/dev/dri/renderD128`.
+`/dev/dri/renderD128`. `macos-hardware-metal` asks ANGLE for its Metal backend
+(`--use-angle=metal --ignore-gpu-blocklist`); it is the profile for an Apple
+Silicon Mac with no window session, where `headless: true` still reaches the
+real GPU (no display server or Xvfb is involved), so a render host does not
+fall back to SwiftShader.
 
 A Gitea runner job using the hardware profile must install
 `mesa-vulkan-drivers` and `xvfb`, require the render device with

package/package.json

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