lecodes-sdk 2.2.3 → 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,9 +583,11 @@ 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
+  const SvgSource: typeof SERVER.SvgSource
   const channel: typeof SERVER.channel
   const defineDb: typeof SERVER.defineDb
   const model: typeof SERVER.model

package/dist/types/animate/tween/spec.d.ts

@@ -124,11 +124,10 @@ export declare const uiValue: (v: unknown) => ({
  *  function is unknown (the caller falls back to matrix decomposition on the host). `scale(2)` and
  *  `translate(5px)` complete their second argument like CSS.
  *
- *  `percent`: a `%` in a translate is a percent of the target's box (`translateX(100%)` →
- *  `translateX%` [100]; a translate mixing the units splits into its two axes). Without it a `%`
- *  reads as px, as the style's own parser reads it — with a warning: only a screen transition
- *  measures a translate in percents. */
-export declare const parseTransformList: (s: string, percent?: boolean) => {
+ *  A `%` in a translate is a percent of the target's own box (`translateX(100%)` → `translateX%`
+ *  [100]; a translate mixing the units splits into its two axes), the way the runtime reads a
+ *  style's transform: the box is measured when the matrix is composed, so a track fits any size. */
+export declare const parseTransformList: (s: string) => {
     sig: string;
     lanes: number[];
 } | null;

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/server/db/fields.d.ts

@@ -41,7 +41,8 @@ export type FieldDef = {
     kind: FieldKind;
     scalar?: ScalarKind;
     optional: boolean;
-    unique: boolean;
+    /** `true` = `@unique`; a string = `@unique(<group>)`: the fields of a model sharing the group are unique together. */
+    unique: boolean | string;
     index: boolean;
     hasDefault: boolean;
     default?: unknown;
@@ -73,8 +74,10 @@ export interface Field<T, M extends FieldMeta = FieldMeta> {
     readonly def: FieldDef;
     /** Nullable column (`String?`). */
     optional(): Field<T, SetMeta<M, "optional", true>>;
-    /** `@unique` (on a relation: one-to-one). */
-    unique(): Field<T, M>;
+    /** `@unique` (on a relation: one-to-one). With a group name, the fields of the model that share it are
+     *  unique TOGETHER — `user: t.one("User").unique("pair"), post: t.one("Post").unique("pair")` is one
+     *  like per user and post; a null part is not constrained. */
+    unique(group?: string): Field<T, M>;
     /** `@index` — used by `$where`, `$order`, aggregations. */
     index(): Field<T, M>;
     /** `@default(...)`; `"now"` on `t.date()` → `now()`. Makes the field optional on insert. */

package/dist/types/server/db/marci/query.d.ts

@@ -197,6 +197,8 @@ export type MarciOp = {
     query?: any;
     data?: any;
     id?: any;
+    key?: any;
+    onInsert?: any;
     journal?: JournalArgs;
 };
 /** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
@@ -255,9 +257,11 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
     readonly [__sel]: Effective<T, Sel>;
     /** Filter (marcidb `$where`). Repeated calls are ANDed. */
     where(where: T["where"]): Query<T, Sel>;
-    /** Sort by one field: `order("age", "desc")` or `order({ age: "desc" })`. */
+    /** Sort: `order("age", "desc")` or `order({ age: "desc" })`. A second `order()` adds the next key — ties on
+     *  the first are broken by it (`order("createdAt", "desc").order("id")`); the keys may also come as an array
+     *  in one call. Several keys sort in memory. */
     order(field: keyof T["order"] & string, direction?: "asc" | "desc"): Query<T, Sel>;
-    order(order: T["order"]): Query<T, Sel>;
+    order(order: T["order"] | T["order"][]): Query<T, Sel>;
     limit(n: number): Query<T, Sel>;
     skip(n: number): Query<T, Sel>;
     /** Keyset cursor: rows strictly after this id in the current order (`$cursor`). */
@@ -287,6 +291,18 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
         select: S;
     }): Promise<Rows<T, S>>;
     update(id: IdArg<T["id"]>, data: T["update"]): Op<void>;
+    /** Writes the row `key` names — the id, or the fields of ONE unique index (a `@unique` field, all the fields of
+     *  a `@unique(<name>)` group): an update of `data` when it exists, an insert of key + data when not. `data` is
+     *  in the insert form (plain values, `{ id }` for a relation; no `$` operators). `onInsert` adds fields used
+     *  only when the row is created. Resolves to the id, like `insert`. */
+    upsert<K extends Partial<T["insert"]> | T["id"]>(key: K, data: Omit<T["insert"], keyof K>, options?: {
+        onInsert?: Partial<T["insert"]>;
+    }): Op<T["id"]>;
+    /** The row written, by `select`'s shape — as stored, whichever path the upsert took. */
+    upsert<K extends Partial<T["insert"]> | T["id"], S extends T["query"]>(key: K, data: Omit<T["insert"], keyof K>, options: {
+        onInsert?: Partial<T["insert"]>;
+        select: S;
+    }): Promise<Rows<T, S>>;
     /** Applies `data` to every row the chain's `where` matches (all rows without one); resolves to the number of rows. */
     updateMany(data: T["update"]): Op<number>;
     /** @deprecated pass the filter through the chain: `db.user.where(w).updateMany(data)` (removed in the next minor). */
@@ -354,6 +370,9 @@ export type QueryLayerOptions = {
     run(op: MarciOp): Promise<any>;
     /** Hook for `insert` payloads (the lecodes SDK generates uuid ids here). */
     prepareInsert?(model: string, data: any): any;
+    /** Hook for the `onInsert` part of an `upsert` — the fields used only when the row is created (the lecodes SDK
+     *  puts a uuid id here). Receives what the caller gave (or undefined), returns what is sent. */
+    prepareUpsert?(model: string, onInsert: any): any;
 };
 /**
  * The query builder over a set of models and a `run` function. Returns `op(descriptor)` — a lazy operation

package/dist/types/server/db/types.d.ts

@@ -66,20 +66,21 @@ export type Scalars<S, N extends keyof S> = Pick<Row<S, N>, (ScalarKeys<FieldsOf
 export type ScalarSelect<S, N extends keyof S> = {
     [K in (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>]: true;
 };
-type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>> : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[] : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>>> : M["kind"] extends "file" ? Nullable<M, Arr<M, FileWrite>> : Nullable<M, Arr<M, TsOf<Fld>>>;
+type FieldInsert<S, Fld, FW, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>> : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[] : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>, FW>> : M["kind"] extends "file" ? Nullable<M, Arr<M, FW>> : Nullable<M, Arr<M, TsOf<Fld>>>;
 type RequiredKeys<F extends Fields> = {
     [K in keyof F]: K extends IdKeys<F> ? never : MetaOf<F[K]>["optional"] extends true ? never : MetaOf<F[K]>["hasDefault"] extends true ? never : MetaOf<F[K]>["kind"] extends "many" | "list" ? never : MetaOf<F[K]>["kind"] extends "file" ? (MetaOf<F[K]>["array"] extends true ? never : K) : K;
 }[keyof F];
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
-type InsertOf<S, F extends Fields> = Simplify<{
-    [K in RequiredKeys<F>]: FieldInsert<S, F[K]>;
+type InsertOf<S, F extends Fields, FW = FileWrite> = Simplify<{
+    [K in RequiredKeys<F>]: FieldInsert<S, F[K], FW>;
 } & {
-    [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K]>;
+    [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K], FW>;
 }>;
-export type Insert<S, N extends keyof S> = InsertOf<S, FieldsOf<S[N]>>;
-type StructInsert<S, F extends Fields> = InsertOf<S, F>;
+/** `FW` is what a file field is written with: an upload of the call; in a seed, a resource of the project as well. */
+export type Insert<S, N extends keyof S, FW = FileWrite> = InsertOf<S, FieldsOf<S[N]>, FW>;
+type StructInsert<S, F extends Fields, FW = FileWrite> = InsertOf<S, F, FW>;
 type FieldUpdate<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? Nullable<M, RefUpdate<Id<S, ModelName<S, Fld>>>> : M["kind"] extends "many" ? RefListUpdate<Id<S, ModelName<S, Fld>>> : M["kind"] extends "list" ? RefListUpdateOrdered<Id<S, ModelName<S, Fld>>> : M["kind"] extends "struct" ? RefUpdateStruct<StructInsert<S, StructFieldsOf<Fld>>, UpdateOf<S, StructFieldsOf<Fld>>> | null : M["kind"] extends "file" ? Nullable<M, Arr<M, FileWrite | StoredFile>> : M["array"] extends true ? TsOf<Fld>[] | PrimitiveListUpdate<TsOf<Fld>> : Nullable<M, TsOf<Fld> | (IsNum<M> extends true ? UpdateNumValue : never)>;
 type UpdateOf<S, F extends Fields> = {
     [K in Exclude<keyof F, IdKeys<F>>]?: FieldUpdate<S, F[K]>;
@@ -103,7 +104,8 @@ type IdWhere<S, N extends keyof S> = {
 export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S[N]>> & IdWhere<S, N>>;
 type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>;
 type OrderKeys<S, N extends keyof S> = (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>;
-/** ONE field and its direction: the engine sorts by a single field, so a second key is a type error. */
+/** One field and its direction. Several keys are several of these, in an array (`$order: [{ createdAt: "desc" },
+ *  { id: "asc" }]`) or chained `.order()` calls — an object with two keys is refused, since JSON promises no key order. */
 export type Order<S, N extends keyof S> = {
     [K in OrderKeys<S, N>]: {
         [P in K]: "asc" | "desc";
@@ -114,7 +116,7 @@ export type Order<S, N extends keyof S> = {
 /** The query object — marcidb's wire form: a select shape plus the `$`-clauses. */
 export type QueryObject<S, N extends keyof S> = Select<S, N> & {
     $where?: Where<S, N>;
-    $order?: Order<S, N>;
+    $order?: Order<S, N> | Order<S, N>[];
     $limit?: number;
     $skip?: number;
     $cursor?: Id<S, N>;
@@ -128,7 +130,7 @@ export type AggregateQuery<S, N extends keyof S> = {
     $max?: (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string;
 };
 /** The per-model type bag marcidb's generic `Query<T>` is parametrised by (what its codegen emits as `UserTypes`). */
-export type Types<S, N extends keyof S> = {
+export type Types<S, N extends keyof S, FW = FileWrite> = {
     name: N & string;
     model: Row<S, N>;
     id: Id<S, N>;
@@ -137,7 +139,7 @@ export type Types<S, N extends keyof S> = {
     query: QueryObject<S, N>;
     where: Where<S, N>;
     order: Order<S, N>;
-    insert: Insert<S, N>;
+    insert: Insert<S, N, FW>;
     update: Update<S, N>;
     aggregate: AggregateQuery<S, N>;
     reindex: false;
@@ -148,7 +150,7 @@ export type Types<S, N extends keyof S> = {
  * `updateMany(data)`/`deleteMany()` write through the chain's `where`; a query placed in another query's
  * select is a sub-query. `Sel` is the projection: id + scalars until `select(...)` sets a shape.
  */
-export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>> = MarciQuery<Types<S, N>, Sel>;
+export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>, FW = FileWrite> = MarciQuery<Types<S, N, FW>, Sel>;
 /** The rows a query with projection `Q` resolves to (no field keys = id + scalars; sub-queries resolved). */
 export type Result<S, N extends keyof S, Q> = Rows<Types<S, N>, Q>;
 /** `db.<model>` — the root query of a model. */
@@ -168,7 +170,18 @@ type DbBase<S extends Schema> = {
     }>;
     /** The `.marci` schema text this db syncs with. */
     readonly $schema: string;
+    /**
+     * The first rows of this database: run by the host ONCE, on a database that is empty, wherever the
+     * database opens (a check, a dev backend, the first deploy). Part of the definition, like sign-in:
+     * written on `defineDb(...)` itself. Inside, a file field takes a resource of the project — the path
+     * of a picture the design shows (`photo: row.photo`) — and stores it the way an upload is stored.
+     */
+    seed(fn: (db: SeedDb<S>) => Promise<void>): Db<S>;
 };
+/** The db a seed writes through: the same queries, a file field taking a resource of the project (its path) too. */
+export type SeedDb<S extends Schema> = {
+    [N in keyof S & string as Uncapitalize<N>]: Query<Full<S>, N, ScalarSelect<Full<S>, N>, FileWrite | string>;
+} & Pick<DbBase<S>, "$transaction">;
 export type Db<S extends Schema> = DbBase<S> & {
     /**
      * Sign-in for this database: `model` is the project's model of a user. Adds the platform's `Session`
@@ -180,8 +193,9 @@ export type Db<S extends Schema> = DbBase<S> & {
         model: N;
     }): DbWithAuth<S, N>;
 };
-export type DbWithAuth<S extends Schema, N extends keyof S & string> = DbBase<S> & {
+export type DbWithAuth<S extends Schema, N extends keyof S & string> = Omit<DbBase<S>, "seed"> & {
     readonly auth: Auth<S, N>;
+    seed(fn: (db: SeedDb<S>) => Promise<void>): DbWithAuth<S, N>;
 };
 /**
  * The user of the current request, as a query over the project's user model: `select(shape)` picks the

package/dist/types/server/errors.d.ts

@@ -1,6 +1,9 @@
 /**
  * `throw new ApiError(404, "Not found")` inside an endpoint → the client's promise rejects with the
- * same status + message. Any other throw is a 500 (message hidden, logged to the server console).
+ * same status + message. A write the database refused for a reason a person could have caused reaches
+ * the app the same way, in the database's words: a taken unique value, a pointer at no row, a delete
+ * other rows forbid are 409, a row that is gone 404. Any other throw is a 500 (message hidden, logged
+ * to the server console).
  */
 export declare class ApiError extends Error {
     readonly status: number;

package/dist/types/server/files/models.d.ts

@@ -124,6 +124,10 @@ export type FilesSeam = {
     /** The id of the `File` row behind an upload of the current request; undefined for anything else —
      *  a value the app sent as JSON is never an upload, whatever it looks like. */
     uploaded(value: unknown): string | undefined;
+    /** While a seed runs: the id of a `File` row made from a resource of the project named by its path
+     *  (what a path literal of the design is in the server bundle); undefined for a path that is no file
+     *  of the project. Absent outside a seed: a string the app sent is never a file. */
+    resource?(path: string): Promise<string | undefined>;
     url(id: string, name: string): string;
     /** Make the upload `id` fit for a `t.image()` field (its bytes are rewritten in place) and say what
      *  it is now. Throws an `ApiError` for what is no picture. */

package/dist/types/server/inject.d.ts

@@ -3,3 +3,9 @@ export { ApiError } from "./errors";
 export { channel } from "./channel";
 export { request } from "./context";
 export type { StoredFile, StoredImage } from "./files/models";
+/** The value an SVG source is to the client (`assetIcon(…)` compiles to `SvgSource(…)`): a shared module of
+ *  the design that names an icon per row loads on the server too. The server draws nothing with it. */
+export declare const SvgSource: (svg: string) => {
+    svg: string;
+    tintColor: string | null;
+};

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

@@ -27,6 +27,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
@@ -373,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/UIVirtualizedList.d.ts

@@ -6,20 +6,14 @@ export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & {
      *  matter how the history is scrolled. */
     keyboardDismissMode?: "interactive" | "scroll" | "none";
 };
-export interface VListConfig<T> {
-    /** The rows, read reactively: the list follows the signals this reads, the way a container's
-     *  function children do. Rows are told apart by `keyOf`; a row whose item is another object
-     *  re-renders. Appended rows and rows added at the start are told from a rewrite (a chat at
-     *  its bottom follows what is appended; older history above moves nothing). */
-    data: () => T[];
+interface VListBaseConfig<T> {
     /** Stable unique key of an item. */
     keyOf: (item: T) => string;
     /** Subtree factory — called when the item enters the window; the subtree lives until it
      *  leaves. */
     render: (item: T) => UINodeChild;
     /** Height estimate (px) used before the first measurement — a number, or a per-item function
-     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Computed once when the item is
-     *  added. */
+     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Read when the item is added. */
     estimatedHeight: number | ((item: T) => number);
     /** Extra px around the viewport kept mounted. Default: one viewport height. */
     overscan?: number;
@@ -27,9 +21,23 @@ export interface VListConfig<T> {
      *  list sits at the bottom. */
     inverted?: boolean;
 }
-/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
- *  and chats. Fed by `data`, a function over signals. */
-export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
+/** A list fed by `data`: the rows are read reactively, the way a container's function children
+ *  are. Such a list has no imperative feed (`append` and the rest are not on its type). */
+export interface VListBoundConfig<T> extends VListBaseConfig<T> {
+    /** The rows, read reactively: the list follows the signals this reads. Rows are told apart by
+     *  `keyOf`; a row whose item is another object re-renders. The change is told from the keys:
+     *  rows gone are removals, new rows are inserts where they stand (a chat at its bottom follows
+     *  an append; rows above the reader move nothing), a reorder rewrites the keys. */
+    data: () => T[];
+}
+/** A list fed by hand: `setData` / `append` / `prepend` / `update` / `removeByKey`. */
+export interface VListFedConfig<T> extends VListBaseConfig<T> {
+    data?: undefined;
+}
+export type VListConfig<T> = VListBoundConfig<T> | VListFedConfig<T>;
+/** What both forms of the list share: the items held, scrolling, the scroll / refresh / edge
+ *  callbacks. */
+export interface UIVirtualizedListBase<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
     readonly type: "vlist";
     /** Number of data items (mounted or not). */
     readonly itemCount: number;
@@ -51,7 +59,29 @@ export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtuali
     /** Same, for the top edge — chat history loading. */
     onStartReached(thresholdPx: number, callback: () => void): this;
 }
-export declare class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {
+/** A virtualized list fed by `data` (a function over signals): write the signal, the list follows. */
+export interface UIBoundVirtualizedList<T = unknown> extends UIVirtualizedListBase<T> {
+}
+/** A virtualized list fed by hand. Each call goes straight to the runtime: `append` is O(1). */
+export interface UIFedVirtualizedList<T = unknown> extends UIVirtualizedListBase<T> {
+    /** Replace the data wholesale — diffed by key like a `data` write (vanished keys are removed,
+     *  new ones inserted where they stand, a reorder rewrites). */
+    setData(items: T[]): this;
+    /** Append items to the end (auto-scrolls when `inverted` and resting at the bottom). */
+    append(...items: T[]): this;
+    /** Insert at the start WITHOUT a scroll jump (the runtime compensates the offset). */
+    prepend(...items: T[]): this;
+    /** Update items with the same keys: mounted ones re-render; the cached height persists until
+     *  re-measured. */
+    update(...items: T[]): this;
+    /** Remove items by key. */
+    removeByKey(...keys: string[]): this;
+}
+/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
+ *  and chats. Fed by `data`, a function over signals, or by hand (`append` and the rest); which
+ *  one is the config's and the type's. */
+export type UIVirtualizedList<T = unknown> = UIBoundVirtualizedList<T> | UIFedVirtualizedList<T>;
+export declare class VListElement<T> extends Element<"vlist"> implements UIFedVirtualizedList<T> {
     private readonly sl;
     private readonly erl;
     private readonly strl;
@@ -64,15 +94,28 @@ export declare class VListElement<T> extends Element<"vlist"> implements UIVirtu
     private estimate;
     private readonly _overscan;
     private readonly _inverted;
+    private readonly _bound;
     private _endThreshold;
     private _startThreshold;
     private _inited;
     constructor(config: VListConfig<T>);
     private _ensure;
-    /** The data as it is now against what the runtime holds: rows added at the end or at the start
-     *  are inserts (the runtime anchors the scroll: a chat follows an append, history above moves
-     *  nothing), rows gone are removals, anything else a rewrite of the keys (measured heights stay). */
+    /** The two feeds are exclusive per list: a hand-made change to a list `data` feeds would be
+     *  undone by the binding's next run, so it is refused and logged. */
+    private _fed;
+    /** The data as it is now against what the runtime holds. Keys gone are removals, keys new are
+     *  inserts where they stand in the new order — both anchored by the runtime (a chat follows an
+     *  append, rows above the reader move nothing) — as long as the keys kept keep their order;
+     *  a reorder rewrites the keys (measured heights stay). A mounted row whose item is another
+     *  object re-renders. */
     private _apply;
+    /** The new rows of `items` (keys not held yet, repeats dropped), registered. */
+    private _register;
+    setData(items: T[]): this;
+    append(...items: T[]): this;
+    prepend(...items: T[]): this;
+    update(...items: T[]): this;
+    removeByKey(...keys: string[]): this;
     get itemCount(): number;
     getItem(key: string): T | undefined;
     scrollTo(offset: number, animated?: boolean): void;
@@ -83,6 +126,9 @@ export declare class VListElement<T> extends Element<"vlist"> implements UIVirtu
     onEndReached(thresholdPx: number, callback: () => void): this;
     onStartReached(thresholdPx: number, callback: () => void): this;
 }
-/** Create a virtualized list from a config (`data` + `keyOf` + `render` + `estimatedHeight`
- *  required). Give it a size (`flexGrow: 1` as a screen body). */
-export declare function UIVirtualizedList<T>(config: VListConfig<T>): UIVirtualizedList<T>;
+/** Create a virtualized list (`keyOf` + `render` + `estimatedHeight` required). With `data` the
+ *  list follows the signals it reads and has no hand feed; without it, feed it with `setData` /
+ *  `append` / `prepend` / `update` / `removeByKey`. Give it a size (`flexGrow: 1` as a screen body). */
+export declare function UIVirtualizedList<T>(config: VListBoundConfig<T>): UIBoundVirtualizedList<T>;
+export declare function UIVirtualizedList<T>(config: VListFedConfig<T>): UIFedVirtualizedList<T>;
+export {};