feat(theme): notify apps of color-scheme change via DECSET 2031

Apps that set terminal colors had to be restarted to pick up a theme
change. Implement the DECSET 2031 light/dark notification so subscribed
apps (helix, neovim) re-query colors and repaint live.

Uses the DSR wire format per the contour spec, not OSC:
- DECSET 2031 (DECSET/DECRST/DECRQM) opts in to notifications
- on theme change, push unsolicited CSI ? 997 ; <1 dark|2 light> n
- answer the CSI ? 996 n query with the stored scheme (ungated)

Polarity comes from the resolved OS appearance / [adaptive-theme],
threaded through update_config and Screen::new — not inferred from
background luminance. New panes inherit the manager's current scheme.

Author: flukejones

frontends/rioterm/src/application.rs

@@ -14,6 +14,7 @@ use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
 use raw_window_handle::HasDisplayHandle;
 use rio_backend::clipboard::{Clipboard, ClipboardType};
 use rio_backend::config::colors::{ColorRgb, NamedColor};
+use rio_backend::config::theme::AppearanceTheme;
 use rio_window::application::ApplicationHandler;
 use rio_window::event::{
     ElementState, Ime, MouseButton, MouseScrollDelta, StartCause, TouchPhase, WindowEvent,
@@ -392,17 +393,19 @@ impl ApplicationHandler<EventPayload> for Application<'_> {
 
                 self.config = config;
 
+                let color_scheme = self.config.force_theme.or_else(|| {
+                    event_loop
+                        .system_theme()
+                        .map(AppearanceTheme::from_window_theme)
+                });
                 let mut has_checked_adaptive_colors = false;
                 for (_id, route) in self.router.routes.iter_mut() {
                     // Apply system theme to ensure colors are consistent
                     if !has_checked_adaptive_colors {
-                        let system_theme = event_loop.system_theme();
-                        let theme = self
-                            .config
-                            .force_theme
-                            .map(|t| t.to_window_theme())
-                            .or(system_theme);
-                        update_colors_based_on_theme(&mut self.config, theme);
+                        update_colors_based_on_theme(
+                            &mut self.config,
+                            color_scheme.map(AppearanceTheme::to_window_theme),
+                        );
                         has_checked_adaptive_colors = true;
                     }
 
@@ -422,6 +425,7 @@ impl ApplicationHandler<EventPayload> for Application<'_> {
                         &self.config,
                         &self.router.font_library,
                         has_font_updates,
+                        color_scheme,
                     );
                     route.window.configure_window(&self.config);
 
@@ -854,7 +858,6 @@ impl ApplicationHandler<EventPayload> for Application<'_> {
             }
             RioEventType::Rio(RioEvent::ToggleAppearanceTheme) => {
                 if let Some(route) = self.router.routes.get_mut(&window_id) {
-                    use rio_backend::config::theme::AppearanceTheme;
                     let current = self
                         .config
                         .force_theme
@@ -876,6 +879,7 @@ impl ApplicationHandler<EventPayload> for Application<'_> {
                         &self.config,
                         &self.router.font_library,
                         false,
+                        Some(toggled),
                     );
                     route.window.configure_window(&self.config);
                 }
@@ -1796,6 +1800,7 @@ impl ApplicationHandler<EventPayload> for Application<'_> {
                     &self.config,
                     &self.router.font_library,
                     false,
+                    Some(AppearanceTheme::from_window_theme(new_theme)),
                 );
                 route.window.configure_window(&self.config);
             }

frontends/rioterm/src/context/mod.rs

@@ -134,6 +134,9 @@ pub struct ContextManagerConfig {
     pub title: rio_backend::config::title::Title,
     pub keyboard: rio_backend::config::keyboard::Keyboard,
     pub scrollback_history_limit: usize,
+    /// Initial color-scheme polarity for new panes, so the
+    /// `CSI ? 996 n` query answers correctly before any theme change.
+    pub color_scheme_is_dark: bool,
 }
 
 const DEFAULT_CONTEXT_CAPACITY: usize = 28;
@@ -245,6 +248,7 @@ impl<T: EventListener + Clone + std::marker::Send + 'static> ContextManager<T> {
             config.scrollback_history_limit,
         );
         terminal.blinking_cursor = cursor_state.1;
+        terminal.set_color_scheme(config.color_scheme_is_dark);
         let terminal: Arc<FairMutex<Crosswords<T>>> = Arc::new(FairMutex::new(terminal));
 
         let pty;
@@ -1057,6 +1061,7 @@ impl<T: EventListener + Clone + std::marker::Send + 'static> ContextManager<T> {
             title: config.title,
             keyboard: config.keyboard,
             scrollback_history_limit: config.scrollback_history_limit,
+            color_scheme_is_dark: self.config.color_scheme_is_dark,
         };
 
         let current = self.current();

frontends/rioterm/src/router/mod.rs

@@ -9,6 +9,7 @@ use crate::screen::{Screen, ScreenWindowProperties};
 use assistant::Assistant;
 use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
 use rio_backend::clipboard::Clipboard;
+use rio_backend::config::theme::AppearanceTheme;
 use rio_backend::config::Config as RioConfig;
 use rio_backend::error::{RioError, RioErrorLevel, RioErrorType};
 
@@ -89,10 +90,11 @@ impl Route<'_> {
         config: &RioConfig,
         db: &rio_backend::sugarloaf::font::FontLibrary,
         should_update_font: bool,
+        color_scheme: Option<AppearanceTheme>,
     ) {
         self.window
             .screen
-            .update_config(config, db, should_update_font);
+            .update_config(config, db, should_update_font, color_scheme);
     }
 
     #[inline]
@@ -700,8 +702,18 @@ impl<'a> RouteWindow<'a> {
             window_id: winit_window.id(),
         };
 
-        let screen = Screen::new(properties, config, event_proxy, font_library, open_url)
-            .expect("Screen not created");
+        let color_scheme = config
+            .force_theme
+            .or_else(|| winit_window.theme().map(AppearanceTheme::from_window_theme));
+        let screen = Screen::new(
+            properties,
+            config,
+            event_proxy,
+            font_library,
+            open_url,
+            color_scheme,
+        )
+        .expect("Screen not created");
 
         if config.window.columns.is_some() || config.window.rows.is_some() {
             let (physical_width, physical_height) = compute_window_size_from_grid(

frontends/rioterm/src/screen/mod.rs

@@ -36,6 +36,7 @@ use rio_backend::clipboard::Clipboard;
 use rio_backend::clipboard::ClipboardType;
 use rio_backend::config::layout::Margin;
 use rio_backend::config::renderer::Backend;
+use rio_backend::config::theme::AppearanceTheme;
 use rio_backend::crosswords::pos::{Boundary, CursorState, Direction, Line};
 use rio_backend::crosswords::search::RegexSearch;
 use rio_backend::error::{RioError, RioErrorLevel, RioErrorType};
@@ -101,6 +102,7 @@ impl Screen<'_> {
         event_proxy: EventProxy,
         font_library: &rio_backend::sugarloaf::font::FontLibrary,
         open_url: Option<String>,
+        color_scheme: Option<AppearanceTheme>,
     ) -> Result<Screen<'screen>, Box<dyn Error>> {
         let size = window_properties.size;
         let scale = window_properties.scale;
@@ -210,6 +212,7 @@ impl Screen<'_> {
             title: config.title.clone(),
             keyboard: config.keyboard,
             scrollback_history_limit: config.scrollback_history_limit,
+            color_scheme_is_dark: !matches!(color_scheme, Some(AppearanceTheme::Light)),
         };
 
         let rich_text_id = next_rich_text_id();
@@ -392,6 +395,7 @@ impl Screen<'_> {
         config: &rio_backend::config::Config,
         font_library: &rio_backend::sugarloaf::font::FontLibrary,
         should_update_font_library: bool,
+        color_scheme: Option<AppearanceTheme>,
     ) {
         let num_tabs = self.ctx().len();
         let padding_y_top = padding_top_from_config(
@@ -402,15 +406,16 @@ impl Screen<'_> {
         );
         let padding_y_bottom = config.margin.bottom;
 
+        // Resolved OS/adaptive scheme drives the DECSET 2031 notify.
+        let scheme_is_dark = !matches!(color_scheme, Some(AppearanceTheme::Light));
+        let color_scheme_changed =
+            self.context_manager.config.color_scheme_is_dark != scheme_is_dark;
+
         if should_update_font_library {
             self.sugarloaf.update_font(font_library);
-            // Drop the grid rasterizer's font_id-keyed caches —
-            // the new library reuses the same ids, so stale handles
-            // and ascents would survive the swap.
+            // New library reuses the same font_ids, so font_id-keyed
+            // caches must be dropped or they serve old-font data.
             self.grid_rasterizer.reset_font_caches();
-            // Each panel's grid atlas caches glyph bitmaps by
-            // (font_id, glyph_id, size); the new font reuses font_ids,
-            // so stale slots would serve the wrong glyph. Flush them.
             for grid in self.grids.values_mut() {
                 grid.clear_glyph_cache();
             }
@@ -466,12 +471,8 @@ impl Screen<'_> {
                 let mut terminal = current_context.terminal.lock();
                 current_context.renderable_content =
                     RenderableContent::from_cursor_config(&config.cursor);
-                // Resetting renderable_content clears term_colors and
-                // the dirty flag. Force a full repaint per pane so every
-                // pane (not just the focused one) picks up the new theme
-                // — the render loop skips non-dirty panes, and
-                // resize_all_contexts only repaints via the PTY wakeup,
-                // which idle panes never get.
+                // Idle panes are skipped by the render loop, so force a
+                // full repaint or they keep the old theme.
                 current_context
                     .renderable_content
                     .pending_update
@@ -480,6 +481,10 @@ impl Screen<'_> {
                 terminal.cursor_shape = shape;
                 terminal.default_cursor_shape = shape;
                 terminal.blinking_cursor = config.cursor.blinking;
+                terminal.set_color_scheme(scheme_is_dark);
+                if color_scheme_changed {
+                    terminal.report_color_scheme(scheme_is_dark);
+                }
                 drop(terminal);
             }
         }
@@ -489,6 +494,9 @@ impl Screen<'_> {
 
         // Update keyboard config in context manager
         self.context_manager.config.keyboard = config.keyboard;
+        // Panes spawned after a theme change must start with the new
+        // scheme so their `CSI ? 996 n` query answers correctly.
+        self.context_manager.config.color_scheme_is_dark = scheme_is_dark;
 
         // Re-evaluate the opaque flag — toggling `window.opacity` /
         // `window.blur` at runtime should flip the compositor mode.

rio-backend/src/ansi/mode.rs

@@ -69,6 +69,7 @@ impl PrivateMode {
             1049 => Self::Named(NamedPrivateMode::SwapScreenAndSetRestoreCursor),
             2004 => Self::Named(NamedPrivateMode::BracketedPaste),
             2026 => Self::Named(NamedPrivateMode::SyncUpdate),
+            2031 => Self::Named(NamedPrivateMode::ColorSchemeUpdates),
             _ => Self::Unknown(mode),
         }
     }
@@ -120,6 +121,9 @@ pub enum NamedPrivateMode {
     BracketedPaste = 2004,
     /// The mode is handled automatically by [`Processor`].
     SyncUpdate = 2026,
+    /// App opts in to unsolicited DSR `CSI ? 997 n` light/dark
+    /// color-scheme notifications (DECSET 2031).
+    ColorSchemeUpdates = 2031,
 }
 
 /// Mode for clearing line.