create-siltrun 0.1.0

package/templates/mass-grid/skills/compact-snapshots.md

@@ -0,0 +1,110 @@
+# Compact snapshots — the state IS the wire
+
+Read this before adding anything to `State`. It is the one hard constraint that most shapes how
+you design a mass-grid game, and the reason this genre — which wants a *crowd* on one board — is
+the sharp 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 roughly
+**~1200 bytes of usable payload**. **A state that outgrows the datagram is silently
+undeliverable on that lane.** There is no automatic fallback and no error — the datagram just
+doesn't arrive.
+
+So there is no separate "encoding" step you could add later. **The object `tick()` returns *is*
+the wire.** You engineer the *state* to be compact, or you don't fit.
+
+## The discipline: pack the state, unpack it in `tick`
+
+The move that makes this genre fit is the same one it uses for the grid, applied to everything
+that scales: **store a compact wire form in `State`; decode it to readable working structures at
+the top of `tick`; re-encode at the end.** `tick` reads like normal game code; the wire stays
+tight.
+
+```ts
+tick(state, inputs, ctx) {
+  const grid = decodeGrid(state.g, state.w, state.h); // RLE string  → Int16Array
+  const players = readPlayers(state);                 // flat arrays → readable objects
+  // …run the sim over `grid` and `players` as ordinary structures…
+  state.g = encodeGrid(grid);                          // pack back to the wire form
+  writePlayers(state, players);
+  return state;
+}
+```
+
+Three things ride compact:
+
+**1. The grid → a run-length string (`state.g`).** Territory is blobby by construction (claims
+are solid regions), so long runs of one owner compress to a few characters. A 20×20 board of
+mostly-solid regions is a few hundred bytes, not 400 cells.
+
+**2. Players → flat, slot-indexed arrays (`state.pf` + `state.pt`).** This is the single biggest
+lesson. The naive shape — `players: Record<peerId, {x,y,d,…}>` — is the trap: per-player object
+keys and peer-id strings are literal bytes repeated on the wire *every tick*, and they blow the
+datagram at ~8 players. Instead players ride as a flat scalar array (`pf` = `[alive,x,y,d,nd,rs]`
+per seat slot) plus trails (`pt`). No keys, no ids on the wire — the seat *index* is the
+identity. `readPlayers`/`writePlayers` convert to/from readable `Player` objects for the sim.
+
+**3. Trails → turn-point polylines (`pt`), and capped.** A trail is stored as its *corners*, not
+its cells — a long straight trail is one point pair, not twenty. And the number of corners is
+capped (`MAX_TRAIL_TURNS`): over-extend and you die. That cap is what makes the worst case
+*bounded* — without it, trails are unbounded and a few zig-zagging players alone blow the budget.
+
+## The measured budget — numbers, not hope
+
+These are **measured** (the budget test + the probes behind it), not guessed:
+
+| component | cost | note |
+|---|---|---|
+| lifecycle shell | ~55 B **per seat** | fixed — you can't shrink the copied block; fewer seats is the only lever |
+| grid RLE | ~hundreds of B, **data-dependent** | grows with cells AND fragmentation (jagged borders → more runs) |
+| players (flat) | ~30 B/player + trail | vs ~60 B/player as objects — the flat encoding roughly halves it |
+| per-peer input ack | **0 B here** | dropped because moves ride the reliable lane (see `skills/genre-lane-mapping.md`) |
+
+That is why this template ships **6 seats on a 20×20 grid with a 6-turn trail cap** — measured
+worst case ~**1099 B**, fitting the ~1200 B datagram with headroom. It is *not* an arbitrary
+choice:
+
+- **8 seats does not fit** once players trail (~1300–1400 B). The verbatim shell's per-seat tax
+  plus trails simply exceed a JSON datagram. Reaching 8+ concurrent needs a different wire (see
+  below), not a tuning tweak.
+- **28×28 did not fit** under realistic jagged play. 20×20 is where 6 seats became robust.
+
+**`SEATS × GRID × TRAIL-LENGTH` is a budget decision, not a taste one.** When you raise any of
+them, you spend against ~1200 B — re-run `bun test room.test.ts` and read the guard.
+
+## The honest ceiling — and why it degrades gracefully
+
+Row-major RLE has a worst case it **cannot** survive: **vertically-striped territory**, where
+every column boundary is a run on every row. There the grid alone can exceed a datagram, at *any*
+seat or grid size — the `room.test.ts` CHARACTERIZATION test pins this so nobody assumes JSON
+snapshots reach 100 players. **They do not.** This is the substrate's honest limit, not a bug in
+the template.
+
+It degrades **gracefully, not fatally**: the state datagram is *latest-wins and droppable*, so a
+transiently-oversized tick is simply dropped and the client recovers on the next in-budget tick —
+a brief stutter, not a freeze. Blobby play (what claiming actually produces) stays well inside
+budget; pathological striping is rare and self-heals as the board un-stripes.
+
+## If you genuinely need more than the budget allows
+
+- **Reaching a true crowd (50–100 players)** needs what alpha Silt does not yet do: **binary
+  and/or delta snapshots** (send only changed cells + periodic keyframes, in a packed binary
+  frame instead of JSON). That is the designed path to the genre's headline promise — but it is
+  **not built**. Don't design assuming it; design for the JSON-snapshot budget you have.
+- **More players on the current wire** — the levers are exactly the three in the table: fewer
+  seats, smaller grid, tighter trail cap. Spend them deliberately.
+- **Hidden information** (fog of war) can't be solved by "just don't render it" — every client
+  receives the full state and can read the wire. Handle secrets with a commit-reveal scheme, not
+  by omitting from render.
+
+## The budget is a test, not a hope
+
+`room.test.ts` builds the fattest state the config allows (full table, every seat trailing at
+the cap, over a jagged realistic board) and asserts it stays under the margin. **When you add
+anything to `State`, that guard is your guardrail.** Add a `Player` field, raise a cap, add a
+seat — re-run `bun test room.test.ts`. If it trips, claw bytes back before you ship: shorten the
+encoding, derive instead of store, or lower a cap. Never ship a state you haven't measured at its
+worst.

package/templates/mass-grid/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/mass-grid/skills/genre-lane-mapping.md

@@ -0,0 +1,88 @@
+# Genre → lane mapping — why moves ride the reliable lane
+
+Read this before sending anything from the client. Silt gives you **two lanes** over one
+connection, with opposite trade-offs. Most templates put continuous intent on the datagram
+lane. **This genre deliberately does the opposite for moves** — and understanding why is the
+lesson.
+
+## The client API
+
+`useRoom` gives you `send`:
+
+```ts
+const { state, send } = useRoom<State>(url, { id });
+
+send({ turn: 2 }, { reliable: true });   // RELIABLE lane — ordered, guaranteed, discrete
+send({ x, y });                          // DATAGRAM lane — droppable, latest-wins (NOT used here)
+```
+
+That `{ reliable: true }` flag is the whole choice. It changes which lane the data rides and how
+it arrives in `tick`.
+
+## The two lanes
+
+| | **Datagram** (default) | **Reliable** (`{ reliable: true }`) |
+|---|---|---|
+| Delivery | best-effort — **may be dropped** | guaranteed, in order |
+| Rate | high-frequency firehose (~20Hz+) | discrete, occasional |
+| Semantics | **latest-wins** — only the newest matters | every one matters, exactly once |
+| Arrives in `tick` as | `{ kind: "input", from, data }` — one latest per peer per tick | `{ kind: "event", from, data }` — each, in arrival order |
+
+## The genre → lane rule
+
+**The right lane is a property of the genre, not a default.**
+
+- **Fast-continuous games → datagram.** A cursor, a ship heading, an aim vector — values that
+  overwrite themselves many times a second. Dropping one costs nothing; the next arrives in
+  ~50ms. (The `minimal` / tower-defense templates use this lane for cursors.)
+- **Slow-discrete grid games → reliable.** In this genre a move is a *turn*: one discrete
+  decision every ~150ms that must not be dropped or reordered — **a lost turn is a death**
+  (you sail off a cliff or into a trap you meant to avoid). So turns ride the reliable lane,
+  where each one lands exactly once, in order.
+
+This template's `Game.tsx` sends every steering key as `send({ turn }, { reliable: true })`,
+and `ready`-up the same way. In `room.ts`, both arrive as `kind: "event"` — the shell reads
+`ready`, the genre reads `turn`.
+
+## The bonus: it keeps the datagram lean
+
+There's a second, quieter reason the reliable lane fits here. When a client sends intent on the
+**datagram** lane, the server attaches a small per-peer acknowledgement map (last-processed
+input, for client-side prediction/reconciliation) to **every** broadcast state datagram. A
+territory game does no client-side prediction — it just renders the authoritative grid — so that
+ack map would be pure dead weight on a datagram budget this genre already pushes hard (see
+`skills/compact-snapshots.md`). Because moves ride the *reliable* lane instead, that map stays
+empty and is dropped from the wire entirely. The lane choice that is *correct for the genre* is
+also the one that *reclaims budget*. That is not a coincidence you should fight.
+
+## The prediction amendment (DIG-763, ratified 2026-07-21)
+
+The rule above has one ratified exception: **a room that opts into client-side prediction
+puts its steering on the INPUT (datagram) lane — even discrete steering.** Prediction's
+reconciliation ack (`appliedSeq`) acks *only* input-envelope seqs; reliable events carry no
+seq and can never reconcile. So the doctrine is:
+
+> **Predicted intent rides the input lane as HELD intent; the event lane is for discrete,
+> non-predicted acts** (fire, ready-up, callsign — things that must apply exactly once and
+> must NOT be optimistically replayed).
+
+"A lost turn is a death" was the pre-prediction rationale — under prediction the held intent
+(`{ d }`, the desired direction) is re-sent every pump tick (~60Hz), so a dropped datagram is
+a non-event: the next pump re-carries it, latest-wins recovers, and your own head already
+turned locally the frame you pressed. The buffered-`nd` semantics are unchanged — latest-wins
+held direction is exactly what the `nd` buffer already reduces turns to.
+
+A room that does NOT predict keeps the original rule (and the lean-datagram bonus below).
+See `packages/PREDICT.md` for the full opt-in.
+
+## Gotchas
+
+- **Reliable events are unbounded arbitrary data** (`data: unknown`) — you type/validate them
+  yourself in `tick`. This template guards with a `type` discriminator for `ready` and a range
+  check for `turn` before acting. Always validate — it's untyped intent from a client.
+- **`status`** from `useRoom` is `"connecting" | "connected" | "reconnecting" | "failed" |
+  "closed"`. Render an explicit failed/joining state (this template does) instead of an eternal
+  spinner.
+- **Adding a fast-continuous signal later?** (say, an aim reticle for a power-up) — *that* one
+  belongs on the datagram lane. The rule is per-signal: discrete-and-must-land → reliable;
+  continuous-and-self-correcting → datagram. Don't put everything on one lane by habit.

package/templates/mass-grid/skills/territory-capture.md

@@ -0,0 +1,115 @@
+# Territory capture — the genre mechanics
+
+Read this before changing the game itself: trails, claiming, collisions, respawn, and the round
+timer. This is the code *below* the shell in `room.ts` — the part you replace to build a
+different game. Everything here assumes `skills/authoritative-tick.md` (the tick model) and
+`skills/compact-snapshots.md` (why state is stored the way it is).
+
+## The loop, in one paragraph
+
+Each player owns a solid patch of the grid (their **territory**). While your head sits on your
+own territory you're safe. Leave it and you draw a **trail** across neutral/enemy ground; loop
+back to touch your own territory again and everything your trail enclosed is **claimed**
+(flood-fill). While your trail is out, it's exposed: if any head — yours or a rival's — steps on
+it, the trail's owner is **cut** (dies, releases their land, respawns). When the round timer
+sounds, most territory wins and a fresh round rolls. That's the whole genre.
+
+## The sim step (`simStep`)
+
+The sim advances one grid-step every `STEP_TICKS` ticks (see `authoritative-tick.md` → *slow sim
+inside a fast clock*). One step is four ordered phases — **order matters**:
+
+1. **Move.** Apply each alive player's buffered turn (`nd`), reject 180° reversals, advance the
+   head one cell. Running off the board edge is death. Leaving your own territory starts/extends
+   a trail; a **turn-point is recorded only when the heading changed this tick**, so the stored
+   polyline's segments are always axis-aligned (a straight run is one segment). Overrunning the
+   trail-turn cap is over-extension death.
+2. **Collisions.** Build the set of occupied trail cells (each trailing player's trail, excluding
+   its own live head). Any head sitting on a trail cell → that **trail's owner** is cut. Two
+   heads on one cell → both die (head-on).
+3. **Claims.** An alive player whose head re-entered its **own** territory with a live trail
+   closes the loop → `claim` fills everything enclosed, and the trail clears.
+4. **Respawns.** A dead player whose respawn tick has arrived (and whose seat is still occupied)
+   gets a fresh 3×3 blob at an empty spot.
+
+## Claiming — the flood-fill (`claim`)
+
+Closing a loop calls `claim(grid, w, h, owner, trailCells)`:
+
+1. The trail cells become owned.
+2. Flood-fill from the grid **border** through every non-owned cell.
+3. Any cell the border flood **couldn't reach** is enclosed → claimed (this captures both empty
+   pockets and enemy cells the loop wrapped around).
+
+It's `O(cells)`, but only runs on the rare tick a loop actually closes, so it's cheap. The
+`room.test.ts` claim tests pin both the capture (a fully-enclosed pocket, including an enemy
+cell) and the no-over-claim case (a loop with a gap to the outside claims nothing new).
+
+## Trails are turn-points, and capped
+
+A trail is stored as its **corners** (`Player.t = [x0,y0,x1,y1,…]`), not its cells — see
+`compact-snapshots.md` for why (wire budget). `trailCells()` expands corners + the live head
+back into cell indices when the sim needs them (collision, claim). **Invariant: consecutive
+points must be axis-aligned** — the move phase guarantees this by only recording a corner when
+the heading changed. (If you ever change trail recording and break that invariant, `trailCells`
+would loop forever; there's a defensive cap that throws instead. Keep the invariant.)
+
+`MAX_TRAIL_TURNS` caps the corners: over-extend and you die. This is both a genre mechanic
+(don't stay exposed too long) and the thing that bounds the trail's wire cost. Don't remove the
+cap without re-reading `compact-snapshots.md` — uncapped trails can blow the datagram.
+
+## Death, release, respawn
+
+Any death (wall, cut, head-on, over-extension) does the same three things: mark the player dead
+(`a = 0`), **release** its territory (its grid cells → 0), clear its trail, and set a respawn
+tick (`ctx.tick + RESPAWN_TICKS`). No elimination — respawn keeps agency alive at scale, which is
+why territory-capture (not instant-death light-cycles) is the genre that stays fun with a crowd.
+
+## How the genre wires to the shell
+
+The shell owns the room lifecycle; the genre plugs into its three signals (full spec:
+`skills/demo-room-lifecycle.md`):
+
+```ts
+if (openRound(...) === "start") startGame(state, players, grid, ctx.random); // seed fresh board + spawns
+if (state.shell.phase === "playing") { /* absorb turns, simStep on step ticks, run round timer */ }
+if (closeRound(...) === "reset") clearGame(state, players, grid);            // wipe the board
+```
+
+The **round timer** is this genre's win condition. When `ctx.tick - shell.phaseSince >=
+ROUND_TICKS`, the genre picks the most-territory slot (the `mostTerritory` helper) into
+`state.win` and sets `shell.over = true` — the shell then shows the winner (`gameover`) and rolls
+a fresh round. `shell.over` is the only bridge from genre to shell; the genre never touches
+`shell.phase` directly.
+
+### Adding another win condition (e.g. a capture threshold)
+
+If you add a second way to end the round — say "first to 40% of the board wins" — three things
+are easy to get subtly wrong:
+
+- **Define your denominator.** "The board" is **`state.w * state.h`** total cells (400 on the
+  default 20×20), not "claimed cells" — neutral ground counts. `countCells(grid, slot + 1)` is a
+  slot's cell count; compare it against `w * h * fraction`.
+- **Read territory AFTER `simStep`, and know a dying player's land is already gone.** The
+  win-check runs on the post-step grid, and `simStep`'s death path calls `release()` (zeroes the
+  dead player's cells) *within* the same step. So a player who dominates *and* dies in one step
+  has no territory left to win with by the time you check — which is correct, but surprising.
+- **Win-checks run every tick, not only on step boundaries.** Note the round-timer check sits
+  *outside* the `if (ctx.tick % STEP_TICKS === 0)` gate — it's evaluated every 60Hz tick so the
+  round can end the instant the condition is met. Put your new check alongside it, same cadence.
+
+Mid-game seating is reconciled by `syncPlayers`: a fresh arrival / a takeover of an emptied slot
+gets a new player; a seat that emptied loses its player and land. An **abandoned** seat (its peer
+left mid-game) keeps its player, frozen, so a newcomer can take over the territory — the shell's
+takeover promise, made concrete.
+
+## Ideas for extending (each is a small, contained change)
+
+- **Kill feed / claim announcements** — `ctx.emit({ type: "cut", by, victim })` on a kill; the
+  client shows a toast. Reliable, off the broadcast state (doesn't cost budget).
+- **Power-ups** — a cell that grants a temporary effect. Store the pickup cells compactly; if you
+  add a continuous aim signal, that one goes on the *datagram* lane (`genre-lane-mapping.md`).
+- **Bots** — spawn seats controlled by server-side logic in `tick` (deterministic via `ctx`),
+  so the room is lively before humans arrive.
+- **Bigger boards / more players** — this is a *budget* change, not a free one. Read
+  `compact-snapshots.md` first and watch the guard test.

package/templates/mass-grid/src/Game.tsx

@@ -0,0 +1,174 @@
+import { useEffect, useRef } from "react";
+import { useRoom } from "@siltrun/react";
+import { createStage, createCamera, type StageHandle } from "@siltrun/stage";
+import { dpad } from "@siltrun/stage/input";
+import { Graphics } from "pixi.js";
+// Type-only import of the room's State (erased at build), PLUS the actual wire codec and
+// board constants — the client decodes the SAME compact grid/player forms the server
+// encoded, and frames the SAME board size. One codec, one source of truth.
+import { decodeGrid, readPlayers, trailCells, W, H, type State } from "../room.ts";
+
+// A stable, SHORT player id for this browser tab. Short ids keep the shell's seat map
+// (which rides the state datagram) lean — see the budget note in room.ts.
+const PLAYER_ID =
+  sessionStorage.getItem("mg-id") ??
+  (() => {
+    const id = Math.random().toString(36).slice(2, 5); // 3 chars
+    sessionStorage.setItem("mg-id", id);
+    return id;
+  })();
+
+// Player colours — the Silt register's warm family (ink ground, hue-restrained), NOT a
+// neon-gamer rainbow. silt · amber · copper · rust · sand · bone.
+const COLORS = [0x7e837a, 0xc98a3d, 0xb07050, 0xa65a2e, 0xcfc9bc, 0xeae7de];
+const COLORS_CSS = ["#7e837a", "#c98a3d", "#b07050", "#a65a2e", "#cfc9bc", "#eae7de"];
+const INK = 0x0b0b0d, BONE = 0xeae7de, HAIR = 0x26262a;
+const CELL = 20; // world units per grid cell (arbitrary — the camera fits the board)
+
+// The dev loop serves room-info on :4000 by default; override for a custom --info-port or a
+// deployed room (VITE_ROOM_URL).
+const ROOM_URL = (import.meta as { env?: Record<string, string> }).env?.VITE_ROOM_URL ?? "http://localhost:4000";
+
+export function Game() {
+  const { state, send, status, error } = useRoom<State>(ROOM_URL, { id: PLAYER_ID });
+
+  // React owns the DOM HUD below; the stage redraws the board each frame from this ref.
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const hostRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    let stage: StageHandle | undefined;
+    let pad: { dispose(): void } | undefined;
+    let cancelled = false;
+    // createStage is awaited INSIDE the effect — never top-level (see @siltrun/stage README).
+    createStage(hostRef.current!, { background: INK }).then((s) => {
+      if (cancelled) return s.dispose();
+      stage = s;
+
+      // God view: fit the whole board on any screen, refit on rotate/resize.
+      const cam = createCamera(s);
+      const fit = () => cam.fitRect({ x: 0, y: 0, w: W * CELL, h: H * CELL }, { pad: 16 });
+      fit();
+      s.onResize(fit);
+
+      // Steer on the RELIABLE lane — a slow grid game wants ordered, no-drop turns.
+      // dpad = arrows/WASD AND swipe, from birth; its dir indices (0=up 1=right 2=down
+      // 3=left) are the same convention the sim uses, so intent passes straight through.
+      pad = dpad(s.app.canvas, {
+        mode: "turn",
+        onDir: (dir) => send({ turn: dir }, { reliable: true }),
+      });
+
+      // Redraw everything from authoritative state, every frame (the Silt idiom).
+      const gfx = s.world.addChild(new Graphics());
+      s.app.ticker.add((tk) => {
+        cam.update(tk.deltaMS / 1000);
+        gfx.clear();
+        const st = stateRef.current;
+        if (!st) return;
+
+        // 1. claimed territory — the RLE grid, decoded
+        const grid = decodeGrid(st.g, st.w, st.h);
+        for (let i = 0; i < grid.length; i++) {
+          const owner = grid[i]!;
+          if (owner === 0) continue;
+          gfx.rect((i % st.w) * CELL, ((i / st.w) | 0) * CELL, CELL, CELL)
+            .fill({ color: COLORS[(owner - 1) % COLORS.length]!, alpha: 0.32 });
+        }
+
+        // 2. live trails + heads
+        const players = readPlayers(st);
+        const mySlot = st.shell.seats.findIndex((seat) => seat.id === PLAYER_ID);
+        players.forEach((pl, slot) => {
+          if (!pl || !pl.a) return;
+          const color = COLORS[slot % COLORS.length]!;
+          for (const c of trailCells(pl.t, pl.x, pl.y, st.w)) {
+            gfx.rect((c % st.w) * CELL, ((c / st.w) | 0) * CELL, CELL, CELL)
+              .fill({ color, alpha: 0.7 });
+          }
+          gfx.rect(pl.x * CELL, pl.y * CELL, CELL, CELL).fill(color); // head
+          if (slot === mySlot) {
+            gfx.rect(pl.x * CELL + 1, pl.y * CELL + 1, CELL - 2, CELL - 2)
+              .stroke({ color: BONE, width: 2 });
+          }
+        });
+
+        // 3. faint grid lines + board frame
+        for (let x = 0; x <= st.w; x++) gfx.moveTo(x * CELL, 0).lineTo(x * CELL, st.h * CELL);
+        for (let y = 0; y <= st.h; y++) gfx.moveTo(0, y * CELL).lineTo(st.w * CELL, y * CELL);
+        gfx.stroke({ color: BONE, width: 1, alpha: 0.06 });
+        gfx.rect(0, 0, st.w * CELL, st.h * CELL).stroke({ color: HAIR, width: 1 });
+      });
+    });
+    return () => {
+      cancelled = true;
+      pad?.dispose(); // dpad holds window key listeners — the stage can't remove those
+      stage?.dispose();
+    };
+  }, [send]);
+
+  // ── DOM HUD (the convention: chrome in DOM, world on the stage) ──
+  const mySlot = state?.shell.seats.findIndex((s) => s.id === PLAYER_ID) ?? -1;
+  const hud = (() => {
+    if (status === "failed") return <span style={{ color: "#a65a2e" }}>connection failed: {String(error)} — is the dev loop running?</span>;
+    if (!state) return <span>{status === "reconnecting" ? "reconnecting…" : "joining…"}</span>;
+    const { phase, seats } = state.shell;
+    const win = state.win; // NOTE: win rides top-level State, not the shell
+    const seated = mySlot >= 0;
+    const iAmReady = seated && seats[mySlot]!.ready;
+    if (phase === "gathering") {
+      const readyCount = seats.filter((s) => s.id && s.ready).length;
+      const playerCount = seats.filter((s) => s.id).length;
+      return (
+        <>
+          <span>{seated ? `${readyCount}/${playerCount} ready` : "room full — spectating"}</span>
+          {seated && (
+            <button onClick={() => send({ type: "ready" }, { reliable: true })} disabled={iAmReady}
+              style={{
+                fontFamily: "inherit", fontSize: 12, padding: "5px 14px", cursor: iAmReady ? "default" : "pointer",
+                background: iAmReady ? "#1c1c1f" : "#eae7de", color: iAmReady ? "#7e837a" : "#0b0b0d",
+                border: "1px solid #3a3a3d", borderRadius: 0, letterSpacing: "0.06em", textTransform: "uppercase",
+              }}>
+              {iAmReady ? "ready ✓" : "ready up"}
+            </button>
+          )}
+        </>
+      );
+    }
+    if (phase === "playing") {
+      const grid = decodeGrid(state.g, state.w, state.h);
+      const total = state.w * state.h;
+      return seats
+        .map((s, slot) => ({ slot, id: s.id, cells: countOwner(grid, slot + 1) }))
+        .filter((s) => s.id)
+        .sort((a, b) => b.cells - a.cells)
+        .map((s) => (
+          <span key={s.slot} style={{ color: COLORS_CSS[s.slot % COLORS_CSS.length], fontWeight: s.slot === mySlot ? 700 : 400, fontVariantNumeric: "tabular-nums" }}>
+            {Math.round((s.cells / total) * 100)}%
+          </span>
+        ));
+    }
+    return (
+      <span style={{ color: win >= 0 ? COLORS_CSS[win % COLORS_CSS.length] : "#7e837a", letterSpacing: "0.06em" }}>
+        {win === mySlot ? "you win the round" : win >= 0 ? `player ${win + 1} wins the round` : "round over"} — next game starting…
+      </span>
+    );
+  })();
+
+  // Static chrome (title, steering hint) lives in index.html; only the DYNAMIC strip is React's.
+  return (
+    <main style={{ position: "fixed", inset: 0, fontFamily: "ui-sans-serif, system-ui, sans-serif" }}>
+      <div ref={hostRef} style={{ position: "absolute", inset: 0 }} />
+      <div style={{ position: "absolute", left: 0, right: 0, bottom: "calc(30px + env(safe-area-inset-bottom, 0px))", display: "flex", justifyContent: "center", alignItems: "center", gap: 12, fontSize: 12, minHeight: 30, color: "#7e837a" }}>
+        {hud}
+      </div>
+    </main>
+  );
+}
+
+function countOwner(grid: Int16Array, owner: number): number {
+  let n = 0;
+  for (let i = 0; i < grid.length; i++) if (grid[i] === owner) n++;
+  return n;
+}

package/templates/mass-grid/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { Game } from "./Game.tsx";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <Game />
+  </StrictMode>,
+);

package/templates/mass-grid/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "room.ts", "room.test.ts", "vite.config.ts"]
+}