lecodes-sdk 2.0.7 → 2.0.9

package/dist/global.d.ts

@@ -124,6 +124,7 @@ 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
@@ -480,6 +481,8 @@ declare global {
   type StepHandler = SDK.StepHandler
   type StepWarpOptions = SDK.StepWarpOptions
   type StopOptions = SDK.StopOptions
+  type StoredFile = SDK.StoredFile
+  type StoredImage = SDK.StoredImage
   type System<K extends string, S extends SystemHost = Scene, E extends EventMap = {}> = SDK.System<K, S, E>
   type SystemHost = SDK.SystemHost
   type TabDef = SDK.TabDef
@@ -554,6 +557,7 @@ declare global {
   type UIVideoStyle = SDK.UIVideoStyle
   type UIVirtualizedList<T = unknown> = SDK.UIVirtualizedList<T>
   type UIWidget = SDK.UIWidget
+  type UIWidgetContent = SDK.UIWidgetContent
   type UIWidgetStyle = SDK.UIWidgetStyle
   type Unit = SDK.Unit
   type UnlitMaterialDef = SDK.UnlitMaterialDef
@@ -580,6 +584,8 @@ declare global {
   const request: typeof SERVER.request
   const t: typeof SERVER.t
   type ApiError = SERVER.ApiError
+  type StoredFile = SERVER.StoredFile
+  type StoredImage = SERVER.StoredImage
 }
 
 export {}

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

@@ -1,6 +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 Vec2Like } from "../math/vec";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import { Camera2D } from "./Camera2D";
@@ -67,6 +68,9 @@ 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;
     /** 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/Light.d.ts

@@ -73,6 +73,23 @@ 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 declare class Light extends Node {
     private _intensity;
     /** Tween `intensity` / `color` (a flash, a sunrise) and the transform — see {@link Node.animateTo}. */
@@ -94,7 +111,25 @@ export declare class Light extends Node {
     static point(options?: PointOptions): Light;
     /** Whether this host can create point lights at all. */
     static get supportsPoint(): boolean;
-    /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
+    _innerAngle: number;
+    /**
+     * 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;
+    /** Whether this host can create spot lights. */
+    static get supportsSpot(): boolean;
+    /** A spot's full cone angle in degrees — live (a flashlight's focus). */
+    get angle(): number;
+    set angle(value: number);
+    /** A spot's fully lit core, full angle in degrees — live. Setting `angle` scales it along. */
+    get innerAngle(): number;
+    set innerAngle(value: number);
+    /** Live intensity (sun: lux, point / spot: lumens) — animate a flash without rebuilding the light. */
     get intensity(): number;
     set intensity(value: number);
     _holdDark(dark: boolean): void;

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

@@ -1,6 +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 { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import type { FetchResponse } from "../runtime/fetch";
 import { Camera } from "./Camera";
@@ -247,6 +248,9 @@ 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;
     /** 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

@@ -23,6 +23,7 @@ export { WebSocket } from "./runtime/net";
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net";
 export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc";
 export type { ChannelSubscription } from "./server/channel";
+export type { StoredFile, StoredImage } from "./server/files/models";
 export { AudioPlayer, VideoPlayer } from "./runtime/media";
 export { Sound, type SoundOptions } from "./audio/Sound";
 export { Voice, type VoiceEvents } from "./audio/Voice";
@@ -54,7 +55,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, 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, 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 { 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/runtime/rpc.d.ts

@@ -9,6 +9,8 @@
  *
  * Wire (implemented by the runner):
  *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *                               — with a `File` among the arguments: multipart, the field `args` is
+ *                               that JSON with `{"$file": <i>}` where the file stood, `file<i>` the files
  *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
  *   WS   <serverUrl>/ws  the channel socket — its frames are ./wire.ts
  *

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

@@ -14,6 +14,10 @@ export type RequestContext = {
     sessionToken?: string;
     /** Set by the auth runtime after resolving the token — read via `db.auth`, not here. */
     auth?: unknown;
+    /** The files a multipart call carried, as the receiving process left them (./files/host.ts `Upload`). */
+    uploads?: unknown[];
+    /** What `/files/<id>/<name>` is appended to in a stored file's url: the backend's own base, as this request reached it. */
+    filesBase?: string;
 };
 type Provider = () => RequestContext | undefined;
 /** Host hook (runner / test harness): install the current-request provider. */

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

@@ -7,7 +7,7 @@
  * `defineDb(models, { transport })` or provided by the host through `setDbTransport()` — user code
  * never sees a connection string.
  */
-import type { FieldDef } from "./fields";
+import { type FieldDef } from "./fields";
 import { type MarciTransport } from "./marci/query";
 import type { Db, Fields, Model, Schema, ValidateRefs } from "./types";
 export declare const model: <F extends Fields>(fields: F) => Model<F>;

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

@@ -6,8 +6,9 @@
  * mutated), so `const s = t.string(); { a: s, b: s.optional() }` behaves as expected.
  */
 import type { JsonValue } from "./marci/query";
+import type { StoredFile, StoredImage } from "../files/models";
 export type ScalarKind = "string" | "int" | "float" | "bool" | "date" | "uuid" | "";
-export type FieldKind = "scalar" | "json" | "enum" | "struct" | "one" | "many" | "list";
+export type FieldKind = "scalar" | "json" | "enum" | "struct" | "one" | "many" | "list" | "file";
 export type OnDelete = "cascade" | "setNull" | "restrict";
 /** Phantom metadata — the type-level twin of `FieldDef`. */
 export type FieldMeta = {
@@ -58,6 +59,10 @@ export type FieldDef = {
     fields?: Record<string, Field<any, any>>;
     /** one / many / list */
     model?: string;
+    /** file: a picture (`t.image()`) — `max` is the most its longer side may be, px. */
+    image?: {
+        max: number;
+    };
     /** many: the field on the related model that holds the reference (`@bind`); resolved by defineDb when omitted. */
     back?: string;
 };
@@ -136,6 +141,25 @@ export declare const t: {
         kind: "many";
         model: N;
     }>>;
+    /**
+     * A stored file: written as a `File` (an upload — an endpoint's parameter), read as
+     * `{ url, name, type, size, width?, height? }`. `.optional()` = may be empty, `.array()` = an ordered
+     * list of files. It is deleted with its row — or when the field is given another file, or `null`.
+     */
+    file: () => Field<StoredFile, Meta<{
+        kind: "file";
+    }>>;
+    /**
+     * A stored PICTURE — a `t.file()` that takes images only and keeps them fit to show: turned the way
+     * the camera meant, without its metadata (a photo's place and time), as WebP, and no larger than
+     * `max` px on its longer side (2048 when not said; a picture is never enlarged).
+     * Read as a `StoredFile` whose `width` and `height` are always there. A GIF is kept as it is.
+     */
+    image: (options?: {
+        max?: number;
+    }) => Field<StoredImage, Meta<{
+        kind: "file";
+    }>>;
     /** Ordered relation list stored inline (`@list`) — hand-arranged collections, duplicates allowed. */
     list: <N extends string>(model: N) => Field<never, Meta<{
         kind: "list";

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

@@ -197,6 +197,15 @@ export type MarciOp = {
     query?: any;
     data?: any;
     id?: any;
+    journal?: JournalArgs;
+};
+/** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
+export type JournalArgs = {
+    name: string;
+    on?: readonly JournalOp[];
+    after?: number;
+    limit?: number;
+    wait?: number;
 };
 export type MarciTransport = {
     exec(op: MarciOp): Promise<any>;
@@ -291,13 +300,41 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
     /** @deprecated use `.select(query).first()` (removed in the next minor). */
     findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>;
 }
-/** `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index. */
+/** What a journal can record. Only deletes so far. */
+export type JournalOp = "delete";
+/** One recorded change. `row` is the row as it last was: its id and every scalar field. */
+export type JournalEntry<T extends ModelTypes, O extends JournalOp = JournalOp> = {
+    seq: number;
+    op: O;
+    row: Rows<T, T["scalars"]>;
+};
+export type JournalOptions<O extends JournalOp> = {
+    /** The operations to record. A journal that exists with other ones is an error, not a redefinition. */
+    on: O | readonly O[];
+    /** `false`: the loop ends when the journal is read through. By default it waits for the next entry. */
+    wait?: boolean;
+};
+/**
+ * A named, durable log of a model's changes. It starts recording when it is first asked for and keeps
+ * every entry until the loop that reads it has moved past it — an entry whose loop body threw, or that
+ * was never reached, is delivered again to the next reader of the same name.
+ */
+export interface Journal<T extends ModelTypes, O extends JournalOp = JournalOp> extends AsyncIterable<JournalEntry<T, O>> {
+    /** Drops the journal with whatever it still holds; the model's writes stop paying for it. */
+    drop(): Promise<void>;
+}
+/**
+ * `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index and
+ * `$journal(name, { on })` — the journal of this model's changes under that name, created on first use.
+ */
 export type Collection<T extends ModelTypes> = Query<T> & (T["reindex"] extends true ? {
     reindex(): Op<{
         ok: boolean;
         indexed: number;
     }>;
-} : {});
+} : {}) & {
+    $journal<O extends JournalOp>(name: string, options: JournalOptions<O>): Journal<T, O>;
+};
 /** One field of a model, in slot order: `n` name, `k` key | body | one | many, `m` the relation's target model. */
 export type FieldDesc = {
     n: string;

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

@@ -8,6 +8,7 @@
  */
 import type { Field, FieldMeta } from "./fields";
 import type { IdentityPublicFields, SessionPublicFields } from "../auth/models";
+import type { StoredFile, UploadedFile as File } from "../files/models";
 import type { CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearchValue, FullTextSearch, JsonCondition, JsonPathWhere, Op, PrimitiveListUpdate, Query as MarciQuery, RefListUpdate, RefListUpdateOrdered, RefUpdate, RefUpdateStruct, Rows, Sub, UpdateNumValue, VectorSearch, WhereValue } from "./marci/query";
 export type Fields = Record<string, Field<any, any>>;
 export type Model<F extends Fields = Fields> = {
@@ -48,7 +49,12 @@ export type Row<S, N extends keyof S> = Id<S, N> & {
 type StructRow<S, F extends Fields> = {
     [K in keyof F]: FieldRow<S, F[K]>;
 };
+/** What a query without a selection returns besides the id: the scalars, and the files. */
 type ScalarKeys<F extends Fields> = {
+    [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" | "file" ? K : never;
+}[keyof F];
+/** The fields a row is ordered and aggregated by. */
+type ValueKeys<F extends Fields> = {
     [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" ? K : never;
 }[keyof F];
 type NumKeys<F extends Fields> = {
@@ -60,9 +66,9 @@ 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>>> : Nullable<M, Arr<M, TsOf<Fld>>>;
+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, File>> : 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 : K;
+    [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];
@@ -74,7 +80,7 @@ type InsertOf<S, F extends Fields> = Simplify<{
 }>;
 export type Insert<S, N extends keyof S> = InsertOf<S, FieldsOf<S[N]>>;
 type StructInsert<S, F extends Fields> = InsertOf<S, F>;
-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["array"] extends true ? TsOf<Fld>[] | PrimitiveListUpdate<TsOf<Fld>> : Nullable<M, TsOf<Fld> | (IsNum<M> extends true ? UpdateNumValue : never)>;
+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, File | 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]>;
 };
@@ -87,7 +93,7 @@ type StructSelect<S, F extends Fields> = {
     [K in keyof F]?: FieldSelect<S, F[K]>;
 };
 type ScalarWhere<T, M extends FieldMeta> = Nullable<M, CompareValue<T>> | (IsNum<M> extends true ? CompareNumValue<T> : M["scalar"] extends "string" ? CompareStrValue<T> : never);
-type FieldWhere<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? CompareRefValue<Where<S, ModelName<S, Fld>> | null> : M["kind"] extends "many" | "list" ? CompareRefListValue<Where<S, ModelName<S, Fld>>> : M["kind"] extends "struct" ? CompareRefValue<WhereValue<StructWhereFields<S, StructFieldsOf<Fld>>> | null> : M["kind"] extends "json" ? JsonPathWhere | JsonCondition : M["array"] extends true ? TsOf<Fld>[] : ScalarWhere<TsOf<Fld>, M> | CustomSearchValue<FullTextSearch> | CustomSearchValue<VectorSearch>;
+type FieldWhere<S, Fld, M extends FieldMeta = MetaOf<Fld>> = M["kind"] extends "one" ? CompareRefValue<Where<S, ModelName<S, Fld>> | null> : M["kind"] extends "many" | "list" ? CompareRefListValue<Where<S, ModelName<S, Fld>>> : M["kind"] extends "struct" ? CompareRefValue<WhereValue<StructWhereFields<S, StructFieldsOf<Fld>>> | null> : M["kind"] extends "json" ? JsonPathWhere | JsonCondition : M["kind"] extends "file" ? never : M["array"] extends true ? TsOf<Fld>[] : ScalarWhere<TsOf<Fld>, M> | CustomSearchValue<FullTextSearch> | CustomSearchValue<VectorSearch>;
 type WhereFieldsOf<S, F extends Fields> = {
     [K in keyof F]?: FieldWhere<S, F[K]>;
 };
@@ -96,7 +102,7 @@ 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> = (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>;
+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. */
 export type Order<S, N extends keyof S> = {
     [K in OrderKeys<S, N>]: {
@@ -118,8 +124,8 @@ export type AggregateQuery<S, N extends keyof S> = {
     $count?: true;
     $sum?: NumKeys<FieldsOf<S[N]>> & string;
     $avg?: NumKeys<FieldsOf<S[N]>> & string;
-    $min?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string;
-    $max?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string;
+    $min?: (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string;
+    $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> = {

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

@@ -0,0 +1,39 @@
+/**
+ * The db layer's half of stored files (./models.ts): what turns a file FIELD — a value in a row — into
+ * operations on the platform's `File` model, and back.
+ *
+ *   read    the field is selected as the reverse relation it is (the `File` rows that point at the
+ *           row, in order) and comes back as a `StoredFile`, or a list of them
+ *   insert  the row is inserted without the field; each upload's `File` row is then pointed at it
+ *           (`ref` to the insert's id) — one transaction
+ *   update  the row's files that are no longer listed are deleted, the uploads are pointed at it —
+ *           one transaction with the update itself
+ *
+ * An upload written to a `t.image()` field is first made a picture fit to show (the host's work,
+ * ./host.ts): that is why a plan is awaited. What it became — its type, its size — goes to its row
+ * in the operation that attaches it.
+ *
+ * A file is written from the FILE's side (its reference to the owner): that is the side the database
+ * cascades over. Only an upload of the current request is ever attached: a `StoredFile` the app hands
+ * back means "keep this one", and one of another row is not moved — a client that knows the url of
+ * someone else's file cannot take it.
+ */
+import type { MarciOp } from "../db/marci/query";
+import { type FileField } from "./models";
+type Plan = {
+    op: MarciOp;
+    after: MarciOp[];
+};
+export type FileLayer = {
+    /** The operation as the database runs it, and the ones that follow it in the same transaction.
+     *  `index` is the operation's place in that transaction (what `ref` counts from). */
+    plan(op: MarciOp, index: number): Promise<Plan>;
+    /** The database's answer to a planned operation, as the project reads it. */
+    result(op: MarciOp, value: any): any;
+};
+/**
+ * `fields`: the schema's `t.file()` fields. `relations`: model → relation field → its target model.
+ * `scalars`: model → what a query without a selection returns (file fields included).
+ */
+export declare const createFileLayer: (fields: FileField[], relations: Record<string, Record<string, string>>, scalars: Record<string, string[]>) => FileLayer;
+export {};

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

@@ -0,0 +1,131 @@
+/**
+ * Stored files: `t.file()` on a model.
+ *
+ * A project never declares where a file lives. A model that has a `t.file()` field makes the db carry
+ * one more model, the PLATFORM's `File` — a row per stored file: what it is (name, type, size, an
+ * image's dimensions) and whose it is. The owner is a reference FROM the file TO its row, with
+ * `onDelete("cascade")`, one optional reference per `t.file()` field of the schema (`postImage`,
+ * `userAvatar`): deleting a post — by name, or because its author was deleted — deletes its files in
+ * the same transaction, by the database's own rule. The field on the owner is the reverse side of
+ * that reference.
+ *
+ * The bytes are the host's (./host.ts): a file on disk named by the row's id. They go only because
+ * the row went — the host reads the deletions from marcidb's journal of this model.
+ *
+ * What a project sees is a VALUE: it writes a `File` (an upload, an endpoint's parameter) and reads a
+ * `StoredFile`. The url is computed when the row is read, never stored.
+ */
+import { type Field } from "../db/fields";
+export declare const FILE_MODEL = "File";
+/** A stored file as a project reads it. */
+export type StoredFile = {
+    /** Where the bytes are served from. Public, not guessable; it never changes for this file. */
+    url: string;
+    name: string;
+    /** The media type: `image/jpeg`, `video/mp4`, `application/pdf`. */
+    type: string;
+    /** Bytes. */
+    size: number;
+    /** An image's dimensions in pixels (absent for anything else). */
+    width?: number;
+    height?: number;
+};
+/** A stored picture (`t.image()`): its size is always known. */
+export type StoredImage = StoredFile & {
+    width: number;
+    height: number;
+};
+/**
+ * A file as an endpoint receives it — the app's `File` (a picked file, a photo), uploaded with the
+ * call. Written to a `t.file()` field, it is stored; an endpoint that writes it nowhere drops it.
+ */
+export type UploadedFile = {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+};
+/** One `t.file()` field of the schema; `image` = it is a `t.image()`, with its rule. */
+export type FileField = {
+    model: string;
+    key: string;
+    array: boolean;
+    owner: string;
+    image?: ImageRule;
+};
+export type ImageRule = {
+    max: number;
+};
+/** What a file became when it was made fit for an image field: the facts its row carries from then on. */
+export type ImageFacts = {
+    name: string;
+    type: string;
+    size: number;
+    width: number;
+    height: number;
+};
+/** The reference on `File` that says "I am this field of that row": `Post.image` → `postImage`. */
+export declare const fileOwnerKey: (model: string, key: string) => string;
+/** What a data browser may show of a file (the rest is the platform's bookkeeping). */
+export declare const filePublicFields: () => {
+    name: Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    type: Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    size: Field<number, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "int";
+    }>>;
+    width: Field<number, {
+        kind: "scalar";
+        scalar: "int";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    height: Field<number, {
+        kind: "scalar";
+        scalar: "int";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    createdAt: Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+};
+/** The whole `File` of a schema with these `t.file()` fields. */
+export declare const fileFields: (fields: FileField[]) => Record<string, Field<any, any>>;
+/**
+ * What the host (./host.ts) gives the db layer of a bundle — a global, because the bundle carries its
+ * own copy of this module. Absent (a unit test without a host): nothing is an upload, urls are relative.
+ */
+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;
+    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. */
+    image(id: string, rule: ImageRule): Promise<ImageFacts>;
+    /** A write that may have removed rows of `File` went through the db (a delete, a rewritten file field): their bytes are due. */
+    dirty: boolean;
+};
+export declare const filesSeam: () => FilesSeam | undefined;
+export declare const setFilesSeam: (value: FilesSeam | null) => void;
+/** The row a `StoredFile` the app handed back stands for (by its url); undefined for anything else. */
+export declare const storedFileId: (value: unknown) => string | undefined;
+export declare const fileUrl: (id: string, name: string) => string;

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

@@ -2,3 +2,4 @@ export { t, model, defineDb, ref } from "./db";
 export { ApiError } from "./errors";
 export { channel } from "./channel";
 export { request } from "./context";
+export type { StoredFile, StoredImage } from "./files/models";

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

@@ -1,3 +1,4 @@
+import { type UIWidgetContent } 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;
@@ -26,6 +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;
 }
 /**
  * Create an instance of a host-registered platform view. `NativeView.isSupported(name)` reports

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

@@ -7,6 +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 { 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

@@ -0,0 +1,25 @@
+import type { UIWidget } from "./UIWidget";
+export type UIWidgetContent = (UIWidget | null | undefined | false)[] | (() => (UIWidget | null | undefined | false)[]);
+/**
+ * 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 declare const UIOverlay: Readonly<{
+    /** 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[];
+}>;