@downdraft/engine 0.2.0 → 0.3.1

package/app/src/renderer/bootstrap.ts

@@ -111,8 +111,6 @@ export interface BootstrapDevToolsOptions {
    * Called after the renderer is initialized.
    */
   createSimStatsProvider?: (renderer: any) => any;
-  /** DevTools panels (game-specific). Can be a factory or static array. */
-  panels?: any[] | ((renderer: any) => any[]);
   /** Whether to enable scene inspector. Default: false. */
   sceneInspector?: boolean;
   /** Custom scene-inspector bridge class (extends BaseSceneInspector).
@@ -236,15 +234,11 @@ export async function bootstrapGame(opts: BootstrapGameOptions): Promise<void> {
     if (!devtoolsMod) return;
     const { initDevTools } = devtoolsMod;
     const simStatsProvider = opts.devtools.createSimStatsProvider?.(renderer);
-    const panels = typeof opts.devtools.panels === "function"
-      ? opts.devtools.panels(renderer)
-      : opts.devtools.panels ?? [];
     const workerHosts = typeof opts.devtools.workerHosts === "function"
       ? opts.devtools.workerHosts(renderer)
       : opts.devtools.workerHosts;
     const devtoolsBridge = await importOrDead(initDevTools(renderer, {
       simStatsProvider,
-      panels,
       sceneInspector: opts.devtools.sceneInspector,
       bridgeClass: opts.devtools.bridgeClass,
       workerHosts,

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

@@ -86,20 +86,12 @@ export function collectRendererFeatureLog(opts: RendererFeatureLogOptions): Feat
     if (nav?.deviceMemory) data.mem = `${nav.deviceMemory}G`;
   } catch { /* navigator unavailable */ }
 
-  // --- SharedArrayBuffer + crossOriginIsolated (browser isolation only —
-  // there is no origin model on the native host) ---
+  // --- SharedArrayBuffer ---
   try {
     data.sab = typeof SharedArrayBuffer !== "undefined" ? 1 : 0;
   } catch {
     data.sab = 0;
   }
-  if (getHostCapabilities().hasDom) {
-    try {
-      data.coi = (self as any).crossOriginIsolated ? 1 : 0;
-    } catch {
-      data.coi = 0;
-    }
-  }
 
   // --- Worker load status (best-effort; na = not checked) ---
   data.wk = "na";

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

@@ -120,17 +120,14 @@ export function createMcpHarness(opts: McpHarnessOptions): void {
 // Games import them instead of duplicating the implementation.
 
 /** Convert a Blob to a base64 string (without the data: prefix). */
-export function blobToBase64(blob: Blob): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onloadend = () => {
-      const result = reader.result as string;
-      const base64 = result.split(",")[1];
-      resolve(base64 ?? "");
-    };
-    reader.onerror = reject;
-    reader.readAsDataURL(blob);
-  });
+export async function blobToBase64(blob: Blob): Promise<string> {
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
 }
 
 /** MCP result helper: wrap data as a JSON content array. */

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

@@ -26,7 +26,7 @@
 //   });
 // ============================================================================
 
-import { getHostCapabilities, KEY, type RenderSurface } from "@downdraft/engine";
+import { 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";
@@ -108,14 +108,6 @@ export interface StandardAutomationContext {
   /** The game render surface (layer 0). Used by capture_screenshot + dispatch_click. */
   surface: RenderSurface | (() => RenderSurface | null);
 
-  /**
-   * Extra canvases to composite between the game canvas and the DOM overlay
-   * in full-page screenshots (e.g. a 2D tile canvas). DOM hosts only —
-   * native capture returns the composited swapchain via captureFrame().
-   * Default: none.
-   */
-  extraLayers?: () => HTMLCanvasElement[];
-
   /**
    * Render one frame when the render loop is paused (deterministic mode), so
    * screenshots reflect current state. Called by capture_screenshot when the
@@ -422,20 +414,13 @@ export function createStandardAutomationTools(ctx: StandardAutomationContext): M
         const rect = surface.getBoundingClientRect();
         const clientX = rect.left + x;
         const clientY = rect.top + y;
-        const hasDom = getHostCapabilities().hasDom;
-        // DOM hosts hit-test the topmost element (mimics a real user click
-        // through UI overlays). On native there is no DOM tree — the surface
-        // itself is the input target.
-        const target = hasDom
-          ? (document.elementFromPoint(clientX, clientY) ?? (surface as unknown as HTMLElement))
-          : (surface as unknown as EventTarget);
-        // MiniEventTarget (native event polyfill) has no capture/bubble —
-        // mirror real propagation by also dispatching on window. In a real
-        // DOM this would double-fire, so only do it under the polyfill.
-        const isNativeDom = !hasDom;
+        // There is no DOM tree — the surface itself is the input target.
+        const target = surface as unknown as EventTarget;
+        // MiniEventTarget (native event target) has no capture/bubble —
+        // mirror DOM propagation by also dispatching on window.
         const fire = (ev: Event) => {
           target.dispatchEvent(ev);
-          if (isNativeDom) (window as any).dispatchEvent?.(ev);
+          (window as any).dispatchEvent?.(ev);
         };
         if (type === "wheel") {
           const deltaX = (params.deltaX as number) ?? 0;
@@ -474,10 +459,10 @@ export function createStandardAutomationTools(ctx: StandardAutomationContext): M
           if (pointerType) fireOne(pointerType, true, buttons);
           fireOne(type, false, buttons);
         }
-        const targetEl = target as Partial<HTMLElement>;
+        const targetEl = target as { tagName?: string; id?: string; className?: unknown };
         return jsonResult({
           dispatched: true, x, y, type,
-          targetTag: targetEl.tagName ?? (targetEl as { id?: string }).id ?? "surface",
+          targetTag: targetEl.tagName ?? targetEl.id ?? "surface",
           targetClass: targetEl.className?.toString().slice(0, 80),
         });
       },
@@ -617,128 +602,6 @@ export function createStandardAutomationTools(ctx: StandardAutomationContext): M
     });
   }
 
-  // ── get_element_bounds ──
-  if (want("get_element_bounds")) {
-    tools.push({
-      def: {
-        name: "get_element_bounds",
-        description: "Get the bounding box of a DOM element matching a CSS selector. Returns {x, y, width, height, top, left, bottom, right} or found:false.",
-        inputSchema: {
-          type: "object",
-          properties: { selector: { type: "string", description: "CSS selector" } },
-          required: ["selector"],
-        },
-      },
-      handler: (params: Record<string, unknown>) => {
-        const selector = params.selector as string;
-        try {
-          const el = document.querySelector(selector);
-          if (!el) return jsonResult({ found: false, selector });
-          const rect = el.getBoundingClientRect();
-          return jsonResult({
-            found: true, selector,
-            x: rect.x, y: rect.y, width: rect.width, height: rect.height,
-            top: rect.top, left: rect.left, bottom: rect.bottom, right: rect.right,
-          });
-        } catch (e) {
-          return errorResult(`Failed to query selector "${selector}": ${(e as Error).message}`);
-        }
-      },
-    });
-  }
-
-  // ── inspect_dom ──
-  if (want("inspect_dom")) {
-    tools.push({
-      def: {
-        name: "inspect_dom",
-        description: "Inspect the main thread's DOM for debugging CSS/layout issues. 'stylesheets' lists all <style>/<link> tags; 'element' gets details for a selector.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            action: { type: "string", enum: ["stylesheets", "element"] },
-            selector: { type: "string", description: "CSS selector (for action='element')" },
-          },
-          required: ["action"],
-        },
-      },
-      handler: (params: Record<string, unknown>) => {
-        if (!getHostCapabilities().hasDom) {
-          return errorResult("inspect_dom requires a real DOM — the native host's document is a canvas-compat facade, not a DOM tree");
-        }
-        const action = params.action as string;
-        if (action === "stylesheets") {
-          const styles = Array.from(document.querySelectorAll("style, link[rel='stylesheet']")).map((el) => {
-            const tag = el.tagName.toLowerCase();
-            if (tag === "style") {
-              const text = el.textContent ?? "";
-              return { tag, length: text.length, preview: text.slice(0, 200) };
-            }
-            return { tag, href: (el as HTMLLinkElement).href };
-          });
-          return jsonResult({ stylesheets: styles, count: styles.length });
-        }
-        if (action === "element" && params.selector) {
-          const el = document.querySelector(params.selector as string);
-          if (!el) return jsonResult({ found: false, selector: params.selector });
-          const cs = getComputedStyle(el);
-          return jsonResult({
-            found: true,
-            selector: params.selector,
-            tagName: el.tagName,
-            className: el.className,
-            id: el.id,
-            style: {
-              width: cs.width, height: cs.height,
-              maxWidth: cs.maxWidth, maxHeight: cs.maxHeight,
-              display: cs.display, position: cs.position,
-              top: cs.top, left: cs.left, overflow: cs.overflow,
-            },
-            bounds: el.getBoundingClientRect().toJSON(),
-            childCount: el.children.length,
-          });
-        }
-        return errorResult("Invalid action or missing selector");
-      },
-    });
-  }
-
-  // ── get_element_style ──
-  if (want("get_element_style")) {
-    tools.push({
-      def: {
-        name: "get_element_style",
-        description: "Get computed style of a DOM element matching a CSS selector. Pass properties[] to read specific CSS properties.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            selector: { type: "string", description: "CSS selector" },
-            properties: { type: "array", items: { type: "string" }, description: "CSS properties to read" },
-          },
-          required: ["selector"],
-        },
-      },
-      handler: (params: Record<string, unknown>) => {
-        if (!getHostCapabilities().hasDom) {
-          return errorResult("get_element_style requires a real DOM — no computed styles on the native host");
-        }
-        const selector = params.selector as string;
-        const props = (params.properties as string[]) ?? [];
-        try {
-          const el = document.querySelector(selector);
-          if (!el) return jsonResult({ found: false, selector });
-          const cs = getComputedStyle(el);
-          const result: Record<string, unknown> = { found: true, selector };
-          props.forEach((p) => { result[p] = cs.getPropertyValue(p);; });
-          result._className = el.className;
-          return jsonResult(result);
-        } catch (e) {
-          return errorResult(`Failed to query style for "${selector}": ${(e as Error).message}`);
-        }
-      },
-    });
-  }
-
   // ── inspectable_list / inspectable_get / inspectable_set ──
   const inspectables = ctx.inspectables;
   if (want("inspectable_list") && inspectables) {

package/core/src/index.ts

@@ -56,7 +56,7 @@ export type { MultiInputChannelInstance, MultiInputChannelOptions } from "./sab/
 export { INP, INP_FLAG, INP_HDR, INPUT_MAGIC, INPUT_VERSION, InputBufferReader, InputBufferWriter, InputChannel, KEY, MAX_INPUT_PLAYERS } from "./sab/game-input";
 
 // Sim SAB Channel
-export { allocateInputBuffer, allocateSimBuffer, ENT, MAX_ENTITIES, MAX_PLAYERS, PLR, PLR_FLAG, SIM_ENTITY_SLOT_SIZE, SIM_HDR, SIM_MAGIC, SIM_PLAYER_SLOT_SIZE, SIM_VERSION, SimBufferReader, SimBufferWriter, SimChannel } from "./sab/sim-channel";
+export { allocateInputBuffer, allocateSimBuffer, ENT, MAX_ENTITIES, MAX_PLAYERS, PLR, PLR_FLAG, PREV, SIM_ENTITY_SLOT_SIZE, SIM_HDR, SIM_MAGIC, SIM_PLAYER_SLOT_SIZE, SIM_VERSION, SimBufferReader, SimBufferWriter, SimChannel } from "./sab/sim-channel";
 export type { PhysicsTimingData } from "./sab/sim-channel";
 
 // SAB Framework
@@ -90,7 +90,7 @@ export { EntitySimWorkerHost } from "./worker/entity-sim-worker-host";
 export type { EntitySimApi, EntitySimHostOptions } from "./worker/entity-sim-worker-host";
 export { exposeProfilingApi, InstrumentedWorkerHost } from "./worker/instrumented-worker-host";
 export type { InstrumentedWorkerHostOptions } from "./worker/instrumented-worker-host";
-export { expose, exposeEvents, getWorkerHost, wrap } from "./worker/rpc";
+export { expose, exposeBatchedEvents, exposeEvents, getWorkerHost, wrap } from "./worker/rpc";
 export type { ExposeOptions, HostMessageHandler, WorkerApi, WorkerEventEmitter, WorkerHost, WorkerProxy } from "./worker/rpc";
 export { createSimWorker } from "./worker/sim-worker-base";
 export type { CreateSimWorkerOptions, SimAfterTicksContext, SimTickContext, SimWorkerControl, SimWorkerStats } from "./worker/sim-worker-base";

package/core/src/module/host.ts

@@ -47,8 +47,8 @@ export class ModuleHost implements ModuleContext {
 
   /**
    * Inject the DevTools API. Called by the game bootstrap after
-   * `initDevTools()` so plugins can self-register debug panels via
-   * `ctx.devtools.registerPanel(...)` during their `register()` lifecycle.
+   * `initDevTools()` so plugins can self-register data feeds via
+   * `ctx.devtools.registerDataFeed(...)` during their `register()` lifecycle.
    */
   setDevToolsAPI(api: ModuleDevToolsAPI): void {
     this._devtools = api;
@@ -56,7 +56,7 @@ export class ModuleHost implements ModuleContext {
 
   get devtools(): ModuleDevToolsAPI {
     // Return the injected API, or a no-op stub if not set (so plugins that
-    // call ctx.devtools.registerPanel() don't crash if devtools isn't wired).
+    // call ctx.devtools.register*() don't crash if devtools isn't wired).
     return this._devtools ?? NoopDevToolsAPI;
   }
 
@@ -488,10 +488,7 @@ export class ModuleHost implements ModuleContext {
 }
 
 // No-op DevTools API stub — used when setDevToolsAPI() hasn't been called.
-// Plugins that call ctx.devtools.registerPanel() will silently no-op.
 const NoopDevToolsAPI: ModuleDevToolsAPI = {
-  registerPanel: () => {},
-  registerOverlayToggle: () => {},
   registerDataFeed: () => {},
   registerCommand: () => {},
   registerSABStat: () => {},

package/core/src/module/index.ts

@@ -3,7 +3,7 @@ export { buildCrossThreadReport, crossThreadToken } from "./cross-thread";
 export type { CrossThreadReport, CrossThreadToken, ModuleThreadInfo, ThreadTag } from "./cross-thread";
 export { DiagnosticError, isStrict, setStrict } from "./diagnostics";
 export { ModuleHost } from "./host";
-export type { DevToolsOverlayToggleRegistration, DevToolsPanelRegistration, Module, ModuleContext, ModuleDevToolsAPI, SABChannel } from "./module";
+export type { Module, ModuleContext, ModuleDevToolsAPI, SABChannel } from "./module";
 export { ModuleRegistry } from "./registry";
 export type {
     CameraControllerLike,

package/core/src/module/module.ts

@@ -7,59 +7,16 @@ export interface SABChannel {
   buffer: SharedArrayBuffer;
 }
 
-/**
- * Panel registration payload for `ctx.devtools.registerPanel()`.
- * Structurally compatible with `IDevToolsPanelExtension` from
- * `@downdraft/engine/modules/devtools` — core declares the minimal shape
- * so it doesn't depend on the devtools module (layering).
- */
-export interface DevToolsPanelRegistration {
-  /** Unique id for this extension (e.g. "debug-info", "game-panel"). */
-  id: string;
-  /** Tab label shown in the tab bar. */
-  tabLabel: string;
-  /** Tab tooltip. */
-  tabTooltip?: string;
-  /** Order/priority for tab placement. Core tabs: 0-100, game tabs: 100+. Default: 100. */
-  order?: number;
-  /** __sceneInspector methods that must exist for this tab to be shown. */
-  requiredMethods?: string[];
-  /** HTML content for the panel body. */
-  html: string;
-  /** CSS to inject into the panel document. */
-  css?: string;
-  /** JS to eval in the panel context. */
-  script?: string;
-}
-
-/**
- * Overlay toggle registration payload for `ctx.devtools.registerOverlayToggle()`.
- * Structurally compatible with `IDevToolsOverlayToggle` from
- * `@downdraft/engine/modules/devtools`.
- */
-export interface DevToolsOverlayToggleRegistration {
-  /** Unique id (e.g. "chunk-grid", "vel-arrows"). */
-  id: string;
-  /** Label shown next to the checkbox. */
-  label: string;
-  /** __sceneInspector methods that must exist for this toggle to be shown. */
-  requiredMethods?: string[];
-  /** JS to eval in the panel context. */
-  script?: string;
-}
-
 /**
  * DevTools registration surface exposed on ModuleContext.
- * Plugins call `ctx.devtools.registerPanel(...)` etc. to self-register
- * debug screens. The same interface works in both main and worker realms.
+ * Plugins call `ctx.devtools.registerDataFeed(...)` etc. to self-register
+ * debug data. The same interface works in both main and worker realms.
  *
  * The actual implementation is provided by @downdraft/engine/modules/devtools via
  * the `devtools` singleton. Core defines the interface; the host injects
  * the concrete object at construction time (see ModuleHost.setDevToolsAPI).
  */
 export interface ModuleDevToolsAPI {
-  registerPanel(ext: DevToolsPanelRegistration): void;
-  registerOverlayToggle(toggle: DevToolsOverlayToggleRegistration): void;
   registerDataFeed(name: string, fn: () => unknown, writeRateHz?: number): void;
   registerCommand(name: string, fn: (...args: unknown[]) => unknown): void;
   registerSABStat(name: string, offset: number, type: "u32" | "f32" | "i32"): void;
@@ -95,8 +52,8 @@ export interface ModuleContext {
   registerMigration(fromVersion: number, fn: (data: unknown) => unknown): void;
   onDispose(fn: () => void): void;
   /**
-   * DevTools registration surface. Plugins self-register debug panels,
-   * data feeds, and commands via `ctx.devtools.register*(...)`.
+   * DevTools registration surface. Plugins self-register data feeds and
+   * commands via `ctx.devtools.register*(...)`.
    * Works in both sim (worker) and renderer (main) plugin contexts.
    */
   readonly devtools: ModuleDevToolsAPI;

package/core/src/physics/interface.ts

@@ -399,6 +399,11 @@ export interface PhysicsBackend {
   /** Set integration timestep on a realm. */
   setIntegrationDt(realmId: number, dt: number): void;
 
+  /** Change a live realm's gravity vector. Optional — backends that can't
+   *  mutate realm gravity simply omit it (callers fall back to per-body
+   *  gravityScale). */
+  setRealmGravity?(realmId: number, gravity: [number, number, number]): void;
+
   /** Per-realm sleep thresholds for graceful degradation (load shedding first line). */
   setSleepThresholds(realmId: number, linearThreshold: number, angularThreshold: number): void;
   /** Per-realm solver iteration count (Rapier `IntegrationParameters.numSolverIterations`). */

package/core/src/platform/render-surface.ts

@@ -29,6 +29,15 @@ export interface RenderSurfaceContext {
    *  the swapchain can't produce a frame (resize in flight, occluded
    *  window) — callers must treat null as "skip this frame". */
   getCurrentTexture(): GPUTexture | null;
+  /** The texture already acquired for the in-flight frame, if any —
+   *  WITHOUT acquiring one. Null when nothing has acquired this frame.
+   *  End-of-frame overlay passes (UI composites) should join a frame via
+   *  peek rather than acquire: on hosts with frame retention (native),
+   *  acquiring here fabricates a frame the game deliberately skipped and
+   *  presents the overlay over a blank swapchain image. Optional — DOM
+   *  GPUCanvasContext has no equivalent; callers fall back to
+   *  getCurrentTexture() where acquire is idempotent within a frame. */
+  peekCurrentTexture?(): GPUTexture | null;
 }
 
 /** Listener signature — the native event target dispatches plain event
@@ -74,4 +83,8 @@ export interface RenderSurface {
    *  concept doesn't exist; presence is the feature check. */
   requestPointerLock?(): Promise<void> | void;
   exitPointerLock?(): void;
+  /** Current pointer-lock state. Optional — read instead of the DOM's
+   *  `document.pointerLockElement` (there is no DOM on native). The surface
+   *  also dispatches a `"pointerlockchange"` event on transitions. */
+  readonly pointerLocked?: boolean;
 }

package/core/src/platform/rpc.ts

@@ -1,3 +1,6 @@
+
+import { untrackedTimeout } from "../util/session-timer";
+
 export type RPCMessageType = "request" | "response" | "event";
 
 export interface RPCMessage {
@@ -34,7 +37,7 @@ export class RPC {
     }
     const id = this.messageIdCounter = (this.messageIdCounter + 1) % 0xFFFFFFFF;
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const timer = untrackedTimeout(() => {
         if (this.pending.has(id)) {
           this.pending.delete(id);
           reject(new Error(`[RPC] Call to "${channel}" timed out after ${timeoutMs}ms`));

package/core/src/render/canvas-resize-watcher.ts

@@ -5,7 +5,6 @@ export interface CanvasResizeHandler {
 }
 
 export class CanvasResizeWatcher {
-  private observer: ResizeObserver | null = null;
   private dpr = 1;
   private onSurfaceResize = () => this.resize();
 
@@ -14,13 +13,7 @@ export class CanvasResizeWatcher {
     private handler: CanvasResizeHandler,
   ) {
     this.dpr = (typeof window !== "undefined" ? window.devicePixelRatio : 0) || 1;
-    // DOM hosts: element box changes fire ResizeObserver. Native surfaces
-    // aren't Elements — they push a "resize" event instead. Both paths feed
-    // the same resize() so either host drives layout updates.
-    if (typeof ResizeObserver !== "undefined") {
-      this.observer = new ResizeObserver(() => this.resize());
-      this.observer.observe(canvas as unknown as Element);
-    }
+    // Native surfaces push a "resize" event when the backing store changes.
     canvas.addEventListener("resize", this.onSurfaceResize);
     this.resize();
   }
@@ -39,8 +32,6 @@ export class CanvasResizeWatcher {
   }
 
   destroy(): void {
-    this.observer?.disconnect();
-    this.observer = null;
     this.canvas.removeEventListener("resize", this.onSurfaceResize);
   }
 }