feat(tui): add theme system with 3 built-in themes (#299)

* feat: add theme TOML files and hex color parser

- Create 3 built-in themes: phosphor, tokyo-night, catppuccin-latte
- Add parse_hex_color() utility for #RRGGBB and #RGB formats
- All themes have 17 required color fields in TOML format
- phosphor.toml matches existing Theme::phosphor() RGB values

Tasks: #2 (TOML files) + #3 (hex parser) from theme-system plan

* feat(tui): add ThemeColor newtype with Serde support

- Add ThemeColor(Color) newtype wrapper for serialization
- Implement Serialize/Deserialize for hex color format
- Update all 17 Theme struct fields to use ThemeColor
- Fix all downstream usage sites with explicit derefs (*)
- Enable TOML-based theme loading (Task 1 complete)

All 399 type errors resolved. Build passes with zero errors.
Part of theme system implementation (Issue #295).

* feat(tui): apply theme changes immediately in settings view

Wire immediate theme application when user changes theme in settings:
- Add pending_theme_change tracking in SettingsView
- Add take_pending_theme_change() accessor in SettingsView
- Check for pending theme in home/input.rs SettingsAction::Continue
- Return Action::SetTheme(name) to apply immediately via app.rs
- Add Action::SetTheme handler to handle_mouse() for consistency

Theme now updates visually in real-time instead of on settings close.

Verified:
- OPENSSL_NO_VENDOR=1 cargo check: 0 errors
- cargo clippy: 0 warnings
- OPENSSL_NO_VENDOR=1 cargo test --lib: 641 passed

* fix(tui): add Theme category to settings view

Discovered during F3 TUI QA: SettingsCategory::Theme was defined but
not included in the categories vector. Theme now appears as first
category in Settings.

* test: add merge_configs tests for theme override

Adds two tests to match the pattern used for other config types:
- test_merge_configs_with_theme_override: verifies profile override applies
- test_merge_configs_theme_inherits_when_not_overridden: verifies global inherits

* feat(themes): add tokyo-night-storm theme

Add darker Tokyo Night variant with official Storm palette colors:
- Background: #24283b (vs #1a1b26 in regular tokyo-night)
- Border: #414868 (Terminal Black)
- Selection: #364a82

All semantic colors (running, waiting, error, idle) match tokyo-night.

* fix: dereference ThemeColor in dialog styles

* chore: remove .sisyphus from tracking

* docs: add theme config section

* chore: remove .sisyphus from tracking

* fix: address PR review feedback

- Use let-else pattern for ThemeColor::Serialize invariant
- Read theme directly from field value instead of config
- Remove comments from tokyo-night-storm.toml for consistency

* refactor: remove ThemeColor wrapper, use native ratatui Color serde

- Enable ratatui 'serde' feature for native Color deserialization
- Delete ThemeColor newtype and color.rs module
- Add semantic color fields to Theme (diff_*, branch, sandbox, worktree_*)
- Update all 4 theme TOML files with official palette colors
- Verify all TUI primitives use theme colors (no hardcoded Color::)

* feat(themes): add diff_modified and help_key semantic colors

- Add diff_modified for FileStatus::Modified (yellow)
- Add help_key for keyboard shortcuts in help panels (yellow)
- Preserves original phosphor Color::Yellow mapping
- Uses palette-correct yellow for tokyo-night/catppuccin

* cleanup

---------

Co-authored-by: njbrake <njbrake@gmail.com>

Author: jerome-benoit

.gitignore

@@ -39,6 +39,7 @@ Thumbs.db
 
 # AI coding tools
 .opencode/
+.sisyphus/
 
 # Per-repo aoe config (created by `aoe init`, should be committed per-repo by users)
 # Ignored here since this is the aoe tool repo itself

docs/guides/configuration.md

@@ -37,6 +37,17 @@ All settings below can also be edited from the TUI settings screen (press `s` or
 | `AGENT_OF_EMPIRES_PROFILE` | Default profile to use |
 | `AGENT_OF_EMPIRES_DEBUG` | Enable debug logging (`1` to enable) |
 
+## Theme
+
+```toml
+[theme]
+name = "phosphor"   # phosphor, tokyo-night-storm, catppuccin-latte
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `name` | `"phosphor"` | TUI color theme. Available: `phosphor` (default green), `tokyo-night-storm` (dark blue/purple), `catppuccin-latte` (light pastel). |
+
 ## Session
 
 ```toml

src/session/profile_config.rs

@@ -703,4 +703,27 @@ mod tests {
             Some(TmuxMouseMode::Enabled)
         );
     }
+
+    #[test]
+    fn test_merge_configs_with_theme_override() {
+        let global = Config::default();
+        let profile = ProfileConfig {
+            theme: Some(ThemeConfigOverride {
+                name: Some("tokyo-night".to_string()),
+            }),
+            ..Default::default()
+        };
+        let merged = merge_configs(global, &profile);
+        assert_eq!(merged.theme.name, "tokyo-night");
+    }
+
+    #[test]
+    fn test_merge_configs_theme_inherits_when_not_overridden() {
+        let mut global = Config::default();
+        global.theme.name = "catppuccin-latte".to_string();
+
+        let profile = ProfileConfig::default();
+        let merged = merge_configs(global, &profile);
+        assert_eq!(merged.theme.name, "catppuccin-latte");
+    }
 }

src/tui/app.rs

@@ -7,6 +7,7 @@ use std::path::PathBuf;
 use std::time::Duration;
 
 use super::home::{HomeView, TerminalMode};
+use super::styles::load_theme;
 use super::styles::Theme;
 use crate::session::{get_update_settings, load_config, save_config, Storage};
 use crate::tmux::AvailableTools;
@@ -78,10 +79,17 @@ impl App {
     pub fn new(profile: &str, available_tools: AvailableTools) -> Result<Self> {
         let storage = Storage::new(profile)?;
         let mut home = HomeView::new(storage, available_tools)?;
-        let theme = Theme::default();
 
         // Check if we need to show welcome or changelog dialogs
         let mut config = load_config()?.unwrap_or_default();
+
+        // Load theme from config, defaulting to phosphor if empty
+        let theme_name = if config.theme.name.is_empty() {
+            "phosphor"
+        } else {
+            &config.theme.name
+        };
+        let theme = load_theme(theme_name);
         let current_version = env!("CARGO_PKG_VERSION").to_string();
 
         if !config.app_state.has_seen_welcome {
@@ -106,6 +114,11 @@ impl App {
         })
     }
 
+    pub fn set_theme(&mut self, name: &str) {
+        self.theme = load_theme(name);
+        self.needs_redraw = true;
+    }
+
     pub async fn run(
         &mut self,
         terminal: &mut Terminal<CrosstermBackend<std::io::Stdout>>,
@@ -304,6 +317,9 @@ impl App {
                 Action::EditFile(path) => {
                     self.edit_file(&path, terminal)?;
                 }
+                Action::SetTheme(name) => {
+                    self.set_theme(&name);
+                }
             }
         }
 
@@ -333,6 +349,9 @@ impl App {
                 Action::EditFile(path) => {
                     self.edit_file(&path, terminal)?;
                 }
+                Action::SetTheme(name) => {
+                    self.set_theme(&name);
+                }
             }
         }
 
@@ -542,6 +561,7 @@ pub enum Action {
     AttachTerminal(String, TerminalMode),
     SwitchProfile(String),
     EditFile(PathBuf),
+    SetTheme(String),
 }
 
 #[cfg(test)]

src/tui/components/preview.rs

@@ -63,7 +63,7 @@ impl Preview {
             if sandbox.enabled {
                 info_lines.push(Line::from(vec![
                     Span::styled("Sandbox: ", Style::default().fg(theme.dimmed)),
-                    Span::styled(&sandbox.container_name, Style::default().fg(Color::Magenta)),
+                    Span::styled(&sandbox.container_name, Style::default().fg(theme.sandbox)),
                 ]));
             }
         }
@@ -193,7 +193,7 @@ impl Preview {
             ]));
             info_lines.push(Line::from(vec![
                 Span::styled("Branch:  ", Style::default().fg(theme.dimmed)),
-                Span::styled(&wt_info.branch, Style::default().fg(Color::Cyan)),
+                Span::styled(&wt_info.branch, Style::default().fg(theme.branch)),
             ]));
             info_lines.push(Line::from(vec![
                 Span::styled("Main:    ", Style::default().fg(theme.dimmed)),
@@ -213,9 +213,9 @@ impl Preview {
                 Span::styled(
                     managed_text,
                     Style::default().fg(if wt_info.managed_by_aoe {
-                        Color::Green
+                        theme.worktree_managed
                     } else {
-                        Color::Yellow
+                        theme.worktree_manual
                     }),
                 ),
             ]));

src/tui/dialogs/new_session/render.rs

@@ -357,7 +357,7 @@ impl NewSessionDialog {
         if let Some(error) = &self.error_message {
             let error_text = format!("✗ Error: {}", error);
             let error_paragraph = Paragraph::new(error_text)
-                .style(Style::default().fg(Color::Red))
+                .style(Style::default().fg(theme.error))
                 .wrap(Wrap { trim: true });
             frame.render_widget(error_paragraph, chunks[hint_chunk]);
         } else {

src/tui/diff/render.rs

@@ -2,7 +2,7 @@
 
 use ratatui::{
     layout::{Constraint, Direction, Layout, Rect},
-    style::{Color, Modifier, Style},
+    style::{Modifier, Style},
     text::{Line, Span},
     widgets::{
         Block, Borders, Clear, List, ListItem, Padding, Paragraph, Scrollbar, ScrollbarOrientation,
@@ -98,9 +98,15 @@ impl DiffView {
                 Style::default().fg(theme.dimmed),
             ),
             Span::styled("  ", Style::default()),
-            Span::styled(format!("+{}", additions), Style::default().fg(Color::Green)),
+            Span::styled(
+                format!("+{}", additions),
+                Style::default().fg(theme.diff_add),
+            ),
             Span::styled(" ", Style::default()),
-            Span::styled(format!("-{}", deletions), Style::default().fg(Color::Red)),
+            Span::styled(
+                format!("-{}", deletions),
+                Style::default().fg(theme.diff_delete),
+            ),
         ]);
 
         frame.render_widget(Paragraph::new(header), inner);
@@ -147,12 +153,12 @@ impl DiffView {
                 let is_selected = i == self.selected_file;
 
                 let status_color = match file.status {
-                    FileStatus::Added => Color::Green,
-                    FileStatus::Modified => Color::Yellow,
-                    FileStatus::Deleted => Color::Red,
-                    FileStatus::Renamed => Color::Cyan,
-                    FileStatus::Copied => Color::Cyan,
-                    FileStatus::Untracked => Color::Gray,
+                    FileStatus::Added => theme.diff_add,
+                    FileStatus::Modified => theme.diff_modified,
+                    FileStatus::Deleted => theme.diff_delete,
+                    FileStatus::Renamed => theme.diff_header,
+                    FileStatus::Copied => theme.diff_header,
+                    FileStatus::Untracked => theme.dimmed,
                 };
 
                 let style = if is_selected {
@@ -239,13 +245,13 @@ impl DiffView {
                     );
                     lines.push(Line::from(Span::styled(
                         header,
-                        Style::default().fg(Color::Cyan),
+                        Style::default().fg(theme.diff_header),
                     )));
 
                     for line in &hunk.lines {
                         let (prefix, style) = match line.tag {
-                            ChangeTag::Delete => ("-", Style::default().fg(Color::Red)),
-                            ChangeTag::Insert => ("+", Style::default().fg(Color::Green)),
+                            ChangeTag::Delete => ("-", Style::default().fg(theme.diff_delete)),
+                            ChangeTag::Insert => ("+", Style::default().fg(theme.diff_add)),
                             ChangeTag::Equal => (" ", Style::default().fg(theme.dimmed)),
                         };
 
@@ -330,7 +336,7 @@ impl DiffView {
         let content = if let Some(ref error) = self.error_message {
             Line::from(Span::styled(error, Style::default().fg(theme.error)))
         } else if let Some(ref success) = self.success_message {
-            Line::from(Span::styled(success, Style::default().fg(Color::Green)))
+            Line::from(Span::styled(success, Style::default().fg(theme.diff_add)))
         } else {
             Line::from(vec![
                 Span::styled("j/k", Style::default().fg(theme.accent)),
@@ -495,7 +501,7 @@ impl DiffView {
             )));
             for (key, desc) in keys {
                 lines.push(Line::from(vec![
-                    Span::styled(format!("  {:14}", key), Style::default().fg(Color::Yellow)),
+                    Span::styled(format!("  {:14}", key), Style::default().fg(theme.help_key)),
                     Span::styled(desc, Style::default().fg(theme.text)),
                 ]));
             }

src/tui/home/input.rs

@@ -35,6 +35,15 @@ impl HomeView {
                         self.settings_view = None;
                         self.confirm_dialog = None;
                         self.settings_close_confirm = false;
+                        // Revert theme to saved config (undo any preview)
+                        if let Ok(config) = resolve_config(self.storage.profile()) {
+                            let theme_name = if config.theme.name.is_empty() {
+                                "phosphor".to_string()
+                            } else {
+                                config.theme.name
+                            };
+                            return Some(Action::SetTheme(theme_name));
+                        }
                         return None;
                     }
                 }
@@ -44,11 +53,22 @@ impl HomeView {
         // Handle settings view (full-screen takeover)
         if let Some(ref mut settings) = self.settings_view {
             match settings.handle_key(key) {
-                SettingsAction::Continue => return None,
+                SettingsAction::Continue => {
+                    return None;
+                }
                 SettingsAction::Close => {
                     self.settings_view = None;
                     // Refresh config-dependent state in case settings changed
                     self.refresh_from_config();
+                    // Reload theme from saved config
+                    if let Ok(config) = resolve_config(self.storage.profile()) {
+                        let theme_name = if config.theme.name.is_empty() {
+                            "phosphor".to_string()
+                        } else {
+                            config.theme.name
+                        };
+                        return Some(Action::SetTheme(theme_name));
+                    }
                     return None;
                 }
                 SettingsAction::UnsavedChangesWarning => {
@@ -61,6 +81,9 @@ impl HomeView {
                     self.settings_close_confirm = true;
                     return None;
                 }
+                SettingsAction::PreviewTheme(name) => {
+                    return Some(Action::SetTheme(name));
+                }
             }
         }
 

src/tui/home/render.rs

@@ -295,15 +295,15 @@ impl HomeView {
                 if let Some(wt_info) = &inst.worktree_info {
                     line_spans.push(Span::styled(
                         format!("  {}", wt_info.branch),
-                        Style::default().fg(Color::Cyan),
+                        Style::default().fg(theme.branch),
                     ));
                 }
                 if inst.is_sandboxed() {
                     match self.view_mode {
                         ViewMode::Agent => {
                             line_spans.push(Span::styled(
                                 " [sandbox]",
-                                Style::default().fg(Color::Magenta),
+                                Style::default().fg(theme.sandbox),
                             ));
                         }
                         ViewMode::Terminal => {
@@ -313,7 +313,7 @@ impl HomeView {
                                 TerminalMode::Host => " [host]",
                             };
                             line_spans
-                                .push(Span::styled(mode_text, Style::default().fg(Color::Magenta)));
+                                .push(Span::styled(mode_text, Style::default().fg(theme.sandbox)));
                         }
                     }
                 }