@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/libraries/devtools/src/cdp-bridge.js

@@ -0,0 +1,293 @@
+// ============================================================================
+// 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;
+try {
+    // ESM-safe require shim — works in Node ESM, Bun, and CommonJS.
+    let requireFn = null;
+    if (typeof globalThis.require === "function") {
+        // Bun and CommonJS have a global require.
+        requireFn = globalThis.require;
+    }
+    else {
+        // Node ESM: use createRequire from node:module.
+        requireFn = nodeCreateRequire(import.meta.url);
+    }
+    insp = requireFn("node:inspector");
+}
+catch {
+    insp = null;
+}
+const MAX_ENTRIES = 1000;
+export class CdpBridge {
+    session = null;
+    connected = false;
+    consoleCallbacks = new Set();
+    exceptionCallbacks = new Set();
+    entries = [];
+    exceptions = [];
+    entryCounter = 0;
+    profiling = false;
+    lastProfile = null;
+    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() { return this.available; }
+    /** Connect the session and enable Runtime + Profiler domains. */
+    start() {
+        if (!this.available || this.connected)
+            return;
+        try {
+            this.session = new insp.Session();
+            this.session.connect();
+            this.connected = true;
+            log.info("cdp-bridge", "Session connected, enabling domains...");
+            // Wire event handlers BEFORE enabling domains so we don't miss events.
+            this.session.on("Runtime.consoleAPICalled", (e) => {
+                this.handleConsole(e.params);
+            });
+            this.session.on("Runtime.exceptionThrown", (e) => {
+                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("cdp-bridge", `Failed to connect session: ${err}`);
+            this.available = false;
+            this.connected = false;
+        }
+    }
+    /** Subscribe to console entries. Returns an unsubscribe function. */
+    onConsole(cb) {
+        this.consoleCallbacks.add(cb);
+        return () => { this.consoleCallbacks.delete(cb); };
+    }
+    /** Subscribe to exceptions. Returns an unsubscribe function. */
+    onException(cb) {
+        this.exceptionCallbacks.add(cb);
+        return () => { this.exceptionCallbacks.delete(cb); };
+    }
+    /** Get all buffered console entries (newest last). */
+    getEntries() { return this.entries; }
+    /** Get all buffered exceptions (newest last). */
+    getExceptions() { return this.exceptions; }
+    /** Clear buffered console entries + exceptions. */
+    clear() {
+        this.entries = [];
+        this.exceptions = [];
+    }
+    /** Start CPU profiling. */
+    startProfile(intervalUs = 100) {
+        if (!this.connected || this.profiling) {
+            log.info("cdp-bridge", `startProfile skipped: connected=${this.connected} profiling=${this.profiling}`);
+            return;
+        }
+        this.profiling = true;
+        log.info("cdp-bridge", "Starting CPU profile...");
+        this.post("Profiler.setSamplingInterval", { interval: intervalUs });
+        this.post("Profiler.start", {});
+    }
+    /** Stop CPU profiling and return the profile. */
+    stopProfile() {
+        if (!this.connected || !this.profiling) {
+            log.info("cdp-bridge", `stopProfile skipped: connected=${this.connected} profiling=${this.profiling}`);
+            return Promise.resolve(null);
+        }
+        this.profiling = false;
+        log.info("cdp-bridge", "Stopping CPU profile...");
+        return new Promise((resolve) => {
+            this.session.post("Profiler.stop", (_err, res) => {
+                if (_err || !res?.profile) {
+                    log.warn("cdp-bridge", `Profiler.stop error: ${_err} res: ${JSON.stringify(res)}`);
+                    resolve(null);
+                    return;
+                }
+                const prof = 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("cdp-bridge", `Profile received: ${prof.nodeCount} nodes, ${prof.sampleCount} samples`);
+                resolve(prof);
+            });
+        });
+    }
+    /** Whether currently profiling. */
+    isProfiling() { return this.profiling; }
+    /** The last recorded profile (null if none). */
+    getLastProfile() { return this.lastProfile; }
+    /** Evaluate an expression (Runtime.evaluate). Stretch goal. */
+    evaluate(expr) {
+        if (!this.connected)
+            return Promise.resolve({ error: "not connected" });
+        return new Promise((resolve) => {
+            this.session.post("Runtime.evaluate", {
+                expression: expr,
+                returnByValue: true,
+            }, (_err, res) => {
+                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() {
+        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 ──
+    post(method, params) {
+        if (!this.session)
+            return;
+        try {
+            this.session.post(method, params, () => { });
+        }
+        catch {
+            // Some methods may not be available in all runtimes; ignore.
+        }
+    }
+    handleConsole(params) {
+        const type = (params.type ?? "log");
+        const args = (params.args ?? []).map((a) => ({
+            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 = {
+            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 */ }
+        }
+    }
+    handleException(params) {
+        const details = params.exceptionDetails ?? {};
+        const exc = {
+            id: ++this.entryCounter,
+            text: details.text ?? "Uncaught exception",
+            stack: details.exception?.description ?? details.stackTrace?.callFrames?.map((f) => `  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 */ }
+        }
+    }
+    serializeArg(arg) {
+        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/dist/libraries/devtools/src/collectors.js

@@ -0,0 +1,318 @@
+// ============================================================================
+// collectors.ts — transport-agnostic devtools data collection.
+//
+// The web mirror sends these as JSON over the devtools WebSocket; the Blitz
+// devtools host calls the same collectors in-process. Collection is
+// identical either way — this module is the single source of truth.
+// ============================================================================
+// Lazy-load the ProfilingSAB reader (avoids importing @downdraft/engine/profiling
+// at module load time; it may not be available in all contexts).
+let profilingMod = undefined;
+async function loadProfilingMod() {
+    if (profilingMod !== undefined)
+        return profilingMod;
+    try {
+        profilingMod = await import("@downdraft/engine/profiling");
+    }
+    catch {
+        profilingMod = null;
+    }
+    return profilingMod;
+}
+// Cache the ProfilingSABReader per SAB — building one per collect would
+// re-parse the layout header and re-drain the full warning/string rings
+// every 500ms instead of incrementally.
+let sabReader = null;
+async function sabReaderFor(sab) {
+    if (sabReader?.sab === sab)
+        return sabReader.reader;
+    const mod = await loadProfilingMod();
+    if (!mod)
+        return null;
+    const layout = mod.profilingLayoutFromSab(sab);
+    if (!layout)
+        return null;
+    sabReader = { sab, reader: new mod.ProfilingSABReader(sab, layout) };
+    return sabReader.reader;
+}
+function formatBytes(bytes) {
+    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, evalThreadIds) {
+    const threads = [{ id: "main", name: "main", kind: 0 }];
+    if (ctx.profilingSAB) {
+        try {
+            const reader = await sabReaderFor(ctx.profilingSAB);
+            if (reader) {
+                const snapshot = reader.readSnapshot();
+                snapshot.slots.forEach((slot) => {
+                    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) {
+    const stage = ctx.gameScene?.stage;
+    if (!stage)
+        return [];
+    const nodes = [];
+    let idCounter = 1;
+    const collect = (node, parentId, depth) => {
+        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) => 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, mode) {
+    if (mode === "scene")
+        return collectSceneTree(ctx);
+    const simReader = ctx.renderer?.simReader ?? ctx.renderer?.getSimReader?.();
+    if (!simReader?.isValid?.())
+        return [];
+    const nodes = [];
+    let idCounter = 1;
+    try {
+        simReader.getEntityCount();
+        const iter = simReader.iterEntities?.();
+        iter?.forEach((ent) => {
+            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) {
+    const r = ctx.renderer;
+    const entries = [];
+    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) => {
+                    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) => {
+                    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) => {
+                    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) => {
+                    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 = [];
+    const memHistory = [];
+    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) => { 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) {
+    const slots = [{
+            slotIndex: 0,
+            name: "main",
+            runtime: 0,
+            history: [{
+                    cpuPercent: 0,
+                    heapUsed: performance?.memory?.usedJSHeapSize ?? 0,
+                    heapTotal: performance?.memory?.totalJSHeapSize ?? 0,
+                    gcPauseMaxUs: 0,
+                    taskLatencyP95Us: 0,
+                }],
+        }];
+    if (ctx.profilingSAB) {
+        try {
+            const reader = await sabReaderFor(ctx.profilingSAB);
+            if (reader) {
+                const snapshot = reader.readSnapshot();
+                snapshot.slots.forEach((slot) => {
+                    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) {
+    const nodes = (profile.nodes ?? []).map((n) => ({
+        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 ?? [],
+    };
+}

package/dist/libraries/devtools/src/index.js

@@ -0,0 +1,31 @@
+// ============================================================================
+// @downdraft/engine/libraries/devtools — engine devtools bridge
+//
+// Two frontends consume the same provider/command data model
+// (DevtoolsProviderTarget — registerEngineProviders works on both):
+//
+//   Blitz devtools (in-engine): an html-ui/Blitz document docked in the game
+//     window — Chrome-DevTools-style tabs driven by the collectors and
+//     provider snapshots below. Lives in @downdraft/engine/modules/devtools
+//     (blitz/). Toggled with F12.
+//
+//   WebDevtoolsHost (web/): development-only loopback server (Bun.serve HTTP
+//     + WebSocket JSON-RPC) serving the browser frontend in
+//     packages/devtools-web. Opens in a desktop browser window.
+//
+// Panels: Console (CDP Runtime.consoleAPICalled + exceptionThrown + logger
+// sink), Scene/DOM trees, GPU info, CDP profiler, per-thread ProfilingSAB
+// metrics, and provider-fed snapshot panels (sim, memory, render-graph,
+// materials, doctor, workers, input, postfx, assets, game).
+// ============================================================================
+export { DevtoolsBackend, panelSlot, slotName } from "./backend.js";
+export { CdpBridge } from "./cdp-bridge.js";
+export { collectDomTree, collectGpuInfo, collectMetrics, collectProfile, collectSceneTree, collectThreads } from "./collectors.js";
+export { registerEngineProviders } from "./native-providers.js";
+export { PANEL, SNAP_FLAG, SNAP_STATUS } from "./snapshot.js";
+export { checkpoint, notify, verifyPixel } from "./verify.js";
+// ── Web devtools (browser UI over WS + JSON-RPC) ──
+export { openDevToolsUrl } from "./web/browser.js";
+export { WebDebuggerSceneShim, WebDevtoolsHost } from "./web/host.js";
+export { WebDevtoolsMirror } from "./web/mirror.js";
+export { DevToolsServer } from "./web/server.js";