create-siltrun 0.1.0

package/templates/turn-based-grid/src/GraphicsView.tsx

@@ -0,0 +1,148 @@
+// GraphicsView.tsx — the HUMAN projection of the same deterministic State the agents
+// read as ASCII. This is the wedge dramatized: identical truth, two renders.
+//
+// It makes the two "agents being agents" primitives READ to a spectator:
+//   • EMOTE CHANNEL — a player's emote glyph pops as a bubble above its piece and fades.
+//   • MISSED-BEAT STUTTER — a piece that failed to act by the boundary dims, shows a "z"
+//     thought bubble, and its scoreboard `missed` climbs. The slow agent visibly stutters
+//     while the greedy ones glide. Too-slow-is-the-fun, made watchable.
+//
+// Rendered on @siltrun/stage. This is a pure SPECTATOR surface — no interaction exists, so
+// the ceremony is createStage + one fitRect, full stop (no input primitive). Movement is
+// interpolated client-side (pieces glide toward their new cell each beat) — presentation
+// over the one authoritative State; the truth is still the grid cell.
+
+import { useEffect, useRef } from "react";
+import { createStage, createCamera, type StageHandle } from "@siltrun/stage";
+import { Graphics, Text } from "pixi.js";
+import type { State } from "./substrate/types.ts";
+import { MAP, GRID_W, GRID_H, BEAT_TICKS } from "./substrate/map.ts";
+
+const CELL = 40; // world units per cell (arbitrary — the camera fits the board)
+const INK = "#0b0b0d", WALL = "#050506", FLOOR = "#17171b", COPPER = "#b07050", RUST = "#a65a2e";
+
+// Seat colors — the register's warm family (hue-restrained), keyed by seat glyph.
+const COLORS: Record<string, string> = {
+  A: "#eae7de", B: "#cfc9bc", C: "#b07050", D: "#c98a3d", E: "#7e837a", F: "#a65a2e",
+};
+const colorFor = (glyph: string) => COLORS[glyph] ?? "#cfc9bc";
+
+type Piece = { x: number; y: number; glyph: Text; bubble: Text };
+
+export function GraphicsView({ state }: { state: State }) {
+  // The stage draws from the latest state via this ref (React re-renders only the DOM bar).
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const hostRef = useRef<HTMLDivElement>(null);
+
+  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;
+
+      // One camera call: frame the whole board, refit on resize.
+      const cam = createCamera(s);
+      const fit = () => cam.fitRect({ x: 0, y: 0, w: GRID_W * CELL, h: GRID_H * CELL }, { pad: 6 });
+      fit();
+      s.onResize(fit);
+
+      const gfx = s.world.addChild(new Graphics());
+      // World-space text lives in Pixi (glyphs, bubbles). Each piece keeps its Text
+      // objects across frames — `.text` is only ASSIGNED on change, because every
+      // assignment re-rasterizes the glyph texture (the stage README's 10 Hz warning).
+      const pieces = new Map<string, Piece>();
+      const makeText = (size: number): Text => {
+        const t = new Text({ text: "", style: { fontFamily: "ui-monospace, monospace", fontSize: size, fontWeight: "700", fill: "#0b0b0c" } });
+        t.anchor.set(0.5);
+        return s.world.addChild(t);
+      };
+
+      s.app.ticker.add(() => {
+        cam.update(1 / 60);
+        const st = stateRef.current;
+        gfx.clear();
+
+        // cells — walls tight, floors rounded (same shape language as the ASCII: # vs .)
+        for (let y = 0; y < GRID_H; y++)
+          for (let x = 0; x < GRID_W; x++) {
+            const wall = MAP[y]!.charAt(x) === "#";
+            gfx.roundRect(x * CELL + 2, y * CELL + 2, CELL - 4, CELL - 4, wall ? 3 : 6)
+              .fill(wall ? WALL : FLOOR);
+          }
+
+        // pellets — the scoring resource; warmth carries the meaning (copper, pulsing)
+        const pulse = 0.55 + 0.45 * Math.sin(performance.now() / 300);
+        for (const p of st.pellets) {
+          gfx.circle(p.x * CELL + CELL / 2, p.y * CELL + CELL / 2, 5).fill({ color: COPPER, alpha: pulse });
+        }
+
+        // pieces — eased toward the authoritative cell (the glide); truth stays discrete
+        for (const [id, pc] of pieces) {
+          if (!st.players[id]) {
+            pc.glyph.destroy();
+            pc.bubble.destroy();
+            pieces.delete(id);
+          }
+        }
+        for (const p of Object.values(st.players)) {
+          let pc = pieces.get(p.id);
+          if (!pc) {
+            pc = { x: p.pos.x * CELL, y: p.pos.y * CELL, glyph: makeText(16), bubble: makeText(15) };
+            pc.glyph.text = p.glyph;
+            pieces.set(p.id, pc);
+          }
+          pc.x += (p.pos.x * CELL - pc.x) * 0.22; // ease per frame (60fps)
+          pc.y += (p.pos.y * CELL - pc.y) * 0.22;
+          const cx = pc.x + CELL / 2, cy = pc.y + CELL / 2;
+          const missed = !p.actedLastBeat && st.phase === "playing";
+          const color = colorFor(p.glyph);
+          const alpha = missed ? 0.5 : 1;
+
+          if (missed) gfx.circle(cx, cy, CELL / 2 - 3).stroke({ color: RUST, width: 1.5, alpha }); // stutter halo
+          gfx.roundRect(pc.x + 5, pc.y + 5, CELL - 10, CELL - 10, 7)
+            .fill({ color, alpha })
+            .stroke({ color: missed ? RUST : "#eae7de", width: 1.5, alpha: missed ? alpha : 0.25 });
+          pc.glyph.position.set(cx, cy);
+          pc.glyph.alpha = alpha;
+
+          // the coarse comms channel (emote bubble) — or the "z" thinking-past-the-beat mark
+          const bubbleText = p.emote ?? (missed ? "z" : "");
+          if (pc.bubble.text !== bubbleText) pc.bubble.text = bubbleText;
+          if (bubbleText) {
+            if (p.emote) {
+              gfx.roundRect(cx + 8, pc.y - 12, 22, 22, 6).fill("#121214").stroke({ color, width: 1.5 });
+              pc.bubble.style.fill = color;
+            } else {
+              pc.bubble.style.fill = RUST;
+            }
+            pc.bubble.position.set(cx + 19, pc.y - 1);
+            pc.bubble.visible = true;
+          } else {
+            pc.bubble.visible = false;
+          }
+        }
+      });
+    });
+    return () => { cancelled = true; stage?.dispose(); };
+  }, []);
+
+  const ticksLeft = Math.max(0, state.nextBeatTick - state.clock);
+  const beatProgress = state.phase === "playing" ? 1 - ticksLeft / BEAT_TICKS : 0;
+  const W = "min(92vw, 480px)";
+
+  return (
+    <div>
+      {/* beat rhythm bar — fills over the beat, snaps back when the beat resolves */}
+      <div style={{ width: W, height: 6, background: "#1c1c1f", borderRadius: 3, overflow: "hidden", marginBottom: 8 }}>
+        <div style={{
+          width: `${Math.round(beatProgress * 100)}%`, height: "100%",
+          background: state.phase === "playing" ? "#cfc9bc" : "#3a3a3d", transition: "width 90ms linear",
+        }} />
+      </div>
+      <div ref={hostRef} style={{ width: W, aspectRatio: `${GRID_W} / ${GRID_H}`, borderRadius: 10, overflow: "hidden" }} />
+    </div>
+  );
+}

package/templates/turn-based-grid/src/brains.ts

@@ -0,0 +1,112 @@
+// brains.ts — scripted stub agents. Each brain is a pure decision function over the
+// AGENT PERCEPTION (the rendered ASCII string) — it never sees State. That constraint
+// is the whole point: if these can play from text alone, the substrate is sufficient,
+// and the same brain lifts behind a real MCP agent later (DIG-718) unchanged.
+//
+// The four brains double as the substrate's live demonstrators:
+//   greedy — competent play (walks to the nearest pellet)
+//   random — a control (moves arbitrarily)
+//   chatty — exercises the EMOTE CHANNEL (a 728 primitive)
+//   slow   — thinks longer than a beat, so it visibly MISSES beats (a 728 primitive)
+
+import type { Cmd, Dir } from "./substrate/types.ts";
+import { EMOTE_VOCAB } from "./substrate/map.ts";
+import { readView, stepTowardNearestPellet } from "./view.ts";
+
+export type Brain = {
+  name: string;
+  /** simulated think latency in ms — the read→think→act loop's variable cost. */
+  thinkMs: () => number;
+  /** decide an action from the ASCII perception alone. null = do nothing this cycle. */
+  decide: (ascii: string, rng: () => number) => Cmd | null;
+};
+
+const DIRS: Dir[] = ["up", "down", "left", "right", "stay"];
+
+/** competent: pathfind to the nearest pellet, else drift to a random legal cell. */
+export const greedy: Brain = {
+  name: "greedy",
+  thinkMs: () => 250 + Math.random() * 400, // ~0.25–0.65s: comfortably inside a 4s beat
+  decide(ascii) {
+    const view = readView(ascii);
+    const toward = stepTowardNearestPellet(view);
+    if (toward) return { t: "act", move: toward };
+    // no reachable pellet: pick any non-wall step so the piece still reads as alive.
+    if (view.self) {
+      for (const dir of ["up", "down", "left", "right"] as Dir[]) {
+        const d = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] }[dir as "up"];
+        if (!view.isWall(view.self.x + d[0], view.self.y + d[1])) return { t: "act", move: dir };
+      }
+    }
+    return { t: "act", move: "stay" };
+  },
+};
+
+/** control: a legal random move each cycle. */
+export const random: Brain = {
+  name: "random",
+  thinkMs: () => 200 + Math.random() * 500,
+  decide(ascii, rng) {
+    const view = readView(ascii);
+    if (!view.self) return { t: "act", move: "stay" };
+    const legal = (["up", "down", "left", "right"] as Dir[]).filter((dir) => {
+      const d = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] }[dir as "up"];
+      return !view.isWall(view.self!.x + d[0], view.self!.y + d[1]);
+    });
+    legal.push("stay");
+    return { t: "act", move: legal[Math.floor(rng() * legal.length)] };
+  },
+};
+
+/** talkative: plays greedily but every few cycles flashes an emote — exercises the channel. */
+export function makeChatty(): Brain {
+  let cycle = 0;
+  return {
+    name: "chatty",
+    thinkMs: () => 300 + Math.random() * 400,
+    decide(ascii, rng) {
+      cycle++;
+      if (cycle % 3 === 0) {
+        const glyph = EMOTE_VOCAB[Math.floor(rng() * EMOTE_VOCAB.length)];
+        return { t: "emote", glyph };
+      }
+      return greedy.decide(ascii, rng);
+    },
+  };
+}
+
+/**
+ * SLOW: thinks longer than a beat (beat ≈ 4000ms), straddling the boundary so it lands
+ * some beats and misses many — the visible stutter. Its missedBeats climbs while the
+ * greedy agents' stays near zero. This is the too-slow-is-the-fun demonstrator.
+ */
+export const slow: Brain = {
+  name: "slow",
+  thinkMs: () => 3500 + Math.random() * 4000, // ~3.5–7.5s vs a 4s beat → frequent misses
+  decide(ascii, rng) {
+    return greedy.decide(ascii, rng);
+  },
+};
+
+export const BRAINS: Record<string, () => Brain> = {
+  greedy: () => greedy,
+  random: () => random,
+  chatty: () => makeChatty(),
+  slow: () => slow,
+};
+
+/** small deterministic-ish rng for a stub (seeded off its id so runs are reproducible-ish). */
+export function seededRng(seedStr: string): () => number {
+  let h = 2166136261;
+  for (let i = 0; i < seedStr.length; i++) {
+    h ^= seedStr.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return () => {
+    h += 0x6d2b79f5;
+    let t = h;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}

package/templates/turn-based-grid/src/main.tsx

@@ -0,0 +1,8 @@
+import { createRoot } from "react-dom/client";
+import { App } from "./App.tsx";
+
+// NB: no React.StrictMode here. StrictMode's dev double-invoke of effects would launch
+// the long-lived stub-agent connections, tear them down, and not relaunch them (the
+// once-guard suppresses the second run). The stubs are real sockets, not idempotent
+// effects — so this app opts out of StrictMode rather than fight the double-mount.
+createRoot(document.getElementById("root")!).render(<App />);

package/templates/turn-based-grid/src/stubAgent.ts

@@ -0,0 +1,82 @@
+// stubAgent.ts — a scripted agent as a REAL Silt client. It opens its own joinRoom
+// connection (exactly like the drift diag two-connection pattern), so from the room's
+// point of view it is indistinguishable from any other peer — and from a real MCP-driven
+// agent later (DIG-718). The only difference is the brain: scripted here, an LLM there.
+//
+// The read→think→act loop is deliberately faithful to real agent latency:
+//   1. snapshot the latest received State,
+//   2. render it to the ASCII perception the brain is allowed to see,
+//   3. WAIT brain.thinkMs (the variable LLM-latency stand-in),
+//   4. send the decision on the reliable lane.
+// Because the send happens AFTER the think delay, the agent acts on stale perception and
+// may land after the beat boundary — which is the entire point of the model.
+
+import { joinRoom, type Room } from "@siltrun/client";
+import type { State } from "./substrate/types.ts";
+import { renderAscii } from "./substrate/ascii.ts";
+import type { Brain } from "./brains.ts";
+import { seededRng } from "./brains.ts";
+
+export type StubHandle = { id: string; brain: string; room: Room; stop: () => void };
+
+export async function runStubAgent(opts: {
+  url: string;
+  id: string;
+  brain: Brain;
+  certHash?: string;
+}): Promise<StubHandle> {
+  const { url, id, brain } = opts;
+  const room = await joinRoom(url, { id, certHash: opts.certHash });
+  const rng = seededRng(id);
+  let latest: State | null = null;
+  let running = true;
+  let thinking = false;
+
+  room.on("state", (s) => {
+    latest = s.state as State;
+  });
+
+  // take a seat immediately; if the connection blips, we re-sit on reconnect via the loop.
+  room.events.send({ t: "sit" });
+
+  const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+  (async function loop() {
+    while (running) {
+      // `as`: TS can't see the room.on("state") callback assigning `latest`, so it
+      // narrows it to its `null` initializer here. The cast restores the real type.
+      const cur = latest as State | null;
+      if (cur) {
+        // ensure we're seated: resend sit until we appear as a player.
+        if (!cur.players[id]) {
+          room.events.send({ t: "sit" });
+          await sleep(200);
+          continue;
+        }
+        if (!thinking) {
+          thinking = true;
+          const ascii = renderAscii(cur, id);            // the ONLY thing the brain sees
+          await sleep(brain.thinkMs());                  // variable think latency
+          if (!running) break;
+          const cmd = brain.decide(ascii, rng);
+          if (cmd) room.events.send(cmd);
+          thinking = false;
+        }
+      }
+      await sleep(60);
+    }
+  })();
+
+  return {
+    id,
+    brain: brain.name,
+    room,
+    stop() {
+      running = false;
+      try {
+        room.events.send({ t: "stand" });
+      } catch {}
+      room.close?.();
+    },
+  };
+}

package/templates/turn-based-grid/src/substrate/ascii.ts

@@ -0,0 +1,87 @@
+// ascii.ts — the AGENT-FACING projection of the canonical state.
+//
+// One deterministic State; two renders. The human sees the React graphics view; the
+// agent sees THIS — a plain-text grid plus a status block. This string is the agent's
+// entire sensorium. The stub-agent honesty rule (test/perception.test.ts) is that a
+// brain may read ONLY this string and the SYMBOLS table — never the State object — so
+// if a brain can play, the projection is provably sufficient.
+
+import type { State, Pos } from "./types.ts";
+import { MAP, GRID_W, GRID_H, cellKey } from "./map.ts";
+
+/** The symbol table. Publish this to agents verbatim (AGENTS.md embeds it). */
+export const SYMBOLS: ReadonlyArray<{ glyph: string; meaning: string }> = [
+  { glyph: "#", meaning: "wall — impassable" },
+  { glyph: ".", meaning: "floor — walkable" },
+  { glyph: "*", meaning: "pellet — move onto it to score" },
+  { glyph: "A-Z", meaning: "a player piece — your own letter is named in the status line" },
+];
+
+function playerAt(state: State, key: string): string | null {
+  for (const id in state.players) {
+    const p = state.players[id];
+    if (cellKey(p.pos) === key) return p.glyph;
+  }
+  return null;
+}
+
+function pelletKeys(state: State): Set<string> {
+  const s = new Set<string>();
+  for (const p of state.pellets) s.add(cellKey(p));
+  return s;
+}
+
+/** Render just the grid (walls, pellets, players) — no status. */
+export function renderGrid(state: State): string {
+  const pellets = pelletKeys(state);
+  const rows: string[] = [];
+  for (let y = 0; y < GRID_H; y++) {
+    let row = "";
+    for (let x = 0; x < GRID_W; x++) {
+      const key = `${x},${y}`;
+      if (MAP[y][x] === "#") { row += "#"; continue; }
+      const who = playerAt(state, key);
+      if (who) { row += who; continue; }
+      if (pellets.has(key)) { row += "*"; continue; }
+      row += ".";
+    }
+    rows.push(row);
+  }
+  return rows.join("\n");
+}
+
+/**
+ * The full agent perception: grid + status. `selfId` names which piece is "you" and
+ * surfaces your score/emote and how many ticks remain before the beat resolves — the
+ * agent's read on "how long do I have to think." Others' emotes are listed so coarse
+ * comms is legible from the ASCII alone.
+ */
+export function renderAscii(state: State, selfId?: string): string {
+  const grid = renderGrid(state);
+  const lines: string[] = [grid, ""];
+
+  const self = selfId ? state.players[selfId] : undefined;
+  const ticksLeft = Math.max(0, state.nextBeatTick - state.clock);
+  lines.push(`phase: ${state.phase}   round: ${state.round}   beat: ${state.beat}`);
+  lines.push(`beat resolves in: ${ticksLeft} ticks (~${(ticksLeft / 60).toFixed(1)}s)   pellets left: ${state.pellets.length}`);
+
+  if (self) {
+    const buffered = state.pending[selfId!];
+    lines.push(
+      `you are: ${self.glyph}   pos: (${self.pos.x},${self.pos.y})   score: ${self.score}` +
+        `   missed: ${self.missedBeats}   buffered this beat: ${buffered ?? "—"}`,
+    );
+  } else if (selfId) {
+    lines.push(`you are: (spectating — send { t: "sit" } to take a seat)`);
+  }
+
+  const others = Object.values(state.players).filter((p) => p.id !== selfId);
+  if (others.length) {
+    lines.push(
+      `others: ${others
+        .map((p) => `${p.glyph}@(${p.pos.x},${p.pos.y})${p.emote ? " " + p.emote : ""}`)
+        .join("  ")}`,
+    );
+  }
+  return lines.join("\n");
+}

package/templates/turn-based-grid/src/substrate/map.ts

@@ -0,0 +1,104 @@
+// map.ts — the static arena + the tick/beat constants + pure geometry.
+//
+// Shared by the server contract and the client. The MAP literal is itself an ASCII
+// teaching artifact: `#` wall, `.` floor. It is the SAME symbol vocabulary the agent
+// perceives, so the source you read and the grid the agent reads are one thing.
+
+import type { Dir, Pos } from "./types.ts";
+
+// ── The tick / beat model constants (the load-bearing design, DIG-725) ──
+//
+// The relay's world clock runs at a fixed 60 ticks/sec and never pauses while ≥1 peer
+// is present. On top of that constant clock we quantize turns into BEATS.
+//
+// A beat is BEAT_TICKS ticks (~4s). Agents buffer at most one action per beat on the
+// reliable lane; at the beat boundary every buffered action resolves SIMULTANEOUSLY.
+// An agent still thinking when the boundary lands simply has nothing buffered — it
+// idles that beat. The too-slow failure is visible (missedBeats) and is the fun.
+//
+// Tune BEAT_TICKS to taste — it's the one knob for tempo. Everything else derives.
+export const TICKS_PER_SEC = 60;
+export const BEAT_TICKS = 240;              // ~4.0s per beat — a watchable turn cadence
+export const ROUND_BEATS = 20;              // a round runs 20 beats (~80s), then intermission
+export const INTERMISSION_BEATS = 3;        // scoreboard breather between rounds (~12s)
+export const EMOTE_DECAY_BEATS = 2;         // an emote glyph shows for 2 beats, then clears
+export const PELLET_COUNT = 10;             // collectibles spawned per round
+
+// The coarse comms vocabulary — deliberately tiny. Agents don't chat in prose; they
+// flash one primitive. Meanings are convention (documented in AGENTS.md); the substrate
+// only guarantees the glyph is delivered, rendered, and decays deterministically.
+export const EMOTE_VOCAB = ["!", "?", "+", "-", "^", "x"] as const;
+export function isEmoteGlyph(g: unknown): g is string {
+  return typeof g === "string" && (EMOTE_VOCAB as readonly string[]).includes(g);
+}
+
+// ── The arena. 12×12. Border walls + a few interior blocks to make routing matter. ──
+export const MAP: readonly string[] = [
+  "############",
+  "#..........#",
+  "#..#....#..#",
+  "#..........#",
+  "#....##....#",
+  "#....##....#",
+  "#..........#",
+  "#..#....#..#",
+  "#..........#",
+  "#..........#",
+  "#..........#",
+  "############",
+];
+
+export const GRID_W = MAP[0].length;   // 12
+export const GRID_H = MAP.length;      // 12
+
+export function isWall(x: number, y: number): boolean {
+  if (y < 0 || y >= GRID_H || x < 0 || x >= GRID_W) return true;   // out of bounds = wall
+  return MAP[y][x] === "#";
+}
+export function isFloor(x: number, y: number): boolean {
+  return !isWall(x, y);
+}
+
+/** All floor cells, top-to-bottom / left-to-right — a stable ordering for deterministic spawns. */
+export const FLOOR_CELLS: readonly Pos[] = (() => {
+  const cells: Pos[] = [];
+  for (let y = 0; y < GRID_H; y++) {
+    for (let x = 0; x < GRID_W; x++) {
+      if (isFloor(x, y)) cells.push({ x, y });
+    }
+  }
+  return cells;
+})();
+
+/** Fixed seat spawn points (floor cells near the corners), assigned in seat order. */
+export const SPAWNS: readonly Pos[] = [
+  { x: 1, y: 1 },
+  { x: 10, y: 10 },
+  { x: 10, y: 1 },
+  { x: 1, y: 10 },
+  { x: 1, y: 5 },
+  { x: 10, y: 6 },
+];
+
+const DELTA: Record<Dir, Pos> = {
+  up: { x: 0, y: -1 },
+  down: { x: 0, y: 1 },
+  left: { x: -1, y: 0 },
+  right: { x: 1, y: 0 },
+  stay: { x: 0, y: 0 },
+};
+
+/** Where `dir` from `pos` lands — no wall check (the resolver decides legality). */
+export function step(pos: Pos, dir: Dir): Pos {
+  const d = DELTA[dir];
+  return { x: pos.x + d.x, y: pos.y + d.y };
+}
+
+export const cellKey = (p: Pos): string => `${p.x},${p.y}`;
+export const samePos = (a: Pos, b: Pos): boolean => a.x === b.x && a.y === b.y;
+
+/** Seat index → board glyph. A, B, C … then wraps into lowercase if ever exhausted. */
+export function glyphFor(seatIndex: number): string {
+  const upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  return upper[seatIndex % upper.length];
+}

package/templates/turn-based-grid/src/substrate/types.ts

@@ -0,0 +1,59 @@
+// types.ts — the shape of the world, shared verbatim across the seam.
+//
+// The SERVER contract (../../room.ts) produces `State`; the CLIENT (spectator app +
+// stub agents) reads it. Both import these types. Nothing here is server-only —
+// it's plain data (CONTRACT §1: "State is just data"), so the same file is safe in
+// the browser bundle and in the Bun host.
+
+/** The five things an agent can do with a turn. `stay` is a real, deliberate move. */
+export type Dir = "up" | "down" | "left" | "right" | "stay";
+
+/**
+ * The AGENT ACTION API — every message an agent sends on the RELIABLE, ordered lane
+ * (`send(msg, { reliable: true })`). Turns MUST NOT ride the droppable datagram lane;
+ * a dropped turn is a silently missed beat you didn't choose. This genre→lane mapping
+ * is a teaching point (see AGENTS.md).
+ *
+ * NB: none of these carry a `clientTick` field — that field would divert the event
+ * into the relay's lag-compensation shot path (main.go). Turn games want the plain
+ * ordered queue, so the shapes stay clientTick-free by construction.
+ */
+export type Cmd =
+  | { t: "sit" }                         // take a seat: spectator → player (spawns your piece)
+  | { t: "stand" }                       // leave your seat: player → spectator (despawns)
+  | { t: "act"; move: Dir }              // buffer your move for the CURRENT beat (latest-wins)
+  | { t: "emote"; glyph: string };       // broadcast a coarse comms glyph (applies on arrival)
+
+export type Pos = { x: number; y: number };
+
+export type Player = {
+  id: string;
+  glyph: string;              // stable single-char board symbol, assigned in seat order (A, B, C…)
+  pos: Pos;
+  score: number;
+  emote: string | null;       // currently-showing emote glyph, or null
+  emoteUntilBeat: number;     // beat index at which the emote decays back to null
+  missedBeats: number;        // cumulative beats this round where no action was buffered in time
+  actedLastBeat: boolean;     // did they land an action on the most recent beat resolution (view hint)
+};
+
+export type Phase = "waiting" | "playing" | "intermission";
+
+/**
+ * THE canonical state — the single deterministic source both renders project from.
+ * Kept small on purpose (BOUNDARIES.md state-size ceiling): the static map lives as a
+ * module constant, NOT in state; only what changes is here.
+ */
+export type State = {
+  phase: Phase;
+  round: number;              // 0 while waiting for the first sitter; 1+ once play starts
+  clock: number;              // mirror of ctx.tick — server truth, for the countdown view
+  beat: number;               // beat index within the current phase span
+  phaseStartTick: number;     // anchor: beat = floor((clock - phaseStartTick) / BEAT_TICKS)
+  nextBeatTick: number;       // clock at which the current beat resolves (derived, stored for view)
+  players: Record<string, Player>;
+  spectators: string[];       // connected peers who haven't sat down (the humans watching)
+  pending: Record<string, Dir>;   // buffered action per seated player, latest-wins, cleared each beat
+  pellets: Pos[];             // remaining collectibles this round
+  seatCounter: number;        // monotonic seat index → next glyph, so leaving/rejoining doesn't reuse a letter mid-round
+};