feat(render): style screenshots and recordings from the config, per profile

.github/workflows/ci.yml

@@ -58,6 +58,9 @@ jobs:
       - run: cargo clippy -p tui-test-rs --all-targets --no-default-features -- -D warnings
       - run: cargo build
       - run: cargo test --workspace -- --test-threads=1
+      # The recording renderer and its font catalog are behind a feature that
+      # is off by default, so the line above never compiles them in.
+      - run: cargo test -p tui-test-rs --features recording-font-jetbrains-mono-styles -- --test-threads=1
 
       - name: Install Python binding
         run: python -m pip install --disable-pip-version-check -e ./bindings/python

README.md

@@ -375,6 +375,37 @@ directory = "./traces"
 screen-history-limit = 10
 ```
 
+Set the appearance of screenshots and recordings with `[recording.style]`:
+
+```toml
+[recording.style]
+font_size = 18
+canvas_background = "#05050a"
+canvas_padding = 30
+
+[recording.style.window]
+background = "#15151f"
+foreground = "#c8c8e0"
+divider = "#2a2a3a"
+
+[recording.style.border]
+width = 1
+color = "#3a3a52"
+radius = 12
+
+[profiles.default.colors]
+background = "#0b0b12"
+foreground = "#d8d8e8"
+```
+
+<p align="center">
+  <img alt="tui-test drawn with a dark canvas, chrome and palette" src="static/style-midnight.svg" width="400">
+</p>
+
+Profiles override individual keys and inherit the rest from the file.
+See the [style types and defaults](crates/tui-test/src/render/style.rs) for all options.
+The [CLI reference](references/cli.md#styling-screenshots-and-recordings) explains profile overrides.
+
 The CLI checks the current directory, the platform config directory, then `~/.tui-test`. Use `--config PATH` or `TUI_TEST_CONFIG` to select a file.
 
 ### Shells and backends

bindings/go/native/src/input.rs

@@ -215,6 +215,7 @@ pub(crate) unsafe fn open(value: TuiOpenOptions) -> Result<OpenOptions> {
         backend,
         shell,
         profile,
+        style: Default::default(),
         cols: u16_option(value.cols, "cols")?.unwrap_or(80),
         rows: u16_option(value.rows, "rows")?.unwrap_or(30),
         cwd: unsafe { value.cwd.optional()? },

bindings/go/native/src/lib.rs

@@ -102,6 +102,7 @@ pub unsafe extern "C" fn tui_run(
                 args: input::strings(args, args_len)?,
                 backend: o.backend,
                 profile: o.profile,
+                style: o.style,
                 cols: o.cols,
                 rows: o.rows,
                 cwd: o.cwd,

bindings/js/native/lib.rs

@@ -1009,6 +1009,7 @@ fn open_options(
     Ok(CoreOpenOptions {
         backend: value.backend.map(Into::into).unwrap_or_default(),
         profile,
+        style: Default::default(),
         shell: value.shell.map(Into::into),
         cols: match value.cols {
             Some(cols) => u16_value(cols, "cols")?,
@@ -1041,6 +1042,7 @@ fn run_options(
     Ok(CoreRunOptions {
         backend: value.backend.map(Into::into).unwrap_or_default(),
         profile,
+        style: Default::default(),
         program: value.program,
         args: value.args.unwrap_or_default(),
         cols: match value.cols {

bindings/js/test/integration.test.mjs

@@ -369,7 +369,8 @@ test("recording API exports styled Unicode to APNG and GIF", async () => {
           await su.screenshot(screenshotPath, { zoom: 0.5 });
           assert.match(
             await readFile(screenshotPath, "utf8"),
-            /width="139" height="92" viewBox="0 0 278 184"/,
+            // Follows the default style; update deliberately if a gap moves.
+            /width="139" height="94" viewBox="0 0 278 188"/,
           );
         }
         await su.startRecording(path, { format, fps: 30, zoom: 0.5 });
@@ -382,11 +383,11 @@ test("recording API exports styled Unicode to APNG and GIF", async () => {
         assert.deepEqual(bytes.subarray(0, 8), Buffer.from("\x89PNG\r\n\x1a\n", "latin1"));
         assert.ok(bytes.includes(Buffer.from("acTL")));
         assert.equal(bytes.readUInt32BE(16), 278);
-        assert.equal(bytes.readUInt32BE(20), 184);
+        assert.equal(bytes.readUInt32BE(20), 188);
       } else {
         assert.equal(bytes.subarray(0, 6).toString("ascii"), "GIF89a");
         assert.equal(bytes.readUInt16LE(6), 278);
-        assert.equal(bytes.readUInt16LE(8), 184);
+        assert.equal(bytes.readUInt16LE(8), 188);
       }
     }
   } finally {

bindings/python/native/src/lib.rs

@@ -228,6 +228,7 @@ impl NativeSession {
                     Operation::Open(OpenOptions {
                         backend: parse_backend(backend.as_deref())?,
                         profile: profile_from_parts(profile_scrollback.as_ref(), &profile_colors)?,
+                        style: Default::default(),
                         shell: parse_shell(shell.as_deref())?,
                         cols: integer_u16(&cols, "cols")?,
                         rows: integer_u16(&rows, "rows")?,
@@ -311,6 +312,7 @@ impl NativeSession {
                     Operation::Run(RunOptions {
                         backend: parse_backend(backend.as_deref())?,
                         profile: profile_from_parts(profile_scrollback.as_ref(), &profile_colors)?,
+                        style: Default::default(),
                         program,
                         args,
                         cols: integer_u16(&cols, "cols")?,

bindings/python/tests/test_integration.py

@@ -211,8 +211,10 @@ async def scenario():
                                     str(screenshot), zoom=0.5
                                 )
                                 self.assertIn(
-                                    'width="139" height="92" '
-                                    'viewBox="0 0 278 184"',
+                                    # Follows the default style; update
+                                    # deliberately if a default gap moves.
+                                    'width="139" height="94" '
+                                    'viewBox="0 0 278 188"',
                                     screenshot.read_text(encoding="utf-8"),
                                 )
                             await su.start_recording(
@@ -231,15 +233,15 @@ async def scenario():
                                 int.from_bytes(data[16:20], "big"), 278
                             )
                             self.assertEqual(
-                                int.from_bytes(data[20:24], "big"), 184
+                                int.from_bytes(data[20:24], "big"), 188
                             )
                         else:
                             self.assertEqual(data[:6], b"GIF89a")
                             self.assertEqual(
                                 int.from_bytes(data[6:8], "little"), 278
                             )
                             self.assertEqual(
-                                int.from_bytes(data[8:10], "little"), 184
+                                int.from_bytes(data[8:10], "little"), 188
                             )
 
         run(scenario())

crates/tui-test-cli/src/main.rs

@@ -309,6 +309,7 @@ fn build_request(command: Command) -> anyhow::Result<Request> {
                 restart,
                 timeouts: settings.timeouts.with_overrides(timeouts.into()),
                 recording: Box::new(settings.recording),
+                style: Box::new(settings.style.clone()),
                 trace: settings.trace,
                 diagnostics: tui_test::DiagnosticRetentionOptions {
                     screen_history_limit: diagnostics
@@ -348,6 +349,7 @@ fn build_request(command: Command) -> anyhow::Result<Request> {
                 restart,
                 timeouts: settings.timeouts.with_overrides(timeouts.into()),
                 recording: Box::new(settings.recording),
+                style: Box::new(settings.style.clone()),
                 trace: settings.trace,
                 diagnostics: tui_test::DiagnosticRetentionOptions {
                     screen_history_limit: diagnostics

crates/tui-test-cli/src/protocol.rs

@@ -31,6 +31,10 @@ pub enum Request {
         /// project-local config against.
         #[serde(default)]
         profile: tui_test::profile::Profile,
+        /// How this session's screenshots and recordings are drawn, resolved
+        /// from the config file by the client for the same reason.
+        #[serde(default)]
+        style: Box<tui_test::render::style::Style>,
         cols: u16,
         rows: u16,
         cwd: Option<String>,
@@ -438,6 +442,7 @@ impl Request {
                 program,
                 backend,
                 profile,
+                style,
                 cols,
                 rows,
                 cwd,
@@ -457,6 +462,7 @@ impl Request {
                     Ok(Operation::Run(RunOptions {
                         backend,
                         profile,
+                        style: *style,
                         program: executable,
                         args: parts.collect(),
                         cols,
@@ -472,6 +478,7 @@ impl Request {
                     Ok(Operation::Open(OpenOptions {
                         backend,
                         profile,
+                        style: *style,
                         shell,
                         cols,
                         rows,
@@ -839,6 +846,7 @@ mod tests {
             program: None,
             backend: Backend::default(),
             profile: Default::default(),
+            style: Box::default(),
             cols: 80,
             rows: 30,
             cwd: None,

crates/tui-test-cli/tests/session_lifecycle.rs

@@ -364,7 +364,8 @@ fn screenshots_dispatch_by_extension_without_changing_svg_output() {
     sandbox.ok(&["screenshot", zoomed_svg.to_str().unwrap(), "--zoom", "2"]);
     let zoomed_svg = std::fs::read_to_string(zoomed_svg).unwrap();
     assert!(
-        zoomed_svg.contains(r#"width="236" height="326" viewBox="0 0 118 163""#),
+        // Follows the default style; update deliberately if a gap moves.
+        zoomed_svg.contains(r#"width="236" height="334" viewBox="0 0 118 167""#),
         "unexpected zoomed SVG dimensions: {zoomed_svg}"
     );
 
@@ -376,7 +377,7 @@ fn screenshots_dispatch_by_extension_without_changing_svg_output() {
     let mut reader = decoder.read_info().unwrap();
     let mut pixels = vec![0; reader.output_buffer_size()];
     let info = reader.next_frame(&mut pixels).unwrap();
-    assert_eq!((info.width, info.height), (236, 326));
+    assert_eq!((info.width, info.height), (236, 334));
     let pixels = &pixels[..info.buffer_size()];
     assert!(
         contains_rgba(pixels, [128, 0, 0, 255]),
@@ -2698,7 +2699,9 @@ fn a_window_title_is_tracked_asserted_and_drawn() {
             backend.as_str()
         );
         assert!(
-            image.contains(r#"width="239" height="365" viewBox="0 0 478 730""#),
+            // The default style at zoom 0.5; update deliberately if a
+            // default gap moves.
+            image.contains(r#"width="239" height="367" viewBox="0 0 478 734""#),
             "{} changed the SVG dimensions at zoom 0.5: {image}",
             backend.as_str()
         );

crates/tui-test/src/api.rs

@@ -91,6 +91,9 @@ pub struct OpenOptions {
     pub restart: bool,
     pub timeouts: Timeouts,
     pub recording: AutomaticRecording,
+    /// How this session's screenshots and recordings are drawn, resolved
+    /// from the config file by the client alongside `profile`.
+    pub style: crate::render::style::Style,
 }
 
 impl Default for OpenOptions {
@@ -107,6 +110,7 @@ impl Default for OpenOptions {
             restart: false,
             timeouts: Timeouts::default(),
             recording: AutomaticRecording::default(),
+            style: crate::render::style::Style::default(),
         }
     }
 }
@@ -129,6 +133,9 @@ pub struct RunOptions {
     pub restart: bool,
     pub timeouts: Timeouts,
     pub recording: AutomaticRecording,
+    /// How this session's screenshots and recordings are drawn, resolved
+    /// from the config file by the client alongside `profile`.
+    pub style: crate::render::style::Style,
 }
 
 /// Clipboard text or regex.

crates/tui-test/src/diagnostics.rs

@@ -858,12 +858,13 @@ impl FailureObservation {
     }
 
     pub(crate) fn svg(&self) -> String {
-        crate::render::svg::render_svg_with_zoom(
+        crate::render::svg::render_svg(
             &self.rows,
             self.cols,
             &self.render_state,
             self.cursor,
             self.title.as_deref(),
+            &crate::render::style::Style::default(),
             1.0,
             None,
         )

crates/tui-test/src/diagnostics/html.rs

@@ -72,7 +72,7 @@ struct FrameCell {
 
 impl FrameCell {
     fn capture(cell: &EmuCell, width: u8, colors: &dyn RenderColors) -> Self {
-        let style = svg::style_of(cell, colors);
+        let style = svg::cell_paint(cell, colors);
         Self {
             char: cell.ch.to_string(),
             link: cell.uri().map(str::to_string),
@@ -120,11 +120,16 @@ fn timeline_with_limit(
     let mut timeline = Timeline {
         schema_version: 1,
         failure_screen_sequence: observation.screen_sequence,
-        geometry: Geometry {
-            grid_x: svg::CANVAS_PADDING as f32 + svg::MARGIN_X,
-            grid_y: svg::CANVAS_PADDING as f32 + svg::HEADER_H + svg::CONTENT_PADDING_TOP,
-            cell_width: svg::CELL_W,
-            cell_height: svg::CELL_H,
+        // The trace viewer draws its own grid rather than the styled SVG, so
+        // it is placed with the default geometry.
+        geometry: {
+            let style = crate::render::style::Style::default();
+            Geometry {
+                grid_x: style.canvas_left() as f32 + style.content_left(),
+                grid_y: style.canvas_top() as f32 + style.header_height() + style.content_top(),
+                cell_width: style.cell_width(),
+                cell_height: style.cell_height(),
+            }
         },
         frames: sources
             .values()
@@ -188,14 +193,15 @@ fn timeline_with_limit(
             } else {
                 frame.omission = None;
                 let cursor = &frame.screen.cursor;
-                frame.svg = Some(svg::render_svg_with_zoom(
+                frame.svg = Some(svg::render_svg(
                     &source.rows,
                     frame.screen.size.cols,
                     &source.render_state,
                     cursor
                         .visible
                         .then_some((cursor.column, usize::from(cursor.row))),
                     frame.screen.title.as_deref(),
+                    &crate::render::style::Style::default(),
                     1.0,
                     None,
                 ));