game-harness 1.0.0

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

@@ -0,0 +1,100 @@
+import { type PlaywrightProviderOptions } from '@vitest/browser-playwright';
+import type { TestUserConfig } from 'vitest/node';
+import { type ChromiumGpuMode } from './chromium-launch.js';
+/**
+ * A single browser instance entry, as accepted by Vitest Browser Mode's
+ * `test.browser.instances` array (one per browser/viewport combination).
+ */
+export interface BrowserInstance {
+    browser: 'chromium' | 'firefox' | 'webkit';
+    [key: string]: unknown;
+}
+export interface BrowserTestConfigOptions {
+    /**
+     * Playwright browser-context options. A device scale factor of 1 is the
+     * default so headed and headless Chromium produce the same deterministic
+     * screenshot dimensions; callers can override it explicitly when a test
+     * needs high-DPI rendering.
+     */
+    contextOptions?: PlaywrightProviderOptions['contextOptions'];
+    /**
+     * Extra Chromium launch args merged after the selected renderer profile.
+     * Forwarded to the Playwright provider's `launchOptions.args`.
+     */
+    gpuArgs?: string[];
+    /** Renderer profile. Defaults to `auto`; software rendering is always explicit. */
+    gpuMode?: ChromiumGpuMode;
+    /**
+     * `true` — always headless. `false` (default) — always headed.
+     * `'ci-only'` — headed locally, headless when `process.env.CI` is set.
+     * CI should normally retain the headed default and supply Xvfb.
+     */
+    headless?: boolean | 'ci-only';
+    /**
+     * Show Vitest's interactive browser UI. Defaults to false so headed runs use
+     * a fixed Playwright viewport and deterministic device scale. The Chromium
+     * window remains visible whenever `headless` is false.
+     */
+    ui?: boolean;
+    /** Browser instances for the `browser.instances` array. Defaults to a single chromium instance. */
+    instances?: BrowserInstance[];
+    /**
+     * Extra module specifiers to add to `optimizeDeps.include`. Useful for
+     * deep-import paths (e.g. `three/examples/jsm/utils/SkeletonUtils.js`)
+     * that Vite's dependency scanner doesn't discover on its own and that
+     * would otherwise trigger a mid-run re-bundle (and a duplicate module
+     * instance) the first time a browser test imports them. Read this field
+     * off the return value (`__optimizeDepsInclude`) and merge it into your
+     * `vite.config.ts`'s own `optimizeDeps.include` — Vitest's `test` fragment
+     * has no `optimizeDeps` field of its own, that lives at the top-level
+     * Vite config.
+     */
+    optimizeDeps?: string[];
+    /** Passed through verbatim to `test.setupFiles`. */
+    setupFiles?: string[];
+    /** Project name. Defaults to `'browser'`. */
+    name?: string;
+    /** Test file glob(s). Defaults to `['tests/browser/**\/*.browser.test.{ts,tsx}']`. */
+    include?: string[];
+    /**
+     * Disable file-level parallelism. A shared Playwright Chromium pool
+     * flakes under parallel browser-test load (independent specs racing for
+     * the same browser context can time out). Defaults to `true` (serialized)
+     * — flip off only once you've
+     * verified your suite tolerates concurrent browser contexts.
+     */
+    fileParallelism?: boolean;
+}
+/**
+ * Builds a `test` fragment for a Vitest Browser Mode project, wired for
+ * real-Chromium (or other Playwright-driven browser) test execution.
+ *
+ * Encodes a reviewed pattern: headed by default both locally and in
+ * CI, silent at the Chromium boundary, and native renderer selection unless a
+ * consumer explicitly requests software or the proven Linux Vulkan profile.
+ *
+ * The returned object is meant to be spread into a Vitest `projects[]`
+ * entry's `test` field (or merged into a top-level `test` block for
+ * single-project setups):
+ *
+ * ```ts
+ * import { defineBrowserTestConfig } from 'game-harness/vitest';
+ *
+ * export default defineConfig({
+ *   test: {
+ *     projects: [
+ *       { extends: true, test: { name: 'unit', environment: 'node', include: [...] } },
+ *       { extends: true, test: defineBrowserTestConfig({
+ *           optimizeDeps: ['three/examples/jsm/utils/SkeletonUtils.js'],
+ *         }) },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * NOTE: a headed browser needs a display server. On Linux CI images without
+ * one, wrap the test command in `xvfb-run` rather than forcing headless here.
+ */
+export declare function defineBrowserTestConfig(opts?: BrowserTestConfigOptions): TestUserConfig & {
+    __optimizeDepsInclude?: string[];
+};

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

@@ -0,0 +1,100 @@
+import { type PlaywrightProviderOptions } from '@vitest/browser-playwright';
+import type { TestUserConfig } from 'vitest/node';
+import { type ChromiumGpuMode } from './chromium-launch.js';
+/**
+ * A single browser instance entry, as accepted by Vitest Browser Mode's
+ * `test.browser.instances` array (one per browser/viewport combination).
+ */
+export interface BrowserInstance {
+    browser: 'chromium' | 'firefox' | 'webkit';
+    [key: string]: unknown;
+}
+export interface BrowserTestConfigOptions {
+    /**
+     * Playwright browser-context options. A device scale factor of 1 is the
+     * default so headed and headless Chromium produce the same deterministic
+     * screenshot dimensions; callers can override it explicitly when a test
+     * needs high-DPI rendering.
+     */
+    contextOptions?: PlaywrightProviderOptions['contextOptions'];
+    /**
+     * Extra Chromium launch args merged after the selected renderer profile.
+     * Forwarded to the Playwright provider's `launchOptions.args`.
+     */
+    gpuArgs?: string[];
+    /** Renderer profile. Defaults to `auto`; software rendering is always explicit. */
+    gpuMode?: ChromiumGpuMode;
+    /**
+     * `true` — always headless. `false` (default) — always headed.
+     * `'ci-only'` — headed locally, headless when `process.env.CI` is set.
+     * CI should normally retain the headed default and supply Xvfb.
+     */
+    headless?: boolean | 'ci-only';
+    /**
+     * Show Vitest's interactive browser UI. Defaults to false so headed runs use
+     * a fixed Playwright viewport and deterministic device scale. The Chromium
+     * window remains visible whenever `headless` is false.
+     */
+    ui?: boolean;
+    /** Browser instances for the `browser.instances` array. Defaults to a single chromium instance. */
+    instances?: BrowserInstance[];
+    /**
+     * Extra module specifiers to add to `optimizeDeps.include`. Useful for
+     * deep-import paths (e.g. `three/examples/jsm/utils/SkeletonUtils.js`)
+     * that Vite's dependency scanner doesn't discover on its own and that
+     * would otherwise trigger a mid-run re-bundle (and a duplicate module
+     * instance) the first time a browser test imports them. Read this field
+     * off the return value (`__optimizeDepsInclude`) and merge it into your
+     * `vite.config.ts`'s own `optimizeDeps.include` — Vitest's `test` fragment
+     * has no `optimizeDeps` field of its own, that lives at the top-level
+     * Vite config.
+     */
+    optimizeDeps?: string[];
+    /** Passed through verbatim to `test.setupFiles`. */
+    setupFiles?: string[];
+    /** Project name. Defaults to `'browser'`. */
+    name?: string;
+    /** Test file glob(s). Defaults to `['tests/browser/**\/*.browser.test.{ts,tsx}']`. */
+    include?: string[];
+    /**
+     * Disable file-level parallelism. A shared Playwright Chromium pool
+     * flakes under parallel browser-test load (independent specs racing for
+     * the same browser context can time out). Defaults to `true` (serialized)
+     * — flip off only once you've
+     * verified your suite tolerates concurrent browser contexts.
+     */
+    fileParallelism?: boolean;
+}
+/**
+ * Builds a `test` fragment for a Vitest Browser Mode project, wired for
+ * real-Chromium (or other Playwright-driven browser) test execution.
+ *
+ * Encodes a reviewed pattern: headed by default both locally and in
+ * CI, silent at the Chromium boundary, and native renderer selection unless a
+ * consumer explicitly requests software or the proven Linux Vulkan profile.
+ *
+ * The returned object is meant to be spread into a Vitest `projects[]`
+ * entry's `test` field (or merged into a top-level `test` block for
+ * single-project setups):
+ *
+ * ```ts
+ * import { defineBrowserTestConfig } from 'game-harness/vitest';
+ *
+ * export default defineConfig({
+ *   test: {
+ *     projects: [
+ *       { extends: true, test: { name: 'unit', environment: 'node', include: [...] } },
+ *       { extends: true, test: defineBrowserTestConfig({
+ *           optimizeDeps: ['three/examples/jsm/utils/SkeletonUtils.js'],
+ *         }) },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * NOTE: a headed browser needs a display server. On Linux CI images without
+ * one, wrap the test command in `xvfb-run` rather than forcing headless here.
+ */
+export declare function defineBrowserTestConfig(opts?: BrowserTestConfigOptions): TestUserConfig & {
+    __optimizeDepsInclude?: string[];
+};

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

@@ -0,0 +1,27 @@
+/** Browser renderer policy for agent-controlled Chromium sessions. */
+export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan';
+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.
+     * `linux-hardware-vulkan` is a proven Mesa/ANGLE profile for a
+     * Linux runner with `/dev/dri/renderD128` passed through.
+     */
+    gpuMode?: ChromiumGpuMode;
+    /** Additional Chromium arguments, de-duplicated ahead of `--mute-audio`. */
+    args?: readonly string[];
+    /** Environment additions. The Linux hardware profile also sets `EGL_PLATFORM=surfaceless`. */
+    env?: Readonly<ChromiumEnvironment>;
+}
+export interface ChromiumLaunchProfile {
+    /** De-duplicated Chromium launch arguments for the selected `gpuMode`, always ending in `--mute-audio`. */
+    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.
+ */
+export declare function createChromiumLaunchProfile(options?: ChromiumLaunchProfileOptions): ChromiumLaunchProfile;

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

@@ -0,0 +1,27 @@
+/** Browser renderer policy for agent-controlled Chromium sessions. */
+export type ChromiumGpuMode = 'auto' | 'software' | 'linux-hardware-vulkan';
+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.
+     * `linux-hardware-vulkan` is a proven Mesa/ANGLE profile for a
+     * Linux runner with `/dev/dri/renderD128` passed through.
+     */
+    gpuMode?: ChromiumGpuMode;
+    /** Additional Chromium arguments, de-duplicated ahead of `--mute-audio`. */
+    args?: readonly string[];
+    /** Environment additions. The Linux hardware profile also sets `EGL_PLATFORM=surfaceless`. */
+    env?: Readonly<ChromiumEnvironment>;
+}
+export interface ChromiumLaunchProfile {
+    /** De-duplicated Chromium launch arguments for the selected `gpuMode`, always ending in `--mute-audio`. */
+    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.
+ */
+export declare function createChromiumLaunchProfile(options?: ChromiumLaunchProfileOptions): ChromiumLaunchProfile;

package/dist/types/index.d.cts

@@ -0,0 +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';

package/dist/types/index.d.ts

@@ -0,0 +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';

package/dist/types/lighthouse.d.cts

@@ -0,0 +1,44 @@
+export interface LighthouseCiConfig {
+    ci: {
+        collect: {
+            staticDistDir: string;
+            url: string[];
+            numberOfRuns: number;
+            settings: {
+                preset: string;
+                chromeFlags: string;
+            };
+        };
+        assert: {
+            preset: string;
+            assertions: Record<string, unknown>;
+        };
+        upload: {
+            target: string;
+        };
+    };
+}
+export interface LighthouseAssertionsOverrides {
+    staticDistDir?: string;
+    url?: string[];
+    numberOfRuns?: number;
+    assertions?: Record<string, unknown>;
+}
+declare const PRESETS: Record<string, LighthouseCiConfig>;
+/**
+ * Returns a Lighthouse CI (`lighthouserc.json`) config object for a named
+ * preset, with an escape hatch for per-repo overrides merged on top.
+ *
+ * ```ts
+ * // lighthouserc.mjs
+ * import { lighthouseAssertions } from 'game-harness';
+ * export default lighthouseAssertions('game-default');
+ * ```
+ *
+ * Or, to keep `lighthouserc.json` as static JSON, run this once and paste
+ * the output — the factory has no runtime dependency on the consumer's
+ * environment beyond the overrides you pass.
+ */
+export type LighthousePreset = keyof typeof PRESETS | (string & {});
+export declare function lighthouseAssertions(preset?: LighthousePreset, overrides?: LighthouseAssertionsOverrides): LighthouseCiConfig;
+export {};

package/dist/types/lighthouse.d.ts

@@ -0,0 +1,44 @@
+export interface LighthouseCiConfig {
+    ci: {
+        collect: {
+            staticDistDir: string;
+            url: string[];
+            numberOfRuns: number;
+            settings: {
+                preset: string;
+                chromeFlags: string;
+            };
+        };
+        assert: {
+            preset: string;
+            assertions: Record<string, unknown>;
+        };
+        upload: {
+            target: string;
+        };
+    };
+}
+export interface LighthouseAssertionsOverrides {
+    staticDistDir?: string;
+    url?: string[];
+    numberOfRuns?: number;
+    assertions?: Record<string, unknown>;
+}
+declare const PRESETS: Record<string, LighthouseCiConfig>;
+/**
+ * Returns a Lighthouse CI (`lighthouserc.json`) config object for a named
+ * preset, with an escape hatch for per-repo overrides merged on top.
+ *
+ * ```ts
+ * // lighthouserc.mjs
+ * import { lighthouseAssertions } from 'game-harness';
+ * export default lighthouseAssertions('game-default');
+ * ```
+ *
+ * Or, to keep `lighthouserc.json` as static JSON, run this once and paste
+ * the output — the factory has no runtime dependency on the consumer's
+ * environment beyond the overrides you pass.
+ */
+export type LighthousePreset = keyof typeof PRESETS | (string & {});
+export declare function lighthouseAssertions(preset?: LighthousePreset, overrides?: LighthouseAssertionsOverrides): LighthouseCiConfig;
+export {};

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

@@ -0,0 +1,122 @@
+import { type Page, type PlaywrightTestConfig, type Response } from '@playwright/test';
+import { type ChromiumGpuMode } from './chromium-launch.js';
+export { SILENT_QA_MARKER_ATTRIBUTE, SILENT_QA_MARKER_VALUE, SILENT_QA_QUERY_PARAMETER, SILENT_QA_QUERY_VALUE, } from './silent-qa.js';
+export type DeviceTier = 'desktop' | 'mobile' | 'tablet' | 'foldable' | 'ultrawide';
+type Project = NonNullable<PlaywrightTestConfig['projects']>[number];
+export type SilentQueryValue = string | number | boolean;
+export interface SilentTestUrlOptions {
+    /** Runtime-only mute query parameter. Defaults to `muted`. */
+    muteQueryParameter?: string;
+    /** Runtime-only mute query value. Defaults to `1`. */
+    muteQueryValue?: string;
+}
+export interface OpenSilentGameOptions extends SilentTestUrlOptions {
+    /** DOM selector that owns the mute-ready marker. Defaults to `html`. */
+    markerSelector?: string;
+    /** Marker attribute set only after runtime audio is muted. */
+    markerAttribute?: string;
+    /** Required marker value. Defaults to `muted-test`. */
+    markerValue?: string;
+    /** Maximum time to wait for the application mute marker. Defaults to 5 seconds. */
+    markerTimeout?: number;
+    /** Options forwarded to `page.goto()`. */
+    navigationOptions?: NonNullable<Parameters<Page['goto']>[1]>;
+}
+export interface ResolvePlaywrightPortOptions {
+    /** Stable local-development port. Defaults to 4173. */
+    localPort?: number;
+    /** Injectable environment for deterministic consumers and tests. Defaults to `process.env`. */
+    environment?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Adds a non-persistent mute mode to a relative or absolute URL.
+ * Explicit caller parameters replace existing values, and the mute value is
+ * applied last so a stale `muted=0` can never make an agent run audible.
+ */
+export declare function silentTestUrl(target?: string, parameters?: Readonly<Record<string, SilentQueryValue>>, options?: SilentTestUrlOptions): string;
+/**
+ * Navigates to a game in runtime-only mute mode and fails closed until the
+ * application confirms that audio was muted before test interaction begins.
+ */
+export declare function openSilentGame(page: Page, target?: string, parameters?: Readonly<Record<string, SilentQueryValue>>, options?: OpenSilentGameOptions): Promise<Response | null>;
+export interface PlaywrightConfigOptions {
+    /** Playwright `testDir`. Defaults to `'./tests'`. */
+    testDir?: string;
+    /** Base path the dev/preview server serves from. Defaults to `'/'`. */
+    basePath?: string;
+    /** Port for the local webServer + baseURL. Defaults to 4173, overridable via `PLAYWRIGHT_PORT`/`PW_PORT`. */
+    port?: number;
+    /**
+     * Builds a custom web-server command with the already-resolved local or
+     * CI-isolated port. Prefer this over hard-coding a port in
+     * `overrides.webServer.command`.
+     */
+    webServerCommand?: (port: number) => string;
+    /** Renderer profile. Defaults to native Chromium selection (`auto`). */
+    gpuMode?: ChromiumGpuMode;
+    /**
+     * `false` (default) keeps Chromium headed locally and in CI. Use Xvfb on
+     * Linux CI. `true` is explicit headless mode; `ci-only` retains the older
+     * hosted-runner behavior when a display is genuinely unavailable.
+     */
+    headless?: boolean | 'ci-only';
+    /**
+     * Which device-tier Playwright projects to include. `desktop` is always
+     * present as the tier-1 CI gate; passing more tiers here is equivalent to
+     * the `MULTIVIEW=1` convention already wired below — you don't
+     * need to also request `desktop` explicitly.
+     * Defaults to `['desktop']` (single project, matching the fast CI gate),
+     * expanding to all requested tiers when `MULTIVIEW=1` or `VISUAL=1` is set.
+     */
+    deviceTiers?: DeviceTier[];
+    /** Extra Playwright projects appended after the device-tier projects. */
+    extraProjects?: Project[];
+    /**
+     * Spec globs that only run when `JOURNEY=1` is set (or when `VISUAL=1` is
+     * set, since visual runs imply the full journey suite). These are
+     * "agent review harness" specs — expensive artefact-producing runs, not
+     * part of the fast tier-1 functional gate. Excluded from `testIgnore`
+     * otherwise.
+     */
+    journeySpecs?: string[];
+    /**
+     * Multiplier applied to the local (non-CI) timeout defaults to derive the
+     * CI timeout. CI runners are consistently slower under WebGL/render load;
+     * defaults to 4 (45s local → 180s CI action-adjacent test timeout, scaled
+     * per-field below).
+     */
+    ciTimeoutMultiplier?: number;
+    /**
+     * Overrides merged last, escape-hatch for anything this factory doesn't
+     * expose. `use` and `webServer` are merged one level deep on top of the
+     * computed defaults (see `definePlaywrightConfig`'s return); every other
+     * field fully replaces.
+     */
+    overrides?: Omit<Partial<PlaywrightTestConfig>, 'use' | 'webServer'> & {
+        use?: Partial<NonNullable<PlaywrightTestConfig['use']>>;
+        webServer?: Partial<Extract<NonNullable<PlaywrightTestConfig['webServer']>, {
+            command?: string;
+        }>>;
+    };
+}
+/**
+ * Resolves one stable Playwright preview port for every config reload in an
+ * Actions job. Explicit `PLAYWRIGHT_PORT`/`PW_PORT` values win; local runs use
+ * `localPort`; GitHub/Gitea CI hashes repository, run, job, and local port into
+ * an isolated port range.
+ */
+export declare function resolvePlaywrightPort(options?: ResolvePlaywrightPortOptions): number;
+/**
+ * Builds a full Playwright config, encoding a tiered-device +
+ * env-gated-suite convention:
+ *
+ * - `desktop` project always runs; `MULTIVIEW=1` (or `VISUAL=1`) expands to
+ *   every requested device tier (mobile/tablet/foldable/ultrawide).
+ * - `JOURNEY=1` (or `VISUAL=1`) opts into expensive artefact-producing specs
+ *   that are excluded from the default tier-1 functional gate so CI stays
+ *   fast.
+ * - `VISUAL=1` additionally adds `visualSpecs` to the test match glob.
+ * - CI timeouts scale up from local defaults via `ciTimeoutMultiplier`
+ *   (CI runners run WebGL/render-heavy tests 2-4x slower than local dev).
+ */
+export declare function definePlaywrightConfig(opts?: PlaywrightConfigOptions): PlaywrightTestConfig;

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

@@ -0,0 +1,122 @@
+import { type Page, type PlaywrightTestConfig, type Response } from '@playwright/test';
+import { type ChromiumGpuMode } from './chromium-launch.js';
+export { SILENT_QA_MARKER_ATTRIBUTE, SILENT_QA_MARKER_VALUE, SILENT_QA_QUERY_PARAMETER, SILENT_QA_QUERY_VALUE, } from './silent-qa.js';
+export type DeviceTier = 'desktop' | 'mobile' | 'tablet' | 'foldable' | 'ultrawide';
+type Project = NonNullable<PlaywrightTestConfig['projects']>[number];
+export type SilentQueryValue = string | number | boolean;
+export interface SilentTestUrlOptions {
+    /** Runtime-only mute query parameter. Defaults to `muted`. */
+    muteQueryParameter?: string;
+    /** Runtime-only mute query value. Defaults to `1`. */
+    muteQueryValue?: string;
+}
+export interface OpenSilentGameOptions extends SilentTestUrlOptions {
+    /** DOM selector that owns the mute-ready marker. Defaults to `html`. */
+    markerSelector?: string;
+    /** Marker attribute set only after runtime audio is muted. */
+    markerAttribute?: string;
+    /** Required marker value. Defaults to `muted-test`. */
+    markerValue?: string;
+    /** Maximum time to wait for the application mute marker. Defaults to 5 seconds. */
+    markerTimeout?: number;
+    /** Options forwarded to `page.goto()`. */
+    navigationOptions?: NonNullable<Parameters<Page['goto']>[1]>;
+}
+export interface ResolvePlaywrightPortOptions {
+    /** Stable local-development port. Defaults to 4173. */
+    localPort?: number;
+    /** Injectable environment for deterministic consumers and tests. Defaults to `process.env`. */
+    environment?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Adds a non-persistent mute mode to a relative or absolute URL.
+ * Explicit caller parameters replace existing values, and the mute value is
+ * applied last so a stale `muted=0` can never make an agent run audible.
+ */
+export declare function silentTestUrl(target?: string, parameters?: Readonly<Record<string, SilentQueryValue>>, options?: SilentTestUrlOptions): string;
+/**
+ * Navigates to a game in runtime-only mute mode and fails closed until the
+ * application confirms that audio was muted before test interaction begins.
+ */
+export declare function openSilentGame(page: Page, target?: string, parameters?: Readonly<Record<string, SilentQueryValue>>, options?: OpenSilentGameOptions): Promise<Response | null>;
+export interface PlaywrightConfigOptions {
+    /** Playwright `testDir`. Defaults to `'./tests'`. */
+    testDir?: string;
+    /** Base path the dev/preview server serves from. Defaults to `'/'`. */
+    basePath?: string;
+    /** Port for the local webServer + baseURL. Defaults to 4173, overridable via `PLAYWRIGHT_PORT`/`PW_PORT`. */
+    port?: number;
+    /**
+     * Builds a custom web-server command with the already-resolved local or
+     * CI-isolated port. Prefer this over hard-coding a port in
+     * `overrides.webServer.command`.
+     */
+    webServerCommand?: (port: number) => string;
+    /** Renderer profile. Defaults to native Chromium selection (`auto`). */
+    gpuMode?: ChromiumGpuMode;
+    /**
+     * `false` (default) keeps Chromium headed locally and in CI. Use Xvfb on
+     * Linux CI. `true` is explicit headless mode; `ci-only` retains the older
+     * hosted-runner behavior when a display is genuinely unavailable.
+     */
+    headless?: boolean | 'ci-only';
+    /**
+     * Which device-tier Playwright projects to include. `desktop` is always
+     * present as the tier-1 CI gate; passing more tiers here is equivalent to
+     * the `MULTIVIEW=1` convention already wired below — you don't
+     * need to also request `desktop` explicitly.
+     * Defaults to `['desktop']` (single project, matching the fast CI gate),
+     * expanding to all requested tiers when `MULTIVIEW=1` or `VISUAL=1` is set.
+     */
+    deviceTiers?: DeviceTier[];
+    /** Extra Playwright projects appended after the device-tier projects. */
+    extraProjects?: Project[];
+    /**
+     * Spec globs that only run when `JOURNEY=1` is set (or when `VISUAL=1` is
+     * set, since visual runs imply the full journey suite). These are
+     * "agent review harness" specs — expensive artefact-producing runs, not
+     * part of the fast tier-1 functional gate. Excluded from `testIgnore`
+     * otherwise.
+     */
+    journeySpecs?: string[];
+    /**
+     * Multiplier applied to the local (non-CI) timeout defaults to derive the
+     * CI timeout. CI runners are consistently slower under WebGL/render load;
+     * defaults to 4 (45s local → 180s CI action-adjacent test timeout, scaled
+     * per-field below).
+     */
+    ciTimeoutMultiplier?: number;
+    /**
+     * Overrides merged last, escape-hatch for anything this factory doesn't
+     * expose. `use` and `webServer` are merged one level deep on top of the
+     * computed defaults (see `definePlaywrightConfig`'s return); every other
+     * field fully replaces.
+     */
+    overrides?: Omit<Partial<PlaywrightTestConfig>, 'use' | 'webServer'> & {
+        use?: Partial<NonNullable<PlaywrightTestConfig['use']>>;
+        webServer?: Partial<Extract<NonNullable<PlaywrightTestConfig['webServer']>, {
+            command?: string;
+        }>>;
+    };
+}
+/**
+ * Resolves one stable Playwright preview port for every config reload in an
+ * Actions job. Explicit `PLAYWRIGHT_PORT`/`PW_PORT` values win; local runs use
+ * `localPort`; GitHub/Gitea CI hashes repository, run, job, and local port into
+ * an isolated port range.
+ */
+export declare function resolvePlaywrightPort(options?: ResolvePlaywrightPortOptions): number;
+/**
+ * Builds a full Playwright config, encoding a tiered-device +
+ * env-gated-suite convention:
+ *
+ * - `desktop` project always runs; `MULTIVIEW=1` (or `VISUAL=1`) expands to
+ *   every requested device tier (mobile/tablet/foldable/ultrawide).
+ * - `JOURNEY=1` (or `VISUAL=1`) opts into expensive artefact-producing specs
+ *   that are excluded from the default tier-1 functional gate so CI stays
+ *   fast.
+ * - `VISUAL=1` additionally adds `visualSpecs` to the test match glob.
+ * - CI timeouts scale up from local defaults via `ciTimeoutMultiplier`
+ *   (CI runners run WebGL/render-heavy tests 2-4x slower than local dev).
+ */
+export declare function definePlaywrightConfig(opts?: PlaywrightConfigOptions): PlaywrightTestConfig;