npm - create-siltrun - Versions diffs - 0.1.0 - Mend

create-siltrun 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/index.mjs +98 -0
package/package.json +18 -0
package/templates/mass-grid/AGENTS.md +106 -0
package/templates/mass-grid/README.md +59 -0
package/templates/mass-grid/_gitignore +4 -0
package/templates/mass-grid/index.html +22 -0
package/templates/mass-grid/package.json +31 -0
package/templates/mass-grid/room.test.ts +214 -0
package/templates/mass-grid/room.ts +530 -0
package/templates/mass-grid/skills/authoritative-tick.md +116 -0
package/templates/mass-grid/skills/compact-snapshots.md +110 -0
package/templates/mass-grid/skills/demo-room-lifecycle.md +145 -0
package/templates/mass-grid/skills/genre-lane-mapping.md +88 -0
package/templates/mass-grid/skills/territory-capture.md +115 -0
package/templates/mass-grid/src/Game.tsx +174 -0
package/templates/mass-grid/src/main.tsx +9 -0
package/templates/mass-grid/tsconfig.json +15 -0
package/templates/mass-grid/vite.config.ts +9 -0
package/templates/minimal/README.md +39 -0
package/templates/minimal/_gitignore +4 -0
package/templates/minimal/index.html +15 -0
package/templates/minimal/package.json +30 -0
package/templates/minimal/room.ts +30 -0
package/templates/minimal/src/Game.tsx +71 -0
package/templates/minimal/src/main.tsx +9 -0
package/templates/minimal/tsconfig.json +15 -0
package/templates/minimal/vite.config.ts +7 -0
package/templates/tower-defense/AGENTS.md +132 -0
package/templates/tower-defense/README.md +53 -0
package/templates/tower-defense/_gitignore +4 -0
package/templates/tower-defense/index.html +15 -0
package/templates/tower-defense/package.json +31 -0
package/templates/tower-defense/room.test.ts +159 -0
package/templates/tower-defense/room.ts +321 -0
package/templates/tower-defense/skills/authoritative-tick.md +96 -0
package/templates/tower-defense/skills/demo-room-lifecycle.md +145 -0
package/templates/tower-defense/skills/state-budget.md +79 -0
package/templates/tower-defense/skills/two-lanes.md +66 -0
package/templates/tower-defense/skills/waves-and-timing.md +79 -0
package/templates/tower-defense/src/Game.tsx +227 -0
package/templates/tower-defense/src/main.tsx +9 -0
package/templates/tower-defense/tsconfig.json +15 -0
package/templates/tower-defense/vite.config.ts +7 -0
package/templates/turn-based-grid/AGENTS.md +183 -0
package/templates/turn-based-grid/README.md +72 -0
package/templates/turn-based-grid/_gitignore +4 -0
package/templates/turn-based-grid/index.html +15 -0
package/templates/turn-based-grid/package.json +30 -0
package/templates/turn-based-grid/room.ts +309 -0
package/templates/turn-based-grid/skills/play.md +97 -0
package/templates/turn-based-grid/src/App.tsx +141 -0
package/templates/turn-based-grid/src/GraphicsView.tsx +148 -0
package/templates/turn-based-grid/src/brains.ts +112 -0
package/templates/turn-based-grid/src/main.tsx +8 -0
package/templates/turn-based-grid/src/stubAgent.ts +82 -0
package/templates/turn-based-grid/src/substrate/ascii.ts +87 -0
package/templates/turn-based-grid/src/substrate/map.ts +104 -0
package/templates/turn-based-grid/src/substrate/types.ts +59 -0
package/templates/turn-based-grid/src/view.ts +94 -0
package/templates/turn-based-grid/tsconfig.json +15 -0
package/templates/turn-based-grid/vite.config.ts +7 -0

package/templates/turn-based-grid/index.html ADDED Viewed

@@ -0,0 +1,15 @@
+<!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>turn-based grid — agent substrate</title>
+  </head>
+  <body style="margin: 0; background: #0b0b0c">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/turn-based-grid/package.json ADDED Viewed

@@ -0,0 +1,30 @@
+{
+  "name": "turn-based-grid-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",
+    "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/turn-based-grid/room.ts ADDED Viewed

@@ -0,0 +1,309 @@
+// room.ts — THE AUTHORITY. This contract runs server-side inside Silt's deterministic
+// realm; it is the single source of truth the whole world projects from. Agents submit
+// intent on the reliable lane; this tick() decides what actually happens; every peer
+// (playing agents + spectating humans) receives the resulting State each tick.
+//
+// THE TICK / BEAT MODEL (DIG-725, the load-bearing decision) ─────────────────────────
+//
+//   • The relay clock is a constant 60Hz and never pauses while ≥1 peer is present.
+//     We do NOT fight it. On top of it we quantize turns into BEATS of BEAT_TICKS ticks.
+//   • Agents buffer at most ONE action per beat (reliable lane, latest-wins within the
+//     window — you may revise until the beat lands). We hold the buffer in `state.pending`.
+//   • At the beat boundary, ALL buffered actions resolve SIMULTANEOUSLY from one snapshot,
+//     with symmetric conflict rules (two movers into one cell → both bounce; no initiative
+//     order to explain). Validation is at RESOLVE time, so agents act on ~1-beat-stale info.
+//   • An agent still thinking when the boundary lands has nothing buffered → it idles that
+//     beat (`missedBeats`++). The too-slow failure is visible and is the fun.
+//   • Emotes are EXEMPT from beat-buffering: they apply on their arrival tick (still
+//     deterministic — ordered inputs) and decay after EMOTE_DECAY_BEATS. This keeps a 4s
+//     beat alive for spectators without touching turn fairness.
+//
+// Determinism: this file touches only ctx.tick and ctx.random. No Date, no Math.random,
+// no wall clock — the realm would throw on ambient authority inside tick() anyway.
+import type { Room, Ctx } from "@siltrun/room";
+import type { State, Cmd, Dir, Player, Pos } from "./src/substrate/types.ts";
+import {
+  BEAT_TICKS,
+  ROUND_BEATS,
+  INTERMISSION_BEATS,
+  EMOTE_DECAY_BEATS,
+  PELLET_COUNT,
+  FLOOR_CELLS,
+  SPAWNS,
+  isFloor,
+  step,
+  cellKey,
+  samePos,
+  glyphFor,
+  isEmoteGlyph,
+} from "./src/substrate/map.ts";
+// ── initial (empty, waiting) state ──
+function freshState(): State {
+  return {
+    phase: "waiting",
+    round: 0,
+    clock: 0,
+    beat: 0,
+    phaseStartTick: 0,
+    nextBeatTick: BEAT_TICKS,
+    players: {},
+    spectators: [],
+    pending: {},
+    pellets: [],
+    seatCounter: 0,
+  };
+}
+// ── deterministic pellet spawn: pick PELLET_COUNT distinct floor cells not under a player ──
+function spawnPellets(state: State, ctx: Ctx): Pos[] {
+  const occupied = new Set<string>();
+  for (const id in state.players) occupied.add(cellKey(state.players[id].pos));
+  const candidates = FLOOR_CELLS.filter((c) => !occupied.has(cellKey(c)));
+  // Fisher–Yates with ctx.random (deterministic: hash(seed, tick, draw)); take the first N.
+  const pool = candidates.slice();
+  for (let i = pool.length - 1; i > 0; i--) {
+    const j = Math.floor(ctx.random() * (i + 1));
+    const t = pool[i];
+    pool[i] = pool[j];
+    pool[j] = t;
+  }
+  return pool.slice(0, Math.min(PELLET_COUNT, pool.length));
+}
+// ── seat a spectator as a player, assigning a spawn point + stable glyph ──
+function seat(state: State, id: string): void {
+  if (state.players[id]) return; // already seated
+  const seatIndex = state.seatCounter++;
+  const spawn = SPAWNS[seatIndex % SPAWNS.length];
+  // If the natural spawn is taken, walk floor cells for the first free one (deterministic order).
+  let pos: Pos = spawn;
+  const taken = new Set<string>();
+  for (const pid in state.players) taken.add(cellKey(state.players[pid].pos));
+  if (taken.has(cellKey(pos))) {
+    pos = FLOOR_CELLS.find((c) => !taken.has(cellKey(c))) ?? spawn;
+  }
+  const player: Player = {
+    id,
+    glyph: glyphFor(seatIndex),
+    pos: { x: pos.x, y: pos.y },
+    score: 0,
+    emote: null,
+    emoteUntilBeat: 0,
+    missedBeats: 0,
+    actedLastBeat: false,
+  };
+  state.players[id] = player;
+  state.spectators = state.spectators.filter((s) => s !== id);
+}
+function unseat(state: State, id: string): void {
+  delete state.players[id];
+  delete state.pending[id];
+}
+// ── start a fresh round: place seated players at spawns, spawn pellets, reset the beat span ──
+function startRound(state: State, ctx: Ctx): void {
+  state.round += 1;
+  state.phase = "playing";
+  state.phaseStartTick = ctx.tick;
+  state.beat = 0;
+  state.nextBeatTick = ctx.tick + BEAT_TICKS;
+  // Re-home every seated player to a spawn and clear round-scoped counters.
+  let i = 0;
+  for (const id in state.players) {
+    const p = state.players[id];
+    const spawn = SPAWNS[i % SPAWNS.length];
+    p.pos = { x: spawn.x, y: spawn.y };
+    p.score = 0;
+    p.missedBeats = 0;
+    p.actedLastBeat = false;
+    p.emote = null;
+    p.emoteUntilBeat = 0;
+    i++;
+  }
+  state.pending = {};
+  state.pellets = spawnPellets(state, ctx);
+}
+function enterIntermission(state: State, ctx: Ctx): void {
+  state.phase = "intermission";
+  state.phaseStartTick = ctx.tick;
+  state.beat = 0;
+  state.nextBeatTick = ctx.tick + BEAT_TICKS;
+  state.pending = {};
+}
+// ── the simultaneous, symmetric beat resolution ──
+//
+// Everyone resolves from the SAME pre-move snapshot. A player moves iff its target is
+// floor AND not the current cell of a player who is staying AND not targeted by any
+// other mover. Any contention → bounce (stay). No initiative, order-independent, fair.
+function resolveBeat(state: State): void {
+  const ids = Object.keys(state.players);
+  const before: Record<string, Pos> = {};
+  const intended: Record<string, Pos> = {};
+  for (const id of ids) {
+    const p = state.players[id];
+    before[id] = { x: p.pos.x, y: p.pos.y };
+  }
+  // 1. intended target for each seated player (buffered move, or stay).
+  for (const id of ids) {
+    const move: Dir = state.pending[id] ?? "stay";
+    const target = move === "stay" ? before[id] : step(before[id], move);
+    // wall / out-of-bounds → bounce to origin.
+    intended[id] = isFloor(target.x, target.y) ? target : before[id];
+  }
+  // 2. cells occupied by a player who is NOT moving this beat (stayers block).
+  const stayerCells = new Set<string>();
+  for (const id of ids) {
+    if (samePos(intended[id], before[id])) stayerCells.add(cellKey(before[id]));
+  }
+  // 3. count how many movers target each destination cell (to detect head-on contention).
+  const targetCount = new Map<string, number>();
+  for (const id of ids) {
+    if (samePos(intended[id], before[id])) continue; // stayers don't contend
+    const k = cellKey(intended[id]);
+    targetCount.set(k, (targetCount.get(k) ?? 0) + 1);
+  }
+  // 4. grant a move only if its target is uncontended by other movers AND not a stayer's cell.
+  const granted: Record<string, boolean> = {};
+  for (const id of ids) {
+    if (samePos(intended[id], before[id])) { granted[id] = false; continue; }
+    const k = cellKey(intended[id]);
+    const contested = (targetCount.get(k) ?? 0) > 1 || stayerCells.has(k);
+    granted[id] = !contested;
+  }
+  // 5. apply, mark acted/missed, collect pellets.
+  for (const id of ids) {
+    const p = state.players[id];
+    const buffered = state.pending[id] != null;
+    if (buffered && p.missedBeats >= 0) p.actedLastBeat = true;
+    if (!buffered) { p.missedBeats += 1; p.actedLastBeat = false; }
+    if (granted[id]) p.pos = { x: intended[id].x, y: intended[id].y };
+    // pellet pickup on the resulting cell.
+    const here = cellKey(p.pos);
+    const idx = state.pellets.findIndex((pel) => cellKey(pel) === here);
+    if (idx !== -1) {
+      state.pellets.splice(idx, 1);
+      p.score += 1;
+    }
+  }
+  state.pending = {};
+}
+function decayEmotes(state: State): void {
+  for (const id in state.players) {
+    const p = state.players[id];
+    if (p.emote && state.beat >= p.emoteUntilBeat) p.emote = null;
+  }
+}
+// ── the contract ──
+export default {
+  tick(state = freshState(), inputs, ctx): State {
+    state.clock = ctx.tick;
+    // 1) fold in everything that happened since last tick (deterministic order:
+    //    joins → leaves → reliable events → datagram inputs; we use joins/leaves/events).
+    for (const ev of inputs) {
+      if (ev.kind === "join") {
+        if (!state.players[ev.id] && !state.spectators.includes(ev.id)) {
+          state.spectators.push(ev.id);
+        }
+        continue;
+      }
+      if (ev.kind === "leave") {
+        unseat(state, ev.id);
+        state.spectators = state.spectators.filter((s) => s !== ev.id);
+        continue;
+      }
+      if (ev.kind === "event") {
+        const msg = ev.data as Cmd;
+        if (!msg || typeof msg !== "object") continue;
+        switch (msg.t) {
+          case "sit":
+            seat(state, ev.from);
+            break;
+          case "stand":
+            unseat(state, ev.from);
+            if (!state.spectators.includes(ev.from)) state.spectators.push(ev.from);
+            break;
+          case "act":
+            // buffer latest-wins; only seated players can act, only during play.
+            if (state.players[ev.from] && state.phase === "playing") {
+              const m = msg.move;
+              if (m === "up" || m === "down" || m === "left" || m === "right" || m === "stay") {
+                state.pending[ev.from] = m;
+              }
+            }
+            break;
+          case "emote":
+            // applies immediately (exempt from beat-buffering), decays after N beats.
+            if (state.players[ev.from] && isEmoteGlyph(msg.glyph)) {
+              const p = state.players[ev.from];
+              p.emote = msg.glyph;
+              p.emoteUntilBeat = state.beat + EMOTE_DECAY_BEATS;
+            }
+            break;
+        }
+        continue;
+      }
+      // ev.kind === "input" (datagram lane) is unused by this genre — turns ride reliable.
+    }
+    const seatedCount = Object.keys(state.players).length;
+    // 2) lifecycle: waiting → playing → intermission → (playing | waiting), agent-population-based.
+    if (state.phase === "waiting") {
+      if (seatedCount > 0) startRound(state, ctx);
+      state.nextBeatTick = state.phaseStartTick + BEAT_TICKS; // keep view honest while waiting
+      return state;
+    }
+    // 3) beat boundary crossing. `beat` advances whenever the clock passes nextBeatTick.
+    //    A pause/resume across an empty room can't desync: everything is anchored to
+    //    phaseStartTick, which we reset on every phase entry.
+    if (ctx.tick >= state.nextBeatTick) {
+      const elapsedBeats = Math.floor((ctx.tick - state.phaseStartTick) / BEAT_TICKS);
+      if (state.phase === "playing") {
+        resolveBeat(state);
+        state.beat = elapsedBeats;
+        decayEmotes(state);
+        state.nextBeatTick = state.phaseStartTick + (elapsedBeats + 1) * BEAT_TICKS;
+        // round over? (all pellets gone also ends it early)
+        if (state.beat >= ROUND_BEATS || state.pellets.length === 0) {
+          enterIntermission(state, ctx);
+        }
+      } else {
+        // intermission: just advance the beat counter; roll to next round or back to waiting.
+        state.beat = elapsedBeats;
+        state.nextBeatTick = state.phaseStartTick + (elapsedBeats + 1) * BEAT_TICKS;
+        if (state.beat >= INTERMISSION_BEATS) {
+          if (Object.keys(state.players).length > 0) startRound(state, ctx);
+          else {
+            const s = freshState();
+            s.clock = ctx.tick;
+            s.round = state.round;
+            s.spectators = state.spectators;
+            s.phaseStartTick = ctx.tick;
+            s.nextBeatTick = ctx.tick + BEAT_TICKS;
+            return s;
+          }
+        }
+      }
+    }
+    return state;
+  },
+} satisfies Room<State, Cmd>;

package/templates/turn-based-grid/skills/play.md ADDED Viewed

@@ -0,0 +1,97 @@
+# Skill: play the turn-based grid
+A hands-on recipe for turning the briefing in [`../AGENTS.md`](../AGENTS.md) into a
+**working brain** — an agent that perceives the ASCII grid, decides a move, and acts before
+the beat deadline. Agent-agnostic: any agent runtime that can (a) receive the rendered ASCII
+and (b) send a reliable-lane JSON message can use this.
+Read `AGENTS.md` first for the world model, the tick/beat model, the action API, and the
+symbol/emote tables. This file is the *how*.
+---
+## The loop
+```
+connect
+send { "t": "sit" }                     # once — become a player
+loop forever:
+    ascii   = <latest rendered perception>   # your only input
+    deadline = ticks-until-beat (from the status line)
+    move    = decide(ascii)              # keep this FAST — you have a deadline
+    send { "t": "act", "move": move }    # reliable lane; latest-wins within the beat
+```
+Two rules that matter more than cleverness:
+1. **Beat the deadline.** The `beat resolves in: N ticks` line is a countdown. If `decide`
+   takes longer than that, you buffer nothing and miss the beat (your piece idles, your
+   `missed` count climbs). A rough move on time beats a perfect move that's late.
+2. **You may revise.** Sent a move, then realized a better one before the beat landed? Send
+   again — latest-wins. Cheap insurance: send an early rough move, refine if time allows.
+---
+## Step 1 — parse the ASCII into something you can reason over
+The perception is text. Turn it into structure:
+- Split into the grid rows (the block of `#./*`-and-letters lines) and the status lines.
+- Find **your own** glyph from the `you are: X` status line.
+- Scan the grid: record wall cells (`#`), pellet cells (`*`), your position (your glyph),
+  and other players (other letters).
+(A reference parser is in [`../src/view.ts`](../src/view.ts) — `readView(ascii)` returns
+`{ self, pellets, others, isWall }`, all recovered from the string alone.)
+## Step 2 — decide a move
+The simplest competent brain: **walk toward the nearest pellet.** Breadth-first search over
+floor cells from your position; the first step of the shortest path to the closest pellet is
+your move. If no pellet is reachable, take any legal step (or `stay`).
+**Directions are grid-relative** (see AGENTS.md §1): `up` = row − 1 (toward the top), `down`
+= row + 1, `left`/`right` = column ∓ 1. **Treat other players' cells as blocked when you
+path** — but only for *this* beat: pieces move simultaneously, so a cell occupied now is
+often free next beat. Re-plan each beat from fresh perception rather than committing to a
+route around a piece that will have moved.
+```
+decide(ascii):
+    v = parse(ascii)
+    if v.self is null: return "stay"          # not seated / spectating
+    target = nearest reachable pellet (BFS over non-wall, non-occupied cells)
+    if target: return first-step-direction toward it
+    else:      return any non-wall direction, or "stay"
+```
+(Reference: `stepTowardNearestPellet(view)` in `../src/view.ts`, used by the `greedy` brain
+in [`../src/brains.ts`](../src/brains.ts).)
+## Step 3 — (optional) use the emote channel
+You have no chat, but you can flash one glyph (`! ? + - ^ x`) that others see for a couple
+of beats. Send `{ "t": "emote", "glyph": "!" }` to signal. Emotes don't consume your turn —
+they apply immediately. Convention gives the glyphs meaning (see `AGENTS.md` §4); the
+substrate just delivers, shows, and decays them.
+---
+## What "a good brain" looks like
+- **Never misses on a clear board.** If a pellet is reachable and you have time, you should
+  be moving toward it every beat. A climbing `missed` count means your `decide` is too slow
+  or you're not sending in time.
+- **Handles contention.** When another piece contests your target cell, both bounce. Notice
+  repeated bounces and try a different route rather than shoving into the same wall.
+- **Degrades gracefully.** No reachable pellet, or ambiguous perception? Return `stay` — a
+  deliberate, legal non-move — never nothing.
+## The bar this template sets
+Four scripted brains ship as proof the substrate is playable from the ASCII alone —
+`greedy` (this recipe), `random`, `chatty` (adds emotes), and `slow` (deliberately misses
+its deadline, to show the stutter). Each perceives **only** the rendered ASCII, never the
+server's state object. That's the whole claim: if a brain can play from the text, the
+agent-facing projection is a sufficient interface — which is what a real agent connection
+(over MCP) will target.

package/templates/turn-based-grid/src/App.tsx ADDED Viewed

@@ -0,0 +1,141 @@
+// App.tsx — the SPECTATOR. Humans watch; they never take a seat (the demo variant is
+// agent-play / human-spectate). This tab joins as a spectator, renders the live state,
+// and — for local demoing — launches in-page stub agents named in the URL:
+//
+//     http://localhost:5173/?agents=greedy,slow,chatty
+//
+// Each stub is its own real client connection (see stubAgent.ts). Ugly-e2e stage: the
+// ASCII pane + scoreboard, driven by real agents. The graphics view lands in polish.
+import { useEffect, useRef, useState } from "react";
+import { useRoom } from "@siltrun/react";
+import type { State } from "./substrate/types.ts";
+import { renderAscii, SYMBOLS } from "./substrate/ascii.ts";
+import { GraphicsView } from "./GraphicsView.tsx";
+import { BRAINS } from "./brains.ts";
+import { runStubAgent, type StubHandle } from "./stubAgent.ts";
+// Defaults to the standard siltrun dev room-info port. Override for local multi-room
+// setups with ?room=<port> or ?room=<full-url> (used by the monorepo verify loop).
+const ROOM_URL = (() => {
+  const p = new URLSearchParams(location.search).get("room");
+  if (!p) return "http://localhost:4000";
+  return /^\d+$/.test(p) ? `http://localhost:${p}` : p;
+})();
+const SPECTATOR_ID = "spectator-" + Math.random().toString(36).slice(2, 8);
+function useStubAgents() {
+  const started = useRef(false);
+  const [names, setNames] = useState<string[]>([]);
+  useEffect(() => {
+    if (started.current) return;
+    started.current = true;
+    const param = new URLSearchParams(location.search).get("agents");
+    if (!param) return;
+    const requested = param.split(",").map((s) => s.trim()).filter(Boolean);
+    const handles: Promise<StubHandle>[] = [];
+    const launched: string[] = [];
+    // A per-page-load nonce keeps stub ids unique across reloads — otherwise a fresh
+    // "greedy-0" collides with the previous load's still-closing "greedy-0" and the two
+    // same-id sessions thrash (the documented concurrent-same-id pathology). Real agents
+    // carry unique identities; the stubs must too.
+    const nonce = Math.random().toString(36).slice(2, 6);
+    requested.forEach((name, i) => {
+      const make = BRAINS[name];
+      if (!make) return;
+      const id = `${name}-${nonce}${i}`;
+      launched.push(name);
+      handles.push(runStubAgent({ url: ROOM_URL, id, brain: make() }));
+    });
+    setNames(launched);
+    return () => {
+      Promise.all(handles).then((hs) => hs.forEach((h) => h.stop()));
+    };
+  }, []);
+  return names;
+}
+export function App() {
+  const { state, status, error } = useRoom<State>(ROOM_URL, { id: SPECTATOR_ID });
+  const agents = useStubAgents();
+  const [showAscii, setShowAscii] = useState(true);
+  if (status === "failed") {
+    return <pre style={box}>connection failed: {String(error)} — is `npm run dev` running?</pre>;
+  }
+  if (!state) return <pre style={box}>{status === "reconnecting" ? "reconnecting…" : "joining…"}</pre>;
+  const players = Object.values(state.players).sort((a, b) => b.score - a.score);
+  const brainOf = (id: string) => id.split("-")[0];
+  return (
+    <div style={{ display: "flex", gap: 28, padding: 24, fontFamily: "ui-monospace, monospace", color: "#eae7de", background: "#0b0b0d", minHeight: "100vh", alignItems: "flex-start" }}>
+      {/* HUMAN VIEW — watch the agents play */}
+      <div>
+        <div style={{ color: "#7e837a", marginBottom: 8 }}>
+          human view — watch the agents play · phase <b style={{ color: "#cfc9bc" }}>{state.phase}</b> · round {state.round} · beat {state.beat}
+        </div>
+        <GraphicsView state={state} />
+        {agents.length > 0 && (
+          <div style={{ color: "#7e837a", marginTop: 10, fontSize: 13 }}>stub agents: {agents.join(", ")}</div>
+        )}
+      </div>
+      {/* AGENT VIEW — the exact ASCII an agent perceives (toggle) */}
+      {showAscii && (
+        <div>
+          <div style={{ color: "#7e837a", marginBottom: 8, display: "flex", gap: 10, alignItems: "center" }}>
+            agent view — the exact ASCII an agent reads
+            <button onClick={() => setShowAscii(false)} style={btn}>hide</button>
+          </div>
+          <pre style={{ ...box, fontSize: 18, lineHeight: 1.18 }}>{renderAscii(state)}</pre>
+        </div>
+      )}
+      <div style={{ minWidth: 280 }}>
+        {!showAscii && (
+          <button onClick={() => setShowAscii(true)} style={{ ...btn, marginBottom: 12 }}>show agent (ASCII) view</button>
+        )}
+        <div style={{ color: "#7e837a", marginBottom: 8 }}>scoreboard</div>
+        <table style={{ borderCollapse: "collapse", fontSize: 14, width: "100%" }}>
+          <thead>
+            <tr style={{ color: "#7e837a", textAlign: "left" }}>
+              <th style={cell}>#</th><th style={cell}>who</th><th style={cell}>score</th><th style={cell}>missed</th><th style={cell}>emote</th>
+            </tr>
+          </thead>
+          <tbody>
+            {players.map((p) => (
+              <tr key={p.id}>
+                <td style={cell}><b style={{ color: "#cfc9bc" }}>{p.glyph}</b></td>
+                <td style={cell}>{brainOf(p.id)}</td>
+                <td style={cell}>{p.score}</td>
+                <td style={{ ...cell, color: p.missedBeats > 0 ? "#a65a2e" : "#3a3a3d", fontWeight: p.missedBeats > 0 ? 700 : 400 }}>{p.missedBeats}</td>
+                <td style={{ ...cell, color: p.emote ? "#cfc9bc" : "#3a3a3d", fontSize: 16 }}>{p.emote ?? "·"}</td>
+              </tr>
+            ))}
+            {players.length === 0 && (
+              <tr><td style={cell} colSpan={5}>no agents seated — waiting…</td></tr>
+            )}
+          </tbody>
+        </table>
+        <div style={{ color: "#7e837a", margin: "20px 0 8px" }}>symbol table</div>
+        <table style={{ borderCollapse: "collapse", fontSize: 13 }}>
+          <tbody>
+            {SYMBOLS.map((s) => (
+              <tr key={s.glyph}><td style={{ ...cell, color: "#cfc9bc" }}>{s.glyph}</td><td style={cell}>{s.meaning}</td></tr>
+            ))}
+          </tbody>
+        </table>
+        <div style={{ color: "#7e837a", marginTop: 8, fontSize: 12 }}>watching: {state.spectators.length}</div>
+      </div>
+    </div>
+  );
+}
+const box: React.CSSProperties = { background: "#121214", padding: 16, borderRadius: 8, margin: 0 };
+const cell: React.CSSProperties = { padding: "3px 10px 3px 0", borderBottom: "1px solid #26262a" };
+const btn: React.CSSProperties = {
+  background: "#1c1c1f", color: "#cfc9bc", border: "1px solid #3a3a3d",
+  borderRadius: 6, padding: "3px 10px", fontSize: 12, cursor: "pointer", fontFamily: "ui-monospace, monospace",
+};