fix: prevent provider switch content flicker

Author: steipete

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 0.34.1 — Unreleased
 
 - Menu bar: restore native macOS positioning for merged provider dropdowns while preparing current content before AppKit lays out the menu.
+- Menu bar: keep cached provider content visible while switching merged tabs so the open menu no longer flickers through an empty state.
 - Settings: memoize cookie cache lookups behind the "Cached: …" picker labels so opening Settings and switching panes no longer pays a synchronous Keychain read per SwiftUI body evaluation, which froze the Providers pane for seconds (#1471). Thanks @ProspectOre!
 - Build: resolve packaged binaries from the bin path SwiftPM reports instead of assuming the legacy `.build/<arch>-apple-macosx/<conf>/` layout, so a stale directory left behind by the older build system no longer silently shadows fresh swiftbuild products in `package_app.sh`. Thanks @ProspectOre!
 - Menu bar: stop the provider-switcher shortcut monitor from killing the menu's event tracking session. Its event-queue peek re-entered the run loop in tracking mode, which could leave a zombie menu on screen that ignored clicks for tens of seconds (beach ball) — most often right after opening the menu or after rapid Cmd-number provider switching, with Settings… the usual victim. Peeks now run in a barren private run-loop mode, start only once the tracking session is pumping, and no longer touch mouse events. Thanks @ProspectOre!

Sources/CodexBar/StatusItemController+MenuReconcile.swift

@@ -79,6 +79,51 @@ extension StatusItemController {
         }
     }
 
+    /// Replaces cached content without first emptying the tracked menu. Compatible item shells
+    /// stay attached while their payloads swap; only separator or row-count differences cause
+    /// structural mutations.
+    func replaceMenuContentKeepingRowsVisible(
+        _ menu: NSMenu,
+        fromIndex: Int,
+        with newItems: [NSMenuItem])
+        -> [NSMenuItem]
+    {
+        guard fromIndex >= 0, fromIndex <= menu.items.count else { return [] }
+        defer { self.finishReconciledHighlightTracking(in: menu) }
+
+        let liveItems = Array(menu.items[fromIndex...])
+        let liveCount = liveItems.count
+        let sharedCount = min(liveCount, newItems.count)
+        var displacedItems: [NSMenuItem] = []
+        displacedItems.reserveCapacity(liveCount)
+        for offset in 0..<sharedCount {
+            let index = fromIndex + offset
+            let liveItem = liveItems[offset]
+            let newItem = newItems[offset]
+            if liveItem.isSeparatorItem == newItem.isSeparatorItem {
+                if !liveItem.isSeparatorItem {
+                    self.swapMenuItemContents(liveItem, newItem)
+                }
+                displacedItems.append(newItem)
+            } else {
+                menu.insertItem(newItem, at: index)
+                menu.removeItem(liveItem)
+                displacedItems.append(liveItem)
+            }
+        }
+        if newItems.count > liveCount {
+            for offset in liveCount..<newItems.count {
+                menu.insertItem(newItems[offset], at: fromIndex + offset)
+            }
+        } else if liveCount > newItems.count {
+            for offset in newItems.count..<liveCount {
+                menu.removeItem(liveItems[offset])
+                displacedItems.append(liveItems[offset])
+            }
+        }
+        return displacedItems
+    }
+
     private func finishReconciledHighlightTracking(in menu: NSMenu) {
         let menuKey = ObjectIdentifier(menu)
         guard let highlightedItem = self.highlightedMenuItems[menuKey] else { return }
@@ -125,8 +170,23 @@ extension StatusItemController {
         liveItem.keyEquivalent = newItem.keyEquivalent
         liveItem.keyEquivalentModifierMask = newItem.keyEquivalentModifierMask
         liveItem.indentationLevel = newItem.indentationLevel
+        liveItem.tag = newItem.tag
+        liveItem.identifier = newItem.identifier
+        liveItem.isHidden = newItem.isHidden
+        liveItem.isAlternate = newItem.isAlternate
+        liveItem.allowsKeyEquivalentWhenHidden = newItem.allowsKeyEquivalentWhenHidden
+        liveItem.onStateImage = newItem.onStateImage
+        liveItem.offStateImage = newItem.offStateImage
+        liveItem.mixedStateImage = newItem.mixedStateImage
         if #available(macOS 14.4, *) {
             liveItem.subtitle = newItem.subtitle
         }
     }
+
+    private func swapMenuItemContents(_ liveItem: NSMenuItem, _ cachedItem: NSMenuItem) {
+        let holder = NSMenuItem()
+        self.updateMenuItemInPlace(holder, from: liveItem)
+        self.updateMenuItemInPlace(liveItem, from: cachedItem)
+        self.updateMenuItemInPlace(cachedItem, from: holder)
+    }
 }

Sources/CodexBar/StatusItemController+MenuSmartUpdate.swift

@@ -32,34 +32,34 @@ extension StatusItemController {
 
             if isSelectionSwitch,
                let outgoingSelection,
-               self.hasReusableMergedSwitcherContent(
+               let cachedItems = self.reusableMergedSwitcherContent(
                    for: context.switcherSelection,
                    in: menu,
                    menuWidth: context.menuWidth,
                    codexAccountDisplay: context.codexAccountDisplay,
                    tokenAccountDisplay: context.tokenAccountDisplay)
             {
-                // Instant path: the incoming tab reattaches wholesale, so park the outgoing
-                // items for an equally instant switch-back.
-                self.cacheVisibleMergedSwitcherContent(
+                // Park the outgoing payloads for an equally instant switch-back. Compatible
+                // menu-item shells stay attached, avoiding the empty intermediate layout that
+                // AppKit can visibly render when the whole content block is removed first.
+                let outgoingCodexAccountDisplay = self.lastCodexAccountMenuDisplay
+                let outgoingTokenAccountDisplay = self.lastTokenAccountMenuDisplay
+                self.rememberMergedSwitcherState(enabledProviders, context.switcherSelection)
+                let displacedItems = self.replaceMenuContentKeepingRowsVisible(
+                    menu,
+                    fromIndex: contentStartIndex,
+                    with: cachedItems)
+                self.cacheMergedSwitcherContent(
+                    displacedItems,
                     in: menu,
                     selection: outgoingSelection,
-                    contentStartIndex: contentStartIndex,
-                    menuWidth: context.menuWidth)
-                while menu.items.count > contentStartIndex {
-                    menu.removeItem(at: contentStartIndex)
-                }
-                self.rememberMergedSwitcherState(enabledProviders, context.switcherSelection)
-                if self.addCachedMergedSwitcherContent(
-                    for: context.switcherSelection,
-                    to: menu,
-                    menuWidth: context.menuWidth,
-                    codexAccountDisplay: context.codexAccountDisplay,
-                    tokenAccountDisplay: context.tokenAccountDisplay)
-                {
-                    return
-                }
-                self.addSwitcherScopedMenuContent(into: menu, captureMenu: menu, context: context)
+                    context: MergedSwitcherContentCacheContext(
+                        menuWidth: context.menuWidth,
+                        codexAccountDisplay: outgoingCodexAccountDisplay,
+                        tokenAccountDisplay: outgoingTokenAccountDisplay,
+                        contentVersion: nil))
+                self.lastCodexAccountMenuDisplay = context.codexAccountDisplay
+                self.lastTokenAccountMenuDisplay = context.tokenAccountDisplay
                 self.cacheVisibleMergedSwitcherContent(
                     in: menu,
                     selection: context.switcherSelection,

Sources/CodexBar/StatusItemController+MergedSwitcherContentCache.swift

@@ -24,6 +24,13 @@ struct CachedMergedSwitcherMenuContent {
     }
 }
 
+struct MergedSwitcherContentCacheContext {
+    let menuWidth: CGFloat
+    let codexAccountDisplay: CodexAccountMenuDisplay?
+    let tokenAccountDisplay: TokenAccountMenuDisplay?
+    let contentVersion: Int?
+}
+
 extension StatusItemController {
     func preservingMergedSwitcherContentCachesDuringInvalidation(_ body: () -> Void) {
         let previous = self.preservesMergedSwitcherContentCachesDuringInvalidation
@@ -51,33 +58,48 @@ extension StatusItemController {
         guard menu.items.first?.view is ProviderSwitcherView else { return }
         guard contentStartIndex < menu.items.count else { return }
         let items = Array(menu.items[contentStartIndex...])
+        self.cacheMergedSwitcherContent(
+            items,
+            in: menu,
+            selection: selection,
+            context: MergedSwitcherContentCacheContext(
+                menuWidth: menuWidth,
+                codexAccountDisplay: self.lastCodexAccountMenuDisplay,
+                tokenAccountDisplay: self.lastTokenAccountMenuDisplay,
+                contentVersion: contentVersion))
+    }
+
+    func cacheMergedSwitcherContent(
+        _ items: [NSMenuItem],
+        in menu: NSMenu,
+        selection: ProviderSwitcherSelection,
+        context: MergedSwitcherContentCacheContext)
+    {
         guard !items.isEmpty else { return }
 
         let entry = CachedMergedSwitcherMenuContent(
-            requiredMenuContentVersion: contentVersion ??
+            requiredMenuContentVersion: context.contentVersion ??
                 self.menuVersions[ObjectIdentifier(menu)] ??
                 self.latestRequiredMenuRebuildVersion,
-            menuWidth: menuWidth,
-            codexAccountDisplay: self.lastCodexAccountMenuDisplay,
-            tokenAccountDisplay: self.lastTokenAccountMenuDisplay,
+            menuWidth: context.menuWidth,
+            codexAccountDisplay: context.codexAccountDisplay,
+            tokenAccountDisplay: context.tokenAccountDisplay,
             localizationSignature: self.lastMenuLocalizationSignature,
             items: items)
         self.mergedSwitcherContentCaches[ObjectIdentifier(menu), default: [:]][selection] = entry
     }
 
-    /// Non-consuming variant of `addCachedMergedSwitcherContent`'s lookup: reports whether a
-    /// reusable entry exists (evicting it when stale) without attaching anything, so callers
-    /// can choose between reattaching cached content and recycling the outgoing views.
-    func hasReusableMergedSwitcherContent(
+    /// Returns a reusable cached content block, evicting stale entries without attaching them.
+    func reusableMergedSwitcherContent(
         for selection: ProviderSwitcherSelection,
         in menu: NSMenu,
         menuWidth: CGFloat,
         codexAccountDisplay: CodexAccountMenuDisplay?,
         tokenAccountDisplay: TokenAccountMenuDisplay?)
-        -> Bool
+        -> [NSMenuItem]?
     {
         let key = ObjectIdentifier(menu)
-        guard let entry = self.mergedSwitcherContentCaches[key]?[selection] else { return false }
+        guard let entry = self.mergedSwitcherContentCaches[key]?[selection] else { return nil }
         guard entry.matches(
             requiredMenuContentVersion: self.latestRequiredMenuRebuildVersion,
             menuWidth: menuWidth,
@@ -86,9 +108,9 @@ extension StatusItemController {
             localizationSignature: self.menuLocalizationSignature())
         else {
             self.mergedSwitcherContentCaches[key]?.removeValue(forKey: selection)
-            return false
+            return nil
         }
-        return true
+        return entry.items
     }
 
     func addCachedMergedSwitcherContent(
@@ -99,22 +121,17 @@ extension StatusItemController {
         tokenAccountDisplay: TokenAccountMenuDisplay?)
         -> Bool
     {
-        let key = ObjectIdentifier(menu)
-        guard let entry = self.mergedSwitcherContentCaches[key]?[selection] else { return false }
-        guard entry.matches(
-            requiredMenuContentVersion: self.latestRequiredMenuRebuildVersion,
+        guard let items = self.reusableMergedSwitcherContent(
+            for: selection,
+            in: menu,
             menuWidth: menuWidth,
             codexAccountDisplay: codexAccountDisplay,
-            tokenAccountDisplay: tokenAccountDisplay,
-            localizationSignature: self.menuLocalizationSignature())
-        else {
-            self.mergedSwitcherContentCaches[key]?.removeValue(forKey: selection)
-            return false
-        }
+            tokenAccountDisplay: tokenAccountDisplay)
+        else { return false }
 
         self.lastCodexAccountMenuDisplay = codexAccountDisplay
         self.lastTokenAccountMenuDisplay = tokenAccountDisplay
-        for item in entry.items {
+        for item in items {
             menu.addItem(item)
         }
         return true

Tests/CodexBarTests/MenuCardViewRecyclingTests.swift

@@ -238,6 +238,51 @@ extension StatusMenuTests {
         #expect(menu.items[2].title == "New Provider Action")
     }
 
+    @Test
+    func `cached provider content swap preserves both item sets for switch back`() {
+        let settings = self.makeSettings()
+        settings.statusChecksEnabled = false
+        let controller = self.makeRecyclingController(settings: settings)
+        defer { controller.releaseStatusItemsForTesting() }
+
+        let switcher = NSMenuItem(title: "Switcher", action: nil, keyEquivalent: "")
+        let outgoing = [
+            NSMenuItem(title: "Overview Card", action: nil, keyEquivalent: ""),
+            NSMenuItem.separator(),
+            NSMenuItem(title: "Overview Action", action: nil, keyEquivalent: ""),
+        ]
+        let incoming = [
+            NSMenuItem(title: "Codex Card", action: nil, keyEquivalent: ""),
+            NSMenuItem.separator(),
+            NSMenuItem(title: "Codex Usage", action: nil, keyEquivalent: ""),
+            NSMenuItem(title: "Codex Settings", action: nil, keyEquivalent: ""),
+        ]
+        let menu = NSMenu()
+        menu.addItem(switcher)
+        outgoing.forEach(menu.addItem)
+
+        let displacedOutgoing = controller.replaceMenuContentKeepingRowsVisible(
+            menu,
+            fromIndex: 1,
+            with: incoming)
+
+        #expect(menu.items.first === switcher)
+        #expect(menu.items.dropFirst().map(\.title) == ["Codex Card", "", "Codex Usage", "Codex Settings"])
+        #expect(Array(menu.items[1...3]).map(ObjectIdentifier.init) == outgoing.map(ObjectIdentifier.init))
+        #expect(displacedOutgoing.map(ObjectIdentifier.init) == incoming.prefix(3).map(ObjectIdentifier.init))
+        #expect(displacedOutgoing.map(\.title) == ["Overview Card", "", "Overview Action"])
+
+        let displacedIncoming = controller.replaceMenuContentKeepingRowsVisible(
+            menu,
+            fromIndex: 1,
+            with: displacedOutgoing)
+
+        #expect(Array(menu.items.dropFirst()).map(ObjectIdentifier.init) == outgoing.map(ObjectIdentifier.init))
+        #expect(displacedIncoming.map(ObjectIdentifier.init) == incoming.map(ObjectIdentifier.init))
+        #expect(displacedIncoming.allSatisfy { $0.menu == nil })
+        #expect(displacedIncoming.map(\.title) == ["Codex Card", "", "Codex Usage", "Codex Settings"])
+    }
+
     @Test
     func `reconcile preserves highlight on a retained custom action row`() {
         let settings = self.makeSettings()