lecodes-sdk 2.6.0 → 2.8.1

package/dist/global.d.ts

@@ -127,7 +127,7 @@ declare global {
   const SpriteAnimation: typeof SDK.SpriteAnimation
   const SpriteSheet: typeof SDK.SpriteSheet
   const StateMachine: typeof SDK.StateMachine
-  const SvgSource: typeof SDK.SvgSource
+  const SvgSource: typeof SDK.SvgSource & typeof SERVER.SvgSource
   const System: typeof SDK.System
   const Terrain: typeof SDK.Terrain
   const Text2D: typeof SDK.Text2D
@@ -181,6 +181,7 @@ declare global {
   const __channel: typeof SDK.__channel
   const __compOp: typeof SDK.__compOp
   const __compWrite: typeof SDK.__compWrite
+  const __computed: typeof SDK.__computed
   const __localAsset: typeof SDK.__localAsset
   const __pushChannel: typeof SDK.__pushChannel
   const __pushEnable: typeof SDK.__pushEnable
@@ -195,7 +196,7 @@ declare global {
   const cells: typeof SDK.cells
   const clipboard: typeof SDK.clipboard
   const colorCurve: typeof SDK.colorCurve
-  const computed: typeof SDK.computed
+  const computed: typeof SERVER.computed & typeof SDK.computed
   const cubicBezier: typeof SDK.cubicBezier
   const curve: typeof SDK.curve
   const dataOf: typeof SDK.dataOf
@@ -213,7 +214,7 @@ declare global {
   const easeOut: typeof SDK.easeOut
   const effect: typeof SDK.effect
   const encodeCells: typeof SDK.encodeCells
-  const env: typeof SDK.env
+  const env: typeof SDK.env & typeof SERVER.env
   const failureOf: typeof SDK.failureOf
   const fetch: typeof SDK.fetch
   const fetchLocal: typeof SDK.fetchLocal
@@ -223,13 +224,14 @@ declare global {
   const localStorage: typeof SDK.localStorage
   const make: typeof SDK.make
   const mediaDevices: typeof SDK.mediaDevices
+  const online: typeof SDK.online
   const openFilePicker: typeof SDK.openFilePicker
   const openURL: typeof SDK.openURL
   const packTile: typeof SDK.packTile
   const permissions: typeof SDK.permissions
   const rawCell: typeof SDK.rawCell
   const rawIndex: typeof SDK.rawIndex
-  const ref: typeof SDK.ref
+  const ref: typeof SDK.ref & typeof SERVER.ref
   const registerEditorTool: typeof SDK.registerEditorTool
   const registerEditorWindow: typeof SDK.registerEditorWindow
   const registerFont: typeof SDK.registerFont
@@ -246,6 +248,7 @@ declare global {
   const tileOriented: typeof SDK.tileOriented
   const tileTurns: typeof SDK.tileTurns
   const toast: typeof SDK.toast
+  const trackGesture: typeof SDK.trackGesture
   const use: typeof SDK.use
   type ARError = SDK.ARError
   type ARErrorCode = SDK.ARErrorCode
@@ -376,6 +379,9 @@ declare global {
   type GeoPosition = SDK.GeoPosition
   type GeoWatch = SDK.GeoWatch
   type Geometry = SDK.Geometry
+  type Gesture = SDK.Gesture
+  type GestureHandler = SDK.GestureHandler
+  type GestureTarget = SDK.GestureTarget
   type GizmoAnchor = SDK.GizmoAnchor
   type GizmoStyle = SDK.GizmoStyle
   type HapticStyle = SDK.HapticStyle
@@ -724,13 +730,11 @@ declare global {
   type Wrap2D = SDK.Wrap2D
   // ---- 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 env: typeof SERVER.env
   const model: typeof SERVER.model
+  const ordered: typeof SERVER.ordered
   const pushChannel: typeof SERVER.pushChannel
-  const ref: typeof SERVER.ref
   const request: typeof SERVER.request
   const t: typeof SERVER.t
   type ApiError = SERVER.ApiError

package/dist/types/inject.d.ts

@@ -23,7 +23,7 @@ export { device, type HapticStyle, type MotionOptions } from "./runtime/device";
 export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input";
 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, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc";
+export { __rpc, __channel, __computed, __pushChannel, __serverOnly, RpcError, online } from "./runtime/rpc";
 export { __registerFont } from "./ui/fonts";
 export { resource, action, dataOf, failureOf, type Loaded, type Failure, type Resource, type Action } from "./runtime/resource";
 export type { ChannelSubscription } from "./server/channel";
@@ -37,6 +37,7 @@ export { audio, type PlaySoundOptions, type SpatialOptions, type Rolloff, type A
 export { openFilePicker, files, type FileData } from "./runtime/files";
 export { share } from "./runtime/share";
 export { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "./runtime/touch";
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures";
 export { Scene2D } from "./g2/Scene2D";
 export { Node2D } from "./g2/Node2D";
 export { Camera2D } from "./g2/Camera2D";

package/dist/types/plugin.d.ts

@@ -22,6 +22,7 @@ export { Vec2, Vec3, type Vec3Like } from "./math/vec";
 export { Quat, type QuatLike } from "./math/quat";
 export { Mat4 } from "./math/mat4";
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch";
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures";
 export type { DismissOptions } from "./ui/presentable";
 /** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
  *  reads the device's address from, registers through, and a push channel's handlers are kept by. */

package/dist/types/plugins/gen/ar/sdk/ar.d.ts

@@ -44,6 +44,9 @@ export type ARSceneOptions = SceneOptions & {
     /** "world" (default): planes, hit tests, anchors, image and QR targets. "images": image and QR
      *  targets only — lighter on iOS; no planes, no hit test, no `root`. */
     mode?: ARMode;
+    /** How far in front of the user `root` is placed, metres (default 1): along the camera's heading,
+     *  on the floor. */
+    rootDistance?: number;
 };
 export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images" | "codes"> & {
     /** The scene's ambient (its `environmentIntensity`) follows the estimated light; turns
@@ -128,6 +131,8 @@ export declare class ARScene extends Scene {
     /** Whether this host registered the "ar" service (the app lists the plugin, the host has a half). */
     static get isSupported(): boolean;
     readonly mode: ARMode;
+    /** Metres between the user and `root` when it is placed (`rootDistance` option, default 1). */
+    readonly rootDistance: number;
     /** `open()` warm-renders the scene first (default true). */
     useWarmRender: boolean;
     private _opening;
@@ -147,7 +152,8 @@ export declare class ARScene extends Scene {
     private _codesWarned;
     private _options;
     private _root;
-    /** The first horizontal plane's pose: where `root` is pinned. */
+    /** The floor's height (world Y, metres): the first horizontal plane below the camera this session
+     *  found. Null until one is; `root` is placed on it. */
     private _floor;
     /** The image targets. `source` is held for the bytes: a fetched response owns its buffer, which the
      *  host frees once the response is collected — the File the session is handed only names it. */
@@ -174,9 +180,17 @@ export declare class ARScene extends Scene {
     /** A grid drawn on every plane (each plane's child mesh). */
     get showPlanes(): boolean;
     set showPlanes(on: boolean);
-    /** The floor: an anchor pinned on the first horizontal plane the session finds (it fires `track`
-     *  then). Until that it is the world's origin — where the session began. Not in "images" mode. */
+    /** The place in front of the user: an anchor `rootDistance` metres ahead of the camera along its
+     *  heading, on the floor — the first horizontal plane below the camera the session finds; it is
+     *  pinned there and fires `track` then — turned the way the user looks (its −Z along the heading,
+     *  so a model's front, +Z, faces the user). Until the floor is found (and on the web, which finds
+     *  none) it sits the same way at the camera's own height, not pinned. Made on first use; put
+     *  content under it. `placeRoot()` puts it in front of the user again. Not in "images" mode. */
     get root(): Anchor;
+    /** Put `root` in front of the user again — where they look now, `rootDistance` metres ahead, on the
+     *  floor if one is known (the camera's height otherwise), facing them: a "reset" button, or a
+     *  placement after the user has moved. Makes `root` when there is none yet. */
+    placeRoot(): Anchor;
     /** An anchor that follows an image (a printed marker, a poster): the session finds it in the camera
      *  image and keeps the anchor on it — a rigid pose in metres (its centre, Y out of the image, the
      *  image in XZ), its size `anchor.extent`. `physicalWidth` = the printed width in metres. Hidden
@@ -244,8 +258,14 @@ export declare class ARScene extends Scene {
     private _wire;
     /** Pin `anchor` at `pose` (where it is until the session holds it) — now, or when a session starts. */
     private _place;
-    /** `root` onto the floor (the first horizontal plane of this session). */
-    private _pinRoot;
+    /** Where `root` goes now: `rootDistance` metres from the camera along its heading (its forward
+     *  flattened to the floor; looking straight down or up, the way the top of the screen points), at
+     *  the floor's height when one is known, else the camera's; turned so its −Z runs along the
+     *  heading — a model's front (+Z) faces the user. */
+    private _rootPose;
+    /** `root` in front of the user: moved there now, and pinned there when the floor is known (a
+     *  session holds a pin; without one `_pinAll` does not re-pin root — it waits for its own floor). */
+    private _placeRoot;
     private _pin;
     /** A session began: every pose anchor is pinned where it is. */
     private _pinAll;

package/dist/types/runtime/firstCall.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The client transport's first-call rule (./rpc.ts), kept apart so a host that calls a backend as a
+ * device — a flow's `call` step, `lecodes call` (tools/cli/src/dev/backendCall.ts) — follows the very
+ * same rule: a device with no token yet sends its first call alone and the calls behind it wait, so a
+ * backend that mints a token on first contact (`request.session`, a guest session) mints ONE — two
+ * calls in flight would each get their own and the device would end up with whichever landed last.
+ * Once per device per run: the gate opens for good when the first call is back, whether or not it
+ * brought a token. Pure: no bridges, no globals.
+ */
+export type FirstCallGate = <T>(hasToken: () => boolean, send: () => Promise<T>) => Promise<T>;
+/** One gate per device (and backend): `gate(hasToken, send)` runs `send` under the rule. */
+export declare const firstCallGate: () => FirstCallGate;

package/dist/types/runtime/gestures.d.ts

@@ -0,0 +1,52 @@
+import type { TouchStartEvent, TrackHandler } from "./touch";
+/** One reading of a gesture, handed to `onStart` / `onMove` / `onEnd` (a fresh object each time). */
+export interface Gesture {
+    /** The centroid of the live fingers, in the event's client coordinates (logical px). */
+    centerX: number;
+    centerY: number;
+    /** The centroid's move since the previous `onMove` (0 on start / end). */
+    deltaX: number;
+    deltaY: number;
+    /** Mean finger distance to the centroid over the previous one (1 with one finger, 1 on start / end). */
+    scale: number;
+    /** The mean change of each finger's angle about the centroid since the previous `onMove`, radians,
+     *  positive = clockwise on screen (0 with one finger, 0 on start / end). */
+    rotation: number;
+    /** The number of live fingers (0 in `onEnd`: the last one lifted). */
+    pointers: number;
+}
+/** What `trackGesture` takes: the gesture's callbacks and the claim every finger's track makes. */
+export interface GestureHandler {
+    /** Passed to every finger's `ev.track(...)` (default `true`: a scrollable above never takes the pan). */
+    claim?: TrackHandler["claim"];
+    /** The first finger landed. */
+    onStart?(g: Gesture): void;
+    /** Any finger moved: the change since the previous `onMove`. */
+    onMove?(g: Gesture): void;
+    /** The last finger lifted. */
+    onEnd?(g: Gesture): void;
+    /** The host cancelled one of the fingers: the whole gesture is over. */
+    onCancel?(): void;
+}
+/** Anything that hands out touchstarts: a UI element (`onTouchStart`) or a scene / node
+ *  (`addEventListener("touchstart", …)`). */
+export type GestureTarget = {
+    onTouchStart(callback: (ev: TouchStartEvent<any>) => void): unknown;
+} | {
+    addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<any>) => void): void;
+    removeEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<any>) => void): void;
+};
+/**
+ * Follow pan, pinch and twist on `target` as one gesture: every finger that lands on it is tracked,
+ * and `onMove` reports the change of the whole set since the previous move — the centroid's move,
+ * the spread's ratio, the twist's angle. One finger is a gesture too (a pan, scale 1, rotation 0).
+ *
+ * ```ts
+ * trackGesture(scene, {
+ *   onMove(g) { zoom *= g.scale; angle += g.rotation; panX += g.deltaX; panY += g.deltaY },
+ * })
+ * ```
+ */
+export declare const trackGesture: (target: GestureTarget, handler: GestureHandler) => {
+    remove(): void;
+};

package/dist/types/runtime/rpc.d.ts

@@ -5,6 +5,7 @@
  *
  *   export const listNotes = __rpc("<serverUrl>", "notes.server.ts#listNotes")
  *   export const chat      = __channel("<serverUrl>", "chat.server.ts#chat")
+ *   export const roomView  = __computed("<serverUrl>", "game.server.ts#roomView")
  *   export const db        = __serverOnly("schema.server.ts#db")
  *
  * Wire (implemented by the runner):
@@ -18,7 +19,11 @@
  * The session token is transport-owned (cookie-like): stored under `lecodes.session:<serverUrl>` in
  * localStorage, sent on every call and on the socket, replaced whenever a response carries `session`.
  * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
+ *
+ * `online` (the app's global) is what this transport last learned of its backends: both the calls and
+ * the socket go through here, so it is kept here (docs/plans/multiplayer-plan.md D5a).
  */
+import { type Computed } from "../core/signals";
 import type { ChannelSubscription } from "../server/channel";
 /** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
  *  (0 = the request itself failed: no network / no server). */
@@ -26,6 +31,14 @@ export declare class RpcError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * Does the app reach its backend: `true` until a call fails without reaching it (`RpcError` status 0)
+ * or the channel socket drops and starts reconnecting; `true` again once the socket opens, a message
+ * comes over it, or a call is answered — with an error too. With several backends, all of them. Read
+ * `.value` in a binding, a `computed` or an `effect`; it is not the device's network (`device.online`)
+ * and says nothing of whether what a screen shows is old: a computed re-delivers by itself.
+ */
+export declare const online: Computed<boolean>;
 /** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
 export declare const __rpc: (serverUrl: string, id: string) => (...args: unknown[]) => Promise<any>;
 /** A server-only export (db, models, helpers) referenced from client code: any use throws. */
@@ -38,6 +51,17 @@ export declare const __serverOnly: (id: string) => any;
 export declare const __channel: (serverUrl: string, id: string) => {
     subscribe(...all: unknown[]): ChannelSubscription;
     publish(): never;
+    members(): never;
+};
+/**
+ * Build the client proxy of computed `id` — what a `computed()` export of a `*.server.ts` file is in the
+ * app (its type is the server's: src/server/computed.ts). Called, it is an endpoint call;
+ * `subscribe([...args,] handler, { error? })` hears its value now (the `ok`) and on every change (an `ev`
+ * to the subscription's own group), over the channel socket.
+ */
+export declare const __computed: (serverUrl: string, id: string) => ((...args: unknown[]) => Promise<any>) & {
+    subscribe(...all: unknown[]): ChannelSubscription;
+    watchers(): never;
 };
 /**
  * Build the client proxy of push channel `id` — what a `pushChannel()` export of a `*.server.ts` file is

package/dist/types/runtime/wire.d.ts

@@ -7,15 +7,20 @@
  *             then DROPS the socket's subscriptions (they were granted to someone else) and the
  *             client sends them again, under new ids.
  *   → sub     subscribe to channel `ch`; `args` are what the app passed to `subscribe` before the
- *             handler — the channel's `groupBy` reads them.
+ *             handler — the channel's `groupBy` reads them. With `computed: true`, to the computed
+ *             `ch` (../server/computed.ts): `args` are its arguments.
  *   → unsub
  *   ← session a token minted while the socket was served (the first contact of a guest): the client
  *             stores it; nothing is dropped, the server already has it.
  *   ← ok      the subscription stands; `group` is where the server put it (null = a channel without
- *             groups). The client learns its group only here — it never names one.
- *   ← err     refused (a hook threw) — the subscription is gone.
+ *             groups). The client learns its group only here — it never names one. A computed's
+ *             group is a number the server made for that one subscription, and `data` its value.
+ *   ← err     refused (a hook threw) — the subscription is gone. For a computed: refused when it comes
+ *             before the `ok` (the first run threw); after it, a later run failed and the
+ *             subscription stands.
  *   ← ev      one published message, addressed by channel + group so the server sends one frame to
- *             every socket of a group; the client hands it to each of its subscriptions there.
+ *             every socket of a group; the client hands it to each of its subscriptions there. For a
+ *             computed: its next value, sent only when it differs from the last one.
  *
  * A group's value is not a secret: its subscriber is told it.
  */
@@ -29,6 +34,7 @@ export type ClientFrame = {
     id: number;
     ch: string;
     args: unknown[];
+    computed?: true;
 } | {
     t: "unsub";
     id: number;
@@ -40,6 +46,7 @@ export type ServerFrame = {
     t: "ok";
     id: number;
     group: ChannelGroup | null;
+    data?: unknown;
 } | {
     t: "err";
     id: number;

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

@@ -22,6 +22,11 @@
  * `globalThis.__lecodesPublish` seam the host installs (same reason as ./context.ts: the bundle
  * carries its own SDK copy). In the app the export is another object altogether — the proxy
  * `__channel` of src/runtime/rpc.ts — which is why `subscribe` here only throws.
+ *
+ * Presence: `roomChannel.members(code)` (and a computed's `watchers(...args)`, ./computed.ts) — the
+ * sessions subscribed to a group now. The hub (./channelHub.ts) holds that table; the read goes to it
+ * through the `globalThis.__lecodesPresence` seam the host installs (./computedHost.ts
+ * `setPresenceProvider`), keyed by the export and the subscription's key as JSON (`presenceKey`).
  */
 import type { ChannelGroup } from "../runtime/wire";
 export type { ChannelGroup };
@@ -48,6 +53,9 @@ export interface Channel<M> {
     groupBy<K extends ChannelGroup, A extends unknown[] = []>(group: (...args: A) => K | Promise<K>): GroupedChannel<M, K, A>;
     /** Server: send `message` to every subscriber (at most once — nothing is kept for a socket that is away). */
     publish(message: M): void;
+    /** Server: the sessions (`request.session`) subscribed now, each once. Inside a `computed`, a join or a
+     *  leave runs it again. */
+    members(): Promise<number[]>;
     /** App: listen until `close()`. */
     subscribe(handler: (message: M) => void, options?: SubscribeOptions): ChannelSubscription;
 }
@@ -55,12 +63,20 @@ export interface Channel<M> {
 export interface GroupedChannel<M, K extends ChannelGroup, A extends unknown[]> {
     /** Server: send `message` to the subscribers of `group`. */
     publish(group: K, message: M): void;
+    /** Server: the sessions (`request.session`) subscribed to `group` now, each once. Inside a `computed`,
+     *  a join or a leave runs it again. */
+    members(group: K): Promise<number[]>;
     /** App: listen until `close()`; the arguments before the handler go to the channel's `groupBy`. */
     subscribe(...args: [...args: A, handler: (message: M) => void, options?: SubscribeOptions]): ChannelSubscription;
 }
 type Publisher = (channelId: string, group: ChannelGroup | null, message: unknown) => void;
 /** Host hook (runner / local backend / test harness): where `publish` delivers to. */
 export declare const setChannelPublisher: (publisher: Publisher | null) => void;
+/** What a presence read asks the host: the sessions subscribed to export `id` under `key` (`presenceKey`). */
+export type PresenceAsk = (id: string, key: string) => Promise<number[]>;
+/** The key a subscription is present under, the hub's and the reads' alike: a computed's arguments, a
+ *  channel's group (null without groups) — as JSON. */
+export declare const presenceKey: (what: unknown) => string;
 export declare const isChannelGroup: (v: unknown) => v is ChannelGroup;
 export declare const channel: <M = unknown>() => Channel<M>;
 export declare const isChannel: (v: unknown) => v is ChannelRecord;

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

@@ -0,0 +1,59 @@
+/**
+ * `computed(fn)` — a server function the runtime keeps fresh (server global). The app calls it once,
+ * like an endpoint, or subscribes to it: the value now, and again whenever the data it read changes.
+ *
+ *   export const roomView = computed(async (code: string) => {           // game.server.ts
+ *     const room = await db.room.where({ code }).first()
+ *     const players = await db.player.where({ room: code }).select({ name: true, device: true })
+ *     return { room, players, me: request.session }
+ *   })
+ *
+ *   const sub = roomView.subscribe(code, (view) => { room.value = view })   // app: now, then on every change
+ *   sub.close()
+ *   const view = await roomView(code)                                        // app: one call
+ *
+ * The app's `computed` (src/core/signals.ts) is the same idea: a value derived from its inputs, made
+ * again when they change. The app's inputs are signals; the server's are the database's rows. Hence its
+ * two rules: it only READS (a write inside is an error), and its value follows from its data and its
+ * arguments alone (`Math.random()` inside = a value that is new at every run).
+ *
+ * How it stays fresh (./computedHost.ts): a subscription runs `fn` in the subscriber's request scope
+ * (`request.session`, `db.auth`), and every read the db client sends meanwhile becomes a WATCH of the
+ * database (./db/watch.ts). When the database says a watched result may have changed, `fn` runs again —
+ * once for any number of signals during a run — and the subscriber hears the value only when it differs
+ * from the last one (JSON equality). The subscription rides the channel socket (a `sub` frame with
+ * `computed: true`, ../runtime/wire.ts); the hub (./channelHub.ts) holds it across a new worker (a deploy,
+ * an eviction) and runs it there again.
+ *
+ * Identity, as a channel's: the export (`<path>#<name>`), set by the runtime when the bundle is loaded
+ * (`loadServerModules`). In the bundle the export is callable — another server function may
+ * `await roomView(code)`, its reads are then that function's own — and `subscribe` only throws; in the
+ * app it is the proxy `__computed` of src/runtime/rpc.ts.
+ *
+ * Who is here: `roomView.watchers(code)` — the sessions subscribed to it with these arguments now (the
+ * hub's table, read as a channel's `members` is: ./channel.ts `askPresence`). A read, not a hook: inside
+ * a computed it is one more input, and a join or a leave there runs that computed again (./computedHost.ts).
+ */
+import { type ChannelSubscription } from "./channel";
+export type ComputedOptions = {
+    /** The server refused the subscription (its first run threw), or a later run failed: an `RpcError`,
+     *  its `status` the thrown one. Without it the failure is logged. A refused subscription is asked
+     *  again when the session changes; after a failed later run the last value stands and the next change
+     *  runs it again. */
+    error?: (e: Error & {
+        readonly status: number;
+    }) => void;
+};
+/** A server function the runtime keeps fresh: `computed(async (…args) => value)`. */
+export interface ServerComputed<A extends unknown[], R> {
+    /** One call, as an endpoint's. */
+    (...args: A): Promise<R>;
+    /** App: `handler` gets the value now, and again each time it changes, until `close()`; the arguments
+     *  before it are the function's. */
+    subscribe(...args: [...args: A, handler: (value: R) => void, options?: ComputedOptions]): ChannelSubscription;
+    /** Server: the sessions (`request.session`) subscribed to it with these arguments now, each once — the
+     *  arguments as the app passed them, matched as JSON. Inside a `computed`, a join or a leave runs it again. */
+    watchers(...args: A): Promise<number[]>;
+}
+export declare const computed: <A extends unknown[], R>(fn: (...args: A) => Promise<R>) => ServerComputed<A, R>;
+export declare const isComputed: (v: unknown) => v is ComputedRecord;

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

@@ -4,6 +4,10 @@
  * server bundle carries its own copy of this module (chisel bundles the SDK in), so the host can't
  * hand it a value by import. `request` reads through that seam; outside a request (module load,
  * timers after the response) every member is undefined.
+ *
+ * `session` is decided in ONE place, the host runtime (./runtime.ts `defineSession`), for endpoints
+ * and channel hooks alike: every host (the runner, `lecodes dev`, a test) gets it by running calls
+ * through `createInvoker` / `createSubscribeGuard`.
  */
 export type RequestContext = {
     /** Endpoint id `<path>#<export>` (or the channel id for a subscription's hooks). */
@@ -14,12 +18,17 @@ export type RequestContext = {
     sessionToken?: string;
     /** Set by the auth runtime after resolving the token — read via `db.auth`, not here. */
     auth?: unknown;
+    /** The device of the request — `request.session`. Defined by the host runtime (./runtime.ts), read lazily:
+     *  a host never sets it. */
+    readonly session?: number;
     /** 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;
+/** `quiet`: the host's own read, not the code's (a stored file's url is made of the request's `filesBase`).
+ *  Every other read is the code's: inside a computed it makes the run its subscriber's alone (./computedHost.ts). */
+type Provider = (quiet?: boolean) => RequestContext | undefined;
 /** Host hook (runner / test harness): install the current-request provider. */
 export declare const setRequestProvider: (provider: Provider | null) => void;
 /** The current request (server global). Undefined members outside a request. */
@@ -27,5 +36,8 @@ export declare const request: {
     readonly id: string | undefined;
     readonly headers: Record<string, string>;
     readonly ip: string | undefined;
+    /** The calling device: a number that stays the same for as long as the app keeps its storage, without
+     *  sign-in; with `withAuth` it is `db.auth.sessionId`. Not a secret — the token behind it is. */
+    readonly session: number | undefined;
 };
 export {};

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

@@ -80,7 +80,8 @@ export interface Field<T, M extends FieldMeta = FieldMeta> {
     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. */
+    /** `@default(...)`; `"now"` on `t.date()` → `now()`, a number is milliseconds since 1970; a json's is
+     *  any JSON value (`t.json<number[]>().default([])`). Makes the field optional on insert. */
     default(value: DefaultOf<T, M>): Field<T, SetMeta<M, "hasDefault", true>>;
     /** Primitive list (`String[]`). */
     array(): Field<T, SetMeta<M, "array", true>>;

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

@@ -197,6 +197,39 @@ export type Settles<T> = PromiseLike<T> & {
 export type Op<T> = Settles<T> & {
     readonly [__op]: T;
 };
+/** A running watch — see `ReadOp.watch`. */
+export interface Watch {
+    /** Stops it: no callback after this returns. Idempotent. */
+    close(): void;
+}
+export type WatchOptions = {
+    /** Gets what a read of the watch failed with (an op the database refuses — after a migration, say),
+     *  and what the callback threw. Without it, they are logged. */
+    error?: (error: unknown) => void;
+};
+/** A read (`select`, `first`, `count`, `aggregate`): an op that can also be watched. */
+export type ReadOp<T> = Op<T> & {
+    /**
+     * Calls `callback` with the result at once, then again each time a commit changed it. The database signals
+     * every commit that may have changed it; the client reads again and calls back only when the result
+     * differs (as JSON) from the one it delivered last. Signals that arrive during a read make one more read.
+     * A dropped connection is reopened and read again by the client — nothing to handle outside.
+     */
+    watch(callback: (result: T) => void, options?: WatchOptions): Watch;
+};
+/** What a transport tells a watch it holds (internal: `op.watch` is built on it). */
+export type WatchListener = {
+    /** A commit may have changed the result — or the transport recovered a lost connection. */
+    changed(): void;
+    /** The database refused the op when the transport registered it again. */
+    failed(error: unknown): void;
+};
+/** A watch registered with a transport: `ready` settles once the database has it (it rejects with the
+ *  refusal), `close` drops it. */
+export type WatchRegistration = {
+    ready: Promise<void>;
+    close(): void;
+};
 export type MarciOp = {
     model: string;
     action: string;
@@ -218,6 +251,16 @@ export type JournalArgs = {
 export type MarciTransport = {
     exec(op: MarciOp): Promise<any>;
     batch(ops: MarciOp[]): Promise<any[]>;
+    /** The binary read fast path, if the transport has one. `schemaHash` is the fingerprint of the schema the
+     *  calling client was generated from; the transport answers with the binary result buffer only for a
+     *  database on the same schema. `{ json }` is an already-parsed JSON answer (HTTP, when the server declined
+     *  binary); `null` means "no binary answer" and the client falls back to `exec`. */
+    queryBinary?(op: MarciOp, schemaHash: string): Promise<Uint8Array | {
+        json: any;
+    } | null>;
+    /** Watches, if the transport has them: registers the read `op` and tells `listener` whenever a commit may
+     *  have changed its result. Only signals — the re-read and the comparison are the query layer's. */
+    watch?(op: MarciOp, listener: WatchListener): WatchRegistration;
 };
 export type ModelTypes = {
     name: string;
@@ -259,6 +302,8 @@ export type IdArg<I> = I | BareId<I>;
  */
 export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles<Rows<T, Sel>[]> {
     readonly [__op]: Rows<T, Sel>[];
+    /** The rows now, then each time a commit changed them — see `ReadOp.watch`. */
+    watch(callback: (rows: Rows<T, Sel>[]) => void, options?: WatchOptions): Watch;
     readonly [__sub]: T["name"];
     readonly [__sel]: Effective<T, Sel>;
     /** Filter (marcidb `$where`). Repeated calls are ANDed. */
@@ -279,18 +324,18 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles
      */
     select<S extends T["query"] = T["scalars"]>(shape?: S): Query<T, S>;
     /** The first matching row or `null`. */
-    first(): Op<Rows<T, Sel> | null>;
+    first(): ReadOp<Rows<T, Sel> | null>;
     /** Row count; inside a select it becomes `{ count }` for the relation. */
-    count(): Op<number> & Sub<T["name"], {
+    count(): ReadOp<number> & Sub<T["name"], {
         $count: true;
     }>;
     /** @deprecated pass the filter through the chain: `db.user.where(w).count()` (removed in the next minor). */
     count(query: {
         $where?: T["where"];
-    }): Op<number> & Sub<T["name"], {
+    }): ReadOp<number> & Sub<T["name"], {
         $count: true;
     }>;
-    aggregate<A extends T["aggregate"]>(query: A): Op<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>;
+    aggregate<A extends T["aggregate"]>(query: A): ReadOp<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>;
     insert(data: T["insert"]): Op<T["id"]>;
     /** The new row by `select`'s shape — its defaults, dates and files as stored: one call, nothing to read back. */
     insert<S extends T["query"]>(data: T["insert"], options: {
@@ -322,9 +367,9 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles
      */
     deleteMany(): Op<number>;
     /** @deprecated use `.select(query)` — it takes the same object, merged with the chain (removed in the next minor). */
-    findMany<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q>[]>;
+    findMany<Q extends T["query"] = {}>(query?: Q): ReadOp<Rows<T, Q>[]>;
     /** @deprecated use `.select(query).first()` (removed in the next minor). */
-    findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>;
+    findFirst<Q extends T["query"] = {}>(query?: Q): ReadOp<Rows<T, Q> | null>;
 }
 /** What a journal can record. Only deletes so far. */
 export type JournalOp = "delete";
@@ -379,6 +424,8 @@ export type QueryLayerOptions = {
     /** 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 transport's watches (`MarciTransport.watch`); without it `op.watch` throws. */
+    watch?(op: MarciOp, listener: WatchListener): WatchRegistration;
 };
 /**
  * The query builder over a set of models and a `run` function. Returns `op(descriptor)` — a lazy operation

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

@@ -2,8 +2,10 @@ export { t, model, defineDb, ref } from "./db";
 export { ApiError } from "./errors";
 export { env, type Env } from "./env";
 export { channel } from "./channel";
+export { computed } from "./computed";
 export { pushChannel, type PushChannel, type PushMessage, type PushNotification, type PushTarget } from "./pushChannel";
 export { request } from "./context";
+export { ordered } from "./ordered";
 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. */

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

@@ -0,0 +1,18 @@
+/**
+ * `ordered(key, fn)` — calls with one key run one after another (server global). A worker runs its
+ * calls concurrently and every `await` lets another one in, so a read-check-write under a key (a
+ * room's code) needs the key's other calls to wait: a chain of promises per key, in this worker. A
+ * key is dropped when its chain drains; different keys run in parallel; nothing else is kept (the
+ * state stays in the database). Honest because one worker serves a project at a time — the runner
+ * lets the new worker of a deploy take calls only once the old one's are done (tools/runner/src/project.ts).
+ *
+ * Two rules: keep the body short (the key's other callers wait; a call has 30 s), and no `ordered` of a
+ * key from inside its own body (it would wait for itself) — that rejects. The keys a body holds follow
+ * its async chain in an AsyncLocalStorage: a body's sibling (another call of the same request) is not
+ * taken for re-entry, nor is a timer that fires after the body ended. The class comes over a global seam
+ * the host runtime installs (./runtime.ts): the bundle carries its own copy of this module and imports
+ * nothing. Without the seam the queue still works; only re-entry is not caught.
+ */
+export type OrderedKey = string | number;
+/** Run `fn` once every earlier call of `key` has finished; its result (or failure) is the call's. */
+export declare const ordered: <T>(key: OrderedKey, fn: () => T | Promise<T>) => Promise<T>;