@downdraft/engine 0.0.0 → 0.1.1

package/core/src/plugin/registry.ts

@@ -0,0 +1,107 @@
+// ============================================================================
+// Plugin registry — tracks discovered plugins and resolves load order.
+//
+// Mirrors `ModuleRegistry` but operates on `PluginManifest`s and resolves
+// order over BOTH `dependencies` (other plugin ids) and `requires` (stringly-
+// typed plugin resource keys). A plugin that `requires` a key must load
+// after whichever plugin `provides` it.
+// ============================================================================
+
+import type { PluginManifest } from "./manifest";
+
+export class PluginRegistry {
+  private manifests: Map<string, PluginManifest> = new Map();
+  private loadOrder: string[] = [];
+
+  register(manifest: PluginManifest): void {
+    if (this.manifests.has(manifest.id)) {
+      throw new Error(`Plugin "${manifest.id}" is already registered`);
+    }
+    this.manifests.set(manifest.id, manifest);
+    this.loadOrder.push(manifest.id);
+  }
+
+  unregister(id: string): void {
+    this.manifests.delete(id);
+    const idx = this.loadOrder.indexOf(id);
+    if (idx >= 0) this.loadOrder.splice(idx, 1);
+  }
+
+  get(id: string): PluginManifest | undefined {
+    return this.manifests.get(id);
+  }
+
+  has(id: string): boolean {
+    return this.manifests.has(id);
+  }
+
+  getAll(): PluginManifest[] {
+    return this.loadOrder.map((id) => this.manifests.get(id)!).filter(Boolean);
+  }
+
+  /**
+   * Resolve load order via topological sort over `dependencies` + `requires`.
+   * Plugins with no dependencies/providers come first.
+   *
+   * Throws on:
+   *   - missing dependency (declared dep not registered)
+   *   - missing provider (requires a key nobody provides)
+   *   - cycle
+   */
+  resolveOrder(): string[] {
+    // Build provider map: resourceKey → plugin id that provides it.
+    const providers = new Map<string, string>();
+    for (const m of this.getAll()) {
+      (m.provides ?? []).forEach((key) => {
+        if (providers.has(key)) {
+          throw new Error(
+            `Plugin resource "${key}" is provided by both "${providers.get(key)}" and "${m.id}".`,
+          );
+        }
+        providers.set(key, m.id);
+      });
+    }
+
+    const visited = new Set<string>();
+    const result: string[] = [];
+    const visiting = new Set<string>();
+
+    const visit = (id: string): void => {
+      if (visited.has(id)) return;
+      if (visiting.has(id)) {
+        throw new Error(`Plugin dependency cycle detected at "${id}"`);
+      }
+      const m = this.manifests.get(id);
+      if (!m) {
+        throw new Error(`Plugin "${id}" is not registered (required as a dependency)`);
+      }
+      visiting.add(id);
+
+      // dependencies (other plugin ids)
+      (m.dependencies ?? []).forEach((dep) => {
+        const depId = dep.split("@")[0];
+        if (!this.manifests.has(depId)) {
+          throw new Error(`Plugin "${id}" depends on "${depId}" which is not registered`);
+        }
+        visit(depId);
+      });
+      // requires (resource keys → provider plugin id)
+      (m.requires ?? []).forEach((key) => {
+        const providerId = providers.get(key);
+        if (!providerId) {
+          throw new Error(
+            `Plugin "${id}" requires resource "${key}" which no registered plugin provides`,
+          );
+        }
+        if (providerId !== id) visit(providerId);
+      });
+
+      visiting.delete(id);
+      visited.add(id);
+      result.push(id);
+    };
+
+    this.loadOrder.forEach((id) => { visit(id);; });
+    return result;
+  }
+}

package/core/src/plugin/sandbox-shim.ts

@@ -0,0 +1,86 @@
+// ============================================================================
+// Sandbox shim — worker-side global restriction.
+//
+// Runs INSIDE the plugin's sandbox worker (sandbox-worker.ts) BEFORE the
+// plugin's entry module is imported. It deletes/overrides every global on
+// `self` that is NOT in the granted allowlist, then dynamically imports the
+// plugin entry.
+//
+// This is best-effort same-origin isolation. For strong security, remote
+// workshop plugins run from a blob:/data: origin with CSP (Phase 2).
+// ============================================================================
+
+import type { PluginPermission } from "./manifest";
+import { BASELINE_GLOBALS, computeGlobalAllowlist } from "./permissions";
+
+/** Result of restrictGlobals: the kept allowlist plus a restore() that puts
+ *  every trapped/deleted global back. Callers that restrict a shared thread
+ *  (InlinePluginLoader) must run restore() when the plugin unloads. */
+export interface RestrictResult {
+  keep: Set<string>;
+  restore: () => void;
+}
+
+/**
+ * Restrict `self` globals to the allowlist computed from `granted`.
+ * Replaces stripped globals with a throwing trap so a plugin that reaches for
+ * a denied capability gets a clear error rather than `undefined`.
+ */
+export function restrictGlobals(granted: ReadonlySet<PluginPermission>): RestrictResult {
+  const keep = computeGlobalAllowlist(granted);
+  const self = globalThis as Record<string, unknown>;
+  // Collect own + inherited enumerable keys of self.
+  const allKeys = new Set<string>();
+  for (const k of Object.getOwnPropertyNames(self)) allKeys.add(k);
+  // Don't strip the host bridge or baseline runtime globals.
+  BASELINE_GLOBALS.forEach((g) => { keep.add(g);; });
+  // Snapshot the original descriptors so the globals can be restored later.
+  const originals = new Map<string, PropertyDescriptor | undefined>();
+  for (const key of allKeys.values()) {
+    if (keep.has(key)) continue;
+    // Skip non-configurable / non-writable props silently (can't delete them).
+    const desc = Object.getOwnPropertyDescriptor(self, key);
+    if (desc && !desc.configurable && !desc.writable) continue;
+    if (!originals.has(key)) originals.set(key, desc);
+    try {
+      // Replace with a throwing trap so access yields a clear error.
+      Object.defineProperty(self, key, {
+        configurable: true,
+        get() {
+          throw new Error(
+            `[downdraft:plugin-sandbox] global "${key}" is not available — permission not granted.`,
+          );
+        },
+        set() {
+          throw new Error(
+            `[downdraft:plugin-sandbox] global "${key}" is not available — permission not granted.`,
+          );
+        },
+      });
+    } catch {
+      // If defineProperty fails, try a plain delete.
+      try {
+        delete self[key];
+      } catch {
+        /* give up — leave as-is */
+      }
+    }
+  }
+  return {
+    keep,
+    restore() {
+      for (const [key, desc] of originals.entries()) {
+        try {
+          if (desc) {
+            Object.defineProperty(self, key, desc);
+          } else {
+            delete self[key];
+          }
+        } catch {
+          /* property may be non-configurable — leave as-is */
+        }
+      }
+      originals.clear();
+    },
+  };
+}

package/core/src/plugin/sandbox-worker.ts

@@ -0,0 +1,215 @@
+// ============================================================================
+// Sandbox worker entry — runs inside a dedicated Web Worker per worker-js
+// plugin. Receives an init message with the plugin entry URL + granted
+// permissions, restricts globals, then imports the entry and calls its
+// register() with a bridge-backed context.
+//
+// Bridge model: every host capability crosses the boundary as an async
+// `__bridgeCall`/`__bridgeResponse` pair correlated by `callId`. The host
+// side enforces an allowlist of methods and each context API enforces the
+// plugin's permission grant — this worker just forwards calls.
+//
+// This file is the worker entry. The host spawns it with:
+//   new Worker(new URL("./sandbox-worker.ts", import.meta.url), { type: "module" })
+// (the loader does this inline per the BaseWorkerHost Vite rule).
+// ============================================================================
+
+import type { PluginEntry, PluginHostCalls, ScriptPluginContext } from "./context";
+import type { PluginPermission } from "./manifest";
+import { restrictGlobals } from "./sandbox-shim";
+
+/** Init message from the host. */
+export interface SandboxInitMessage {
+  entryUrl: string;
+  granted: PluginPermission[];
+  /** Serialized context method names the host supports (for proxy wiring). */
+  contextId: string;
+}
+
+// ── Bridge call machinery ──
+
+let contextId = "";
+let nextCallId = 1;
+const pendingCalls = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+
+/** Invoke an allowlisted host method. Awaits the host's response. */
+function bridgeCall(method: string, args: unknown[]): Promise<unknown> {
+  const callId = nextCallId++;
+  return new Promise((resolve, reject) => {
+    pendingCalls.set(callId, { resolve, reject });
+    (self as any).postMessage({ __bridgeCall: true, contextId, callId, method, args });
+  });
+}
+
+/** Fire-and-forget bridge call (publish, subscribe — no meaningful result). */
+function bridgeNotify(method: string, args: unknown[]): void {
+  (self as any).postMessage({ __bridgeCall: true, contextId, method, args });
+}
+
+// ── Worker-local state ──
+
+const tickCallbacks = new Set<(dt: number, t: number) => void>();
+const disposeCallbacks: Array<() => void> = [];
+const eventHandlers = new Map<string, Set<(data: unknown) => void>>();
+/** Local KV mirror — get/set/delete/keys are synchronous; save()/load()
+ *  round-trip to the host's store via the bridge. */
+const localState = new Map<string, unknown>();
+
+// ── Message handling ──
+
+self.addEventListener("message", (ev: MessageEvent) => {
+  const msg = ev.data;
+  if (!msg) return;
+
+  if (msg.__sandboxInit) {
+    void runPlugin(msg as SandboxInitMessage & { __sandboxInit: true });
+    return;
+  }
+  if (msg.__bridgeResponse) {
+    const pending = pendingCalls.get(msg.callId);
+    if (pending) {
+      pendingCalls.delete(msg.callId);
+      if (msg.error !== undefined) {
+        pending.reject(new Error(msg.error));
+      } else {
+        pending.resolve(msg.result);
+      }
+    }
+    return;
+  }
+  // Host-driven tick → ctx.tick.onTick callbacks.
+  if (msg.__tick) {
+    for (const cb of tickCallbacks.values()) cb(msg.dt, msg.elapsedTime);
+    return;
+  }
+  // Host-published event → local subscribers (registered via ctx.events.subscribe).
+  if (msg.__event) {
+    const set = eventHandlers.get(msg.event);
+    if (set) for (const h of set.values()) h(msg.data);
+    return;
+  }
+  if (msg.__dispose) {
+    disposeCallbacks.forEach((cb) => {
+      try { cb(); } catch { /* dispose errors are non-fatal */ }
+    });
+    return;
+  }
+});
+
+async function runPlugin(init: SandboxInitMessage): Promise<void> {
+  try {
+    contextId = init.contextId;
+    // 1. Restrict globals based on granted permissions.
+    restrictGlobals(new Set<PluginPermission>(init.granted));
+
+    // 2. Build the bridge-backed context and expose it as `ddPlugin`.
+    const ctx = makeBridgeContext(init.contextId, new Set(init.granted));
+    (self as any).ddPlugin = { ctx };
+
+    // 3. Dynamically import the plugin entry. @vite-ignore because the URL is
+    //    dynamic (not statically analyzable).
+    const mod = await import(/* @vite-ignore */ init.entryUrl);
+    const entry: PluginEntry = mod.default ?? mod;
+    if (typeof entry.register !== "function") {
+      throw new Error(`Plugin entry "${init.entryUrl}" has no register() function`);
+    }
+    // 4. Call register.
+    await entry.register(ctx);
+    // 5. Notify host that registration completed.
+    (self as any).postMessage({ __sandboxReady: true, contextId: init.contextId });
+  } catch (e) {
+    // Report failures so the host's ready-wait rejects instead of hanging.
+    const err = e as Error;
+    (self as any).postMessage({
+      __sandboxError: true,
+      contextId: init.contextId,
+      error: `${err.message}\n${err.stack ?? ""}`,
+    });
+  }
+}
+
+/** Permissions that map to host-call methods (game mutation API). */
+const HOST_CALL_PERMS: PluginPermission[] = ["assets", "ecs", "physics"];
+const HOST_CALL_METHODS = [
+  "spawnProp",
+  "removeProp",
+  "setPhysics",
+  "getPhysics",
+  "applyImpulse",
+  "applyTorque",
+  "getAssetRef",
+] as const;
+
+/** Build a ScriptPluginContext that forwards calls to the host via postMessage. */
+function makeBridgeContext(
+  pluginId: string,
+  granted: ReadonlySet<PluginPermission>,
+): ScriptPluginContext {
+  const ctx: ScriptPluginContext = {
+    id: pluginId,
+    events: {
+      subscribe(event, handler) {
+        let set = eventHandlers.get(event);
+        if (!set) {
+          set = new Set();
+          eventHandlers.set(event, set);
+          // First local subscriber for this event — subscribe host-side too.
+          bridgeNotify("events.subscribe", [event]);
+        }
+        set.add(handler as (data: unknown) => void);
+        return () => set!.delete(handler as (data: unknown) => void);
+      },
+      publish(event, data) {
+        // Route through the host's shared bus — it echoes back to every
+        // subscriber (including this worker's own, if subscribed), so
+        // publish semantics match the in-process bus exactly.
+        bridgeNotify("events.publish", [event, data]);
+      },
+    },
+    state: {
+      get: <T>(key: string) => localState.get(key) as T | undefined,
+      set: (key, value) => { localState.set(key, value); },
+      delete: (key) => { localState.delete(key); },
+      keys: () => [...localState.keys()],
+      // Persist to the host's store (storage permission enforced host-side).
+      save: async () => { await bridgeCall("state.save", [[...localState.entries()]]); },
+      load: async () => {
+        const entries = (await bridgeCall("state.load", [])) as Array<[string, unknown]> | undefined;
+        if (entries) {
+          localState.clear();
+          entries.forEach(([k, v]) => { localState.set(k, v);; });
+        }
+      },
+    },
+    tick: {
+      onTick(fn) {
+        const wrapped = (dt: number, t: number) => fn(dt, t);
+        tickCallbacks.add(wrapped);
+        return () => tickCallbacks.delete(wrapped);
+      },
+    },
+    log: {
+      info: (m) => (self as any).postMessage({ __pluginLog: true, level: "info", msg: m }),
+      warn: (m) => (self as any).postMessage({ __pluginLog: true, level: "warn", msg: m }),
+      error: (m) => (self as any).postMessage({ __pluginLog: true, level: "error", msg: m }),
+      debug: (m) => (self as any).postMessage({ __pluginLog: true, level: "debug", msg: m }),
+    },
+    onDispose: (fn) => disposeCallbacks.push(fn),
+  };
+
+  // Expose the host-call bridge when the plugin was granted any host-call
+  // permission. Each method forwards over the bridge; the host enforces the
+  // allowlist + per-method permission gate. Script-tier contexts reject with
+  // "not available on this context".
+  const hasHostCallPerm = HOST_CALL_PERMS.some((p) => granted.has(p));
+  if (hasHostCallPerm) {
+    const hostCalls: Record<string, (...args: unknown[]) => Promise<unknown>> = {};
+    HOST_CALL_METHODS.forEach((m) => {
+      hostCalls[m] = (...args: unknown[]) => bridgeCall(m, args) as Promise<never>;
+    });
+    (ctx as ScriptPluginContext & { hostCalls: PluginHostCalls }).hostCalls =
+      hostCalls as unknown as PluginHostCalls;
+  }
+
+  return ctx;
+}

package/core/src/plugin/wasm-abi.ts

@@ -0,0 +1,152 @@
+// ============================================================================
+// WASM plugin ABI v3 — the contract between the host and WASM plugin modules.
+//
+// WASM plugins always run in their own dedicated worker (stability isolation).
+// The ABI uses WebAssembly linear memory for string/data passing:
+//   - The host provides an `env` import module with functions for logging,
+//     state access, event publishing, and game mutation (host calls).
+//   - The plugin exports `register`, and optionally `tick`, `dispose`,
+//     `on_event`, and `alloc` (for the host to allocate strings in the
+//     plugin's memory).
+//
+// v3 adds host-call imports for game mutation (spawn_prop, remove_prop,
+// set_physics, get_physics, apply_impulse, apply_torque, get_asset_ref).
+// These are async on the host side (forwarded to the game's PluginHostCalls);
+// the host-call imports return a u32 request id, and the host posts the
+// result back via the `on_host_call_result` export (ptr+len for JSON result,
+// or 0 for void / error). v2 imports are unchanged — a v2 plugin works as-is.
+//
+// All string/data passing uses (ptr, len) pairs into the plugin's linear
+// memory. The host calls `alloc(size)` to get a pointer, writes the data,
+// then calls the plugin function.
+// ============================================================================
+
+/** ABI version — incremented on breaking changes. v3 adds host-call imports. */
+export const WASM_PLUGIN_ABI_VERSION = 3;
+
+/** Host-provided import module (the `env` namespace). */
+export interface WasmPluginImports {
+  env: {
+    /** Log functions: (str_ptr, str_len) → void */
+    log_info: (ptr: number, len: number) => void;
+    log_warn: (ptr: number, len: number) => void;
+    log_error: (ptr: number, len: number) => void;
+    log_debug: (ptr: number, len: number) => void;
+    /** State: get(key_ptr, key_len) → value_ptr (0 if not found).
+     *  The value length is stored at [value_ptr-4] as a u32. */
+    state_get: (keyPtr: number, keyLen: number) => number;
+    /** State: set(key_ptr, key_len, val_ptr, val_len) → void */
+    state_set: (keyPtr: number, keyLen: number, valPtr: number, valLen: number) => void;
+    /** State: delete(key_ptr, key_len) → void */
+    state_delete: (keyPtr: number, keyLen: number) => void;
+    /** Events: publish(name_ptr, name_len, data_ptr, data_len) → void */
+    event_publish: (namePtr: number, nameLen: number, dataPtr: number, dataLen: number) => void;
+    /** Events: subscribe(name_ptr, name_len) → subscription_id (u32).
+     *  The host calls `on_event(sub_id, data_ptr, data_len)` when the event fires. */
+    event_subscribe: (namePtr: number, nameLen: number) => number;
+    /** Events: unsubscribe(sub_id) → void */
+    event_unsubscribe: (subId: number) => void;
+    // ── Host-call bridge (v3): game mutation ──
+    // Each returns a u32 request id. The host calls `on_host_call_result`
+    // (export) with the result when the async host call completes.
+    /** Spawn a prop: (content_id_ptr, content_id_len, x, y, z, qx, qy, qz, qw, scale) → request_id.
+     *  Result: JSON { entityId } or { error }. */
+    spawn_prop: (
+      contentIdPtr: number, contentIdLen: number,
+      x: number, y: number, z: number,
+      qx: number, qy: number, qz: number, qw: number,
+      scale: number,
+    ) => number;
+    /** Remove a prop: (entity_id) → request_id. Result: void or { error }. */
+    remove_prop: (entityId: number) => number;
+    /** Set physics: (entity_id, mass, restitution, friction, gravity_scale) → request_id.
+     *  Pass NaN for any field to leave it unchanged. Result: void or { error }. */
+    set_physics: (
+      entityId: number, mass: number, restitution: number, friction: number, gravityScale: number,
+    ) => number;
+    /** Get physics: (entity_id) → request_id. Result: JSON { mass, restitution, friction, gravityScale }. */
+    get_physics: (entityId: number) => number;
+    /** Apply impulse: (entity_id, x, y, z) → request_id. Result: void or { error }. */
+    apply_impulse: (entityId: number, x: number, y: number, z: number) => number;
+    /** Apply torque: (entity_id, x, y, z) → request_id. Result: void or { error }. */
+    apply_torque: (entityId: number, x: number, y: number, z: number) => number;
+    /** Get asset ref: (asset_id_ptr, asset_id_len) → request_id. Result: JSON { handle } or { error }. */
+    get_asset_ref: (assetIdPtr: number, assetIdLen: number) => number;
+  };
+}
+
+/** Plugin module exports (resolved after instantiation). */
+export interface WasmPluginExports {
+  /** Allocate `size` bytes in the plugin's linear memory. Returns a pointer. */
+  alloc: (size: number) => number;
+  /** Called once on load. The plugin can register systems, subscribe to events, etc. */
+  register: () => void;
+  /** Called every tick (if present). dt + elapsedTime in seconds. */
+  tick?: (dt: number, elapsedTime: number) => void;
+  /** Called on unload (if present). */
+  dispose?: () => void;
+  /** Called when a subscribed event fires (if present).
+   *  sub_id matches the id returned by `env.event_subscribe`. */
+  on_event?: (subId: number, dataPtr: number, dataLen: number) => void;
+  /** Called when a host-call (v3) completes (if present).
+   *  request_id matches the id returned by the host-call import.
+   *  resultPtr/resultLen point to a JSON result string (or 0,0 for void).
+   *  errorPtr/errorLen point to an error string (or 0,0 on success). */
+  on_host_call_result?: (
+    requestId: number,
+    resultPtr: number, resultLen: number,
+    errorPtr: number, errorLen: number,
+  ) => void;
+  /** The plugin's linear memory (for reading/writing strings). */
+  memory?: WebAssembly.Memory;
+}
+
+/** Helper: write a string into the plugin's linear memory.
+ *  Returns [ptr, len] or null if alloc failed. */
+export function writeStringToMemory(
+  exports: WasmPluginExports,
+  str: string,
+): [number, number] | null {
+  if (!exports.memory || !exports.alloc) return null;
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(str);
+  const ptr = exports.alloc(bytes.length);
+  if (ptr === 0) return null;
+  const view = new Uint8Array(exports.memory.buffer, ptr, bytes.length);
+  view.set(bytes);
+  return [ptr, bytes.length];
+}
+
+/** Helper: read a string from the plugin's linear memory. */
+export function readStringFromMemory(
+  exports: WasmPluginExports,
+  ptr: number,
+  len: number,
+): string {
+  if (!exports.memory) return "";
+  const view = new Uint8Array(exports.memory.buffer, ptr, len);
+  return new TextDecoder().decode(view);
+}
+
+/** Helper: write a byte array into the plugin's linear memory. */
+export function writeBytesToMemory(
+  exports: WasmPluginExports,
+  bytes: Uint8Array,
+): [number, number] | null {
+  if (!exports.memory || !exports.alloc) return null;
+  const ptr = exports.alloc(bytes.length);
+  if (ptr === 0) return null;
+  const view = new Uint8Array(exports.memory.buffer, ptr, bytes.length);
+  view.set(bytes);
+  return [ptr, bytes.length];
+}
+
+/** Helper: read a byte array from the plugin's linear memory. */
+export function readBytesFromMemory(
+  exports: WasmPluginExports,
+  ptr: number,
+  len: number,
+): Uint8Array {
+  if (!exports.memory) return new Uint8Array(0);
+  return new Uint8Array(exports.memory.buffer, ptr, len).slice();
+}