@downdraft/engine 0.2.0 → 0.3.0

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

@@ -1,10 +1,14 @@
 // ============================================================================
-// panels/elements.ts — Elements panel: scene graph / DOM / ECS entity tree.
-// Merges the web frontend's scene + dom tabs behind a mode switch, matching
-// the Chrome Elements panel's single-tree presentation.
+// panels/elements.ts — Elements panel: scene graph / ECS entity tree.
+//
+// Clicking a row selects it (Chrome-style): the .sel class flips via
+// incremental attr mutation so the scrollport survives, and a details strip
+// in the bottom chrome shows the row fields plus `getNodeJSON` output when
+// the node has a stable id and the scene inspector is live. The caret on
+// parent rows folds/unfolds the subtree.
 // ============================================================================
 import { esc } from "./types.js";
-const MODE_LABEL = { scene: "Scene graph", dom: "DOM", ecs: "ECS entities" };
+const MODE_LABEL = { scene: "Scene graph", ecs: "ECS entities" };
 const MAX_ROWS = 4000;
 export class ElementsPanel {
     id = "elements";
@@ -14,66 +18,251 @@ export class ElementsPanel {
     ctx;
     mode = "scene";
     rows = [];
+    /** Stable per-row key (nodeId or label path), parallel to rows. */
+    keys = [];
+    collapsed = new Set();
+    /** Logical selection — survives refreshes via keys. */
+    selKey = null;
+    /** Ephemeral DOM id of the row currently carrying .sel — lets pick flip
+     *  the class without a body reparse. Stale after a refresh; harmless —
+     *  renderBody re-emits .sel from selKey. */
+    selRowId = null;
+    details = null;
+    lastError = "";
+    lastSig = "";
+    /** Scroll offset of #dt-body — restored after every body re-render, since
+     *  setInnerHtml replaces the subtree and drops scrollTop. */
+    lastScrollTop = 0;
     constructor(ctx) { this.ctx = ctx; }
     renderTop() {
         const btn = (m) => `<span class="dbtn${this.mode === m ? " on" : ""}" data-action="el.mode" data-mode="${m}">${MODE_LABEL[m]}</span>`;
         return `<div class="panel-toolbar">
       <span class="dbtn" data-action="el.refresh">Refresh</span>
-      ${btn("scene")}${btn("dom")}${btn("ecs")}
+      ${btn("scene")}${btn("ecs")}
       <span class="spacer"></span>
-      <span class="count">${this.rows.length} nodes</span>
+      <span class="count">${this.rows.length} nodes${this.collapsed.size ? ` · ${this.collapsed.size} folded` : ""}</span>
     </div>`;
     }
     renderBody() {
-        if (!this.rows.length)
-            return `<div class="empty-note">no nodes</div>`;
-        const html = this.rows.slice(0, MAX_ROWS).map((n) => `<div class="trow" style="padding-left:${4 + n.depth * 14}px" data-action="el.pick" data-node="${n.id}">
-        <span>${n.childCount > 0 ? "▾" : " "} ${esc(n.label)}</span>
+        const err = this.lastError
+            ? `<div class="status-banner error">${esc(this.lastError)}</div>` : "";
+        const vis = this.visibleRows();
+        if (!vis.length)
+            return err + `<div class="empty-note">no nodes</div>`;
+        const html = vis.slice(0, MAX_ROWS).map(({ row: n, key }) => {
+            const isSel = key === this.selKey;
+            const folded = this.collapsed.has(key);
+            const caret = n.childCount > 0
+                ? `<span class="caret" data-action="el.fold" data-node="${n.id}">${folded ? "▸" : "▾"}</span>`
+                : `<span class="caret leaf"></span>`;
+            return `<div class="trow${isSel ? " sel" : ""}" style="padding-left:${4 + n.depth * 14}px" data-action="el.pick" data-node="${n.id}">
+        ${caret}<span>${esc(n.label)}</span>
         ${n.detail ? `<span class="detail">${esc(n.detail)}</span>` : ""}
         ${n.childCount > 0 ? `<span class="kids">(${n.childCount})</span>` : ""}
-      </div>`).join("");
-        const more = this.rows.length > MAX_ROWS
-            ? `<div class="empty-note">… ${this.rows.length - MAX_ROWS} more rows</div>` : "";
-        return `<div class="tree">${html}${more}</div>`;
+      </div>`;
+        }).join("");
+        const more = vis.length > MAX_ROWS
+            ? `<div class="empty-note">… ${vis.length - MAX_ROWS} more rows</div>` : "";
+        return err + `<div class="tree">${html}${more}</div>`;
     }
+    renderBottom() {
+        if (!this.details)
+            return "";
+        return `<div class="el-details">
+      <div class="el-details-head"><span class="dt-title">${esc(this.details.title)}</span>
+        <span class="spacer"></span><span class="dbtn" data-action="el.unpick">✕</span></div>
+      <div class="el-details-body lines">${esc(this.details.body)}</div>
+    </div>`;
+    }
+    // ── Data ──
+    /** Cheap change-detection — scene/ecs pushes arrive every ~2s while the
+     *  dock is visible; identical payloads must not force a re-render (it
+     *  would bounce the scrollport twice per second). */
+    applyRows(rows) {
+        const sig = JSON.stringify(rows.map((r) => [r.label, r.detail, r.childCount, r.depth, r.nodeId ?? ""]));
+        if (sig === this.lastSig)
+            return;
+        this.lastSig = sig;
+        this.setRows(rows);
+        this.dirty = true;
+        this.shellDirty = true;
+    }
+    setRows(rows) {
+        this.rows = rows;
+        // Rows arrive pre-order flattened — the parent of a row is the most
+        // recent row at depth-1. Keys: nodeId when the collector provided one,
+        // else a positional label path (stable while the tree shape holds).
+        const stack = [];
+        this.keys = rows.map((r, i) => {
+            const parent = r.depth > 0 ? (stack[r.depth - 1] ?? "") : "";
+            const k = r.nodeId ?? `${parent}/${r.label}@${i}`;
+            stack[r.depth] = k;
+            stack.length = r.depth + 1;
+            return k;
+        });
+        const present = new Set(this.keys);
+        for (const k of [...this.collapsed])
+            if (!present.has(k))
+                this.collapsed.delete(k);
+        if (this.selKey && !present.has(this.selKey)) {
+            this.selKey = null;
+            this.selRowId = null;
+            this.details = null;
+        }
+    }
+    /** Rows minus descendants of folded parents. */
+    visibleRows() {
+        const out = [];
+        const skipDepths = [];
+        for (let i = 0; i < this.rows.length; i++) {
+            const r = this.rows[i];
+            const k = this.keys[i];
+            while (skipDepths.length && r.depth <= skipDepths[skipDepths.length - 1])
+                skipDepths.pop();
+            if (!skipDepths.length)
+                out.push({ row: r, key: k });
+            if (r.childCount > 0 && this.collapsed.has(k))
+                skipDepths.push(r.depth);
+        }
+        return out;
+    }
+    localDetails(r) {
+        return [
+            `label: ${r.label}`,
+            r.detail ? `detail: ${r.detail}` : "",
+            `kind: ${r.kind === 1 ? "ecs entity" : "scene node"}`,
+            `children: ${r.childCount}`,
+            `depth: ${r.depth}`,
+            r.nodeId ? `nodeId: ${r.nodeId}` : "nodeId: (none — pick can't reach the inspector)",
+        ].filter(Boolean).join("\n");
+    }
+    async loadDetails(row, key) {
+        this.details = { title: row.label, body: this.localDetails(row) };
+        this.shellDirty = true;
+        const nodeId = row.nodeId;
+        if (!nodeId)
+            return;
+        // Best-effort inspector enrichment + in-scene selection highlight.
+        try {
+            await this.ctx.call("inspector.call", { method: "selectNode", args: [nodeId] });
+        }
+        catch { /* inspector absent or id unknown — local details stand */ }
+        try {
+            const json = await this.ctx.call("inspector.call", { method: "getNodeJSON", args: [nodeId] });
+            // A newer pick while this call was in flight wins.
+            if (this.selKey === key && typeof json === "string" && json) {
+                this.details = { title: row.label, body: json };
+                this.shellDirty = true;
+            }
+        }
+        catch { /* no inspector — keep the row-level details */ }
+    }
+    // ── Events ──
     onBackendEvent(event, data) {
-        // "scene" pushes feed the Scene-graph mode; "dom" pushes feed DOM/ECS.
+        // "scene" pushes feed scene mode; "dom" pushes feed ECS mode.
         if (event === "scene" && this.mode === "scene") {
-            this.rows = data ?? [];
-            this.dirty = true;
+            this.applyRows(data ?? []);
         }
-        else if (event === "dom" && this.mode !== "scene") {
-            this.rows = data ?? [];
-            this.dirty = true;
+        else if (event === "dom" && this.mode === "ecs") {
+            this.applyRows(data ?? []);
         }
     }
     onAction(data, _ev) {
-        if (data.action === "el.refresh") {
+        const act = data.action;
+        if (act === "el.refresh") {
             void this.refresh();
         }
-        else if (data.action === "el.mode") {
+        else if (act === "el.mode") {
             const m = data.mode;
-            if (m && m !== this.mode) {
+            if ((m === "scene" || m === "ecs") && m !== this.mode) {
                 this.mode = m;
+                this.selKey = null;
+                this.selRowId = null;
+                this.details = null;
+                this.collapsed.clear();
                 this.shellDirty = true;
+                // Point the backend's periodic push at the mode being viewed.
+                void this.ctx.call("domTree.mode", { mode: m }).catch(() => { });
                 void this.refresh();
             }
         }
+        else if (act === "el.fold") {
+            const id = Number(data.node);
+            const i = this.rows.findIndex((r) => r.id === id);
+            if (i < 0)
+                return;
+            const key = this.keys[i];
+            if (this.collapsed.has(key))
+                this.collapsed.delete(key);
+            else
+                this.collapsed.add(key);
+            this.dirty = true;
+            this.shellDirty = true;
+        }
+        else if (act === "el.pick") {
+            this.pick(Number(data.node));
+        }
+        else if (act === "el.unpick") {
+            this.unpick();
+        }
+    }
+    pick(id) {
+        const i = this.rows.findIndex((r) => r.id === id);
+        if (i < 0)
+            return;
+        const row = this.rows[i];
+        const key = this.keys[i];
+        this.selKey = key;
+        // Flip .sel via targeted mutations instead of a body re-render —
+        // reparse would reset the scrollport mid-browse. Falls back to a full
+        // render on backends without incremental ops.
+        const ops = [];
+        if (this.selRowId !== null && this.selRowId !== id) {
+            ops.push({ op: "attr", sel: `[data-node="${this.selRowId}"]`, name: "class", value: "trow" });
+        }
+        ops.push({ op: "attr", sel: `[data-node="${id}"]`, name: "class", value: "trow sel" });
+        this.ctx.mutate(ops);
+        this.selRowId = id;
+        void this.loadDetails(row, key);
+    }
+    unpick() {
+        if (this.selRowId !== null) {
+            this.ctx.mutate([{ op: "attr", sel: `[data-node="${this.selRowId}"]`, name: "class", value: "trow" }]);
+        }
+        this.selKey = null;
+        this.selRowId = null;
+        this.details = null;
+        this.shellDirty = true;
+        void this.ctx.call("inspector.call", { method: "selectNode", args: [null] }).catch(() => { });
+    }
+    onEvent(ev) {
+        if (ev.t === "scroll" && ev.id === "dt-body") {
+            this.lastScrollTop = ev.st ?? 0;
+        }
     }
     activate() {
+        // Keep the backend's push mode aligned with what's on screen.
+        void this.ctx.call("domTree.mode", { mode: this.mode }).catch(() => { });
         void this.refresh();
     }
+    afterRender() {
+        // Body reparse dropped the scroll position — put it back.
+        if (this.lastScrollTop > 0)
+            this.ctx.scrollTo("#dt-body", 0, this.lastScrollTop);
+    }
     async refresh() {
         try {
             const rows = this.mode === "scene"
                 ? await this.ctx.call("sceneTree")
-                : await this.ctx.call("domTree", { mode: this.mode === "ecs" ? "ecs" : "scene" });
-            this.rows = rows ?? [];
+                : await this.ctx.call("domTree", { mode: "ecs" });
+            this.lastError = "";
+            this.applyRows(rows ?? []);
         }
-        catch {
-            this.rows = [];
+        catch (err) {
+            // Keep the last good tree; surface the failure instead of blanking.
+            this.lastError = `refresh failed: ${String(err)}`;
         }
         this.dirty = true;
-        this.shellDirty = true; // node count in the toolbar
+        this.shellDirty = true;
     }
 }

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

@@ -19,10 +19,13 @@ export class GpuPanel {
     renderBody() {
         if (!this.info)
             return `<div class="empty-note">no GPU info</div>`;
-        const times = (this.info.frameTimes ?? []).map((t) => t[0]);
+        const times = (Array.isArray(this.info.frameTimes) ? this.info.frameTimes : [])
+            .map((t) => (Array.isArray(t) ? t[0] : 0));
         const chart = `<div class="snap-section"><h3>Frame times (ms)</h3>${chartHtml(times, { max: Math.max(16.7, ...times), label: "" })}</div>`;
         const sections = [];
-        for (const e of (this.info.entries ?? []).values()) {
+        for (const e of (Array.isArray(this.info.entries) ? this.info.entries : []).values()) {
+            if (!e || typeof e !== "object")
+                continue;
             if (e.isHeader || !sections.length) {
                 sections.push({ header: e.isHeader ? e.key : null, rows: [] });
                 if (e.isHeader)

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,9 +39,12 @@ 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.values()) {
             const h = s.history?.[0] ?? {};
             tbl += `<tr><td>${s.slotIndex}</td><td>${esc(s.name)}</td>
@@ -44,24 +53,29 @@ 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 ?? [];
+            this.slots = Array.isArray(data) ? data : [];
             for (const s of this.slots.values()) {
                 const h = s.history?.[0];
                 if (!h)
@@ -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);