@downdraft/engine 0.1.1 → 0.2.0

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

@@ -92,19 +92,19 @@ export function installSimHotReload(deps: SimHotReloadDeps): void {
     const store = useHotReloadStore.getState();
     if (!store.enabled) return;
     hot.send("sim:hot-reload:ack", {});
-    log.info("HMR", `Sim file changed: ${data.file}`);
+    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)`);
+      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}`);
+      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");
+      log.warn("hmr", "Falling back to full reload");
       if (!bridge().requestRestart?.("sim hot-reload failed")) {
         window.location.reload();
       }
@@ -115,7 +115,7 @@ export function installSimHotReload(deps: SimHotReloadDeps): void {
     const store = useHotReloadStore.getState();
     if (!store.enabled) return;
     hot.send("renderer:hot-reload:ack", {});
-    log.info("HMR", `Renderer file changed: ${data.file}`);
+    log.info("hmr", `Renderer file changed: ${data.file}`);
     store.setStatus("reloading");
     if (store.preserveState) {
       try {
@@ -128,10 +128,10 @@ export function installSimHotReload(deps: SimHotReloadDeps): void {
           }
           dd.saveGameState(SLOT, JSON.stringify(components));
           sessionStorage.setItem(PENDING_KEY, "1");
-          log.info("HMR", "State saved, reloading page...");
+          log.info("hmr", "State saved, reloading page...");
         }
       } catch (err) {
-        log.warn("HMR", `State save failed, reloading without preservation: ${err}`);
+        log.warn("hmr", `State save failed, reloading without preservation: ${err}`);
       }
     }
     if (!bridge().requestRestart?.("renderer hot-reload")) {
@@ -168,11 +168,11 @@ export async function restoreHotReloadState(
         deps.renderer?.restoreRendererMeta?.(components.renderer.data);
       }
     } catch { /* ignore */ }
-    log.info("HMR", "Restored state after page reload");
+    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.`);
+    log.error("hmr", `Failed to restore hot-reload state: ${err}. Starting fresh.`);
     return false;
   }
 }

package/app/src/renderer/mcp-harness.ts

@@ -107,12 +107,12 @@ export function createMcpHarness(opts: McpHarnessOptions): void {
   };
 
   if (!downdraft?.isAvailable || typeof downdraft.onMcpRequest !== "function") {
-    log.warn("MCP", "Host bridge or onMcpRequest not available; automation harness disabled");
+    log.warn("mcp", "Host bridge or onMcpRequest not available; automation harness disabled");
     return;
   }
 
   downdraft.onMcpRequest(async (request) => handleRequest(request as McpRequest));
-  log.info("MCP", `${serverName} registered; tools: ${tools.map((t) => t.def.name).join(", ")}`);
+  log.info("mcp", `${serverName} registered; tools: ${tools.map((t) => t.def.name).join(", ")}`);
 }
 
 // ── Shared MCP tool helpers ──────────────────────────────────────────────────

package/app/src/renderer/standard-automation-tools.ts

@@ -27,6 +27,7 @@
 // ============================================================================
 
 import { getHostCapabilities, KEY, type RenderSurface } from "@downdraft/engine";
+import type { InspectableRegistry } from "@downdraft/engine/libraries/inspectable";
 import { createLogger } from "@downdraft/engine/util/logger";
 import { downdraft } from "./index";
 import {
@@ -71,7 +72,10 @@ export type StandardToolName =
   | "get_ui_state"
   | "get_element_bounds"
   | "inspect_dom"
-  | "get_element_style";
+  | "get_element_style"
+  | "inspectable_list"
+  | "inspectable_get"
+  | "inspectable_set";
 
 // dispatch_click: real pointer input produces a pointer* event before its
 // compat mouse* event (pointerdown→mousedown, pointermove→mousemove,
@@ -148,6 +152,14 @@ export interface StandardAutomationContext {
   getWorldState?: () => unknown | Promise<unknown>;
   getUiState?: () => unknown;
 
+  /**
+   * InspectableRegistry for the inspectable_list/get/set tools — schema'd
+   * read/write nodes over game state (player customization, settings, …) so
+   * agents mutate semantics directly instead of synthesizing input. Nodes'
+   * set() callbacks route through the game's normal apply pipeline.
+   */
+  inspectables?: InspectableRegistry;
+
   /**
    * Extra variables exposed to wait_for_condition expressions, keyed by name.
    * E.g. `{ ui: () => store.getState() }` exposes `ui` in the predicate.
@@ -262,7 +274,7 @@ export function createStandardAutomationTools(ctx: StandardAutomationContext): M
                 };
               }
             } catch (e) {
-              log.warn("MCP", `Host frame capture failed, falling back to canvas-only: ${(e as Error).message}`);
+              log.warn("mcp", `Host frame capture failed, falling back to canvas-only: ${(e as Error).message}`);
             }
           }
         }
@@ -727,6 +739,95 @@ export function createStandardAutomationTools(ctx: StandardAutomationContext): M
     });
   }
 
+  // ── inspectable_list / inspectable_get / inspectable_set ──
+  const inspectables = ctx.inspectables;
+  if (want("inspectable_list") && inspectables) {
+    tools.push({
+      def: {
+        name: "inspectable_list",
+        description:
+          "List the game's inspectable state nodes — schema'd read/write points over game state " +
+          "(player customization, settings, etc.). Returns each node's path, type, valid " +
+          "range/options, readOnly flag, and current value. Mutate them with inspectable_set " +
+          "instead of synthesizing input — writes run through the game's normal apply pipeline.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            prefix: { type: "string", description: "Limit to nodes under this path prefix (e.g. 'player.customization')" },
+            tree: { type: "boolean", default: false, description: "Also return a nested tree keyed by path segments" },
+          },
+        },
+      },
+      handler: (params: Record<string, unknown>) => {
+        const prefix = params.prefix as string | undefined;
+        const nodes = inspectables.list(prefix).map((info) => {
+          let value: unknown, error: string | undefined;
+          try {
+            value = inspectables.get(info.path).value;
+          } catch (e) {
+            error = (e as Error).message;
+          }
+          return { ...info, value, error };
+        });
+        return jsonResult({
+          nodes,
+          ...(params.tree ? { tree: inspectables.tree(prefix) } : {}),
+        });
+      },
+    });
+  }
+  if (want("inspectable_get") && inspectables) {
+    tools.push({
+      def: {
+        name: "inspectable_get",
+        description: "Read the current value and schema of a single inspectable node. Discover paths with inspectable_list.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Node path (e.g. 'player.customization.girth')" },
+          },
+          required: ["path"],
+        },
+      },
+      handler: (params: Record<string, unknown>) => {
+        const path = params.path as string;
+        try {
+          return jsonResult({ ...inspectables.describe(path), ...inspectables.get(path) });
+        } catch (e) {
+          return errorResult((e as Error).message);
+        }
+      },
+    });
+  }
+  if (want("inspectable_set") && inspectables) {
+    tools.push({
+      def: {
+        name: "inspectable_set",
+        description:
+          "Write a value to an inspectable node (see inspectable_list for paths, types, and valid " +
+          "options/ranges). The write is validated then routed through the game's apply function — " +
+          "engine side-effects (mesh re-resolution, sim dispatch, saves) happen as if the game's " +
+          "own UI had made the change. Returns the post-write value.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Node path (e.g. 'player.customization.girth')" },
+            value: { description: "JSON value matching the node's declared type" },
+          },
+          required: ["path", "value"],
+        },
+      },
+      handler: async (params: Record<string, unknown>) => {
+        try {
+          const res = await inspectables.set(params.path as string, params.value);
+          return jsonResult({ applied: true, ...res });
+        } catch (e) {
+          return errorResult((e as Error).message);
+        }
+      },
+    });
+  }
+
   return [...tools, ...(ctx.extraTools ?? [])];
 }
 
@@ -766,6 +867,6 @@ export function createGameMcp(opts: GameMcpOptions): void {
       }),
     });
   } catch (e) {
-    log.warn("MCP", `${appId} automation harness setup failed (non-fatal): ${e}`);
+    log.warn("mcp", `${appId} automation harness setup failed (non-fatal): ${e}`);
   }
 }

package/app/src/shared/feature-log.ts

@@ -8,7 +8,8 @@
 // line carries GPU identity.
 // ============================================================================
 
-import { ENGINE_VERSION, condenseText, formatBytesShort, type FeatureLogData } from "@downdraft/engine";
+import { condenseText, formatBytesShort, type FeatureLogData } from "@downdraft/engine/util/feature-log";
+import { ENGINE_VERSION } from "@downdraft/engine/version";
 import os from "node:os";
 
 export interface CollectHostFeatureLogOptions {

package/app/src/shared/mcp-discovery.ts

@@ -28,17 +28,22 @@ export function mcpPortDir(): string {
  * `Authorization: Bearer <token>` or `X-Downdraft-Token` header. The port
  * file format stays a bare number for backward compatibility with existing
  * bridges. Returns a cleanup function that removes both files (best-effort).
+ *
+ * `suffix` distinguishes a second endpoint in the same process:
+ * `writeMcpPidFile(port, token, ".editor")` writes `<pid>.editor` +
+ * `<pid>.editor.token` (the createMcpModule editor toolset endpoint), leaving
+ * the automation endpoint's `<pid>` file untouched.
  */
-export function writeMcpPidFile(port: number, token: string): () => void {
+export function writeMcpPidFile(port: number, token: string, suffix: string = ""): () => void {
   const dir = mcpPortDir();
-  const pidFile = join(dir, String(process.pid));
+  const pidFile = join(dir, `${process.pid}${suffix}`);
   const tokenFile = `${pidFile}.token`;
   try {
     mkdirSync(dir, { recursive: true });
     writeFileSync(pidFile, String(port));
     writeFileSync(tokenFile, token, { mode: 0o600 });
   } catch (e) {
-    log.warn("MCP", `Failed to write PID file ${pidFile}: ${(e as Error).message}`);
+    log.warn("mcp", `Failed to write PID file ${pidFile}: ${(e as Error).message}`);
   }
   return () => {
     try { unlinkSync(pidFile); } catch { /* already gone */ }

package/app/src/shared/mcp-proxy.ts

@@ -54,12 +54,12 @@ export function createMcpProxyHandler(
         const rendererResult = await forwardToRenderer({ method, params });
         const r = rendererResult as { tools?: unknown[]; error?: unknown };
         if ("error" in r && r.error) {
-          log.warn("MCP", `tools/list renderer error: ${JSON.stringify(r.error)} (returning host tools only)`);
+          log.warn("mcp", `tools/list renderer error: ${JSON.stringify(r.error)} (returning host tools only)`);
         } else {
           rendererTools = (r as { tools?: unknown[] }).tools ?? [];
         }
       } catch (e) {
-        log.warn("MCP", `tools/list renderer unavailable: ${(e as Error).message} (returning host tools only)`);
+        log.warn("mcp", `tools/list renderer unavailable: ${(e as Error).message} (returning host tools only)`);
       }
       const hostDefs = hostTools.map((t) => ({
         name: t.def.name,

package/asset-bake/README.md

@@ -0,0 +1,22 @@
+# `@downdraft/engine/asset-bake`
+
+Offline asset baking pipeline — converts and optimizes meshes, textures, and shaders into engine-ready formats at build time.
+
+## Install
+
+```sh
+bun add @downdraft/engine/asset-bake
+```
+
+## Key exports
+
+- `BAKE_CONFIG_VERSION`
+- `BakeCache`
+- `DEFAULT_BAKE_OPTIONS`
+- `bakeAsset`
+- `bakeAssetFromBytes`
+- `bakeAudio`
+- `bakeGltf`
+- `resolveOptions`
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/core/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine`
+
+Downdraft engine core — ECS, WebGPU renderer, module/DI system, SharedArrayBuffer sim channels, sim worker host, plugin API, animation, and particles.
+
+## Install
+
+```sh
+bun add @downdraft/engine
+```
+
+## Key exports
+
+- `AudioEngine`
+- `AudioListener`
+- `AudioMixer`
+- `AudioSABChannel`
+- `AudioSABChannelDef`
+- `AudioSource`
+- `BSPNode`
+- `BaseWorkerHost`
+- `BoneTransforms`
+- `BufferSyncHost`
+- …and 210 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/core/src/animation/skeleton-animator.ts

@@ -379,7 +379,7 @@ export class SkeletonAnimator {
     this.targetZUp = skin.skeletonUpAxis !== "y";
     this.isMixamoSkeleton = this.boneNameToIndex.has("mixamorig:Hips");
     if (this.isMixamoSkeleton) {
-      log.info("Anim", "Mixamo skeleton detected — direct animation mapping (no retargeting)");
+      log.info("anim", "Mixamo skeleton detected — direct animation mapping (no retargeting)");
     }
   }
 
@@ -1138,22 +1138,40 @@ export class SkeletonAnimator {
     const clip = this.animationDataToClip(mergedAnim, stateName);
     if (clip) {
       this.clips.set(stateName, clip);
-      log.info("Anim", `Registered: ${stateName} (${allChannels.length} channels, ${this.isMixamoSkeleton ? "direct Mixamo" : "retargeted-v2"})`);
+      log.info("anim", `Registered: ${stateName} (${allChannels.length} channels, ${this.isMixamoSkeleton ? "direct Mixamo" : "retargeted-v2"})`);
     }
   }
 
-  protected setAnimationState(state: AnimState): void {
+  /**
+   * Minimum time between state changes. Callers re-request their desired
+   * state every frame, so a blocked request lands as soon as the interval
+   * passes — this only debounces frame-to-frame churn (e.g. a flag toggling
+   * at a boundary), which would otherwise restart the crossfade each frame
+   * and freeze the pose mid-blend. (Was a 0.5s gate, which deferred every
+   * legitimate transition — entering water, landing — by up to half a
+   * second.)
+   */
+  private static readonly MIN_STATE_INTERVAL = 0.1;
+
+  protected setAnimationState(state: AnimState, fadeDuration?: number): void {
     if (state === this.currentState && this.player.isPlaying(state)) return;
-    if (this.timeSinceLastStateChange < 0.5 && this.player.isPlaying()) return;
     const clip = this.clips.get(state);
     if (!clip) return;
+    if (this.timeSinceLastStateChange < SkeletonAnimator.MIN_STATE_INTERVAL && this.player.isPlaying()) return;
 
     // Use AnimationPlayer's fade for crossfade blending
-    this.player.play(state, clip, { fadeDuration: this.blendDuration });
+    this.player.play(state, clip, { fadeDuration: fadeDuration ?? this.blendDuration });
     this.currentState = state;
     this.timeSinceLastStateChange = 0;
   }
 
+  /** Scale the playback speed of a currently-playing state's layer (e.g.
+   *  faster swim strokes at higher swim velocity). No-op if the state's
+   *  clip isn't active. */
+  setStateSpeed(state: AnimState, speed: number): void {
+    this.player.setSpeed(state, speed);
+  }
+
   setFootTargets(left: Float32Array | null, right: Float32Array | null): void {
     this.leftFootTarget = left;
     this.rightFootTarget = right;

package/core/src/assets/manager.ts

@@ -274,7 +274,7 @@ export class AssetManager {
             this.pendingRejectors.delete(uri);
             this.pendingResolvers.delete(uri);
           }
-          log.warn("AssetManager", budgetError.message);
+          log.warn("asset-manager", budgetError.message);
           return;
         }
 
@@ -307,7 +307,7 @@ export class AssetManager {
           this.pendingRejectors.delete(uri);
           this.pendingResolvers.delete(uri);
         }
-        log.error("AssetManager", `Failed to load ${uri}: ${error.message}`);
+        log.error("asset-manager", `Failed to load ${uri}: ${error.message}`);
       } finally {
         this.loading.delete(uri);
       }
@@ -365,11 +365,11 @@ export class AssetManager {
         const result = destructor(ref.data);
         if (result instanceof Promise) {
           result.catch((e) =>
-            log.error("AssetManager", `Destructor error for ${key}: ${e}`),
+            log.error("asset-manager", `Destructor error for ${key}: ${e}`),
           );
         }
       } catch (e) {
-        log.error("AssetManager", `Destructor error for ${key}: ${e}`);
+        log.error("asset-manager", `Destructor error for ${key}: ${e}`);
       }
     }
     this.assets.delete(key);

package/core/src/ecs/events.ts

@@ -25,7 +25,7 @@ export function createEventChannel<T>(): EventChannel<T> {
         droppedCount++;
         if (droppedCount === 1 || droppedCount % 1000 === 0) {
           log.warn(
-            "EventChannel",
+            "event-channel",
             `queue full (${MAX_QUEUE_SIZE}), dropped ${droppedCount} oldest event(s) total`,
           );
         }

package/core/src/ecs/schedule.ts

@@ -145,7 +145,7 @@ export class Schedule {
     const visit = (name: string, path: Set<string>) => {
       if (visited.has(name)) return;
       if (path.has(name)) {
-        log.warn("Schedule", `System dependency cycle detected involving "${name}" — skipping`);
+        log.warn("schedule", `System dependency cycle detected involving "${name}" — skipping`);
         return;
       }
       const entry = nameToSys.get(name);

package/core/src/ecs/world.ts

@@ -220,7 +220,7 @@ export class World {
       try {
         this.commands[i](this);
       } catch (err) {
-        log.error("World", `Command at index ${i} threw: ${err}`);
+        log.error("world", `Command at index ${i} threw: ${err}`);
         // In debug mode, re-throw to surface command errors immediately.
         // In production, log and continue for game-loop resilience.
         if (isDebug()) throw err;

package/core/src/index.ts

@@ -7,8 +7,6 @@
 
 /// <reference path="./webgpu-destroy-augmentation.d.ts" />
 
-import pkg from "../../package.json" with { type: "json" };
-
 // Sub-barrel re-exports — these aggregate all items from their respective domains.
 export * from "./assets";
 export * from "./ecs";
@@ -26,8 +24,9 @@ export * from "./util";
 // Used by the feature log, save headers (via features.saves.engineVersion
 // default), and any code that needs to report the running engine version.
 // Sourced from package.json so it can never drift from the published version.
+// Defined in ./version.ts so leaf-import consumers skip this barrel.
 // ─────────────────────────────────────────────────────────────────────────────
-export const ENGINE_VERSION: string = pkg.version;
+export { ENGINE_VERSION } from "./version";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Worker (task-worker lives outside ecs/)
@@ -135,7 +134,7 @@ export {
     isDevMode,
     NATIVE_HOST_CAPABILITIES
 } from "./platform/runtime";
-export type { HostCapabilities, HostRuntime, NativeHostHandle } from "./platform/runtime";
+export type { GpuPassMailboxLike, GpuShareBrokerLike, HostCapabilities, HostRuntime, NativeHostHandle } from "./platform/runtime";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Mesh

package/core/src/input/local-player-manager.ts

@@ -140,11 +140,11 @@ export class LocalPlayerManager {
   }
 
   private emitConnect(device: InputDevice): void {
-    for (const cb of this.connectCallbacks) cb(device);
+    for (const cb of this.connectCallbacks.values()) cb(device);
   }
 
   private emitDisconnect(device: InputDevice): void {
-    for (const cb of this.disconnectCallbacks) cb(device);
+    for (const cb of this.disconnectCallbacks.values()) cb(device);
   }
 
   startListening(): void {

package/core/src/library/host.ts

@@ -11,7 +11,7 @@
 // ============================================================================
 
 import type { ResourceToken } from "../ecs/resource";
-import { assertNoDuplicate, assertRequired, isStrict, warnLeak } from "../module/diagnostics";
+import { assertNoDuplicate, isStrict, warnLeak } from "../module/diagnostics";
 import { createLogger } from "../util/logger";
 import type {
     EngineLibrary,
@@ -82,7 +82,7 @@ export class LibraryHostImpl implements LibraryHost {
         if (this.buffers[ch.name]) {
           const msg = `SAB channel "${ch.name}" declared by library "${active.lib.name}" is already allocated — duplicate channel names across libraries are not allowed`;
           if (isStrict()) throw new Error(msg);
-          log.warn("LibraryHost", msg);
+          log.warn("library-host", msg);
           continue;
         }
         this.buffers[ch.name] = new SharedArrayBuffer(ch.size);
@@ -111,14 +111,21 @@ export class LibraryHostImpl implements LibraryHost {
         allProviders.set(token.key, active.lib.name);
       });
     });
-    for (let _i = 0, _it = this.libraries, _n = _it.length; _i < _n; _i++) { const active = _it[_i];
-      if (!active.lib.requires) continue;
+    // Missing `requires` only warns: the library DI graph is OPEN — tokens can
+    // be satisfied by game modules or other external providers the host can't
+    // enumerate (unlike ModuleHost's closed module graph, which hard-fails).
+    // A truly missing provider still throws at `inject()` call time.
+    this.libraries.forEach((active) => {
+      if (!active.lib.requires) return;
       active.lib.requires.forEach((token) => {
-        if (!allProviders.has(token.key)) {
-          assertRequired(allProviders, token, active.lib.name);
+        if (!allProviders.has(token.key) && !this.providers.has(token.key)) {
+          log.warn(
+            "library-host",
+            `Library "${active.lib.name}" requires "${token.key}" which no library provides — it must be provided by a game module or external provider, or inject() will throw.`,
+          );
         }
       });
-    }
+    });
   }
 
   initSim(ctx: LibrarySimContext): void {
@@ -147,7 +154,7 @@ export class LibraryHostImpl implements LibraryHost {
         active.simSystem = null;
         (created as Promise<unknown>).then(
           (resolved) => { active.simSystem = resolved; },
-          (err) => { log.error("LibraryHost", `async sim.create for "${active.lib.name}" failed: ${err}`); },
+          (err) => { log.error("library-host", `async sim.create for "${active.lib.name}" failed: ${err}`); },
         );
       } else {
         active.simSystem = created;
@@ -243,19 +250,26 @@ export class LibraryHostImpl implements LibraryHost {
     }
   }
 
-  setRendererBuffers(buffers: Record<string, SharedArrayBuffer>): void {
-    for (let _i = 0, _it = this.libraries, _n = _it.length; _i < _n; _i++) { const active = _it[_i];
-      if (!active.lib.renderer?.setBuffers || active.rendererInstance === null) continue;
+  setRendererBuffers(
+    buffers: Record<string, SharedArrayBuffer>,
+    ctx?: { provide<T>(token: ResourceToken<T>, value: T): void },
+  ): void {
+    this.libraries.forEach((active) => {
+      if (!active.lib.renderer?.setBuffers) return;
+      // rendererInstance may be null — libraries whose `init` returned null
+      // (non-GPU participants, e.g. water's buffer reader) still get their
+      // SABs and can provide resources into the DI graph.
       active.lib.renderer.setBuffers(active.rendererInstance, buffers, {
-        provide: (token: ResourceToken<unknown>, _value: unknown) => {
+        provide: (token: ResourceToken<unknown>, value: unknown) => {
           if (isStrict()) {
             assertNoDuplicate(this.providers, token, active.lib.name);
           }
           this.providers.set(token.key, active.lib.name);
           active.rendererProvidedKeys.add(token.key);
+          ctx?.provide(token, value);
         },
       });
-    }
+    });
   }
 
   drawRenderer(ctx: LibraryRendererDrawContext): void {

package/core/src/library/library.ts

@@ -126,7 +126,9 @@ export interface LibraryRendererSetup<C = unknown, R = unknown> {
   init?(config: C, ctx: LibraryRendererInitContext): R | null | undefined;
   /**
    * Called when SABs are set on the renderer (`setBuffers()`).
-   * Receives the renderer instance from `init()` + the SABs.
+   * Receives the renderer instance from `init()`/`create()` + the SABs —
+   * the instance may be null when `init()` returned null (libraries that
+   * only need the SABs still run).
    * The optional context provides `provide()` for registering resources
    * into the DI graph (e.g. a buffer reader created during setBuffers).
    */
@@ -253,8 +255,9 @@ export type LibraryEntry<C = unknown> =
 // ── LibraryHost (internal — wires libraries) ──
 
 /**
- * Internal host that manages library lifecycle. Created by `startGame()`
- * and the sim worker. Not exported — games interact with libraries via
+ * Host that manages library lifecycle. Created by `startGame()`
+ * and the sim worker; exposed on `GameContext.libraryHost` for diagnostics
+ * and advanced wiring. Games normally interact with libraries via
  * the DI graph (`ctx.inject(WaterWriterTok)` etc.).
  */
 export interface LibraryHost {
@@ -279,8 +282,13 @@ export interface LibraryHost {
   createRenderer(ctx: LibraryRendererCreateContext): void;
   /** Initialize renderer-side passes. Called during renderer init. */
   initRenderer(ctx: LibraryRendererInitContext): void;
-  /** Set buffers on renderer-side passes. Called during renderer setBuffers. */
-  setRendererBuffers(buffers: Record<string, SharedArrayBuffer>): void;
+  /**
+   * Set buffers on renderer-side passes. Called during renderer setBuffers.
+   * `ctx.provide` (when given) forwards resources into the renderer DI
+   * graph — pass it so `setBuffers` implementations that `ctx.provide(...)`
+   * (e.g. a SAB reader created at buffer-bind time) are actually injectable.
+   */
+  setRendererBuffers(buffers: Record<string, SharedArrayBuffer>, ctx?: { provide<T>(token: ResourceToken<T>, value: T): void }): void;
   /** Draw all renderer-side passes. Called per frame. */
   drawRenderer(ctx: LibraryRendererDrawContext): void;
   /** Dispose all sim-side systems. */

package/core/src/module/cross-thread.ts

@@ -32,6 +32,12 @@ export interface CrossThreadToken<T> extends ResourceToken<T> {
  * Create a cross-thread resource token. The token is a standard ResourceToken
  * (compatible with provide/inject) with an added `__thread` tag for
  * cross-thread validation and diagnostics.
+ *
+ * NOTE: experimental — no engine library or module currently creates
+ * cross-thread tokens, so the `threadMismatches`/`incompleteShared` checks in
+ * `buildCrossThreadReport` are inert. Also, `ModuleHost.snapshot()` only
+ * covers Module/RendererModule plugins — EngineLibrary descriptors are not
+ * part of the cross-thread report yet.
  */
 export function crossThreadToken<T>(key: string, thread: ThreadTag): CrossThreadToken<T> {
   const token = resourceToken<T>(key) as CrossThreadToken<T>;