@downdraft/engine 0.0.0 → 0.1.0

package/libraries/devtools/src/web/mirror.ts

@@ -0,0 +1,430 @@
+// ============================================================================
+// web/mirror.ts — WebDevtoolsMirror: the web transport for devtools data.
+//
+// Same public surface as DevtoolsMirror (registerProvider,
+// registerCommandHandler, registerThreadEval, push*, update) but instead of
+// FFI-encoding into the egui crate it emits JSON events on the DevToolsServer
+// WebSocket. Eval is request/response over WS — no polling queue.
+//
+// WS events emitted: console, threads, scene, dom, gpu, metrics, snapshot,
+// profile, threads.
+// RPC handled (via server.call): ping, eval, snapshot, command, sceneTree,
+// domTree, gpuInfo, metrics, threads, inspector.call, profile.start|stop,
+// console.clear, domTree.mode.
+// ============================================================================
+
+import { addLogSink, createLogger, getRecentLogs, type LogSinkEntry } from "@downdraft/engine/util/logger";
+import type { CdpBridge, CdpConsoleEntry, CdpException } from "../cdp-bridge";
+import {
+    collectDomTree,
+    collectGpuInfo,
+    collectMetrics,
+    collectProfile,
+    collectSceneTree,
+    collectThreads,
+    type CollectorContext,
+} from "../collectors";
+import { PANEL, type DevtoolsCommand, type PanelName, type PanelSnapshot } from "../egui-ffi";
+import type { DevToolsServer } from "./server";
+
+const log = createLogger("info");
+
+type EvalFn = (expr: string) => Promise<{ result?: unknown; error?: string }>;
+export type PanelProvider = () => PanelSnapshot | null | undefined | Promise<PanelSnapshot | null | undefined>;
+export type PanelCommandHandler = (cmd: DevtoolsCommand) => void | Promise<void>;
+
+function panelSlot(panel: PanelName | number): number {
+  return typeof panel === "number" ? panel : (PANEL[panel] ?? 0);
+}
+
+function slotName(slot: number): string {
+  for (const [name, s] of Object.entries(PANEL)) {
+    if (s === slot) return name;
+  }
+  return `slot-${slot}`;
+}
+
+export interface WebMirrorOptions {
+  server: DevToolsServer;
+  cdp: CdpBridge;
+  renderer: unknown;
+  gameScene?: unknown;
+  profilingSAB: SharedArrayBuffer | null;
+}
+
+export class WebDevtoolsMirror {
+  private server: DevToolsServer;
+  private cdp: CdpBridge;
+  private ctx: CollectorContext;
+  private threadEvals = new Map<string, EvalFn>();
+  private disposed = false;
+
+  private providers = new Map<number, PanelProvider>();
+  private commandHandlers = new Map<number, PanelCommandHandler>();
+  private globalCommandHandler: PanelCommandHandler | null = null;
+  private lastProviderPush = new Map<number, number>();
+  providerIntervalMs = 1500;
+
+  private lastMetricsPush = 0;
+  private lastGpuPush = 0;
+  private lastScenePush = 0;
+  private firstUpdate = true;
+  private domTreeMode: "scene" | "ecs" = "scene";
+
+  private unsubConsole: (() => void) | null = null;
+  private unsubException: (() => void) | null = null;
+  private unsubLogger: (() => void) | null = null;
+  private loggerBuffer: LogSinkEntry[] = [];
+
+  constructor(opts: WebMirrorOptions) {
+    this.server = opts.server;
+    this.cdp = opts.cdp;
+    this.ctx = {
+      renderer: opts.renderer,
+      gameScene: opts.gameScene,
+      profilingSAB: opts.profilingSAB,
+    };
+    this.server.setHello(() => ({
+      version: 1,
+      panels: [...this.providers.keys()].map((s) => ({ slot: s, name: slotName(s) })),
+      inspector: this.inspectorMethodNames(),
+    }));
+  }
+
+  // ── Lifecycle ──
+
+  start(): void {
+    this.unsubConsole = this.cdp.onConsole((entry: CdpConsoleEntry) => {
+      const severity = entry.type === "error" ? 3
+        : entry.type === "warning" ? 2
+        : entry.type === "info" ? 1
+        : entry.type === "debug" ? 4
+        : entry.type === "trace" ? 5
+        : 0;
+      const text = entry.args.map((a: { value?: unknown; description?: string }) =>
+        a.value ?? a.description ?? String(a)).join(" ");
+      this.emitConsole(text, severity, "main", entry.timestamp ?? performance.now(), !!entry.stack);
+    });
+    this.unsubException = this.cdp.onException((exc: CdpException) => {
+      const text = `${exc.text}\n${exc.stack ?? ""}`.trim();
+      this.emitConsole(text, 3, "main", performance.now(), true);
+    });
+    void this.pushThreads();
+  }
+
+  attachLoggerBridge(): void {
+    if (this.unsubLogger) return;
+    for (const entry of getRecentLogs()) {
+      this.pushLogEntry(entry);
+    }
+    this.unsubLogger = addLogSink((entry) => {
+      this.loggerBuffer.push(entry);
+      if (this.loggerBuffer.length > 200) this.loggerBuffer.shift();
+    });
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubConsole?.();
+    this.unsubException?.();
+    this.unsubLogger?.();
+  }
+
+  resetFirstUpdate(): void {
+    this.firstUpdate = true;
+  }
+
+  // ── Emission helpers ──
+
+  private emit(event: string, data: unknown): void {
+    if (this.disposed) return;
+    this.server.emit(event, data);
+  }
+
+  private emitConsole(text: string, severity: number, thread: string, ts: number, hasStack: boolean): void {
+    this.emit("console", { text, severity, thread, ts, hasStack });
+  }
+
+  private flushLoggerBuffer(): void {
+    if (this.loggerBuffer.length === 0) return;
+    const entries = this.loggerBuffer;
+    this.loggerBuffer = [];
+    entries.forEach((entry) => this.pushLogEntry(entry));
+  }
+
+  private pushLogEntry(entry: LogSinkEntry): void {
+    if (this.disposed) return;
+    this.emitConsole(
+      `[${entry.module}] ${entry.message}`,
+      logLevelToSeverity(entry.level),
+      entry.thread || "main",
+      entry.timestamp,
+      false,
+    );
+  }
+
+  // ── Thread eval ──
+
+  registerThreadEval(threadId: string, evalFn: EvalFn): void {
+    this.threadEvals.set(threadId, evalFn);
+    void this.pushThreads();
+  }
+
+  // ── Data pushes (same names as DevtoolsMirror) ──
+
+  async pushThreads(): Promise<void> {
+    this.emit("threads", await collectThreads(this.ctx, [...this.threadEvals.keys()]));
+  }
+
+  pushSceneTree(): void {
+    this.emit("scene", collectSceneTree(this.ctx));
+  }
+
+  pushDomTree(mode: "scene" | "ecs"): void {
+    this.domTreeMode = mode;
+    this.emit("dom", collectDomTree(this.ctx, mode));
+  }
+
+  pushGpuInfo(): void {
+    this.emit("gpu", collectGpuInfo(this.ctx));
+  }
+
+  async pushMetrics(): Promise<void> {
+    this.emit("metrics", await collectMetrics(this.ctx));
+  }
+
+  pushProfile(profile: Parameters<typeof collectProfile>[0]): void {
+    this.emit("profile", collectProfile(profile));
+  }
+
+  clearConsole(): void {
+    this.emit("console.clear", {});
+  }
+
+  // ── Providers / commands ──
+
+  registerProvider(panel: PanelName | number, collect: PanelProvider): void {
+    this.providers.set(panelSlot(panel), collect);
+  }
+
+  registerCommandHandler(panel: PanelName | number | "*", handler: PanelCommandHandler): void {
+    if (panel === "*") {
+      this.globalCommandHandler = handler;
+    } else {
+      this.commandHandlers.set(panelSlot(panel), handler);
+    }
+  }
+
+  /** Collect + emit one provider's snapshot immediately. */
+  refreshPanel(panel: PanelName | number): void {
+    const slot = panelSlot(panel);
+    const collect = this.providers.get(slot);
+    if (!collect) return;
+    const push = (snap: PanelSnapshot | null | undefined) => {
+      if (snap) this.emit("snapshot", { panel: slotName(slot), slot, snap });
+      this.lastProviderPush.set(slot, performance.now());
+    };
+    const fail = (err: unknown) => {
+      this.emit("snapshot", {
+        panel: slotName(slot), slot,
+        snap: { status: "error", statusMsg: String(err), sections: [] },
+      });
+      this.lastProviderPush.set(slot, performance.now());
+    };
+    try {
+      const r = collect();
+      if (r && typeof (r as Promise<PanelSnapshot>).then === "function") {
+        (r as Promise<PanelSnapshot>).then(push, fail);
+      } else {
+        push(r as PanelSnapshot | null | undefined);
+      }
+    } catch (err) {
+      fail(err);
+    }
+  }
+
+  private pushAllProviders(): void {
+    for (const slot of this.providers.keys()) {
+      void this.refreshPanel(slot);
+    }
+  }
+
+  private dispatchCommand(cmd: DevtoolsCommand): void {
+    if (cmd.action === "refresh") {
+      void this.refreshPanel(cmd.panel);
+      return;
+    }
+    const handler = this.commandHandlers.get(cmd.panel) ?? this.globalCommandHandler;
+    if (!handler) {
+      log.warn("WebDevtoolsMirror", `unhandled command panel=${cmd.panel} action=${cmd.action}`);
+      return;
+    }
+    try {
+      const r = handler(cmd);
+      if (r instanceof Promise) r.catch((err) => log.warn("WebDevtoolsMirror", `command error: ${err}`));
+    } catch (err) {
+      log.warn("WebDevtoolsMirror", `command error: ${err}`);
+    }
+  }
+
+  setPerfRecording(start: boolean): void {
+    if (start) this.startProfiling();
+    else void this.stopProfiling();
+  }
+
+  private startProfiling(): void {
+    try {
+      this.cdp.startProfile();
+      log.info("WebDevtoolsMirror", "Profiling started");
+    } catch (err) {
+      log.warn("WebDevtoolsMirror", `Failed to start profiling: ${err}`);
+    }
+  }
+
+  private async stopProfiling(): Promise<void> {
+    try {
+      const profile = await this.cdp.stopProfile();
+      if (profile) this.pushProfile(profile);
+    } catch (err) {
+      log.warn("WebDevtoolsMirror", `Failed to stop profiling: ${err}`);
+    }
+  }
+
+  // ── Per-frame pump (called from WebDevtoolsHost.update) ──
+
+  update(): void {
+    if (this.disposed) return;
+    if (this.server.clientCount === 0) return; // nobody listening — save the work
+
+    this.flushLoggerBuffer();
+
+    if (this.firstUpdate) {
+      this.firstUpdate = false;
+      this.pushSceneTree();
+      this.pushDomTree(this.domTreeMode);
+      this.pushGpuInfo();
+      void this.pushMetrics();
+      void this.pushThreads();
+      this.pushAllProviders();
+    }
+
+    const now = performance.now();
+    if (now - this.lastMetricsPush > 500) {
+      this.lastMetricsPush = now;
+      void this.pushMetrics();
+      void this.pushThreads();
+    }
+    if (now - this.lastGpuPush > 1000) {
+      this.lastGpuPush = now;
+      this.pushGpuInfo();
+    }
+    if (now - this.lastScenePush > 2000) {
+      this.lastScenePush = now;
+      this.pushSceneTree();
+      this.pushDomTree(this.domTreeMode);
+    }
+    // Provider snapshots on their own cadence.
+    for (const slot of this.providers.keys()) {
+      const last = this.lastProviderPush.get(slot) ?? 0;
+      if (now - last > this.providerIntervalMs) {
+        void this.refreshPanel(slot);
+      }
+    }
+  }
+
+  // ── RPC dispatch (called by DevToolsServer for client requests) ──
+
+  async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
+    switch (method) {
+      case "eval": {
+        const threadId = String(params.thread ?? "main");
+        const expr = String(params.expr ?? "");
+        const evalFn = this.threadEvals.get(threadId) ?? (threadId === "main" ? this.cdp.evaluate.bind(this.cdp) : null);
+        if (!evalFn) return { error: `no eval for thread "${threadId}"` };
+        return evalFn(expr);
+      }
+      case "sceneTree":
+        return collectSceneTree(this.ctx);
+      case "domTree":
+        return collectDomTree(this.ctx, (params.mode === "ecs" ? "ecs" : "scene"));
+      case "gpuInfo":
+        return collectGpuInfo(this.ctx);
+      case "metrics":
+        return collectMetrics(this.ctx);
+      case "threads":
+        return collectThreads(this.ctx, [...this.threadEvals.keys()]);
+      case "snapshot": {
+        const panel = params.panel;
+        const slot = typeof panel === "number" ? panel : panelSlot(panel as PanelName);
+        const collect = this.providers.get(slot);
+        if (!collect) return { status: "unsupported", statusMsg: `no provider for ${String(panel)}`, sections: [] };
+        try {
+          const snap = await collect();
+          return snap ?? { status: "ok", sections: [] };
+        } catch (err) {
+          return { status: "error", statusMsg: String(err), sections: [] };
+        }
+      }
+      case "command": {
+        const panel = params.panel;
+        const slot = typeof panel === "number" ? panel : panelSlot((panel as PanelName) ?? "console");
+        this.dispatchCommand({ panel: slot, action: String(params.action ?? ""), payload: String(params.payload ?? "") });
+        return true;
+      }
+      case "inspector.call": {
+        const api = this.sceneInspector();
+        const name = String(params.method ?? "");
+        const fn = api?.[name];
+        if (typeof fn !== "function") throw new Error(`__sceneInspector.${name} is not a function`);
+        return fn(...((params.args as unknown[]) ?? []));
+      }
+      case "profile.start":
+        this.startProfiling();
+        return true;
+      case "profile.stop":
+        await this.stopProfiling();
+        return true;
+      case "console.clear":
+        this.cdp.clear();
+        this.emit("console.clear", {});
+        return true;
+      case "domTree.mode":
+        this.domTreeMode = params.mode === "ecs" ? "ecs" : "scene";
+        this.pushDomTree(this.domTreeMode);
+        return this.domTreeMode;
+      default:
+        throw new Error(`unknown method ${method}`);
+    }
+  }
+
+  private sceneInspector(): Record<string, unknown> | null {
+    const g = globalThis as Record<string, unknown>;
+    const win = g.window as Record<string, unknown> | undefined;
+    return (win?.__sceneInspector ?? g.__sceneInspector ?? null) as Record<string, unknown> | null;
+  }
+
+  private inspectorMethodNames(): string[] {
+    const api = this.sceneInspector();
+    if (!api) return [];
+    return Object.keys(api).filter((k) => typeof api[k] === "function");
+  }
+}
+
+function logLevelToSeverity(level: string): number {
+  switch (level) {
+    case "error":
+    case "fatal":
+      return 3;
+    case "warn":
+      return 2;
+    case "info":
+      return 1;
+    case "debug":
+      return 4;
+    case "trace":
+      return 5;
+    default:
+      return 0;
+  }
+}

package/libraries/devtools/src/web/server.ts

@@ -0,0 +1,198 @@
+// ============================================================================
+// server.ts — DevToolsServer: the web-devtools loopback endpoint.
+//
+// Development-only. Binds 127.0.0.1:0 (ephemeral), serves the devtools-web
+// frontend over HTTP and the JSON-RPC channel over WebSocket. A bearer token
+// is required on the WS upgrade; discovery is via ~/.downdraft/devtools/<pid>
+// (mirrors the MCP ~/.downdraft/port convention).
+//
+// Wire protocol (JSON, single WS connection):
+//   client → {id, method, params}
+//   server → {id, result} | {id, error: {message}}
+//   server → {event, data}            (unsolicited pushes: console, metrics…)
+//   server → {event:"hello", data:{version, panels, inspectorMethods}}
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, extname, join, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const log = createLogger("info");
+
+const MIME: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+};
+
+export interface DevToolsServerOptions {
+  /** Directory containing index.html + panel assets. Defaults to the
+   *  sibling devtools-web package. */
+  webRoot?: string;
+  /** Extra routes: path → content (e.g. generated kit.css). */
+  extraRoutes?: Record<string, string>;
+  /** JSON-RPC dispatch — see WebDevtoolsMirror.dispatch(). */
+  call?: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+  /** Connection bookkeeping (e.g. host focuses data pushes on live clients). */
+  onClientsChanged?: (n: number) => void;
+}
+
+interface WsSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+
+export class DevToolsServer {
+  private port = 0;
+  private token = randomBytes(16).toString("hex");
+  private server: { port: number; stop(): void; upgrade(req: Request, opts?: unknown): boolean } | null = null;
+  private sockets = new Set<WsSocket>();
+  private opts: DevToolsServerOptions;
+  private cleanupPid: (() => void) | null = null;
+  private nextId = 1;
+
+  constructor(opts: DevToolsServerOptions = {}) {
+    this.opts = opts;
+  }
+
+  /** The websocket-capable URL handed to the browser launcher. */
+  get url(): string {
+    return `http://127.0.0.1:${this.port}/?t=${this.token}`;
+  }
+
+  get clientCount(): number { return this.sockets.size; }
+
+  async start(): Promise<void> {
+    if (this.server) return;
+    const BunG = (globalThis as Record<string, unknown>).Bun;
+    if (!BunG || typeof (BunG as { serve?: unknown }).serve !== "function") {
+      throw new Error("DevToolsServer requires Bun.serve (Bun runtime)");
+    }
+    const webRoot = this.opts.webRoot ?? join(
+      dirname(fileURLToPath(import.meta.url)), "../../../../../devtools-web",
+    );
+    const srv = (BunG as {
+      serve(o: Record<string, unknown>): { port: number; stop(): void; upgrade(r: Request, o?: unknown): boolean };
+    }).serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: (req: Request, server: { upgrade(r: Request, o?: unknown): boolean }) => {
+        const url = new URL(req.url);
+        // ── WS upgrade (token via query — browsers can't set headers on WS) ──
+        if (url.pathname === "/ws") {
+          if (url.searchParams.get("t") !== this.token) {
+            return new Response("unauthorized", { status: 401 });
+          }
+          if (server.upgrade(req, { data: {} })) return undefined as unknown as Response;
+          return new Response("upgrade failed", { status: 400 });
+        }
+        if (url.pathname === "/health") {
+          return Response.json({ status: "ok", clients: this.sockets.size, port: this.port });
+        }
+        // ── Static: extra routes (generated) then webRoot files ──
+        const extra = this.opts.extraRoutes?.[url.pathname];
+        if (extra !== undefined) {
+          return new Response(extra, { headers: { "content-type": "text/css; charset=utf-8" } });
+        }
+        let rel = url.pathname === "/" ? "/index.html" : url.pathname;
+        rel = normalize(rel);
+        if (rel.includes("..")) return new Response("no", { status: 403 });
+        const file = join(webRoot, rel);
+        if (!existsSync(file)) return new Response("not found", { status: 404 });
+        const body = readFileSync(file);
+        return new Response(body, {
+          headers: { "content-type": MIME[extname(file)] ?? "application/octet-stream" },
+        });
+      },
+      websocket: {
+        open: (ws: WsSocket) => {
+          this.sockets.add(ws);
+          this.opts.onClientsChanged?.(this.sockets.size);
+          ws.send(JSON.stringify({ event: "hello", data: this.helloData() }));
+        },
+        message: async (ws: WsSocket, raw: string | Buffer) => {
+          let msg: { id?: number; method?: string; params?: Record<string, unknown> };
+          try {
+            msg = JSON.parse(String(raw));
+          } catch {
+            ws.send(JSON.stringify({ id: 0, error: { message: "parse error" } }));
+            return;
+          }
+          if (!msg.method) return;
+          const id = msg.id ?? this.nextId++;
+          try {
+            const result = await this.callRpc(msg.method, msg.params ?? {});
+            ws.send(JSON.stringify({ id, result }));
+          } catch (err) {
+            ws.send(JSON.stringify({ id, error: { message: String(err) } }));
+          }
+        },
+        close: (ws: WsSocket) => {
+          this.sockets.delete(ws);
+          this.opts.onClientsChanged?.(this.sockets.size);
+        },
+      },
+    });
+    this.server = srv;
+    this.port = srv.port;
+    this.writeDiscoveryFile();
+    log.info("DevToolsServer", `devtools at ${this.url}`);
+  }
+
+  private helloData(): Record<string, unknown> {
+    const hello = (this.opts as { hello?: () => Record<string, unknown> }).hello;
+    return hello?.() ?? { version: 1 };
+  }
+
+  /** Provide the "hello" payload producer (panel list, inspector methods). */
+  setHello(fn: () => Record<string, unknown>): void {
+    (this.opts as { hello?: () => Record<string, unknown> }).hello = fn;
+  }
+
+  private async callRpc(method: string, params: Record<string, unknown>): Promise<unknown> {
+    if (method === "ping") return "pong";
+    if (!this.opts.call) throw new Error(`no dispatcher for ${method}`);
+    return this.opts.call(method, params);
+  }
+
+  /** Push an event to every connected client. */
+  emit(event: string, data: unknown): void {
+    if (this.sockets.size === 0) return;
+    const msg = JSON.stringify({ event, data });
+    this.sockets.forEach((ws) => {
+      try { ws.send(msg); } catch { /* dropping client errors */ }
+    });
+  }
+
+  private writeDiscoveryFile(): void {
+    const dir = join(homedir(), ".downdraft", "devtools");
+    try {
+      mkdirSync(dir, { recursive: true });
+      const file = join(dir, `${process.pid}.json`);
+      writeFileSync(file, JSON.stringify({
+        pid: process.pid, port: this.port, token: this.token,
+        url: this.url, startedAt: Date.now(),
+      }), { mode: 0o600 });
+      this.cleanupPid = () => { try { unlinkSync(file); } catch { /* gone */ } };
+    } catch (err) {
+      log.warn("DevToolsServer", `discovery file failed: ${err}`);
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.sockets.forEach((ws) => { try { ws.close(); } catch { /* ignore */ } });
+    this.sockets.clear();
+    try { this.server?.stop(); } catch { /* ignore */ }
+    this.server = null;
+    this.cleanupPid?.();
+    this.cleanupPid = null;
+  }
+}

package/libraries/entities/README.md

@@ -0,0 +1,17 @@
+# `@downdraft/engine/libraries/entities`
+
+Generic entity rendering — ModelRenderer and entity-display plumbing shared by games (EntitiesLib descriptor).
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/entities
+```
+
+## Key exports
+
+- `EntitiesLib`
+- `ModelRenderer`
+- `ModelRendererTok`
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/libraries/entities/src/index.ts

@@ -0,0 +1,4 @@
+export { ModelRenderer } from "./model-renderer";
+
+// Engine library descriptor
+export { EntitiesLib, ModelRendererTok, type EntitiesLibConfig } from "./library";