feat: generalize peek_dev harness as scripts/tui_dev for any TUI iteration

The snapshot/live harness was already capable of rendering any
ConsoleEmitter state — only the fixtures and naming pinned it to the
peek panel. Rename the directory and add an EVENT_SCENARIOS dict with
non-peek fixtures so the harness can drive iteration result lines, run
summaries, error logs, and markdown rendering through the same
PNG-snapshot loop.

Renames:
- scripts/peek_dev/                        → scripts/tui_dev/
- docs/contributing/peek-dev-harness.md    → tui-dev-harness.md

snapshot.py grows a `_snapshot_event_sequence` driver that takes a
list of (EventType, dict) tuples and emits them through the recording
console — used for any TUI state that doesn't need direct access to
the panel internals. Five new fixtures land in fixtures.py:

- 10_iteration_success      (happy path + markdown result)
- 11_iteration_failed       (red failure + log file path)
- 12_iteration_timeout      (yellow timeout branch)
- 13_run_summary_mixed      (multi-iteration summary)
- 14_log_error              (error log + traceback)

CLAUDE.md gets a new "Iterating on the TUI" section pointing at the
harness as the primary visual-design loop. The docs page is rewritten
to describe both fixture flavours and explain when to add each.

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

Author: 2 people

.gitignore

@@ -14,4 +14,6 @@ mess/
 .agents/
 .DS_Store
 .coverage
-.ralphify/
+.ralphify/
+scripts/tui_dev/output/
+

CLAUDE.md

@@ -59,6 +59,10 @@ A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-l
   - `README.md` — keep short and high-level. Update only when the change affects the quickstart, install, or core concepts.
   - `CHANGELOG.md` — add an entry for every release.
 
+## Iterating on the TUI
+
+Editing `_console_emitter.py` and need to see what the terminal output looks like? Run `./scripts/tui_dev/run.sh` to regenerate PNG snapshots in `scripts/tui_dev/output/`, then `Read` them in your editor. The harness covers both the live peek panel *and* general terminal states (iteration result lines, run summaries, error logs, markdown results) — add a fixture to `scripts/tui_dev/fixtures.py` for any new state worth iterating on. See `docs/contributing/tui-dev-harness.md` for details.
+
 ## Boundaries
 
 ### Always Do

docs/contributing/tui-dev-harness.md

@@ -0,0 +1,148 @@
+# TUI dev harness
+
+The `ralph` CLI's terminal output — the iteration headers, peek panel,
+result lines, run summary, and error logs — is rendered by
+`ConsoleEmitter` in `src/ralphify/_console_emitter.py`. Iterating on
+that visual design needs visual feedback, but coding agents running in
+a non-interactive environment can't watch a live terminal. The harness
+at `scripts/tui_dev/` solves this — it generates PNG snapshots of any
+`ConsoleEmitter` state that any agent (or human) can view.
+
+## Usage
+
+```bash
+./scripts/tui_dev/run.sh            # regenerate everything (~15s)
+./scripts/tui_dev/run.sh snapshot   # fixture-driven mode only
+./scripts/tui_dev/run.sh live       # real ralph run via pty only
+```
+
+Outputs land in `scripts/tui_dev/output/*.png` (gitignored). The
+iteration cycle is: edit `_console_emitter.py` → rerun the harness →
+view the PNGs → repeat.
+
+## Modes
+
+### Snapshot mode (`snapshot.py`)
+
+Drives the real `ConsoleEmitter` in-process through canned fixtures
+defined in `fixtures.py`. Two flavours of fixture are supported:
+
+#### Peek-panel scenarios (`ALL_SCENARIOS`)
+
+Each scenario is a list of parsed Claude stream-json dicts that get
+fed through a real `_IterationPanel`. Used for iterating on the live
+activity feed (the bordered panel shown when peek is on).
+
+| Scenario | What it shows |
+|---|---|
+| `01_empty` | Peek toggled on, zero scroll lines yet |
+| `02_single_tool` | First tool call after peek turns on |
+| `03_mixed_activity` | Thinking, tool calls, text preview — typical mid-iteration |
+| `04_scroll_buffer_full` | 17 tool calls — exceeds the visible scroll cap |
+| `05_heavy_tokens` | 1M+ input tokens, exercising the `M` unit in the token formatter |
+| `06_rate_limit` | Rate-limit event mixed with normal activity |
+| `07_tool_error` | Red `tool_result` error branch |
+| `08_raw_spinner` | `_IterationSpinner` path for non-Claude agents |
+| `09_peek_off` | Peek toggled off mid-iteration — verifies the buffer persists |
+
+#### Event-sequence scenarios (`EVENT_SCENARIOS`)
+
+Each scenario is a list of `(EventType, dict)` tuples that get fed
+through the real emitter. Whatever the emitter prints to the recording
+console is what ends up in the snapshot. Used for iterating on
+**anything that isn't the peek panel** — iteration result lines, run
+summaries, error logs, markdown result rendering.
+
+| Scenario | What it shows |
+|---|---|
+| `10_iteration_success` | Happy path: green checkmark + markdown result |
+| `11_iteration_failed` | Red failure with exit code and log file path |
+| `12_iteration_timeout` | Yellow timeout branch |
+| `13_run_summary_mixed` | Multi-iteration run with success / failure / timeout |
+| `14_log_error` | Error log message with traceback |
+
+Snapshot mode subclasses `ConsoleEmitter` to disable `Live.start`, so
+each scenario produces exactly one frozen render. Rendering goes
+through Rich's own `save_svg` → headless Chrome → PNG — no lossy
+intermediaries, and colors/fonts match what Rich emits to the terminal.
+
+Fast (~15s total), deterministic, no subprocess — this is the mode to
+use for most design work.
+
+### Live mode (`live.py`)
+
+Maximum fidelity. Spawns the real `ralph` binary in a pseudo-terminal
+via `pty.openpty()`, with `fake_bin/claude` (a Python script named
+`claude` so `_is_claude_command` treats it as a structured agent)
+emitting realistic stream-json on a 1.8s cadence. The capture
+deliberately freezes at t=9s so the `Live` panel is still
+mid-iteration, then feeds the raw ANSI byte stream through
+[`pyte`](https://github.com/selectel/pyte) — a pure-Python terminal
+emulator — to reduce cursor moves and clears to a stable screen grid.
+That grid is then rendered through Rich for the final SVG → PNG.
+
+pyte is installed on-demand via `uv run --with pyte` (not a project
+dep).
+
+## Adding a new scenario
+
+### Peek-panel scenario
+
+Append a builder function to `scripts/tui_dev/fixtures.py` and
+register it in `ALL_SCENARIOS`:
+
+```python
+def scenario_my_new_case() -> list[dict[str, Any]]:
+    return [
+        system_init(),
+        assistant_tool_use("Bash", {"command": "pytest -x"}, input_tokens=1200),
+        # ...
+    ]
+
+
+ALL_SCENARIOS = {
+    # ...
+    "15_my_new_case": scenario_my_new_case(),
+}
+```
+
+### Event-sequence scenario
+
+Append an events builder and register it in `EVENT_SCENARIOS`:
+
+```python
+def events_my_new_case() -> list[tuple[EventType, dict[str, Any]]]:
+    return [
+        _run_started("demo / 16_my_new_case"),
+        (EventType.ITERATION_STARTED, {"iteration": 1}),
+        (EventType.ITERATION_COMPLETED, {
+            "iteration": 1,
+            "detail": "completed (5s)",
+            "log_file": None,
+            "result_text": "all good",
+        }),
+    ]
+
+
+EVENT_SCENARIOS = {
+    # ...
+    "16_my_new_case": events_my_new_case(),
+}
+```
+
+The next `./scripts/tui_dev/run.sh snapshot` will produce
+`scripts/tui_dev/output/16_my_new_case.png`.
+
+## Files
+
+```
+scripts/tui_dev/
+├── run.sh              # one-command launcher
+├── snapshot.py         # mode A: in-process ConsoleEmitter + fixtures
+├── live.py             # mode B: real ralph run via pty + pyte
+├── fixtures.py         # canned event sequences (peek + general)
+├── render.py           # shared SVG → PNG via headless Chrome
+├── fake_bin/claude     # stub Claude agent used by live mode
+├── demo_ralph/RALPH.md # minimal ralph dir used by live mode
+└── output/             # PNG + SVG snapshots (gitignored)
+```

mkdocs.yml

@@ -139,3 +139,4 @@ nav:
   - Contributing:
     - contributing/index.md
     - Codebase Map: contributing/codebase-map.md
+    - TUI Dev Harness: contributing/tui-dev-harness.md

scripts/tui_dev/demo_ralph/RALPH.md

@@ -0,0 +1,4 @@
+---
+agent: claude
+---
+refine the iteration panel layout in _console_emitter.py and keep tests green

scripts/tui_dev/fake_bin/claude

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Stub Claude agent for peek dev harness.
+
+Named ``claude`` (no extension) on purpose — ralphify's ``_is_claude_command``
+matches on ``Path(parts[0]).stem == "claude"``, so placing this file on PATH
+with that name makes ralphify treat it as a structured stream-json agent.
+
+It ignores the ``--output-format stream-json --verbose`` flags that
+ralphify appends, drains the prompt from stdin (prompts can be large, so
+we must actually read them to avoid blocking ralphify's writer thread),
+and emits a realistic sequence of Claude stream-json events on stdout
+with small delays so peek has time to render intermediate states.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import time
+
+EVENTS = [
+    {"type": "system", "subtype": "init", "model": "claude-opus-4-6"},
+    # Thinking
+    {
+        "type": "assistant",
+        "message": {"content": [{"type": "thinking", "thinking": "..."}]},
+    },
+    # Read file
+    {
+        "type": "assistant",
+        "message": {
+            "content": [
+                {
+                    "type": "tool_use",
+                    "name": "Read",
+                    "input": {
+                        "file_path": "/Users/kasper/Code/ralphify/src/ralphify/_console_emitter.py"
+                    },
+                }
+            ],
+            "usage": {
+                "input_tokens": 2_800,
+                "output_tokens": 120,
+                "cache_read_input_tokens": 16_500,
+            },
+        },
+    },
+    # Grep
+    {
+        "type": "assistant",
+        "message": {
+            "content": [
+                {
+                    "type": "tool_use",
+                    "name": "Grep",
+                    "input": {"pattern": "_IterationPanel"},
+                }
+            ],
+            "usage": {
+                "input_tokens": 3_100,
+                "output_tokens": 210,
+                "cache_read_input_tokens": 16_500,
+            },
+        },
+    },
+    # Text preview
+    {
+        "type": "assistant",
+        "message": {
+            "content": [
+                {
+                    "type": "text",
+                    "text": "I can see the iteration panel structure — let me refine the spacing.",
+                }
+            ],
+            "usage": {
+                "input_tokens": 3_250,
+                "output_tokens": 340,
+                "cache_read_input_tokens": 16_500,
+            },
+        },
+    },
+    # Edit
+    {
+        "type": "assistant",
+        "message": {
+            "content": [
+                {
+                    "type": "tool_use",
+                    "name": "Edit",
+                    "input": {
+                        "file_path": "/Users/kasper/Code/ralphify/src/ralphify/_console_emitter.py"
+                    },
+                }
+            ],
+            "usage": {
+                "input_tokens": 3_500,
+                "output_tokens": 480,
+                "cache_read_input_tokens": 16_500,
+            },
+        },
+    },
+    # Bash
+    {
+        "type": "assistant",
+        "message": {
+            "content": [
+                {
+                    "type": "tool_use",
+                    "name": "Bash",
+                    "input": {
+                        "command": "uv run pytest tests/test_console_emitter.py -x"
+                    },
+                }
+            ],
+            "usage": {
+                "input_tokens": 3_750,
+                "output_tokens": 560,
+                "cache_read_input_tokens": 16_500,
+            },
+        },
+    },
+    # Final result
+    {
+        "type": "result",
+        "result": "Refined the iteration panel spacing; all tests pass.",
+    },
+]
+
+
+def _drain_stdin() -> None:
+    """Read and discard the prompt from stdin.
+
+    Ralphify writes the prompt on a background thread and closes stdin;
+    if we never read it, the writer thread blocks on a full pipe buffer
+    for large prompts.  Daemon thread so the process can exit once all
+    events are flushed to stdout.
+    """
+    try:
+        sys.stdin.read()
+    except Exception:
+        pass
+
+
+def main() -> int:
+    drainer = threading.Thread(target=_drain_stdin, daemon=True)
+    drainer.start()
+
+    # Slow pacing so the live-mode capture harness can freeze the pty
+    # state mid-iteration and observe the active peek panel.  Total
+    # runtime is ~18s; capture typically freezes around t=8-10s after
+    # 5-6 events have been emitted.
+    delay = 1.8
+
+    for event in EVENTS:
+        sys.stdout.write(json.dumps(event) + "\n")
+        sys.stdout.flush()
+        time.sleep(delay)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())