lecodes-sdk 2.6.0 → 2.8.0

package/package.json

@@ -40,10 +40,10 @@
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4",
-    "marcidb-embedded": "^0.15.0",
+    "marcidb-embedded": "^0.18.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.6.0",
+  "version": "2.8.0",
   "files": [
     "src",
     "dist",

package/src/compile/serverSplit.ts

@@ -2,14 +2,15 @@
  * The client/server split of a project (docs/backend-plan.md §4).
  *
  * `*.server.ts` files never reach the client bundle: `compileProject` swaps each one for a STUB
- * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__pushChannel`, `__serverOnly` — client SDK
+ * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__computed`, `__pushChannel`, `__serverOnly` — client SDK
  * globals, src/runtime/rpc.ts), so `import { listNotes } from "./notes.server"` in client code keeps
  * its types and calls the server. `compileServerBundle` bundles the same files with the SERVER inject
  * behind a synthetic entry that registers every module on `globalThis.__lecodesServer` (chisel keeps
  * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
  *
  * Export kinds are found by a static scan (no TS program needed): a function export is an
- * endpoint, a `channel<…>()…` export is a channel, a `pushChannel<…>()` export a push channel, anything else is server-only.
+ * endpoint, a `channel<…>()…` export is a channel, a `computed(…)` export a computed (an endpoint the app
+ * may also subscribe to), a `pushChannel<…>()` export a push channel, anything else is server-only.
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
@@ -26,11 +27,12 @@ export const serverModuleId = (path: string) => path.split("\\").join("/").repla
 
 /**
  * What an export of a server module is to the app: `fn` = an endpoint — an ASYNC function, called
- * over the network; `channel` = a channel; `other` = server-only — a model, the db, a constant, or
+ * over the network; `channel` = a channel; `computed` = a computed (../server/computed.ts): called like
+ * an endpoint, or subscribed to; `push` = a push channel; `other` = server-only — a model, the db, a constant, or
  * a helper: a function that is not async is used by server files alone, and the app's import of
  * it is refused at compile time (serverTypes.ts), never a call that silently holds a promise.
  */
-export type ServerExportKind = "fn" | "channel" | "push" | "other"
+export type ServerExportKind = "fn" | "channel" | "computed" | "push" | "other"
 export type ServerExport = { name: string, kind: ServerExportKind }
 
 // ───────────────────────────── static export scan ─────────────────────────────
@@ -86,6 +88,7 @@ const IDENT = "[A-Za-z_$][\\w$]*"
 const classifyInit = (init: string): ServerExportKind => {
   const s = init.trimStart()
   if (/^channel\s*[<(]/.test(s)) return "channel"
+  if (/^computed\s*[<(]/.test(s)) return "computed"
   if (/^pushChannel\s*[<(]/.test(s)) return "push"
   if (/^async\s+function\b/.test(s)) return "fn"
   if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
@@ -164,6 +167,7 @@ export const serverStubSource = (path: string, exports: ServerExport[], serverUr
     const id = JSON.stringify(`${mod}#${name}`)
     if (kind === "fn") return `export const ${name} = __rpc(${url}, ${id})`
     if (kind === "channel") return `export const ${name} = __channel(${url}, ${id})`
+    if (kind === "computed") return `export const ${name} = __computed(${url}, ${id})`
     if (kind === "push") return `export const ${name} = __pushChannel(${url}, ${id})`
     return `export const ${name} = __serverOnly(${id})`
   })

package/src/compile/serverTypes.ts

@@ -14,7 +14,8 @@
  * "endpoint args must be JSON-serializable". Return types are not validated.
  *
  * A channel's `groupBy(fn)` is the same case: `fn` is called with what the app passed to
- * `subscribe`, so its parameters get a schema under the channel's id.
+ * `subscribe`, so its parameters get a schema under the channel's id; and so is a `computed(fn)` —
+ * called and subscribed to with the same arguments, under the computed's id.
  *
  * `typescript` is loaded lazily (it's a devDependency of the SDK and a dependency of the platform
  * compile step); the browser-safe parts of the compiler never import this module's runtime.
@@ -252,6 +253,11 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
         if (!hook) { params[id] = []; continue }
         type = checker.getTypeAtLocation(hook)
         where = `${id}.groupBy`
+      } else if (ex.kind === "computed") {
+        // `computed` too: its function is the call's first argument
+        const fn = computedFn(ts, decl)
+        if (!fn) { params[id] = []; continue }
+        type = checker.getTypeAtLocation(fn)
       } else {
         type = checker.getTypeOfSymbolAtLocation(sym, decl)
       }
@@ -261,8 +267,8 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
       for (const p of sig.getParameters()) {
         const pd = p.valueDeclaration as import("typescript").ParameterDeclaration | undefined
         // nothing here gives a hook's parameter a type but its own annotation — without one it is `any`, unchecked
-        if (ex.kind === "channel" && pd && !pd.type && !pd.initializer) {
-          problems.push(`${where}(${p.name}): give the parameter a type — it is what the app passes to subscribe, and it is checked against it`)
+        if ((ex.kind === "channel" || ex.kind === "computed") && pd && !pd.type && !pd.initializer) {
+          problems.push(`${where}(${p.name}): give the parameter a type — it is what the app passes to ${ex.kind === "channel" ? "subscribe" : "the call and to subscribe"}, and it is checked against it`)
           continue
         }
         const ptype = checker.getTypeOfSymbolAtLocation(p, pd ?? decl)
@@ -294,6 +300,14 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
   return { params, warnings }
 }
 
+/** The function a computed export is made of (`computed(async (…) => …)`). */
+const computedFn = (ts: TS, decl: import("typescript").Declaration): import("typescript").Expression | null => {
+  let node: import("typescript").Expression | undefined = ts.isVariableDeclaration(decl) ? decl.initializer : undefined
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node))) node = node.expression
+  if (node && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "computed") return node.arguments[0] ?? null
+  return null
+}
+
 /** The function given to `.groupBy(…)` in a channel export's initializer (`channel<M>().authorize(…).groupBy(fn)`). */
 const groupByHook = (ts: TS, decl: import("typescript").Declaration): import("typescript").Expression | null => {
   let node: import("typescript").Expression | undefined = ts.isVariableDeclaration(decl) ? decl.initializer : undefined

package/src/inject.ts

@@ -43,8 +43,9 @@ export { WebSocket } from "./runtime/net"
 // Multiplayer (docs/multiplayer-plan.md): roles, players, JSON messages over the _creatorNet transport.
 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"
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
-// only ever imports its server functions (docs/backend-plan.md §4).
-export { __rpc, __channel, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc"
+// only ever imports its server functions (docs/backend-plan.md §4) — and reads `online`, whether the
+// transport reaches the backend.
+export { __rpc, __channel, __computed, __pushChannel, __serverOnly, RpcError, online } from "./runtime/rpc"
 // The font() compile macro's generated `.__fonts.ts` modules call this per face (UI tree + Font2D).
 export { __registerFont } from "./ui/fonts"
 // What a screen asks of the server, as reactive state: a request a screen follows, an action with its own busy / error.

package/src/runtime/firstCall.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 const firstCallGate = (): FirstCallGate => {
+  /** undefined: no call yet; a promise: the first call is out; null: it came back */
+  let first: Promise<void> | null | undefined
+  return async (hasToken, send) => {
+    if (!hasToken()) {
+      if (first) await first
+      else if (first === undefined) {
+        let release!: () => void
+        first = new Promise<void>((r) => { release = r })
+        try { return await send() } finally { first = null; release() }
+      }
+    }
+    return send()
+  }
+}

package/src/runtime/rpc.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,14 +19,20 @@
  * 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 { fetch, File, FormData } from "./fetch"
+import { signal, type Computed } from "../core/signals"
 import { localStorage } from "./storage"
 import { WebSocket } from "./net"
 import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
 import type { ChannelSubscription } from "../server/channel"
+import type { ComputedOptions } from "../server/computed"
 import { _pushRuntime } from "./pushSeam"
+import { firstCallGate, type FirstCallGate } from "./firstCall"
 
 /** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
  *  (0 = the request itself failed: no network / no server). */
@@ -38,6 +45,32 @@ export class RpcError extends Error {
   }
 }
 
+// ───────────────────────────── online ─────────────────────────────
+
+/** The backends the transport did not reach the last time it tried — a call that never got there, a
+ *  socket that dropped and is trying again — by server URL. */
+const unreachable = new Set<string>()
+const reachable = signal(true)
+/** What a call or the socket just learned of one backend: it answered (an error answer is an answer),
+ *  or it could not be reached. */
+const heard = (serverUrl: string, answered: boolean) => {
+  if (answered) unreachable.delete(serverUrl)
+  else unreachable.add(serverUrl)
+  reachable.value = unreachable.size === 0
+}
+
+/**
+ * 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 const online: Computed<boolean> = reachable
+
+/** @internal forget what was learned of every backend (a test's teardown: `online` is module state). */
+export const _resetOnline = () => { unreachable.clear(); reachable.value = true }
+
 // ───────────────────────────── session token ─────────────────────────────
 
 const sessionKey = (serverUrl: string) => `lecodes.session:${serverUrl}`
@@ -61,6 +94,15 @@ const setSession = (serverUrl: string, token: string | null) => {
 
 const noServer = (id: string) => new RpcError(0, `Endpoint ${id}: the project has no deployed server (compile with serverUrl)`)
 
+/** A device with no token yet: its first call to a backend goes alone and the calls behind it wait
+ *  (./firstCall.ts — the rule a host that calls as a device follows too). One gate per backend per run. */
+const firstCall = new Map<string, FirstCallGate>()
+const gateOf = (serverUrl: string) => {
+  let gate = firstCall.get(serverUrl)
+  if (!gate) { gate = firstCallGate(); firstCall.set(serverUrl, gate) }
+  return gate
+}
+
 /** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
 export const __rpc = (serverUrl: string, id: string) => {
   const call = async (...args: unknown[]): Promise<any> => {
@@ -68,6 +110,22 @@ export const __rpc = (serverUrl: string, id: string) => {
     // an optional argument left out is `undefined` in its place — JSON has no such value (it would
     // travel as null and fail the parameter's type), and it is the last ones
     while (args.length && args[args.length - 1] === undefined) args.pop()
+    return gateOf(serverUrl)(() => !!getSession(serverUrl), () => send(args))
+  }
+  // what the call tells of the backend goes to `online`: an RpcError of status 0 never reached it, any
+  // other end of the call (an error answer too) did — an error thrown before sending (an argument JSON
+  // cannot carry) says nothing of it
+  const send = async (args: unknown[]): Promise<any> => {
+    try {
+      const result = await post(args)
+      heard(serverUrl, true)
+      return result
+    } catch (e) {
+      if (e instanceof RpcError) heard(serverUrl, e.status !== 0)
+      throw e
+    }
+  }
+  const post = async (args: unknown[]): Promise<any> => {
     const headers: Record<string, string> = {}
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
@@ -118,10 +176,21 @@ type Options = {
   error?: (e: RpcError) => void
 }
 /** `group` is the server's answer (the `ok` frame): undefined until it came. `refused` = the server
- *  said no under that session: the subscription is kept and asked again under another one. */
+ *  said no under that session: the subscription is kept and asked again under another one. `computed`
+ *  = a computed's (`__computed`): the `ok` carries a value, and `last` is the JSON of the one handed on. */
 type Sub = {
   id: number, ch: string, args: unknown[], handler: (message: any) => void, options: Options,
   group: ChannelGroup | null | undefined, refused: { session: string | null } | null,
+  computed: boolean, last: string | undefined,
+}
+const subFrame = (s: Sub): ClientFrame => s.computed ? { t: "sub", id: s.id, ch: s.ch, args: s.args, computed: true } : { t: "sub", id: s.id, ch: s.ch, args: s.args }
+/** A computed's value goes on only when it differs from the last one (a new socket, a new worker, a
+ *  new session answer what the app may already have). */
+const handOn = (s: Sub, value: unknown) => {
+  const json = JSON.stringify(value === undefined ? null : value)
+  if (json === s.last) return
+  s.last = json
+  s.handler(value === undefined ? null : value)
 }
 
 const BACKOFF_MS = [1000, 2000, 5000, 10000, 30000]
@@ -140,15 +209,18 @@ class ChannelSocket {
   private linger: ReturnType<typeof setTimeout> | null = null
   private closedByUs = false
   private everOpened = false
+  /** The token this socket's last `hello` said: a `session` frame answers that hello, and is taken
+   *  only while the storage still holds it — a call may have stored a newer one meanwhile. */
+  private hello: string | null = null
   private serverUrl: string
 
   constructor(serverUrl: string) { this.serverUrl = serverUrl }
 
-  subscribe(ch: string, args: unknown[], handler: (message: any) => void, options: Options): ChannelSubscription {
-    const sub: Sub = { id: this.nextId++, ch, args, handler, options, group: undefined, refused: null }
+  subscribe(ch: string, args: unknown[], handler: (message: any) => void, options: Options, computed = false): ChannelSubscription {
+    const sub: Sub = { id: this.nextId++, ch, args, handler, options, group: undefined, refused: null, computed, last: undefined }
     this.subs.set(sub.id, sub)
     if (this.linger !== null) { clearTimeout(this.linger); this.linger = null }
-    if (this.open) this.send({ t: "sub", id: sub.id, ch, args })
+    if (this.open) this.send(subFrame(sub))
     else this.connect()
     return {
       close: () => {
@@ -166,6 +238,7 @@ class ChannelSocket {
    *  ones are sent too: the new user may be let in. */
   onSessionChanged(token: string | null) {
     if (!this.open) return
+    this.hello = token
     this.send({ t: "hello", session: token })
     const subs = [...this.subs.values()]
     this.subs.clear()
@@ -174,7 +247,7 @@ class ChannelSocket {
       sub.group = undefined
       sub.refused = null
       this.subs.set(sub.id, sub)
-      this.send({ t: "sub", id: sub.id, ch: sub.ch, args: sub.args })
+      this.send(subFrame(sub))
     }
   }
 
@@ -187,7 +260,9 @@ class ChannelSocket {
     ws.addEventListener("open", () => {
       this.open = true
       this.attempts = 0
+      heard(this.serverUrl, true)
       const session = getSession(this.serverUrl)
+      this.hello = session
       this.send({ t: "hello", session })
       const reconnected = this.everOpened
       this.everOpened = true
@@ -196,11 +271,14 @@ class ChannelSocket {
         if (sub.refused && sub.refused.session === session) continue
         sub.group = undefined
         sub.refused = null
-        this.send({ t: "sub", id: sub.id, ch: sub.ch, args: sub.args })
-        if (reconnected) sub.options.reconnect?.()
+        this.send(subFrame(sub))
+        // a computed's `ok` brings the value again: nothing was missed
+        if (reconnected && !sub.computed) sub.options.reconnect?.()
       }
     })
     ws.addEventListener("message", (data) => {
+      // the backend spoke (a socket the app has let go says nothing)
+      if (this.ws === ws) heard(this.serverUrl, true)
       if (typeof data !== "string") return
       let msg: ServerFrame
       try { msg = JSON.parse(data) } catch { return }
@@ -212,6 +290,9 @@ class ChannelSocket {
       this.open = false
       if (this.closedByUs) return
       if (this.subs.size === 0) { this.shutdown(); return }
+      // down while the app listens: it is trying again, and until then the backend is out of reach. A
+      // close the app asked for (the last subscription gone, a teardown) says nothing of it
+      heard(this.serverUrl, false)
       const delay = BACKOFF_MS[Math.min(this.attempts++, BACKOFF_MS.length - 1)]
       this.timer = setTimeout(() => { this.timer = null; this.connect() }, delay)
     }
@@ -221,24 +302,46 @@ class ChannelSocket {
 
   private onFrame(msg: ServerFrame) {
     switch (msg?.t) {
-      // the server already serves this socket under the token it sends: stored, nothing re-sent
-      case "session": storeSession(this.serverUrl, msg.session ?? null); break
-      case "ok": { const s = this.subs.get(msg.id); if (s) s.group = msg.group ?? null; break }
+      // the server already serves this socket under the token it sends: stored, nothing re-sent — unless a
+      // call stored another token since the hello this answers: then the socket follows the storage (a
+      // device has one identity, the one its calls write rows under)
+      case "session": {
+        const token = msg.session ?? null
+        if (getSession(this.serverUrl) === this.hello) { storeSession(this.serverUrl, token); this.hello = token }
+        else this.onSessionChanged(getSession(this.serverUrl))
+        break
+      }
+      case "ok": {
+        const s = this.subs.get(msg.id)
+        if (!s) break
+        s.group = msg.group ?? null
+        if (s.computed) handOn(s, msg.data)
+        break
+      }
       case "err": {
         const s = this.subs.get(msg.id)
         if (!s) break
+        // a computed's later run failed: the subscription stands, the last value too
+        if (s.computed && s.group !== undefined) {
+          const e = new RpcError(msg.status ?? 0, msg.message ?? "the computed failed")
+          if (s.options.error) s.options.error(e)
+          else console.error(`Computed ${s.ch}: a run failed (${e.status}) — ${e.message}`)
+          break
+        }
         // kept until close(): another session may be let in (onSessionChanged)
         s.group = undefined
         s.refused = { session: getSession(this.serverUrl) }
         const e = new RpcError(msg.status ?? 0, msg.message ?? "subscription refused")
         if (s.options.error) s.options.error(e)
-        else console.error(`Channel ${s.ch}: the subscription was refused (${e.status}) — ${e.message}`)
+        else console.error(`${s.computed ? "Computed" : "Channel"} ${s.ch}: the subscription was refused (${e.status}) — ${e.message}`)
         break
       }
       case "ev": {
         const group = msg.group ?? null
         for (const s of [...this.subs.values()]) {
-          if (s.ch === msg.ch && s.group === group) s.handler(msg.data)
+          if (s.ch !== msg.ch || s.group !== group) continue
+          if (s.computed) handOn(s, msg.data)
+          else s.handler(msg.data)
         }
         break
       }
@@ -293,6 +396,32 @@ export const __channel = (serverUrl: string, id: string) => ({
   publish(): never {
     throw new RpcError(0, `Channel ${id}: the server publishes, the app subscribes — call a server function that publishes`)
   },
+  members(): never {
+    throw new RpcError(0, `Channel ${id}: members() is read on the server — call a server function that reads it`)
+  },
+})
+
+// ───────────────────────────── computeds ─────────────────────────────
+
+/**
+ * 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 const __computed = (serverUrl: string, id: string) => Object.assign(__rpc(serverUrl, id), {
+  subscribe(...all: unknown[]): ChannelSubscription {
+    if (!serverUrl) throw noServer(id)
+    const at = all.findIndex(a => typeof a === "function")
+    if (at < 0) throw new RpcError(0, `Computed ${id}: subscribe([...args,] handler) — no handler given`)
+    const args = all.slice(0, at)
+    while (args.length && args[args.length - 1] === undefined) args.pop()
+    const options = (all[at + 1] as ComputedOptions | undefined) ?? {}
+    return socketFor(serverUrl).subscribe(id, args, all[at] as (value: any) => void, { error: options.error as Options["error"] }, true)
+  },
+  watchers(): never {
+    throw new RpcError(0, `Computed ${id}: watchers() is read on the server — call a server function that reads it`)
+  },
 })
 
 // ───────────────────────────── push channels ─────────────────────────────

package/src/runtime/wire.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.
  */
@@ -25,11 +30,11 @@ export type ChannelGroup = string | number
 
 export type ClientFrame =
   | { t: "hello", session: string | null }
-  | { t: "sub", id: number, ch: string, args: unknown[] }
+  | { t: "sub", id: number, ch: string, args: unknown[], computed?: true }
   | { t: "unsub", id: number }
 
 export type ServerFrame =
   | { t: "session", session: string }
-  | { t: "ok", id: number, group: ChannelGroup | null }
+  | { t: "ok", id: number, group: ChannelGroup | null, data?: unknown }
   | { t: "err", id: number, status: number, message: string }
   | { t: "ev", ch: string, group: ChannelGroup | null, data: unknown }

package/src/server/channel.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"
@@ -49,6 +54,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
 }
@@ -57,6 +65,9 @@ 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
 }
@@ -81,6 +92,22 @@ export const setChannelPublisher = (publisher: Publisher | null) => {
   else delete seam.__lecodesPublish
 }
 
+/** 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[]>
+const presenceSeam = globalThis as unknown as { __lecodesPresence?: PresenceAsk }
+
+/** 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 const presenceKey = (what: unknown): string => JSON.stringify(what === undefined ? null : what)
+
+/** @internal `members` / `watchers` of export `id` (null = not registered): the host's answer. */
+export const askPresence = async (what: string, id: string | null, key: unknown): Promise<number[]> => {
+  if (!id) throw new Error(`${what}: not registered — export it from a *.server.ts file`)
+  const ask = presenceSeam.__lecodesPresence
+  if (!ask) throw new Error(`${what}: no host presence installed`)
+  return ask(id, presenceKey(key))
+}
+
 export const isChannelGroup = (v: unknown): v is ChannelGroup =>
   typeof v === "string" || (typeof v === "number" && Number.isFinite(v))
 
@@ -113,6 +140,11 @@ export const channel = <M = unknown>(): Channel<M> => {
       if (!isChannelGroup(args[0])) throw new Error(`channel.publish: a group is a string or a number, got ${args[0] === null ? "null" : typeof args[0]}`)
       deliver(args[0], args[1])
     },
+    async members(...args: unknown[]) {
+      if (!ch.__groupBy) return askPresence("channel.members", ch.__id, null)
+      if (!isChannelGroup(args[0])) throw new Error(`channel.members: this channel has groups — members(group), a string or a number, got ${args[0] === null ? "null" : typeof args[0]}`)
+      return askPresence("channel.members", ch.__id, args[0])
+    },
     subscribe() {
       throw new Error("channel.subscribe: the app subscribes, the server publishes")
     },