@downdraft/engine 0.0.0 → 0.1.0

package/libraries/devtools/src/verify.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// verify.ts — Screenshot + pixel-verification + notify-send helpers.
+//
+// Used by the debugger to capture screenshots of the composited frame
+// (which includes the debug overlay) and verify panels render correctly
+// by sampling specific pixels.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import { existsSync } from "node:fs";
+
+const log = createLogger("info");
+
+// ── notify-send (Linux desktop notification) ──
+
+/** Send a Linux desktop notification via notify-send. */
+export function notify(title: string, body: string): void {
+  try {
+    const { execSync } = require("node:child_process");
+    execSync(`notify-send -a "Devin" -i dialog-information "${title.replace(/"/g, "'")}" "${body.replace(/"/g, "'")}"`, {
+      stdio: "ignore",
+      timeout: 5000,
+    });
+  } catch {
+    // ignore — notify-send may not be available in all environments
+  }
+}
+
+// ── PNG pixel reader (minimal, for verification) ──
+
+interface PngData {
+  width: number;
+  height: number;
+  rgba: Uint8Array;
+}
+
+/**
+ * Read a PNG file and return its pixel data. Uses node:zlib to inflate IDAT.
+ * Supports 8-bit RGBA (color type 6) and 8-bit RGB (color type 2) PNGs.
+ */
+export function readPng(path: string): PngData | null {
+  if (!existsSync(path)) return null;
+  const { readFileSync } = require("node:fs");
+  const { inflateSync } = require("node:zlib");
+  const buf: Buffer = readFileSync(path);
+  // Verify PNG signature
+  const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+  for (let i = 0; i < 8; i++) {
+    if (buf[i] !== sig[i]) return null;
+  }
+  let offset = 8;
+  let width = 0, height = 0, bitDepth = 0, colorType = 0;
+  let idatData: Buffer[] = [];
+  while (offset < buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString("ascii", offset + 4, offset + 8);
+    const dataStart = offset + 8;
+    if (type === "IHDR") {
+      width = buf.readUInt32BE(dataStart);
+      height = buf.readUInt32BE(dataStart + 4);
+      bitDepth = buf[dataStart + 8];
+      colorType = buf[dataStart + 9];
+    } else if (type === "IDAT") {
+      idatData.push(buf.subarray(dataStart, dataStart + length));
+    } else if (type === "IEND") {
+      break;
+    }
+    offset = dataStart + length + 4; // skip data + CRC
+  }
+  if (idatData.length === 0) return null;
+  const compressed = Buffer.concat(idatData);
+  const raw = inflateSync(compressed);
+  // Determine bytes per pixel
+  const bpp = colorType === 6 ? 4 : colorType === 2 ? 3 : 4;
+  const stride = width * bpp;
+  const rgba = new Uint8Array(width * height * 4);
+  let srcIdx = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[srcIdx++]; // filter byte (0 = none)
+    for (let x = 0; x < stride; x++) {
+      // For simplicity, only handle filter 0 (none). Most screenshots use it.
+      if (filter !== 0) {
+        // Defilter: Paeth for filter 4, etc. For now, copy raw (works for filter 0).
+      }
+      const byte = raw[srcIdx + x];
+      const px = Math.floor(x / bpp);
+      const channel = x % bpp;
+      const dstIdx = (y * width + px) * 4 + channel;
+      if (channel < 3) rgba[dstIdx] = byte;
+      else if (bpp === 4) rgba[dstIdx] = byte;
+      else rgba[dstIdx] = 255; // opaque for RGB
+    }
+    srcIdx += stride;
+  }
+  return { width, height, rgba };
+}
+
+// ── Pixel verification ──
+
+export interface PixelCheck {
+  x: number;
+  y: number;
+  /** [R, G, B, A] each 0-255. */
+  expected: number[];
+  /** Tolerance per channel. */
+  tolerance?: number;
+}
+
+/**
+ * Verify a pixel in a PNG file matches the expected RGBA within tolerance.
+ * Returns true if the pixel matches.
+ */
+export function verifyPixel(
+  pngPath: string,
+  x: number,
+  y: number,
+  expected: number[],
+  tolerance = 15,
+): boolean {
+  const png = readPng(pngPath);
+  if (!png) {
+    log.error("verify", `Could not read PNG: ${pngPath}`);
+    return false;
+  }
+  if (x < 0 || x >= png.width || y < 0 || y >= png.height) {
+    log.error("verify", `Pixel (${x},${y}) out of bounds (${png.width}x${png.height})`);
+    return false;
+  }
+  const idx = (y * png.width + x) * 4;
+  const actual = [png.rgba[idx], png.rgba[idx + 1], png.rgba[idx + 2], png.rgba[idx + 3]];
+  for (let i = 0; i < expected.length; i++) {
+    if (Math.abs(actual[i] - expected[i]) > tolerance) {
+      log.error(
+        "verify",
+        `Pixel (${x},${y}) channel ${i}: expected ${expected[i]}, got ${actual[i]} (tolerance ${tolerance})`,
+      );
+      return false;
+    }
+  }
+  log.info("verify", `Pixel (${x},${y}) OK: rgba(${actual.join(",")})`);
+  return true;
+}
+
+/**
+ * Run multiple pixel checks against a PNG. Returns the number of failures.
+ */
+export function verifyPixels(pngPath: string, checks: PixelCheck[]): number {
+  let failures = 0;
+  checks.forEach((check) => {
+    if (!verifyPixel(pngPath, check.x, check.y, check.expected, check.tolerance)) {
+      failures++;
+    }
+  });
+  return failures;
+}
+
+// ── Checkpoint (notify + screenshot path) ──
+
+/**
+ * Emit a checkpoint: notify the user + log. The caller is responsible for
+ * capturing the screenshot (the host's captureScreenshot method) and committing.
+ */
+export function checkpoint(name: string, screenshotPath?: string): void {
+  const body = screenshotPath ? `${name} — screenshot: ${screenshotPath}` : name;
+  notify("Devin Checkpoint", body);
+  log.info("checkpoint", body);
+}

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

@@ -0,0 +1,102 @@
+// ============================================================================
+// browser.ts — launches the devtools UI in a desktop browser.
+//
+// Priority: chromium-family with --app mode (chromeless window) first, then
+// anything else we can find. Falls back to the OS default opener.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import { spawn } from "node:child_process";
+
+const log = createLogger("info");
+
+interface BrowserCandidate {
+  names: string[];
+  /** App-window flag supported by chromium forks. */
+  appMode: boolean;
+}
+
+const CANDIDATES: BrowserCandidate[] = [
+  { names: ["chromium", "chromium-browser"], appMode: true },
+  { names: ["brave-browser", "brave"], appMode: true },
+  { names: ["vivaldi", "vivaldi-stable"], appMode: true },
+  { names: ["firefox"], appMode: false },
+  { names: ["google-chrome", "google-chrome-stable"], appMode: true },
+  { names: ["microsoft-edge", "msedge"], appMode: true },
+];
+
+function which(bin: string): string | null {
+  const dirs = (process.env.PATH ?? "").split(":");
+  for (let i = 0; i < dirs.length; i++) {
+    const p = `${dirs[i]}/${bin}`;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { accessSync, constants } = require("node:fs") as typeof import("node:fs");
+      accessSync(p, constants.X_OK);
+      return p;
+    } catch { /* next dir */ }
+  }
+  return null;
+}
+
+let resolved: { bin: string; appMode: boolean } | null | undefined;
+
+function resolveBrowser(): { bin: string; appMode: boolean } | null {
+  if (resolved !== undefined) return resolved;
+  const override = process.env.DOWNDRAFT_DEVTOOLS_BROWSER;
+  if (override) {
+    resolved = { bin: which(override) ?? override, appMode: override.includes("chrom") };
+    return resolved;
+  }
+  for (let i = 0; i < CANDIDATES.length; i++) {
+    const c = CANDIDATES[i];
+    for (let j = 0; j < c.names.length; j++) {
+      const bin = which(c.names[j]);
+      if (bin) {
+        resolved = { bin, appMode: c.appMode };
+        return resolved;
+      }
+    }
+  }
+  resolved = null;
+  return null;
+}
+
+/**
+ * Open `url` in the best available browser. Returns true if a process was
+ * spawned; false when no browser was found (caller should log the URL).
+ */
+export function openDevToolsUrl(url: string): boolean {
+  const b = resolveBrowser();
+  if (b) {
+    const args = b.appMode
+      ? [`--app=${url}`, "--disable-session-crashed-bubble", "--no-first-run"]
+      : [url];
+    try {
+      const child = spawn(b.bin, args, {
+        detached: true, stdio: "ignore",
+        env: { ...process.env },
+      });
+      child.unref();
+      child.on("error", (err) => {
+        log.warn("devtools-browser", `failed to launch ${b.bin}: ${err}`);
+      });
+      log.info("devtools-browser", `opened ${b.bin}`);
+      return true;
+    } catch (err) {
+      log.warn("devtools-browser", `spawn failed for ${b.bin}: ${err}`);
+    }
+  }
+  // OS default opener fallback.
+  const openers = ["xdg-open", "open"];
+  for (let i = 0; i < openers.length; i++) {
+    const bin = which(openers[i]);
+    if (!bin) continue;
+    try {
+      const child = spawn(bin, [url], { detached: true, stdio: "ignore" });
+      child.unref();
+      return true;
+    } catch { /* try next */ }
+  }
+  return false;
+}

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

@@ -0,0 +1,212 @@
+// ============================================================================
+// web/host.ts — WebDevtoolsHost: the web-based devtools backend.
+//
+// Drop-in replacement for NativeDebuggerHost (the egui overlay). Instead of
+// rendering an egui overlay into the frame, it runs a loopback devtools
+// server (Bun.serve: HTTP static + WS JSON-RPC) and opens the browser-based
+// devtools UI when toggled (F12).
+//
+// The host keeps the same public surface as NativeDebuggerHost —
+// `visible`, `toggle/show/hide`, `update()`, `devtoolsMirror`,
+// `debuggerScene`, `registerThreadEval`, `setPerfRecording`, input handlers
+// (all no-ops: a separate browser window receives input, nothing in-game) —
+// so native-entry.ts needs only the constructor swap.
+// ============================================================================
+
+import { createLogger } from "@downdraft/engine/util/logger";
+import { CdpBridge } from "../cdp-bridge";
+import { openDevToolsUrl } from "./browser";
+import { WebDevtoolsMirror } from "./mirror";
+import { DevToolsServer } from "./server";
+
+const log = createLogger("info");
+
+export interface WebDevtoolsOptions {
+  /** Shared wgpu-native GPUDevice (unused — kept for constructor parity). */
+  device: GPUDevice;
+  /** Shared GPUAdapter (unused — parity). */
+  adapter: GPUAdapter;
+  /** Swapchain format (unused — parity). */
+  targetFormat: GPUTextureFormat;
+  /** Overlay width (unused — parity). */
+  width: number;
+  /** Overlay height (unused — parity). */
+  height: number;
+  /** The game renderer (WebGPURenderer) — for GPU/scene data. */
+  renderer: unknown;
+  /** Optional scene-graph host (an object exposing `.stage` with
+   *  children/label) — feeds the scene tree panel. */
+  gameScene?: unknown;
+  /** Optional ProfilingSAB for per-worker performance metrics. */
+  profilingSAB?: SharedArrayBuffer | null;
+  /** Directory containing the devtools-web frontend (default: sibling package). */
+  webRoot?: string;
+  /** Extra static routes (e.g. "/kit.css" → generated kit stylesheet). */
+  extraRoutes?: Record<string, string>;
+}
+
+export class WebDevtoolsHost {
+  private opts: WebDevtoolsOptions;
+  private cdp: CdpBridge;
+  private server: DevToolsServer;
+  private mirror: WebDevtoolsMirror;
+  private sceneShim: WebDebuggerSceneShim;
+  private _ready = false;
+  private disposed = false;
+  private browserOpened = false;
+
+  constructor(opts: WebDevtoolsOptions) {
+    this.opts = opts;
+    this.cdp = new CdpBridge();
+    // The server's RPC dispatcher closes over `this.mirror` — assigned just
+    // below, before any client can connect.
+    this.server = new DevToolsServer({
+      webRoot: opts.webRoot,
+      extraRoutes: opts.extraRoutes,
+      call: (method, params) => this.mirror.dispatch(method, params),
+    });
+    this.mirror = new WebDevtoolsMirror({
+      server: this.server,
+      cdp: this.cdp,
+      renderer: opts.renderer,
+      gameScene: opts.gameScene,
+      profilingSAB: opts.profilingSAB ?? null,
+    });
+    this.sceneShim = new WebDebuggerSceneShim(this);
+  }
+
+  /** Whether the devtools UI is "visible" — i.e. a browser client is attached. */
+  get visible(): boolean { return this.server.clientCount > 0; }
+
+  get ready(): boolean { return this._ready; }
+  get cdpBridge(): CdpBridge { return this.cdp; }
+  get devtoolsMirror(): WebDevtoolsMirror { return this.mirror; }
+  get debuggerScene(): WebDebuggerSceneShim { return this.sceneShim; }
+  get app(): null { return null; }
+  /** The URL a browser would connect to (for tests / manual open). */
+  get url(): string { return this.server.url; }
+
+  /** Start the loopback server + mirror + CDP session. */
+  async start(): Promise<void> {
+    if (this._ready || this.disposed) return;
+    try {
+      await this.server.start();
+    } catch (err) {
+      log.warn("WebDevtoolsHost", `devtools server failed to start: ${err}`);
+      // Still bring up mirror/cdp so the RPC surface exists for embedded
+      // callers (e.g. tests); the browser UI just won't be reachable.
+    }
+    this.mirror.start();
+    this.mirror.attachLoggerBridge();
+    this.cdp.start();
+    this._ready = true;
+    log.info("WebDevtoolsHost", `Web devtools ready (F12 opens ${this.server.url})`);
+  }
+
+  /** F12: open (or refocus) the devtools browser window. */
+  toggle(): void {
+    if (!this._ready) return;
+    if (this.visible) {
+      // Already open — ask the frontend to close its window (it can only
+      // succeed if the window was script-opened, which --app mode satisfies
+      // on some browsers; worst case the user closes it normally).
+      this.server.emit("devtools.close", {});
+      log.info("WebDevtoolsHost", "Devtools close requested");
+      return;
+    }
+    this.open();
+  }
+
+  /** Open the devtools browser window (idempotent while a client is up). */
+  open(): void {
+    if (!this._ready) return;
+    if (this.visible) {
+      this.server.emit("devtools.focus", {});
+      return;
+    }
+    const url = this.server.url;
+    if (!url.includes(":0")) {
+      if (openDevToolsUrl(url)) {
+        this.browserOpened = true;
+        this.mirror.resetFirstUpdate();
+      } else {
+        log.warn("WebDevtoolsHost", `No browser found — open manually: ${url}`);
+      }
+    }
+  }
+
+  show(): void { this.open(); }
+  hide(): void { this.server.emit("devtools.close", {}); }
+
+  /** Per-frame pump (call from the render loop). */
+  update(_externalEncoder?: GPUCommandEncoder): void {
+    if (!this._ready || this.disposed) return;
+    try {
+      this.mirror.update();
+    } catch (err) {
+      log.error("WebDevtoolsHost", `mirror update error: ${err}`);
+    }
+  }
+
+  registerThreadEval(threadName: string, evalFn: (expr: string) => Promise<{ result?: unknown; error?: string }>): void {
+    this.mirror.registerThreadEval(threadName, evalFn);
+  }
+
+  /** Track the frontend's active panel (reported via inspector calls; best-effort). */
+  private activePanel = "";
+  setActivePanel(panel: string): void { this.activePanel = panel; }
+  getActivePanel(): string { return this.activePanel; }
+
+  setPerfRecording(start: boolean): void {
+    this.mirror.setPerfRecording(start);
+  }
+
+  // ── Input handlers: all no-ops (the devtools live in a separate window) ──
+  handlePointerDown(_x: number, _y: number, _button: number, _mods: number): boolean { return false; }
+  handlePointerMove(_x: number, _y: number, _button: number, _mods: number): boolean { return false; }
+  handlePointerUp(_x: number, _y: number, _button: number, _mods: number): boolean { return false; }
+  handleWheel(_x: number, _y: number, _deltaY: number): boolean { return false; }
+  handleTextInput(_text: string): boolean { return false; }
+  handleKeyDown(_key: string, _keyCode: number): boolean { return false; }
+  isTextInputActive(): boolean { return false; }
+  setModifiers(_alt: boolean, _ctrl: boolean, _shift: boolean): void { /* noop */ }
+  resize(_w: number, _h: number): void { /* browser window owns layout */ }
+
+  getUiTextureView(): GPUTextureView | null { return null; }
+  blit(_encoder: GPUCommandEncoder, _targetView: GPUTextureView): void { /* no overlay */ }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    try { this.mirror.dispose(); } catch { /* ignore */ }
+    try { this.cdp.dispose(); } catch { /* ignore */ }
+    void this.server.stop().catch(() => { /* ignore */ });
+    this._ready = false;
+    this.browserOpened = false;
+  }
+}
+
+/** `debuggerScene` compatibility shim for native-entry.ts call sites. */
+export class WebDebuggerSceneShim {
+  private host: WebDevtoolsHost;
+  constructor(host: WebDevtoolsHost) { this.host = host; }
+  registerThreadEval(threadName: string, evalFn: (expr: string) => Promise<{ result?: unknown; error?: string }>): void {
+    this.host.registerThreadEval(threadName, evalFn);
+  }
+  setActivePanel(panel: string): void { this.host.setActivePanel(panel); }
+  getActivePanel(): string { return this.host.getActivePanel(); }
+  setPerfRecording(start: boolean): void { this.host.setPerfRecording(start); }
+  // Legacy DEBUGGER_TEST stubs (the web UI is tested via WS, not clicks).
+  handlePointerDown(_x: number, _y: number): boolean { return false; }
+  handlePointerUp(_x: number, _y: number): boolean { return false; }
+  handlePointerMove(_x: number, _y: number): boolean { return false; }
+  handleWheel(_x: number, _y: number, _d: number): boolean { return false; }
+  handleKeyDown(_k: string, _kc: number): boolean { return false; }
+  handleTextInput(_t: string): boolean { return false; }
+  isTextInputActive(): boolean { return false; }
+  getFocusedWidget(): string | null { return null; }
+  getConsoleReplInput(): string { return ""; }
+  getDockX(): number { return 0; }
+  get dockWidth(): number { return 0; }
+  getHits(): { regions: unknown[] } { return { regions: [] }; }
+}