tatui-frontend

name	tatui-frontend
description	Use when building or reviewing Maestro's Nim/Tatui TUI: mapping Maestro panels to Tatui widgets, constraint layout, the stdio protocol client, and headless snapshot tests.

Tatui Frontend Skill

Use When

• Building or changing a TUI panel in frontend/.
• Wiring the TUI to the Rust core's stdio protocol.

Tatui at a glance

• Install (not on the nimble registry yet): run scripts/install-tatui.sh (installs the exact commit behind tatui v0.1.2, Nim ≥ 2.0). Declare a bare requires "tatui" in the nimble file.
• Immediate mode: redraw the whole UI each tick from state; Tatui diffs and writes only changes.
• Constraint layout: Length, Percentage, Ratio, Min, Max, Fill; split with f.area.split(...).
• Test backend renders a Buffer to text with no TTY → golden snapshots in CI.

API taste

import tatui
var term = newTerminal(newAnsiBackend())
term.setup()
defer: term.restore()
term.draw proc(f: var Frame) =
  let chunks = f.area.split(Vertical, @[length(3), fill(1)])
  f.renderWidget(initBlock(title = " Maestro ", borders = AllBorders), chunks[0])
  f.renderWidget(paragraph("…"), chunks[1])

Panel → widget map

Maestro panel	Tatui widgets
Chat / conversation	Block + Paragraph + List + Scrollbar
Agent roster + status (idle/observe/think/act/error)	Table/List + Gauge
FSM stepper (Ideation→…→Verification)	Tabs + Block
Event / message log	List + Scrollbar
Project lists (available/done)	Tabs + Table/List
System / health metrics	Sparkline + BarChart + Gauge + Chart
Command input	Block input + event decoder
Approval / rollback modal	Clear + Block + Paragraph + List

Rules

• Consume Tatui only; never re-implement buffer/diff/backend/layout.
• Keep the draw function a pure function of the latest core snapshot; no business logic in the TUI.
• Talk to the core only via the line-delimited JSON stdio protocol (protocol.nim).
• Restore terminal state with defer even on error.

Outputs

• A panel composed from shipped widgets, driven by core events, covered by test-backend snapshots.