lecodes-sdk 2.0.7 → 2.0.9

package/src/server/runtime.ts

@@ -14,6 +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 { isChannel, isChannelGroup, setChannelPublisher, type ChannelRecord } from "./channel"
 import { setRequestProvider, type RequestContext } from "./context"
 import type { Db } from "./db/types"
@@ -69,6 +70,9 @@ export type InvokerOptions = {
   onError?: (id: string, error: unknown) => void
   /** The auth host (./auth/host.ts): resolves the bearer token into `ctx.auth` before each call. Absent = no sessions. */
   auth?: AuthHost | null
+  /** The files host (./files/host.ts): the uploads of a call become `File` arguments, and what the call
+   *  left unused — or deleted — is cleaned up after it. Absent = a call with files is refused. */
+  files?: FilesHost | null
 }
 
 // The bundle's ApiError is a different class object than ours (its own SDK copy) — duck-type it.
@@ -96,6 +100,7 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
   const onError = opts.onError ?? ((id, e) => console.error(`[server] ${id}:`, e))
   const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
   const auth = opts.auth ?? null
+  const files = opts.files ?? null
 
   return async (id: string, args: unknown[], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
     const fn = server.endpoints.get(id)
@@ -103,6 +108,9 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
     if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
     const rc: RequestContext = { ...ctx, id }
     try {
+      // an upload is an argument like any other once it is adopted: validated, then passed
+      if (files) args = await files.adopt(args, rc)
+      else if (rc.uploads?.length) return { ok: false, status: 400, message: "this server takes no files" }
       if (validate && params?.[id]) validateArgs(params[id], args)
       if (auth) await auth.resolve(rc)
       const result = await als.run(rc, () => fn(...args))
@@ -113,6 +121,39 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
       if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
       onError(id, e)
       return withSession({ ok: false, status: 500, message: "Internal error" }, rc)
+    } finally {
+      // in the request's scope: the urls of what the call returned are already made, this is the cleanup
+      if (files) await als.run(rc, () => files.finish(rc))
+    }
+  }
+}
+
+/**
+ * A file field of one row written from OUTSIDE the project's code — a data browser's form. It goes
+ * the way an endpoint's write does, through the bundle's own db: `args` are `[model, id, key, value]`,
+ * the value what an endpoint would write to the field — an upload of this call (`{ "$file": i }`), a
+ * file the row already has (`{ url }`, kept), a list of them, or null. So the field's rule (`t.image()`),
+ * the quota and the removal of what is no longer listed are the same.
+ */
+export const createFileWriter = (server: LoadedServer, opts: { files?: FilesHost | null } = {}) => {
+  installProvider()
+  const files = opts.files ?? null
+  return async (args: unknown[], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
+    const refuse = (message: string): InvokeResult => ({ ok: false, status: 400, message })
+    if (!files?.enabled) return refuse("this project stores no files — a model needs a t.file() field")
+    const rc: RequestContext = { ...ctx, id: "$file" }
+    try {
+      const [model, id, key, value] = await files.adopt(args, rc)
+      const db = server.dbs.find(d => d.$files.some(f => f.model === model && f.key === key))
+      if (!db) return refuse(`${model}.${key} is not a file field`)
+      const name = model as string
+      await als.run(rc, () => (db as any)[name.charAt(0).toLowerCase() + name.slice(1)].update(id, { [key as string]: value }))
+      return { ok: true, result: null }
+    } catch (e) {
+      // whoever asks is the project's developer: the reason as it is
+      return { ok: false, status: apiStatus(e) ?? 500, message: (e as Error)?.message ?? String(e) }
+    } finally {
+      await als.run(rc, () => files.finish(rc))
     }
   }
 }

package/src/server/validate.ts

@@ -12,6 +12,8 @@ export type Schema =
   | { t: "tuple", items: Schema[], rest?: Schema }
   | { t: "object", props: Record<string, Schema>, optional?: string[], index?: Schema }
   | { t: "union", of: Schema[] }
+  /** A `File` parameter: an upload of this very call (./files/host.ts) — nothing the app can spell in JSON. */
+  | { t: "file" }
 
 /** One endpoint parameter: its schema and whether it may be omitted (`?`, default value, rest). */
 export type ParamSchema = { name: string, schema: Schema, optional?: boolean, rest?: boolean }
@@ -61,6 +63,9 @@ export const check = (schema: Schema, value: unknown, path: string): string | nu
       }
       return null
     }
+    case "file":
+      return (globalThis as { __lecodesFiles?: { uploaded(v: unknown): string | undefined } }).__lecodesFiles?.uploaded(value)
+        ? null : `${path}: expected a file, got ${typeName(value)}`
     case "union": {
       const errors: string[] = []
       for (const s of schema.of) { const e = check(s, value, path); if (!e) return null; errors.push(e) }

package/src/ui/NativeView.ts

@@ -10,6 +10,7 @@
 // wrapper convention.
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
+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"
@@ -45,6 +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
   /** @internal The destination tuple (Presentable). */
   _dest(): DestTuple
 }
@@ -85,6 +88,14 @@ 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. */
+  _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
+  }
 
   open(options?: PresentOptions): void {
     if (!tree().isViewSupported(this.viewName)) {

package/src/ui/UI.ts

@@ -10,6 +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 { UIModal, type UIModalStyle } from './UIModal'
 export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet'
 export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover'

package/src/ui/UIBottomSheet.ts

@@ -67,6 +67,7 @@ export class BottomSheetElement extends ModalElement {
     // The inherited show/hide pose animates ONLY the scrim: sheet geometry rides the
     // sheetDetent style key, never the pose system.
     this._transition = { duration: SHEET_ANIM_MS }
+    this._syncPose()
     this._addFlags(TREE_FLAG_DETENT)
   }
 
@@ -97,7 +98,7 @@ export class BottomSheetElement extends ModalElement {
   setDetent(index: number): void {
     const clamped = Math.max(0, Math.min(Math.floor(index), this._detents.length - 1))
     this._detent = clamped
-    if (!this._open) return                     // applied by the next show()
+    if (!this._shown) return                    // applied by the next show()
     this.style({ sheetDetent: clamped } as UIBottomSheetStyle)
     for (const callback of this._detentListeners) callback(clamped)
   }
@@ -107,20 +108,20 @@ export class BottomSheetElement extends ModalElement {
     return this
   }
 
-  show(): void {
-    if (this._open) return
+  override show(): void {
+    if (this._shown) return
     // Before the mount, so the built node carries the target and hosts play the entrance to it.
     this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
     super.show()
   }
 
-  hide(): void {
-    if (!this._open) return
-    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; unmount follows
+  override hide(): void {
+    if (!this._shown) return
+    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; the hide follows
     super.hide()
   }
 
-  dismissible(enabled: boolean): this {
+  override dismissible(enabled: boolean): this {
     super.dismissible(enabled)
     this.style({ sheetDismissible: enabled ? 1 : 0 } as UIBottomSheetStyle)
     return this

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