@downdraft/engine 0.1.1 → 0.2.0

package/dist/app/src/renderer/hot-reload.js

@@ -0,0 +1,158 @@
+// ============================================================================
+// installSimHotReload / restoreHotReloadState — shared dev-mode HMR wiring.
+//
+// Generalized from to-the-ocean's main.tsx. The vite plugin emits
+// "sim:hot-reload" / "renderer:hot-reload" custom events when watched sim or
+// renderer files change. These helpers own the standard response:
+//
+//   sim:hot-reload      → sim.hotReload(config, preserveState) — save/stop/
+//                         respawn/restore inside the running page.
+//   renderer:hot-reload → save sim state (+ renderer meta) via the app bridge,
+//                         set the "hot-reload-pending" session flag, reload.
+//
+// restoreHotReloadState() is the other half: call it during init to pick up
+// the saved state after the page reload.
+//
+// Status is reported through the shared useHotReloadStore (devtools reads it).
+// ============================================================================
+import { isDevMode, useHotReloadStore } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { downdraft } from "./index.js";
+const log = createLogger("info");
+const PENDING_KEY = "hot-reload-pending";
+const SLOT = "hot-reload";
+/**
+ * Register the sim:hot-reload / renderer:hot-reload handlers.
+ * No-op outside dev mode or when import.meta.hot is absent.
+ * Call once from onReady (or equivalent) — safe to call again after HMR
+ * re-mount because import.meta.hot.on dedupes per-module.
+ */
+export function installSimHotReload(deps) {
+    if (!isDevMode || !import.meta.hot)
+        return;
+    const bridge = () => deps.downdraft ?? downdraft;
+    const getConfig = () => typeof deps.simConfig === "function" ? deps.simConfig() : deps.simConfig;
+    // Native dev shell: the in-runner runtime (@downdraft/platform-native
+    // dev/native-dev-runtime) owns the single sim:hot-reload / renderer:
+    // hot-reload handler set, fanning out over the __ddSession registry.
+    // Registering hot.on here too would fire the swap twice. Contribute the
+    // sim handle + renderer meta provider to the session instead.
+    const session = globalThis.__ddSession;
+    if (session) {
+        if (deps.sim?.hotReload && !session.hasSimFor?.(deps.sim)) {
+            session.registerSim?.({
+                label: "game-sim",
+                host: deps.sim,
+                hotReload: (preserve) => deps.sim.hotReload(getConfig(), preserve),
+                save: async () => (await deps.sim.save?.(SLOT))?.stateJson ?? null,
+                restore: (json) => deps.sim.restoreFromState?.(json),
+            });
+        }
+        if (deps.renderer?.serializeRendererMeta) {
+            const renderer = deps.renderer;
+            session.registerMetaProvider?.({
+                serialize: () => renderer.serializeRendererMeta(),
+                restore: (meta) => renderer.restoreRendererMeta?.(meta),
+            });
+        }
+        return;
+    }
+    // Cast: bun-types' ImportMeta augmentation can shadow vite/client's HMR
+    // typing when both are in the program (node config). This code is
+    // Vite-specific, so pin the subset of the vite HMR surface we use.
+    const hot = import.meta.hot;
+    hot.on("sim:hot-reload", async (data) => {
+        const store = useHotReloadStore.getState();
+        if (!store.enabled)
+            return;
+        hot.send("sim:hot-reload:ack", {});
+        log.info("hmr", `Sim file changed: ${data.file}`);
+        store.setStatus("reloading");
+        const t0 = performance.now();
+        try {
+            await deps.sim.hotReload?.(getConfig(), store.preserveState);
+            const elapsed = (performance.now() - t0).toFixed(0);
+            log.info("hmr", `Sim worker swap complete (${elapsed}ms)`);
+            store.setStatus("ready");
+            store.setLastReload({ file: data.file, elapsed: Number(elapsed), timestamp: data.timestamp });
+        }
+        catch (err) {
+            log.error("hmr", `Sim hot-reload failed: ${err.message}`);
+            store.setStatus("error", err.message);
+            log.warn("hmr", "Falling back to full reload");
+            if (!bridge().requestRestart?.("sim hot-reload failed")) {
+                window.location.reload();
+            }
+        }
+    });
+    hot.on("renderer:hot-reload", async (data) => {
+        const store = useHotReloadStore.getState();
+        if (!store.enabled)
+            return;
+        hot.send("renderer:hot-reload:ack", {});
+        log.info("hmr", `Renderer file changed: ${data.file}`);
+        store.setStatus("reloading");
+        if (store.preserveState) {
+            try {
+                const result = await deps.sim.save?.(SLOT);
+                const dd = bridge();
+                if (result?.stateJson && dd?.saveGameState) {
+                    const components = JSON.parse(result.stateJson);
+                    if (deps.renderer?.serializeRendererMeta) {
+                        components.renderer = { v: 1, data: deps.renderer.serializeRendererMeta() };
+                    }
+                    dd.saveGameState(SLOT, JSON.stringify(components));
+                    sessionStorage.setItem(PENDING_KEY, "1");
+                    log.info("hmr", "State saved, reloading page...");
+                }
+            }
+            catch (err) {
+                log.warn("hmr", `State save failed, reloading without preservation: ${err}`);
+            }
+        }
+        if (!bridge().requestRestart?.("renderer hot-reload")) {
+            window.location.reload();
+        }
+    });
+}
+/**
+ * Restore sim state saved by the renderer:hot-reload handler. Call during
+ * init (after the sim worker is started, before rendering). Returns true when
+ * a pending state was found and restored.
+ */
+export async function restoreHotReloadState(deps) {
+    // Native dev shell: state restore is pushed by the session tracker
+    // (notifySimStarted on sim start + registerMetaProvider for renderer
+    // meta). If this sim was already restored, report success without a
+    // second restore.
+    const session = globalThis.__ddSession;
+    if (session?.wasRestored?.(deps.sim))
+        return true;
+    if (!sessionStorage.getItem(PENDING_KEY))
+        return false;
+    sessionStorage.removeItem(PENDING_KEY);
+    const dd = deps.downdraft ?? downdraft;
+    if (!dd?.loadGameState)
+        return false;
+    try {
+        const stateJson = await dd.loadGameState(SLOT);
+        if (!stateJson)
+            return false;
+        await deps.sim.restoreFromState?.(stateJson);
+        try {
+            const components = JSON.parse(stateJson);
+            if (components.renderer?.data) {
+                deps.renderer?.restoreRendererMeta?.(components.renderer.data);
+            }
+        }
+        catch { /* ignore */ }
+        log.info("hmr", "Restored state after page reload");
+        if (dd.deleteGameState)
+            dd.deleteGameState(SLOT);
+        return true;
+    }
+    catch (err) {
+        log.error("hmr", `Failed to restore hot-reload state: ${err}. Starting fresh.`);
+        return false;
+    }
+}

package/dist/app/src/renderer/import-cache.js

@@ -0,0 +1,77 @@
+// ============================================================================
+// Host Import Cache — renderer-side adapter for the host's SQLite cache
+// ============================================================================
+// When a host bridge is installed, delegates to the host via `downdraft`
+// (direct in-process calls on native). Without a host, falls back to an
+// in-memory Map via MemoryImportCache.
+//
+import { MemoryImportCache } from "@downdraft/engine";
+/**
+ * Create an ImportCache backed by the host SQLite database.
+ * Falls back to MemoryImportCache if the bridge is unavailable (browser-only mode).
+ */
+export function createHostImportCache(bridge) {
+    if (bridge?.importCacheGet && bridge.importCacheSet && bridge.importCacheInvalidate) {
+        return new HostImportCache(bridge);
+    }
+    return new MemoryImportCache();
+}
+/**
+ * ImportCache implementation that delegates to the host's SQLite store.
+ */
+/** Marker for a confirmed-persisted miss — prevents refetching absent paths. */
+const ABSENT = Symbol("absent");
+class HostImportCache {
+    // Synchronous get/set are backed by an in-memory mirror, since the host
+    // calls are async. The async methods on the bridge are used for actual
+    // persistence. This is a pragmatic trade-off: the cache is eventually
+    // consistent with the SQLite store.
+    memory = new Map();
+    pending = new Set();
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    get(modelPath) {
+        const hit = this.memory.get(modelPath);
+        if (hit)
+            return hit === ABSENT ? null : hit;
+        // Sync interface over an async store: on a miss, hydrate the mirror in
+        // the background so a later get() sees the persisted entry. First-read
+        // after restart can still miss — callers treat null as "reimport". A
+        // negative result is cached so absent paths don't refire per get().
+        if (!this.pending.has(modelPath)) {
+            this.pending.add(modelPath);
+            this.bridge.importCacheGet?.(modelPath).then((entry) => {
+                // Only commit if the fetch is still pending — set()/invalidate()
+                // clear the marker, and an in-flight result must not resurrect an
+                // invalidated entry or clobber a fresher local write.
+                if (!this.pending.delete(modelPath))
+                    return;
+                this.memory.set(modelPath, entry === null ? ABSENT : entry);
+            }).catch(() => { this.pending.delete(modelPath); });
+        }
+        return null;
+    }
+    set(modelPath, entry) {
+        this.pending.delete(modelPath);
+        this.memory.set(modelPath, entry);
+        // Persist to SQLite via the host bridge (fire-and-forget)
+        this.bridge.importCacheSet?.(modelPath, {
+            settings: entry.settings,
+            sourceMtime: entry.sourceMtime,
+            sidecarMtime: entry.sidecarMtime,
+            updatedAt: entry.updatedAt,
+        }).catch(() => {
+            // Host failures are non-fatal — the in-memory cache still works
+        });
+    }
+    invalidate(modelPath) {
+        this.pending.delete(modelPath);
+        this.memory.delete(modelPath);
+        this.bridge.importCacheInvalidate?.(modelPath).catch(() => { });
+    }
+    close() {
+        this.memory.clear();
+    }
+}

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

@@ -0,0 +1,149 @@
+// ============================================================================
+// @downdraft/engine/app/renderer — typed accessor for globalThis.downdraft
+// ============================================================================
+//
+// Import `downdraft` from this module in game/bootstrap code instead of
+// casting `(globalThis as any).downdraft`. The host installs the HostAPI
+// object on `globalThis.downdraft`; this module provides a typed view.
+//
+// When no host bridge is installed (pure browser, headless test), the
+// accessor returns a stub that no-ops / returns null. Callers that need
+// real values should guard with `downdraft?.isAvailable`.
+import { getNativeHost } from "@downdraft/engine";
+import { OpfsSaveStore } from "@downdraft/engine/libraries/persistence/browser";
+import { createSaveStore as _createSaveStore } from "./save-store-factory.js";
+function noop() { }
+const stubBridge = {
+    isAvailable: false,
+    saveGameState: () => Promise.resolve(false),
+    loadGameState: () => Promise.resolve(null),
+    deleteGameState: () => Promise.resolve(false),
+    listSaveSlots: () => Promise.resolve([]),
+    listSaveGenerations: () => Promise.resolve([]),
+    deleteSaveGeneration: () => Promise.resolve(false),
+    setThumbnail: () => Promise.resolve(),
+    getThumbnail: () => Promise.resolve(null),
+    setSaveProperties: () => Promise.resolve(),
+    getSaveProperties: () => Promise.resolve({}),
+    quit: () => Promise.resolve(),
+    setDebugMode: noop,
+    toggleDevtools: noop,
+    toggleFullscreen: noop,
+    getDisplayInfo: () => Promise.resolve({ refreshRate: 0 }),
+    openExternal: noop,
+    getGPUSystemInfo: () => Promise.resolve(null),
+    getGpuInfo: () => Promise.resolve(null),
+    getFeatureLog: () => Promise.resolve(null),
+    captureFrame: () => Promise.resolve(null),
+    getProcessStats: () => Promise.reject(new Error("Process stats not available on this host")),
+    importCacheGet: () => Promise.resolve(null),
+    importCacheSet: () => Promise.resolve(),
+    importCacheInvalidate: () => Promise.resolve(),
+    onSimReady: () => noop,
+    onDisplayInfo: () => noop,
+    onDisplayMetricsChanged: () => noop,
+    onPerfStats: () => noop,
+    onDebugMode: () => noop,
+    onDevtoolsToggle: () => noop,
+    deterministic: false,
+    onMcpRequest: noop,
+};
+/**
+ * Typed accessor for the `globalThis.downdraft` host bridge.
+ *
+ * On the native runtime this is the real HostAPI. In a host-less context
+ * (e.g. model-viewer running standalone in a browser), it returns a stub
+ * with `isAvailable: false`.
+ *
+ * The accessor is lazy: the bridge may be installed AFTER this module is
+ * evaluated (the native host installs `globalThis.downdraft` once its
+ * window/device exist — after static imports have already run). Reads go
+ * through a Proxy so `downdraft.isAvailable` flips live when a bridge
+ * appears. Callers that need a stable snapshot should read it at use time,
+ * not module-eval time (all engine consumers already do).
+ */
+function currentBridge() {
+    const raw = globalThis.downdraft;
+    if (raw) {
+        return { ...raw, isAvailable: true };
+    }
+    return stubBridge;
+}
+export const downdraft = new Proxy({}, {
+    get(_target, prop) {
+        return currentBridge()[prop];
+    },
+    has(_target, prop) {
+        return prop in currentBridge();
+    },
+});
+// Import cache adapter — host-backed with memory fallback
+export { createHostImportCache } from "./import-cache.js";
+export { bootstrapGame } from "./bootstrap.js";
+export { startGame } from "./game-module.js";
+export { useDeterministicRenderPause, useDisplayInfo, useFpsPolling, useHotReloadDispose } from "./hooks.js";
+export { installSimHotReload, restoreHotReloadState } from "./hot-reload.js";
+export { createSimBridge } from "./sim-bridge.js";
+// Save store factory + host save-store bridge type
+export { createInlineSaveStore, createSaveStore } from "./save-store-factory.js";
+/**
+ * Create the default ISaveStore for a game.
+ *
+ * When the host exposes a typed save store (`downdraft.saveStore` — the
+ * native host's HostSaveStore over FileSaveStore), defaults to "host" mode —
+ * disk persistence, stable across sessions, not origin-scoped.
+ *
+ * In a pure browser (no bridge), falls back to "auto" (OPFS worker → inline
+ * OPFS), since there is no host save path available.
+ *
+ * Games that want a specific backend should call `createSaveStore` directly
+ * with an explicit `mode` rather than relying on this default.
+ */
+export async function createDefaultSaveStore(engineVersion) {
+    const mode = downdraft.saveStore ? "host" : "auto";
+    const { store } = await _createSaveStore({
+        mode,
+        opfsOptions: { engineVersion },
+        bridge: downdraft,
+    });
+    if (!store) {
+        const fallback = new OpfsSaveStore({ engineVersion });
+        await fallback.init();
+        return fallback;
+    }
+    return store;
+}
+// AutosaveManager (re-exported from @downdraft/engine/libraries/persistence)
+export { AutosaveManager } from "@downdraft/engine/libraries/persistence/browser";
+// MCP automation harness factory + shared tool helpers
+export { blobToBase64, createMcpHarness, errorResult, jsonResult } from "./mcp-harness.js";
+export { createGameMcp, createStandardAutomationTools } from "./standard-automation-tools.js";
+// Feature log (renderer collector + combined accessor + MCP tool factory)
+export { collectRendererFeatureLog, createFeatureLogMcpTool, getCombinedFeatureLog, getRendererFeatureLog } from "./feature-log.js";
+// --- Render surface ---
+/**
+ * Get the renderer-facing surface for a given layer index.
+ *
+ * This is the canonical accessor — it returns the host-owned `RenderSurface`
+ * on the native runtime (the SDL-windowed wgpu surface installed by
+ * `createNativeHost`) and the DOM `<canvas>` element on browser hosts (which
+ * satisfies `RenderSurface` structurally).
+ *
+ * Layer 0 is the primary game surface. On native, layer 0 is the only
+ * surface — requesting any other layer throws (multi-canvas layering is a
+ * DOM-host concept).
+ */
+export function getSurface(layer = 0) {
+    if (layer !== 0) {
+        throw new Error(`No surface for layer ${layer} — the native host exposes exactly one RenderSurface (layer 0).`);
+    }
+    // The boundary cast: NativeSurface's WebGPU context returns the wgpu
+    // wrapper types (WgpuTexture), not @webgpu/types' branded GPUTexture.
+    // The contract is honored at runtime; the cast bridges the two type
+    // universes.
+    const surface = getNativeHost()?.surface;
+    if (!surface) {
+        throw new Error("No native surface — the host has not installed __nativeHost.surface yet");
+    }
+    return surface;
+}

package/dist/app/src/renderer/mcp-harness.js

@@ -0,0 +1,112 @@
+// ============================================================================
+// createMcpHarness() — factory for renderer-side MCP automation harnesses.
+//
+// Centralizes the MCP request-handling boilerplate shared by games
+// that have MCP automation:
+//   - initialize / tools/list / tools/call / shutdown method dispatch
+//   - downdraft.onMcpRequest wiring
+//   - Error handling + logging
+//
+// Games provide only their tool definitions + handlers.
+// ============================================================================
+import { createLogger } from "@downdraft/engine/util/logger";
+import { downdraft } from "./index.js";
+const log = createLogger();
+/**
+ * Create and register an MCP automation harness.
+ *
+ * Wires `downdraft.onMcpRequest` to handle the standard MCP protocol
+ * (initialize, tools/list, tools/call, shutdown) and dispatches tool calls
+ * to the provided handlers.
+ *
+ * If no host bridge is installed (e.g. running standalone in a browser),
+ * this is a no-op.
+ *
+ * @example
+ * createMcpHarness({
+ *   serverName: "downdraft-mygame-automation",
+ *   tools: [
+ *     {
+ *       def: { name: "capture_screenshot", description: "...", inputSchema: {...} },
+ *       handler: async (params) => { ... },
+ *     },
+ *   ],
+ * });
+ */
+export function createMcpHarness(opts) {
+    const { serverName, serverVersion = "0.1.0", tools } = opts;
+    const handleRequest = async (req) => {
+        const { id, method, params = {} } = req;
+        try {
+            if (method === "initialize") {
+                return {
+                    id,
+                    result: {
+                        protocolVersion: "2024-11-05",
+                        capabilities: { tools: {}, resources: {}, prompts: {} },
+                        serverInfo: { name: serverName, version: serverVersion },
+                    },
+                };
+            }
+            if (method === "tools/list") {
+                return {
+                    id,
+                    result: {
+                        tools: tools.map((t) => ({
+                            name: t.def.name,
+                            description: t.def.description,
+                            inputSchema: t.def.inputSchema,
+                        })),
+                    },
+                };
+            }
+            if (method === "tools/call") {
+                const name = params.name;
+                const args = params.arguments ?? {};
+                const tool = tools.find((t) => t.def.name === name);
+                if (!tool) {
+                    return { id, error: { code: -32602, message: `Unknown tool: ${name}` } };
+                }
+                const result = await tool.handler(args);
+                return { id, result: result };
+            }
+            if (method === "shutdown") {
+                return { id, result: {} };
+            }
+            return { id, error: { code: -32601, message: `Method not found: ${method}` } };
+        }
+        catch (e) {
+            return { id, error: { code: -32603, message: e.message } };
+        }
+    };
+    if (!downdraft?.isAvailable || typeof downdraft.onMcpRequest !== "function") {
+        log.warn("mcp", "Host bridge or onMcpRequest not available; automation harness disabled");
+        return;
+    }
+    downdraft.onMcpRequest(async (request) => handleRequest(request));
+    log.info("mcp", `${serverName} registered; tools: ${tools.map((t) => t.def.name).join(", ")}`);
+}
+// ── Shared MCP tool helpers ──────────────────────────────────────────────────
+// These utilities are used by multiple games' MCP automation harnesses.
+// Games import them instead of duplicating the implementation.
+/** Convert a Blob to a base64 string (without the data: prefix). */
+export function blobToBase64(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onloadend = () => {
+            const result = reader.result;
+            const base64 = result.split(",")[1];
+            resolve(base64 ?? "");
+        };
+        reader.onerror = reject;
+        reader.readAsDataURL(blob);
+    });
+}
+/** MCP result helper: wrap data as a JSON content array. */
+export function jsonResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+/** MCP result helper: wrap an error message. */
+export function errorResult(message) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }] };
+}

package/dist/app/src/renderer/save-store-factory.js

@@ -0,0 +1,180 @@
+// ============================================================================
+// Save Store Factory — creates the appropriate ISaveStore based on
+// environment capabilities and game configuration.
+// ============================================================================
+//
+// Mode selection:
+//   "inline"  — OpfsSaveStore runs inside the sim worker (caller is responsible
+//               for creating it there). The factory returns null here; the
+//               sim worker creates the store directly.
+//   "worker"  — Spawns a dedicated save Web Worker with OpfsSaveStore inside.
+//               Returns a SaveWorkerProxy. (Browser builds only — the native
+//               host has no OPFS.)
+//   "host"    — The host's own save store (`downdraft.saveStore`). On native
+//               this is HostSaveStore over HostServices → FileSaveStore: real
+//               SaveState in, real SaveResult/LoadResult out, no JSON
+//               boundary. The default when a host bridge is installed.
+//   "auto"    — Picks "host" when the host exposes a typed save store, else
+//               "worker" if OPFS is available. (On native there is no OPFS
+//               and no process boundary, so no fallback flip can produce a
+//               divergent save location.)
+//
+// The factory is called from the renderer after the sim worker is initialized.
+import { OpfsSaveStore, SaveWorkerProxy } from "@downdraft/engine/libraries/persistence/browser";
+/**
+ * Check if OPFS is available in the current environment.
+ */
+export function isOpfsAvailable() {
+    const nav = globalThis;
+    return typeof nav.navigator?.storage?.getDirectory === "function";
+}
+/**
+ * Create the appropriate ISaveStore based on the mode and environment.
+ *
+ * - "inline": Returns null. The caller should create an OpfsSaveStore inside
+ *   the sim worker directly (the worker has the serialized state and can
+ *   write to OPFS without crossing worker boundaries).
+ * - "worker": Spawns a dedicated save worker with OpfsSaveStore. Returns
+ *   a SaveWorkerProxy. The caller must call init() on it.
+ * - "host": Returns the host's save store (native HostSaveStore →
+ *   FileSaveStore on disk). Stable across sessions; not origin-scoped.
+ * - "auto": Picks "host" when the bridge exposes a typed save store, else
+ *   "worker" when OPFS is available.
+ *
+ * Returns `{ store, mode }` where `mode` is the backend that was actually
+ * selected (which may differ from the requested mode in "auto" fallback).
+ */
+export async function createSaveStore(opts) {
+    const mode = opts.mode ?? "auto";
+    switch (mode) {
+        case "inline":
+            // The caller creates the OpfsSaveStore inside the sim worker.
+            // Return null to signal that the sim worker handles saves directly.
+            return { store: null, mode: "inline" };
+        case "worker": {
+            if (!isOpfsAvailable()) {
+                throw new Error("OPFS is not available — cannot use 'worker' mode. Use 'auto' or 'inline' mode.");
+            }
+            const proxy = new SaveWorkerProxy({
+                storeOptions: opts.opfsOptions,
+                workerUrl: opts.workerUrl,
+            });
+            await proxy.init();
+            return { store: proxy, mode: "worker" };
+        }
+        case "host": {
+            if (!opts.bridge?.saveStore) {
+                throw new Error("No host save store on the bridge — 'host' mode requires a native host (downdraft.saveStore)");
+            }
+            return { store: opts.bridge.saveStore, mode: "host" };
+        }
+        case "auto": {
+            // Native-first: when the host exposes a typed save store, use it.
+            // There is no OPFS and no process boundary on native.
+            if (opts.bridge?.saveStore) {
+                return { store: opts.bridge.saveStore, mode: "host" };
+            }
+            if (isOpfsAvailable()) {
+                // Try dedicated worker mode, with a 5s init timeout — the worker
+                // spawn can hang in some environments (e.g. when Vite's worker URL
+                // resolution fails in dev mode).
+                const proxy = new SaveWorkerProxy({
+                    storeOptions: opts.opfsOptions,
+                    workerUrl: opts.workerUrl,
+                });
+                await Promise.race([
+                    proxy.init(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("SaveWorkerProxy init timeout (5s)")), 5000)),
+                ]);
+                return { store: proxy, mode: "worker" };
+            }
+            // Last resort: the bridge's JSON save methods. On native this only
+            // happens in headless/test hosts with no appId (the stub bridge) —
+            // saves no-op but callers get a well-formed store. In a browser with
+            // a real bridge this preserves the pre-migration fallback behavior.
+            if (opts.bridge) {
+                return { store: new BridgeJsonSaveStore(opts.bridge), mode: "host" };
+            }
+            throw new Error("No save backend available in 'auto' mode — no host save store, no OPFS, no bridge");
+        }
+        default:
+            throw new Error(`Unknown save store mode: ${mode}`);
+    }
+}
+/**
+ * ISaveStore over the bridge's JSON-string save methods — the last-resort
+ * "auto" backend for headless hosts (stub bridge) and environments without
+ * a typed store or OPFS. The wire format is the components
+ * map (what host `saveGame`/`loadGame` handlers parse/return); SaveResult
+ * metadata is unavailable across the JSON boundary.
+ */
+export class BridgeJsonSaveStore {
+    bridge;
+    warningCallbacks = new Set();
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    async save(slot, state, opts) {
+        try {
+            const success = await this.bridge.saveGameState(slot, JSON.stringify(state.components), opts);
+            return { success, bytes: 0 };
+        }
+        catch {
+            return { success: false, bytes: 0 };
+        }
+    }
+    async load(slot, opts) {
+        try {
+            const result = await this.bridge.loadGameState(slot, opts);
+            if (!result)
+                return { state: null };
+            const components = JSON.parse(result);
+            return {
+                state: {
+                    components,
+                    meta: { engineVersion: "", timestamp: 0, entityCount: 0, playerCount: 0 },
+                },
+            };
+        }
+        catch {
+            return { state: null };
+        }
+    }
+    listSaves() {
+        return this.bridge.listSaveSlots();
+    }
+    async listGenerations(slot) {
+        return this.bridge.listSaveGenerations?.(slot) ?? [];
+    }
+    deleteSave(slot) {
+        return this.bridge.deleteGameState(slot);
+    }
+    async deleteGeneration(slot, gen) {
+        return this.bridge.deleteSaveGeneration?.(slot, gen) ?? false;
+    }
+    async setThumbnail(slot, data) {
+        await this.bridge.setThumbnail?.(slot, data);
+    }
+    async getThumbnail(slot) {
+        return (await this.bridge.getThumbnail?.(slot)) ?? null;
+    }
+    async setProperties(slot, props) {
+        await this.bridge.setSaveProperties?.(slot, props);
+    }
+    async getProperties(slot) {
+        return (await this.bridge.getSaveProperties?.(slot)) ?? {};
+    }
+    onWarning(cb) {
+        this.warningCallbacks.add(cb);
+        return () => { this.warningCallbacks.delete(cb); };
+    }
+}
+/**
+ * Create an OpfsSaveStore directly (for inline mode where the store runs
+ * inside the sim worker). This is a convenience wrapper that calls init().
+ */
+export async function createInlineSaveStore(opts) {
+    const store = new OpfsSaveStore(opts);
+    await store.init();
+    return store;
+}