create-siltrun 0.1.0

package/templates/mass-grid/room.ts

@@ -0,0 +1,530 @@
+// room.ts — a MASS-GRID territory-capture room (Paper.io / Splix.io genre).
+//
+// This file runs SERVER-SIDE inside a deterministic realm: browsers submit intent, this
+// tick() decides truth, and every client receives the full authoritative state each tick.
+// Edit it while the dev loop runs — it hot-reloads. Two things live here, separated:
+//
+//   1. THE DEMO-ROOM LIFECYCLE SHELL — genre-agnostic, COPIED VERBATIM from the tower-
+//      defense template. One always-warm room: drop-in join, take over an abandoned
+//      player or start fresh, ready-up → rolling rounds → a new game auto-starts. No
+//      lobby. Normative spec + invariants: skills/demo-room-lifecycle.md.
+//   2. THE TERRITORY-CAPTURE GENRE — everything below the shell.
+//
+// Two ideas make this genre reach a CROWD in one room:
+//
+//   • THE STATE SHAPE IS THE WIRE SHAPE. There is no separate "encoding" step — the
+//     object tick() returns is JSON-marshaled into ONE UDP datagram (~1200 bytes) and
+//     sent as-is. So you engineer the STATE to be compact: the grid rides as a run-length
+//     string (`g`), players ride as a flat SLOT-INDEXED array (`players`), trails ride as
+//     turn-point polylines — never a per-cell or per-id object map. Naive id-keyed object
+//     state is the trap that blows the datagram at ~8 players; flat index-keyed state is
+//     what lets one datagram carry a whole board. (See skills/compact-snapshots.md.)
+//
+//   • SLOW TICK INSIDE A FAST CLOCK. The host ticks 60Hz, but a grid game wants ~6 steps/
+//     sec — so the sim only ADVANCES every STEP_TICKS ticks; ticks between just absorb
+//     input. Cheap, and it gives the classic grid cadence.
+//
+// MOVE INPUT RIDES THE RELIABLE LANE (`room.events.send`), NOT presence datagrams. A slow
+// discrete grid game wants ORDERED, no-drop turns — a dropped turn is a death. The genre→
+// lane rule: fast-continuous games use the presence/datagram lane; slow-discrete grid
+// games use the reliable events lane. (See skills/genre-lane-mapping.md.)
+import type { Room, Input, Ctx } from "@siltrun/room";
+
+// ════════════════════════════════════════════════════════════════════════════════════
+// ══ DEMO-ROOM LIFECYCLE SHELL — genre-agnostic. Copy verbatim.                      ══
+// ══ Normative spec + invariants: skills/demo-room-lifecycle.md                       ══
+// ════════════════════════════════════════════════════════════════════════════════════
+
+export type Phase = "gathering" | "playing" | "gameover";
+
+/** A fixed seat at the table. `id` is the peer holding it (null = empty). A seat whose
+ *  peer left MID-GAME is kept (`abandoned`) so a newcomer can take it over — its game
+ *  data (towers, etc.) keeps running. The original can also reclaim it by rejoining. */
+export type Seat = { id: string | null; ready: boolean; abandoned: boolean };
+
+/** Shell-owned meta. Namespaced under one key so the genre state stays cleanly separable
+ *  and this whole block copies without collision. */
+export type Shell = {
+  phase: Phase;
+  seats: Seat[];
+  round: number;      // increments each game start
+  phaseSince: number; // ctx.tick when the current phase began — drives countdowns
+  over: boolean;      // the GENRE sets this true to end a game (playing → gameover)
+};
+
+export type ShellOpts = {
+  seats: number;         // fixed table size
+  minPlayers: number;    // ready seats required to start a game
+  gameoverTicks: number; // how long the gameover screen holds before auto-reset
+};
+
+export function initShell(o: ShellOpts): Shell {
+  return {
+    phase: "gathering",
+    seats: Array.from({ length: o.seats }, () => ({ id: null, ready: false, abandoned: false })),
+    round: 0,
+    phaseSince: 0,
+    over: false,
+  };
+}
+
+/** Seat a peer: resume your own seat (reconnect), else claim an empty seat, else TAKE
+ *  OVER an abandoned seat (adopt its in-progress game data). No seat available →
+ *  spectator (returns -1); a mid-game spectator waits for the next gathering. */
+function seatFor(shell: Shell, id: string): number {
+  const own = shell.seats.findIndex((s) => s.id === id);
+  if (own >= 0) { shell.seats[own].abandoned = false; return own; }        // reconnect
+  const empty = shell.seats.findIndex((s) => s.id === null);
+  if (empty >= 0) { shell.seats[empty] = { id, ready: false, abandoned: false }; return empty; }
+  const aband = shell.seats.findIndex((s) => s.abandoned);
+  if (aband >= 0) { shell.seats[aband].id = id; shell.seats[aband].abandoned = false; return aband; } // takeover
+  return -1; // spectator
+}
+
+/** Runs FIRST in tick(). Applies membership (join/leave) + `ready` events, then opens a
+ *  round when enough seats are ready. Returns "start" on the tick a game begins (the genre
+ *  seeds a fresh game on that signal); the caller passes back which seats went live. */
+export function openRound(shell: Shell, inputs: Input[], ctx: Ctx, o: ShellOpts): "start" | null {
+  for (const ev of inputs) {
+    if (ev.kind === "join") {
+      seatFor(shell, ev.id);
+    } else if (ev.kind === "leave") {
+      const i = shell.seats.findIndex((s) => s.id === ev.id);
+      if (i < 0) continue;
+      if (shell.phase === "playing") shell.seats[i].abandoned = true;       // keep data, allow takeover
+      else shell.seats[i] = { id: null, ready: false, abandoned: false };   // no game to preserve → free it
+    } else if (ev.kind === "event" && isReady(ev.data)) {
+      const i = shell.seats.findIndex((s) => s.id === ev.from);
+      if (i >= 0 && shell.phase === "gathering") shell.seats[i].ready = true;
+    }
+  }
+  if (shell.phase === "gathering") {
+    const readyCount = shell.seats.filter((s) => s.id && s.ready && !s.abandoned).length;
+    if (readyCount >= o.minPlayers) {
+      shell.phase = "playing";
+      shell.round += 1;
+      shell.phaseSince = ctx.tick;
+      shell.over = false;
+      for (const s of shell.seats) s.ready = false;
+      return "start";
+    }
+  }
+  return null;
+}
+
+/** Runs LAST in tick(). Advances playing→gameover (when the genre set `over`) and
+ *  gameover→gathering (after the countdown, freeing abandoned seats). Returns "reset" on
+ *  the tick a fresh gathering begins (the genre clears its game state on that signal). */
+export function closeRound(shell: Shell, ctx: Ctx, o: ShellOpts): "reset" | null {
+  if (shell.phase === "playing" && shell.over) {
+    shell.phase = "gameover";
+    shell.phaseSince = ctx.tick;
+    return null;
+  }
+  if (shell.phase === "gameover" && ctx.tick - shell.phaseSince >= o.gameoverTicks) {
+    shell.phase = "gathering";
+    shell.phaseSince = ctx.tick;
+    shell.over = false;
+    for (const s of shell.seats) {
+      if (s.abandoned) { s.id = null; s.abandoned = false; } // its player is gone
+      s.ready = false;
+    }
+    return "reset";
+  }
+  return null;
+}
+
+function isReady(data: unknown): boolean {
+  return !!data && typeof data === "object" && (data as { type?: unknown }).type === "ready";
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════
+// ══ END DEMO-ROOM LIFECYCLE SHELL                                                    ══
+// ════════════════════════════════════════════════════════════════════════════════════
+
+// ── TERRITORY-CAPTURE GENRE ───────────────────────────────────────────────────
+
+// tuneables.  SEATS × GRID × TRAIL-LENGTH is a DATAGRAM-BUDGET decision, not a taste one:
+// the whole State is JSON-marshaled into ONE ~1200-byte datagram every tick, so every
+// per-player and per-cell byte is multiplied by the crowd. The budget breaks down as:
+//   • the copied lifecycle shell — ~55B per SEAT (fixed; can't shrink the verbatim block),
+//   • the grid RLE — grows with cells AND territory fragmentation; row-major RLE is the
+//     dominant, data-dependent cost (jagged contested borders multiply runs),
+//   • the players — flat-encoded, but TRAILS are variable-length, so they are capped.
+// These numbers were MEASURED, not guessed (room.test.ts + the probes behind it). Under a
+// messy-realistic worst (all 6 seats trailing at the cap, jagged contested board), 20×20 ×
+// 6 seats ≈ 1099B — fits with headroom. 28×28 broke it (~1400B); 8 seats never fits once
+// players trail. VERTICALLY-STRIPED territory breaks the RLE at ANY size/seat count (the
+// grid alone can exceed a datagram) — that is the JSON-snapshot ceiling, fixed only by
+// binary/delta snapshots (out of scope for a demo). It degrades GRACEFULLY, not fatally:
+// state datagrams are latest-wins + droppable, so an oversized tick is dropped and the
+// client recovers on the next in-budget tick — a brief stutter, not a freeze. The math +
+// scaling path is in skills/compact-snapshots.md; room.test.ts is the guard.
+export const W = 20;              // grid width (cells)
+export const H = 20;              // grid height
+export const STEP_TICKS = 9;      // 60Hz / 9 ≈ 6.7 sim-steps/sec
+export const ROUND_TICKS = 60 * 63; // ~63s round (in 60Hz ticks)
+export const RESPAWN_TICKS = 108; // ~1.8s dead → respawn (in 60Hz ticks)
+export const MAX_TRAIL_TURNS = 6; // trail turn-points cap → bounds the datagram AND is a
+//                                   genre mechanic: over-extend (too many bends out in the
+//                                   open) and you die. Straight trails are cheap (1 turn).
+const SPAWN = 3;                  // starting blob is SPAWN×SPAWN
+const SHELL_OPTS: ShellOpts = { seats: 6, minPlayers: 2, gameoverTicks: 200 };
+
+// direction: 0=up 1=right 2=down 3=left
+const DX = [0, 1, 0, -1];
+const DY = [-1, 0, 1, 0];
+const opposite = (d: number) => (d + 2) % 4;
+
+/** Per-seat game data. This is the WORKING form used inside tick() — readable objects.
+ *  It is NEVER stored in state directly (that would be the fat id/object-map trap). Instead
+ *  tick() decodes the flat wire form (`pf`/`pt`) into these, mutates them, and re-encodes —
+ *  exactly the pack/unpack discipline the grid uses. The state IS the wire; keep it flat. */
+export type Player = {
+  x: number;  // head cell x
+  y: number;  // head cell y
+  d: number;  // facing direction 0..3
+  nd: number; // buffered next direction (applied on the next step)
+  a: 0 | 1;   // alive (0 = dead, awaiting respawn)
+  t: number[]; // trail turn-points, flat [x0,y0,x1,y1,…]; empty when home
+  rs: number; // respawn-at ctx.tick when dead (0 when alive)
+};
+
+export type State = {
+  shell: Shell;
+  w: number;
+  h: number;
+  g: string;      // row-major RLE of cell ownership (0 empty, slot+1 = owner)
+  // players ride FLAT, index-keyed by seat slot — the compact wire form:
+  pf: number[];   // scalars, STRIDE per slot: [alive(0/1/2), x, y, d, nd, rs]  (0 = empty seat)
+  pt: number[][]; // trail turn-points per slot (flat [x0,y0,…]); [] when home/empty
+  win: number;    // winning slot of the last round (-1 = none) — for the gameover screen
+};
+
+/** A reliable-lane event: a turn (0..3) or ready-up (`{type:"ready"}`, handled by shell). */
+export type Cmd = { turn: number };
+
+const STRIDE = 6; // pf scalars per slot: [alive, x, y, d, nd, rs]
+// alive marker in pf: 0 = empty seat (no player), 1 = alive, 2 = dead (awaiting respawn)
+
+/** Decode the flat wire form into readable working players (index === seat slot). */
+export function readPlayers(state: State): (Player | null)[] {
+  const out: (Player | null)[] = [];
+  for (let slot = 0; slot < state.pf.length / STRIDE; slot++) {
+    const b = slot * STRIDE;
+    const mark = state.pf[b]!;
+    if (mark === 0) { out.push(null); continue; }
+    out.push({
+      a: mark === 1 ? 1 : 0,
+      x: state.pf[b + 1]!, y: state.pf[b + 2]!, d: state.pf[b + 3]!,
+      nd: state.pf[b + 4]!, rs: state.pf[b + 5]!,
+      t: state.pt[slot] ?? [],
+    });
+  }
+  return out;
+}
+
+/** Encode working players back into the flat wire form. */
+export function writePlayers(state: State, players: (Player | null)[]): void {
+  const pf: number[] = [];
+  const pt: number[][] = [];
+  for (const pl of players) {
+    if (!pl) { pf.push(0, 0, 0, 0, 0, 0); pt.push([]); continue; }
+    pf.push(pl.a ? 1 : 2, pl.x, pl.y, pl.d, pl.nd, pl.rs);
+    pt.push(pl.t);
+  }
+  state.pf = pf;
+  state.pt = pt;
+}
+
+// ── grid RLE codec ────────────────────────────────────────────────────────────
+// A run is "<value36>.<len36>"; runs joined by ",". Value is the owner (0 empty, slot+1).
+export function encodeGrid(cells: Int16Array): string {
+  const runs: string[] = [];
+  let cur = cells[0]!, len = 1;
+  for (let i = 1; i < cells.length; i++) {
+    if (cells[i] === cur) len++;
+    else { runs.push(cur.toString(36) + "." + len.toString(36)); cur = cells[i]!; len = 1; }
+  }
+  runs.push(cur.toString(36) + "." + len.toString(36));
+  return runs.join(",");
+}
+export function decodeGrid(rle: string, w: number, h: number): Int16Array {
+  const out = new Int16Array(w * h);
+  if (rle.length === 0) return out;
+  let i = 0;
+  for (const run of rle.split(",")) {
+    const dot = run.indexOf(".");
+    const val = parseInt(run.slice(0, dot), 36);
+    const len = parseInt(run.slice(dot + 1), 36);
+    out.fill(val, i, i + len);
+    i += len;
+  }
+  return out;
+}
+
+// ── trail geometry ────────────────────────────────────────────────────────────
+// Expand a turn-point polyline (+ the live head) into the set of cell indices it covers.
+// Consecutive points are always axis-aligned, so each segment is a straight walk.
+export function trailCells(t: number[], headX: number, headY: number, w: number): number[] {
+  const pts: [number, number][] = [];
+  for (let i = 0; i < t.length; i += 2) pts.push([t[i]!, t[i + 1]!]);
+  pts.push([headX, headY]);
+  const seen = new Set<number>();
+  const out: number[] = [];
+  const push = (x: number, y: number) => {
+    const idx = y * w + x;
+    if (!seen.has(idx)) { seen.add(idx); out.push(idx); }
+  };
+  push(pts[0]![0], pts[0]![1]);
+  for (let i = 1; i < pts.length; i++) {
+    let [x, y] = pts[i - 1]!;
+    const [tx, ty] = pts[i]!;
+    const sx = Math.sign(tx - x), sy = Math.sign(ty - y);
+    let guard = 0;
+    while (x !== tx || y !== ty) {
+      x += sx; y += sy; push(x, y);
+      if (++guard > 4096) throw new Error(`trailCells non-axis-aligned segment [${pts[i-1]}]->[${pts[i]}] in [${t}] head[${headX},${headY}]`);
+    }
+  }
+  return out;
+}
+
+// ── flood-fill claim ──────────────────────────────────────────────────────────
+// Close a loop: the trail cells become owned, then every cell the OUTSIDE border can't
+// reach (without crossing the owner's territory) is enclosed → claimed. Captures empty
+// pockets AND enemy cells the loop wrapped around. O(cells), on claim-events only.
+export function claim(grid: Int16Array, w: number, h: number, owner: number, trail: number[]): void {
+  for (const c of trail) grid[c] = owner;
+  const outside = new Uint8Array(w * h);
+  const q: number[] = [];
+  const visit = (idx: number) => {
+    if (outside[idx] || grid[idx] === owner) return;
+    outside[idx] = 1;
+    q.push(idx);
+  };
+  for (let x = 0; x < w; x++) { visit(x); visit((h - 1) * w + x); }
+  for (let y = 0; y < h; y++) { visit(y * w); visit(y * w + w - 1); }
+  for (let head = 0; head < q.length; head++) {
+    const idx = q[head]!, x = idx % w, y = (idx / w) | 0;
+    if (x > 0) visit(idx - 1);
+    if (x < w - 1) visit(idx + 1);
+    if (y > 0) visit(idx - w);
+    if (y < h - 1) visit(idx + w);
+  }
+  for (let i = 0; i < grid.length; i++) if (grid[i] !== owner && !outside[i]) grid[i] = owner;
+}
+
+export function countCells(grid: Int16Array, owner: number): number {
+  let n = 0;
+  for (let i = 0; i < grid.length; i++) if (grid[i] === owner) n++;
+  return n;
+}
+
+// ── genre lifecycle glue ────────────────────────────────────────────────────────
+function freshState(): State {
+  const s: State = {
+    shell: initShell(SHELL_OPTS),
+    w: W,
+    h: H,
+    g: encodeGrid(new Int16Array(W * H)),
+    pf: [],
+    pt: [],
+    win: -1,
+  };
+  writePlayers(s, Array.from({ length: SHELL_OPTS.seats }, () => null));
+  return s;
+}
+
+function spawn(grid: Int16Array, w: number, h: number, slot: number, rnd: () => number): Player {
+  const m = SPAWN;
+  const r = (SPAWN - 1) >> 1;
+  // find a spawn center whose SPAWN×SPAWN footprint is empty, so every player gets a real
+  // home (a player with no territory can never close a loop — it would be stuck). Retry a
+  // few times; fall back to the last pick if the board is crowded (rare at demo scale).
+  let cx = m, cy = m;
+  for (let attempt = 0; attempt < 12; attempt++) {
+    cx = m + Math.floor(rnd() * (w - 2 * m));
+    cy = m + Math.floor(rnd() * (h - 2 * m));
+    let clear = true;
+    for (let dy = -r; dy <= r && clear; dy++)
+      for (let dx = -r; dx <= r; dx++) if (grid[(cy + dy) * w + (cx + dx)] !== 0) { clear = false; break; }
+    if (clear) break;
+  }
+  const owner = slot + 1;
+  for (let dy = -r; dy <= r; dy++)
+    for (let dx = -r; dx <= r; dx++) {
+      const x = cx + dx, y = cy + dy;
+      if (x >= 0 && x < w && y >= 0 && y < h) grid[y * w + x] = owner;
+    }
+  return { x: cx, y: cy, d: 1, nd: 1, a: 1, t: [], rs: 0 };
+}
+
+function release(grid: Int16Array, owner: number): void {
+  for (let i = 0; i < grid.length; i++) if (grid[i] === owner) grid[i] = 0;
+}
+
+/** GENRE ← "start": seed a fresh board and spawn a player for every occupied seat. */
+function startGame(state: State, players: (Player | null)[], grid: Int16Array, rnd: () => number): void {
+  grid.fill(0);
+  for (let slot = 0; slot < state.shell.seats.length; slot++) {
+    players[slot] = state.shell.seats[slot]!.id ? spawn(grid, state.w, state.h, slot, rnd) : null;
+  }
+  state.win = -1;
+}
+
+/** GENRE ← "reset": drop all game data (the board goes empty for the next gathering). */
+function clearGame(state: State, players: (Player | null)[], grid: Int16Array): void {
+  grid.fill(0);
+  for (let slot = 0; slot < players.length; slot++) players[slot] = null;
+  state.win = -1;
+}
+
+/** Reconcile players to seats mid-game: a fresh arrival / takeover of an emptied slot gets
+ *  a new player; a seat that emptied loses its player + territory. Abandoned seats keep
+ *  their id (so their player + territory persist, frozen, awaiting takeover). */
+function syncPlayers(state: State, players: (Player | null)[], grid: Int16Array, rnd: () => number): void {
+  for (let slot = 0; slot < state.shell.seats.length; slot++) {
+    const occupied = state.shell.seats[slot]!.id !== null;
+    if (occupied && !players[slot]) players[slot] = spawn(grid, state.w, state.h, slot, rnd);
+    else if (!occupied && players[slot]) { release(grid, slot + 1); players[slot] = null; }
+  }
+}
+
+// Advance the whole sim one grid-step. Mutates `grid` and players.
+function simStep(state: State, players: (Player | null)[], grid: Int16Array, ctx: Ctx): void {
+  const { w, h } = state;
+  const seats = state.shell.seats;
+
+  // 1. apply buffered turns + move each alive, non-abandoned head one cell.
+  for (let slot = 0; slot < players.length; slot++) {
+    const pl = players[slot];
+    if (!pl || !pl.a || seats[slot]!.abandoned) continue; // abandoned players freeze until taken over
+    const prevDir = pl.d;
+    if (pl.nd !== opposite(pl.d)) pl.d = pl.nd; // no 180° reversal
+    const turned = pl.d !== prevDir; // did this tick change heading?
+    const ox = pl.x, oy = pl.y;
+    const nx = ox + DX[pl.d]!, ny = oy + DY[pl.d]!;
+    if (nx < 0 || nx >= w || ny < 0 || ny >= h) { // ran into the wall → die
+      pl.a = 0; pl.rs = ctx.tick + RESPAWN_TICKS; release(grid, slot + 1); pl.t = [];
+      continue;
+    }
+    const owner = slot + 1;
+    const newIsOutside = grid[ny * w + nx] !== owner;
+    // Trail turn-points: consecutive points MUST be axis-aligned, so a corner is recorded
+    // only when the heading actually changed this tick (`turned`). The current cell (ox,oy)
+    // is that corner. On leaving home the first point anchors the trail to the territory edge.
+    if (newIsOutside) {
+      if (pl.t.length === 0) {
+        pl.t.push(ox, oy); // entry: anchor on the last owned cell
+      } else if (turned) {
+        if (pl.t.length >= MAX_TRAIL_TURNS * 2) { // over-extension death → bounds trail wire cost
+          pl.a = 0; pl.rs = ctx.tick + RESPAWN_TICKS; release(grid, slot + 1); pl.t = [];
+          continue;
+        }
+        pl.t.push(ox, oy); // record the corner
+      }
+    }
+    pl.x = nx; pl.y = ny;
+  }
+
+  // 2. collisions: a head sitting on ANY trail cell (not its own live head) cuts that
+  //    trail's owner; two heads on one cell → both die.
+  const trailOwnerOf = new Int16Array(w * h).fill(-1);
+  for (let slot = 0; slot < players.length; slot++) {
+    const pl = players[slot];
+    if (!pl || !pl.a || pl.t.length === 0) continue;
+    for (const c of trailCells(pl.t, pl.x, pl.y, w)) if (c !== pl.y * w + pl.x) trailOwnerOf[c] = slot;
+  }
+  const kills = new Set<number>();
+  const headAt = new Map<number, number[]>();
+  for (let slot = 0; slot < players.length; slot++) {
+    const pl = players[slot];
+    if (!pl || !pl.a) continue;
+    const idx = pl.y * w + pl.x;
+    let arr = headAt.get(idx);
+    if (!arr) { arr = []; headAt.set(idx, arr); }
+    arr.push(slot);
+    if (trailOwnerOf[idx]! >= 0) kills.add(trailOwnerOf[idx]!);
+  }
+  for (const [, slots] of headAt) if (slots.length > 1) for (const s of slots) kills.add(s);
+  for (const slot of kills) {
+    const pl = players[slot];
+    if (!pl) continue;
+    pl.a = 0; pl.rs = ctx.tick + RESPAWN_TICKS; release(grid, slot + 1); pl.t = [];
+  }
+
+  // 3. claims: an alive player whose head re-entered its OWN territory with a live trail
+  //    closes the loop.
+  for (let slot = 0; slot < players.length; slot++) {
+    const pl = players[slot];
+    if (!pl || !pl.a || pl.t.length === 0) continue;
+    const owner = slot + 1;
+    if (grid[pl.y * w + pl.x] === owner) {
+      claim(grid, w, h, owner, trailCells(pl.t, pl.x, pl.y, w));
+      pl.t = [];
+    }
+  }
+
+  // 4. respawns
+  for (let slot = 0; slot < players.length; slot++) {
+    const pl = players[slot];
+    if (pl && !pl.a && pl.rs > 0 && ctx.tick >= pl.rs && seats[slot]!.id !== null)
+      players[slot] = spawn(grid, w, h, slot, ctx.random);
+  }
+}
+
+function mostTerritory(players: (Player | null)[], grid: Int16Array): number {
+  let best = -1, bestN = -1;
+  for (let slot = 0; slot < players.length; slot++) {
+    if (!players[slot]) continue;
+    const n = countCells(grid, slot + 1);
+    if (n > bestN) { bestN = n; best = slot; }
+  }
+  return best;
+}
+
+export default {
+  init(): State {
+    return freshState();
+  },
+  tick(state = freshState(), inputs, ctx): State {
+    // unpack the compact wire form into readable working structures (state IS the wire)
+    const grid = decodeGrid(state.g, state.w, state.h);
+    const players = readPlayers(state);
+
+    // ── the lifecycle shell drives the room (runs FIRST) ──
+    if (openRound(state.shell, inputs, ctx, SHELL_OPTS) === "start") startGame(state, players, grid, ctx.random);
+
+    if (state.shell.phase === "playing") {
+      syncPlayers(state, players, grid, ctx.random); // mid-game join / takeover / departure
+
+      // buffer turn intents every tick; the sim consumes them on the next step
+      for (const ev of inputs) {
+        if (ev.kind !== "event") continue;
+        const turn = (ev.data as Partial<Cmd>)?.turn;
+        if (turn === undefined || turn < 0 || turn > 3) continue;
+        const slot = state.shell.seats.findIndex((s) => s.id === ev.from);
+        const pl = slot >= 0 ? players[slot] : null;
+        if (pl && pl.a) pl.nd = turn;
+      }
+
+      // advance the slow sim only on step boundaries
+      if (ctx.tick % STEP_TICKS === 0) simStep(state, players, grid, ctx);
+
+      // timer horn: round elapsed → most territory wins → hand the shell `over`
+      if (ctx.tick - state.shell.phaseSince >= ROUND_TICKS) {
+        state.win = mostTerritory(players, grid);
+        state.shell.over = true;
+      }
+    }
+
+    // ── the shell closes the round (runs LAST) ──
+    if (closeRound(state.shell, ctx, SHELL_OPTS) === "reset") clearGame(state, players, grid);
+
+    // re-pack the working structures into the compact wire form
+    state.g = encodeGrid(grid);
+    writePlayers(state, players);
+    return state;
+  },
+} satisfies Room<State, Cmd>;

package/templates/mass-grid/skills/authoritative-tick.md

@@ -0,0 +1,116 @@
+# The authoritative tick — how server truth works
+
+Read this before changing any server logic in `room.ts`. It is the core Silt model; every
+other skill assumes it.
+
+## The contract
+
+`room.ts` default-exports an object with one required method (and an optional `init`):
+
+```ts
+export default {
+  init() { return freshState(); },              // runs once when the room is created
+  tick(state = freshState(), inputs, ctx) {      // 60×/sec while ≥1 peer is present
+    /* mutate state, return it */ return state;
+  },
+} satisfies Room<State, Cmd>;
+```
+
+- Runs **server-side**, **60 times per second**, while ≥1 peer is present (an empty room pauses).
+- Receives a **fresh clone of the canonical state** each tick. Mutate it freely and return it.
+  **Never stash a reference across ticks** — next tick gets a new clone; a stashed reference is
+  a determinism bug waiting to happen.
+- Returns the new state, which the server **broadcasts in full to every client**.
+
+## Intent in, truth out
+
+Clients cannot write state. They call `send(...)` (see `skills/genre-lane-mapping.md`), which
+arrives in `tick` as an entry in the `inputs` batch. Your `tick` is the ONLY place truth is
+decided. The pattern — **validate intent, then commit**. From this template, a turn:
+
+```ts
+const turn = (ev.data as Partial<Cmd>)?.turn;
+if (turn === undefined || turn < 0 || turn > 3) continue; // reject: not a valid direction
+if (pl && pl.a) pl.nd = turn;                             // accept: buffered, applied next step
+```
+
+And the sim itself refuses an illegal move — you can't reverse into your own neck:
+
+```ts
+if (pl.nd !== opposite(pl.d)) pl.d = pl.nd; // a 180° reversal is silently ignored
+```
+
+A malicious client can *ask* to teleport or reverse; the server decides what actually happens.
+This is the whole security model — never trust intent, always decide in `tick`.
+
+## The input batch
+
+`inputs` is an ordered `Input<Cmd>[]`. Each entry is one of:
+
+| `kind` | fields | meaning |
+|---|---|---|
+| `"join"` | `id` | a peer joined |
+| `"leave"` | `id`, `reason: "left" \| "timeout"` | a peer left (clean bye vs dropped) |
+| `"input"` | `from`, `data: Cmd` | a peer's latest **datagram** intent (droppable, latest-wins) |
+| `"event"` | `from`, `data: unknown` | a peer's **reliable** event (ordered) — here, `ready` + `turn` |
+
+Ordering within a tick is deterministic: joins, then leaves (by id), then reliable events
+(arrival order), then each present peer's single latest `input`. Membership rides the same batch
+— there are no join/leave callbacks; you handle them by looping `inputs`. This genre reads only
+`event`s (ready-up handled by the shell, turns by the genre) — it doesn't use the datagram
+`input` lane at all (see `skills/genre-lane-mapping.md` for why).
+
+## The determinism realm — the rule that bites first
+
+`tick` runs in a sandbox where **non-deterministic APIs are removed**. A determinism doctor
+replays your contract on every hot-reload and **rejects** it if two runs of the same inputs
+diverge. Inside `tick` you must NOT use:
+
+- `Date.now()`, `performance.now()`, `new Date()` — use `ctx.time` / `ctx.tick`.
+- `Math.random()`, `crypto.getRandomValues` — use `ctx.random()`.
+- `fetch`, timers, or any I/O.
+
+The `ctx` gives deterministic substitutes:
+
+```ts
+ctx.tick     // integer tick count from 0 — THE clock. Count ticks to measure time.
+ctx.dt       // fixed 1/60. Never wall time.
+ctx.time     // ctx.tick * ctx.dt, seconds. Derived.
+ctx.random() // deterministic hash(seed, tick, drawIndex) → [0,1). Reproducible.
+ctx.emit(ev) // queue a reliable event to broadcast AFTER this tick (from "@server").
+```
+
+This template uses `ctx.random()` to place spawns and `ctx.tick` for the round timer and
+respawn countdowns. If the doctor rejects a change, you reached for a forbidden API — find it
+and route through `ctx`.
+
+## Slow sim inside a fast clock
+
+`tick` runs at 60Hz, but a grid game wants ~6 steps/sec. So the sim only ADVANCES every
+`STEP_TICKS` ticks; the ticks in between just absorb input and return state unchanged:
+
+```ts
+if (ctx.tick % STEP_TICKS === 0) simStep(state, players, grid, ctx);
+```
+
+Turns buffer as they arrive (any tick) and are consumed on the next step. This is a common Silt
+pattern — a cheap way to get a slower discrete cadence on the fixed 60Hz loop.
+
+## Failure is safe
+
+Throwing inside `tick` **skips that tick** — the last good state holds, the room survives. One
+bad input can't kill the room. Still, prefer explicit validation over relying on throws.
+
+## Verify
+
+`tick` is a pure function of `(state, inputs, ctx)`, so test it with no browser: build inputs,
+call `tick`, assert the returned state. See `room.test.ts` — membership, phase transitions,
+claim/collision/respawn, and the datagram budget are all asserted by scripted ticks.
+
+Two test styles live there, and you pick by what you're proving:
+- **Drive the game forward** — use the `makeRunner()` helper (`step(inputs)` ticks the sim one
+  step at a time from an empty room). Best for lifecycle and "play it and see" assertions.
+- **Pin an exact board** — construct a `State` literal (grid + `writePlayers([...])`) and call
+  `contract.tick(state, inputs, makeCtx(...))` once. Best when a precise pre-seeded position
+  matters (the collision test does this) — you control the whole board instead of playing into
+  it. `makeCtx(tick, seed)` gives a deterministic `Ctx`.