lecodes-sdk 2.2.4 → 2.2.5

package/src/ui/UILayer.ts

@@ -1,37 +1,106 @@
-// The LAYER roots widgets live in when they belong to no screen (docs/plans/widgets-plan.md):
+// The WIDGETS of a destination (docs/plans/widgets-plan.md): one face on every destination —
 //
-//   · 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.
+//   screen.widgets(dialog, sheet)      scene.widgets(hud)      map.widgets(header, card)
+//   x.widgets.append(w) / x.widgets.remove(w) / x.widgets.list
+//
+// A screen keeps its widgets in the tree as the TAIL of its children (the runtime's portal link:
+// never a yoga child, hoisted to the outermost presented root); `children` of a screen reads its
+// content only, `widgets.list` the tail. A surface — a `Scene`, a `Scene2D`, a `NativeView`, a
+// `UIVideo` — cannot take children, so its widgets live in a LAYER root of their own, bound to the
+// destination (`_creatorTree.setLayer`) and shown over it while it is presented. The APP layer is
+// the same kind of root above every destination, always shown: where a widget with no place lands
+// on `show()` (a global loader, a dialog opened from anywhere) — it has no name of its own.
 //
 // 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`.
+// the host paints after the destination; its own box is never hit, only its widgets are.
 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)[])
+/** A widget slot: a widget, or a falsy value (skipped). */
+export type UIWidgetChild = UIWidget | null | undefined | false
+/** The widgets of a destination as `widgets()` takes them: a list, or a function for reactive
+ *  content (re-run when a signal read inside it changes, reconciled against the shown ones). */
+export type UIWidgetContent = UIWidgetChild[] | (() => UIWidgetChild[])
+
+/**
+ * The widgets of a destination — a dialog, a sheet, a HUD: what floats over it, laid out and
+ * painted in its box above everything else. Call it to set them (`screen.widgets(dialog)`, same
+ * argument forms as `UIColumn`: widgets, arrays of them, or ONE function for reactive content);
+ * `append` / `remove` manage them one at a time; `list` reads them. A widget shows with its
+ * destination unless its style says `display: "none"`; `show()` / `hide()` flip that, and
+ * `show()` puts it on top of the others.
+ *
+ * ```ts
+ * const home = UIScreen(content).widgets(dialog, sheet)
+ * scene.widgets(hud)
+ * scene.widgets(() => [hud, paused() && pauseMenu])
+ * home.widgets.append(toast); home.widgets.remove(toast)
+ * home.widgets.list   // [dialog, sheet] — never in `children`
+ * ```
+ */
+export interface WidgetSet<Owner> {
+  (...widgets: (UIWidgetChild | UIWidgetChild[])[]): Owner
+  (widgets: UIWidgetContent): Owner
+  /** Add widgets at the end (on top). */
+  append(...widgets: UIWidgetChild[]): void
+  /** Take widgets out (they stay valid while you hold them; a dropped one is freed). */
+  remove(...widgets: UIWidgetChild[]): void
+  /** The widgets, bottom to top — a snapshot read from the runtime. */
+  readonly list: UIWidget[]
+}
+
+/** @internal What a widget set drives: a screen (its widget tail) or a surface's layer. */
+export interface WidgetHost {
+  _setWidgets(content: UIWidgetContent): void
+  _appendWidgets(widgets: UINodeChild[]): void
+  _removeWidgets(widgets: UINodeChild[]): void
+  _widgetList(): UIWidget[]
+}
+
+/** @internal `widgets(...)`'s arguments as content: one function → reactive, one array → the
+ *  list, otherwise the rest arguments with arrays among them flattened (as the UI factories). */
+export const _widgetContent = (args: any[]): UIWidgetContent => {
+  if (args.length === 1 && (typeof args[0] === "function" || Array.isArray(args[0]))) return args[0]
+  const flat: UIWidgetChild[] = []
+  for (const a of args) {
+    if (Array.isArray(a)) for (const w of a) flat.push(w)
+    else flat.push(a)
+  }
+  return flat
+}
+
+/** @internal The widget set of `owner` over `host()` (resolved at every call: a surface's layer
+ *  is made on first use). */
+export const _makeWidgetSet = <O>(owner: O, host: () => WidgetHost): WidgetSet<O> => {
+  const set = ((...args: any[]) => { host()._setWidgets(_widgetContent(args)); return owner }) as WidgetSet<O>
+  set.append = (...widgets) => { host()._appendWidgets(widgets as UINodeChild[]) }
+  set.remove = (...widgets) => { host()._removeWidgets(widgets as UINodeChild[]) }
+  Object.defineProperty(set, "list", { get: () => host()._widgetList() })
+  return set
+}
 
 /** @internal A layer root: a container whose children are widgets. */
-export class LayerElement extends ContainerElement<"layer"> {
+export class LayerElement extends ContainerElement<"layer"> implements WidgetHost {
   constructor() {
     super("layer", {}, [])
   }
+  _setWidgets(content: UIWidgetContent): void { this.setContent(content as UINodeChild[] | ChildrenFn) }
+  _appendWidgets(widgets: UINodeChild[]): void { this.append(...widgets) }
+  _removeWidgets(widgets: UINodeChild[]): void { this.remove(...widgets) }
+  _widgetList(): UIWidget[] { return this.children as UIWidget[] }
 }
 
-/** @internal A surface destination that can hold its content layer. */
+/** @internal A surface destination that holds its widgets in a layer of its own. */
 export interface LayerOwner {
   _contentLayer?: LayerElement
+  _widgetSet?: WidgetSet<any>
   _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. */
+/** @internal The 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()
@@ -43,15 +112,18 @@ export const _destLayer = (owner: LayerOwner): LayerElement => {
   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)
+/** @internal The `widgets` of a surface: one set per owner, over its layer. */
+export const _surfaceWidgets = <O extends LayerOwner>(owner: O): WidgetSet<O> => {
+  if (!owner._widgetSet) owner._widgetSet = _makeWidgetSet(owner, () => _destLayer(owner))
+  return owner._widgetSet as WidgetSet<O>
 }
 
 // ---- the app layer ------------------------------------------------------------------------------------
 let appLayer: LayerElement | null = null
 
-const layer = (): LayerElement => {
+/** @internal The app layer, made on first use: above every destination, always shown — where a
+ *  widget with no parent lands on `show()` (UIWidget), where a popover with no anchor goes. */
+export const _appLayer = (): LayerElement => {
   if (!appLayer) {
     appLayer = new LayerElement()
     tree().setLayer(TREE_DEST_NONE, 0, appLayer._h.id)
@@ -62,27 +134,3 @@ const layer = (): LayerElement => {
 
 /** @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/UINode.ts

@@ -798,11 +798,11 @@ export function buildUI<R>(args: any[], defaults: any, make: (style: any, childr
 const acceptChild = (parent: { type: string }, node: any): boolean => {
   if (!node) return false
   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.`)
+    // A widget is never a CHILD (docs/plans/widgets-plan.md decision 9): it is one of the
+    // `widgets` of a screen or a surface — a layer's children are widgets, and only a widget set
+    // puts one there (acceptWidget). This says what to write instead.
+    if (node.type === "widget" && parent.type !== "layer") {
+      throw new Error(`${parent.type}: a widget (UIWidget / UIModal / UIBottomSheet / UIPopover) is not a child. It belongs to the widgets of a screen or a surface: UIScreen(content).widgets(dialog), scene.widgets(hud). A floating element of a box is an absolute child: UIBox(...).style({ position: "absolute", ... }), not a widget.`)
     }
     return true
   }
@@ -817,6 +817,16 @@ const acceptChild = (parent: { type: string }, node: any): boolean => {
   return false
 }
 
+/** A widget slot of `widgets(...)` takes a widget (falsy = conditional, skipped silently);
+ *  anything else is reported and skipped. */
+export const acceptWidget = (owner: { type: string }, node: any): boolean => {
+  if (!node) return false
+  if (node instanceof Element && node.type === "widget") return true
+  const what = node instanceof Element ? `a ${node.type}` : typeof node === "object" ? (node.constructor?.name || "object") : typeof node
+  console.error(`${owner.type}.widgets: not a widget (${what}) — skipped. widgets() takes UIWidget / UIModal / UIBottomSheet / UIPopover; content goes among the children`)
+  return false
+}
+
 export class ContainerElement<T extends string> extends Element<T> {
   constructor(type: T, style: any, children: any[] | ChildrenFn) {
     super(type, style)
@@ -855,13 +865,19 @@ export class ContainerElement<T extends string> extends Element<T> {
   _reconcile(next: UINodeChild[]) {
     const target: any[] = []
     for (const c of next) if (acceptChild(this, c)) target.push(c)
-    if (this._h.id === 0) return
+    this._reconcileList(target, () => this.children, (i, node) => this._insertAt(i, node))
+  }
 
-    const current: any[] = this.children
+  /** @internal The diff of `_reconcile` over any list of this node's children: `current` reads
+   *  the mounted ones (a screen's content, or its widget tail), `insertAt` mounts one at an index
+   *  of that list. */
+  _reconcileList(target: any[], current: () => any[], insertAt: (index: number, node: any) => void) {
+    if (this._h.id === 0) return
+    const mounted: any[] = current()
     const targetSet = new Set(target)
-    const departed = current.filter(c => !targetSet.has(c))
+    const departed = mounted.filter(c => !targetSet.has(c))
     if (departed.length > 0) this.remove(...departed)
-    const cur: any[] = departed.length > 0 ? this.children : current
+    const cur: any[] = departed.length > 0 ? current() : mounted
 
     // `cur` mirrors the mounted order; walk the target and fix mismatches in place
     for (let i = 0; i < target.length; i++) {
@@ -872,12 +888,15 @@ export class ContainerElement<T extends string> extends Element<T> {
         this.remove(node)   // moved forward — remount at its new position
         cur.splice(j, 1)
       }
-      this._insertAt(i, node)
+      insertAt(i, node)
       cur.splice(i, 0, node)
     }
   }
 
-  private _insertAt(index: number, node: any): void {
+  /** @internal Mount `node` at `index` of the runtime's child list (a screen: its content, then
+   *  its widgets — tree.cpp treeInsert clamps a content index into the content, a widget's into
+   *  the tail). */
+  _insertAt(index: number, node: any): void {
     if (this._h.id === 0 || !node || node._h.id === 0) return
     tree().insert(this._h.id, node._h.id, index)
     pin(node)

package/src/ui/UIPopover.ts

@@ -58,7 +58,7 @@ export class PopoverElement extends ModalElement {
       }
       // 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)
+      if (root && this.parent !== root) root._appendWidgets([this])
     } else {
       this._anchorRect = undefined   // unanchored show: the user's own style owns the position
     }
@@ -92,13 +92,13 @@ 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 anchorRoot = (anchor: UIPopoverAnchor): { _appendWidgets(nodes: any[]): void, 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
+  return el && typeof el._appendWidgets === "function" && (el.type === "screen" || el.type === "layer") ? el : null
 }
 
 const makePopover = (style: any, children: any) => new PopoverElement(style, children)

package/src/ui/UIScreen.ts

@@ -1,7 +1,10 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "./presentable"
 import { _transitionId, TRANSITION_NONE } from "./transitions"
-import { ContainerElement, buildUI, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { createBinding, disposeBinding } from "../core/signals"
+import { ContainerElement, acceptWidget, buildUI, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { _makeWidgetSet, type UIWidgetContent, type WidgetHost, type WidgetSet } from "./UILayer"
+import type { UIWidget } from "./UIWidget"
 import { TREE_DEST_SCREEN, TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_KEEP_ALIVE, pin, tree } from "./tree"
 import { autofocusIn } from "./autofocus"
 
@@ -57,16 +60,61 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
 
   /** Touch began on the screen; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
+
+  /** The screen's widgets — a dialog, a sheet, a toast: `UIScreen(content).widgets(dialog)` sets
+   *  them, `widgets.append` / `.remove` manage them, `widgets.list` reads them. Never among
+   *  `children`: that is the content. A widget is laid out and painted over the whole screen (on a
+   *  pager page: over the pager too) and shows with it unless its style says `display: "none"`. */
+  readonly widgets: WidgetSet<this>,
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
 
-export class ScreenElement extends ContainerElement<"screen"> {
+export class ScreenElement extends ContainerElement<"screen"> implements WidgetHost {
   // The per-type default: a screen's background is the theme's `bg` (no theme = none, the host's).
   constructor(type: "screen", style: any, children: any) {
     super(type, { bgColor: "var(--bg)", ...style }, children)
   }
 
+  // ---- content vs widgets: ONE list in the runtime (the content, then the widget tail), two faces here
+  /** The content — the children read from the runtime without the widget tail. */
+  override get children(): any[] {
+    return super.children.filter((c: any) => c.type !== "widget")
+  }
+  private _widgetSet?: WidgetSet<this>
+  get widgets(): WidgetSet<this> {
+    if (!this._widgetSet) this._widgetSet = _makeWidgetSet(this, () => this)
+    return this._widgetSet
+  }
+  /** @internal */
+  _widgetList(): UIWidget[] {
+    return super.children.filter((c: any) => c.type === "widget") as UIWidget[]
+  }
+  /** @internal The widget tail; an index past every child lands at its end (tree.cpp). */
+  _appendWidgets(widgets: UINodeChild[]): void {
+    if (this._h.id === 0) return
+    for (const w of widgets) if (acceptWidget(this, w)) this._insertAt(tree().children(this._h.id).length, w)
+  }
+  /** @internal */
+  _removeWidgets(widgets: UINodeChild[]): void { this.remove(...widgets) }
+  /** @internal `widgets(...)`: the list replaced, or a reactive function bound as the content's is. */
+  _setWidgets(content: UIWidgetContent): void {
+    if (typeof content === "function") {
+      createBinding(this, "#widgets", () => {
+        const next = content()
+        const target: any[] = []
+        for (const w of (Array.isArray(next) ? next : [])) if (acceptWidget(this, w)) target.push(w)
+        // a widget's index is counted from the first widget: offset by the content (treeInsert)
+        this._reconcileList(target, () => this._widgetList(), (i, node) => this._insertAt(this.children.length + i, node))
+      })
+      return
+    }
+    disposeBinding(this, "#widgets")
+    const current = this._widgetList()
+    if (current.length > 0) this.remove(...current)
+    this._appendWidgets(content)
+  }
+
   /** @internal */
   _dest(): DestTuple { return [TREE_DEST_SCREEN, this._h.id, "", ""] }
 

package/src/ui/UIVideo.ts

@@ -1,5 +1,5 @@
 import type { VideoPlayer } from "../runtime/media"
-import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "./UILayer"
+import { _surfaceWidgets, type LayerElement, type WidgetSet } 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"
@@ -25,8 +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
+  /** The widgets over the video when it is presented (`Presentable.widgets`): `video.widgets(controls)`. */
+  readonly widgets: WidgetSet<this>
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
@@ -50,13 +50,15 @@ 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. */
+  /** @internal The video's widget layer (ui/UILayer.ts), made on the first use of `widgets`. */
   _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
+  /** @internal */
+  _widgetSet?: WidgetSet<any>
+  /** The widgets over the video while it is presented — a HUD, a dialog, a sheet: `video.widgets(hud)`
+   *  sets them, `widgets.append` / `.remove` manage them, `widgets.list` reads them. Laid out
+   *  over it; touches outside a widget's box reach the video. */
+  get widgets(): WidgetSet<this> {
+    return _surfaceWidgets(this)
   }
 
   open(options?: PresentOptions): void {

package/src/ui/UIWidget.ts

@@ -1,7 +1,8 @@
 import { TouchStartEvent } from "../runtime/touch"
 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 { UIOverlay } from "./UILayer"
-import { TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, tree } from "./tree"
+import { _appLayer } from "./UILayer"
+import type { Presentable } from "./presentable"
+import { TREE_FLAG_BACK, TREE_FLAG_INTERACTIVE, TREE_FLAG_OVERLAY_TAP, tree, unpin } from "./tree"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
@@ -14,13 +15,13 @@ export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
 }
 
 
-/** 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.
+/** A floating overlay that belongs to a DESTINATION, not to a box (docs/plans/widgets-plan.md): a
+ *  dialog, a sheet, a HUD, a mini-player. A widget is one of the `widgets` of the place it belongs
+ *  to — `UIScreen(content).widgets(dialog)`, `scene.widgets(hud)` — 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 among the children of a 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` /
@@ -28,13 +29,12 @@ export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
 export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle & BaseStyle & { overlayColor?: Color | null }> {
   readonly type: "widget",
 
-  /** 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 the widget: `display: "flex"`, on top of its root — it moves to the end of its
+   *  destination's widgets, so a dialog opened later covers an earlier one and a HUD declared after
+   *  it. A widget that belongs nowhere goes ABOVE EVERY destination — a global loader, a dialog
+   *  opened from anywhere — and stays there, hidden by `hide()`, until it is given a place. */
   show(): void,
-  /** Hide the widget: `display: "none"`. It stays where it is (its place, the app layer), ready
-   *  for the next `show()`. */
+  /** Hide the widget: `display: "none"`. It stays where it is, ready for the next `show()`. */
   hide(): void,
 
   /** Shown right now by its own display (`show()` ran, `hide()` hasn't, no state block hides
@@ -42,6 +42,14 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
    *  visibility, not the widget's. */
   readonly isShown: boolean,
 
+  /** @deprecated A widget is one of the `widgets` of the place it belongs to (2026-10-07): write
+   *  `UIScreen(content).widgets(widget)` / `scene.widgets(widget)` instead. This alias is
+   *  `owner.widgets.append(widget)` with the widget hidden, so the `show()` that follows flips it as
+   *  on any placed widget; `attachTo(null)` takes it out, and the next `show()` puts it above every
+   *  destination. For the projects compiled before the change; removed with the release that
+   *  recompiles them. */
+  attachTo(owner: Presentable | null): this,
+
   /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
   onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this,
   /** Tap on the overlay layer (requires an `overlayColor`). */
@@ -74,7 +82,7 @@ export class WidgetElement extends ContainerElement<"widget"> {
       // 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
+      _appLayer().append(this as any)   // pins it: _pinned reads the display
     } else {
       // 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
@@ -97,6 +105,21 @@ export class WidgetElement extends ContainerElement<"widget"> {
   get isShown(): boolean {
     return this._shown
   }
+  /** @deprecated see the interface */
+  attachTo(owner: Presentable | null): this {
+    if (this._h.id === 0) return this
+    const parentId = tree().parent(this._h.id)
+    if (parentId !== 0) {                                      // one parent: a re-attach moves it
+      tree().remove(parentId, this._h.id)
+      unpin(this._h.id)                                        // as a node's remove(): shown nowhere
+    }
+    if (owner) {
+      // Hidden first: a widget shows with its place, and the old contract showed it on show() only.
+      this.style({ display: "none" } as any)
+      owner.widgets.append(this as any)
+    }
+    return this
+  }
   /** @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 {
@@ -163,8 +186,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`). Put it where it belongs — among a screen's
- *  children, in `scene.setContent([...])`, or `UIOverlay` — position it with absolute-style props
+/** Create a widget (same argument forms as `UIColumn`). Give it to the destination it belongs to —
+ *  `UIScreen(content).widgets(w)`, `scene.widgets(w)` — 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
-// `scene.setContent([hud])` — a widget is the destination's content (docs/plans/widgets-plan.md).
+// `scene.widgets(hud)` — a widget belongs to a destination (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,7 +12,7 @@
 // element code into engine-only bundles.
 
 import type { EasingInput } from "../animate/tween/easing"
-import type { UIWidget } from "./UIWidget"
+import type { WidgetSet } from "./UILayer"
 
 /** 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;
@@ -101,12 +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
+  /** The destination's widgets (docs/plans/widgets-plan.md): a dialog, a HUD, a sheet — what floats
+   *  over it. `x.widgets(a, b)` sets them, `x.widgets.append` / `.remove` manage them, `x.widgets.list`
+   *  reads them; the same on a `UIScreen` (apart from its `children`), a `Scene`, a `Scene2D`, a
+   *  `NativeView`, a `UIVideo`. A widget shows with its destination unless its style says
+   *  `display: "none"`; `show()` / `hide()` flip that. */
+  readonly widgets: WidgetSet<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/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.2.4"
+export const SDK_VERSION = "2.2.5"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {

package/tests/helpers/fakeTree.ts

@@ -87,7 +87,12 @@ export class FakeTree {
     if (!p || !c) return
     if (c.parent !== 0) return
     c.parent = parent
-    const i = Math.max(0, Math.min(index, p.children.length))
+    // tree.cpp treeInsert: a widget is the TAIL of a screen's children (its index counted past the
+    // content, clamped into the tail); a content index past the content lands before the widgets.
+    const own = p.type === "layer" ? 0 : p.children.filter((x) => this.nodes.get(x)?.type !== "widget").length
+    const i = c.type === "widget"
+      ? own + Math.max(0, Math.min(index < own ? 0 : index - own, p.children.length - own))
+      : Math.max(0, Math.min(index, own))
     p.children.splice(i, 0, child)
   }
   remove = (parent: number, child: number): void => {