@downdraft/engine 0.1.2-alpha.5 → 0.3.0

package/dist/modules/devtools/src/blitz/panels/performance.js

@@ -25,6 +25,12 @@ export class PerformancePanel {
     </div>`;
     }
     renderBody() {
+        // `chart + table + prof || note` could never fall through — the table
+        // markup is non-empty even with zero slots, so the empty-state hint was
+        // dead. Gate the whole thing on having anything to show.
+        if (!this.slots.length && !this.profile && !this.recording) {
+            return `<div class="empty-note">no metrics — is ProfilingSAB attached?</div>`;
+        }
         const heapSeries = [...this.history.entries()].map(([slot, rec]) => ({
             name: `heap — ${this.slotName(slot)}`,
             values: rec.heap,
@@ -33,10 +39,13 @@ export class PerformancePanel {
         const chart = heapSeries.length
             ? `<div class="snap-section"><h3>Heap per thread (MB)</h3>${heapSeries.map((s) => chartHtml(s.values, { max: Math.max(64, ...heapSeries.flatMap((x) => x.values)), color: s.color, label: s.name })).join("")}</div>`
             : "";
-        let tbl = `<table class="dt"><tr>
+        let tbl = "";
+        if (this.slots.length) {
+            tbl = `<table class="dt"><tr>
       <th>slot</th><th>name</th><th>cpu%</th><th>heap</th>
       <th>gc max µs</th><th>task p95 µs</th></tr>`;
-        for (const s of this.slots) {
+        }
+        for (const s of this.slots.values()) {
             const h = s.history?.[0] ?? {};
             tbl += `<tr><td>${s.slotIndex}</td><td>${esc(s.name)}</td>
         <td>${(h.cpuPercent ?? 0).toFixed(1)}</td>
@@ -44,25 +53,30 @@ export class PerformancePanel {
         <td>${(h.gcPauseMaxUs ?? 0).toFixed(0)}</td>
         <td>${(h.taskLatencyP95Us ?? 0).toFixed(0)}</td></tr>`;
         }
-        tbl += `</table>`;
-        const table = `<div class="snap-section"><h3>Threads</h3>${tbl}</div>`;
+        if (this.slots.length)
+            tbl += `</table>`;
+        const table = tbl ? `<div class="snap-section"><h3>Threads</h3>${tbl}</div>` : "";
         let prof = "";
         if (this.recording) {
             prof = `<div class="status-banner">● recording — press Stop to capture</div>`;
         }
+        else if (this.profile && !Array.isArray(this.profile.nodes)) {
+            prof = `<div class="status-banner error">malformed profile payload</div>`;
+        }
         else if (this.profile) {
-            const top = [...this.profile.nodes].sort((a, b) => b.hitCount - a.hitCount).slice(0, 40);
-            const total = Math.max(1, top.reduce((s, n) => s + n.hitCount, 0));
-            const durMs = (this.profile.endUs - this.profile.startUs) / 1000;
-            prof = `<div class="snap-section"><h3>CPU profile — ${this.profile.nodes.length} nodes, ${durMs.toFixed(0)} ms</h3>
-        <div class="lines">${top.map((n) => esc(`${(100 * n.hitCount / total).toFixed(1).padStart(5)}%  ${n.callFrame}  ${n.url}:${n.line}`)).join("\n")}</div></div>`;
+            const nodes = this.profile.nodes;
+            const top = [...nodes].sort((a, b) => (b.hitCount ?? 0) - (a.hitCount ?? 0)).slice(0, 40);
+            const total = Math.max(1, top.reduce((s, n) => s + (n.hitCount ?? 0), 0));
+            const durMs = ((this.profile.endUs ?? 0) - (this.profile.startUs ?? 0)) / 1000;
+            prof = `<div class="snap-section"><h3>CPU profile — ${nodes.length} nodes, ${durMs.toFixed(0)} ms</h3>
+        <div class="lines">${top.map((n) => esc(`${(100 * (n.hitCount ?? 0) / total).toFixed(1).padStart(5)}%  ${n.callFrame}  ${n.url}:${n.line}`)).join("\n")}</div></div>`;
         }
-        return chart + table + prof || `<div class="empty-note">no metrics — is ProfilingSAB attached?</div>`;
+        return chart + table + prof;
     }
     onBackendEvent(event, data) {
         if (event === "metrics") {
-            this.slots = data ?? [];
-            for (const s of this.slots) {
+            this.slots = Array.isArray(data) ? data : [];
+            for (const s of this.slots.values()) {
                 const h = s.history?.[0];
                 if (!h)
                     continue;
@@ -71,8 +85,8 @@ export class PerformancePanel {
                     rec = { cpu: [], heap: [] };
                     this.history.set(s.slotIndex, rec);
                 }
-                rec.cpu.push(h.cpuPercent);
-                rec.heap.push(h.heapUsed / 1048576);
+                rec.cpu.push(h.cpuPercent ?? 0);
+                rec.heap.push((h.heapUsed ?? 0) / 1048576);
                 if (rec.cpu.length > HIST) {
                     rec.cpu.shift();
                     rec.heap.shift();

package/dist/modules/devtools/src/blitz/panels/snapshot.js

@@ -18,6 +18,7 @@ export class SnapshotPanel {
     slot;
     snap = null;
     updatedAt = "";
+    lastError = "";
     constructor(ctx, slot, name) {
         this.ctx = ctx;
         this.slot = slot;
@@ -32,19 +33,22 @@ export class SnapshotPanel {
     </div>`;
     }
     renderBody() {
+        const err = this.lastError
+            ? `<div class="status-banner error">${esc(this.lastError)}</div>` : "";
         const snap = this.snap;
         if (!snap)
-            return `<div class="empty-note">no data</div>`;
+            return err + `<div class="empty-note">no data</div>`;
         const banner = snap.status && snap.status !== "ok"
             ? `<div class="status-banner${snap.status === "error" ? " error" : ""}">${esc(snap.statusMsg ?? snap.status)}</div>`
             : "";
-        return banner + (snap.sections ?? []).map((s) => this.renderSection(s)).join("");
+        return err + banner + (snap.sections ?? []).map((s) => this.renderSection(s)).join("");
     }
     onBackendEvent(event, data) {
         if (event === "snapshot") {
             const d = data;
             if (d?.slot === this.slot) {
                 this.snap = d.snap;
+                this.lastError = "";
                 this.updatedAt = `updated ${new Date().toLocaleTimeString()}`;
                 this.dirty = true;
                 this.shellDirty = true;
@@ -61,18 +65,32 @@ export class SnapshotPanel {
                 return;
             void this.ctx.call("command", {
                 panel: this.slot, action: cmd, payload: data.payload ?? "",
-            }).then(() => this.refresh());
+            }).then(() => this.refresh()).catch(() => { });
         }
     }
     activate() {
         void this.refresh();
     }
+    refreshSeq = 0;
     async refresh() {
+        // Overlapping refreshes (activate + provider push + manual Refresh) are
+        // last-call-wins — a slow stale response must not clobber a newer one.
+        const req = ++this.refreshSeq;
         try {
-            this.snap = (await this.ctx.call("snapshot", { panel: this.slot }));
+            const snap = (await this.ctx.call("snapshot", { panel: this.slot }));
+            if (req !== this.refreshSeq)
+                return;
+            this.snap = snap;
+            this.lastError = "";
             this.updatedAt = `updated ${new Date().toLocaleTimeString()}`;
         }
-        catch { /* keep last */ }
+        catch (err) {
+            if (req !== this.refreshSeq)
+                return;
+            // Keep the last good snapshot; surface the failure instead of
+            // pretending the data is current.
+            this.lastError = `refresh failed: ${String(err)}`;
+        }
         this.dirty = true;
         this.shellDirty = true;
     }
@@ -118,12 +136,17 @@ export class SnapshotPanel {
             return `<label><span class="dbtn${c.checked ? " on" : ""}" ${cmdAttr} data-payload="${c.checked ? "0" : "1"}">${c.checked ? "☑" : "☐"}</span> ${esc(c.label)}</label>`;
         }
         if (c.type === "slider") {
-            const span = c.max - c.min || 1;
+            // Providers can emit a slider without min/max/value — coerce so the
+            // stepper never ships "NaN" payloads back through snap.cmd.
+            const min = Number.isFinite(c.min) ? c.min : 0;
+            const max = Number.isFinite(c.max) ? c.max : min + 1;
+            const value = Number.isFinite(c.value) ? c.value : min;
+            const span = max - min || 1;
             const step = span / 20;
-            const dec = (d) => Math.min(c.max, Math.max(c.min, c.value + d * step)).toFixed(2);
+            const dec = (d) => Math.min(max, Math.max(min, value + d * step)).toFixed(2);
             return `<label>${esc(c.label)}
         <span class="dbtn" ${cmdAttr} data-payload="${dec(-1)}">−</span>
-        <span class="val">${c.value.toFixed(2)}</span>
+        <span class="val">${value.toFixed(2)}</span>
         <span class="dbtn" ${cmdAttr} data-payload="${dec(1)}">+</span></label>`;
         }
         return esc(c.label ?? "");

package/dist/modules/devtools/src/blitz/panels/types.js

@@ -39,7 +39,8 @@ export function chartHtml(values, opts = {}) {
     const step = Math.max(1, Math.floor(vals.length / cols));
     const cells = [];
     for (let i = 0; i < vals.length; i += step) {
-        const h = Math.max(0, Math.min(100, (vals[i] / max) * 100));
+        const v = Number.isFinite(vals[i]) ? vals[i] : 0;
+        const h = Math.max(0, Math.min(100, (v / max) * 100));
         cells.push(`<div class="col" style="height:${h.toFixed(1)}%;background:${color}"></div>`);
     }
     if (!cells.length)

package/dist/modules/devtools/src/blitz/theme.js

@@ -14,7 +14,7 @@ export const DEVTOOLS_CSS = `
   --warn: #e0b341;
   --err: #e5534b;
   --ok: #57ab5a;
-  --mono: "SF Mono", "Cascadia Mono", Consolas, monospace;
+  --mono: "DevTools Mono", "SF Mono", "Cascadia Mono", Consolas, monospace;
 }
 * { box-sizing: border-box; margin: 0; padding: 0; }
 /* height:100% must be on html AND body — Blitz resolves body % against
@@ -22,7 +22,7 @@ export const DEVTOOLS_CSS = `
 html, body {
   width: 100%; height: 100%; overflow: hidden;
   background: var(--bg); color: var(--fg);
-  font: 12px/1.45 system-ui, sans-serif;
+  font: 12px/1.45 "DevTools Sans", system-ui, sans-serif;
 }
 #dt-root {
   /* Absolute inset — Blitz doesn't resolve height:100% against the doc
@@ -50,7 +50,11 @@ html, body {
   display: flex; align-items: center; gap: 2px;
   background: var(--bg2); border-bottom: 1px solid var(--line);
   padding: 0 8px; height: 30px; flex-shrink: 0;
+  /* Provider tabs can overflow the strip — wheel-scroll it instead of
+   *  clipping tabs unreachable. */
+  overflow-x: auto; overflow-y: hidden;
 }
+#dt-tabs .tab, #dt-tabs .brand, #dt-tabs .hint { flex-shrink: 0; }
 #dt-tabs .brand { color: var(--accent); font-weight: 600; margin-right: 12px; }
 #dt-tabs .spacer { flex: 1; }
 #dt-tabs .hint { font-size: 11px; color: var(--fg-dim); }
@@ -124,14 +128,32 @@ html, body {
 .console-repl input:focus { border-color: var(--accent); }
 .console-repl .prompt { color: var(--accent); font-family: var(--mono); }
 
-/* ── Tree (scene/dom/ecs) ── */
+/* ── Tree (scene/ecs) ── */
 .tree { font-family: var(--mono); font-size: 11.5px; }
-.trow { padding: 1px 4px; white-space: nowrap; }
+.trow { padding: 1px 4px; white-space: nowrap; cursor: default; }
 .trow:hover { background: var(--bg3); }
 .trow.sel { background: #2d4a72; }
+.trow .caret {
+  display: inline-block; width: 12px; color: var(--fg-dim);
+  cursor: pointer; user-select: none;
+}
+.trow .caret:hover { color: var(--fg); }
 .trow .detail { color: var(--fg-dim); margin-left: 8px; }
 .trow .kids { color: var(--fg-dim); }
 
+/* ── Elements details strip (bottom chrome) ── */
+.el-details { border-top: 1px solid var(--line); background: var(--bg); }
+.el-details-head {
+  display: flex; align-items: center; gap: 8px;
+  padding: 3px 8px; border-bottom: 1px solid var(--line);
+}
+.el-details-head .dt-title { color: var(--accent); font-weight: 600; }
+.el-details-head .spacer { flex: 1; }
+.el-details-body {
+  max-height: 140px; overflow-y: auto; padding: 6px 8px;
+  font-family: var(--mono); font-size: 11.5px; white-space: pre-wrap;
+}
+
 /* ── KV / tables / snapshot panels ── */
 .snap-section { margin-bottom: 14px; }
 .snap-section > h3 {

package/dist/modules/html-ui/src/doc-backend.js

@@ -147,9 +147,32 @@ export function createDocCore(emit, gpuHooks) {
             s.statsLast = now;
         }
     }
+    // Smooth-wheel ease: fraction of the remainder applied per elapsed ms.
+    // τ≈45ms → ~30% per 16ms tick, ~95% drained in ~135ms — snappy but
+    // animated. A 1/MAX_TICKS floor bounds any backlog at ~320ms of drain —
+    // a fast wheel can't make scroll trail input indefinitely. Dispatching
+    // real wheel events keeps Blitz's hit-testing, scroll chaining, scrollbar
+    // reveal, and scroll DOM events intact.
+    const WHEEL_TAU_MS = 45;
+    const WHEEL_MAX_TICKS = 20;
+    function stepWheel(s, now) {
+        const dt = Math.min(50, Math.max(1, now - s.wheelT));
+        s.wheelT = now;
+        const f = Math.max(1 - Math.exp(-dt / WHEEL_TAU_MS), 1 / WHEEL_MAX_TICKS);
+        // Snap the tail: a step below ~¾px/axis applies the whole residue instead
+        // of asymptoting through invisible sub-pixel repaints.
+        const dx = Math.abs(s.wheelRx) * f < 0.75 ? s.wheelRx : s.wheelRx * f;
+        const dy = Math.abs(s.wheelRy) * f < 0.75 ? s.wheelRy : s.wheelRy * f;
+        s.wheelRx -= dx;
+        s.wheelRy -= dy;
+        const k = s.scale;
+        s.doc.wheel(s.wheelX * k, s.wheelY * k, dx * k, dy * k, s.wheelMods);
+    }
     function pump() {
         const now = performance.now();
         for (const [id, s] of docs.entries()) {
+            if (s.smoothWheel && (s.wheelRx !== 0 || s.wheelRy !== 0))
+                stepWheel(s, now);
             const events = s.doc.pollEvents();
             if (events.length)
                 emit({ type: "events", id, events });
@@ -233,6 +256,8 @@ export function createDocCore(emit, gpuHooks) {
                         doc, scale: m.scale, cssW: m.cssW, cssH: m.cssH,
                         maxFps: m.maxFps ?? 0, lastFrame: -1e9,
                         sab: null, sabU32: null, sabDisabled: false, gpuTex: null,
+                        smoothWheel: m.smoothWheel === true,
+                        wheelRx: 0, wheelRy: 0, wheelX: 0, wheelY: 0, wheelT: 0,
                         stats: freshStats(), statsLast: 0,
                     };
                     docs.set(m.id, s);
@@ -245,11 +270,18 @@ export function createDocCore(emit, gpuHooks) {
                         s.maxFps = m.maxFps;
                     break;
                 }
-                case "setHtml":
+                case "setHtml": {
                     if (/float\s*:/.test(m.html))
                         emit({ type: "error", id: m.id, message: "CSS float hangs Blitz layout — use flex instead" });
-                    docs.get(m.id)?.doc.setHtml(m.html);
+                    const s = docs.get(m.id);
+                    if (!s)
+                        break;
+                    // Drop any in-flight smooth-wheel drain — its remainder belongs to
+                    // the document being replaced.
+                    s.wheelRx = s.wheelRy = 0;
+                    s.doc.setHtml(m.html);
                     break;
+                }
                 case "resize": {
                     const s = docs.get(m.id);
                     if (s) {
@@ -374,13 +406,30 @@ export function createDocCore(emit, gpuHooks) {
                             s.doc.pointerMove(msg.x * k, msg.y * k, msg.mods);
                             break;
                         case "down":
+                            // A press interrupts any in-flight wheel scroll (mirrors
+                            // Blitz's interrupt_animation semantics for user input).
+                            s.wheelRx = 0;
+                            s.wheelRy = 0;
                             s.doc.pointerDown(msg.x * k, msg.y * k, msg.button, msg.mods);
                             break;
                         case "up":
                             s.doc.pointerUp(msg.x * k, msg.y * k, msg.button, msg.mods);
                             break;
                         case "wheel":
-                            s.doc.wheel(msg.x * k, msg.y * k, msg.deltaX * k, msg.deltaY * k, msg.mods);
+                            if (s.smoothWheel) {
+                                // A fresh gesture back-dates wheelT so the first pump tick
+                                // applies a full ~16ms step immediately — no dead frame.
+                                if (s.wheelRx === 0 && s.wheelRy === 0)
+                                    s.wheelT = performance.now() - 16;
+                                s.wheelRx += msg.deltaX;
+                                s.wheelRy += msg.deltaY;
+                                s.wheelX = msg.x;
+                                s.wheelY = msg.y;
+                                s.wheelMods = msg.mods;
+                            }
+                            else {
+                                s.doc.wheel(msg.x * k, msg.y * k, msg.deltaX * k, msg.deltaY * k, msg.mods);
+                            }
                             break;
                         case "key":
                             s.doc.key(msg.down, msg.key, msg.code, msg.text, msg.mods);

package/dist/modules/html-ui/src/host.js

@@ -7,6 +7,7 @@
 // ============================================================================
 import { getHostCapabilities, getNativeHost } from "@downdraft/engine/platform/runtime";
 import { createLogger } from "@downdraft/engine/util/logger";
+import { untrackedTimeout } from "@downdraft/engine/util/session-timer";
 import { PanelBlitPass } from "./composite.js";
 import { createLocalBackend, createWorkerBackend } from "./doc-backend.js";
 const log = createLogger("info");
@@ -136,7 +137,7 @@ export class HtmlUiHost {
         this.order.push(id);
         // Doc viewport scale = raster px per CSS px = scale * zoom; layout size
         // is rect/zoom CSS px so the raster still covers rect*scale texture px.
-        this.send({ type: "create", id, cssW: spec.rect.w / zoom, cssH: spec.docH ?? spec.rect.h / zoom, scale: scale * zoom, html: spec.html, maxFps: spec.maxFps });
+        this.send({ type: "create", id, cssW: spec.rect.w / zoom, cssH: spec.docH ?? spec.rect.h / zoom, scale: scale * zoom, html: spec.html, maxFps: spec.maxFps, smoothWheel: spec.smoothWheel });
         // GPU-direct: create the panel texture eagerly so the worker's texBind
         // lands before its first upload — the host knows raster dims at mount.
         if (this.gpuReady)
@@ -301,6 +302,8 @@ export class HtmlUiHost {
     /** Doc-backend capabilities (populated by the `ready` handshake —
      *  `incrementalDom` is false until then, and forever on old cdylibs). */
     get docCaps() { return this.caps; }
+    /** Which doc backend is live — "worker" (raster off-thread) or "local". */
+    get backendKind() { return this.backend.kind; }
     /** Compositor surface for GameRenderer's end-of-frame UI pass. */
     get compositor() {
         return {
@@ -349,7 +352,7 @@ export class HtmlUiHost {
             this.terminating = true;
             this.send({ type: "gpuDetach" });
             const backend = this.backend;
-            setTimeout(() => {
+            untrackedTimeout(() => {
                 if (!this.gpuDetachAcked)
                     backend.dispose();
                 this.destroyRetired();
@@ -775,7 +778,7 @@ export class HtmlUiHost {
                 || (p.postedBindPtr !== null && BigInt(ptr) === p.postedBindPtr));
         if (borrowed) {
             const key = BigInt(ptr);
-            const timer = setTimeout(() => {
+            const timer = untrackedTimeout(() => {
                 if (this.retiredTex.delete(key))
                     t.destroy();
             }, 1000);

package/dist/modules/html-ui/src/jsx-runtime.js

@@ -98,7 +98,7 @@ function renderNode(v) {
         return out.join("");
     }
     if (typeof t === "function") {
-        const r = t({ ...(p ?? {}) });
+        const r = t({ ...p });
         const out = [];
         renderInner(r, out);
         return out.join("");

package/libraries/blitz-ui/native/Cargo.toml

@@ -31,3 +31,9 @@ web-time = "1"
 # Workaround copied from blitz examples: disable unicode URL support
 # (see https://github.com/hsivonen/idna_adapter)
 idna_adapter = "=1.0.0"
+
+# Enable the vendored glifo's FreeType mask path (see [patch.crates-io] in the
+# workspace root). Feature unification turns it on inside vello_cpu's copy.
+# Target-gated: freetype-sys compiles bundled C, which wasm32 can't build.
+[target.'cfg(not(target_family = "wasm"))'.dependencies]
+glifo = { version = "0.2", features = ["freetype"] }

package/libraries/blitz-ui/native-osr/Cargo.toml

@@ -13,7 +13,9 @@ crate-type = ["cdylib"]
 blitz-html = { git = "https://github.com/DioxusLabs/blitz", rev = "efef6519fe6520caf66dc82df557580eecbf652b" }
 blitz-dom = { git = "https://github.com/DioxusLabs/blitz", rev = "efef6519fe6520caf66dc82df557580eecbf652b", default-features = false, features = ["woff"] }
 blitz-traits = { git = "https://github.com/DioxusLabs/blitz", rev = "efef6519fe6520caf66dc82df557580eecbf652b" }
-blitz-paint = { git = "https://github.com/DioxusLabs/blitz", rev = "efef6519fe6520caf66dc82df557580eecbf652b", features = ["custom-widget"] }
+# scrollbars: painted overlay thumbs on scroll containers + thumb drag/hover
+# hit-testing (pulls blitz-dom/scrollbars transitively).
+blitz-paint = { git = "https://github.com/DioxusLabs/blitz", rev = "efef6519fe6520caf66dc82df557580eecbf652b", features = ["custom-widget", "scrollbars"] }
 # Enable the vendored glifo's FreeType mask path (see [patch.crates-io] in the
 # workspace root). Feature unification turns it on inside vello_cpu's copy.
 glifo = { version = "0.2", features = ["freetype"] }

package/libraries/devtools/src/backend.ts

@@ -77,6 +77,12 @@ export class DevtoolsBackend {
   private providers = new Map<number, PanelProvider>();
   private commandHandlers = new Map<number, PanelCommandHandler>();
   private globalCommandHandler: PanelCommandHandler | null = null;
+  /** Dynamically-allocated slots for provider names outside the fixed PANEL
+   *  table — panelSlot() alone collapsed every unknown name onto slot 0
+   *  ("console"), so a second game provider silently replaced the first. */
+  private dynSlots = new Map<string, number>();
+  private dynSlotNames = new Map<number, string>();
+  private nextDynSlot = 100;
   private lastProviderPush = new Map<number, number>();
   providerIntervalMs = 1500;
   /** When non-null, the cadence loop only auto-refreshes this provider
@@ -237,37 +243,57 @@ export class DevtoolsBackend {
 
   // ── Providers / commands ──
 
-  registerProvider(panel: PanelName | number, collect: PanelProvider): void {
-    this.providers.set(panelSlot(panel), collect);
+  /** Resolve a panel id to its slot. Names outside the fixed PANEL table
+   *  get a stable dynamically-allocated slot so bespoke game providers can
+   *  coexist instead of colliding on slot 0. */
+  private slotFor(panel: PanelName | number | string): number {
+    if (typeof panel === "number") return panel;
+    const fixed = PANEL[panel as PanelName];
+    if (fixed !== undefined) return fixed;
+    let s = this.dynSlots.get(panel);
+    if (s === undefined) {
+      s = this.nextDynSlot++;
+      this.dynSlots.set(panel, s);
+      this.dynSlotNames.set(s, panel);
+    }
+    return s;
+  }
+
+  private nameFor(slot: number): string {
+    return this.dynSlotNames.get(slot) ?? slotName(slot);
+  }
+
+  registerProvider(panel: PanelName | number | string, collect: PanelProvider): void {
+    this.providers.set(this.slotFor(panel), collect);
   }
 
-  registerCommandHandler(panel: PanelName | number | "*", handler: PanelCommandHandler): void {
+  registerCommandHandler(panel: PanelName | number | string, handler: PanelCommandHandler): void {
     if (panel === "*") {
       this.globalCommandHandler = handler;
     } else {
-      this.commandHandlers.set(panelSlot(panel), handler);
+      this.commandHandlers.set(this.slotFor(panel), handler);
     }
   }
 
   /** Registered provider slots — the dynamic tab list for frontends. */
   providerSlots(): { slot: number; name: string }[] {
-    return [...this.providers.keys()].map((slot) => ({ slot, name: slotName(slot) }));
+    return [...this.providers.keys()].map((slot) => ({ slot, name: this.nameFor(slot) }));
   }
 
   /** Collect + emit one provider's snapshot immediately. */
-  refreshPanel(panel: PanelName | number): void {
+  refreshPanel(panel: PanelName | number | string): void {
     const trace: number[] = [performance.now()];
-    const slot = panelSlot(panel);
+    const slot = this.slotFor(panel);
     trace.push(performance.now());
     const collect = this.providers.get(slot);
     if (!collect) return;
     const push = (snap: PanelSnapshot | null | undefined) => {
-      if (snap) this.emit("snapshot", { panel: slotName(slot), slot, snap });
+      if (snap) this.emit("snapshot", { panel: this.nameFor(slot), slot, snap });
       this.lastProviderPush.set(slot, performance.now());
     };
     const fail = (err: unknown) => {
       this.emit("snapshot", {
-        panel: slotName(slot), slot,
+        panel: this.nameFor(slot), slot,
         snap: { status: "error", statusMsg: String(err), sections: [] },
       });
       this.lastProviderPush.set(slot, performance.now());
@@ -288,7 +314,7 @@ export class DevtoolsBackend {
     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}]`);
+      this.diagWarn(`slow provider ${this.nameFor(slot)}: ${total.toFixed(1)}ms [${seg}]`);
     }
   }
 
@@ -431,7 +457,7 @@ export class DevtoolsBackend {
         return collectThreads(this.ctx, [...this.threadEvals.keys()]);
       case "snapshot": {
         const panel = params.panel;
-        const slot = typeof panel === "number" ? panel : panelSlot(panel as PanelName);
+        const slot = typeof panel === "number" ? panel : this.slotFor(String(panel));
         const collect = this.providers.get(slot);
         if (!collect) return { status: "unsupported", statusMsg: `no provider for ${String(panel)}`, sections: [] };
         try {
@@ -443,7 +469,7 @@ export class DevtoolsBackend {
       }
       case "command": {
         const panel = params.panel;
-        const slot = typeof panel === "number" ? panel : panelSlot((panel as PanelName) ?? "console");
+        const slot = typeof panel === "number" ? panel : this.slotFor(String(panel ?? "console"));
         this.dispatchCommand({ panel: slot, action: String(params.action ?? ""), payload: String(params.payload ?? "") });
         return true;
       }

package/libraries/devtools/src/collectors.ts

@@ -18,6 +18,11 @@ 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;
+  /** Stable node identity for pick/inspect — scene-store id, stage node id,
+   *  or ECS entity index ("ent-N") when the collector can provide one. The
+   *  numeric `id` is ephemeral (re-assigned per collect); `nodeId` survives
+   *  refreshes and is what `inspector.call` methods take. */
+  nodeId?: string;
 }
 export interface GpuInfoJson {
   entries: { key: string; value: string; isHeader: boolean }[];
@@ -100,30 +105,77 @@ export async function collectThreads(
   return threads;
 }
 
-/** Scene-graph tree (label + ctor + child counts). */
+function sceneInspectorApi(): Record<string, any> | null {
+  const g = globalThis as Record<string, any>;
+  return (g.window?.__sceneInspector ?? g.__sceneInspector ?? null) as Record<string, any> | null;
+}
+
+/** Scene-graph tree (label + ctor + child counts). Prefers a live
+ *  `gameScene.stage` walk; falls back to the SceneInspector's scene store
+ *  (`__sceneInspector.getSceneTree`) so games without a DOM-like stage still
+ *  get a populated tree — with stable nodeIds for pick/details. */
 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;
+  if (stage) {
+    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 : "",
+        nodeId: typeof node.id === "string" ? node.id : undefined,
+      });
+      node.children?.forEach((child: any) => collect(child, id, depth + 1));
+    };
+    collect(stage, -1, 0);
+    return nodes;
+  }
+
+  // Scene-store fallback — the same snapshot the inspector's getSceneTree
+  // exposes. Nodes are flat with id/parentId links; walk roots → children.
+  try {
+    const snap = sceneInspectorApi()?.getSceneTree?.();
+    const storeNodes = snap?.nodes;
+    if (!Array.isArray(storeNodes) || !storeNodes.length) return [];
+    const byId = new Map<string, any>(storeNodes.map((n: any) => [n.id, n]));
+    const roots = storeNodes.filter((n: any) => n.parentId === null || !byId.has(n.parentId));
+    const rows: TreeRow[] = [];
+    const visited = new Set<string>();
+    let idCounter = 1;
+    const walk = (n: any, parentId: number, depth: number): void => {
+      if (visited.has(n.id)) return; // corrupted parent/child links — don't loop
+      visited.add(n.id);
+      const id = idCounter++;
+      const p = n.position;
+      rows.push({
+        id, parentId, depth,
+        childCount: n.children?.length ?? 0,
+        kind: 0,
+        label: String(n.name ?? n.id),
+        detail: `${n.type ?? "node"}${Array.isArray(p) ? ` (${p.map((v: number) => (+v).toFixed(1)).join(", ")})` : ""}`,
+        nodeId: String(n.id),
+      });
+      for (const cid of n.children ?? []) {
+        const c = byId.get(cid);
+        if (c) walk(c, id, depth + 1);
+      }
+    };
+    roots.forEach((n: any) => walk(n, -1, 0));
+    // Orphans (every node has a parent but no root resolves) — still show them.
+    for (const n of storeNodes) if (!visited.has(n.id)) walk(n, -1, 0);
+    return rows;
+  } catch {
+    return [];
+  }
 }
 
 /** DOM tree: scene-graph stage or ECS entities depending on mode. */
@@ -148,6 +200,7 @@ export function collectDomTree(ctx: CollectorContext, mode: "scene" | "ecs"): Tr
         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)})`,
+        nodeId: `ent-${ent.idx}`,
       });
     });
   } catch { /* sim reader hiccup */ }