lecodes-viewer 0.19.0

package/src/ui/presentPlayer.ts

@@ -0,0 +1,156 @@
+// Destination transition player (docs/navigation-presentable-plan.md, phase 2 — web reference).
+// Named transitions are predefined TransitionSpecs; both shapes play through element.animate(),
+// so a custom spec from the SDK needs no extra machinery.
+//
+// The static rule (mirrors the Android SurfaceView constraint so apps feel the same): a side
+// marked `static` (the scene canvas) never animates — only the screen side moves. Screens are
+// position:absolute so they always paint above the in-flow canvas, which makes the degradations
+// coherent: entering a scene slides the old screen away to reveal it; leaving a scene slides the
+// new screen in over it.
+
+export type SpecTransform = { x?: number | string, y?: number | string, scale?: number, opacity?: number }
+export type TransitionSpecLike = {
+  duration?: number
+  easing?: [number, number, number, number]
+  incoming?: { from?: SpecTransform }
+  outgoing?: { to?: SpecTransform }
+  dim?: number
+  onTop?: "incoming" | "outgoing"
+}
+
+const STACK_EASING: [number, number, number, number] = [0.2, 0, 0, 1]
+
+const NAMED: Record<string, TransitionSpecLike> = {
+  "none": {},
+  "fade": { duration: 280, incoming: { from: { opacity: 0 } } },
+  "slide-from-right": { duration: 400, incoming: { from: { x: "100%" } }, outgoing: { to: { x: "-30%" } } },
+  "slide-from-left": { duration: 400, incoming: { from: { x: "-100%" } }, outgoing: { to: { x: "30%" } } },
+  "slide-from-top": { duration: 400, incoming: { from: { y: "-100%" } }, outgoing: { to: { y: "30%" } } },
+  "slide-from-bottom": { duration: 400, incoming: { from: { y: "100%" } }, outgoing: { to: { y: "-30%" } } },
+  "zoom": { duration: 400, easing: [0.33, 1.2, 0.62, 1], incoming: { from: { scale: 0.985 } } },
+  "zoom-in": { duration: 400, easing: [0.33, 1.2, 0.62, 1], incoming: { from: { scale: 1.08, opacity: 0 } }, onTop: "incoming" },
+  "zoom-out": { duration: 420, outgoing: { to: { scale: 0.92, opacity: 0 } }, onTop: "outgoing" },
+  "push": { duration: 350, easing: STACK_EASING, incoming: { from: { x: "100%" } }, outgoing: { to: { x: "-25%" } }, dim: 0.3, onTop: "incoming" },
+  "pop": { duration: 350, easing: STACK_EASING, incoming: { from: { x: "-25%" } }, outgoing: { to: { x: "100%" } }, dim: 0.3, onTop: "outgoing" },
+}
+
+const toTransform = (t: SpecTransform): string => {
+  const parts: string[] = []
+  if (t.x !== undefined || t.y !== undefined) {
+    const px = (v: number | string | undefined) => v === undefined ? "0px" : typeof v === "number" ? v + "px" : v
+    parts.push(`translate(${px(t.x)}, ${px(t.y)})`)
+  }
+  if (t.scale !== undefined) parts.push(`scale(${t.scale})`)
+  return parts.length > 0 ? parts.join(" ") : "none"
+}
+
+const poseKeyframe = (t: SpecTransform): Keyframe => {
+  const kf: Keyframe = { transform: toTransform(t) }
+  if (t.opacity !== undefined) kf.opacity = t.opacity
+  return kf
+}
+const IDENTITY: Keyframe = { transform: "none", opacity: 1 }
+
+// The exit pose for an outgoing side when the incoming one is static (a scene): mirror the
+// incoming entry so the reveal keeps the transition's direction (push's 100%-from-right becomes
+// a full slide-out to the left); pure opacity entries become a fade-out.
+const mirrorExit = (from: SpecTransform): SpecTransform => {
+  const neg = (v: number | string | undefined) =>
+    v === undefined ? undefined : typeof v === "number" ? -v : v.startsWith("-") ? v.slice(1) : "-" + v
+  const out: SpecTransform = {}
+  if (from.x !== undefined) out.x = neg(from.x)
+  if (from.y !== undefined) out.y = neg(from.y)
+  if (from.scale !== undefined) out.scale = 2 - from.scale
+  if (from.opacity !== undefined || Object.keys(out).length === 0) out.opacity = 0
+  return out
+}
+
+type Side = { el: HTMLElement, static?: boolean }
+
+export const createPresentPlayer = (container: HTMLElement) => {
+  let finishActive: (() => void) | null = null
+
+  /** Play `transition` between the mounted `incoming` and the still-mounted `outgoing`; calls
+   *  `onDone` exactly once (after the animation, or immediately for none/unsupported) — the
+   *  caller physically unmounts the outgoing side there. A new play() snaps the previous
+   *  transition to its end first. */
+  const play = (opts: {
+    incoming?: Side
+    outgoing?: Side
+    transition: string | TransitionSpecLike | null | undefined
+    onDone: () => void
+  }) => {
+    finishActive?.()
+
+    const spec = typeof opts.transition === "string" ? NAMED[opts.transition] : opts.transition ?? undefined
+    const inSide = opts.incoming && !opts.incoming.static ? opts.incoming.el : null
+    const outSide = opts.outgoing && !opts.outgoing.static ? opts.outgoing.el : null
+
+    let inFrom = spec?.incoming?.from
+    let outTo = spec?.outgoing?.to
+
+    // Static-side degradations (see header). A poseless spec ("none") stays instant — the
+    // degradations only reshape transitions that actually wanted to move something.
+    if (opts.incoming?.static && outSide && (spec?.incoming || spec?.outgoing)) {
+      // The incoming scene can't animate: unless this is an exit-shaped transition (onTop:
+      // "outgoing" — pop/zoom-out already fully remove the old side), the outgoing screen leaves
+      // by the mirror of the entry it was supposed to be covered by.
+      if (spec?.onTop !== "outgoing") outTo = inFrom ? mirrorExit(inFrom) : (outTo ?? { opacity: 0 })
+      inFrom = undefined
+    }
+    if (opts.outgoing?.static && inSide && !inFrom && spec && Object.keys(spec).length > 0) {
+      inFrom = { opacity: 0 }   // something must move; fade the screen in over the scene
+    }
+
+    const hasWork = (inSide && inFrom) || (outSide && outTo)
+    if (!spec || !hasWork || typeof (inSide ?? outSide)?.animate !== "function") {
+      opts.onDone()
+      return
+    }
+
+    const duration = spec.duration ?? 300
+    const easing = spec.easing ? `cubic-bezier(${spec.easing.join(",")})` : "cubic-bezier(0.25, 0.1, 0.25, 1)"
+    const animations: Animation[] = []
+
+    // z-order for the duration of the transition (screens only — the static canvas stays in
+    // flow at the bottom). Dim sits between the two.
+    const onTop = spec.onTop ?? "incoming"
+    const topEl = onTop === "incoming" ? inSide : outSide
+    const bottomEl = onTop === "incoming" ? outSide : inSide
+    if (topEl) topEl.style.zIndex = "3"
+    if (bottomEl) bottomEl.style.zIndex = "1"
+
+    let dimEl: HTMLElement | null = null
+    if (spec.dim && spec.dim > 0) {
+      dimEl = document.createElement("div")
+      dimEl.style.cssText = "position:absolute;inset:0;background:#000;pointer-events:none;z-index:2"
+      container.appendChild(dimEl)
+      // Entering (push): the under layer darkens; exiting (pop): it un-darkens.
+      const [a, b] = onTop === "incoming" ? [0, spec.dim] : [spec.dim, 0]
+      animations.push(dimEl.animate([{ opacity: a }, { opacity: b }], { duration, easing }))
+    }
+
+    if (inSide && inFrom) {
+      animations.push(inSide.animate([poseKeyframe(inFrom), IDENTITY], { duration, easing }))
+    }
+    if (outSide && outTo) {
+      animations.push(outSide.animate([IDENTITY, poseKeyframe(outTo)], { duration, easing, fill: "forwards" }))
+    }
+
+    let done = false
+    const cleanup = () => {
+      if (done) return
+      done = true
+      finishActive = null
+      for (const a of animations) a.cancel()   // drops fill:forwards so a detached-not-freed screen restores clean
+      if (topEl) topEl.style.zIndex = ""
+      if (bottomEl) bottomEl.style.zIndex = ""
+      dimEl?.remove()
+      opts.onDone()
+    }
+    finishActive = cleanup
+    Promise.all(animations.map(a => a.finished)).then(cleanup, cleanup)
+  }
+
+  return { play, finish: () => finishActive?.() }
+}

package/src/ui/props-apply.ts

@@ -0,0 +1,403 @@
+// The DOM host's property-application surface (docs/ui-property-registry-plan.md, phase 3).
+//
+// One entry per creator-ui host property, keyed and compiler-checked against the generated
+// registry surface (CuiProps.gen.ts): a missing key, an extra key, a reset handler on a prop
+// that resets through the set channel, or a MISSING reset on a host-reset prop are all type
+// errors. "unsupported" is the explicit opt-out and feeds the parity registry.
+//
+// String-channel values arrive here already UTF8-decoded; float/uint as numbers. The matrix
+// singleton channel (transform) is registered here too.
+import { CUI_HOST_PROPS, type CuiHostPropKey } from "./CuiProps.gen"
+import { cssFontFamily } from "./createMeasureSystem"
+import type { UIScreen } from "./UIScreen"
+
+type ValueOf<K extends CuiHostPropKey> =
+  (typeof CUI_HOST_PROPS)[K]["channel"] extends "string" ? string : number
+
+type Impl<K extends CuiHostPropKey> =
+  | "unsupported"
+  | ((typeof CUI_HOST_PROPS)[K]["hostReset"] extends true
+      ? { set(screenId: number, nodeId: number, value: ValueOf<K>): void
+          reset(screenId: number, nodeId: number): void }
+      : { set(screenId: number, nodeId: number, value: ValueOf<K>): void
+          reset?: never })
+
+export interface UIPropsCtx {
+  module: any
+  root: HTMLElement
+  getNode: (screenId: number, nodeId: number) => HTMLElement | undefined
+  getScreen: (screenId: number) => UIScreen | undefined
+  addStringHandler(key: string, cb: (screenId: number, nodePtr: number, str: number) => void): void
+  addFloatHandler(key: string, cb: (screenId: number, nodePtr: number, val: number) => void): void
+  addUIntHandler(key: string, cb: (screenId: number, nodePtr: number, val: number) => void): void
+  addResetHandler(key: string, cb: (screenId: number, nodePtr: number) => void): void
+  addMatrixHandler(cb: (screenId: number, nodePtr: number, matrixPtr: number) => void): void
+  addTransformOriginHandler(cb: (screenId: number, nodePtr: number, x: number, y: number, xPercent: number, yPercent: number) => void): void
+}
+
+export const registerUIProps = (ctx: UIPropsCtx) => {
+  const { module, root, getNode, getScreen } = ctx
+
+  const hexColor = (val: number) => "#" + (val >>> 0).toString(16).padStart(8, "0")
+
+  function applyBg(el: HTMLElement) {
+    const layers = []
+    if ((el as any)._bgGradient) layers.push((el as any)._bgGradient)  // сверху
+    if ((el as any)._bgImage)    layers.push((el as any)._bgImage)     // под градиентом
+    el.style.backgroundImage = layers.join(", ")
+  }
+
+  // lineClamp / textOverflow. Applied together (and alongside `display`, which the clamp has to
+  // take over) because -webkit-line-clamp ALWAYS ellipsizes — there is no CSS opt-out. A hard cut
+  // is therefore spelled a different way: Yoga has already sized the box to the clamped line
+  // count (see createMeasureSystem), so plain overflow:hidden does it. That makes "clip"
+  // approximate on the web — it cuts on the line-height box, not on the glyph as UIKit does.
+  const applyTextClamp = (el: HTMLElement) => {
+    const clamp = (el as any)._lineClamp as number | undefined
+    const declared = (el as any)._display as string | undefined
+    const clamped = !!clamp && clamp > 0
+    const ellipsis = clamped && (el as any)._textOverflow !== "clip"
+
+    if (ellipsis) {
+      el.style.setProperty("-webkit-box-orient", "vertical")
+      el.style.setProperty("-webkit-line-clamp", String(clamp))
+    } else {
+      el.style.removeProperty("-webkit-box-orient")
+      el.style.removeProperty("-webkit-line-clamp")
+    }
+
+    // An explicit `display: none` still wins — hiding a clamped node must keep working.
+    el.style.display = declared === "none" ? "none"
+      : ellipsis ? "-webkit-box"
+      : (declared ?? "")
+  }
+
+  // Style writers shared by the side/corner families (the key doubles as the camelCase CSS prop).
+  const setStyle = (prop: string) => (screenId: number, nodeId: number, value: string) => {
+    ;(getNode(screenId, nodeId)!.style as any)[prop] = value
+  }
+  const borderWidth = (side: string) => ({
+    set(screenId: number, nodeId: number, val: number) {
+      const el = getNode(screenId, nodeId)!
+      ;(el.style as any)[`border${side}Width`] = val + "px"
+      el.style.boxSizing = "border-box"
+    },
+  })
+  const borderColor = (side: string) => ({
+    set(screenId: number, nodeId: number, val: number) {
+      const el = getNode(screenId, nodeId)!
+      ;(el.style as any)[`border${side}Color`] = hexColor(val)
+      ;(el.style as any)[`border${side}Style`] = "solid"
+      el.style.boxSizing = "border-box"
+    },
+  })
+  const cornerRadius = (corner: string) => ({
+    set(screenId: number, nodeId: number, val: number) {
+      ;(getNode(screenId, nodeId)!.style as any)[`border${corner}Radius`] = val + "px"
+    },
+  })
+
+  const impl: { [K in CuiHostPropKey]: Impl<K> } = {
+    // ---- layout-dual ----
+    // `display` is routed through applyTextClamp because an active lineClamp needs to own the
+    // property (-webkit-box). Reset dispatches "flex" through this same handler (registry default).
+    display: {
+      set(screenId, nodeId, value) {
+        const el = getNode(screenId, nodeId)!
+        ;(el as any)._display = value
+        applyTextClamp(el)
+      },
+    },
+    // "visible" maps to "" so the stylesheet (e.g. .scrollable) keeps owning untouched nodes.
+    overflow: {
+      set(screenId, nodeId, value) {
+        getNode(screenId, nodeId)!.style.overflow = value === "visible" ? "" : value
+      },
+    },
+
+    // ---- scroll ----
+    scrollDirection: {
+      set(screenId, nodeId, value) {
+        const el = getNode(screenId, nodeId)!
+        if (value === 2) el.classList.add("scrollable_horizontal")
+        else el.classList.remove("scrollable_horizontal")
+      },
+    },
+    showScrollbar: {
+      set(screenId, nodeId, value) {
+        ;(getNode(screenId, nodeId)!.style as any).scrollbarWidth = value > 0.5 ? "" : "none"
+      },
+    },
+    overscrollMode: {
+      set(screenId, nodeId, value) {
+        // "absorb" (rubber-band without chaining) has no exact CSS spelling — contain is closest.
+        ;(getNode(screenId, nodeId)!.style as any).overscrollBehavior =
+          value === "default" ? "" : value === "none" ? "none" : "contain"
+      },
+    },
+    keyboardDismissMode: "unsupported",   // browser owns the virtual keyboard
+    snap: "unsupported",                  // CSS scroll-snap needs per-child align coordination
+    refreshControlColor: "unsupported",   // no DOM pull-to-refresh control
+
+    // ---- border ----
+    borderWidth: borderWidth(""),
+    borderTopWidth: borderWidth("Top"),
+    borderRightWidth: borderWidth("Right"),
+    borderBottomWidth: borderWidth("Bottom"),
+    borderLeftWidth: borderWidth("Left"),
+    // Yoga lays these edge variants out, but no host paints them (registry note).
+    borderHorizontalWidth: "unsupported",
+    borderVerticalWidth: "unsupported",
+    borderStartWidth: "unsupported",
+    borderEndWidth: "unsupported",
+    borderColor: borderColor(""),
+    borderTopColor: borderColor("Top"),
+    borderRightColor: borderColor("Right"),
+    borderBottomColor: borderColor("Bottom"),
+    borderLeftColor: borderColor("Left"),
+    borderRadius: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.borderRadius = val + "px" },
+    },
+    // Per-corner longhands, dispatched by the core's masked `borderRadius` string path ("0 0 20 20").
+    borderTopLeftRadius: cornerRadius("TopLeft"),
+    borderTopRightRadius: cornerRadius("TopRight"),
+    borderBottomRightRadius: cornerRadius("BottomRight"),
+    borderBottomLeftRadius: cornerRadius("BottomLeft"),
+
+    // ---- text ----
+    // Theme-kind reset: the core dispatches the theme value through set; only a theme WITHOUT a
+    // `color` key lands here — clear the inline value so defaultStyle.css's cascade takes over.
+    color: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.color = hexColor(val) },
+      reset(screenId, nodeId) { getNode(screenId, nodeId)!.style.color = "" },
+    },
+    fontFamily: {
+      set(screenId, nodeId, value) {
+        getNode(screenId, nodeId)!.style.fontFamily = cssFontFamily(value)
+      },
+      reset(screenId, nodeId) { getNode(screenId, nodeId)!.style.fontFamily = "" },
+    },
+    fontSize: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.fontSize = val + "px" },
+    },
+    fontWeight: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.fontWeight = val.toString() },
+    },
+    fontStyle: {
+      set(screenId, nodeId, val) {
+        if (val === 0) getNode(screenId, nodeId)!.style.fontStyle = "normal"
+        else if (val === 2) getNode(screenId, nodeId)!.style.fontStyle = "italic"
+      },
+    },
+    lineHeight: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.lineHeight = val + "px" },
+    },
+    letterSpacing: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.letterSpacing = val + "px" },
+    },
+    textAlign: { set: setStyle("textAlign") },
+    textDecoration: { set: setStyle("textDecoration") },
+    lineClamp: {
+      set(screenId, nodeId, val) {
+        const el = getNode(screenId, nodeId)!
+        ;(el as any)._lineClamp = val
+        // `overflow` is a function of the clamp alone, written ONLY here — never from
+        // applyTextClamp, which also runs for `display` on non-text nodes and would clear the
+        // overflow a scrollable/cell set at build time (UIScreen). Reset dispatches 0 here too.
+        el.style.overflow = val > 0 ? "hidden" : ""
+        applyTextClamp(el)
+        // The clamp changes the node's measured HEIGHT but touches no Yoga style, so nothing marks
+        // the leaf dirty on its own — Yoga would reuse the cached full-text measure. The recalc()
+        // that updateStyle/mergeStyle run after this handler then picks up the new size.
+        module._markNodeDirty(nodeId)
+      },
+    },
+    textOverflow: {
+      set(screenId, nodeId, value) {
+        const el = getNode(screenId, nodeId)!
+        ;(el as any)._textOverflow = value
+        applyTextClamp(el)
+      },
+    },
+
+    // ---- box / background ----
+    backgroundColor: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.backgroundColor = hexColor(val) },
+    },
+    backgroundImage: {
+      set(screenId, nodeId, value) {
+        const el = getNode(screenId, nodeId)!
+        // "" is the registry's no-image default — clear the layer (never emit `url()`).
+        ;(el as any)._bgImage = value ? `url(${value})` : undefined
+        applyBg(el)
+      },
+    },
+    backgroundSize: { set: setStyle("backgroundSize") },
+    // The raw validated CSS gradient string, emitted alongside the struct channel for DOM hosts;
+    // "" = no gradient (parse failure or removal).
+    backgroundGradientStr: {
+      set(screenId, nodeId, value) {
+        const el = getNode(screenId, nodeId)!
+        ;(el as any)._bgGradient = value || undefined
+        applyBg(el)
+      },
+    },
+    rippleColor: "unsupported",   // no press-ripple system on the DOM host
+
+    // ---- effects ----
+    opacity: {
+      set(screenId, nodeId, val) { getNode(screenId, nodeId)!.style.opacity = val.toString() },
+    },
+    pointerEvents: {
+      set(screenId, nodeId, value) {
+        getNode(screenId, nodeId)!.style.pointerEvents = value === "none" ? "none" : "auto"
+      },
+    },
+
+    // ---- image ----
+    objectFit: {
+      set(screenId, nodeId, value) {
+        const el = getNode(screenId, nodeId)!
+        // An explicit sourceRect crop overrides objectFit (the frame always fills the box, via
+        // background-size on the crop <div>) — ignore objectFit rather than picking a least-bad fit.
+        if ((el as any)._sourceRect) return
+        if (el.hasAttribute("data-viewbox")) {
+          const size = value === "cover" ? "cover" : value === "fill" ? "100% 100%" : "contain"
+          const s = el.style as any
+          s.webkitMaskSize = s.maskSize = size
+        } else {
+          el.style.objectFit = value
+        }
+      },
+    },
+    tintColor: {
+      set(screenId, nodeId, val) {
+        const tint = hexColor(val)
+        const screen = getScreen(screenId)
+        const el = screen?.nodeMap.get(nodeId)!
+        if (el instanceof HTMLDivElement) {
+          el.style.backgroundColor = tint              // already masked div → just recolor
+        } else if (el instanceof HTMLImageElement && el.hasAttribute("data-viewbox")) {
+          screen!.tintSvgImage(nodeId, tint)           // svg img + new tint → swap to masked div
+        } else {
+          el.style.backgroundColor = tint              // non-svg img: harmless, no mask possible
+        }
+      },
+      // Presence prop: no tint = the image's original colors (masked div swaps back to <img>).
+      reset(screenId, nodeId) { getScreen(screenId)?.untintSvgImage(nodeId) },
+    },
+
+    // ---- input ----
+    placeholder: {
+      set(screenId, nodeId, value) {
+        ;(getNode(screenId, nodeId) as HTMLInputElement).placeholder = value
+      },
+    },
+    placeholderColor: {
+      set(screenId, nodeId, val) {
+        ;(getNode(screenId, nodeId) as HTMLInputElement).style
+          .setProperty("--placeholder-color", hexColor(val))
+      },
+      // Platform-default prop: absent = the browser's placeholder gray (defaultStyle.css fallback).
+      reset(screenId, nodeId) {
+        ;(getNode(screenId, nodeId) as HTMLInputElement).style.removeProperty("--placeholder-color")
+      },
+    },
+    type: {
+      set(screenId, nodeId, value) {
+        ;(getNode(screenId, nodeId) as HTMLInputElement).type = value
+      },
+    },
+    enterKey: {
+      set(screenId, nodeId, value) {
+        ;(getNode(screenId, nodeId) as HTMLInputElement).enterKeyHint = value
+      },
+    },
+    autocapitalize: {
+      set(screenId, nodeId, value) {
+        ;(getNode(screenId, nodeId) as HTMLInputElement).autocapitalize = value
+      },
+    },
+    autocorrect: {
+      set(screenId, nodeId, val) {
+        getNode(screenId, nodeId)!.setAttribute("autocorrect", val > 0.5 ? "on" : "off")
+      },
+    },
+    maxLength: {
+      set(screenId, nodeId, val) {
+        const el = getNode(screenId, nodeId) as HTMLInputElement
+        if (val > 0) el.maxLength = val
+        else el.removeAttribute("maxlength")   // registry: 0 = unlimited
+      },
+    },
+    keyboardShrink: "unsupported",   // browser owns the visual-viewport policy
+    keyboardDismiss: "unsupported",
+
+    // ---- widget ----
+    // overlayColor: a full-screen layer behind the widget that intercepts clicks. It is kept
+    // separate from the widget subtree and sits below `.widget` (z-index 10) but above the scene.
+    // A pointerup on it fires onOverlayTap. The layer exists for any non-null overlayColor
+    // ("transparent" included); only overlayColor: null removes it (presence prop → host reset).
+    // Teardown on hide is handled by UIScreen.removeFromHTML.
+    overlayColor: {
+      set(screenId, _nodeId, val) {
+        const screen = getScreen(screenId)
+        if (!screen) return
+        let overlay = screen.overlayElement
+        if (!overlay) {
+          overlay = document.createElement("div")
+          overlay.style.position = "absolute"
+          overlay.style.inset = "0"
+          overlay.style.pointerEvents = "auto"
+          overlay.style.zIndex = "9"
+          overlay.addEventListener("click", () => {
+            for (const listener of screen.node.otl ?? []) listener()
+          })
+          root.appendChild(overlay)
+          screen.overlayElement = overlay
+        }
+        overlay.style.background = hexColor(val)
+      },
+      reset(screenId) {
+        const screen = getScreen(screenId)
+        if (!screen) return
+        screen.overlayElement?.remove()
+        screen.overlayElement = null
+      },
+    },
+    sheetDetents: "unsupported",      // docs/bottom-sheet-plan.md owns these — no web sheet yet
+    sheetDetent: "unsupported",
+    sheetDismissible: "unsupported",
+  }
+
+  // ---- registration (channel-driven; string pointers decode before the impl sees them) --------
+  const unsupported: CuiHostPropKey[] = []
+  for (const key of Object.keys(CUI_HOST_PROPS) as CuiHostPropKey[]) {
+    const entry = impl[key] as { set: Function, reset?: Function } | "unsupported"
+    if (entry === "unsupported") { unsupported.push(key); continue }
+    const { channel } = CUI_HOST_PROPS[key]
+    if (channel === "string") {
+      ctx.addStringHandler(key, (screenId, nodePtr, str) =>
+        entry.set(screenId, nodePtr, module.UTF8ToString(str)))
+    } else if (channel === "uint") {
+      ctx.addUIntHandler(key, (screenId, nodePtr, val) => entry.set(screenId, nodePtr, val))
+    } else {
+      ctx.addFloatHandler(key, (screenId, nodePtr, val) => entry.set(screenId, nodePtr, val))
+    }
+    if (entry.reset) ctx.addResetHandler(key, (screenId, nodePtr) => entry.reset!(screenId, nodePtr))
+  }
+
+  // Singleton matrix channel (transform).
+  ctx.addMatrixHandler((screenId, nodePtr, matrixPtr) => {
+    const i = matrixPtr >> 2
+    const f = module.HEAPF32
+    getNode(screenId, nodePtr)!.style.transform =
+      `matrix(${f[i + 0]}, ${f[i + 1]}, ${f[i + 3]}, ${f[i + 4]}, ${f[i + 6]}, ${f[i + 7]})`
+  })
+  // Singleton origin channel (transformOrigin) — the matrix's pivot, per axis % of the box or px.
+  ctx.addTransformOriginHandler((screenId, nodePtr, x, y, xPercent, yPercent) => {
+    getNode(screenId, nodePtr)!.style.transformOrigin = `${x}${xPercent ? "%" : "px"} ${y}${yPercent ? "%" : "px"}`
+  })
+
+  return { unsupported }
+}

package/src/ui/router.ts

@@ -0,0 +1,2 @@
+// Moved to viewer-lite (genericized over the screen type); re-export shim.
+export * from "lecodes-viewer-lite/src/ui/router"

package/src/ui/safeAreaSpec.ts

@@ -0,0 +1,3 @@
+// Lives in the viewer-lite package (the minimal web host owns the shared leaf modules);
+// re-exported so viewer-internal imports keep working with ONE definition.
+export * from "lecodes-viewer-lite/src/ui/safeAreaSpec"

package/src/ui/shells.ts

@@ -0,0 +1,37 @@
+// Device shells the runner can emulate for an embedder that drives it by name (the landing's
+// `?shell=` / `lecodes-shell`). "abstract" is the neutral frame with the host's default web insets;
+// "ios"/"android" pin the safe-area insets to that device's real values so a screen that skips
+// safe-top visibly collides with the Dynamic Island / status bar.
+//
+// The values mirror the editor's SHELL_SAFE_AREAS (frontend simulator/shells.ts) and lecodes-design's
+// board shells (`lecodes render --device`) — portrait matches the board; landscape is the simulator's
+// own (the board is portrait-only). This is the runner-owned copy so the catalog lives with the host
+// that applies it; the URL/postMessage driver only needs a shell NAME from the embedder.
+
+import type { SafeAreaSpec } from "./safeAreaSpec"
+
+export type SimulatorShell = "abstract" | "ios" | "android"
+
+/** Ordered shell ids (also the accepted `?shell=` values). */
+export const SIMULATOR_SHELLS: SimulatorShell[] = ["abstract", "ios", "android"]
+
+export const SHELL_SAFE_AREAS: Record<SimulatorShell, SafeAreaSpec | undefined> = {
+  abstract: undefined,
+  // Dynamic Island + home indicator (iPhone 14 Pro+) — clearance zones, breathing room built in.
+  // Landscape hides the status bar: symmetric island-side insets + a shallower home indicator.
+  ios: { portrait: [59, 0, 34, 0], landscape: [0, 59, 21, 59] },
+  // Status bar + 3-button navigation bar — both exact-height system BARS (`comfort-*` ADDS its
+  // knob past them instead of flooring). Both stay put in landscape.
+  android: {
+    portrait: [24, 0, 48, 0],
+    landscape: [24, 0, 48, 0],
+    portraitBars: ["top", "bottom"],
+    landscapeBars: ["top", "bottom"],
+  },
+}
+
+/** Narrow an untrusted string (URL param / postMessage) to a known shell; anything else → abstract. */
+export const asShell = (raw: unknown): SimulatorShell =>
+  typeof raw === "string" && (SIMULATOR_SHELLS as string[]).includes(raw)
+    ? (raw as SimulatorShell)
+    : "abstract"

package/src/ui/toasts.ts

@@ -0,0 +1,2 @@
+// Moved to viewer-lite; re-export shim.
+export * from "lecodes-viewer-lite/src/ui/toasts"