lecodes-sdk 2.5.1 → 2.8.0

package/src/server/rateLimit.ts

@@ -0,0 +1,72 @@
+/**
+ * How often one caller may knock: a token bucket per key, written once for the hosts that serve a
+ * project's backend — the runner (tools/runner/src/http.ts, its main thread) and the dev backend of
+ * `lecodes dev` (tools/cli/src/dev/projectBackend.ts) — and the channel hub both of them run (./channelHub.ts).
+ *
+ *   endpoint calls   per (session, endpoint id): 20 a second, a burst of 40
+ *   subscriptions    per session (channels and computeds alike): 10 a second, a burst of 20
+ *
+ * The session is the caller's bearer token, or its ip when it has none yet (a first call). Over the limit
+ * a call is answered with the envelope `{ ok: false, status: 429, message: "Too many calls" }` — the app
+ * sees `RpcError(429)` — and a subscription with an `err` frame of the same status. The limits are
+ * constants for now (the docs' "The limits"), the same on le.codes and on the developer's machine.
+ *
+ * A bucket holds `burst` tokens and gains `rate` a second; a call takes one. A full bucket is the same as
+ * none, so the table forgets the ones that have filled up again (it is swept as it grows) and a host keeps
+ * only the callers of the last few seconds.
+ */
+
+export type RateLimit = {
+  /** tokens gained a second */
+  rate: number
+  /** what the bucket holds: how many calls may come at once */
+  burst: number
+}
+
+export const RATE_LIMITS = {
+  /** an endpoint's calls by one session */
+  call: { rate: 20, burst: 40 },
+  /** the subscriptions one session opens */
+  subscribe: { rate: 10, burst: 20 },
+} as const satisfies Record<string, RateLimit>
+
+/** What a refused call answers (the transport's envelope; the app sees `RpcError(429)`). */
+export const TOO_MANY_CALLS = { ok: false as const, status: 429, message: "Too many calls" }
+
+export type RateLimiter = {
+  /** One call of `key`: true when it may go, false over the limit (nothing is taken then). */
+  take(key: string): boolean
+}
+
+/** The key of a caller: its session token, or its ip while it has none. */
+export const callerKey = (session: string | null | undefined, ip: string | undefined): string =>
+  session ? `s:${session}` : `ip:${ip ?? "?"}`
+
+/** A table of buckets. `now` (ms, monotonic) is a test's knob. */
+export const createRateLimiter = (limit: RateLimit, opts: { now?: () => number } = {}): RateLimiter => {
+  const now = opts.now ?? (() => performance.now())
+  const buckets = new Map<string, { tokens: number, at: number }>()
+  /** how long an empty bucket takes to fill: one untouched for as long is the same as none */
+  const fullAfter = (limit.burst / limit.rate) * 1000
+  let sweepAt = 1024
+  const sweep = (t: number) => {
+    for (const [k, b] of buckets) if (t - b.at >= fullAfter) buckets.delete(k)
+    sweepAt = Math.max(1024, buckets.size * 2)
+  }
+  return {
+    take(key) {
+      const t = now()
+      let b = buckets.get(key)
+      if (!b) {
+        if (buckets.size >= sweepAt) sweep(t)
+        buckets.set(key, b = { tokens: limit.burst, at: t })
+      } else {
+        b.tokens = Math.min(limit.burst, b.tokens + ((t - b.at) / 1000) * limit.rate)
+        b.at = t
+      }
+      if (b.tokens < 1) return false
+      b.tokens -= 1
+      return true
+    },
+  }
+}

package/src/server/runtime.ts

@@ -1,21 +1,29 @@
 /**
  * Host side of a compiled server bundle — used by the runner (tools/runner) and by tests.
  * Imported normally (Node/Bun), NOT through chisel: the bundle carries its own SDK copy and talks
- * to this module only through globals (`__lecodesServer`, `__lecodesRequest`, `__lecodesPublish`).
+ * to this module only through globals (`__lecodesServer`, `__lecodesRequest`, `__lecodesPublish`,
+ * `__lecodesAsyncLocalStorage` — the class `ordered` keeps the keys a body holds in, ./ordered.ts;
+ * `__lecodesDbGate` — what the bundle's db client shows every operation to, ./computedHost.ts;
+ * `__lecodesPresence` — where `watchers` / `members` are answered, ./computedHost.ts `setPresenceProvider`).
  *
  *   evaluate the bundle (it sets globalThis.__lecodesServer)
  *   const server = loadServerModules()          // classify exports, name channels
  *   const invoke = createInvoker(server)        // validate → run in request context → envelope
  *   const subscribe = createSubscribeGuard(server)   // a channel's hooks → the subscriber's group
+ *   const computed = createComputedHost(server, { watch })   // computed subscriptions (./computedHost.ts)
  *   await invoke("notes.server.ts#listNotes", [20], { headers, ip })
  */
 
 import { AsyncLocalStorage } from "node:async_hooks"
+import { createHash, randomBytes } from "node:crypto"
 import type { ServerManifest } from "../compile/serverSplit"
 import type { AuthHost } from "./auth/host"
 import type { AuthState } from "./auth/types"
 import type { FilesHost, ResourceReader } from "./files/host"
 import { isChannel, isChannelGroup, setChannelPublisher, type ChannelRecord } from "./channel"
+import { isComputed, type ComputedRecord } from "./computed"
+import { ComputedWriteError, computedSubscriptions, installDbGate, readOnly, requestRead, setPresenceProvider, type ComputedHost } from "./computedHost"
+import type { WatchSource } from "./db/watch"
 import { isPushChannel, type PushChannelRecord } from "./pushChannel"
 import { setRequestProvider, type RequestContext } from "./context"
 import type { Db } from "./db/types"
@@ -27,6 +35,8 @@ export type ServerRegistration = { modules: Record<string, Record<string, unknow
 export type LoadedServer = {
   endpoints: Map<string, (...args: any[]) => unknown>
   channels: Map<string, ChannelRecord>
+  /** The computeds (`computed()` exports). Each is an endpoint too — its one-shot call, under the read-only rule. */
+  computeds: Map<string, ComputedRecord>
   /** The push channels (`pushChannel()` exports): their presence is what makes a response ask a signed-in device to register. */
   pushChannels: Map<string, PushChannelRecord>
   /** The project's `defineDb` handle — exported or not (the bundle registers it on globalThis); none or one. */
@@ -41,14 +51,19 @@ export const loadServerModules = (
   reg: ServerRegistration | undefined = (globalThis as any).__lecodesServer,
 ): LoadedServer => {
   if (!reg) throw new Error("loadServerModules: no server bundle registered (globalThis.__lecodesServer)")
-  const out: LoadedServer = { endpoints: new Map(), channels: new Map(), pushChannels: new Map(), dbs: [], manifest: reg.manifest }
+  const out: LoadedServer = { endpoints: new Map(), channels: new Map(), computeds: new Map(), pushChannels: new Map(), dbs: [], manifest: reg.manifest }
   for (const [mod, exports] of Object.entries(reg.modules)) {
     // the compile's word on each export (serverSplit.ts): a function that is not async is the
     // server's helper, never an endpoint — an old manifest without kinds counts every function
     const kinds = new Map((reg.manifest?.modules?.[mod] ?? []).map(e => [e.name, e.kind]))
     for (const [name, value] of Object.entries(exports)) {
       const id = `${mod}#${name}`
-      if (typeof value === "function") { if (kinds.get(name) !== "other") out.endpoints.set(id, value as (...args: any[]) => unknown) }
+      if (isComputed(value)) {
+        value.__id = id
+        out.computeds.set(id, value)
+        out.endpoints.set(id, (...args: unknown[]) => readOnly(id, () => value.__fn(...args)))
+      }
+      else if (typeof value === "function") { if (kinds.get(name) !== "other") out.endpoints.set(id, value as (...args: any[]) => unknown) }
       else if (isChannel(value)) { value.__id = id; out.channels.set(id, value) }
       else if (isPushChannel(value)) { value.__id = id; out.pushChannels.set(id, value) }
       else if (isDb(value)) out.dbs.push(value)
@@ -67,9 +82,12 @@ export const loadServerModules = (
 
 /** The wire envelope. `session` = a token the client must store from now on (new guest session / rotation).
  *  `push` = the device is asked to register for notifications: its session is signed in, has no push address,
- *  and the project has push channels (the transport registers, once per run — the OS prompt comes then). */
+ *  and the project has push channels (the transport registers, once per run — the OS prompt comes then).
+ *  `subscriber` = a subscription's only (the subscribe guard's, a computed's run), for the hub and never on
+ *  the wire: the subscriber's `request.session` when it has one — who the subscription is present as
+ *  (./channelHub.ts). A device that has none yet (no call or hook read it) is nobody, and not listed. */
 export type InvokeResult =
-  | { ok: true, result: unknown, session?: string, push?: true }
+  | { ok: true, result: unknown, session?: string, push?: true, subscriber?: number }
   | { ok: false, status: number, message: string, session?: string, push?: true }
 
 export type InvokerOptions = {
@@ -108,14 +126,65 @@ const dbStatus = (e: unknown): number | null => {
  */
 // One request store for endpoints AND channel hooks (a second store would steal the provider).
 const als = new AsyncLocalStorage<RequestContext>()
-const installProvider = () => setRequestProvider(() => als.getStore())
+const installProvider = () => {
+  // a read of the request in a computed's run makes that run its subscriber's (./computedHost.ts shared runs)
+  setRequestProvider((quiet) => {
+    if (!quiet) requestRead()
+    return als.getStore()
+  })
+  installDbGate()
+  ;(globalThis as { __lecodesAsyncLocalStorage?: unknown }).__lecodesAsyncLocalStorage = AsyncLocalStorage
+}
+
+/** A token the client transport may hold: what this file and the auth host mint (32 random bytes, base64url). */
+const DEVICE_TOKEN = /^[A-Za-z0-9_-]{32,128}$/
+/** A token minted by `request.session` (no sign-in): it rides on the call's envelope, as a guest session's does. */
+const minted = new WeakMap<RequestContext, string>()
+
+/**
+ * `request.session` — decided here only, for endpoints and channel hooks, on every host. With sign-in it is
+ * the request's session row (`db.auth.sessionId`, resolved before the call). Without, a number derived from
+ * the bearer token the transport keeps per backend: the same on every worker and host for as long as the
+ * device keeps the token, and nothing is stored. A hash, not the token: the id may be shown to other players,
+ * the token is the device's password. Read lazily: the first read in a call that carries no usable token
+ * mints one and the envelope hands it to the transport — a call that never asks changes nothing.
+ *
+ * Answers the session as it stands, minting nothing (undefined = none yet): what a subscription is present as.
+ */
+const defineSession = (rc: RequestContext, auth: AuthHost | null): (() => number | undefined) => {
+  let id: number | undefined
+  const peek = () => {
+    if (auth?.enabled) return (rc.auth as AuthState | undefined)?.sessionId
+    if (id !== undefined) return id
+    if (!rc.sessionToken || !DEVICE_TOKEN.test(rc.sessionToken)) return undefined
+    // 52 bits of sha256: a safe integer, the way a row id is one
+    return id = Number.parseInt(createHash("sha256").update(rc.sessionToken).digest("hex").slice(0, 13), 16)
+  }
+  Object.defineProperty(rc, "session", {
+    configurable: true,
+    get: () => {
+      if (!auth?.enabled && id === undefined && (!rc.sessionToken || !DEVICE_TOKEN.test(rc.sessionToken))) {
+        rc.sessionToken = randomBytes(32).toString("base64url")
+        minted.set(rc, rc.sessionToken)
+      }
+      return peek()
+    },
+  })
+  return peek
+}
+/** A subscription's envelope names its subscriber, when there is one (`InvokeResult.subscriber`). */
+const subscriberOf = (peek: () => number | undefined): { subscriber?: number } => {
+  const n = peek()
+  return n === undefined ? {} : { subscriber: n }
+}
 
 // A token minted/rotated during the call rides on the envelope (the client transport stores it); so does the
 // request to register the device for notifications, when a signed-in session has no address and there are
 // push channels to hear.
 const envelope = (server: LoadedServer) => (r: InvokeResult, rc: RequestContext): InvokeResult => {
   const s = rc.auth as AuthState | undefined
-  const out = s?.issuedToken ? { ...r, session: s.issuedToken } : r
+  const token = s?.issuedToken ?? minted.get(rc)
+  const out = token ? { ...r, session: token } : r
   return s && s.userId !== null && !s.pushAddress && server.pushChannels.size ? { ...out, push: true } : out
 }
 
@@ -133,6 +202,7 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
     if (!fn) return { ok: false, status: 404, message: `Unknown endpoint ${id}` }
     if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
     const rc: RequestContext = { ...ctx, id }
+    defineSession(rc, auth)
     try {
       // an upload is an argument like any other once it is adopted: validated, then passed
       if (files) args = await files.adopt(args, rc)
@@ -146,6 +216,8 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
       if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
       if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
       onError(id, e)
+      // a computed's one-shot call that wrote: the rule it broke, in its words
+      if (e instanceof ComputedWriteError) return withSession({ ok: false, status: 500, message: e.message }, rc)
       return withSession({ ok: false, status: 500, message: "Internal error" }, rc)
     } finally {
       // in the request's scope: the urls of what the call returned are already made, this is the cleanup
@@ -249,6 +321,7 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
     if (!ch) return { ok: false, status: 404, message: `Unknown channel ${channelId}` }
     if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
     const rc: RequestContext = { ...ctx, id: channelId }
+    const peek = defineSession(rc, auth)
     try {
       if (validate && ch.__groupBy && params?.[channelId]) validateArgs(params[channelId], args)
       if (auth) await auth.resolve(rc)
@@ -257,7 +330,7 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
         return ch.__groupBy ? await ch.__groupBy(...args) : null
       })
       if (group !== null && !isChannelGroup(group)) throw new Error(`groupBy answered ${group === undefined ? "nothing" : typeof group} — a group is a string or a number`)
-      return withSession({ ok: true, result: group }, rc)
+      return withSession({ ok: true, result: group, ...subscriberOf(peek) }, rc)
     } catch (e) {
       const status = apiStatus(e) ?? dbStatus(e)
       if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
@@ -268,5 +341,50 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
   }
 }
 
-export { setChannelPublisher, setRequestProvider }
+export type ComputedHostOptions = Pick<InvokerOptions, "validate" | "onError" | "auth"> & {
+  /** Where the reads of a computed are watched (./db/watch.ts): the database's source. `null` = this host
+   *  watches nothing — a computed that reads the database cannot be subscribed to. */
+  watch: WatchSource | null
+  /** Where a new value goes: `(id, sub, envelope)`. Default: the host's channel publisher (`setChannelPublisher`). */
+  publish?: (ch: string, group: number, envelope: InvokeResult) => void
+}
+
+/**
+ * The computed subscriptions of a worker (./computedHost.ts): `start(id, args, ctx, sub)` runs computed
+ * `id` for the hub's subscription `sub` the way a channel's hooks run — `args` validated like an
+ * endpoint's, in the subscriber's request scope (`request.session`, `db.auth`) — and keeps it fresh from
+ * then on; `end(sub)` lets it go. The envelope's `result` is the value. A run that read nothing of the
+ * request is the run of every subscription of its key (the export and its arguments): one run per change.
+ */
+export const createComputedHost = (server: LoadedServer, opts: ComputedHostOptions): ComputedHost => {
+  installProvider()
+  const validate = opts.validate ?? true
+  const onError = opts.onError ?? ((id, e) => console.error(`[server] ${id}:`, e))
+  const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
+  const auth = opts.auth ?? null
+  const withSession = envelope(server)
+  const run = async (id: string, args: unknown[], ctx: Omit<RequestContext, "id">, around: <T>(fn: () => T, me: () => number | undefined) => T): Promise<InvokeResult> => {
+    const c = server.computeds.get(id)
+    if (!c) return { ok: false, status: 404, message: `Unknown computed ${id}` }
+    if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
+    const rc: RequestContext = { ...ctx, id }
+    const peek = defineSession(rc, auth)
+    try {
+      if (validate && params?.[id]) validateArgs(params[id], args)
+      if (auth) await auth.resolve(rc)
+      const value = await als.run(rc, () => around(() => c.__fn(...args), peek))
+      return withSession({ ok: true, result: value === undefined ? null : value, ...subscriberOf(peek) }, rc)
+    } catch (e) {
+      const status = apiStatus(e) ?? dbStatus(e)
+      if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
+      if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
+      onError(id, e)
+      if (e instanceof ComputedWriteError) return withSession({ ok: false, status: 500, message: e.message }, rc)
+      return withSession({ ok: false, status: 500, message: "Internal error" }, rc)
+    }
+  }
+  return computedSubscriptions({ run, watch: opts.watch, publish: opts.publish })
+}
+
+export { setChannelPublisher, setRequestProvider, setPresenceProvider }
 export { setPushSender } from "./pushChannel"

package/src/ui/UIBottomSheet.ts

@@ -1,4 +1,4 @@
-import { ModalElement, type UIModalStyle } from "./UIModal"
+import { ModalElement, type UIModalShow, type UIModalStyle } from "./UIModal"
 import type { UIWidget } from "./UIWidget"
 import { buildUI, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
 import { TREE_FLAG_DETENT } from "./tree"
@@ -15,14 +15,18 @@ const SHEET_ANIM_MS = 250
  * node type — docs/bottom-sheet-plan.md): hosts without sheet support show a static bottom panel.
  *
  * With detents, content lays out at the HIGHEST detent's size; lower detents show the top
- * slice. The scrim, `onOpen`/`onClose`, back-button and scrim-tap dismissal all come from the
- * modal machinery.
+ * slice. The scrim, `bindShow` / `onDismiss`, `onOpen` / `onClose` all come from the modal
+ * machinery; the drag below the lowest detent is the sheet's third dismissal gesture, routed like
+ * the scrim tap. The host hears whether a drag may dismiss (`sheetDismissible`):
+ * `dismissible(false)`, or a bound sheet with no `onDismiss`, resists instead.
  *
  * ```ts
- * const actions = UIBottomSheet(rows).style({ bgColor: "#1c1c1e", borderRadius: 16 })   // content-sized
+ * const actions = UIBottomSheet(rows).style({ bgColor: "#1c1c1e", borderRadius: 16 })   // content-sized, show()
+ *
+ * const card = UIBottomSheet(place).bindShow(() => data.value.pick != null).onDismiss(on.unpick)   // the data's
  *
  * const mapSheet = UIBottomSheet(results).style({ bgColor: "#1c1c1e", borderRadius: 16 })
- *   .detents([0.3, 0.6, 1])
+ *   .detents([0.3, 0.6, 1]).dismissible(false)                                            // persistent: show() once placed
  *   .onDetent(i => map.setPadding(...))
  * ```
  */
@@ -38,16 +42,21 @@ export interface UIBottomSheet extends UIWidget {
   /** Fires on every settle: a finger snap on native hosts, or a `setDetent()` call. */
   onDetent(callback: (index: number) => void): this,
 
-  /** Mount and slide in to the current detent. No-op while already open. */
+  /** Bind the shown state, as on `UIModal`: a function of the data (`bindShow(() =>
+   *  data.value.pick != null)`) or a signal. */
+  bindShow(value: UIModalShow): this,
+  /** Slide in to the current detent. No-op while already shown. Bound: as on `UIModal`. */
   show(): void,
-  /** Slide out, fade the scrim, then unmount. No-op while closed. */
+  /** Slide out, fade the scrim. No-op while hidden. */
   hide(): void,
-  /** True from `show()` until `hide()` starts. */
-  readonly isOpen: boolean,
 
-  /** Called when `show()` mounts the sheet. */
+  /** The user asked to close — a scrim tap, the back press, a drag below the lowest detent. The
+   *  one hook for all three; a bound sheet needs it to be dismissible at all (it resists the drag
+   *  otherwise). When the callback leaves the sheet open, it slides back to its detent. */
+  onDismiss(callback: () => void): this,
+  /** Called when the sheet opens. */
   onOpen(callback: () => void): this,
-  /** Called when the sheet starts closing — scrim tap, back button, drag-dismiss, or `hide()`. */
+  /** Called when the sheet starts closing — a dismissal, `hide()`, the data. */
   onClose(callback: () => void): this,
   /** `dismissible(false)`: scrim taps, the back button and dragging below the lowest detent no
    *  longer close the sheet (a drag collapses to the lowest detent instead). Default `true`. */
@@ -72,13 +81,23 @@ export class BottomSheetElement extends ModalElement {
   }
 
   /** @internal The host's GESTURE settles only (programmatic `setDetent` fires JS-side); `-1` =
-   *  dragged below the lowest detent while dismissible. */
+   *  dragged below the lowest detent while dismissible — a dismissal like the scrim tap. */
   _emitDetent(index: number): void {
-    if (index < 0) { this.hide(); return }
+    if (index < 0) { this._dismiss(); return }
     this._detent = index
     for (const callback of this._detentListeners) callback(index)
   }
 
+  /** @internal The dismiss callbacks left the sheet open (the data said so): the host slid it out
+   *  on the drag, so put it back on its detent. */
+  override _afterDismiss(): void {
+    if (this._shown) this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
+  }
+
+  override _syncDismissible(): void {
+    this.style({ sheetDismissible: this._dismissAllowed() ? 1 : 0 } as UIBottomSheetStyle)
+  }
+
   detents(list: number[]): this {
     const sorted = [...list].filter(d => d > 0).sort((a, b) => a - b)
     if (sorted.length === 0) return this
@@ -108,23 +127,13 @@ export class BottomSheetElement extends ModalElement {
     return this
   }
 
-  override show(): void {
-    if (this._shown) return
-    // Before the mount, so the built node carries the target and hosts play the entrance to it.
-    this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
-    super.show()
-  }
-
-  override hide(): void {
-    if (!this._shown) return
-    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; the hide follows
-    super.hide()
-  }
-
-  override dismissible(enabled: boolean): this {
-    super.dismissible(enabled)
-    this.style({ sheetDismissible: enabled ? 1 : 0 } as UIBottomSheetStyle)
-    return this
+  /** @internal The display write is the moment the host enters or leaves: the detent rides along —
+   *  written BEFORE the display, so the node carries the target when the host plays the entrance
+   *  to it (`-1` on a hide: the host slides out, the hide follows). Every way of opening goes
+   *  through here: show() / hide(), `open()`, the binding. */
+  override _writeDisplay(display: "flex" | "none"): void {
+    this.style({ sheetDetent: display === "flex" ? this._detent : -1 } as UIBottomSheetStyle)
+    super._writeDisplay(display)
   }
 }
 

package/src/ui/UIModal.ts

@@ -3,6 +3,7 @@ import { buildUI, type BaseStyle, type ChildrenFn, type Color, type DrawableStyl
 import type { TransitionPose } from "./presentable"
 import { _widgetPoseId } from "./transitions"
 import { tree } from "./tree"
+import { createBinding, disposeBinding, flushEffects, type Signal } from "../core/signals"
 
 export type UIModalStyle = UIWidgetStyle
 
@@ -15,27 +16,49 @@ export type UIModalTransition = DrawableStyle & BaseStyle & {
   duration?: number,
 }
 
+/** What `bindShow()` takes: a function of the data, or a signal the modal also writes (`false` on
+ *  a dismissal, `show()` / `hide()` set it). */
+export type UIModalShow = (() => boolean) | Signal<boolean>
+
 const MODAL_ANIM_MS = 200
+const SHOW_BINDING = "#show"
 
 /**
  * A dialog: a `UIWidget` with the modal boilerplate built in. Comes with a scrim
- * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), animates on `show()`/`hide()` and on
- * a state block flipping its `display` (a 200 ms fade by default — swap the pose via
- * `transition()`; the runtime plays it as tracks that never touch the style), and closes itself
- * on a scrim tap or the Android back button (disable via `dismissible(false)`). Everything else
- * is a plain widget: declare it where it belongs — among its screen's children, hidden until a
- * tap (`display: "none"`), or shown with `show()` from anywhere, which puts a parentless modal in
- * the app layer. A dialog bound to data (its display from a binding) is declared
- * `dismissible(false)` and routes `onOverlayTap` / `onBack` into the data's dismiss, so the data
- * stays what the screen shows.
+ * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), is HIDDEN until shown, animates on
+ * every show / hide (a 200 ms fade by default — swap the pose via `transition()`; the runtime
+ * plays it as tracks that never touch the style).
+ *
+ * One state, shown or not, driven one of two ways:
+ * - `show()` / `hide()` from code — an action sheet opened by a button;
+ * - `bindShow(…)`: a function of the data (`bindShow(() => data.value.confirm)` — the data is the
+ *   truth, `show()` / `hide()` are refused) or a `Signal<boolean>` the modal reads AND writes.
+ *
+ * A dismissal — the scrim tap, the back press, a sheet dragged below its lowest detent — is ONE
+ * request, `onDismiss`. By default it hides an unbound modal and writes `false` into a bound
+ * signal; a bound function has nowhere to write, so a modal bound to one without `onDismiss`
+ * cannot be dismissed (a forced choice — the same as `dismissible(false)`). `display` is not a
+ * modal's switch: a `.style({ display })` on it throws (a bound display died on the first
+ * dismissal, which wrote a static `display: "none"` over the binding — the dialog never opened
+ * again).
  */
 export interface UIModal extends UIWidget {
-  /** Show and play the entrance transition. No-op while already open. */
+  /**
+   * Bind the shown state. A function: the modal follows the data, and `show()` / `hide()` are
+   * errors — flip the data (`onDismiss` is where a dismissal goes). A signal: read and written —
+   * a dismissal sets it `false`, `show()` / `hide()` set it.
+   *
+   * ```ts
+   * UIModal(...).bindShow(() => data.value.confirm).onDismiss(on.cancel)   // the data is the truth
+   * UIModal(...).bindShow(confirmOpen)                                       // a Signal<boolean>
+   * ```
+   */
+  bindShow(value: UIModalShow): this,
+  /** Show and play the entrance transition. No-op while already shown. Bound to a signal: writes
+   *  `true` into it; bound to a function: an error (flip the data). */
   show(): void,
-  /** Play the exit transition, then hide. No-op while closed or already closing. */
+  /** Play the exit transition, then hide. No-op while hidden. Bound: as `show()`. */
   hide(): void,
-  /** True from `show()` until `hide()` starts (already false during the exit animation). */
-  readonly isOpen: boolean,
 
   /**
    * Replace the show/hide animation. `hidden` is the off-screen pose — `show()` animates from
@@ -49,13 +72,17 @@ export interface UIModal extends UIWidget {
    */
   transition(hidden: UIModalTransition): this,
 
-  /** Called when the modal opens — `show()`, or a state block flipping its display. */
+  /** The user asked to close: a scrim tap, the back press, a sheet dragged below its lowest
+   *  detent. Replaces the default (hide, or `false` into the signal): the callback decides —
+   *  usually the action that flips the data the modal is bound to. */
+  onDismiss(callback: () => void): this,
+  /** Called when the modal is shown — whoever showed it. */
   onOpen(callback: () => void): this,
-  /** Called when the modal starts closing — scrim tap, back button, a `hide()` call, or a state
-   *  block flipping its display. */
+  /** Called when the modal starts hiding — whoever hid it. */
   onClose(callback: () => void): this,
-  /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
-   *  (forced-choice dialogs, a dialog whose display is bound to data). Default `true`. */
+  /** `dismissible(false)`: the dismissal gestures are off — the scrim tap does nothing, the back
+   *  press is swallowed, a sheet resists below its lowest detent (a forced choice, the persistent
+   *  map sheet). Default `true`. */
   dismissible(enabled: boolean): this,
 }
 
@@ -64,16 +91,32 @@ export class ModalElement extends WidgetElement {
   _transition: UIModalTransition = { opacity: 0 }
   readonly _openListeners: (() => void)[] = []
   readonly _closeListeners: (() => void)[] = []
+  readonly _dismissListeners: (() => void)[] = []
+  /** @internal `bindShow` was called: show() / hide() are not the modal's to call (a signal's: they write it). */
+  _bound = false
+  /** @internal The signal `bindShow()` was given, which a dismissal writes. */
+  _showSignal?: Signal<boolean>
   private _poseObj?: TransitionPose
   private _poseKey = ""
 
   constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn) {
-    super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", ...style }, children)
-    this.onOverlayTap(() => { if (this._dismissible) this.hide() })
-    this.onBack(() => { if (this._dismissible) this.hide() })
+    // Hidden by default: a dialog is shown, never found open — show() / bindShow() flip it.
+    super("widget", { overlayColor: "rgba(0, 0, 0, 0.5)", display: "none", ...style }, children)
+    this.onOverlayTap(() => this._dismiss())
+    this.onBack(() => this._dismiss())
     this._syncPose()
   }
 
+  /** @internal `display` is not a modal's switch. Refused on every write of the app's — `.style({
+   *  display })`, `el.style.display =` — and let through for the widget's own (`_ownWrite`). During
+   *  the constructor the field is still undefined (it is initialised after `super()`), which lets
+   *  the default `display: "none"` through. */
+  _mapStyle(style: any): void {
+    if ("display" in style && this._ownWrite === false) {
+      throw new Error("a modal's `display` is not its switch — a dialog, a sheet or a menu is shown with show() / hide(), or bound to the data with bindShow(…), never by its display")
+    }
+  }
+
   // The pose the runtime plays on a display flip: the hidden pose + its duration, plus the scrim
   // fade — only when the modal actually has a scrim (overlayColor: null opts out; a track on a
   // null scrim would create the intercepting layer) and the pose doesn't drive the scrim itself.
@@ -106,27 +149,80 @@ export class ModalElement extends WidgetElement {
     return this
   }
 
+  bindShow(value: UIModalShow): this {
+    if (this._fx !== undefined) disposeBinding(this, SHOW_BINDING)
+    this._bound = true
+    let read: () => boolean
+    if (typeof value === "function") { this._showSignal = undefined; read = value }
+    else { this._showSignal = value; read = () => value.value }
+    // The first value is the START state (bound before the modal is placed, it shows with its
+    // place); every later one is a flip, played like a show() / hide().
+    let initial = true
+    createBinding(this, SHOW_BINDING, () => {
+      const shown = !!read()
+      if (this._h.id !== 0) {
+        if (initial && tree().parent(this._h.id) === 0) this._writeDisplay(shown ? "flex" : "none")
+        else this._setOpen(shown)
+      }
+      initial = false
+    })
+    this._syncDismissible()
+    return this
+  }
+
   override show(): void {
-    if (this._shown) return
-    this._syncPose()
-    super.show()
+    if (this._showSignal) { this._showSignal.value = true; return }
+    if (this._bound) { console.error("show() on a modal bound with bindShow(() => …) — flip the data it follows"); return }
+    this._setOpen(true)
   }
 
   override hide(): void {
-    if (!this._shown) return
+    if (this._showSignal) { this._showSignal.value = false; return }
+    if (this._bound) { console.error("hide() on a modal bound with bindShow(() => …) — flip the data it follows"); return }
+    this._setOpen(false)
+  }
+
+  override _setOpen(open: boolean): void {
     this._syncPose()
-    super.hide()
+    super._setOpen(open)
+  }
+
+  /** @internal A dismissal gesture — the scrim tap, the back press, a sheet dragged below its
+   *  lowest detent — asks to close. The default hides an unbound modal and writes `false` into a
+   *  bound signal; a bound function has no default (the data decides, through `onDismiss`). */
+  _dismiss(): void {
+    if (!this._dismissible) return
+    if (this._dismissListeners.length > 0) {
+      for (const callback of this._dismissListeners.slice()) callback()
+      flushEffects()          // the data's flip lands now, so the sheet below knows whether it stays
+      this._afterDismiss()
+      return
+    }
+    if (this._showSignal) { this._showSignal.value = false; return }
+    if (!this._bound) this._setOpen(false)
   }
 
-  get isOpen(): boolean {
-    return this._shown
+  /** @internal After the dismiss callbacks: a sheet still shown puts itself back on its detent. */
+  _afterDismiss(): void {}
+
+  /** @internal Can a gesture close it? What the host is told (a sheet's drag resists otherwise). */
+  _dismissAllowed(): boolean {
+    return this._dismissible && (!this._bound || this._showSignal !== undefined || this._dismissListeners.length > 0)
   }
 
+  /** @internal The host's copy of `_dismissAllowed()` (a sheet writes `sheetDismissible`). */
+  _syncDismissible(): void {}
+
   /** @internal onOpen / onClose follow the intent, whoever flipped it. */
   override _shownChanged(shown: boolean): void {
     for (const callback of (shown ? this._openListeners : this._closeListeners).slice()) callback()
   }
 
+  onDismiss(callback: () => void): this {
+    this._dismissListeners.push(callback)
+    this._syncDismissible()
+    return this
+  }
   onOpen(callback: () => void): this {
     this._openListeners.push(callback)
     return this
@@ -137,15 +233,16 @@ export class ModalElement extends WidgetElement {
   }
   dismissible(enabled: boolean): this {
     this._dismissible = enabled
+    this._syncDismissible()
     return this
   }
 }
 
 const makeModal = (style: any, children: any) => new ModalElement(style, children)
 
-/** Create a modal dialog (see {@link UIModal}): declare it among its screen's children with
- *  `display: "none"` and `show()` it from a tap, or `show()` a parentless one from anywhere.
- *  Same argument forms as `UIColumn`. */
+/** Create a modal dialog (see {@link UIModal}): give it to its screen (`.widgets(dialog)`) and
+ *  `show()` it from a tap, bind it to the data with `bindShow(() => …)`, or `show()` a parentless
+ *  one from anywhere. Same argument forms as `UIColumn`. */
 export function UIModal(...children: UIChildArg[]): UIModal;
 export function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
 export function UIModal(...args: any[]): UIModal {