lecodes-sdk 2.0.3 → 2.0.5

package/src/net/index.ts

@@ -10,12 +10,12 @@ import {
   type Listener, type NetEvents, type NetLaunch, type NetMessage, type NetRole, type NetStatus,
 } from "./core"
 import {
-  NetEntity, Replicated, allEntities, currentTick, declareInput, declareKind, entityById, installReplication, setInput, stats,
-  type NetInput, type NetKind, type NetTransform,
+  NetEntity, Replicated, allEntities, currentTick, declareInput, declareKind, entityById, installReplication, setInput, stats, viewTick,
+  type NetCorrection, type NetInput, type NetKind, type NetTransform,
 } from "./replication"
 
 export { NetPlayer, NetEntity, Replicated }
-export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform }
+export type { NetEvents, NetLaunch, NetMessage, NetRole, NetStatus, NetInput, NetKind, NetTransform, NetCorrection }
 
 class NetImpl {
   get role(): NetRole { return state.role }
@@ -34,12 +34,21 @@ class NetImpl {
   /** The simulation tick — one per fixed step (`updateFixed`). The server's is THE tick; a client
    *  runs a few ticks ahead so its inputs arrive in time. */
   get tick(): number { return currentTick() }
+  /** The server tick this machine is SHOWING the others at: on a client, its estimate of the server's
+   *  clock less the interpolation delay (fractional); `tick` everywhere else, where nothing is
+   *  interpolated. What a client names when it tells the server "as I saw it". */
+  get viewTick(): number { return viewTick() }
   /** Live counters: snapshots, input lead / `ahead`, corrections, missed inputs, bytes out. */
   get stats(): typeof stats { return stats }
 
   /** Start serving on `port`. From offline this makes us the host (a player who is also the
-   *  server); on the dedicated exe (`Net.launch.role === "server"`) there is no local player. */
-  listen(opts: { port?: number; maxClients?: number; name?: string; dedicated?: boolean } = {}): boolean {
+   *  server); on the dedicated exe (`Net.launch.role === "server"`) there is no local player.
+   *  `accept` is the game's say in the handshake: it is given what the client's `connect` passed as
+   *  `hello` and returns a reason to refuse (the client's `reject` event carries it), nothing to accept. */
+  listen(opts: {
+    port?: number; maxClients?: number; name?: string; dedicated?: boolean
+    accept?: (hello: unknown, who: { name: string }) => string | null | void
+  } = {}): boolean {
     const b = bridge()
     if (!b) { emit("error", "multiplayer is not supported on this host"); return false }
     if (state.role !== "offline") this.disconnect()
@@ -56,6 +65,7 @@ class NetImpl {
     state.isServer = true
     state.isClient = !dedicated
     state.status = "online"
+    state.accept = opts.accept ?? null
     if (!dedicated) ensureMe()
     installReplication()
     startPhases()
@@ -63,12 +73,15 @@ class NetImpl {
     return true
   }
 
-  /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us. */
-  connect(target: { address: string }, opts: { name?: string } = {}): Promise<void> {
+  /** Connect to a host/server (`address` = "ip:port"). Resolves once the server welcomed us.
+   *  `hello` = anything JSON the game wants the server to see before it lets us in (its
+   *  `Net.listen({ accept })`, then `player.hello`); the SDK only carries it. */
+  connect(target: { address: string }, opts: { name?: string; hello?: unknown } = {}): Promise<void> {
     const b = bridge()
     if (!b) return Promise.reject(new Error("multiplayer is not supported on this host"))
     if (state.role !== "offline") this.disconnect()
     if (opts.name) state.myName = opts.name
+    state.hello = opts.hello
     return new Promise<void>((resolve, reject) => {
       if (!b.connect(target.address)) { reject(new Error(`bad address '${target.address}'`)); return }
       state.role = "client"
@@ -163,8 +176,16 @@ class NetImpl {
 
   /** A replicated entity type: the defaults are the snapshot layout (same field rules as `input`),
    *  `transform` tells the SDK which fields mirror the node's pose, `client` births the proxy on a
-   *  client when the server spawns one (`new Node().aspect(Replicated, { kind, owner })`). */
-  kind<S extends object>(name: string, defaults: S, opts: { transform?: NetTransform; client?: (rep: NetEntity<S>, scene: any) => any } = {}): NetKind<S> {
+   *  client when the server spawns one (`new Node().aspect(Replicated, { kind, owner })`) — it may
+   *  be set later, `Kind.client = …`, where the client's code lives. `discrete` names the numeric
+   *  fields that are never interpolated (an index, a count); `correction` tunes how the owner's
+   *  prediction is brought back to the server's state (all in the game's own units). */
+  kind<S extends object>(name: string, defaults: S, opts: {
+    transform?: NetTransform
+    client?: (rep: NetEntity<S>, scene: any) => any
+    discrete?: readonly (keyof S & string)[]
+    correction?: Partial<NetCorrection>
+  } = {}): NetKind<S> {
     return declareKind(name, defaults, opts as any)
   }
 

package/src/net/replication.ts

@@ -16,9 +16,10 @@
 // offset `rep.correction` absorbs the jump and decays.
 //
 // Wire (channel 1, unreliable, binary; a leading type byte):
-//   1 inputs    C→S  u8 1 · u32 firstTick · u8 count · count × input record        (last 3 ticks)
+//   1 inputs    C→S  u8 1 · u32 firstTick · u8 count · count × input record        (the ticks since the
+//                    last send + 2 older ones, 3 at least; sent when the tick moved)
 //   2 snapshot  S→C  u8 2 · u32 tick · u32 lastInputTick · u8 missed · u16 count ·
-//                    count × { u16 netId · u8 kind · state record }                (every 3rd tick)
+//                    count × { u32 netId · u8 kind · state record }                (every 3rd tick)
 // Channel 0 (reliable JSON): `$spawn {netId, kind, owner, state}` · `$despawn {netId}`.
 
 import { Aspect } from "../core/Aspect"
@@ -31,6 +32,19 @@ import { CH_UNRELIABLE, CH_RELIABLE, LOCAL_SLOT, NetPlayer, bridge, broadcastRaw
 
 export type NetTransform = "pos" | "pos+rot" | "none"
 
+/** How an owner's prediction is brought back to the server's state. The SDK knows nothing of what
+ *  the entity is, so the defaults are neutral: every disagreement counts, none is a teleport. */
+export type NetCorrection = {
+  /** A vertical disagreement below this is ignored (world units). 0 = none ignored. A body that
+   *  snaps to a floor differs by a little between two machines, and lifting it by that feeds itself. */
+  deadbandY: number
+  /** A disagreement of this much or more is a teleport: the body jumps and `correction` stays zero
+   *  (world units). Infinity = always smoothed. */
+  snap: number
+  /** The decay time constant of the visual offset `correction` (seconds). 0 = no smoothing. */
+  tau: number
+}
+
 /** The per-tick input layout: `const PlayerInput = Net.input({ moveX: 0, moveY: 0, jump: false })`. */
 export type NetInput<T extends object = any> = { readonly layout: Layout; readonly defaults: T; readonly __t?: T }
 
@@ -44,8 +58,10 @@ export type NetKind<S extends object = any> = {
   /** Which state fields the SDK samples on the server and applies to a client proxy: `pos` (a
    *  `pos: [x,y,z]` field), `pos+rot` (+ a `rot: [x,y,z,w]` quaternion field), or `none`. */
   readonly transform: NetTransform
-  /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns. */
-  readonly client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void
+  readonly correction: NetCorrection
+  /** Births the client-side proxy on spawn; the SDK attaches `Replicated` to what it returns.
+   *  Assignable: a declaration both ends share may leave it to the client's own module. */
+  client?: (rep: NetEntity<S>, scene: Scene | null) => Node | void
   readonly __t?: S
   /** @internal scratch state for snapshot decoding */
   readonly _scratch: S
@@ -56,10 +72,10 @@ const SNAPSHOT_EVERY = 3        // 20 Hz
 const INTERP_DELAY = 6          // ticks behind the estimated server tick (100 ms)
 const LEAD_MIN = 2, LEAD_MAX = 8
 const SNAPSHOT_BUDGET = 1000    // bytes — one unreliable datagram (creator-net caps messages at 1024)
-const CORRECTION_TAU = 0.1      // seconds — the visual offset's decay time constant
-const SNAP_DISTANCE = 2         // metres — a bigger disagreement is a teleport: no smoothing
+const CORRECTION_TAU = 0.1      // seconds — the visual offset's decay time constant, unless the kind says
 const NO_INPUT = 0xffffffff
-const VERTICAL_DEADBAND = 0.12  // metres — owner height disagreements below this are floor-snap noise
+const INPUT_MAX = 8             // input records in one packet (the ring keeps as many ticks)
+const REC_HEAD = 5              // u32 netId · u8 kind
 
 // ---- registries ---------------------------------------------------------------------------------------
 
@@ -72,6 +88,8 @@ let nextNetId = 1
 
 let tick = 0
 let localInput: any = null                // what Net.setInput set this tick (every role but `server`)
+let localSet = false                      // Net.setInput was called at all this session
+let sentTick = -1                         // client: the tick of the newest input sent
 const inputRing = new Map<number, any>()  // client: tick → values, resent with the next 2 sends
 let estimate = -1                         // client: the server's tick, fractional, advanced per frame
 let leadCooldown = 0
@@ -147,6 +165,12 @@ export class NetEntity<S extends object = any> {
     const p = this.owner
     return (p?._in?.cur ?? inp.defaults) as T
   }
+  /** `input()` is an input the owner gave — false until the first one exists (the server before
+   *  the owner's first packet, the owner before its first `Net.setInput`), when it is the defaults. */
+  get hasInput(): boolean {
+    if (!state.isServer || this.isMine) return localSet
+    return !!this.owner?._in?.cur
+  }
 
   /** Client: `state` was refreshed (a snapshot landed / the interpolation moved). */
   on(event: "state", cb: (s: S) => void): this { if (!this._listeners.includes(cb)) this._listeners.push(cb); return this }
@@ -157,10 +181,13 @@ export class NetEntity<S extends object = any> {
 
 // ---- declarations (Net.kind / Net.input) --------------------------------------------------------------
 
-export const declareKind = <S extends object>(name: string, defaults: S, opts: { transform?: NetTransform; client?: NetKind<S>["client"] } = {}): NetKind<S> => {
+export const declareKind = <S extends object>(name: string, defaults: S, opts: {
+  transform?: NetTransform; client?: NetKind<S>["client"]; discrete?: readonly string[]; correction?: Partial<NetCorrection>
+} = {}): NetKind<S> => {
   if (kinds.has(name)) throw new Error(`Net.kind('${name}') is already declared`)
   if (kindList.length >= 255) throw new Error("Net.kind: at most 255 kinds")
-  const layout = makeLayout(defaults as Record<string, unknown>, `Net.kind('${name}')`)
+  const layout = makeLayout(defaults as Record<string, unknown>, `Net.kind('${name}')`, opts.discrete)
+  const correction: NetCorrection = { deadbandY: 0, snap: Infinity, tau: CORRECTION_TAU, ...opts.correction }
   const transform = opts.transform ?? "none"
   const need = transform === "pos" ? ["pos"] : transform === "pos+rot" ? ["pos", "rot"] : []
   for (const key of need) {
@@ -168,7 +195,7 @@ export const declareKind = <S extends object>(name: string, defaults: S, opts: {
     const len = key === "pos" ? 3 : 4
     if (!f || f.kind !== 2 || f.len !== len) throw new Error(`Net.kind('${name}'): transform '${transform}' needs a '${key}' field of ${len} numbers`)
   }
-  const kind: NetKind<S> = { name, id: kindList.length, layout, defaults: cloneDefaults(defaults), transform, client: opts.client, _scratch: cloneDefaults(defaults) }
+  const kind: NetKind<S> = { name, id: kindList.length, layout, defaults: cloneDefaults(defaults), transform, correction, client: opts.client, _scratch: cloneDefaults(defaults) }
   kinds.set(name, kind)
   kindList.push(kind)
   return kind
@@ -187,6 +214,7 @@ export const setInput = <T extends object>(inp: NetInput<T>, values: Partial<T>)
   const v = cloneDefaults(inp.defaults)
   assignState(inp.layout, v, values)
   localInput = v
+  localSet = true
   if (state.role === "client") {
     inputRing.set(tick, v)
     for (const t of inputRing.keys()) if (t < tick - 8) inputRing.delete(t)
@@ -194,6 +222,7 @@ export const setInput = <T extends object>(inp: NetInput<T>, values: Partial<T>)
 }
 
 export const currentTick = (): number => tick
+export const viewTick = (): number => (state.role === "client" && estimate >= 0 ? estimate - INTERP_DELAY : tick)
 export const allEntities = (): NetEntity[] => [...entities.values()]
 export const entityById = (netId: number): NetEntity | undefined => entities.get(netId)
 
@@ -314,6 +343,7 @@ export class Replicated extends Aspect<"replicated", Node> {
   get correction(): Vec3 { return this._rec?.correction ?? ZERO }
   /** The owner's input for the tick being simulated (see `NetEntity.input`). */
   input<T extends object>(inp: NetInput<T>): T { return this._rec ? this._rec.input(inp) : (localInput ?? inp.defaults) }
+  get hasInput(): boolean { return this._rec ? this._rec.hasInput : localSet }
   // state-change listeners live on the entity: `node.replicated.entity.on('state', cb)` (the aspect's
   // own on/off are its aspect events)
 }
@@ -358,7 +388,7 @@ const buildSnapshot = (forTick: number): void => {
   const list = [...entities.values()]
   if (list.length === 0) { pendingSnapshot = null; return }
   let size = 0
-  for (const e of list) size += 3 + e.kind.layout.bytes
+  for (const e of list) size += REC_HEAD + e.kind.layout.bytes
   const buf = new ArrayBuffer(Math.min(size, SNAPSHOT_BUDGET))
   const view = new DataView(buf)
   let o = 0
@@ -370,10 +400,10 @@ const buildSnapshot = (forTick: number): void => {
   }
   for (let i = 0; i < n; i++) {
     const e = list[(snapshotStart + i) % n]
-    const rec = 3 + e.kind.layout.bytes
+    const rec = REC_HEAD + e.kind.layout.bytes
     if (o + rec > buf.byteLength) break
     samplePose(e)
-    view.setUint16(o, e.netId, true); o += 2
+    view.setUint32(o, e.netId, true); o += 4
     view.setUint8(o, e.kind.id); o += 1
     o = packInto(view, o, e.kind.layout, e.state)
     written++
@@ -439,10 +469,10 @@ const onClientBinary = (channel: number, data: ArrayBuffer): void => {
 
   let o = 12
   for (let i = 0; i < count; i++) {
-    if (o + 3 > data.byteLength) break
-    const netId = view.getUint16(o, true)
-    const kind = clientKinds[view.getUint8(o + 2)]
-    o += 3
+    if (o + REC_HEAD > data.byteLength) break
+    const netId = view.getUint32(o, true)
+    const kind = clientKinds[view.getUint8(o + 4)]
+    o += REC_HEAD
     if (!kind) {
       if (!warnedKind) { warnedKind = true; console.warn("Net: snapshot with an unknown kind id — dropped") }
       return
@@ -478,11 +508,9 @@ const reconcileOwner = (e: NetEntity, T: number): void => {
   if (!pred) return
   const s = e.state as any
   const dx = s.pos[0] - pred[0], dz = s.pos[2] - pred[2]
-  // Vertical deadband: a grounded character's height differs by a few cm between two machines
-  // (landing phase, floor snap) and lifting the body by that much only makes it fall again — an
-  // oscillation the correction itself feeds. Only a real height difference (a ledge, a jump) counts.
+  // the kind's vertical deadband (NetCorrection.deadbandY): what it calls noise is not corrected
   let dy = s.pos[1] - pred[1]
-  if (Math.abs(dy) < VERTICAL_DEADBAND) dy = 0
+  if (Math.abs(dy) < e.kind.correction.deadbandY) dy = 0
   const d = Math.hypot(dx, dy, dz)
   if (d < 0.005) return
   stats.corrections++
@@ -491,7 +519,7 @@ const reconcileOwner = (e: NetEntity, T: number): void => {
   for (const q of e._pred.values()) { q[0] += dx; q[1] += dy; q[2] += dz }
   const sh = e._shift ?? (e._shift = [0, 0, 0])
   sh[0] += dx; sh[1] += dy; sh[2] += dz
-  if (d >= SNAP_DISTANCE) e.correction.set(0, 0, 0)
+  if (d >= e.kind.correction.snap) e.correction.set(0, 0, 0)
 }
 
 const applyOwnerShift = (e: NetEntity): void => {
@@ -502,7 +530,7 @@ const applyOwnerShift = (e: NetEntity): void => {
   e.node.position = [p.x + sh[0], p.y + sh[1], p.z + sh[2]]
   const rec = e._pred.get(tick - 1)
   if (rec) { rec[0] += sh[0]; rec[1] += sh[1]; rec[2] += sh[2] }
-  if (Math.hypot(sh[0], sh[1], sh[2]) < SNAP_DISTANCE) { e.correction.x -= sh[0]; e.correction.y -= sh[1]; e.correction.z -= sh[2] }
+  if (Math.hypot(sh[0], sh[1], sh[2]) < e.kind.correction.snap) { e.correction.x -= sh[0]; e.correction.y -= sh[1]; e.correction.z -= sh[2] }
 }
 
 const clientFrame = (): void => {
@@ -510,11 +538,12 @@ const clientFrame = (): void => {
   if (estimate >= 0) estimate += dt * 60
   stats.lead = estimate >= 0 ? tick - estimate : 0
   const rt = estimate - INTERP_DELAY
-  const k = Math.exp(-dt / CORRECTION_TAU)
   for (const e of entities.values()) {
     if (e.isMine) {
       const c = e.correction
       if (c.x !== 0 || c.y !== 0 || c.z !== 0) {
+        const tau = e.kind.correction.tau
+        const k = tau > 0 ? Math.exp(-dt / tau) : 0
         c.x *= k; c.y *= k; c.z *= k
         if (Math.hypot(c.x, c.y, c.z) < 1e-3) c.set(0, 0, 0)
       }
@@ -538,13 +567,17 @@ const clientFrame = (): void => {
 }
 
 const sendInputs = (): void => {
-  if (!inputDef || inputRing.size === 0) return
-  const first = tick - 2
-  const buf = new ArrayBuffer(6 + 3 * inputDef.layout.bytes)
+  // nothing new since the last send: a frame without a fixed step
+  if (!inputDef || inputRing.size === 0 || tick === sentTick) return
+  // every tick since the last send (a long frame steps more than once) + 2 older ones against loss
+  const count = Math.min(INPUT_MAX, Math.max(3, tick - sentTick + 2))
+  sentTick = tick
+  const first = tick - count + 1
+  const buf = new ArrayBuffer(6 + count * inputDef.layout.bytes)
   const view = new DataView(buf)
   view.setUint8(0, 1)
   view.setUint32(1, first, true)
-  view.setUint8(5, 3)
+  view.setUint8(5, count)
   let o = 6
   let last: any = localInput ?? inputDef.defaults
   for (let t = first; t <= tick; t++) {
@@ -615,6 +648,8 @@ export const installReplication = (): void => {
       estimate = -1
     }
     inputRing.clear()
+    localSet = false
+    sentTick = -1
     pendingSnapshot = null
     leadCooldown = 0
     for (const p of state.players) p._in = null

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 }