Improve heavy workspace switch latency

Sources/BackgroundWorkspacePrimeCoordinator.swift

@@ -3,6 +3,8 @@ import Combine
 
 @MainActor
 final class BackgroundWorkspacePrimeCoordinator {
+    private let timeoutSeconds: TimeInterval
+
     private nonisolated enum PrimeCompletionReason: String {
         case alreadyCleared = "already_cleared"
         case cancelled
@@ -93,10 +95,26 @@ final class BackgroundWorkspacePrimeCoordinator {
         }
     }
 
+    init(timeoutSeconds: TimeInterval = Policy.timeoutSeconds) {
+        self.timeoutSeconds = timeoutSeconds
+    }
+
     deinit {
         // Explicit for the required_deinit lint; per-prime resources live on Waiter.
     }
 
+#if DEBUG
+    func debugPrimeBackgroundWorkspaceOnceForTesting(
+        workspaceId: UUID,
+        tabManager: TabManager
+    ) async -> String {
+        await primeBackgroundWorkspaceIfNeeded(
+            workspaceId: workspaceId,
+            tabManager: tabManager
+        ).rawValue
+    }
+#endif
+
     func taskKey(for tabManager: TabManager) -> [String] {
         tabManager.pendingBackgroundWorkspaceLoadIds
             .map(\.uuidString)
@@ -114,8 +132,6 @@ final class BackgroundWorkspacePrimeCoordinator {
 
                 switch reason {
                 case .timeout:
-                    // Keep the hidden mount retained; pending background initial commands
-                    // must stay eligible to start until the surface is actually ready.
                     continue
                 case .cancelled:
                     continue
@@ -141,14 +157,22 @@ final class BackgroundWorkspacePrimeCoordinator {
         cmuxDebugLog("workspace.backgroundPrime.start workspace=\(workspaceId.uuidString.prefix(5))")
 #endif
 
-        let completionReason: PrimeCompletionReason
+        var completionReason: PrimeCompletionReason = .cancelled
+        defer {
+            switch completionReason {
+            case .timeout, .cancelled:
+                tabManager.releaseBackgroundWorkspaceMount(for: workspaceId)
+            case .alreadyCleared, .surfaceReady, .workspaceRemoved:
+                break
+            }
+        }
         switch stepBackgroundWorkspacePrime(workspaceId: workspaceId, tabManager: tabManager) {
         case .completed(let reason):
             completionReason = reason
         case .pending:
             completionReason = await waitForBackgroundWorkspacePrimeCompletion(
                 workspaceId: workspaceId,
-                timeoutSeconds: Policy.timeoutSeconds,
+                timeoutSeconds: timeoutSeconds,
                 tabManager: tabManager
             )
         }

Sources/ContentView.swift

@@ -831,6 +831,20 @@ enum WorkspaceMountPolicy {
         return ordered
     }
 
+    static func pinnedWorkspaceIds(
+        retiringWorkspaceId: UUID?,
+        backgroundWorkspaceLoadIds: Set<UUID>,
+        debugPinnedWorkspaceLoadIds: Set<UUID>,
+        isCycleHot: Bool
+    ) -> Set<UUID> {
+        let handoffPinnedIds = retiringWorkspaceId.map { Set([ $0 ]) } ?? []
+        let shouldMountBackgroundLoads = retiringWorkspaceId == nil && !isCycleHot
+        let backgroundPinnedIds = shouldMountBackgroundLoads ? backgroundWorkspaceLoadIds : []
+        return handoffPinnedIds
+            .union(backgroundPinnedIds)
+            .union(debugPinnedWorkspaceLoadIds)
+    }
+
     private static func cycleWarmIds(selected: UUID, orderedTabIds: [UUID]) -> [UUID] {
         guard orderedTabIds.contains(selected) else { return [selected] }
         // Keep warming focused to the selected workspace. Retiring/target workspaces are
@@ -2786,6 +2800,13 @@ struct ContentView: View {
             scheduleTitlebarTextRefresh()
         })
 
+        view = AnyView(view.onReceive(NotificationCenter.default.publisher(for: .terminalPortalVisibilityDidChange)) { notification in
+            guard let tabId = notification.userInfo?[GhosttyNotificationKey.tabId] as? UUID,
+                  tabId == tabManager.selectedTabId,
+                  notification.userInfo?[GhosttyNotificationKey.terminalVisibleInUI] as? Bool == true else { return }
+            completeWorkspaceHandoffIfNeeded(focusedTabId: tabId, reason: "terminal_visible")
+        })
+
         view = AnyView(view.onChange(of: titlebarThemeGeneration) { oldValue, newValue in
             guard GhosttyApp.shared.backgroundLogEnabled else { return }
             GhosttyApp.shared.logBackground(
@@ -3271,11 +3292,14 @@ struct ContentView: View {
         let currentTabs = tabs ?? tabManager.tabs
         let orderedTabIds = currentTabs.map { $0.id }
         let effectiveSelectedId = selectedId ?? tabManager.selectedTabId
-        let handoffPinnedIds = retiringWorkspaceId.map { Set([ $0 ]) } ?? []
-        let pinnedIds = handoffPinnedIds
-            .union(tabManager.mountedBackgroundWorkspaceLoadIds)
-            .union(tabManager.debugPinnedWorkspaceLoadIds)
         let isCycleHot = tabManager.isWorkspaceCycleHot
+        let pinnedIds = WorkspaceMountPolicy.pinnedWorkspaceIds(
+            retiringWorkspaceId: retiringWorkspaceId,
+            backgroundWorkspaceLoadIds: tabManager.mountedBackgroundWorkspaceLoadIds,
+            debugPinnedWorkspaceLoadIds: tabManager.debugPinnedWorkspaceLoadIds,
+            isCycleHot: isCycleHot
+        )
+        let handoffPinnedIds = retiringWorkspaceId.map { Set([ $0 ]) } ?? []
         let shouldKeepHandoffPair = isCycleHot && !handoffPinnedIds.isEmpty
         let baseMaxMounted = shouldKeepHandoffPair
             ? WorkspaceMountPolicy.maxMountedWorkspacesDuringCycle

Sources/GhosttyTerminalAppearance.swift

@@ -94,6 +94,7 @@ enum GhosttyNotificationKey {
     static let cellSize = "ghostty.cellSize"
     static let tabId = "ghostty.tabId"
     static let surfaceId = "ghostty.surfaceId"
+    static let terminalVisibleInUI = "ghostty.terminalVisibleInUI"
     static let explicitFocusIntent = "ghostty.explicitFocusIntent"
     static let title = "ghostty.title"
     static let backgroundColor = "ghostty.backgroundColor"

Sources/GhosttyTerminalView.swift

@@ -11313,7 +11313,8 @@ final class GhosttySurfaceScrollView: NSView {
                 object: self,
                 userInfo: [
                     GhosttyNotificationKey.surfaceId: surfaceView.terminalSurface?.id as Any,
-                    GhosttyNotificationKey.tabId: surfaceView.tabId as Any
+                    GhosttyNotificationKey.tabId: surfaceView.tabId as Any,
+                    GhosttyNotificationKey.terminalVisibleInUI: visible
                 ]
             )
         }

Sources/TabManager.swift

@@ -4398,9 +4398,16 @@ class TabManager: ObservableObject {
     }
 
     func selectWorkspace(_ workspace: Workspace) {
+        guard selectedTabId != workspace.id else {
+#if DEBUG
+            debugPrimeWorkspaceSwitchTrigger("select", to: workspace.id)
+#endif
+            return
+        }
 #if DEBUG
         debugPrimeWorkspaceSwitchTrigger("select", to: workspace.id)
 #endif
+        activateWorkspaceCycleHotWindow()
         selectedTabId = workspace.id
     }
 
@@ -5454,14 +5461,24 @@ class TabManager: ObservableObject {
 
     func selectTab(at index: Int) {
         guard index >= 0 && index < tabs.count else { return }
+        let tabId = tabs[index].id
+        guard selectedTabId != tabId else {
+#if DEBUG
+            debugPrimeWorkspaceSwitchTrigger("select_index", to: tabId)
+#endif
+            return
+        }
 #if DEBUG
-        debugPrimeWorkspaceSwitchTrigger("select_index", to: tabs[index].id)
+        debugPrimeWorkspaceSwitchTrigger("select_index", to: tabId)
 #endif
-        selectedTabId = tabs[index].id
+        activateWorkspaceCycleHotWindow()
+        selectedTabId = tabId
     }
 
     func selectLastTab() {
         guard let lastTab = tabs.last else { return }
+        guard selectedTabId != lastTab.id else { return }
+        activateWorkspaceCycleHotWindow()
         selectedTabId = lastTab.id
     }
 

Sources/Workspace.swift

@@ -12086,21 +12086,22 @@ final class Workspace: Identifiable, ObservableObject {
         }
     }
 
-    func setPortalRenderingEnabled(_ enabled: Bool, reason: String) {
+    @discardableResult
+    func setPortalRenderingEnabled(_ enabled: Bool, reason: String) -> Bool {
         let changed = portalRenderingEnabled != enabled
+        guard changed else { return false }
         portalRenderingEnabled = enabled
         if enabled {
-            if changed {
-                beginEventDrivenLayoutFollowUp(
-                    reason: reason,
-                    includeGeometry: true
-                )
-            }
+            beginEventDrivenLayoutFollowUp(
+                reason: reason,
+                includeGeometry: true
+            )
         } else {
             clearLayoutFollowUp()
             hideAllTerminalPortalViews()
             hideAllBrowserPortalViews()
         }
+        return true
     }
 
     // MARK: - Utility

cmuxTests/TabManagerUnitTests.swift

@@ -122,6 +122,33 @@ private func runGit(
     return result.stdout
 }
 
+@MainActor
+final class TabManagerWorkspaceSelectionPerfTests: XCTestCase {
+    func testDirectWorkspaceSelectionActivatesHotSwitchWindow() {
+        let manager = TabManager(autoWelcomeIfNeeded: false)
+        let second = manager.addWorkspace(select: false, autoWelcomeIfNeeded: false)
+
+        XCTAssertFalse(manager.isWorkspaceCycleHot)
+
+        manager.selectWorkspace(second)
+
+        XCTAssertEqual(manager.selectedTabId, second.id)
+        XCTAssertTrue(manager.isWorkspaceCycleHot)
+    }
+
+    func testSelectingCurrentWorkspaceDoesNotActivateHotSwitchWindow() {
+        let manager = TabManager(autoWelcomeIfNeeded: false)
+        guard let selected = manager.selectedWorkspace else {
+            XCTFail("Expected initial workspace")
+            return
+        }
+
+        manager.selectWorkspace(selected)
+
+        XCTAssertFalse(manager.isWorkspaceCycleHot)
+    }
+}
+
 @MainActor
 final class TabManagerChildExitCloseTests: XCTestCase {
     func testChildExitOnLastPanelClosesSelectedWorkspaceAndKeepsIndexStable() {

cmuxTests/WorkspaceUnitTests.swift

@@ -5192,6 +5192,90 @@ final class WorkspaceMountPolicyTests: XCTestCase {
 
         XCTAssertEqual(next, [b, a])
     }
+
+    func testPinnedWorkspaceIdsIncludesBackgroundLoadsWhenIdle() {
+        let background = UUID()
+        let debug = UUID()
+
+        let pinnedIds = WorkspaceMountPolicy.pinnedWorkspaceIds(
+            retiringWorkspaceId: nil,
+            backgroundWorkspaceLoadIds: [background],
+            debugPinnedWorkspaceLoadIds: [debug],
+            isCycleHot: false
+        )
+
+        XCTAssertEqual(pinnedIds, [background, debug])
+    }
+
+    func testPinnedWorkspaceIdsSuppressesBackgroundLoadsDuringHandoff() {
+        let retiring = UUID()
+        let background = UUID()
+        let debug = UUID()
+
+        let pinnedIds = WorkspaceMountPolicy.pinnedWorkspaceIds(
+            retiringWorkspaceId: retiring,
+            backgroundWorkspaceLoadIds: [background],
+            debugPinnedWorkspaceLoadIds: [debug],
+            isCycleHot: false
+        )
+
+        XCTAssertEqual(pinnedIds, [retiring, debug])
+    }
+
+    func testPinnedWorkspaceIdsSuppressesBackgroundLoadsDuringHotCycle() {
+        let background = UUID()
+        let debug = UUID()
+
+        let pinnedIds = WorkspaceMountPolicy.pinnedWorkspaceIds(
+            retiringWorkspaceId: nil,
+            backgroundWorkspaceLoadIds: [background],
+            debugPinnedWorkspaceLoadIds: [debug],
+            isCycleHot: true
+        )
+
+        XCTAssertEqual(pinnedIds, [debug])
+    }
+}
+
+
+@MainActor
+final class BackgroundWorkspacePrimeCoordinatorTests: XCTestCase {
+    func testTimedOutPrimeReleasesMountButKeepsPendingLoad() async {
+#if DEBUG
+        let manager = TabManager(autoWelcomeIfNeeded: false)
+        let workspace = manager.addWorkspace(
+            select: false,
+            eagerLoadTerminal: false,
+            autoWelcomeIfNeeded: false
+        )
+        manager.requestBackgroundWorkspaceLoad(for: workspace.id)
+
+        let coordinator = BackgroundWorkspacePrimeCoordinator(timeoutSeconds: 0.01)
+        let reason = await coordinator.debugPrimeBackgroundWorkspaceOnceForTesting(
+            workspaceId: workspace.id,
+            tabManager: manager
+        )
+
+        XCTAssertEqual(reason, "timeout")
+        XCTAssertTrue(manager.pendingBackgroundWorkspaceLoadIds.contains(workspace.id))
+        XCTAssertFalse(manager.mountedBackgroundWorkspaceLoadIds.contains(workspace.id))
+#else
+        throw XCTSkip("Debug-only background prime timeout test")
+#endif
+    }
+}
+
+
+@MainActor
+final class WorkspacePortalRenderingTests: XCTestCase {
+    func testPortalRenderingToggleReportsOnlyStateTransitions() {
+        let workspace = Workspace()
+
+        XCTAssertTrue(workspace.setPortalRenderingEnabled(false, reason: "test"))
+        XCTAssertFalse(workspace.setPortalRenderingEnabled(false, reason: "test"))
+        XCTAssertTrue(workspace.setPortalRenderingEnabled(true, reason: "test"))
+        XCTAssertFalse(workspace.setPortalRenderingEnabled(true, reason: "test"))
+    }
 }