renderers: add background-aware cell styling

Author: rupurt

ARCHITECTURE.md

@@ -41,6 +41,7 @@ The public API is intentionally split into two layers:
 
 - Stores one byte mask per terminal cell for Braille dots
 - Stores optional foreground colors per cell
+- Stores optional background colors per cell
 - Stores an optional text overlay layer per cell
 - Tracks plot insets in pixel coordinates
 - Owns composition helpers such as overlay and merge behavior
@@ -84,11 +85,12 @@ The important boundary is between data-space and pixel-space:
 
 ## Composition Model
 
-The current composition model uses three parallel concerns at the cell level:
+The current composition model uses four parallel concerns at the cell level:
 
 1. Braille mask bits for dot occupancy
 2. Optional foreground color
-3. Optional text overlay
+3. Optional background color
+4. Optional text overlay
 
 This enables:
 

GUIDE.md

@@ -130,7 +130,7 @@ Typical flow:
 1. Create a canvas once
 2. Clear and redraw each frame
 3. Use screen coordinates for sprites, UI chrome, and projected geometry
-4. Overlay text with `set_char()`
+4. Overlay text with `set_char()` and use `set_cell_background()` for panel-style cells
 5. Render into a reusable `String` with `render_to()`
 
 Good fits for direct-canvas work:

README.md

@@ -31,6 +31,7 @@ If you use Nix, `nix develop` provides the Rust toolchain plus `cargo-nextest`,
 - Advanced pixel and color control:
   - `unset_pixel` and `toggle_pixel`
   - color blending modes with `Overwrite` and `KeepFirst`
+  - cell background colors for terminal panels and HUD-style layouts
 - Drawing primitives:
   - lines, circles, polygons
   - filled shapes via `rect_filled` and `circle_filled`

src/canvas/composition.rs

@@ -12,6 +12,7 @@ impl<R: CellRenderer> CellCanvas<R> {
             plot_bottom_inset_px: 0,
             buffer: vec![R::Cell::default(); size],
             colors: vec![None; size],
+            background_colors: vec![None; size],
             text_layer: vec![None; size],
             _renderer: PhantomData,
         }
@@ -30,6 +31,7 @@ impl<R: CellRenderer> CellCanvas<R> {
     pub fn clear(&mut self) {
         self.buffer.fill(R::Cell::default());
         self.colors.fill(None);
+        self.background_colors.fill(None);
         self.text_layer.fill(None);
         self.plot_left_inset_px = 0;
         self.plot_bottom_inset_px = 0;
@@ -58,6 +60,7 @@ impl<R: CellRenderer> CellCanvas<R> {
             if !R::is_empty(top.buffer[idx]) || top.text_layer[idx].is_some() {
                 self.buffer[idx] = top.buffer[idx];
                 self.colors[idx] = top.colors[idx];
+                self.background_colors[idx] = top.background_colors[idx];
                 self.text_layer[idx] = top.text_layer[idx];
             }
         }
@@ -73,13 +76,19 @@ impl<R: CellRenderer> CellCanvas<R> {
                 if top.colors[idx].is_some() {
                     self.colors[idx] = top.colors[idx];
                 }
+                if top.background_colors[idx].is_some() {
+                    self.background_colors[idx] = top.background_colors[idx];
+                }
             }
 
             if let Some(ch) = top.text_layer[idx] {
                 self.text_layer[idx] = Some(ch);
                 if top.colors[idx].is_some() {
                     self.colors[idx] = top.colors[idx];
                 }
+                if top.background_colors[idx].is_some() {
+                    self.background_colors[idx] = top.background_colors[idx];
+                }
             }
         }
     }
@@ -123,6 +132,10 @@ impl<R: CellRenderer> CellCanvas<R> {
             } else if top.colors[idx].is_some() || R::is_empty(self.buffer[idx]) {
                 self.colors[idx] = top.colors[idx];
             }
+
+            if top.background_colors[idx].is_some() || R::is_empty(self.buffer[idx]) {
+                self.background_colors[idx] = top.background_colors[idx];
+            }
         }
     }
 }

src/canvas/mod.rs

@@ -11,6 +11,7 @@ mod tests;
 use colored::Color;
 use std::marker::PhantomData;
 
+pub use renderer::CellAppearance;
 pub use renderer::{BrailleRenderer, CellRenderer, QuadrantRenderer};
 
 #[derive(Clone, Copy, PartialEq, Eq)]
@@ -29,6 +30,7 @@ pub struct CellCanvas<R: CellRenderer> {
     plot_bottom_inset_px: usize,
     buffer: Vec<R::Cell>,
     colors: Vec<Option<Color>>,
+    background_colors: Vec<Option<Color>>,
     text_layer: Vec<Option<char>>,
     _renderer: PhantomData<R>,
 }
@@ -81,4 +83,13 @@ impl<R: CellRenderer> CellCanvas<R> {
             self.colors[index] = None;
         }
     }
+
+    fn set_cell_background_impl(&mut self, col: usize, row: usize, color: Option<Color>) {
+        if col >= self.width || row >= self.height {
+            return;
+        }
+
+        let index = self.idx(col, row);
+        self.background_colors[index] = color;
+    }
 }

src/canvas/pixels.rs

@@ -20,6 +20,15 @@ impl<R: CellRenderer> CellCanvas<R> {
         self.unset_pixel_impl(x, y);
     }
 
+    pub fn set_cell_background(&mut self, col: usize, row: usize, color: Option<Color>) {
+        let inverted_row = self.height.saturating_sub(1).saturating_sub(row);
+        self.set_cell_background_impl(col, inverted_row, color);
+    }
+
+    pub fn set_cell_background_screen(&mut self, col: usize, row: usize, color: Option<Color>) {
+        self.set_cell_background_impl(col, row, color);
+    }
+
     pub fn toggle_pixel_screen(&mut self, x: usize, y: usize, color: Option<Color>) {
         if x >= self.pixel_width() || y >= self.pixel_height() {
             return;

src/canvas/render.rs

@@ -25,6 +25,68 @@ impl<R: CellRenderer> CellCanvas<R> {
         }
     }
 
+    fn write_ansi_background_color<W: Write>(w: &mut W, color: Color) -> fmt::Result {
+        match color {
+            Color::Black => w.write_str("\x1b[40m"),
+            Color::Red => w.write_str("\x1b[41m"),
+            Color::Green => w.write_str("\x1b[42m"),
+            Color::Yellow => w.write_str("\x1b[43m"),
+            Color::Blue => w.write_str("\x1b[44m"),
+            Color::Magenta => w.write_str("\x1b[45m"),
+            Color::Cyan => w.write_str("\x1b[46m"),
+            Color::White => w.write_str("\x1b[47m"),
+            Color::BrightBlack => w.write_str("\x1b[100m"),
+            Color::BrightRed => w.write_str("\x1b[101m"),
+            Color::BrightGreen => w.write_str("\x1b[102m"),
+            Color::BrightYellow => w.write_str("\x1b[103m"),
+            Color::BrightBlue => w.write_str("\x1b[104m"),
+            Color::BrightMagenta => w.write_str("\x1b[105m"),
+            Color::BrightCyan => w.write_str("\x1b[106m"),
+            Color::BrightWhite => w.write_str("\x1b[107m"),
+            Color::TrueColor { r, g, b } => write!(w, "\x1b[48;2;{};{};{}m", r, g, b),
+        }
+    }
+
+    fn write_style<W: Write>(
+        w: &mut W,
+        foreground: Option<Color>,
+        background: Option<Color>,
+        last_foreground: &mut Option<Color>,
+        last_background: &mut Option<Color>,
+    ) -> fmt::Result {
+        if foreground == *last_foreground && background == *last_background {
+            return Ok(());
+        }
+
+        let needs_reset = (foreground.is_none() && last_foreground.is_some())
+            || (background.is_none() && last_background.is_some());
+
+        if needs_reset {
+            w.write_str("\x1b[0m")?;
+            if let Some(bg) = background {
+                Self::write_ansi_background_color(w, bg)?;
+            }
+            if let Some(fg) = foreground {
+                Self::write_ansi_color(w, fg)?;
+            }
+        } else {
+            if background != *last_background {
+                if let Some(bg) = background {
+                    Self::write_ansi_background_color(w, bg)?;
+                }
+            }
+            if foreground != *last_foreground {
+                if let Some(fg) = foreground {
+                    Self::write_ansi_color(w, fg)?;
+                }
+            }
+        }
+
+        *last_foreground = foreground;
+        *last_background = background;
+        Ok(())
+    }
+
     pub fn render_to<W: Write>(
         &self,
         w: &mut W,
@@ -44,7 +106,8 @@ impl<R: CellRenderer> CellCanvas<R> {
             w.write_char('\n')?;
         }
 
-        let mut last_color: Option<Color> = None;
+        let mut last_foreground: Option<Color> = None;
+        let mut last_background: Option<Color> = None;
 
         for row in 0..self.height {
             if show_border {
@@ -53,27 +116,28 @@ impl<R: CellRenderer> CellCanvas<R> {
 
             for col in 0..self.width {
                 let idx = self.idx(col, row);
-                let char_to_print = if let Some(c) = self.text_layer[idx] {
-                    c
-                } else {
-                    R::glyph(self.buffer[idx])
-                };
-
-                let current_color = self.colors[idx];
-                if current_color != last_color {
-                    match current_color {
-                        Some(c) => Self::write_ansi_color(w, c)?,
-                        None => w.write_str("\x1b[0m")?,
-                    }
-                    last_color = current_color;
-                }
+                let appearance = R::appearance(
+                    self.buffer[idx],
+                    self.colors[idx],
+                    self.background_colors[idx],
+                    self.text_layer[idx],
+                );
+
+                Self::write_style(
+                    w,
+                    appearance.foreground,
+                    appearance.background,
+                    &mut last_foreground,
+                    &mut last_background,
+                )?;
 
-                w.write_char(char_to_print)?;
+                w.write_char(appearance.glyph)?;
             }
 
-            if last_color.is_some() {
+            if last_foreground.is_some() || last_background.is_some() {
                 w.write_str("\x1b[0m")?;
-                last_color = None;
+                last_foreground = None;
+                last_background = None;
             }
 
             if show_border {

src/canvas/renderer.rs

@@ -1,3 +1,12 @@
+use colored::Color;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct CellAppearance {
+    pub glyph: char,
+    pub foreground: Option<Color>,
+    pub background: Option<Color>,
+}
+
 pub trait CellRenderer {
     type Cell: Copy + Default + PartialEq + Eq;
 
@@ -14,6 +23,27 @@ pub trait CellRenderer {
     fn subpixel_count(cell: Self::Cell) -> u32;
     fn is_empty(cell: Self::Cell) -> bool;
     fn glyph(cell: Self::Cell) -> char;
+
+    fn appearance(
+        cell: Self::Cell,
+        foreground: Option<Color>,
+        background: Option<Color>,
+        text: Option<char>,
+    ) -> CellAppearance {
+        let glyph = text.unwrap_or_else(|| {
+            if background.is_some() && Self::is_empty(cell) {
+                ' '
+            } else {
+                Self::glyph(cell)
+            }
+        });
+
+        CellAppearance {
+            glyph,
+            foreground,
+            background,
+        }
+    }
 }
 
 #[derive(Clone, Copy, Default)]

src/canvas/tests.rs

@@ -67,3 +67,25 @@ fn quadrant_canvas_renders_quadrant_blocks() {
     canvas.set_pixel_screen(0, 1, None);
     assert_eq!(canvas.render_no_color(), "█\n");
 }
+
+#[test]
+fn render_with_background_color_emits_ansi_background() {
+    let mut canvas = BrailleCanvas::new(1, 1);
+    canvas.set_char(0, 0, 'A', None);
+    canvas.set_cell_background(0, 0, Some(Color::Blue));
+
+    let rendered = canvas.render_with_options(false, None);
+
+    assert!(rendered.contains("\x1b[44m"));
+    assert!(rendered.contains("A"));
+}
+
+#[test]
+fn background_only_cells_render_as_spaces_with_background() {
+    let mut canvas = BrailleCanvas::new(1, 1);
+    canvas.set_cell_background(0, 0, Some(Color::BrightBlack));
+
+    let rendered = canvas.render_with_options(false, None);
+
+    assert!(rendered.contains("\x1b[100m "));
+}