# TUI Module Structure
This directory contains the Terminal User Interface (TUI) for the Conflux orchestrator.
## Module Organization
- **runner.rs**: Main event loop and TUI initialization
- **key_handlers.rs**: Keyboard input handling (Tab, arrow keys, shortcuts, etc.)
- **command_handlers.rs**: TuiCommand processing (queue operations, worktree management, etc.)
- **state.rs**: Application state management
- **render.rs**: UI rendering logic
- **events.rs**: Event types and definitions
- **orchestrator.rs**: Cumulative worktree orchestration logic
- **queue.rs**: Dynamic queue for runtime change additions
- **types.rs**: Type definitions (AppExecutionMode, ModalState, ViewMode, StopMode, etc.)
- **utils.rs**: Utility functions (editor launch, terminal management, etc.)
## Recent Refactoring (refactor-tui-runner-handlers)
The key event handling and TuiCommand processing logic was extracted from `runner.rs` into separate modules for better maintainability:
### key_handlers.rs (532 lines)
Handles all keyboard input:
- `handle_tab_key()`: Switch between Changes/Worktrees views
- `handle_cursor_movement()`: Navigate with arrows/k/j keys
- `handle_editor_launch()`: Launch editor with 'e' key
- `handle_merge_key()`: Merge operations with 'M' key
- `handle_esc_key()`: Graceful/force stop
- `handle_start_key()`: Start/resume/retry processing via the resolved TUI start keybindings
- `handle_enter_key()`: Execute worktree commands
- `handle_plus_key()`: Create new worktrees with '+' key
- `handle_key_event()`: Main key event dispatcher
### command_handlers.rs (672 lines)
Handles all TuiCommand variants:
- `handle_start_processing_command()`: Spawn orchestrator tasks
- `handle_tui_command()`: Main TuiCommand dispatcher
- Processes commands: StartProcessing (also the retry intent — marked retry-eligible target evidence, not the process mode, is what makes a start an explicit retry; ordinary `not queued` marks keep priority in Select/Stopped), AddToQueue, RemoveFromQueue, DequeueChange, DeleteWorktree, Stop, CancelStop, ForceStop, MergeWorktreeBranch, ResolveMerge
Queue, stop-and-dequeue, and retry commands are adapters over the shared
`orchestration::operator_command::OperatorCommandService`. Lifecycle validation,
reducer ordering, dynamic queue mutation, `on_queue_add`/`on_queue_remove`
cardinality, cancellation-before-dequeue ordering, and retry routing live in that
service so a remote frontend behaves identically.
Worktree create/delete/merge are adapters over one shared
`worktree_ops::service::WorktreeService`, built once in `runner.rs` and handed to
both the TUI command loop and the `/api/v2` worktree port so the two contend for
a single repository mutation guard.
`DeleteWorktree` carries a typed `DeleteIntent`. Its two permissions are
independent: `skip_teardown` is chosen by `S` in the ordinary confirmation, and
`allow_known_dirty` is granted only by uppercase `X` in the destructive
`ConfirmDirtyDiscard` confirmation, which the service's own fresh `Dirty` refusal
is what opens.
### Integration Status
The helper modules are created and tested but not yet integrated into `run_tui_loop()`.
Integration is deferred to allow for manual TUI behavior testing before making the change.
To integrate the helpers:
1. Replace the large key event match block in `run_tui_loop` with calls to `key_handlers::handle_key_event()`
2. Replace the TuiCommand match block with calls to `command_handlers::handle_tui_command()`
3. Test all keyboard shortcuts and command flows manually in the TUI
4. Verify no regression in user experience
## Testing
Run TUI-specific tests:
```bash
cargo test --bin cflx tui::runner::
```
Verify code quality:
```bash
cargo fmt --check
cargo clippy -- -D warnings
```