@downdraft/engine 0.1.0 → 0.1.2-alpha.5

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

@@ -0,0 +1,449 @@
+// ============================================================================
+// backend.ts — DevtoolsBackend: transport-neutral devtools data engine.
+//
+// Owns the provider/command registry, thread evals, collector context, CDP +
+// logger-sink wiring, and the per-frame push cadence. Frontends differ only
+// in how events leave the process: WebDevtoolsMirror emits JSON over the
+// DevToolsServer WebSocket; the docked Blitz devtools host emits into its
+// in-process UI state. Both subscribe to the same event names and dispatch
+// the same RPC methods.
+//
+// Events emitted: console, threads, scene, dom, gpu, metrics, snapshot,
+// profile, console.clear.
+// RPC handled (via dispatch): ping, eval, snapshot, command, sceneTree,
+// domTree, gpuInfo, metrics, threads, inspector.call, profile.start|stop,
+// console.clear, domTree.mode.
+// ============================================================================
+import { addLogSink, createLogger, getRecentLogs } from "@downdraft/engine/util/logger";
+import { collectDomTree, collectGpuInfo, collectMetrics, collectProfile, collectSceneTree, collectThreads, } from "./collectors.js";
+import { PANEL } from "./snapshot.js";
+const log = createLogger("info");
+// Devtools' own diagnostics must not round-trip through the logger sink
+// into the console panel: a "slow update" row would dirty the console,
+// forcing a re-render that makes the next update slower — a self-feeding
+// lag spiral. These still write to stdout; only the devtools console view
+// skips them.
+const SELF_LOG_MODULES = new Set(["devtools-backend", "blitz-devtools-host"]);
+export function panelSlot(panel) {
+    return typeof panel === "number" ? panel : (PANEL[panel] ?? 0);
+}
+export function slotName(slot) {
+    for (const [name, s] of Object.entries(PANEL)) {
+        if (s === slot)
+            return name;
+    }
+    return `slot-${slot}`;
+}
+export class DevtoolsBackend {
+    emitFn;
+    hasClientFn;
+    cdp;
+    ctx;
+    threadEvals = new Map();
+    disposed = false;
+    providers = new Map();
+    commandHandlers = new Map();
+    globalCommandHandler = null;
+    lastProviderPush = new Map();
+    providerIntervalMs = 1500;
+    /** When non-null, the cadence loop only auto-refreshes this provider
+     *  slot — the docked Blitz host sets it to the active snapshot tab (or
+     *  -1 when a fixed panel is active) so providers for unviewed tabs
+     *  don't collect at all. null = refresh all providers (web mirror). */
+    providerWatch = null;
+    lastProviderTick = 0;
+    lastDiagWarn = 0;
+    lastMetricsPush = 0;
+    lastGpuPush = 0;
+    lastScenePush = 0;
+    firstUpdate = true;
+    domTreeMode = "scene";
+    unsubConsole = null;
+    unsubException = null;
+    unsubLogger = null;
+    loggerBuffer = [];
+    constructor(opts) {
+        this.emitFn = opts.emit;
+        this.hasClientFn = opts.hasClient;
+        this.cdp = opts.cdp;
+        this.ctx = {
+            renderer: opts.renderer,
+            gameScene: opts.gameScene,
+            profilingSAB: opts.profilingSAB,
+        };
+    }
+    // ── Lifecycle ──
+    start() {
+        this.unsubConsole = this.cdp.onConsole((entry) => {
+            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) => a.value ?? a.description ?? String(a)).join(" ");
+            this.emitConsole(text, severity, "main", entry.timestamp ?? performance.now(), !!entry.stack);
+        });
+        this.unsubException = this.cdp.onException((exc) => {
+            const text = `${exc.text}\n${exc.stack ?? ""}`.trim();
+            this.emitConsole(text, 3, "main", performance.now(), true);
+        });
+        void this.pushThreads();
+    }
+    attachLoggerBridge() {
+        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() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.unsubConsole?.();
+        this.unsubException?.();
+        this.unsubLogger?.();
+    }
+    resetFirstUpdate() {
+        this.firstUpdate = true;
+    }
+    // ── Emission helpers ──
+    emit(event, data) {
+        if (this.disposed)
+            return;
+        this.emitFn(event, data);
+    }
+    /** Diagnostic warnings, ≤1/sec — they still reach stdout, but a flood of
+     *  them would go through the sink machinery per frame for nothing (and
+     *  pre-filter they'd also dirty the console panel each time). */
+    diagWarn(msg) {
+        const now = performance.now();
+        if (now - this.lastDiagWarn < 1000)
+            return;
+        this.lastDiagWarn = now;
+        log.warn("devtools-backend", msg);
+    }
+    emitConsole(text, severity, thread, ts, hasStack) {
+        this.emit("console", { text, severity, thread, ts, hasStack });
+    }
+    flushLoggerBuffer() {
+        if (this.loggerBuffer.length === 0)
+            return;
+        const entries = this.loggerBuffer;
+        this.loggerBuffer = [];
+        entries.forEach((entry) => this.pushLogEntry(entry));
+    }
+    pushLogEntry(entry) {
+        if (this.disposed)
+            return;
+        if (SELF_LOG_MODULES.has(entry.module))
+            return;
+        this.emitConsole(`[${entry.module}] ${entry.message}`, logLevelToSeverity(entry.level), entry.thread || "main", entry.timestamp, false);
+    }
+    // ── Thread eval ──
+    registerThreadEval(threadId, evalFn) {
+        this.threadEvals.set(threadId, evalFn);
+        void this.pushThreads();
+    }
+    threadEvalNames() {
+        return [...this.threadEvals.keys()];
+    }
+    // ── Data pushes ──
+    async pushThreads() {
+        this.emit("threads", await collectThreads(this.ctx, [...this.threadEvals.keys()]));
+    }
+    pushSceneTree() {
+        this.emit("scene", collectSceneTree(this.ctx));
+    }
+    pushDomTree(mode) {
+        this.domTreeMode = mode;
+        this.emit("dom", collectDomTree(this.ctx, mode));
+    }
+    pushGpuInfo() {
+        this.emit("gpu", collectGpuInfo(this.ctx));
+    }
+    async pushMetrics() {
+        this.emit("metrics", await collectMetrics(this.ctx));
+    }
+    pushProfile(profile) {
+        this.emit("profile", collectProfile(profile));
+    }
+    clearConsole() {
+        this.emit("console.clear", {});
+    }
+    // ── Providers / commands ──
+    registerProvider(panel, collect) {
+        this.providers.set(panelSlot(panel), collect);
+    }
+    registerCommandHandler(panel, handler) {
+        if (panel === "*") {
+            this.globalCommandHandler = handler;
+        }
+        else {
+            this.commandHandlers.set(panelSlot(panel), handler);
+        }
+    }
+    /** Registered provider slots — the dynamic tab list for frontends. */
+    providerSlots() {
+        return [...this.providers.keys()].map((slot) => ({ slot, name: slotName(slot) }));
+    }
+    /** Collect + emit one provider's snapshot immediately. */
+    refreshPanel(panel) {
+        const trace = [performance.now()];
+        const slot = panelSlot(panel);
+        trace.push(performance.now());
+        const collect = this.providers.get(slot);
+        if (!collect)
+            return;
+        const push = (snap) => {
+            if (snap)
+                this.emit("snapshot", { panel: slotName(slot), slot, snap });
+            this.lastProviderPush.set(slot, performance.now());
+        };
+        const fail = (err) => {
+            this.emit("snapshot", {
+                panel: slotName(slot), slot,
+                snap: { status: "error", statusMsg: String(err), sections: [] },
+            });
+            this.lastProviderPush.set(slot, performance.now());
+        };
+        trace.push(performance.now());
+        try {
+            const r = collect();
+            trace.push(performance.now());
+            if (r && typeof r.then === "function") {
+                r.then(push, fail);
+            }
+            else {
+                push(r);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+        trace.push(performance.now());
+        const total = trace[4] - trace[0];
+        if (total > 10) {
+            const seg = `pre=${(trace[2] - trace[0]).toFixed(1)} collect=${(trace[3] - trace[2]).toFixed(1)} emit=${(trace[4] - trace[3]).toFixed(1)}`;
+            this.diagWarn(`slow provider ${slotName(slot)}: ${total.toFixed(1)}ms [${seg}]`);
+        }
+    }
+    dispatchCommand(cmd) {
+        if (cmd.action === "refresh") {
+            void this.refreshPanel(cmd.panel);
+            return;
+        }
+        const handler = this.commandHandlers.get(cmd.panel) ?? this.globalCommandHandler;
+        if (!handler) {
+            log.warn("devtools-backend", `unhandled command panel=${cmd.panel} action=${cmd.action}`);
+            return;
+        }
+        try {
+            const r = handler(cmd);
+            if (r instanceof Promise)
+                r.catch((err) => log.warn("devtools-backend", `command error: ${err}`));
+        }
+        catch (err) {
+            log.warn("devtools-backend", `command error: ${err}`);
+        }
+    }
+    setPerfRecording(start) {
+        if (start)
+            this.startProfiling();
+        else
+            void this.stopProfiling();
+    }
+    startProfiling() {
+        try {
+            this.cdp.startProfile();
+            log.info("devtools-backend", "Profiling started");
+        }
+        catch (err) {
+            log.warn("devtools-backend", `Failed to start profiling: ${err}`);
+        }
+    }
+    async stopProfiling() {
+        try {
+            const profile = await this.cdp.stopProfile();
+            if (profile)
+                this.pushProfile(profile);
+        }
+        catch (err) {
+            log.warn("devtools-backend", `Failed to stop profiling: ${err}`);
+        }
+    }
+    // ── Per-frame pump (called from the host's update) ──
+    update() {
+        if (this.disposed)
+            return;
+        if (!this.hasClientFn())
+            return; // nobody listening — save the work
+        const t0 = performance.now();
+        this.flushLoggerBuffer();
+        const t1 = performance.now();
+        if (this.firstUpdate) {
+            this.firstUpdate = false;
+            this.pushSceneTree();
+            this.pushDomTree(this.domTreeMode);
+            this.pushGpuInfo();
+            void this.pushMetrics();
+            void this.pushThreads();
+            // Providers intentionally skipped — the cadence loop below serves
+            // overdue providers one-per-update, spreading the initial burst.
+        }
+        const now = performance.now();
+        const seg = {};
+        let tSeg = now;
+        const mark = (name) => { const t = performance.now(); seg[name] = (seg[name] ?? 0) + t - tSeg; tSeg = t; };
+        if (now - this.lastMetricsPush > 500) {
+            this.lastMetricsPush = now;
+            void this.pushMetrics();
+            void this.pushThreads();
+            mark("metrics");
+        }
+        if (now - this.lastGpuPush > 1000) {
+            this.lastGpuPush = now;
+            this.pushGpuInfo();
+            mark("gpu");
+        }
+        if (now - this.lastScenePush > 2000) {
+            this.lastScenePush = now;
+            this.pushSceneTree();
+            this.pushDomTree(this.domTreeMode);
+            mark("scene");
+        }
+        // Provider snapshots on their own cadence — at most one synchronous
+        // collect per tick so a batch of overdue panels can't stall a single
+        // frame. The tick gap spreads N providers evenly across the interval
+        // instead of refreshing them in one burst; providerWatch (set by the
+        // docked host to the active snapshot tab, or -1 for fixed panels)
+        // skips collection for tabs nobody is looking at.
+        const count = this.providers.size;
+        if (count > 0) {
+            const gap = Math.max(100, this.providerIntervalMs / count);
+            if (now - this.lastProviderTick >= gap) {
+                for (const slot of this.providers.keys()) {
+                    if (this.providerWatch !== null && slot !== this.providerWatch)
+                        continue;
+                    const last = this.lastProviderPush.get(slot) ?? 0;
+                    if (now - last > this.providerIntervalMs) {
+                        this.lastProviderTick = now;
+                        void this.refreshPanel(slot);
+                        break;
+                    }
+                }
+            }
+        }
+        mark("providers");
+        const t2 = performance.now();
+        if (t2 - t0 > 6) {
+            const rest = [
+                t1 - t0 > 2 ? `logs=${(t1 - t0).toFixed(1)}ms` : "",
+                now - t1 > 2 ? `init=${(now - t1).toFixed(1)}ms` : "",
+                ...Object.entries(seg).filter(([, v]) => v > 2).map(([k, v]) => `${k}=${v.toFixed(1)}ms`),
+            ].filter(Boolean).join(" ");
+            this.diagWarn(`slow update ${(t2 - t0).toFixed(1)}ms: ${rest}`);
+        }
+    }
+    // ── RPC dispatch (WS requests for the web frontend; direct calls for Blitz) ──
+    async dispatch(method, params) {
+        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);
+                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 ?? "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 ?? []));
+            }
+            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}`);
+        }
+    }
+    sceneInspector() {
+        const g = globalThis;
+        const win = g.window;
+        return (win?.__sceneInspector ?? g.__sceneInspector ?? null);
+    }
+    inspectorMethodNames() {
+        const api = this.sceneInspector();
+        if (!api)
+            return [];
+        return Object.keys(api).filter((k) => typeof api[k] === "function");
+    }
+}
+function logLevelToSeverity(level) {
+    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;
+    }
+}