TUI (Terminal User Interface)

Dibangun di atas ratatui + crossterm. Kode ada di apps/interfaces/tui/src/.

Struktur Source

apps/interfaces/tui/src/
├── run.rs          # Event loop utama
├── state.rs        # AppStateRest — single source of truth
├── action.rs       # apply_action(): satu-satunya mutator state
├── turn.rs         # Spawn agent turn di background thread
├── lib.rs          # Re-export publik
├── controller/
│   ├── input.rs    # Key handler → Vec<Action>
│   └── command.rs  # Slash command parser
├── view/
│   ├── mod.rs      # Layout + pre_render() + draw()
│   ├── chat.rs     # Chat transcript panel (dengan display cache)
│   ├── sidebar.rs  # Sidebar: workflow, tasks, usage
│   ├── status.rs   # Status bar satu baris
│   ├── markdown.rs # Markdown → styled Span (pulldown-cmark)
│   ├── workflow.rs # Workflow/hive-mind progress panel
│   ├── theme.rs    # Tokyo Night color palette (const)
│   └── overlays/   # 16 overlay panel
└── model/          # Data model lokal TUI

Render Pipeline (Per Frame)

run_loop_inner()  [50ms in-flight / 200ms idle]
      │
      ├── drain expired toasts (1x, bukan 2x)
      │
      ├── if dirty:
      │     view::pre_render(&mut state)   ← update cache (markdown, token count)
      │     terminal.draw(|f| view::draw(f, &state))
      │     state.dirty = false
      │
      └── poll events → apply_action → Action::Tick

Optimasi Performa

Masalah lama	Solusi saat ini
`count_tokens` (tiktoken) setiap frame	Cache `cached_token_count`, update hanya saat pesan baru
`render_markdown` ulang setiap frame	`display_lines_cache` di `AppStateRest`, rebuild saat `transcript_cache.dirty`
`Vec::remove(0)` untuk evict pesan lama	`VecDeque::pop_front()` — O(1)
`Mutex<bool>` untuk `turn_in_flight`	`Arc<AtomicBool>` — lock-free
Render terus meski idle	Skip `terminal.draw()` jika `dirty == false`
Poll 50ms konstan	Adaptif: 50ms saat in-flight, 200ms saat idle
`drain_expired_toasts` 2x per iterasi	Sekali saja di `run_loop_inner`

State (AppStateRest)

AppStateRest di state.rs adalah satu-satunya sumber kebenaran TUI:

AppStateRest {
  settings: Settings               // provider, model, dll
  app_config: AppConfig            // endpoint, env vars
  workspace_roots: Vec<PathBuf>    // working directories
  session_dir / session_id         // path sesi aktif
  memory_dir                       // direktori memory
  session_runtime: Option<SessionRuntime>  // history pesan, usage stats

  transcript_cache: TranscriptCache  // VecDeque<ChatMessageDisplay>
  scroll: ScrollState                // offset scroll pane chat
  input: InputState                  // buffer, cursor, history, autocomplete
  misc: MiscState                    // overlay aktif, toasts, flags

  turn_events: Arc<Mutex<VecDeque<TurnEvent>>>  // queue event dari agent
  turn_in_flight_flag: Arc<AtomicBool>          // apakah agent sedang jalan
  abort_flag: Arc<AtomicBool>                   // sinyal abort oleh user

  // Cache performa
  display_lines_cache: Vec<Line<'static>>  // hasil render markdown
  cached_token_count: usize                // token count terkini
  token_count_dirty: bool                  // perlu hitung ulang?
  last_render_width: u16                   // lebar terminal saat render terakhir

  dirty: bool   // perlu render ulang?
  quit: bool    // keluar dari loop?
}

Aturan mutasi:

Dimutasi hanya dari action.rs::apply_action() dan run.rs (untuk dirty/quit)
Semua fungsi view/* bersifat read-only terhadap state
pre_render_chat() boleh mutasi hanya field cache (display_lines_cache, cached_token_count, token_count_dirty)

Input & Actions

controller/input.rs::handle_key() → Vec<Action> → apply_action(&mut state, action)

Semua mutasi state melewati satu titik: apply_action. Controller tidak tahu bagaimana state diubah, hanya action apa yang dihasilkan.

Action Utama

Action	Efek
`SubmitInput(text)`	Push ke transcript, spawn agent turn
`Tick`	Drain `TurnEvent` queue, update state dari hasil agent
`ScrollUp/Down`	Ubah `scroll.offset`
`OpenOverlay(v)`	Set `misc.overlay = v`
`Resize(w, h)`	Invalidasi cache display, set `last_render_width`
`AbortTurn`	Store `true` ke `abort_flag`
`ForceQuit`	Set `quit = true`

Overlays (16 Panel)

Overlay	File	Fungsi
`Help`	`overlays/help.rs`	Daftar shortcut keyboard
`Settings`	`overlays/settings.rs`	Panel pengaturan
`Bash`	`overlays/bash.rs`	Background shell jobs
`QuitConfirm`	`overlays/quit_confirm.rs`	Konfirmasi keluar
`KeyInput`	`overlays/key_input.rs`	Capture key binding
`Editor`	`overlays/editor.rs`	File editor inline
`Effort`	`overlays/effort.rs`	Pilih level reasoning LLM
`Mcp`	`overlays/mcp.rs`	Manajemen MCP server
`Todo`	`overlays/todo.rs`	Daftar TODO
`Rewind`	`overlays/rewind.rs`	Navigasi history pesan
`Learning`	`overlays/learning.rs`	Viewer lesson
`Usage`	`overlays/usage.rs`	Statistik token
`Loading`	`overlays/loading.rs`	Spinner generik
`ModelSelector`	`overlays/model_selector.rs`	Pilih model LLM
`ClearConfirm`	`overlays/clear_confirm.rs`	Konfirmasi clear chat

Layout Terminal

┌───────────────────────────────────────────────┐
│                                               │
│   Chat Transcript              Sidebar (≥90)  │
│   (view/chat.rs)               ┌────────────┐ │
│   VecDeque messages            │ Workflow   │ │
│   + markdown cache             ├────────────┤ │
│   scrollable                   │ Tasks      │ │
│                                ├────────────┤ │
│                                │ Usage      │ │
│                                └────────────┘ │
├───────────────────────────────────────────────┤
│ ❯ Input Bar + Autocomplete dropdown           │
├───────────────────────────────────────────────┤
│ ⚡zesdex  READY │ ...center... │ tok · model  │
└───────────────────────────────────────────────┘

Sidebar hanya tampil jika lebar terminal ≥ 90 kolom.

Theme

view/theme.rs mendefinisikan palette Tokyo Night sebagai const Color: PRIMARY, BG, SURFACE, SURFACE_ELEVATED, BORDER, TEXT, TEXT_DIM, TEXT_MUTED, SUCCESS, WARNING, ERROR, INFO, HIGHLIGHT, CODE_BG, dll.

Markdown Rendering

view/markdown.rs::render_markdown(text, width, dim):

Parse dengan pulldown-cmark
Hasilkan Vec<Span<'static>> dengan styling
Support: heading, code block, diff block (warna +/-/@@), list, blockquote, table, inline code, link
dim=true → semua span memakai TEXT_DIM + italic (untuk tool output)
Hasil di-cache di AppStateRest::display_lines_cache

7.4 KiB Raw Blame History