@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/save/store.js

@@ -0,0 +1,269 @@
+import { defaultHost } from '../host/default.js';
+import { decodeExport, encodeExport, isEnvelope, saveReplacer, saveReviver, } from './codec.js';
+import { assertMigrationChain, runMigrations } from './migrate.js';
+import { isQuotaError } from './storage.js';
+const NAME_RE = /^[a-z0-9][a-z0-9_-]*$/i;
+/** `thunderclap:<game>:<slot>` */
+export function saveKey(game, slot) {
+    if (!NAME_RE.test(game))
+        throw new Error(`invalid save game id "${game}"`);
+    if (!NAME_RE.test(slot))
+        throw new Error(`invalid save slot "${slot}"`);
+    return `thunderclap:${game}:${slot}`;
+}
+/** Slot names that currently have data for `game` (excludes backups). */
+export function listSlots(game, storage = defaultHost().storage.open()) {
+    if (!storage)
+        return [];
+    const prefix = `thunderclap:${game}:`;
+    const out = [];
+    try {
+        for (let i = 0; i < storage.length; i++) {
+            const k = storage.key(i);
+            if (k?.startsWith(prefix) && !k.endsWith(':backup') && !k.endsWith(':meta'))
+                out.push(k.slice(prefix.length));
+        }
+    }
+    catch {
+        return [];
+    }
+    return out.sort();
+}
+export function createSaveStore(opts) {
+    const key = saveKey(opts.game, opts.slot ?? 'main');
+    const backupKey = `${key}:backup`;
+    const metaKey = `${key}:meta`;
+    const version = opts.version;
+    if (!Number.isInteger(version) || version < 1)
+        throw new Error('save version must be an integer ≥ 1');
+    const migrations = opts.migrations ?? {};
+    assertMigrationChain(version, migrations);
+    const debounceMs = opts.debounceMs ?? 250;
+    const now = opts.now ?? Date.now;
+    const check = typeof opts.schema === 'function'
+        ? (v) => opts.schema(v) ? null : 'save data failed schema check'
+        : (v) => opts.schema.validate(v);
+    const source = opts.storage === undefined ? (opts.host ?? defaultHost()).storage : null;
+    let storage = source ? source.open() : (opts.storage ?? null);
+    const status = {
+        persistent: storage !== null,
+        loadResult: 'fresh',
+        error: storage === null ? 'storage unavailable; progress is kept in memory only' : null,
+        dirty: false,
+    };
+    const listeners = new Set();
+    let data;
+    let savedAt = 0;
+    let timer = null;
+    const notify = () => {
+        for (const fn of listeners)
+            fn(status);
+    };
+    /** Turn an envelope into current-version data, or throw with a reason. */
+    const adopt = (env) => {
+        const value = runMigrations(env.d, env.v, version, migrations);
+        const err = check(value);
+        if (err)
+            throw new Error(err);
+        return { value: value, migrated: env.v !== version };
+    };
+    const readRaw = () => {
+        if (!storage)
+            return null;
+        try {
+            return storage.getItem(key);
+        }
+        catch (err) {
+            status.persistent = false;
+            status.error = `storage read failed: ${String(err)}`;
+            return null;
+        }
+    };
+    const backup = (raw) => {
+        try {
+            storage?.setItem(backupKey, raw);
+        }
+        catch {
+            // Best effort.
+        }
+    };
+    // ---- initial load ----
+    const raw = readRaw();
+    data = opts.defaults();
+    if (raw !== null) {
+        try {
+            const parsed = JSON.parse(raw, saveReviver);
+            if (!isEnvelope(parsed))
+                throw new Error('stored value has no version envelope');
+            const { value, migrated } = adopt(parsed);
+            data = value;
+            savedAt = parsed.t;
+            status.loadResult = migrated ? 'migrated' : 'loaded';
+            status.dirty = migrated;
+            // Keep the pre-migration bytes until the player has played on the new version a while.
+            if (migrated)
+                backup(raw);
+        }
+        catch (err) {
+            backup(raw);
+            status.loadResult = 'recovered';
+            status.error = `could not load save (kept a backup): ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    const write = () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (!status.dirty)
+            return status.persistent;
+        savedAt = now();
+        const env = { v: version, t: savedAt, d: data };
+        if (!storage) {
+            // Re-probe: storage may have become available (e.g. user changed a browser setting).
+            if (source)
+                storage = source.open();
+        }
+        if (storage) {
+            try {
+                const text = JSON.stringify(env, saveReplacer);
+                storage.setItem(key, text);
+                status.persistent = true;
+                status.error = null;
+                if (opts.meta)
+                    writeMeta(storage, text.length);
+            }
+            catch (err) {
+                status.persistent = false;
+                status.error = isQuotaError(err)
+                    ? 'storage is full; progress is kept in memory only'
+                    : `storage write failed; progress is kept in memory only (${String(err)})`;
+            }
+        }
+        else {
+            status.persistent = false;
+        }
+        status.dirty = false;
+        notify();
+        return status.persistent;
+    };
+    const writeMeta = (target, size) => {
+        try {
+            const m = { ...opts.meta(data), v: version, t: savedAt, size };
+            target.setItem(metaKey, JSON.stringify(m));
+        }
+        catch {
+            // Best effort: the data is saved; the menu falls back to reading it.
+        }
+    };
+    const schedule = () => {
+        status.dirty = true;
+        if (debounceMs <= 0) {
+            write();
+            return;
+        }
+        if (timer === null)
+            timer = setTimeout(write, debounceMs);
+        notify();
+    };
+    const set = (next) => {
+        const err = check(next);
+        if (err) {
+            status.error = `rejected invalid save data: ${err}`;
+            console.warn(`[save] ${status.error}`);
+            notify();
+            return false;
+        }
+        data = next;
+        schedule();
+        return true;
+    };
+    // ---- auto flush on page hide ----
+    const autoFlush = opts.autoFlush ?? typeof window !== 'undefined';
+    const onHide = () => {
+        if (typeof document === 'undefined' || document.visibilityState === 'hidden')
+            write();
+    };
+    const onPageHide = () => write();
+    if (autoFlush && typeof window !== 'undefined') {
+        window.addEventListener('pagehide', onPageHide);
+        document.addEventListener('visibilitychange', onHide);
+        // Chrome on Android freezes background tabs and may later discard them with no other event.
+        document.addEventListener('freeze', onPageHide);
+    }
+    const store = {
+        key,
+        get persistent() {
+            return status.persistent;
+        },
+        get status() {
+            return status;
+        },
+        get savedAt() {
+            return savedAt;
+        },
+        get: () => data,
+        set,
+        update(fn) {
+            const draft = structuredClone(data);
+            const result = fn(draft);
+            return set(result === undefined ? draft : result);
+        },
+        flush: write,
+        reset() {
+            data = opts.defaults();
+            status.dirty = true;
+            write();
+        },
+        clear() {
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+            try {
+                storage?.removeItem(key);
+                storage?.removeItem(backupKey);
+                storage?.removeItem(metaKey);
+            }
+            catch {
+                // ignore
+            }
+            data = opts.defaults();
+            savedAt = 0;
+            status.dirty = false;
+            status.loadResult = 'fresh';
+            notify();
+        },
+        exportString() {
+            return encodeExport(opts.game, { v: version, t: status.dirty ? now() : savedAt, d: data });
+        },
+        importString(text) {
+            const decoded = decodeExport(opts.game, text);
+            if (!decoded.ok)
+                return decoded;
+            try {
+                const { value, migrated } = adopt(decoded.envelope);
+                data = value;
+                status.dirty = true;
+                write();
+                return { ok: true, migrated };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+        dispose() {
+            write();
+            listeners.clear();
+            if (autoFlush && typeof window !== 'undefined') {
+                window.removeEventListener('pagehide', onPageHide);
+                document.removeEventListener('visibilitychange', onHide);
+                document.removeEventListener('freeze', onPageHide);
+            }
+        },
+    };
+    return store;
+}

package/dist/testing/fake-host.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Test-only `Host` (ws/testing-kit): everything a page or shell offers the game, in memory and
+ * under the test's control. Storage is a `MemoryStorage`, the lifecycle moves on `setState`,
+ * haptics, fullscreen, links, copies and wake-lock requests are written down, the safe area is
+ * set by hand, and frames run only when the test calls `runFrame`. Nothing touches the DOM.
+ */
+import type { HapticImpact, HapticNotification, Host, HostHaptics, HostInsets, HostKind, HostLifecycle, HostLifecycleState, HostSafeArea } from '../host/index.js';
+import type { CopyResult, EmbedContext, LinkActivation, OpenResult } from '../platform/index.js';
+import { type StorageLike } from '../save/index.js';
+/** `createFakeHost` options. Every field has a default that makes the host fully capable. */
+export interface FakeHostOptions {
+    /** `Host.kind`. Default `'web'`. */
+    kind?: HostKind;
+    /** `Host.embed`. Default `'top'`. */
+    embed?: EmbedContext;
+    /**
+     * The save backend `storage.open()` returns. Default a fresh `MemoryStorage`; `null` is a host
+     * with no working storage (`open()` returns null), as when the browser blocks it.
+     */
+    storage?: StorageLike | null;
+    /** The lifecycle state at creation. Default `'active'`. */
+    state?: HostLifecycleState;
+    /** The safe-area insets at creation, CSS px. Missing sides are 0. */
+    safeArea?: Partial<HostInsets>;
+    /** `fullscreen.available()`. Default true. When false, `toggle` resolves false and changes nothing. */
+    fullscreen?: boolean;
+    /** `haptics.available()`. Default true. Calls are recorded either way. */
+    haptics?: boolean;
+    /** What `openExternal` answers. Default `'opened'`. */
+    openResult?: OpenResult;
+    /** What `copyText` resolves to. Default `'copied'`. */
+    copyResult?: CopyResult;
+    /** `clipboardWriteAllowed()`. Default true. */
+    clipboardWriteAllowed?: boolean;
+    /** Timestamp of the first `runFrame` that is given none, ms. Default 0. */
+    startTime?: number;
+    /** How far a `runFrame` without a timestamp moves frame time, ms. Default 1000 / 60. */
+    frameMs?: number;
+}
+/** One haptic call, in the order made. */
+export type FakeHapticCall = {
+    readonly op: 'impact';
+    readonly style: HapticImpact;
+} | {
+    readonly op: 'notification';
+    readonly kind: HapticNotification;
+} | {
+    readonly op: 'vibrate';
+    readonly ms: number;
+};
+/**
+ * A wake-lock stub. `Host` has no wake-lock facet yet; this records what a game that keeps the
+ * screen on through its own code would ask for, so the test can assert it.
+ */
+export interface FakeWakeLock {
+    /** True between a `request()` and the next `release()`. */
+    readonly held: boolean;
+    /** Every call, in order. */
+    readonly calls: readonly ('request' | 'release')[];
+    /** Takes the lock. Resolves true. */
+    request(): Promise<boolean>;
+    /** Drops the lock; a second release does nothing more than record the call. */
+    release(): void;
+}
+/** A full `Host` the test drives. Every optional facet is present. */
+export interface FakeHost extends Host {
+    readonly lifecycle: HostLifecycle;
+    readonly haptics: HostHaptics;
+    readonly safeArea: HostSafeArea;
+    /** The backend `storage.open()` returns (the same object every call), or null. */
+    readonly memory: StorageLike | null;
+    /** Moves the lifecycle; watchers run only when the state changes. */
+    setState(state: HostLifecycleState): void;
+    /** Sets some or all insets; watchers run only when a value changes. */
+    setSafeArea(insets: Partial<HostInsets>): void;
+    /** Every haptic call, in order. */
+    readonly hapticCalls: readonly FakeHapticCall[];
+    /** Every `fullscreen.toggle` call with its options, in order. */
+    readonly fullscreenCalls: readonly {
+        readonly lockLandscape?: boolean;
+    }[];
+    /** Every `openExternal` call, in order. */
+    readonly opened: readonly {
+        readonly url: string;
+        readonly activation: LinkActivation;
+    }[];
+    /** Every `copyText` argument, in order. */
+    readonly copied: readonly string[];
+    /** The wake-lock stub. */
+    readonly wakeLock: FakeWakeLock;
+    /** Frame requests waiting for the next `runFrame`. */
+    readonly pendingFrames: number;
+    /** The timestamp of the last `runFrame`, ms (`startTime` before the first one). */
+    readonly frameTime: number;
+    /**
+     * Runs every frame requested before this call, with `timeMs` (default: the last frame time
+     * plus `frameMs`). A callback that requests another frame is queued for the next call, so one
+     * `runFrame` is one display frame. Returns how many callbacks ran.
+     */
+    runFrame(timeMs?: number): number;
+}
+/** A recording, fully controllable `Host` for unit tests. See `FakeHostOptions`. */
+export declare function createFakeHost(opts?: FakeHostOptions): FakeHost;

package/dist/testing/fake-host.js

@@ -0,0 +1,163 @@
+import { MemoryStorage } from '../save/index.js';
+/** A recording, fully controllable `Host` for unit tests. See `FakeHostOptions`. */
+export function createFakeHost(opts = {}) {
+    const memory = opts.storage === undefined ? new MemoryStorage() : opts.storage;
+    const frameMs = opts.frameMs ?? 1000 / 60;
+    let frameTime = opts.startTime ?? 0;
+    let firstFrame = true;
+    let nextHandle = 1;
+    let queue = new Map();
+    /** The batch `runFrame` is running, so a callback can cancel one later in it. */
+    let running = null;
+    let state = opts.state ?? 'active';
+    const stateWatchers = new Set();
+    const lifecycle = {
+        get state() {
+            return state;
+        },
+        watch(fn) {
+            stateWatchers.add(fn);
+            return () => stateWatchers.delete(fn);
+        },
+    };
+    const insets = { top: 0, right: 0, bottom: 0, left: 0, ...opts.safeArea };
+    const insetWatchers = new Set();
+    const safeArea = {
+        insets: () => insets,
+        watch(fn) {
+            insetWatchers.add(fn);
+            return () => insetWatchers.delete(fn);
+        },
+    };
+    const hapticCalls = [];
+    const hapticsOn = opts.haptics ?? true;
+    const haptics = {
+        available: () => hapticsOn,
+        impact: (style) => hapticCalls.push({ op: 'impact', style }),
+        notification: (kind) => hapticCalls.push({ op: 'notification', kind }),
+        vibrate: (ms) => hapticCalls.push({ op: 'vibrate', ms }),
+    };
+    const fullscreenCalls = [];
+    const fullscreenOn = opts.fullscreen ?? true;
+    let fullscreenActive = false;
+    const fullscreenWatchers = new Set();
+    const fullscreen = {
+        available: () => fullscreenOn,
+        get active() {
+            return fullscreenActive;
+        },
+        toggle(topts) {
+            fullscreenCalls.push(topts?.lockLandscape === undefined ? {} : { lockLandscape: topts.lockLandscape });
+            if (!fullscreenOn)
+                return Promise.resolve(false);
+            fullscreenActive = !fullscreenActive;
+            for (const fn of [...fullscreenWatchers])
+                fn(fullscreenActive);
+            return Promise.resolve(fullscreenActive);
+        },
+        watch(fn) {
+            fullscreenWatchers.add(fn);
+            return () => fullscreenWatchers.delete(fn);
+        },
+    };
+    const storage = { kind: 'memory', open: () => memory };
+    const wakeCalls = [];
+    let wakeHeld = false;
+    const wakeLock = {
+        get held() {
+            return wakeHeld;
+        },
+        calls: wakeCalls,
+        request() {
+            wakeCalls.push('request');
+            wakeHeld = true;
+            return Promise.resolve(true);
+        },
+        release() {
+            wakeCalls.push('release');
+            wakeHeld = false;
+        },
+    };
+    const opened = [];
+    const copied = [];
+    const openResult = opts.openResult ?? 'opened';
+    const copyResult = opts.copyResult ?? 'copied';
+    const clipboardOk = opts.clipboardWriteAllowed ?? true;
+    return {
+        kind: opts.kind ?? 'web',
+        embed: opts.embed ?? 'top',
+        requestFrame(cb) {
+            const handle = nextHandle++;
+            queue.set(handle, cb);
+            return handle;
+        },
+        cancelFrame(handle) {
+            queue.delete(handle);
+            running?.delete(handle);
+        },
+        openExternal(url, o) {
+            opened.push({ url, activation: o.activation });
+            return openResult;
+        },
+        copyText(text) {
+            copied.push(text);
+            return Promise.resolve(copyResult);
+        },
+        clipboardWriteAllowed: () => clipboardOk,
+        fullscreen,
+        storage,
+        lifecycle,
+        haptics,
+        safeArea,
+        memory,
+        setState(next) {
+            if (next === state)
+                return;
+            state = next;
+            for (const fn of [...stateWatchers])
+                fn(next);
+        },
+        setSafeArea(patch) {
+            let changed = false;
+            for (const side of ['top', 'right', 'bottom', 'left']) {
+                const v = patch[side];
+                if (v !== undefined && v !== insets[side]) {
+                    insets[side] = v;
+                    changed = true;
+                }
+            }
+            if (changed)
+                for (const fn of [...insetWatchers])
+                    fn(insets);
+        },
+        hapticCalls,
+        fullscreenCalls,
+        opened,
+        copied,
+        wakeLock,
+        get pendingFrames() {
+            return queue.size;
+        },
+        get frameTime() {
+            return frameTime;
+        },
+        runFrame(timeMs) {
+            frameTime = timeMs ?? (firstFrame ? frameTime : frameTime + frameMs);
+            firstFrame = false;
+            const run = queue;
+            queue = new Map();
+            running = run;
+            let count = 0;
+            try {
+                for (const cb of run.values()) {
+                    count++;
+                    cb(frameTime);
+                }
+            }
+            finally {
+                running = null;
+            }
+            return count;
+        },
+    };
+}

package/dist/testing/fixed-clock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Test-only fixed-step clock (ws/testing-kit). It is a `TickClock`, so it goes wherever
+ * `ctx.clock` goes: `createGestures({ clock })`, `createLook({ clock })`,
+ * `createInputPlayback(input, rec, { clock })`, and as `GameLoop`'s `now`. A test moves it one
+ * fixed step at a time, and N steps read exactly N × step, with no float drift.
+ */
+import type { TickClock } from '../input/index.js';
+/** A `TickClock` that moves in whole fixed steps, plus any loose `advance(ms)`. */
+export interface FixedClock extends TickClock {
+    /** The step length, ms. */
+    readonly stepMs: number;
+    /**
+     * Whole steps taken so far: each `step`, and each `advance(ms)` of exactly `stepMs` (how
+     * `createGame`'s loop moves its clock once per fixed update, ws/core-8). Other advances do
+     * not count.
+     */
+    readonly ticks: number;
+    /** Moves the clock by `n` steps (default 1). Negative, fractional and non-finite `n` are ignored. */
+    step(n?: number): void;
+}
+/**
+ * A fixed-step clock starting at `start` ms (default 0) with steps of `stepMs` (default
+ * 1000 / 60, the engine's default fixed step). `now()` is `start + advanced + ticks × stepMs`.
+ */
+export declare function createFixedClock(stepMs?: number, start?: number): FixedClock;

package/dist/testing/fixed-clock.js

@@ -0,0 +1,30 @@
+/**
+ * A fixed-step clock starting at `start` ms (default 0) with steps of `stepMs` (default
+ * 1000 / 60, the engine's default fixed step). `now()` is `start + advanced + ticks × stepMs`.
+ */
+export function createFixedClock(stepMs = 1000 / 60, start = 0) {
+    if (!(stepMs > 0) || !Number.isFinite(stepMs)) {
+        throw new RangeError(`createFixedClock: stepMs must be a positive finite number, got ${stepMs}`);
+    }
+    const origin = Number.isFinite(start) ? start : 0;
+    let ticks = 0;
+    let loose = 0;
+    return {
+        stepMs,
+        get ticks() {
+            return ticks;
+        },
+        now: () => origin + loose + ticks * stepMs,
+        advance(ms) {
+            // The loop's own step is a whole step, so N fixed updates read exactly N × step.
+            if (ms === stepMs)
+                ticks++;
+            else if (ms > 0 && Number.isFinite(ms))
+                loose += ms;
+        },
+        step(n = 1) {
+            if (Number.isInteger(n) && n > 0)
+                ticks += n;
+        },
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { createFakeDevice, type FakeBindGroup, type FakeBuffer, type FakeBufferCopy, type FakeDevice, FakeGpuValidationError, type FakePass, type FakeQuerySet, type FakeTexture, type FakeView, fakeCanvasContext, fakeRendererGpu, installGpuGlobals, type PassCommand, } from '../render/fake-gpu.js';
+export { createFakeHost, type FakeHapticCall, type FakeHost, type FakeHostOptions, type FakeWakeLock, } from './fake-host.js';
+export { createFixedClock, type FixedClock } from './fixed-clock.js';
+export { createTestGame, type TestGame, type TestGameOptions, } from './test-game.js';

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+// @thunderclap-engine/engine/testing: helpers for a game's unit tests. Never imported by the engine.
+export { createFakeDevice, FakeGpuValidationError, fakeCanvasContext, fakeRendererGpu, installGpuGlobals, } from '../render/fake-gpu.js';
+export { createFakeHost, } from './fake-host.js';
+export { createFixedClock } from './fixed-clock.js';
+export { createTestGame, } from './test-game.js';

package/dist/testing/test-game.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `createTestGame` (ws/core-8): `createGame` itself, headless, on the fake GPU, the fake host
+ * and the fixed clock. `step(n)` runs the game's own loop for `n` frames of one fixed step
+ * each, so a test presses an action, steps and asserts state with the engine's real frame
+ * order. Needs a DOM for the overlay (`// @vitest-environment happy-dom`), unless
+ * `overlay: false`, which is `createGame`'s no-DOM mode (ws/core-9) and runs in plain Node.
+ */
+import type { CreateGameOptions, EngineCtx, FlushableSave } from '../core/game.js';
+import type { Input } from '../input/index.js';
+import { type FakeDevice } from '../render/fake-gpu.js';
+import { type FakeHost } from './fake-host.js';
+import { type FixedClock } from './fixed-clock.js';
+/**
+ * `createTestGame` options: `createGame`'s, without `gpu`, `host` and `clock` (the kit makes
+ * them; pass `host` or `device` to bring your own) and with `root` optional.
+ */
+export interface TestGameOptions<A extends string, S extends FlushableSave | null = null, P = any> extends Omit<CreateGameOptions<A, S, P>, 'gpu' | 'host' | 'clock' | 'root'> {
+    /** Where the canvas and overlay mount. Default a new `<div>` appended to `document.body`. */
+    root?: HTMLElement;
+    /** The host. Default `createFakeHost()`. */
+    host?: FakeHost;
+    /** The fake GPU device. Default `createFakeDevice()`. */
+    device?: FakeDevice;
+    /**
+     * The CSS px size the root reports (happy-dom lays nothing out), so the surface letterboxes
+     * and pointers map as on a page of that size. Default the design size: client px are design
+     * px. The root sits at the viewport's top-left.
+     */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * `false`: the test needs no DOM (ws/testing-2). The game runs in `createGame`'s no-DOM mode
+     * (`CreateGameOptions.overlay`, ws/core-9), in plain Node (Vitest's default `node`
+     * environment) or under happy-dom alike, and nothing touches `document` or `window`: no
+     * overlay (reading `ctx.ui` throws), no canvas (`ctx.surface` letterboxes a virtual
+     * container of `viewport`), no DOM listeners. `root` is not used. Drive the game through
+     * `input`. Default true: the overlay needs a DOM (`// @vitest-environment happy-dom`).
+     */
+    overlay?: boolean;
+}
+/** What `createTestGame` returns. */
+export interface TestGame<A extends string, S extends FlushableSave | null = null, C = unknown, P = unknown> {
+    /** The game's ctx, exactly as `createGame` built it. */
+    readonly ctx: EngineCtx<A, S, C, P>;
+    /** `ctx.input`. */
+    readonly input: Input<A>;
+    /** The fake host (`ctx.host`): storage in memory, `setState`, recorded haptics. */
+    readonly host: FakeHost;
+    /** `ctx.clock`: N steps read exactly N × the fixed step. */
+    readonly clock: FixedClock;
+    /** The fake GPU device the renderer records into. */
+    readonly device: FakeDevice;
+    /**
+     * Run `n` frames (default 1) through the game's loop (`ctx.loop.tickOnce(step)`), each one
+     * fixed update (replay, clock, input, pad navigation, `hooks.update`, particles, scenes) and
+     * one render. With `sim: false` each frame updates once with the step as its delta. A halted
+     * loop (device lost) runs nothing.
+     */
+    step(n?: number): void;
+    /**
+     * Lose the GPU device (ws/testing-2): `device.loseDevice(reason, message)`, then wait until the
+     * engine has handled it. Afterwards the loop is halted for good (`ctx.loop.halted`, `step`
+     * runs nothing), `hooks.deviceLost` and every `ctx.onDeviceLost` listener ran with the info,
+     * audio is halted, captions are suspended and the save flushed, as on a page. Default reason
+     * `'unknown'`; `'destroyed'` is an explicit `device.destroy()`, which the engine ignores.
+     */
+    loseDevice(reason?: GPUDeviceLostReason, message?: string): Promise<void>;
+}
+/**
+ * `createGame` with the testing kit's fakes: a `FakeDevice` as the GPU, a `FakeHost` as the
+ * host (save storage in memory) and a `FixedClock` as `ctx.clock`, on the step of `opts.sim`
+ * (default 1/60 s). The loop is not started; `step(n)` drives it.
+ */
+export declare function createTestGame<A extends string, S extends FlushableSave | null = null, C = unknown, P = unknown>(opts: TestGameOptions<A, S, P>): Promise<TestGame<A, S, C, P>>;