UI MODULE

TUI layer built on Ratatui + Crossterm. State machine with 3 modes (Solver/Game/History), handler-per-concern pattern, and modular rendering.

STRUCTURE

ui/
├── mod.rs              # Bootstrap: run_ui() — terminal init, word loading, event loop
├── app.rs              # App struct (central state), run() loop, draw() dispatch
├── types.rs            # GameMode enum, InputStatus, ParsedInput, LogBuffer
├── tests.rs            # 705 lines, 40+ tests across 7 suites
├── handlers/
│   ├── input_handler.rs  # Key event router (375 lines) — dispatches by mode + modifier
│   ├── game_handler.rs   # Game lifecycle: start, check state, toggle mode
│   ├── solver_handler.rs # Undo, recompute suggestions + analysis
│   └── history_handler.rs # View cycling, pagination, game selection
├── rendering/
│   ├── mod.rs            # draw() — layout construction, panel dispatch
│   ├── guesses.rs        # Colored guess history (Green/Yellow/Gray tiles)
│   ├── suggestions.rs    # Ranked word suggestions list
│   ├── input_field.rs    # Input bar with validation coloring
│   ├── status.rs         # Mode indicator / game status bar
│   ├── logs.rs           # Log panel
│   ├── analysis/         # 4 analysis panels: letters, positions, constraints, pool
│   └── history/          # 4 history views: stats, list, detail, solver
└── history/
    ├── parser.rs         # Log file parser (529 lines) — regex over tracing output
    ├── types.rs          # GameRecord, HistoryData, HistoryStats, GameOutcome
    └── solver_types.rs   # SolverSession, SolverStats, SolverOutcome

WHERE TO LOOK

CONVENTIONS

• Handler pattern: Struct borrows &mut App, constructed inline per use. No persistent handler state.

  SolverHandler::new(&mut self).recompute_analysis();  // in app.rs run loop
  InputHandler::new(self).handle_key(key);              // returns bool (quit?)
  

• Rendering: draw_* methods implemented on App in separate files via impl App blocks. Each panel is a standalone method receiving Frame + Rect.
• Analysis recomputation: Lazy — analysis_dirty flag set on guess add/undo, recomputed at top of run loop before draw.
• Visibility: All App fields are pub(in crate::ui) — handlers and rendering access them directly, but nothing outside ui/ can.
• History view cycling: Stats → List → Detail (if selected) / Solver (if not) → Stats

ANTI-PATTERNS

• Do NOT add persistent state to handlers — they are ephemeral &mut App wrappers
• Do NOT access App fields from outside crate::ui — use the public API (run_ui(), exported types)
• Do NOT skip analysis_dirty = true when modifying solver state — panels will show stale data
• History parser depends on exact tracing log format — changes to app.log() messages will break parsing

NOTES

• Input validation differs by mode: Solver expects <word> <pattern>, Game expects just <word>
• Game mode toggles: show_suggestions and show_analysis default OFF in Game, always ON in Solver
• Solver sessions: Tracked via solver_session_active/start/paused fields for history stats
• Test helper: create_test_app() uses 8-word vocabulary — sufficient for unit tests, not representative of real word counts