@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/README.md

@@ -0,0 +1,33 @@
+# `@downdraft/engine`
+
+Downdraft engine — a native-runtime game engine (winit + wgpu, no Electron, no browser shell). The JS host is interchangeable: Bun, Node, and Deno all run the same engine through a shared FFI/device layer.
+
+Everything the engine ships is exposed as **subpath exports** of this one package:
+
+- `@downdraft/engine` — core index (ECS, render loop, HostAPI types)
+- `@downdraft/engine/app/renderer` — `startGame()` / `bootstrapGame()` game bootstrap
+- `@downdraft/engine/libraries/<name>` — engine building blocks (physics, audio, models, water, weather, navmesh, gpu-kernels, …)
+- `@downdraft/engine/modules/<name>` — opt-in feature modules with lifecycle + typed DI (movement-2d/3d, terrain, sailing, camera-controls, devtools, …)
+- `@downdraft/engine/platform/…` — runtime adapters (native surface, FFI, SAB channels)
+
+## Install
+
+```sh
+bun add @downdraft/engine @downdraft/platform-native @downdraft/cli
+```
+
+`@downdraft/platform-native` supplies the native window/GPU device layer (prebuilt binaries per OS/arch arrive via optional dependencies).
+
+## Quick start
+
+```ts
+import { startGame } from "@downdraft/engine/app/renderer";
+
+startGame({
+  renderer: (canvas) => new WebGPURenderer(canvas),
+  sim: (seed) => new SimWebWorker(seed?.libraryBuffers),
+  simConfig: { seed: 12345 },
+});
+```
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/app/README.md

@@ -0,0 +1,11 @@
+# `@downdraft/engine/app`
+
+Downdraft application runtime — renderer runtime (startGame/GameModule), shared host services, and dev-shell support.
+
+## Install
+
+```sh
+bun add @downdraft/engine/app
+```
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/app/src/renderer/bootstrap.ts

@@ -21,13 +21,79 @@
 // that need full control can call `bootstrapGame()` directly.
 // ============================================================================
 
-import { encodeFeatureLogLine, isDevMode, type RenderSurface } from "@downdraft/engine";
+import { encodeFeatureLogLine, getNativeHost, isDevMode, type RenderSurface } from "@downdraft/engine";
 import { createLogger } from "@downdraft/engine/util/logger";
 import { collectRendererFeatureLog } from "./feature-log";
 import { downdraft, getSurface } from "./index";
 
 const log = createLogger("info");
 
+// Pre-warm the devtools chunks in dev mode. The dynamic imports below are
+// awaited deep inside async bootstrap frames — if the fetch is still in
+// flight when a dev-session restart clears the runner's module cache, the
+// pending fetch can be dropped unresolved, leaving the async frame suspended
+// forever and pinning the dead generation's renderer/devtools graph. Firing
+// the import at module eval collapses the awaits to a settled-cache lookup.
+const devtoolsModuleP = isDevMode
+  ? import("@downdraft/engine/modules/devtools")
+  : null;
+const devtoolsLibP = isDevMode
+  ? import("@downdraft/engine/libraries/devtools")
+  : null;
+// ./hooks is tiny and same-graph, but pre-warming it too keeps the await at
+// the bottom of bootstrapGame() off the in-flight-fetch path as well.
+const hooksP = import("./hooks");
+// Attach benign handlers so a rejection before the first await isn't flagged
+// as unhandled — awaiting the original promise still propagates the error.
+devtoolsModuleP?.catch(() => {});
+devtoolsLibP?.catch(() => {});
+hooksP.catch(() => {});
+
+/**
+ * Race an awaited import against session teardown: under the dev shell a
+ * fetch can be orphaned mid-flight (module-cache clear drops the pending
+ * entry unresolved), which would suspend the awaiting async frame forever —
+ * JSC retains suspended frames via their rooted executables, so the frame's
+ * captured environment (renderer, module host, devtools host) leaks per
+ * restart. Resolving to null lets the caller abandon the work cleanly.
+ */
+function importOrDead<T>(p: Promise<T>, expectedSession?: any): Promise<T | null> {
+  const tracker = (globalThis as any).__ddSession;
+  if (!tracker || typeof tracker.onDispose !== "function") return p;
+  const s = tracker.session;
+  // No live session — or a DIFFERENT session than the caller's generation —
+  // at await time means this frame belongs to a generation that is already
+  // dead. Resolve null now so it unwinds rather than parking on a
+  // possibly-orphaned fetch or registering into the wrong session.
+  if (!s || s.dead || (expectedSession !== undefined && s !== expectedSession)) {
+    return Promise.resolve(null);
+  }
+  return Promise.race([
+    p,
+    new Promise<null>((resolve) => {
+      tracker.onDispose(() => resolve(null));
+      // The registration is dropped when the session is already dying —
+      // re-check so the race can't park on a resolve that will never fire.
+      if (s.dead || tracker.session !== s) resolve(null);
+    }),
+  ]);
+}
+
+/** Bail predicate for bootstrapGame's mid-boot awaits. The session snapshot
+ *  captured at ENTRY is this generation's identity: after any await a restart
+ *  may have torn it down AND begun a fresh session — checking the tracker's
+ *  current session alone would let dead-generation continuations register
+ *  timers/listeners into the new session (which tracks them faithfully,
+ *  pinning the dead module graph for a whole generation). Also bails when a
+ *  host restart stripped the DOM polyfill globals. */
+function makeBootGuard(mySession: any): () => boolean {
+  const tracker = (globalThis as any).__ddSession;
+  return () => {
+    if (tracker && (tracker.session !== mySession || !mySession || mySession.dead)) return true;
+    return typeof (globalThis as any).window === "undefined";
+  };
+}
+
 export interface BootstrapAutosaveOptions {
   /** Load saved state. Returns null if no save exists. */
   load: () => Promise<any | null>;
@@ -56,6 +122,8 @@ export interface BootstrapDevToolsOptions {
    *  renderer init — a factory runs when the game's sim worker is already
    *  started, e.g. by an overridden onInit). */
   workerHosts?: any[] | ((renderer: any) => any[]);
+  /** Extra game-level rows for the Input panel. */
+  inputInfo?: () => { key: string; value: string; flags?: number }[];
   /**
    * Enable the profiling system (ProfilingSAB + ProfilingBridge + built-in views).
    * When true, a ProfilingBridge is created and the ProfilingSAB is shared
@@ -63,6 +131,19 @@ export interface BootstrapDevToolsOptions {
    * pre-allocated buffer. Default: false.
    */
   profiling?: boolean | { sharedSAB?: { sab: SharedArrayBuffer; layout: unknown } };
+  /**
+   * Devtools UI frontend. "blitz" (default) mounts the docked in-window UI
+   * (F12 toggles); "web" starts the loopback browser frontend
+   * (WebDevtoolsHost, requires Bun); "none" wires data only.
+   * Object form: `{ kind: "blitz", dockFraction?, autoShow?, toggleKey? }`.
+   * `DOWNDRAFT_DISABLE_DEVTOOLS=1` forces "none".
+   */
+  ui?: "blitz" | "web" | "none" | {
+    kind?: "blitz" | "web";
+    dockFraction?: number;
+    autoShow?: boolean;
+    toggleKey?: string | null;
+  };
 }
 
 export interface BootstrapGameOptions {
@@ -128,6 +209,8 @@ export interface BootstrapGameOptions {
  * partial composition can use the individual hooks from `./hooks.ts` instead.
  */
 export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
+  const bootSession = (globalThis as any).__ddSession?.session ?? null;
+  const bootAborted = makeBootGuard(bootSession);
   const canvasLayer = opts.canvasLayer ?? 0;
   const deterministic = downdraft?.deterministic === true;
 
@@ -137,17 +220,21 @@ export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
   // 3. Create + init renderer
   const renderer = opts.createRenderer(surface);
   if (opts.initRenderer) {
-    const ok = await opts.initRenderer(renderer);
+    const ok = await importOrDead(Promise.resolve(opts.initRenderer(renderer)), bootSession);
+    if (ok === null) return;
     if (!ok) {
-      log.error("bootstrapGame", "Renderer init failed");
+      log.error("bootstrap-game", "Renderer init failed");
       return;
     }
   }
+  if (bootAborted()) return;
 
   // 4. Wire DevTools (if provided) — runs BEFORE onRendererInit so that
   //    games can access the ProfilingBridge + __sceneInspector API in onReady.
   if (opts.devtools) {
-    const { initDevTools } = await import("@downdraft/engine/modules/devtools");
+    const devtoolsMod = await importOrDead(devtoolsModuleP ?? import("@downdraft/engine/modules/devtools"), bootSession);
+    if (!devtoolsMod) return;
+    const { initDevTools } = devtoolsMod;
     const simStatsProvider = opts.devtools.createSimStatsProvider?.(renderer);
     const panels = typeof opts.devtools.panels === "function"
       ? opts.devtools.panels(renderer)
@@ -155,21 +242,149 @@ export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
     const workerHosts = typeof opts.devtools.workerHosts === "function"
       ? opts.devtools.workerHosts(renderer)
       : opts.devtools.workerHosts;
-    await initDevTools(renderer, {
+    const devtoolsBridge = await importOrDead(initDevTools(renderer, {
       simStatsProvider,
       panels,
       sceneInspector: opts.devtools.sceneInspector,
       bridgeClass: opts.devtools.bridgeClass,
       workerHosts,
       profiling: opts.devtools.profiling as any,
-    });
+    }), bootSession);
+    if (!devtoolsBridge) return;
+    if (bootAborted()) {
+      try { devtoolsBridge.destroy(); } catch {}
+      return;
+    }
+    // The bridge exposes `window.__sceneInspector` on the PERSISTENT window —
+    // its methods close over `renderer`, so without a destroy on session
+    // teardown the old session's renderer (and through it the whole module
+    // graph) stays rooted across hot-reload restarts.
+    const hooksMod = await importOrDead(hooksP, bootSession);
+    if (!hooksMod) return;
+    hooksMod.dispose(() => { try { devtoolsBridge.destroy(); } catch {} });
+
+    // 4a. Profiling wiring — `profiling: true` allocates the SAB + bridge,
+    //     but without this nothing ticks the bridge or shares the SAB with
+    //     workers, so the perf tab would only ever report the main thread.
+    //     wireProfilingBridge guards against games that also call it
+    //     manually; worker-side attach is idempotent.
+    if (opts.devtools.profiling) {
+      try {
+        const mod = await importOrDead(devtoolsModuleP ?? import("@downdraft/engine/modules/devtools"), bootSession);
+        if (!mod) return;
+        const { wireProfilingBridge } = mod;
+        const bridge =
+          (globalThis as Record<string, any>).window?.__sceneInspector?.__getProfilingBridge?.()
+          ?? (globalThis as Record<string, any>).__sceneInspector?.__getProfilingBridge?.()
+          ?? null;
+        if (bridge) {
+          // workerHosts entries are {prefix, proxy} — the devtools proxy
+          // exposes __profilingAttach via exposeDevToolsApi → wrap each into
+          // the ProfilingWireHost surface wireProfilingBridge expects.
+          const hosts: Array<{ host: { attachProfilingSAB(sab: SharedArrayBuffer, o?: any): Promise<void> }; workerTag?: string }> = [];
+          (workerHosts ?? []).forEach((wh: any) => {
+            const proxy = wh?.proxy;
+            if (typeof proxy?.__profilingAttach !== "function") return;
+            const prefix = wh?.prefix;
+            hosts.push({
+              host: {
+                attachProfilingSAB: async (sab, o) => {
+                  await proxy.__profilingAttach(sab, {
+                    workerTag: o?.workerTag ?? prefix ?? "worker",
+                    layout: o?.layout,
+                  });
+                },
+              },
+              workerTag: prefix,
+            });
+          });
+          // The native services worker (save + SQLite) exposes the same
+          // profiling RPC — claim a slot for it too.
+          const services = (getNativeHost() as any)?.services;
+          if (typeof services?.api?.__profilingAttach === "function") {
+            hosts.push({
+              host: {
+                attachProfilingSAB: async (sab, o) => {
+                  await services.api.__profilingAttach(sab, {
+                    workerTag: "services",
+                    layout: o?.layout,
+                  });
+                },
+              },
+              workerTag: "services",
+            });
+          }
+          wireProfilingBridge({ renderer, bridge, workerHosts: hosts });
+        }
+      } catch (err) {
+        log.warn("bootstrap-game", `profiling wiring failed: ${err}`);
+      }
+    }
+
+    // 4b. Devtools UI frontend — the Blitz dock is the default surface.
+    const disabled = typeof process !== "undefined" && !!process.env?.DOWNDRAFT_DISABLE_DEVTOOLS;
+    const uiOpt = opts.devtools.ui ?? "blitz";
+    const uiKind = disabled ? "none" : (typeof uiOpt === "string" ? uiOpt : uiOpt.kind ?? "blitz");
+    if (uiKind !== "none" && typeof renderer.useRendererModule === "function") {
+      try {
+        const uiCfg = typeof uiOpt === "object" ? uiOpt : {};
+        const profilingSAB =
+          (globalThis as Record<string, any>).window?.__sceneInspector?.__getProfilingBridge?.()?.getProfilingSAB?.()
+          ?? (globalThis as Record<string, any>).__sceneInspector?.__getProfilingBridge?.()?.getProfilingSAB?.()
+          ?? null;
+        if (uiKind === "blitz") {
+          const mod = await importOrDead(devtoolsModuleP ?? import("@downdraft/engine/modules/devtools"), bootSession);
+          if (!mod) return;
+          const { createDevtoolsUiModule } = mod;
+          renderer.useRendererModule(createDevtoolsUiModule({
+            renderer,
+            profilingSAB,
+            dockFraction: uiCfg.dockFraction,
+            autoShow: uiCfg.autoShow,
+            toggleKey: uiCfg.toggleKey,
+            onHost: (host) => {
+              renderer.nativeDebugger = host;
+              wireDevtoolsFrontend(host.devtoolsMirror, host, renderer, workerHosts, profilingSAB, opts.devtools?.inputInfo, bootSession);
+            },
+          }));
+        } else {
+          // "web" — loopback browser frontend (Bun-only transport).
+          const libMod = await importOrDead(devtoolsLibP ?? import("@downdraft/engine/libraries/devtools"), bootSession);
+          if (!libMod) return;
+          const { WebDevtoolsHost } = libMod;
+          const webHost = new WebDevtoolsHost({
+            device: renderer.getDevice?.() as GPUDevice,
+            adapter: null as any,
+            targetFormat: renderer.getFormat?.() ?? "bgra8unorm",
+            width: 0, height: 0,
+            renderer,
+            profilingSAB,
+          });
+          await webHost.start();
+          renderer.nativeDebugger = webHost;
+          wireDevtoolsFrontend(webHost.devtoolsMirror, webHost, renderer, workerHosts, profilingSAB, opts.devtools?.inputInfo, bootSession);
+          // Per-frame pump + F12 through the renderer's input bus, same as
+          // the Blitz module's wiring.
+          renderer.setCallbacks?.({
+            ...renderer.getCallbacks?.(),
+            beforeFrame: ((prev: any) => (dt: number, t: number) => {
+              try { webHost.update(); } catch { /* ignore */ }
+              prev?.(dt, t);
+            })(renderer.getCallbacks?.().beforeFrame),
+          });
+        }
+      } catch (err) {
+        log.error("bootstrap-game", `Devtools UI init failed: ${err}`);
+      }
+    }
   }
 
-  // 4b. onRendererInit — library setup, sim start, game-specific wiring (onReady).
+  // 4c. onRendererInit — library setup, sim start, game-specific wiring (onReady).
   //     DevTools is already wired, so games can access __sceneInspector +
   //     the ProfilingBridge from their onReady hook.
   if (opts.onRendererInit) {
-    await opts.onRendererInit(renderer);
+    await importOrDead(Promise.resolve(opts.onRendererInit(renderer)), bootSession);
+    if (bootAborted()) return;
   }
 
   // 5. Start the render loop immediately — don't let a hung autosave load
@@ -191,16 +406,19 @@ export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
     deterministic,
     getActiveModules: opts.getActiveModules,
   });
-  log.info("bootstrapGame", encodeFeatureLogLine(renderFeatureLog));
+  log.info("bootstrap-game", encodeFeatureLogLine(renderFeatureLog));
 
-  // 7. FPS polling (if onFpsUpdate provided)
+  // 7. FPS polling (if onFpsUpdate provided). unref so the interval can't
+  //    pin the runtime after the window closes (packaged mode has no session
+  //    tracker to clear it).
   if (opts.onFpsUpdate) {
     const fpsInterval = opts.fpsPollIntervalMs ?? 500;
-    setInterval(() => {
+    const id = setInterval(() => {
       if (typeof renderer.getFPS === "function") {
         opts.onFpsUpdate!(renderer.getFPS());
       }
     }, fpsInterval);
+    (id as any)?.unref?.();
   }
 
   // 8. Display info wiring (if onDisplayInfo provided)
@@ -228,40 +446,49 @@ export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
     const intervalMs = autosaveOpts.intervalMs ?? 3000;
 
     try {
-      const saved = await Promise.race([
+      // The inner race's timeout leg is session-tracked — teardown sweeps it
+      // unresolved — so the whole race is additionally raced against session
+      // teardown via importOrDead (returns null → bootAborted bails below).
+      const saved = await importOrDead(Promise.race([
         autosaveOpts.load(),
         new Promise<null>((r) => setTimeout(() => r(null), 5000)),
-      ]);
+      ]), bootSession);
       if (saved && autosaveOpts.onLoad) {
         await autosaveOpts.onLoad(saved);
       }
     } catch (e) {
-      log.warn("bootstrapGame", `Autosave load failed: ${e}`);
+      log.warn("bootstrap-game", `Autosave load failed: ${e}`);
     }
+    // A restart landing during the load await must not leave this dead
+    // generation's save interval registered into the NEXT live session.
+    if (bootAborted()) return;
 
     let saveInProgress = false;
-    setInterval(async () => {
+    const id = setInterval(async () => {
       if (saveInProgress) return;
       saveInProgress = true;
       try {
         await autosaveOpts.save();
       } catch (e) {
-        log.warn("bootstrapGame", `Autosave save failed: ${e}`);
+        log.warn("bootstrap-game", `Autosave save failed: ${e}`);
       } finally {
         saveInProgress = false;
       }
     }, intervalMs);
+    (id as any)?.unref?.();
   }
+  if (bootAborted()) return;
 
   // 10. MCP setup (if provided)
   if (opts.mcp) {
-    await opts.mcp();
+    await importOrDead(Promise.resolve(opts.mcp()), bootSession);
   }
 
   // 11. Hot-reload dispose (if provided)
   if (opts.onHotReloadDispose) {
-    const { dispose } = await import("./hooks");
-    dispose(opts.onHotReloadDispose);
+    const hooksMod = await importOrDead(hooksP, bootSession);
+    if (!hooksMod) return;
+    hooksMod.dispose(opts.onHotReloadDispose);
   }
 
   // 12. Deterministic callbacks (if onDeterministic provided)
@@ -269,3 +496,52 @@ export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
     opts.onDeterministic(renderer);
   }
 }
+
+/**
+ * Shared wiring for a live devtools frontend (Blitz dock or web host):
+ * engine-generic providers + thread evals derived from the devtools
+ * workerHosts entries ({prefix, proxy} — proxies exposing __devtoolsEval
+ * get a REPL target under their prefix name).
+ */
+async function wireDevtoolsFrontend(
+  mirror: { registerProvider?: any; registerCommandHandler?: any },
+  host: { registerThreadEval: (n: string, fn: (e: string) => Promise<{ result?: unknown; error?: string }>) => void },
+  renderer: any,
+  workerHosts: any[] | undefined,
+  profilingSAB: SharedArrayBuffer | null,
+  inputInfo?: () => { key: string; value: string; flags?: number }[],
+  bootSession?: any,
+): Promise<void> {
+  const mod = await importOrDead(devtoolsLibP ?? import("@downdraft/engine/libraries/devtools"), bootSession);
+  // If the dev session died while the import was in flight, abandon the
+  // wiring — registering providers now would root the dead generation's
+  // context through persistent host closures.
+  if (!mod) return;
+  const { registerEngineProviders } = mod;
+  // Main-thread REPL evaluates directly in this context — Bun's inspector
+  // doesn't implement Runtime.evaluate, and a direct eval works on every
+  // runtime. Registered evals take precedence over the CDP fallback.
+  host.registerThreadEval("main", async (expr) => {
+    try {
+      return { result: (0, eval)(expr) };
+    } catch (e) {
+      return { error: e instanceof Error ? `${e.name}: ${e.message}` : String(e) };
+    }
+  });
+  const evalNames: string[] = ["main"];
+  for (const wh of workerHosts ?? []) {
+    const evalFn = wh?.proxy?.__devtoolsEval;
+    if (typeof evalFn === "function" && wh.prefix) {
+      host.registerThreadEval(wh.prefix, (expr) => evalFn.call(wh.proxy, expr));
+      evalNames.push(wh.prefix);
+    }
+  }
+  registerEngineProviders(mirror as any, {
+    renderer,
+    profilingSAB,
+    simProxy: workerHosts?.[0]?.proxy ?? undefined,
+    evalTargetNames: () => evalNames,
+    inputInfo,
+  });
+}
+

package/app/src/renderer/game-module.ts

@@ -88,6 +88,12 @@ export interface GameSimWorker {
   restoreFromState?(stateJson: string): Promise<void>;
   hotReload?(config: unknown, preserveState: boolean): Promise<void>;
   getDevToolsProxy?(): unknown;
+  /** Stop and terminate the worker. Entry points call this on window close —
+   *  an unstopped worker's loop pins the runtime and the process never exits.
+   *  Optional: bespoke workers without it leak-stop via `worker.unref()`. */
+  stop?(): Promise<void> | void;
+  /** Alias for stop() on some host implementations (BaseWorkerHost). */
+  shutdown?(): Promise<void> | void;
 }
 
 /** Optional seed passed to the sim worker factory. */
@@ -174,7 +180,7 @@ export function serializeRestorePayload(
   if (explicit) {
     const comp = components[explicit];
     if (!comp) {
-      log.warn("startGame", `Save component "${explicit}" not found; available: ${Object.keys(components).join(", ")}`);
+      log.warn("start-game", `Save component "${explicit}" not found; available: ${Object.keys(components).join(", ")}`);
       return undefined;
     }
     return JSON.stringify(comp.data);
@@ -474,6 +480,18 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
   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 as any).__ddSession;
+  const bootSession = ddTracker?.session ?? null;
+  const sessionAborted = () =>
+    (!!ddTracker && (ddTracker.session !== bootSession || !bootSession || bootSession.dead))
+    || typeof (globalThis as any).window === "undefined";
+
   // 0. Resolve the render surface (NativeSurface on the native runtime)
   const surface = getSurface(module.canvasLayer ?? 0);
 
@@ -515,7 +533,7 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
   //    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 as any) : null;
+  const simWorker = hasSim ? module.sim!(simSeed) : null;
   const simSAB = simWorker?.getSimBuffer();
   const inputSAB = simWorker?.getInputBuffer();
   const extraBuffers = simWorker?.getExtraBuffers?.() ?? {};
@@ -542,6 +560,9 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
   // 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;
@@ -578,10 +599,10 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
         try {
           handler(msg.data, ctx);
         } catch (err) {
-          log.error("startGame", `Event handler error for "${msg.kind}": ${err}`);
+          log.error("start-game", `Event handler error for "${msg.kind}": ${err}`);
         }
       } else if (isDev && !ENGINE_EMITTED_EVENT_KINDS.has(msg.kind)) {
-        log.warn("startGame", `Unhandled sim event kind: "${msg.kind}"`);
+        log.warn("start-game", `Unhandled sim event kind: "${msg.kind}"`);
       }
     });
   };
@@ -590,6 +611,7 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
   // 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
@@ -623,9 +645,10 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
           : resolvedMode === "worker" ? "worker" : "host";
       }
     } catch (e) {
-      log.warn("startGame", `Save store init failed, falling back to host bridge: ${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
@@ -667,7 +690,7 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
         }
         return result?.success ?? false;
       } catch (e) {
-        log.error("startGame", `Manual save failed: ${e}`);
+        log.error("start-game", `Manual save failed: ${e}`);
         return false;
       }
     };
@@ -737,12 +760,27 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
         }
         return null;
       } catch (e) {
-        log.error("startGame", `Manual load failed: ${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: Promise<void> | null = 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,
@@ -764,6 +802,9 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
         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: any, value: unknown) => {
           if (moduleHost) moduleHost.provideExternal("library", token, value);
         };
@@ -779,7 +820,7 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
         // GPU-pass library init (after device is ready).
         if (device && format) {
           libHost.initRenderer({ device, format, provide: libProvide, inject: libInject, injectOptional: libInjectOptional });
-          libHost.setRendererBuffers(libBuffers);
+          libHost.setRendererBuffers(libBuffers, { provide: libProvide });
         }
       }
 
@@ -804,8 +845,9 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
             wireSimEvents(owned);
           }
         } catch (e) {
-          log.warn("startGame", `simFromRenderer resolution failed: ${e}`);
+          log.warn("start-game", `simFromRenderer resolution failed: ${e}`);
         }
+        if (sessionAborted()) return;
       }
 
       // ── Sim worker start ──
@@ -817,9 +859,12 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
       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) ──
@@ -833,9 +878,10 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
             maxGenerations: module.save.maxGenerations ?? 3,
           });
         } catch (e) {
-          log.warn("startGame", `Inline save store init failed, falling back to host save store: ${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 ──
@@ -854,8 +900,9 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
           if (mh) pluginHost.setModuleHost(mh);
           await pluginHost.loadAll();
         } catch (e) {
-          log.warn("startGame", `Plugin loading error: ${e}`);
+          log.warn("start-game", `Plugin loading error: ${e}`);
         }
+        if (sessionAborted()) return;
       }
 
       // ── Declarative UI lifecycle ──
@@ -867,9 +914,10 @@ export async function startGame<Sim extends GameSimWorker, R extends GameRendere
           await ctx.ui.start();
         } catch (e) {
           // UI failure is non-fatal — the game canvas still runs.
-          log.error("startGame", `UI start failed: ${e}`);
+          log.error("start-game", `UI start failed: ${e}`);
           ctx.ui = undefined;
         }
+        if (sessionAborted()) return;
       }
 
       // ── Game-specific wiring ──