@downdraft/engine 0.2.0 → 0.3.0

package/modules/html-ui/src/doc-backend.ts

@@ -76,6 +76,19 @@ interface DocState {
   gpuTex: { ptr: number | bigint; tex: unknown; w: number; h: number } | null;
   stats: { frames: number; resolveMs: number; paintMs: number; diffMs: number; bytes: number };
   statsLast: number;
+  /** smoothWheel (PanelSpec): wheel deltas accumulate here and drain as
+   *  eased per-tick steps in pump() instead of each event repainting an
+   *  instant jump. Deltas/positions stay in doc CSS px (scale applied at
+   *  dispatch); DOM sign convention (+y = scroll down). */
+  smoothWheel: boolean;
+  wheelRx: number;
+  wheelRy: number;
+  wheelX: number;
+  wheelY: number;
+  wheelMods?: string[];
+  /** performance.now() of the last step — the ease is dt-based so the curve
+   *  holds regardless of pump cadence. */
+  wheelT: number;
 }
 
 // Bound-buffer header (u32 indices) — mirrors BoundBuf layout in lib.rs.
@@ -211,9 +224,32 @@ export function createDocCore(emit: (m: WorkerToUi) => void, gpuHooks?: DocGpuHo
     }
   }
 
+  // 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: DocState, now: number): void {
+    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 });
       if (!s.doc.pending()) continue;
@@ -284,6 +320,8 @@ export function createDocCore(emit: (m: WorkerToUi) => void, gpuHooks?: DocGpuHo
             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);
@@ -295,9 +333,16 @@ export function createDocCore(emit: (m: WorkerToUi) => void, gpuHooks?: DocGpuHo
           if (s) 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); break;
+          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) {
@@ -403,9 +448,27 @@ export function createDocCore(emit: (m: WorkerToUi) => void, gpuHooks?: DocGpuHo
           const k = s.scale;
           switch (msg.kind) {
             case "move": s.doc.pointerMove(msg.x * k, msg.y * k, msg.mods); break;
-            case "down": s.doc.pointerDown(msg.x * k, msg.y * k, msg.button, 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); break;
+            case "wheel":
+              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); break;
           }
           break;

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

@@ -10,6 +10,7 @@ import type { OsrDomEvent } from "@downdraft/engine/libraries/blitz-ui/native-os
 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 { untrackedTimeout } from "@downdraft/engine/util/session-timer";
 import { PanelBlitPass } from "./composite";
 import { createLocalBackend, createWorkerBackend, type DocBackend } from "./doc-backend";
 import type { DocInputMsg, DocMutation, NavNodeInfo, UiPointerMsg, WorkerToUi } from "./protocol";
@@ -40,6 +41,10 @@ export interface PanelSpec {
   zoom?: number;
   /** Raster-rate cap for animating docs (0 = uncapped). Static docs repaint on demand regardless. */
   maxFps?: number;
+  /** Ease wheel deltas out at frame cadence instead of applying each detent
+   *  as an instant jump — scrolling animates smoothly and repaints stay at
+   *  one per pump tick regardless of input rate. Default false. */
+  smoothWheel?: boolean;
   /** Initial markup (or `vdom` rendered beforehand by the caller). */
   html: string;
   /** When false the panel never receives pointer input and `panelAt` skips
@@ -306,7 +311,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) this.bindPanelTex(panel);
@@ -470,6 +475,9 @@ export class HtmlUiHost {
    *  `incrementalDom` is false until then, and forever on old cdylibs). */
   get docCaps(): { incrementalDom: boolean } { return this.caps; }
 
+  /** Which doc backend is live — "worker" (raster off-thread) or "local". */
+  get backendKind(): "worker" | "local" { return this.backend.kind; }
+
   /** Compositor surface for GameRenderer's end-of-frame UI pass. */
   get compositor(): { hasContent(): boolean; render(pass: GPURenderPassEncoder, w: number, h: number): void } {
     return {
@@ -511,7 +519,7 @@ export class HtmlUiHost {
       this.terminating = true;
       this.send({ type: "gpuDetach" });
       const backend = this.backend;
-      setTimeout(() => {
+      untrackedTimeout(() => {
         if (!this.gpuDetachAcked) backend.dispose();
         this.destroyRetired();
       }, 150);
@@ -912,7 +920,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);
       this.retiredTex.set(key, { tex: t, timer });

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

@@ -52,7 +52,7 @@ export interface NavNodeInfo {
 
 /** Host → backend */
 export type UiToWorker =
-  | { type: "create"; id: string; cssW: number; cssH: number; scale: number; html: string; maxFps?: number }
+  | { type: "create"; id: string; cssW: number; cssH: number; scale: number; html: string; maxFps?: number; smoothWheel?: boolean }
   | { type: "fps"; id: string; maxFps: number }
   | { type: "setHtml"; id: string; html: string }
   | { type: "resize"; id: string; cssW: number; cssH: number; scale: number }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downdraft/engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/knackstedt/downdraft.git",
@@ -865,7 +865,7 @@
     "zustand": "^5.0.2"
   },
   "peerDependencies": {
-    "@downdraft/platform-native": "^0.2.0"
+    "@downdraft/platform-native": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "@downdraft/platform-native": {