lecodes-sdk 2.2.4 → 2.2.5

package/dist/global.d.ts

@@ -124,7 +124,6 @@ declare global {
   const UIImage: typeof SDK.UIImage
   const UIInput: typeof SDK.UIInput
   const UIModal: typeof SDK.UIModal
-  const UIOverlay: typeof SDK.UIOverlay
   const UIPager: typeof SDK.UIPager
   const UIPopover: typeof SDK.UIPopover
   const UIRow: typeof SDK.UIRow
@@ -566,6 +565,7 @@ declare global {
   type UIVideoStyle = SDK.UIVideoStyle
   type UIVirtualizedList<T = unknown> = SDK.UIVirtualizedList<T>
   type UIWidget = SDK.UIWidget
+  type UIWidgetChild = SDK.UIWidgetChild
   type UIWidgetContent = SDK.UIWidgetContent
   type UIWidgetStyle = SDK.UIWidgetStyle
   type Unit = SDK.Unit
@@ -583,6 +583,7 @@ declare global {
   type WebSocket = SDK.WebSocket
   type Wheel = SDK.Wheel
   type WheelSuspension = SDK.WheelSuspension
+  type WidgetSet<Owner> = SDK.WidgetSet<Owner>
   type With<N, A extends Aspect<any, any, any>> = SDK.With<N, A>
   // ---- server globals (available in *.server.ts; using them in client code is a build error) ----
   const ApiError: typeof SERVER.ApiError

package/dist/types/g2/Scene2D.d.ts

@@ -1,7 +1,7 @@
 import { type ColorInput } from "../core/color";
 import { type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect";
 import { Presentable, type DismissOptions, type PresentOptions } from "../ui/presentable";
-import { type UIWidgetContent } from "../ui/UILayer";
+import { type WidgetSet } from "../ui/UILayer";
 import { type Vec2Like } from "../math/vec";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import { Camera2D } from "./Camera2D";
@@ -68,9 +68,10 @@ export declare class Scene2D implements Presentable {
     /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
      *  rename; removed with the release that recompiles them. */
     onBackPressed(callback: () => void): this;
-    /** 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;
+    /** The widgets over the scene while it is presented — a HUD, a dialog, a sheet: `scene.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 scene. */
+    get widgets(): WidgetSet<this>;
     /** Make this the active scene — shows it as the current destination (replaces a screen /
      *  another scene; only the active scene renders). */
     open(options?: PresentOptions): this;

package/dist/types/gl/Scene.d.ts

@@ -1,7 +1,7 @@
 import { type ColorInput } from "../core/color";
 import { type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect";
 import { Presentable, type DismissOptions, type PresentOptions } from "../ui/presentable";
-import { type UIWidgetContent } from "../ui/UILayer";
+import { type WidgetSet } from "../ui/UILayer";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import type { FetchResponse } from "../runtime/fetch";
 import { Camera } from "./Camera";
@@ -233,9 +233,10 @@ export declare class Scene implements Presentable {
     /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
      *  rename; removed with the release that recompiles them. */
     onBackPressed(callback: () => void): this;
-    /** 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;
+    /** The widgets over the scene while it is presented — a HUD, a dialog, a sheet: `scene.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 scene. */
+    get widgets(): WidgetSet<this>;
     /** Make this the active scene — shows it as the current destination (replaces a screen /
      *  another scene; only the active scene renders). The runtime activates the engine as part of
      *  presenting the destination. */

package/dist/types/inject.d.ts

@@ -56,7 +56,7 @@ export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d";
 export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d";
 export { cells, encodeCells, type CellsData } from "./g2/cells";
 export { CameraFollow } from "./g2/scenarios2d";
-export { UIScreen, type UIScreenStyle, UIRow, UIColumn, UIBox, type UIContainerStyle, UIText, type UITextStyle, UIButton, type UIButtonStyle, UIImage, type UIImageStyle, UIVideo, type UIVideoStyle, UIInput, UITextArea, type UIInputStyle, UIScrollable, type UIScrollableStyle, UIPager, type UIPagerStyle, UITabs, type UITabDef, defineTabs, type TabDef, type TabsHandle, UIWidget, type UIWidgetStyle, UIOverlay, type UIWidgetContent, UIModal, type UIModalStyle, UIBottomSheet, type UIBottomSheetStyle, UIPopover, type UIPopoverStyle, UISpacer, type UISpacerStyle, UIVirtualizedList, Router, NativeView, type UINativeViewStyle, registerFont, __uiMap, __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget, } from "./ui/UI";
+export { UIScreen, type UIScreenStyle, UIRow, UIColumn, UIBox, type UIContainerStyle, UIText, type UITextStyle, UIButton, type UIButtonStyle, UIImage, type UIImageStyle, UIVideo, type UIVideoStyle, UIInput, UITextArea, type UIInputStyle, UIScrollable, type UIScrollableStyle, UIPager, type UIPagerStyle, UITabs, type UITabDef, defineTabs, type TabDef, type TabsHandle, UIWidget, type UIWidgetStyle, type WidgetSet, type UIWidgetContent, type UIWidgetChild, UIModal, type UIModalStyle, UIBottomSheet, type UIBottomSheetStyle, UIPopover, type UIPopoverStyle, UISpacer, type UISpacerStyle, UIVirtualizedList, Router, NativeView, type UINativeViewStyle, registerFont, __uiMap, __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget, } from "./ui/UI";
 export { Presentable } from "./ui/UI";
 export type { DismissOptions, PresentOptions, Transition, TransitionName, TransitionPose, TransitionSpec } from "./ui/UI";
 export type { UINode, UINodeChild } from "./ui/UINode";

package/dist/types/ui/NativeView.d.ts

@@ -1,4 +1,4 @@
-import { type UIWidgetContent } from "./UILayer";
+import { type WidgetSet } from "./UILayer";
 import { type DismissOptions, type PresentOptions } from "./presentable";
 import { type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode";
 export type UINativeViewStyle = ElementStyle & DrawableStyle;
@@ -27,8 +27,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>;
 }
 /**
  * Create an instance of a host-registered platform view. `NativeView.isSupported(name)` reports

package/dist/types/ui/UI.d.ts

@@ -7,7 +7,7 @@ export { UIImage, type UIImageStyle } from './UIImage';
 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/dist/types/ui/UILayer.d.ts

@@ -1,25 +1,32 @@
 import type { UIWidget } from "./UIWidget";
-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 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.
+ * 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
- * UIOverlay.append(miniPlayer)
- * miniPlayer.hide()   // display: none — still here, ready for show()
+ * 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 declare const UIOverlay: Readonly<{
+export interface WidgetSet<Owner> {
+    (...widgets: (UIWidgetChild | UIWidgetChild[])[]): Owner;
+    (widgets: UIWidgetContent): Owner;
     /** Add widgets at the end (on top). */
-    append(...widgets: (UIWidget | null | undefined | false)[]): void;
-    /** Insert widgets at `index` (0 = the bottom of the layer). */
-    insert(index: number, ...widgets: (UIWidget | null | undefined | false)[]): void;
-    /** Take widgets out of the layer (they stay valid; a dropped one is freed). */
-    remove(...widgets: (UIWidget | null | undefined | false)[]): void;
-    /** Replace the layer's widgets — a list, or a function for reactive content. */
-    setContent(content: UIWidgetContent): void;
-    /** The layer's widgets, bottom to top (a snapshot read from the runtime). */
-    readonly children: UIWidget[];
-}>;
+    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[];
+}

package/dist/types/ui/UINode.d.ts

@@ -376,11 +376,15 @@ export type ChildrenFn = () => UINodeChild[];
  * results it behaves exactly like Array.prototype.map — a wrong rewrite can't change behavior.
  */
 export declare function __uiMap(list: any, render: (item: any, index: number) => any, slot: string): any[];
+/** A widget slot of `widgets(...)` takes a widget (falsy = conditional, skipped silently);
+ *  anything else is reported and skipped. */
+export declare const acceptWidget: (owner: {
+    type: string;
+}, node: any) => boolean;
 export declare class ContainerElement<T extends string> extends Element<T> {
     constructor(type: T, style: any, children: any[] | ChildrenFn);
     /** The children — a snapshot read from the runtime (falsy entries were never mounted). */
     get children(): any[];
-    private _insertAt;
     /** Append children (falsy entries are skipped). */
     append(...nodes: UINodeChild[]): this;
     /** Insert children at `index`. */

package/dist/types/ui/UIScreen.d.ts

@@ -1,6 +1,7 @@
 import { TouchStartEvent } from "../runtime/touch";
 import { type DismissOptions, type PresentOptions } from "./presentable";
 import { ContainerElement, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode";
+import { type WidgetHost, type WidgetSet } from "./UILayer";
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle;
 /** A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
  *  fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
@@ -46,9 +47,18 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
     url(route: string | null): this;
     /** 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>;
 }
-export declare class ScreenElement extends ContainerElement<"screen"> {
+export declare class ScreenElement extends ContainerElement<"screen"> implements WidgetHost {
     constructor(type: "screen", style: any, children: any);
+    /** The content — the children read from the runtime without the widget tail. */
+    get children(): any[];
+    private _widgetSet?;
+    get widgets(): WidgetSet<this>;
     open(options?: PresentOptions): void;
     close(options?: DismissOptions): void;
     protected ol: (() => void)[];

package/dist/types/ui/UIVideo.d.ts

@@ -1,5 +1,5 @@
 import type { VideoPlayer } from "../runtime/media";
-import { type UIWidgetContent } from "./UILayer";
+import { type WidgetSet } from "./UILayer";
 import { type DismissOptions, type PresentOptions } from "./presentable";
 import { type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode";
 export type UIVideoStyle = ElementStyle & DrawableStyle & {
@@ -22,8 +22,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>;
 }
 /** Create a video node showing `player`'s output. */
 export declare function UIVideo(player: VideoPlayer): UIVideo;

package/dist/types/ui/UIWidget.d.ts

@@ -1,5 +1,6 @@
 import { TouchStartEvent } from "../runtime/touch";
 import { ContainerElement, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type PaddingStyle, type PositionStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode";
+import type { Presentable } from "./presentable";
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
     /** Shown (`"flex"`, the default) or not: what `show()` / `hide()` write, what a state block may
      *  flip (`$open: { display: "flex" }`). */
@@ -8,13 +9,13 @@ export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & Base
      *  removes the layer. A tap on it fires `onOverlayTap`. */
     overlayColor?: Color | null;
 };
-/** 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` /
@@ -23,18 +24,24 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
     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
      *  it). True for a widget hidden WITH its page or its covered screen: that is its place's
      *  visibility, not the widget's. */
     readonly isShown: boolean;
+    /** @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`). */
@@ -51,6 +58,8 @@ export declare class WidgetElement extends ContainerElement<"widget"> {
     show(): void;
     hide(): void;
     get isShown(): boolean;
+    /** @deprecated see the interface */
+    attachTo(owner: Presentable | null): this;
     readonly touchStartListeners: any[];
     onTouchStart(callback: any): this;
     readonly otl: (() => void)[];
@@ -60,8 +69,8 @@ export declare class WidgetElement extends ContainerElement<"widget"> {
     /** @deprecated see the interface */
     onBackPressed(callback: any): this;
 }
-/** 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 declare function UIWidget(...children: UIChildArg[]): UIWidget;
 export declare function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;

package/dist/types/ui/presentable.d.ts

@@ -1,5 +1,5 @@
 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;
  *  the rest are two-screen moves. */
@@ -74,12 +74,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>;
 }
 /** Runtime companion of the `Presentable` interface (declaration merging): the navigation
  *  state that isn't tied to the Router. */

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.2.4";
+export declare const SDK_VERSION = "2.2.5";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from