Add a Themes settings page listing every terminal theme; TextBox leaves beta

CLI/CMUXCLI+DocsSettings.swift

@@ -747,7 +747,7 @@ extension CMUXCLI {
           docs                Print the same output as `cmux docs settings`.
 
         Targets:
-          account, app, terminal, networking, computers, devices, sidebar-appearance,
+          account, app, themes, terminal, networking, computers, devices, sidebar-appearance,
           custom-sidebars, automation, browser, browser-import,
           global-hotkey, keyboard-shortcuts, shortcuts, workspace-colors,
           cmux-json, json, reset
@@ -779,6 +779,8 @@ extension CMUXCLI {
             return "account"
         case "app", "general":
             return "app"
+        case "themes", "theme", "appearance":
+            return "themes"
         case "terminal":
             return "terminal"
         case "sidebar", "sidebar-appearance", "sidebarappearance":

Packages/macOS/CmuxAppKitSupportUI/Sources/CmuxAppKitSupportUI/IconRendering/CmuxResolvedIconImageView.swift

@@ -1,9 +1,15 @@
 public import AppKit
 
 /// AppKit image view that re-renders its icon when the window or effective appearance changes.
+///
+/// The rendered bitmap already carries every intended opacity (tint, hover,
+/// disabled), so it is drawn as-is by ``BitmapView`` rather than an
+/// `NSImageView`. `NSImageView` in a titlebar dims its image to about 45%
+/// whenever the window is not key, which made titlebar symbols change color
+/// on focus loss while drawn chrome beside them did not.
 @MainActor
 public final class CmuxResolvedIconImageView: NSView {
-    private let imageView = NSImageView(frame: .zero)
+    private let imageView = BitmapView(frame: .zero)
     private let renderer = CmuxResolvedIconRenderer()
     private var request: CmuxResolvedIconRequest?
     private var renderKey: RenderKey?
@@ -14,10 +20,6 @@ public final class CmuxResolvedIconImageView: NSView {
     public override init(frame frameRect: NSRect) {
         super.init(frame: frameRect)
         imageView.translatesAutoresizingMaskIntoConstraints = false
-        imageView.imageScaling = .scaleProportionallyDown
-        imageView.imageAlignment = .alignCenter
-        imageView.animates = false
-        imageView.contentTintColor = nil
         addSubview(imageView)
         NSLayoutConstraint.activate([
             imageView.leadingAnchor.constraint(equalTo: leadingAnchor),
@@ -80,7 +82,6 @@ public final class CmuxResolvedIconImageView: NSView {
                 break
             }
         }
-        imageView.contentTintColor = nil
     }
 
     private func updateAccessibilityDescription(_ description: String?) {
@@ -192,3 +193,50 @@ public final class CmuxResolvedIconImageView: NSView {
         }
     }
 }
+
+/// Draws a pre-rendered bitmap centered in its bounds, scaled down (never up)
+/// to fit, matching `NSImageView`'s `.scaleProportionallyDown` +
+/// `.alignCenter` layout without its window-activity and enabled-state dimming.
+@MainActor
+final class BitmapView: NSView {
+    var image: NSImage? {
+        didSet {
+            guard image !== oldValue else { return }
+            if image?.size != oldValue?.size {
+                invalidateIntrinsicContentSize()
+            }
+            needsDisplay = true
+        }
+    }
+
+    override var isFlipped: Bool { true }
+
+    override var intrinsicContentSize: NSSize {
+        image?.size ?? NSSize(width: NSView.noIntrinsicMetric, height: NSView.noIntrinsicMetric)
+    }
+
+    override func draw(_ dirtyRect: NSRect) {
+        guard let image, image.size.width > 0, image.size.height > 0 else { return }
+        image.draw(
+            in: Self.drawRect(imageSize: image.size, in: bounds),
+            from: .zero,
+            operation: .sourceOver,
+            fraction: 1,
+            respectFlipped: true,
+            hints: nil
+        )
+    }
+
+    /// The image rect: its natural size, shrunk proportionally when larger
+    /// than `bounds`, centered and pixel-aligned in points.
+    nonisolated static func drawRect(imageSize: NSSize, in bounds: NSRect) -> NSRect {
+        let scale = min(1, bounds.width / imageSize.width, bounds.height / imageSize.height)
+        let size = NSSize(width: imageSize.width * scale, height: imageSize.height * scale)
+        return NSRect(
+            x: (bounds.midX - size.width / 2).rounded(),
+            y: (bounds.midY - size.height / 2).rounded(),
+            width: size.width,
+            height: size.height
+        )
+    }
+}

Packages/macOS/CmuxAppKitSupportUI/Sources/CmuxAppKitSupportUI/WindowChrome/Appearance/WindowAppearanceResolver.swift

@@ -74,7 +74,8 @@ public struct WindowAppearanceResolver {
                 opacity: terminalAppearance.backgroundOpacity
             )
         return current(settings: WindowAppearanceUserSettingsSnapshot(
-            unifySurfaceBackdrops: defaults.object(forKey: "sidebarMatchTerminalBackground") as? Bool ?? false,
+            unifySurfaceBackdrops: defaults.object(forKey: "sidebarMatchTerminalBackground") as? Bool
+                ?? WindowChromeSidebarTintDefaults.matchesTerminalBackground,
             colorScheme: ambientScheme,
             sidebarMaterial: defaults.string(forKey: "sidebarMaterial") ?? WindowChromeSidebarMaterialOption.sidebar.rawValue,
             sidebarBlendMode: defaults.string(forKey: "sidebarBlendMode") ?? WindowChromeSidebarBlendModeOption.withinWindow.rawValue,

Packages/macOS/CmuxAppKitSupportUI/Sources/CmuxAppKitSupportUI/WindowChrome/Appearance/WindowAppearanceSnapshot.swift

@@ -230,6 +230,21 @@ public struct WindowAppearanceSnapshot {
         sidebarColorScheme
     }
 
+    /// The opaque color the left sidebar's content is drawn over when it
+    /// shares the terminal backdrop, or `nil` when the sidebar draws its own
+    /// material (whose colors AppKit already keeps readable).
+    ///
+    /// Secondary text uses this to hold a contrast floor on saturated
+    /// terminal themes; see ``WindowChromeColorResolver/contrastFloored(_:over:minimumContrast:)``.
+    public var sidebarReadabilityBackdrop: NSColor? {
+        guard unifySurfaceBackdrops else { return nil }
+        return Self.compositedTerminalColor(
+            backgroundColor: terminalBackgroundColor,
+            opacity: Double(terminalBackgroundOpacity),
+            over: Self.resolvedColor(.windowBackgroundColor, for: sidebarColorScheme)
+        )
+    }
+
     /// Returns the backdrop policy for one chrome role.
     public func policy(for role: WindowBackdropRole) -> WindowBackdropPolicy {
         switch role {

Packages/macOS/CmuxAppKitSupportUI/Sources/CmuxAppKitSupportUI/WindowChrome/Color/WindowChromeColorResolver.swift

@@ -69,6 +69,43 @@ public struct WindowChromeColorResolver: Sendable {
         )
     }
 
+    /// Returns `foreground` with just enough extra opacity to reach
+    /// `minimumContrast` (a WCAG contrast ratio) once composited over
+    /// `background`.
+    ///
+    /// Secondary chrome text is the label color at reduced opacity, which is
+    /// tuned for neutral backgrounds. Over a saturated mid-tone terminal
+    /// theme the same opacity can fall to about 2.6:1. A color that already
+    /// meets the floor comes back unchanged, so neutral themes keep the
+    /// system look; one that cannot reach it comes back fully opaque.
+    public func contrastFloored(
+        _ foreground: NSColor,
+        over background: NSColor,
+        minimumContrast: CGFloat
+    ) -> NSColor {
+        let color = foreground.usingColorSpace(.sRGB) ?? foreground
+        let backgroundLuminance = relativeLuminance(compositedColor(background, over: .black))
+        func contrast(atAlpha alpha: CGFloat) -> CGFloat {
+            let composited = compositedColor(color.withAlphaComponent(alpha), over: background)
+            return contrastRatio(relativeLuminance(composited), backgroundLuminance)
+        }
+        let startAlpha = color.alphaComponent
+        guard contrast(atAlpha: startAlpha) < minimumContrast else { return foreground }
+        guard contrast(atAlpha: 1) >= minimumContrast else { return color.withAlphaComponent(1) }
+        var low = startAlpha
+        var high: CGFloat = 1
+        for _ in 0..<12 {
+            let mid = (low + high) / 2
+            if contrast(atAlpha: mid) >= minimumContrast { high = mid } else { low = mid }
+        }
+        return color.withAlphaComponent(high)
+    }
+
+    /// Returns the WCAG contrast ratio between two opaque colors.
+    public func contrastRatio(_ lhs: NSColor, _ rhs: NSColor) -> CGFloat {
+        contrastRatio(relativeLuminance(lhs), relativeLuminance(rhs))
+    }
+
     /// Returns the color scheme with stronger contrast against `backgroundColor`.
     public func readableColorScheme(for backgroundColor: NSColor) -> ColorScheme {
         let backgroundLuminance = relativeLuminance(backgroundColor)

Packages/macOS/CmuxAppKitSupportUI/Sources/CmuxAppKitSupportUI/WindowChrome/Sidebar/WindowChromeSidebarTintDefaults.swift

@@ -6,6 +6,11 @@ public struct WindowChromeSidebarTintDefaults: Sendable {
     /// Default tint opacity.
     public let opacity: Double
 
+    /// Whether the sidebar uses the terminal background instead of the tint
+    /// when the user has not chosen. Mirrors the
+    /// `sidebarAppearance.matchTerminalBackground` catalog default.
+    public static let matchesTerminalBackground = true
+
     /// Creates sidebar tint defaults.
     public init(
         hex: String = "#000000",

Packages/macOS/CmuxAppKitSupportUI/Tests/CmuxAppKitSupportUITests/BitmapViewLayoutTests.swift

@@ -0,0 +1,19 @@
+import AppKit
+import Testing
+
+@testable import CmuxAppKitSupportUI
+
+/// `BitmapView` replaces `NSImageView` for hosted icons, so it must keep the
+/// `.scaleProportionallyDown` + `.alignCenter` layout icons were tuned for.
+@Suite struct BitmapViewLayoutTests {
+    @Test func smallerImageKeepsItsSizeAndIsCentered() {
+        let rect = BitmapView.drawRect(imageSize: NSSize(width: 14, height: 14), in: NSRect(x: 0, y: 0, width: 22, height: 22))
+        #expect(rect == NSRect(x: 4, y: 4, width: 14, height: 14))
+    }
+
+    @Test func largerImageShrinksProportionally() {
+        let rect = BitmapView.drawRect(imageSize: NSSize(width: 40, height: 20), in: NSRect(x: 0, y: 0, width: 20, height: 20))
+        #expect(rect.size == NSSize(width: 20, height: 10))
+        #expect(rect.midY == 10)
+    }
+}

Packages/macOS/CmuxAppKitSupportUI/Tests/CmuxAppKitSupportUITests/CmuxResolvedIconRendererTests.swift

@@ -409,7 +409,7 @@ import Testing
     }
 
     private func renderedImage(in view: CmuxResolvedIconImageView) -> NSImage? {
-        view.subviews.compactMap { ($0 as? NSImageView)?.image }.first
+        view.subviews.compactMap { ($0 as? BitmapView)?.image }.first
     }
 
     private func prewarmImageCache(_ image: NSImage) {

Packages/macOS/CmuxAppKitSupportUI/Tests/CmuxAppKitSupportUITests/CmuxResolvedIconSymbolPointSizeTests.swift

@@ -92,7 +92,7 @@ import Testing
     }
 
     private func renderedImage(in view: CmuxResolvedIconImageView) -> NSImage? {
-        view.subviews.compactMap { $0 as? NSImageView }.first?.image
+        view.subviews.compactMap { $0 as? BitmapView }.first?.image
     }
 
     private func directDraw(_ image: NSImage, size: NSSize) -> NSImage? {

Packages/macOS/CmuxAppKitSupportUI/Tests/CmuxAppKitSupportUITests/WindowChrome/Appearance/WindowAppearanceResolverTests.swift

@@ -182,6 +182,28 @@ import Testing
         #expect(snapshot.resolvedColorScheme == terminalScheme)
     }
 
+    /// A user who never chose keeps the sidebar and titlebar on the terminal
+    /// background, so a light terminal theme never sits beside dark chrome.
+    @Test func sidebarMatchesTerminalBackgroundUntilTheUserOptsOut() throws {
+        let suiteName = "cmux.tests.match-terminal-default"
+        let defaults = try #require(UserDefaults(suiteName: suiteName))
+        defaults.removePersistentDomain(forName: suiteName)
+        defer { defaults.removePersistentDomain(forName: suiteName) }
+        let resolver = WindowAppearanceResolver(
+            terminalAppearance: WindowTerminalAppearanceSnapshot(
+                backgroundColor: NSColor(hex: "#FFFFFF") ?? .white,
+                backgroundOpacity: 1,
+                backgroundBlur: .disabled,
+                usesHostLayerBackground: true
+            )
+        )
+
+        #expect(resolver.currentFromUserDefaults(defaults: defaults).unifySurfaceBackdrops)
+
+        defaults.set(false, forKey: "sidebarMatchTerminalBackground")
+        #expect(!resolver.currentFromUserDefaults(defaults: defaults).unifySurfaceBackdrops)
+    }
+
     @Test func ghosttyMacOSGlassStyleForcesClearRootAndTerminalTintedGlass() {
         let resolver = WindowAppearanceResolver(
             terminalAppearance: WindowTerminalAppearanceSnapshot(

Packages/macOS/CmuxAppKitSupportUI/Tests/CmuxAppKitSupportUITests/WindowChrome/Color/WindowChromeColorResolverContrastTests.swift

@@ -0,0 +1,47 @@
+import AppKit
+import Testing
+
+@testable import CmuxAppKitSupportUI
+
+@Suite struct WindowChromeColorResolverContrastTests {
+    private let resolver = WindowChromeColorResolver()
+
+    /// Hot Dog Stand's red backdrop took half-opacity black secondary text to
+    /// about 2.6:1; the floor raises only the opacity until it reads.
+    @Test func saturatedBackdropRaisesSecondaryOpacityToTheFloor() throws {
+        let red = try #require(NSColor(hex: "#E44330"))
+        let secondary = NSColor(srgbRed: 0, green: 0, blue: 0, alpha: 0.5)
+        #expect(contrast(secondary, over: red) < 3.5)
+
+        let floored = resolver.contrastFloored(secondary, over: red, minimumContrast: 3.5)
+
+        #expect(contrast(floored, over: red) >= 3.5)
+        #expect(floored.alphaComponent > secondary.alphaComponent)
+        #expect(floored.alphaComponent < 1)
+    }
+
+    /// Neutral themes keep the system secondary color untouched.
+    @Test func readableSecondaryIsReturnedUnchanged() throws {
+        let white = try #require(NSColor(hex: "#FFFFFF"))
+        let secondary = NSColor(srgbRed: 0, green: 0, blue: 0, alpha: 0.5)
+
+        let floored = resolver.contrastFloored(secondary, over: white, minimumContrast: 3.5)
+
+        #expect(floored.alphaComponent == secondary.alphaComponent)
+    }
+
+    /// When even the opaque color cannot reach the floor, the most readable
+    /// version, fully opaque, is returned.
+    @Test func unreachableFloorReturnsOpaqueColor() throws {
+        let gray = try #require(NSColor(hex: "#777777"))
+        let secondary = NSColor(srgbRed: 1, green: 1, blue: 1, alpha: 0.5)
+
+        let floored = resolver.contrastFloored(secondary, over: gray, minimumContrast: 7)
+
+        #expect(floored.alphaComponent == 1)
+    }
+
+    private func contrast(_ foreground: NSColor, over background: NSColor) -> CGFloat {
+        resolver.contrastRatio(resolver.compositedColor(foreground, over: background), background)
+    }
+}

Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/ConfigValidation/CmuxConfigSchema.generated.swift

@@ -834,13 +834,13 @@ enum CmuxEmbeddedConfigSchema {
           "type": "boolean",
           "default": false,
           "descriptionKey": "schemaDescriptions.terminal.showTextBoxOnNewTerminals",
-          "description": "Show the beta TextBox input by default for newly created workspaces, terminal tabs, and terminal splits."
+          "description": "Show the TextBox input by default for newly created workspaces, terminal tabs, and terminal splits."
         },
         "focusTextBoxOnNewTerminals": {
           "type": "boolean",
           "default": false,
           "descriptionKey": "schemaDescriptions.terminal.focusTextBoxOnNewTerminals",
-          "description": "Focus the beta TextBox input by default for newly created workspaces, terminal tabs, and terminal splits. Focusing also shows the TextBox."
+          "description": "Focus the TextBox input by default for newly created workspaces, terminal tabs, and terminal splits. Focusing also shows the TextBox."
         },
         "agentHibernation": {
           "type": "object",
@@ -1570,7 +1570,7 @@ enum CmuxEmbeddedConfigSchema {
       "properties": {
         "matchTerminalBackground": {
           "type": "boolean",
-          "default": false,
+          "default": true,
           "description": "Use the terminal background instead of the sidebar tint."
         },
         "tintColor": {

Packages/macOS/CmuxSettings/Sources/CmuxSettings/Keys/SidebarAppearanceCatalogSection.swift

@@ -4,7 +4,7 @@ import Foundation
 public struct SidebarAppearanceCatalogSection: SettingCatalogSection {
     public let matchTerminalBackground = DefaultsKey<Bool>(
         id: "sidebarAppearance.matchTerminalBackground",
-        defaultValue: false,
+        defaultValue: true,
         userDefaultsKey: "sidebarMatchTerminalBackground"
     )