@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/modules/devtools/src/blitz/panels/types.ts

@@ -0,0 +1,120 @@
+// ============================================================================
+// panels/types.ts — Blitz devtools panel contract + shared render helpers.
+//
+// A panel is a plain state object: backend push events update its state and
+// set `dirty`; the host re-renders `#dt-body` for the active dirty panel.
+// `renderTop`/`renderBottom` produce persistent chrome (toolbar, REPL row)
+// that is mounted once per tab activation — inputs living there keep focus
+// across body re-renders.
+// ============================================================================
+
+import type { DocMutation, OsrDomEvent } from "@downdraft/engine/modules/html-ui";
+
+export interface DtPanelCtx {
+  /** Backend RPC — same methods as the web frontend's call(). */
+  call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  /** Set an element's attribute (e.g. an input's `value`) — history recall. */
+  setValue(target: number | string, value: string): void;
+  /** Scroll a doc element into view (console tail pinning). */
+  scrollIntoView(target: number | string): void;
+  /** Scroll a scroll-container to absolute offsets — reaches nested
+   *  scrollports (scrollIntoView only moves the root viewport). */
+  scrollTo(target: number | string, x: number, y: number): void;
+  /** Border-box rect of a doc element in CSS px (scroll math). */
+  getRect(target: number | string): Promise<{ x: number; y: number; w: number; h: number } | null>;
+  /** Batched DOM mutations on the dock doc — panels with an incremental
+   *  update path (the console's append/trim) use this instead of returning
+   *  a whole new body from renderBody. */
+  mutate(ops: DocMutation[]): void;
+  /** True when the doc backend supports appendHtml/trimChildren — panels
+   *  fall back to full innerHTML renders when false (older cdylib). */
+  readonly incrementalDom: boolean;
+}
+
+export interface DtPanel {
+  readonly id: string;
+  readonly title: string;
+  /** Set when a body render is needed; host clears after re-render. */
+  dirty: boolean;
+  /** Set when the persistent chrome (top/bottom) needs re-rendering. */
+  shellDirty?: boolean;
+  /** Provider slot this panel views (snapshot tabs only) — the host gates
+   *  backend auto-refresh to the active slot so unviewed providers skip
+   *  their periodic collect entirely. */
+  readonly providerSlot?: number;
+  renderTop?(): string;
+  renderBody(): string;
+  renderBottom?(): string;
+  /**
+   * Optional incremental DOM flush — called instead of renderBody() when
+   * `dirty`; return true after applying mutations via ctx.mutate, or false
+   * to request a full body re-render (the host then calls renderBody).
+   */
+  flushDom?(): boolean;
+  /** `data-action` activations routed by the host. */
+  onAction?(data: Record<string, string>, ev: OsrDomEvent): void;
+  /** Raw DOM events (input, keydown, mousedown, scroll…). */
+  onEvent?(ev: OsrDomEvent): void;
+  /** Backend push events (console, scene, dom, gpu, metrics, snapshot…). */
+  onBackendEvent?(event: string, data: unknown): void;
+  /** Called on tab activation (after shell regions are mounted). */
+  activate?(): void;
+  /** Called after `#dt-body` was re-rendered (scroll pinning etc.). */
+  afterRender?(): void;
+  dispose?(): void;
+}
+
+export function esc(s: unknown): string {
+  return String(s ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+export function fmtBytes(b: unknown): string {
+  const n = Number(b) || 0;
+  if (n < 1024) return `${n} B`;
+  if (n < 1048576) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1073741824) return `${(n / 1048576).toFixed(1)} MB`;
+  return `${(n / 1073741824).toFixed(2)} GB`;
+}
+
+export const CHART_COLORS = ["#4da3ff", "#57ab5a", "#e0b341", "#e5534b", "#bc8cff", "#39c5cf"];
+
+/**
+ * Div-column chart — Blitz has no canvas/SVG, so a series renders as a flex
+ * row of colored columns. `cols` caps the column count (decimation keeps
+ * the DOM small). Each column's height is the value normalized to `max`.
+ */
+export function chartHtml(values: ArrayLike<number>, opts: {
+  max?: number;
+  cols?: number;
+  color?: string;
+  cls?: string;
+  label?: string;
+} = {}): string {
+  const vals = Array.from(values, Number);
+  const cols = opts.cols ?? 120;
+  const color = opts.color ?? CHART_COLORS[0];
+  const max = Math.max(opts.max ?? 1e-9, ...vals, 1e-9);
+  const step = Math.max(1, Math.floor(vals.length / cols));
+  const cells: string[] = [];
+  for (let i = 0; i < vals.length; i += step) {
+    const h = Math.max(0, Math.min(100, (vals[i]! / max) * 100));
+    cells.push(`<div class="col" style="height:${h.toFixed(1)}%;background:${color}"></div>`);
+  }
+  if (!cells.length) cells.push(`<div class="col" style="height:0%"></div>`);
+  const lbl = opts.label ? `<div class="chart-label">${esc(opts.label)}</div>` : "";
+  return `${lbl}<div class="chart${opts.cls ? ` ${opts.cls}` : ""}">${cells.join("")}</div>`;
+}
+
+/** Multi-series chart — one labeled strip per series. */
+export function multiChartHtml(series: { name: string; values: ArrayLike<number> }[], opts: { cols?: number } = {}): string {
+  const all = series.flatMap((s) => Array.from(s.values, Number));
+  const max = Math.max(1e-9, ...all);
+  return series.map((s, i) =>
+    chartHtml(s.values, { ...opts, max, color: CHART_COLORS[i % CHART_COLORS.length], cls: "cap", label: s.name })
+  ).join("");
+}

package/modules/devtools/src/blitz/theme.ts

@@ -0,0 +1,168 @@
+// ============================================================================
+// theme.ts — devtools dock stylesheet (Chrome-DevTools-flavored dark theme,
+// adapted from packages/devtools-web/style.css).
+// ============================================================================
+
+export const DEVTOOLS_CSS = `
+:root {
+  --bg: #16181d;
+  --bg2: #1d2026;
+  --bg3: #242832;
+  --line: #30363f;
+  --fg: #d6dbe2;
+  --fg-dim: #8b94a1;
+  --accent: #4da3ff;
+  --warn: #e0b341;
+  --err: #e5534b;
+  --ok: #57ab5a;
+  --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
+ * <html>'s content height (0), not the doc viewport. */
+html, body {
+  width: 100%; height: 100%; overflow: hidden;
+  background: var(--bg); color: var(--fg);
+  font: 12px/1.45 system-ui, sans-serif;
+}
+#dt-root {
+  /* Absolute inset — Blitz doesn't resolve height:100% against the doc
+   *  viewport, but inset:0 anchors to it (same pattern as game UI). */
+  position: absolute; inset: 0;
+  display: flex; flex-direction: column;
+}
+#dt-grip {
+  height: 5px; cursor: ns-resize; flex-shrink: 0;
+  background: var(--bg2); border-top: 1px solid var(--line);
+}
+#dt-grip:hover, #dt-grip.drag { background: var(--accent); }
+/* Blitz's hit_inner doesn't clip scrolled-off content to its scrollport, so
+ * overflow rows in #dt-body remain hit-testable over the fixed chrome. The DOM
+ * order (body first, chrome last) makes paint_children test chrome first — grid
+ * rows keep the visual order independent of DOM order. */
+#dt-chrome {
+  display: grid; flex: 1; overflow: hidden;
+  grid-template-rows: 30px auto 1fr auto auto;
+}
+
+/* ── Tab bar ── */
+#dt-tabs {
+  grid-row: 1;
+  display: flex; align-items: center; gap: 2px;
+  background: var(--bg2); border-bottom: 1px solid var(--line);
+  padding: 0 8px; height: 30px; 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); }
+.tab {
+  background: none; border: none; color: var(--fg-dim);
+  padding: 6px 10px; cursor: pointer; font: inherit;
+  border-bottom: 2px solid transparent; white-space: nowrap;
+}
+.tab:hover { color: var(--fg); }
+.tab.active { color: var(--fg); border-bottom-color: var(--accent); }
+#dt-close { color: var(--fg-dim); padding: 4px 8px; cursor: pointer; }
+#dt-close:hover { color: var(--err); }
+
+/* ── Panel regions ── */
+#dt-top { grid-row: 2; flex-shrink: 0; }
+#dt-body { grid-row: 3; min-height: 0; overflow-y: auto; overflow-x: hidden; padding: 8px; }
+#dt-bottom { grid-row: 4; flex-shrink: 0; }
+#dt-status {
+  grid-row: 5;
+  display: flex; justify-content: space-between;
+  background: var(--bg2); border-top: 1px solid var(--line);
+  padding: 3px 8px; font-size: 11px; color: var(--fg-dim); flex-shrink: 0;
+}
+
+/* ── Shared panel chrome ── */
+.panel-toolbar {
+  display: flex; gap: 8px; align-items: center;
+  padding: 4px 8px; background: var(--bg);
+  border-bottom: 1px solid var(--line);
+}
+.panel-toolbar .spacer { flex: 1; }
+.panel-toolbar .count { font-size: 11px; color: var(--fg-dim); }
+.dbtn {
+  background: var(--bg3); border: 1px solid var(--line); color: var(--fg);
+  padding: 3px 10px; border-radius: 3px; cursor: pointer;
+  font: inherit; font-size: 11px;
+}
+.dbtn:hover { border-color: var(--accent); }
+.dbtn.on { background: #2d4a72; border-color: var(--accent); }
+.dbtn.warn { color: var(--warn); }
+.status-banner { padding: 10px; color: var(--fg-dim); font-style: italic; }
+.status-banner.error { color: var(--err); font-style: normal; }
+.empty-note { color: var(--fg-dim); font-style: italic; padding: 12px; }
+
+/* ── Console ── */
+.console-log { font-family: var(--mono); font-size: 11.5px; }
+.crow { padding: 1px 4px; border-bottom: 1px solid #ffffff08; white-space: pre-wrap; }
+.crow .th { color: var(--fg-dim); margin-right: 6px; }
+.crow.sev-2 { color: var(--warn); }
+.crow.sev-3 { color: var(--err); background: #e5534b14; }
+.crow.sev-4, .crow.sev-5 { color: var(--fg-dim); }
+.crow.repl-in { color: var(--accent); }
+.console-filter {
+  background: var(--bg3); border: 1px solid var(--line); color: var(--fg);
+  font-family: var(--mono); font-size: 11px; padding: 2px 6px; border-radius: 3px;
+}
+.console-repl {
+  display: flex; gap: 6px; align-items: center;
+  padding: 4px 8px; border-top: 1px solid var(--line); background: var(--bg);
+}
+.console-repl .thr {
+  background: var(--bg3); border: 1px solid var(--line); color: var(--fg-dim);
+  font-family: var(--mono); font-size: 11px; padding: 2px 8px; border-radius: 3px;
+  cursor: pointer;
+}
+.console-repl .thr.on { color: var(--fg); border-color: var(--accent); }
+.console-repl input {
+  flex: 1; background: var(--bg3); border: 1px solid var(--line); color: var(--fg);
+  font-family: var(--mono); font-size: 12px; padding: 4px 6px; border-radius: 3px;
+}
+.console-repl input:focus { border-color: var(--accent); }
+.console-repl .prompt { color: var(--accent); font-family: var(--mono); }
+
+/* ── Tree (scene/dom/ecs) ── */
+.tree { font-family: var(--mono); font-size: 11.5px; }
+.trow { padding: 1px 4px; white-space: nowrap; }
+.trow:hover { background: var(--bg3); }
+.trow.sel { background: #2d4a72; }
+.trow .detail { color: var(--fg-dim); margin-left: 8px; }
+.trow .kids { color: var(--fg-dim); }
+
+/* ── KV / tables / snapshot panels ── */
+.snap-section { margin-bottom: 14px; }
+.snap-section > h3 {
+  font-size: 11px; text-transform: uppercase;
+  letter-spacing: .06em; color: var(--fg-dim); border-bottom: 1px solid var(--line);
+  padding-bottom: 3px; margin-bottom: 4px;
+}
+.kv { display: flex; flex-direction: column; }
+.kvrow { display: flex; border-bottom: 1px solid #ffffff08; }
+.kvrow > .k { flex: 0 0 30%; min-width: 140px; padding: 2px 6px; color: var(--fg-dim); }
+.kvrow > .v { flex: 1; padding: 2px 6px; font-family: var(--mono); font-size: 11.5px; }
+.kvrow.hdr > .k { color: var(--accent); font-weight: 600; padding-top: 8px; }
+.fl-warn { color: var(--warn); }
+.fl-err { color: var(--err); }
+table.dt { border-collapse: collapse; width: 100%; font-size: 11.5px; }
+table.dt th { text-align: left; color: var(--fg-dim); font-weight: 600; padding: 3px 8px 3px 6px; border-bottom: 1px solid var(--line); }
+table.dt td { padding: 2px 8px 2px 6px; border-bottom: 1px solid #ffffff08; font-family: var(--mono); }
+.lines { font-family: var(--mono); font-size: 11.5px; white-space: pre-wrap; }
+.controls { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
+.controls label { display: flex; align-items: center; gap: 6px; }
+.controls .val { color: var(--fg-dim); font-family: var(--mono); min-width: 42px; }
+
+/* ── Bar-strip chart (no canvas/SVG in Blitz — columns of divs) ── */
+.chart {
+  display: flex; align-items: flex-end; gap: 0;
+  width: 100%; height: 90px; background: var(--bg2);
+  border: 1px solid var(--line); border-radius: 3px;
+  padding: 2px; overflow: hidden; margin-bottom: 8px;
+}
+.chart .col { flex: 1; min-width: 1px; }
+.chart.cap { height: 60px; }
+.chart-label { font-size: 10px; color: var(--fg-dim); margin-bottom: 2px; }
+`;

package/modules/devtools/src/data-bridge.ts

@@ -69,7 +69,7 @@ export class DevToolsDataBridge {
 
     const api = this.buildApi();
     (window as any).__sceneInspector = api;
-    log.info("DevToolsDataBridge", "API exposed on window.__sceneInspector");
+    log.info("dev-tools-data-bridge", "API exposed on window.__sceneInspector");
   }
 
   protected buildApi(): Record<string, any> {

package/modules/devtools/src/index.ts

@@ -79,3 +79,9 @@ export type { BuiltinViewKind, DebugViewDescriptor } from "./debug-view-descript
 export { createMaterialStatsPanelExtension } from "./material-stats-panel";
 export type { MaterialStatsPanelOptions } from "./material-stats-panel";
 
+// Blitz devtools — docked in-window DevTools UI (F12)
+export { BlitzDevtoolsHost, createSelfHostedDevtoolsUi } from "./blitz/host";
+export type { BlitzDevtoolsOptions, DevtoolsUiSurface } from "./blitz/host";
+export { BlitzDevtoolsTok, createDevtoolsUiModule } from "./blitz/module";
+export type { DevtoolsUiModuleConfig } from "./blitz/module";
+

package/modules/devtools/src/profiling-bridge.ts

@@ -25,6 +25,10 @@ import {
     DEFAULT_RENDERER_WARNING_RULES,
     EventLoopMonitor,
     fnv1a32,
+    PROFILING_IOPS_RING_CAP,
+    PROFILING_MAX_SLOTS,
+    PROFILING_STRING_TABLE_CAP,
+    PROFILING_WARNING_RING_CAP,
     ProfilingSABReader,
     ProfilingSABWriter,
     TraceEventWriter,
@@ -34,7 +38,7 @@ import {
     type SeverityLevel,
     type TraceSource,
     type WarningContext,
-    type WarningRecordData,
+    type WarningRecordData
 } from "@downdraft/engine/profiling";
 import { createLogger } from "@downdraft/engine/util/logger";
 import { devtools } from "./api";
@@ -47,7 +51,7 @@ const log = createLogger("info");
  *  configs) degrade gracefully. */
 function normalizeTraceSource(source: TraceSource): TraceSource {
   if (source !== "in-engine") {
-    log.warn("ProfilingBridge", `traceSource "${source}" is unsupported — using the in-engine trace writer`);
+    log.warn("profiling-bridge", `traceSource "${source}" is unsupported — using the in-engine trace writer`);
     return "in-engine";
   }
   return source;
@@ -61,13 +65,13 @@ export interface ProfilingBridgeOptions {
   enableEventLoopMonitor?: boolean;
   /** Expected frame time in ms (for rAF jitter). Default: 16.67. */
   expectedFrameMs?: number;
-  /** Max slots in the ProfilingSAB. Default: 16. */
+  /** Max slots in the ProfilingSAB. Default: PROFILING_MAX_SLOTS (32). */
   maxSlots?: number;
-  /** IOPS ring capacity per slot. Default: 256. */
+  /** IOPS ring capacity per slot. Default: PROFILING_IOPS_RING_CAP (256). */
   iopsRingCap?: number;
-  /** Warning ring capacity (global). Default: 128. */
+  /** Warning ring capacity (global). Default: PROFILING_WARNING_RING_CAP (128). */
   warningRingCap?: number;
-  /** String table capacity per slot. Default: 64. */
+  /** String table capacity per slot. Default: PROFILING_STRING_TABLE_CAP (64). */
   stringTableCap?: number;
   /**
    * Reuse an externally-allocated ProfilingSAB instead of allocating a new
@@ -106,10 +110,10 @@ export class ProfilingBridge {
 
   constructor(opts: ProfilingBridgeOptions = {}) {
     this.layout = opts.sharedSAB?.layout ?? computeProfilingSABLayout(
-      opts.maxSlots ?? 16,
-      opts.iopsRingCap ?? 256,
-      opts.warningRingCap ?? 128,
-      opts.stringTableCap ?? 64,
+      opts.maxSlots ?? PROFILING_MAX_SLOTS,
+      opts.iopsRingCap ?? PROFILING_IOPS_RING_CAP,
+      opts.warningRingCap ?? PROFILING_WARNING_RING_CAP,
+      opts.stringTableCap ?? PROFILING_STRING_TABLE_CAP,
     );
     const allocated = opts.sharedSAB ?? allocateProfilingSAB(
       this.layout.maxSlots,
@@ -324,7 +328,7 @@ export class ProfilingBridge {
       // Fire callbacks
       for (const cb of this.warningCallbacks.values()) {
         try { cb(record, ctx); } catch (err) {
-          log.error("ProfilingBridge", `Warning callback error: ${err}`);
+          log.error("profiling-bridge", `Warning callback error: ${err}`);
         }
       }
 
@@ -336,7 +340,7 @@ export class ProfilingBridge {
         this.autoTraceActive = true;
         this.autoTraceWarningId = warningId;
         this.startRecording();
-        log.warn("ProfilingBridge", `Auto-trace started due to warning ${w.ruleIdHash}`);
+        log.warn("profiling-bridge", `Auto-trace started due to warning ${w.ruleIdHash}`);
         const rule = this.warningEngine.getRules().find((r) => fnv1a32(r.id) === w.ruleIdHash);
         const durationMs = rule?.autoTrace?.durationMs ?? 3000;
         const timer = setTimeout(() => {
@@ -344,7 +348,7 @@ export class ProfilingBridge {
           this.autoTraceWarningId = null;
           void this.stopRecording().then((result) => {
             this.lastAutoTrace = result;
-            log.info("ProfilingBridge", `Auto-trace captured ${result.bytes} bytes`);
+            log.info("profiling-bridge", `Auto-trace captured ${result.bytes} bytes`);
           }).catch(() => {});
         }, durationMs);
         timer.unref?.();

package/modules/devtools/src/profiling-hooks.ts

@@ -70,19 +70,28 @@ export function wireProfilingBridge(opts: WireProfilingBridgeOptions): Profiling
   if (!bridge) return null;
 
   const { renderer } = opts;
-  const prevCallbacks: ProfilingLoopCallbacks =
-    renderer.getCallbacks?.() ?? (renderer as any).callbacks ?? {};
-  renderer.setCallbacks({
-    ...prevCallbacks,
-    beforeFrame: (dt: number, elapsedTime: number) => {
-      bridge.tick();
-      prevCallbacks.beforeFrame?.(dt, elapsedTime);
-    },
-    afterFrame: (dt: number, elapsedTime: number) => {
-      prevCallbacks.afterFrame?.(dt, elapsedTime);
-      bridge.endFrame();
-    },
-  });
+  // Guard against double-wiring: bootstrapGame auto-wires the bridge when
+  // `devtools.profiling` is enabled, but older games call this themselves —
+  // a second wrap would tick/endFrame twice per frame. Worker attach below
+  // still runs every call (the worker-side attach is idempotent).
+  const marker = "__ddProfilingWired";
+  const rend = renderer as unknown as Record<string, unknown>;
+  if (!rend[marker]) {
+    rend[marker] = true;
+    const prevCallbacks: ProfilingLoopCallbacks =
+      renderer.getCallbacks?.() ?? (renderer as any).callbacks ?? {};
+    renderer.setCallbacks({
+      ...prevCallbacks,
+      beforeFrame: (dt: number, elapsedTime: number) => {
+        bridge.tick();
+        prevCallbacks.beforeFrame?.(dt, elapsedTime);
+      },
+      afterFrame: (dt: number, elapsedTime: number) => {
+        prevCallbacks.afterFrame?.(dt, elapsedTime);
+        bridge.endFrame();
+      },
+    });
+  }
 
   // Share the ProfilingSAB with each worker host so it can claim a slot.
   const sab = bridge.getProfilingSAB();

package/modules/devtools/src/scene-inspector.ts

@@ -622,7 +622,7 @@ export abstract class BaseSceneInspector extends DevToolsDataBridge {
       this.thumbnailCache.set(path, dataUrl);
       return dataUrl;
     } catch (e) {
-      log.error("BaseSceneInspector", `Thumbnail error for path ${path}: ${e}`);
+      log.error("base-scene-inspector", `Thumbnail error for path ${path}: ${e}`);
       this.evictThumbnailCache();
       this.thumbnailCache.set(path, null);
       return null;

package/modules/devtools/src/worker-sync.ts

@@ -50,12 +50,20 @@ export async function syncWorkerManifests(
   };
 }
 
+/** A crashed or still-initializing worker may never answer the manifest RPC —
+ *  bound the wait so devtools wiring can't wedge the whole game bootstrap. */
+const MANIFEST_TIMEOUT_MS = 5000;
+
 async function syncOneWorker(entry: WorkerSyncEntry): Promise<void> {
   const { prefix, proxy } = entry;
 
   let manifest: DevToolsManifest;
   try {
-    manifest = await proxy.__devtoolsGetManifest();
+    manifest = await Promise.race([
+      proxy.__devtoolsGetManifest(),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`timeout after ${MANIFEST_TIMEOUT_MS}ms`)), MANIFEST_TIMEOUT_MS)),
+    ]);
   } catch (e) {
     log.warn("devtools", `Failed to fetch manifest from worker "${prefix}": ${e}`);
     return;

package/modules/editor/src/commands/registry.ts

@@ -196,7 +196,7 @@ export class EditorCommandRegistry {
       outcome = await cmd.apply(this.ctx, validated);
     } catch (e) {
       const msg = `${commandId} failed: ${e instanceof Error ? e.message : String(e)}`;
-      log.error("EditorCommands", msg);
+      log.error("editor-commands", msg);
       throw new EditorCommandError(msg);
     }
 
@@ -325,7 +325,7 @@ export class EditorCommandRegistry {
 
   private emit(entry: JournalEntry): void {
     this.listeners.forEach((fn) => {
-      try { fn(entry); } catch (e) { log.error("EditorCommands", `listener error: ${e}`); }
+      try { fn(entry); } catch (e) { log.error("editor-commands", `listener error: ${e}`); }
     });
   }
 }

package/modules/editor/src/module.ts

@@ -51,7 +51,7 @@ export interface EditorModuleConfig {
  * Owns an HtmlUiHost + input binding + compositor registration.
  */
 function createSelfHostedUi(ctx: RendererModuleContext): HtmlUiContext {
-  const host = new HtmlUiHost(ctx.getDevice(), ctx.getFormat());
+  const host = new HtmlUiHost(ctx.getDevice(), ctx.getFormat(), undefined, { profilingTag: "editor-ui" });
   host.bindInput(ctx.getInputBus());
   ctx.onDispose(() => host.dispose());
   const unreg = ctx.registerUiCompositor?.(host.compositor);

package/modules/html-ui/src/composite.ts

@@ -5,7 +5,7 @@
 // swapchain is gamma-space *8unorm). Premultiplied-alpha blend.
 // ============================================================================
 
-import { createValidatedShaderModule } from "@downdraft/engine";
+import { createValidatedShaderModule } from "@downdraft/engine/render/shader-validator";
 
 const BLIT_WGSL = `
 struct Uniforms {

package/modules/html-ui/src/create-html-ui.ts

@@ -9,11 +9,12 @@
 // selector-scoped mutator ops so HUD ticks don't reparse the document.
 // ============================================================================
 
-import type { RendererModule, RendererModuleContext } from "@downdraft/engine";
-import { createLogger, resourceToken } from "@downdraft/engine";
+import { resourceToken } from "@downdraft/engine/ecs/resource";
 import type { OsrDomEvent } from "@downdraft/engine/libraries/blitz-ui/native-osr-ffi";
 import { GamepadSourceTok } from "@downdraft/engine/libraries/gamepad/library";
 import { UiNavRouter, type UiNavRouterOptions } from "@downdraft/engine/libraries/html-ui-kit/nav/router";
+import type { RendererModule, RendererModuleContext } from "@downdraft/engine/module/renderer-module";
+import { createLogger } from "@downdraft/engine/util/logger";
 import { HtmlUiHost, type PanelSpec, type UiPanelHandle } from "./host";
 import { renderHtml, type Child } from "./jsx-runtime";
 
@@ -40,8 +41,10 @@ export interface HtmlUiContext {
   loadResource(uiUrl: string, src: string | Uint8Array | ArrayBuffer): Promise<void>;
   /** Convenience: register a font and get the @font-face CSS rule to inject. */
   fontFaceCss(family: string, uiUrl: string): string;
-  /** True when the pointer is inside any panel rect. */
-  isPointerOverUI(): boolean;
+  /** True when the pointer is inside any panel rect. Pass coords to hit-test
+   *  a specific point (e.g. the event's clientX/Y) rather than the last seen
+   *  pointer position. */
+  isPointerOverUI(x?: number, y?: number): boolean;
   /** Per-frame hook (see createGameUi.onUpdate semantics). */
   onUpdate(fn: (dt: number, elapsed: number) => void): void;
   onResize(fn: (w: number, h: number, dpr: number) => void): void;
@@ -65,6 +68,13 @@ export interface HtmlUiOptions {
    * nav is always wired when enabled.
    */
   nav?: boolean | Omit<UiNavRouterOptions, "screenW" | "screenH">;
+  /**
+   * Upload panel frames via the ui worker's shared-device view (native only,
+   * default true). The worker queue.writeTextures straight into panel
+   * textures instead of posting SAB frames for the host to upload. `false`
+   * forces the SAB path; `DOWNDRAFT_NO_UI_GPU=1` forces it globally.
+   */
+  gpuUpload?: boolean;
   build(ui: HtmlUiContext): void;
 }
 
@@ -75,11 +85,13 @@ export const HtmlUiTok = resourceToken<HtmlUiContext>("htmlUi");
 // contexts (game UI + devtools overlay) OR together.
 const activeContexts = new Set<HtmlUiContext>();
 
-/** True when the pointer is inside any mounted html-ui panel. */
-export function isPointerOverUI(): boolean {
+/** True when the pointer is inside any mounted html-ui panel. Optional
+ *  coords hit-test a specific point instead of the last pointer position —
+ *  use the event's clientX/Y inside pointer handlers. */
+export function isPointerOverUI(x?: number, y?: number): boolean {
   let over = false;
   activeContexts.forEach((ui) => {
-    if (ui.isPointerOverUI()) over = true;
+    if (ui.isPointerOverUI(x, y)) over = true;
   });
   return over;
 }
@@ -91,7 +103,7 @@ export function createHtmlUi(options: HtmlUiOptions): RendererModule {
     version: "1.0.0",
     provides: [HtmlUiTok],
     register(ctx: RendererModuleContext) {
-      const host = new HtmlUiHost(ctx.getDevice(), ctx.getFormat());
+      const host = new HtmlUiHost(ctx.getDevice(), ctx.getFormat(), undefined, { profilingTag: `ui:${moduleName}`, gpuUpload: options.gpuUpload });
       host.bindInput(ctx.getInputBus());
       ctx.onDispose(() => host.dispose());
       const unregCompositor = ctx.registerUiCompositor?.(host.compositor);
@@ -163,7 +175,7 @@ export function createHtmlUi(options: HtmlUiOptions): RendererModule {
         },
         fontFaceCss: (family, uiUrl) =>
           `@font-face { font-family: '${family}'; src: url('${uiUrl}'); }`,
-        isPointerOverUI: () => host.isPointerOverUI(),
+        isPointerOverUI: (x, y) => host.isPointerOverUI(x, y),
         onUpdate(fn) { updateSubs.push(fn); },
         onResize(fn) { ctx.onResize(fn); },
         onDispose(fn) { disposeFns.push(fn); },