bug-fix: keep HUD above fullscreen windows

Author: manitofigh

Sources/Spotlight/SpotlightWindow.swift

@@ -21,11 +21,13 @@ public final class SpotlightWindowController {
   /// that app's fullscreen Space.
   /// `.canJoinAllSpaces` keeps the panel reachable from every Space,
   /// `.fullScreenAuxiliary` lets it sit alongside fullscreen windows,
-  /// `.stationary` stops it being dragged along during Space
-  /// transitions (which would otherwise yank focus during the swipe),
-  /// and `.ignoresCycle` keeps this transient HUD out of Cmd-` cycling.
+  /// `.transient` keeps it in the floating Spaces group. `.stationary`
+  /// looks tempting for all-space overlays, but AppKit treats it like
+  /// desktop chrome; fullscreen Spaces can then leave a reused panel
+  /// behind the fullscreen layer.
+  /// `.ignoresCycle` keeps this transient HUD out of Cmd-` cycling.
   nonisolated static let panelCollectionBehavior: NSWindow.CollectionBehavior = [
-    .canJoinAllApplications, .canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle
+    .canJoinAllApplications, .canJoinAllSpaces, .fullScreenAuxiliary, .transient, .ignoresCycle
   ]
   nonisolated static let defaultUnfocusedAlpha: CGFloat = 0.55
 
@@ -356,6 +358,8 @@ public final class SpotlightWindowController {
   }
 
   private func bringPanelToFront(_ panel: NSPanel) {
+    Self.configurePanel(panel)
+    panel.orderFrontRegardless()
     panel.makeKeyAndOrderFront(nil)
     panel.orderFrontRegardless()
     syncFuzzyPreviewPanel()
@@ -687,11 +691,20 @@ extension SpotlightWindowController {
       if fuzzyController.isVisible { fuzzyController.close() }
       commandController.toggle(shortcuts: shortcuts, preferences: preferences)
     case .insertTodayBadge:
-      _ = panel?.firstResponder?.tryToPerform(#selector(PlaceholderTextView.insertTodayBadgeToken(_:)), with: nil)
+      _ = panel?.firstResponder?.tryToPerform(
+        #selector(PlaceholderTextView.insertTodayBadgeToken(_:)),
+        with: nil
+      )
     case .insertChecklist:
-      _ = panel?.firstResponder?.tryToPerform(#selector(PlaceholderTextView.insertChecklistToken(_:)), with: nil)
+      _ = panel?.firstResponder?.tryToPerform(
+        #selector(PlaceholderTextView.insertChecklistToken(_:)),
+        with: nil
+      )
     case .toggleChecklist:
-      _ = panel?.firstResponder?.tryToPerform(#selector(PlaceholderTextView.toggleChecklistShortcut(_:)), with: nil)
+      _ = panel?.firstResponder?.tryToPerform(
+        #selector(PlaceholderTextView.toggleChecklistShortcut(_:)),
+        with: nil
+      )
     case .pinNote:
       Task { await session.togglePin() }
     case .shareCurrentChat:

Tests/SpotlightTests/SpotlightWindowControllerTests.swift

@@ -35,7 +35,9 @@ struct SpotlightWindowControllerTests {
   /// **Regression guard** -- `.fullScreenAuxiliary` is what allows the
   /// HUD to render in a Space owned by a fullscreen app. Without it,
   /// the panel is hidden behind the fullscreen layer and never shown.
-  @Test("panel collection behavior includes .fullScreenAuxiliary -- required for over-fullscreen HUD")
+  @Test(
+    "panel collection behavior includes .fullScreenAuxiliary -- required for over-fullscreen HUD"
+  )
   func panelCollectionBehaviorAllowsFullscreen() {
     let behavior = SpotlightWindowController.panelCollectionBehavior
     #expect(behavior.contains(.fullScreenAuxiliary))
@@ -54,6 +56,17 @@ struct SpotlightWindowControllerTests {
     #expect(!behavior.contains(.auxiliary))
   }
 
+  /// **Regression guard** -- the HUD is a summonable floating overlay,
+  /// not desktop chrome. `.stationary` can leave a reused panel behind
+  /// a fullscreen window set after AppKit rebuilds Spaces membership.
+  @Test("panel uses transient Spaces behavior -- required for reused over-fullscreen HUD")
+  func panelUsesTransientSpacesBehavior() {
+    let behavior = SpotlightWindowController.panelCollectionBehavior
+    #expect(behavior.contains(.transient))
+    #expect(!behavior.contains(.managed))
+    #expect(!behavior.contains(.stationary))
+  }
+
   /// **Regression guard** -- recent macOS releases can keep
   /// fullscreen windows above `.statusBar` auxiliary panels. The HUD is
   /// transient, so it uses the overlay-grade screen saver level.
@@ -78,7 +91,8 @@ struct SpotlightWindowControllerTests {
     #expect(panel.collectionBehavior.contains(.canJoinAllSpaces))
     #expect(panel.collectionBehavior.contains(.canJoinAllApplications))
     #expect(panel.collectionBehavior.contains(.fullScreenAuxiliary))
-    #expect(panel.collectionBehavior.contains(.stationary))
+    #expect(panel.collectionBehavior.contains(.transient))
+    #expect(!panel.collectionBehavior.contains(.stationary))
     #expect(panel.collectionBehavior.contains(.ignoresCycle))
     #expect(panel.hidesOnDeactivate == false)
     #expect(panel.isFloatingPanel)