lecodes-sdk 2.0.4 → 2.0.6

package/src/compile/serverTypes.ts

@@ -13,13 +13,17 @@
  * compile error: functions, classes with methods, `Date`, `Map`/`Set`, symbols, recursive types —
  * "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.
+ *
  * `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.
  */
 
 import type { CompileEntry } from "./compileProject"
 import type { ParamSchema, Schema } from "../server/validate"
-import { serverModuleId, type ServerExport } from "./serverSplit"
+import { isServerPath, serverModuleId, type ServerExport } from "./serverSplit"
+import { readInjectSources } from "./bundler"
 
 type TS = typeof import("typescript")
 
@@ -42,6 +46,87 @@ export class EndpointTypeError extends Error {
   }
 }
 
+/**
+ * In the app an endpoint's call is always a promise: it goes over the network. An endpoint that is
+ * not `async` is imported with the type it was written with (`number`), so `const n = add(1, 2)`
+ * type-checks and holds a promise. Declared `async`, the two agree.
+ */
+export class SyncEndpointError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`an endpoint is called over the network, so in the app its result is a promise — declare it async:\n  ${problems.join("\n  ")}`)
+    this.name = "SyncEndpointError"
+    this.problems = problems
+  }
+}
+
+/**
+ * The app and the server are two programs with two sets of globals: `UIText`, `Vec3`, `toast` exist
+ * in the app only, `defineDb`, `ApiError`, `channel` in server files only. The project's types
+ * declare both sets everywhere (one tsconfig), so a global used on the wrong side type-checks — and
+ * is a ReferenceError when that line runs. The compile refuses it instead.
+ */
+export class WrongSideGlobalError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`the app and the server have their own globals — one is used on the wrong side:\n  ${problems.join("\n  ")}`)
+    this.name = "WrongSideGlobalError"
+    this.problems = problems
+  }
+}
+
+/** The value names an inject module exports (`export { a, b as c, type T } from "…"`). */
+const injectNames = (ts: TS, source: string): Set<string> => {
+  const out = new Set<string>()
+  const sf = ts.createSourceFile("inject.ts", source, ts.ScriptTarget.ESNext, false)
+  for (const st of sf.statements) {
+    if (!ts.isExportDeclaration(st) || st.isTypeOnly || !st.exportClause || !ts.isNamedExports(st.exportClause)) continue
+    for (const el of st.exportClause.elements) if (!el.isTypeOnly) out.add(el.name.text)
+  }
+  return out
+}
+
+/**
+ * Uses of a global of the other side, in the project's files of `program`. A name counts when it is
+ * a VALUE the file does not declare or import itself (the checker finds no symbol for it: this
+ * program has no SDK types) — so a local `t`, a parameter `request`, a property `x.model` are not
+ * touched. A name both sides have (`ref`), and one the server's runtime has by itself (`fetch`), are
+ * nobody's mistake.
+ */
+const wrongSideGlobals = (ts: TS, program: import("typescript").Program, checker: import("typescript").TypeChecker, projectFiles: Set<string>): string[] => {
+  const sources = readInjectSources()
+  const app = injectNames(ts, sources.client), server = injectNames(ts, sources.server)
+  const appOnly = new Set([...app].filter(n => !server.has(n) && !(n in globalThis)))
+  const serverOnly = new Set([...server].filter(n => !app.has(n)))
+  const out: string[] = []
+  for (const sf of program.getSourceFiles()) {
+    if (!projectFiles.has(sf.fileName) || sf.isDeclarationFile) continue
+    const onServer = isServerPath(sf.fileName)
+    const foreign = onServer ? appOnly : serverOnly
+    const file = serverModuleId(sf.fileName)
+    const seen = new Set<string>()
+    const visit = (node: import("typescript").Node) => {
+      if (ts.isTypeNode(node)) return                                   // a type is erased: no harm at run time
+      if (ts.isIdentifier(node) && foreign.has(node.text) && !seen.has(node.text)) {
+        const parent = node.parent as import("typescript").Node & { name?: import("typescript").Node, propertyName?: import("typescript").Node }
+        // the name of a declaration, of a property (`x.model`, `{ model: 1 }`), of an import / export specifier
+        const isName = (parent.name === node || parent.propertyName === node) && !ts.isShorthandPropertyAssignment(parent)
+        const symbol = isName ? null : ts.isShorthandPropertyAssignment(parent) ? checker.getShorthandAssignmentValueSymbol(parent) : checker.getSymbolAtLocation(node)
+        if (!isName && !symbol) {
+          seen.add(node.text)                                           // once per file: the first use
+          const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+          out.push(onServer
+            ? `${file}:${line + 1}: ${node.text} is a global of the app — it does not exist in server code`
+            : `${file}:${line + 1}: ${node.text} is a global of server files (*.server.ts) — it does not exist in the app: call an endpoint that uses it`)
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  return out
+}
+
 export type DeriveResult = {
   /** endpoint id → parameter schemas (only endpoints the checker could see). */
   params: Record<string, ParamSchema[]>
@@ -52,9 +137,10 @@ export type DeriveResult = {
  * Derive `{ "<module>#<fn>": ParamSchema[] }` for every function export of every `*.server.ts` entry.
  * Throws `EndpointTypeError` when a parameter type can't be validated at runtime.
  */
-export const deriveEndpointParams = async (entries: CompileEntry[], modules: Record<string, ServerExport[]>): Promise<DeriveResult> => {
+export const deriveEndpointParams = async (entries: CompileEntry[], modules: Record<string, ServerExport[]>, typescript?: TS): Promise<DeriveResult> => {
   let ts: TS
-  try {
+  if (typescript) ts = typescript
+  else try {
     ts = (await import("typescript")).default ?? (await import("typescript")) as unknown as TS
   } catch {
     throw new Error("serverTypes: the `typescript` package is required to compile server endpoints")
@@ -66,7 +152,8 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!/\.[tj]sx?$/.test(e.path)) continue
     files.set(normalizePath(e.path), e.text)
   }
-  const roots = Object.keys(modules).map(normalizePath).filter(p => files.has(p))
+  // the server modules, and every other file of the project: the app's are read for the globals they use
+  const roots = [...new Set([...Object.keys(modules).map(normalizePath).filter(p => files.has(p)), ...files.keys()])]
 
   const options: import("typescript").CompilerOptions = {
     target: ts.ScriptTarget.ESNext,
@@ -104,6 +191,11 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
   const params: Record<string, ParamSchema[]> = {}
   const warnings: string[] = []
   const problems: string[] = []
+  const sync: string[] = []
+  // a promise, or anything awaited the same way (a query handed back as it is); `any` is not judged
+  const awaitable = (type: import("typescript").Type): boolean =>
+    !!(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
+    || (type.flags & ts.TypeFlags.Union ? (type as import("typescript").UnionType).types.every(awaitable) : !!type.getProperty("then"))
 
   for (const [path, exports] of Object.entries(modules)) {
     const sf = program.getSourceFile(normalizePath(path))
@@ -112,26 +204,45 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!modSym) continue
     const exported = new Map(checker.getExportsOfModule(modSym).map(s => [s.name, s]))
     for (const ex of exports) {
-      if (ex.kind !== "fn") continue
+      if (ex.kind === "other") continue
       const id = `${serverModuleId(path)}#${ex.name}`
       let sym = exported.get(ex.name)
       if (!sym) { warnings.push(`${id}: export not found by the checker — unvalidated`); continue }
       if (sym.flags & ts.SymbolFlags.Alias) sym = checker.getAliasedSymbol(sym)
       const decl = sym.valueDeclaration ?? sym.declarations?.[0]
       if (!decl) { warnings.push(`${id}: no declaration — unvalidated`); continue }
-      const type = checker.getTypeOfSymbolAtLocation(sym, decl)
+      let type: import("typescript").Type
+      let where = id
+      if (ex.kind === "channel") {
+        // `channel` is a global this program has no types for: the hook is found in the text of the export
+        const hook = groupByHook(ts, decl)
+        if (!hook) { params[id] = []; continue }
+        type = checker.getTypeAtLocation(hook)
+        where = `${id}.groupBy`
+      } else {
+        type = checker.getTypeOfSymbolAtLocation(sym, decl)
+      }
       const sig = type.getCallSignatures()[0]
-      if (!sig) { warnings.push(`${id}: not callable — unvalidated`); continue }
+      if (!sig) { warnings.push(`${where}: not callable — unvalidated`); continue }
+      if (ex.kind === "fn" && !awaitable(checker.getReturnTypeOfSignature(sig))) {
+        const { line } = sf.getLineAndCharacterOfPosition(decl.getStart(sf))
+        sync.push(`${serverModuleId(path)}:${line + 1}: ${ex.name} — write \`async\` before it`)
+      }
       const list: ParamSchema[] = []
       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`)
+          continue
+        }
         const ptype = checker.getTypeOfSymbolAtLocation(p, pd ?? decl)
         const rest = !!pd?.dotDotDotToken
         const optional = !!pd?.questionToken || !!pd?.initializer || rest
         try {
           // `x?: T` carries `undefined` in its type — the optional flag covers it, strip it from the schema
           const members = ptype.flags & ts.TypeFlags.Union ? (ptype as import("typescript").UnionType).types : [ptype]
-          const schema = lowerMembers(ts, checker, pd?.questionToken ? members.filter(t => !(t.flags & ts.TypeFlags.Undefined)) : members, `${id}(${p.name})`, new Set())
+          const schema = lowerMembers(ts, checker, pd?.questionToken ? members.filter(t => !(t.flags & ts.TypeFlags.Undefined)) : members, `${where}(${p.name})`, new Set())
           list.push({ name: p.name, schema, optional, rest })
         } catch (e) {
           problems.push((e as Error).message)
@@ -141,9 +252,79 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     }
   }
   if (problems.length) throw new EndpointTypeError(problems)
+  if (sync.length) throw new SyncEndpointError(sync)
+  const wrongSide = wrongSideGlobals(ts, program, checker, new Set(files.keys()))
+  if (wrongSide.length) throw new WrongSideGlobalError(wrongSide)
+  const unawaited: string[] = []
+  for (const path of Object.keys(modules)) {
+    const sf = program.getSourceFile(normalizePath(path))
+    if (sf) unawaited.push(...unawaitedUserQueries(ts, sf, serverModuleId(path)))
+  }
+  if (unawaited.length) throw new UnawaitedUserQueryError(unawaited)
   return { params, warnings }
 }
 
+/** 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
+  while (node) {
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) { node = node.expression; continue }
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null
+    if (node.expression.name.text === "groupBy") return node.arguments[0] ?? null
+    node = node.expression.expression
+  }
+  return null
+}
+
+// ───────────────────────────── the user of a request is a QUERY ─────────────────────────────
+
+/**
+ * `db.auth.requireUser(...)` / `db.auth.user()` build a query: the check of who is calling happens when
+ * it is AWAITED. Written as a statement, or tested in a condition, it does nothing — and an endpoint
+ * that looks guarded is open to anyone. So such a query must be awaited (or returned) where it is made.
+ */
+export class UnawaitedUserQueryError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`the user of a request is read with await — a query that is not awaited checks nothing:\n  ${problems.join("\n  ")}`)
+    this.name = "UnawaitedUserQueryError"
+    this.problems = problems
+  }
+}
+
+const unawaitedUserQueries = (ts: TS, sf: import("typescript").SourceFile, file: string): string[] => {
+  const out: string[] = []
+  // `<x>.requireUser(…)` whatever it is called on; `.user()` only on something named `auth` (`auth.user()`, `db.auth.user()`)
+  const isUserQuery = (node: import("typescript").Node): node is import("typescript").CallExpression => {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return false
+    const name = node.expression.name.text
+    if (name === "requireUser") return true
+    if (name !== "user" || node.arguments.length) return false
+    const on = node.expression.expression
+    return (ts.isIdentifier(on) && on.text === "auth") || (ts.isPropertyAccessExpression(on) && on.name.text === "auth")
+  }
+  const awaited = (node: import("typescript").Node): boolean => {
+    const parent = node.parent
+    if (ts.isParenthesizedExpression(parent) || ts.isAsExpression(parent) || ts.isNonNullExpression(parent)) return awaited(parent)
+    // `.select(…)` continues the same query
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === node && parent.name.text === "select" && ts.isCallExpression(parent.parent)) return awaited(parent.parent)
+    if (ts.isAwaitExpression(parent) || ts.isReturnStatement(parent)) return true
+    if (ts.isArrowFunction(parent) && parent.body === node) return true
+    // one of several things awaited together: `await Promise.all([db.auth.requireUser(), …])`
+    if (ts.isArrayLiteralExpression(parent) && ts.isCallExpression(parent.parent)) return awaited(parent.parent)
+    return false
+  }
+  const visit = (node: import("typescript").Node) => {
+    if (isUserQuery(node) && !awaited(node)) {
+      const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+      out.push(`${file}:${line + 1}: ${node.expression.getText(sf)}(…) — write \`await\` before it`)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return out
+}
+
 // ───────────────────────────── type → schema ─────────────────────────────
 
 const lower = (ts: TS, checker: import("typescript").TypeChecker, type: import("typescript").Type, where: string, stack: Set<import("typescript").Type>): Schema => {

package/src/host.d.ts

@@ -31,6 +31,9 @@ declare global {
   /** Compile-time macro: `asset('./data.json')` yields the file's PARSED data (a .json file is
    *  data, not code — it ships inside the bundle). See the `string` overload for everything else. */
   function asset(path: `${string}.json`): any
+  /** Compile-time macro: `asset('./logo.svg')` yields the file as an SVG image source — for
+   *  `UIImage(...)` and `bgImage`. */
+  function asset(path: `${string}.svg`): { readonly svg: string, tintColor: string | null }
   /** Compile-time macro: `asset('./hero.png')` is desugared by the bundler into the module import
    *  for that resource. The file must exist — a path that resolves to nothing fails the compile
    *  (`asset not found: ./hero.png (main.ts:3)`); there is no runtime fallback. Calls inside

package/src/inject.ts

@@ -42,7 +42,8 @@ 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"
 // 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, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
+export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc"
+export type { ChannelSubscription } from "./server/channel"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 // Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
 // AudioSource / AudioZone aspects (gl/) and scene.audio.
@@ -118,9 +119,9 @@ export type { DismissOptions, PresentOptions, Transition, TransitionName, Transi
 // The base node type + the union a container accepts as children — documented as the signature of
 // UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
 export type { UINode, UINodeChild } from "./ui/UINode"
-// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
-// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
-export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
+// App theme variables: theme({...}) merges + returns the var() accessors; the roles the SDK reads
+// are static props (theme.accent, theme["comfort-top"], …). `el.theme({...})` scopes a subtree.
+export { theme, type ThemeValues, type ThemeAccessors, type ThemeRoles } from "./ui/theme"
 
 // ---- animate ----
 // animate() runs on the keyframe core (a VALUE track) since 2026-09-14: same handle, easing and clocks
@@ -136,7 +137,7 @@ export { type EasingInput } from "./animate/tween/easing"
 export { easeIn, easeOut, easeInOut } from "./animate/easings"
 
 // ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers). The first-party
-// ones are VENDORED from the plugin repo (src/plugins/gen, `bun run vendor:plugins`); oauth / service are the SDK's. ----
+// ones are VENDORED from the plugin repo (src/plugins/gen, `bun run vendor:plugins`); service is the SDK's. ----
 export { QRScanner } from "./plugins/gen/qr-scanner/sdk/qr-scanner"
 export { CameraView, type CameraFacing } from "./plugins/gen/camera/sdk/camera"
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/gen/geolocation/sdk/geolocation"
@@ -146,7 +147,6 @@ export {
   type LineLayer, type LineLayerOptions, type UserLocationOptions,
 } from "./plugins/gen/map/sdk/map"
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push"
-export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
 export { Service } from "./plugins/service"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----

package/src/runtime/device.ts

@@ -133,6 +133,18 @@ export const device = {
   vibrate(style: HapticStyle = "medium"): void {
     _creatorDevice.vibrate?.(style)
   },
+  /** The host's performance overlay: one line over everything with the frames per second the
+   *  display actually got, how evenly they came (`66 fps · 73% even` is judder, `60 fps · 100% even`
+   *  is smooth), and the GPU's and the main thread's milliseconds per frame. The host measures and
+   *  draws it itself about once a second — nothing of it runs in the app's JS, so it does not change
+   *  what it measures. It belongs to the host, not to the project: it stays on when another project
+   *  is opened. Reads `false`, and writing does nothing, on hosts without one (web, headless). */
+  get statsOverlay(): boolean {
+    return _creatorDevice.statsOverlay?.() ?? false
+  },
+  set statsOverlay(on: boolean) {
+    _creatorDevice.setStatsOverlay?.(!!on)
+  },
   /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
    *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
    *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */

package/src/runtime/rpc.ts

@@ -10,10 +10,7 @@
  * Wire (implemented by the runner):
  *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
  *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
- *   WS   <serverUrl>/ws  frames: → {t:"hello",session} {t:"sub",id,ch,topic} {t:"unsub",id}
- *                                ← {t:"session",session} {t:"ok",id} {t:"err",id,status,message} {t:"ev",ch,topic,event,data}
- *   (`ev` is addressed by channel + topic, not by subscription id, so the server can fan one publish out
- *   to every socket of a topic natively; the client delivers it to each matching subscription.)
+ *   WS   <serverUrl>/ws  the channel socket — its frames are ./wire.ts
  *
  * 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`.
@@ -23,6 +20,8 @@
 import { fetch } from "./fetch"
 import { localStorage } from "./storage"
 import { WebSocket } from "./net"
+import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
+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). */
@@ -41,12 +40,17 @@ const sessionKey = (serverUrl: string) => `lecodes.session:${serverUrl}`
 const getSession = (serverUrl: string): string | null => {
   try { return localStorage.getItem(sessionKey(serverUrl)) } catch { return null }
 }
-const setSession = (serverUrl: string, token: string | null) => {
+const storeSession = (serverUrl: string, token: string | null) => {
   try {
     if (token) localStorage.setItem(sessionKey(serverUrl), token)
     else localStorage.removeItem(sessionKey(serverUrl))
   } catch { /* storage-less host: the session lives for this run only */ }
-  sockets.get(serverUrl)?.onSessionChanged(token)
+}
+/** A response carried a token: when it is another one, the channel socket is told (its subscriptions are the old session's). */
+const setSession = (serverUrl: string, token: string | null) => {
+  const before = getSession(serverUrl)
+  storeSession(serverUrl, token)
+  if (token !== before) sockets.get(serverUrl)?.onSessionChanged(token)
 }
 
 // ───────────────────────────── endpoints ─────────────────────────────
@@ -57,6 +61,9 @@ const noServer = (id: string) => new RpcError(0, `Endpoint ${id}: the project ha
 export const __rpc = (serverUrl: string, id: string) => {
   const call = async (...args: unknown[]): Promise<any> => {
     if (!serverUrl) throw noServer(id)
+    // 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()
     const headers: Record<string, string> = { "content-type": "application/json" }
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
@@ -85,15 +92,23 @@ export const __serverOnly = (id: string): any =>
 
 // ───────────────────────────── channels ─────────────────────────────
 
-type Handlers = Record<string, ((payload: any) => void) | undefined> & {
-  /** The socket dropped and came back: subscriptions were re-sent, but events in between are lost — refetch. */
+type Options = {
+  /** The socket dropped and came back: subscriptions were re-sent, but what was published in between is lost — read the state again. */
   reconnect?: () => void
-  /** The subscription was refused (`onJoin` threw) or the socket can't connect. */
+  /** The subscription was refused (a hook of the channel threw). It is asked again when the session changes. */
   error?: (e: RpcError) => void
 }
-type Sub = { id: number, ch: string, topic: string, handlers: Handlers, ready: boolean }
+/** `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. */
+type Sub = {
+  id: number, ch: string, args: unknown[], handler: (message: any) => void, options: Options,
+  group: ChannelGroup | null | undefined, refused: { session: string | null } | null,
+}
 
 const BACKOFF_MS = [1000, 2000, 5000, 10000, 30000]
+/** How long the socket outlives its last subscription: one screen closing its own and the next
+ *  opening its own is not a new connection. */
+const LINGER_MS = 3000
 
 /** One multiplexed socket per server URL, shared by every channel of the app. */
 class ChannelSocket {
@@ -103,28 +118,45 @@ class ChannelSocket {
   private nextId = 1
   private attempts = 0
   private timer: ReturnType<typeof setTimeout> | null = null
+  private linger: ReturnType<typeof setTimeout> | null = null
   private closedByUs = false
   private everOpened = false
   private serverUrl: string
 
   constructor(serverUrl: string) { this.serverUrl = serverUrl }
 
-  subscribe(ch: string, topic: string, handlers: Handlers): { close(): void } {
-    const sub: Sub = { id: this.nextId++, ch, topic, handlers, ready: false }
+  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 }
     this.subs.set(sub.id, sub)
-    if (this.open) this.send({ t: "sub", id: sub.id, ch, topic })
+    if (this.linger !== null) { clearTimeout(this.linger); this.linger = null }
+    if (this.open) this.send({ t: "sub", id: sub.id, ch, args })
     else this.connect()
     return {
       close: () => {
+        // the id changes when the subscription is sent again (a new session)
         if (!this.subs.delete(sub.id)) return
-        if (this.open) this.send({ t: "unsub", id: sub.id })
-        if (this.subs.size === 0) this.shutdown()
+        if (this.open && !sub.refused) this.send({ t: "unsub", id: sub.id })
+        this.idle()
       },
     }
   }
 
+  /** The session changed outside this socket (a sign-in, a sign-out): what the server granted was
+   *  granted to someone else. It drops this socket's subscriptions on the `hello`; they are sent
+   *  again under NEW ids, so an answer still on its way to an old one finds nothing. The refused
+   *  ones are sent too: the new user may be let in. */
   onSessionChanged(token: string | null) {
-    if (this.open) this.send({ t: "hello", session: token })
+    if (!this.open) return
+    this.send({ t: "hello", session: token })
+    const subs = [...this.subs.values()]
+    this.subs.clear()
+    for (const sub of subs) {
+      sub.id = this.nextId++
+      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 })
+    }
   }
 
   private connect() {
@@ -136,18 +168,22 @@ class ChannelSocket {
     ws.addEventListener("open", () => {
       this.open = true
       this.attempts = 0
-      this.send({ t: "hello", session: getSession(this.serverUrl) })
+      const session = getSession(this.serverUrl)
+      this.send({ t: "hello", session })
       const reconnected = this.everOpened
       this.everOpened = true
       for (const sub of this.subs.values()) {
-        sub.ready = false
-        this.send({ t: "sub", id: sub.id, ch: sub.ch, topic: sub.topic })
-        if (reconnected) sub.handlers.reconnect?.()
+        // refused under this very session: the answer would be the same
+        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?.()
       }
     })
     ws.addEventListener("message", (data) => {
       if (typeof data !== "string") return
-      let msg: any
+      let msg: ServerFrame
       try { msg = JSON.parse(data) } catch { return }
       this.onFrame(msg)
     })
@@ -155,7 +191,8 @@ class ChannelSocket {
       if (this.ws !== ws) return
       this.ws = null
       this.open = false
-      if (this.closedByUs || this.subs.size === 0) return
+      if (this.closedByUs) return
+      if (this.subs.size === 0) { this.shutdown(); return }
       const delay = BACKOFF_MS[Math.min(this.attempts++, BACKOFF_MS.length - 1)]
       this.timer = setTimeout(() => { this.timer = null; this.connect() }, delay)
     }
@@ -163,35 +200,49 @@ class ChannelSocket {
     ws.addEventListener("error", onDown)
   }
 
-  private onFrame(msg: any) {
+  private onFrame(msg: ServerFrame) {
     switch (msg?.t) {
-      case "session": setSession(this.serverUrl, msg.session ?? null); break
-      case "ok": { const s = this.subs.get(msg.id); if (s) s.ready = true; break }
+      // 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 }
       case "err": {
         const s = this.subs.get(msg.id)
         if (!s) break
-        this.subs.delete(msg.id)
-        s.handlers.error?.(new RpcError(msg.status ?? 0, msg.message ?? "subscription refused"))
+        // 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}`)
         break
       }
       case "ev": {
-        for (const s of this.subs.values()) {
-          if (s.ch === msg.ch && s.topic === msg.topic) s.handlers[msg.event]?.(msg.data)
+        const group = msg.group ?? null
+        for (const s of [...this.subs.values()]) {
+          if (s.ch === msg.ch && s.group === group) s.handler(msg.data)
         }
         break
       }
     }
   }
 
-  private send(frame: unknown) { this.ws?.send(JSON.stringify(frame)) }
+  private send(frame: ClientFrame) { this.ws?.send(JSON.stringify(frame)) }
 
-  private shutdown() {
+  /** Nothing is subscribed any more: the socket goes after LINGER_MS, unless something subscribes. */
+  private idle() {
+    if (this.subs.size !== 0 || this.linger !== null) return
+    this.linger = setTimeout(() => { this.linger = null; if (this.subs.size === 0) this.shutdown() }, LINGER_MS)
+  }
+
+  shutdown() {
     this.closedByUs = true
     if (this.timer !== null) { clearTimeout(this.timer); this.timer = null }
+    if (this.linger !== null) { clearTimeout(this.linger); this.linger = null }
     this.ws?.close()
     this.ws = null
     this.open = false
-    sockets.delete(this.serverUrl)
+    this.subs.clear()
+    if (sockets.get(this.serverUrl) === this) sockets.delete(this.serverUrl)
   }
 }
 
@@ -202,15 +253,25 @@ const socketFor = (serverUrl: string) => {
   return s
 }
 
-export interface ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> {
-  /** Subscribe to `topic`; handlers are keyed by event name (+ `reconnect`/`error`). Returns `{ close }`. */
-  subscribe(topic: string, handlers: { [K in keyof E]?: (payload: E[K]) => void } & { reconnect?: () => void, error?: (e: RpcError) => void }): { close(): void }
-}
+/** @internal close every channel socket now (a test's teardown: no socket lingers into the next one). */
+export const _closeChannelSockets = () => { for (const s of [...sockets.values()]) s.shutdown() }
 
-/** Build the client proxy of channel `id`. */
-export const __channel = (serverUrl: string, id: string): ClientChannel<any> => ({
-  subscribe(topic, handlers) {
+/**
+ * Build the client proxy of channel `id` — what a `channel()` export of a `*.server.ts` file is in
+ * the app (its type is the server's: src/server/channel.ts). `subscribe([...args,] handler, options?)`:
+ * what stands before the handler travels to the channel's `groupBy`.
+ */
+export const __channel = (serverUrl: string, id: string) => ({
+  subscribe(...all: unknown[]): ChannelSubscription {
     if (!serverUrl) throw noServer(id)
-    return socketFor(serverUrl).subscribe(id, topic, handlers as Handlers)
+    const at = all.findIndex(a => typeof a === "function")
+    if (at < 0) throw new RpcError(0, `Channel ${id}: subscribe([...args,] handler) — no handler given`)
+    // an optional argument left out is `undefined` in its place — JSON has no such value, and it is the last ones
+    const args = all.slice(0, at)
+    while (args.length && args[args.length - 1] === undefined) args.pop()
+    return socketFor(serverUrl).subscribe(id, args, all[at] as (message: any) => void, (all[at + 1] as Options | undefined) ?? {})
+  },
+  publish(): never {
+    throw new RpcError(0, `Channel ${id}: the server publishes, the app subscribes — call a server function that publishes`)
   },
 })

package/src/runtime/wire.ts

@@ -0,0 +1,35 @@
+/**
+ * The frames of the channel socket (`<serverUrl>/ws`) — the ONE description both ends are written
+ * against: the client transport (./rpc.ts) and the server's hub (../server/channelHub.ts, which the
+ * runner and the local backend of `lecodes dev` both run). JSON text frames, one per message.
+ *
+ *   → hello   who is on this socket. Sent first, and again whenever the session changes: the server
+ *             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.
+ *   → 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.
+ *   ← 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.
+ *
+ * A group's value is not a secret: its subscriber is told it.
+ */
+
+/** What `groupBy` may answer. `42` and `"42"` are two groups. */
+export type ChannelGroup = string | number
+
+export type ClientFrame =
+  | { t: "hello", session: string | null }
+  | { t: "sub", id: number, ch: string, args: unknown[] }
+  | { t: "unsub", id: number }
+
+export type ServerFrame =
+  | { t: "session", session: string }
+  | { t: "ok", id: number, group: ChannelGroup | null }
+  | { t: "err", id: number, status: number, message: string }
+  | { t: "ev", ch: string, group: ChannelGroup | null, data: unknown }