lecodes-sdk 2.0.8 → 2.0.9

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.14.1",
     "sharp": "^0.35.2"
   },
-  "version": "2.0.8",
+  "version": "2.0.9",
   "files": [
     "src",
     "dist",

package/prompts/3d-scene-files.md

@@ -66,10 +66,10 @@ export class Spinner extends Aspect<'spinner'> {
 // ===== UI OVER AN OPEN SCENE =====
 
 // Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+// a UIWidget that is the scene's CONTENT — it shows and hides together with it:
 const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
     .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
+scene.setContent([hud])
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -107,7 +107,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/prompts/3d-scene.md

@@ -114,6 +114,6 @@ const hud = UIWidget(
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
 ).style({ top: 'max(safe-top, 16px)', right: 16 })
 
+scene.setContent([hud])
 scene.open()
-hud.attachTo(scene).show()
 </file>

package/prompts/dist/3d-app.md

@@ -775,8 +775,8 @@ const hud = UIWidget(
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
 ).style({ top: 'max(safe-top, 16px)', right: 16 })
 
+scene.setContent([hud])
 scene.open()
-hud.attachTo(scene).show()
 </file>
 
 ## Scene files (.scene.ts)
@@ -847,10 +847,10 @@ export class Spinner extends Aspect<'spinner'> {
 // ===== UI OVER AN OPEN SCENE =====
 
 // Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+// a UIWidget that is the scene's CONTENT — it shows and hides together with it:
 const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
     .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
+scene.setContent([hud])
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -888,7 +888,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/src/bridges/gl.d.ts

@@ -95,6 +95,11 @@ declare global {
     /** Punctual light. `intensity` is luminous POWER in lumens; `falloff` is the metres of
      *  influence (filament's own default is 1 m, i.e. invisible, so it is always passed). */
     createPointLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, castShadows: boolean): void
+    /** Spot light: the point light's lumens and falloff in a cone along the entity's local -Z. `inner` / `outer` are
+     *  HALF-angles in radians (outer ≤ π/2); the cone does not change the brightness. Real time only (the bake skips it). */
+    createSpotLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, inner: f32, outer: f32, castShadows: boolean): void
+    /** A spot light's cone, live — half-angles in radians, as createSpotLight. */
+    setLightCone?(entityId: u32, inner: f32, outer: f32): void
     /** The lightmap bake takes this point light as a RECTANGLE of `width` x `height` metres (an area light: a ceiling
      *  panel) in the light's local XZ plane, emitting along its local -Y with the same lumens; 0, 0 = a point again. */
     setLightBakeArea?(entityId: u32, width: f32, height: f32): void

package/src/bridges/tree.d.ts

@@ -112,10 +112,20 @@ declare global {
     isViewSupported(name: string): boolean
     viewVersion(name: string): i32
     viewCall(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-    // Show a widget root; `ownerKind` / `ownerId` bind it to a destination (widget.attachTo: it
-    // mounts inside that page and rides its transition) — TREE_DEST_NONE = a global overlay.
-    showWidget(id: TreeNodeId, ownerKind: u8, ownerId: f64): void
-    hideWidget(id: TreeNodeId): void
+    // ---- widgets (docs/plans/widgets-plan.md): a widget is a CHILD — of a screen root, of a
+    //      destination's content layer, of the app layer — never a root of its own; `insert` /
+    //      `remove` place it, `display` shows it, the runtime lays it out in the outermost presented
+    //      destination's box (the portal) and mounts it under that root for the host. ------------
+    // The content LAYER of a destination: a "layer" root (a pass-through root laid out at the frame,
+    // shown while the destination is presented) whose widget children are the surface's UI — a HUD
+    // over a scene, a card over a map. `kind` TREE_DEST_NONE (id 0) = the APP layer, above every
+    // destination, always shown. 0 takes the layer away.
+    setLayer(kind: u8, id: f64, layer: TreeNodeId): void
+    // The pose a widget child enters from and leaves to: a transition id (defineTransition) whose
+    // ALONE roles the runtime plays as tracks on the widget when its resolved `display` flips —
+    // `none → flex` from the enter pose to rest, `flex → none` from rest to the exit pose, `none`
+    // taking effect when the tracks land. TRANSITION_NONE = no pose (the flip is instant).
+    setWidgetPose(id: TreeNodeId, transition: i32): void
 
     // ---- pager (a "pager" node's children are its pages; TAB-MAJOR order, `lens` = per-tab stack
     //      lengths, `index` = the selected tab). A change of the current tab's stack plays a
@@ -251,11 +261,16 @@ export interface HostUI {
    *  call's arguments, valid for the call. Settle exactly one of the two callbacks through the
    *  dispatch bridge — `onComplete` with the result as ONE value, or with none. */
   viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-  /** Show a widget root: `ownerKind` = TREE_DEST_* (0xFF = a global overlay), `ownerId` = the sceneId /
-   *  viewId of a scene / native owner (0 for a screen), `ownerNode` = the owner screen's root (a
-   *  screen destination or a pager page) — 0 otherwise. */
-  widgetOpen(node: nodeid, ownerKind: u8, ownerId: i32, ownerNode: nodeid): void
-  widgetClose(node: nodeid): void
+  /** A LAYER root is shown: a pass-through root the runtime lays out at the frame, above every
+   *  destination (the app layer) or over the presented surface (a scene's / a native view's / a
+   *  video's content layer). Its own box is never hit — only its children are — so a touch outside
+   *  them reaches what is under the layer; it is painted after the destination, layers in open
+   *  order. Its children are widgets (the runtime inserts them with insertNode, as under a screen
+   *  root): a widget child with an overlay layer (`overlayColor`, any color — "transparent" too)
+   *  intercepts every touch outside its own box within its root and reports it as the overlay tap. */
+  layerOpen(node: nodeid): void
+  /** The layer root is hidden (its view stays; releaseNode says when it is gone). */
+  layerClose(node: nodeid): void
   /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle
    *  one of the callbacks through the dispatch bridge. */
   registerFont(url: string, fontFamily: string, weight: i32, style: i32, onComplete: () => void, onReject: (err: string) => void): void
@@ -289,9 +304,6 @@ export interface HostUI {
    *  a child (covered by a push, a keepAlive page); a page that is released goes through
    *  removeNode right after. */
   pagerDropPage?(node: nodeid, page: nodeid): void
-  /** A pager page root (`page`) was mounted under the pager or released (an attachTo widget names the
-   *  page node as its owner). */
-  pagerPageMounted?(page: nodeid, mounted: boolean): void
   /** Optional: the host may PLAY a UI tween track itself — a platform animation interpolating on its
    *  own clock (Core Animation on iOS) instead of one style write per runtime frame. `samples` holds
    *  the track evaluated at even points of its length, easing included, `lanes` floats each: 1 for a

package/src/chisel.ts

@@ -129,7 +129,7 @@ export const chiselVocab: ChiselVocab = {
       "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",
       "onEndReached", "onStartReached",
       "append", "insert", "remove", "setContent", "keepAlive", "url",
-      "attachTo", "detents", "dismissible", "transition", "setSourceRect",
+      "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
       // UITabs / UIVirtualizedList / the native views (NativeView, CameraView, MapView, QRScanner)
       "badge", "setData", "update", "prepend", "removeByKey",

package/src/g2/Scene2D.ts

@@ -6,6 +6,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE2D, ensureEmitter, registerDest } from "../ui/tree"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
@@ -188,6 +189,15 @@ export class Scene2D implements Presentable {
     registerDest(TREE_DEST_SCENE2D, this.id, this)
     return [TREE_DEST_SCENE2D, this.id, "", ""]
   }
+  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the scene — widgets (a HUD, a dialog), laid out over the scene while it is
+   *  presented; touches outside a widget's box reach the scene. */
+  setContent(content: UIWidgetContent): this {
+    ensureEmitter()
+    _setSurfaceContent(this, content)
+    return this
+  }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
   /** @internal */

package/src/gl/Light.ts

@@ -1,4 +1,4 @@
-// Lights. A directional sun (the engine's primary light) and punctual point lights. Add one to a
+// Lights. A directional sun (the engine's primary light), punctual point lights and spot lights. Add one to a
 // scene like any node; `intensity` and `color` stay writable so a light can be animated.
 
 import { Color, type ColorInput } from "../core/color"
@@ -80,6 +80,24 @@ export type PointOptions = {
   bakeArea?: readonly [number, number]
 }
 
+export type SpotOptions = {
+  /**
+   * Luminous power in lumens, as a point light's. The cone does not change the brightness: widen it and the
+   * same lumens light a larger patch at the same level. On its axis a spot is 4x brighter than a point light of
+   * the same lumens (its light is not spread over the whole sphere). Default 1000.
+   */
+  intensity?: number
+  color?: ColorInput
+  /** Metres of influence along the cone, the performance knob as for a point light. Default 10. */
+  range?: number
+  /** The cone's full angle in degrees, up to 180: past it the light contributes nothing. Default 45. */
+  angle?: number
+  /** The full angle in degrees of the cone's fully lit core; the light fades from it out to `angle`. Default 0.75 x `angle`. */
+  innerAngle?: number
+  /** A spot's shadow is one 2D shadow map (a point light's is a cubemap); off by default. */
+  castShadows?: boolean
+}
+
 export class Light extends Node {
   private _intensity = 0
 
@@ -159,7 +177,65 @@ export class Light extends Node {
   /** Whether this host can create point lights at all. */
   static get supportsPoint(): boolean { return _creator.createPointLight !== undefined }
 
-  /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
+  /** @internal a spot's cone, full angles in degrees (the engine takes half-angles in radians). */
+  _angle = 0
+  _innerAngle = 0
+
+  /**
+   * A spot light — a flashlight, a headlight, a stage light. It shines along the node's forward (-Z): position
+   * it like any node and aim it with `lookAt`. Real time only: the lightmap bake takes no spot lights, so a spot
+   * lights the baked statics live too.
+   *
+   * Feature-detected like `Light.point`: on a host without it the node exists and lights nothing
+   * (`Light.supportsSpot`).
+   */
+  static spot(options: SpotOptions = {}): Light {
+    const light = new Light()
+    light._intensity = options.intensity ?? 1000
+    light._color = options.color ?? 0xffffff
+    light._baked = false
+    light._angle = options.angle ?? 45
+    light._innerAngle = options.innerAngle ?? light._angle * 0.75
+    const [ inner, outer ] = light._cone()
+    _creator.createSpotLight?.(
+      light.id,
+      light._intensity,
+      Color.toPackedRgb(light._color),
+      options.range ?? 10,
+      inner, outer,
+      options.castShadows ?? false,
+    )
+    // the statics of a lightmapped level are on Filament channel 1 alone (see Lightmap)
+    _creator.setLightChannel?.(light.id, 1, true)
+    return light
+  }
+
+  /** Whether this host can create spot lights. */
+  static get supportsSpot(): boolean { return _creator.createSpotLight !== undefined }
+
+  /** @internal the cone as the engine takes it: half-angles in radians, outer in (0, 90°], inner in [0, outer]. */
+  _cone(): [number, number] {
+    const rad = Math.PI / 360
+    const outer = Math.min(Math.max(this._angle, 0.1), 180) * rad
+    const inner = Math.min(Math.max(this._innerAngle, 0), this._angle) * rad
+    return [ Math.min(inner, outer), outer ]
+  }
+
+  /** A spot's full cone angle in degrees — live (a flashlight's focus). */
+  get angle(): number { return this._angle }
+  set angle(value: number) {
+    this._innerAngle *= this._angle > 0 ? value / this._angle : 0
+    this._angle = value
+    _creator.setLightCone?.(this.id, ...this._cone())
+  }
+  /** A spot's fully lit core, full angle in degrees — live. Setting `angle` scales it along. */
+  get innerAngle(): number { return this._innerAngle }
+  set innerAngle(value: number) {
+    this._innerAngle = value
+    _creator.setLightCone?.(this.id, ...this._cone())
+  }
+
+  /** Live intensity (sun: lux, point / spot: lumens) — animate a flash without rebuilding the light. */
   get intensity(): number { return this._intensity }
   set intensity(value: number) {
     this._intensity = value

package/src/gl/Material.ts

@@ -187,6 +187,9 @@ export class Material {
     } else if ("_h" in (shader as any)) {
       this.shader = shader as FetchResponse
       this._h = _creator.createMaterial((shader as any)._h.id)   // owned: dropped and unused → freed
+      // 0xFFFFFFFF = the engine refused the package: no shader in it for the running backend (a
+      // phone on Vulkan handed the mobile `_opengl` artifact — the host's log names what is missing).
+      if (this._h.id === 0xFFFFFFFF) throw new Error("Material: the engine refused the shader (no variant for its backend — see the host log)")
     } else {
       this.shader = "unknown"
       this._h = shader as Handle           // an instance the runtime already wrapped for us

package/src/gl/Scene.ts

@@ -10,6 +10,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _navEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
 import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
@@ -478,10 +479,19 @@ export class Scene implements Presentable {
 
   /** @internal The destination tuple (ui/presentable.ts). */
   _dest(): DestTuple {
-    // Addressed by the router / an attached widget: make sure the (kind, id) resolves back to us.
+    // Addressed by the router / its content layer: make sure the (kind, id) resolves back to us.
     registerDest(TREE_DEST_SCENE3D, this._id, this)
     return [TREE_DEST_SCENE3D, this._id, "", ""]
   }
+  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the scene — widgets (a HUD, a dialog), laid out over the scene while it is
+   *  presented; touches outside a widget's box reach the scene. `scene.setContent([hud])`. */
+  setContent(content: UIWidgetContent): this {
+    ensureEmitter()
+    _setSurfaceContent(this, content)
+    return this
+  }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
   /** @internal */

package/src/inject.ts

@@ -102,6 +102,7 @@ export {
   UITabs, type UITabDef,
   defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
+  UIOverlay, type UIWidgetContent,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,
   UIPopover, type UIPopoverStyle,

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[]) : [] },
+})