lecodes-web-canvas 2.0.0

package/src/runtime/TreeUI.ts

@@ -0,0 +1,822 @@
+/// <reference path="../contract.d.ts" />
+// The tree UI: the HostUI table of the runtime (sdk/src/bridges/tree.d.ts `HostUI`) implemented
+// in TypeScript over the wasm runtime module — the shared core of the web renderers (the canvas
+// mount in the browser, the DOM renderer, the headless host). The runtime OWNS the tree (creator-ui
+// Yoga, the screens / destinations / widgets / pager / vlist); this class keeps one HNode per node
+// id (the yoga pointer), the paint-ready style creator-ui's handlers write into it, the content
+// properties, and the boxes of the last layout pass — and turns them into the render tree (the
+// RenderNode: the semantic JSON AND the paint source), hit-tests pointers over it and reports what
+// happened back to the runtime through the creatorWeb* entry points (node events, touches, scroll,
+// focus / change). Nothing of JavaScript reaches it: the SDK's element objects live behind the
+// runtime's emitter.
+import type { WasmModule } from "lecodes-web-runtime/src/gen/wasm"
+import type { WasmHostUI } from "lecodes-web-runtime/src/gen/host.gen"
+import { paintPending, readPaintOf, syncPaint, type PaintModule } from "../layout/creatorUi/paint-read"
+import type { CreatorUiModule } from "../layout/creatorUi/loadCreatorUi"
+import type { Host } from "../host/Host"
+import type { Layer, Rect, RenderNode, ResolvedStyle, WorkerNode } from "../types"
+import type { SceneNode } from "../core/SceneNode"
+import type { Painter } from "../paint/Painter"
+import { clampLines, measureEditableNode, measureImageNode, measureTextNode, resolveTextStyle, toFontSpec, wrapText } from "../core/text"
+import { paintFrame, type PaintOptions } from "../paint/paintTree"
+import { frameToText, serializeFrame } from "../serialize/serializeRenderTree"
+import { hitTest } from "../core/hitTest"
+import { svgToDataUri } from "../core/util/svgSrc"
+import {
+  TREE_DEST_SCREEN, TREE_EVENT_BLUR, TREE_EVENT_CHANGE, TREE_EVENT_FOCUS, TREE_EVENT_OVERLAY_TAP, TREE_EVENT_OVERSCROLL,
+  TREE_EVENT_SCROLL_RELEASE, TREE_EVENT_SUBMIT, TREE_FLAG_BLUR, TREE_FLAG_CHANGE, TREE_FLAG_CLICK, TREE_FLAG_FOCUS,
+  TREE_FLAG_INTERACTIVE, TREE_FLAG_LAYOUT, TREE_FLAG_LONG_PRESS, TREE_FLAG_OVERLAY_TAP, TREE_FLAG_OVERSCROLL, TREE_FLAG_SCROLL,
+  TREE_FLAG_SCROLL_RELEASE, TREE_FLAG_SUBMIT,
+} from "lecodes-sdk/ui/tree"
+
+/** Fraction of the viewport the simulated keyboard occupies while an input is focused (the number
+ *  every simulator host uses); the focused root re-flows above it (runtime pkgSetShrunkRoot). */
+const KEYBOARD_FRACTION = 0.32
+/** Drag distance (px) before a press commits to scrolling. */
+const SCROLL_THRESHOLD = 4
+
+/** One node of the runtime's tree as this renderer sees it. Structurally a web-canvas SceneNode for
+ *  the shared text / measure helpers (they read `style`, `parent`, `text`, `value`, `sourceRect`). */
+/**
+ * The image src as the SDK puts it on the wire (sdk/src/ui/UIImage.ts): a url, `id:<buffer>` (the
+ * fetch host serves it), `canvas:<id>` (a baked _creatorCanvas surface → the web-canvas host's
+ * `lecodes-canvas://` scheme), `svg:<markup>` (an inline SvgSource → the data-uri the image decoder
+ * loads, encoded once per distinct markup). A `scene2d:` source has no image: the box is the render.
+ */
+const svgUris = new Map<string, string>()
+function wireSrc(s: string | undefined): string | undefined {
+  if (!s) return s
+  if (s.startsWith("canvas:")) return `lecodes-canvas://${s.slice(7)}`
+  if (s.startsWith("svg:")) {
+    let uri = svgUris.get(s)
+    if (uri === undefined) { uri = svgToDataUri(s.slice(4)); svgUris.set(s, uri) }
+    return uri
+  }
+  return s
+}
+
+export class HNode {
+  parent: HNode | null = null
+  children: HNode[] = []
+  style: ResolvedStyle = { lineHeight: 14 * 1.2 }   // the core's fresh-node record; the first paint sync replaces it
+  name?: string
+  text = ""
+  src: string | undefined
+  value = ""
+  sourceRect?: [number, number, number, number]
+  viewName?: string
+  viewParams?: string
+  /** "playerId" of a video node / "viewId" of a native node (setPropertyInt). */
+  playerId = 0
+  viewId = 0
+  flags = 0
+  /** The box of the last layout pass (parent-relative; a root's is its own frame). */
+  layoutRect: Rect | null = null
+  scrollOffset = 0
+  wrapCache?: { key: string, lines: string[] }
+  /** The minimal WorkerNode the shared helpers expect (unused fields). */
+  readonly jsNode: Record<string, unknown>
+  constructor(readonly id: number, readonly type: string) { this.jsNode = { type, _id: id } }
+  get measured(): boolean { return this.type === "text" || this.type === "image" || this.editable }
+  get editable(): boolean { return this.type === "input" || this.type === "textarea" }
+  get scrollable(): boolean { return this.type === "scrollable" || this.type === "scrollableScreen" || this.type === "vlist" }
+  get scrollAxis(): "x" | "y" { return this.style.scrollAxis === "x" ? "x" : "y" }
+  get interactive(): boolean { return (this.flags & TREE_FLAG_INTERACTIVE) !== 0 }
+  get imageSrcRaw(): unknown { return this.type === "image" ? wireSrc(this.src) : undefined }
+  has(flag: number): boolean { return (this.flags & flag) !== 0 }
+}
+
+type Gesture = {
+  node: HNode | null       // the pressed interactive node
+  scroll: HNode | null     // the overflowing scrollable this gesture may drive
+  backdrop: HNode | null   // a modal widget whose backdrop was tapped
+  edit: HNode | null       // the editable the press landed in
+  global: boolean          // fell through to the scene
+  dismiss: boolean         // a clean release blurs the focused input
+  lastX: number
+  lastY: number
+  acc: number
+  scrolling: boolean
+  swallowClick: boolean    // a long-press listener took the gesture
+}
+
+export type TreeUIOptions = {
+  /** The app-facing keyboard listener state: the host reports the band height through the runtime. */
+  onKeyboard?: (height: number) => void
+  /** The band the on-screen keyboard takes while an input is focused, in logical px. Absent = a
+   *  simulated one (a fixed fraction of the height: the headless host, where nothing else tells);
+   *  a browser page answers with what its window really loses. */
+  keyboardHeight?: () => number
+  /** A toast to show (the headless host records it, a browser mount paints one). */
+  onToast?: (message: string, duration: number) => void
+}
+
+export class TreeUI implements WasmHostUI {
+  readonly nodes = new Map<number, HNode>()
+  /** The presented screen root (TREE_DEST_SCREEN), null while a scene / nothing is presented. */
+  root: HNode | null = null
+  /** The screen that LEFT and is still shown: the runtime moves it and the incoming one through
+   *  their own transform / opacity / dim (a transition is tween tracks on the roots — a host plays
+   *  none of its own) and drops it when the transition lands (dropView). Painted only. */
+  leaving: HNode | null = null
+  /** …over the current screen, else under it. */
+  leavingAbove = false
+  /** Per pager: the page its current tab shows, and the one that left that place and is still
+   *  shown — the runtime moves both through their own transform / opacity / dim and says when the
+   *  one that left goes (HostUI.pagerShowPage / pagerDropPage). `above` = over the page shown. */
+  private pagerShown = new Map<number, HNode>()
+  private pagerLeaving = new Map<number, { page: HNode, above: boolean }>()
+  /** TREE_DEST_* of the current destination, -1 when none. */
+  destKind = -1
+  readonly widgetRoots: HNode[] = []
+  width = 0
+  height = 0
+  private focused: HNode | null = null
+  private readonly pressed = new Set<number>()
+  private readonly gestures = new Map<number, Gesture>()
+  private readonly vlists = new Set<HNode>()
+  private frameCache: Layer[] | null = null
+  private painted: Layer[] | null = null
+  private fontsPending = 0
+  private lastToast: string | null = null
+  /** Bumped by every mutation; the render tree is rebuilt when it changed. */
+  private dirty = true
+  /** The host's hook on the destination change (TREE_DEST_*; -1 = none) — `id` is the sceneId of a
+   *  scene destination: it shows / hides its scene canvases. */
+  onDestination: ((kind: number, id: number) => void) | null = null
+  /** The destination that left was dropped (HostUI.dropView): the host takes a surface away here,
+   *  not when the next destination opens — a screen may still be coming in over it. */
+  onDropped: ((kind: number, id: number) => void) | null = null
+
+  constructor(readonly M: WasmModule, readonly host: Host, private readonly options: TreeUIOptions = {}) {}
+
+  // ---- setup ------------------------------------------------------------------------------------
+  /** Register the measure function with creator-ui (once, before any node). Style needs no
+   *  registration: the runtime keeps every node's paint record, this renderer reads it (paint-read.ts). */
+  install(): void {
+    const view = new DataView(new ArrayBuffer(8))
+    const measure = (_screenId: number, nodePtr: number, width: number, _wType: number, height: number, _hType: number): bigint => {
+      const r = this.measure(nodePtr, width, height)
+      view.setFloat32(4, r.width, true)
+      view.setFloat32(0, r.height, true)
+      return view.getBigUint64(0, true)
+    }
+    this.M._setMeasureFunc(this.M.addFunction(measure, "jiififi"))
+  }
+
+  private measure(nodeId: number, width: number, height: number): { width: number, height: number } {
+    const n = this.nodes.get(nodeId)
+    if (!n) return { width: 0, height: 0 }
+    // A layout the runtime runs before this frame's sync (it lays a screen out when it presents
+    // it) must still measure with the font the record holds NOW.
+    const P = this.M as unknown as PaintModule
+    if (paintPending(P, nodeId)) readPaintOf(P, nodeId, n.style)
+    const sn = n as unknown as SceneNode
+    if (n.type === "text") return measureTextNode(sn, this.host, width)
+    if (n.type === "image") return measureImageNode(sn, this.host, width, height)
+    if (n.editable) return measureEditableNode(sn, this.host, width)
+    return { width: 0, height: 0 }
+  }
+
+  /** The viewport in logical px; safe-area insets in CSS order + the system-bar edges. */
+  resize(width: number, height: number): void {
+    this.width = width
+    this.height = height
+    this.M._creatorWebResize(width, height)
+    this.M._setConditionValue(width, height)
+    this.dirty = true
+  }
+  setSafeArea(area: [number, number, number, number] | null, bars: readonly ("top" | "right" | "bottom" | "left")[] = []): void {
+    const [t, r, b, l] = area ?? (this.width > this.height ? [0, 8, 0, 20] : [20, 0, 8, 0])
+    const BIT = { top: 1, right: 2, bottom: 4, left: 8 }
+    this.M._setSafeAreaBars(bars.reduce((m, e) => m | BIT[e], 0))
+    this.M._setSafePaddings(t, r, b, l, 0)
+    this.dirty = true
+  }
+
+  // ---- the frame ---------------------------------------------------------------------------------
+  /** After a runtime tick: lay every live root out (the runtime's pass), read the boxes, settle the
+   *  virtualized lists, report onLayout to the nodes that listen. */
+  layoutFrame(): void {
+    const M = this.M
+    // Every style write since the last frame sits in the core's dirty paint records: take them
+    // BEFORE layout (measure reads the font) — a non-empty batch is a mutation of the render tree.
+    const changed = syncPaint(M as unknown as PaintModule, (ptr, read) => {
+      const node = this.nodes.get(ptr)
+      if (node) read(node.style)
+    })
+    if (changed > 0) this.dirty = true
+    const n = M._creatorWebLayoutFrame(this.width, this.height)
+    if (n > 0) this.readLayoutBatch(n)
+    for (const v of this.vlists) {
+      if (!M._vlistExists(v.id)) continue
+      M._vlistUpdateLayout(v.id)
+      // the mounted items are detached core roots the batch never visits: read their boxes here
+      for (const item of v.children) this.deliverSubtree(item)
+    }
+  }
+  /** Whether the render tree changed since the last `frame()` (a mount paints only then). */
+  /** Whether the picture is behind the tree: something changed since the frame that was PAINTED.
+   *  Not since the frame that was last built — a hit test or a hover builds one between a change
+   *  and the paint, and the change is still owed its picture. */
+  needsPaint(): boolean { return this.dirty || this.frameCache === null || this.frameCache !== this.painted }
+  /** Consume a subtree's new layouts (getLayoutPointer: one-shot per node) into the cached boxes. */
+  private deliverSubtree(node: HNode): void {
+    const M = this.M
+    if (!this.layoutPtr) this.layoutPtr = M._malloc(16)
+    if (M._getLayoutPointer(node.id, this.layoutPtr)) {
+      const i = this.layoutPtr >> 2
+      const rect = { x: M.HEAPF32[i], y: M.HEAPF32[i + 1], width: M.HEAPF32[i + 2], height: M.HEAPF32[i + 3] }
+      const old = node.layoutRect
+      const changed = !old || old.x !== rect.x || old.y !== rect.y || old.width !== rect.width || old.height !== rect.height
+      node.layoutRect = rect
+      if (changed) this.dirty = true
+      if (changed && node.has(TREE_FLAG_LAYOUT)) M._creatorWebNodeLayout(node.id, rect.x, rect.y, rect.width, rect.height)
+    }
+    for (const c of node.children) this.deliverSubtree(c)
+  }
+  private layoutPtr = 0
+  private readLayoutBatch(n: number): void {
+    const M = this.M
+    const nodesPtr = M._collectNodes() >>> 2
+    const rectsPtr = M._collectRects() >>> 2
+    const u32 = M.HEAPU32, f32 = M.HEAPF32
+    for (let i = 0; i < n; i++) {
+      const ptr = u32[nodesPtr + i]
+      const node = this.nodes.get(ptr)
+      if (!node) continue
+      const l = f32[rectsPtr + i * 4], t = f32[rectsPtr + i * 4 + 1], r = f32[rectsPtr + i * 4 + 2], b = f32[rectsPtr + i * 4 + 3]
+      const rect = { x: l, y: t, width: r - l, height: b - t }
+      const old = node.layoutRect
+      const changed = !old || old.x !== rect.x || old.y !== rect.y || old.width !== rect.width || old.height !== rect.height
+      node.layoutRect = rect
+      if (changed) this.dirty = true
+      if (changed && node.has(TREE_FLAG_LAYOUT)) M._creatorWebNodeLayout(ptr, l, t, rect.width, rect.height)
+    }
+  }
+
+  /** Every compositing layer, bottom-to-top: the screen — and the one that left, under or over it
+   *  — then the widgets in show order. */
+  frame(): Layer[] {
+    if (this.frameCache && !this.dirty) return this.frameCache
+    const layers: Layer[] = []
+    const viewport = { x: 0, y: 0, width: this.width, height: this.height }
+    const left = this.leaving ? this.build(this.leaving, viewport) : null
+    if (left && !this.leavingAbove) layers.push({ tree: left, leaving: true })
+    if (this.root) {
+      const tree = this.build(this.root, viewport)
+      if (tree) layers.push({ tree })
+    }
+    if (left && this.leavingAbove) layers.push({ tree: left, leaving: true })
+    for (const w of this.widgetRoots) {
+      const box = w.layoutRect ?? { x: 0, y: 0, width: this.width, height: this.height }
+      const tree = this.build(w, box)
+      if (!tree) continue
+      const color = tree.style.overlayColor
+      layers.push({ tree, widget: true, backdrop: color !== undefined ? { color, jsNode: w.jsNode as WorkerNode } : undefined })
+    }
+    this.frameCache = layers
+    this.dirty = false
+    return layers
+  }
+  renderTree(): RenderNode | null { return this.frame().find((l) => !l.widget && !l.leaving)?.tree ?? null }
+  widgetTrees(): RenderNode[] { return this.frame().filter((l) => l.widget).map((l) => l.tree) }
+  /** The widget overlay trees, in show order (the scenario engine reads them). */
+  widgets(): RenderNode[] { return this.widgetTrees() }
+  serialize(): unknown { return serializeFrame(this.renderTree(), this.widgetTrees()) }
+  toText(): string { return frameToText(this.renderTree(), this.widgetTrees()) }
+  paint(painter: Painter, options?: PaintOptions): void {
+    const frame = this.frame()
+    paintFrame(frame, painter, this.host, this.width, this.height, undefined, options)
+    this.painted = frame
+  }
+
+  /** The absolute, fully-resolved render tree of a root (the web-canvas builder, over the runtime's
+   *  boxes: a pager shows its selected page, a vlist places its mounted items at the core's offsets). */
+  private build(root: HNode, rootRect: Rect): RenderNode | null {
+    const M = this.M
+    const walk = (node: HNode, px: number, py: number, isRoot: boolean): RenderNode | null => {
+      if (node.style.display === "none") return null
+      let x: number, y: number, width: number, height: number
+      if (isRoot) { x = rootRect.x; y = rootRect.y; width = rootRect.width; height = rootRect.height }
+      else {
+        const rel = node.layoutRect
+        if (!rel) return null
+        x = px + rel.x; y = py + rel.y; width = rel.width; height = rel.height
+      }
+      const out: RenderNode = { id: node.id, type: node.type, rect: { x, y, width, height }, style: node.style, children: [] }
+      if (node.name) out.name = node.name
+      const sn = node as unknown as SceneNode
+      if (node.type === "text") {
+        const t = resolveTextStyle(sn)
+        const font = toFontSpec(t)
+        out.text = node.text
+        const pad = this.padding(node.id)
+        if (pad[0] || pad[1] || pad[2] || pad[3]) out.padding = pad
+        const contentW = width - pad[0] - pad[2]
+        const key = `${contentW}|${font.size}|${font.weight}|${font.italic ? 1 : 0}|${font.letterSpacing}|${font.family}|${node.style.lineClamp ?? 0}|${node.style.textOverflow ?? ""}|${node.text}`
+        if (node.wrapCache?.key === key) out.lines = node.wrapCache.lines
+        else {
+          const measure = (s: string) => this.host.measureText(s, font)
+          const lines = clampLines(wrapText(node.text, contentW, measure).lines, node.style, contentW, measure)
+          node.wrapCache = { key, lines }
+          out.lines = lines
+        }
+        out.style = { ...node.style, color: t.color, fontSize: t.fontSize, fontFamily: t.fontFamily, fontWeight: t.fontWeight, fontStyle: t.fontStyle, lineHeight: t.lineHeight, letterSpacing: t.letterSpacing, textAlign: t.textAlign, textDecoration: t.textDecoration }
+      } else if (node.type === "image") {
+        const src = this.host.resolveSrc(node.imageSrcRaw)
+        const info = src ? this.host.getImage(src) : undefined
+        out.image = info ?? (src ? { src, naturalWidth: 0, naturalHeight: 0 } : undefined)
+        if (node.sourceRect) out.sourceRect = node.sourceRect
+      } else if (node.editable) {
+        out.value = node.value
+        const pad = this.padding(node.id)
+        if (pad[0] || pad[1] || pad[2] || pad[3]) out.padding = pad
+        const t = resolveTextStyle(sn)
+        out.style = { ...node.style, color: t.color, fontSize: t.fontSize, fontFamily: t.fontFamily, fontWeight: t.fontWeight, fontStyle: t.fontStyle, lineHeight: t.lineHeight, letterSpacing: t.letterSpacing, textAlign: t.textAlign, textDecoration: t.textDecoration }
+      }
+      if (node.interactive) out.state = { pressed: this.pressed.has(node.id) }
+      if (node.editable && this.focused === node) out.state = { ...out.state, focused: true }
+      if (node.style.overflow === "hidden") out.clip = true
+      let childX = x, childY = y
+      if (node.scrollable) {
+        const axis = node.scrollAxis
+        const content = axis === "x" ? M._getContentWidth(node.id) : M._getContentHeight(node.id)
+        out.clip = true
+        out.scroll = { offset: node.scrollOffset, content, axis }
+        if (axis === "x") childX = x - node.scrollOffset
+        else childY = y - node.scrollOffset
+      }
+      if (node.type === "pager") {
+        // the selected tab's top page: an independent root laid out at the pager's box
+        const tab = M._creatorWebPagerSelectedIndex(node.id)
+        const len = M._creatorWebPagerStackLen(node.id, tab)
+        const pageId = len > 0 ? M._creatorWebPagerPageNode(node.id, tab, len - 1) : 0
+        const page = pageId ? this.nodes.get(pageId) : undefined
+        if (page) this.pagerShown.set(node.id, page); else this.pagerShown.delete(node.id)
+        const left = this.pagerLeaving.get(node.id)
+        for (const p of left && left.page !== page ? (left.above ? [page, left.page] : [left.page, page]) : [page]) {
+          const r = p ? walk(p, x, y, false) : null
+          if (r) out.children.push(r)
+        }
+        return out
+      }
+      if (node.type === "vlist") {
+        // mounted items: each a detached core root at the offset the window math gave it
+        for (const child of node.children) {
+          const itemRoot = M._getParentNode(child.id)
+          if (!itemRoot) continue
+          const off = M._vlistItemOffsetOf(node.id, itemRoot)
+          if (Number.isNaN(off)) continue
+          const rel = child.layoutRect ?? { x: 0, y: 0, width: 0, height: 0 }
+          const r = walk(child, x - rel.x, y + off - node.scrollOffset - rel.y, false)
+          if (r) out.children.push(r)
+        }
+        return out
+      }
+      for (const child of node.children) { const r = walk(child, childX, childY, false); if (r) out.children.push(r) }
+      return out
+    }
+    return walk(root, 0, 0, true)
+  }
+  /** A node's resolved padding, [left, top, right, bottom] (an inspector's). */
+  paddingOf(nodeId: number): [number, number, number, number] { return this.padding(nodeId) }
+  private padding(nodeId: number): [number, number, number, number] {
+    const M = this.M
+    if (!this.padPtr) this.padPtr = M._malloc(16)
+    M._getPaddingPointer(nodeId, this.padPtr)
+    const i = this.padPtr >> 2
+    return [M.HEAPF32[i], M.HEAPF32[i + 1], M.HEAPF32[i + 2], M.HEAPF32[i + 3]]
+  }
+  private padPtr = 0
+  /** Call an export that takes a C string. */
+  private withStr<T>(s: string, fn: (ptr: number) => T): T {
+    const p = this.M.stringToNewUTF8(s)
+    try { return fn(p) } finally { this.M._free(p) }
+  }
+
+  // ---- lookups ---------------------------------------------------------------------------------------
+  get(id: number): HNode | undefined { return this.nodes.get(id) }
+  /** Rendered nodes by their author-given `name`, the screen first, then the widgets. */
+  findAll(name: string): RenderNode[] {
+    const out: RenderNode[] = []
+    const walk = (n: RenderNode) => { if (n.name === name) out.push(n); for (const c of n.children) walk(c) }
+    for (const l of this.frame()) walk(l.tree)
+    return out
+  }
+  /** The absolute rect of a rendered node, null when it is not on screen. */
+  findRect(id: number): Rect | null {
+    const walk = (n: RenderNode): Rect | null => {
+      if (n.id === id) return n.rect
+      for (const c of n.children) { const r = walk(c); if (r) return r }
+      return null
+    }
+    for (const l of this.frame()) { const r = walk(l.tree); if (r) return r }
+    return null
+  }
+  /** The last toast shown (the host paints none). */
+  toast(): string | null { return this.lastToast }
+  pendingFonts(): number { return this.fontsPending }
+  keyboardHeight(): number {
+    if (!this.focused) return 0
+    return this.options.keyboardHeight ? this.options.keyboardHeight() : Math.round(this.height * KEYBOARD_FRACTION)
+  }
+  focusedId(): number { return this.focused?.id ?? 0 }
+
+  // ---- HostUI: the tree ---------------------------------------------------------------------------
+  /** The node the runtime made last (an inspector ties the element the SDK is making to it). */
+  lastCreated = 0
+  nodeFactory(id: number, type: string, parent: number, index: number): void {
+    this.lastCreated = id
+    const n = new HNode(id, type)
+    this.nodes.set(id, n)
+    if (type === "vlist") this.vlists.add(n)
+    const p = this.nodes.get(parent)
+    if (p) this.link(p, n, Math.max(0, index))
+    this.dirty = true
+  }
+  private link(p: HNode, c: HNode, index: number): void {
+    if (c.parent) c.parent.children = c.parent.children.filter((x) => x !== c)
+    c.parent = p
+    p.children.splice(Math.min(index, p.children.length), 0, c)
+  }
+  insertNode(parent: number, child: number, index: number): void {
+    const p = this.nodes.get(parent), c = this.nodes.get(child)
+    if (p && c) this.link(p, c, index)
+    this.dirty = true
+  }
+  removeNode(parent: number, child: number): void {
+    const p = this.nodes.get(parent), c = this.nodes.get(child)
+    if (!p || !c) return
+    this.forget(c)
+    p.children = p.children.filter((x) => x !== c)
+    if (c.parent === p) c.parent = null
+    if (this.pagerLeaving.get(parent)?.page === c) this.pagerLeaving.delete(parent)
+    if (this.pagerShown.get(parent) === c) this.pagerShown.delete(parent)
+    this.dirty = true
+  }
+  releaseNode(id: number): void {
+    const n = this.nodes.get(id)
+    if (!n) return
+    this.nodes.delete(id)
+    this.forget(n)
+    if (n.parent) n.parent.children = n.parent.children.filter((x) => x !== n)
+    if (this.root === n) this.root = null
+    if (this.leaving === n) this.leaving = null
+    this.pagerShown.delete(id)
+    this.pagerLeaving.delete(id)
+    for (const [pager, left] of this.pagerLeaving) if (left.page === n) this.pagerLeaving.delete(pager)
+    if (this.focused === n) { this.focused = null; this.M._creatorWebSetShrunkRoot(0, 0); this.emitKeyboard() }
+    const wi = this.widgetRoots.indexOf(n)
+    if (wi >= 0) this.widgetRoots.splice(wi, 1)
+    this.vlists.delete(n)
+    this.pressed.delete(id)
+    this.dirty = true
+  }
+  /** A node leaving the tree must leave every in-flight gesture too. */
+  private forget(n: HNode): void {
+    for (const g of this.gestures.values()) {
+      if (g.node === n) g.node = null
+      if (g.scroll === n) g.scroll = null
+      if (g.backdrop === n) g.backdrop = null
+      if (g.edit === n) g.edit = null
+    }
+    for (const c of n.children) this.forget(c)
+  }
+
+  // ---- HostUI: content -----------------------------------------------------------------------------
+  setPropertyString(id: number, prop: string, value: string | null): void {
+    const n = this.nodes.get(id)
+    if (!n) return
+    const v = value ?? ""
+    switch (prop) {
+      case "text": n.text = v; n.wrapCache = undefined; break
+      case "value": n.value = v; break
+      case "name": n.name = v || undefined; break
+      case "src": {
+        n.src = v || undefined
+        const src = this.host.resolveSrc(this.srcOf(n))
+        if (src && !this.host.getImage(src)) {
+          this.host.loadImage(src).then(() => { if (this.nodes.get(id) === n && this.M._nodeHasMeasure(id)) this.M._markNodeDirty(id); this.dirty = true }).catch(() => {})
+        }
+        break
+      }
+      case "sourceRect": {
+        const p = v.split(" ").map(Number)
+        n.sourceRect = p.length === 4 ? [p[0], p[1], p[2], p[3]] : undefined
+        break
+      }
+      case "focus": if (v === "1" || v === "true") this.focusInput(id); else if (this.focused === n) this.blurInput(); break
+      case "viewName": n.viewName = v; break
+      case "viewParams": n.viewParams = v; break
+      default: break   // viewParams, placeholder-like props reach the style through creator-ui
+    }
+    this.dirty = true
+  }
+  private srcOf(n: HNode): unknown { return wireSrc(n.src) }
+  setPropertyInt(id: number, prop: string, value: number): void {
+    const n = this.nodes.get(id)
+    if (n) { if (prop === "playerId") n.playerId = value; else if (prop === "viewId") n.viewId = value }
+    this.dirty = true
+  }
+  setFlags(id: number, mask: number): void { const n = this.nodes.get(id); if (n) n.flags = mask >>> 0 }
+
+  // ---- HostUI: presentation -------------------------------------------------------------------------
+  /** The screen that was shown stays painted until the runtime drops it — one at a time: the
+   *  runtime lands a transition before it starts the next one. */
+  private leave(above: boolean): void {
+    if (!this.root) return
+    this.leaving = this.root
+    this.leavingAbove = above
+    this.root = null
+  }
+  openView(kind: number, node: number, id: number, _viewName: string, _paramsJson: string, above: boolean): void {
+    this.destKind = kind
+    const next = kind === TREE_DEST_SCREEN ? this.nodes.get(node) ?? null : null
+    if (next !== this.root) this.leave(!above || next === null)   // a screen next to a surface is above it
+    if (this.leaving === next) this.leaving = null
+    this.root = next
+    if (this.focused) this.blurInput()   // a navigation dismisses the keyboard
+    this.dirty = true
+    this.onDestination?.(kind, id)
+  }
+  dropView(kind: number, node: number, id: number): void {
+    if (kind === TREE_DEST_SCREEN) {
+      const n = this.nodes.get(node) ?? null
+      if (n !== null && this.leaving === n) this.leaving = null
+      if (n !== null && this.root === n) this.root = null
+    }
+    this.dirty = true
+    this.onDropped?.(kind, id)
+  }
+  closeView(): void { this.destKind = -1; this.leave(true); this.dirty = true; this.onDestination?.(-1, 0) }
+  widgetOpen(node: number, _ownerKind: number, _ownerId: number, _ownerNode: number): void {
+    const w = this.nodes.get(node)
+    if (w && !this.widgetRoots.includes(w)) this.widgetRoots.push(w)
+    this.dirty = true
+  }
+  widgetClose(node: number): void {
+    const w = this.nodes.get(node)
+    for (const g of this.gestures.values()) if (g.backdrop === w) g.backdrop = null
+    const i = w ? this.widgetRoots.indexOf(w) : -1
+    if (i >= 0) this.widgetRoots.splice(i, 1)
+    this.dirty = true
+  }
+  registerFont(url: string, fontFamily: string, weight: number, style: number, onComplete: () => void, onReject: (err: string) => void): void {
+    this.fontsPending++
+    this.host.loadFont(fontFamily, url, { weight, style: style === 2 ? "italic" : "normal" })
+      .then(() => { this.invalidateText(); onComplete() }, (e) => onReject(String(e)))
+      .finally(() => { this.fontsPending-- })
+  }
+  /** A late face changes metrics without touching any style: re-measure every text leaf. */
+  private invalidateText(): void {
+    for (const n of this.nodes.values()) {
+      n.wrapCache = undefined
+      if (n.measured && n.type !== "image" && this.M._nodeHasMeasure(n.id)) this.M._markNodeDirty(n.id)
+    }
+    this.dirty = true
+  }
+  showToast(message: string, duration: number): void { this.lastToast = message; this.options.onToast?.(message, duration) }
+  getButtonPressed(node: number): boolean { return this.pressed.has(node) }
+  getTextValue(node: number): string { return this.nodes.get(node)?.value ?? "" }
+  getBoundingRect(node: number): ArrayLike<number> | null {
+    const r = this.findRect(node)
+    return r ? [r.x, r.y, r.width, r.height] : null
+  }
+  longPressHandler(pointerId: number, _node: number): void {
+    const g = this.gestures.get(pointerId)
+    if (g) g.swallowClick = true
+  }
+  vlistScroll(node: number, scrollY: number, _animated: boolean): void {
+    const n = this.nodes.get(node)
+    if (n) n.scrollOffset = scrollY
+    this.dirty = true
+  }
+  /** "select" / "content": the pages are re-read from the runtime's pulls when the frame is built;
+   *  nothing is in flight then (the runtime lands a pager's transition before either). */
+  pagerCommand(node: number, _cmd: string, _animated: boolean): void {
+    this.pagerLeaving.delete(node)
+    this.dirty = true
+  }
+  /** `page` is the top of the current tab now: the page shown there stays shown, under it or over
+   *  it, until the runtime drops it. */
+  pagerShowPage(node: number, page: number, above: boolean): void {
+    const next = this.nodes.get(page), shown = this.pagerShown.get(node)
+    if (next) this.pagerShown.set(node, next)
+    if (shown && shown !== next) this.pagerLeaving.set(node, { page: shown, above: !above })
+    this.dirty = true
+  }
+  pagerDropPage(node: number, page: number): void {
+    if (this.pagerLeaving.get(node)?.page.id === page) this.pagerLeaving.delete(node)
+    this.dirty = true
+  }
+  pagerPageMounted(_page: number, _mounted: boolean): void { this.dirty = true }
+  refreshDone(_node: number): void {}
+
+  // ---- input: focus + values --------------------------------------------------------------------------
+  private rootOf(n: HNode): HNode { let r = n; while (r.parent) r = r.parent; return r }
+  private emitKeyboard(): void {
+    const h = this.keyboardHeight()
+    this.options.onKeyboard?.(h)
+    this.M._creatorWebKeyboardEvent(h, 0)
+  }
+  focusInput(id: number): void {
+    const n = this.nodes.get(id)
+    if (!n || !n.editable || this.focused === n) return
+    if (this.focused) this.blurInput()
+    this.focused = n
+    this.M._setNodeFocused(id, 1)
+    if (n.has(TREE_FLAG_FOCUS)) this.M._creatorWebNodeEvent(id, TREE_EVENT_FOCUS)
+    // the focused-root rule: only the root that owns the input re-flows above the keyboard band
+    this.M._creatorWebSetShrunkRoot(this.rootOf(n).id, this.keyboardHeight())
+    this.emitKeyboard()
+    this.dirty = true
+  }
+  blurInput(): void {
+    const n = this.focused
+    if (!n) return
+    this.focused = null
+    this.M._setNodeFocused(n.id, 0)
+    if (n.has(TREE_FLAG_BLUR)) this.M._creatorWebNodeEvent(n.id, TREE_EVENT_BLUR)
+    this.M._creatorWebSetShrunkRoot(0, 0)
+    this.emitKeyboard()
+    this.dirty = true
+  }
+  /** A value typed by the user: onChange fires (a code-set value comes through setPropertyString). */
+  setInputValue(id: number, value: string): void {
+    const n = this.nodes.get(id)
+    if (!n) return
+    n.value = value
+    if (n.has(TREE_FLAG_CHANGE)) this.withStr(value, (p) => this.M._creatorWebNodeEventStr(id, TREE_EVENT_CHANGE, p))
+    if (this.M._nodeHasMeasure(id)) this.M._markNodeDirty(id)
+    this.dirty = true
+  }
+  /** The return key on the focused input: onSubmit with its value, then the keyboard goes. */
+  submitInput(): boolean {
+    const n = this.focused
+    if (!n) return false
+    if (n.has(TREE_FLAG_SUBMIT)) this.withStr(n.value, (p) => this.M._creatorWebNodeEventStr(n.id, TREE_EVENT_SUBMIT, p))
+    if (this.focused === n) this.blurInput()
+    return true
+  }
+
+  // ---- input: scrolling ---------------------------------------------------------------------------------
+  private scrollMax(n: HNode): number {
+    const rect = this.findRect(n.id) ?? n.layoutRect ?? { width: 0, height: 0 }
+    const viewport = n.scrollAxis === "x" ? rect.width : rect.height
+    const content = n.scrollAxis === "x" ? this.M._getContentWidth(n.id) : this.M._getContentHeight(n.id)
+    return Math.max(0, content - viewport)
+  }
+  /** Scroll a scrollable by `delta` px along its axis (clamped); onScroll / onOverscroll fire. */
+  scrollBy(id: number, delta: number): boolean {
+    const n = this.nodes.get(id)
+    if (!n || !n.scrollable) return false
+    const max = this.scrollMax(n)
+    const desired = n.scrollOffset + delta
+    const next = Math.min(max, Math.max(0, desired))
+    const over = desired < 0 ? desired : desired > max ? desired - max : 0
+    if (over !== 0 && n.has(TREE_FLAG_OVERSCROLL)) this.M._creatorWebNodeEventNum(id, TREE_EVENT_OVERSCROLL, over)
+    if (next === n.scrollOffset) return false
+    n.scrollOffset = next
+    if (n.type === "vlist" && this.M._vlistExists(id)) this.M._vlistOnScroll(id, next)
+    if (n.has(TREE_FLAG_SCROLL)) this.M._creatorWebNodeScroll(id, next)
+    this.dirty = true
+    return true
+  }
+
+  // ---- input: pointers (the tgfx renderer's routing, over the render tree) -----------------------------------
+  private topInteractive(x: number, y: number): HNode | null {
+    const layers = this.frame()
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const hit = hitTest(layers[i].tree, x, y, (n) => this.nodes.get(n.id)?.interactive ?? false)
+      if (hit) return this.nodes.get(hit.id) ?? null
+      if (layers[i].backdrop) return null
+    }
+    return null
+  }
+  private setPressed(n: HNode, pressed: boolean): void {
+    if (pressed) this.pressed.add(n.id); else this.pressed.delete(n.id)
+    if (this.nodes.get(n.id) === n) this.M._setNodePressed(n.id, pressed ? 1 : 0)
+    this.dirty = true
+  }
+  // ---- input: the mouse cursor (hover) — the tgfx renderer's tickHover over the render tree ----------------
+  private hoverX = 0
+  private hoverY = 0
+  private hoverInside = false
+  private hoverMoved = false
+  /** The cursor's position (logical px), button or not. Only stored: `tickHover` resolves the node
+   *  under it once per frame and hands it to the runtime (emitHover → `$hovered`, onMouseEnter). */
+  pointerHover(x: number, y: number): void { this.hoverX = x; this.hoverY = y; this.hoverInside = true; this.hoverMoved = true }
+  /** The cursor left the surface: nothing is hovered. */
+  pointerLeave(): void { if (!this.hoverInside) return; this.hoverInside = false; this.hoverMoved = true }
+  /** Whether this runtime module routes hover (the export landed with the 2026-09-27 rebuild). */
+  get hasHover(): boolean { return typeof this.M._creatorWebHover === "function" }
+  /** Once per frame, after layout: the topmost interactive node under the cursor → the runtime.
+   *  Resolved when the cursor moved or the frame changed under a still cursor, never otherwise. */
+  tickHover(): void {
+    if (!this.hasHover) return
+    if (!this.hoverMoved && !this.dirty) return
+    this.hoverMoved = false
+    const node = this.hoverInside ? this.topInteractive(this.hoverX, this.hoverY) : null
+    this.M._creatorWebHover(node?.id ?? 0, this.hoverX, this.hoverY)
+  }
+  pointerDown(fingerId: number, x: number, y: number): void {
+    const M = this.M
+    if (M._creatorWeb2dSceneOpen()) M._creatorWeb2dEmitPointer(0, fingerId, x, y)
+    const g: Gesture = { node: null, scroll: null, backdrop: null, edit: null, global: false, dismiss: true, lastX: x, lastY: y, acc: 0, scrolling: false, swallowClick: false }
+    this.gestures.set(fingerId, g)
+    const layers = this.frame()
+    // an editable takes the press (focus), a modal backdrop blocks below
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const e = hitTest(layers[i].tree, x, y, (n) => this.nodes.get(n.id)?.editable ?? false)
+      if (e) { const n = this.nodes.get(e.id)!; this.focusInput(n.id); g.edit = n; g.dismiss = false; return }
+      if (layers[i].backdrop) break
+    }
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const layer = layers[i]
+      const inter = hitTest(layer.tree, x, y, (n) => this.nodes.get(n.id)?.interactive ?? false)
+      const scrollHit = hitTest(layer.tree, x, y, (n) => !!n.scroll && n.scroll.content > (n.scroll.axis === "x" ? n.rect.width : n.rect.height) + 0.5)
+      const scroll = scrollHit ? this.nodes.get(scrollHit.id) ?? null : null
+      if (inter) {
+        const n = this.nodes.get(inter.id)!
+        g.node = n
+        g.scroll = scroll
+        g.dismiss = n.type !== "button"   // a control keeps the keyboard up
+        this.setPressed(n, true)
+        M._creatorWebNodeTouchStart(n.id, fingerId, x, y)
+        return
+      }
+      if (scroll) { g.scroll = scroll; return }
+      if (layer.backdrop) {
+        const r = layer.tree.rect
+        const insideBody = x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height
+        g.backdrop = insideBody ? null : this.nodes.get(layer.tree.id) ?? null
+        return
+      }
+    }
+    g.global = true
+    M._creatorWebSceneTouchStart(fingerId, x, y)
+  }
+  pointerMove(fingerId: number, x: number, y: number): void {
+    const g = this.gestures.get(fingerId)
+    if (!g) return
+    const M = this.M
+    if (M._creatorWeb2dSceneOpen()) M._creatorWeb2dEmitPointer(1, fingerId, x, y)
+    const dx = x - g.lastX, dy = y - g.lastY
+    g.lastX = x; g.lastY = y
+    g.acc += Math.abs(dx) + Math.abs(dy)
+    if (g.edit) return
+    if (!g.scrolling && g.scroll && g.acc > SCROLL_THRESHOLD) {
+      g.scrolling = true
+      if (g.node) this.setPressed(g.node, false)
+    }
+    if (g.scrolling && g.scroll) { this.scrollBy(g.scroll.id, g.scroll.scrollAxis === "x" ? -dx : -dy); return }
+    M._creatorWebTouchMove(fingerId, x, y, dx, dy)
+  }
+  pointerUp(fingerId: number, x: number, y: number): void {
+    const g = this.gestures.get(fingerId)
+    if (!g) return
+    this.gestures.delete(fingerId)
+    const M = this.M
+    if (M._creatorWeb2dSceneOpen()) M._creatorWeb2dEmitPointer(2, fingerId, x, y)
+    const dx = x - g.lastX, dy = y - g.lastY
+    M._creatorWebTouchEnd(fingerId, x, y, dx, dy)
+    if (g.edit) return
+    if (g.scrolling && g.scroll && g.scroll.has(TREE_FLAG_SCROLL_RELEASE)) M._creatorWebNodeEvent(g.scroll.id, TREE_EVENT_SCROLL_RELEASE)
+    if (g.dismiss && !g.scrolling && this.focused) this.blurInput()
+    if (g.node) {
+      this.setPressed(g.node, false)
+      if (!g.scrolling && !g.swallowClick && this.topInteractive(x, y) === g.node && g.node.has(TREE_FLAG_CLICK)) M._creatorWebNodeClick(g.node.id, fingerId, x, y)
+    } else if (g.backdrop) {
+      if (!g.scrolling && g.backdrop.has(TREE_FLAG_OVERLAY_TAP)) M._creatorWebNodeEvent(g.backdrop.id, TREE_EVENT_OVERLAY_TAP)
+    } else if (g.global) {
+      if (!g.scrolling) M._creatorWebSceneTouchClick(fingerId, x, y)
+    }
+  }
+  /** The pointer left without a release (the browser's pointercancel): every gesture state goes. */
+  pointerCancel(fingerId: number): void {
+    const g = this.gestures.get(fingerId)
+    if (!g) return
+    this.gestures.delete(fingerId)
+    const M = this.M
+    if (M._creatorWeb2dSceneOpen()) M._creatorWeb2dEmitPointer(3, fingerId, g.lastX, g.lastY)
+    if (g.node) this.setPressed(g.node, false)
+    M._creatorWebTouchCancel(fingerId)
+  }
+  /** A wheel notch over (x, y): scrolls the overflowing scrollable under it (a mouse host). */
+  wheel(x: number, y: number, dx: number, dy: number): boolean {
+    const layers = this.frame()
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const hit = hitTest(layers[i].tree, x, y, (n) => !!n.scroll && n.scroll.content > (n.scroll.axis === "x" ? n.rect.width : n.rect.height) + 0.5)
+      if (hit) { const n = this.nodes.get(hit.id); return n ? this.scrollBy(n.id, n.scrollAxis === "x" ? dx : dy) : false }
+      if (layers[i].backdrop) return false
+    }
+    return false
+  }
+  /** A long press: the runtime asks the node's listener; a handled one swallows the release's click. */
+  longPress(fingerId: number, x: number, y: number): void {
+    const g = this.gestures.get(fingerId)
+    if (g?.node && g.node.has(TREE_FLAG_LONG_PRESS)) this.M._creatorWebNodeLongPress(g.node.id, fingerId, x, y)
+  }
+  isVlist(n: HNode): boolean { return this.vlists.has(n) }
+}