From 2157f986489f36a0cd4c866b17e8f8ff418cf959 Mon Sep 17 00:00:00 2001
From: Joe Savona <joesavona@openai.com>
Date: Sat, 7 Nov 2026 01:18:45 +0000
Subject: [PATCH] Add theme-aware semantic colors to extension UI trees
 (#60019)

## Why

Extension UI trees previously accepted only named terminal colors and literal RGB values. Semantic colors let extension content follow the active syntax theme and terminal color capabilities.

## What changed

- Accept `primary`, `surface`, `accent`, and `status-*` color roles for text foregrounds and row backgrounds.
- Resolve semantic colors against the active theme when rendering extension footer content. Prefer the `codex.accent` scope for `accent`, falling back to the theme's accent setting.
- Reuse status-line scope mappings and fallback colors, with terminal-default fallbacks for unavailable primary, surface, and accent colors.

## Testing

Add color serialization coverage and rendering snapshots for dark, light, and empty themes in truecolor and ANSI 16-color terminals, including nested foreground and background styles.

GitOrigin-RevId: 156f137859d74178f9ae6aa46a02eecb815e9802
---
 .../src/bottom_pane/footer/footer_content.rs  |  14 +-
 codex-rs/tui/src/bottom_pane/mod.rs           |   1 +
 .../tui/src/bottom_pane/status_line_style.rs  |  29 +++-
 codex-rs/tui/src/render/highlight.rs          |  24 ++-
 ...ee__tests__semantic_statusline_ansi16.snap |  37 ++++
 ..._tests__semantic_statusline_truecolor.snap |  39 +++++
 codex-rs/tui/src/ui_tree/render.rs            |  30 ++--
 codex-rs/tui/src/ui_tree/theme.rs             |  77 ++++++++-
 codex-rs/tui/src/ui_tree_tests.rs             | 162 ++++++++++++++++--
 9 files changed, 366 insertions(+), 47 deletions(-)
 create mode 100644 codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_ansi16.snap
 create mode 100644 codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_truecolor.snap

diff --git a/codex-rs/tui/src/bottom_pane/footer/footer_content.rs b/codex-rs/tui/src/bottom_pane/footer/footer_content.rs
index 05ce7ddd51..5fff31b0bd 100644
--- a/codex-rs/tui/src/bottom_pane/footer/footer_content.rs
+++ b/codex-rs/tui/src/bottom_pane/footer/footer_content.rs
@@ -7,6 +7,7 @@ use ratatui::text::Line;
 use ratatui::widgets::Widget;
 
 use crate::line_truncation::truncate_line_with_ellipsis_if_overflow;
+use crate::render::highlight::with_syntax_theme;
 use crate::terminal_hyperlinks::HyperlinkLine;
 use crate::ui_tree::UiTree;
 
@@ -24,7 +25,9 @@ impl FooterContent {
         let width = match self {
             Self::Line(line) => line.width(),
             Self::HyperlinkLine(line) => line.width(),
-            Self::Extension { content } => content.render_line(u16::MAX).width(),
+            Self::Extension { content } => {
+                with_syntax_theme(|theme| content.render_line(u16::MAX, theme)).width()
+            }
         };
         u16::try_from(width).unwrap_or(u16::MAX)
     }
@@ -33,7 +36,10 @@ impl FooterContent {
     pub(crate) fn render(self, area: Rect, buf: &mut Buffer) {
         match self {
             Self::Line(line) => Widget::render(line, area, buf),
-            Self::Extension { content } => content.render_line(area.width).render_fitted(area, buf),
+            Self::Extension { content } => {
+                with_syntax_theme(|theme| content.render_line(area.width, theme))
+                    .render_fitted(area, buf)
+            }
             Self::HyperlinkLine(mut line) => {
                 let area = Rect {
                     height: area.height.min(1),
@@ -55,7 +61,9 @@ impl FooterContent {
         match self {
             Self::Line(line) => line.into(),
             Self::HyperlinkLine(line) => line,
-            Self::Extension { content } => content.render_line(u16::MAX),
+            Self::Extension { content } => {
+                with_syntax_theme(|theme| content.render_line(u16::MAX, theme))
+            }
         }
     }
 }
diff --git a/codex-rs/tui/src/bottom_pane/mod.rs b/codex-rs/tui/src/bottom_pane/mod.rs
index 006c777a9d..a6f2e71312 100644
--- a/codex-rs/tui/src/bottom_pane/mod.rs
+++ b/codex-rs/tui/src/bottom_pane/mod.rs
@@ -125,6 +125,7 @@ pub(crate) use mcp_server_elicitation::McpServerElicitationFormRequest;
 pub(crate) use mcp_server_elicitation::McpServerElicitationOverlay;
 pub(crate) use request_user_input::RequestUserInputOverlay;
 pub(crate) use status_line_style::STATUS_LINE_SEPARATOR;
+pub(crate) use status_line_style::StatusLineAccent;
 pub(crate) use status_line_style::status_line_from_segments;
 pub(crate) use voice_strip::VoiceStripPhase;
 pub(crate) use voice_strip::VoiceStripState;
diff --git a/codex-rs/tui/src/bottom_pane/status_line_style.rs b/codex-rs/tui/src/bottom_pane/status_line_style.rs
index 571530d1c4..8fa1b120c2 100644
--- a/codex-rs/tui/src/bottom_pane/status_line_style.rs
+++ b/codex-rs/tui/src/bottom_pane/status_line_style.rs
@@ -19,17 +19,27 @@ pub(crate) const STATUS_LINE_SEPARATOR: &str = " · ";
 const STATUS_LINE_COLOR_SATURATION_PERCENT: u16 = 85;
 const STATUS_LINE_COLOR_BRIGHTNESS_PERCENT: u16 = 100;
 
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-enum StatusLineAccent {
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub(crate) enum StatusLineAccent {
+    #[serde(rename = "status-model")]
     Model,
+    #[serde(rename = "status-path")]
     Path,
+    #[serde(rename = "status-branch")]
     Branch,
+    #[serde(rename = "status-state")]
     State,
+    #[serde(rename = "status-usage")]
     Usage,
+    #[serde(rename = "status-limit")]
     Limit,
+    #[serde(rename = "status-metadata")]
     Metadata,
+    #[serde(rename = "status-mode")]
     Mode,
+    #[serde(rename = "status-thread")]
     Thread,
+    #[serde(rename = "status-progress")]
     Progress,
 }
 
@@ -70,7 +80,7 @@ impl StatusLineAccent {
         }
     }
 
-    fn scopes(self) -> &'static [&'static str] {
+    pub(crate) fn scopes(self) -> &'static [&'static str] {
         match self {
             Self::Model => &["entity.name.type", "support.type", "variable"],
             Self::Path => &["string", "markup.underline.link"],
@@ -85,11 +95,11 @@ impl StatusLineAccent {
         }
     }
 
-    fn fallback_style(self) -> Style {
+    pub(crate) fn fallback_color(self) -> Color {
         match self {
-            Self::Model | Self::State | Self::Metadata | Self::Mode => Style::default().cyan(),
-            Self::Path | Self::Usage | Self::Progress => Style::default().green(),
-            Self::Branch | Self::Limit | Self::Thread => Style::default().magenta(),
+            Self::Model | Self::State | Self::Metadata | Self::Mode => Color::Cyan,
+            Self::Path | Self::Usage | Self::Progress => Color::Green,
+            Self::Branch | Self::Limit | Self::Thread => Color::Magenta,
         }
     }
 }
@@ -142,7 +152,8 @@ where
         } else if use_theme_colors {
             let accent = StatusLineAccent::for_item(item);
             soften_status_line_style(
-                theme_style_for_accent(accent).unwrap_or_else(|| accent.fallback_style()),
+                theme_style_for_accent(accent)
+                    .unwrap_or_else(|| Style::default().fg(accent.fallback_color())),
             )
         } else {
             secondary_text_style()
@@ -152,7 +163,7 @@ where
             if effective_stdout_color_level() == StdoutColorLevel::Ansi16
                 && matches!(foreground, Color::Rgb(..) | Color::Indexed(16..))
             {
-                style.patch(StatusLineAccent::for_item(item).fallback_style())
+                style.fg(StatusLineAccent::for_item(item).fallback_color())
             } else {
                 style.fg(readable_color_on(foreground, /*background*/ None))
             }
diff --git a/codex-rs/tui/src/render/highlight.rs b/codex-rs/tui/src/render/highlight.rs
index 41b1d239c1..26c21acabe 100644
--- a/codex-rs/tui/src/render/highlight.rs
+++ b/codex-rs/tui/src/render/highlight.rs
@@ -290,11 +290,16 @@ pub(crate) fn syntax_theme_revision() -> u64 {
 
 /// Clone the current syntax theme (e.g. to save for cancel-restore).
 pub(crate) fn current_syntax_theme() -> Theme {
+    with_syntax_theme(Theme::clone)
+}
+
+/// Borrow the active theme for one synchronous render operation.
+pub(crate) fn with_syntax_theme<T>(f: impl FnOnce(&Theme) -> T) -> T {
     let active_theme = theme_lock();
-    match active_theme.read() {
-        Ok(theme) => theme.clone(),
-        Err(poisoned) => poisoned.into_inner().clone(),
-    }
+    let theme = active_theme
+        .read()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    f(&theme)
 }
 
 /// An explicit diff background, including the ANSI terminal-default marker.
@@ -366,11 +371,18 @@ pub(crate) fn foreground_style_for_scopes_with_theme(
     theme: &Theme,
     scope_names: &[&str],
 ) -> Option<Style> {
-    let highlighter = Highlighter::new(theme);
+    foreground_color_for_scopes(&Highlighter::new(theme), scope_names)
+        .map(|fg| Style::default().fg(fg))
+}
+
+pub(crate) fn foreground_color_for_scopes(
+    highlighter: &Highlighter<'_>,
+    scope_names: &[&str],
+) -> Option<RtColor> {
     scope_names.iter().find_map(|scope_name| {
         let scope = Scope::new(scope_name).ok()?;
         let fg = highlighter.style_mod_for_stack(&[scope]).foreground?;
-        convert_syntect_color(fg).map(|fg| Style::default().fg(fg))
+        convert_syntect_color(fg)
     })
 }
 
diff --git a/codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_ansi16.snap b/codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_ansi16.snap
new file mode 100644
index 0000000000..fb778f8237
--- /dev/null
+++ b/codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_ansi16.snap
@@ -0,0 +1,37 @@
+---
+source: tui/src/ui_tree_tests.rs
+expression: paint_semantic_samples()
+---
+Buffer {
+    area: Rect { x: 0, y: 0, width: 5, height: 1 },
+    content: [
+        "pabid",
+    ],
+    styles: [
+        x: 0, y: 0, fg: Reset, bg: Reset, underline: Reset, modifier: NONE,
+        x: 2, y: 0, fg: Magenta, bg: Reset, underline: Reset, modifier: NONE,
+        x: 3, y: 0, fg: Magenta, bg: Magenta, underline: Reset, modifier: NONE,
+    ]
+}
+Buffer {
+    area: Rect { x: 0, y: 0, width: 5, height: 1 },
+    content: [
+        "pabid",
+    ],
+    styles: [
+        x: 0, y: 0, fg: Reset, bg: Reset, underline: Reset, modifier: NONE,
+        x: 2, y: 0, fg: Magenta, bg: Reset, underline: Reset, modifier: NONE,
+        x: 3, y: 0, fg: Magenta, bg: Magenta, underline: Reset, modifier: NONE,
+    ]
+}
+Buffer {
+    area: Rect { x: 0, y: 0, width: 5, height: 1 },
+    content: [
+        "pabid",
+    ],
+    styles: [
+        x: 0, y: 0, fg: Reset, bg: Reset, underline: Reset, modifier: NONE,
+        x: 2, y: 0, fg: Magenta, bg: Reset, underline: Reset, modifier: NONE,
+        x: 3, y: 0, fg: Magenta, bg: Magenta, underline: Reset, modifier: NONE,
+    ]
+}
diff --git a/codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_truecolor.snap b/codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_truecolor.snap
new file mode 100644
index 0000000000..8e04b3d8d4
--- /dev/null
+++ b/codex-rs/tui/src/snapshots/codex_tui__ui_tree__tests__semantic_statusline_truecolor.snap
@@ -0,0 +1,39 @@
+---
+source: tui/src/ui_tree_tests.rs
+expression: paint_semantic_samples()
+---
+Buffer {
+    area: Rect { x: 0, y: 0, width: 5, height: 1 },
+    content: [
+        "pabid",
+    ],
+    styles: [
+        x: 0, y: 0, fg: Rgb(220, 221, 222), bg: Rgb(0, 0, 0), underline: Reset, modifier: NONE,
+        x: 1, y: 0, fg: Rgb(0, 200, 80), bg: Rgb(0, 0, 0), underline: Reset, modifier: NONE,
+        x: 2, y: 0, fg: Rgb(230, 230, 230), bg: Rgb(0, 0, 0), underline: Reset, modifier: NONE,
+        x: 3, y: 0, fg: Rgb(230, 230, 230), bg: Rgb(230, 230, 230), underline: Reset, modifier: NONE,
+    ]
+}
+Buffer {
+    area: Rect { x: 0, y: 0, width: 5, height: 1 },
+    content: [
+        "pabid",
+    ],
+    styles: [
+        x: 0, y: 0, fg: Rgb(1, 2, 3), bg: Rgb(255, 255, 255), underline: Reset, modifier: NONE,
+        x: 1, y: 0, fg: Reset, bg: Rgb(255, 255, 255), underline: Reset, modifier: NONE,
+        x: 2, y: 0, fg: Rgb(80, 0, 120), bg: Rgb(255, 255, 255), underline: Reset, modifier: NONE,
+        x: 3, y: 0, fg: Rgb(80, 0, 120), bg: Rgb(80, 0, 120), underline: Reset, modifier: NONE,
+    ]
+}
+Buffer {
+    area: Rect { x: 0, y: 0, width: 5, height: 1 },
+    content: [
+        "pabid",
+    ],
+    styles: [
+        x: 0, y: 0, fg: Reset, bg: Reset, underline: Reset, modifier: NONE,
+        x: 2, y: 0, fg: Magenta, bg: Reset, underline: Reset, modifier: NONE,
+        x: 3, y: 0, fg: Magenta, bg: Magenta, underline: Reset, modifier: NONE,
+    ]
+}
diff --git a/codex-rs/tui/src/ui_tree/render.rs b/codex-rs/tui/src/ui_tree/render.rs
index 2704a76420..8c1c6247e6 100644
--- a/codex-rs/tui/src/ui_tree/render.rs
+++ b/codex-rs/tui/src/ui_tree/render.rs
@@ -5,6 +5,7 @@ use super::TextProps;
 use super::TextWeight;
 use super::UiNode;
 use super::UiTree;
+use super::theme::RenderTheme;
 use crate::history_cell::sanitize_user_text;
 use crate::line_truncation::truncate_line_with_ellipsis;
 use crate::terminal_hyperlinks::HyperlinkLine;
@@ -12,15 +13,16 @@ use crate::terminal_hyperlinks::TerminalHyperlink;
 use ratatui::style::Modifier;
 use ratatui::style::Style;
 use ratatui::text::Span;
+use syntect::highlighting::Theme;
 
 impl UiTree {
     /// Render one row. On overflow, fit an unlinked ellipsis inside the supplied width.
-    pub(crate) fn render_line(&self, width: u16) -> HyperlinkLine {
+    pub(crate) fn render_line(&self, width: u16, theme: &Theme) -> HyperlinkLine {
         let width = usize::from(width);
         let Some(root) = self.0.as_ref().filter(|_| width > 0) else {
             return HyperlinkLine::default();
         };
-        let mut line = node_line(root, width, Style::default());
+        let mut line = node_line(root, width, Style::default(), &RenderTheme::new(theme));
         if line.width() > width {
             line.line = truncate_line_with_ellipsis(line.line, width);
             line.clip_hyperlinks_to_width(line.width() - 1);
@@ -29,7 +31,7 @@ impl UiTree {
     }
 }
 
-fn node_line(node: &UiNode, width: usize, style: Style) -> HyperlinkLine {
+fn node_line(node: &UiNode, width: usize, style: Style, theme: &RenderTheme<'_>) -> HyperlinkLine {
     let (children, gap, style) = match node {
         UiNode::String(raw) => {
             // Built-in values are constructed directly, bypassing the wire decoder.
@@ -39,7 +41,7 @@ fn node_line(node: &UiNode, width: usize, style: Style) -> HyperlinkLine {
             return HyperlinkLine::new(Span::styled(visible, style).into());
         }
         UiNode::Link { props, children } => {
-            let mut line = row_line(children, /*gap*/ 0, width, style.underlined());
+            let mut line = row_line(children, /*gap*/ 0, width, style.underlined(), theme);
             let width = line.width();
             if width > 0 {
                 line.hyperlinks = vec![TerminalHyperlink::web(0..width, props.href.0.clone())];
@@ -50,22 +52,28 @@ fn node_line(node: &UiNode, width: usize, style: Style) -> HyperlinkLine {
             let style = props
                 .background
                 .as_ref()
-                .map_or(style, |color| style.bg(color.resolve()));
+                .map_or(style, |color| style.bg(color.resolve(theme)));
             (children, props.gap, style)
         }
-        UiNode::Text { props, children } => (children, 0, props.style(style)),
+        UiNode::Text { props, children } => (children, 0, props.style(style, theme)),
         UiNode::Bold { children } => (children, 0, style.bold()),
         UiNode::Italic { children } => (children, 0, style.italic()),
         UiNode::Underline { children } => (children, 0, style.underlined()),
     };
-    row_line(children, gap, width, style)
+    row_line(children, gap, width, style, theme)
 }
 
-fn row_line(children: &[Option<UiNode>], gap: u64, width: usize, style: Style) -> HyperlinkLine {
+fn row_line(
+    children: &[Option<UiNode>],
+    gap: u64,
+    width: usize,
+    style: Style,
+    theme: &RenderTheme<'_>,
+) -> HyperlinkLine {
     let mut result = HyperlinkLine::default();
     let mut used = 0;
     for child in children.iter().flatten() {
-        let child = node_line(child, width, style);
+        let child = node_line(child, width, style, theme);
         let child_width = child.width();
         if child_width == 0 {
             continue;
@@ -95,9 +103,9 @@ fn row_line(children: &[Option<UiNode>], gap: u64, width: usize, style: Style) -
 }
 
 impl TextProps {
-    fn style(&self, mut style: Style) -> Style {
+    fn style(&self, mut style: Style, theme: &RenderTheme<'_>) -> Style {
         if let Some(color) = &self.color {
-            style = style.fg(color.resolve());
+            style = style.fg(color.resolve(theme));
         }
         for (enabled, modifier) in [
             (
diff --git a/codex-rs/tui/src/ui_tree/theme.rs b/codex-rs/tui/src/ui_tree/theme.rs
index 1efa59949d..78c963ca8b 100644
--- a/codex-rs/tui/src/ui_tree/theme.rs
+++ b/codex-rs/tui/src/ui_tree/theme.rs
@@ -1,13 +1,59 @@
-//! Literal provider colors use the terminal's palette at paint time.
+//! Resolve typed wire colors against the active theme and terminal palette.
 
-use crate::terminal_palette;
 use ratatui::style::Color as TerminalColor;
 use serde::Deserialize;
 use serde::Serialize;
 
+use crate::bottom_pane::StatusLineAccent;
+use crate::render::highlight;
+use crate::terminal_palette;
+use crate::terminal_palette::StdoutColorLevel;
+use std::cell::OnceCell;
+use syntect::highlighting::Highlighter;
+use syntect::highlighting::Theme;
+use syntect::parsing::Scope;
+
+pub(super) struct RenderTheme<'a> {
+    theme: &'a Theme,
+    highlighter: OnceCell<Highlighter<'a>>,
+}
+
+impl<'a> RenderTheme<'a> {
+    pub(super) fn new(theme: &'a Theme) -> Self {
+        Self {
+            theme,
+            highlighter: OnceCell::new(),
+        }
+    }
+
+    // Plain text and literal colors need no TextMate scope matching.
+    fn highlighter(&self) -> &Highlighter<'a> {
+        self.highlighter
+            .get_or_init(|| Highlighter::new(self.theme))
+    }
+}
+
+fn terminal_color(color: Option<TerminalColor>, fallback: TerminalColor) -> TerminalColor {
+    let Some(color) = color else { return fallback };
+    let level = terminal_palette::effective_stdout_color_level();
+    match (level, color) {
+        (
+            StdoutColorLevel::Ansi16 | StdoutColorLevel::Unknown,
+            TerminalColor::Rgb(..) | TerminalColor::Indexed(16..),
+        ) => fallback,
+        (_, TerminalColor::Rgb(r, g, b)) => {
+            terminal_palette::best_color_for_level((r, g, b), level)
+        }
+        _ => color,
+    }
+}
+
 #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub(super) enum Color {
+    Primary,
+    Surface,
+    Accent,
     Black,
     Red,
     Green,
@@ -17,12 +63,37 @@ pub(super) enum Color {
     Cyan,
     White,
     #[serde(untagged)]
+    Status(StatusLineAccent),
+    #[serde(untagged)]
     Rgb(HexRgb),
 }
 
 impl Color {
-    pub(super) fn resolve(&self) -> TerminalColor {
+    pub(super) fn resolve(&self, palette: &RenderTheme<'_>) -> TerminalColor {
+        let setting = |color: Option<syntect::highlighting::Color>| {
+            terminal_color(
+                color.and_then(highlight::convert_syntect_color),
+                TerminalColor::Reset,
+            )
+        };
         match self {
+            Self::Primary => setting(palette.theme.settings.foreground),
+            Self::Surface => setting(palette.theme.settings.background),
+            Self::Accent => setting(
+                Scope::new("codex.accent")
+                    .ok()
+                    .and_then(|scope| {
+                        palette
+                            .highlighter()
+                            .style_mod_for_stack(&[scope])
+                            .foreground
+                    })
+                    .or(palette.theme.settings.accent),
+            ),
+            Self::Status(role) => terminal_color(
+                highlight::foreground_color_for_scopes(palette.highlighter(), role.scopes()),
+                role.fallback_color(),
+            ),
             Self::Rgb(rgb) => terminal_palette::best_color(rgb.0),
             Self::Black => TerminalColor::Black,
             Self::Red => TerminalColor::Red,
diff --git a/codex-rs/tui/src/ui_tree_tests.rs b/codex-rs/tui/src/ui_tree_tests.rs
index 28ed4227ed..5589532647 100644
--- a/codex-rs/tui/src/ui_tree_tests.rs
+++ b/codex-rs/tui/src/ui_tree_tests.rs
@@ -6,6 +6,7 @@ use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
 use serde_json::Value;
 use serde_json::json;
+use syntect::highlighting::Theme;
 
 fn parse(value: Value) -> serde_json::Result<UiTree> {
     value.to_string().parse()
@@ -28,7 +29,12 @@ fn elements_round_trip_and_require_explicit_row_spacing() {
     }
     for (gap, expected) in [(0, "AB"), (1, "A B"), (2, "A  B"), (MAX_GAP, "A  …")] {
         let row = tree(json!({"type":"row","props":{"gap":gap},"children":["A","B"]}));
-        assert_eq!(row.render_line(/*width*/ 4).line.to_string(), expected);
+        assert_eq!(
+            row.render_line(/*width*/ 4, &Theme::default())
+                .line
+                .to_string(),
+            expected
+        );
     }
 }
 
@@ -93,7 +99,7 @@ fn links_only_annotate_their_own_cells() {
         /*x*/ 0, /*y*/ 0, /*width*/ 16, /*height*/ 1,
     );
     let mut buffer = Buffer::empty(area);
-    tree.render_line(area.width)
+    tree.render_line(area.width, &Theme::default())
         .render_fitted(area, &mut buffer);
     assert_eq!(buffer[(0, 0)].symbol(), "界");
     assert!(
@@ -103,12 +109,17 @@ fn links_only_annotate_their_own_cells() {
     );
     insta::assert_snapshot!(format!("{buffer:?}"));
 
-    assert_eq!(tree.render_line(/*width*/ 1).line.to_string(), "…");
+    assert_eq!(
+        tree.render_line(/*width*/ 1, &Theme::default())
+            .line
+            .to_string(),
+        "…"
+    );
     let narrow = Rect::new(
         /*x*/ 0, /*y*/ 0, /*width*/ 6, /*height*/ 2,
     );
     let mut buffer = Buffer::empty(narrow);
-    tree.render_line(narrow.width)
+    tree.render_line(narrow.width, &Theme::default())
         .render_fitted(narrow, &mut buffer);
     assert!(
         buffer[(4, 0)]
@@ -126,7 +137,7 @@ fn render_line_keeps_exactly_fitting_halfwidth_voiced_katakana() {
         /*x*/ 0, /*y*/ 0, /*width*/ 2, /*height*/ 1,
     );
     let mut buffer = Buffer::empty(area);
-    text.render_line(area.width)
+    text.render_line(area.width, &Theme::default())
         .render_fitted(area, &mut buffer);
     assert_eq!(buffer[(0, 0)].symbol(), "ｶﾞ");
 }
@@ -135,16 +146,21 @@ fn render_line_keeps_exactly_fitting_halfwidth_voiced_katakana() {
 fn ellipsis_counts_toward_width_only_when_there_is_overflow() {
     let row = tree(json!({"type":"row","props":{"gap":1},"children":["abcde", null]}));
     for (width, expected) in [(0, ""), (1, "…"), (4, "abc…"), (5, "abcde")] {
-        let line = row.render_line(width);
+        let line = row.render_line(width, &Theme::default());
         assert_eq!(line.line.to_string(), expected);
         assert!(line.width() <= usize::from(width));
     }
     let wide = tree(json!("a界界"));
-    assert_eq!(wide.render_line(/*width*/ 4).line.to_string(), "a界…");
+    assert_eq!(
+        wide.render_line(/*width*/ 4, &Theme::default())
+            .line
+            .to_string(),
+        "a界…"
+    );
     let long = "x".repeat(513);
     assert_eq!(
         tree(json!(&long))
-            .render_line(/*width*/ 513)
+            .render_line(/*width*/ 513, &Theme::default())
             .line
             .to_string(),
         long
@@ -157,19 +173,37 @@ fn first_line_skips_hidden_text_before_rendering_its_sibling() {
     let tree = tree(json!({"type":"row","props":{"gap":0},"children":[
         &multiline, "!"
     ]}));
-    assert_eq!(tree.render_line(/*width*/ 4).line.to_string(), "ok!");
+    assert_eq!(
+        tree.render_line(/*width*/ 4, &Theme::default())
+            .line
+            .to_string(),
+        "ok!"
+    );
 }
 
 #[test]
 fn directly_constructed_text_keeps_a_bounded_utf8_prefix() {
     let prefix = "x".repeat(MAX_TEXT_BYTES - 1);
     let text = UiTree(Some(UiNode::String(format!("{prefix}界tail"))));
-    assert_eq!(text.render_line(u16::MAX).line.to_string(), prefix);
+    assert_eq!(
+        text.render_line(u16::MAX, &Theme::default())
+            .line
+            .to_string(),
+        prefix
+    );
 }
 
 #[test]
-fn text_and_row_share_the_literal_color_contract() {
-    for color in ["red", "white", "#ab12f0"] {
+fn text_and_row_share_the_color_contract() {
+    for color in [
+        "red",
+        "white",
+        "#ab12f0",
+        "primary",
+        "accent",
+        "surface",
+        "status-branch",
+    ] {
         let value = json!({"type":"row","props":{"gap":0,"background":color},"children":[
             {"type":"text","props":{"color":color,"weight":"bold","italic":true,"underline":false},"children":["ok"]}
         ]});
@@ -210,7 +244,7 @@ fn inline_modifiers_and_row_surfaces_follow_the_tree() {
             {"type":"link","props":{"href":"https://example.com"},"children":["f"]}
         ]
     }));
-    let clipped = node.render_line(/*width*/ 6);
+    let clipped = node.render_line(/*width*/ 6, &Theme::default());
     assert_eq!(
         clipped.line.spans.last().unwrap(),
         &ratatui::text::Span::styled(
@@ -218,7 +252,7 @@ fn inline_modifiers_and_row_surfaces_follow_the_tree() {
             ratatui::style::Style::default().bg(ratatui::style::Color::Blue),
         )
     );
-    let line = node.render_line(/*width*/ 12);
+    let line = node.render_line(/*width*/ 12, &Theme::default());
     let area = Rect::new(
         /*x*/ 0, /*y*/ 0, /*width*/ 12, /*height*/ 1,
     );
@@ -240,7 +274,7 @@ fn hex_colors_use_the_terminal_palette_for_both_channels() {
             bg: (0, 0, 0),
         },
         || {
-            let line = tree.render_line(/*width*/ 3);
+            let line = tree.render_line(/*width*/ 3, &Theme::default());
             let colors: Vec<_> = line
                 .line
                 .spans
@@ -256,3 +290,101 @@ fn hex_colors_use_the_terminal_palette_for_both_channels() {
         },
     );
 }
+
+#[test]
+fn semantic_colors_follow_the_theme_and_terminal() {
+    use crate::terminal_palette::with_test_default_colors;
+    use crate::terminal_probe::DefaultColors;
+
+    const CHILD: &str = "CODEX_STATUSLINE_SEMANTIC_PALETTE_TEST";
+    if std::env::var_os(CHILD).is_some() {
+        insta::assert_snapshot!("semantic_statusline_ansi16", paint_semantic_samples());
+        return;
+    }
+    let limited = std::process::Command::new(std::env::current_exe().unwrap())
+        .args([
+            "--exact",
+            "ui_tree::tests::semantic_colors_follow_the_theme_and_terminal",
+        ])
+        .env(CHILD, "1")
+        .env("FORCE_COLOR", "1")
+        .output()
+        .unwrap();
+    with_test_default_colors(
+        DefaultColors {
+            fg: (255, 255, 255),
+            bg: (0, 0, 0),
+        },
+        || {
+            insta::assert_snapshot!("semantic_statusline_truecolor", paint_semantic_samples());
+        },
+    );
+    assert!(
+        limited.status.success(),
+        "{}",
+        String::from_utf8_lossy(&limited.stdout)
+    );
+}
+
+fn paint_semantic_samples() -> String {
+    use ratatui::style::Color as TerminalColor;
+    use ratatui::style::Style;
+    use syntect::highlighting::Color;
+    use syntect::highlighting::StyleModifier;
+    use syntect::highlighting::ThemeItem;
+
+    let node = tree(
+        json!({"type":"row","props":{"gap":0,"background":"surface"},"children":[
+            {"type":"text","props":{"color":"primary"},"children":["p"]},
+            {"type":"text","props":{"color":"accent"},"children":["a"]},
+            {"type":"text","props":{"color":"status-branch"},"children":["b",
+                {"type":"row","props":{"gap":0,"background":"status-branch"},"children":["i",
+                    {"type":"text","props":{"color":"status-branch"},"children":["d"]}]}]}
+        ]}),
+    );
+    let rgb = |r, g, b| Color { r, g, b, a: 255 };
+    let scope = |name: &str, color| ThemeItem {
+        scope: name.parse().unwrap(),
+        style: StyleModifier {
+            foreground: Some(color),
+            ..Default::default()
+        },
+    };
+    let mut dark = Theme::default();
+    dark.settings.background = Some(rgb(0, 0, 0));
+    dark.settings.foreground = Some(rgb(220, 221, 222));
+    dark.settings.accent = Some(rgb(0, 200, 80));
+    dark.scopes
+        .push(scope("entity.name.function", rgb(230, 230, 230)));
+    let mut light = Theme::default();
+    light.settings.background = Some(rgb(255, 255, 255));
+    light.settings.foreground = Some(rgb(1, 2, 3));
+    light.settings.accent = dark.settings.accent;
+    light.scopes.push(scope(
+        "codex.accent",
+        Color {
+            a: 1,
+            ..Color::BLACK
+        },
+    ));
+    light
+        .scopes
+        .push(scope("entity.name.function", rgb(80, 0, 120)));
+    let area = Rect::new(
+        /*x*/ 0, /*y*/ 0, /*width*/ 5, /*height*/ 1,
+    );
+    let mut samples = Vec::new();
+    for theme in [dark, light, Theme::default()] {
+        let mut buffer = Buffer::empty(area);
+        buffer.set_style(
+            area,
+            Style::default()
+                .fg(TerminalColor::Yellow)
+                .bg(TerminalColor::Blue),
+        );
+        node.render_line(area.width, &theme)
+            .render_fitted(area, &mut buffer);
+        samples.push(format!("{buffer:?}"));
+    }
+    samples.join("\n")
+}