create-siltrun 0.1.0

package/templates/tower-defense/skills/two-lanes.md

@@ -0,0 +1,66 @@
+# Two lanes — datagram vs reliable
+
+Read this before sending anything from the client. Silt gives you **two lanes** over one
+connection, with opposite trade-offs. Choosing the wrong one is the most common design mistake.
+
+## The client API
+
+`useRoom` gives you `send`:
+
+```ts
+const { state, send, status } = useRoom<State>("http://localhost:4000", { id });
+
+send({ x, y });                      // DATAGRAM lane — droppable, latest-wins, unordered
+send({ type: "place", slot, kind },  // RELIABLE lane — ordered, guaranteed, discrete
+     { reliable: true });
+```
+
+That single `{ 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 |
+| Use for | continuous, self-correcting signals | state-changing actions |
+
+## The rule
+
+- **Continuous state that overwrites itself → datagram.** A cursor, a position, a heading, an
+  aim direction. If the newest value makes the previous one irrelevant, dropping one costs
+  nothing — the next arrives in ~50ms. Sending these reliably would flood the ordered lane and
+  add latency for no benefit.
+- **Discrete actions that must land exactly once → reliable.** Place a tower, ready up, cast a
+  spell, end a turn, buy an item. Dropping or reordering these corrupts the game. This is where
+  `{ reliable: true }` earns its keep.
+
+## In this template
+
+Both lanes are used for a real reason — that's the teaching point:
+
+- **Teammate cursors → datagram.** `Game.tsx` calls `send({ x, y })` on pointer-move (~pointer
+  rate). In `room.ts`, the top of `tick` reads `kind: "input"` and stores `state.cursors[from]`.
+  Latest-wins: a dropped cursor frame is invisible. Losing one is fine; the next paints over it.
+- **Ready-up + tower placement → reliable.** `Game.tsx` sends `{ type: "ready" }` and
+  `{ type: "place", slot, kind }` with `{ reliable: true }`. These are handled as
+  `kind: "event"` — the shell reads `ready`, `stepGame` reads `place`. A dropped "place" would
+  mean gold spent with no tower (or vice versa) — unacceptable, so it rides the guaranteed lane.
+
+## Gotchas
+
+- **`kind: "input"` is latest-wins per peer per tick** — if a peer sends five cursor updates
+  between ticks, `tick` sees only the last. Don't put anything you must not lose on this lane.
+- **Reliable events are unbounded arbitrary data** (`data: unknown`) — you type/validate them
+  yourself in `tick`. This template guards with a `type` discriminator (`"ready"` / `"place"`)
+  and range-checks the payload before acting. Always validate — it's untyped intent from a
+  client (see `skills/authoritative-tick.md`).
+- **Server-originated events**: `ctx.emit(ev)` (from `authoritative-tick`) pushes a reliable
+  event out after the tick, appearing to clients as an event from `"@server"`. Use it to
+  announce discrete outcomes (a wave cleared, a boss spawned) without bloating broadcast state.
+- **`status`** from `useRoom` is `"connecting" | "connected" | "reconnecting" | "failed" |
+  "closed"`. Render an explicit failed/joining state (this template does) instead of an eternal
+  spinner.

package/templates/tower-defense/skills/waves-and-timing.md

@@ -0,0 +1,79 @@
+# Timing in a deterministic realm — waves, spawns, cooldowns
+
+Read this before doing anything time-based: spawning on a schedule, cooldowns, delays,
+countdowns, "every N seconds". The key shift: **there is no `setTimeout`.** You measure time by
+counting ticks.
+
+## Time = ticks
+
+`tick` runs at a fixed 60Hz. You don't get wall-clock time inside it (it's forbidden — see
+`skills/authoritative-tick.md`). Instead:
+
+- `ctx.tick` — integer count from 0. **This is the clock.** 60 ticks = 1 second.
+- `ctx.dt` — always `1/60`. Multiply per-tick rates by nothing (dt is already baked into "per
+  tick"); use it only when converting a per-second quantity.
+- `ctx.time` — `ctx.tick / 60`, seconds. Derived convenience.
+
+Two idioms cover almost everything:
+
+**A. Countdown counters** — store a number of ticks remaining, decrement each tick, act at 0:
+
+```ts
+if (state.spawnCd <= 0) {
+  spawnACreep(state);
+  state.spawnCd = 24 + Math.floor(ctx.random() * 12);  // reset with jitter
+} else {
+  state.spawnCd -= 1;
+}
+```
+
+**B. Absolute deadlines** — stamp `ctx.tick` when something starts, compare later:
+
+```ts
+shell.phaseSince = ctx.tick;                    // when the phase began
+if (ctx.tick - shell.phaseSince >= gameoverTicks) resetPhase();  // elapsed check
+```
+
+Use (A) for repeating intervals (spawns, cooldowns), (B) for one-shot delays (the gameover
+hold, a warmup). Both are deterministic and replay identically.
+
+## How this template does waves
+
+The wave system in `stepGame` is entirely counter-driven:
+
+- `beginWave(state, n)` sets `state.spawnLeft = 3 + n * 2` — how many creeps this wave still owes.
+- Each tick, if `spawnLeft > 0` and the `spawnCd` counter hits 0, spawn one creep, decrement
+  `spawnLeft`, and reset `spawnCd` to `24 + random jitter` ticks (~0.4–0.6s between spawns).
+- A wave ends when `spawnLeft === 0` **and** `creeps.length === 0` (all spawned and cleared).
+  Then `beginWave(n+1)`, or — past the last wave — set `shell.over = true` (a win).
+- Tower cooldowns are the same idiom per-tower: a tower fires, sets `c` (cooldown ticks), and
+  counts it down each tick before it can fire again.
+
+Nothing here references wall time. Change the pace by changing the counts (`WAVES`, the
+`3 + n*2` formula, the `24` spawn gap, `CREEP_SPEED`) — never by reaching for a timer.
+
+## Deterministic randomness
+
+Jitter, crit chance, spawn variety — all must use `ctx.random()`, never `Math.random()`. It's a
+deterministic hash of `(seed, tick, drawIndex)`: reproducible across replays, but still well-
+distributed. This template uses it for the spawn gap so creeps don't arrive on a robotic beat.
+
+`Math.floor`, `Math.hypot`, `Math.min/max` etc. are pure and **fine** — only the *sources of
+nondeterminism* (random, clock) are banned. (This template calls `Math.floor(ctx.random()*12)`
+— pure math wrapping a deterministic draw.)
+
+## Empty rooms pause — a subtlety
+
+The room only ticks while ≥1 peer is present; an empty room pauses at its last tick and resumes
+on the next join. So `ctx.tick` measures **occupied** time, not real elapsed time. Don't build
+mechanics that assume ticks keep advancing while nobody's watching (e.g. "regenerate 1 gold/sec
+even when empty" won't run when empty). For this always-warm demo it doesn't matter; for a game
+with offline progression, keep the source of truth outside the room (Silt has no durable
+cross-restart persistence yet — see the silt `docs/BOUNDARIES.md`).
+
+## Verify
+
+Because timing is just counters over `ctx.tick`, you test it deterministically: drive N ticks
+with a scripted `ctx` and assert the state (creeps spawned, wave advanced, cooldown elapsed).
+`room.test.ts` drives thousands of ticks to force a full game to its loss, and asserts the
+determinism of a fixed script — copy that pattern for your own timing changes.

package/templates/tower-defense/src/Game.tsx

@@ -0,0 +1,227 @@
+import { useEffect, useRef } from "react";
+import { useRoom } from "@siltrun/react";
+import { createStage, createCamera, type StageHandle } from "@siltrun/stage";
+import { tapBoard } from "@siltrun/stage/input";
+import { Graphics } from "pixi.js";
+// Types are erased at build; PATH/SLOTS/KINDS/creepPos are shared GEOMETRY — the client
+// derives rendering from the very same waypoints the server owns (one source of truth).
+import { PATH, SLOTS, KINDS, WAVES, creepPos, type State } from "../room.ts";
+
+// Register palette (ink-on-bone, Silt #7E837A the one accent). Tokens, not invented art —
+// one set of CSS strings serves both worlds: Pixi 8 accepts them, and so does the DOM.
+const INK = "#0B0B0D", BONE = "#EAE7DE", SAND = "#CFC9BC", SILT = "#7E837A", RUST = "#8a3b2e";
+const BOARD = "#141417", HAIR = "#2a2a2e";
+const A = 480; // arena size in world units (arena-space is 0..1 → ×A); the camera fits it
+
+// A stable identity for this browser tab.
+const PLAYER_ID =
+  sessionStorage.getItem("td-id") ??
+  (() => { const id = crypto.randomUUID().slice(0, 8); sessionStorage.setItem("td-id", id); return id; })();
+
+// Local UI: which tower kind the next tap will place. Kept out of authoritative state.
+let SELECTED_KIND = 0;
+
+export function Game() {
+  const { state, send, status, error } = useRoom<State>("http://localhost:4000", { id: PLAYER_ID });
+
+  // React owns the DOM HUD; the stage redraws the arena each frame from this ref.
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const hostRef = useRef<HTMLDivElement>(null);
+
+  // Machine-readable proof hook — the two-window test reads this, not pixels.
+  useEffect(() => {
+    (window as unknown as { __silt: unknown }).__silt = {
+      id: PLAYER_ID, status,
+      phase: state?.shell.phase, round: state?.shell.round,
+      gold: state?.gold, lives: state?.lives, wave: state?.wave,
+      creeps: state?.creeps.length, towers: state?.towers.length,
+      seats: state?.shell.seats,
+      mySeat: state?.shell.seats.findIndex((s) => s.id === PLAYER_ID),
+    };
+  });
+
+  useEffect(() => {
+    let stage: StageHandle | 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;
+
+      // Fit the whole arena on any screen, refit on rotate/resize.
+      const cam = createCamera(s);
+      const fit = () => cam.fitRect({ x: 0, y: 0, w: A, h: A }, { pad: 16 });
+      fit();
+      s.onResize(fit);
+
+      // THE core verb, phone-first: tap a build slot to place the selected tower.
+      // Taps map through the camera into arena space; the server still validates.
+      tapBoard(s.app.canvas, {
+        map: (sx, sy) => { const w = cam.toWorld(sx, sy); return { x: w.x / A, y: w.y / A }; },
+        onTap: (p) => {
+          const st = stateRef.current;
+          if (!st || st.shell.phase !== "playing") return;
+          let slot = -1, best = 0.08; // tap must land within 0.08 arena units of a slot
+          SLOTS.forEach(([x, y], i) => {
+            const d = Math.hypot(p.x - x, p.y - y);
+            if (d < best) { best = d; slot = i; }
+          });
+          if (slot >= 0 && !st.towers.some((t) => t.s === slot))
+            send({ type: "place", slot, kind: SELECTED_KIND }, { reliable: true });
+        },
+      });
+
+      // Teammate presence: my cursor rides the datagram lane (latest-wins, droppable).
+      const onMove = (e: PointerEvent) => {
+        const r = s.app.canvas.getBoundingClientRect();
+        const w = cam.toWorld(e.clientX - r.left, e.clientY - r.top);
+        send({ x: w.x / A, y: w.y / A });
+      };
+      s.app.canvas.addEventListener("pointermove", onMove);
+
+      // Redraw the arena 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;
+        // board ground + frame
+        gfx.rect(0, 0, A, A).fill(BOARD).stroke({ color: HAIR, width: 1 });
+        // creep path — the sand track the server marches creeps along
+        const [px0, py0] = PATH[0]!;
+        gfx.moveTo(px0 * A, py0 * A);
+        for (const [x, y] of PATH.slice(1)) gfx.lineTo(x * A, y * A);
+        gfx.stroke({ color: SAND, alpha: 0.35, width: 16, join: "round", cap: "round" });
+        if (!st) return;
+        // build slots — square markers (register shape language); tap to place
+        SLOTS.forEach(([x, y], slot) => {
+          const t = st.towers.find((tw) => tw.s === slot);
+          const cx = x * A, cy = y * A;
+          if (!t) gfx.rect(cx - 9, cy - 9, 18, 18).stroke({ color: SILT, alpha: 0.5, width: 1 });
+          else if (t.k === 0) gfx.rect(cx - 8, cy - 8, 16, 16).stroke({ color: BONE, width: 2 }); // arrow: open
+          else gfx.rect(cx - 8, cy - 8, 16, 16).fill(BONE); // cannon: filled
+        });
+        // creeps — position DERIVED from (waypoint idx + progress), never stored
+        for (const c of st.creeps) {
+          const [x, y] = creepPos(c);
+          const cx = x * A, cy = y * A;
+          gfx.circle(cx, cy, 7).fill(SILT);
+          gfx.rect(cx - 8, cy - 13, 16, 2.5).fill(INK);
+          gfx.rect(cx - 8, cy - 13, 16 * Math.max(0, Math.min(1, c.h / (8 + st.wave * 4))), 2.5).fill(BONE);
+        }
+        // teammate cursors — the datagram lane, latest-wins
+        for (const [id, cur] of Object.entries(st.cursors)) {
+          if (id === PLAYER_ID) continue;
+          const cx = cur.x * A, cy = cur.y * A;
+          gfx.moveTo(cx - 6, cy).lineTo(cx + 6, cy).moveTo(cx, cy - 6).lineTo(cx, cy + 6)
+            .stroke({ color: SAND, width: 1 });
+        }
+      });
+    });
+    return () => { cancelled = true; stage?.dispose(); }; // dispose reaps canvas + its listeners
+  }, [send]);
+
+  if (status === "failed") return <Note>connection failed: {String(error)} — is `siltrun dev` running?</Note>;
+  if (!state) return <Note>{status === "reconnecting" ? "reconnecting…" : "joining the room…"}</Note>;
+
+  const { shell, gold, lives, wave } = state;
+  const mySeat = shell.seats.findIndex((s) => s.id === PLAYER_ID);
+
+  // ── DOM chrome (the HUD convention): top bar, phase overlay, bottom bar ──
+  return (
+    <main style={{ position: "fixed", inset: 0, fontFamily: "Geist, system-ui, sans-serif" }}>
+      <div ref={hostRef} style={{ position: "absolute", inset: 0 }} />
+      <Bar at="top">
+        <SeatStrip seats={shell.seats} me={PLAYER_ID} />
+        <span style={{ color: SILT, textTransform: "uppercase", letterSpacing: "0.1em", fontSize: 11 }}>
+          {shell.phase} · game {shell.round}
+        </span>
+      </Bar>
+
+      {shell.phase !== "playing" && (
+        <div style={{ position: "absolute", inset: 0, display: "grid", placeItems: "center", pointerEvents: "none", background: "rgba(11,11,13,0.55)" }}>
+          <div style={{ textAlign: "center" }}>
+            <div style={{ color: BONE, fontSize: 26, letterSpacing: "0.14em" }}>
+              {shell.phase === "gathering" ? "READY UP" : lives <= 0 ? "OVERRUN" : "HELD THE LINE"}
+            </div>
+            <div style={{ color: SILT, fontSize: 12, letterSpacing: "0.1em", marginTop: 8 }}>
+              {shell.phase === "gathering" ? "two players to begin" : `reached wave ${wave}`}
+            </div>
+          </div>
+        </div>
+      )}
+
+      {shell.phase === "gathering" ? (
+        <Bar at="bottom">
+          <span style={{ color: SAND, fontSize: 12 }}>
+            {mySeat < 0 ? "no free seat — you'll play next round" : shell.seats[mySeat]!.ready ? "ready — waiting for a teammate" : "ready up to start (needs 2)"}
+          </span>
+          <button disabled={mySeat < 0 || shell.seats[mySeat]?.ready}
+            onClick={() => send({ type: "ready" }, { reliable: true })}
+            style={btn(mySeat >= 0 && !shell.seats[mySeat]?.ready)}>Ready</button>
+        </Bar>
+      ) : shell.phase === "playing" ? (
+        <Bar at="bottom">
+          <Stat label="gold" value={gold} />
+          <Stat label="lives" value={lives} tone={lives <= 5 ? RUST : BONE} />
+          <Stat label="wave" value={`${wave}/${WAVES}`} />
+          <KindPicker />
+        </Bar>
+      ) : (
+        <Bar at="bottom"><span style={{ color: SAND, fontSize: 12 }}>a new game starts in a moment…</span></Bar>
+      )}
+    </main>
+  );
+}
+
+function SeatStrip({ seats, me }: { seats: State["shell"]["seats"]; me: string }) {
+  return (
+    <span style={{ display: "inline-flex", gap: 6 }}>
+      {seats.map((s, i) => {
+        const mine = s.id === me;
+        const bg = s.abandoned ? "transparent" : s.id ? (s.ready ? SILT : SAND) : "transparent";
+        return (
+          <span key={i} title={s.id ?? "empty"} style={{
+            width: 26, height: 16, border: `1px solid ${s.id ? SILT : HAIR}`, background: bg,
+            display: "grid", placeItems: "center", fontSize: 9, color: s.ready ? INK : SAND,
+            opacity: s.abandoned ? 0.5 : 1,
+          }}>{mine ? "you" : s.abandoned ? "—" : s.id ? "P" : ""}</span>
+        );
+      })}
+    </span>
+  );
+}
+
+function KindPicker() {
+  // kind 0 = arrow (open square), kind 1 = cannon (filled square) — mono glyphs, no art.
+  return (
+    <span style={{ display: "inline-flex", gap: 6 }}>
+      {KINDS.map((k, i) => (
+        <button key={i} onClick={() => { SELECTED_KIND = i; }} style={{ ...btn(true), fontSize: 11, padding: "3px 8px" }}>
+          {i === 0 ? "arrow" : "cannon"} · {k[0]}g
+        </button>
+      ))}
+    </span>
+  );
+}
+
+const Bar = ({ at, children }: { at: "top" | "bottom"; children: React.ReactNode }) => (
+  <div style={{
+    position: "absolute", left: 0, right: 0, [at]: 0, display: "flex", alignItems: "center",
+    justifyContent: "space-between", gap: 12, padding: at === "top"
+      ? "calc(10px + env(safe-area-inset-top, 0px)) 12px 10px"
+      : "10px 12px calc(10px + env(safe-area-inset-bottom, 0px))",
+  }}>{children}</div>
+);
+const Stat = ({ label, value, tone = BONE }: { label: string; value: React.ReactNode; tone?: string }) => (
+  <span style={{ fontSize: 12, color: SAND }}>{label} <b style={{ color: tone, fontVariantNumeric: "tabular-nums" }}>{value}</b></span>
+);
+const Note = ({ children }: { children: React.ReactNode }) => (
+  <p style={{ color: SAND, fontSize: 13, fontFamily: "system-ui", padding: 24 }}>{children}</p>
+);
+const btn = (on: boolean): React.CSSProperties => ({
+  background: on ? BONE : "transparent", color: on ? INK : SAND, border: `1px solid ${on ? BONE : HAIR}`,
+  borderRadius: 0, padding: "5px 14px", fontSize: 12, letterSpacing: "0.06em", textTransform: "uppercase",
+  cursor: on ? "pointer" : "default", fontFamily: "Geist, system-ui, sans-serif",
+});

package/templates/tower-defense/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/tower-defense/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", "vite.config.ts"]
+}

package/templates/tower-defense/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: { port: 5173 },
+});

package/templates/turn-based-grid/AGENTS.md

@@ -0,0 +1,183 @@
+# AGENTS.md — how to play this world as an agent
+
+This is a **turn-based grid** built on [Silt](https://silt.run): an authoritative,
+deterministic world that runs server-side. Humans *watch*; **agents play**. This file is
+your complete briefing. If you are an agent about to play, read it top to bottom — it is
+everything you need, and it is *sufficient* (a brain that reads only what's described here
+can play competently; see `skills/play.md`).
+
+> The game itself (collect pellets on a grid) is deliberately thin — it exists to
+> demonstrate the **substrate**, not to be deep. What's worth learning here is the
+> perception → decision → action loop against a live deterministic clock. Richer games
+> ride this same substrate.
+
+---
+
+## 1. The world
+
+A 12×12 grid. Some cells are walls; the rest are floor. Pellets appear on floor cells;
+move onto a pellet to collect it and score. Every player is one piece, one cell, and moves
+one cell per turn. That's it.
+
+You never see the server's internal state object. You see a **rendered ASCII grid** — the
+same projection a human sees rendered as graphics. This ASCII *is your sensorium*:
+
+```
+############
+#A...*.....#
+#..#....#..#
+#....**....#
+#....##....#
+#....##....#
+#........B.#
+#..#....#..#
+#.......*..#
+#....*.....#
+#.....*....#
+############
+
+phase: playing   round: 3   beat: 7
+beat resolves in: 118 ticks (~2.0s)   pellets left: 6
+you are: A   pos: (1,1)   score: 4   missed: 0   buffered this beat: —
+others: B@(9,6)
+```
+
+### Symbol table
+
+| Glyph | Meaning |
+|------|---------|
+| `#` | wall — impassable |
+| `.` | floor — walkable |
+| `*` | pellet — move onto it to score |
+| `A`–`Z` | a player piece. **Your own letter is named in the `you are:` line.** |
+
+The status lines below the grid tell you who you are, your score, how many beats you've
+missed, what you have buffered this turn, and — critically — **how long until the beat
+resolves**.
+
+### Reading coordinates and directions — the exact convention
+
+Both are needed to move correctly; neither is optional to know:
+
+- **`pos: (x, y)` is `(column, row)`**, zero-indexed, **origin top-left**, with **y
+  increasing downward**. The grid is exactly the width and height of the ASCII block (12×12
+  here, walls included). In the sample, `A` is at `(1,1)` — column 1, row 1 (the top-left
+  interior cell). The **first** grid line under the status is the top row; you can trust the
+  rendered layout, not just the `pos:` numbers.
+- **Moves are grid-relative to what you see**: `up` = toward the top of the grid (row − 1),
+  `down` = row + 1, `left` = column − 1, `right` = column + 1. `up` really is visually up.
+
+---
+
+## 2. The tick / beat model — the one thing to internalize
+
+The world runs on a **constant clock** that never stops while anyone is present (60 steps
+per second). You do **not** act on that clock directly. Turns are quantized into **beats**
+— roughly every **4 seconds**. Here is the whole model:
+
+1. **You buffer one action per beat.** Send your move any time during the ~4s beat window.
+2. **Latest-wins.** If you send again before the beat resolves, your newer action replaces
+   the older one. You may change your mind until the beat lands.
+3. **The beat resolves all buffered actions simultaneously.** At the boundary, every
+   player's buffered move applies at once, from one shared snapshot.
+4. **Conflicts are symmetric.** Two players moving into the same cell? *Both bounce* (stay
+   put). Move into a cell someone is holding? *You bounce.* Move into a wall? *You bounce.*
+   There is no turn order and no initiative — contention just means nobody wins that cell.
+5. **If you don't act in time, you idle that beat.** Were you still thinking when the beat
+   landed? Then you had nothing buffered, your `missed` count ticks up, and your piece
+   stays put. **Being too slow is a real, visible failure** — and it's part of the game.
+
+### What this means for you, the agent
+
+- **You have a deadline every beat.** The `beat resolves in: N ticks (~Ns)` line is your
+  clock. If your think-time exceeds it, you miss. Budget accordingly — a fast, rough
+  decision that lands beats a perfect decision that arrives late.
+- **Your perception is stale by up to one beat.** You decide from the grid as it was when
+  you read it; by the time your action resolves, others have moved. Plan for it — don't
+  assume the board is frozen while you think.
+- **You cannot be starved by another slow agent.** The clock never waits for anyone. A
+  frozen opponent just misses its beats; the world rolls on.
+
+That's the design. A constant clock that never pauses + buffered actions + a hard per-beat
+deadline is what lets variable-latency agents share one live, watchable world.
+
+---
+
+## 3. The action API
+
+You act by sending messages on the **reliable, ordered lane** (in Silt client terms:
+`send(msg, { reliable: true })`). **Turns must use the reliable lane, never the droppable
+datagram lane** — a dropped turn is a silently missed beat you didn't choose.
+
+| Message | Effect |
+|---|---|
+| `{ "t": "sit" }` | Take a seat — become a player and spawn your piece. Send this first. |
+| `{ "t": "act", "move": "up" \| "down" \| "left" \| "right" \| "stay" }` | Buffer your move for the current beat (latest-wins). `stay` is a real, deliberate action — it is **not** a miss. |
+| `{ "t": "emote", "glyph": "<one of the vocab>" }` | Broadcast a coarse signal (see §4). Applies immediately; does not consume your turn. |
+| `{ "t": "stand" }` | Leave your seat — become a spectator, despawn your piece. |
+
+The loop, in words: **`sit` once → each beat, read the ASCII, decide a move, `act` before
+the deadline → repeat.**
+
+---
+
+## 4. The emote channel — coarse comms
+
+You can't send prose. You can flash **one glyph** that every other agent (and the
+spectators) see next to your piece for a couple of beats, then it fades. Emotes are how
+agents signal intent in a world with no chat. The vocabulary is tiny and the meanings are
+**convention, not enforced** — the substrate only guarantees your glyph is delivered,
+shown, and decays.
+
+| Glyph | Suggested meaning |
+|------|---------|
+| `!` | alert / danger here |
+| `?` | confused / need help |
+| `+` | friendly / let's cooperate |
+| `-` | back off / hostile |
+| `^` | good / agreed |
+| `x` | no / taunt |
+
+Emotes are exempt from beat-buffering: they apply the moment they arrive (so they keep the
+world lively between the slower turn beats). Rate-limited to roughly one per beat.
+
+---
+
+## 5. Strategy hints
+
+- **Path to the nearest pellet.** Parse the grid, find `*` cells, breadth-first search over
+  floor toward the closest one, take the first step. (A worked example is in
+  `skills/play.md`.)
+- **Act early in the beat, revise if you learn more.** Latest-wins means an early rough move
+  is free insurance against missing; refine it if you have time.
+- **Expect contention.** If another piece wants the same pellet, you may both bounce. A
+  `stay` or a sidestep sometimes beats a doomed push.
+- **Don't over-think.** The deadline is real. A good-enough move on time always beats a
+  perfect move that misses the beat.
+
+---
+
+## 6. Honest limits
+
+- **Presence-gated clock.** The world clock is constant *while at least one peer is
+  present*; an empty room pauses until someone joins. During play this never bites — there's
+  always at least you.
+- **Stale-by-one-beat perception**, as above. Baked into the model, not a bug.
+- **Use a unique, stable identity.** Your `id` is how the world knows you. It must be
+  unique per agent: if two live connections claim the same id, the server treats the newer
+  as a reconnection and *supersedes* the old one in place — so two genuinely-concurrent
+  agents sharing an id will thrash (each keeps kicking the other off) and neither plays.
+  One agent, one durable id. (This is a real multi-agent-deploy requirement — it bites the
+  moment you run more than one agent, so pick unique ids up front.)
+- **This template proves the interface with scripted stub agents.** Connecting a *real*
+  LLM agent over MCP is a separate piece of work — the substrate here is exactly the surface
+  such a connection targets, verified by stubs that perceive only this ASCII and play well.
+
+---
+
+## Files
+
+- `skills/play.md` — a hands-on recipe: how to turn this briefing into a working brain.
+- `room.ts` — the authoritative contract (the rules above, as deterministic code). Read it
+  if you want ground truth; you don't need to in order to play.
+- `src/substrate/` — the shared kernel: the map, the ASCII projection, the types.

package/templates/turn-based-grid/README.md

@@ -0,0 +1,72 @@
+# turn-based grid — an agent-native game on Silt
+
+A genre starter for **agent-first games**: a deterministic, authoritative world that *agents*
+play and *humans* watch. This template is the substrate — an action API for agents, dual
+rendering (a graphics view for people + an ASCII view for agents, both projections of one
+state), an emote channel, and the agent-paced beat model — proven with scripted stub agents.
+
+The game itself (collect pellets on a 12×12 grid) is deliberately thin. What's worth learning
+is the **substrate**: how a variable-latency agent perceives, decides, and acts against a
+constant server clock. Richer games ride the same shape.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+This boots both halves:
+
+- **room** — `siltrun dev room.ts`: your authoritative contract at 60Hz (room-info on
+  `http://localhost:4000`, WebTransport on `:4433`). A determinism doctor re-checks it on
+  every save.
+- **web** — vite on [http://localhost:5173](http://localhost:5173): the human spectator view.
+
+Then launch some agents by naming them in the URL — they join and play, you watch:
+
+```
+http://localhost:5173/?agents=greedy,slow,chatty
+```
+
+`greedy` plays well, `slow` is deliberately too slow (watch it stutter and rack up missed
+beats), `chatty` flashes emotes. They connect as real, independent clients — each perceiving
+**only** the ASCII grid, exactly as a real agent would.
+
+## The one thing to understand — the beat model
+
+The world clock never stops. Turns are quantized into **beats** (~4s). An agent buffers one
+action per beat on the reliable lane (latest-wins); at the beat boundary every buffered action
+resolves at once, with symmetric conflict rules. **An agent still thinking when the beat lands
+simply misses it** — the too-slow failure is visible, and it's the point. Read
+[`AGENTS.md`](./AGENTS.md) for the full model; it's the real deliverable here.
+
+## Edit
+
+- `room.ts` — the authority: the beat engine, movement/collision resolution, pellets, rounds.
+  Hot-reloads on save (determinism re-checked each time).
+- `src/App.tsx` — the spectator: the graphics view + the agent ASCII view, side by side.
+- `src/GraphicsView.tsx` — the human render on `@siltrun/stage` (PixiJS): `createStage` +
+  `cam.fitRect(board)` — a pure spectator surface, so that IS the whole ceremony (gliding
+  pieces, emote bubbles, missed-beat stutter, beat-progress bar; phone-viewable by default).
+- `src/substrate/` — the shared kernel both sides project from: `types.ts`, `map.ts`
+  (geometry + the tick/beat constants — tune `BEAT_TICKS` for tempo), `ascii.ts` (the
+  agent-facing projection + the symbol table).
+- `src/brains.ts` — the scripted stub agents. Swap in your own brain here.
+
+## Learn to write an agent
+
+- [`AGENTS.md`](./AGENTS.md) — the complete agent briefing: world model, symbol table, the
+  beat model, the action API, the emote vocabulary, strategy, and honest limits.
+- [`skills/play.md`](./skills/play.md) — a hands-on recipe: turn the briefing into a working
+  brain (parse the ASCII → BFS to the nearest pellet → act before the deadline).
+
+## Determinism
+
+The contract is a pure function of `(state, inputs, ctx)`, so the whole beat engine —
+buffering, simultaneous resolution, missed beats, scoring, rounds — is deterministic and
+replayable. `siltrun dev` runs a **determinism doctor** on every save that replays your contract
+and fails loudly if it drifts (uses wall-clock time, unseeded randomness, etc.). Watch for the
+`determinism ✔ ok` line in the room output — that's your correctness guard. Because the
+contract is pure, you can also unit-test it directly by calling `tick()` with scripted input
+batches; no transport or browser needed.

package/templates/turn-based-grid/_gitignore

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