Auto-assign distinct colors to split panes

.github/swift-file-length-budget.tsv

@@ -5,9 +5,9 @@
 17954	Sources/AppDelegate.swift
 16427	Sources/ContentView.swift
 14270	Sources/TerminalController.swift
-13172	Sources/Workspace.swift
+13349	Sources/Workspace.swift
 12348	cmuxTests/AppDelegateShortcutRoutingTests.swift
-12296	Sources/GhosttyTerminalView.swift
+12324	Sources/GhosttyTerminalView.swift
 11669	Sources/Panels/BrowserPanel.swift
 9497	cmuxTests/CLINotifyProcessIntegrationRegressionTests.swift
 8032	Sources/Panels/BrowserPanelView.swift
@@ -24,8 +24,8 @@
 4483	Sources/cmuxApp.swift
 4482	Sources/Panels/FilePreviewPanel.swift
 4367	cmuxTests/BrowserPanelTests.swift
-4283	Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
 4121	Sources/BrowserWindowPortal.swift
+3964	Packages/iOS/CmuxMobileTerminal/Sources/CmuxMobileTerminal/GhosttySurfaceView.swift
 3934	Sources/Feed/FeedPanelView.swift
 3926	cmuxTests/TabManagerUnitTests.swift
 3896	cmuxTests/WindowAndDragTests.swift
@@ -45,7 +45,7 @@
 2229	Sources/TerminalWindowPortal.swift
 2126	cmuxTests/CmuxConfigTests.swift
 2085	cmuxTests/ShortcutAndCommandPaletteTests.swift
-2078	Sources/SessionPersistence.swift
+2081	Sources/SessionPersistence.swift
 2011	Sources/KeyboardShortcutSettingsFileStore.swift
 1944	Sources/RestorableAgentSession.swift
 1900	cmuxTests/NotificationAndMenuBarTests.swift
@@ -214,14 +214,14 @@
 549	Sources/Panels/BrowserAutomation.swift
 547	Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/BackingUpPairedMacStore.swift
 546	Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/AutomationSection.swift
+546	Sources/App/WorkspaceRuntimeSettings.swift
 544	cmuxUITests/DisplayResolutionRegressionUITests.swift
 540	Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/MobileTerminalRenderGridReplay.swift
 539	CLI/CMUXCLI+Themes.swift
 539	CLI/CodexTeamsApprovalBridge.swift
 538	Packages/Shared/CMUXMobileCore/Tests/CMUXMobileCoreTests/MobileTerminalRenderGridTests.swift
 538	Packages/macOS/CmuxRemoteWorkspace/Sources/CmuxRemoteWorkspace/PTYBridge/RemotePTYBridgeSession.swift
 536	cmuxTests/CmuxConfigContextMenuTests.swift
-535	Sources/App/WorkspaceRuntimeSettings.swift
 533	Packages/macOS/CmuxSettingsUI/Sources/CmuxSettingsUI/Scene/SettingsWindowScene.swift
 530	Sources/BrowserPaneDropTargetView.swift
 530	Sources/TerminalController+ControlSurfaceContext3.swift
@@ -250,8 +250,8 @@
 506	Sources/App/MainWindowVisibilityController.swift
 504	Packages/macOS/CmuxSettings/Tests/CmuxSettingsTests/UserDefaultsSettingsStoreTests.swift
 504	cmuxTests/TerminalNotificationSocketActionTests.swift
+503	Sources/RemoteTmuxSessionMirror.swift
 503	Sources/Settings/ConfigSource.swift
 502	Sources/CmuxEventPublishing.swift
-502	Sources/RemoteTmuxSessionMirror.swift
 500	Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandContextTestStubs.swift
 500	Sources/KeyboardShortcutRecorder.swift

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

@@ -27,6 +27,14 @@ public struct TerminalCatalogSection: SettingCatalogSection {
         userDefaultsKey: "terminal.autoResumeAgentSessions"
     )
 
+    /// Whether new terminal split panes automatically receive subtle, distinct
+    /// background tints so adjacent panes stay visually distinguishable. On by default.
+    public let autoTintSplitPanes = DefaultsKey<Bool>(
+        id: "terminal.autoTintSplitPanes",
+        defaultValue: true,
+        userDefaultsKey: "terminal.autoTintSplitPanes"
+    )
+
     public let agentHibernationEnabled = DefaultsKey<Bool>(
         id: "terminal.agentHibernation.enabled",
         defaultValue: false,

Sources/App/WorkspaceRuntimeSettings.swift

@@ -1,4 +1,5 @@
 import Darwin
+import CmuxSettings
 import Foundation
 
 enum WorkspaceTitlebarSettings {
@@ -203,6 +204,16 @@ enum TerminalCopyOnSelectSettings {
     }
 }
 
+struct TerminalSplitPaneTintSettings {
+    private static let autoTintSplitPanes = TerminalCatalogSection().autoTintSplitPanes
+    static var autoTintSplitPanesKey: String { autoTintSplitPanes.userDefaultsKey }
+    static var defaultAutoTintSplitPanes: Bool { autoTintSplitPanes.defaultValue }
+
+    func isEnabled(defaults: UserDefaults = .standard) -> Bool {
+        Self.autoTintSplitPanes.value(in: defaults)
+    }
+}
+
 enum TerminalManagedGhosttySettings {
     static func ghosttyConfigContents(defaults: UserDefaults = .standard, emitsCopyOnSelectFalse: Bool = true) -> String? {
         let lines = [

Sources/CmuxSettingsJSONPathSupport.swift

@@ -185,6 +185,11 @@ enum TerminalSettingsFileMapping {
             defaultsKey: AgentSessionAutoResumeSettings.autoResumeAgentSessionsKey,
             invalidPath: "terminal.autoResumeAgentSessions"
         ),
+        .init(
+            jsonKey: "autoTintSplitPanes",
+            defaultsKey: TerminalSplitPaneTintSettings.autoTintSplitPanesKey,
+            invalidPath: "terminal.autoTintSplitPanes"
+        ),
     ]
 }
 
@@ -369,6 +374,7 @@ extension CmuxSettingsFileStore {
         "terminal.scrollSpeed",
         "terminal.copyOnSelect",
         "terminal.autoResumeAgentSessions",
+        "terminal.autoTintSplitPanes",
         "terminal.showTextBoxOnNewTerminals",
         "terminal.focusTextBoxOnNewTerminals",
         "terminal.textBoxDefaultSubmitAction",

Sources/GhosttyTerminalView.swift

@@ -308,6 +308,16 @@ extension TerminalSurface {
         }
         return hosted
     }
+
+    var paneBackgroundOverrideColor: NSColor? {
+        get { hostedView.paneBackgroundOverrideColor }
+        set { hostedView.paneBackgroundOverrideColor = newValue }
+    }
+
+    var autoAssignedSplitTintHex: String? {
+        get { hostedView.autoAssignedSplitTintHex }
+        set { hostedView.autoAssignedSplitTintHex = newValue }
+    }
 }
 
 // The engine's Metal layer reports vended drawables through this seam
@@ -8036,6 +8046,24 @@ final class GhosttySurfaceScrollView: NSView {
         return window
     }
 
+    var paneBackgroundOverrideColor: NSColor? {
+        get { surfaceView.backgroundColor }
+        set {
+            surfaceView.backgroundColor = newValue
+            surfaceView.applySurfaceBackground()
+            surfaceView.applyWindowBackgroundIfActive()
+        }
+    }
+
+    /// Hex of the split-pane tint cmux most recently assigned to this surface,
+    /// or nil when cmux never auto-tinted it. This is provenance for session
+    /// persistence only: `paneBackgroundOverrideColor` is a shared slot that
+    /// terminal OSC background changes (`GHOSTTY_ACTION_COLOR_CHANGE`) and
+    /// Ghostty config reloads (`GHOSTTY_ACTION_CONFIG_CHANGE`) also write, so a
+    /// live override is a cmux-owned tint worth persisting only while it still
+    /// equals this value. See `TerminalSplitPaneTintPlanner.persistableTintHex`.
+    var autoAssignedSplitTintHex: String?
+
     func forwardKeyDownToSurface(_ event: NSEvent) {
         surfaceView.keyDown(with: event)
     }

Sources/KeyboardShortcutSettingsFileStore+Template.swift

@@ -93,6 +93,7 @@ extension CmuxSettingsFileStore {
                     "scrollSpeed": TerminalScrollSpeedSettings.defaultMultiplier,
                     "copyOnSelect": TerminalCopyOnSelectSettings.defaultCopyOnSelect,
                     "autoResumeAgentSessions": AgentSessionAutoResumeSettings.defaultAutoResumeAgentSessions,
+                    "autoTintSplitPanes": TerminalSplitPaneTintSettings.defaultAutoTintSplitPanes,
                     "showTextBoxOnNewTerminals": TerminalTextBoxInputSettings.defaultShowOnNewTerminals,
                     "focusTextBoxOnNewTerminals": TerminalTextBoxInputSettings.defaultFocusOnNewTerminals,
                     "textBoxDefaultSubmitAction": TerminalTextBoxInputSettings.defaultSubmitActionID,

Sources/RemoteTmuxSessionMirror.swift

@@ -330,6 +330,7 @@ final class RemoteTmuxSessionMirror {
             panelId: panelId,
             connection: connection,
             layout: window.layout,
+            paneTintDefaults: workspace.terminalSplitPaneTintDefaults,
             makePanel: { [weak workspace, weak connection] tmuxPaneId in
                 workspace?.makeRemoteTmuxPanePanel(onInput: { data in
                     Task { @MainActor in connection?.sendKeys(paneId: tmuxPaneId, data: data) }

Sources/RemoteTmuxWindowMirror.swift

@@ -1,5 +1,6 @@
 import AppKit
 import Bonsplit
+import CmuxFoundation
 import CmuxTerminal
 import Foundation
 import Observation
@@ -25,6 +26,7 @@ final class RemoteTmuxWindowMirror {
     @ObservationIgnored private weak var connection: RemoteTmuxControlConnection?
     /// Creates a configured manual-I/O pane panel whose input goes to `tmuxPaneId`.
     @ObservationIgnored private let makePanel: (_ tmuxPaneId: Int) -> TerminalPanel?
+    @ObservationIgnored private let paneTintDefaults: UserDefaults
 
     /// The window's current pane layout — drives the SwiftUI split container.
     private(set) var layout: RemoteTmuxLayoutNode
@@ -44,12 +46,14 @@ final class RemoteTmuxWindowMirror {
         panelId: UUID,
         connection: RemoteTmuxControlConnection,
         layout: RemoteTmuxLayoutNode,
+        paneTintDefaults: UserDefaults = .standard,
         makePanel: @escaping (_ tmuxPaneId: Int) -> TerminalPanel?
     ) {
         self.windowId = windowId
         self.panelId = panelId
         self.connection = connection
         self.makePanel = makePanel
+        self.paneTintDefaults = paneTintDefaults
         self.layout = layout
         reconcile(layout: layout)
     }
@@ -95,6 +99,34 @@ final class RemoteTmuxWindowMirror {
             if activePaneId == paneId { activePaneId = nil }
         }
         if layout != newLayout { layout = newLayout }
+        applyAutomaticPaneTints()
+    }
+
+    private func applyAutomaticPaneTints() {
+        guard TerminalSplitPaneTintSettings().isEnabled(defaults: paneTintDefaults) else { return }
+        let baseColor = GhosttyApp.shared.defaultBackgroundColor
+        var usedHexes = Set(
+            panelsByPaneId.values.compactMap { panel in
+                panel.surface.paneBackgroundOverrideColor?.hexString()
+            }
+        )
+        var selectedHexes = Set<String>()
+        for paneId in paneIDsInOrder {
+            guard let panel = panelsByPaneId[paneId],
+                  panel.surface.paneBackgroundOverrideColor == nil,
+                  let color = TerminalSplitPaneTintPlanner.nextColor(
+                    baseColor: baseColor,
+                    usedHexes: usedHexes,
+                    excludedHexes: selectedHexes
+                  ) else {
+                continue
+            }
+            panel.surface.paneBackgroundOverrideColor = color
+            let hex = color.hexString()
+            panel.surface.autoAssignedSplitTintHex = hex
+            usedHexes.insert(hex)
+            selectedHexes.insert(hex)
+        }
     }
 
     /// Routes a tmux `%output` to the surface for `paneId` (no-op if unknown).

Sources/SessionPersistence.swift

@@ -1395,6 +1395,7 @@ struct SessionTerminalPanelSnapshot: Codable, Sendable {
     var textBoxDraft: SessionTextBoxInputDraftSnapshot?
     var isRemoteTerminal: Bool?
     var remotePTYSessionID: String?
+    var backgroundColorHex: String?
     /// Whether the agent process was actively running when this snapshot was captured.
     /// Nil means unknown (legacy snapshots); treated as true for backwards compatibility.
     var wasAgentRunning: Bool?
@@ -1409,6 +1410,7 @@ struct SessionTerminalPanelSnapshot: Codable, Sendable {
         textBoxDraft: SessionTextBoxInputDraftSnapshot? = nil,
         isRemoteTerminal: Bool? = nil,
         remotePTYSessionID: String? = nil,
+        backgroundColorHex: String? = nil,
         wasAgentRunning: Bool? = nil
     ) {
         self.workingDirectory = workingDirectory
@@ -1420,6 +1422,7 @@ struct SessionTerminalPanelSnapshot: Codable, Sendable {
         self.textBoxDraft = textBoxDraft
         self.isRemoteTerminal = isRemoteTerminal
         self.remotePTYSessionID = remotePTYSessionID
+        self.backgroundColorHex = backgroundColorHex
         self.wasAgentRunning = wasAgentRunning
     }
 }