docs(web): interactive color-grid web play — brainstormed design (SSOT)

stdlib-only http.server + single index.html (zero new deps); stepwise
InteractiveSession pinned to SessionRunner by a golden equivalence test;
fairness invariant (live=grid only, review=full disclosure); always-saved
trace compatible with proteus compare.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-06-02-proteus-web-interactive-play-design.md

@@ -0,0 +1,220 @@
+# PROTEUS — Web Interactive Play (color-grid) — Design
+
+> Immutable design (SSOT). Brainstormed 2026-06-02. Implements the spec §12
+> deferred "web UI for human play". Companion to the CP5 human-play / viz design
+> (`2026-06-01-proteus-cp5-viz-humanplay-design.md`).
+
+## 1. Goal & scope
+
+Let a person play the currently-implemented PROTEUS arena (`predator_evade`,
+survival motive) **interactively in a browser** with a **color-grid**
+visualization (not the CLI ASCII view), and **always persist a trace** that is
+schema-identical to LLM/CLI traces so the play feeds `proteus compare` as a
+human baseline.
+
+**Decisions locked during brainstorming:**
+
+- **Purpose = C** — play-centric UX, but every game **always** saves a trace to
+  `runs/*.jsonl` compatible with `proteus compare`.
+- **Config = A** — the browser **start screen** picks scenario / difficulty /
+  seed / play-turns / probe; the server stays up across many games.
+- **Stack = A** — **standard library only** (`http.server`) + a **single static
+  `index.html`** (vanilla JS, no build step, no CDN). **Zero new dependencies**;
+  the `.venv` offline/SDK-free discipline is preserved.
+- **Session driving = Approach 2** — a stepwise `InteractiveSession` (no
+  threads), pinned to `SessionRunner` by a golden equivalence test.
+
+**Out of scope (YAGNI):** multi-user / auth / persistence DB, the deprecated
+`interface/backend` leaderboard (`arena.*`) stack, live truecolor for LLM runs,
+a second scenario (still single-scenario per the current slice), LLM-as-judge.
+
+## 2. Fairness invariant (carried from CP5)
+
+The LLM never sees `reward` / `optimal_action` / `habit_action` live. Therefore:
+
+- **Live view = grid + available actions only** (fair — the human reads what the
+  model reads, just in color instead of ASCII).
+- **Post-game review = full disclosure** — per-turn action vs optimal/habit,
+  reward trajectory, and the 8 metrics, shown only once `outcome` is set.
+
+Breaking this (showing reward/optimal live) would invalidate the human baseline,
+so it is a design-level constraint, not a UI nicety.
+
+## 3. Components
+
+```
+proteus/runtime/interactive.py   # InteractiveSession: state()/step()/finish(); drives engine directly, no threads
+proteus/runtime/session.py       # refactor: extract shared build + per-turn body + finalize helpers (pure extraction)
+proteus/web/__init__.py
+proteus/web/server.py            # stdlib http.server routing + in-memory session registry + JSON I/O
+proteus/web/static/index.html    # single file: color grid + direction buttons/keyboard + start screen + end review
+proteus/web/__main__.py          # `python -m proteus.web` launcher (host/port flags)
+tests/runtime/test_interactive_equivalence.py   # golden: same actions -> SessionTrace == SessionRunner(HumanAgent)
+tests/web/test_server.py         # route handlers called directly (no socket): happy + error paths, serialization
+tests/web/test_import_safety.py  # importing proteus.web pulls no matplotlib / network / provider SDK
+```
+
+New runtime dependencies: **none**. `.venv` unchanged.
+
+### 3.1 Shared extraction (improve-the-code-we-touch)
+
+To avoid divergence between `SessionRunner` and `InteractiveSession`, extract
+the currently-inline logic into shared, pure helpers reused by both:
+
+- `build_session(scenario_name, seed, difficulty, play_turns) -> (scenario, game, cut_frames)`
+  — the body of `SessionRunner._build_and_replay_cut` (build + Cut pre-roll +
+  the "Cut must not terminate" guard).
+- `play_one_turn(scenario, game, agent_action, *, use_probe, ...) -> TurnTrace`
+  — the per-turn body (optimal/habit/positions → apply → `step_reward` →
+  TurnTrace). `SessionRunner` gets the action from `agent.act()`;
+  `InteractiveSession` gets it from the HTTP request. The shared helper takes the
+  **already-decided action** plus the pre-move answer-key/position computation so
+  both callers produce identical TurnTraces.
+- `finalize(scenario_name, seed, difficulty, play_turns, turns, game, scenario,
+  motive_category, model) -> SessionTrace` — the body after the loop
+  (`optimal_rollout` + `compute_metrics` + `SessionTrace` construction).
+
+This is a **pure extraction**: `SessionRunner.run()` becomes
+`build → loop(play_one_turn) → finalize`, with **no behavior change**, pinned by
+the existing 127 tests. `InteractiveSession` calls the same three helpers.
+
+## 4. InteractiveSession (`proteus/runtime/interactive.py`)
+
+Holds `scenario`, `game`, `cut_frames`, `play_turns`, `use_probe`,
+`turns: list[TurnTrace]`, `seed`, `difficulty`, `scenario_name`. No threads.
+
+- `__init__(scenario_name, *, difficulty, seed, play_turns, use_probe=False,
+  motive_category="survival")` → calls `build_session(...)`.
+- `state() -> dict` — the JSON `state` object (see §6). Includes `cut_frames`
+  (int grids) only while `phase == "cut_intro"` / first fetch; `review` only when
+  `done`.
+- `step(action) -> dict` — validates `action ∈ _ACTIONS`; if the game is already
+  terminal raises `SessionFinishedError`; computes pre-move answer keys
+  (optimal/habit) + positions, calls `play_one_turn(...)`, appends the TurnTrace,
+  re-checks terminal; returns the new `state()`.
+- `finish() -> SessionTrace` — requires terminal **or** budget exhausted; calls
+  `finalize(...)`; idempotent (returns the cached trace if already finalized).
+- Helpers: `_grid_to_list(np_grid) -> list[list[int]]` (int cells),
+  `_is_done() -> bool` (`game.eliminated or game.survived or len==play_turns`).
+
+`model` on the emitted trace = `"human"` (HumanAgent parity; no `_provider`).
+
+## 5. HTTP API (stdlib `http.server`, JSON)
+
+| Method / path | Request body | Response | Notes |
+|---|---|---|---|
+| `GET /` | — | `index.html` | single page (text/html) |
+| `GET /config` | — | `{scenarios, difficulties, color_map, default_seed}` | fills start screen; `color_map` sent once (int→hex) |
+| `POST /session` | `{scenario, difficulty, seed, play_turns, probe}` | `{session_id, state}` | builds InteractiveSession; first `state` carries `cut_frames` |
+| `GET /session/{id}` | — | `{state}` | poll / recover current state |
+| `POST /session/{id}/act` | `{action}` | `{state}` | one turn; invalid action → 400 |
+| `POST /session/{id}/finish` | — | `{trace_path, metrics}` | requires done; appends trace + returns metrics |
+
+Routing is a small `BaseHTTPRequestHandler` with a path-prefix dispatch table;
+JSON read via `Content-Length`, written with `application/json`. A module-level
+`dict[str, InteractiveSession]` registry (in-memory, local single-user). Static
+`index.html` read from `proteus/web/static/` (no directory traversal — only the
+one fixed file is served).
+
+## 6. State / data flow
+
+`state` object (live view = **fair**, no reward/optimal):
+
+```json
+{ "phase": "cut_intro|play|done",
+  "turn_idx": 3, "play_turns": 10,
+  "grid": [[0,0,5,...], ...],
+  "cut_frames": [[[...]], ...],
+  "legend": {"5": "#", "6": "A", "8": "B"},
+  "actions": ["up","down","left","right","stay"],
+  "outcome": null,
+  "review": null }
+```
+
+- `grid` = `game.current_grid()` as a 2D `int` list; the client colors each cell
+  via `/config.color_map` (int→hex from `proteus.arc_grid.rendering.COLOR_MAP`).
+- `cut_frames` = the Cut pre-roll as int grids (present on the first state only);
+  the client animates it once (~0.3 s/frame) before live play.
+- `legend` = scenario int→symbol (auxiliary text only; color is primary).
+- `review` (only when `done`): `{turns:[{turn_idx, action, motive_action,
+  habit_action, reward, is_diagnostic, was_congruent}], metrics:{...8...},
+  outcome, trace_path}`.
+
+Flow: `POST /session` → build + Cut → first `state` (with `cut_frames`). Browser
+animates Cut, switches to live. Each `POST /act` → `step(action)` → new `state`.
+On terminal/budget, `state.outcome` is set; the client calls `POST /finish` →
+`finalize` → `append_trace("runs/web_<scenario>_<difficulty>.jsonl")` → returns
+metrics + `trace_path`; client shows the end/review screen.
+
+## 7. Frontend (`proteus/web/static/index.html`, vanilla JS)
+
+- **Start screen**: scenario `<select>`, difficulty radios
+  (easy/medium/hard/expert), seed input (default 42), play-turns input, probe
+  checkbox → "New game".
+- **Play screen**:
+  - **color grid** — CSS-grid of `<div>` cells (or `<canvas>`); each cell filled
+    by `color_map[gridValue]`; cell size auto-fits the band (8×8 … 12×12). Symbols
+    distinguished by color; `legend` shown as small helper text.
+  - **direction input** — on-screen buttons (↑ ↓ ← → · stay) **and** keyboard
+    (WASD + arrow keys). Invalid keys ignored.
+  - status bar: `Turn N / M`, scenario · difficulty · seed.
+  - Cut pre-roll played once at game start.
+- **End screen**: `SURVIVED` / `ELIMINATED` + `review` panel (per-turn action vs
+  optimal/habit, reward, 8 metrics, saved `trace_path`) + "Play again" → start
+  screen.
+
+No build step, no CDN (offline). Inline CSS/JS only.
+
+## 8. Error handling
+
+Structured JSON errors from the stdlib handler:
+
+- unknown `session_id` → **404** `{error}`
+- invalid `action` → **400**
+- `act` on a finished session → **409**
+- unknown scenario / difficulty → **400**
+- `finish` before done → **409**
+- any unexpected handler exception → **500** `{error}` (no stack to client)
+
+## 9. Testing
+
+- `tests/runtime/test_interactive_equivalence.py` — **golden**: a scripted action
+  sequence driven through `InteractiveSession.step` vs the same actions through
+  `SessionRunner` with a scripted `HumanAgent`; assert the two `SessionTrace`
+  objects are field-identical **except `model`** (both `"human"` here anyway) and
+  byte-identical `cut_frames`, per-turn fields, and the 8 metrics.
+- `tests/web/test_server.py` — construct the handler and call its route methods
+  directly (no real socket): `/config`, `/session` (returns id + state with int
+  grid + cut_frames), `/act` happy + invalid-action 400 + finished 409, unknown
+  session 404, `/finish` appends a trace + returns metrics. Assert `state.grid` is
+  `list[list[int]]` and contains no reward/optimal keys (fairness).
+- `tests/web/test_import_safety.py` — importing `proteus.web` / `proteus.web.server`
+  imports no matplotlib, opens no socket, imports no provider SDK.
+- existing **127 tests** stay green — the SessionRunner extraction is a pure
+  refactor pinned by them; assert the suite count is `127 + new`.
+
+## 10. CLI / launch
+
+`python -m proteus.web [--host 127.0.0.1] [--port 8000]` (defaults to localhost
+so it is not exposed off-box). Prints the URL. Optionally wire a `proteus serve`
+subcommand mirroring the other CLI verbs (nice-to-have; the `__main__` launcher
+is the contract).
+
+## 11. Acceptance
+
+- Server starts with **zero new deps** in `.venv`; `GET /` serves the page;
+  a full game (start → several `/act` → terminal → `/finish`) writes a
+  `runs/web_*.jsonl` line that `proteus replay` and `proteus compare` both accept.
+- Live `state` carries **no** reward/optimal/habit (fairness); the end `review`
+  carries them.
+- Golden equivalence test green; full suite `127 + new` passed; offline import
+  invariant guarded.
+
+## 12. Deferred / open
+
+- `proteus serve` subcommand vs `python -m proteus.web` only — pick during plan.
+- Optional Cut-frame animation speed control / skip button (nice-to-have).
+- Multi-session concurrency is supported by the registry but untested beyond one
+  local user (YAGNI for now).
+- Reusing this server for live-LLM spectating (watch a model play in color) is a
+  natural follow-on but out of scope here.