create-siltrun 0.1.0

package/index.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// create-siltrun — `npm create siltrun <dir>` scaffolds a runnable, editable Silt project:
+// an authoritative room contract (room.ts) + a React client (vite), wired together
+// by the siltrun CLI. Plain Node, zero dependencies — npm initializers run under Node.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function usage(exit = 1) {
+  console.log(`create-siltrun — scaffold a Silt multiplayer project
+
+Usage
+  npm create siltrun <project-dir> [-- --template <name>]
+  npx create-siltrun <project-dir> [--template <name>]
+
+Options
+  --template <name>   project template (default: minimal)
+
+Then
+  cd <project-dir> && npm install && npm run dev`);
+  process.exit(exit);
+}
+
+// ---- args ----
+const argv = process.argv.slice(2);
+let targetArg = null;
+let template = "minimal";
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--help" || a === "-h") usage(0);
+  else if (a === "--template") {
+    template = argv[++i];
+    if (!template) usage();
+  } else if (a.startsWith("--template=")) template = a.slice("--template=".length);
+  else if (!a.startsWith("-") && targetArg === null) targetArg = a;
+  else usage();
+}
+if (!targetArg) usage();
+
+const templateDir = join(here, "templates", template);
+if (!existsSync(templateDir)) {
+  const available = readdirSync(join(here, "templates")).join(", ");
+  console.error(`create-siltrun: unknown template "${template}" (available: ${available})`);
+  process.exit(1);
+}
+
+const target = resolve(process.cwd(), targetArg);
+if (existsSync(target)) {
+  // If the target is a FILE (or anything non-directory), readdirSync would throw
+  // a raw ENOTDIR stack (`npx create-siltrun notes.txt`). Stat first and give the
+  // same friendly "already exists" class of error instead.
+  if (!statSync(target).isDirectory()) {
+    console.error(`create-siltrun: ${target} already exists (it's a file, not a directory)`);
+    process.exit(1);
+  }
+  if (readdirSync(target).length > 0) {
+    console.error(`create-siltrun: ${target} already exists and is not empty`);
+    process.exit(1);
+  }
+}
+
+// Package names must be npm-safe; derive from the directory basename.
+const rawName = basename(target);
+const pkgName = rawName
+  .toLowerCase()
+  .replace(/[^a-z0-9._-]+/g, "-")
+  .replace(/^[-._]+|[-._]+$/g, "") || "my-silt-game";
+
+// ---- scaffold ----
+mkdirSync(target, { recursive: true });
+cpSync(templateDir, target, { recursive: true });
+
+// npm strips .gitignore from published tarballs — templates ship it as _gitignore.
+const gi = join(target, "_gitignore");
+if (existsSync(gi)) renameSync(gi, join(target, ".gitignore"));
+
+// Stamp the project name.
+const pkgPath = join(target, "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+pkg.name = pkgName;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+
+const rel = targetArg;
+console.log(`
+Scaffolded ${pkgName} (template: ${template})
+
+  cd ${rel}
+  npm install
+  npm run dev
+
+npm run dev boots both halves: your authoritative room (siltrun dev room.ts,
+room-info on http://localhost:4000) and the vite client (http://localhost:5173).
+Open http://localhost:5173 in two windows — that's your multiplayer room.
+Edit room.ts and watch both reload.
+`);

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "create-siltrun",
+  "version": "0.1.0",
+  "description": "Scaffold a Silt multiplayer project — `npm create siltrun my-game`.",
+  "type": "module",
+  "bin": {
+    "create-siltrun": "index.mjs"
+  },
+  "files": ["index.mjs", "templates"],
+  "repository": "https://github.com/digitalpine/silt",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "true"
+  }
+}

package/templates/mass-grid/AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md — mass-grid territory capture on Silt
+
+You (a coding agent) are working in a **Silt** project: an authoritative multiplayer room.
+This file orients you so you can extend the game immediately. Read it fully once, then read
+the one skill in `skills/` that matches what you're about to change. The skills are the deep
+knowledge; this file is the map.
+
+## What this project is
+
+A **mass-grid territory-capture** starter — the Paper.io / Splix.io genre. Players share one
+always-warm room: they drop in, ready up, and race to paint the grid. You leave your territory
+to draw a **trail**, loop back to your own land to **claim** everything you enclosed, and you
+**cut** a rival by crossing their exposed trail. Most territory when the round timer sounds
+wins; a new round rolls immediately. It is a **teaching template**, not a finished game:
+minimal genre mechanics chosen so each one demonstrates a Silt concept. Build your real game by
+extending it.
+
+Two parts, deliberately separated in `room.ts`:
+
+1. **The demo-room lifecycle shell** — the `══ DEMO-ROOM LIFECYCLE SHELL ══` block. Genre-
+   agnostic: the always-warm, tap-and-play room model (drop-in join, take over an abandoned
+   player, ready-up → rolling rounds → auto-restart, no lobby). You usually **don't edit this**
+   — you wire your game to its three signals. Spec: `skills/demo-room-lifecycle.md`.
+2. **The territory-capture genre** — everything below the shell. This is what you replace or
+   extend to change the game.
+
+## The one mental model that matters
+
+**The server owns truth. Clients submit intent. The room decides.**
+
+```
+browser ──send(intent)──▶  Go relay ──inputs──▶  room.ts tick()  ──full state──▶ every browser
+                           (WebTransport)        (Bun, 60Hz, deterministic)
+```
+
+`room.ts` default-exports `{ init, tick }`. It runs **server-side at 60Hz** inside a
+deterministic realm. Each tick it receives the canonical state + a batch of inputs (joins,
+leaves, and peers' intent), mutates state, and returns it. The server broadcasts the **entire**
+returned state to every client every tick. Clients never own state — they render what the
+server sends and send intent back. This is why cheating is hard: a client asking to turn is
+*intent*; `tick` decides truth. Full model → `skills/authoritative-tick.md`.
+
+## The two ideas this genre is built to teach
+
+- **The state IS the wire — so engineer it compact.** The whole `State` is JSON-marshaled into
+  ONE ~1200-byte datagram every tick. This genre wants a *crowd* on one board, so it packs
+  hard: the grid rides as a run-length string, players ride as a flat slot-indexed array, trails
+  ride as turn-point polylines. `tick()` unpacks these into readable objects, mutates, and
+  re-packs — exactly the way it treats the grid. **This is the single most important thing to
+  understand before you touch `State`.** → `skills/compact-snapshots.md`.
+- **The genre picks the lane.** Moves ride the *reliable* lane, not the presence datagram lane,
+  because a slow discrete grid game wants ordered, no-drop turns (a dropped turn is a death).
+  **Ratified amendment (DIG-763): a room that opts into client-side prediction moves its
+  steering to the INPUT lane as held intent** — only input-envelope seqs are acked, so only
+  they can reconcile. → `skills/genre-lane-mapping.md` (incl. the prediction amendment).
+
+## Code map
+
+| File | What it is |
+|---|---|
+| `room.ts` | The authoritative contract. Shell block (copy-verbatim) + territory-capture genre. **The game lives here.** |
+| `room.test.ts` | Deterministic contract tests — `tick` is a pure function, so you test it with no browser. Your safety net, including the datagram-budget guard. |
+| `src/Game.tsx` | The React client. `useRoom(url, { id })` → `{ state, send }`. Renders on `@siltrun/stage`: `createStage` + `cam.fitRect(board)` + `dpad` (keys AND swipe — phone-steerable by default). Decodes the compact state with the SAME codec the server uses (imported from `room.ts`) and redraws it each frame; sends turns on the reliable lane. |
+| `src/main.tsx`, `index.html` | Standard vite entry. |
+| `skills/` | The deep concept docs. Read the one for your change. |
+
+## Run it + verify your change
+
+```bash
+npm install
+npm run dev          # boots BOTH halves: `siltrun dev room.ts` (room-info :4000) + vite (:5173)
+```
+
+Open `http://localhost:5173` in **two windows** — that's your two-player room. Ready up in both
+to start. Leave your patch of colour, loop back, and watch the enclosed area fill.
+
+**Verify by observation, not by reading your own diff:**
+- `bun test room.test.ts` — the fast loop and your **primary** verification. The contract is a
+  pure function; scripted inputs assert truth (membership, phase transitions, claim/collision/
+  respawn, and the datagram-size budget). It runs with **no install** because the `@siltrun/*`
+  imports are type-only and erased at runtime. When you change mechanics, add/adjust a test and
+  keep it green — especially the budget guard if you touch `State`.
+  - Note: `npm run typecheck` (`tsc`) will NOT resolve `@siltrun/*` until they're published (see
+    the alpha limitation) — it errors on unresolved modules, not your code. `bun test` is the
+    real check in the shipped state.
+- Two windows for the live feel. `room.ts` hot-reloads on save (a determinism doctor re-checks
+  each reload) — if it rejects your change as non-deterministic, read `skills/authoritative-tick.md`.
+
+## The skills — read the one for your change
+
+| Skill | Read it before you… |
+|---|---|
+| `skills/authoritative-tick.md` | change any server logic in `room.ts` (the core model + the determinism rule) |
+| `skills/compact-snapshots.md` | add anything to `State` (the datagram budget + the pack/unpack discipline) — **the load-bearing one for this genre** |
+| `skills/genre-lane-mapping.md` | send anything from the client (which lane, and why this genre chose reliable) |
+| `skills/territory-capture.md` | change the game itself — trails, claiming, collisions, respawn, the round timer |
+| `skills/demo-room-lifecycle.md` | touch seating, phases, or rounds (the shared shell spec + its invariants) |
+
+## ⚠️ Alpha limitation — installing `@siltrun/*`
+
+At the time this template ships, the `@siltrun/*` packages are **not yet published to npm**, so
+`npm install` here will fail to resolve them. Until the publish lands, consume Silt from a local
+checkout using the workspace path documented in the silt repo's `docs/QUICKSTART.md` (clone
+silt, point your project's `package.json` deps at the local `packages/*`, `bun install`,
+`bun run dev`). The game code in this template is identical either way — only the dependency
+wiring differs. `bun test room.test.ts` works regardless (type-only imports).

package/templates/mass-grid/README.md

@@ -0,0 +1,59 @@
+# silt · mass-grid territory capture
+
+A Paper.io / Splix.io-style **territory-capture** game on [Silt](https://silt.run) — an
+authoritative server contract (`room.ts`) plus a React client (`src/`), one project, one
+language. Players share one always-warm room: drop in, ready up, paint the grid. Leave your
+land to draw a trail, loop back to claim what you enclosed, cut a rival by crossing their trail.
+Most territory when the timer sounds wins; a new round rolls immediately.
+
+**Building on this with a coding agent? Point it at [`AGENTS.md`](./AGENTS.md) first** — it's
+the orientation map, and `skills/` holds the deep concept docs.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Boots both halves:
+- **room** — `siltrun dev room.ts`: your contract running authoritatively at 60Hz (room-info on
+  `http://localhost:4000`, WebTransport on `:4433`). Hot-reloads on save.
+- **web** — vite dev server on [http://localhost:5173](http://localhost:5173).
+
+Open `http://localhost:5173` in **two windows** and ready up in both — that's your game. Arrows
+or WASD to steer.
+
+> **Alpha note:** the `@siltrun/*` packages aren't published to npm yet, so `npm install` won't
+> resolve them until the publish lands. Until then, consume Silt from a local checkout per the
+> silt repo's `docs/QUICKSTART.md` (the game code is identical; only dependency wiring differs).
+> See [`AGENTS.md`](./AGENTS.md) → *Alpha limitation*.
+
+## Test
+
+```bash
+bun test room.test.ts
+```
+
+`room.ts` is a deterministic pure function, so the whole game is testable with no browser:
+membership, phase transitions, claiming, collisions, respawn, and the **datagram-size budget**
+are all asserted by scripted ticks. This is your fast feedback loop — keep it green as you build,
+especially the budget guard if you touch `State`.
+
+## What's here
+
+- `room.ts` — the authoritative contract: a genre-agnostic **demo-room lifecycle shell** (drop-in
+  join, take over an abandoned player, ready-up → rolling rounds → auto-restart) plus the
+  **territory-capture genre** below it. Replace the genre to build a different game on the same
+  shell.
+- `src/Game.tsx` — the React client, rendered on `@siltrun/stage` (PixiJS): `createStage` +
+  `cam.fitRect(board)` + `dpad` is the whole ceremony, so the board fits any screen and is
+  steerable by swipe AND keys from birth. Decodes the compact state with the same codec the
+  server uses and redraws it each frame; sends turns on the reliable lane.
+- `AGENTS.md` + `skills/` — the teaching layer. Read these to extend the game. The load-bearing
+  one for this genre is `skills/compact-snapshots.md` — the state is the wire, so you engineer it
+  compact.
+
+## Learn more
+
+- Quickstart, the two lanes, the determinism realm, and the honest limits: https://silt.run/docs

package/templates/mass-grid/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

package/templates/mass-grid/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="mobile-web-app-capable" content="yes" />
+    <style>html, body { overscroll-behavior: none; }</style>
+    <title>Silt — mass-grid (territory capture)</title>
+  </head>
+  <body style="margin: 0; background: #0b0b0d; color: #eae7de; font-family: ui-sans-serif, system-ui, sans-serif;">
+    <div id="root"></div>
+    <!-- static chrome overlays the stage; the dynamic HUD strip is rendered by src/Game.tsx -->
+    <h1 style="position: fixed; top: calc(10px + env(safe-area-inset-top, 0px)); left: 0; right: 0; margin: 0; text-align: center; pointer-events: none; font-size: 13px; font-weight: 600; letter-spacing: 0.14em; text-transform: uppercase; color: #7e837a;">
+      Silt · mass-grid
+    </h1>
+    <p style="position: fixed; bottom: calc(6px + env(safe-area-inset-bottom, 0px)); left: 0; right: 0; margin: 0; text-align: center; pointer-events: none; font-size: 10px; letter-spacing: 0.1em; text-transform: uppercase; color: #7e837a;">
+      swipe / arrows to steer · loop home to claim · cut trails to take out
+    </p>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/mass-grid/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "my-silt-game",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently -k -n room,web -c yellow,cyan \"siltrun dev room.ts\" \"vite\"",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "bun test room.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@siltrun/stage": "^0.1.0",
+    "pixi.js": "^8.19.0",
+    "@siltrun/client": "^0.3.0",
+    "@siltrun/react": "^0.1.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@siltrun/room": "^0.1.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "concurrently": "^9.0.0",
+    "siltrun": "^0.1.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0"
+  }
+}

package/templates/mass-grid/room.test.ts

@@ -0,0 +1,214 @@
+// room.test.ts — the contract is a deterministic pure function, so we verify it by driving
+// tick() with scripted inputs and asserting truth. No browser, no network, no install
+// (the @siltrun/room import is type-only and erased).
+//   bun test room.test.ts
+import { test, expect } from "bun:test";
+import contract, {
+  encodeGrid, decodeGrid, trailCells, claim, countCells, readPlayers, writePlayers,
+  W, H, STEP_TICKS, ROUND_TICKS, MAX_TRAIL_TURNS,
+  type State, type Player, type Seat, type Cmd,
+} from "./room.ts";
+import type { Ctx, Input } from "@siltrun/room";
+
+const MTU_BUDGET = 1150; // design target: worst-case state < this, headroom to the ~1200B datagram
+
+// A deterministic Ctx. `random` is seeded + reproducible so spawn placement is testable.
+function makeCtx(tick: number, seed = 1): Ctx {
+  let s = seed >>> 0;
+  return { tick, dt: 1 / 60, time: tick / 60, random() { s = (s * 1664525 + 1013904223) >>> 0; return s / 2 ** 32; }, emit() {} };
+}
+const join = (id: string): Input<Cmd> => ({ kind: "join", id });
+const leave = (id: string): Input<Cmd> => ({ kind: "leave", id, reason: "left" });
+const ready = (from: string): Input<Cmd> => ({ kind: "event", from, data: { type: "ready" } });
+const turn = (from: string, t: number): Input<Cmd> => ({ kind: "event", from, data: { turn: t } });
+
+// Drive to sim-step N (tick N*STEP_TICKS) with the given inputs. The sim only advances on
+// step boundaries, so tests tick on them. Reuses the returned state (host feeds it back).
+function makeRunner() {
+  let s: State | undefined;
+  let n = 0;
+  const step = (inputs: Input<Cmd>[] = []): State => (s = contract.tick(s, inputs, makeCtx(++n * STEP_TICKS)) as State);
+  return { step, get: () => s! };
+}
+const seatOf = (s: State, id: string) => s.shell.seats.findIndex((x) => x.id === id);
+
+// ── PURE UNITS ────────────────────────────────────────────────────────────────
+
+test("RLE codec round-trips an arbitrary grid", () => {
+  const g = new Int16Array(W * H);
+  for (let i = 0; i < g.length; i++) g[i] = (i * 7) % 5 === 0 ? i % 9 : 0;
+  expect(Array.from(decodeGrid(encodeGrid(g), W, H))).toEqual(Array.from(g));
+});
+
+test("trailCells expands an L polyline to the exact cells it covers", () => {
+  expect(trailCells([0, 0, 2, 0], 2, 2, 5).sort((a, b) => a - b)).toEqual([0, 1, 2, 7, 12]);
+});
+
+test("claim captures a fully-enclosed pocket (empty AND enemy cells)", () => {
+  const w = 5, h = 5, g = new Int16Array(w * h);
+  for (let x = 0; x < w; x++) { g[x] = 1; g[(h - 1) * w + x] = 1; }
+  for (let y = 0; y < h; y++) { g[y * w] = 1; g[y * w + w - 1] = 1; }
+  g[2 * w + 2] = 2;
+  claim(g, w, h, 1, []);
+  expect(countCells(g, 1)).toBe(w * h);
+  expect(countCells(g, 2)).toBe(0);
+});
+
+test("claim does NOT over-claim when the loop has a gap to the outside", () => {
+  const w = 5, h = 5, g = new Int16Array(w * h);
+  for (let x = 0; x < w; x++) { g[x] = 1; g[(h - 1) * w + x] = 1; }
+  for (let y = 0; y < h; y++) { g[y * w] = 1; g[y * w + w - 1] = 1; }
+  g[2 * w] = 0; g[2 * w + 1] = 0;
+  const before = countCells(g, 1);
+  claim(g, w, h, 1, []);
+  expect(countCells(g, 1)).toBe(before);
+});
+
+// ── LIFECYCLE ─────────────────────────────────────────────────────────────────
+
+test("gathering → ready-up (2) → playing: round starts, players spawned", () => {
+  const r = makeRunner();
+  r.step([join("a"), join("b")]);
+  expect(r.get().shell.phase).toBe("gathering");
+  r.step([ready("a"), ready("b")]);
+  expect(r.get().shell.phase).toBe("playing");
+  expect(r.get().shell.round).toBe(1);
+  expect(readPlayers(r.get()).filter(Boolean).length).toBe(2);
+});
+
+test("a turn event steers the player on the next step", () => {
+  const r = makeRunner();
+  r.step([join("a"), join("b")]);
+  r.step([ready("a"), ready("b")]);
+  const seat = seatOf(r.get(), "a");
+  const p0 = readPlayers(r.get())[seat]!;
+  r.step([turn("a", 2)]); // face down → moves down one cell this step
+  const p1 = readPlayers(r.get())[seat]!;
+  expect([p1.x, p1.y]).toEqual([p0.x, p0.y + 1]);
+});
+
+test("timer horn ends the round; gameover then auto-resets to gathering", () => {
+  const r = makeRunner();
+  r.step([join("a"), join("b")]);
+  r.step([ready("a"), ready("b")]);
+  const roundSteps = Math.ceil(ROUND_TICKS / STEP_TICKS);
+  for (let i = 0; i < roundSteps + 1; i++) r.step();
+  expect(r.get().shell.phase).toBe("gameover");
+  expect(r.get().win).toBeGreaterThanOrEqual(0);
+  const overSteps = Math.ceil(200 / STEP_TICKS);
+  for (let i = 0; i < overSteps + 2; i++) r.step();
+  expect(r.get().shell.phase).toBe("gathering");
+  expect(readPlayers(r.get()).filter(Boolean).length).toBe(0);
+});
+
+test("take-over-abandoned: at a full table a leaver's seat + territory is adopted", () => {
+  const r = makeRunner();
+  r.step(["a", "b", "c", "d", "e", "f"].map(join)); // fills the 6-seat table
+  r.step([ready("a"), ready("b")]);
+  const seat = seatOf(r.get(), "a");
+  r.step([leave("a")]); // mid-game leave → abandoned, territory kept
+  expect(r.get().shell.seats[seat]!.abandoned).toBe(true);
+  const kept = countCells(decodeGrid(r.get().g, W, H), seat + 1);
+  expect(kept).toBeGreaterThan(0);
+  r.step([join("z")]); // full table → takes over the abandoned seat
+  expect(r.get().shell.seats[seat]!.id).toBe("z");
+  expect(countCells(decodeGrid(r.get().g, W, H), seat + 1)).toBe(kept);
+});
+
+// ── GENRE MECHANICS ─────────────────────────────────────────────────────────────
+
+test("claim FLOW: a steered loop out and back grows territory (no diagonal trail)", () => {
+  const r = makeRunner();
+  r.step([join("a"), join("b")]);
+  r.step([ready("a"), ready("b")]);
+  const seat = seatOf(r.get(), "a");
+  const before = countCells(decodeGrid(r.get().g, W, H), seat + 1);
+  const DIR = { up: 0, right: 1, down: 2, left: 3 };
+  const plan: [keyof typeof DIR, number][] = [["right", 3], ["down", 3], ["left", 5], ["up", 4], ["right", 3]];
+  for (const [dir, n] of plan) for (let i = 0; i < n; i++) r.step([turn("a", DIR[dir])]);
+  expect(countCells(decodeGrid(r.get().g, W, H), seat + 1)).toBeGreaterThan(before);
+  expect(readPlayers(r.get())[seat]!.a).toBe(1);
+});
+
+test("collision: stepping onto a rival's trail cuts the TRAIL OWNER (not the cutter)", () => {
+  const seats: Seat[] = [
+    { id: "a", ready: false, abandoned: false },
+    { id: "b", ready: false, abandoned: false },
+  ];
+  const grid = new Int16Array(W * H);
+  for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) { grid[(5 + dy) * W + (5 + dx)] = 1; grid[(8 + dy) * W + (8 + dx)] = 2; }
+  const a: Player = { x: 10, y: 5, d: 1, nd: 1, a: 1, t: [6, 5], rs: 0 }; // trail cells (6..9,5)
+  const b: Player = { x: 8, y: 6, d: 0, nd: 0, a: 1, t: [], rs: 0 };      // steps up onto (8,5)
+  const state: State = { shell: { phase: "playing", seats, round: 1, phaseSince: 0, over: false }, w: W, h: H, g: encodeGrid(grid), pf: [], pt: [], win: -1 };
+  writePlayers(state, [a, b]);
+  const next = contract.tick(state, [], makeCtx(STEP_TICKS)) as State;
+  const [pa, pb] = readPlayers(next);
+  expect(pa!.a).toBe(0);
+  expect(countCells(decodeGrid(next.g, W, H), 1)).toBe(0);
+  expect(pb!.a).toBe(1);
+});
+
+test("respawn: a player that runs into a wall dies, then respawns with fresh territory", () => {
+  const r = makeRunner();
+  r.step([join("a"), join("b")]);
+  r.step([ready("a"), ready("b")]);
+  const seat = seatOf(r.get(), "a");
+  let dead = false;
+  for (let i = 0; i < H + 2 && !dead; i++) { r.step([turn("a", 0)]); dead = readPlayers(r.get())[seat]!.a === 0; }
+  expect(dead).toBe(true);
+  expect(countCells(decodeGrid(r.get().g, W, H), seat + 1)).toBe(0);
+  for (let i = 0; i < 20 && readPlayers(r.get())[seat]!.a === 0; i++) r.step();
+  expect(readPlayers(r.get())[seat]!.a).toBe(1);
+  expect(countCells(decodeGrid(r.get().g, W, H), seat + 1)).toBeGreaterThan(0);
+});
+
+// ── BUDGET ─────────────────────────────────────────────────────────────────────
+
+function datagramBytes(grid: Int16Array, seats: Seat[], players: (Player | null)[]): number {
+  const state: State = { shell: { phase: "playing", seats, round: 5, phaseSince: 4200, over: false }, w: W, h: H, g: encodeGrid(grid), pf: [], pt: [], win: -1 };
+  writePlayers(state, players);
+  return 1 + new TextEncoder().encode(JSON.stringify({ tick: 4321, state })).length;
+}
+function fullTableAtTrailCap(): { seats: Seat[]; players: (Player | null)[] } {
+  const seats: Seat[] = Array.from({ length: 6 }, (_, i) => ({ id: i.toString(36).padStart(3, "0"), ready: false, abandoned: false }));
+  const players: (Player | null)[] = seats.map((_, slot) => {
+    const t: number[] = [];
+    let cx = (slot * 5) % W, cy = (slot * 7) % H;
+    for (let k = 0; k < MAX_TRAIL_TURNS; k++) { t.push(cx, cy); if (k % 2) cx = (cx + 2) % W; else cy = (cy + 2) % H; }
+    return { x: cx, y: cy, d: slot % 4, nd: slot % 4, a: 1 as const, t, rs: 0 };
+  });
+  return { seats, players };
+}
+
+test("GUARD: messy-realistic worst-case state fits one datagram with margin", () => {
+  const { seats, players } = fullTableAtTrailCap();
+  const N = 6;
+  const messy = (seed: number) => {
+    let s = seed >>> 0; const rnd = () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296);
+    const seeds = Array.from({ length: N }, (_, i) => [((i * 5) % W) + 2, ((i * 9) % H) + 2]);
+    const g = new Int16Array(W * H); const R = Math.sqrt((W * H * 0.72) / (N * Math.PI));
+    for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+      let b = -1, bd = Infinity, b2 = -1, bd2 = Infinity;
+      for (let k = 0; k < N; k++) { const dx = x - seeds[k]![0]!, dy = y - seeds[k]![1]!, d = dx * dx + dy * dy; if (d < bd) { bd2 = bd; b2 = b; bd = d; b = k; } else if (d < bd2) { bd2 = d; b2 = k; } }
+      const dd = Math.sqrt(bd);
+      if (dd <= R) { const border = Math.sqrt(bd2) - dd < 2.2; if (border && rnd() < 0.5) g[y * W + x] = rnd() < 0.5 ? b2 + 1 : 0; else g[y * W + x] = b + 1; }
+      else if (rnd() < 0.05) g[y * W + x] = b + 1;
+    }
+    return g;
+  };
+  let worst = 0;
+  for (let seed = 1; seed <= 60; seed++) worst = Math.max(worst, datagramBytes(messy(seed), seats, players));
+  expect(worst).toBeLessThan(MTU_BUDGET);
+});
+
+test("CHARACTERIZATION: vertically-striped territory exceeds a datagram — the JSON-RLE ceiling", () => {
+  // Row-major RLE degrades on vertical striping (every column boundary is a run on every
+  // row). No seat/grid count survives this — the grid alone blows the datagram. It degrades
+  // GRACEFULLY (latest-wins droppable datagram → dropped tick → recover next tick); the real
+  // fix is binary/delta snapshots. This pins that the ceiling is real — nobody should assume
+  // JSON snapshots reach 100 players. See skills/compact-snapshots.md.
+  const { seats, players } = fullTableAtTrailCap();
+  const striped = new Int16Array(W * H);
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) striped[y * W + x] = (x % 6) + 1;
+  expect(datagramBytes(striped, seats, players)).toBeGreaterThan(1200);
+});