lecodes-sdk 2.2.3 → 2.2.5

package/src/server/runtime.ts

@@ -14,7 +14,7 @@ import { AsyncLocalStorage } from "node:async_hooks"
 import type { ServerManifest } from "../compile/serverSplit"
 import type { AuthHost } from "./auth/host"
 import type { AuthState } from "./auth/types"
-import type { FilesHost } from "./files/host"
+import type { FilesHost, ResourceReader } from "./files/host"
 import { isChannel, isChannelGroup, setChannelPublisher, type ChannelRecord } from "./channel"
 import { setRequestProvider, type RequestContext } from "./context"
 import type { Db } from "./db/types"
@@ -55,7 +55,7 @@ export const loadServerModules = (
   // One database per project: the host syncs one schema, so the models of a second `defineDb` would not exist.
   if (out.dbs.length > 1) {
     // named by their collections (own enumerable keys): reading `$models` would seal a db that is being refused
-    const each = out.dbs.map(db => Object.keys(db).filter(k => k !== "auth" && !k.startsWith("$") && k !== "withAuth").map(k => `db.${k}`).join(", ")).join(" | ")
+    const each = out.dbs.map(db => Object.keys(db).filter(k => k !== "auth" && !k.startsWith("$") && k !== "withAuth" && k !== "seed").map(k => `db.${k}`).join(", ")).join(" | ")
     throw new Error(`a project has one database, and defineDb is called ${out.dbs.length} times (${each}) — put every model in one defineDb({...}) and import that db where it is needed`)
   }
   return out
@@ -83,6 +83,19 @@ const apiStatus = (e: unknown): number | null =>
   e && typeof e === "object" && (e as { name?: string }).name === "ApiError" && typeof (e as { status?: unknown }).status === "number"
     ? (e as { status: number }).status : null
 
+/** What the app is told when the database refused a write a person could have caused: the engine's own
+ *  words — `Like.user, Like.post: the value is already taken (by the row with id 7)` — with the status
+ *  its kind means. A taken unique value, a pointer at no row, a delete other rows forbid: 409; a row that
+ *  is gone: 404. Anything else the database says (a bad payload, a fault) stays a 500: a mistake of the
+ *  code, not of the person. Both transports' errors carry `kind` (marcidb-embedded's, the HTTP one's). */
+const DB_ERROR_STATUS: Record<string, number> = { unique: 409, foreign_key: 409, restrict: 409, duplicate_id: 409, not_found: 404 }
+const dbStatus = (e: unknown): number | null => {
+  if (!e || typeof e !== "object") return null
+  const { name, kind } = e as { name?: unknown, kind?: unknown }
+  if ((name !== "MarciEmbeddedError" && name !== "MarciHttpError") || typeof kind !== "string") return null
+  return DB_ERROR_STATUS[kind] ?? null
+}
+
 /**
  * Build the invoker: `invoke(id, args, ctx)` runs endpoint `id` inside an AsyncLocalStorage-scoped
  * request context (what the `request` global and `db.auth` read) and returns the wire envelope.
@@ -119,7 +132,7 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
       const result = await als.run(rc, () => fn(...args))
       return withSession({ ok: true, result: result === undefined ? null : result }, rc)
     } catch (e) {
-      const status = apiStatus(e)
+      const status = apiStatus(e) ?? dbStatus(e)
       if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
       if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
       onError(id, e)
@@ -161,6 +174,54 @@ export const createFileWriter = (server: LoadedServer, opts: { files?: FilesHost
   }
 }
 
+/** What stops a seed — the project's own doing, in words the project's author can act on. */
+export class SeedError extends Error {
+  constructor(message: string) { super(message); this.name = "SeedError" }
+}
+
+export type SeedOutcome =
+  /** the definition has no seed */
+  | { status: "none" }
+  /** the database has rows already: the seed did not run */
+  | { status: "skipped" }
+  /** the seed ran: the rows of every table of the project */
+  | { status: "seeded", rows: Record<string, number> }
+
+/**
+ * The first rows of the project's database: `defineDb(...).seed(fn)` run ONCE, after the host has
+ * brought an EMPTY database to the bundle's schema — a check's, a dev backend's, a deploy's first.
+ * A database with any row of the project's own tables is left as it is (the seed is the start, not a
+ * migration). Inside the seed a file field takes a resource of the project by its path (what a path
+ * literal of a shared module is in the server bundle), read through `read` and stored as an upload
+ * would be. Throws a `SeedError` with the seed's own words when it fails — the host reports it, and the
+ * database is whatever the seed wrote before (the host that wants an all-or-nothing start starts over).
+ */
+export const runSeed = async (server: LoadedServer, opts: { files?: FilesHost | null, read?: ResourceReader } = {}): Promise<SeedOutcome> => {
+  installProvider()
+  const db = server.dbs[0]
+  const fn = db?.$seed
+  if (!db || !fn) return { status: "none" }
+  const names = Object.keys(db.$given)
+  const collection = (name: string) => (db as any)[name.charAt(0).toLowerCase() + name.slice(1)]
+  for (const name of names) if ((await collection(name).count()) > 0) return { status: "skipped" }
+  const rc: RequestContext = { id: "$seed", headers: {} }
+  const files = opts.files ?? null
+  const read: ResourceReader = opts.read ?? (async () => null)
+  const done = files?.enabled ? files.seeding(rc, read) : () => {}
+  try {
+    await als.run(rc, () => fn(db as any))
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e)
+    throw new SeedError(`seed: ${message}`)
+  } finally {
+    done()
+    if (files?.enabled) await als.run(rc, () => files.finish(rc))
+  }
+  const rows: Record<string, number> = {}
+  for (const name of names) rows[name] = await collection(name).count()
+  return { status: "seeded", rows }
+}
+
 /**
  * A subscription to a channel: run its hooks (`authorize`, then `groupBy`) in the subscriber's
  * request scope. The envelope's `result` is the group the subscriber is in — `null` for a channel
@@ -187,7 +248,7 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
       if (group !== null && !isChannelGroup(group)) throw new Error(`groupBy answered ${group === undefined ? "nothing" : typeof group} — a group is a string or a number`)
       return withSession({ ok: true, result: group }, rc)
     } catch (e) {
-      const status = apiStatus(e)
+      const status = apiStatus(e) ?? dbStatus(e)
       if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
       if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
       onError(channelId, e)

package/src/ui/NativeView.ts

@@ -10,7 +10,7 @@
 // wrapper convention.
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
-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"
@@ -46,8 +46,8 @@ export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableSty
   /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
   on(event: string, callback: (data?: any) => void): this
   off(event: string, callback: (data?: any) => void): this
-  /** The UI over the view when presented: widgets over it (`Presentable.setContent`). */
-  setContent(content: UIWidgetContent): this
+  /** The widgets over the view when it is presented (`Presentable.widgets`): `map.widgets(header, card)`. */
+  readonly widgets: WidgetSet<this>
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
@@ -88,13 +88,15 @@ export class NativeViewElement extends Element<"native"> implements Presentable
 
   /** @internal */
   _dest(): DestTuple { return [TREE_DEST_NATIVE, this._viewId, this.viewName, this._paramsJson] }
-  /** @internal The view's content layer (ui/UILayer.ts), made by the first setContent. */
+  /** @internal The view's widget layer (ui/UILayer.ts), made on the first use of `widgets`. */
   _contentLayer?: LayerElement
-  /** The UI over the view when it is presented full screen — widgets (a header, a card, a sheet
-   *  over a map), laid out over it; touches outside a widget's box reach the view. */
-  setContent(content: UIWidgetContent): this {
-    _setSurfaceContent(this, content)
-    return this
+  /** @internal */
+  _widgetSet?: WidgetSet<any>
+  /** The widgets over the view while it is presented — a HUD, a dialog, a sheet: `map.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 view. */
+  get widgets(): WidgetSet<this> {
+    return _surfaceWidgets(this)
   }
 
   open(options?: PresentOptions): void {

package/src/ui/UI.ts

@@ -10,7 +10,7 @@ export { UIVideo, type UIVideoStyle } from './UIVideo'
 export { UIInput, UITextArea, type UIInputStyle } from './UIInput'
 
 export { UIWidget, type UIWidgetStyle } from './UIWidget'
-export { UIOverlay, type UIWidgetContent } from './UILayer'
+export { type WidgetSet, type UIWidgetContent, type UIWidgetChild } from './UILayer'
 export { UIModal, type UIModalStyle } from './UIModal'
 export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet'
 export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover'

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

@@ -41,6 +41,9 @@ export type Color = ColorInput | null
 /** Style props every element accepts. */
 export type BaseStyle = {
   opacity?: number | `${number}`,
+  /** A CSS-style list of `translate` / `scale` / `rotate`. A `%` in a translate is a percent of the
+   *  element's own box (`translate(-50%, -50%)` centres it on its corner), kept as a percent: it
+   *  follows the box through every layout. */
   transform?: string | null,
   /** Pivot of `transform` (CSS `transform-origin` subset): one or two values, each a keyword
    *  (`left`/`center`/`right`, `top`/`center`/`bottom`), a percentage of the box, or a px length
@@ -795,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
   }
@@ -814,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)
@@ -852,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++) {
@@ -869,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 {