lecodes-sdk 2.0.8 → 2.0.10

package/src/ui/UILayer.ts

@@ -0,0 +1,88 @@
+// The LAYER roots widgets live in when they belong to no screen (docs/plans/widgets-plan.md):
+//
+//   · the APP layer (`UIOverlay`): above every destination, always shown — the home of what belongs
+//     to the app rather than to a place in it: a global loader, a mini-player, a toast with actions.
+//     `widget.show()` on a widget that has no parent appends it here first.
+//   · a SURFACE's content layer: a `Scene`, a `Scene2D`, a `NativeView` or a `UIVideo` cannot take
+//     children, so its widgets (a HUD, a card over a map) go in a layer of its own, shown over it
+//     while it is presented — `scene.setContent([hud])` fills it.
+//
+// A layer is a "layer" node of the tree: a pass-through root the runtime lays out at the frame and
+// the host paints after the destination; its own box is never hit, only its widgets are. The
+// runtime learns which destination a layer belongs to through `_creatorTree.setLayer`.
+import { ContainerElement, type UINodeChild, type ChildrenFn } from "./UINode"
+import type { UIWidget } from "./UIWidget"
+import type { DestTuple } from "./presentable"
+import { TREE_DEST_NONE, pin, tree } from "./tree"
+
+export type UIWidgetContent = (UIWidget | null | undefined | false)[] | (() => (UIWidget | null | undefined | false)[])
+
+/** @internal A layer root: a container whose children are widgets. */
+export class LayerElement extends ContainerElement<"layer"> {
+  constructor() {
+    super("layer", {}, [])
+  }
+}
+
+/** @internal A surface destination that can hold its content layer. */
+export interface LayerOwner {
+  _contentLayer?: LayerElement
+  _dest(): DestTuple
+}
+
+/** @internal The content layer of a surface destination, made on first use and bound to the
+ *  destination (`setLayer(kind, id, layer)`); the runtime shows it while the surface is presented. */
+export const _destLayer = (owner: LayerOwner): LayerElement => {
+  if (!owner._contentLayer) {
+    const layer = new LayerElement()
+    const [kind, id] = owner._dest()
+    tree().setLayer(kind, id, layer._h.id)
+    pin(layer)   // the runtime holds it (its owner's content) — findable by id while it does
+    owner._contentLayer = layer
+  }
+  return owner._contentLayer
+}
+
+/** @internal `setContent` of a surface: its widgets, as a list or a reactive function. */
+export const _setSurfaceContent = (owner: LayerOwner, content: UIWidgetContent): void => {
+  _destLayer(owner).setContent(content as UINodeChild[] | ChildrenFn)
+}
+
+// ---- the app layer ------------------------------------------------------------------------------------
+let appLayer: LayerElement | null = null
+
+const layer = (): LayerElement => {
+  if (!appLayer) {
+    appLayer = new LayerElement()
+    tree().setLayer(TREE_DEST_NONE, 0, appLayer._h.id)
+    pin(appLayer)
+  }
+  return appLayer
+}
+
+/** @internal Tests: a new fake runtime has no app layer of the previous one. */
+export const _resetOverlay = (): void => { appLayer = null }
+
+/**
+ * The app layer: the widgets above EVERY destination, always shown — a global loader, a mini-player
+ * that follows the user across screens, a toast with actions. Widgets that belong to a place go in
+ * that place instead: a dialog among its screen's children (`UIScreen(..., dialog)`), a HUD in
+ * `scene.setContent([hud])`. A widget shown with `show()` while it has no parent lands here.
+ *
+ * ```ts
+ * UIOverlay.append(miniPlayer)
+ * miniPlayer.hide()   // display: none — still here, ready for show()
+ * ```
+ */
+export const UIOverlay = /*#__PURE__*/ Object.freeze({
+  /** Add widgets at the end (on top). */
+  append(...widgets: (UIWidget | null | undefined | false)[]): void { layer().append(...(widgets as UINodeChild[])) },
+  /** Insert widgets at `index` (0 = the bottom of the layer). */
+  insert(index: number, ...widgets: (UIWidget | null | undefined | false)[]): void { layer().insert(index, ...(widgets as UINodeChild[])) },
+  /** Take widgets out of the layer (they stay valid; a dropped one is freed). */
+  remove(...widgets: (UIWidget | null | undefined | false)[]): void { layer().remove(...(widgets as UINodeChild[])) },
+  /** Replace the layer's widgets — a list, or a function for reactive content. */
+  setContent(content: UIWidgetContent): void { layer().setContent(content as UINodeChild[] | ChildrenFn) },
+  /** The layer's widgets, bottom to top (a snapshot read from the runtime). */
+  get children(): UIWidget[] { return appLayer ? (appLayer.children as UIWidget[]) : [] },
+})

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`