feat(window): add configurable opacity

CHANGELOG.md

@@ -5,6 +5,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+- add `window.opacity` for a transparent background (compositor-dependent)
+
 ## [0.10.0] - 2026-07-25
 
 ### Added

README.md

@@ -159,6 +159,7 @@ width           = 800
 height          = 600
 title           = "mmterm"
 cursor_blink_ms = 500
+opacity         = 1.0             # < 1.0 = transparent background (needs a compositor that supports it)
 
 [shell]
 # program = "/bin/zsh"   # defaults to $SHELL

assets/config.toml

@@ -11,6 +11,7 @@ title           = "mmterm"
 cursor_blink_ms = 500
 inactive_dim    = 0.55
 detect_urls     = true
+opacity         = 1.0
 
 [shell]
 # program = "/bin/zsh"

doc/SPEC.md

@@ -221,13 +221,19 @@ Screenshot capture is a two-step flow: region selection followed by a name promp
 | window | cursor_blink_ms | uint | `500` |
 | window | inactive_dim | float | `0.55` |
 | window | detect_urls | bool | `true` |
+| window | opacity | float | `1.0` |
 | terminal | scrollback_lines | uint | `10000` (min 100) |
 | shell | program | string? | `$SHELL` |
 | logging | auto_log | bool | `false` |
 | logging | log_dir | string | `""` (→ `~/.mmterm`) |
 | status_bar | right | string | `""` |
 | theme | name | string | `"default"` |
 
+`window.opacity` sets the alpha of the terminal background. Values below `1.0`
+make the window transparent while keeping text and UI chrome fully opaque; this
+requires a compositor that supports transparency and the exact result is
+platform-dependent (X11, Wayland, and macOS handle window alpha differently).
+
 ### Themes
 
 Themes define all terminal and UI colors in a single `.toml` file.

src/config/config_test.rs

@@ -134,6 +134,44 @@ fn default_detect_urls_value() {
     assert!(default_detect_urls());
 }
 
+#[test]
+fn default_opacity_value() {
+    assert_eq!(default_opacity(), 1.0);
+    assert_eq!(Config::default().window.opacity, 1.0);
+}
+
+#[test]
+fn opacity_default_applied_when_missing() {
+    let toml = r###"
+[font]
+family = "Mono"
+size = 14.0
+[window]
+width = 800
+height = 600
+title = "t"
+cursor_blink_ms = 500
+[shell]
+[colors]
+background = "#000000"
+foreground = "#ffffff"
+cursor = "#ffffff"
+selection = "#333333"
+palette = []
+"###;
+    let cfg: Config = toml::from_str(toml).expect("parse failed");
+    assert_eq!(cfg.window.opacity, 1.0);
+}
+
+#[test]
+fn opacity_round_trips_through_toml() {
+    let mut cfg = Config::default();
+    cfg.window.opacity = 0.8;
+    let s = toml::to_string_pretty(&cfg).expect("serialize failed");
+    let back: Config = toml::from_str(&s).expect("parse failed");
+    assert_eq!(back.window.opacity, 0.8);
+}
+
 #[test]
 fn detect_urls_default_applied_when_missing() {
     let toml = r###"

src/config/mod.rs

@@ -147,6 +147,9 @@ fn default_inactive_dim() -> f32 {
 fn default_detect_urls() -> bool {
     true
 }
+fn default_opacity() -> f32 {
+    1.0
+}
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct WindowConfig {
@@ -158,6 +161,8 @@ pub struct WindowConfig {
     pub inactive_dim: f32,
     #[serde(default = "default_detect_urls")]
     pub detect_urls: bool,
+    #[serde(default = "default_opacity")]
+    pub opacity: f32,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]

src/config/tui_config.rs

@@ -33,6 +33,7 @@ const F_AUTO_UPDATE_CHECK: usize = 37;
 const F_AUTO_UPDATE_INSTALL: usize = 38;
 const F_SHELL_INTEGRATION: usize = 39;
 const F_DESKTOP_NOTIFICATIONS: usize = 40;
+const F_OPACITY: usize = 41;
 
 const PALETTE_LABELS: [&str; 16] = [
     "Palette 0  black",
@@ -302,6 +303,14 @@ impl ConfigPanel {
             section: None,
         });
 
+        fields.push(Field {
+            label: "Opacity",
+            hint: "0.0–1.0 window background opacity",
+            value: cfg.window.opacity.to_string(),
+            kind: FieldKind::Float,
+            section: None,
+        });
+
         let mut collapsed = HashSet::new();
         collapsed.insert("Palette");
 
@@ -624,6 +633,10 @@ impl ConfigPanel {
         let detect_urls = get(F_DETECT_URLS)
             .parse::<bool>()
             .map_err(|_| "Invalid detect_urls — use true or false")?;
+        let opacity = get(F_OPACITY)
+            .parse::<f32>()
+            .map_err(|_| "Invalid opacity")?
+            .clamp(0.0, 1.0);
         let shell = {
             let s = get(F_SHELL);
             if s.is_empty() { None } else { Some(s) }
@@ -687,6 +700,7 @@ impl ConfigPanel {
                 cursor_blink_ms: blink_ms,
                 inactive_dim,
                 detect_urls,
+                opacity,
             },
             shell: ShellConfig { program: shell },
             terminal: TerminalConfig { scrollback_lines },

src/config/tui_config_test.rs

@@ -10,8 +10,8 @@ fn make_panel() -> ConfigPanel {
 #[test]
 fn from_config_has_correct_field_count() {
     let panel = make_panel();
-    // 9 base + 1 scrollback + 2 logging + 1 theme + 4 colors + 16 palette + 1 status_bar + 3 general + 2 updates + 2 shell/notify = 41
-    assert_eq!(panel.fields.len(), 41);
+    // 9 base + 1 scrollback + 2 logging + 1 theme + 4 colors + 16 palette + 1 status_bar + 3 general + 2 updates + 2 shell/notify + 1 opacity = 42
+    assert_eq!(panel.fields.len(), 42);
 }
 
 #[test]
@@ -305,6 +305,7 @@ fn distinct_config() -> Config {
             cursor_blink_ms: 523,
             inactive_dim: 0.42,
             detect_urls: true,
+            opacity: 0.8,
         },
         shell: ShellConfig {
             program: Some("/bin/xyzsh".into()),
@@ -375,6 +376,7 @@ fn field_index_sanity() {
         F_AUTO_UPDATE_INSTALL,
         F_SHELL_INTEGRATION,
         F_DESKTOP_NOTIFICATIONS,
+        F_OPACITY,
     ];
     occupied.extend((0..16).map(|i| F_PALETTE + i));
     occupied.sort_unstable();
@@ -433,6 +435,37 @@ fn build_config_roundtrip_toggles_desktop_notifications() {
     }
 }
 
+#[test]
+fn build_config_preserves_opacity() {
+    let mut panel = make_panel();
+    panel.fields[F_OPACITY].value = "0.75".to_string();
+    if let ConfigAction::Save(cfg) = panel.save() {
+        assert_eq!(cfg.window.opacity, 0.75);
+    } else {
+        panic!("expected Save action");
+    }
+}
+
+#[test]
+fn build_config_clamps_opacity_above_one() {
+    let mut panel = make_panel();
+    panel.fields[F_OPACITY].value = "2.5".to_string();
+    let cfg = panel
+        .build_config()
+        .expect("opacity clamps, does not error");
+    assert_eq!(cfg.window.opacity, 1.0);
+}
+
+#[test]
+fn build_config_clamps_opacity_below_zero() {
+    let mut panel = make_panel();
+    panel.fields[F_OPACITY].value = "-1.0".to_string();
+    let cfg = panel
+        .build_config()
+        .expect("opacity clamps, does not error");
+    assert_eq!(cfg.window.opacity, 0.0);
+}
+
 #[test]
 fn build_config_shell_empty_becomes_none() {
     let mut panel = make_panel();
@@ -680,8 +713,8 @@ fn palette_collapsed_by_default() {
 #[test]
 fn visible_indices_hides_palette_body() {
     let panel = make_panel();
-    // 41 total - 15 palette body fields = 26 visible
-    assert_eq!(panel.visible_indices().len(), 26);
+    // 42 total - 15 palette body fields = 27 visible
+    assert_eq!(panel.visible_indices().len(), 27);
 }
 
 #[test]
@@ -690,7 +723,7 @@ fn toggle_on_palette_header_expands() {
     panel.selected = F_PALETTE;
     panel.toggle_collapse();
     assert!(!panel.collapsed.contains("Palette"));
-    assert_eq!(panel.visible_indices().len(), 41);
+    assert_eq!(panel.visible_indices().len(), 42);
 }
 
 #[test]
@@ -700,7 +733,7 @@ fn toggle_twice_restores_collapsed() {
     panel.toggle_collapse();
     panel.toggle_collapse();
     assert!(panel.collapsed.contains("Palette"));
-    assert_eq!(panel.visible_indices().len(), 26);
+    assert_eq!(panel.visible_indices().len(), 27);
 }
 
 #[test]
@@ -755,10 +788,10 @@ fn move_up_skips_collapsed_palette() {
 #[test]
 fn move_down_at_last_visible_clamps() {
     let mut panel = make_panel();
-    // F_DESKTOP_NOTIFICATIONS is the last field and is always visible
-    panel.selected = F_DESKTOP_NOTIFICATIONS;
+    // F_OPACITY is the last field and is always visible
+    panel.selected = F_OPACITY;
     panel.handle_down();
-    assert_eq!(panel.selected, F_DESKTOP_NOTIFICATIONS);
+    assert_eq!(panel.selected, F_OPACITY);
 }
 
 #[test]

src/renderer/draw_fns.rs

@@ -72,6 +72,13 @@ pub(super) fn color_u32(c: Color) -> u32 {
     (0xFF << 24) | ((c.r as u32) << 16) | ((c.g as u32) << 8) | (c.b as u32)
 }
 
+/// Pack a color with an explicit alpha byte in the high 8 bits (`0xAARRGGBB`).
+/// Used for the terminal background when `window.opacity < 1.0`; whether the
+/// alpha is honored depends on the platform compositor (softbuffer).
+pub(super) fn color_u32_with_alpha(c: Color, a: u8) -> u32 {
+    ((a as u32) << 24) | ((c.r as u32) << 16) | ((c.g as u32) << 8) | (c.b as u32)
+}
+
 pub(super) fn dim_color(c: u32, factor: f32) -> u32 {
     let r = (((c >> 16) & 0xFF) as f32 * factor) as u32;
     let g = (((c >> 8) & 0xFF) as f32 * factor) as u32;
@@ -203,6 +210,7 @@ fn resolve_bg_color(
     cursor_color: Color,
     selection_color: Color,
     theme: &ResolvedTheme,
+    bg_alpha: BgAlpha,
 ) -> u32 {
     if is_cursor && cursor_shape == CursorShape::Block {
         color_u32(cursor_color)
@@ -213,7 +221,26 @@ fn resolve_bg_color(
     } else if in_match {
         color_u32(theme.search_match)
     } else {
-        color_u32(bg)
+        // Only cells still on the default background become translucent; a cell
+        // painted by the application keeps its color fully opaque.
+        color_u32_with_alpha(bg, bg_alpha.for_bg(bg))
+    }
+}
+
+/// Window background alpha plus the default background it applies to.
+#[derive(Debug, Clone, Copy)]
+pub(super) struct BgAlpha {
+    pub alpha: u8,
+    pub default_bg: Color,
+}
+
+impl BgAlpha {
+    pub(super) fn for_bg(&self, bg: Color) -> u8 {
+        if bg == self.default_bg {
+            self.alpha
+        } else {
+            0xFF
+        }
     }
 }
 
@@ -228,6 +255,7 @@ pub(super) fn resolve_cell_colors(
     cursor_color: Color,
     selection_color: Color,
     theme: &ResolvedTheme,
+    bg_alpha: BgAlpha,
 ) -> (u32, Color) {
     let (fg, bg) = if cell.reverse {
         (cell.bg, cell.fg)
@@ -253,6 +281,7 @@ pub(super) fn resolve_cell_colors(
         cursor_color,
         selection_color,
         theme,
+        bg_alpha,
     );
     let fg = if (in_match || is_current_match) && !is_cursor {
         SEARCH_MATCH_FG
@@ -429,6 +458,26 @@ mod tests {
         assert_eq!(color_u32(c), 0xFF_12_34_56);
     }
 
+    #[test]
+    fn color_u32_with_alpha_packs_alpha_in_high_byte() {
+        let c = Color::rgb(0x12, 0x34, 0x56);
+        assert_eq!(color_u32_with_alpha(c, 0x80), 0x80_12_34_56);
+        assert_eq!(color_u32_with_alpha(c, 0x00), 0x00_12_34_56);
+        // Full alpha is identical to the opaque packing.
+        assert_eq!(color_u32_with_alpha(c, 0xFF), color_u32(c));
+    }
+
+    #[test]
+    fn bg_alpha_applies_only_to_the_default_background() {
+        let default_bg = Color::rgb(0x1e, 0x1e, 0x2e);
+        let a = BgAlpha {
+            alpha: 0xCC,
+            default_bg,
+        };
+        assert_eq!(a.for_bg(default_bg), 0xCC);
+        assert_eq!(a.for_bg(Color::rgb(0xAA, 0xBB, 0xCC)), 0xFF);
+    }
+
     #[test]
     fn dim_color_reduces_brightness() {
         let c = 0xFF_80_80_80u32;

src/renderer/render_ops.rs

@@ -248,6 +248,7 @@ impl App {
                 &self.state.theme,
                 update_badge.as_ref(),
                 self.state.hovered_url.as_deref(),
+                self.state.config.window.opacity,
             );
 
             // Capture screenshot before overlays; views/guards still alive here.