lecodes-viewer 0.19.0

package/src/ui/CuiProps.gen.ts

@@ -0,0 +1,103 @@
+// AUTO-GENERATED from packages/creator-ui/properties.mjs — DO NOT EDIT. Regenerate: bun run gen:ui-props
+//
+// The per-key host property surface of the creator-ui core (docs/ui-property-registry-plan.md):
+// wire channel + host-reset marking for every add*Handler key. Hosts implement a full Record
+// over CuiHostPropKey — the compiler enforces that every property is either implemented or
+// explicitly "unsupported", and that reset handlers exist exactly where the registry says.
+// transform (matrix) and backgroundGradient (struct) use setMatrixHandler/setGradientHandler.
+
+export type CuiChannel = "float" | "uint" | "string"
+
+export interface CuiHostPropMeta {
+  readonly channel: CuiChannel
+  /** On the host ResetHandler surface (presence / theme-fallback props): a reset
+   *  implementation is REQUIRED (or the whole prop marked "unsupported"). All other props
+   *  reset through the normal set channel and must NOT register a reset handler. */
+  readonly hostReset: boolean
+  /** Node-type applicability; a dispatch to any other node type is a defined no-op. */
+  readonly nodes: "all" | readonly string[]
+}
+
+export const CUI_HOST_PROPS = {
+  // ---- layout ----
+  display: { channel: "string", hostReset: false, nodes: "all" },
+  overflow: { channel: "string", hostReset: false, nodes: "all" },
+  // ---- scroll ----
+  scrollDirection: { channel: "float", hostReset: false, nodes: ["scrollable"] },
+  // ---- border ----
+  borderWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderTopWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderRightWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderBottomWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderLeftWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderHorizontalWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderVerticalWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderStartWidth: { channel: "float", hostReset: false, nodes: "all" },
+  borderEndWidth: { channel: "float", hostReset: false, nodes: "all" },
+  // ---- text ----
+  color: { channel: "uint", hostReset: true, nodes: "all" },
+  // ---- box ----
+  backgroundColor: { channel: "uint", hostReset: false, nodes: "all" },
+  // ---- border ----
+  borderColor: { channel: "uint", hostReset: false, nodes: "all" },
+  borderTopColor: { channel: "uint", hostReset: false, nodes: "all" },
+  borderRightColor: { channel: "uint", hostReset: false, nodes: "all" },
+  borderBottomColor: { channel: "uint", hostReset: false, nodes: "all" },
+  borderLeftColor: { channel: "uint", hostReset: false, nodes: "all" },
+  // ---- input ----
+  placeholderColor: { channel: "uint", hostReset: true, nodes: ["input"] },
+  // ---- scroll ----
+  refreshControlColor: { channel: "uint", hostReset: true, nodes: ["scrollable"] },
+  // ---- image ----
+  tintColor: { channel: "uint", hostReset: true, nodes: ["image"] },
+  // ---- box ----
+  rippleColor: { channel: "uint", hostReset: false, nodes: ["button"] },
+  // ---- widget ----
+  overlayColor: { channel: "uint", hostReset: true, nodes: ["widget"] },
+  // ---- box ----
+  backgroundImage: { channel: "string", hostReset: false, nodes: "all" },
+  backgroundSize: { channel: "string", hostReset: false, nodes: "all" },
+  backgroundGradientStr: { channel: "string", hostReset: false, nodes: "all" },
+  // ---- border ----
+  borderRadius: { channel: "float", hostReset: false, nodes: "all" },
+  borderTopLeftRadius: { channel: "float", hostReset: false, nodes: "all" },
+  borderTopRightRadius: { channel: "float", hostReset: false, nodes: "all" },
+  borderBottomRightRadius: { channel: "float", hostReset: false, nodes: "all" },
+  borderBottomLeftRadius: { channel: "float", hostReset: false, nodes: "all" },
+  // ---- effects ----
+  opacity: { channel: "float", hostReset: false, nodes: "all" },
+  pointerEvents: { channel: "string", hostReset: false, nodes: "all" },
+  // ---- text ----
+  fontSize: { channel: "float", hostReset: false, nodes: ["text", "input"] },
+  fontWeight: { channel: "float", hostReset: false, nodes: ["text", "input"] },
+  fontStyle: { channel: "float", hostReset: false, nodes: ["text", "input"] },
+  fontFamily: { channel: "string", hostReset: true, nodes: ["text", "input"] },
+  lineHeight: { channel: "float", hostReset: false, nodes: ["text", "input"] },
+  letterSpacing: { channel: "float", hostReset: false, nodes: ["text", "input"] },
+  textAlign: { channel: "string", hostReset: false, nodes: ["text", "input"] },
+  textDecoration: { channel: "string", hostReset: false, nodes: ["text"] },
+  lineClamp: { channel: "float", hostReset: false, nodes: ["text"] },
+  textOverflow: { channel: "string", hostReset: false, nodes: ["text"] },
+  // ---- image ----
+  objectFit: { channel: "string", hostReset: false, nodes: ["image", "video"] },
+  // ---- input ----
+  placeholder: { channel: "string", hostReset: false, nodes: ["input"] },
+  type: { channel: "string", hostReset: false, nodes: ["input"] },
+  enterKey: { channel: "string", hostReset: false, nodes: ["input"] },
+  autocapitalize: { channel: "string", hostReset: false, nodes: ["input"] },
+  autocorrect: { channel: "float", hostReset: false, nodes: ["input"] },
+  maxLength: { channel: "float", hostReset: false, nodes: ["input"] },
+  keyboardShrink: { channel: "float", hostReset: false, nodes: ["input"] },
+  keyboardDismiss: { channel: "float", hostReset: false, nodes: ["input"] },
+  // ---- scroll ----
+  showScrollbar: { channel: "float", hostReset: false, nodes: ["scrollable"] },
+  overscrollMode: { channel: "string", hostReset: false, nodes: ["scrollable"] },
+  keyboardDismissMode: { channel: "string", hostReset: false, nodes: ["scrollable", "vlist"] },
+  snap: { channel: "string", hostReset: false, nodes: ["scrollable"] },
+  // ---- widget ----
+  sheetDetents: { channel: "string", hostReset: false, nodes: ["widget"] },
+  sheetDetent: { channel: "float", hostReset: false, nodes: ["widget"] },
+  sheetDismissible: { channel: "float", hostReset: false, nodes: ["widget"] },
+} as const satisfies Record<string, CuiHostPropMeta>
+
+export type CuiHostPropKey = keyof typeof CUI_HOST_PROPS

package/src/ui/UIScreen.ts

@@ -0,0 +1,486 @@
+import { UINode } from "ui"
+import { TouchSystem } from "./createTouchSystem"
+import { createNodeElement } from "./createNodeElement"
+import {
+  configureImage,
+  setImageSourceRect,
+  tintSvgImage,
+  untintSvgImage,
+  updateImageSrc,
+  refreshCanvasSurface,
+} from "../utils/imageNode"
+import { configureVideo } from "../utils/videoNode"
+import { ImageSrc } from "../utils/svg"
+import { createVListSystem } from "./vListSystem"
+import type { PagerSystem } from "./createPagerSystem"
+import type { NativeViewSystem } from "./nativeViewSystem"
+const LAYER_DEFAULT = 256
+
+export type ApplyStyleCallback = (
+  layer: number,
+  yogaId: number,
+  key: string,
+  value: string | number,
+) => void
+
+export class UIScreen {
+
+  module: any
+  touchSystem: TouchSystem
+  applyStyle: ApplyStyleCallback
+  /** Resolve a user style class ("$"+name) to its layer id (shares createUI's interned-key cache). */
+  classLayer: (nodeId: number, name: string) => number
+  deregister: (screenId: number) => void
+  /** Resolve a baked `_creatorCanvas` surface id to a data-uri, for UIImage(canvas). */
+  canvasHost?: { surfaceToDataUrl(surfaceId: number): string | null }
+
+  layoutPtrBytes: number
+  layoutPtr: number
+  paddingPtrBytes: number
+  paddingPtr: number
+
+  vlistSystem: ReturnType<typeof createVListSystem>
+  pagerSystem: PagerSystem
+  nativeViewSystem?: NativeViewSystem
+
+  // Set on widget roots by showWidget(widget, owner): the destination descriptor this widget is
+  // attached to. createUI toggles the widget's visibility to track the owner's presentation.
+  ownerDesc?: any
+
+  constructor(module: any, touchSystem: TouchSystem, applyStyle: ApplyStyleCallback, classLayer: (nodeId: number, name: string) => number, vlistSystem: ReturnType<typeof createVListSystem>, pagerSystem: PagerSystem, deregister: (screenId: number) => void, canvasHost?: { surfaceToDataUrl(surfaceId: number): string | null }, nativeViewSystem?: NativeViewSystem) {
+    this.module = module
+    this.touchSystem = touchSystem
+    this.applyStyle = applyStyle
+    this.classLayer = classLayer
+    this.deregister = deregister
+    this.canvasHost = canvasHost
+
+    this.layoutPtrBytes = module._malloc(4 * 4)
+    this.layoutPtr = this.layoutPtrBytes >> 2
+    this.paddingPtrBytes = module._malloc(4 * 4)
+    this.paddingPtr = this.paddingPtrBytes >> 2
+    this.vlistSystem = vlistSystem
+    this.pagerSystem = pagerSystem
+    this.nativeViewSystem = nativeViewSystem
+  }
+
+  nodeMap = new Map<number, HTMLElement>()
+  weakMap = new WeakMap<HTMLElement, number>()
+  nodeOnLayoutEventsMap = new Map<number, ((layout: any) => void)[]>()
+
+  root!: HTMLElement
+  rootNodePtr!: number
+  screenId!: number
+  node: any
+  isWidget = false
+
+  // Overlay layer behind a widget (overlayColor). Managed by createUI's overlayColor
+  // handlers; tracked here so teardown removes it even when the widget is hidden
+  // without an explicit overlayColor: null reset.
+  overlayElement: HTMLElement | null = null
+
+  private vlistIds: number[] = []
+  private pagerIds: number[] = []
+
+  init(screenId: number, node: any) {
+    this.node = node
+    this.screenId = screenId
+    this.root = this.addNodeRecursive(node)
+    this.rootNodePtr = node._id
+  }
+
+  // ===== node creation =====
+
+  private addNodeRecursive(node: any, parent: number | null = null, index = 0): HTMLElement {
+    // Editables are measured leaves too: an input is one intrinsic text line, a textarea's
+    // height follows its content (auto-grow) — see createMeasureSystem.
+    const hasMeasureFunc = node.type === "text" || node.type === "image"
+      || node.type === "input" || node.type === "textarea"
+    const yogaId = parent === null
+      ? this.module._createNodeRoot(this.screenId)
+      : this.module._createNode(parent, index, hasMeasureFunc)
+
+    const element = createNodeElement(node)
+    element.setAttribute("data-node-id", yogaId)
+    element.style.position = "absolute"
+    // Back-reference for the editor's element inspector: from a DOM hit straight to the SDK node
+    // (type, name, _style, and — when the host enabled capture — the _site creation stack).
+    ;(element as any)._lecodesNode = node
+
+    if (node._text) {
+      element.textContent = node._text
+      element.style.whiteSpace = "pre-wrap"
+      element.style.lineHeight = "1.2em"
+      element.style.fontSize = "14px"
+      element.toggleAttribute("data-using-padding")
+    }
+    if (node.type === "scrollable" || node.scrollable) {
+      element.toggleAttribute("data-using-scroll")
+    }
+    if (node.type === "image") {
+      configureImage(this, node, element)
+    }
+    if (node.type === "video") {
+      configureVideo(element)
+    }
+    this.attachListeners(node, element)
+    // Per-type default styles come from the SDK (DEFAULT_STYLES, merged into node._style at
+    // construction) — the host applies only what the node carries.
+
+    node._id = yogaId
+    this.weakMap.set(element, yogaId)
+    this.nodeMap.set(node._id, element)
+
+    for (const [key, value] of Object.entries(node._style)) {
+      this.applyStyle(LAYER_DEFAULT, yogaId, key, value as any)
+    }
+
+    // Re-apply style classes the SDK node carries (el.class writes persist them on the element so a
+    // detached node re-mounts with them active — screens re-assign _id on every open). No recalc
+    // here: the mount runs a full layout afterward.
+    if (node._classes) {
+      for (const name of node._classes) {
+        this.module._enableNodeLayer(yogaId, this.classLayer(yogaId, name))
+      }
+    }
+
+    // A value assigned before mount (a pre-filled form) is stashed on the SDK node as `_value` —
+    // apply it once every style layer is on the element, so `type` is settled first (a `date` field
+    // only keeps a canonical value once it IS a date field). No recalc: the mount lays out
+    // afterward, and editables are measured leaves — a pre-filled textarea comes up already grown.
+    if ((node.type === "input" || node.type === "textarea") && node._value) {
+      (element as HTMLInputElement | HTMLTextAreaElement).value = node._value
+    }
+
+    if (node.type === "vlist") {
+      element.toggleAttribute("data-using-scroll")
+      element.toggleAttribute("data-vlist")
+      element.style.overflowY = "auto"          // если createNodeElement не делает это по типу
+      this.vlistSystem.register(this, node, element, yogaId)
+      this.vlistIds.push(yogaId)
+    }
+
+    // A NativeView embedded as a layout node: the yoga node sizes a cell; the registered web
+    // factory's live element mounts inside it (one live instance per NativeView — mounting here
+    // steals it from wherever it was, which is the promotion contract).
+    if (node.type === "native") {
+      element.toggleAttribute("data-native-view")
+      element.style.overflow = "hidden"
+      this.nativeViewSystem?.mountInto(node, element)
+    }
+
+    // A pager's pages (tab-major `children` partitioned by `_lens`) are separate layout roots
+    // built by the pager system, not yoga children — so it registers here and its children are
+    // skipped by the recursion below.
+    if (node.type === "pager") {
+      element.toggleAttribute("data-pager")
+      this.pagerSystem.register(this, node, element, yogaId)
+      this.pagerIds.push(yogaId)
+    }
+
+    if (node.ll) {
+      this.nodeOnLayoutEventsMap.set(yogaId, node.ll)
+    }
+
+    if ("children" in node && node.type !== "pager") {
+      let i = 0
+      for (const child of node.children as Array<UINode>) {
+        if (!child) continue
+        element.appendChild(this.addNodeRecursive(child, yogaId, i))
+        i++
+      }
+    }
+
+    return element
+  }
+
+  private attachListeners(node: any, element: HTMLElement) {
+    if (node.type === "button" || node.type === "widget" || node.type === "screen") {
+      element.addEventListener("pointerdown", this.touchSystem.onUIButtonTouchStart.bind(null, node))
+      if (node.type === "button") {
+        element.addEventListener("pointerup", this.touchSystem.onUIButtonTouchEnd.bind(null, node))
+      }
+    }
+
+    if (node.type === "input" || node.type === "textarea") {
+      element.toggleAttribute("data-using-padding")
+      const el = element as HTMLInputElement | HTMLTextAreaElement
+      ;(el as any)._lcNode = node // backref for the keyboard-dismiss guard (keyboardDismiss policy)
+      el.addEventListener("input", () => {
+        // Auto-grow: a content-measured textarea re-measures + relayouts as the user types.
+        if (node.type === "textarea") {
+          this.module._markNodeDirty(node._id)
+          this.recalc()
+        }
+        for (const listener of node.cl) listener(el.value)
+      })
+      el.addEventListener("focus", () => {
+        // Flips onFocused AND the cascading `$focused` class (creator-ui pairs them).
+        this.module._setNodeFocused(node._id, true)
+        for (const listener of node.fl) listener()
+      })
+      el.addEventListener("blur", () => {
+        this.module._setNodeFocused(node._id, false)
+        for (const listener of node.bl) listener()
+      })
+    }
+  }
+
+  // ===== images =====
+
+  updateImageSrc = (el: HTMLElement, src: ImageSrc) => updateImageSrc(this, el, src)
+  tintSvgImage = (nodeId: number, tint: string) => tintSvgImage(this, nodeId, tint)
+  untintSvgImage = (nodeId: number) => untintSvgImage(this, nodeId)
+  setSourceRect = (nodeId: number, x: number, y: number, w: number, h: number) =>
+    setImageSourceRect(this, nodeId, x, y, w, h)
+  refreshCanvasSurface = (surfaceId: number) => refreshCanvasSurface(this, surfaceId)
+
+  // ===== layout =====
+
+  screenWidth = 0
+  screenHeight = 0
+
+  // Dimensions for which the root (screen) onLayout was last fired. The screen's
+  // layout depends solely on screen dimensions, which only change in applyLayout —
+  // never during recalc(). Tracking them prevents re-firing onLayout on every node update.
+  private firedScreenWidth = -1
+  private firedScreenHeight = -1
+
+  // Set when a recalc was requested while this screen had no dimensions (detached).
+  // Forces the next applyLayout to re-lay-out even if the dimensions are unchanged, so
+  // updates made while the screen was in history are applied when it is shown again.
+  private pendingRecalc = false
+
+  applyLayout(screenWidth: number, screenHeight: number) {
+    if (screenWidth === this.screenWidth && screenHeight === this.screenHeight && !this.pendingRecalc) return
+    this.pendingRecalc = false
+    this.screenWidth = screenWidth
+    this.screenHeight = screenHeight
+    if (this.isWidget) {
+      this.module._calculateWidget(this.rootNodePtr, screenWidth, screenHeight)
+    } else {
+      this.module._calculate(this.rootNodePtr, screenWidth, screenHeight)
+    }
+    this.updateSizes(this.root)
+  }
+
+  private fireLayout(yogaId: number, rect: { left: number; top: number; width: number; height: number }) {
+    const onLayout = this.nodeOnLayoutEventsMap.get(yogaId)
+    if (!onLayout) return
+    for (const callback of onLayout) callback(rect)
+  }
+
+  private updateSizes(element: HTMLElement) {
+    if (element.style.display === "none") return
+
+    const yogaId = this.weakMap.get(element)
+    if (!yogaId) {
+      console.warn("Trying to update size for element without yogaId", element)
+      return
+    }
+
+    if (element === this.root && !this.isWidget) {
+      if (this.screenWidth !== this.firedScreenWidth || this.screenHeight !== this.firedScreenHeight) {
+        this.firedScreenWidth = this.screenWidth
+        this.firedScreenHeight = this.screenHeight
+        this.fireLayout(yogaId, { left: 0, top: 0, width: this.screenWidth, height: this.screenHeight })
+      }
+    } else if (this.module._getLayoutDOMPointer(yogaId, this.layoutPtrBytes)) {
+      const left = this.module.HEAPF32[this.layoutPtr]
+      const top = this.module.HEAPF32[this.layoutPtr + 1]
+      const width = this.module.HEAPF32[this.layoutPtr + 2]
+      const height = this.module.HEAPF32[this.layoutPtr + 3]
+
+      element.style.left = left + "px"
+      element.style.top = top + "px"
+      element.style.width = width + "px"
+      element.style.height = height + "px"
+      element.style.maxWidth = ""
+
+      this.fireLayout(yogaId, { left, top, width, height })
+    }
+
+    if (element.hasAttribute("data-using-padding")) {
+      this.module._getPaddingPointer(yogaId, this.paddingPtrBytes)
+      const left = this.module.HEAPF32[this.paddingPtr]
+      const top = this.module.HEAPF32[this.paddingPtr + 1]
+      const right = this.module.HEAPF32[this.paddingPtr + 2]
+      const bottom = this.module.HEAPF32[this.paddingPtr + 3]
+      element.style.padding = `${top}px ${right}px ${bottom}px ${left}px`
+      element.style.boxSizing = "border-box"
+    }
+
+    if (element.hasAttribute("data-using-scroll")) {
+      if (element.classList.contains("scrollable_horizontal")) {
+        const width = this.module._getContentWidth(yogaId)
+        element.style.setProperty("--scroll-width", width + "px")
+        element.style.setProperty("--scroll-height", "0px")
+      } else {
+        const height = this.module._getContentHeight(yogaId)
+        element.style.setProperty("--scroll-height", height + "px")
+        element.style.setProperty("--scroll-width", "0px")
+      }
+    }
+
+    if (element.hasAttribute("data-vlist")) {
+      this.vlistSystem.updateLayout(this.weakMap.get(element)!)
+      return   // айтемы кладёт refresh() с top из vlistOffsetOf
+    }
+
+    if (element.hasAttribute("data-pager")) {
+      // Pager pages are separate roots the pager system lays out to this element's box — don't
+      // recurse into its wrappers (they aren't in this screen's yoga tree).
+      this.pagerSystem.updateLayout(this.weakMap.get(element)!)
+      return
+    }
+
+    for (const child of element.children) {
+      this.updateSizes(child as HTMLElement)
+    }
+  }
+
+  // Chain page-lifecycle activation to this screen's pagers: the current tab's top page is "open"
+  // only while this screen's chain is active (this screen is the current/visible one). Cascades
+  // through nested pagers (a tab screen that itself hosts a pager).
+  setPagersActive(active: boolean) {
+    for (const id of this.pagerIds) this.pagerSystem.instances.get(id)?.setActive(active)
+  }
+
+  // ===== recalc =====
+
+  scheduledRecalc = false
+
+  recalc() {
+    if (this.scheduledRecalc) return
+    this.scheduledRecalc = true
+    queueMicrotask(this.recalcImmediately)
+  }
+
+  recalcImmediately = () => {
+    this.scheduledRecalc = false
+    // A detached/never-laid-out screen has no dimensions to lay out against. Defer the
+    // recalc until it is shown (applyLayout will honor pendingRecalc). This is what was
+    // broken: a non-active screen used to recalc the GLOBAL cachedRoot (the active
+    // screen) instead of itself, so e.g. a .text change never re-measured this screen.
+    if (this.screenWidth === 0) {
+      this.pendingRecalc = true
+      return
+    }
+    // Always recalc this screen's OWN root (not the global cachedRoot), so updates to a
+    // screen that isn't the active one are still applied to that screen.
+    if (this.isWidget) {
+      this.module._calculateWidget(this.rootNodePtr, this.screenWidth, this.screenHeight)
+    } else {
+      this.module._calculate(this.rootNodePtr, this.screenWidth, this.screenHeight)
+    }
+    this.updateSizes(this.root)
+  }
+
+  // ===== tree mutation =====
+
+  insertNode = (index: number, nodeId: number, node: any) => {
+    const element = this.nodeMap.get(nodeId)
+    if (!element) return
+    element.appendChild(this.addNodeRecursive(node, nodeId, index))
+    this.recalc()
+  }
+
+  removeNode = (nodeId: number, node: any) => {
+    const parent = this.nodeMap.get(nodeId)
+    if (!parent) return
+    this.detachNode(parent, nodeId, node)
+    this.recalc()
+  }
+
+  setContent(nodeId: number, oldChildren: any[], newChildren: any[]) {
+    const parent = this.nodeMap.get(nodeId)
+    if (!parent) return
+
+    for (const node of oldChildren) {
+      this.detachNode(parent, nodeId, node)
+    }
+
+    let index = 0
+    for (const child of newChildren) {
+      if (!child) continue
+      parent.appendChild(this.addNodeRecursive(child, nodeId, index))
+      index++
+    }
+    this.recalc()
+  }
+
+  private detachNode(parentEl: HTMLElement, parentId: number, node: any) {
+    const el = this.nodeMap.get(node._id)
+    this.nodeMap.delete(node._id)
+    if (el) parentEl.removeChild(el)
+    this.module._removeNode(parentId, node._id)
+    this.setNodeIdNullRecursive(node)
+  }
+
+  private setNodeIdNullRecursive(node: any) {
+    node._id = 0
+    if ("children" in node) {
+      for (const child of node.children as Array<UINode>) {
+        if (!child) continue
+        this.setNodeIdNullRecursive(child)
+      }
+    }
+  }
+
+  // построить поддерево айтема как ребёнка detached yoga root
+    buildSubtree(subtree: any, itemRootPtr: number): HTMLElement {
+        return this.addNodeRecursive(subtree, itemRootPtr, 0)
+    }
+
+    // layout-проход по DOM-поддереву айтема (тот же updateSizes, но от произвольного корня)
+    updateSizesFor(element: HTMLElement) {
+        this.updateSizes(element)
+    }
+
+    // чистка при unmount: nodeMap + _id = 0
+    releaseSubtree(subtree: any) {
+        const drop = (n: any) => {
+            if (n._id) this.nodeMap.delete(n._id)
+            n._id = 0
+            if ("children" in n) for (const c of n.children ?? []) if (c) drop(c)
+        }
+        drop(subtree)
+    }
+
+  // ===== teardown =====
+
+  remove() {
+    this.setPagersActive(false)   // fire onClose for active embedded pages before teardown
+    for (const id of this.vlistIds) {
+      this.vlistSystem.unregister(id)
+    }
+    for (const id of this.pagerIds) {
+      this.pagerSystem.unregister(id)        // frees every tab's page roots
+    }
+
+    this.removeFromHTML()
+    this.setNodeIdNullRecursive(this.node)
+    if (this.isWidget) {
+      this.module._freeWidget(this.rootNodePtr)
+    } else {
+      this.module._freeNode(this.rootNodePtr)
+    }
+
+    this.module._free(this.layoutPtrBytes)
+    this.module._free(this.paddingPtrBytes)
+    this.nodeMap.clear()
+
+    this.deregister(this.screenId)
+  }
+
+  removeFromHTML() {
+    this.setPagersActive(false)   // detaching (e.g. router history) closes embedded pages; restore re-opens
+    this.root.remove()
+    this.overlayElement?.remove()
+    this.overlayElement = null
+    this.screenWidth = 0
+    this.screenHeight = 0
+    this.firedScreenWidth = -1
+    this.firedScreenHeight = -1
+  }
+}

package/src/ui/createBareUI.ts

@@ -0,0 +1,32 @@
+// Minimal `_creatorUI` for engine-only hosts (the 3D scene editor viewport): scene pointer dispatch
+// + resize fan-out, no DOM/canvas UI renderer. Covers exactly the surface the 3D SDK reaches through
+// `_creatorUI` (registerTouchStartEvent/registerTouchEndEvent for scene picking, toast) plus the
+// host-side contract (`_setCreator`, `_onResize`, `_destroy`).
+
+import { createTouchSystem } from "./createTouchSystem"
+
+export const createBareUI = async (root: HTMLElement) => {
+  const touch = createTouchSystem(root)
+  const onPointerDown = (e: PointerEvent) => touch.onSceneTouchDown(e)
+  const onPointerUp = (e: PointerEvent) => touch.onSceneTouchEnd(e)
+  root.addEventListener("pointerdown", onPointerDown)
+  root.addEventListener("pointerup", onPointerUp)
+
+  const resizeCallbacks: Array<(width: number, height: number) => void> = []
+
+  return {
+    toast(_message: string) {},
+    registerTouchStartEvent: touch.registerTouchStartEvent,
+    registerTouchEndEvent: touch.registerTouchEndEvent,
+    registerResizeEvent(cb: (width: number, height: number) => void) { resizeCallbacks.push(cb) },
+    _setCreator: touch.setCreator,
+    _onResize(width: number, height: number) {
+      for (const cb of resizeCallbacks) cb(width, height)
+    },
+    _destroy() {
+      root.removeEventListener("pointerdown", onPointerDown)
+      root.removeEventListener("pointerup", onPointerUp)
+      touch._destroy()
+    },
+  }
+}