create-siltrun 0.1.0

package/templates/tower-defense/room.ts

@@ -0,0 +1,321 @@
+// room.ts — co-op tower defense. This file runs SERVER-SIDE at 60Hz 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
+// is running — it hot-reloads (a determinism doctor re-checks each reload).
+//
+// Two things live here, deliberately separated:
+//   1. THE DEMO-ROOM LIFECYCLE SHELL — genre-agnostic. One always-warm persistent room:
+//      drop-in join, take over an abandoned player or start fresh, ready-up → rolling
+//      rounds → play until you lose → a new game auto-starts. No lobby. Other genre
+//      templates COPY this block verbatim. Normative spec: skills/demo-room-lifecycle.md.
+//   2. THE TOWER-DEFENSE GENRE — everything below the shell. Replace this to build a
+//      different game on the same lifecycle.
+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                                                    ══
+// ════════════════════════════════════════════════════════════════════════════════════
+
+// ─────────────────────────────────────────────────────────────────────────────────────
+// TOWER-DEFENSE GENRE — replace everything below to build a different game.
+//
+// Design notes (each mechanic is here to TEACH a Silt substrate concept):
+//   • Waves spawn on a ctx.tick schedule with ctx.random jitter  → the determinism realm
+//   • Creeps walk a fixed server-side path; clients interpolate   → server-owns-truth
+//   • Fixed build slots; place via a reliable event, server valid.→ reliable lane + intent
+//   • Teammate cursors ride the datagram lane (kind:"input")      → latest-wins presence
+//   • Shared gold + shared lives; a leak costs a life; 0 = loss   → co-op shared state
+//
+// STATE BUDGET (see skills/state-budget.md): the whole State is broadcast every tick in
+// ONE ~1200B datagram. Short keys on the arrays that scale (creeps/towers) are a
+// deliberate budget choice — measured by room.test.ts. Positions are DERIVED client-side
+// from (waypoint index + progress), never stored.
+// ─────────────────────────────────────────────────────────────────────────────────────
+
+// The creeps' path as grid waypoints (0..1 arena space). Rendering derives pixel positions.
+const PATH: ReadonlyArray<readonly [number, number]> = [
+  [0.0, 0.2], [0.8, 0.2], [0.8, 0.5], [0.2, 0.5], [0.2, 0.8], [1.0, 0.8],
+];
+// Fixed build slots (0..1 arena space) — the only places a tower may go.
+const SLOTS: ReadonlyArray<readonly [number, number]> = [
+  [0.5, 0.12], [0.9, 0.35], [0.5, 0.42], [0.1, 0.42], [0.35, 0.62], [0.5, 0.9], [0.85, 0.65], [0.1, 0.72],
+];
+// Tower kinds: [cost, range(arena units), damage, cooldown(ticks)].
+const KINDS: ReadonlyArray<readonly [number, number, number, number]> = [
+  [50, 0.18, 3, 30], // 0: arrow — cheap, steady
+  [90, 0.14, 8, 55], // 1: cannon — pricier, hits hard
+];
+const CAPS = { creeps: 14, towers: SLOTS.length }; // hard ceilings — keep state under MTU
+const WAVES = 5;
+const CREEP_SPEED = 0.006; // arena units / tick along the path
+const START_GOLD = 120;
+const START_LIVES = 20;
+
+type Creep = { i: number; w: number; t: number; h: number }; // id, waypoint idx, seg progress 0..1, hp
+type Tower = { s: number; k: number; c: number };            // slot idx, kind, cooldown-remaining
+type Cursor = { x: number; y: number };
+
+export type State = {
+  shell: Shell;
+  gold: number;
+  lives: number;
+  wave: number;      // 0 = not started; 1..WAVES active
+  creeps: Creep[];
+  towers: Tower[];
+  next: number;      // next creep id
+  spawnLeft: number; // creeps still to spawn this wave
+  spawnCd: number;   // ticks until next spawn
+  cursors: Record<string, Cursor>; // teammate pointers — datagram lane, latest-wins
+};
+
+/** The datagram-lane intent: a teammate's live cursor. */
+export type Cmd = { x: number; y: number };
+/** A reliable-lane event: place a tower, or ready-up. */
+type Place = { type: "place"; slot: number; kind: number };
+
+const SHELL_OPTS: ShellOpts = { seats: 2, minPlayers: 2, gameoverTicks: 180 };
+
+function freshState(): State {
+  return {
+    shell: initShell(SHELL_OPTS),
+    gold: START_GOLD, lives: START_LIVES, wave: 0,
+    creeps: [], towers: [], next: 0, spawnLeft: 0, spawnCd: 0, cursors: {},
+  };
+}
+
+function startGame(state: State): void {
+  state.gold = START_GOLD;
+  state.lives = START_LIVES;
+  state.wave = 0;
+  state.creeps = [];
+  state.towers = [];
+  state.next = 0;
+  state.spawnLeft = 0;
+  state.spawnCd = 0;
+  beginWave(state, 1);
+}
+
+function clearGame(state: State): void {
+  state.wave = 0;
+  state.creeps = [];
+  state.towers = [];
+  state.spawnLeft = 0;
+  state.spawnCd = 0;
+}
+
+function beginWave(state: State, wave: number): void {
+  state.wave = wave;
+  state.spawnLeft = 3 + wave * 2; // more creeps each wave
+  state.spawnCd = 0;
+}
+
+function dist(ax: number, ay: number, bx: number, by: number): number {
+  return Math.hypot(ax - bx, ay - by);
+}
+
+/** Derive a creep's arena position from (waypoint idx + progress). Pure — clients run the
+ *  same math to render, so positions never need to live in state. */
+function creepPos(c: Creep): [number, number] {
+  const a = PATH[c.w], b = PATH[Math.min(c.w + 1, PATH.length - 1)];
+  return [a[0] + (b[0] - a[0]) * c.t, a[1] + (b[1] - a[1]) * c.t];
+}
+
+/** One tick of the tower-defense game. Only runs while shell.phase === "playing". */
+function stepGame(state: State, inputs: Input<Cmd>[], ctx: Ctx): void {
+  // 1. reliable events: tower placement (server validates — occupied? affordable?)
+  for (const ev of inputs) {
+    if (ev.kind !== "event") continue;
+    const d = ev.data as Partial<Place>;
+    if (d?.type !== "place") continue;
+    const slot = d.slot ?? -1, kind = d.kind ?? -1;
+    if (slot < 0 || slot >= SLOTS.length || kind < 0 || kind >= KINDS.length) continue; // bad input
+    if (state.towers.some((t) => t.s === slot)) continue;      // slot occupied
+    if (state.towers.length >= CAPS.towers) continue;          // ceiling
+    const cost = KINDS[kind][0];
+    if (state.gold < cost) continue;                           // can't afford
+    state.gold -= cost;
+    state.towers.push({ s: slot, k: kind, c: 0 });             // truth: the server placed it
+  }
+
+  // 2. spawn this wave's creeps on a tick schedule with deterministic jitter
+  if (state.spawnLeft > 0) {
+    if (state.spawnCd <= 0) {
+      if (state.creeps.length < CAPS.creeps) {
+        const hp = 8 + state.wave * 4;
+        state.creeps.push({ i: state.next++, w: 0, t: 0, h: hp });
+        state.spawnLeft -= 1;
+        state.spawnCd = 24 + Math.floor(ctx.random() * 12); // jitter — ctx.random, never Math.random
+      }
+    } else {
+      state.spawnCd -= 1;
+    }
+  }
+
+  // 3. towers fire (nearest creep in range)
+  for (const tw of state.towers) {
+    if (tw.c > 0) { tw.c -= 1; continue; }
+    const [tx, ty] = SLOTS[tw.s];
+    const [, range, dmg, cd] = KINDS[tw.k];
+    let best = -1, bestD = Infinity;
+    for (let j = 0; j < state.creeps.length; j++) {
+      const [cx, cy] = creepPos(state.creeps[j]);
+      const dd = dist(tx, ty, cx, cy);
+      if (dd <= range && dd < bestD) { bestD = dd; best = j; }
+    }
+    if (best >= 0) { state.creeps[best].h -= dmg; tw.c = cd; }
+  }
+
+  // 4. move creeps along the path; remove the dead (bounty) and leaks (a life)
+  const survivors: Creep[] = [];
+  for (const c of state.creeps) {
+    if (c.h <= 0) { state.gold += 5; continue; } // killed → bounty
+    c.t += CREEP_SPEED / segLen(c.w);
+    while (c.t >= 1 && c.w < PATH.length - 1) { c.t -= 1; c.w += 1; }
+    if (c.w >= PATH.length - 1 && c.t >= 1) { state.lives -= 1; continue; } // leaked the exit
+    survivors.push(c);
+  }
+  state.creeps = survivors;
+
+  // 5. wave / loss progression
+  if (state.spawnLeft === 0 && state.creeps.length === 0) {
+    if (state.wave < WAVES) beginWave(state, state.wave + 1);
+    else state.shell.over = true; // cleared all waves — the demo ends in a win, then resets
+  }
+  if (state.lives <= 0) state.shell.over = true; // loss → the shell rolls a new game
+}
+
+function segLen(w: number): number {
+  const a = PATH[w], b = PATH[Math.min(w + 1, PATH.length - 1)];
+  return Math.max(1e-3, Math.hypot(b[0] - a[0], b[1] - a[1]));
+}
+
+export default {
+  tick(state = freshState(), inputs, ctx) {
+    // datagram lane: teammate cursors (latest-wins). Only keep cursors for live seats.
+    for (const ev of inputs) {
+      if (ev.kind === "input") state.cursors[ev.from] = { x: ev.data.x, y: ev.data.y };
+    }
+
+    // ── the lifecycle shell drives the room ──
+    if (openRound(state.shell, inputs, ctx, SHELL_OPTS) === "start") startGame(state);
+    if (state.shell.phase === "playing") stepGame(state, inputs, ctx);
+    if (closeRound(state.shell, ctx, SHELL_OPTS) === "reset") clearGame(state);
+
+    // prune cursors for peers no longer seated (keeps state small + correct)
+    const live = new Set(state.shell.seats.map((s) => s.id).filter(Boolean));
+    for (const id in state.cursors) if (!live.has(id)) delete state.cursors[id];
+
+    return state;
+  },
+} satisfies Room<State, Cmd>;
+
+// Exposed for the derive/verify tooling (room.test.ts) — not part of the wire contract.
+export { PATH, SLOTS, KINDS, CAPS, WAVES, freshState, creepPos };

package/templates/tower-defense/skills/authoritative-tick.md

@@ -0,0 +1,96 @@
+# 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:
+
+```ts
+export default {
+  tick(state, inputs, ctx) { /* 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 — see `skills/waves-and-timing.md`).
+- 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**.
+- Optional `init()` runs once when the room is created and returns the starting state. This
+  template uses a default parameter instead (`tick(state = freshState(), …)`) — either works.
+  If neither seeds it, the first tick receives `state === undefined`.
+
+## Intent in, truth out
+
+Clients cannot write state. They call `send(...)` (see `skills/two-lanes.md`), which arrives in
+`tick` as an entry in the `inputs` batch. Your `tick` is the ONLY place truth is decided.
+
+The pattern to internalize — **validate intent, then commit**. From this template's `stepGame`,
+tower placement:
+
+```ts
+if (state.towers.some((t) => t.s === slot)) continue;  // reject: slot occupied
+if (state.gold < cost) continue;                        // reject: can't afford
+state.gold -= cost;                                     // commit: now it's truth
+state.towers.push({ s: slot, k: kind, c: 0 });
+```
+
+A malicious client can *ask* to place ten free towers; the server prices and validates every
+one. 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) — here, a cursor |
+| `"event"` | `from`, `data: unknown` | a peer's **reliable** event (ordered) — here, `ready`/`place` |
+
+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 template
+loops it twice: the shell reads join/leave/`ready`; `stepGame` reads `place`; the top of `tick`
+reads cursor `input`s. That's fine — iterate as many times as clarity wants.
+
+## 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 (`setTimeout`/`setInterval`), or any I/O.
+
+Why: the server must be able to replay ticks identically (crash recovery, verification). The
+`ctx` gives you 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()` for spawn jitter and `ctx.tick` for phase countdowns. If the
+doctor rejects a change, you reached for a forbidden API — find it and route through `ctx`.
+
+## 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 (like the placement checks
+above) 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` — including a determinism test that
+runs the same script twice and asserts identical output. That test is how you *prove* your
+change stayed deterministic, beyond the doctor's reload check.

package/templates/tower-defense/skills/demo-room-lifecycle.md

@@ -0,0 +1,145 @@
+# The demo-room lifecycle shell
+
+**This is the always-warm, tap-and-play room model — genre-agnostic.** It is the block
+between the `══ DEMO-ROOM LIFECYCLE SHELL ══` markers in `room.ts`. Copy that block
+verbatim into any genre template; wire your game to the three signals it emits. This
+document is its **normative spec**: the state, the transitions, and the invariants an
+extender must preserve.
+
+## The idea
+
+One constant, persistent room. No lobby, no matchmaking, no "create game" button. A player
+opens the page and is immediately *in* — they drop into a seat, ready up, and play. When a
+game ends, a new one starts on its own. The room is always warm because the Silt room runs
+whenever ≥1 peer is present and pauses when empty (BOUNDARIES §6).
+
+Three moves define it:
+
+- **Drop-in join** — claim an empty seat the instant you arrive.
+- **Take over an abandoned player, or start fresh** — if a teammate left mid-game, the next
+  arrival inherits their in-progress position; the game never pauses for a missing player.
+- **Ready-up → rolling rounds → play until you lose → a new game starts** — the loop runs
+  forever with no operator.
+
+## State
+
+The shell owns one namespaced key, `shell`, so your genre state stays cleanly separable:
+
+```ts
+type Phase = "gathering" | "playing" | "gameover";
+type Seat  = { id: string | null; ready: boolean; abandoned: boolean };
+type Shell = {
+  phase: Phase;
+  seats: Seat[];       // fixed length = opts.seats; index is the stable seat number
+  round: number;       // increments each time a game starts
+  phaseSince: number;  // ctx.tick when the current phase began — drives countdowns
+  over: boolean;       // YOUR GENRE sets this true to end a game (see "The over flag")
+};
+```
+
+A **seat** is a fixed slot at the table, addressed by index (`seats[0]`, `seats[1]`, …).
+`id` is the peer holding it, or `null` if empty. `abandoned` marks a seat whose peer left
+*mid-game*: the seat and its game data are kept so a newcomer can take it over.
+
+## Phases
+
+```
+   ┌─────────────────────────────────────────────────────────────┐
+   ▼                                                               │
+gathering ──(≥ minPlayers ready)──▶ playing ──(over)──▶ gameover ──┘
+                                                        (after gameoverTicks)
+```
+
+- **gathering** — seated players ready up. When `minPlayers` seats are occupied *and* ready,
+  a game starts.
+- **playing** — the genre runs. Rolling rounds/waves happen entirely inside your game code;
+  the shell does not know or care what a "round" is. It only waits for you to set `over`.
+- **gameover** — a brief hold (`gameoverTicks`) so players see the result, then the room
+  auto-resets to `gathering` and the loop repeats.
+
+## Seat assignment — the takeover rule
+
+On a `join`, the shell seats the peer by this priority (`seatFor` in the shell):
+
+1. **Reconnect** — if the peer already holds a seat (same `id`), resume it and clear
+   `abandoned`. (Silt's stable-id reconnect means a dropped player who returns keeps its
+   seat — see WIRE "Identity & reconnect".)
+2. **Empty seat** — claim the first `id === null` seat.
+3. **Takeover** — else adopt the first `abandoned` seat: set its `id` to the newcomer, clear
+   `abandoned`. The seat's genre data (towers, score, …) carries over untouched.
+4. **Spectator** — if every seat is held by a live player, the joiner gets no seat
+   (`seatFor` returns −1). A mid-game spectator waits; the next `gathering` frees seats and
+   they can ready up then.
+
+On a `leave`:
+
+- **During `playing`** → mark the seat `abandoned` (keep `id` and all game data). The game
+  continues; the seat is now takeover-eligible.
+- **During `gathering`/`gameover`** → free the seat entirely (`id: null`), because there is
+  no in-progress game to preserve.
+
+On reset (`gameover → gathering`), any still-`abandoned` seat is freed — its player is gone.
+
+## The three signals — how your genre wires in
+
+The shell exposes exactly two functions and one flag. Your `tick` composes them around your
+game step:
+
+```ts
+tick(state = freshState(), inputs, ctx) {
+  // (optional) datagram-lane intent you handle yourself, e.g. cursors
+
+  if (openRound(state.shell, inputs, ctx, SHELL_OPTS) === "start") startGame(state); // ① seed a fresh game
+  if (state.shell.phase === "playing") stepGame(state, inputs, ctx);                 // ② run your game; set shell.over on loss/win
+  if (closeRound(state.shell, ctx, SHELL_OPTS) === "reset") clearGame(state);        // ③ tear the game down
+
+  return state;
+}
+```
+
+- **`openRound(...) === "start"`** — fired on the single tick a game begins. Seed a fresh
+  game: reset resources, spawn the first wave, clear the board. Runs FIRST so membership and
+  the start transition are settled before your game steps.
+- **`shell.over`** — YOUR game sets this `true` when the game ends (you lost, you won, time
+  ran out — the shell doesn't judge). It is the ONLY bridge from genre → shell. `closeRound`
+  reads it.
+- **`closeRound(...) === "reset"`** — fired on the single tick a fresh `gathering` begins
+  (after the gameover hold). Clear your game state back to idle. Runs LAST.
+
+**Order is load-bearing:** `openRound` before your step (so a just-started game steps this
+same tick), `closeRound` after (so an `over` set during the step is seen this same tick).
+
+## `SHELL_OPTS`
+
+```ts
+const SHELL_OPTS = { seats: 2, minPlayers: 2, gameoverTicks: 180 };
+```
+
+- `seats` — table size (fixed). This template ships 2 (the smallest co-op).
+- `minPlayers` — ready seats required to start. Keep ≤ `seats`.
+- `gameoverTicks` — how long `gameover` holds before reset. 180 ticks = 3s at 60Hz.
+
+## Invariants an extender MUST preserve
+
+Break these and the room stops being a safe, always-warm demo:
+
+1. **`shell` is the only shell-owned state.** Keep it namespaced; don't scatter phase/seat
+   fields into your genre state.
+2. **Only the genre writes `shell.over`; only the shell writes `shell.phase`.** One flag in,
+   one machine out. Don't set `phase` from game code.
+3. **Seats are fixed-length and index-stable.** Never `push`/`splice` `seats`; mutate slots
+   in place. Clients and game data address players by seat index.
+4. **A mid-game leave abandons, never deletes.** Deleting a seat's data mid-game desyncs any
+   client rendering it and forfeits the takeover promise.
+5. **State stays under the datagram MTU (~1100B).** The shell is ~150B of that budget; the
+   rest is your genre's. See `state-budget.md`. Fixed seats + short keys keep it bounded.
+6. **`tick` stays deterministic.** No wall clock / `Math.random` / `fetch` inside the shell
+   or your step — use `ctx` (BOUNDARIES §5). `phaseSince` uses `ctx.tick`, never time.
+
+## Verifying the shell
+
+The shell is a pure function of `(state, inputs, ctx)`, so it is tested without a browser —
+see `room.test.ts`: scripted input sequences assert seat claim, takeover of an abandoned
+seat, reconnect-resume, the ready-up gate, `gathering → playing → gameover → gathering`, and
+a loss rolling into a fresh game. Run `bun test room.test.ts`. When you change the shell, the
+membership and phase-transition tests are your safety net — keep them green.

package/templates/tower-defense/skills/state-budget.md

@@ -0,0 +1,79 @@
+# The state budget — the ceiling that shapes everything
+
+Read this before adding anything to `State`. It is the one hard constraint that most shapes how
+you design a Silt game, and the reason tower defense — a genre that wants many entities on
+screen — is a good stress test of the substrate.
+
+## The ceiling
+
+The server broadcasts the **entire authoritative state** to every client **every tick** (60Hz),
+as a single WebTransport **datagram**. There is no diffing, no delta compression, no interest
+management — the whole `State`, serialized to JSON, every tick.
+
+A QUIC datagram gives you roughly **~1200 bytes of usable payload**. At ~40 bytes of JSON per
+small entity, that's a hard ceiling of about **28–30 small entities** in state before the
+datagram no longer fits. **A state that outgrows the datagram is silently undeliverable on that
+lane** — there is no automatic fallback. So the budget is not a soft guideline; exceed it and
+the game breaks quietly.
+
+(Full limits doc: the silt repo's `docs/BOUNDARIES.md` §1.)
+
+## The three disciplines
+
+**1. Store only what the server must own to decide truth.** Positions, health, ownership, whose
+turn — the minimum. Everything else is derived.
+
+**2. Derive rendering client-side — don't store it.** This is the biggest saver. This template
+never stores creep pixel positions. It stores a creep as `{ i, w, t, h }` — id, **waypoint
+index**, **progress along that segment** (0..1), and hp — and both server and client compute the
+actual position from the shared `PATH` via `creepPos()`. Animation, interpolation, particle
+effects, glow, health-bar layout — all live in `Game.tsx`, none in `State`. A creep costs ~4
+numbers on the wire instead of a fat object.
+
+**3. Short keys on the arrays that scale.** Object keys are literal bytes in the JSON, repeated
+per entity per tick. The types that appear in bounded-but-growing arrays use terse keys:
+
+```ts
+type Creep = { i: number; w: number; t: number; h: number }; // NOT {id,waypoint,progress,hp}
+type Tower = { s: number; k: number; c: number };            // slot, kind, cooldown
+```
+
+Meta fields that appear **once** (`gold`, `lives`, `wave`) stay readable — one occurrence, the
+bytes don't multiply. Only shorten what repeats.
+
+## Hard caps
+
+The template caps the arrays that could otherwise blow the budget:
+
+```ts
+const CAPS = { creeps: 14, towers: SLOTS.length /* 8 */ };
+```
+
+Spawns refuse to exceed `CAPS.creeps`; placement refuses past the fixed slots. With 2 seats + 8
+towers + 14 creeps + meta + 2 cursors, the **worst-case serialized state is ~931 bytes** —
+comfortably under the ~1100B budget. When you add fields or raise caps, you spend against that
+headroom.
+
+## The budget is a test, not a hope
+
+`room.test.ts` builds a **maxed** state (full seats, every slot towered, creep array saturated,
+cursors set) and asserts:
+
+```ts
+expect(Buffer.byteLength(JSON.stringify(s), "utf8")).toBeLessThan(1100);
+```
+
+**When you add anything to `State`, this test is your guardrail.** Add a field to `Creep`, raise
+`CAPS.creeps`, add a third seat — re-run `bun test room.test.ts` and watch the printed
+`worst-case state = NNNB`. If it approaches 1100, you must claw bytes back: shorten a key, drop a
+stored value you can derive, lower a cap. Don't ship a state you haven't measured at its worst.
+
+## If you genuinely need more than the budget allows
+
+- **Hidden information** (fog of war, secret hands) can't be solved by "just don't render it" —
+  every client receives the full state and can read the wire. Handle secrets client-side (e.g.
+  commit-reveal). See `docs/BOUNDARIES.md` §2.
+- **More entities than fit** — you're past what alpha Silt broadcasts. Options: reduce entity
+  count (the design move), or represent many things as a few (e.g. a wave as a count + a
+  spawn-schedule rather than N individual pre-spawned creeps). Per-tick diffs + keyframes are the
+  designed v1 path but are **not built** — don't design assuming them.