From 211eeed2112bec6bd1301c7a15d1e0deebe78226 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Sat, 23 May 2026 03:12:37 +0800
Subject: [PATCH] Prepare Mac App Store release checklist

---
 Apptag/ApptagApp.swift |  424 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 364 insertions(+), 60 deletions(-)

diff --git a/Apptag/ApptagApp.swift b/Apptag/ApptagApp.swift
index a0487fd..b78c05a 100644
--- a/Apptag/ApptagApp.swift
+++ b/Apptag/ApptagApp.swift
@@ -25,16 +25,21 @@
 final class OverlayPanel: NSPanel {
     override var canBecomeKey: Bool { true }
     override var canBecomeMain: Bool { true }
+
+    override func constrainFrameRect(_ frameRect: NSRect, to screen: NSScreen?) -> NSRect {
+        frameRect
+    }
 }
 
-final class AppDelegate: NSObject, NSApplicationDelegate {
+final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
     private static let showDockIconKey = "showDockIcon"
-    private static let statusItemAutosaveName = "com.apptag.launcher.statusItem"
+    private static let statusItemAutosaveName = AppIdentity.statusItemAutosaveName
     private static let statusItemButtonIdentifier = NSUserInterfaceItemIdentifier("TagLauncherStatusItemButton")
-    private static let statusItemAccessibilityLabel = "TagLauncher"
+    private static let statusItemAccessibilityLabel = AppIdentity.displayName
     private static let showAppListMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherShowAppListMenuItem")
-    private static let overlayDefaultLevel = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
-    private static let overlayTextInputLevel = NSWindow.Level.modalPanel
+    private static let launcherOverlayLevel = NSWindow.Level(rawValue: NSWindow.Level.mainMenu.rawValue - 1)
+    private static let overlayDefaultLevel = launcherOverlayLevel
+    private static let overlayTextInputLevel = launcherOverlayLevel
 
     private var statusItem: NSStatusItem?
     private var overlayWindow: NSWindow?
@@ -50,6 +55,40 @@
     private var isEditingAppNote = false
     private var isConfiguringApplicationMenu = false
     private var lastShowDockIcon: Bool?
+    private var statusMenuScreenForNextOverlay: NSScreen?
+    private var overlayGeneration = 0
+    private var suppressReopenUntil = Date.distantPast
+
+    private struct OverlayPlacementContext {
+        let screen: NSScreen
+        let frame: NSRect
+    }
+
+    private var isOverlayVisible: Bool {
+        overlayWindow?.isVisible == true
+    }
+
+    private var isSettingsVisible: Bool {
+        settingsWindow?.isVisible == true
+    }
+
+    private var requiresForegroundOwnership: Bool {
+        isOverlayVisible || isSettingsVisible
+    }
+
+    private var currentOverlayLevel: NSWindow.Level {
+        if isEditingAppNote || isQuickSearchOpen {
+            return Self.overlayTextInputLevel
+        }
+        return Self.overlayDefaultLevel
+    }
+
+    private func overlayLevel(initialQuickSearchSource: String? = nil) -> NSWindow.Level {
+        if initialQuickSearchSource != nil {
+            return Self.overlayTextInputLevel
+        }
+        return currentOverlayLevel
+    }
 
     static func refreshChromeSettings() {
         (NSApp.delegate as? AppDelegate)?.syncChromeSettings(force: true)
@@ -77,17 +116,27 @@
         observeChromeSettings()
         observeLanguageChanges()
         setupLaunchAtLogin()
-        configureApplicationMenuWhenAvailable()
+        suppressReopenUntil = Date().addingTimeInterval(1.0)
+        configureApplicationMenuWhenAvailable(retries: 200)
+    }
+
+    func applicationDidBecomeActive(_ notification: Notification) {
+        configureApplicationMenuWhenAvailable(retries: 12)
     }
 
     /// Dock icon click → show overlay (same as menubar "Show TagLauncher")
     func applicationShouldHandleReopen(_ sender: NSApplication, hasVisibleWindows flag: Bool) -> Bool {
+        guard Date() >= suppressReopenUntil else { return false }
         showOverlay()
         return false  // Suppress default "unhide all windows" behavior
     }
 
     func applicationWillTerminate(_ notification: Notification) {
+        hideOverlay(force: true, discardWindow: true)
+        unregisterHotkey(for: .main)
+        unregisterHotkey(for: .quickSearch)
         TagDatabase.flushPendingCategorySchemeBackupBatch()
+        removeOverlayKeyMonitor()
         removeQuickSearchExternalMouseMonitor()
     }
 
@@ -124,12 +173,109 @@
         let dockChanged = lastShowDockIcon != showDock
 
         if force || dockChanged {
-            NSApp.setActivationPolicy(showDock ? .regular : .accessory)
             lastShowDockIcon = showDock
+            refreshLauncherChromeState()
         }
 
         if force {
             setupMenuBar()
+        }
+    }
+
+    private func beginLauncherForegroundOwnership(activate: Bool = true, keyWindow: NSWindow? = nil) {
+        if NSApp.activationPolicy() != .regular {
+            NSApp.setActivationPolicy(.regular)
+        }
+        if activate {
+            claimLauncherForeground(keyWindow: keyWindow)
+        }
+    }
+
+    private func claimLauncherForeground(
+        keyWindow: NSWindow? = nil,
+        retries: Int = 0,
+        overlayGeneration expectedOverlayGeneration: Int? = nil
+    ) {
+        if NSApp.activationPolicy() != .regular {
+            NSApp.setActivationPolicy(.regular)
+        }
+
+        if isOverlayVisible && !NSApp.presentationOptions.contains(.hideDock) {
+            NSApp.presentationOptions = [.hideDock]
+        }
+
+        NSApp.unhide(nil)
+        NSApp.activate(ignoringOtherApps: true)
+
+        if let keyWindow, keyWindow.isVisible {
+            keyWindow.makeKeyAndOrderFront(nil)
+            keyWindow.makeMain()
+            keyWindow.orderFrontRegardless()
+        }
+        configureApplicationMenuWhenAvailable(retries: 4)
+
+        let overlayShouldYieldToSettings = keyWindow == overlayWindow && isSettingsVisible
+        let keyWindowStillNeedsFocus = !overlayShouldYieldToSettings
+            && keyWindow?.isVisible == true
+            && keyWindow?.isKeyWindow == false
+        let shouldRetry = !NSApp.isActive
+            || !NSApp.presentationOptions.contains(.hideDock)
+            || keyWindowStillNeedsFocus
+        guard retries > 0, isOverlayVisible else { return }
+        guard shouldRetry else { return }
+
+        let retryWindow = keyWindow
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) { [weak self] in
+            guard let self, self.isOverlayVisible else { return }
+            if let expectedOverlayGeneration,
+               expectedOverlayGeneration != self.overlayGeneration {
+                return
+            }
+            self.refreshLauncherChromeState()
+            self.claimLauncherForeground(
+                keyWindow: retryWindow,
+                retries: retries - 1,
+                overlayGeneration: expectedOverlayGeneration
+            )
+        }
+    }
+
+    private func refreshLauncherChromeState(activate: Bool = false) {
+        let showDock = UserDefaults.standard.bool(forKey: Self.showDockIconKey)
+        lastShowDockIcon = showDock
+
+        let desiredPolicy: NSApplication.ActivationPolicy = requiresForegroundOwnership
+            ? .regular
+            : (showDock ? .regular : .accessory)
+        if NSApp.activationPolicy() != desiredPolicy {
+            NSApp.setActivationPolicy(desiredPolicy)
+        }
+
+        let desiredPresentation: NSApplication.PresentationOptions = isOverlayVisible ? [.hideDock] : []
+        if NSApp.presentationOptions != desiredPresentation {
+            NSApp.presentationOptions = desiredPresentation
+        }
+
+        if activate && requiresForegroundOwnership {
+            let keyWindow = isSettingsVisible ? settingsWindow : (isOverlayVisible ? overlayWindow : nil)
+            claimLauncherForeground(
+                keyWindow: keyWindow,
+                retries: isOverlayVisible && !isSettingsVisible ? 5 : 0,
+                overlayGeneration: isOverlayVisible ? overlayGeneration : nil
+            )
+        }
+    }
+
+    private func handleApplicationDidResignActive() {
+        if isQuickSearchOpen {
+            NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+        }
+
+        guard !isOverlayVisible else {
+            return
+        }
+        if !requiresForegroundOwnership {
+            refreshLauncherChromeState()
         }
     }
 
@@ -146,7 +292,7 @@
 
     // MARK: - Launch at Login (LaunchAgent, zero permissions)
 
-    private static let launchAgentLabel = "com.apptag.launcher"
+    private static let launchAgentLabel = AppIdentity.launchAgentLabel
     static var supportsLaunchAtLogin: Bool {
         ProcessInfo.processInfo.environment["APP_SANDBOX_CONTAINER_ID"] == nil
     }
@@ -219,14 +365,15 @@
             button.imageScaling = .scaleProportionallyDown
             button.imagePosition = .imageOnly
             button.toolTip = "TagLauncher — Tag-based app launcher"
-            button.action = #selector(toggleOverlay)
+            button.action = #selector(toggleOverlay(_:))
             button.target = self
         }
 
         let menu = NSMenu()
+        menu.delegate = self
         let showItem = NSMenuItem(
             title: showAppListMenuTitle,
-            action: #selector(toggleOverlay),
+            action: #selector(toggleOverlayFromStatusMenu(_:)),
             keyEquivalent: ""
         )
         showItem.target = self
@@ -247,7 +394,7 @@
         menu.addItem(.separator())
         let prefsItem = NSMenuItem(
             title: tr("menu.preferences"),
-            action: #selector(openPreferences),
+            action: #selector(openPreferences(_:)),
             keyEquivalent: ","
         )
         prefsItem.target = self
@@ -277,6 +424,19 @@
             )
         )
         statusItem.menu = menu
+    }
+
+    func menuWillOpen(_ menu: NSMenu) {
+        statusMenuScreenForNextOverlay = screenContainingCurrentPointer()
+            ?? statusItem?.button?.window?.screen
+            ?? NSScreen.main
+            ?? NSScreen.screens.first
+    }
+
+    func menuDidClose(_ menu: NSMenu) {
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) { [weak self] in
+            self?.statusMenuScreenForNextOverlay = nil
+        }
     }
 
     private func makeMenuBarIcon() -> NSImage {
@@ -442,7 +602,7 @@
 
     private func configureShowAppListItem(_ item: NSMenuItem) {
         item.title = showAppListMenuTitle
-        item.action = #selector(toggleOverlay)
+        item.action = #selector(toggleOverlayFromStatusMenu(_:))
         item.target = self
         item.keyEquivalent = ""
         item.keyEquivalentModifierMask = []
@@ -463,7 +623,7 @@
         }
 
         item.title = tr("menu.preferences")
-        item.action = #selector(openPreferences)
+        item.action = #selector(openPreferences(_:))
         item.target = self
         item.keyEquivalent = ","
         item.keyEquivalentModifierMask = .command
@@ -472,7 +632,7 @@
 
     private func isSettingsMenuItem(_ item: NSMenuItem) -> Bool {
         item.action == Selector(("showSettingsWindow:"))
-            || item.action == #selector(openPreferences)
+            || item.action == #selector(openPreferences(_:))
             || item.title == tr("menu.preferences")
     }
 
@@ -504,57 +664,112 @@
 
     // MARK: - Overlay Window
 
-    @objc private func toggleOverlay() {
-        if overlayWindow?.isVisible == true {
-            hideOverlay()
-        } else {
-            showOverlay()
+    @objc func toggleOverlay(_ sender: Any) {
+        performToggleOverlay(preferredScreen: nil)
+    }
+
+    @objc func toggleOverlayFromStatusMenu(_ sender: Any) {
+        let preferredScreen = statusMenuScreenForNextOverlay
+        statusMenuScreenForNextOverlay = nil
+        DispatchQueue.main.async { [weak self] in
+            self?.performToggleOverlay(preferredScreen: preferredScreen)
         }
     }
 
-    private func showOverlay(initialQuickSearchSource: String? = nil) {
-        // Use the screen under the mouse cursor — works in fullscreen spaces
-        let mousePoint = NSEvent.mouseLocation
-        guard let screen = NSScreen.screens.first(where: {
-            NSMouseInRect(mousePoint, $0.frame, false)
-        }) ?? NSScreen.main ?? NSScreen.screens.first else { return }
-
-        let window: NSWindow
-        if let existingWindow = overlayWindow {
-            window = existingWindow
+    private func performToggleOverlay(preferredScreen: NSScreen?) {
+        if overlayWindow?.isVisible == true {
+            hideOverlay(force: true)
         } else {
-            window = makeOverlayWindow(on: screen, initialQuickSearchSource: initialQuickSearchSource)
-            overlayWindow = window
+            showOverlay(preferredScreen: preferredScreen)
+        }
+    }
+
+    private func showOverlay(
+        initialQuickSearchSource: String? = nil,
+        preferredScreen: NSScreen? = nil,
+        stagedForAllSpaces: Bool = false
+    ) {
+        guard let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen) else { return }
+
+        if !stagedForAllSpaces && !isSettingsVisible && NSApp.isActive {
+            // Let the all-spaces panel attach to the pointer's display before the app reclaims focus.
+            if NSApp.activationPolicy() != .accessory {
+                NSApp.setActivationPolicy(.accessory)
+            }
+            NSApp.deactivate()
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) { [weak self] in
+                self?.showOverlay(
+                    initialQuickSearchSource: initialQuickSearchSource,
+                    preferredScreen: placement.screen,
+                    stagedForAllSpaces: true
+                )
+            }
+            return
         }
 
-        window.setFrame(screen.frame, display: true)
-        window.level = isEditingAppNote ? Self.overlayTextInputLevel : Self.overlayDefaultLevel
+        if overlayWindow?.isVisible == true {
+            hideOverlay(force: true)
+        } else if let existingWindow = overlayWindow {
+            existingWindow.orderOut(nil)
+            overlayWindow = nil
+        }
 
+        let window = makeOverlayWindow(
+            on: placement.screen,
+            initialQuickSearchSource: initialQuickSearchSource
+        )
+        overlayGeneration &+= 1
+        overlayWindow = window
         installOverlayKeyMonitor()
-
-        if let initialQuickSearchSource {
-            NotificationCenter.default.post(
-                name: .tagLauncherQuickSearchRequested,
-                object: nil,
-                userInfo: ["source": initialQuickSearchSource]
-            )
+        if !isSettingsVisible {
+            if NSApp.isActive {
+                NSApp.deactivate()
+            }
+            if NSApp.activationPolicy() != .accessory {
+                NSApp.setActivationPolicy(.accessory)
+            }
         }
+
+        let targetLevel = overlayLevel(initialQuickSearchSource: initialQuickSearchSource)
+        window.setFrame(placement.frame, display: true)
+        window.level = targetLevel
 
         window.makeKeyAndOrderFront(nil)
         window.orderFrontRegardless()
-        NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
+
+        let placementFrame = placement.frame
+        let finishForegroundClaim: () -> Void = { [weak self, weak window] in
+            guard let self, let window, self.overlayWindow === window else { return }
+            self.refreshLauncherChromeState(activate: true)
+            if window.frame != placementFrame {
+                window.setFrame(placementFrame, display: true)
+                window.makeKeyAndOrderFront(nil)
+                window.orderFrontRegardless()
+            }
+            if let settingsWindow = self.settingsWindow, settingsWindow.isVisible {
+                self.prepareSettingsWindow(settingsWindow)
+            }
+            NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
+        }
+
+        if !isSettingsVisible && stagedForAllSpaces {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.12, execute: finishForegroundClaim)
+        } else {
+            finishForegroundClaim()
+        }
     }
 
     private func installOverlayKeyMonitor() {
         guard overlayKeyMonitor == nil else { return }
         overlayKeyMonitor = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
             guard let self else { return event }
+            guard self.shouldHandleOverlayKeyEvent(event) else { return event }
             if event.keyCode == 53 { // Escape
                 if self.isQuickSearchOpen {
                     NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
                     return nil
                 }
-                self.hideOverlay()
+                self.hideOverlay(force: true)
                 return nil
             }
             if self.shouldOpenQuickSearch(for: event) {
@@ -567,6 +782,12 @@
             }
             return event
         }
+    }
+
+    private func shouldHandleOverlayKeyEvent(_ event: NSEvent) -> Bool {
+        guard overlayWindow?.isVisible == true else { return false }
+        if event.window == overlayWindow { return true }
+        return event.window == nil && NSApp.keyWindow == overlayWindow
     }
 
     private func shouldOpenQuickSearch(for event: NSEvent) -> Bool {
@@ -618,15 +839,16 @@
         )
         panel.isFloatingPanel = true
         panel.hidesOnDeactivate = false
+        // This combination keeps the overlay on the pointer display, including fullscreen Spaces.
         panel.collectionBehavior = [
-            .moveToActiveSpace,
+            .canJoinAllSpaces,
             .fullScreenAuxiliary,
             .stationary,
             .transient,
             .ignoresCycle
         ]
         panel.isOpaque = false
-        panel.backgroundColor = .clear
+        panel.backgroundColor = NSColor.black.withAlphaComponent(0.001)
         panel.hasShadow = false
         panel.titlebarAppearsTransparent = true
         panel.titleVisibility = .hidden
@@ -645,8 +867,9 @@
         return panel
     }
 
-    private func hideOverlay(force: Bool = false) {
+    private func hideOverlay(force: Bool = false, discardWindow: Bool = false) {
         guard force || !isInEditMode else { return }
+        overlayGeneration &+= 1
         TagDatabase.flushPendingCategorySchemeBackupBatch()
         if let settingsWindow, settingsWindow.parent == overlayWindow {
             detachSettingsWindow(settingsWindow)
@@ -654,8 +877,9 @@
         overlayWindow?.orderOut(nil)
         removeOverlayKeyMonitor()
         removeQuickSearchExternalMouseMonitor()
+        refreshLauncherChromeState()
         NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
-        if force {
+        if discardWindow {
             overlayWindow = nil
         }
     }
@@ -752,12 +976,21 @@
         if id == LauncherHotkeyKind.quickSearch.eventID {
             showQuickSearchFromGlobalHotkey()
         } else {
-            toggleOverlay()
+            performToggleOverlay(preferredScreen: nil)
         }
     }
 
     private func showQuickSearchFromGlobalHotkey() {
-        guard overlayWindow?.isVisible != true else { return }
+        if overlayWindow?.isVisible == true {
+            guard !isSettingsVisible else { return }
+            refreshLauncherChromeState(activate: true)
+            NotificationCenter.default.post(
+                name: .tagLauncherQuickSearchRequested,
+                object: nil,
+                userInfo: ["source": QuickSearchOpenSource.globalVisible]
+            )
+            return
+        }
         showOverlay(initialQuickSearchSource: QuickSearchOpenSource.globalHidden)
     }
 
@@ -797,6 +1030,10 @@
                   keyWindow != self.overlayWindow,
                   !self.isInEditMode
             else { return }
+
+            if self.isSettingsOwnedPanel(keyWindow) {
+                return
+            }
 
             // Settings/Preferences window -> float it above overlay for real-time preview.
             if self.isSettingsWindowCandidate(keyWindow) {
@@ -838,6 +1075,7 @@
         window.makeKeyAndOrderFront(nil)
         window.orderFrontRegardless()
         settingsWindow = window
+        refreshLauncherChromeState(activate: true)
     }
 
     private func attachSettingsWindow(_ window: NSWindow, to overlayWindow: NSWindow) {
@@ -862,6 +1100,15 @@
         return true
     }
 
+    private func isSettingsOwnedPanel(_ window: NSWindow) -> Bool {
+        guard window is NSPanel else { return false }
+        if window is NSSavePanel { return true }
+        guard let settingsWindow else { return false }
+        return window.sheetParent == settingsWindow
+            || settingsWindow.attachedSheet == window
+            || window.parent == settingsWindow
+    }
+
     private func center(_ window: NSWindow, over rect: NSRect) {
         let frame = window.frame
         let origin = NSPoint(
@@ -872,10 +1119,24 @@
     }
 
     private func screenUnderMouse() -> NSScreen? {
+        overlayPlacementContextForNextOverlay(preferredScreen: nil)?.screen
+    }
+
+    private func overlayPlacementContextForNextOverlay(preferredScreen: NSScreen?) -> OverlayPlacementContext? {
+        if let screen = preferredScreen {
+            return OverlayPlacementContext(screen: screen, frame: screen.frame)
+        }
+        guard let screen = screenContainingCurrentPointer() ?? NSScreen.main ?? NSScreen.screens.first else {
+            return nil
+        }
+        return OverlayPlacementContext(screen: screen, frame: screen.frame)
+    }
+
+    private func screenContainingCurrentPointer() -> NSScreen? {
         let mousePoint = NSEvent.mouseLocation
         return NSScreen.screens.first(where: {
             NSMouseInRect(mousePoint, $0.frame, false)
-        }) ?? NSScreen.main ?? NSScreen.screens.first
+        })
     }
 
     /// Clean up settingsWindow reference when the Settings window closes.
@@ -891,6 +1152,7 @@
             else { return }
             self.detachSettingsWindow(closingWindow)
             self.settingsWindow = nil
+            self.refreshLauncherChromeState()
         }
     }
 
@@ -905,7 +1167,7 @@
         }
     }
 
-    /// Lower the overlay while editing app notes so IME candidate windows are not hidden behind it.
+    /// Keep text-input overlays at the launcher level so Quick Search stays visible in fullscreen Spaces.
     private func observeAppNoteEditing() {
         NotificationCenter.default.addObserver(
             forName: .tagLauncherAppNoteEditingChanged,
@@ -914,8 +1176,18 @@
         ) { [weak self] notification in
             guard let self else { return }
             self.isEditingAppNote = (notification.userInfo?["active"] as? Bool) ?? false
+            if self.isEditingAppNote {
+                self.promoteOverlayToForegroundInput()
+            }
             self.updateOverlayLevelForTextInput()
         }
+    }
+
+    private func promoteOverlayToForegroundInput() {
+        beginLauncherForegroundOwnership()
+        guard let overlayWindow else { return }
+        overlayWindow.makeKeyAndOrderFront(nil)
+        overlayWindow.orderFrontRegardless()
     }
 
     private func observeQuickSearch() {
@@ -926,6 +1198,10 @@
         ) { [weak self] notification in
             guard let self else { return }
             self.isQuickSearchOpen = (notification.userInfo?["active"] as? Bool) ?? false
+            if self.isQuickSearchOpen {
+                self.promoteOverlayToForegroundInput()
+            }
+            self.updateOverlayLevelForTextInput()
             if self.isQuickSearchOpen {
                 self.installQuickSearchExternalMouseMonitor()
             } else {
@@ -946,8 +1222,7 @@
             object: NSApp,
             queue: .main
         ) { [weak self] _ in
-            guard self?.isQuickSearchOpen == true else { return }
-            NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+            self?.handleApplicationDidResignActive()
         }
     }
 
@@ -972,7 +1247,7 @@
 
     private func updateOverlayLevelForTextInput() {
         guard let overlayWindow else { return }
-        overlayWindow.level = isEditingAppNote ? Self.overlayTextInputLevel : Self.overlayDefaultLevel
+        overlayWindow.level = currentOverlayLevel
         if let settingsWindow, settingsWindow.parent == overlayWindow {
             settingsWindow.level = overlayWindow.level
         }
@@ -989,14 +1264,14 @@
         }
     }
 
-    @objc private func openPreferences() {
+    @objc private func openPreferences(_ sender: Any? = nil) {
         TagDatabase.flushPendingCategorySchemeBackupBatch()
+        beginLauncherForegroundOwnership()
         // Don't hide overlay — keep it visible for real-time setting preview.
         if let overlayWindow, overlayWindow.isVisible {
             overlayWindow.makeKeyAndOrderFront(nil)
             overlayWindow.orderFrontRegardless()
         }
-        NSApp.activate(ignoringOtherApps: true)
 
         if let settingsWindow {
             prepareSettingsWindow(settingsWindow)
@@ -1027,29 +1302,46 @@
 
 final class DismissibleHostingView<Content: View>: NSHostingView<Content> {
     private let onBackdropTap: () -> Void
-    private var suppressBackdropDismiss = false
+    private var modalInteractionSuppressesBackdropDismiss = false
+    private var quickSearchSuppressesBackdropDismiss = false
     private var modalInteractionObserver: NSObjectProtocol?
+    private var quickSearchVisibilityObserver: NSObjectProtocol?
+
+    private var suppressBackdropDismiss: Bool {
+        modalInteractionSuppressesBackdropDismiss || quickSearchSuppressesBackdropDismiss
+    }
 
     @MainActor required init(rootView: Content) {
         self.onBackdropTap = {}
         super.init(rootView: rootView)
-        observeModalInteractionChanges()
+        installWindowServerAnchorLayer()
+        observeBackdropDismissSuppressionChanges()
     }
 
     init(rootView: Content, onBackdropTap: @escaping () -> Void) {
         self.onBackdropTap = onBackdropTap
         super.init(rootView: rootView)
-        observeModalInteractionChanges()
+        installWindowServerAnchorLayer()
+        observeBackdropDismissSuppressionChanges()
     }
 
     deinit {
         if let modalInteractionObserver {
             NotificationCenter.default.removeObserver(modalInteractionObserver)
         }
+        if let quickSearchVisibilityObserver {
+            NotificationCenter.default.removeObserver(quickSearchVisibilityObserver)
+        }
     }
 
     @available(*, unavailable)
     required init?(coder: NSCoder) { fatalError() }
+
+    private func installWindowServerAnchorLayer() {
+        wantsLayer = true
+        // A near-transparent backing pixel makes the WindowServer publish the panel immediately.
+        layer?.backgroundColor = NSColor.black.withAlphaComponent(0.001).cgColor
+    }
 
     override func mouseDown(with event: NSEvent) {
         let location = convert(event.locationInWindow, from: nil)
@@ -1058,6 +1350,10 @@
             return
         }
         if hit == self {
+            if quickSearchSuppressesBackdropDismiss {
+                NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+                return
+            }
             if suppressBackdropDismiss {
                 super.mouseDown(with: event)
                 return
@@ -1084,13 +1380,21 @@
         super.mouseDown(with: event)
     }
 
-    private func observeModalInteractionChanges() {
+    private func observeBackdropDismissSuppressionChanges() {
         modalInteractionObserver = NotificationCenter.default.addObserver(
             forName: .tagLauncherModalInteractionChanged,
             object: nil,
             queue: .main
         ) { [weak self] notification in
-            self?.suppressBackdropDismiss = (notification.userInfo?["active"] as? Bool) ?? false
+            self?.modalInteractionSuppressesBackdropDismiss = (notification.userInfo?["active"] as? Bool) ?? false
+        }
+
+        quickSearchVisibilityObserver = NotificationCenter.default.addObserver(
+            forName: .tagLauncherQuickSearchVisibilityChanged,
+            object: nil,
+            queue: .main
+        ) { [weak self] notification in
+            self?.quickSearchSuppressesBackdropDismiss = (notification.userInfo?["active"] as? Bool) ?? false
         }
     }
 

--
Gitblit v1.9.3