@downdraft/engine 0.0.0 → 0.1.1

package/app/src/renderer/hooks.ts

@@ -0,0 +1,88 @@
+// ============================================================================
+// 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";
+
+/**
+ * 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: { getFPS: () => number },
+  onFps: (fps: number) => void,
+  intervalMs: number = 500,
+): () => void {
+  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: { pause?: () => void },
+  deterministic: boolean,
+): void {
+  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: (refreshRate: number) => void,
+): () => void {
+  if (!downdraft?.isAvailable) return () => {};
+
+  downdraft.getDisplayInfo().then((info) => {
+    if (info.refreshRate > 0) onRefreshRate(info.refreshRate);
+  }).catch(() => { /* ignore */ });
+
+  return downdraft.onDisplayInfo((info: any) => {
+    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: () => Promise<void> | void,
+): void {
+  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: () => Promise<void> | void): void {
+  const hot = (import.meta as any).hot;
+  const session = (globalThis as any).__ddSession;
+  if (!hot?.dispose && !session?.onDispose) return;
+  let offSession: (() => void) | null = null;
+  const wrapped = () => {
+    offSession?.();
+    offSession = null;
+    return disposeFn();
+  };
+  if (hot?.dispose) hot.dispose(wrapped);
+  if (session?.onDispose) offSession = session.onDispose(wrapped);
+}

package/app/src/renderer/hot-reload.ts

@@ -0,0 +1,178 @@
+// ============================================================================
+// 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, type IRendererStateProvider, type SaveOptions } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { downdraft, type Host } from "./index";
+
+const log = createLogger("info");
+
+/** Minimal sim surface needed by the HMR handlers. */
+export interface HotReloadableSim {
+  hotReload?(config: unknown, preserveState: boolean): Promise<void>;
+  save?(slotName: string, opts?: SaveOptions): Promise<{ stateJson?: string } | null>;
+  restoreFromState?(stateJson: string): Promise<void>;
+}
+
+export interface SimHotReloadDeps {
+  sim: HotReloadableSim;
+  /** Renderer meta provider — grafted into the hot-reload save. */
+  renderer?: IRendererStateProvider | null;
+  /** Config passed to sim.hotReload(). May be a getter evaluated per reload. */
+  simConfig: unknown | (() => unknown);
+  /** App bridge — defaults to the window.downdraft singleton (or its stub). */
+  downdraft?: Host | null;
+}
+
+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: SimHotReloadDeps): void {
+  if (!isDevMode || !import.meta.hot) return;
+  const bridge = () => deps.downdraft ?? downdraft;
+  const getConfig = () =>
+    typeof deps.simConfig === "function" ? (deps.simConfig as () => unknown)() : 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 as any).__ddSession;
+  if (session) {
+    if (deps.sim?.hotReload && !session.hasSimFor?.(deps.sim)) {
+      session.registerSim?.({
+        label: "game-sim",
+        host: deps.sim,
+        hotReload: (preserve: boolean) => deps.sim.hotReload!(getConfig(), preserve),
+        save: async () => (await deps.sim.save?.(SLOT))?.stateJson ?? null,
+        restore: (json: string) => deps.sim.restoreFromState?.(json),
+      });
+    }
+    if (deps.renderer?.serializeRendererMeta) {
+      const renderer = deps.renderer;
+      session.registerMetaProvider?.({
+        serialize: () => renderer.serializeRendererMeta!(),
+        restore: (meta: unknown) => renderer.restoreRendererMeta?.(meta as Record<string, unknown>),
+      });
+    }
+    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 as unknown as {
+    on(event: string, cb: (data: any) => void): void;
+    send(event: string, data?: any): void;
+  };
+
+  hot.on("sim:hot-reload", async (data: { file: string; timestamp: number }) => {
+    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 as Error).message}`);
+      store.setStatus("error", (err as Error).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: { file: string; timestamp: number }) => {
+    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: Pick<SimHotReloadDeps, "sim" | "renderer" | "downdraft">,
+): Promise<boolean> {
+  // 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 as any).__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/app/src/renderer/import-cache.ts

@@ -0,0 +1,88 @@
+// ============================================================================
+// 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, type CacheEntry, type ImportCache } 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?: {
+  importCacheGet?: (modelPath: string) => Promise<{ settings: unknown; sourceMtime: number; sidecarMtime: number; updatedAt: number } | null>;
+  importCacheSet?: (modelPath: string, entry: { settings: unknown; sourceMtime: number; sidecarMtime: number; updatedAt: number }) => Promise<void>;
+  importCacheInvalidate?: (modelPath: string) => Promise<void>;
+} | null): ImportCache {
+  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 implements ImportCache {
+  // 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.
+  private memory = new Map<string, CacheEntry | typeof ABSENT>();
+  private pending = new Set<string>();
+  private bridge: NonNullable<Parameters<typeof createHostImportCache>[0]>;
+
+  constructor(bridge: NonNullable<Parameters<typeof createHostImportCache>[0]>) {
+    this.bridge = bridge;
+  }
+
+  get(modelPath: string): CacheEntry | null {
+    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 as CacheEntry));
+      }).catch(() => { this.pending.delete(modelPath); });
+    }
+    return null;
+  }
+
+  set(modelPath: string, entry: CacheEntry): void {
+    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: string): void {
+    this.pending.delete(modelPath);
+    this.memory.delete(modelPath);
+    this.bridge.importCacheInvalidate?.(modelPath).catch(() => {});
+  }
+
+  close(): void {
+    this.memory.clear();
+  }
+}

package/app/src/renderer/index.ts

@@ -0,0 +1,206 @@
+// ============================================================================
+// @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, type RenderSurface } from "@downdraft/engine";
+import { OpfsSaveStore } from "@downdraft/engine/libraries/persistence/browser";
+import type {
+    HostAPI,
+    HostOsrAPI
+} from "../shared/types";
+import { createSaveStore as _createSaveStore } from "./save-store-factory";
+
+export type HostOsr = HostOsrAPI;
+
+export interface Host extends Omit<HostAPI, "osr"> {
+  isAvailable: boolean;
+  isDev?: boolean;
+  osr?: HostOsr;
+}
+
+function noop(): void {}
+
+const stubBridge: Host = {
+  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(): Host {
+  const raw = (globalThis as unknown as { downdraft?: HostAPI }).downdraft;
+  if (raw) {
+    return { ...raw, isAvailable: true } as Host;
+  }
+  return stubBridge;
+}
+
+export const downdraft: Host = new Proxy({} as Host, {
+  get(_target, prop) {
+    return (currentBridge() as unknown as Record<string | symbol, unknown>)[prop];
+  },
+  has(_target, prop) {
+    return prop in currentBridge();
+  },
+});
+
+// Import cache adapter — host-backed with memory fallback
+export { createHostImportCache } from "./import-cache";
+
+// Bootstrap orchestrator + composable hooks
+export type { GameRendererLike } from "@downdraft/engine";
+export { bootstrapGame } from "./bootstrap";
+export type { BootstrapAutosaveOptions, BootstrapDevToolsOptions, BootstrapGameOptions } from "./bootstrap";
+export { startGame } from "./game-module";
+export type {
+    GameContext,
+    GameModule,
+    GameSaveConfig,
+    GameSaveSource,
+    GameSimWorker, GameUiHandle,
+    PluginRuntimeConfig,
+    RendererFactory,
+    SimEventMap,
+    SimWorkerFactory,
+    SimWorkerSeed
+} from "./game-module";
+export { useDeterministicRenderPause, useDisplayInfo, useFpsPolling, useHotReloadDispose } from "./hooks";
+export { installSimHotReload, restoreHotReloadState } from "./hot-reload";
+export type { HotReloadableSim, SimHotReloadDeps } from "./hot-reload";
+export { createSimBridge } from "./sim-bridge";
+export type { SimBridge, SimBridgeDeps, SimBridgeWorker } from "./sim-bridge";
+
+// Save store factory + host save-store bridge type
+export { createInlineSaveStore, createSaveStore, type CreateSaveStoreOptions, type CreateSaveStoreResult, type SaveBridge, type SaveStoreMode } from "./save-store-factory";
+
+/**
+ * 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: string): Promise<import("@downdraft/engine").ISaveStore> {
+  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, type AutosaveManagerOptions } from "@downdraft/engine/libraries/persistence/browser";
+
+// MCP automation harness factory + shared tool helpers
+export { blobToBase64, createMcpHarness, errorResult, jsonResult } from "./mcp-harness";
+export type { McpHarnessOptions, McpRequest, McpResponse, McpToolDef, McpToolRegistration } from "./mcp-harness";
+export { createGameMcp, createStandardAutomationTools } from "./standard-automation-tools";
+export type {
+    GameMcpOptions,
+    InjectedInputFrame,
+    StandardAutomationContext,
+    StandardInputInjector,
+    StandardToolName
+} from "./standard-automation-tools";
+
+// Feature log (renderer collector + combined accessor + MCP tool factory)
+export {
+    collectRendererFeatureLog,
+    createFeatureLogMcpTool,
+    getCombinedFeatureLog,
+    getRendererFeatureLog
+} from "./feature-log";
+export type { CombinedFeatureLog, RendererFeatureLogOptions } from "./feature-log";
+
+// --- 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: number = 0): RenderSurface {
+  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 as RenderSurface;
+}