feat: declutter overlays — gate status bar on pause, blank frame behind modals

Two visual-noise fixes for the windowed overlay experience:

1. Status bar now appears only when paused AND no overlay is open. Previously
   it showed whenever paused OR any overlay was open, cluttering the screen
   behind modals. on_pause() no longer expands chrome while an overlay is open,
   and on_modal_open() leaves the default (Minimal) base chrome collapsed
   instead of forcing ModalPane (persistent Expanded chrome is unchanged).

2. When a modal panel overlaps the window-frame border, the simulation and
   frame are wiped to a clean matte behind it so the panel is the sole focus.
   Panels fully contained within the sim interior leave the sim showing, so the
   blanking only kicks in when the frame would otherwise poke out as noise.
   Added FrameBuffer::fill_background and TerminalRenderer::modal_overlaps_frame,
   wired into both the single- and multi-species render paths.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: tamirelazar

src/terminal/frame_buffer.rs

@@ -146,6 +146,28 @@ impl FrameBuffer {
         }
     }
 
+    /// Resets every cell to the matte background (blank space + background color),
+    /// wiping any simulation content and window frame already drawn. Used to give
+    /// a clean backdrop behind a modal overlay that would otherwise overlap the
+    /// frame border and read as visual noise.
+    pub fn fill_background(&mut self) {
+        let (bg_color_256, bg_color_rgb) = match (self.background_color, self.color_mode) {
+            (Some(bg), ColorMode::TrueColor) => (None, Some(bg)),
+            (Some(bg), _) => (Some(palette::rgb_to_256(bg)), None),
+            (None, _) => (None, None),
+        };
+        let blank = Cell {
+            char: ' ',
+            fg_color_256: None,
+            bg_color_256,
+            fg_color_rgb: None,
+            bg_color_rgb,
+        };
+        for cell in &mut self.cells {
+            *cell = blank;
+        }
+    }
+
     #[cfg(test)]
     pub(crate) fn get_cell(&self, x: usize, y: usize) -> &Cell {
         &self.cells[y * self.width + x]

src/terminal/renderer.rs

@@ -640,6 +640,46 @@ impl TerminalRenderer {
         }
     }
 
+    /// Whether a modal panel overlay overlaps the window-frame border, in which
+    /// case the sim + frame should be wiped to a clean matte behind it.
+    ///
+    /// Returns false when there is no visible frame (fullscreen / no layout), so
+    /// the simulation always shows through when there is no border to clutter.
+    /// A panel "intersects the border" when its rectangle is not fully contained
+    /// within the sim interior — i.e. it reaches into or past the frame ring.
+    fn modal_overlaps_frame(&self, panels: &[Option<(&RenderedOverlay, usize, usize)>]) -> bool {
+        use crate::render::window::FallbackMode;
+        if !self.window_frame.is_visible() {
+            return false;
+        }
+        let Some(layout) = &self.window_layout else {
+            return false;
+        };
+        if matches!(layout.fallback, FallbackMode::Fullscreen) {
+            return false;
+        }
+        let (sx, sy, sw, sh) = (layout.sim_x, layout.sim_y, layout.sim_w, layout.sim_h);
+        panels.iter().flatten().any(|(overlay, x, y)| {
+            let w = overlay
+                .lines
+                .iter()
+                .map(|l| l.chars().count())
+                .max()
+                .unwrap_or(0);
+            let h = overlay.lines.len();
+            if w == 0 || h == 0 {
+                return false;
+            }
+            // The floating title box sits one row above the body.
+            let top = y.saturating_sub(usize::from(overlay.title_box.is_some()));
+            let bottom = y + h;
+            let right = x + w;
+            // Fully inside the interior → does not touch the border.
+            let contained = *x >= sx && top >= sy && right <= sx + sw && bottom <= sy + sh;
+            !contained
+        })
+    }
+
     /// Render a frame with text overlays.
     ///
     /// Draws the sim frame, then composites overlays on top in z-order:
@@ -760,39 +800,64 @@ impl TerminalRenderer {
             buffer.apply_pause_effect(pause_style, fc, pause_pulse_draw_mode);
         }
 
-        if let Some(mut grid) = grid_renderer.cloned() {
-            grid.initialize(self.width, self.height);
-
-            // Calculate average brightness for adaptive opacity
-            let total_brightness: f32 = downsampled
-                .iter()
-                .map(|cell| cell.top.max(cell.bottom))
-                .sum();
-            let avg_brightness = if !downsampled.is_empty() && max_trail_value > 0.0 {
-                (total_brightness / (downsampled.len() as f32)) / max_trail_value
-            } else {
-                0.0
-            };
+        // When a modal panel overlaps the window-frame border, wipe the sim + frame
+        // to a clean matte so the panel reads as the sole focus instead of fighting
+        // the border and simulation behind it.
+        let blank_backdrop = self.modal_overlaps_frame(&[
+            controls_lines,
+            dashboard_lines,
+            config_browser_lines,
+            config_save_lines,
+            dirty_guard_lines,
+            keyboard_hints_lines,
+            preset_comparison_lines,
+            palette_editor_overlay,
+        ]);
+
+        if !blank_backdrop {
+            if let Some(mut grid) = grid_renderer.cloned() {
+                grid.initialize(self.width, self.height);
+
+                // Calculate average brightness for adaptive opacity
+                let total_brightness: f32 = downsampled
+                    .iter()
+                    .map(|cell| cell.top.max(cell.bottom))
+                    .sum();
+                let avg_brightness = if !downsampled.is_empty() && max_trail_value > 0.0 {
+                    (total_brightness / (downsampled.len() as f32)) / max_trail_value
+                } else {
+                    0.0
+                };
 
-            for y in 0..self.height {
-                for x in 0..self.width {
-                    if grid.is_grid_position(x, y, self.width, self.height) {
-                        let (on_vertical, on_horizontal) = grid.get_grid_lines(x, y);
-                        let opacity =
-                            grid.calculate_opacity(x, y, self.width, self.height, avg_brightness);
-                        buffer.render_grid_background(
-                            x,
-                            y,
-                            grid.color,
-                            opacity,
-                            on_vertical,
-                            on_horizontal,
-                        );
+                for y in 0..self.height {
+                    for x in 0..self.width {
+                        if grid.is_grid_position(x, y, self.width, self.height) {
+                            let (on_vertical, on_horizontal) = grid.get_grid_lines(x, y);
+                            let opacity = grid.calculate_opacity(
+                                x,
+                                y,
+                                self.width,
+                                self.height,
+                                avg_brightness,
+                            );
+                            buffer.render_grid_background(
+                                x,
+                                y,
+                                grid.color,
+                                opacity,
+                                on_vertical,
+                                on_horizontal,
+                            );
+                        }
                     }
                 }
             }
         }
 
+        if blank_backdrop {
+            buffer.fill_background();
+        }
+
         // Palette accent color used for accented title badges and border.
         let accent = palette::palette_accent_color(
             &self.palette,
@@ -802,7 +867,7 @@ impl TerminalRenderer {
             self.intensity_mapping.as_ref(),
         );
 
-        if self.window_frame.is_visible() {
+        if !blank_backdrop && self.window_frame.is_visible() {
             if let Some(ref layout) = self.window_layout {
                 use crate::render::window::FallbackMode;
                 if !matches!(layout.fallback, FallbackMode::Fullscreen) {
@@ -1180,39 +1245,63 @@ impl TerminalRenderer {
             buffer.apply_pause_effect(pause_style, fc, pause_pulse_draw_mode);
         }
 
-        if let Some(mut grid) = grid_renderer.cloned() {
-            grid.initialize(self.width, self.height);
-
-            // Calculate average brightness from all species combined
-            let total_brightness: f32 = all_downsampled_cells
-                .iter()
-                .map(|cell| cell.top.max(cell.bottom))
-                .sum();
-            let avg_brightness = if !all_downsampled_cells.is_empty() && max_trail_value > 0.0 {
-                (total_brightness / (all_downsampled_cells.len() as f32)) / max_trail_value
-            } else {
-                0.0
-            };
+        // See render_with_overlay: blank the sim + frame when a modal panel overlaps
+        // the window-frame border, so the panel is the sole focus.
+        let blank_backdrop = self.modal_overlaps_frame(&[
+            controls_lines,
+            dashboard_lines,
+            config_browser_lines,
+            config_save_lines,
+            dirty_guard_lines,
+            keyboard_hints_lines,
+            preset_comparison_lines,
+            palette_editor_overlay,
+        ]);
+
+        if !blank_backdrop {
+            if let Some(mut grid) = grid_renderer.cloned() {
+                grid.initialize(self.width, self.height);
+
+                // Calculate average brightness from all species combined
+                let total_brightness: f32 = all_downsampled_cells
+                    .iter()
+                    .map(|cell| cell.top.max(cell.bottom))
+                    .sum();
+                let avg_brightness = if !all_downsampled_cells.is_empty() && max_trail_value > 0.0 {
+                    (total_brightness / (all_downsampled_cells.len() as f32)) / max_trail_value
+                } else {
+                    0.0
+                };
 
-            for y in 0..self.height {
-                for x in 0..self.width {
-                    if grid.is_grid_position(x, y, self.width, self.height) {
-                        let (on_vertical, on_horizontal) = grid.get_grid_lines(x, y);
-                        let opacity =
-                            grid.calculate_opacity(x, y, self.width, self.height, avg_brightness);
-                        buffer.render_grid_background(
-                            x,
-                            y,
-                            grid.color,
-                            opacity,
-                            on_vertical,
-                            on_horizontal,
-                        );
+                for y in 0..self.height {
+                    for x in 0..self.width {
+                        if grid.is_grid_position(x, y, self.width, self.height) {
+                            let (on_vertical, on_horizontal) = grid.get_grid_lines(x, y);
+                            let opacity = grid.calculate_opacity(
+                                x,
+                                y,
+                                self.width,
+                                self.height,
+                                avg_brightness,
+                            );
+                            buffer.render_grid_background(
+                                x,
+                                y,
+                                grid.color,
+                                opacity,
+                                on_vertical,
+                                on_horizontal,
+                            );
+                        }
                     }
                 }
             }
         }
 
+        if blank_backdrop {
+            buffer.fill_background();
+        }
+
         // Palette accent color for accented title badges (same approach as single-species).
         let accent = palette::palette_accent_color(
             &self.palette,
@@ -1222,7 +1311,7 @@ impl TerminalRenderer {
             self.intensity_mapping.as_ref(),
         );
 
-        if self.window_frame.is_visible() {
+        if !blank_backdrop && self.window_frame.is_visible() {
             if let Some(ref layout) = self.window_layout {
                 use crate::render::window::FallbackMode;
                 if !matches!(layout.fallback, FallbackMode::Fullscreen) {

src/terminal/state.rs

@@ -1716,11 +1716,14 @@ impl RuntimeState {
 
     /// Called when simulation is paused.
     ///
-    /// If the base chrome state is Minimal, expands chrome to show title + footer.
+    /// If the base chrome state is Minimal, expands chrome to show title + footer
+    /// — but only when no overlay is open. An open overlay owns the screen, and
+    /// the status bar would just clutter behind it, so the chrome stays collapsed
+    /// (the status bar appears on pause **and** no-overlay only).
     /// If base is Expanded, stays Expanded (no change needed).
     /// Also cancels any in-progress fade-out, snapping back to Expanded.
     pub fn on_pause(&mut self) {
-        if self.base_chrome_state == ChromeState::Minimal {
+        if self.base_chrome_state == ChromeState::Minimal && !self.any_overlay_open() {
             self.chrome_state = ChromeState::Expanded; // cancels any fade
         }
     }
@@ -1773,9 +1776,16 @@ impl RuntimeState {
 
     /// Called when a modal pane is opened.
     ///
-    /// Always sets chrome to ModalPane regardless of base state.
+    /// The overlay owns the screen. With persistent (Expanded) base chrome the
+    /// title + footer stay visible as ModalPane (with modal-navigation keybinds);
+    /// with the default Minimal base, chrome collapses to Minimal so the status
+    /// bar / title block don't clutter behind the overlay.
     pub fn on_modal_open(&mut self) {
-        self.chrome_state = ChromeState::ModalPane;
+        if self.base_chrome_state == ChromeState::Expanded {
+            self.chrome_state = ChromeState::ModalPane;
+        } else {
+            self.chrome_state = ChromeState::Minimal;
+        }
     }
 
     /// Called when the last modal pane is closed.
@@ -2502,13 +2512,39 @@ mod tests {
     }
 
     #[test]
-    fn test_chrome_base_minimal_modal_open() {
+    fn test_chrome_base_minimal_modal_open_stays_collapsed() {
+        // Default (Minimal) base: opening an overlay keeps chrome collapsed so the
+        // status bar does not clutter behind it.
         let mut state = create_test_runtime_state();
         state.base_chrome_state = ChromeState::Minimal;
+        state.chrome_state = ChromeState::Minimal;
+        state.on_modal_open();
+        assert_eq!(state.chrome_state, ChromeState::Minimal);
+    }
+
+    #[test]
+    fn test_chrome_base_expanded_modal_open_is_modal_pane() {
+        // Persistent (Expanded) base: an overlay shows ModalPane chrome.
+        let mut state = create_test_runtime_state();
+        state.base_chrome_state = ChromeState::Expanded;
         state.on_modal_open();
         assert_eq!(state.chrome_state, ChromeState::ModalPane);
     }
 
+    #[test]
+    fn test_chrome_pause_with_overlay_open_stays_collapsed() {
+        // Status bar appears on (pause AND no overlay): pausing while an overlay is
+        // open must NOT expand chrome.
+        let mut state = create_test_runtime_state();
+        state.base_chrome_state = ChromeState::Minimal;
+        state.chrome_state = ChromeState::Minimal;
+        state
+            .overlay_state
+            .open(crate::overlay::OverlayType::KeyboardHints);
+        state.on_pause();
+        assert_eq!(state.chrome_state, ChromeState::Minimal);
+    }
+
     #[test]
     fn test_chrome_base_minimal_modal_close_no_pause() {
         let mut state = create_test_runtime_state();