@downdraft/engine 0.0.0 → 0.1.0

package/core/src/plugin/material-registry.ts

@@ -0,0 +1,65 @@
+// ============================================================================
+// MaterialRegistry — mod-defined material shaders for spawned props.
+//
+// Mods register custom WGSL material shaders via the ShaderRegistry extension
+// loader. The MaterialRegistry tracks registered materials and provides
+// lookup by id. The renderer integrates with this registry to apply custom
+// materials to spawned props.
+//
+// This is a lightweight, testable registry. The actual GPU pipeline creation
+// + bindless material integration happens in the renderer when a prop is
+// spawned with a custom material id (the renderer looks up the material in
+// this registry and compiles the WGSL on demand).
+// ============================================================================
+
+/** A registered mod-defined material shader. */
+export interface RegisteredMaterial {
+  /** Unique material id (namespaced, e.g. "my-mod:iridescent"). */
+  id: string;
+  /** WGSL material shader source. */
+  wgsl: string;
+  /** The mod that registered this material. */
+  manifestId: string;
+  /** Uniform buffer size in bytes (if the shader needs a uniform). */
+  uniforms?: number;
+  /** Extra properties from the extension declaration. */
+  props: Record<string, unknown>;
+}
+
+/** Registry for mod-defined material shaders. */
+export class MaterialRegistry {
+  private materials = new Map<string, RegisteredMaterial>();
+
+  /** Register a material shader. Throws if the id is already registered. */
+  register(material: RegisteredMaterial): void {
+    if (this.materials.has(material.id)) {
+      throw new Error(`Material "${material.id}" is already registered`);
+    }
+    this.materials.set(material.id, material);
+  }
+
+  /** Unregister a material by id. */
+  unregister(id: string): void {
+    this.materials.delete(id);
+  }
+
+  /** Get a registered material by id. Returns undefined if not found. */
+  get(id: string): RegisteredMaterial | undefined {
+    return this.materials.get(id);
+  }
+
+  /** Check if a material is registered. */
+  has(id: string): boolean {
+    return this.materials.has(id);
+  }
+
+  /** Get all registered material ids. */
+  ids(): string[] {
+    return [...this.materials.keys()];
+  }
+
+  /** Clear all registered materials. */
+  clear(): void {
+    this.materials.clear();
+  }
+}

package/core/src/plugin/mcp-tools.ts

@@ -0,0 +1,165 @@
+// ============================================================================
+// MCP automation tools for the plugin system.
+//
+// Games call `createPluginMcpTools(pluginHost)` in their MCP setup to register
+// tools that let the in-game MCP harness (and `draft test` e2e specs) inspect
+// and control plugins:
+//   - plugin_list: list all discovered plugins with status.
+//   - plugin_get_info: get detailed info for a single plugin.
+//   - plugin_reload: reload a plugin by id.
+//   - plugin_unload: unload a plugin by id.
+//   - plugin_get_state: get a plugin's KV state.
+//
+// These integrate with the existing createMcpHarness from @downdraft/engine/app/renderer.
+// ============================================================================
+
+import type { PluginHost } from "./host";
+
+/** MCP tool definition (structurally compatible with McpToolRegistration). */
+export interface McpToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface McpToolRegistration {
+  def: McpToolDef;
+  handler: (params: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+
+function jsonResult(data: unknown): { content: [{ type: "text"; text: string }] } {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+
+function errorResult(msg: string): { content: [{ type: "text"; text: string }] } {
+  return { content: [{ type: "text", text: JSON.stringify({ error: msg }) }] };
+}
+
+/**
+ * Create MCP tool registrations for plugin management.
+ * Games pass these to `createMcpHarness({ tools: [...] })`.
+ */
+export function createPluginMcpTools(pluginHost: PluginHost): McpToolRegistration[] {
+  return [
+    {
+      def: {
+        name: "plugin_list",
+        description:
+          "List all discovered plugins with their current status, format, tier, and thread. " +
+          "Useful for verifying plugins loaded correctly in e2e tests.",
+        inputSchema: { type: "object", properties: {} },
+      },
+      handler: async () => {
+        const snap = pluginHost.snapshot();
+        return jsonResult({
+          count: snap.length,
+          plugins: snap.map((p) => ({
+            id: p.id,
+            name: p.name,
+            version: p.version,
+            format: p.format,
+            tier: p.tier,
+            thread: p.thread,
+            status: p.status,
+            error: p.error,
+            permissions: p.permissions,
+          })),
+        });
+      },
+    },
+    {
+      def: {
+        name: "plugin_get_info",
+        description:
+          "Get detailed info for a single plugin by id, including denied permissions and source.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Plugin id" },
+          },
+          required: ["id"],
+        },
+      },
+      handler: async (params) => {
+        const id = params.id as string;
+        const snap = pluginHost.snapshot();
+        const info = snap.find((p) => p.id === id);
+        if (!info) return errorResult(`Plugin "${id}" not found`);
+        return jsonResult(info);
+      },
+    },
+    {
+      def: {
+        name: "plugin_reload",
+        description:
+          "Reload a plugin by id. The plugin is unloaded and re-loaded from its source. " +
+          "Useful for testing plugin lifecycle in e2e specs.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Plugin id" },
+          },
+          required: ["id"],
+        },
+      },
+      handler: async (params) => {
+        const id = params.id as string;
+        try {
+          await pluginHost.reload(id);
+          const snap = pluginHost.snapshot();
+          const info = snap.find((p) => p.id === id);
+          return jsonResult({ success: true, status: info?.status, error: info?.error });
+        } catch (e) {
+          return errorResult(`Failed to reload plugin "${id}": ${(e as Error).message}`);
+        }
+      },
+    },
+    {
+      def: {
+        name: "plugin_unload",
+        description:
+          "Unload a plugin by id. The plugin is disposed and removed from the active set.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Plugin id" },
+          },
+          required: ["id"],
+        },
+      },
+      handler: async (params) => {
+        const id = params.id as string;
+        try {
+          pluginHost.unload(id);
+          return jsonResult({ success: true });
+        } catch (e) {
+          return errorResult(`Failed to unload plugin "${id}": ${(e as Error).message}`);
+        }
+      },
+    },
+    {
+      def: {
+        name: "plugin_get_state",
+        description:
+          "Get a plugin's KV state keys. Returns the list of state keys for the plugin.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Plugin id" },
+          },
+          required: ["id"],
+        },
+      },
+      handler: async (params) => {
+        const id = params.id as string;
+        const snap = pluginHost.snapshot();
+        const info = snap.find((p) => p.id === id);
+        if (!info) return errorResult(`Plugin "${id}" not found`);
+        // The PluginHost doesn't expose the per-plugin state store directly,
+        // but the snapshot includes the manifest. For full state access, the
+        // game would need to expose the context backing. This is a stub.
+        return jsonResult({ id, stateKeys: [], note: "State access requires game-side wiring" });
+      },
+    },
+  ];
+}

package/core/src/plugin/permissions.ts

@@ -0,0 +1,175 @@
+// ============================================================================
+// Plugin permissions — the sandbox permission model.
+//
+// Each `PluginPermission` maps to a set of Web Worker globals the sandbox
+// shim keeps (vs. strips) before the plugin's code runs. The host resolves
+// the *granted* permission set = (requested ∩ tier-allowed ∩ game-allowlist),
+// then hands it to the sandbox shim which deletes/overrides disallowed
+// globals.
+//
+// This module is the single source of truth for:
+//   - the per-tier allowed permission sets (mirrored in manifest.ts)
+//   - the permission → global-allowlist mapping
+//   - permission resolution + grant computation
+// ============================================================================
+
+import type { PluginPermission, PluginTier } from "./manifest";
+
+// ── Per-tier allowed permissions (mirror of manifest.ts rules) ──
+
+export const TIER_ALLOWED: Record<PluginTier, ReadonlySet<PluginPermission>> = {
+  data: new Set<PluginPermission>([]),
+  script: new Set<PluginPermission>(["events", "state", "tick", "storage", "log"]),
+  native: new Set<PluginPermission>([
+    "ecs",
+    "sab",
+    "gpu",
+    "events",
+    "state",
+    "tick",
+    "storage",
+    "network",
+    "log",
+    "physics",
+    "assets",
+  ]),
+};
+
+// ── Permission → worker-global allowlist ──
+//
+// The sandbox shim deletes every global NOT in the granted allowlist. The
+// allowlist is the union of (a) a baseline set always kept (needed for the
+// plugin runtime itself) and (b) per-permission additions.
+//
+// Baseline: the JS runtime essentials + the host-provided `ddPlugin` bridge.
+// These are NEVER stripped — without them the plugin can't run at all.
+
+export const BASELINE_GLOBALS: readonly string[] = [
+  // JS runtime
+  "Object",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "BigInt",
+  "Symbol",
+  "Math",
+  "JSON",
+  "Date",
+  "Error",
+  "TypeError",
+  "RangeError",
+  "SyntaxError",
+  "ReferenceError",
+  "EvalError",
+  "URIError",
+  "Promise",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "ArrayBuffer",
+  "SharedArrayBuffer",
+  "Int8Array",
+  "Uint8Array",
+  "Uint8ClampedArray",
+  "Int16Array",
+  "Uint16Array",
+  "Int32Array",
+  "Uint32Array",
+  "Float32Array",
+  "Float64Array",
+  "BigInt64Array",
+  "BigUint64Array",
+  "DataView",
+  "TextEncoder",
+  "TextDecoder",
+  "console",
+  "setTimeout",
+  "clearTimeout",
+  "setInterval",
+  "clearInterval",
+  "queueMicrotask",
+  "atob",
+  "btoa",
+  "structuredClone",
+  "performance",
+  "self",
+  "globalThis",
+  // Host bridge (injected by the sandbox shim)
+  "ddPlugin",
+];
+
+/** Globals kept when a given permission is granted. */
+export const PERMISSION_GLOBALS: Record<PluginPermission, readonly string[]> = {
+  network: ["fetch", "WebSocket", "XMLHttpRequest", "EventSource", "Request", "Response", "Headers", "URL", "URLSearchParams"],
+  storage: ["indexedDB", "caches"],
+  // ecs/sab/gpu/events/state/tick/log don't add raw globals — they're
+  // mediated through the `ddPlugin` host bridge (typed APIs on the context).
+  // Listing them empty keeps the mapping explicit and extensible.
+  ecs: [],
+  sab: [],
+  gpu: [],
+  events: [],
+  state: [],
+  tick: [],
+  log: [],
+  physics: [],
+  assets: [],
+};
+
+// ── Permission resolution ──
+
+export interface PermissionGrant {
+  /** The final granted permission set (requested ∩ tier ∩ game-allowlist). */
+  granted: ReadonlySet<PluginPermission>;
+  /** Permissions requested but denied (with reason). */
+  denied: Array<{ permission: PluginPermission; reason: string }>;
+}
+
+/**
+ * Resolve the granted permission set for a plugin.
+ *
+ * @param requested  Permissions requested in the manifest.
+ * @param tier       The plugin's tier.
+ * @param gameAllow  Optional game-defined allowlist. If provided, only
+ *                   permissions in this set can be granted (game can forbid
+ *                   e.g. `network` even for native-tier plugins). If omitted,
+ *                   the tier set is the only constraint.
+ */
+export function resolvePermissions(
+  requested: PluginPermission[],
+  tier: PluginTier,
+  gameAllow?: ReadonlySet<PluginPermission>,
+): PermissionGrant {
+  const tierSet = TIER_ALLOWED[tier];
+  const granted = new Set<PluginPermission>();
+  const denied: Array<{ permission: PluginPermission; reason: string }> = [];
+
+  for (let _i = 0, _it = requested, _n = _it.length; _i < _n; _i++) { const p = _it[_i];
+    if (!tierSet.has(p)) {
+      denied.push({ permission: p, reason: `not allowed for tier "${tier}"` });
+      continue;
+    }
+    if (gameAllow && !gameAllow.has(p)) {
+      denied.push({ permission: p, reason: "denied by game allowlist" });
+      continue;
+    }
+    granted.add(p);
+  }
+
+  return { granted, denied };
+}
+
+/**
+ * Compute the full set of worker-global names the sandbox shim should KEEP
+ * for a plugin with the given granted permissions. Everything else on `self`
+ * gets deleted/replaced with a throwing trap.
+ */
+export function computeGlobalAllowlist(granted: ReadonlySet<PluginPermission>): Set<string> {
+  const keep = new Set<string>(BASELINE_GLOBALS);
+  for (const p of granted.values()) {
+    PERMISSION_GLOBALS[p].forEach((g) => { keep.add(g);; });
+  }
+  return keep;
+}

package/core/src/plugin/quickjs-bridge.ts

@@ -0,0 +1,294 @@
+// ============================================================================
+// QuickJS bridge — host↔QuickJS value marshaling + interrupt/timeout.
+//
+// QuickJS plugins run in-process on the renderer thread inside a QuickJS WASM
+// VM (via quickjs-emscripten). The VM provides hard isolation by construction:
+// only the host-bridged globals exist. This module:
+//   - creates a QuickJS runtime + context,
+//   - sets an interrupt handler for per-tick instruction-budget enforcement,
+//   - bridges the ScriptPluginContext API into QuickJS functions,
+//   - marshals values between host and VM (primitives + plain objects via JSON),
+//   - evaluates the plugin entry and calls its register().
+// ============================================================================
+
+import type { QuickJSContext, QuickJSWASMModule } from "quickjs-emscripten";
+import { getQuickJS as _getQuickJS } from "quickjs-emscripten";
+import { getWarningEngine, METRIC_TASK_LATENCY, recordTaskLatency } from "../profiling/worker-prelude";
+
+/** Re-export getQuickJS so consumers don't need a direct dep on quickjs-emscripten. */
+export const getQuickJS = _getQuickJS;
+
+/** Maximum instructions per eval/tick before the interrupt handler fires. */
+const DEFAULT_INSTRUCTION_BUDGET = 1_000_000;
+
+export interface QuickjsBridgeOptions {
+  /** Instruction budget per eval/tick. Exceeding → throws a budget error. */
+  instructionBudget?: number;
+  /** The plugin id (for logging + error messages). */
+  pluginId: string;
+}
+
+export interface QuickjsBridge {
+  /** The QuickJS context. */
+  ctx: QuickJSContext;
+  /** Evaluate code in the VM. Returns the result marshaled to a host value. */
+  eval(code: string, filename?: string): unknown;
+  /** Call a global function by name with marshaled args. */
+  callGlobal(fnName: string, ...args: unknown[]): unknown;
+  /** Drain pending jobs (promises). */
+  drainJobs(): void;
+  /** Dispose the VM (runtime + context). */
+  dispose(): void;
+}
+
+/** Marshal a host value into a QuickJS handle. Caller must dispose. */
+function marshalToVm(ctx: QuickJSContext, value: unknown): any {
+  if (value === undefined || value === null) return ctx.undefined;
+  if (typeof value === "number") return ctx.newNumber(value);
+  if (typeof value === "string") return ctx.newString(value);
+  if (typeof value === "boolean") return value ? ctx.true : ctx.false;
+  // Objects + arrays → JSON round-trip (simple, safe, no live sharing).
+  if (typeof value === "object") {
+    const result = ctx.evalCode(`JSON.parse(${JSON.stringify(JSON.stringify(value))})`);
+    if (result.error) {
+      result.error.dispose();
+      return ctx.undefined;
+    }
+    // unwrapResult transfers ownership — caller must dispose.
+    return ctx.unwrapResult(result);
+  }
+  return ctx.undefined;
+}
+
+/** Marshal a QuickJS handle to a host value. Does NOT consume the handle. */
+function marshalFromVm(ctx: QuickJSContext, handle: any): unknown {
+  try {
+    return ctx.dump(handle);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Create a QuickJS bridge with a runtime + context, interrupt handler, and
+ * bridged host functions. The `hostApi` object provides the actual
+ * ScriptPluginContext methods; the bridge wraps them as QuickJS functions.
+ */
+export function createQuickjsBridge(
+  module: QuickJSWASMModule,
+  hostApi: {
+    id: string;
+    events: {
+      subscribe(event: string, handler: (data: unknown) => void): () => void;
+      publish(event: string, data: unknown): void;
+    };
+    state: {
+      get(key: string): unknown;
+      set(key: string, value: unknown): void;
+      delete(key: string): void;
+      keys(): string[];
+    };
+    tick: { onTick(fn: (dt: number, t: number) => void): () => void };
+    log: { info(m: string): void; warn(m: string): void; error(m: string): void; debug(m: string): void };
+    onDispose(fn: () => void): void;
+  },
+  opts: QuickjsBridgeOptions,
+): QuickjsBridge {
+  const runtime = module.newRuntime();
+  const budget = opts.instructionBudget ?? DEFAULT_INSTRUCTION_BUDGET;
+  let instructions = 0;
+  runtime.setInterruptHandler(() => {
+    instructions++;
+    if (instructions > budget) {
+      return true; // interrupt — throws "interrupted" in the VM
+    }
+    return false;
+  });
+
+  const ctx = runtime.newContext();
+
+  // Track all persistent handles so we can dispose them before the context.
+  const handles: any[] = [];
+  const track = <T>(h: T): T => { handles.push(h); return h; };
+  const unsubFns: Array<() => void> = [];
+  const disposeCbs: Array<() => void> = [];
+
+  // Bridge the host API into the VM global as `ddPlugin`.
+  const ddPlugin = track(ctx.newObject());
+
+  // ── events ──
+  const events = track(ctx.newObject());
+  ctx.setProp(
+    events,
+    "subscribe",
+    track(ctx.newFunction("subscribe", (eventHandle, handlerHandle) => {
+      const event = ctx.getString(eventHandle as any);
+      // Dup the handler handle so it stays alive after this callback returns.
+      const handlerDup = (handlerHandle as any).dup();
+      handles.push(handlerDup);
+      const handler = (data: unknown) => {
+        try {
+          const dataHandle = marshalToVm(ctx, data);
+          ctx.unwrapResult(ctx.callFunction(handlerDup, ctx.undefined, dataHandle));
+          dataHandle.dispose();
+          runtime.executePendingJobs();
+        } catch { /* swallow */ }
+      };
+      unsubFns.push(hostApi.events.subscribe(event, handler));
+      return ctx.undefined;
+    })),
+  );
+  ctx.setProp(
+    events,
+    "publish",
+    track(ctx.newFunction("publish", (eventHandle, dataHandle) => {
+      hostApi.events.publish(ctx.getString(eventHandle as any), marshalFromVm(ctx, dataHandle));
+      return ctx.undefined;
+    })),
+  );
+  ctx.setProp(ddPlugin, "events", events);
+
+  // ── state ──
+  const state = track(ctx.newObject());
+  ctx.setProp(
+    state,
+    "get",
+    track(ctx.newFunction("get", (keyHandle) => marshalToVm(ctx, hostApi.state.get(ctx.getString(keyHandle as any))))),
+  );
+  ctx.setProp(
+    state,
+    "set",
+    track(ctx.newFunction("set", (keyHandle, valueHandle) => {
+      hostApi.state.set(ctx.getString(keyHandle as any), marshalFromVm(ctx, valueHandle));
+      return ctx.undefined;
+    })),
+  );
+  ctx.setProp(
+    state,
+    "delete",
+    track(ctx.newFunction("delete", (keyHandle) => { hostApi.state.delete(ctx.getString(keyHandle as any)); return ctx.undefined; })),
+  );
+  ctx.setProp(
+    state,
+    "keys",
+    track(ctx.newFunction("keys", () => marshalToVm(ctx, hostApi.state.keys()))),
+  );
+  ctx.setProp(ddPlugin, "state", state);
+
+  // ── tick ──
+  const tick = track(ctx.newObject());
+  ctx.setProp(
+    tick,
+    "onTick",
+    track(ctx.newFunction("onTick", (fnHandle) => {
+      const fnDup = (fnHandle as any).dup();
+      handles.push(fnDup);
+      const cb = (dt: number, t: number) => {
+        try {
+          const tickStart = performance.now();
+          ctx.unwrapResult(ctx.callFunction(fnDup, ctx.undefined, ctx.newNumber(dt), ctx.newNumber(t)));
+          runtime.executePendingJobs();
+          const durationUs = (performance.now() - tickStart) * 1000;
+          recordTaskLatency("quickjs", durationUs, "tick");
+          getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+        } catch { /* swallow */ }
+      };
+      unsubFns.push(hostApi.tick.onTick(cb));
+      return ctx.undefined;
+    })),
+  );
+  ctx.setProp(ddPlugin, "tick", tick);
+
+  // ── log ──
+  const log = track(ctx.newObject());
+  ctx.setProp(log, "info", track(ctx.newFunction("info", (m) => { hostApi.log.info(ctx.getString(m as any)); return ctx.undefined; })));
+  ctx.setProp(log, "warn", track(ctx.newFunction("warn", (m) => { hostApi.log.warn(ctx.getString(m as any)); return ctx.undefined; })));
+  ctx.setProp(log, "error", track(ctx.newFunction("error", (m) => { hostApi.log.error(ctx.getString(m as any)); return ctx.undefined; })));
+  ctx.setProp(log, "debug", track(ctx.newFunction("debug", (m) => { hostApi.log.debug(ctx.getString(m as any)); return ctx.undefined; })));
+  ctx.setProp(ddPlugin, "log", log);
+
+  // ── onDispose ──
+  ctx.setProp(
+    ddPlugin,
+    "onDispose",
+    track(ctx.newFunction("onDispose", (fnHandle) => {
+      const fnDup = (fnHandle as any).dup();
+      handles.push(fnDup);
+      // Register the dispose callback directly — the bridge calls these
+      // in dispose() while the VM is still alive.
+      disposeCbs.push(() => {
+        try {
+          ctx.unwrapResult(ctx.callFunction(fnDup, ctx.undefined));
+          runtime.executePendingJobs();
+        } catch { /* swallow */ }
+      });
+      // Also notify the host API (for external tracking).
+      hostApi.onDispose(() => {});
+      return ctx.undefined;
+    })),
+  );
+
+  // ── id ──
+  ctx.setProp(ddPlugin, "id", track(ctx.newString(hostApi.id)));
+
+  // Expose ddPlugin as a global.
+  ctx.setProp(ctx.global, "ddPlugin", ddPlugin);
+
+  return {
+    ctx,
+    eval(code, filename) {
+      instructions = 0;
+      const evalStart = performance.now();
+      const result = ctx.evalCode(code, filename);
+      const durationUs = (performance.now() - evalStart) * 1000;
+      recordTaskLatency("quickjs", durationUs, "eval");
+      getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+      if (result.error) {
+        const err = ctx.dump(result.error);
+        result.error.dispose();
+        throw new Error(`QuickJS eval error in "${opts.pluginId}": ${err}`);
+      }
+      const val = marshalFromVm(ctx, result.value);
+      result.value.dispose();
+      return val;
+    },
+    callGlobal(fnName, ...args) {
+      instructions = 0;
+      const fn = ctx.getProp(ctx.global, fnName);
+      if (ctx.typeof(fn) !== "function") {
+        fn.dispose();
+        throw new Error(`QuickJS: global "${fnName}" is not a function`);
+      }
+      const argHandles = args.map((a) => marshalToVm(ctx, a));
+      const callStart = performance.now();
+      const result = ctx.callFunction(fn, ctx.undefined, ...argHandles);
+      const durationUs = (performance.now() - callStart) * 1000;
+      recordTaskLatency("quickjs", durationUs, fnName);
+      getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+      fn.dispose();
+      argHandles.forEach((h) => { try { h.dispose?.(); } catch { /* */ } });
+      if (result.error) {
+        const err = ctx.dump(result.error);
+        result.error.dispose();
+        throw new Error(`QuickJS call error in "${opts.pluginId}": ${err}`);
+      }
+      const val = marshalFromVm(ctx, result.value);
+      result.value.dispose();
+      return val;
+    },
+    drainJobs() {
+      runtime.executePendingJobs();
+    },
+    dispose() {
+      // Run dispose callbacks while the VM is still alive.
+      disposeCbs.forEach((cb) => { cb();; });
+      disposeCbs.length = 0;
+      unsubFns.forEach((unsub) => { unsub();; });
+      // Dispose all tracked handles before the context.
+      handles.forEach((h) => { try { h.dispose?.(); } catch { /* */ } });
+      handles.length = 0;
+      ctx.dispose();
+      runtime.dispose();
+    },
+  };
+}