fix(tui): render WelcomeCard mascot in the docs demo

Stop drawing a parallel welcome card in the GIF recorder. Empty-session
frames now paint the same WelcomeCard and MASCOT_MINIMAL_LINES the TUI
uses, with snapshot coverage on the four block-brain glyphs.

Co-authored-by: Mathis <echobt@users.noreply.github.com>

Author: cursoragent

docs/guides/tui.md

@@ -41,7 +41,7 @@ The timeline is the transcript. It renders several kinds of row:
 | Tool call | `◐`/`●` then the tool name and a short argument summary | A tool the agent invoked |
 | Tool result | `⎿ …` indented under the call | What the tool returned |
 | Subagent task | `● Task <type>` with a todo list underneath | Work delegated to a subagent |
-| Welcome card | A bordered card | Shown while the session is empty |
+| Welcome card | Bordered card with the ASCII mascot, greeting, and tips | Shown while the session is empty |
 
 Tool rows collapse to a summary. Press `e` while the timeline has focus to
 expand or collapse the details of the selected tool call.

src/cortex-tui-capture/Cargo.toml

@@ -30,6 +30,9 @@ cortex-tui-core = { workspace = true }
 # Product theme, so the recorded demo tracks the real TUI palette
 cortex-core = { workspace = true }
 
+# Same welcome card / mascot the live TUI mounts, so the GIF cannot drift
+cortex-tui-components = { workspace = true }
+
 # Async runtime
 tokio = { workspace = true, features = ["full", "sync", "time", "macros", "fs"] }
 

src/cortex-tui-capture/src/demo/mod.rs

@@ -241,7 +241,7 @@ mod tests {
         let recording = recording();
         let first = &recording.frames[0];
         assert!(
-            first.plain.contains("Cortex Code"),
+            first.plain.contains("Cortex CLI"),
             "welcome frame missing the product name:\n{}",
             first.plain
         );
@@ -250,6 +250,36 @@ mod tests {
             "welcome frame missing the public endpoint:\n{}",
             first.plain
         );
+        for glyph in cortex_tui_components::mascot::MASCOT_MINIMAL_LINES {
+            let needle = glyph.trim();
+            assert!(
+                first.plain.contains(needle),
+                "welcome frame missing mascot line {needle:?}:\n{}",
+                first.plain
+            );
+        }
+        assert!(
+            first.plain.contains("Welcome!"),
+            "welcome frame missing the greeting:\n{}",
+            first.plain
+        );
+    }
+
+    #[test]
+    fn welcome_beats_keep_the_mascot_on_screen() {
+        let recording = recording();
+        for frame in recording
+            .frames
+            .iter()
+            .filter(|frame| frame.label == "welcome")
+        {
+            assert!(
+                frame.plain.contains("▄█▀▀▀▀█▄"),
+                "welcome beat {} lost the mascot:\n{}",
+                frame.index,
+                frame.plain
+            );
+        }
     }
 
     #[test]

src/cortex-tui-capture/src/demo/render.rs

@@ -4,9 +4,9 @@
 //! real TUI palette instead of a second, drifting copy of it.
 
 use cortex_core::style::{
-    BORDER, BORDER_FOCUS, CYAN_PRIMARY, SKY_BLUE, SUCCESS, SURFACE_0, TEXT, TEXT_DIM, TEXT_MUTED,
-    VOID,
+    BORDER, BORDER_FOCUS, CYAN_PRIMARY, SKY_BLUE, SUCCESS, TEXT, TEXT_DIM, TEXT_MUTED, VOID,
 };
+use cortex_tui_components::welcome_card::{InfoCard, InfoCardPair, ToLines, WelcomeCard};
 use ratatui::Frame;
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Modifier, Style};
@@ -47,56 +47,46 @@ pub fn draw_scene(frame: &mut Frame, scene: &Scene) {
     draw_hints(frame, hints_area, scene);
 }
 
+/// Empty-session frame: the same `WelcomeCard` + info cards the live TUI paints
+/// via `generate_welcome_lines`, including `MASCOT_MINIMAL_LINES`.
 fn draw_welcome(frame: &mut Frame, area: Rect, scene: &Scene) {
-    let card_width = area.width.min(82);
-    let card_height = 11.min(area.height);
-    let card = Rect {
-        x: area.x,
-        y: area.y + area.height.saturating_sub(card_height) / 2,
-        width: card_width,
-        height: card_height,
-    };
-
-    let block = Block::default()
-        .borders(Borders::ALL)
-        .border_type(BorderType::Rounded)
-        .border_style(Style::default().fg(BORDER))
-        .style(Style::default().bg(SURFACE_0))
-        .padding(Padding::new(2, 2, 1, 0))
-        .title(Span::styled(
-            " Cortex Code ",
-            Style::default()
-                .fg(CYAN_PRIMARY)
-                .add_modifier(Modifier::BOLD),
-        ));
-
-    let lines = vec![
-        Line::from(Span::styled(
-            "A coding agent that reads, edits, runs and tests your project.",
-            Style::default().fg(TEXT),
-        )),
-        Line::default(),
-        field_line("workspace", &scene.workspace),
-        field_line("endpoint", &scene.endpoint),
-        field_line(
-            "mode",
-            &format!("{} · {} autonomy", scene.mode, scene.autonomy),
-        ),
-        Line::default(),
-        Line::from(Span::styled(
-            "Describe a change and Cortex Code works through it, tool call by tool call.",
-            Style::default().fg(TEXT_MUTED),
-        )),
-    ];
-
-    frame.render_widget(Paragraph::new(lines).block(block), card);
-}
+    let welcome_card = WelcomeCard::new()
+        .subtitle("Your AI-powered coding assistant.")
+        .version(env!("CARGO_PKG_VERSION"))
+        .tips(&[
+            "Send /help for available commands.",
+            "Use Tab for autocomplete. Press Esc to cancel.",
+        ])
+        .accent_color(CYAN_PRIMARY)
+        .text_color(TEXT)
+        .dim_color(TEXT_DIM)
+        .border_color(CYAN_PRIMARY);
+
+    let mut lines = welcome_card.to_lines(area.width);
+    lines.push(Line::default());
+
+    let left_card = InfoCard::new()
+        .add("Directory", &scene.workspace)
+        .add("Endpoint", &scene.endpoint)
+        .dim_color(TEXT_DIM)
+        .text_color(TEXT)
+        .border_color(CYAN_PRIMARY);
+
+    let right_card = InfoCard::new()
+        .add("Mode", &scene.mode)
+        .add("Autonomy", &scene.autonomy)
+        .dim_color(TEXT_DIM)
+        .text_color(TEXT)
+        .border_color(CYAN_PRIMARY);
+
+    lines.extend(
+        InfoCardPair::new(left_card, right_card)
+            .gap(2)
+            .right_width(25)
+            .to_lines(area.width),
+    );
 
-fn field_line(label: &str, value: &str) -> Line<'static> {
-    Line::from(vec![
-        Span::styled(format!("{label:<11}"), Style::default().fg(TEXT_MUTED)),
-        Span::styled(value.to_string(), Style::default().fg(TEXT_DIM)),
-    ])
+    frame.render_widget(Paragraph::new(lines).style(Style::default().bg(VOID)), area);
 }
 
 fn draw_timeline(frame: &mut Frame, area: Rect, scene: &Scene) {

src/cortex-tui-components/src/mascot.rs

@@ -171,4 +171,16 @@ mod tests {
         let expr = MascotExpression::default();
         assert_eq!(expr.art(), MASCOT);
     }
+
+    #[test]
+    fn minimal_mascot_is_four_block_brain_lines() {
+        assert_eq!(MASCOT_MINIMAL_LINES.len(), 4);
+        assert_eq!(MASCOT_MINIMAL_LINES[0].trim(), "▄█▀▀▀▀█▄");
+        assert_eq!(MASCOT_MINIMAL_LINES[1].trim(), "██ ▌  ▐ ██");
+        assert_eq!(MASCOT_MINIMAL_LINES[2].trim(), "█▄▄▄▄▄▄█");
+        assert_eq!(MASCOT_MINIMAL_LINES[3].trim(), "█    █");
+        assert!(MASCOT_MINIMAL.contains("▄█▀▀▀▀█▄"));
+        assert!(MASCOT_MINIMAL.contains("▌"));
+        assert!(MASCOT_MINIMAL.contains("▐"));
+    }
 }

src/cortex-tui-components/src/welcome_card.rs

@@ -630,4 +630,77 @@ mod tests {
         let card = WelcomeCard::new().tips(&["Tip 1", "Tip 2"]);
         assert!(card.required_height() >= 10);
     }
+
+    fn buffer_text(buf: &Buffer) -> String {
+        let area = buf.area();
+        let mut out = String::new();
+        for y in 0..area.height {
+            for x in 0..area.width {
+                out.push_str(buf[(x, y)].symbol());
+            }
+            out.push('\n');
+        }
+        out
+    }
+
+    fn assert_contains_mascot(text: &str) {
+        for line in MASCOT_MINIMAL_LINES {
+            let needle = line.trim();
+            assert!(
+                text.contains(needle),
+                "missing mascot line {needle:?}:\n{text}"
+            );
+        }
+    }
+
+    #[test]
+    fn welcome_card_to_lines_includes_mascot() {
+        let card = WelcomeCard::new()
+            .subtitle("Your AI-powered coding assistant.")
+            .tips(&[
+                "Send /help for available commands.",
+                "Use Tab for autocomplete. Press Esc to cancel.",
+            ]);
+        let text = card
+            .to_lines(80)
+            .into_iter()
+            .map(|line| line.to_string())
+            .collect::<Vec<_>>()
+            .join("\n");
+        assert_contains_mascot(&text);
+        assert!(text.contains("Welcome!"));
+        assert!(text.contains("Cortex CLI"));
+    }
+
+    #[test]
+    fn welcome_card_widget_renders_mascot() {
+        let mut buf = Buffer::empty(Rect::new(0, 0, 80, 16));
+        WelcomeCard::new()
+            .subtitle("Your AI-powered coding assistant.")
+            .tips(&["Send /help for available commands."])
+            .render(Rect::new(0, 0, 80, 16), &mut buf);
+        let text = buffer_text(&buf);
+        assert_contains_mascot(&text);
+        assert!(text.contains("Welcome!"));
+    }
+
+    #[test]
+    fn welcome_card_narrow_and_wide_viewports_keep_the_mascot() {
+        for (width, height) in [(40, 12), (120, 40)] {
+            let card = WelcomeCard::new().tips(&["Send /help for available commands."]);
+            let text = card
+                .to_lines(width)
+                .into_iter()
+                .map(|line| line.to_string())
+                .collect::<Vec<_>>()
+                .join("\n");
+            assert_contains_mascot(&text);
+
+            let mut buf = Buffer::empty(Rect::new(0, 0, width, height));
+            WelcomeCard::new()
+                .tips(&["Send /help for available commands."])
+                .render(Rect::new(0, 0, width, height), &mut buf);
+            assert_contains_mascot(&buffer_text(&buf));
+        }
+    }
 }

src/cortex-tui/src/runner/login_screen.rs

@@ -19,6 +19,7 @@ use ratatui::widgets::{Clear, Paragraph};
 use tokio::sync::mpsc;
 
 use cortex_login::{SecureAuthData, save_auth_with_fallback};
+use cortex_tui_components::mascot::MASCOT_MINIMAL_LINES;
 use cortex_tui_components::spinner::SpinnerStyle;
 
 // ============================================================================
@@ -398,27 +399,29 @@ impl LoginScreen {
         ]));
         f.render_widget(welcome, chunks[0]);
 
-        // Line 3: Mascot top
-        let mascot_top = Paragraph::new(" ▄█▀▀▀▀█▄ ").style(Style::default().fg(PRIMARY));
-        f.render_widget(mascot_top, chunks[2]);
-
-        // Line 4: Mascot + waiting message
-        let mascot_middle = Paragraph::new(Line::from(vec![
-            Span::styled("██ ▌  ▐ ██  ", Style::default().fg(PRIMARY)),
-            Span::styled(
-                format!("Waiting for browser authentication  {}", spinner),
-                Style::default().fg(PRIMARY),
-            ),
-        ]));
-        f.render_widget(mascot_middle, chunks[3]);
-
-        // Line 5: Mascot bottom
-        let mascot_bottom = Paragraph::new(" █▄▄▄▄▄▄█ ").style(Style::default().fg(PRIMARY));
-        f.render_widget(mascot_bottom, chunks[4]);
-
-        // Line 6: Mascot legs
-        let mascot_legs = Paragraph::new("  █    █").style(Style::default().fg(PRIMARY));
-        f.render_widget(mascot_legs, chunks[5]);
+        // Lines 3-6: official welcome mascot (`MASCOT_MINIMAL_LINES`).
+        f.render_widget(
+            Paragraph::new(MASCOT_MINIMAL_LINES[0]).style(Style::default().fg(PRIMARY)),
+            chunks[2],
+        );
+        f.render_widget(
+            Paragraph::new(Line::from(vec![
+                Span::styled(MASCOT_MINIMAL_LINES[1], Style::default().fg(PRIMARY)),
+                Span::styled(
+                    format!(" Waiting for browser authentication  {spinner}"),
+                    Style::default().fg(PRIMARY),
+                ),
+            ])),
+            chunks[3],
+        );
+        f.render_widget(
+            Paragraph::new(MASCOT_MINIMAL_LINES[2]).style(Style::default().fg(PRIMARY)),
+            chunks[4],
+        );
+        f.render_widget(
+            Paragraph::new(MASCOT_MINIMAL_LINES[3]).style(Style::default().fg(PRIMARY)),
+            chunks[5],
+        );
 
         // Line 8: Browser message
         let copy_hint = if self.copied_notification.is_some() {
@@ -960,6 +963,13 @@ mod tests {
                 || waiting.contains("Cortex"),
             "{waiting}"
         );
+        for glyph in MASCOT_MINIMAL_LINES {
+            let needle = glyph.trim();
+            assert!(
+                waiting.contains(needle),
+                "login waiting screen missing mascot line {needle:?}: {waiting}"
+            );
+        }
 
         screen.state = LoginState::SelectMethod;
         screen.error_message = Some("The coding service is temporarily unavailable".into());

src/cortex-tui/src/views/minimal_session/tests.rs

@@ -45,9 +45,15 @@ mod harness_snapshots {
         dump_snapshot("home", &text);
         assert!(!text.to_lowercase().contains("grok"));
         assert!(
-            text.contains("Cortex") || text.contains("session") || !text.trim().is_empty(),
-            "home session should render: {text}"
+            text.contains("Cortex CLI"),
+            "home session should render WelcomeCard: {text}"
         );
+        for glyph in ["▄█▀▀▀▀█▄", "██ ▌  ▐ ██", "█▄▄▄▄▄▄█", "█    █"] {
+            assert!(
+                text.contains(glyph),
+                "home session missing mascot line {glyph:?}: {text}"
+            );
+        }
     }
 
     #[test]