@downdraft/engine 0.1.1 → 0.2.0

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

@@ -6,9 +6,10 @@
 // done by PanelBlitPass via the compositor object exposed by `compositor`.
 // ============================================================================
 
-import type { InputEventControl, RendererInputBus } from "@downdraft/engine";
-import { createLogger } from "@downdraft/engine";
 import type { OsrDomEvent } from "@downdraft/engine/libraries/blitz-ui/native-osr-ffi";
+import type { InputEventControl, RendererInputBus } from "@downdraft/engine/module/renderer-module";
+import { getHostCapabilities, getNativeHost } from "@downdraft/engine/platform/runtime";
+import { createLogger } from "@downdraft/engine/util/logger";
 import { PanelBlitPass } from "./composite";
 import { createLocalBackend, createWorkerBackend, type DocBackend } from "./doc-backend";
 import type { DocInputMsg, DocMutation, NavNodeInfo, UiPointerMsg, WorkerToUi } from "./protocol";
@@ -30,6 +31,13 @@ export interface PanelSpec {
   z?: number;
   /** Supersample factor (raster size = rect * scale). Default 2 — crisper text. */
   scale?: number;
+  /** UI zoom — the doc is laid out at `rect/zoom` CSS px so everything renders
+   *  `zoom`× larger on screen. `scale` stays relative to display px: pair
+   *  `zoom` with `scale:1` for a native-res raster (hardest edges) or the
+   *  default `scale:2` for supersampled text. Doc-space coords (events,
+   *  getRect, navSnapshot) stay in layout CSS px — multiply by `zoom` for
+   *  display px. Pointer input is converted automatically. Default 1. */
+  zoom?: number;
   /** Raster-rate cap for animating docs (0 = uncapped). Static docs repaint on demand regardless. */
   maxFps?: number;
   /** Initial markup (or `vdom` rendered beforehand by the caller). */
@@ -49,7 +57,10 @@ interface Panel {
   spec: PanelSpec;
   rect: PanelRect;
   z: number;
+  /** Raster px per display px (PanelSpec.scale). */
   scale: number;
+  /** Display px per CSS px (PanelSpec.zoom). */
+  zoom: number;
   /** Doc layout height when it differs from rect.h (scrollable texture). */
   docH: number | null;
   /** Texture sub-region in texel px — displayed at `rect` (GPU scroll). */
@@ -65,6 +76,23 @@ interface Panel {
   /** Bound SAB frame channel — frames arrive as headers, pixels stay shared. */
   sab: SharedArrayBuffer | null;
   sabI32: Int32Array | null;
+  /** Seq of the buffer state at the last SAB upload + the rect it covered.
+   *  Dedupes poll uploads and stale "frame" messages: a message is a no-op
+   *  when a newer-or-equal upload already covered its rect. */
+  lastSeq: number;
+  lastRect: { x: number; y: number; w: number; h: number } | null;
+  /** True once the worker has demonstrably written the CURRENT texture —
+   *  set when a gpu:true frame's texPtr matches the displayed texture, and
+   *  cleared on SAB fallback (gpuFallback bind) or a stale-target frame.
+   *  While false the host uploads SAB frames itself — the doc's raster
+   *  scratch SAB is always current, so fallback needs no negotiation. */
+  gpuBound: boolean;
+  /** The texPtr the worker is confirmed to be writing — keeps retired
+   *  textures alive until the worker drops its borrow (texAck). */
+  boundPtr: bigint | null;
+  /** The texPtr of the last texBind posted — suppresses duplicate posts
+   *  and keeps the target alive while the bind may still be in flight. */
+  postedBindPtr: bigint | null;
 }
 
 const UI_TRACE = typeof process !== "undefined" && !!process.env?.DD_UI_TRACE;
@@ -89,6 +117,12 @@ export interface UiPanelHandle {
   removeAttr(target: number | string, name: string): void;
   setStyle(target: number | string, prop: string, value: string): void;
   setInnerHtml(target: number | string, html: string): void;
+  /** Append parsed HTML as the node's last children (`innerHTML +=`) —
+   *  existing children survive. No-op when the cdylib predates
+   *  dd_osr_append_html — check `HtmlUiHost.docCaps.incrementalDom`. */
+  appendHtml(target: number | string, html: string): void;
+  /** Drop all but the last `keep` children of `target`. */
+  trimChildren(target: number | string, keep: number): void;
   /** Apply multiple DOM mutations in one backend pass — a single relayout. */
   mutate(ops: DocMutation[]): void;
   focus(target?: number | string): void;
@@ -119,6 +153,9 @@ export interface UiPanelHandle {
   focusedNode(): Promise<number>;
   /** Scroll the doc so `target` is visible. */
   scrollIntoView(target: number | string, opts?: { smooth?: boolean; vertical?: "start" | "center" | "end" | "nearest"; horizontal?: "start" | "center" | "end" | "nearest" }): void;
+  /** Scroll a scroll-container node to absolute offsets — reaches nested
+   *  scrollports (scrollIntoView only moves the root viewport). */
+  scrollTo(target: number | string, x: number, y: number, smooth?: boolean): void;
   /** Snapshot every node matching `sel` with rect/zone/disabled/editable —
    *  the nav engine's focusable enumeration. */
   navSnapshot(selector: string): Promise<NavNodeInfo[]>;
@@ -149,6 +186,9 @@ export class HtmlUiHost {
   private unsubInput: Array<() => void> = [];
   private focusedPanel: string | null = null;
   private pointerPos = { x: -1, y: -1 };
+  /** Doc-backend capabilities from the `ready` handshake — e.g. whether the
+   *  loaded cdylib supports appendHtml/trimChildren. */
+  private caps = { incrementalDom: false };
 
   readonly blit: PanelBlitPass;
 
@@ -156,16 +196,88 @@ export class HtmlUiHost {
     private device: GPUDevice,
     format: GPUTextureFormat,
     backend?: DocBackend,
+    opts?: {
+      /** ProfilingSAB slot tag for this host's ui worker. */
+      profilingTag?: string;
+      /** Upload panels via the worker's shared-device view (native only).
+       *  Default true; false forces the SAB upload path. */
+      gpuUpload?: boolean;
+    },
   ) {
     this.blit = new PanelBlitPass(device, format);
     this.backend = backend ?? HtmlUiHost.spawnWorker() ?? createLocalBackend();
     this.backend.onMessage((m) => this.handleMessage(m));
+    this.profilingTag = opts?.profilingTag ?? "ui";
+    this.gpuUpload = opts?.gpuUpload !== false
+      && !(typeof process !== "undefined" && process.env?.DOWNDRAFT_NO_UI_GPU === "1");
+    // The doc-backend story isn't settled while a gpu-direct upgrade is
+    // still possible — the gpuReady ack logs the final form at info.
+    const gpuDirectPossible = this.gpuUpload
+      && this.backend.kind === "worker"
+      && getHostCapabilities().supportsMultiWorkerGpu;
+    log[gpuDirectPossible ? "debug" : "info"]("html-ui", `doc backend: ${this.backend.kind}`);
+    this.attachProfiling();
+    this.attachGpu();
+  }
+
+  private profilingTag = "ui";
+  private profilingSent = false;
+
+  // ── GPU-direct upload ──
+  // The ui worker attaches to the host's shared wgpu device (one attach per
+  // worker, all docs share it) and borrows each panel's texture by ptr —
+  // uploads become the worker's queue.writeTexture calls instead of ours.
+  private gpuUpload = true;
+  private gpuAttachSent = false;
+  private gpuReady = false;
+  private gpuDetachAcked = false;
+  private terminating = false;
+  /** Textures retired while still possibly borrowed by the worker —
+   *  destroyed on texAck or a fallback timer (whichever lands first). */
+  private retiredTex = new Map<bigint, { tex: GPUTexture; timer: ReturnType<typeof setTimeout> }>();
+
+  /** Hand the worker the shared-device attach payload. Retried from mount()
+   *  — like the profiling bridge, the native host may postdate the ctor. */
+  private attachGpu(): void {
+    if (this.gpuAttachSent || !this.gpuUpload || this.backend.kind !== "worker") return;
+    if (!getHostCapabilities().supportsMultiWorkerGpu) return;
+    const payload = getNativeHost()?.gpuShare?.payload?.();
+    if (!payload) return;
+    this.gpuAttachSent = true;
+    this.send({
+      type: "gpuAttach",
+      gpu: payload.gpu as { devicePtr: number | bigint; instancePtr: number | bigint; queuePtr: number | bigint; generation: number },
+      cells: payload.cells,
+    });
+  }
+
+  /** Hand the engine ProfilingSAB to the ui worker so the devtools perf tab
+   *  can see it. Retried from mount() — the profiling bridge is created by
+   *  initDevTools, which may run after this host exists. */
+  private attachProfiling(): void {
+    if (this.profilingSent || this.backend.kind !== "worker") return;
+    const g = globalThis as Record<string, any>;
+    const bridge = g.window?.__sceneInspector?.__getProfilingBridge?.()
+      ?? g.__sceneInspector?.__getProfilingBridge?.();
+    const sab = bridge?.getProfilingSAB?.();
+    if (!sab) return;
+    this.profilingSent = true;
+    this.send({ type: "profilingAttach", sab, workerTag: this.profilingTag, layout: bridge.getLayoutParams?.() });
   }
 
   private static spawnWorker(): DocBackend | null {
     try {
       const w = new Worker(new URL("./ui-worker.ts", import.meta.url));
-      w.addEventListener("error", (e) => log.error("html-ui", `ui-worker error: ${(e as ErrorEvent).message ?? e}`));
+      // Don't let a leaked doc worker pin the runtime after the window closes.
+      (w as any).unref?.();
+      w.addEventListener("error", (e) => {
+        // Expected terminate() during teardown fires a contentless error
+        // event — not a fault (see doc-backend.ts dispose).
+        if ((w as any).__ddExpectTerminate && !(e as ErrorEvent).message) return;
+        const ee = e as ErrorEvent;
+        const detail = ee.message ?? (ee.filename ? `${ee.filename}:${ee.lineno ?? "?"}` : `type=${e.type}`);
+        log.error("html-ui", `ui-worker error: ${detail}`);
+      });
       w.addEventListener("messageerror", (e) => log.error("html-ui", `ui-worker messageerror: ${e.data}`));
       return createWorkerBackend(w);
     } catch (err) {
@@ -177,18 +289,27 @@ export class HtmlUiHost {
   // ── Panels ──
 
   mount(spec: PanelSpec): UiPanelHandle {
+    this.attachProfiling(); // retry — the profiling bridge may postdate ctor
+    this.attachGpu(); // retry — the native host may postdate the ctor
     const id = spec.id ?? `panel-${this.nextId++}`;
     const scale = spec.scale ?? 2;
+    const zoom = spec.zoom && spec.zoom > 0 ? spec.zoom : 1;
     const panel: Panel = {
-      id, spec, rect: { ...spec.rect }, z: spec.z ?? 0, scale,
+      id, spec, rect: { ...spec.rect }, z: spec.z ?? 0, scale, zoom,
       docH: spec.docH ?? null, src: null,
       texture: null, texW: 0, texH: 0, ubo: null, bindGroup: null,
       handlers: new Set(spec.onEvent ? [spec.onEvent] : []),
-      editing: false, sab: null, sabI32: null,
+      editing: false, sab: null, sabI32: null, lastSeq: 0, lastRect: null,
+      gpuBound: false, boundPtr: null, postedBindPtr: null,
     };
     this.panels.set(id, panel);
     this.order.push(id);
-    this.send({ type: "create", id, cssW: spec.rect.w, cssH: spec.docH ?? spec.rect.h, scale, html: spec.html, maxFps: spec.maxFps });
+    // 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 });
+    // 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) this.bindPanelTex(panel);
     return this.handleFor(panel);
   }
 
@@ -233,6 +354,8 @@ export class HtmlUiHost {
       removeAttr: (t, name) => mutate({ op: "rattr", ...tgt(t), name }),
       setStyle: (t, prop, value) => mutate({ op: "style", ...tgt(t), prop, value }),
       setInnerHtml: (t, html) => mutate({ op: "innerHtml", ...tgt(t), html }),
+      appendHtml: (t, html) => mutate({ op: "appendHtml", ...tgt(t), html }),
+      trimChildren: (t, keep) => mutate({ op: "trimChildren", ...tgt(t), keep }),
       mutate: (ops) => {
         const out = filterOps(ops);
         if (out.length) this.send({ type: "mutate", id: p.id, ops: out });
@@ -248,12 +371,14 @@ export class HtmlUiHost {
         const r = p.rect;
         if (r.x === rect.x && r.y === rect.y && r.w === rect.w && r.h === rect.h) return;
         p.rect = { ...rect };
-        this.send({ type: "resize", id: p.id, cssW: rect.w, cssH: p.docH ?? rect.h, scale: p.scale });
+        this.send({ type: "resize", id: p.id, cssW: rect.w / p.zoom, cssH: p.docH ?? rect.h / p.zoom, scale: p.scale * p.zoom });
+        this.bindPanelTex(p); // rebind the worker to the resized texture
       },
       setDocHeight: (h) => {
         if (p.docH === h) return;
         p.docH = h;
-        this.send({ type: "resize", id: p.id, cssW: p.rect.w, cssH: h, scale: p.scale });
+        this.send({ type: "resize", id: p.id, cssW: p.rect.w / p.zoom, cssH: h, scale: p.scale * p.zoom });
+        this.bindPanelTex(p);
       },
       setSrcRect: (src) => { p.src = src ? { ...src } : null; },
       setZ: (z) => { p.z = z; },
@@ -286,10 +411,17 @@ export class HtmlUiHost {
       }),
       scrollIntoView: (t, opts) =>
         mutate({ op: "scrollIntoView", ...tgt(t), smooth: opts?.smooth, vertical: opts?.vertical, horizontal: opts?.horizontal }),
+      scrollTo: (t, x, y, smooth) =>
+        mutate({ op: "scrollTo", ...tgt(t), x, y, smooth }),
       click: (t) => mutate({ op: "click", ...tgt(t) }),
       sendKey: (down, key, opts) =>
         this.send({ type: "input", id: p.id, msg: { kind: "key", down, key, code: opts?.code, text: opts?.text, mods: opts?.mods } }),
-      sendPointer: (msg) => this.input(p.id, msg),
+      // Callers pass panel-local display px (like real pointer events) —
+      // convert to doc CSS px here the same way local() does.
+      sendPointer: (msg) => this.input(p.id,
+        msg.kind === "wheel"
+          ? { ...msg, x: msg.x / p.zoom, y: msg.y / p.zoom, deltaX: msg.deltaX / p.zoom, deltaY: msg.deltaY / p.zoom }
+          : { ...msg, x: msg.x / p.zoom, y: msg.y / p.zoom }),
       navSnapshot: (sel) => new Promise((resolve) => {
         const reqId = this.nextReqId++;
         this.navReqs.set(reqId, resolve);
@@ -304,7 +436,7 @@ export class HtmlUiHost {
     if (!p) return;
     this.panels.delete(id);
     this.order = this.order.filter((x) => x !== id);
-    p.texture?.destroy();
+    this.retireTexture(p);
     p.ubo?.destroy();
     p.sab = null;
     p.sabI32 = null;
@@ -326,16 +458,30 @@ export class HtmlUiHost {
     return () => { set.delete(fn); };
   }
 
-  /** True when the pointer is inside any panel rect (UI owns the cursor). */
-  isPointerOverUI(): boolean {
-    return this.panelAt(this.pointerPos.x, this.pointerPos.y) !== null;
+  /** True when the pointer is inside any panel rect (UI owns the cursor).
+   *  Optional coords hit-test a specific point instead of the last seen
+   *  pointer position — the right check inside pointer-event handlers, where
+   *  pointerPos may lag the event. */
+  isPointerOverUI(x?: number, y?: number): boolean {
+    return this.panelAt(x ?? this.pointerPos.x, y ?? this.pointerPos.y) !== null;
   }
 
+  /** Doc-backend capabilities (populated by the `ready` handshake —
+   *  `incrementalDom` is false until then, and forever on old cdylibs). */
+  get docCaps(): { incrementalDom: boolean } { return this.caps; }
+
   /** Compositor surface for GameRenderer's end-of-frame UI pass. */
   get compositor(): { hasContent(): boolean; render(pass: GPURenderPassEncoder, w: number, h: number): void } {
     return {
-      hasContent: () => [...this.panels.values()].some((p) => p.bindGroup !== null),
+      // Polling here (not only in render) means a freshly-bound panel's
+      // first SAB frame lands the same frame — hasContent is what gates the
+      // compositor into the UI pass.
+      hasContent: () => {
+        this.pollSabFrames();
+        return [...this.panels.values()].some((p) => p.bindGroup !== null);
+      },
       render: (pass, w, h) => {
+        this.pollSabFrames();
         const draw = this.sortedPanels()
           .filter((p) => p.bindGroup && p.ubo)
           .map((p) => ({
@@ -354,10 +500,30 @@ export class HtmlUiHost {
     this.unsubInput.forEach((u) => u());
     this.unsubInput = [];
     if (this.moveTimer) { clearTimeout(this.moveTimer); this.moveTimer = null; }
-    for (const p of this.panels.values()) { p.texture?.destroy(); p.ubo?.destroy(); p.sab = null; p.sabI32 = null; }
+    for (const p of this.panels.values()) { this.retireTexture(p); p.ubo?.destroy(); p.sab = null; p.sabI32 = null; }
     this.panels.clear();
     this.order = [];
+    if (this.gpuAttachSent && this.backend.kind === "worker" && !this.gpuDetachAcked) {
+      // Graceful detach: let the worker drop its shared-device view before
+      // terminate() kills it — an un-detached view stalls the broker's
+      // retire() until timeout, and retired textures must outlive the
+      // worker's last writeTexture. Both settle on gpuDetached or 150ms.
+      this.terminating = true;
+      this.send({ type: "gpuDetach" });
+      const backend = this.backend;
+      setTimeout(() => {
+        if (!this.gpuDetachAcked) backend.dispose();
+        this.destroyRetired();
+      }, 150);
+      return;
+    }
     this.backend.dispose();
+    this.destroyRetired();
+  }
+
+  private destroyRetired(): void {
+    for (const r of this.retiredTex.values()) { clearTimeout(r.timer); r.tex.destroy(); }
+    this.retiredTex.clear();
   }
 
   // ── Input coalescing ──
@@ -402,7 +568,7 @@ export class HtmlUiHost {
     };
     const input = (id: string, msg: DocInputMsg) => this.input(id, msg);
     const local = (p: Panel, e: { clientX: number; clientY: number }) => ({
-      x: e.clientX - p.rect.x, y: e.clientY - p.rect.y,
+      x: (e.clientX - p.rect.x) / p.zoom, y: (e.clientY - p.rect.y) / p.zoom,
     });
 
     this.unsubInput.push(
@@ -440,7 +606,7 @@ export class HtmlUiHost {
         const p = this.panelAt(e.clientX, e.clientY);
         if (!p) return;
         ctrl.stopPropagation();
-        input(p.id, { kind: "wheel", ...local(p, e), deltaX: e.deltaX, deltaY: e.deltaY, mods: modsOf(e) });
+        input(p.id, { kind: "wheel", ...local(p, e), deltaX: e.deltaX / p.zoom, deltaY: e.deltaY / p.zoom, mods: modsOf(e) });
       }, -10),
       bus.onKeyDown((e: KeyboardEvent, ctrl: InputEventControl) => {
         const p = this.focusedPanel ? this.panels.get(this.focusedPanel) : null;
@@ -498,36 +664,90 @@ export class HtmlUiHost {
         if (!p) return;
         p.sab = m.buf;
         p.sabI32 = new Int32Array(m.buf);
+        // Fresh buffer — its seqlock restarts at 0, so reset the dedupe
+        // state or the stale lastSeq could suppress real uploads.
+        p.lastSeq = 0;
+        p.lastRect = null;
+        // gpuFallback binds mean the worker dropped GPU-direct delivery —
+        // resume host-side uploads. Plain binds just keep p.sab current so
+        // fallback is instant when needed.
+        if (m.gpuFallback === true) {
+          p.gpuBound = false;
+          p.boundPtr = null;
+        }
+        break;
+      }
+      case "gpuReady": {
+        this.gpuReady = m.ok;
+        log.info("html-ui", `doc backend: ${this.backend.kind}${m.ok ? " (gpu-direct)" : ""}`);
+        if (m.ok) {
+          this.panels.forEach((p) => this.bindPanelTex(p));
+        }
+        break;
+      }
+      case "gpuDetached": {
+        this.gpuDetachAcked = true;
+        if (this.terminating) {
+          this.backend.dispose();
+          this.destroyRetired();
+        }
+        break;
+      }
+      case "texAck": {
+        // The worker dropped its borrow of this ptr — safe to destroy the
+        // retired texture now (no worker FFI call can still be in flight).
+        const ptr = BigInt(m.texPtr);
+        const r = this.retiredTex.get(ptr);
+        if (r) {
+          this.retiredTex.delete(ptr);
+          clearTimeout(r.timer);
+          r.tex.destroy();
+        }
+        // Release bookkeeping — a bind for the same ptr may be reposted.
+        const p = this.panels.get(m.id);
+        if (p) {
+          if (p.postedBindPtr === ptr) p.postedBindPtr = null;
+          if (p.boundPtr === ptr) { p.boundPtr = null; p.gpuBound = false; }
+        }
         break;
       }
       case "frame": {
         const p = this.panels.get(m.id);
         if (process.env.DD_UI_TRACE_FRAMES === "1") {
-          log.info("html-ui", `frame ${m.id} x=${m.x} y=${m.y} w=${m.w} h=${m.h} pw=${m.pw} ph=${m.ph} seq=${m.seq ?? "-"}`);
+          log.info("html-ui", `frame ${m.id} x=${m.x} y=${m.y} w=${m.w} h=${m.h} pw=${m.pw} ph=${m.ph} seq=${m.seq ?? "-"} gpu=${m.gpu === true}${m.texPtr !== undefined ? ` tex=${m.texPtr}` : ""}`);
         }
         if (!p) return;
+        if (m.gpu === true) {
+          // GPU-direct: the worker already wrote the dirty rect into a
+          // texture — nothing to upload when it's the displayed one. A
+          // mismatched texPtr means the worker is writing a stale target
+          // (a bind it ignored, or a texture retired underneath it): fall
+          // back to SAB and repost the live texture's bind to reconverge.
+          const cur = p.texture ? BigInt((p.texture as unknown as { ptr: number | bigint }).ptr) : null;
+          const fp = m.texPtr !== undefined ? BigInt(m.texPtr) : null;
+          if (fp === null || fp !== cur) {
+            if (p.gpuBound) { p.gpuBound = false; p.boundPtr = null; }
+            if (cur !== null && p.postedBindPtr !== cur) this.bindPanelTex(p);
+            break;
+          }
+          // Confirmed: the worker uploads the displayed texture itself —
+          // host-side SAB uploads stay skipped until the next fallback.
+          p.gpuBound = true;
+          p.boundPtr = fp;
+          if (p.texW !== m.pw || p.texH !== m.ph) this.bindPanelTex(p);
+          break;
+        }
         if (m.seq !== undefined && m.stride !== undefined && p.sab && p.sabI32) {
+          if (p.gpuBound) break; // stale seq frame — worker owns uploads now
           // Zero-copy path: the backend wrote the dirty rect into the shared
-          // buffer — seqlock-check and upload straight from it. Use the
-          // message's captured rect, NOT the live SAB header: a newer write
-          // may have already overwritten the header, and re-reading it would
-          // silently drop this emit's dirty region (ghost pixels).
-          const i32 = p.sabI32;
-          const seq0 = Atomics.load(i32, 0);
-          if (seq0 === 0 || (seq0 & 1) !== 0) { this.send({ type: "refresh", id: p.id }); break; }
-          const x = m.x, y = m.y, w = m.w, h = m.h;
-          const pw = m.pw, ph = m.ph, stride = m.stride;
-          if (w <= 0 || h <= 0) break;
-          this.ensureTexture(p, pw, ph);
-          if (!p.texture) break;
-          this.device.queue.writeTexture(
-            { texture: p.texture, origin: [x, y, 0] },
-            p.sab as unknown as GPUAllowSharedBufferSource,
-            { offset: 64 + y * stride + x * 4, bytesPerRow: stride, rowsPerImage: h },
-            { width: w, height: h, depthOrArrayLayers: 1 },
-          );
-          // Torn read (a newer write started mid-upload) — ask for a re-emit.
-          if (Atomics.load(i32, 0) !== seq0) this.send({ type: "refresh", id: p.id });
+          // buffer. Skip when a poll already uploaded this emit (or a newer
+          // frame covering its rect) — otherwise upload the message's
+          // captured rect: superseded header entries still carry regions the
+          // newest frame's rect may not cover.
+          const r = p.lastRect;
+          if (p.lastSeq >= m.seq && r &&
+              m.x >= r.x && m.y >= r.y && m.x + m.w <= r.x + r.w && m.y + m.h <= r.y + r.h) break;
+          this.uploadSabFrame(p, m.x, m.y, m.w, m.h, m.pw, m.ph, m.stride);
           break;
         }
         if (!m.pixels) break;
@@ -603,13 +823,107 @@ export class HtmlUiHost {
         break;
       }
       case "error": log.error("html-ui", `doc ${m.id} backend error: ${m.message}`); break;
-      case "ready": break;
+      case "ready": {
+        this.caps.incrementalDom = m.caps?.incrementalDom === true;
+        break;
+      }
+    }
+  }
+
+  /** Upload one dirty rect straight out of the panel's bound SAB, seqlock
+   *  verified. Records lastSeq/lastRect so the poll path and late "frame"
+   *  messages don't re-upload the same content. */
+  private uploadSabFrame(p: Panel, x: number, y: number, w: number, h: number, pw: number, ph: number, stride: number): void {
+    if (p.gpuBound) return; // the worker uploads directly — don't race it
+    const i32 = p.sabI32!;
+    const seq0 = Atomics.load(i32, 0);
+    // seq0 === 0 → bound but nothing emitted yet; odd → write in progress.
+    // A frame message implies a write, so ask for a re-emit; the poll path
+    // skips both cases itself and just retries next frame.
+    if (seq0 === 0 || (seq0 & 1) !== 0) { this.send({ type: "refresh", id: p.id }); return; }
+    if (w <= 0 || h <= 0) return;
+    this.ensureTexture(p, pw, ph);
+    if (!p.texture) return;
+    this.device.queue.writeTexture(
+      { texture: p.texture, origin: [x, y, 0] },
+      p.sab as unknown as GPUAllowSharedBufferSource,
+      { offset: 64 + y * stride + x * 4, bytesPerRow: stride, rowsPerImage: h },
+      { width: w, height: h, depthOrArrayLayers: 1 },
+    );
+    // Torn read (a newer write started mid-upload) — ask for a re-emit.
+    if (Atomics.load(i32, 0) !== seq0) { this.send({ type: "refresh", id: p.id }); return; }
+    p.lastSeq = seq0;
+    p.lastRect = { x, y, w, h };
+  }
+
+  /** Poll bound SAB frame channels once per render frame and upload pending
+   *  dirty rects directly — the worker's "frame" postMessage is delivered on
+   *  a macrotask boundary, so waiting for it can cost a whole frame of lag
+   *  when it lands behind a long renderFrame. The header only describes the
+   *  newest emit; superseded dirty rects still arrive via their messages. */
+  private pollSabFrames(): void {
+    for (const p of this.panels.values()) {
+      const i32 = p.sabI32;
+      if (!i32 || !p.sab || p.gpuBound) continue;
+      const seq0 = Atomics.load(i32, 0);
+      if (seq0 === 0 || (seq0 & 1) !== 0 || seq0 === p.lastSeq) continue;
+      const x = i32[1], y = i32[2], w = i32[3], h = i32[4];
+      const pw = i32[5], ph = i32[6], stride = i32[8];
+      this.uploadSabFrame(p, x, y, w, h, pw, ph, stride);
+    }
+  }
+
+  /**
+   * Create (or recreate) the panel texture and post it to the worker as a
+   * borrowed upload target. No-op when the worker's attach hasn't resolved
+   * or a bind for the same texture is already in flight/confirmed. Host
+   * uploads keep flowing until a gpu:true frame proves the worker is
+   * writing the displayed texture — an ignored bind is a no-op, never a
+   * deadlock. Raster dims are always rect*scale — the doc's layout height
+   * may exceed the display rect for scrollable views (docH).
+   */
+  private bindPanelTex(p: Panel): void {
+    if (!this.gpuReady || this.backend.kind !== "worker") return;
+    const pw = Math.max(1, Math.round(p.rect.w * p.scale));
+    // docH is a layout-px override: it scales by zoom like the doc does.
+    const ph = Math.max(1, Math.round((p.docH !== null ? p.docH * p.zoom : p.rect.h) * p.scale));
+    this.ensureTexture(p, pw, ph);
+    if (!p.texture) return;
+    const ptr = BigInt((p.texture as unknown as { ptr: number | bigint }).ptr);
+    if (p.postedBindPtr === ptr || (p.gpuBound && p.boundPtr === ptr)) return;
+    this.send({ type: "texBind", id: p.id, texPtr: ptr, w: pw, h: ph, format: "rgba8unorm" });
+    p.postedBindPtr = ptr;
+  }
+
+  /**
+   * Release a panel's texture — deferred when the worker may still be
+   * writing through it. A bound texture's ptr could be mid-writeTexture on
+   * the worker right now; destroying the handle while an FFI call derefs it
+   * is a use-after-free inside the shim. Bound textures go to retiredTex
+   * and die on texAck (worker swapped) or a 1s fallback timer (worker gone).
+   */
+  private retireTexture(p: Panel): void {
+    const t = p.texture;
+    p.texture = null;
+    if (!t) return;
+    const ptr = (t as unknown as { ptr?: number | bigint }).ptr;
+    const borrowed = ptr !== undefined
+      && ((p.boundPtr !== null && BigInt(ptr) === p.boundPtr)
+        || (p.postedBindPtr !== null && BigInt(ptr) === p.postedBindPtr));
+    if (borrowed) {
+      const key = BigInt(ptr);
+      const timer = setTimeout(() => {
+        if (this.retiredTex.delete(key)) t.destroy();
+      }, 1000);
+      this.retiredTex.set(key, { tex: t, timer });
+      return;
     }
+    t.destroy();
   }
 
   private ensureTexture(p: Panel, w: number, h: number): void {
     if (p.texture && p.texW === w && p.texH === h) return;
-    p.texture?.destroy();
+    this.retireTexture(p);
     const tw = Math.max(1, w), th = Math.max(1, h);
     p.texture = this.device.createTexture({
       size: { width: tw, height: th },

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

@@ -4,7 +4,7 @@ export type { CompositePanel } from "./composite";
 export { createHtmlUi, HtmlUiTok, isPointerOverUI } from "./create-html-ui";
 export type { HtmlUiContext, HtmlUiOptions, UISubscribable } from "./create-html-ui";
 export { createDocCore, createLocalBackend, createWorkerBackend } from "./doc-backend";
-export type { DocBackend } from "./doc-backend";
+export type { DocBackend, DocGpuHooks, DocGpuView } from "./doc-backend";
 export { HtmlUiHost } from "./host";
 export type { PanelActionHandler, PanelEventHandler, PanelRect, PanelSpec, UiPanelHandle } from "./host";
 export { Fragment, jsx, jsxDEV, jsxs, renderHtml } from "./jsx-runtime";

package/modules/html-ui/src/jsx-runtime.ts

@@ -13,7 +13,7 @@
 // event queue, dispatched by data-action / selector handlers.
 // ============================================================================
 
-import { createLogger } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
 
 const log = createLogger();
 
@@ -93,7 +93,7 @@ function renderNode(v: VNode): string {
     return out.join("");
   }
   if (typeof t === "function") {
-    const r = t({ ...(p ?? {}) });
+    const r = t({ ...p });
     const out: string[] = [];
     renderInner(r as Child, out);
     return out.join("");