tickcli-js 0.0.0-stage → 0.1.1

package/src/hub.ts

@@ -0,0 +1,1521 @@
+// tickcli hub: live rooms for browser games. Pure logic: no sockets, an injected clock, so every rule is unit-testable; start() runs the
+// 10 ms sub-tick on a timer (tests call tick() themselves). node.ts connects it to WebSocket sockets (ws); any other transport only needs the Conn interface below.
+//
+// Who decides what: each player writes only their own state (me), one player's browser (the host) writes the shared state, and this hub owns membership,
+// order, the match number, the change counter, the host term and the clock. The host's writes carry its term; a write from an older term or an older
+// connection is refused. The shared state lives here, so a new host continues from this copy, never from its own memory.
+//
+// Saving is optional and goes through a port (SavePort, below): the hub never touches storage itself. With a port and a slot (a stable game key the app
+// decides, not the page hash, so editing a game keeps its saves) a person has a PROFILE (stats, items, level: their own, 16 KB) and a game that asks for
+// it (multiplayer.save) has a WORLD save (the host's shared state, written every few seconds and when the match ends; Continue starts a new room from it).
+// Without a port nothing is saved: a restart ends every match (close 1012), players reconnect and start a new one.
+//
+// Writes merge deeply: {hp: {a: 80}} changes only a's hp; null removes a key; lists are replaced whole. Shared keys starting with "_" belong to the game
+// shell (teams) and survive a new match.
+import crypto from "node:crypto";
+
+export const PROTOCOL = 1;
+
+/** Close codes (also in docs/security.md). 1012 = restart. */
+export const CLOSE = {
+  restart: 1012, roomError: 1011, busy: 1013, silent: 4009, notAllowed: 4001, full: 4002, replaced: 4003, tooFast: 4004, badMessage: 4005, removed: 4006, gameUpdated: 4007, tooSlow: 4008, idle: 4010,
+} as const;
+
+export interface Limits {
+  maxPlayers: number;          // per room (the page asks for 2 to this)
+  maxRooms: number;            // whole server
+  maxRoomsPerScope: number;    // per namespace (scope)
+  maxConnections: number;      // whole server, signed in or not
+  maxPending: number;          // whole server: sockets that have not proven who they are yet
+  maxPerAddress: number;       // open sockets per client address
+  joinsPerMinute: number;      // per client address
+  messageBytes: number;        // one message
+  playerStateBytes: number;    // one player's state, as JSON
+  sharedStateBytes: number;    // a room's shared state, as JSON
+  stateRate: number;           // state-like messages a second per connection (me, shared, fx, ...), with a burst of twice that
+  sharedRate: number;          // the host's shared writes a second, burst twice that (on top of stateRate)
+  actionRate: number;          // actions a second per connection, burst twice that
+  timeRate: number;            // clock pings a second per connection, burst twice that (the relay needs one every 5 s); 2 before sign-in
+  pendingMs: number;           // time to prove who you are, then to send join
+  seatHoldMs: number;          // a dropped player keeps the seat this long
+  evictAfterMs: number;        // a full room gives a held seat to a newcomer only when its player has been gone at least this long
+  awayHoldMs: number;          // ... or this long when the page was put away first (a phone switched to another app, e.g. to send the invite)
+  hostSilenceMs: number;       // a host whose game loop stops reporting for this long loses host duty
+  roomOutBytes: number;        // a room sending more than this a second (moving average) sends half as often until it is back under
+  maxOutMbit: number;          // whole server: above 80% of it rooms over 4 players send at half rate and new rooms are refused (busy); 0 = no cap
+  silentMs: number;            // a visible page that sends nothing (its clock ping comes every 5 s) for this long is treated as gone
+  acceptRate: number;          // new sockets a second, whole server; over it: 1013 busy, try again
+  actionTimeoutMs: number;     // an action the host never answers fails after this
+  slowBytes: number;           // queued bytes at which a reader stops getting changes (one fresh copy follows)
+  dropBytes: number;           // queued bytes at which a reader is disconnected
+  rateBytes: number;           // queued bytes at which a reader drops to the next slower update rate (half, then a quarter); see Session.div
+  rateUpMs: number;            // a slowed reader goes one rate back up after its queue stayed near empty this long
+  listRate: number;            // room-list requests a second per connection, burst twice that
+  idleMs: number;              // a room where no person did anything for this long is closed (4010); 0 = never. The host's own updates do not count
+  idleWarnMs: number;          // ... its players are warned this long before (idle {closesAt}); anything a person does cancels it
+  listIdleMs: number;          // a room idle this long is left out of room lists (it still runs until idleMs)
+  tickMs: number;              // fan-out period; rooms over 8 players send every second tick
+  profileBytes: number;        // one person's saved profile, as JSON
+  profileEveryMs: number;      // a changed profile is written at most this often (and when the person leaves or the match ends)
+  worldEveryMs: number;        // a changed world is written at most this often (and when the match ends or the room empties)
+  saveDays: number;            // a world save older than this is ignored (the store may delete it)
+}
+
+export const DEFAULT_LIMITS: Limits = {
+  maxPlayers: 16, maxRooms: 500, maxRoomsPerScope: 50, maxConnections: 2000, maxPending: 200, maxPerAddress: 20, joinsPerMinute: 30,
+  messageBytes: 16 * 1024, playerStateBytes: 2048, sharedStateBytes: 64 * 1024, stateRate: 50, sharedRate: 20, actionRate: 5, timeRate: 2,
+  pendingMs: 5000, seatHoldMs: 30_000, evictAfterMs: 10_000, awayHoldMs: 300_000, hostSilenceMs: 5000, silentMs: 15_000, acceptRate: 200, roomOutBytes: 250 * 1024, maxOutMbit: 100, actionTimeoutMs: 5000, slowBytes: 64 * 1024, dropBytes: 256 * 1024, rateBytes: 16 * 1024, rateUpMs: 10_000, listRate: 1, idleMs: 15 * 60_000, idleWarnMs: 60_000, listIdleMs: 5 * 60_000, tickMs: 50,
+  profileBytes: 16 * 1024, profileEveryMs: 3000, worldEveryMs: 5000, saveDays: 90,
+};
+
+/** One open socket, as the hub sees it. */
+export interface Conn {
+  send(data: string): void;
+  close(code: number, reason: string): void;
+  /** bytes queued and not yet written to the network */
+  buffered(): number;
+}
+
+/**
+ * Where saves live; the host app supplies it. `who` is a seat key ("u:<user id>") for a person's profile, null for a game's shared world save (rooms
+ * played together), "alone:<seat key>" for one person's own world save (Play alone: a room of one keeps its own game, so playing together never
+ * touches it). `slot` is the app's stable key for the game. store(..., null) deletes. Keep a world at least `saveDays` (90).
+ */
+export interface SavePort {
+  /** null = nothing saved. Reject only when the save could not be read (the hub then writes nothing over it and tries again later). */
+  load(scope: string, slot: string, who: string | null): Promise<{ at: number; data: unknown; v?: number } | null>;
+  /** meta.session: one id per room session for world saves, so a store that keeps an earlier copy can take it once per session. meta.v: the game's
+   *  save format number (multiplayer.saveVersion), kept with the data and given back by load (a file without it counts as 1). */
+  store(scope: string, slot: string, who: string | null, data: unknown | null, meta?: { session?: string; v?: number }): Promise<void>;
+}
+
+/** Who a connection is, decided by the server (ticket or guest pass), never by the page. */
+export interface Who {
+  /** stable seat key: "u:<user id>" or "g:<guest pass id>" */
+  seat: string;
+  name: string;
+  guest: boolean;
+}
+
+/** The page's declaration: room size and the number range of each player field. */
+/** saveVersion: the game's save format (whole number, default 1); a page edited to read another shape raises it (README: saved games). */
+export interface Spec { max: number; player: Record<string, [number, number]>; save: boolean; saveVersion: number }
+
+export interface PlayerView { id: string; name: string; online: boolean; hidden: boolean; guest: boolean; state: Record<string, unknown> }
+
+type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+const CODE_ABC = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";   // no 0/O, 1/I/L
+const CODE_RE = /^[A-HJ-NP-Z2-9]{4,6}$/;
+const NAME_RE = /^[a-z_][a-z0-9_-]{0,23}$/i;   // a leading underscore is the game shell's own (_team, _seat, _shot)
+const BAD_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** The shape limits of everything a page writes (also in room.js, which checks before sending, and in the README). */
+export const SHAPE = { text: 200, list: 64, keys: 64, depth: 4, key: 40 } as const;
+
+/** Plain JSON within the shape limits: depth, keys, text and list lengths, finite numbers. Returns false for anything else. */
+export function plain(v: unknown, depth = 0): v is Json { return badPath(v, depth) === null; }
+
+/** Where a value breaks the shape limits: the path of the first bad part ("mobs.12.name", "" for the value itself), or null when it is fine. */
+export function badPath(v: unknown, depth = 0, at = ""): string | null {
+  if (v === null || typeof v === "boolean") return null;
+  if (typeof v === "number") return Number.isFinite(v) ? null : at;
+  if (typeof v === "string") return v.length <= SHAPE.text ? null : at;
+  if (depth >= SHAPE.depth) return at;
+  if (Array.isArray(v)) {
+    if (v.length > SHAPE.list) return at;
+    for (let i = 0; i < v.length; i++) { const b = badPath(v[i], depth + 1, at ? `${at}.${i}` : String(i)); if (b !== null) return b; }
+    return null;
+  }
+  if (typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) return at;
+  const keys = Object.keys(v as object);
+  if (keys.length > SHAPE.keys) return at;
+  for (const k of keys) {
+    const here = at ? `${at}.${k}` : k;
+    if (k.length > SHAPE.key || BAD_KEYS.has(k)) return here;
+    const b = badPath((v as Record<string, unknown>)[k], depth + 1, here);
+    if (b !== null) return b;
+  }
+  return null;
+}
+
+/** A checked spec, or null. */
+export function parseSpec(raw: unknown, maxPlayers = DEFAULT_LIMITS.maxPlayers): Spec | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as { max?: unknown; player?: unknown; save?: unknown; saveVersion?: unknown };
+  const sv = Number(r.saveVersion ?? 1);
+  if (!Number.isInteger(sv) || sv < 1 || sv > 1e6) return null;
+  const max = Number(r.max ?? 4);
+  if (!Number.isInteger(max) || max < 1 || max > maxPlayers) return null;
+  const player: Record<string, [number, number]> = {};
+  const p = r.player ?? {};
+  if (!p || typeof p !== "object" || Array.isArray(p)) return null;
+  const keys = Object.keys(p);
+  if (keys.length > 16) return null;
+  for (const k of keys) {
+    const range = (p as Record<string, unknown>)[k];
+    if (!NAME_RE.test(k) || BAD_KEYS.has(k) || !Array.isArray(range) || range.length !== 2) return null;
+    const [lo, hi] = range.map(Number);
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo >= hi || Math.abs(lo) > 1e9 || Math.abs(hi) > 1e9) return null;
+    player[k] = [lo, hi];
+  }
+  return { max, player, save: r.save === true, saveVersion: sv };
+}
+
+/** The world save a room reads and writes: the shared one, or (Play alone) its owner's own. */
+const worldOf = (room: { owner: string }) => (room.owner ? `alone:${room.owner}` : null);
+const stable = (spec: Spec) => JSON.stringify({ max: spec.max, save: spec.save, sv: spec.saveVersion, player: Object.keys(spec.player).sort().map((k) => [k, spec.player[k]]) });
+const bytes = (v: unknown) => Buffer.byteLength(JSON.stringify(v));
+
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+/** Apply a patch to state: objects merge key by key, null removes, anything else (lists too) replaces. Returns a new object; `into` is not changed. */
+export function applyPatch(into: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...into };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null) delete out[k];
+    else if (isObj(v)) out[k] = applyPatch(isObj(out[k]) ? out[k] as Record<string, unknown> : {}, v);
+    else out[k] = v;
+  }
+  return out;
+}
+/** The part of a patch that changes `cur`: leaves equal to the current value are left out, a null for a key that is not there too, lists equal by
+ *  their JSON text. Null = nothing changes. So a game may write whole objects every step: only what changed is applied, counted and sent. */
+export function changedOnly(cur: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown> | null {
+  let out: Record<string, unknown> | null = null;
+  for (const k of Object.keys(patch)) {
+    const v = patch[k], has = Object.prototype.hasOwnProperty.call(cur, k), c = has ? cur[k] : undefined;
+    let keep: unknown;
+    if (v === null) { if (!has) continue; keep = null; }
+    else if (isObj(v)) { if (isObj(c)) { const d = changedOnly(c, v); if (!d) continue; keep = d; } else keep = stripNulls(v); }
+    else if (Array.isArray(v)) { if (Array.isArray(c) && JSON.stringify(c) === JSON.stringify(v)) continue; keep = v; }
+    else { if (c === v && (v !== 0 || Object.is(c, v))) continue; keep = v; }
+    (out ??= {})[k] = keep;
+  }
+  return out;
+}
+const stripNulls = (v: Record<string, unknown>): Record<string, unknown> => {
+  const o: Record<string, unknown> = {};
+  for (const [k, x] of Object.entries(v)) if (x !== null) o[k] = isObj(x) ? stripNulls(x) : x;
+  return o;
+};
+const jlen = (v: unknown) => Buffer.byteLength(JSON.stringify(v));
+/** How many bytes the JSON text of `cur` grows by when `patch` (already reduced by changedOnly) is applied: only the changed leaves are measured. */
+export function sizeDelta(cur: Record<string, unknown>, patch: Record<string, unknown>): number {
+  let d = 0, n0 = 0, n1 = 0;
+  for (const _ in cur) n0++;
+  n1 = n0;
+  for (const k of Object.keys(patch)) {
+    const v = patch[k], has = Object.prototype.hasOwnProperty.call(cur, k), c = has ? cur[k] : undefined, kl = jlen(k) + 1;
+    if (v === null) { if (has) { d -= kl + jlen(c); n1--; } continue; }
+    if (isObj(v) && isObj(c)) { d += sizeDelta(c, v); continue; }
+    const nv = isObj(v) ? stripNulls(v) : v;
+    d += jlen(nv) - (has ? jlen(c) : 0);
+    if (!has) { d += kl; n1++; }
+  }
+  return d + Math.max(0, n1 - 1) - Math.max(0, n0 - 1);
+}
+/** Combine two patches that go out together (nulls kept, so removals still reach the others). */
+export function joinPatch(into: Record<string, unknown>, patch: Record<string, unknown>) {
+  for (const [k, v] of Object.entries(patch)) {
+    if (isObj(v) && isObj(into[k])) joinPatch(into[k] as Record<string, unknown>, v);
+    else into[k] = isObj(v) ? structuredClone(v) : v;
+  }
+}
+
+class Bucket {
+  tokens: number;
+  at: number;
+  rate: number;
+  constructor(rate: number, now: number) { this.rate = rate; this.tokens = rate * 2; this.at = now; }
+  take(now: number): boolean {
+    this.tokens = Math.min(this.rate * 2, this.tokens + ((now - this.at) / 1000) * this.rate);
+    this.at = now;
+    if (this.tokens < 1) return false;
+    this.tokens -= 1;
+    return true;
+  }
+}
+
+interface Seat {
+  key: string;
+  id: string;
+  name: string;
+  guest: boolean;
+  state: Record<string, unknown>;
+  session: Session | null;
+  hidden: boolean;
+  /** the host's game loop stopped reporting (a frozen tab) while its socket stayed open */
+  stalled: boolean;
+  since: number;
+  offlineAt: number;
+  lastAct: number;
+  /** the save format number of the profile as loaded */
+  profV: number;
+  /** restored from a snapshot after a restart: the first welcome says kept (the page carries on in the same match) */
+  kept: boolean;
+  /** the person's saved profile once loaded (null = not loaded, or saving is off) */
+  prof: Record<string, unknown> | null;
+  profLoad: Promise<Record<string, unknown> | null> | null;
+  profDirty: boolean;
+  profAt: number;
+  /** JSON size of state, kept up to date by each write (an exact count near the limit and every 256 writes) */
+  stateBytes: number;
+}
+
+interface Room {
+  key: string;
+  scope: string;
+  game: string;
+  spec: Spec;
+  specKey: string;
+  code: string;
+  priv: boolean;
+  /** the app's stable key for saves ("" = none) and whether this room keeps a world save */
+  slot: string;
+  /** Play alone: the one seat this room belongs to ("" = a room for anyone). Its world save is that person's own, not the shared one. */
+  owner: string;
+  world: boolean;
+  /** the world save this room holds the lease on ("" = none). One room at a time writes a given save. */
+  lease: string;
+  /** the game keeps a world save, but another room is playing it: this room is not saved */
+  saveBusy: boolean;
+  /** the world save's load: nothing is written (and nothing cleared) until it is "ready"; "failed" retries on a timer (loadAt) */
+  worldState: "off" | "loading" | "ready" | "failed";
+  loadTries: number;
+  loadAt: number;
+  /** a Start that came while the save was still loading: run once it is loaded (Continue / New game is offered first when a save turns up) */
+  startWait: { resume: boolean; at: number } | null;
+  /** this room's session id for the store (one earlier copy per session) */
+  sid: string;
+  saved: { at: number; data: Record<string, unknown>; v: number } | null;
+  /** how many shared writes the room had at the last world write; a world save is due when it differs */
+  wrev: number;
+  savedWrev: number;
+  savedAt: number;
+  /** the host cleared the save (the game is won or lost): nothing is written until the next start */
+  noSave: boolean;
+  resumed: boolean;
+  seats: Map<string, Seat>;      // by seat key
+  byId: Map<string, Seat>;       // by public id
+  banned: Set<string>;
+  match: number;
+  rev: number;
+  term: number;
+  host: Seat | null;
+  hostAliveAt: number;
+  started: boolean;
+  /** a match ended; the next start begins a new one */
+  played: boolean;
+  shared: Record<string, unknown>;
+  pendPlayers: Map<string, Record<string, unknown>>;
+  pendShared: { patch: Record<string, unknown>; term: number } | null;
+  /** when the pending values were sampled by their senders (shared clock): per player id, and for the shared part */
+  pendPT: Map<string, number>;
+  pendSC: number;
+  pendAt: number;
+  actions: Map<number, { from: Seat; ref: number; at: number }>;
+  nextAction: number;
+  tickN: number;
+  /** bytes sent to this room's sockets: total, at the last one-second mark, and the rate over the last second */
+  outBytes: number;
+  outMark: number;
+  outRate: number;
+  /** effects waiting for the next frame (g.fx, shots): they go out with the state, in order */
+  /** 0..9: which sub-tick this room sends on, so all rooms do not write their sockets in the same instant */
+  phase: number;
+  /** data budget: the room's moving average of bytes out a second, its send interval multiplier (1, 2, 4, 8) and whether its host was told */
+  outAvg: number;
+  slowF: number;
+  slowTold: boolean;
+  pendFx: { from: string; name: string; data: unknown }[];
+  pendFxBytes: number;
+  /** when the room was made (room list: newest first among equals) */
+  created: number;
+  /** when a person last did something here (moved, acted, sent an effect, joined, left, started, came back to the page, pressed stay);
+   *  the host's automatic shared writes and the pages' clock pings do not count, so a game left running with nobody at it still ends */
+  activeAt: number;
+  /** the players were told the room closes soon */
+  idleWarned: boolean;
+  /** state frames sent on the tick so far; a reader on rate 1/d gets every d-th one (see Session.div) */
+  flushN: number;
+  /** per slower rate (2, 4): everything since that rate's last frame, merged; null while every reader is on the full rate */
+  tiers: Map<number, Frame> | null;
+  /** JSON size of shared, kept like seat.stateBytes; writes since the last exact count */
+  sharedBytes: number;
+  sizeChecks: number;
+}
+
+/** A frame's content: changed player fields and their sample times, the shared patch and its sample time, effects. */
+interface Frame {
+  players: Map<string, Record<string, unknown>>;
+  pt: Map<string, number>;
+  shared: { patch: Record<string, unknown>; term: number } | null;
+  sc: number;
+  fx: { from: string; name: string; data: unknown }[];
+}
+const emptyFrame = (): Frame => ({ players: new Map(), pt: new Map(), shared: null, sc: 0, fx: [] });
+/** Folds `f` into `into` (later values win, as when a page applies both in order). */
+function foldFrame(into: Frame, f: Frame) {
+  for (const [id, p] of f.players) { const cur = into.players.get(id); if (cur) joinPatch(cur, p); else into.players.set(id, structuredClone(p)); }
+  for (const [id, t] of f.pt) into.pt.set(id, t);
+  if (f.shared) { if (!into.shared) into.shared = { patch: {}, term: f.shared.term }; joinPatch(into.shared.patch, f.shared.patch); into.shared.term = f.shared.term; into.sc = f.sc; }
+  if (f.fx.length) into.fx.push(...f.fx);
+}
+/** Messages that show a person is there (resetting a room's idle time): moving, actions, effects, start, end, kick, rename, stay. */
+const ACTIVE = new Set(["me", "act", "fx", "start", "end", "kick", "name", "stay"]);
+/** Update rates a reader can be on: every state frame, every second one, every fourth one. */
+const RATES = [1, 2, 4];
+
+/** One socket's life in the hub: pending (not yet identified) -> identified -> joined a room -> closed. */
+export class Session {
+  who: Who | null = null;
+  scope = "";
+  game = "";
+  slot = "";
+  room: Room | null = null;
+  seat: Seat | null = null;
+  dead = false;
+  lagging = false;
+  readonly opened: number;
+  state: Bucket;
+  acts: Bucket;
+  /** clock pings: their own small bucket, and a count before sign-in */
+  clock: Bucket;
+  early = 0;
+  strikes = 0;
+  /** when this socket was last told too_fast */
+  slowAt = 0;
+  /** when the last message came in (a visible page sends a clock ping every 5 s) */
+  lastRx: number;
+  /** shared writes: a bucket of their own (room.js sends at most 12.5 a second plus split parts) */
+  sharedB: Bucket;
+  /** Update rate: this reader gets every div-th state frame (1, 2 or 4; effects and changes in between are merged into it, nothing is lost).
+   *  netDiv is the hub's own reading of the socket (its send queue), askDiv what the page asked for (rate {div}: a slow link or device seen by
+   *  the page); the slower of the two is used, taken over only when every rate's frame has just gone out (so nobody misses a change). */
+  div = 1;
+  netDiv = 1;
+  askDiv = 1;
+  /** when netDiv last went down, and since when the send queue has been near empty */
+  downAt = 0;
+  clearAt = 0;
+  /** the page's round trip to the hub (ms, its own best recent ping, sent along with its clock pings); 0 = not known */
+  rtt = 0;
+  /** room-list requests */
+  listB: Bucket;
+  /** what the page understands (join f: ["fxb", ...]): "fxb" = effects inside the delta frame. Pages without it get one fx message per effect. */
+  feats = new Set<string>();
+  readonly hub: RoomHub;
+  readonly conn: Conn;
+  readonly addr: string;
+  constructor(hub: RoomHub, conn: Conn, addr: string) {
+    this.hub = hub; this.conn = conn; this.addr = addr;
+    this.opened = hub.now();
+    this.lastRx = this.opened;
+    this.state = new Bucket(hub.limits.stateRate, this.opened);
+    this.acts = new Bucket(hub.limits.actionRate, this.opened);
+    this.clock = new Bucket(hub.limits.timeRate, this.opened);
+    this.sharedB = new Bucket(hub.limits.sharedRate, this.opened);
+    this.listB = new Bucket(hub.limits.listRate, this.opened);
+    this.clearAt = this.opened;
+  }
+  /** The server decided who this is (ticket or guest pass) and which namespace and game version they may join. */
+  identify(scope: string, game: string, who: Who, slot = "") {
+    if (this.dead || this.who) return;
+    this.who = who; this.scope = scope; this.game = game; this.slot = slot;
+    this.hub.pending--;
+  }
+  receive(text: string) { this.hub.receive(this, text); }
+  /** The socket closed (any reason). */
+  closed() { this.hub.drop(this); }
+  send(m: Record<string, unknown>) {
+    if (this.dead) return;
+    const text = JSON.stringify({ v: PROTOCOL, ...m });
+    this.hub.sent(Buffer.byteLength(text), 1, this.room);
+    try { this.conn.send(text); } catch { /* the close handler cleans up */ }
+  }
+  end(code: number, reason: string) {
+    if (this.dead) return;
+    this.hub.drop(this);
+    try { this.conn.close(code, reason); } catch { /* already gone */ }
+  }
+}
+
+/** Live numbers (per second over the last second unless named otherwise). No names, no scope ids. */
+export interface LiveStats {
+  framesOut: number; bytesOut: number; msgsIn: number;
+  /** time one sub-tick took (one every 10 ms), over the last 1,200 (about 12 s; ms) */
+  tickMs: { p50: number; p99: number; max: number };
+  /** sockets behind on their reads now */
+  slow: number;
+  /** rooms with a match in progress */
+  started: number;
+  savesOk: number; savesFailed: number; loadsFailed: number; worldWritesPerMin: number;
+  /** event-loop delay, set by the host process (main.ts) once a minute */
+  loop: { p50: number; p99: number; max: number } | null;
+  /** over the data cap or a late loop now; rooms slowed by their own budget */
+  pressure: boolean;
+  slowedRooms: number;
+  /** the 5 rooms sending the most */
+  top: { players: number; bytesOut: number; sharedBytes: number }[];
+}
+/** A restart's hand-over of live rooms (exportRooms / importRooms). The format number changes when the shape does; another format is ignored. */
+export const SNAPSHOT_FORMAT = 1;
+export interface SnapRoom {
+  key: string; scope: string; game: string; spec: Spec; code: string; priv: boolean; slot: string; owner: string; world: boolean; lease: string; saveBusy: boolean;
+  worldState: "ready" | "loading"; saved: { at: number; data: Record<string, unknown>; v: number } | null; wrev: number; savedWrev: number; noSave: boolean; resumed: boolean; sid: string;
+  match: number; rev: number; term: number; started: boolean; played: boolean; shared: Record<string, unknown>; banned: string[];
+  seats: { key: string; id: string; name: string; guest: boolean; state: Record<string, unknown>; hidden: boolean; since: number }[];
+}
+export interface RoomsSnapshot { format: number; at: number; rooms: SnapRoom[] }
+
+export interface HubStats { rooms: number; players: number; online: number; connections: number; pending: number; refused: Record<string, number>; live: LiveStats }
+
+export class RoomHub {
+  readonly limits: Limits;
+  readonly now: () => number;
+  readonly boot = crypto.randomBytes(6).toString("base64url");
+  private readonly secret: Buffer;
+  private rooms = new Map<string, Room>();          // by scope|code
+  private sessions = new Set<Session>();
+  pending = 0;
+  private perAddr = new Map<string, number>();
+  private joins = new Map<string, number[]>();
+  private refused: Record<string, number> = {};
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private sub = 0;
+  private acceptAt = 0;
+  private accepted = 0;
+  private houseAt = 0;
+  /** games whose room failed once (logged once each) */
+  private erred = new Set<string>();
+  private closing = false;
+  private readonly saves: SavePort | null;
+  private writing = new Set<Promise<boolean>>();
+  /** the newest write of each save ("scope|slot|who"): a load waits for that one only, not for other rooms' saves */
+  private writingKey = new Map<string, Promise<boolean>>();
+  private loading = new Set<Promise<unknown>>();
+  /** plain counters for stats() (saves_ok, ...) */
+  private counts: Record<string, number> = {};
+  /** meters: totals, the totals at the last one-second mark, the per-second rates, tick times, world writes in the last minute */
+  private meter = { framesOut: 0, bytesOut: 0, msgsIn: 0 };
+  private mark = { at: 0, framesOut: 0, bytesOut: 0, msgsIn: 0 };
+  private rates = { framesOut: 0, bytesOut: 0, msgsIn: 0 };
+  private tickTimes = new Float64Array(1200);
+  private tickCount = 0;
+  private worldWrites: number[] = [];
+  /** event-loop delay from the host process (main.ts sets it once a minute) */
+  loop: { p50: number; p99: number; max: number } | null = null;
+  /** the same over the last 10 s (main.ts), for the half-rate switch */
+  loopRecent: { p99: number } | null = null;
+  /** over the data cap or a late loop: bigger rooms at half rate, no new rooms */
+  pressure = false;
+  /** world save leases: "scope|slot|who" -> the room key that may write it */
+  private leases = new Map<string, string>();
+
+  /** shutdown() hands the live rooms to this (a restart writes them to disk; importRooms() in the next process takes them back) */
+  private readonly onSnapshot: ((snap: RoomsSnapshot) => Promise<void> | void) | null;
+  /** the room list (rooms {}) is answered; off: the answer is {off: true} */
+  readonly listRooms: boolean;
+  /** room lists made in the last 250 ms, per namespace, game and save slot (many pages asking at once cost one build) */
+  private lists = new Map<string, { at: number; rooms: Record<string, unknown>[] }>();
+
+  /** rooms allowed in one namespace when it differs from limits.maxRoomsPerScope (a host app's per-customer cap, tickcli-js/remote) */
+  private readonly roomsPerScope: ((scope: string) => number | undefined) | null;
+
+  constructor(opts: { secret: string; now?: () => number; limits?: Partial<Limits>; saves?: SavePort; onSnapshot?: (snap: RoomsSnapshot) => Promise<void> | void; listRooms?: boolean; roomsPerScope?: (scope: string) => number | undefined }) {
+    this.roomsPerScope = opts.roomsPerScope ?? null;
+    this.saves = opts.saves ?? null;
+    this.listRooms = opts.listRooms !== false;
+    this.onSnapshot = opts.onSnapshot ?? null;
+    this.secret = Buffer.from(opts.secret);
+    this.now = opts.now ?? Date.now;
+    this.limits = { ...DEFAULT_LIMITS, ...(opts.limits ?? {}) };
+  }
+
+  /** A short public id for a seat in one namespace; the seat key itself (a user id or guest pass id) is never shown to others. */
+  publicId(scope: string, seat: string): string {
+    return crypto.createHmac("sha256", this.secret).update(`${scope}|${seat}`).digest("base64url").slice(0, 10);
+  }
+
+  /** The save slot a socket plays under; without a store there are no slots. */
+  private slotOf(s: Session) { return this.saves ? s.slot : ""; }
+
+  private refuse(why: string) { this.refused[why] = (this.refused[why] || 0) + 1; }
+  private count(what: string, n = 1) { this.counts[what] = (this.counts[what] || 0) + n; }
+
+  /** A new socket. Null = refused (the caller closes it with the code given). */
+  connect(conn: Conn, addr: string): Session | { refused: number; reason: string } {
+    const L = this.limits;
+    if (this.closing) return { refused: CLOSE.restart, reason: "server restarting" };
+    if (this.sessions.size >= L.maxConnections) { this.refuse("connections"); return { refused: CLOSE.full, reason: "server is full" }; }
+    // busy (not full): the page tries again with its normal backoff, so a reconnect wave after a restart spreads out instead of ending on a "full" screen
+    if (this.pending >= L.maxPending) { this.refuse("pending"); return { refused: CLOSE.busy, reason: "server is busy, try again" }; }
+    const now = this.now();
+    if (now - this.acceptAt >= 1000) { this.acceptAt = now; this.accepted = 0; }
+    if (++this.accepted > L.acceptRate) { this.refuse("accept_rate"); return { refused: CLOSE.busy, reason: "server is busy, try again" }; }
+    if ((this.perAddr.get(addr) || 0) >= L.maxPerAddress) { this.refuse("address"); return { refused: CLOSE.tooFast, reason: "too many connections" }; }
+    const s = new Session(this, conn, addr);
+    this.sessions.add(s);
+    this.pending++;
+    this.perAddr.set(addr, (this.perAddr.get(addr) || 0) + 1);
+    return s;
+  }
+
+  /** Meter: `n` copies of a text of `len` bytes (UTF-8, as on the wire) went out (to one room's sockets when given). */
+  sent(len: number, n: number, room?: Room | null) {
+    this.meter.framesOut += n; this.meter.bytesOut += len * n;
+    if (room) room.outBytes += len * n;
+  }
+
+  receive(s: Session, text: string) {
+    if (s.dead) return;
+    this.meter.msgsIn++;
+    const now = this.now();
+    s.lastRx = now;
+    if (typeof text !== "string") return this.bad(s, "not text");
+    if (Buffer.byteLength(text) > this.limits.messageBytes) {
+      // a size mistake by a game is answered, not punished with a closed connection; a socket that never signed in is closed
+      if (!s.who) return this.bad(s, "message too large");
+      this.refuse("too_big");
+      this.err(s, "too_big");
+      return this.strike(s);
+    }
+    let m: Record<string, unknown>;
+    try { m = JSON.parse(text); } catch { return this.bad(s, "not JSON"); }
+    if (!m || typeof m !== "object" || Array.isArray(m) || m.v !== PROTOCOL || typeof m.t !== "string") return this.bad(s, "wrong protocol version");
+    const t = m.t;
+    if (t === "time") {
+      // clock pings have their own small bucket (the relay sends one every 5 s), and only 2 before the socket proves who it is
+      if (!s.who ? ++s.early > 2 : !s.clock.take(now)) return this.strike(s);
+      if (typeof m.r === "number" && Number.isFinite(m.r)) s.rtt = Math.max(1, Math.min(10_000, Math.round(m.r)));   // the page's own best round trip (display only)
+      return s.send({ t: "time", c: typeof m.c === "number" && Number.isFinite(m.c) ? m.c : 0, s: now });
+    }
+    if (!s.who) return this.bad(s, "sign in first");
+    if (t === "join") return this.join(s, m);
+    if (t === "rooms") { if (!s.listB.take(now)) return this.strike(s); return s.send(this.roomList(s, m)); }
+    const room = s.room, seat = s.seat;
+    if (!room || !seat) return this.bad(s, "join first");
+    if (ACTIVE.has(t) || (t === "vis" && m.hidden !== true)) this.active(room);
+    if (t === "act") return this.act(s, room, seat, m);
+    if (t === "result") { if (!s.state.take(now)) return this.strike(s); return this.result(room, seat, m); }
+    if (!s.state.take(now) || (t === "shared" && !s.sharedB.take(now))) {
+      // a dropped state write leaves the sender's copy different from everyone else's: say so (once a second at most), the page asks for a resync
+      if ((t === "me" || t === "shared") && now - s.slowAt >= 1000) { s.slowAt = now; this.err(s, "too_fast"); }
+      return this.strike(s);
+    }
+    s.strikes = Math.max(0, s.strikes - 1);
+    switch (t) {
+      case "me": return this.me(s, room, seat, m);
+      case "shared": return this.sharedWrite(s, room, seat, m);
+      case "fx": return this.fx(room, seat, m, s);
+      case "alive": return this.alive(room, seat, m);
+      case "vis": return this.vis(room, seat, m);
+      case "name": return this.rename(s, room, seat, m);
+      case "profile": return void this.sendProfile(s, room, seat);
+      case "sync": return s.send(this.snapshot(room, seat, "sync"));   // a page whose write was refused asks for the server's copy
+      case "save": return this.saveProfile(s, room, seat, m);
+      case "world": return this.worldMsg(s, room, seat, m);
+      case "start": return this.startMatch(s, room, seat, m.resume === true);
+      case "end": return this.endMatch(s, room, seat);
+      case "kick": return this.kick(s, room, seat, m);
+      case "stay": return;   // the person pressed "keep this room" (counted as activity above)
+      case "rate": { const d = Number(m.div); s.askDiv = RATES.includes(d) ? d : 1; return; }
+      case "leave": this.removeSeat(room, seat); return s.end(1000, "left");   // a person who chose to go does not linger as "reconnecting"
+      default: return this.bad(s, "unknown message");
+    }
+  }
+
+  private bad(s: Session, why: string) { this.refuse("bad_message"); s.end(CLOSE.badMessage, why); }
+  /** Over the rate: the message is dropped; a sender that keeps pushing far past it is disconnected. */
+  private strike(s: Session) {
+    this.refuse("rate");
+    if (++s.strikes > 60) { this.refuse("too_fast"); s.end(CLOSE.tooFast, "too many messages"); }
+  }
+  private err(s: Session, code: string, ref?: unknown) { s.send({ t: "error", code, ...(ref === undefined ? {} : { ref }) }); }
+
+  // ---- joining ----------------------------------------------------------------------------------------------------------------------------
+  private join(s: Session, m: Record<string, unknown>) {
+    const L = this.limits, now = this.now();
+    if (s.room) return this.bad(s, "already in a room");
+    const spec = parseSpec(m.spec, L.maxPlayers);
+    if (!spec) return this.bad(s, "bad multiplayer option");
+    const hits = (this.joins.get(s.addr) || []).filter((x) => now - x < 60_000);
+    if (hits.length >= L.joinsPerMinute) { this.refuse("joins"); return s.end(CLOSE.tooFast, "too many joins, wait a minute"); }
+    hits.push(now); this.joins.set(s.addr, hits);
+    if (this.joins.size > 10_000) for (const [k, v] of this.joins) if (!v.length || now - v[v.length - 1] > 60_000) this.joins.delete(k);
+    const who = s.who!;
+    if (who.guest && typeof m.name === "string") { const n = cleanName(m.name); if (n) who.name = n; }
+    const specKey = stable(spec);
+    let room: Room | undefined;
+    const want = typeof m.code === "string" ? m.code.toUpperCase() : "";
+    if (want) {
+      if (!CODE_RE.test(want)) return this.bad(s, "bad room code");
+      room = this.rooms.get(`${s.scope}|${want}`);
+      // The game was edited since this room started (a join always carries the page's current version): the code goes to the current version, so
+      // everyone who reloads lands together; the old room carries on for whoever is still in it under a hidden code, and they are told.
+      if (room && room.game !== s.game && room.slot === this.slotOf(s) && !(room.owner && room.owner !== who.seat)) { this.retire(room); room = undefined; }
+      if (room && (room.game !== s.game || room.slot !== this.slotOf(s) || room.specKey !== specKey)) { this.refuse("game_updated"); return s.end(CLOSE.gameUpdated, "this room plays another version of the game, reload"); }
+      if (room?.owner && room.owner !== who.seat) { this.refuse("full"); return s.end(CLOSE.full, "this room is full"); }   // someone's game alone
+      if (!room) room = this.create(s, spec, specKey, want, true, m.alone === true ? who.seat : "") ?? undefined;
+    } else {
+      // asking for a private room (Play alone, Private room) never matches a public one, even with a free seat
+      if (m.private !== true && m.alone !== true) for (const r of this.rooms.values()) {
+        if (r.scope === s.scope && r.game === s.game && r.slot === this.slotOf(s) && r.specKey === specKey && !r.priv && !r.banned.has(who.seat) && (r.seats.has(who.seat) || r.seats.size < r.spec.max)) { room = r; break; }
+      }
+      if (!room) room = this.create(s, spec, specKey, "", m.private === true || m.alone === true, m.alone === true ? who.seat : "") ?? undefined;
+    }
+    if (!room) return;   // refused in create()
+    if (room.banned.has(who.seat)) { this.refuse("removed"); return s.end(CLOSE.removed, "the host removed you from this room"); }
+    let seat = room.seats.get(who.seat);
+    if (seat) {
+      // The same person again (refresh, second tab, dropped connection): take the seat over in one step; the old connection is closed and its
+      // late messages are refused (it is dead before it closes).
+      const old = seat.session;
+      if (old && old !== s) { this.refuse("replaced"); old.seat = null; old.room = null; old.end(CLOSE.replaced, "opened in another tab"); }
+      seat.name = who.name;
+      // A new page counts its actions from 1 again: start the seat's count over, and forget actions the old page sent (their answers would reach
+      // the new page under ids it reuses).
+      seat.lastAct = 0;
+      for (const [aid, a] of room.actions) if (a.from === seat) room.actions.delete(aid);
+    } else {
+      if (room.seats.size >= room.spec.max) {
+        // a seat held for someone who dropped out gives way to a person who is here, once they have been gone evictAfterMs (a blink keeps the
+        // seat): a page that was put away first, then the longest gone; the room keeps its other players
+        let gone: Seat | null = null;
+        const better = (x: Seat, y: Seat) => x.hidden !== y.hidden ? x.hidden : x.offlineAt < y.offlineAt;
+        for (const x of room.seats.values()) if (!x.session && x.offlineAt && now - x.offlineAt >= L.evictAfterMs && (!gone || better(x, gone))) gone = x;
+        if (gone && room.seats.size > 1) this.removeSeat(room, gone);
+        if (room.seats.size >= room.spec.max) { this.refuse("full"); return s.end(CLOSE.full, "this room is full"); }
+      }
+      seat = { key: who.seat, id: this.publicId(s.scope, who.seat), name: who.name, guest: who.guest, state: {}, session: null, hidden: false, stalled: false, since: now, offlineAt: 0, lastAct: 0, prof: null, profLoad: null, profDirty: false, profAt: 0, stateBytes: 2, kept: false, profV: 1 };
+      room.seats.set(seat.key, seat);
+      room.byId.set(seat.id, seat);
+    }
+    if (Array.isArray(m.f)) for (const f of m.f.slice(0, 16)) if (typeof f === "string" && f.length <= 8) s.feats.add(f);
+    // what was waiting goes out first, so a newcomer gets no effect from before they joined and nobody gets a change after the "joined"
+    this.flush(room);
+    seat.session = s; seat.offlineAt = 0; seat.hidden = m.hidden === true; seat.stalled = false;
+    s.room = room; s.seat = seat;
+    const kept = seat.kept; seat.kept = false;
+    // Others hear "joined" (and a host change, if any); the newcomer gets one welcome with the full current state, host and term included.
+    this.broadcast(room, { t: "joined", player: view(seat) }, s);
+    this.elect(room, s);
+    s.send({ ...this.snapshot(room, seat, "welcome"), ...(kept ? { kept: true } : {}) });
+    this.active(room);
+  }
+
+  /** A person did something in the room: its idle time starts over (a warning already sent is taken back). */
+  private active(room: Room) {
+    room.activeAt = this.now();
+    if (room.idleWarned) { room.idleWarned = false; this.broadcast(room, { t: "idle", closesAt: 0 }); }
+  }
+
+  /** Nobody did anything for idleMs: saves are written, every page hears 4010 (game.js offers a new room), the room is gone. */
+  private closeIdle(room: Room) {
+    this.count("rooms_idle");
+    this.flush(room);
+    this.saveWorld(room, true);
+    for (const seat of room.seats.values()) { this.flushProfile(room, seat, true); seat.session?.end(CLOSE.idle, "closed: nobody played for a while"); }
+    this.closeRoom(room);
+  }
+
+  /** Moves a room running an older version of its game off its code (see join): a new hidden code, private, its save lease kept; its pages hear
+   *  `newer` (game.js: press restart to play the new version). */
+  private retire(room: Room) {
+    const old = room.key;
+    let code = "";
+    for (let i = 0; i < 50 && (!code || this.rooms.has(`${room.scope}|${code}`)); i++) code = Array.from(crypto.randomBytes(4), (b) => CODE_ABC[b % CODE_ABC.length]).join("");
+    this.rooms.delete(old);
+    room.code = code; room.key = `${room.scope}|${code}`; room.priv = true;
+    this.rooms.set(room.key, room);
+    if (room.lease && this.leases.get(room.lease) === old) this.leases.set(room.lease, room.key);
+    this.count("rooms_retired");
+    for (const x of room.seats.values()) x.session?.send({ t: "newer" });
+  }
+
+  private create(s: Session, spec: Spec, specKey: string, code: string, priv: boolean, owner = ""): Room | null {
+    const L = this.limits;
+    if (this.rooms.size >= L.maxRooms) { this.refuse("rooms"); s.end(CLOSE.full, "the server has no free rooms, try again soon"); return null; }
+    if (this.pressure) { this.refuse("busy_rooms"); s.end(CLOSE.busy, "the server is busy, try again soon"); return null; }
+    let inScope = 0;
+    for (const r of this.rooms.values()) if (r.scope === s.scope) inScope++;
+    if (inScope >= (this.roomsPerScope?.(s.scope) ?? L.maxRoomsPerScope)) { this.refuse("scope_rooms"); s.end(CLOSE.full, "too many rooms are open for this game, try again soon"); return null; }
+    if (!code) {
+      for (let i = 0; i < 50 && (!code || this.rooms.has(`${s.scope}|${code}`)); i++) code = Array.from(crypto.randomBytes(4), (b) => CODE_ABC[b % CODE_ABC.length]).join("");
+    }
+    const room: Room = {
+      key: `${s.scope}|${code}`, scope: s.scope, game: s.game, spec, specKey, code, priv, slot: this.slotOf(s), owner, world: !!this.saves && !!s.slot && spec.save,
+      lease: "", saveBusy: false, worldState: "off", loadTries: 0, loadAt: 0, startWait: null, sid: crypto.randomBytes(6).toString("base64url"), saved: null, wrev: 0, savedWrev: 0, savedAt: 0, noSave: false, resumed: false, seats: new Map(), byId: new Map(), banned: new Set(),
+      match: 1, rev: 0, term: 0, host: null, hostAliveAt: 0, started: false, played: false, shared: {}, pendPlayers: new Map(), pendShared: null, pendPT: new Map(), pendSC: 0, pendAt: 0,
+      actions: new Map(), nextAction: 1, tickN: 0, outBytes: 0, outMark: 0, outRate: 0, phase: crypto.randomInt(10), outAvg: 0, slowF: 1, slowTold: false, pendFx: [], pendFxBytes: 0, sharedBytes: 2, sizeChecks: 0, created: this.now(), flushN: 0, tiers: null, activeAt: this.now(), idleWarned: false,
+    };
+    this.rooms.set(room.key, room);
+    if (room.world) {
+      // One room at a time plays a given save: a second room of the same game (another group, a second tab alone) plays unsaved, so the two never
+      // write over each other. The lease goes when the room closes; the next new room then continues the save.
+      const lk = `${room.scope}|${room.slot}|${worldOf(room) ?? ""}`;
+      // a room whose players are all gone (seats only held for a comeback, e.g. someone who left their game alone and came straight back) hands
+      // the save on: it is written first, then that room closes
+      const holder = this.rooms.get(this.leases.get(lk) ?? "");
+      if (holder && ![...holder.seats.values()].some((x) => x.session)) {
+        this.saveWorld(holder, true);
+        for (const x of holder.seats.values()) this.flushProfile(holder, x, true);
+        this.closeRoom(holder);
+      } else if (!holder) this.leases.delete(lk);
+      if (this.leases.has(lk)) { room.world = false; room.saveBusy = true; }
+      else { this.leases.set(lk, room.key); room.lease = lk; room.worldState = "loading"; this.loadWorld(room); }
+    }
+    return room;
+  }
+
+  private snapshot(room: Room, seat: Seat, t: "welcome" | "sync") {
+    return {
+      t, you: seat.id, boot: this.boot, ver: room.game.slice(0, 16), code: room.code, private: room.priv, max: room.spec.max, match: room.match, rev: room.rev, term: room.term,
+      host: room.host?.id ?? null, started: room.started, players: [...room.seats.values()].map(view), shared: room.shared, now: this.now(),
+      ...(seat.kept ? { kept: true } : {}), tick: room.seats.size > 8 ? this.limits.tickMs * 2 : this.limits.tickMs,
+      saved: room.saved ? { at: room.saved.at, v: room.saved.v } : null, resumed: room.resumed, ...(room.saveBusy ? { saveBusy: true } : {}), ...(room.worldState === "failed" ? { saveError: true } : {}),
+    };
+  }
+
+  // ---- host -----------------------------------------------------------------------------------------------------------------------------
+  /** Host = the longest-connected player who is online and visible. None = the match waits. Every change starts a new term. */
+  private elect(room: Room, quiet?: Session) {
+    const ok = (x: Seat | null) => !!x && !!x.session && !x.hidden && !x.stalled;
+    if (ok(room.host)) return;
+    let best: Seat | null = null;
+    for (const x of room.seats.values()) if (ok(x) && (!best || x.since < best.since)) best = x;
+    if (best === room.host) return;
+    this.flush(room, quiet);   // changes written under the old term go out before the new term is announced
+    room.host = best;
+    room.term++;
+    room.hostAliveAt = this.now();
+    // Actions the old host never answered fail now, so no player waits on a host that is gone.
+    for (const [aid, a] of room.actions) { a.from.session?.send({ t: "result", id: a.ref, ok: false, error: "host changed" }); room.actions.delete(aid); }
+    this.broadcast(room, { t: "host", term: room.term, player: best?.id ?? null }, quiet);
+  }
+
+  private alive(room: Room, seat: Seat, m: Record<string, unknown>) {
+    if (room.host === seat && m.term === room.term) room.hostAliveAt = this.now();
+    else if (seat.stalled) { seat.stalled = false;   /* its game loop runs again */ this.broadcast(room, { t: "online", player: view(seat) }); this.elect(room); }
+  }
+
+  private vis(room: Room, seat: Seat, m: Record<string, unknown>) {
+    const hidden = m.hidden === true;
+    if (seat.hidden === hidden) return;
+    seat.hidden = hidden;
+    // a hidden page gets no state frames (a phone in the background on mobile data): one fresh copy when it is back, before the next frame
+    if (!hidden && seat.session && !seat.session.lagging) seat.session.send(this.snapshot(room, seat, "sync"));
+    this.broadcast(room, { t: "online", player: view(seat) });
+    this.elect(room);
+  }
+
+  // ---- state ----------------------------------------------------------------------------------------------------------------------------
+  private me(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    const p = m.s;
+    if (!p || typeof p !== "object" || Array.isArray(p)) return this.err(s, "bad_value");
+    const bad = badPath(p);
+    if (bad !== null) return this.err(s, "bad_value", bad);
+    for (const [k, v] of Object.entries(p)) {
+      const range = room.spec.player[k];
+      if (range && v !== null && (typeof v !== "number" || v < range[0] || v > range[1])) return this.err(s, "out_of_range", k);
+    }
+    const ch = changedOnly(seat.state, p as Record<string, unknown>);
+    if (!ch) return;   // nothing changed: nothing applied, counted or sent
+    const size = this.sized(seat.stateBytes + sizeDelta(seat.state, ch), this.limits.playerStateBytes, () => applyPatch(seat.state, ch), room);
+    if (size > this.limits.playerStateBytes) return this.err(s, "too_big");
+    seat.state = applyPatch(seat.state, ch);
+    seat.stateBytes = size;
+    room.rev++;
+    const pend = room.pendPlayers.get(seat.id) ?? {};
+    joinPatch(pend, ch);
+    room.pendPlayers.set(seat.id, pend);
+    room.pendPT.set(seat.id, this.stamp(m.c));
+  }
+
+  private sharedWrite(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    if (room.host !== seat) return this.err(s, "not_host");
+    if (m.term !== room.term) return this.err(s, "old_term");
+    const p = m.p;
+    if (!p || typeof p !== "object" || Array.isArray(p)) return this.err(s, "bad_value");
+    const bad = badPath(p);
+    if (bad !== null) return this.err(s, "bad_value", bad);
+    room.hostAliveAt = this.now();
+    const ch = changedOnly(room.shared, p as Record<string, unknown>);
+    if (!ch) return;   // a write that changes nothing: no new revision, no world save, nothing sent
+    const size = this.sized(room.sharedBytes + sizeDelta(room.shared, ch), this.limits.sharedStateBytes, () => applyPatch(room.shared, ch), room);
+    if (size > this.limits.sharedStateBytes) return this.err(s, "too_big");
+    room.shared = applyPatch(room.shared, ch);
+    room.sharedBytes = size;
+    room.rev++; room.wrev++;
+    if (!room.pendShared) room.pendShared = { patch: {}, term: room.term };
+    joinPatch(room.pendShared.patch, ch);
+    room.pendSC = this.stamp(m.c);
+  }
+
+  /** The sender's sample time of a write (its shared clock, whole ms), trusted within 500 ms back and 50 ms ahead; else now. Pages draw others
+   *  at these times, so updates sent 80 ms apart are drawn 80 ms apart whatever the fan-out tick did to them. */
+  private stamp(c: unknown): number {
+    const now = this.now();
+    return typeof c === "number" && Number.isFinite(c) && c >= now - 500 && c <= now + 50 ? Math.round(c) : now;
+  }
+
+  /** A state size after a write: the running count, or the exact one when it is within 10% of the limit and every 256th time (a drift is counted). */
+  private sized(running: number, limit: number, next: () => Record<string, unknown>, room: Room): number {
+    if (running < limit * 0.9 && ++room.sizeChecks % 256) return running;
+    const exact = bytes(next());
+    if (exact !== running) this.refuse("size_drift");
+    return exact;
+  }
+
+  private fx(room: Room, seat: Seat, m: Record<string, unknown>, s: Session) {
+    if (typeof m.name !== "string" || !NAME_RE.test(m.name) || (m.data !== undefined && !plain(m.data))) return this.err(s, "bad_value");
+    const len = bytes(m.data ?? null);
+    if (len > 1024) return this.err(s, "bad_value");
+    // effects ride the next frame (one frame a tick instead of one per shot); a full queue goes out at once, nothing is dropped
+    room.pendFx.push({ from: seat.id, name: m.name, data: m.data ?? null });
+    room.pendFxBytes += len + m.name.length + 32;
+    if (room.pendFx.length >= 128 || room.pendFxBytes >= 16 * 1024) this.flush(room);
+  }
+
+  private rename(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    if (!seat.guest) return this.err(s, "not_allowed");
+    const n = cleanName(m.name);
+    if (!n) return this.err(s, "bad_value");
+    seat.name = n;
+    this.broadcast(room, { t: "online", player: view(seat) });
+  }
+
+  // ---- actions: any player asks, the host decides, the asker gets one answer -------------------------------------------------------------
+  private act(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    const ref = m.id;
+    if (typeof ref !== "number" || !Number.isInteger(ref) || ref < 1) return this.bad(s, "bad action id");
+    if (ref <= seat.lastAct) return;   // a duplicate: already answered once
+    seat.lastAct = ref;
+    if (!s.acts.take(this.now())) { this.refuse("actions"); return s.send({ t: "result", id: ref, ok: false, error: "too_fast" }); }
+    if (typeof m.name !== "string" || !NAME_RE.test(m.name) || (m.data !== undefined && !plain(m.data)) || bytes(m.data ?? null) > 1024) return s.send({ t: "result", id: ref, ok: false, error: "bad_value" });
+    // The game's own actions wait for the match; the shell's (a leading underscore: switch team, take a seat) are for the lobby too.
+    const lobbyOk = m.name.startsWith("_");
+    if (!room.host?.session || (!room.started && !lobbyOk)) return s.send({ t: "result", id: ref, ok: false, error: room.host?.session ? "not_started" : "no_host" });
+    const aid = room.nextAction++;
+    room.actions.set(aid, { from: seat, ref, at: this.now() });
+    room.host.session.send({ t: "action", id: aid, from: seat.id, name: m.name, data: m.data ?? null });
+  }
+
+  private result(room: Room, seat: Seat, m: Record<string, unknown>) {
+    if (room.host !== seat || typeof m.id !== "number") return;
+    const a = room.actions.get(m.id);
+    if (!a) return;   // answered or timed out already
+    room.actions.delete(m.id);
+    const error = typeof m.error === "string" ? m.error.slice(0, 80) : undefined;
+    a.from.session?.send({ t: "result", id: a.ref, ok: m.ok === true, ...(m.ok === true || !error ? {} : { error }) });
+  }
+
+  // ---- match ----------------------------------------------------------------------------------------------------------------------------
+  private startMatch(s: Session, room: Room, seat: Seat, resume = false) {
+    if (room.host !== seat) return this.err(s, "not_host");
+    if (room.started) return;
+    // the save is still loading: wait for it (3 s at most), so a host who taps Start early is still asked Continue or New game
+    if (room.worldState === "loading") { room.startWait = { resume, at: this.now() }; return; }
+    this.beginMatch(room, resume);
+  }
+
+  private beginMatch(room: Room, resume: boolean) {
+    room.startWait = null;
+    room.noSave = false;
+    if (resume && room.saved) {
+      // Continue: the saved world becomes the shared state (the shell's clock key excepted); the game's setup must not overwrite it
+      this.flush(room);
+      if (room.played) { room.match++; room.played = false; }
+      room.rev++; room.wrev++; room.resumed = true;
+      room.shared = Object.fromEntries(Object.entries(structuredClone(room.saved.data)).filter(([k]) => k !== "_go"));
+      room.sharedBytes = bytes(room.shared);
+      room.started = true;
+      return this.broadcast(room, { t: "started", match: room.match, shared: room.shared, rev: room.rev, resumed: true });
+    }
+    room.resumed = false;
+    this.flush(room);   // effects from the lobby go out before "started"
+    if (room.played) {
+      // a finished match: the next one starts from empty shared state
+      this.flush(room);
+      room.match++; room.rev++; room.played = false;
+      room.shared = Object.fromEntries(Object.entries(room.shared).filter(([k]) => k.startsWith("_")));   // the shell's keys (teams) carry over
+      room.sharedBytes = bytes(room.shared);
+    }
+    room.started = true;
+    this.broadcast(room, { t: "started", match: room.match, shared: room.shared, rev: room.rev });
+  }
+
+  private endMatch(s: Session, room: Room, seat: Seat) {
+    if (room.host !== seat) return this.err(s, "not_host");
+    if (!room.started) return;
+    this.flush(room);
+    room.started = false;
+    room.played = true;
+    this.saveWorld(room, true);
+    for (const x of room.seats.values()) this.flushProfile(room, x, true);
+    for (const [aid, a] of room.actions) { a.from.session?.send({ t: "result", id: a.ref, ok: false, error: "match over" }); room.actions.delete(aid); }
+    this.broadcast(room, { t: "ended", match: room.match, shared: room.shared });
+  }
+
+  private kick(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    if (room.host !== seat) return this.err(s, "not_host");
+    const target = typeof m.player === "string" ? room.byId.get(m.player) : undefined;
+    if (!target || target === seat) return this.err(s, "bad_value");
+    room.banned.add(target.key);
+    const ts = target.session;
+    this.removeSeat(room, target);
+    ts?.end(CLOSE.removed, "the host removed you from this room");
+  }
+
+  private removeSeat(room: Room, seat: Seat) {
+    this.flush(room);   // the player's last effects and changes go out before their "left"
+    room.seats.delete(seat.key);
+    room.byId.delete(seat.id);
+    room.pendPlayers.delete(seat.id);
+    this.flushProfile(room, seat, true);
+    if (seat.session) { seat.session.room = null; seat.session.seat = null; seat.session = null; }
+    this.broadcast(room, { t: "left", player: seat.id });
+    if (!room.seats.size) { this.saveWorld(room, true); this.closeRoom(room); return; }
+    this.elect(room);
+  }
+
+  /** Forget a room (its last write is already queued) and give up its save lease. Every path that ends a room goes through here. */
+  private closeRoom(room: Room) {
+    if (this.rooms.get(room.key) === room) this.rooms.delete(room.key);
+    if (room.lease && this.leases.get(room.lease) === room.key) this.leases.delete(room.lease);
+    room.lease = "";
+  }
+
+  // ---- leaving --------------------------------------------------------------------------------------------------------------------------
+  /** A socket is gone. Its seat stays (offline) for seatHoldMs, without host duty. */
+  drop(s: Session) {
+    if (s.dead) return;
+    s.dead = true;
+    this.sessions.delete(s);
+    if (!s.who) this.pending--;
+    const n = (this.perAddr.get(s.addr) || 1) - 1;
+    if (n > 0) this.perAddr.set(s.addr, n); else this.perAddr.delete(s.addr);
+    const room = s.room, seat = s.seat;
+    s.room = null; s.seat = null;
+    if (!room || !seat || seat.session !== s) return;
+    seat.session = null;
+    seat.offlineAt = this.now();
+    this.flushProfile(room, seat, true);
+    this.broadcast(room, { t: "online", player: view(seat) });
+    this.elect(room);
+  }
+
+  // ---- saves: a person's profile, a game's world --------------------------------------------------------------------------------------
+  private write(scope: string, slot: string, who: string | null, data: unknown | null, session?: string, v?: number): Promise<boolean> {
+    const key = `${scope}|${slot}|${who ?? ""}`;
+    const p = this.saves!.store(scope, slot, who, data, session || v ? { ...(session ? { session } : {}), ...(v ? { v } : {}) } : undefined).then(() => { this.count("saves_ok"); return true; }, () => { this.refuse("save_failed"); return false; });
+    this.writing.add(p);
+    this.writingKey.set(key, p);
+    void p.then(() => { this.writing.delete(p); if (this.writingKey.get(key) === p) this.writingKey.delete(key); });
+    return p;
+  }
+
+  /** The person's profile, loaded once per seat. Null = saving is off here, or the store failed (nothing is ever written over a profile that did not load). */
+  private loadProfile(room: Room, seat: Seat): Promise<Record<string, unknown> | null> {
+    if (!this.saves || !room.slot) return Promise.resolve(null);
+    if (seat.prof) return Promise.resolve(seat.prof);
+    if (seat.profLoad) return seat.profLoad;
+    const p = this.saves.load(room.scope, room.slot, seat.key).then((r) => {
+      const d = r?.data;
+      seat.prof = isObj(d) && plain(d) && bytes(d) <= this.limits.profileBytes ? d : {};
+      seat.profV = typeof r?.v === "number" ? r.v : 1;
+      return seat.prof;
+    }).catch(() => { this.refuse("load_failed"); seat.profLoad = null; return null; });
+    seat.profLoad = p;
+    return p;
+  }
+
+  private async sendProfile(s: Session, room: Room, seat: Seat) {
+    const p = await this.loadProfile(room, seat);
+    if (!s.dead) s.send(p ? { t: "profile", p, v: seat.profV } : { t: "profile", off: true });
+  }
+
+  private saveProfile(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    const patch = m.p;
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) return this.err(s, "bad_value");
+    const bad = badPath(patch);
+    if (bad !== null) return this.err(s, "bad_value", bad);
+    void this.loadProfile(room, seat).then((cur) => {
+      if (!cur) return this.err(s, "save_off");
+      const next = applyPatch(seat.prof ?? cur, patch as Record<string, unknown>);   // not `cur`: two saves queued behind one load must build on each other
+      if (bytes(next) > this.limits.profileBytes) return this.err(s, "too_big");
+      seat.prof = next; seat.profDirty = true;
+    });
+  }
+
+  private flushProfile(room: Room, seat: Seat, force: boolean) {
+    if (!seat.profDirty || !seat.prof || !room.slot) return;
+    const now = this.now();
+    if (!force && now - seat.profAt < this.limits.profileEveryMs) return;
+    seat.profDirty = false; seat.profAt = now;
+    void this.write(room.scope, room.slot, seat.key, seat.prof, undefined, room.spec.saveVersion).then((ok) => { if (!ok) seat.profDirty = true; });
+  }
+
+  /** Load the room's world save. Until it is loaded nothing is written or cleared (a save that could not be read is never written over); a failed
+   *  load is tried again after 2, 5, 15 s and then every 30 s, and the lobby says the game is not being saved meanwhile. */
+  private loadWorld(room: Room) {
+    const who = worldOf(room), key = `${room.scope}|${room.slot}|${who ?? ""}`;
+    // after a write of this same save still on its way (a room that just handed it on), so the newest copy is read
+    const job = (this.writingKey.get(key) ?? Promise.resolve(true)).then(() => this.saves!.load(room.scope, room.slot, who)).then((r) => {
+      if (this.rooms.get(room.key) !== room || room.worldState === "ready") return;
+      const wasFailed = room.worldState === "failed";
+      room.worldState = "ready"; room.loadTries = 0;
+      if (wasFailed) this.broadcast(room, { t: "savestate", error: false });
+      const ok = !!r && isObj(r.data) && this.now() - r.at <= this.limits.saveDays * 86_400_000 && bytes(r.data) <= this.limits.sharedStateBytes;
+      if (ok) {
+        room.saved = { at: r!.at, data: r!.data as Record<string, unknown>, v: typeof r!.v === "number" ? r!.v : 1 };
+        // a match that started without it (the load failed or was late) is not saved: its first write would replace the real game
+        if (room.started) room.noSave = true;
+        this.broadcast(room, { t: "saved", at: r!.at, v: room.saved.v });
+      }
+      const w = room.startWait;
+      if (w && room.host && !room.started) {
+        if (ok && !w.resume) room.startWait = null;   // a save turned up: the host is asked Continue or New game first
+        else this.beginMatch(room, w.resume && ok);
+      }
+    }).catch(() => {
+      this.refuse("load_failed");
+      if (this.rooms.get(room.key) !== room || room.worldState === "ready") return;
+      this.loadFailed(room);
+    });
+    this.loading.add(job);
+    void job.then(() => this.loading.delete(job));
+  }
+
+  private loadFailed(room: Room) {
+    const first = room.worldState !== "failed";
+    room.worldState = "failed";
+    room.loadAt = this.now() + ([2000, 5000, 15_000][room.loadTries] ?? 30_000);
+    room.loadTries++;
+    if (first) this.broadcast(room, { t: "savestate", error: true });
+    const w = room.startWait;
+    if (w && room.host && !room.started) this.beginMatch(room, false);   // the host asked to start: play on, unsaved
+  }
+
+  /** Write the shared state as the world save when it changed (every worldEveryMs, or now when forced) and holds something besides the shell's own keys. */
+  private saveWorld(room: Room, force: boolean) {
+    if (!room.world || room.worldState !== "ready" || room.noSave || room.wrev === room.savedWrev) return;
+    const now = this.now();
+    if (!force && now - room.savedAt < this.limits.worldEveryMs) return;
+    const data = Object.fromEntries(Object.entries(structuredClone(room.shared)).filter(([k]) => k !== "_go"));
+    if (!Object.keys(data).some((k) => !k.startsWith("_"))) return;
+    const was = room.savedWrev, first = !room.saved;
+    room.savedWrev = room.wrev; room.savedAt = now;
+    room.saved = { at: now, data, v: room.spec.saveVersion };
+    if (first || force) this.broadcast(room, { t: "saved", at: now, v: room.saved.v });
+    this.worldWrites.push(now);
+    void this.write(room.scope, room.slot, worldOf(room), data, room.sid, room.spec.saveVersion).then((ok) => { if (!ok && room.savedWrev === room.wrev) room.savedWrev = was; });
+  }
+
+  /** {t:"world", clear:true}: the host ends the saved game (won, lost, abandoned); nothing is saved again until the next start. */
+  private worldMsg(s: Session, room: Room, seat: Seat, m: Record<string, unknown>) {
+    if (room.host !== seat) return this.err(s, "not_host");
+    if (m.clear !== true || !room.world) return this.err(s, "bad_value");
+    if (room.worldState !== "ready") return this.err(s, "save_off");   // a save that was never read is not cleared either
+    room.noSave = true; room.saved = null; room.savedWrev = room.wrev;
+    this.broadcast(room, { t: "saved", at: 0 });
+    void this.write(room.scope, room.slot, worldOf(room), null, room.sid);
+  }
+
+  // ---- fan-out --------------------------------------------------------------------------------------------------------------------------
+  private broadcast(room: Room, m: Record<string, unknown>, except?: Session) {
+    const text = JSON.stringify({ v: PROTOCOL, ...m });
+    let n = 0;
+    for (const seat of room.seats.values()) {
+      const s = seat.session;
+      if (!s || s === except || s.dead || s.lagging) continue;
+      n++;
+      try { s.conn.send(text); } catch { /* close handler cleans up */ }
+    }
+    this.sent(Buffer.byteLength(text), n, room);
+  }
+
+  /** Send a room's pending changes and effects now. Variants of one frame, each made once: the host does not get its own shared writes back
+   *  (it applied them), pages without "fxb" get effects as single fx messages, an effect never goes back to its sender's old-style page, and hidden
+   *  pages get nothing (one fresh copy when they come back). fxOnly: effects alone (big rooms send state every second tick, effects every tick).
+   *  tick: called by the fan-out tick. Readers on a slower rate (Session.div) get every div-th tick frame, with everything since their last one
+   *  merged in; any other call (a join, a leave, a new host, the start) sends every rate's frame at once, so those events never overtake a change. */
+  private flush(room: Room, except?: Session, fxOnly = false, tick = false) {
+    const cur = this.takePending(room, fxOnly);
+    if (tick && !fxOnly) room.flushN++;
+    if (cur) {
+      if (room.tiers) for (const acc of room.tiers.values()) foldFrame(acc, cur);
+      this.emit(room, cur, except, 1);
+    }
+    if (room.tiers) for (const [d, acc] of room.tiers) {
+      if (tick && (fxOnly || room.flushN % d)) continue;
+      if (acc.players.size || acc.shared || acc.fx.length) this.emit(room, acc, except, d);
+      room.tiers.set(d, emptyFrame());
+    }
+    // every rate's frame just went out: readers can change rate here without missing or repeating anything
+    if (!tick || (!fxOnly && room.flushN % 4 === 0)) this.retier(room);
+  }
+
+  /** The room's pending changes as one frame (null when there is nothing), and the pending lists cleared. */
+  private takePending(room: Room, fxOnly: boolean): Frame | null {
+    if (fxOnly ? !room.pendFx.length : !room.pendPlayers.size && !room.pendShared && !room.pendFx.length) return null;
+    const f: Frame = { players: new Map(), pt: new Map(), shared: null, sc: 0, fx: room.pendFx };
+    room.pendFx = []; room.pendFxBytes = 0;
+    if (!fxOnly) {
+      f.players = room.pendPlayers; f.pt = room.pendPT; f.shared = room.pendShared; f.sc = room.pendSC;
+      room.pendPlayers = new Map(); room.pendShared = null; room.pendPT = new Map();
+    }
+    return f;
+  }
+
+  /** Readers take their wanted rate (the slower of the hub's reading and the page's ask); the merged frames exist only for rates in use. */
+  private retier(room: Room) {
+    let used: Set<number> | null = null;
+    for (const seat of room.seats.values()) {
+      const x = seat.session;
+      if (!x) continue;
+      const want = Math.max(x.netDiv, x.askDiv);
+      if (want !== x.div) {
+        x.div = want;
+        this.count(want > 1 ? "rate_slower" : "rate_full");
+        x.send({ t: "rate", div: want, every: this.every(room) * this.limits.tickMs * want });   // the page sizes its smoothing delay to it
+      }
+      if (x.div > 1) (used ??= new Set()).add(x.div);
+    }
+    if (!used) { room.tiers = null; return; }
+    const tiers = room.tiers ?? new Map<number, Frame>();
+    for (const d of [...tiers.keys()]) if (!used.has(d)) tiers.delete(d);
+    for (const d of used) if (!tiers.has(d)) tiers.set(d, emptyFrame());
+    room.tiers = tiers;
+  }
+
+  /** One frame to the room's readers on rate 1/div. A room of one gets none: everything in it came from that page (its own moves, its
+   *  own shared writes as host, its own effects), so playing alone costs no data coming down. */
+  private emit(room: Room, f: Frame, except: Session | undefined, div: number) {
+    if (room.seats.size <= 1) return;
+    const base: Record<string, unknown> = { t: "delta", rev: room.rev, at: this.now() };
+    const fx = f.fx, sh = f.shared;
+    if (f.players.size) { base.players = Object.fromEntries(f.players); base.pt = Object.fromEntries(f.pt); }
+    if (sh) base.sc = f.sc;
+    // the host wrote the shared part in this term: it gets the frame without it
+    const hostS = sh && sh.term === room.term ? room.host?.session ?? null : null;
+    // each variant is made and measured once (bytes as on the wire: UTF-8, so names and text in any language count in full)
+    const texts = new Map<string, { text: string; bytes: number } | null>();
+    const textOf = (withShared: boolean, withFx: boolean) => {
+      const k = `${withShared ? 1 : 0}${withFx ? 1 : 0}`;
+      if (!texts.has(k)) {
+        const m: Record<string, unknown> = { ...base };
+        if (withFx && fx.length) m.fx = fx;
+        if (withShared && sh) { m.shared = sh.patch; m.st = sh.term; }
+        const text = m.players || m.fx || m.shared ? JSON.stringify({ v: PROTOCOL, ...m }) : null;
+        texts.set(k, text === null ? null : { text, bytes: Buffer.byteLength(text) });
+      }
+      return texts.get(k)!;
+    };
+    let frames = 0, out = 0;
+    const put = (x: Session, t: { text: string; bytes: number }) => { frames++; out += t.bytes; try { x.conn.send(t.text); } catch { /* close handler cleans up */ } };
+    for (const seat of room.seats.values()) {
+      const x = seat.session;
+      if (!x || x.div !== div || x === except || x.dead || x.lagging || seat.hidden) continue;
+      const fxb = x.feats.has("fxb");
+      const text = textOf(x !== hostS, fxb);
+      if (text) put(x, text);
+      if (!fxb) for (const e of fx) if (e.from !== seat.id) { const one = JSON.stringify({ v: PROTOCOL, t: "fx", ...e }); put(x, { text: one, bytes: Buffer.byteLength(one) }); }
+    }
+    this.meter.framesOut += frames; this.meter.bytesOut += out; room.outBytes += out;
+  }
+
+  /** The open rooms a page could join instead (rooms {spec?}): same namespace, game version and save slot; not private, not someone's game
+   *  alone, not empty. Per room: code, host name, players connected and away (dropped, seat held), max, started, match, the host's round trip to the hub (ms, 0 = not
+   *  known: the host's browser runs the rules, so its link is what a newcomer feels), slowed (the room sends less often than normal), full,
+   *  yours. Up to 50, the ones you can join first, then those waiting to start, then the fullest, then the newest. Made at most every 250 ms
+   *  per game; asking costs one token of a 1-a-second bucket. */
+  private roomList(s: Session, m: Record<string, unknown>): Record<string, unknown> {
+    if (!this.listRooms) return { t: "rooms", off: true };
+    const now = this.now(), slot = this.slotOf(s), key = `${s.scope}|${s.game}|${slot}`;
+    let hit = this.lists.get(key);
+    if (!hit || now - hit.at >= 250) {
+      const rooms: (Record<string, unknown> & { _r: Room })[] = [];
+      for (const r of this.rooms.values()) {
+        if (r.scope !== s.scope || r.game !== s.game || r.slot !== slot || r.priv || r.owner) continue;
+        if (this.limits.listIdleMs > 0 && now - r.activeAt > this.limits.listIdleMs) continue;   // probably left open and forgotten
+        let on = 0, away = 0, taken = 0;
+        for (const x of r.seats.values()) {
+          if (x.session) on++; else away++;   // a page put away (another tab) still holds its seat: counted as in
+          // a seat held for someone gone at least evictAfterMs gives way to a newcomer (join): it does not make the room full
+          if (x.session || !x.offlineAt || now - x.offlineAt < this.limits.evictAfterMs) taken++;
+        }
+        if (!on) continue;
+        const h = r.host?.session;
+        rooms.push({ _r: r, code: r.code, host: r.host?.name ?? null, players: on, away, max: r.spec.max, started: r.started, match: r.match,
+          ping: h?.rtt ?? 0, slowed: r.slowF > 1 || (this.pressure && r.seats.size > 4), full: taken >= r.spec.max, spec: r.specKey, created: r.created });
+      }
+      rooms.sort((a, b) => Number(a.full) - Number(b.full) || Number(a.started) - Number(b.started) || (b.players as number) - (a.players as number) || (b.created as number) - (a.created as number));
+      if (this.lists.size > 1000) this.lists.clear();
+      hit = { at: now, rooms: rooms.slice(0, 50).map(({ _r, created, ...x }) => { void _r; void created; return x; }) };
+      this.lists.set(key, hit);
+    }
+    // a page that says its spec sees only rooms it can join (another spec = another version of the game's options)
+    const want = m.spec !== undefined ? parseSpec(m.spec, this.limits.maxPlayers) : null;
+    const wantKey = want ? stable(want) : null;
+    const mine = s.room?.code;
+    const rooms = hit.rooms.filter((x) => !wantKey || x.spec === wantKey).map(({ spec, ...x }) => { void spec; return x.code === mine ? { ...x, you: true } : x; });
+    return { t: "rooms", rooms, at: now };
+  }
+
+  /** Every tickMs: send changes (every second tick in rooms over 8), handle slow readers, timeouts, silent hosts, expired seats. */
+  tick() {
+    const t0 = performance.now();
+    try { this.tickInner(); } finally { this.tickTimes[this.tickCount++ % this.tickTimes.length] = performance.now() - t0; }
+  }
+
+  /** A room over its data budget sends half as often (up to 8 times less), its host is told once (error too_much_data); it speeds up again when
+   *  the faster rate would be under 80% of the budget. */
+  private budget(r: Room) {
+    const L = this.limits;
+    r.outAvg = r.outAvg ? r.outAvg * 0.7 + r.outRate * 0.3 : r.outRate;
+    if (r.outAvg > L.roomOutBytes && r.slowF < 8) {
+      r.slowF *= 2; r.outAvg /= 2;
+      this.refuse("room_budget");
+      if (!r.slowTold && r.host?.session) { r.slowTold = true; this.err(r.host.session, "too_much_data"); }
+    } else if (r.slowF > 1 && r.outAvg * 2 < L.roomOutBytes * 0.8) { r.slowF /= 2; r.outAvg *= 2; }
+  }
+  /** How many ticks apart a room sends its state: 1 (50 ms), 2 in rooms over 8 players, times its own budget factor, times 2 under server pressure
+   *  for rooms over 4 players. */
+  private every(r: Room) { return (r.seats.size > 8 ? 2 : 1) * r.slowF * (this.pressure && r.seats.size > 4 ? 2 : 1); }
+
+  /** Once a second: the rates over the last second (server and per room). */
+  private meters(now: number) {
+    if (now - this.mark.at < 1000) return;
+    const sec = this.mark.at ? (now - this.mark.at) / 1000 : 1;
+    for (const k of ["framesOut", "bytesOut", "msgsIn"] as const) { this.rates[k] = Math.round((this.meter[k] - this.mark[k]) / sec); this.mark[k] = this.meter[k]; }
+    this.mark.at = now;
+    for (const r of this.rooms.values()) { r.outRate = Math.round((r.outBytes - r.outMark) / sec); r.outMark = r.outBytes; this.budget(r); }
+    // the whole server: over 80% of its data cap, or the event loop running late (p99 over 30 ms for 10 s, from the host process), bigger rooms
+    // send at half rate and new rooms wait; back to normal under 60% and a loop on time
+    const mbit = (this.rates.bytesOut * 8) / 1e6, cap = this.limits.maxOutMbit;
+    const late = (this.loopRecent?.p99 ?? 0) > 30;
+    if (!this.pressure && ((cap > 0 && mbit > cap * 0.8) || late)) { this.pressure = true; this.refuse("pressure"); }
+    else if (this.pressure && (cap <= 0 || mbit < cap * 0.6) && !late) this.pressure = false;
+    while (this.worldWrites.length && now - this.worldWrites[0] > 60_000) this.worldWrites.shift();
+  }
+
+  /** Everything but the room sends; `sendAll` false when subTick sends rooms on their own phase. */
+  private tickInner(sendAll = true) {
+    const L = this.limits, now = this.now();
+    this.meters(now);
+    for (const s of this.sessions) {
+      if ((!s.who || !s.room) && now - s.opened > L.pendingMs * (s.who ? 2 : 1) && !s.dead) { this.refuse("timeout"); s.end(s.who ? CLOSE.badMessage : CLOSE.notAllowed, s.who ? "join took too long" : "sign-in took too long"); continue; }
+      const b = s.conn.buffered();
+      if (b > L.dropBytes) { this.refuse("too_slow"); s.end(CLOSE.tooSlow, "connection too slow"); continue; }
+      if (b > L.slowBytes) { s.lagging = true; continue; }
+      if (s.lagging && b < L.slowBytes / 4 && s.room && s.seat) { s.lagging = false; s.send(this.snapshot(s.room, s.seat, "sync")); }
+      // a reader whose queue builds up goes to half the update rate (a second time after another second: a quarter); it goes back one step after
+      // its queue stayed near empty for rateUpMs. Slower fast, faster slowly, so a phone on a weak signal does not swing between the two.
+      if (b > L.rateBytes) {
+        s.clearAt = now;
+        if (s.netDiv < 4 && now - s.downAt >= 1000) { s.netDiv *= 2; s.downAt = now; }
+      } else if (b > 1024) s.clearAt = now;
+      else if (s.netDiv > 1 && now - s.clearAt >= L.rateUpMs) { s.netDiv /= 2; s.clearAt = now; }
+      // a visible page that went quiet (a phone that lost its signal): gone after silentMs, its seat held as for any drop. Hidden pages are left to
+      // the socket's own 30 s ping (browsers slow a hidden page's timers to once a minute).
+      if (s.seat && !s.seat.hidden && now - s.lastRx > L.silentMs) { this.refuse("silent"); s.end(CLOSE.silent, "no answer from this page"); }
+    }
+    // seats, silent hosts, action time-outs, load retries and save timers: once a second is exact enough (all are seconds long)
+    const house = now - this.houseAt >= 1000;
+    if (house) this.houseAt = now;
+    for (const room of this.rooms.values()) {
+      this.guard(room, () => {
+        room.tickN++;
+        if (house) this.housekeep(room, now);
+        if (!sendAll || this.rooms.get(room.key) !== room) return;
+        if (room.tickN % this.every(room)) this.flush(room, undefined, true, true);
+        else this.flush(room, undefined, false, true);
+      });
+    }
+  }
+
+  private housekeep(room: Room, now: number) {
+    const L = this.limits;
+    let gone: Seat[] | null = null;
+    for (const seat of room.seats.values()) if (!seat.session && seat.offlineAt && now - seat.offlineAt > (seat.hidden ? Math.max(L.seatHoldMs, L.awayHoldMs) : L.seatHoldMs)) (gone ??= []).push(seat);
+    if (gone) for (const seat of gone) this.removeSeat(room, seat);
+    if (this.rooms.get(room.key) !== room) return;
+    // idle rooms (PlayFab's lobby TTL works the same way: any member activity resets it): warned idleWarnMs before, then closed
+    if (L.idleMs > 0) {
+      const idle = now - room.activeAt;
+      if (idle >= L.idleMs) return this.closeIdle(room);
+      if (!room.idleWarned && idle >= L.idleMs - L.idleWarnMs) { room.idleWarned = true; this.flush(room); this.broadcast(room, { t: "idle", closesAt: room.activeAt + L.idleMs }); }
+    }
+    if (room.host && now - room.hostAliveAt > L.hostSilenceMs) {
+      // The host's connection is open but its game stopped (a frozen phone tab): hand host duty on.
+      const h = room.host;
+      h.stalled = true;
+      this.broadcast(room, { t: "online", player: view(h) });
+      this.elect(room);
+    }
+    for (const [aid, a] of room.actions) if (now - a.at > L.actionTimeoutMs) { room.actions.delete(aid); a.from.session?.send({ t: "result", id: a.ref, ok: false, error: "no answer" }); }
+    if (room.worldState === "loading" && room.startWait && now - room.startWait.at > 3000) { this.refuse("load_slow"); this.loadFailed(room); }
+    else if (room.worldState === "failed" && now >= room.loadAt) { room.loadAt = Infinity; this.loadWorld(room); }
+    this.saveWorld(room, false);
+    for (const x of room.seats.values()) this.flushProfile(room, x, false);
+  }
+
+  /** One room's part of a tick. An error there closes that room (1011) and the server keeps going: one bad room never stops the process. */
+  private guard(room: Room, fn: () => void) {
+    try { fn(); } catch (e) {
+      this.refuse("room_error");
+      if (!this.erred.has(room.game)) { this.erred.add(room.game); console.error(`tickcli: a room of game ${room.game} failed and was closed:`, (e as Error)?.message || e); }
+      try {
+        for (const seat of room.seats.values()) { const x = seat.session; if (x) { x.room = null; x.seat = null; x.end(CLOSE.roomError, "something went wrong in this room, join again"); } }
+      } catch { /* closing anyway */ }
+      this.closeRoom(room);
+    }
+  }
+
+  /** Called every tickMs / 5 by start(). Housekeeping once per tickMs; each room sends on its own phase (every 5 sub-ticks, every 10 in rooms
+   *  over 8 players, effects every 5), so 2,000 sockets are not written in one burst. tick() stays the one-call form for tests and simple hosts. */
+  subTick() {
+    const t0 = performance.now(), n = this.sub++;
+    try {
+      if (n % 5 === 0) this.tickInner(false);
+      for (const room of this.rooms.values()) {
+        const k = n + room.phase;
+        if (k % 5) continue;
+        this.guard(room, () => { if ((k / 5) % this.every(room)) this.flush(room, undefined, true, true); else this.flush(room, undefined, false, true); });
+      }
+    } finally { this.tickTimes[this.tickCount++ % this.tickTimes.length] = performance.now() - t0; }
+  }
+
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.subTick(), this.limits.tickMs / 5);
+    this.timer.unref?.();
+  }
+  stop() { if (this.timer) clearInterval(this.timer); this.timer = null; }
+
+  /** Server shutdown: pending changes and saves are written, the live rooms go to onSnapshot (the next process takes them back), then every player
+   *  hears 1012 and reconnects. Without onSnapshot a restart ends every match. */
+  async shutdown(): Promise<void> {
+    this.closing = true;
+    this.stop();
+    for (const room of this.rooms.values()) {
+      this.flush(room);
+      // an action nobody will answer fails now, as on a host change
+      for (const [aid, a] of room.actions) { a.from.session?.send({ t: "result", id: a.ref, ok: false, error: "server restarting" }); room.actions.delete(aid); }
+      this.saveWorld(room, true);
+      for (const x of room.seats.values()) this.flushProfile(room, x, true);
+    }
+    const snap = this.onSnapshot ? this.exportRooms() : null;
+    for (const s of [...this.sessions]) s.end(CLOSE.restart, "server restarting");
+    for (const room of [...this.rooms.values()]) this.closeRoom(room);
+    await this.settle();
+    if (snap) await this.onSnapshot!(snap);
+  }
+
+  /** The live rooms as plain JSON: everything a new process needs to carry on (sockets, timers and open actions are not kept). */
+  exportRooms(): RoomsSnapshot {
+    const rooms: SnapRoom[] = [];
+    for (const r of this.rooms.values()) {
+      if (r.seats.size === 0) continue;
+      rooms.push({
+        key: r.key, scope: r.scope, game: r.game, spec: r.spec, code: r.code, priv: r.priv, slot: r.slot, owner: r.owner, world: r.world, lease: r.lease, saveBusy: r.saveBusy,
+        worldState: r.worldState === "ready" ? "ready" : "loading", saved: r.saved, wrev: r.wrev, savedWrev: r.savedWrev, noSave: r.noSave, resumed: r.resumed, sid: r.sid,
+        match: r.match, rev: r.rev, term: r.term, started: r.started, played: r.played, shared: r.shared, banned: [...r.banned],
+        seats: [...r.seats.values()].map((x) => ({ key: x.key, id: x.id, name: x.name, guest: x.guest, state: x.state, hidden: x.hidden, since: x.since })),
+      });
+    }
+    return { format: SNAPSHOT_FORMAT, at: this.now(), rooms };
+  }
+
+  /** Take back rooms from exportRooms() after a restart: every seat offline (held 60 s for its player to come back), no host until one is back, a new
+   *  term, save leases taken again. A snapshot older than maxAgeMs or of another format is ignored. Returns how many rooms came back. */
+  importRooms(snap: unknown, o: { maxAgeMs?: number } = {}): number {
+    const sn = snap as RoomsSnapshot;
+    const now = this.now(), L = this.limits;
+    if (!sn || typeof sn !== "object" || sn.format !== SNAPSHOT_FORMAT || !Array.isArray(sn.rooms) || !(now - sn.at <= (o.maxAgeMs ?? 120_000))) return 0;
+    let n = 0;
+    for (const x of sn.rooms) {
+      if (this.rooms.size >= L.maxRooms || this.rooms.has(x.key)) continue;
+      const spec = parseSpec(x.spec, L.maxPlayers);
+      if (!spec || !isObj(x.shared) || !Array.isArray(x.seats)) continue;
+      const room: Room = {
+        key: x.key, scope: x.scope, game: x.game, spec, specKey: stable(spec), code: x.code, priv: !!x.priv, slot: x.slot, owner: x.owner, world: !!x.world, lease: "", saveBusy: !!x.saveBusy,
+        worldState: x.world ? x.worldState : "off", loadTries: 0, loadAt: 0, startWait: null, sid: x.sid, saved: x.saved && isObj(x.saved.data) ? x.saved : null, wrev: x.wrev, savedWrev: x.savedWrev, savedAt: now,
+        noSave: !!x.noSave, resumed: !!x.resumed, seats: new Map(), byId: new Map(), banned: new Set(x.banned), match: x.match, rev: x.rev, term: x.term + 1, host: null, hostAliveAt: now,
+        started: !!x.started, played: !!x.played, shared: x.shared, pendPlayers: new Map(), pendShared: null, pendPT: new Map(), pendSC: 0, pendAt: 0, actions: new Map(), nextAction: 1, tickN: 0,
+        outBytes: 0, outMark: 0, outRate: 0, phase: crypto.randomInt(10), outAvg: 0, slowF: 1, slowTold: false, pendFx: [], pendFxBytes: 0, sharedBytes: bytes(x.shared), sizeChecks: 0, created: this.now(), flushN: 0, tiers: null, activeAt: this.now(), idleWarned: false,
+      };
+      // held 60 s from now (seatHoldMs counts from offlineAt)
+      const off = now + Math.max(0, 60_000 - L.seatHoldMs);
+      for (const z of x.seats) {
+        const seat: Seat = { key: z.key, id: z.id, name: z.name, guest: !!z.guest, state: isObj(z.state) ? z.state : {}, session: null, hidden: !!z.hidden, stalled: false, since: z.since, offlineAt: off,
+          lastAct: 0, kept: true, profV: 1, prof: null, profLoad: null, profDirty: false, profAt: 0, stateBytes: bytes(isObj(z.state) ? z.state : {}) };
+        room.seats.set(seat.key, seat); room.byId.set(seat.id, seat);
+      }
+      if (x.world && x.lease) {
+        if (this.leases.has(x.lease)) { room.world = false; room.saveBusy = true; room.worldState = "off"; }
+        else { this.leases.set(x.lease, room.key); room.lease = x.lease; if (room.worldState === "loading") this.loadWorld(room); }
+      }
+      this.rooms.set(room.key, room);
+      n++;
+    }
+    return n;
+  }
+
+  /** Write every changed profile and world now and wait until the store has taken them (a restart, a test). */
+  flushSaves(): Promise<void> {
+    for (const room of this.rooms.values()) { this.saveWorld(room, true); for (const x of room.seats.values()) this.flushProfile(room, x, true); }
+    return this.settle();
+  }
+  /** Resolves once every world save being read now has been read (tests, a bench). */
+  async whenLoaded() { while (this.loading.size) await Promise.all([...this.loading]); }
+  private async settle() { while (this.writing.size) await Promise.all([...this.writing]); }
+
+  /** Close every room of one namespace (a public link stopped). */
+  closeScope(scope: string, reason = "this game is no longer shared") {
+    for (const room of [...this.rooms.values()]) {
+      if (room.scope !== scope) continue;
+      this.saveWorld(room, true);
+      for (const seat of room.seats.values()) { this.flushProfile(room, seat, true); seat.session?.end(CLOSE.notAllowed, reason); }
+      this.closeRoom(room);
+    }
+  }
+
+  /** One namespace's use right now: rooms, seats, connected players and bytes out a second (over the last second). For per-customer caps. */
+  scopeStats(scope: string): { rooms: number; players: number; online: number; bytesOut: number } {
+    let rooms = 0, players = 0, online = 0, bytesOut = 0;
+    for (const r of this.rooms.values()) {
+      if (r.scope !== scope) continue;
+      rooms++; bytesOut += r.outRate;
+      for (const x of r.seats.values()) { players++; if (x.session) online++; }
+    }
+    return { rooms, players, online, bytesOut };
+  }
+
+  stats(): HubStats {
+    let players = 0, online = 0, started = 0, slow = 0;
+    for (const r of this.rooms.values()) { if (r.started) started++; for (const s of r.seats.values()) { players++; if (s.session) online++; } }
+    for (const s of this.sessions) if (s.lagging) slow++;
+    const n = Math.min(this.tickCount, this.tickTimes.length), sorted = Array.from(this.tickTimes.subarray(0, n)).sort((a, b) => a - b);
+    const pct = (p: number) => (n ? Math.round(sorted[Math.min(n - 1, Math.floor(n * p))] * 100) / 100 : 0);
+    const top = [...this.rooms.values()].sort((a, b) => b.outRate - a.outRate).slice(0, 5).filter((r) => r.outRate > 0)
+      .map((r) => ({ players: r.seats.size, bytesOut: r.outRate, sharedBytes: r.sharedBytes }));
+    const live: LiveStats = {
+      ...this.rates, tickMs: { p50: pct(0.5), p99: pct(0.99), max: n ? Math.round(sorted[n - 1] * 100) / 100 : 0 }, slow, started,
+      savesOk: this.counts.saves_ok || 0, savesFailed: this.refused.save_failed || 0, loadsFailed: this.refused.load_failed || 0, worldWritesPerMin: this.worldWrites.length,
+      loop: this.loop, top, pressure: this.pressure, slowedRooms: [...this.rooms.values()].filter((r) => r.slowF > 1).length,
+    };
+    return { rooms: this.rooms.size, players, online, connections: this.sessions.size, pending: this.pending, refused: { ...this.refused }, live };
+  }
+}
+
+const view = (s: Seat): PlayerView => ({ id: s.id, name: s.name, online: !!s.session, hidden: s.hidden || s.stalled, guest: s.guest, state: s.state });
+
+/** A guest's display name: letters, digits, spaces, "_" and "-", at most 20 characters. */
+export function cleanName(raw: unknown): string | null {
+  if (typeof raw !== "string" || raw.length > 200) return null;
+  let s = raw.normalize("NFKC").replace(/[^\p{L}\p{N}\p{M} _-]/gu, "").replace(/(\p{M}{2})\p{M}+/gu, "$1").replace(/\s+/g, " ").trim();
+  s = Array.from(s).slice(0, 20).join("").trim();
+  return /[\p{L}\p{N}]/u.test(s) ? s : null;
+}