Let TUI-painted cell backgrounds follow the window opacity (#306)

Author: thdxg

AGENTS.md

@@ -192,7 +192,7 @@ Automatic mode delegates the default user layer to `ghostty_config_load_default_
 `GhosttyConfigSource` is the matching raw-text seam for features whose values the C API cannot expose or whose user-stated value matters. It concatenates readable default root files in Ghostty order (XDG `config`, XDG `config.ghostty`, Application Support `config`, Application Support `config.ghostty`), followed by the custom files in Settings order. Recursive `config-file` includes are loaded by libghostty at runtime but remain outside those raw-text scans.
 
 - **`macterm-defaults.conf`** — first-launch tasteful defaults; anything in the user's config overrides them.
-- **`macterm-overrides.conf`** — keys Macterm must lock: `background-opacity = 0` / `background-blur = 0` (so `WindowAppearance` composites translucency itself without double-tinting), plus `env = GHOSTTY_BIN_DIR=<bundle>/Contents/Resources/ssh-bridge` and a `shell-integration-features` line forcing `no-path`. The shell-integration `ssh` wrapper execs `"$GHOSTTY_BIN_DIR/ghostty" +ssh`, and that dir holds Macterm's own `ghostty` shim (`scripts/ghostty-shim.sh`, installed by the "Bundle macterm CLI" post-build step), which relays to `macterm ssh` — so `ssh-env`/`ssh-terminfo` work with **no Ghostty.app installed** and are never forced off (only if the shim is missing from the bundle — a broken build — are they, so the wrapper falls through to plain `ssh` instead of dying on a bad exec). The shim lives in its own dir, NOT `Resources/bin` or `Contents/MacOS`, because both land on pane PATHs (`EnvironmentSetup` prepends bin; libghostty unconditionally appends the exe dir) and a `ghostty` that only answers `+ssh` must never be reachable by name — which is also why `no-path` is always forced (that feature's only effect is putting `GHOSTTY_BIN_DIR` on PATH). The features key can't be written bare — libghostty re-parses it from defaults on every occurrence, wiping the user's own flags — so `ShellIntegrationFeatures.overrideValue` re-emits the user's effective value with our `no-*` flags appended (#75). Because the override depends on the user's config content, `loadConfig` calls `regenerate()` before every load.
+- **`macterm-overrides.conf`** — keys Macterm must lock: `background-default-transparent = true` (fork patch 0004 — the renderer never paints the *default* background, so `WindowAppearance` composites translucency itself without double-tinting; the same renderer mechanism ghostty's macOS glass styles use, exposed as a config key), `background-opacity = <Preferences.windowOpacity>` (the REAL opacity, not a pinned 0 — that's what lets the user's own `background-opacity-cells` flag work as ghostty documents it, making TUI-painted cell backgrounds translucent at the window opacity; under the old `background-opacity = 0` pin that flag multiplied every painted cell to invisible. `Preferences.windowOpacity` keeps it current via a debounced regenerate+reload — the instant window resync stays on the cheap no-reload path), `background-blur = 0` (Macterm calls the CGS blur SPI itself), plus `env = GHOSTTY_BIN_DIR=<bundle>/Contents/Resources/ssh-bridge` and a `shell-integration-features` line forcing `no-path`. The shell-integration `ssh` wrapper execs `"$GHOSTTY_BIN_DIR/ghostty" +ssh`, and that dir holds Macterm's own `ghostty` shim (`scripts/ghostty-shim.sh`, installed by the "Bundle macterm CLI" post-build step), which relays to `macterm ssh` — so `ssh-env`/`ssh-terminfo` work with **no Ghostty.app installed** and are never forced off (only if the shim is missing from the bundle — a broken build — are they, so the wrapper falls through to plain `ssh` instead of dying on a bad exec). The shim lives in its own dir, NOT `Resources/bin` or `Contents/MacOS`, because both land on pane PATHs (`EnvironmentSetup` prepends bin; libghostty unconditionally appends the exe dir) and a `ghostty` that only answers `+ssh` must never be reachable by name — which is also why `no-path` is always forced (that feature's only effect is putting `GHOSTTY_BIN_DIR` on PATH). The features key can't be written bare — libghostty re-parses it from defaults on every occurrence, wiping the user's own flags — so `ShellIntegrationFeatures.overrideValue` re-emits the user's effective value with our `no-*` flags appended (#75). Because the override depends on the user's config content, `loadConfig` calls `regenerate()` before every load.
 
 Macterm-specific UI state (window opacity/blur, quick terminal, hotkeys, auto-tile) lives in `Preferences` and never touches the ghostty config pipeline.
 

Macterm/App/Preferences.swift

@@ -372,15 +372,20 @@ final class Preferences {
 
     // MARK: - Window
 
-    /// Macterm-painted window background opacity (0–1). Independent from
-    /// ghostty's renderer — `macterm-overrides.conf` pins `background-opacity
-    /// = 0` so ghostty draws fully transparent, then Macterm composites this
-    /// translucency at the window level. Avoids the double-paint problem when
-    /// both layers tint.
+    /// Macterm-painted window background opacity (0–1). Macterm composites
+    /// this translucency at the window level while `macterm-overrides.conf`
+    /// sets `background-default-transparent` so ghostty never paints the
+    /// default background — avoiding the double-paint problem when both
+    /// layers tint. The value is also written into the overrides as
+    /// `background-opacity`, which ghostty applies to TUI-painted cell
+    /// backgrounds when the user's own `background-opacity-cells` flag is
+    /// on — hence the debounced config reload alongside the instant window
+    /// resync.
     var windowOpacity: Double {
         didSet {
             defaults.set(windowOpacity, forKey: Keys.windowOpacity)
             notifyWindowAppearanceChanged()
+            scheduleGhosttyConfigReload()
         }
     }
 
@@ -481,16 +486,36 @@ final class Preferences {
 
     /// Notify observers that a WINDOW-APPEARANCE pref (opacity/blur/glass)
     /// changed, WITHOUT regenerating the ghostty config or reloading libghostty.
-    /// Those values don't appear in the regenerated files (`background-opacity`
-    /// is pinned to 0 unconditionally) — `WindowAppearance.sync` reads them
-    /// straight from Preferences. Previously these setters ran the full
-    /// `notifyConfigChanged()` (two file writes + a whole-config libghostty
-    /// reload) purely to piggy-back on the `.mactermConfigDidChange` post it
-    /// ends with — heavyweight, and fired continuously while dragging a slider.
+    /// `WindowAppearance.sync` reads these values straight from Preferences.
+    /// Previously these setters ran the full `notifyConfigChanged()` (two file
+    /// writes + a whole-config libghostty reload) purely to piggy-back on the
+    /// `.mactermConfigDidChange` post it ends with — heavyweight, and fired
+    /// continuously while dragging a slider.
+    ///
+    /// One value DOES also live in the regenerated overrides: `windowOpacity`
+    /// is written as ghostty's `background-opacity` (so the user's
+    /// `background-opacity-cells` makes painted cells translucent at the
+    /// window opacity). That side is followed by `scheduleGhosttyConfigReload`
+    /// below — debounced, so slider drags stay on this cheap path and the
+    /// libghostty reload fires once after the value settles.
     private func notifyWindowAppearanceChanged() {
         NotificationCenter.default.post(name: .mactermConfigDidChange, object: nil)
     }
 
+    /// The pending debounced reload for `windowOpacity`'s ghostty-side copy.
+    @ObservationIgnored private var ghosttyOpacityReloadTask: Task<Void, Never>?
+
+    /// Regenerate + reload the ghostty config shortly after the last call,
+    /// so a slider drag costs one whole-config reload instead of dozens.
+    private func scheduleGhosttyConfigReload() {
+        ghosttyOpacityReloadTask?.cancel()
+        ghosttyOpacityReloadTask = Task { @MainActor [weak self] in
+            try? await Task.sleep(for: .milliseconds(250))
+            guard !Task.isCancelled else { return }
+            self?.notifyConfigChanged()
+        }
+    }
+
     // MARK: - Quick terminal
 
     /// Fraction of screen width (0–1).

Macterm/Config/MactermConfig.swift

@@ -56,11 +56,39 @@ final class MactermConfig {
         ].joined(separator: "\n") + "\n"
         write(Data(defaults.utf8), to: defaultsURL)
 
+        let body = Self.overridesBody(
+            windowOpacity: Preferences.shared.windowOpacity,
+            userConfigText: userGhosttyConfigText(),
+            shimDirectory: Self.sshShimDirectory()
+        )
+        write(Data(body.utf8), to: overridesURL)
+    }
+
+    /// The full text of `macterm-overrides.conf`. Pure — live inputs are
+    /// passed in — so the wire contract with libghostty (most importantly the
+    /// fork's `background-default-transparent` key) is unit-testable without
+    /// touching disk.
+    static func overridesBody(
+        windowOpacity: Double,
+        userConfigText: String?,
+        shimDirectory: String?
+    ) -> String {
         var overrides = [
             // Macterm composites window translucency at the AppKit level —
-            // ghostty must draw a fully transparent terminal or we'd double-
-            // tint. See WindowAppearance.swift.
-            "background-opacity = 0",
+            // ghostty must not paint the default background or we'd double-
+            // tint. See WindowAppearance.swift. This fork key skips exactly
+            // that paint (the same renderer mechanism ghostty's own macOS
+            // glass styles use) while leaving `background-opacity`
+            // meaningful for everything else.
+            "background-default-transparent = true",
+            // The real window opacity, so the user's own
+            // `background-opacity-cells` flag works as ghostty documents it:
+            // TUI-painted cell backgrounds become translucent at the window
+            // opacity. Before the fork key existed this was pinned to 0 —
+            // which that flag multiplies into every painted cell, turning
+            // them invisible instead of translucent. Kept current by the
+            // debounced reload in `Preferences.windowOpacity`.
+            "background-opacity = \(windowOpacity)",
             // We call CGSSetWindowBackgroundBlurRadius ourselves; ghostty's
             // own blur would compose on top of it.
             "background-blur = 0",
@@ -81,8 +109,8 @@ final class MactermConfig {
         // GHOSTTY_BIN_DIR on PATH, and the shim answers nothing but `+ssh` —
         // exposing it as a bare `ghostty` would impersonate the real CLI.
         var disabledFeatures = ["no-path"]
-        if let shimDir = Self.sshShimDirectory() {
-            overrides.append("env = GHOSTTY_BIN_DIR=\(shimDir)")
+        if let shimDirectory {
+            overrides.append("env = GHOSTTY_BIN_DIR=\(shimDirectory)")
         } else {
             disabledFeatures.append(contentsOf: ["no-ssh-env", "no-ssh-terminfo"])
         }
@@ -92,21 +120,21 @@ final class MactermConfig {
         // Re-emit the user's effective value with our forced flags appended
         // so only those change. (#75)
         let value = ShellIntegrationFeatures.overrideValue(
-            userConfigText: userGhosttyConfigText(),
+            userConfigText: userConfigText,
             disabled: disabledFeatures
         )
         if let value {
             overrides.append("shell-integration-features = \(value)")
         }
 
-        let body = overrides.joined(separator: "\n") + "\n"
-        write(Data(body.utf8), to: overridesURL)
+        return overrides.joined(separator: "\n") + "\n"
     }
 
     /// Write a wrapper-config file, logging on failure. These writes are
     /// behavior-changing — a failed overrides write silently breaks the
-    /// translucency contract (`background-opacity = 0` never lands, causing
-    /// double-tinting) — so a swallowed `try?` would leave zero diagnostics.
+    /// translucency contract (`background-default-transparent` never lands,
+    /// causing double-tinting) — so a swallowed `try?` would leave zero
+    /// diagnostics.
     private func write(_ data: Data, to url: URL) {
         do {
             try data.write(to: url, options: .atomic)

Macterm/Ghostty/GhosttyApp.swift

@@ -84,9 +84,13 @@ final class GhosttyApp {
         rt.supports_selection_clipboard = true
         rt.wakeup_cb = { _ in GhosttyApp.shared.callbacks.wakeup() }
         rt.action_cb = { _, target, action in GhosttyApp.shared.callbacks.action(target: target, action: action) }
-        rt.read_clipboard_cb = { ud, loc, state in GhosttyApp.shared.callbacks.readClipboard(ud: ud, location: loc, state: state) }
-        rt.confirm_read_clipboard_cb = { ud, content, state, _ in
-            GhosttyApp.shared.callbacks.confirmReadClipboard(ud: ud, content: content, state: state)
+        rt.read_clipboard_cb = { ud, _, state, mimes, mimesLen, list in
+            GhosttyApp.shared.callbacks.readClipboard(
+                ud: ud, state: state, mimes: mimes, mimesLen: mimesLen, list: list
+            )
+        }
+        rt.confirm_read_clipboard_cb = { ud, confirm, state, _ in
+            GhosttyApp.shared.callbacks.confirmReadClipboard(ud: ud, confirm: confirm, state: state)
         }
         rt.write_clipboard_cb = { _, loc, content, len, confirm in
             GhosttyApp.shared.callbacks.writeClipboard(
@@ -445,8 +449,9 @@ final class GhosttyApp {
         //   2. User's Ghostty config files, overriding any default. In automatic
         //      mode, libghostty loads its default roots.
         //   3. Macterm overrides — keys Macterm absolutely needs to control,
-        //      currently just background-opacity/blur for the window-level
-        //      translucency contract. Loaded last so it overrides the user.
+        //      currently the background keys for the window-level translucency
+        //      contract (default-background paint, opacity value, blur).
+        //      Loaded last so it overrides the user.
         // libghostty merges last-wins, so this ordering produces:
         //   Macterm defaults < user's Ghostty config < Macterm overrides
         MactermConfig.shared.defaultsPath.withCString { ghostty_config_load_file(cfg, $0) }