lecodes-viewer 0.19.0

package/src/ui/createUI.ts

@@ -0,0 +1,806 @@
+// @ts-ignore
+import createModule from './creator-ui'
+import wasmLib from './creator-ui.wasm?url'
+import { getUrl } from "../utils/fetch"
+import { createToastSystem } from "./toasts"
+import { createTouchSystem } from "./createTouchSystem"
+import { installKeyboardDismissGuard } from "lecodes-viewer-lite/src/ui/keyboardDismissGuard"
+import { installTouchDefaultsGuard } from "lecodes-viewer-lite/src/ui/touchDefaultsGuard"
+import { createTransitionSystem } from "./transitions"
+import { createMeasureSystem, cssFontFamily, setDefaultFontFamily } from "./createMeasureSystem"
+import { registerUIProps } from "./props-apply"
+import defaultStyleRaw from './defaultStyle.css?raw'
+import { UIScreen } from './UIScreen'
+import { Router } from './router'
+import { convertSvgToDataUri, isSvgSrc } from '../utils/svg'
+import { createVListSystem } from './vListSystem'
+import { createPagerSystem } from './createPagerSystem'
+import { createNativeViewSystem } from './nativeViewSystem'
+import { createPresentPlayer } from './presentPlayer'
+import { getVideoElement } from '../utils/videoNode'
+import { DEFAULT_SAFE_AREA, orientedSafeArea, type SafeAreaSpec } from './safeAreaSpec'
+const LAYER_DEFAULT = 256
+// creator-ui setSafeAreaBars bitmask, in the setSafePaddings arg order.
+const EDGE_BIT = { top: 1, right: 2, bottom: 4, left: 8 } as const
+
+export const createUI = async (root: HTMLElement, canvasHost?: { surfaceToDataUrl(surfaceId: number): string | null }) => {
+
+  const wasmBinary = await fetch(wasmLib).then(resp => resp.arrayBuffer())
+  // const nodeMap = new Map<number, HTMLElement>()
+  // const weakMap = new WeakMap<HTMLElement, number>()
+  
+  // const nodeOnLayoutEventsMap = new Map<number, ((layout: any) => void)[]>()
+
+  const module = await createModule({ wasmBinary })
+  
+  const styleBlock = document.createElement("style")
+  styleBlock.innerHTML = defaultStyleRaw
+  root.append(styleBlock)
+
+  // Screens (positive ids) and widgets (negative ids) live in id-keyed Maps so that a
+  // closed screen/widget can be reclaimed. Ids come from monotonic counters — they stay
+  // stable and are never reused, preserving the C++ NodeContext.screenId contract.
+  const screens = new Map<number, UIScreen>()
+  let nextScreenId = 0
+  const widgets = new Map<number, UIScreen>()
+  let widgetsId = 1
+
+  const getNode = (screenId: number, nodeId: number) =>
+    (screenId < 0 ? widgets : screens).get(screenId)?.nodeMap.get(nodeId)
+
+  const getScreen = (screenId: number) =>
+    (screenId < 0 ? widgets : screens).get(screenId)
+
+  // Single teardown hook: every permanent remove() leaves the registry, making the
+  // screen/widget GC-eligible. Router history uses removeFromHTML() (not remove()), so
+  // history screens stay registered and restorable.
+  const deregister = (screenId: number) => {
+    if (screenId < 0) widgets.delete(screenId)
+    else screens.delete(screenId)
+  }
+
+  const measureSystem = createMeasureSystem(getNode)
+  const func = module.addFunction(measureSystem.measure, "jiififi")
+  module._setMeasureFunc(func)
+
+  const vlistSystem = createVListSystem(module)
+  // Assigned once `newScreen` exists (the screen host / pager build each page as its own layout
+  // root). Referenced only from runtime paths (openScreen/newScreen/showWidget), which run after
+  // createUI returns.
+  let pagerSystem: ReturnType<typeof createPagerSystem>
+
+  let currentScreen: UIScreen | null = null
+
+  const addStringHandler = (key: string, callback: (screenId: number, nodePtr: number, str: number) => void) => {
+    const maxLen = (key as string).length + 1;
+    const keyPtr = module._malloc(maxLen);
+    module.stringToUTF8(key, keyPtr, maxLen);
+
+    const func = module.addFunction(callback, "viii")
+
+    module._addStringHandler(keyPtr, func);
+    module._free(keyPtr)
+  }
+  const addFloatHandler = (key: string, callback: (screenId: number, nodePtr: number, val: number) => void) => {
+    const maxLen = key.length + 1;
+    const valuePtr = module._malloc(maxLen);
+    module.stringToUTF8(key, valuePtr, maxLen);
+    const func = module.addFunction(callback, "viif")
+    module._addFloatHandler(valuePtr, func)
+    module._free(valuePtr)
+  }
+  const addUIntHandler = (key: string, callback: (screenId: number, nodePtr: number, val: number) => void) => {
+    const maxLen = key.length + 1;
+    const valuePtr = module._malloc(maxLen);
+    module.stringToUTF8(key, valuePtr, maxLen);
+    const func = module.addFunction(callback, "viii")
+    module._addUIntHandler(valuePtr, func)
+    module._free(valuePtr)
+  }
+  const addResetHandler = (key: string, callback: (screenId: number, nodePtr: number) => void) => {
+    const maxLen = key.length + 1;
+    const valuePtr = module._malloc(maxLen);
+    module.stringToUTF8(key, valuePtr, maxLen);
+    const func = module.addFunction(callback, "vii")
+    module._addResetHandler(valuePtr, func)
+    module._free(valuePtr)
+  }
+
+  const addMatrixHandler = (callback: (screenId: number, nodePtr: number, matrixPtr: number) => void) => {
+    const func = module.addFunction(callback, "viii")
+    module._setMatrixHandler(func)
+  }
+  const addTransformOriginHandler = (callback: (screenId: number, nodePtr: number, x: number, y: number, xPercent: number, yPercent: number) => void) => {
+    const func = module.addFunction(callback, "viiffii")
+    module._setTransformOriginHandler(func)
+  }
+
+  // Property application (every set + reset dispatch from the core) lives in props-apply.ts,
+  // enum-exhaustive against the generated registry surface (CuiProps.gen.ts).
+  registerUIProps({ module, root, getNode, getScreen, addStringHandler, addFloatHandler, addUIntHandler, addResetHandler, addMatrixHandler, addTransformOriginHandler })
+
+  // Style keys are a tiny, fixed set; intern their WASM pointers once instead of
+  // mallocing/freeing on every applyStyle call. The cache lives for the module
+  // lifetime by design (not a leak).
+  const keyPtrCache = new Map<string, number>()
+  const internKey = (key: string) => {
+    let ptr = keyPtrCache.get(key)!
+    if (ptr === undefined) {
+      const maxLen = key.length + 1
+      ptr = module._malloc(maxLen)
+      module.stringToUTF8(key, ptr, maxLen)
+      keyPtrCache.set(key, ptr)
+    }
+    return ptr
+  }
+
+  const applyStyle = (layer: number, yogaId: number, key: string, value: number | string | boolean) => {
+    const keyPtr = internKey(key)
+
+    // A reactive/conditional style can resolve to undefined (e.g. `active ? "#fff" : undefined`).
+    // Treat it as a reset, exactly like an explicit null — otherwise `typeof undefined` falls into
+    // the string `default` branch below and lengthBytesUTF8(undefined) throws. Matches viewer-lite's
+    // applyStyleValue (createLiteUI.ts), which clears the prop for null/undefined alike.
+    // Layer-scoped (_resetPropExt, not _resetProp): a null inside a `$class`/orientation block
+    // must land in THAT layer — reset semantics only while it's active — never erase the base
+    // entry. The core keeps erase semantics when `layer` is the default (256).
+    if (value === undefined) {
+      module._resetPropExt(layer, yogaId, keyPtr)
+      return
+    }
+
+    switch(typeof value) {
+      case "number":
+        module._setFloatExt(layer, yogaId, keyPtr, value)
+        break
+      case "boolean":
+        module._setFloatExt(layer, yogaId, keyPtr, value? 1: 0)
+        break
+      case "object":
+        if (value === null) {
+          module._resetPropExt(layer, yogaId, keyPtr)
+        } else if ("_id" in value) {
+          applyStyle(layer, yogaId, key, getUrl((value as any)._id))
+        } else if ("svg" in value) {
+          applyStyle(layer, yogaId, key, convertSvgToDataUri((value as any).svg))
+        } else {
+          const layer = module._getLayer(yogaId, keyPtr)
+          transitionSystem.applyStyleTransition(yogaId, value, layer)
+        }
+        break
+      default:
+        const maxLen = module.lengthBytesUTF8(value)  + 1;
+        const valuePtr = module._malloc(maxLen);
+        module.stringToUTF8(value, valuePtr, maxLen);
+
+        module._setStringExt(layer, yogaId, keyPtr, valuePtr)
+        module._free(valuePtr)
+    }
+  }
+  
+  // Layout size of the root. Unlike getBoundingClientRect, client sizes ignore CSS transforms,
+  // so a host's appear animation (e.g. the editor simulator's scale/translate pop) can't poison
+  // a screen/widget laid out while it plays.
+  const rootSize = (): [number, number] => [root.clientWidth, root.clientHeight]
+
+  // ==== destinations (docs/navigation-presentable-plan.md — phase 2, web reference host) ========
+  // Exactly one destination (screen / scene / native view / fullscreen video) is visible at a
+  // time. The scene canvas is no longer an always-on bottom layer: presenting a scene shows its
+  // canvas and activates the engine; covering it closes the engine (rendering pauses) and hides
+  // the canvas. Screens stay position:absolute siblings, so during transitions they naturally
+  // paint above the in-flow canvas (see presentPlayer's static rule).
+
+  type SceneHooks = { el: HTMLElement, open(sceneId: number): void, close(): void }
+  let sceneHost: { scene3d?: SceneHooks, scene2d?: SceneHooks } = {}
+  // Wired by host.ts once the engines exist (same late-wiring seam as _setCreator).
+  const _setSceneHost = (hooks: { scene3d?: SceneHooks, scene2d?: SceneHooks }) => { sceneHost = hooks }
+
+  const nativeViews = createNativeViewSystem()
+  const presentPlayer = createPresentPlayer(root)
+
+  type Dest =
+    | { kind: "screen", node: any, screen: UIScreen }
+    | { kind: "scene3d", desc: any }
+    | { kind: "scene2d", desc: any }
+    | { kind: "native", desc: any, cell?: HTMLElement }
+    | { kind: "videoView", desc: any, wrapper?: HTMLElement, restore?: { parent: HTMLElement | null, next: Node | null, cssText: string } }
+
+  let current: Dest | null = null
+
+  const newScreen = (node: any) => {
+    const screen = new UIScreen(module, touchSystem, applyStyle, classLayer, vlistSystem, pagerSystem, deregister, canvasHost, nativeViews)
+    const id = nextScreenId++
+    screens.set(id, screen)
+    screen.init(id, node)
+    return screen
+  }
+
+  // Built here (not at the top) because each page is hosted by its own `newScreen` layout root.
+  pagerSystem = createPagerSystem(module, { newScreen })
+
+  const makeDest = (view: any): Dest => {
+    switch (view?.type) {
+      case "scene3d":
+      case "scene2d": return { kind: view.type, desc: view }
+      case "native": return { kind: "native", desc: view }
+      case "videoView": return { kind: "videoView", desc: view }
+      default: return { kind: "screen", node: view, screen: newScreen(view) }
+    }
+  }
+
+  // Presentation lifecycle arrays: screens carry ol/cl on the node; descriptors on their `_p`.
+  const fireLifecycle = (dest: Dest, key: "ol" | "cl") => {
+    const owner = dest.kind === "screen" ? dest.node : dest.desc._p
+    for (const callback of owner?.[key] ?? []) callback()
+  }
+
+  // Attached widgets (widget.attachTo(owner)) show only while their owner is the current
+  // destination. Owner identity: the screen node object itself, or the scene/native descriptor.
+  const ownerIsCurrent = (ownerDesc: any) =>
+    current !== null && (current.kind === "screen" ? current.node === ownerDesc : current.desc === ownerDesc)
+  const updateAttachedWidgets = () => {
+    for (const widget of widgets.values()) {
+      if (widget.ownerDesc === undefined) continue
+      const visible = ownerIsCurrent(widget.ownerDesc)
+      widget.root.style.display = visible ? "" : "none"
+      if (widget.overlayElement) widget.overlayElement.style.display = visible ? "" : "none"
+    }
+  }
+
+  // Mounts a destination and returns the element the transition moves (scenes are static — the
+  // canvas never animates, mirroring the Android SurfaceView rule; screens animate over it).
+  const mountDest = (dest: Dest): { el: HTMLElement, static?: boolean } | undefined => {
+    if (dest.kind === "screen") {
+      root.appendChild(dest.screen.root)
+      dest.screen.applyLayout(cachedWidth, cachedHeight)
+      fireLifecycle(dest, "ol")
+      dest.screen.setPagersActive(true)   // open embedded pages (after the screen's onOpen)
+      return { el: dest.screen.root }
+    }
+    if (dest.kind === "scene3d" || dest.kind === "scene2d") {
+      const hooks = sceneHost[dest.kind]
+      if (!hooks) {
+        console.error(`[le.codes] openView: this host has no ${dest.kind === "scene3d" ? "3D" : "2D"} engine`)
+        return undefined
+      }
+      hooks.open(dest.desc.sceneId)   // the host activates the engine — the SDK no longer does
+      hooks.el.style.display = "block"
+      fireLifecycle(dest, "ol")
+      return { el: hooks.el, static: true }
+    }
+    if (dest.kind === "native") {
+      const cell = dest.cell ??= document.createElement("div")
+      cell.style.cssText = "position:absolute;inset:0;overflow:hidden"
+      nativeViews.mountInto(dest.desc._p, cell)
+      root.appendChild(cell)
+      fireLifecycle(dest, "ol")
+      return { el: cell }
+    }
+    // videoView — fullscreen promotion of the player's own <video> element: reparent it into a
+    // fullscreen wrapper (playback continues) and put it back on dismiss.
+    const videoEl = getVideoElement(dest.desc.node)
+    dest.restore = { parent: videoEl.parentElement, next: videoEl.nextSibling, cssText: videoEl.style.cssText }
+    const wrapper = dest.wrapper ??= document.createElement("div")
+    wrapper.style.cssText = "position:absolute;inset:0;background:#000"
+    videoEl.style.cssText = "position:absolute;inset:0;width:100%;height:100%;object-fit:contain"
+    wrapper.appendChild(videoEl)
+    root.appendChild(wrapper)
+    fireLifecycle(dest, "ol")
+    return { el: wrapper }
+  }
+
+  const destElement = (dest: Dest): { el: HTMLElement, static?: boolean } | undefined => {
+    if (dest.kind === "screen") return { el: dest.screen.root }
+    if (dest.kind === "scene3d" || dest.kind === "scene2d") {
+      const hooks = sceneHost[dest.kind]
+      return hooks ? { el: hooks.el, static: true } : undefined
+    }
+    if (dest.kind === "native") return dest.cell ? { el: dest.cell } : undefined
+    return dest.wrapper ? { el: dest.wrapper } : undefined
+  }
+
+  // Physical dismount, after the transition. `free` releases a screen for good unless the router
+  // still holds it in history (then it only detaches, staying restorable).
+  const unmountDest = (dest: Dest, free: boolean) => {
+    if (dest.kind === "screen") {
+      if (free && !router.stack.includes(dest)) dest.screen.remove()
+      else dest.screen.removeFromHTML()
+      return
+    }
+    if (dest.kind === "scene3d" || dest.kind === "scene2d") {
+      const hooks = sceneHost[dest.kind]
+      if (hooks) { hooks.close(); hooks.el.style.display = "none" }   // rendering pauses while covered
+      return
+    }
+    if (dest.kind === "native") {
+      dest.cell?.remove()   // the live instance survives (keeps its state) — only the mount point goes
+      return
+    }
+    const videoEl = getVideoElement(dest.desc.node)
+    if (dest.restore) {
+      videoEl.style.cssText = dest.restore.cssText
+      if (dest.restore.parent) dest.restore.parent.insertBefore(videoEl, dest.restore.next)
+      else videoEl.remove()
+    }
+    dest.wrapper?.remove()
+  }
+
+  // Router history leaving for good (replace/pop/re-init). If the dest is mid-exit-animation,
+  // defer the free to the transition's onDone.
+  let animatingPrev: Dest | null = null
+  let animatingPrevFree = false
+  const freeDest = (dest: Dest) => {
+    if (dest === animatingPrev) { animatingPrevFree = true; return }
+    if (dest.kind === "screen") dest.screen.remove()
+  }
+
+  const show = (next: Dest | null, transition: string | object | null | undefined, freePrev: boolean) => {
+    presentPlayer.finish()   // snap any in-flight transition (dismounts its outgoing side)
+    const prev = current
+    if (prev === next) return
+    if (prev) fireLifecycle(prev, "cl")   // onClose fires at transition start (native parity)
+
+    current = next
+    currentScreen = next?.kind === "screen" ? next.screen : null
+    const incoming = next ? mountDest(next) : undefined
+    updateAttachedWidgets()
+
+    if (!prev) return
+    animatingPrev = prev
+    animatingPrevFree = false
+    presentPlayer.play({
+      incoming,
+      outgoing: destElement(prev),
+      transition,
+      onDone: () => {
+        const wantFree = freePrev || animatingPrevFree
+        animatingPrev = null
+        unmountDest(prev, wantFree)
+      },
+    })
+  }
+
+  // ---- the bridge surface ----------------------------------------------------------------------
+
+  const openView = (view: any, transition?: string | object) => {
+    if (router.show) routerHide()
+    const [ width, height ] = rootSize()
+    _onResize(width, height)
+    show(makeDest(view), transition ?? "none", true)
+  }
+  const closeView = () => {
+    show(null, "none", true)
+  }
+
+  // Legacy aliases — previously compiled bundles keep running, with the new one-destination
+  // semantics (an openScreen over a scene now replaces it instead of overlaying it).
+  const openScreen = (screenObj: any) => openView(screenObj, "none")
+
+  let onRouterChange: (view: any) => void
+  // The shared Router class doesn't thread a transition through onScreen — stash it around the call.
+  let pendingTransition: string | object | null = null
+  const router = new Router<Dest>((dest) => {
+    const transition = pendingTransition
+    pendingTransition = null
+    show(dest, transition, false)   // router history detaches, never frees (freeDest handles that)
+    onRouterChange?.(dest.kind === "screen" ? dest.node : dest.desc)
+  }, freeDest)
+
+  const routerOpen = (homePage: any, onChange: (view: any) => void) => {
+    if (current) {
+      // A current router destination is freed by the stack loop below (detach only here to avoid
+      // a double free); anything else is closed outright.
+      fireLifecycle(current, "cl")
+      unmountDest(current, !router.stack.includes(current))
+      current = null
+      currentScreen = null
+    }
+    // Re-initializing the router: free any leftover history from a previous session.
+    for (const dest of router.stack) freeDest(dest)
+    router.stack = []
+
+    const [ width, height ] = rootSize()
+    _onResize(width, height)
+
+    onRouterChange = onChange
+    router.init(makeDest(homePage))
+  }
+
+  const routerPush = (page: any, transition?: string | object) => {
+    pendingTransition = transition ?? "push"
+    router.push(makeDest(page))
+  }
+
+  const routerReplace = (page: any, transition?: string | object) => {
+    pendingTransition = transition ?? "fade"
+    router.replace(makeDest(page))
+  }
+
+  const routerPop = (to: number, transition?: string | object) => {
+    pendingTransition = transition ?? "pop"
+    router.pop(to)
+  }
+
+  const routerHide = () => {
+    router.hide()
+    if (current && router.stack.includes(current)) {
+      presentPlayer.finish()
+      fireLifecycle(current, "cl")
+      const detached = current
+      current = null
+      currentScreen = null
+      unmountDest(detached, false)
+      updateAttachedWidgets()
+    }
+  }
+
+  const routerRestore = () => {
+    router.restore()
+  }
+
+  const getTextValue = (nodeId: number): string => {
+    // Resolve the owning screen by id — an input can live inside a hosted page (its own layout
+    // root), not just the active screen.
+    const owner = getScreen(module._getScreenId(nodeId)) ?? currentScreen
+    const element = owner?.nodeMap.get(nodeId) as (HTMLInputElement | HTMLTextAreaElement)
+    if (!element) return ""
+    return element.value
+  }
+
+  // Absolute device-space rect [left, top, width, height] backing el.getBoundingClientRect().
+  // Read from the DOM rather than the yoga tree so scroll offsets, vlist windows, and in-flight
+  // transition transforms are all included for free; normalized against the app root's own rect
+  // (and its scale, when the editor preview shrinks the device frame) so values come back in
+  // logical px — the same space widget top/left position in.
+  const getBoundingClientRect = (nodeId: number): [number, number, number, number] | null => {
+    const owner = getScreen(module._getScreenId(nodeId)) ?? currentScreen
+    const element = owner?.nodeMap.get(nodeId)
+    if (!element || !element.isConnected) return null
+    const rect = element.getBoundingClientRect()
+    // an all-zero DOMRect means display:none — a screen parked in router history
+    if (rect.width === 0 && rect.height === 0 && rect.left === 0 && rect.top === 0) return null
+    const appRect = root.getBoundingClientRect()
+    const [displayWidth] = getDisplaySize()
+    const scale = displayWidth > 0 && appRect.width > 0 ? appRect.width / displayWidth : 1
+    return [
+      (rect.left - appRect.left) / scale, (rect.top - appRect.top) / scale,
+      rect.width / scale, rect.height / scale,
+    ]
+  }
+
+  const closeScreen = () => closeView()
+
+  const updateNode = (nodeId: number, prop: string, value: string | number) => {
+    const screenId = module._getScreenId(nodeId)
+    const screen = getScreen(screenId)
+    if (!screen) return
+    const element = screen.nodeMap.get(nodeId)
+    if (!element) return
+
+    switch (prop) {
+      case "text": 
+        element.textContent = value as string
+        module._markNodeDirty(nodeId)
+        screen.recalc()
+        break
+      case "value":
+        (element as HTMLInputElement).value = value as string
+        // Auto-grow: a content-measured textarea re-measures on programmatic value sets too.
+        if (element instanceof HTMLTextAreaElement && module._nodeHasMeasure(nodeId)) {
+          module._markNodeDirty(nodeId)
+          screen.recalc()
+        }
+        break
+      case "src":
+        screen.updateImageSrc(element, value as any)
+        break
+    }
+  }
+
+  // Render only a sub-rectangle of an image's source texture — the atlas / spritesheet
+  // primitive. Coords are texture pixels (= CSS px on web, no density scaling). The crop is
+  // applied by swapping the <img> for a background-image <div> (see setImageSourceRect).
+  const setSourceRect = (nodeId: number, x: number, y: number, w: number, h: number) => {
+    getScreen(module._getScreenId(nodeId))?.setSourceRect(nodeId, x, y, w, h)
+  }
+
+  // Canvas.update() → repaint every live UIImage(canvas) node showing this baked surface with the
+  // re-rasterized pixels (draw-only, no relayout). The surface can back nodes on any screen/widget
+  // — including ones parked in router history — so sweep them all.
+  const refreshCanvasSurface = (surfaceId: number) => {
+    for (const screen of screens.values()) screen.refreshCanvasSurface(surfaceId)
+    for (const widget of widgets.values()) widget.refreshCanvasSurface(surfaceId)
+  }
+
+  // Fonts the user code registered, tracked so _destroy can remove them from the (process-wide)
+  // document.fonts set instead of letting them accumulate across runs.
+  const registeredFonts: FontFace[] = []
+
+  // Every cached yoga text measure goes stale when a face lands after layout (or the default
+  // font retargets): dirty the measure leaves everywhere — screens in history included — and
+  // lay the live surfaces out again.
+  const dirtyAllTextMeasures = () => {
+    for (const collection of [screens, widgets]) {
+      for (const screen of collection.values()) {
+        for (const id of screen.nodeMap.keys()) {
+          if (module._nodeHasMeasure(id)) module._markNodeDirty(id)
+        }
+      }
+    }
+  }
+  const relayoutAll = () => {
+    if (!cachedWidth || !cachedHeight) return
+    currentScreen?.applyLayout(cachedWidth, cachedHeight)
+    for (const widget of widgets.values()) widget.applyLayout(cachedWidth, cachedHeight)
+  }
+
+  const registerFont = (fontFamily: string, url: string, options: { weight?: number, style?: string }, onComplete: () => void, onReject: () => void) => {
+    const font = new FontFace(fontFamily, `url(${url})`, options as any)
+    // Added before load resolves: DOM text swaps the moment the bytes land (font-display: swap
+    // semantics), whether or not anything awaits the legacy completion callback.
+    document.fonts.add(font)
+    registeredFonts.push(font)
+    font.load().then(() => {
+      // Late arrival is the fallback path (boot faces are prefetched via the `// fonts:` header):
+      // re-measure + re-layout so yoga agrees with the swapped-in glyphs.
+      dirtyAllTextMeasures()
+      relayoutAll()
+      onComplete()
+    })
+    .catch(onReject)
+  }
+
+  const updateStyle = (nodeId: number, prop: string, value: string | number) => {
+    applyStyle(LAYER_DEFAULT, nodeId, prop, value)
+    // Recalc the node's own screen — not necessarily the active one (the node may live
+    // on a screen that's currently in history).
+    getScreen(module._getScreenId(nodeId))?.recalc()
+  }
+  const mergeStyle = (nodeId: number, style: any) => {
+    for (let [ key, value ] of Object.entries(style)) {
+      applyStyle(LAYER_DEFAULT, nodeId, key, value as string | number)
+    }
+    getScreen(module._getScreenId(nodeId))?.recalc()
+  }
+
+  // Resolve a user style class ("$"+name) to its layer id (allocated app-global by getLayer on
+  // first sight). Reuses the interned-key pointer cache. The declaration path needs no changes —
+  // a `$checked: {...}` block already flows through applyStyle → getLayer → applyStyleTransition.
+  const classLayer = (nodeId: number, name: string) => module._getLayer(nodeId, internKey("$" + name))
+
+  // Class toggling lives in creator-ui (setNodeClass): name→layer conversion + the DESCENDANT
+  // CASCADE — a class set here is active on the whole subtree (docs/style-class-cascade-plan.md).
+  const setClass = (nodeId: number, name: string, enabled: boolean) => {
+    module._setNodeClass(nodeId, internKey(name), enabled)
+    getScreen(module._getScreenId(nodeId))?.recalc()
+  }
+
+  const getOverlay = (yogaId: number) => getScreen(module._getScreenId(yogaId))?.overlayElement
+  const transitionSystem = createTransitionSystem(module, styleBlock, getNode, applyStyle, getOverlay)
+
+  const toast = createToastSystem(root)
+
+  let onResizeCallback: (width: number, height: number) => void = () => {}
+  let cachedWidth: number
+  let cachedHeight: number
+  // Simulated safe insets: the neutral web defaults, unless a device-emulating embedder (the
+  // editor Simulator's iOS/Android shells) pins a spec via _setSafeAreaSpec.
+  let safeAreaSpec: SafeAreaSpec = DEFAULT_SAFE_AREA
+  const _onResize = (width: number, height: number) => {
+    if (width === 0 || height === 0) return
+
+    // Bars first — the paddings call is what re-resolves the dynamic safe-*/comfort-* styles.
+    const { insets, bars } = orientedSafeArea(safeAreaSpec, width > height)
+    module._setSafeAreaBars(bars.reduce((mask, edge) => mask | EDGE_BIT[edge], 0))
+    module._setSafePaddings(insets[0], insets[1], insets[2], insets[3])
+    module._setConditionValue(width, height)
+    if (currentScreen) {
+      currentScreen?.applyLayout(width, height)
+    }
+    // Widgets are their own layout roots — without this they'd keep the dimensions they were
+    // opened with forever (the "gap after opening during the simulator's pop animation" bug).
+    for (const widget of widgets.values()) {
+      widget.applyLayout(width, height)
+    }
+
+    cachedWidth = width
+    cachedHeight = height
+
+    onResizeCallback(width, height)
+  }
+  
+  const registerResizeEvent = (callback: (width: number, height: number) => void) => {
+    onResizeCallback = callback
+  }
+  // Current display size (device.width / device.height) — the last size seen by _onResize.
+  const getDisplaySize = (): [number, number] => [cachedWidth ?? 0, cachedHeight ?? 0]
+
+  // Host-config: pin the safe-area insets/bars (null restores the web defaults); re-applies
+  // through _onResize when the host is already sized.
+  const setSafeAreaSpec = (spec: SafeAreaSpec | null) => {
+    safeAreaSpec = spec ?? DEFAULT_SAFE_AREA
+    if (cachedWidth && cachedHeight) _onResize(cachedWidth, cachedHeight)
+  }
+
+  // _creatorUI.setTheme (docs/ui-theme-plan.md): merge app theme values into the core table,
+  // then re-resolve every live root's dynamic styles (var() refs, comfort-* tokens). Numbers are
+  // lengths → "px" suffix (the core's bare-number string branches mean percent); null removes.
+  // Colors/strings re-dispatch through the registered handlers synchronously; layout props mark
+  // yoga dirty, so the visible roots relayout the same way a resize does (covered screens
+  // relayout when shown).
+  const setTheme = (values: Record<string, string | number | null>) => {
+    for (const key of Object.keys(values)) {
+      const value = key === "fontFamily" && typeof values[key] === "string"
+        ? cssFontFamily(values[key] as string)
+        : values[key]
+      const str = value == null ? null : typeof value === "number" ? `${value}px` : value
+      const keyLen = key.length + 1
+      const keyPtr = module._malloc(keyLen)
+      module.stringToUTF8(key, keyPtr, keyLen)
+      let valPtr = 0
+      if (str !== null) {
+        const valLen = module.lengthBytesUTF8(str) + 1
+        valPtr = module._malloc(valLen)
+        module.stringToUTF8(str, valPtr, valLen)
+      }
+      module._setThemeValue(keyPtr, valPtr)
+      if (valPtr) module._free(valPtr)
+      module._free(keyPtr)
+      // Mirror as a CSS custom property on the app root: `var(--x)` values the DOM renders and
+      // the theme-sourced defaults (.screen color/font-family in defaultStyle.css) re-resolve
+      // natively. Env names never reach here (the SDK strips them; the core ignores them too).
+      if (str === null) root.style.removeProperty(`--${key}`)
+      else root.style.setProperty(`--${key}`, str)
+    }
+
+    let relayout = module._applyTheme()
+
+    // System default: the `fontFamily` theme key retargets the default text font. The DOM side
+    // follows via CSS above — measurement must agree, and every text node's cached yoga measure
+    // is stale, so dirty the measure leaves everywhere (screens in history included).
+    if ("fontFamily" in values) {
+      setDefaultFontFamily(values.fontFamily == null ? null : String(values.fontFamily))
+      dirtyAllTextMeasures()
+      relayout = true
+    }
+
+    if (relayout && cachedWidth && cachedHeight) {
+      currentScreen?.applyLayout(cachedWidth, cachedHeight)
+      for (const widget of widgets.values()) {
+        widget.applyLayout(cachedWidth, cachedHeight)
+      }
+    }
+  }
+
+  const touchSystem = createTouchSystem(root)
+  touchSystem.onNodeStateChanged((nodeId, pressed) => {
+    // Flips the built-in onPressed layer AND the cascading `$pressed` class (creator-ui pairs them).
+    module._setNodePressed(nodeId, pressed)
+  })
+
+  // Touch: native defaults (focus, scroll) stay on editables/scrollers; gesture surfaces (canvas,
+  // `.interactive`) keep the touch for the app — see viewer-lite's touchDefaultsGuard. Root-level
+  // touch-action drops double-tap/pinch zoom on the app surface without touching native panning.
+  const savedTouchAction = root.style.touchAction
+  root.style.touchAction = "pan-x pan-y"
+  const removeTouchGuard = installTouchDefaultsGuard(root, { scroller: ".scrollable,.vlist,.pager" })
+  root.addEventListener("pointerdown", touchSystem.onSceneTouchDown)
+  root.addEventListener("pointerup", touchSystem.onSceneTouchEnd)
+  root.addEventListener("pointercancel", touchSystem.onSceneTouchCancel)
+  const removeDismissGuard = installKeyboardDismissGuard(root)
+
+  const _destroy = () => {
+    removeDismissGuard()
+    removeTouchGuard()
+    root.style.touchAction = savedTouchAction
+    root.removeEventListener("pointerdown", touchSystem.onSceneTouchDown)
+    root.removeEventListener("pointerup", touchSystem.onSceneTouchEnd)
+    root.removeEventListener("pointercancel", touchSystem.onSceneTouchCancel)
+    touchSystem._destroy()
+    nativeViews.destroy()
+    for (const font of registeredFonts) document.fonts.delete(font)
+    registeredFonts.length = 0
+  }
+
+  const showWidget = (widgetJS: any, ownerDesc?: any) => {
+    for (let w of widgets.values()) {
+      if (w.node === widgetJS) return
+    }
+    const screen = new UIScreen(module, touchSystem, applyStyle, classLayer, vlistSystem, pagerSystem, deregister, canvasHost, nativeViews)
+    screen.isWidget = true
+    screen.ownerDesc = ownerDesc   // attached widget: visible only while the owner is presented
+
+    widgets.set(-widgetsId, screen)
+    screen.init(-widgetsId, widgetJS)
+    widgetsId++
+
+    const [ width, height ] = rootSize()
+    screen.applyLayout(width, height)
+
+    screen.root.classList.add("widget")
+    // A widget with a root-level touch listener catches taps on its whole surface (pointer-events:
+    // all); without one it stays pointer-transparent so taps fall through to the scene beneath — same
+    // rule as `.screen` (createNodeElement). Non-interactive children re-enable events themselves.
+    if (widgetJS.touchStartListeners?.length > 0) screen.root.classList.add("interactive")
+    root.appendChild(screen.root)
+    screen.setPagersActive(true)   // a pager inside a widget opens its current page
+    if (ownerDesc !== undefined) updateAttachedWidgets()
+  }
+  const hideWidget = (widgetJS: any) => {
+    if (!widgetJS._id) return
+    const screenId = module._getScreenId(widgetJS._id)
+    if (screenId >= 0) return
+    const widget = getScreen(screenId)
+    widget?.remove()   // self-deregisters via the deregister hook
+  }
+
+  const insertNode = (index: number, nodeId: number, node: any) => {
+    const screenId = module._getScreenId(nodeId)
+    const screen = getScreen(screenId)
+    screen?.insertNode(index, nodeId, node)
+  }
+  const removeNode = (nodeId: number, node: any) => { 
+    const screenId = module._getScreenId(nodeId)
+    const screen = getScreen(screenId)
+    screen?.removeNode(nodeId, node)
+  }
+  const setContent = (nodeId: number, oldChildren: any[], newChildren: any[]) => { 
+    const screenId = module._getScreenId(nodeId)
+    const screen = getScreen(screenId)
+    screen?.setContent(nodeId, oldChildren, newChildren)
+  }
+
+  return {
+    openScreen,
+    closeScreen,
+    routerOpen,
+    routerPush,
+    routerReplace,
+    routerPop,
+    routerHide,
+    routerRestore,
+    // Presentable navigation (docs/navigation-presentable-plan.md) — the SDK feature-detects these.
+    openView,
+    closeView,
+    isViewSupported: nativeViews.isViewSupported,
+    viewCall: nativeViews.viewCall,
+    // Host-side plugin registration (the embedding app calls host._creatorUI._registerView).
+    _registerView: nativeViews.registerView,
+    _setSceneHost,
+    updateNode,
+    setSourceRect,
+    refreshCanvasSurface,
+    updateStyle,
+    mergeStyle,
+    setClass,
+    registerFont,
+    // Browser host: CDN faces should come as woff2 (the font() macro's generated code reads this).
+    fontFormat: "woff2",
+    toast,
+    registerTouchStartEvent: touchSystem.registerTouchStartEvent,
+    registerTouchEndEvent: touchSystem.registerTouchEndEvent,
+    isButtonPressed: touchSystem.isButtonPressed,
+    registerResizeEvent,
+    getDisplaySize,
+    getTextValue,
+    getBoundingClientRect,
+    insertNode,
+    removeNode,
+    setContent,
+    animateTo: transitionSystem.animateTo,
+    animateFrom: transitionSystem.animateFrom,
+    showWidget,
+    hideWidget,
+    _onResize,
+    _destroy,
+    _setCreator: touchSystem.setCreator,
+    _setSafeAreaSpec: setSafeAreaSpec,
+    setTheme,
+    ...vlistSystem.api,
+    // Generic command channel — pager nodes route to their system, everything else to vlist.
+    command: (jsNode: any, name: string, ...args: any[]) => {
+      if (jsNode?.type === "pager") return pagerSystem.command(jsNode, name, ...args)
+      return vlistSystem.api.command(jsNode, name, ...args)
+    },
+  }
+}