lecodes-sdk 2.0.8 → 2.0.9

package/src/ui/UIModal.ts

@@ -1,5 +1,8 @@
 import { type UIWidget, type UIWidgetStyle, WidgetElement } from "./UIWidget"
 import { buildUI, type BaseStyle, type ChildrenFn, type Color, type DrawableStyle, type UIChildArg, type UINodeChild } from "./UINode"
+import type { TransitionPose } from "./presentable"
+import { _widgetPoseId } from "./transitions"
+import { tree } from "./tree"
 
 export type UIModalStyle = UIWidgetStyle
 
@@ -16,17 +19,20 @@ const MODAL_ANIM_MS = 200
 
 /**
  * A dialog: a `UIWidget` with the modal boilerplate built in. Comes with a scrim
- * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()`
- * (a 200 ms fade by default — swap the pose via `transition()`; the exit plays with
- * `commit: false`, so the style is intact for the next show), and closes itself on a scrim tap
- * or the Android back button (disable via `dismissible(false)`). Everything else is a plain
- * widget — same styling, children, touch and `attachTo()` surface; create it **once** at module
- * scope and reuse it.
+ * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()` and on
+ * a state block flipping its `display` (a 200 ms fade by default — swap the pose via
+ * `transition()`; the runtime plays it as tracks that never touch the style), and closes itself
+ * on a scrim tap or the Android back button (disable via `dismissible(false)`). Everything else
+ * is a plain widget: declare it where it belongs — among its screen's children, hidden until a
+ * tap (`display: "none"`), or shown with `show()` from anywhere, which puts a parentless modal in
+ * the app layer. A dialog bound to data (its display from a binding) is declared
+ * `dismissible(false)` and routes `onOverlayTap` / `onBack` into the data's dismiss, so the data
+ * stays what the screen shows.
  */
 export interface UIModal extends UIWidget {
-  /** Mount as an overlay and play the entrance transition. No-op while already open. */
+  /** Show and play the entrance transition. No-op while already open. */
   show(): void,
-  /** Play the exit transition, then unmount. No-op while closed or already closing. */
+  /** Play the exit transition, then hide. No-op while closed or already closing. */
   hide(): void,
   /** True from `show()` until `hide()` starts (already false during the exit animation). */
   readonly isOpen: boolean,
@@ -43,73 +49,82 @@ export interface UIModal extends UIWidget {
    */
   transition(hidden: UIModalTransition): this,
 
-  /** Called when `show()` mounts the modal. */
+  /** Called when the modal opens — `show()`, or a state block flipping its display. */
   onOpen(callback: () => void): this,
-  /** Called when the modal starts closing — scrim tap, back button, or a `hide()` call. */
+  /** Called when the modal starts closing — scrim tap, back button, a `hide()` call, or a state
+   *  block flipping its display. */
   onClose(callback: () => void): this,
   /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
-   *  (forced-choice dialogs). Default `true`. */
+   *  (forced-choice dialogs, a dialog whose display is bound to data). Default `true`. */
   dismissible(enabled: boolean): this,
 }
 
 export class ModalElement extends WidgetElement {
-  _open = false
   _dismissible = true
   _transition: UIModalTransition = { opacity: 0 }
-  _closeTimer?: ReturnType<typeof setTimeout>
   readonly _openListeners: (() => void)[] = []
   readonly _closeListeners: (() => void)[] = []
+  private _poseObj?: TransitionPose
+  private _poseKey = ""
 
   constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn) {
     super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", ...style }, children)
     this.onOverlayTap(() => { if (this._dismissible) this.hide() })
     this.onBack(() => { if (this._dismissible) this.hide() })
+    this._syncPose()
   }
 
-  // The full animate argument: hidden pose + duration, plus the scrim fade — only when the
-  // modal actually has a scrim (overlayColor: null opts out; animating a null scrim would
-  // create the intercepting layer) and the pose doesn't drive the scrim itself.
-  private _pose(extra?: Record<string, unknown>): Record<string, unknown> {
-    const pose: Record<string, unknown> = { duration: MODAL_ANIM_MS, ...this._transition, ...extra }
-    const overlayColor = (this._style as UIModalStyle).overlayColor
-    if (pose.overlayColor === undefined && overlayColor !== undefined && overlayColor !== null) {
-      pose.overlayColor = "transparent"
-    }
+  // The pose the runtime plays on a display flip: the hidden pose + its duration, plus the scrim
+  // fade — only when the modal actually has a scrim (overlayColor: null opts out; a track on a
+  // null scrim would create the intercepting layer) and the pose doesn't drive the scrim itself.
+  private _pose(): TransitionPose {
+    const t = this._transition
+    const pose: TransitionPose = { duration: t.duration ?? MODAL_ANIM_MS }
+    if (t.transform !== undefined) pose.transform = t.transform as string
+    if (t.opacity !== undefined) pose.opacity = t.opacity as number
+    const scrim = t.overlayColor !== undefined ? t.overlayColor : (this._style as UIModalStyle).overlayColor
+    if (t.overlayColor !== undefined) { if (t.overlayColor !== null) pose.overlayColor = String(t.overlayColor) }
+    else if (scrim !== undefined && scrim !== null) pose.overlayColor = "transparent"
     return pose
   }
 
-  private get _duration(): number {
-    return this._transition.duration ?? MODAL_ANIM_MS
+  /** @internal Register the pose with the runtime when it changed (ctor, transition(), a show /
+   *  hide — the scrim may have been restyled since). */
+  _syncPose(): void {
+    if (this._h.id === 0) return
+    const pose = this._pose()
+    const key = JSON.stringify(pose)
+    if (key === this._poseKey) return
+    this._poseKey = key
+    this._poseObj = pose
+    tree().setWidgetPose(this._h.id, _widgetPoseId(pose))
   }
 
   transition(hidden: UIModalTransition): this {
     this._transition = hidden
+    this._syncPose()
     return this
   }
 
-  show(): void {
-    if (this._open) return
-    if (this._closeTimer !== undefined) {   // reopened mid exit: finish that hide now
-      clearTimeout(this._closeTimer)
-      this._closeTimer = undefined
-      super.hide()
-    }
-    this._open = true
+  override show(): void {
+    if (this._shown) return
+    this._syncPose()
     super.show()
-    this.animateFrom(this._pose())
-    for (const callback of this._openListeners) callback()
   }
 
-  hide(): void {
-    if (!this._open) return
-    this._open = false
-    this.animateTo(this._pose({ commit: false }))
-    this._closeTimer = setTimeout(() => { this._closeTimer = undefined; super.hide() }, this._duration)
-    for (const callback of this._closeListeners) callback()
+  override hide(): void {
+    if (!this._shown) return
+    this._syncPose()
+    super.hide()
   }
 
   get isOpen(): boolean {
-    return this._open
+    return this._shown
+  }
+
+  /** @internal onOpen / onClose follow the intent, whoever flipped it. */
+  override _shownChanged(shown: boolean): void {
+    for (const callback of (shown ? this._openListeners : this._closeListeners).slice()) callback()
   }
 
   onOpen(callback: () => void): this {
@@ -128,8 +143,9 @@ export class ModalElement extends WidgetElement {
 
 const makeModal = (style: any, children: any) => new ModalElement(style, children)
 
-/** Create a modal dialog (see {@link UIModal}) — create once at module scope, then
- *  `show()`/`hide()`. Same argument forms as `UIColumn`. */
+/** Create a modal dialog (see {@link UIModal}): declare it among its screen's children with
+ *  `display: "none"` and `show()` it from a tap, or `show()` a parentless one from anywhere.
+ *  Same argument forms as `UIColumn`. */
 export function UIModal(...children: UIChildArg[]): UIModal;
 export function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
 export function UIModal(...args: any[]): UIModal {

package/src/ui/UINode.ts

@@ -793,7 +793,15 @@ export function buildUI<R>(args: any[], defaults: any, make: (style: any, childr
  *  names the usual cause (both come from code written for the older SDK). */
 const acceptChild = (parent: { type: string }, node: any): boolean => {
   if (!node) return false
-  if (node instanceof Element) return true
+  if (node instanceof Element) {
+    // A widget belongs to a WINDOW, never to a box (docs/plans/widgets-plan.md decision 9): a
+    // child of a screen root, a surface's content or the app layer only. The runtime refuses it
+    // too; this says what to write instead.
+    if (node.type === "widget" && parent.type !== "screen" && parent.type !== "layer") {
+      throw new Error(`${parent.type}: a widget cannot be a child of a ${parent.type}. A widget (UIWidget / UIModal / UIBottomSheet / UIPopover) belongs to the window: put it among the screen's children — UIScreen(content, dialog) — or in scene.setContent([...]) / UIOverlay. A floating element of a box is an absolute child: UIBox(...).style({ position: "absolute", ... }), not a widget.`)
+    }
+    return true
+  }
   const hint =
     typeof node === "function" ? "reactive children are the factory's only argument: UIColumn(() => [ ... ])"
     // by its backing fields: in a bundle chisel drops the accessors nobody reads (`finished`)

package/src/ui/UIPopover.ts

@@ -1,7 +1,7 @@
 import { ModalElement, type UIModal, type UIModalStyle } from "./UIModal"
-import { Presentable } from "./presentable"
 import { device } from "../runtime/device"
 import { buildUI, type BoundingClientRect, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
+import { byId, tree } from "./tree"
 
 export type UIPopoverStyle = UIModalStyle
 
@@ -22,9 +22,11 @@ const VIEWPORT_MARGIN = 8  // minimum distance kept to every screen edge
  * tooltips; create it **once** at module scope and reuse it.
  */
 export interface UIPopover extends UIModal {
-  /** Position next to `anchor` (an element or an `{x, y}` point), attach to
-   *  `Presentable.current` (unless an owner was set via `attachTo`), and play the entrance
-   *  transition. Without an anchor the popover shows wherever its own style puts it. */
+  /** Position next to `anchor` (an element or an `{x, y}` point), put the popover where the
+   *  anchor is — the anchor's screen, page or surface content, found through the tree, so the
+   *  menu lands where it was opened and goes with it — and play the entrance transition. A
+   *  popover with no anchor and no parent goes to the app layer; without an anchor it shows
+   *  wherever its own style puts it. */
   show(anchor?: UIPopoverAnchor): void,
 }
 
@@ -41,7 +43,7 @@ export class PopoverElement extends ModalElement {
     this.onLayout(({ width, height }) => this._place(width, height))
   }
 
-  show(anchor?: UIPopoverAnchor): void {
+  override show(anchor?: UIPopoverAnchor): void {
     if (anchor) {
       const r = "getBoundingClientRect" in anchor
         ? anchor.getBoundingClientRect()
@@ -54,18 +56,18 @@ export class PopoverElement extends ModalElement {
         // refines it once the size is known.
         this.style({ left: r.left, top: r.bottom + ANCHOR_GAP })
       }
+      // A menu belongs where it opened: the anchor's root — a screen, a page, a surface's layer.
+      const root = anchorRoot(anchor)
+      if (root && this.parent !== root) root.append(this)
     } else {
       this._anchorRect = undefined   // unanchored show: the user's own style owns the position
     }
-    // A menu belongs to the page it opened on: it hides with it and rides its transition. An
-    // explicit attachTo() owner (e.g. a scene HUD's popover) is respected.
-    if (!this._owner) this.attachTo(Presentable.current)
     super.show()
   }
 
   private _place(width: number, height: number): void {
     const anchor = this._anchorRect
-    if (!anchor || !this._open) return
+    if (!anchor || !this._shown) return
     const displayWidth = device.width, displayHeight = device.height   // 0 on hosts without a size
     let left = anchor.left
     let top = anchor.bottom + ANCHOR_GAP
@@ -87,6 +89,18 @@ export class PopoverElement extends ModalElement {
   }
 }
 
+// The root an anchor element sits in, when it is a place a widget can belong to: a screen or a
+// layer that is ATTACHED (presented, in the router, a pager's page, a shown layer — the pins find
+// it by id); null for a point, a loose subtree, or a screen that is not on any stack.
+const anchorRoot = (anchor: UIPopoverAnchor): { append(...nodes: any[]): unknown, type: string } | null => {
+  const h = (anchor as any)._h
+  if (!h || typeof h.id !== "number" || h.id === 0) return null
+  let id = h.id as number
+  for (let up = tree().parent(id); up !== 0; up = tree().parent(id)) id = up
+  const el = byId(id) as any
+  return el && typeof el.append === "function" && (el.type === "screen" || el.type === "layer") ? el : null
+}
+
 const makePopover = (style: any, children: any) => new PopoverElement(style, children)
 
 /** Create an anchored popover (see {@link UIPopover}) — create once at module scope, then

package/src/ui/UIVideo.ts

@@ -1,4 +1,5 @@
 import type { VideoPlayer } from "../runtime/media"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "./UILayer"
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "./presentable"
 import { _transitionId, TRANSITION_NONE } from "./transitions"
 import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
@@ -24,6 +25,8 @@ export interface UIVideo extends UIElementBase<UIVideoStyle, DrawableStyle & Bas
   onClose(callback: () => void): this
   /** Hardware/system back while current. */
   onBack(callback: () => void): this
+  /** The UI over the video when presented: widgets over it (`Presentable.setContent`). */
+  setContent(content: UIWidgetContent): this
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
@@ -47,6 +50,14 @@ class VideoElement extends Element<"video"> implements Presentable {
 
   /** @internal */
   _dest(): DestTuple { return [TREE_DEST_VIDEO, this._h.id, "", ""] }
+  /** @internal The video's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the video when it is presented full screen — widgets (controls, a title),
+   *  laid out over it; touches outside a widget's box reach the video. */
+  setContent(content: UIWidgetContent): this {
+    _setSurfaceContent(this, content)
+    return this
+  }
 
   open(options?: PresentOptions): void {
     if (this._h.id === 0) return

package/src/ui/UIWidget.ts

@@ -1,42 +1,45 @@
 import { TouchStartEvent } from "../runtime/touch"
-import { Presentable } from "./presentable"
 import { ContainerElement, buildUI, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type PaddingStyle, type PositionStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode"
-import { TREE_DEST_NONE, TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, pin, tree, unpin } from "./tree"
+import { UIOverlay } from "./UILayer"
+import { TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, tree } from "./tree"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
+  /** Shown (`"flex"`, the default) or not: what `show()` / `hide()` write, what a state block may
+   *  flip (`$open: { display: "flex" }`). */
+  display?: "none" | "flex",
   /** A layer behind the widget that intercepts clicks — `"transparent"` still intercepts, `null`
    *  removes the layer. A tap on it fires `onOverlayTap`. */
   overlayColor?: Color | null
 }
 
 
-/** A floating overlay — absolutely positioned in device coordinates, mounted above the page as
- *  its own layout root (never a child of what's underneath). The base of dialogs, toasts,
- *  mini-players and scene HUDs; `UIModal`/`UIPopover`/`UIBottomSheet` build on it. */
+/** A floating overlay that belongs to a WINDOW, not to a box (docs/plans/widgets-plan.md): a dialog,
+ *  a sheet, a HUD, a mini-player. A widget is a CHILD of the place it belongs to — a `UIScreen`
+ *  (among its children), a surface's content (`scene.setContent([hud])`) or the app layer
+ *  (`UIOverlay`) — and is laid out and painted in the box of the outermost presented destination
+ *  that contains it: absolutely positioned in that box, above everything else in it. A widget on a
+ *  tab page covers the tab bar and rides the shell's push and pop. A widget inside a `UIColumn` or
+ *  any other box is an error: a floating element of a box is an absolute child, not a widget.
+ *
+ *  It shows with its place unless its style says `display: "none"`; `show()` / `hide()` flip that,
+ *  and so does a state block (`$class: { display: "flex" }`). `UIModal` / `UIPopover` /
+ *  `UIBottomSheet` build on it. */
 export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle & BaseStyle & { overlayColor?: Color | null }> {
   readonly type: "widget",
 
-  /**
-   * Attach this widget to a destination (a `Scene`, a `UIScreen`, …): the widget lives on that
-   * page's layer — it shows/hides with the page and rides its transition, and a screen pushed
-   * on top covers it (a scene HUD behaves like part of the scene). Sticky until `attachTo(null)`
-   * (= back to a global overlay). Set it while the widget is hidden. The widget is always its own
-   * overlay root mounted into the owner's page view — it never becomes a child of the owner, so it
-   * stays topmost and its updates never trigger the owner's relayout. Works with a `UIScreen` that
-   * is a page inside a `UIPager`: the widget mounts into that tab and rides its swipe.
-   */
-  attachTo(owner: Presentable | null): this,
-
-  /** Show the widget. By default it is a global overlay above every destination — it stays
-   *  visible across navigation until `hide()` (dialogs, mini-player, global loader). If the
-   *  widget was attached via `attachTo(owner)`, it mounts on that page's layer instead and is
-   *  only visible while the owner is presented. */
+  /** Show the widget: `display: "flex"`, on top of its root — it moves to the end of its parent's
+   *  children, so a dialog opened later covers an earlier one and a HUD declared after it. A widget
+   *  with no parent is appended to the app layer first (`UIOverlay`) — a global overlay above every
+   *  destination, up until `hide()`. */
   show(): void,
-  /** Unmount the widget. */
+  /** Hide the widget: `display: "none"`. It stays where it is (its place, the app layer), ready
+   *  for the next `show()`. */
   hide(): void,
 
-  /** Mounted right now (`show()` ran, `hide()` hasn't). */
+  /** Shown right now by its own display (`show()` ran, `hide()` hasn't, no state block hides
+   *  it). True for a widget hidden WITH its page or its covered screen: that is its place's
+   *  visibility, not the widget's. */
   readonly isShown: boolean,
 
   /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
@@ -53,41 +56,63 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
 
 export class WidgetElement extends ContainerElement<"widget"> {
   scrollable = false as const
-  _owner?: Presentable
-  private _shown = false
+  /** @internal The widget's own display as last known, while it has a place: what the app wrote,
+   *  corrected by the runtime's report when a state block flipped it (TREE_EVENT_WIDGET_VISIBLE).
+   *  False while the widget is nowhere (made, not placed; removed). */
+  _shown = false
   constructor(type: "widget", style: UIWidgetStyle, children: UINodeChild[] | ChildrenFn) {
-    // Widgets are absolutely positioned in device coordinates — in the constructor (not the
+    // Widgets are absolutely positioned in their root's box — in the constructor (not the
     // factory) so subclasses like ModalElement inherit it.
     super(type, { position: "absolute", ...style }, children)
   }
-  attachTo(owner: Presentable | null): this {
-    this._owner = owner ?? undefined
-    return this
-  }
   show(): void {
-    // A widget is always its OWN overlay root (a separate Yoga tree mounted above the owner's
-    // content) — never a child of the owner, so it stays topmost, its updates never relayout the
-    // owner, and it doesn't pollute the owner's children. `attachTo(owner)` just tells the host
-    // which page view to mount that root into; ownerless widgets are global overlays.
-    if (this._h.id === 0 || this._shown) return
-    this._shown = true
-    pin(this)
-    if (this._owner) {
-      const [kind, id] = this._owner._dest()
-      tree().showWidget(this._h.id, kind, id)
+    if (this._h.id === 0) return
+    const parentId = tree().parent(this._h.id)
+    if (parentId !== 0 && this._shown) return
+    if (parentId === 0) {
+      // No place of its own: the app layer takes it HIDDEN, and the flip below shows it — a show()
+      // is a display flip wherever the widget is, so its pose plays (a modal's fade) exactly as on
+      // a placed one. Appended shown, it would merely appear: a widget shows with its place, no pose.
+      this.style({ display: "none" } as any)
+      UIOverlay.append(this as any)   // pins it: _pinned reads the display
     } else {
-      tree().showWidget(this._h.id, TREE_DEST_NONE, 0)
+      // Shown = on top of its root: a show() moves the widget to the TAIL of its parent's children
+      // (child order is the one ordering rule), so a modal opened later covers an earlier one and
+      // the HUD declared after it — while still hidden, so the move is silent (no onClose / onOpen).
+      // A state block flipping the display moves nothing: the order is what the tree says.
+      const siblings = tree().children(parentId)
+      if (siblings[siblings.length - 1] !== this._h.id) {
+        tree().remove(parentId, this._h.id)
+        tree().insert(parentId, this._h.id, siblings.length - 1)
+      }
     }
+    this.style({ display: "flex" } as any)
+    this._setShown(true)
   }
   hide(): void {
     if (this._h.id === 0 || !this._shown) return
-    this._shown = false
-    tree().hideWidget(this._h.id)
-    unpin(this._h.id)
+    this._setShown(false)
+    this.style({ display: "none" } as any)
   }
   get isShown(): boolean {
     return this._shown
   }
+  /** @internal The intent changed (the app's call, or the runtime's report of a cascade flip):
+   *  subclasses hook the change (UIModal's onOpen / onClose). */
+  _setShown(shown: boolean): void {
+    if (shown === this._shown) return
+    this._shown = shown
+    this._shownChanged(shown)
+  }
+  /** @internal */
+  _shownChanged(_shown: boolean): void {}
+  /** @internal The runtime: the widget's resolved display flipped — or, at its place, the cascade
+   *  says otherwise than the style it read in `_pinned` (the runtime reports nothing else there). */
+  _emitVisible(shown: boolean): void { this._setShown(shown) }
+  /** @internal Placed (inserted under a screen, a layer): shown by its own display from here on. */
+  _pinned(): void { this._setShown((this._style as { display?: string }).display !== "none") }
+  /** @internal Taken out of its place: shown nowhere. */
+  _unpinned(): void { this._setShown(false) }
 
   readonly touchStartListeners: any[] = []
   onTouchStart (callback: any): this {
@@ -138,7 +163,8 @@ const makeWidget = (style: any, children: any) => new WidgetElement("widget", st
 /** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
 export const __UIWidget = (children: UINodeChild[] | ChildrenFn): UIWidget => makeWidget({}, children)
 
-/** Create a widget (same argument forms as `UIColumn`). Position it with absolute-style props
+/** Create a widget (same argument forms as `UIColumn`). Put it where it belongs — among a screen's
+ *  children, in `scene.setContent([...])`, or `UIOverlay` — position it with absolute-style props
  *  (`top`/`left`/`bottom`/`right`), then `show()`/`hide()`. */
 export function UIWidget(...children: UIChildArg[]): UIWidget;
 export function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;

package/src/ui/presentable.ts

@@ -2,7 +2,7 @@
 // Anything that can occupy the app's main slot implements it: UIScreen, Scene (+ARScene),
 // Scene2D, NativeView, UIVideo. Exactly one Presentable is visible at a time — a screen no
 // longer overlays a scene, it replaces it (with a transition); UI over a scene goes through
-// `UIWidget.attachTo(scene)`.
+// `scene.setContent([hud])` — a widget is the destination's content (docs/plans/widgets-plan.md).
 //
 // A destination is addressed by (kind, id): a screen / video by its node id, a scene by its
 // scene id, a native view by its viewId (`_dest()`). The runtime reports the lifecycle back through
@@ -12,6 +12,7 @@
 // element code into engine-only bundles.
 
 import type { EasingInput } from "../animate/tween/easing"
+import type { UIWidget } from "./UIWidget"
 
 /** The built-in transitions (ui/transitions.ts holds what each one is). `push` / `pop` are the
  *  stacked-navigation pair — the incoming screen slides over the other one, which drifts and dims;
@@ -32,6 +33,9 @@ export type TransitionPose = {
   opacity?: number | number[]
   /** Black over this screen, 0..1: how dark the screen UNDER the other one gets. */
   dim?: number | number[]
+  /** A widget's overlay layer (its scrim) in the pose — a widget's enter / exit pose only
+   *  (`UIModal.transition`): `"transparent"` fades the scrim in with the dialog. */
+  overlayColor?: string | string[]
   /** ms (default 300). */
   duration?: number
   /** ms to wait; the screen holds its first pose through it. */
@@ -97,6 +101,12 @@ export interface Presentable {
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
   onBack(callback: () => void): this
+  /** The destination's widgets (docs/plans/widgets-plan.md): a dialog, a HUD, a sheet declared as
+   *  CONTENT of the place they belong to. A `UIScreen` takes them among its children; a surface — a
+   *  `Scene`, a `Scene2D`, a `NativeView`, a `UIVideo` — takes widgets alone, laid out over it while
+   *  it is presented (touches outside a widget's box reach the surface). A widget shows with its
+   *  destination unless its style says `display: "none"`; `show()` / `hide()` flip that. */
+  setContent(content: (UIWidget | null | undefined | false)[] | (() => (UIWidget | null | undefined | false)[])): this
   /** @internal Async work that must finish BEFORE this destination replaces the current one
    *  (camera permission, warm render, session launch — ARScene). The previous destination —
    *  typically a loading screen — stays visible while it runs; `open()` and `Router.push/replace`

package/src/ui/transitions.ts

@@ -9,7 +9,7 @@
 
 import type { Easing } from "../animate/easings"
 import { DEFAULT_EASING, parseEasing, type EasingSpec } from "../animate/tween/easing"
-import { CLOCK_UI, DOM_UI, KIND_FLOAT, KIND_TRANSFORM, buildBlob, parseTransformList, transformLanes, warnOnce, type Keyframe, type Track, type TweenTarget } from "../animate/tween/spec"
+import { CLOCK_UI, DOM_UI, KIND_FLOAT, KIND_STRING, KIND_TRANSFORM, buildBlob, parseTransformList, transformLanes, warnOnce, type Keyframe, type Track, type TweenTarget } from "../animate/tween/spec"
 import type { Transition, TransitionName, TransitionPose, TransitionSpec } from "./presentable"
 
 /** Wire ids: a registered transition is > 0. */
@@ -120,7 +120,9 @@ export const mirrored = (s: TransitionSpec): TransitionSpec => ({
 
 /** One prop of a side: its keys in the order the side plays them (an incoming side ends at rest
  *  after them, an outgoing one starts at rest before them), and what rest is. */
-type Lane = { prop: string, kind: number, sig?: string, keys: number[][], rest: number[] }
+// A string lane (a widget's `overlayColor`): its keys are strings, its rest is CAPTURED at play —
+// the widget's own scrim color, which the transition cannot know.
+type Lane = { prop: string, kind: number, sig?: string, keys: number[][], rest: number[], strKeys?: string[] }
 type Side = { lanes: Lane[], atMs: number, durMs: number, easing: EasingSpec }
 
 const list = <T>(v: T | T[]): T[] => (Array.isArray(v) ? v : [v])
@@ -141,12 +143,16 @@ const transformLane = (value: string | string[]): Lane | null => {
 const floatLane = (prop: string, value: number | number[], rest: number): Lane =>
   ({ prop, kind: KIND_FLOAT, keys: list(value).map((v) => [v]), rest: [rest] })
 
+const stringLane = (prop: string, value: string | string[]): Lane =>
+  ({ prop, kind: KIND_STRING, keys: list(value).map(() => [0]), rest: [0], strKeys: list(value) })
+
 const sideOf = (pose: TransitionPose | undefined): Side | null => {
   if (!pose) return null
   const lanes: Lane[] = []
   if (pose.transform !== undefined) { const l = transformLane(pose.transform); if (l) lanes.push(l) }
   if (pose.opacity !== undefined) lanes.push(floatLane("opacity", pose.opacity, 1))
   if (pose.dim !== undefined) lanes.push(floatLane("dim", pose.dim, 0))
+  if (pose.overlayColor !== undefined) lanes.push(stringLane("overlayColor", pose.overlayColor))
   if (lanes.length === 0) return null
   return {
     lanes,
@@ -162,7 +168,7 @@ const sideOf = (pose: TransitionPose | undefined): Side | null => {
  *  the direction being the opposite one. No dim: nothing is over it. */
 const borrowed = (side: Side | null): Side | null => {
   if (!side) return null
-  const lanes = side.lanes.filter((l) => l.prop !== "dim").map((l) => {
+  const lanes = side.lanes.filter((l) => l.prop !== "dim" && l.strKeys === undefined).map((l) => {
     if (l.kind !== KIND_TRANSFORM) return { ...l, keys: l.keys.slice().reverse() }
     const sign: number[] = []
     for (const fn of l.sig!.split(",")) for (let i = transformLanes(fn); i > 0; i--) sign.push(fn.startsWith("translate") ? -1 : 1)
@@ -178,6 +184,12 @@ const tracksOf = (side: Side | null, role: number, incoming: boolean): Track[] =
   if (!side) return []
   const channel = { domain: DOM_UI, id: () => role + 1, value: () => null }
   return side.lanes.map((l) => {
+    if (l.strKeys !== undefined) {
+      // a string lane: the keys as strings, the rest captured at play (the node's own value)
+      const values: (string | null)[] = incoming ? [...l.strKeys, null] : [null, ...l.strKeys]
+      const keys: Keyframe[] = values.map((str, i) => ({ t: i / (values.length - 1), easing: side.easing, value: str === null ? undefined : { str } }))
+      return { target: roleTarget, prop: l.prop, channel, kind: l.kind, lanes: 1, atMs: side.atMs, durMs: side.durMs, commit: false, keys }
+    }
     // explicit keys at both ends: a captured one that fails to read would leave a screen in its pose
     const values = incoming ? [...l.keys, l.rest] : [l.rest, ...l.keys]
     const keys: Keyframe[] = values.map((lanes, i) => ({ t: i / (values.length - 1), easing: side.easing, value: { lanes } }))
@@ -186,15 +198,16 @@ const tracksOf = (side: Side | null, role: number, incoming: boolean): Track[] =
 }
 
 /** @internal The blob of a spec: `roles[i]` is the role of the blob's target `i`. Null = the spec
- *  moves nothing. */
-export const _transitionBlob = (spec: TransitionSpec): { data: Float32Array, strings: string[], roles: number[], flags: number } | null => {
+ *  moves nothing. `ownAlone`: the ALONE roles are the spec's own sides as written (a widget's pose:
+ *  it enters from `enter`, leaves to `exit`, nothing is borrowed from the other side). */
+export const _transitionBlob = (spec: TransitionSpec, ownAlone = false): { data: Float32Array, strings: string[], roles: number[], flags: number } | null => {
   const enter = sideOf(spec.enter), exit = sideOf(spec.exit)
   const enterOnTop = (spec.onTop ?? "enter") === "enter"
   const tracks = [
     ...tracksOf(enter, ROLE_ENTER, true),
     ...tracksOf(exit, ROLE_EXIT, false),
-    ...tracksOf(enterOnTop ? enter : borrowed(exit), ROLE_ENTER_ALONE, true),
-    ...tracksOf(enterOnTop ? borrowed(enter) : exit, ROLE_EXIT_ALONE, false),
+    ...tracksOf(ownAlone ? enter : enterOnTop ? enter : borrowed(exit), ROLE_ENTER_ALONE, true),
+    ...tracksOf(ownAlone ? exit : enterOnTop ? borrowed(enter) : exit, ROLE_EXIT_ALONE, false),
   ]
   if (tracks.length === 0) return null
   let durationMs = 0
@@ -242,8 +255,24 @@ export const _transitionBack = (t: Transition): number => {
   return e.back
 }
 
+/** @internal The wire id of a WIDGET's pose (docs/plans/widgets-plan.md decision 11): the pose it
+ *  enters from and leaves to, as one transition whose ALONE roles the runtime plays on the widget's
+ *  display flips. Registered once per distinct pose object; `null` = no pose (TRANSITION_NONE). */
+let poseIds = new WeakMap<TransitionPose, number>()
+export const _widgetPoseId = (pose: TransitionPose | null): number => {
+  if (!pose) return TRANSITION_NONE
+  let id = poseIds.get(pose)
+  if (id === undefined) {
+    const blob = _transitionBlob({ enter: pose, exit: pose }, true)
+    id = blob ? _creatorTree.defineTransition(blob.data, blob.strings, blob.roles, blob.flags) : TRANSITION_NONE
+    poseIds.set(pose, id)
+  }
+  return id
+}
+
 /** @internal Tests: a new fake runtime has no transition of the previous one. */
 export const _resetTransitions = (): void => {
   byName = new Map()
   bySpec = new WeakMap()
+  poseIds = new WeakMap()
 }

package/src/ui/tree.ts

@@ -45,6 +45,7 @@ export const TREE_EVENT_HOVER_ENTER = 32
 export const TREE_EVENT_HOVER_MOVE = 33
 export const TREE_EVENT_HOVER_END = 34
 export const TREE_EVENT_HOVER_CANCEL = 35
+export const TREE_EVENT_WIDGET_VISIBLE = 36
 
 // ---- setFlags(id, mask) ---------------------------------------------------------------------------
 export const TREE_FLAG_INTERACTIVE = 1 << 0
@@ -132,6 +133,8 @@ export interface TreeElement {
   _pinned?(): void
   _unpinned?(): void
   _emitBack?(): boolean
+  /** A widget: its resolved display flipped (a style write or the cascade) — `isShown` follows. */
+  _emitVisible?(shown: boolean): void
 }
 
 /** @internal A track handler (runtime/touch.ts TrackHandler), as the emitter reads it. */
@@ -285,6 +288,7 @@ const emit = (id: number, kind: number, a?: any, b?: any, c?: any, d?: any, e?:
       t?.onEnd?.({ clientX: a, clientY: b, deltaX: c, deltaY: d })
       return
     }
+    case TREE_EVENT_WIDGET_VISIBLE: pins.get(id)?._emitVisible?.(!!a); return
     case TREE_EVENT_HOVER_CANCEL: {
       const t = hoverTracker
       hoverTracker = null

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.0.8"
+export const SDK_VERSION = "2.0.9"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {