@downdraft/engine 0.0.0 → 0.1.1

package/libraries/devtools/src/cdp-bridge.ts

@@ -0,0 +1,349 @@
+// ============================================================================
+// cdp-bridge.ts — Chrome DevTools Protocol bridge via Bun's node:inspector.
+//
+// Wraps a node:inspector Session connected to the current (main) isolate.
+// Captures console API calls + uncaught exceptions (Runtime domain) and
+// provides CPU profiling via the Profiler domain.
+//
+// Verified in Bun 1.4.0:
+//   ✅ Runtime.enable + Runtime.consoleAPICalled + Runtime.exceptionThrown
+//   ✅ Profiler.enable + Profiler.setSamplingInterval + Profiler.start/stop
+//   ❌ Performance.* (not found)
+//   ❌ HeapProfiler.* (not found)
+//   ❌ Runtime.getHeapUsage (returns undefined)
+//
+// The session connects to the MAIN isolate only. The sim worker (separate
+// process) is not captured here — per-worker metrics come from the
+// ProfilingSAB (see perf-metrics panel).
+// ============================================================================
+
+// node:inspector is a Node/Bun built-in. Use createRequire (ESM-safe) so the
+// import doesn't fail at typecheck time in environments without the module.
+// At runtime in Bun, `require("node:inspector")` returns the inspector API.
+import { createLogger } from "@downdraft/engine/util/logger";
+import { createRequire as nodeCreateRequire } from "node:module";
+
+const log = createLogger("info");
+
+let insp: any;
+try {
+  // ESM-safe require shim — works in Node ESM, Bun, and CommonJS.
+  let requireFn: any = null;
+  if (typeof (globalThis as any).require === "function") {
+    // Bun and CommonJS have a global require.
+    requireFn = (globalThis as any).require;
+  } else {
+    // Node ESM: use createRequire from node:module.
+    requireFn = nodeCreateRequire(import.meta.url);
+  }
+  insp = requireFn("node:inspector");
+} catch {
+  insp = null;
+}
+
+// ── Types ──
+
+export type ConsoleType = "log" | "info" | "warn" | "warning" | "error" | "debug" | "trace" | "dir" | "assert";
+
+export interface CdpRemoteObject {
+  type: string;        // "string" | "number" | "boolean" | "object" | "undefined" | "function"
+  value?: any;
+  description?: string;
+  subtype?: string;
+  className?: string;
+  objectId?: string;
+  unserializableValue?: string;
+}
+
+export interface CdpConsoleEntry {
+  id: number;
+  type: ConsoleType;
+  text: string;          // serialized message
+  args: CdpRemoteObject[];
+  timestamp: number;     // performance.now() at capture
+  source: string;        // "console-api" | "exception" | etc.
+  stack?: string;        // for exceptions / expanded entries
+  url?: string;
+  line?: number;
+  column?: number;
+}
+
+export interface CdpException {
+  id: number;
+  text: string;
+  stack: string;
+  timestamp: number;
+  url?: string;
+  line?: number;
+  column?: number;
+}
+
+export interface CdpProfileNode {
+  id: number;
+  callFrame: {
+    functionName: string;
+    scriptId: string;
+    url: string;
+    lineNumber: number;
+    columnNumber: number;
+  };
+  hitCount: number;
+  children: number[];
+  positionTicks?: { line: number; ticks: number }[];
+}
+
+export interface CdpProfile {
+  nodes: CdpProfileNode[];
+  startTime: number;   // microseconds
+  endTime: number;     // microseconds
+  samples: number[];   // node ids
+  timeDeltas: number[]; // microseconds between samples
+  // Derived (computed by stopProfile):
+  totalDurationUs?: number;
+  nodeCount?: number;
+  sampleCount?: number;
+}
+
+// ── CdpBridge ──
+
+type ConsoleCallback = (entry: CdpConsoleEntry) => void;
+type ExceptionCallback = (exc: CdpException) => void;
+
+const MAX_ENTRIES = 1000;
+
+export class CdpBridge {
+  private session: any = null;
+  private connected = false;
+  private consoleCallbacks = new Set<ConsoleCallback>();
+  private exceptionCallbacks = new Set<ExceptionCallback>();
+  private entries: CdpConsoleEntry[] = [];
+  private exceptions: CdpException[] = [];
+  private entryCounter = 0;
+  private profiling = false;
+  private lastProfile: CdpProfile | null = null;
+  private available = false;
+
+  constructor() {
+    if (!insp || typeof insp.Session !== "function") {
+      this.available = false;
+      return;
+    }
+    this.available = true;
+  }
+
+  /** Whether the node:inspector module is available. */
+  get isAvailable(): boolean { return this.available; }
+
+  /** Connect the session and enable Runtime + Profiler domains. */
+  start(): void {
+    if (!this.available || this.connected) return;
+    try {
+      this.session = new insp.Session();
+      this.session.connect();
+      this.connected = true;
+      log.info("CdpBridge", "Session connected, enabling domains...");
+
+      // Wire event handlers BEFORE enabling domains so we don't miss events.
+      this.session.on("Runtime.consoleAPICalled", (e: any) => {
+        this.handleConsole(e.params);
+      });
+      this.session.on("Runtime.exceptionThrown", (e: any) => {
+        this.handleException(e.params);
+      });
+
+      // Enable domains (callbacks are optional; events fire via .on()).
+      this.post("Runtime.enable", {});
+      this.post("Profiler.enable", {});
+    } catch (err) {
+      log.warn("CdpBridge", `Failed to connect session: ${err}`);
+      this.available = false;
+      this.connected = false;
+    }
+  }
+
+  /** Subscribe to console entries. Returns an unsubscribe function. */
+  onConsole(cb: ConsoleCallback): () => void {
+    this.consoleCallbacks.add(cb);
+    return () => { this.consoleCallbacks.delete(cb); };
+  }
+
+  /** Subscribe to exceptions. Returns an unsubscribe function. */
+  onException(cb: ExceptionCallback): () => void {
+    this.exceptionCallbacks.add(cb);
+    return () => { this.exceptionCallbacks.delete(cb); };
+  }
+
+  /** Get all buffered console entries (newest last). */
+  getEntries(): CdpConsoleEntry[] { return this.entries; }
+
+  /** Get all buffered exceptions (newest last). */
+  getExceptions(): CdpException[] { return this.exceptions; }
+
+  /** Clear buffered console entries + exceptions. */
+  clear(): void {
+    this.entries = [];
+    this.exceptions = [];
+  }
+
+  /** Start CPU profiling. */
+  startProfile(intervalUs = 100): void {
+    if (!this.connected || this.profiling) {
+      log.info("CdpBridge", `startProfile skipped: connected=${this.connected} profiling=${this.profiling}`);
+      return;
+    }
+    this.profiling = true;
+    log.info("CdpBridge", "Starting CPU profile...");
+    this.post("Profiler.setSamplingInterval", { interval: intervalUs });
+    this.post("Profiler.start", {});
+  }
+
+  /** Stop CPU profiling and return the profile. */
+  stopProfile(): Promise<CdpProfile | null> {
+    if (!this.connected || !this.profiling) {
+      log.info("CdpBridge", `stopProfile skipped: connected=${this.connected} profiling=${this.profiling}`);
+      return Promise.resolve(null);
+    }
+    this.profiling = false;
+    log.info("CdpBridge", "Stopping CPU profile...");
+    return new Promise((resolve) => {
+      this.session.post("Profiler.stop", (_err: any, res: any) => {
+        if (_err || !res?.profile) {
+          log.warn("CdpBridge", `Profiler.stop error: ${_err} res: ${JSON.stringify(res)}`);
+          resolve(null);
+          return;
+        }
+        const prof: CdpProfile = res.profile;
+        prof.totalDurationUs = prof.endTime - prof.startTime;
+        prof.nodeCount = prof.nodes?.length ?? 0;
+        prof.sampleCount = prof.samples?.length ?? 0;
+        this.lastProfile = prof;
+        log.info("CdpBridge", `Profile received: ${prof.nodeCount} nodes, ${prof.sampleCount} samples`);
+        resolve(prof);
+      });
+    });
+  }
+
+  /** Whether currently profiling. */
+  isProfiling(): boolean { return this.profiling; }
+
+  /** The last recorded profile (null if none). */
+  getLastProfile(): CdpProfile | null { return this.lastProfile; }
+
+  /** Evaluate an expression (Runtime.evaluate). Stretch goal. */
+  evaluate(expr: string): Promise<{ result?: any; error?: string }> {
+    if (!this.connected) return Promise.resolve({ error: "not connected" });
+    return new Promise((resolve) => {
+      this.session.post("Runtime.evaluate", {
+        expression: expr,
+        returnByValue: true,
+      }, (_err: any, res: any) => {
+        if (_err) { resolve({ error: String(_err) }); return; }
+        if (res?.exceptionDetails) {
+          resolve({ error: res.exceptionDetails.text ?? res.exceptionDetails.exception?.description ?? "eval error" });
+          return;
+        }
+        resolve({ result: res?.result?.value });
+      });
+    });
+  }
+
+  /** Disconnect + cleanup. */
+  dispose(): void {
+    if (this.profiling) {
+      try { this.session?.post("Profiler.stop", {}); } catch { /* ignore */ }
+      this.profiling = false;
+    }
+    if (this.connected) {
+      try { this.session?.disconnect(); } catch { /* ignore */ }
+      this.connected = false;
+    }
+    this.consoleCallbacks.clear();
+    this.exceptionCallbacks.clear();
+    this.entries = [];
+    this.exceptions = [];
+    this.session = null;
+  }
+
+  // ── Internal ──
+
+  private post(method: string, params: any): void {
+    if (!this.session) return;
+    try {
+      this.session.post(method, params, () => {});
+    } catch {
+      // Some methods may not be available in all runtimes; ignore.
+    }
+  }
+
+  private handleConsole(params: any): void {
+    const type = (params.type ?? "log") as ConsoleType;
+    const args: CdpRemoteObject[] = (params.args ?? []).map((a: any) => ({
+      type: a.type,
+      value: a.value,
+      description: a.description,
+      subtype: a.subtype,
+      className: a.className,
+      objectId: a.objectId,
+      unserializableValue: a.unserializableValue,
+    }));
+    const text = args.map((a) => this.serializeArg(a)).join(" ");
+    const entry: CdpConsoleEntry = {
+      id: ++this.entryCounter,
+      type,
+      text,
+      args,
+      timestamp: performance.now(),
+      source: params.executionContextId !== undefined ? "console-api" : "console-api",
+      url: params.stackTrace?.callFrames?.[0]?.url,
+      line: params.stackTrace?.callFrames?.[0]?.lineNumber,
+      column: params.stackTrace?.callFrames?.[0]?.columnNumber,
+    };
+    this.entries.push(entry);
+    if (this.entries.length > MAX_ENTRIES) this.entries.shift();
+    for (const cb of this.consoleCallbacks.values()) {
+      try { cb(entry); } catch { /* ignore callback errors */ }
+    }
+  }
+
+  private handleException(params: any): void {
+    const details = params.exceptionDetails ?? {};
+    const exc: CdpException = {
+      id: ++this.entryCounter,
+      text: details.text ?? "Uncaught exception",
+      stack: details.exception?.description ?? details.stackTrace?.callFrames?.map(
+        (f: any) => `  at ${f.functionName ?? "<anon>"} (${f.url}:${f.lineNumber}:${f.columnNumber})`,
+      ).join("\n") ?? "",
+      timestamp: performance.now(),
+      url: details.stackTrace?.callFrames?.[0]?.url ?? details.url,
+      line: details.stackTrace?.callFrames?.[0]?.lineNumber ?? details.lineNumber,
+      column: details.stackTrace?.callFrames?.[0]?.columnNumber ?? details.columnNumber,
+    };
+    this.exceptions.push(exc);
+    if (this.exceptions.length > MAX_ENTRIES) this.exceptions.shift();
+    for (const cb of this.exceptionCallbacks.values()) {
+      try { cb(exc); } catch { /* ignore */ }
+    }
+  }
+
+  private serializeArg(arg: CdpRemoteObject): string {
+    if (arg.unserializableValue) return arg.unserializableValue;
+    if (arg.type === "string") return String(arg.value ?? "");
+    if (arg.type === "number") return String(arg.value ?? arg.description ?? "");
+    if (arg.type === "boolean") return String(arg.value ?? "");
+    if (arg.type === "undefined") return "undefined";
+    if (arg.type === "function") return `[Function ${arg.className ?? "anonymous"}]`;
+    if (arg.type === "object") {
+      if (arg.subtype === "null") return "null";
+      if (arg.subtype === "array") return arg.description ?? "[Array]";
+      if (arg.subtype === "date") return arg.description ?? "[Date]";
+      if (arg.subtype === "error") return arg.description ?? "[Error]";
+      if (arg.subtype === "regexp") return arg.description ?? "[RegExp]";
+      // Try to show the value if it was returned by value
+      if (arg.value !== undefined && arg.value !== null) {
+        try { return JSON.stringify(arg.value); } catch { return arg.description ?? "[Object]"; }
+      }
+      return arg.description ?? arg.className ?? "[Object]";
+    }
+    return arg.description ?? String(arg.value ?? "");
+  }
+}

package/libraries/devtools/src/collectors.ts

@@ -0,0 +1,346 @@
+// ============================================================================
+// collectors.ts — transport-agnostic devtools data collection.
+//
+// The egui mirror encodes these results and pushes them over FFI; the web
+// mirror sends them as JSON over the devtools WebSocket. Collection is
+// identical either way — this module is the single source of truth.
+// ============================================================================
+
+import type { CdpProfile } from "./cdp-bridge";
+
+export interface CollectorContext {
+  renderer: any;
+  gameScene?: any;
+  profilingSAB: SharedArrayBuffer | null;
+}
+
+export interface ThreadInfo { id: string; name: string; kind: number }
+export interface TreeRow {
+  id: number; parentId: number; depth: number; childCount: number;
+  kind: number; label: string; detail: string;
+}
+export interface GpuInfoJson {
+  entries: { key: string; value: string; isHeader: boolean }[];
+  frameTimes: [number, number][];
+  memHistory: number[];
+}
+export interface MetricsSlot {
+  slotIndex: number; name: string; runtime: number;
+  history: {
+    cpuPercent: number; heapUsed: number; heapTotal: number;
+    gcPauseMaxUs: number; taskLatencyP95Us: number;
+  }[];
+}
+export interface ProfileJson {
+  nodes: { id: number; hitCount: number; callFrame: string; url: string; line: number; children: number[] }[];
+  startUs: number; endUs: number;
+  samples: number[]; timeDeltasUs: number[];
+}
+
+// Lazy-load the ProfilingSAB reader (avoids importing @downdraft/engine/profiling
+// at module load time; it may not be available in all contexts).
+let profilingMod: any = undefined;
+async function loadProfilingMod(): Promise<any> {
+  if (profilingMod !== undefined) return profilingMod;
+  try {
+    profilingMod = await import("@downdraft/engine/profiling");
+  } catch {
+    profilingMod = null;
+  }
+  return profilingMod;
+}
+
+function formatBytes(bytes: any): string {
+  const b = typeof bytes === "bigint" ? Number(bytes) : bytes;
+  if (!b || b < 0 || !Number.isFinite(b)) return String(bytes);
+  if (b < 1024) return `${b} B`;
+  if (b < 1024 * 1024) return `${(b / 1024).toFixed(1)} KB`;
+  if (b < 1024 * 1024 * 1024) return `${(b / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(b / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/** Thread list: main + ProfilingSAB worker slots + registered eval threads. */
+export async function collectThreads(
+  ctx: CollectorContext,
+  evalThreadIds: string[],
+): Promise<ThreadInfo[]> {
+  const threads: ThreadInfo[] = [{ id: "main", name: "main", kind: 0 }];
+  if (ctx.profilingSAB) {
+    try {
+      const mod = await loadProfilingMod();
+      if (mod) {
+        const { ProfilingSABReader, computeProfilingSABLayout } = mod;
+        const layout = computeProfilingSABLayout();
+        if (ctx.profilingSAB.byteLength >= layout.byteLength) {
+          const reader = new ProfilingSABReader(ctx.profilingSAB, layout);
+          const snapshot = reader.readSnapshot();
+          snapshot.slots.forEach((slot: any) => {
+            threads.push({
+              id: `slot-${slot.slotIndex}`,
+              name: slot.name || `worker-${slot.slotIndex}`,
+              kind: 1,
+            });
+          });
+        }
+      }
+    } catch { /* profiling unavailable */ }
+  }
+  evalThreadIds.forEach((id) => {
+    if (!threads.find((t) => t.id === id)) threads.push({ id, name: id, kind: 1 });
+  });
+  return threads;
+}
+
+/** Scene-graph tree (label + ctor + child counts). */
+export function collectSceneTree(ctx: CollectorContext): TreeRow[] {
+  const stage = ctx.gameScene?.stage;
+  if (!stage) return [];
+  const nodes: TreeRow[] = [];
+  let idCounter = 1;
+  const collect = (node: any, parentId: number, depth: number): void => {
+    const id = idCounter++;
+    // Prefer `label` (some scene-graph hosts warn on `name` access); fall
+    // back to `name` for hosts that only set that.
+    const nodeLabel = typeof node.label === "string" ? node.label
+      : typeof node.name === "string" ? node.name : "";
+    const ctorName = node.constructor?.name ?? "Node";
+    nodes.push({
+      id, parentId, depth,
+      childCount: node.children?.length ?? 0,
+      kind: 0,
+      label: nodeLabel || ctorName,
+      detail: nodeLabel ? ctorName : "",
+    });
+    node.children?.forEach((child: any) => collect(child, id, depth + 1));
+  };
+  collect(stage, -1, 0);
+  return nodes;
+}
+
+/** DOM tree: scene-graph stage or ECS entities depending on mode. */
+export function collectDomTree(ctx: CollectorContext, mode: "scene" | "ecs"): TreeRow[] {
+  if (mode === "scene") return collectSceneTree(ctx);
+  const simReader = ctx.renderer?.simReader ?? ctx.renderer?.getSimReader?.();
+  if (!simReader?.isValid?.()) return [];
+  const nodes: TreeRow[] = [];
+  let idCounter = 1;
+  try {
+    simReader.getEntityCount();
+    const iter = simReader.iterEntities?.();
+    iter?.forEach((ent: any) => {
+      const id = idCounter++;
+      const f32 = ent.f32;
+      const u32 = ent.u32;
+      const entityType = u32?.[0] ?? 0;
+      const x = f32?.[0] ?? 0;
+      const y = f32?.[1] ?? 0;
+      const z = f32?.[2] ?? 0;
+      nodes.push({
+        id, parentId: -1, depth: 0, childCount: 0, kind: 1,
+        label: `Entity ${ent.idx}`,
+        detail: `type=${entityType} pos=(${x.toFixed(1)},${y.toFixed(1)},${z.toFixed(1)})`,
+      });
+    });
+  } catch { /* sim reader hiccup */ }
+  return nodes;
+}
+
+/** GPU adapter/limits/telemetry/resources/pass-timings as key-value entries. */
+export function collectGpuInfo(ctx: CollectorContext): GpuInfoJson {
+  const r = ctx.renderer;
+  const entries: { key: string; value: string; isHeader: boolean }[] = [];
+  try {
+    const adapterInfo = r?.getAdapterInfo?.() ?? r?.gpuProfiler?.getAdapterInfo?.() ?? {};
+    entries.push({ key: "GPU Adapter Info", value: "", isHeader: true });
+    entries.push({ key: "Vendor", value: adapterInfo.vendor ?? "?", isHeader: false });
+    entries.push({ key: "Architecture", value: adapterInfo.architecture ?? "?", isHeader: false });
+    entries.push({ key: "Description", value: adapterInfo.description ?? "?", isHeader: false });
+    entries.push({ key: "Device", value: adapterInfo.device ?? "?", isHeader: false });
+
+    const device = r?.getDevice?.() ?? r?.device;
+    const limits = device?.limits;
+    if (limits) {
+      entries.push({ key: "Device Limits", value: "", isHeader: true });
+      const maxBuf = limits.maxBufferSize;
+      const maxBufNum = typeof maxBuf === "bigint" ? Number(maxBuf) : maxBuf;
+      const maxBufDisplay = maxBufNum > 4 * 1024 * 1024 * 1024 ? "4 GB (capped)" : formatBytes(maxBuf);
+      entries.push({ key: "maxBufferSize", value: maxBufDisplay, isHeader: false });
+      entries.push({ key: "maxTextureDim2D", value: String(limits.maxTextureDimension2D), isHeader: false });
+      entries.push({ key: "maxTextureDim3D", value: String(limits.maxTextureDimension3D), isHeader: false });
+      entries.push({ key: "maxTextureArrayLayers", value: String(limits.maxTextureArrayLayers), isHeader: false });
+      entries.push({ key: "maxStorageBuffer", value: formatBytes(limits.maxStorageBufferBindingSize), isHeader: false });
+      entries.push({ key: "maxUniformBuffer", value: formatBytes(limits.maxUniformBufferBindingSize), isHeader: false });
+      entries.push({ key: "maxBindGroups", value: String(limits.maxBindGroups), isHeader: false });
+      entries.push({ key: "maxVertexAttributes", value: String(limits.maxVertexAttributes), isHeader: false });
+      entries.push({ key: "maxVertexBuffers", value: String(limits.maxVertexBuffers), isHeader: false });
+      entries.push({ key: "maxColorAttachments", value: String(limits.maxColorAttachments), isHeader: false });
+      entries.push({ key: "maxComputeWorkgroupsPerDimension", value: String(limits.maxComputeWorkgroupsPerDimension), isHeader: false });
+    }
+
+    const telemetry = r?.telemetryCollector;
+    if (telemetry?.getFrameTelemetry) {
+      const ft = telemetry.getFrameTelemetry();
+      if (ft) {
+        entries.push({ key: "Frame Performance", value: "", isHeader: true });
+        entries.push({ key: "FPS", value: String(Math.round(ft.fps ?? 0)), isHeader: false });
+        entries.push({ key: "Avg frame time", value: `${(ft.avgFrameTime ?? 0).toFixed(2)} ms`, isHeader: false });
+        entries.push({ key: "P95 frame time", value: `${(ft.p95 ?? 0).toFixed(2)} ms`, isHeader: false });
+        entries.push({ key: "P99 frame time", value: `${(ft.p99 ?? 0).toFixed(2)} ms`, isHeader: false });
+        entries.push({ key: "GPU time", value: `${(ft.gpuTimeMs ?? 0).toFixed(2)} ms`, isHeader: false });
+        entries.push({ key: "Draw calls", value: String(ft.drawCalls ?? 0), isHeader: false });
+        entries.push({ key: "Triangles", value: String(ft.triangles ?? 0), isHeader: false });
+      }
+    }
+
+    const resTracker = r?.gpuResourceTracker;
+    if (resTracker?.getStats) {
+      const stats = resTracker.getStats();
+      entries.push({ key: "GPU Resources", value: "", isHeader: true });
+      entries.push({ key: "Textures", value: String(stats.textureCount), isHeader: false });
+      entries.push({ key: "Buffers", value: String(stats.bufferCount), isHeader: false });
+      entries.push({ key: "Texture VRAM", value: formatBytes(stats.textureBytes), isHeader: false });
+      entries.push({ key: "Buffer VRAM", value: formatBytes(stats.bufferBytes), isHeader: false });
+      entries.push({ key: "Total VRAM", value: formatBytes(stats.totalBytes), isHeader: false });
+      const topResources = (stats.resources ?? []).slice(0, 15);
+      if (topResources.length > 0) {
+        entries.push({ key: "Top Resources", value: "", isHeader: true });
+        topResources.forEach((res: any) => {
+          entries.push({
+            key: res.label ?? res.type ?? "resource",
+            value: `${res.type} ${formatBytes(res.size)} ${res.dims ?? ""}`.trim(),
+            isHeader: false,
+          });
+        });
+      }
+    }
+
+    const profiler = r?.gpuProfiler;
+    if (profiler?.getPassTimings) {
+      const timings = profiler.getPassTimings();
+      if (timings.length > 0) {
+        entries.push({ key: "Per-Pass GPU Timing", value: "", isHeader: true });
+        timings.forEach((t: any) => {
+          const gpu = t.gpuMs > 0 ? `gpu=${t.gpuMs.toFixed(2)}ms` : "";
+          entries.push({
+            key: t.name ?? "pass",
+            value: `cpu=${t.cpuMs.toFixed(2)}ms ${gpu} draws=${t.drawCalls} tris=${t.triangles}`.trim(),
+            isHeader: false,
+          });
+        });
+      }
+    }
+
+    if (profiler?.getGPUErrors) {
+      const errors = profiler.getGPUErrors();
+      if (errors.length > 0) {
+        entries.push({ key: "GPU Errors", value: "", isHeader: true });
+        errors.forEach((e: any) => {
+          entries.push({ key: e.type ?? "error", value: e.message ?? String(e), isHeader: false });
+        });
+      }
+    }
+
+    const frameGraph = r?.frameGraph ?? r?.getFrameGraph?.();
+    if (frameGraph) {
+      const slots = frameGraph.getSlots?.() ?? frameGraph.getSlotRegistry?.()?.getAll?.() ?? [];
+      if (slots.length > 0) {
+        entries.push({ key: "Frame Graph Passes", value: "", isHeader: true });
+        slots.forEach((s: any) => {
+          const name = typeof s === "string" ? s : (s.name ?? s.label ?? "slot");
+          entries.push({ key: name, value: "", isHeader: false });
+        });
+      }
+    }
+  } catch (err) {
+    entries.push({ key: "Error", value: String(err), isHeader: false });
+  }
+
+  const frameTimes: [number, number][] = [];
+  const memHistory: number[] = [];
+  try {
+    const telemetry = r?.telemetryCollector;
+    if (telemetry?.getFrameTimes) {
+      const times = telemetry.getFrameTimes();
+      for (let i = Math.max(0, times.length - 120); i < times.length; i++) {
+        frameTimes.push([times[i], 0]);
+      }
+    }
+    const profiler = r?.gpuProfiler;
+    if (profiler?.getPassTimings) {
+      const timings = profiler.getPassTimings();
+      if (timings.length > 0 && frameTimes.length > 0) {
+        let gpuTotal = 0;
+        timings.forEach((t: any) => { gpuTotal += t.gpuMs ?? 0;; });
+        if (frameTimes.length > 0) frameTimes[frameTimes.length - 1][1] = gpuTotal;
+      }
+    }
+    const resTracker = r?.gpuResourceTracker;
+    if (resTracker?.getStats) memHistory.push(resTracker.getStats().totalBytes);
+  } catch { /* ignore */ }
+
+  return { entries, frameTimes, memHistory };
+}
+
+/** Per-thread metrics snapshot (main via performance.memory, workers via SAB). */
+export async function collectMetrics(ctx: CollectorContext): Promise<MetricsSlot[]> {
+  const slots: MetricsSlot[] = [{
+    slotIndex: 0,
+    name: "main",
+    runtime: 0,
+    history: [{
+      cpuPercent: 0,
+      heapUsed: (performance as any)?.memory?.usedJSHeapSize ?? 0,
+      heapTotal: (performance as any)?.memory?.totalJSHeapSize ?? 0,
+      gcPauseMaxUs: 0,
+      taskLatencyP95Us: 0,
+    }],
+  }];
+
+  if (ctx.profilingSAB) {
+    try {
+      const mod = await loadProfilingMod();
+      if (mod) {
+        const { ProfilingSABReader, computeProfilingSABLayout } = mod;
+        const layout = computeProfilingSABLayout();
+        if (ctx.profilingSAB.byteLength >= layout.byteLength) {
+          const reader = new ProfilingSABReader(ctx.profilingSAB, layout);
+          const snapshot = reader.readSnapshot();
+          snapshot.slots.forEach((slot: any) => {
+            slots.push({
+              slotIndex: slot.slotIndex,
+              name: slot.name || `worker-${slot.slotIndex}`,
+              runtime: slot.runtime ?? 0,
+              history: [{
+                cpuPercent: slot.metrics?.cpuPercent ?? 0,
+                heapUsed: slot.metrics?.heapUsed ?? 0,
+                heapTotal: slot.metrics?.heapTotal ?? 0,
+                gcPauseMaxUs: slot.metrics?.gcPauseMaxUs ?? 0,
+                taskLatencyP95Us: slot.metrics?.taskLatencyP95Us ?? 0,
+              }],
+            });
+          });
+        }
+      }
+    } catch { /* profiling unavailable */ }
+  }
+  return slots;
+}
+
+/** Normalize a CDP CPU profile into the shared JSON shape. */
+export function collectProfile(profile: CdpProfile): ProfileJson {
+  const nodes = (profile.nodes ?? []).map((n: any) => ({
+    id: n.id,
+    hitCount: n.hitCount ?? 0,
+    callFrame: n.callFrame?.functionName ?? "?",
+    url: n.callFrame?.url ?? "",
+    line: n.callFrame?.lineNumber ?? 0,
+    children: n.children ?? [],
+  }));
+  return {
+    nodes,
+    startUs: profile.startTime ?? 0,
+    endUs: profile.endTime ?? 0,
+    samples: profile.samples ?? [],
+    timeDeltasUs: profile.timeDeltas ?? [],
+  };
+}