feat(designer): ANSI color dump for scenario previews

Emit truecolor SGR from cell styles via dump --color auto|always|never
so cortexnight themes are visible; plain text remains the golden path.

Author: cortex-qa

README.md

@@ -135,6 +135,9 @@ cargo run --release -- run --scenario home-motd
 
 # Headless UTF-8 buffer to stdout (default size 92x30, theme cortexnight)
 cargo run --release -- dump --scenario home-motd
+# ANSI colors (theme tokens: truecolor SGR) — use in a real terminal
+cargo run --release -- dump --scenario home-motd --color always
+cargo run --release -- dump --scenario view-mc-home --color always
 cargo run --release -- dump --scenario chat-idle --width 92 --height 30 --theme cortexnight
 ```
 

src/cli.rs

@@ -1,6 +1,6 @@
 //! CLI: `list`, `dump`, `run`.
 
-use std::io::{self, Write};
+use std::io::{self, IsTerminal, Write};
 use std::path::Path;
 use std::process::ExitCode;
 
@@ -17,7 +17,8 @@ use tui::draw;
 use crate::catalog::{Catalog, CatalogError, default_catalog};
 use crate::gallery::{GalleryAction, GalleryState};
 use crate::paint::{
-    DEFAULT_HEIGHT, DEFAULT_THEME, DEFAULT_WIDTH, PaintError, apply_theme, render_to_string,
+    DEFAULT_HEIGHT, DEFAULT_THEME, DEFAULT_WIDTH, PaintError, apply_theme, render_to_ansi,
+    render_to_string,
 };
 
 /// Exit code for unknown scenario id (plan todo 9).
@@ -38,7 +39,10 @@ pub struct Cli {
 pub enum Commands {
     /// Print scenario ids grouped by category.
     List,
-    /// Headless paint one scenario to stdout (C5 plain text).
+    /// Headless paint one scenario to stdout.
+    ///
+    /// Default is plain C5 text (stable goldens). Pass `--color` / `--color=always` for
+    /// ANSI SGR so themes (e.g. cortexnight magenta/orange) are visible in a terminal.
     Dump {
         /// Scenario id (C6).
         #[arg(long)]
@@ -49,6 +53,9 @@ pub enum Commands {
         height: u16,
         #[arg(long, default_value = DEFAULT_THEME)]
         theme: String,
+        /// Color mode for dump: `auto` (TTY→ANSI), `always`, `never` (plain C5).
+        #[arg(long, default_value = "auto", value_parser = ["auto", "always", "never"])]
+        color: String,
     },
     /// Interactive gallery (TTY). Optional starting scenario id.
     Run {
@@ -91,7 +98,22 @@ pub fn run_cli(args: impl IntoIterator<Item = std::ffi::OsString>) -> ExitCode {
             width,
             height,
             theme,
-        } => match cmd_dump(&catalog, &scenario, width, height, &theme, &mut io::stdout()) {
+            color,
+        } => {
+            let use_ansi = match color.as_str() {
+                "always" => true,
+                "never" => false,
+                _ => io::stdout().is_terminal(),
+            };
+            match cmd_dump(
+                &catalog,
+                &scenario,
+                width,
+                height,
+                &theme,
+                use_ansi,
+                &mut io::stdout(),
+            ) {
             Ok(()) => ExitCode::SUCCESS,
             Err(DumpError::Unknown(e)) => {
                 eprintln!("{e}");
@@ -105,6 +127,7 @@ pub fn run_cli(args: impl IntoIterator<Item = std::ffi::OsString>) -> ExitCode {
                 eprintln!("io failed: {e}");
                 ExitCode::FAILURE
             }
+            }
         },
         Commands::Run {
             id,
@@ -166,12 +189,17 @@ pub fn cmd_dump(
     width: u16,
     height: u16,
     theme: &str,
+    ansi: bool,
     out: &mut impl Write,
 ) -> Result<(), DumpError> {
     let scenario = catalog.get(id)?;
     let mut app = scenario.build();
     apply_theme(&mut app, theme);
-    let screen = render_to_string(&app, width, height)?;
+    let screen = if ansi {
+        render_to_ansi(&app, width, height)?
+    } else {
+        render_to_string(&app, width, height)?
+    };
     out.write_all(screen.as_bytes())?;
     Ok(())
 }
@@ -341,6 +369,7 @@ mod tests {
             DEFAULT_WIDTH,
             DEFAULT_HEIGHT,
             DEFAULT_THEME,
+            false,
             &mut buf,
         )
         .expect("dump");
@@ -364,6 +393,7 @@ mod tests {
             DEFAULT_WIDTH,
             DEFAULT_HEIGHT,
             DEFAULT_THEME,
+            false,
             &mut buf,
         )
         .expect_err("must fail");

src/lib.rs

@@ -15,7 +15,8 @@ pub use catalog::{Catalog, CatalogError, REQUIRED_IDS, category_for_id, default_
 pub use gallery::{GalleryAction, GalleryState};
 pub use goldens::{CORE_GOLDEN_IDS, dump_normalized, golden_path, normalize, snapshots_dir, write_core_goldens};
 pub use paint::{
-    DEFAULT_HEIGHT, DEFAULT_THEME, DEFAULT_WIDTH, PaintError, apply_theme, render_to_string,
+    DEFAULT_HEIGHT, DEFAULT_THEME, DEFAULT_WIDTH, PaintError, apply_theme, render_to_ansi,
+    render_to_string,
 };
 pub use scenario::{FnScenario, Scenario, fixture_status, prepare_base};
 

src/paint.rs

@@ -4,6 +4,7 @@ use std::fmt;
 
 use ratatui::Terminal;
 use ratatui::backend::TestBackend;
+use ratatui::style::{Color, Modifier};
 use tui::{App, draw};
 
 /// Default canvas width (plan C5).
@@ -73,6 +74,135 @@ pub fn render_to_string(app: &App, width: u16, height: u16) -> Result<String, Pa
     Ok(out)
 }
 
+/// Render `app` to an ANSI-colored grid for terminal preview.
+///
+/// Same geometry rules as [`render_to_string`], but each cell emits SGR codes for
+/// fg/bg/modifiers when styles change. A reset (`\x1b[0m`) is emitted at end of
+/// each line. Use this for human `dump --color`; keep goldens on plain text.
+pub fn render_to_ansi(app: &App, width: u16, height: u16) -> Result<String, PaintError> {
+    if width == 0 || height == 0 {
+        return Err(PaintError::ZeroSize { width, height });
+    }
+
+    let backend = TestBackend::new(width, height);
+    let mut terminal = Terminal::new(backend).map_err(|e| PaintError::Terminal(e.to_string()))?;
+    terminal
+        .draw(|frame| draw(frame, app))
+        .map_err(|e| PaintError::Draw(e.to_string()))?;
+
+    let buffer = terminal.backend().buffer();
+    let area = buffer.area();
+    // ANSI overhead estimate ~24 bytes/cell worst case.
+    let mut out =
+        String::with_capacity(usize::from(width) * usize::from(height) * 8 + usize::from(height));
+
+    for y in 0..area.height {
+        let mut line = String::with_capacity(usize::from(width) * 8);
+        let mut prev_style: Option<(Color, Color, Modifier)> = None;
+        let mut cells: Vec<(String, Color, Color, Modifier)> =
+            Vec::with_capacity(usize::from(width));
+
+        for x in 0..area.width {
+            let cell = &buffer[(x, y)];
+            let style = cell.style();
+            let fg = style.fg.unwrap_or(Color::Reset);
+            let bg = style.bg.unwrap_or(Color::Reset);
+            let mods = style.add_modifier;
+            cells.push((cell.symbol().to_owned(), fg, bg, mods));
+        }
+
+        // Trim trailing whitespace cells (symbol is space/empty) so ANSI dump matches
+        // plain dump line length after trim — compute last non-space index.
+        let mut last_content = cells.len();
+        while last_content > 0 {
+            let sym = cells[last_content - 1].0.as_str();
+            if sym == " " || sym.is_empty() {
+                last_content -= 1;
+            } else {
+                break;
+            }
+        }
+        cells.truncate(last_content);
+
+        for (symbol, fg, bg, mods) in cells {
+            let cur = (fg, bg, mods);
+            if prev_style != Some(cur) {
+                line.push_str("\u{1b}[0m");
+                push_sgr(&mut line, fg, bg, mods);
+                prev_style = Some(cur);
+            }
+            line.push_str(&symbol);
+        }
+        if prev_style.is_some() {
+            line.push_str("\u{1b}[0m");
+        }
+        out.push_str(&line);
+        out.push('\n');
+    }
+
+    debug_assert_eq!(
+        out.bytes().filter(|&b| b == b'\n').count(),
+        usize::from(height)
+    );
+    Ok(out)
+}
+
+fn push_sgr(out: &mut String, fg: Color, bg: Color, mods: Modifier) {
+    if mods.contains(Modifier::BOLD) {
+        out.push_str("\u{1b}[1m");
+    }
+    if mods.contains(Modifier::DIM) {
+        out.push_str("\u{1b}[2m");
+    }
+    if mods.contains(Modifier::ITALIC) {
+        out.push_str("\u{1b}[3m");
+    }
+    if mods.contains(Modifier::UNDERLINED) {
+        out.push_str("\u{1b}[4m");
+    }
+    if mods.contains(Modifier::REVERSED) {
+        out.push_str("\u{1b}[7m");
+    }
+    if let Some(code) = color_sgr(fg, true) {
+        out.push_str(&code);
+    }
+    if let Some(code) = color_sgr(bg, false) {
+        out.push_str(&code);
+    }
+}
+
+fn color_sgr(color: Color, foreground: bool) -> Option<String> {
+    let base = if foreground { 30 } else { 40 };
+    let bright = if foreground { 90 } else { 100 };
+    match color {
+        Color::Reset => None,
+        Color::Black => Some(format!("\u{1b}[{base}m")),
+        Color::Red => Some(format!("\u{1b}[{}m", base + 1)),
+        Color::Green => Some(format!("\u{1b}[{}m", base + 2)),
+        Color::Yellow => Some(format!("\u{1b}[{}m", base + 3)),
+        Color::Blue => Some(format!("\u{1b}[{}m", base + 4)),
+        Color::Magenta => Some(format!("\u{1b}[{}m", base + 5)),
+        Color::Cyan => Some(format!("\u{1b}[{}m", base + 6)),
+        Color::Gray => Some(format!("\u{1b}[{}m", base + 7)),
+        Color::DarkGray => Some(format!("\u{1b}[{bright}m")),
+        Color::LightRed => Some(format!("\u{1b}[{}m", bright + 1)),
+        Color::LightGreen => Some(format!("\u{1b}[{}m", bright + 2)),
+        Color::LightYellow => Some(format!("\u{1b}[{}m", bright + 3)),
+        Color::LightBlue => Some(format!("\u{1b}[{}m", bright + 4)),
+        Color::LightMagenta => Some(format!("\u{1b}[{}m", bright + 5)),
+        Color::LightCyan => Some(format!("\u{1b}[{}m", bright + 6)),
+        Color::White => Some(format!("\u{1b}[{}m", bright + 7)),
+        Color::Rgb(r, g, b) => {
+            let kind = if foreground { 38 } else { 48 };
+            Some(format!("\u{1b}[{kind};2;{r};{g};{b}m"))
+        }
+        Color::Indexed(i) => {
+            let kind = if foreground { 38 } else { 48 };
+            Some(format!("\u{1b}[{kind};5;{i}m"))
+        }
+    }
+}
+
 /// Apply optional theme override after scenario build.
 pub fn apply_theme(app: &mut App, theme: &str) {
     if !theme.is_empty() && app.theme() != theme {
@@ -136,4 +266,22 @@ mod tests {
         }
         assert_eq!(screen.lines().count(), 10);
     }
+
+    #[test]
+    fn ansi_render_emits_sgr_and_line_count() {
+        let app = prepare_base();
+        let colored = render_to_ansi(&app, DEFAULT_WIDTH, DEFAULT_HEIGHT).expect("ansi paint");
+        assert_eq!(colored.lines().count(), usize::from(DEFAULT_HEIGHT));
+        assert!(
+            colored.contains('\u{1b}'),
+            "ansi dump must contain ESC sequences; got bare text"
+        );
+        assert!(
+            colored.contains("Cortex") || colored.contains('✦') || colored.contains('❯'),
+            "chrome missing in ansi dump"
+        );
+        // Still human-readable after stripping-ish sanity: plain dump shorter but both same line count.
+        let plain = render_to_string(&app, DEFAULT_WIDTH, DEFAULT_HEIGHT).expect("plain");
+        assert_eq!(plain.lines().count(), colored.lines().count());
+    }
 }