@downdraft/engine 0.1.1 → 0.2.0

package/dist/app/src/renderer/game-module.js

@@ -0,0 +1,562 @@
+// ============================================================================
+// GameModule — declarative game definition + startGame() entry point
+//
+// A `GameModule` is a declarative description of a game's renderer-side
+// bootstrap: the renderer factory, sim worker factory, UI mount, event
+// routing, save config, devtools, and game-specific hooks. `startGame()`
+// consumes a module and orchestrates the full bootstrap sequence, collapsing
+// the ~700-line per-game `main.tsx` into a ~100-line module declaration.
+//
+// Design goals:
+//   - Declarative: games declare *what* they need, not *how* to wire it.
+//   - Progressive: every field is optional except `renderer` and `sim`.
+//     Simple games get a 10-line module; complex games add hooks.
+//   - Typed: the `GameContext` passed to hooks carries typed references
+//     (renderer, simWorker, SABs, saveStore, bridge) — no module-scope `let`.
+//   - Escape hatches: `onInit` / `onReady` / `onDispose` hooks let games
+//     run bespoke logic at well-defined points in the sequence.
+//
+// `startGame()` wraps `bootstrapGame()` — games that need full control can
+// still call `bootstrapGame()` directly.
+// ============================================================================
+import { ENGINE_VERSION, LibraryHostImpl, PluginHost, WorkerPluginLoader, isDevMode } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { bootstrapGame } from "./bootstrap.js";
+import { downdraft, getSurface } from "./index.js";
+import { createSaveStore, isOpfsAvailable } from "./save-store-factory.js";
+const log = createLogger("info");
+/**
+ * Serialize the restore payload for a SaveState components map.
+ * `explicit` (GameSaveConfig.componentName) selects a single component's
+ * `data`. Otherwise: a single-component save unwraps to its `data` (the raw
+ * payload restores expect), while a multi-component save forwards the whole
+ * map — the worker's extractRestoreData passes component-map input through
+ * to the game's restore, which selects the sections it owns. Picking the
+ * first component would silently drop the rest of the world.
+ */
+export function serializeRestorePayload(components, explicit) {
+    if (explicit) {
+        const comp = components[explicit];
+        if (!comp) {
+            log.warn("start-game", `Save component "${explicit}" not found; available: ${Object.keys(components).join(", ")}`);
+            return undefined;
+        }
+        return JSON.stringify(comp.data);
+    }
+    const keys = Object.keys(components).filter((k) => components[k]?.data !== undefined && components[k]?.data !== null);
+    if (keys.length === 0)
+        return undefined;
+    if (keys.length === 1)
+        return JSON.stringify(components[keys[0]].data);
+    return JSON.stringify(components);
+}
+// ── startGame() ──
+/**
+ * Start a game from a declarative `GameModule`.
+ *
+ * This is the high-level entry point. It wraps `bootstrapGame()` and adds:
+ *   - Engine library auto-wiring (SAB allocation, sim systems, renderer passes)
+ *   - Sim worker spawn + SAB capture (skipped for renderer-only games)
+ *   - Declarative event routing (the `events` map — sim-worker games only)
+ *   - Save store initialization (sim-worker or renderer-side save source)
+ *   - Typed `GameContext` passed to all hooks
+ *
+ * Two topologies are supported:
+ *   - **Sim-worker**: `module.sim` is declared → worker spawned, SABs captured,
+ *     events routed, sim started after renderer init.
+ *   - **Renderer-only**: `module.sim` is omitted → no worker, no SABs, no
+ *     event routing. All logic runs on the renderer thread. Declare
+ *     `module.saveSource` for autosave support.
+ *
+ * Games that need full control can call `bootstrapGame()` directly.
+ */
+export async function startGame(module) {
+    const deterministic = !!downdraft?.deterministic;
+    const isDev = !!(downdraft?.isDev) || isDevMode;
+    const hasSim = !!module.sim;
+    // Dev-session guard: capture the session snapshot this boot belongs to.
+    // If an HMR restart lands while a boot-stage await below is suspended, the
+    // continuation belongs to a dead generation — and the tracker by then may
+    // already host the NEXT session, which would happily track this dead gen's
+    // listeners/timers (pinning its whole module graph for a generation). Bail
+    // instead. No tracker → production mode → never aborts.
+    const ddTracker = globalThis.__ddSession;
+    const bootSession = ddTracker?.session ?? null;
+    const sessionAborted = () => (!!ddTracker && (ddTracker.session !== bootSession || !bootSession || bootSession.dead))
+        || typeof globalThis.window === "undefined";
+    // 0. Resolve the render surface (NativeSurface on the native runtime)
+    const surface = getSurface(module.canvasLayer ?? 0);
+    // 0b. Allocate library SABs (if any libraries declared) — before sim worker
+    //     creation so the sim factory can receive externally-allocated SABs.
+    let libHost = null;
+    let libBuffers = {};
+    if (module.libraries && module.libraries.length > 0) {
+        libHost = new LibraryHostImpl(module.libraries);
+        libBuffers = libHost.allocateBuffers();
+    }
+    // 0c. Construct the renderer-side plugin host (if plugins declared).
+    //     Sim-thread plugins are forwarded to the sim worker after it starts;
+    //     renderer/own-worker plugins load here. The host is exposed on ctx so
+    //     games + the doctor panel can query snapshots.
+    let pluginHost = null;
+    if (module.plugins) {
+        const pCfg = module.plugins;
+        const hostOpts = {
+            gameId: downdraft?.appId ?? "unknown",
+            engineVersion: ENGINE_VERSION,
+            gameAllow: pCfg.permissions,
+            eventCatalog: pCfg.eventCatalog,
+            sources: pCfg.sources,
+        };
+        pluginHost = new PluginHost(hostOpts);
+        // Register the worker-js loader (handles own-worker plugins on renderer).
+        pluginHost.registerLoader(new WorkerPluginLoader());
+        // Pre-resolved manifests (tests / first-party plugins).
+        for (let _i23990 = 0, _it23990 = (pCfg.manifests ?? []), _n23990 = _it23990.length; _i23990 < _n23990; _i23990++) {
+            const m = _it23990[_i23990];
+            pluginHost.discover(m, "inline");
+        }
+        ;
+        // Manifests are discovered via the plugin host's discover() API. Here we
+        // only load what's been discovered so far.
+    }
+    // 1. Create sim worker + capture SABs (renderer-only games skip this).
+    //    If libraries declared, pass the library-allocated SABs to the sim
+    //    factory via a seed object so the sim can share them zero-copy.
+    const simSeed = Object.keys(libBuffers).length > 0 ? { libraryBuffers: libBuffers } : undefined;
+    const simWorker = hasSim ? module.sim(simSeed) : null;
+    const simSAB = simWorker?.getSimBuffer();
+    const inputSAB = simWorker?.getInputBuffer();
+    const extraBuffers = simWorker?.getExtraBuffers?.() ?? {};
+    // 2. Create renderer
+    const renderer = module.renderer(surface);
+    // 3. Build the game context. Sim fields are undefined for renderer-only games.
+    const ctx = {
+        renderer,
+        surface,
+        sim: simWorker,
+        simSAB,
+        inputSAB,
+        extraBuffers,
+        saveStore: null,
+        saveMode: "host",
+        saveSource: module.saveSource,
+        bridge: downdraft,
+        deterministic,
+        isDev,
+    };
+    // 3b. Merge library SABs into extraBuffers + store host on ctx
+    if (libHost) {
+        for (const [name, sab] of Object.entries(libBuffers)) {
+            if (name in ctx.extraBuffers) {
+                log.warn("start-game", `library SAB channel "${name}" shadows a same-named sim extra buffer in ctx.extraBuffers`);
+            }
+            ctx.extraBuffers[name] = sab;
+        }
+        ctx.libraryHost = libHost;
+    }
+    // 3c. Expose the plugin host on ctx (if constructed).
+    if (pluginHost) {
+        ctx.pluginHost = pluginHost;
+    }
+    // Event kinds emitted by the engine itself (sim-worker-base lifecycle)
+    // that games are not required to handle — suppress the dev warning for
+    // these so autosave doesn't spam the console when no handler is wired.
+    const ENGINE_EMITTED_EVENT_KINDS = new Set(["ready", "saved", "loaded", "error"]);
+    // 4. Wire event routing from the declarative events map (sim-worker only).
+    //    Supports both GameSimWorker.onEvent(cb) and SimWorkerHost's
+    //    subscribeEvents(cb) (renderer-owned worker hosts).
+    const wireSimEvents = (worker) => {
+        if (!module.events || !worker)
+            return;
+        const events = module.events;
+        // Prefer subscribeEvents when present: SimWorkerHost subclasses expose it
+        // as the public registration API, while their protected onEvent(kind,data)
+        // is the internal dispatcher (and would be incorrectly bound if we probed
+        // onEvent first — it exists on the prototype at runtime).
+        const onEvent = worker.subscribeEvents
+            ? (cb) => { worker.subscribeEvents(cb); }
+            : worker.onEvent?.bind(worker);
+        if (!onEvent)
+            return;
+        onEvent((msg) => {
+            const handler = events[msg.kind];
+            if (handler) {
+                try {
+                    handler(msg.data, ctx);
+                }
+                catch (err) {
+                    log.error("start-game", `Event handler error for "${msg.kind}": ${err}`);
+                }
+            }
+            else if (isDev && !ENGINE_EMITTED_EVENT_KINDS.has(msg.kind)) {
+                log.warn("start-game", `Unhandled sim event kind: "${msg.kind}"`);
+            }
+        });
+    };
+    if (simWorker)
+        wireSimEvents(simWorker);
+    // 5. Run onBeforeInit hook
+    if (module.onBeforeInit) {
+        await module.onBeforeInit(ctx);
+        if (sessionAborted())
+            return;
+    }
+    // 6. Initialize save store (if configured) — for non-inline modes this
+    //    runs before bootstrapGame so onReady can use it. For inline mode
+    //    (sim-worker + OPFS), the store is initialized inside onRendererInit
+    //    after the sim worker has started.
+    if (module.save && !deterministic) {
+        try {
+            // Default to "host" (disk via the host's typed save store) when the
+            // bridge exposes one — on native this is HostSaveStore over
+            // HostServices. Fall back to "auto" (OPFS) only in a pure browser
+            // where there is no host bridge.
+            const saveMode = module.save.mode ?? (downdraft.saveStore ? "host" : "auto");
+            if (saveMode === "auto" && simWorker?.initSaveStore && isOpfsAvailable() && !downdraft.saveStore) {
+                // Inline mode — defer init to onRendererInit (after sim worker starts).
+                ctx.saveMode = "inline";
+                ctx.saveStore = null;
+            }
+            else {
+                const { store, mode: resolvedMode } = await createSaveStore({
+                    mode: saveMode,
+                    opfsOptions: {
+                        engineVersion: module.save.engineVersion,
+                        maxGenerations: module.save.maxGenerations ?? 3,
+                    },
+                    bridge: downdraft,
+                });
+                ctx.saveStore = store;
+                // resolvedMode is "worker" | "host" | "inline" (inline returns a
+                // null store); narrow to the ctx.saveMode union accordingly.
+                ctx.saveMode = resolvedMode === "inline" ? "inline"
+                    : resolvedMode === "worker" ? "worker" : "host";
+            }
+        }
+        catch (e) {
+            log.warn("start-game", `Save store init failed, falling back to host bridge: ${e}`);
+            ctx.saveMode = "host";
+        }
+        if (sessionAborted())
+            return;
+    }
+    // 6b. Mode-aware save/load helpers — exposed on ctx so games can trigger manual
+    //     saves/loads that work regardless of the selected backend. This is the
+    //     same logic the autosave interval uses below. Games MUST use ctx.save /
+    //     ctx.load instead of sim.save / sim.load directly: sim.save only writes
+    //     in inline mode (it has its own OPFS store) and silently drops the save
+    //     in host mode (it returns stateJson but nothing forwards it to disk).
+    if (module.save && !deterministic) {
+        ctx.save = async (slotName) => {
+            try {
+                // Renderer-side save source takes priority (renderer-only games);
+                // otherwise fall back to the sim worker's save() (sim-worker games).
+                // ctx.sim covers simFromRenderer games, resolved after renderer init.
+                const sim = ctx.sim ?? simWorker;
+                const result = ctx.saveSource
+                    ? await ctx.saveSource.save(slotName)
+                    : sim?.save
+                        ? await sim.save(slotName)
+                        : null;
+                // In inline mode, the sim worker's save() already persisted to its own
+                // OPFS store — nothing more to do. In host/worker mode the sim worker
+                // only serialized — the renderer owns the store write.
+                if (result?.stateJson && ctx.saveMode !== "inline" && ctx.saveStore) {
+                    const components = JSON.parse(result.stateJson);
+                    const state = {
+                        components,
+                        meta: {
+                            engineVersion: module.save?.engineVersion ?? "",
+                            timestamp: Date.now() / 1000,
+                            entityCount: 0,
+                            playerCount: 0,
+                            // Real SaveMeta from the worker's save.meta() hook wins.
+                            ...result.meta,
+                        },
+                    };
+                    const sr = await ctx.saveStore.save(slotName, state);
+                    return result.success !== false && sr.success;
+                }
+                return result?.success ?? false;
+            }
+            catch (e) {
+                log.error("start-game", `Manual save failed: ${e}`);
+                return false;
+            }
+        };
+        ctx.load = async (slotName) => {
+            try {
+                // Renderer-side save source load (renderer-only games)
+                if (ctx.saveSource?.load) {
+                    const stateJson = await ctx.saveSource.load(slotName);
+                    return stateJson ? JSON.parse(stateJson) : null;
+                }
+                // ctx.sim covers simFromRenderer games (resolved post renderer-init).
+                const sim = ctx.sim ?? simWorker;
+                // Inline mode: sim worker loads directly from its own OPFS store.
+                // The sim worker's load() restores state internally; we just need a
+                // truthy return value so any onLoad hook fires.
+                if (ctx.saveMode === "inline" && sim?.load) {
+                    const success = await sim.load(slotName);
+                    return success ? { restored: true } : null;
+                }
+                if (ctx.saveStore) {
+                    const result = await ctx.saveStore.load(slotName);
+                    const state = result?.state ?? null;
+                    if (state && sim?.restoreFromState) {
+                        // The save store returns a SaveState with `components`. Each
+                        // component has { v, data } structure — forward the restore
+                        // payload to the sim worker.
+                        const components = state.components;
+                        if (components) {
+                            const payload = serializeRestorePayload(components, module.save?.componentName);
+                            if (payload !== undefined) {
+                                await sim.restoreFromState(payload);
+                            }
+                        }
+                    }
+                    return state;
+                }
+                if (downdraft?.loadGameState) {
+                    const stateJson = await downdraft.loadGameState(slotName);
+                    if (!stateJson)
+                        return null;
+                    // The host bridge returns JSON.stringify(result.state.components),
+                    // so the parsed result is the components map directly (not a
+                    // SaveState). Find the game component (e.g. "sandbox") and
+                    // forward its `data` to the sim worker.
+                    let parsed = null;
+                    try {
+                        parsed = JSON.parse(stateJson);
+                    }
+                    catch {
+                        // Non-JSON payload — fall through to raw restore.
+                    }
+                    if (sim?.restoreFromState) {
+                        const components = parsed;
+                        const payload = components && typeof components === "object"
+                            ? serializeRestorePayload(components, module.save?.componentName)
+                            : undefined;
+                        if (payload !== undefined) {
+                            await sim.restoreFromState(payload);
+                        }
+                        else {
+                            // No recognizable components map — forward the raw payload.
+                            await sim.restoreFromState(stateJson);
+                        }
+                    }
+                    // Return the parsed payload (or the raw string when it isn't JSON)
+                    // — the previous version re-parsed unconditionally here, so a
+                    // successful raw restore still reported failure.
+                    return parsed ?? stateJson;
+                }
+                return null;
+            }
+            catch (e) {
+                log.error("start-game", `Manual load failed: ${e}`);
+                return null;
+            }
+        };
+    }
+    // 6c. Kick the default sim start early — `simWorker.start()` spawns the
+    //     worker + sends init config and doesn't touch renderer state, so it
+    //     can overlap renderer.init() instead of serializing behind it inside
+    //     onRendererInit. `onInit` overrides own sim start entirely (e.g.
+    //     to-the-ocean's Promise.all); `onSimStart` overrides stay deferred
+    //     since they may depend on post-init ctx state; renderer-owned workers
+    //     (simFromRenderer) are untouched.
+    let simStartPromise = null;
+    if (simWorker && !module.onInit && !module.onSimStart) {
+        simStartPromise = Promise.resolve(simWorker.start(module.simConfig ?? {}));
+        // Mark handled now — the real await (which re-throws on failure) happens
+        // at the original join point inside onRendererInit.
+        simStartPromise.catch(() => { });
+    }
+    // 7. Delegate to bootstrapGame() for the standard sequence
+    await bootstrapGame({
+        canvasLayer: module.canvasLayer,
+        fpsPollIntervalMs: module.fpsPollIntervalMs,
+        getActiveModules: module.getActiveModules,
+        createRenderer: () => renderer,
+        initRenderer: module.onInit
+            ? () => module.onInit(ctx)
+            : (r) => r.init(),
+        onRendererInit: async (r) => {
+            // ── Library renderer setup ──
+            // Early renderer-only library setup (hosts, workers — no GPU needed).
+            // Runs before the GPU device is available so libraries can construct
+            // their host + provide DI tokens.
+            if (libHost && r) {
+                const device = r.getDevice?.();
+                const format = r.getFormat?.();
+                const moduleHost = r.getRendererModuleHost?.();
+                if (!moduleHost) {
+                    log.warn("start-game", "renderer does not expose getRendererModuleHost() — EngineLibrary DI provides will be silently dropped");
+                }
+                const libProvide = (token, value) => {
+                    if (moduleHost)
+                        moduleHost.provideExternal("library", token, value);
+                };
+                const libInject = (token) => {
+                    if (moduleHost)
+                        return moduleHost.injectResource(token);
+                    throw new Error(`Library inject("${token.key}") failed — no renderer plugin host available`);
+                };
+                const libInjectOptional = (token) => {
+                    if (moduleHost)
+                        return moduleHost.injectResourceOptional(token);
+                    return undefined;
+                };
+                libHost.createRenderer({ provide: libProvide, inject: libInject, injectOptional: libInjectOptional });
+                // GPU-pass library init (after device is ready).
+                if (device && format) {
+                    libHost.initRenderer({ device, format, provide: libProvide, inject: libInject, injectOptional: libInjectOptional });
+                    libHost.setRendererBuffers(libBuffers, { provide: libProvide });
+                }
+            }
+            // ── Renderer-owned sim resolution ──
+            // Games whose renderer spawns/starts the sim worker internally (declared
+            // via `module.simFromRenderer` instead of `module.sim`) get the worker
+            // resolved here — after renderer.init() has created it. ctx.sim is
+            // populated and declarative `events` routing is wired, matching the
+            // factory-created path. startGame() never calls start() on it — the
+            // renderer owns the lifecycle.
+            if (module.simFromRenderer) {
+                try {
+                    const owned = await module.simFromRenderer(r, ctx);
+                    if (owned) {
+                        ctx.sim = owned;
+                        ctx.simSAB = owned.getSimBuffer();
+                        ctx.inputSAB = owned.getInputBuffer();
+                        const extra = owned.getExtraBuffers?.() ?? {};
+                        for (const [name, sab] of Object.entries(extra)) {
+                            ctx.extraBuffers[name] = sab;
+                        }
+                        wireSimEvents(owned);
+                    }
+                }
+                catch (e) {
+                    log.warn("start-game", `simFromRenderer resolution failed: ${e}`);
+                }
+                if (sessionAborted())
+                    return;
+            }
+            // ── Sim worker start ──
+            // When `onInit` is NOT overridden, startGame owns sim start — it runs
+            // here, after renderer.init() has succeeded. When `onInit` IS overridden,
+            // the game's onInit owns sim start (e.g. to-the-ocean starts the sim in
+            // parallel with renderer.init() inside its onInit). Renderer-only games
+            // have no sim worker to start.
+            if (simWorker && !module.onInit) {
+                if (module.onSimStart) {
+                    await module.onSimStart(ctx);
+                }
+                else if (simStartPromise) {
+                    await simStartPromise;
+                }
+                else {
+                    await simWorker.start(module.simConfig ?? {});
+                }
+                if (sessionAborted())
+                    return;
+            }
+            // ── Inline save store init (sim-worker + OPFS) ──
+            // Now that the sim worker is started, initialize its inline OPFS store.
+            // This must happen before the autosave load (which runs in bootstrapGame
+            // after onRendererInit returns) so that the sim worker can load from OPFS.
+            if (ctx.saveMode === "inline" && (ctx.sim ?? simWorker)?.initSaveStore && module.save) {
+                try {
+                    await (ctx.sim ?? simWorker).initSaveStore({
+                        engineVersion: module.save.engineVersion,
+                        maxGenerations: module.save.maxGenerations ?? 3,
+                    });
+                }
+                catch (e) {
+                    log.warn("start-game", `Inline save store init failed, falling back to host save store: ${e}`);
+                    ctx.saveMode = "host";
+                }
+                if (sessionAborted())
+                    return;
+            }
+            // ── Plugin loading ──
+            // Load all discovered plugins (renderer + own-worker threads). Sim-
+            // thread plugins are forwarded to the sim worker by the game's sim
+            // bridge (the sim worker runs its own PluginHost); here we load the
+            // renderer/own-worker subset. Failures are recorded on the plugin
+            // snapshot (ctx.pluginHost.snapshot()) and do not abort startup.
+            if (pluginHost) {
+                try {
+                    // Wire the renderer's ModuleHost now that it exists — required for
+                    // native-tier plugins (their context bridges into the typed-DI
+                    // graph). Without it a native-tier mod fails with "no ModuleHost
+                    // configured on this thread".
+                    const mh = r?.getRendererModuleHost?.();
+                    if (mh)
+                        pluginHost.setModuleHost(mh);
+                    await pluginHost.loadAll();
+                }
+                catch (e) {
+                    log.warn("start-game", `Plugin loading error: ${e}`);
+                }
+                if (sessionAborted())
+                    return;
+            }
+            // ── Declarative UI lifecycle ──
+            // Create + start the UI handle before onReady so
+            // hooks can wire subscriptions against ctx.ui.
+            if (module.ui) {
+                try {
+                    ctx.ui = await module.ui(ctx);
+                    await ctx.ui.start();
+                }
+                catch (e) {
+                    // UI failure is non-fatal — the game canvas still runs.
+                    log.error("start-game", `UI start failed: ${e}`);
+                    ctx.ui = undefined;
+                }
+                if (sessionAborted())
+                    return;
+            }
+            // ── Game-specific wiring ──
+            if (module.onReady) {
+                await module.onReady(ctx);
+            }
+        },
+        devtools: module.devtools,
+        autosave: module.save && !deterministic
+            ? {
+                // Reuse the mode-aware ctx.save / ctx.load helpers so the autosave
+                // interval and manual saves share one code path.
+                load: async () => {
+                    const slotName = module.save.slotName ?? "autosave";
+                    return ctx.load(slotName);
+                },
+                save: async () => {
+                    const slotName = module.save.slotName ?? "autosave";
+                    await ctx.save(slotName);
+                },
+                intervalMs: module.save?.intervalMs,
+            }
+            : undefined,
+        mcp: module.mcp ? () => module.mcp(ctx) : undefined,
+        onDisplayInfo: module.onDisplayInfo
+            ? (rate) => module.onDisplayInfo(rate, ctx)
+            : undefined,
+        onHotReloadDispose: () => {
+            ctx.ui?.dispose();
+            ctx.ui = undefined;
+            pluginHost?.disposeAll();
+            libHost?.disposeRenderer();
+            if (module.onDispose) {
+                module.onDispose(ctx);
+            }
+        },
+        onDeterministic: module.onDeterministic
+            ? () => module.onDeterministic(ctx)
+            : undefined,
+        onFpsUpdate: module.onFpsUpdate
+            ? (fps) => module.onFpsUpdate(fps, ctx)
+            : undefined,
+    });
+}

package/dist/app/src/renderer/hooks.js

@@ -0,0 +1,82 @@
+// ============================================================================
+// Individual composable hooks — fallback for games that need partial
+// composition instead of the full bootstrapGame() orchestrator.
+//
+// These are plain functions (not React hooks) that return cleanup callbacks.
+// ============================================================================
+import { downdraft } from "./index.js";
+/**
+ * Poll the renderer's FPS and call the callback at the given interval.
+ * Returns a cleanup function that clears the interval.
+ */
+export function useFpsPolling(renderer, onFps, intervalMs = 500) {
+    const id = setInterval(() => {
+        onFps(renderer.getFPS());
+    }, intervalMs);
+    return () => clearInterval(id);
+}
+/**
+ * In deterministic mode, pause the renderer's sim (so the e2e test can
+ * control it via MCP). No-op in non-deterministic mode.
+ */
+export function useDeterministicRenderPause(renderer, deterministic) {
+    if (deterministic && typeof renderer.pause === "function") {
+        renderer.pause();
+    }
+}
+/**
+ * Wire display info refresh rate updates.
+ * Returns a cleanup function that removes the listener.
+ */
+export function useDisplayInfo(onRefreshRate) {
+    if (!downdraft?.isAvailable)
+        return () => { };
+    downdraft.getDisplayInfo().then((info) => {
+        if (info.refreshRate > 0)
+            onRefreshRate(info.refreshRate);
+    }).catch(() => { });
+    return downdraft.onDisplayInfo((info) => {
+        if (info?.refreshRate > 0)
+            onRefreshRate(info.refreshRate);
+    });
+}
+/**
+ * Register a Vite hot-reload dispose callback.
+ * In non-hot-reload environments, this is a no-op.
+ */
+export function useHotReloadDispose(disposeFn) {
+    dispose(disposeFn);
+}
+/**
+ * Internal: register a dispose callback via Vite's import.meta.hot API.
+ * Exported for bootstrapGame() to use.
+ *
+ * Under the native dev shell the callback also lands on the __ddSession
+ * dispose registry — vite only fires hot.dispose on targeted invalidation,
+ * NOT when a session restart clears the whole module cache, so the session
+ * teardown must own the second copy. The wrapper unregisters from the
+ * session when vite fires it (directed update) so it never runs twice.
+ */
+export function dispose(disposeFn) {
+    const hot = import.meta.hot;
+    const session = globalThis.__ddSession;
+    if (!hot?.dispose && !session?.onDispose) {
+        // Packaged/direct-run mode: no vite hot and no dev-shell session, so the
+        // callback would otherwise never fire — html-ui workers, plugin hosts,
+        // and module.onDispose would leak and pin the runtime after the window
+        // closes. Native entries drain this queue in their shutdown finally.
+        const g = globalThis;
+        (g.__ddDisposeQueue ??= []).push(disposeFn);
+        return;
+    }
+    let offSession = null;
+    const wrapped = () => {
+        offSession?.();
+        offSession = null;
+        return disposeFn();
+    };
+    if (hot?.dispose)
+        hot.dispose(wrapped);
+    if (session?.onDispose)
+        offSession = session.onDispose(wrapped);
+}