# The TUI — working map Read this before touching `internal/tui/`. The generic side — how a Go CLI/TUI project is built, tested and reviewed — belongs to the pipeline that started you. ## Build and test ```sh go build ./... go test ./internal/tui # fast (~2-4 s); the whole tree is ~1 min go vet ./... ``` No device, no capture, no network: a TUI change is verified by unit tests plus a rendered frame. ## How the TUI is put together - `model.go` — the `Model`, the key map (`keys`), and `Update`/`View` dispatch. Key bindings are declared in one place; a new binding goes there, not inline. - `dashboard.go`, `pipeline.go`, `runs.go`, `run_detail.go` — the screens. A run's detail is built from sections, and a section can open as its own pane in the sliding stack. - `context_footer.go` — the footer for the current mode. A modal's footer replaces the page's; never inherit shortcuts that the modal does not honour. - `theme.go` / `style.go` — colours and text styles. Status colour comes from one vocabulary so a state looks the same in every screen. - `linetext.go`, `graph.go` — line building and the stage graph rendering. - Human decision stages are answered in the TUI: `↑/↓ choose · Tab feedback · Enter decide · Esc cancel`. ## Reviewing a TUI change without a terminal The pinned frames in `internal/harness/tmp/ui-review/render/` (`empty-catalog-*`, `filter-no-match-*`, `narrow-long-model-*`, `plain-nocolor-*`, `wide-focused-*`, in dark and light) are the reference renders. Compare against them when a change alters layout, spacing, colour or the footer, and add a frame when you introduce a new state worth pinning. A change that alters a pinned frame and does not say why is a review finding. ## Conventions and traps - No polling: state arrives from the server; do not add a ticker to look busy. - The footer and the pane stack are shared surfaces — a change there affects every screen, so say what you checked. - Terminal width matters: verify at a narrow width as well as a wide one, and never assume colour support (`plain-nocolor-*` exists for a reason). - Do not restart the deployed server or ntfy to test a TUI change: run the binary against a scratch server or use the fixtures.