docs(tui): add inline comments throughout TUI codebase

Add concise, high-signal inline comments to function bodies across the
TUI implementation. Comments explain intent, edge cases, boundary math,
ownership/cloning decisions, and performance trade-offs rather than
restating code behavior.

Key areas covered:
- Config screen rendering (panels, overlays, layouts)
- Dictating screen rendering (visualizer, status, controls)
- Runtime event loop (channel draining, input routing, periodic tasks)
- State management (initialization, selection logic, feedback)
- Widget rendering (logs, hotkeys, brand header)
- Override parsing and application

Author: hate

keyless/src/main.rs

@@ -38,22 +38,27 @@ use keyless::Cli;
 fn handle_top_level_flags() -> Result<Option<Cli>, String> {
     let cli = Cli::parse();
     if cli.list_devices {
-        // Enable CLI logging formatting for non-TUI output
+        // Enable CLI logging formatting for non-TUI output (stdout is safe here).
+        // TUI path avoids stdout logging to prevent tearing alternate screen buffer.
         keyless_logging::init_stdout();
         match keyless_audio::input::list_input_device_names() {
             Ok(list) => {
+                // Empty list: show helpful message instead of blank output.
                 if list.is_empty() {
                     println!("(no input devices)");
                 } else {
+                    // Print index:name pairs; enumerate provides 0-based indices for user reference.
                     for (i, n) in list.iter().enumerate() {
                         println!("{}: {}", i, n);
                     }
                 }
             }
             Err(e) => {
+                // Print error to stdout (non-TUI path); user expects to see it.
                 println!("failed to list devices: {}", e);
             }
         }
+        // Early return: list-devices handled, don't start TUI.
         return Ok(None);
     }
     Ok(Some(cli))
@@ -65,17 +70,20 @@ fn main() -> ExitCode {
     match handle_top_level_flags() {
         Ok(None) => ExitCode::SUCCESS, // handled and printed, exit early
         Ok(Some(cli)) => {
-            // Do NOT init stdout logging for the TUI path
+            // Do NOT init stdout logging for the TUI path (prevents alternate screen corruption).
+            // Build overrides from CLI flags and ENV vars (CLI takes precedence).
             let ov = keyless::overrides::overrides_from_env_and_cli(&cli);
             if let Err(e) = keyless::tui::run_with_overrides(Some(ov)) {
-                // Best-effort error reporting to stderr after TUI exits
+                // Best-effort error reporting to stderr after TUI exits (terminal restored).
+                // Use stderr to avoid mixing with TUI output if terminal wasn't fully restored.
                 eprintln!("tui error: {}", e);
                 ExitCode::FAILURE
             } else {
                 ExitCode::SUCCESS
             }
         }
         Err(e) => {
+            // Flag parsing error: report to stderr before any TUI initialization.
             eprintln!("flag handling error: {}", e);
             ExitCode::FAILURE
         }

keyless/src/overrides.rs

@@ -59,18 +59,22 @@ pub struct Overrides {
 /// set in `ov` will override the corresponding field in `config`.
 pub fn apply_overrides(config: &mut Config, ov: &Overrides) {
     if let Some(v) = ov.model.as_ref() {
+        // Trim whitespace from model ID/path; reject empty strings (defensive).
         let t = v.trim();
         if !t.is_empty() {
             config.model_path = PathBuf::from(t);
         }
     }
     if let Some(v) = ov.language.as_ref() {
+        // Trim whitespace from language code; reject empty strings (None = auto-detect).
         let t = v.trim();
         if !t.is_empty() {
             config.language = Some(t.to_string());
         }
     }
     if let Some(v) = ov.sink.as_ref() {
+        // Parse sink string (paste/clipboard/file); ignore parse errors (invalid strings ignored).
+        // File mode not set here (handled by file override below); only Paste/Clipboard applied.
         match OutputMode::from_str(v.trim()) {
             Ok(OutputMode::Paste) => config.output_mode = OutputMode::Paste,
             Ok(OutputMode::Clipboard) => config.output_mode = OutputMode::Clipboard,
@@ -79,23 +83,28 @@ pub fn apply_overrides(config: &mut Config, ov: &Overrides) {
         }
     }
     if let Some(p) = ov.file.as_ref() {
+        // File path override: trim whitespace, reject empty strings.
+        // Takes precedence over sink=file parsing above (explicit path provided).
         let t = p.trim();
         if !t.is_empty() {
             config.output_mode = OutputMode::File(PathBuf::from(t));
         }
     }
     if let Some(v) = ov.device.as_ref() {
+        // Trim whitespace from device name; reject empty strings (None = use default).
         let t = v.trim();
         if !t.is_empty() {
             config.device_name = Some(t.to_string());
         }
     }
     if let Some(v) = ov.hotkey.as_ref() {
+        // Trim whitespace from hotkey string; reject empty strings (prevent invalid config).
         let t = v.trim();
         if !t.is_empty() {
             config.hotkey = t.to_string();
         }
     }
+    // VAD overrides: direct assignment (no clamping; user may want extreme values).
     if let Some(f) = ov.vad_start {
         config.vad.start_db = f;
     }
@@ -108,6 +117,7 @@ pub fn apply_overrides(config: &mut Config, ov: &Overrides) {
     if let Some(s) = ov.vad_max_silence {
         config.vad.max_silence_ms = s;
     }
+    // EQ overrides: clamp to valid ranges to prevent invalid audio processing parameters.
     if let Some(b) = ov.eq_bands {
         config.eq.bands = b.clamp(EQ_BANDS_MIN, EQ_BANDS_MAX);
     }
@@ -126,21 +136,25 @@ pub fn apply_overrides(config: &mut Config, ov: &Overrides) {
     if let Some(d) = ov.eq_decay {
         config.eq.decay = d.clamp(EQ_DECAY_MIN, EQ_DECAY_MAX);
     }
+    // Validate config after applying all overrides; ignore result (errors logged internally).
     let _ = config.validate();
 }
 
 /// Overrides source used by the TUI; constructed in main from CLI/ENV.
 #[allow(clippy::module_name_repetitions)]
 pub fn overrides_from_env_and_cli(cli: &Cli) -> Overrides {
-    // precedence: CLI > ENV
+    // Precedence: CLI > ENV (CLI flags override environment variables).
+    // Clone CLI Option<String> to move value into closure (needs owned String).
     let pick_str = |cli_opt: &Option<String>, env_key: &str| -> Option<String> {
         if let Some(v) = cli_opt.clone() {
             Some(v)
         } else {
+            // Fallback to ENV var if CLI flag not set; ok() converts Result to Option.
             std::env::var(env_key).ok()
         }
     };
 
+    // Parse f32 from ENV if CLI flag not set; ignore parse errors (invalid strings = None).
     let pick_f32 = |cli_opt: Option<f32>, env_key: &str| -> Option<f32> {
         cli_opt.or_else(|| {
             std::env::var(env_key)
@@ -149,6 +163,7 @@ pub fn overrides_from_env_and_cli(cli: &Cli) -> Overrides {
         })
     };
 
+    // Parse u16 from ENV if CLI flag not set; ignore parse errors (invalid strings = None).
     let pick_u16 = |cli_opt: Option<u16>, env_key: &str| -> Option<u16> {
         cli_opt.or_else(|| {
             std::env::var(env_key)

keyless/src/tui/config/device.rs

@@ -10,12 +10,16 @@ use crate::tui::theme::{Colors, Theme};
 
 /// Render the input devices list.
 pub fn render_devices(f: &mut ratatui::Frame, area: Rect, app: &AppState) {
+    // Recompute list items each frame; incurs small allocs for text styling/formatting.
+    // Acceptable given the short list size and TUI frame budget.
     let device_items: Vec<ListItem> = app
         .selections
         .device_names
         .iter()
         .enumerate()
         .map(|(idx, d)| {
+            // Selection is driven by `app.selections.device_idx` (external state).
+            // Assumes the index is in-bounds of `device_names`; upstream logic must enforce it.
             let is_selected = idx == app.selections.device_idx;
             let style = if is_selected {
                 Style::default()
@@ -25,22 +29,35 @@ pub fn render_devices(f: &mut ratatui::Frame, area: Rect, app: &AppState) {
                 Theme::text_muted()
             };
             let text = if is_selected {
+                // Selected row shows the raw device name; the active indicator will be provided by
+                // the widget's `highlight_symbol` below to avoid duplicate indicators.
                 d.clone()
             } else {
+                // Non-selected rows are visually de-emphasized and receive an inactive indicator.
                 format!("{} {}", Theme::inactive_indicator(), d)
             };
             ListItem::new(Span::styled(text, style))
         })
         .collect();
+
+    // Local list state is ephemeral; selection is persisted in `app` not this state object.
     let mut device_state = ratatui::widgets::ListState::default();
+    // No bounds guard here; relies on upstream to keep `device_idx < device_names.len()`.
+    // Ratatui tolerates out-of-range select without panicking but may render no highlight.
     device_state.select(Some(app.selections.device_idx));
+
+    // Trailing space ensures padding between the indicator glyph and the text.
     let indicator_symbol = format!("{} ", Theme::active_indicator());
+
+    // Visual container: rounded border and accent-colored title for discoverability.
     let block = Block::default()
         .borders(Borders::ALL)
         .border_type(BorderType::Rounded)
         .border_style(Style::default().fg(Colors::border()))
         .title_style(Style::default().fg(Colors::device_accent()))
         .title("🎤 input devices");
+
+    // Highlight uses accent fg + selected bg for strong contrast; bold improves readability.
     let list = List::new(device_items)
         .block(block)
         .highlight_style(
@@ -50,5 +67,7 @@ pub fn render_devices(f: &mut ratatui::Frame, area: Rect, app: &AppState) {
                 .add_modifier(Modifier::BOLD),
         )
         .highlight_symbol(&indicator_symbol);
+
+    // Render with stateful API so the selected row gets the highlight/indicator this frame.
     f.render_stateful_widget(list, area, &mut device_state);
 }

keyless/src/tui/config/draw.rs

@@ -19,7 +19,8 @@ pub fn draw_config(
 ) {
     let full = f.area();
 
-    // Dynamic footer height based on the footer content and available width (generic estimator)
+    // Compute footer height from hotkey segments and terminal width (cells).
+    // This prevents the footer from wrapping unexpectedly when the screen is narrow.
     let segs = if app
         .overlays
         .expert
@@ -37,6 +38,8 @@ pub fn draw_config(
 
     let layout = Layout::default()
         .direction(Direction::Vertical)
+        // Reserve at least 10 rows for content; footer is exact length computed above.
+        // Using fixed footer length avoids layout jitter across frames.
         .constraints([Constraint::Min(10), Constraint::Length(lines_needed)])
         .split(full);
 
@@ -51,27 +54,33 @@ pub fn draw_config(
         main_outer,
     );
     let mut content = main_outer;
+    // Shrink to inner content area (1-cell border on all sides).
+    // Use saturating ops to avoid underflow on very small terminals.
     content.x += 1;
     content.y += 1;
     content.width = content.width.saturating_sub(2);
     content.height = content.height.saturating_sub(2);
 
+    // Heuristic height for sinks panel: items + 2 (title/padding), capped at 6 rows.
+    // Small cap keeps the top area from starving models/languages.
     let sink_height: u16 = ((sinks_list.len() as u16) + 2).min(6);
 
     let chunks = Layout::default()
         .direction(Direction::Vertical)
         .constraints([
             Constraint::Length(3),                  // Top info (metrics + warnings)
-            Constraint::Length(sink_height.max(5)), // Sinks
+            Constraint::Length(sink_height.max(5)), // Sinks (min 5 rows for readability)
             Constraint::Min(10),                    // Models + (Languages/Devices)
-            Constraint::Length(7),                  // VAD + Logs
+            Constraint::Length(7),                  // VAD + Logs (fixed to avoid flicker)
         ])
         .split(content);
     // Brand overlay: render title intersecting the top frame border
     {
         use crate::tui::widgets::brand::{BrandOptions, render_brand};
         let brand_area = ratatui::layout::Rect {
             x: main_outer.x,
+            // Lift the brand one cell above to overlap the outer border.
+            // `saturating_sub` prevents underflow when y == 0.
             y: main_outer.y.saturating_sub(1),
             width: main_outer.width,
             height: 1,
@@ -100,6 +109,7 @@ pub fn draw_config(
         Span::raw("    "),
         Span::styled("time: ", Theme::label()),
         Span::styled(
+            // Convert milliseconds to HH:MM:SS string; assumes ms are monotonic counters.
             keyless_core::utils::fmt_hms(app.lifetime_talk_ms),
             Theme::text_primary(),
         ),
@@ -110,6 +120,8 @@ pub fn draw_config(
     // Warnings / file path (rendered below metrics)
     let mut warn_lines: Vec<Line> = Vec::new();
     if matches!(app.selections.sink_choice, SinkChoice::File) {
+        // File sink: show current path and edit state. `file_path` is cloned to avoid
+        // borrowing across UI composition. Encoding assumed UTF-8 for display.
         let mut spans = vec![
             Span::styled("file: ", Theme::label()),
             Span::styled(app.selections.file_path.clone(), Colors::text_primary()),
@@ -130,6 +142,7 @@ pub fn draw_config(
         ));
         warn_lines.push(Line::from(spans));
     } else {
+        // Show the most recent error (if any) and permission warnings gathered at startup.
         if let Some(err) = &app.overlays.error_message {
             warn_lines.push(Line::from(vec![
                 Span::styled("error: ", Theme::warn()),
@@ -146,6 +159,7 @@ pub fn draw_config(
         }
     }
     if !warn_lines.is_empty() {
+        // Only render the warnings box when there is content to avoid consuming vertical space.
         let warning_p = Paragraph::new(warn_lines);
         f.render_widget(warning_p, extra_rows[1]);
     }
@@ -160,6 +174,7 @@ pub fn draw_config(
         .split(chunks[2]);
 
     // Left: Models
+    // Build an O(1) membership set for installed models; allocates proportional to count.
     let installed_set: std::collections::HashSet<String> =
         app.models.discovered.iter().cloned().collect();
     models::render_models(
@@ -213,11 +228,13 @@ pub fn draw_config(
 
     // Expert overlay (centered)
     if app.expert_mode() {
+        // Render after footer so overlay sits on top of lower widgets.
         expert::render_expert(f, full, app);
     }
 
     // Download overlay (centered, modal)
     if app.is_downloading() {
+        // Two states: transient "loading" (no progress) vs active download.
         let is_loading = app
             .overlays
             .download
@@ -257,7 +274,7 @@ pub fn draw_config(
                 ])
                 .alignment(Alignment::Center)
             });
-        // center a box for message + gauge
+        // Center a box for message + gauge. The middle 4 rows are dedicated to content.
         let outer = Layout::default()
             .direction(Direction::Vertical)
             .constraints([
@@ -275,10 +292,11 @@ pub fn draw_config(
             ])
             .split(outer);
         let area = inner_cols[1];
-        // Clear the background to make overlay opaque
+        // Clear the background to make overlay opaque and avoid bleed-through.
         f.render_widget(Clear, area);
         f.render_widget(overlay, area);
         let mut msg_area = area;
+        // Inset by 2 cells horizontally to avoid text hugging the border.
         msg_area.x += 2;
         msg_area.y += 1;
         msg_area.width = msg_area.width.saturating_sub(4);
@@ -289,11 +307,11 @@ pub fn draw_config(
             .as_ref()
             .map(|d| d.message.as_str())
             .unwrap_or("this may take a few minutes on first run...");
-        // If text starts with percentage (e.g., "75% model..."), hide it from display
+        // If text starts with a percentage (e.g., "75% model..."), hide it to reduce noise.
         let display_text = if let Some(pct_end) = text.find('%') {
             let before_pct = &text[..pct_end];
             if before_pct.trim().parse::<u16>().is_ok() {
-                // Skip past "NN% " to hide the percentage from user
+                // Skip past "NN% ". Assumes percentage fits in u16 and precedes '%'.
                 text.get(pct_end + 1..).unwrap_or(text).trim_start()
             } else {
                 text
@@ -309,11 +327,11 @@ pub fn draw_config(
         } else {
             Theme::text_primary()
         };
-        // render primary line
+        // Render primary line; keep same bg as overlay for a seamless modal look.
         let p = Paragraph::new(Line::from(vec![Span::styled(display_text, stage_style)]))
             .style(Style::default().bg(Colors::bg_selected()));
         f.render_widget(p, msg_area);
-        // render gauge on second line if percent known
+        // Render gauge on the second line if a percentage can be parsed.
         let mut gauge_area = msg_area;
         gauge_area.y = gauge_area.y.saturating_add(1);
         if let Some(pct_end) = text.find('%') {
@@ -323,6 +341,7 @@ pub fn draw_config(
                     .gauge_style(Theme::selected())
                     .style(Style::default().bg(Colors::bg_selected()))
                     .ratio({
+                        // Clamp to [0,1]. Use 1.0 when nearing completion and ETA reports 0s.
                         let r = val as f64 / 100.0;
                         if val >= 99 && text.contains("ETA 0s") {
                             1.0
@@ -360,6 +379,7 @@ pub fn draw_config(
             let area = cols[1];
             f.render_widget(toast, area);
             let mut msg = area;
+            // One-line message centered horizontally; trim margins to avoid wrapping.
             msg.x += 2;
             msg.y += 1;
             msg.width = msg.width.saturating_sub(4);