Show more languages in preferences

Ariver

2026-05-30 b02c7cd28f1c48c5380bb5e3f839bdfb7615f25f

 Apptag/ApptagApp.swift

@@ -6,30 +6,27 @@

@main
struct TagLauncherApp: App {
    private static let singletonLockFile = TagLauncherProcessSingleton.acquireOrHandOffAndExit()
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    init() {
        _ = Self.singletonLockFile
    }

    var body: some Scene {
        Settings {
            PreferencesView()
        }
        .defaultSize(width: 880, height: 460)
        .defaultSize(width: 1000, height: 480)
        .commands {
            CommandGroup(replacing: .systemServices) { }
            CommandGroup(replacing: .appVisibility) { }
            CommandGroup(replacing: .help) { }
        }
    }
}

// MARK: - App Delegate (menubar + overlay window + hotkey)

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, NSMenuDelegate {
    private static let showDockIconKey = "showDockIcon"
@@ -37,31 +34,113 @@
    private static let statusItemButtonIdentifier = NSUserInterfaceItemIdentifier("TagLauncherStatusItemButton")
    private static let statusItemAccessibilityLabel = AppIdentity.displayName
    private static let showAppListMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherShowAppListMenuItem")
    private static let helpMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherHelpMenu")
    private static let downloadHelpMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherDownloadHelpMenuItem")
    private static let externalActivationNotification = Notification.Name("TagLauncherExternalActivationRequested")
    private static let externalActivationObject = AppIdentity.bundleIdentifier
    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?
    private var overlayKeyMonitor: Any?
    private var quickSearchLocalMouseMonitor: Any?
    private var quickSearchExternalMouseMonitor: Any?
    private var settingsWindow: NSWindow?    // Track Settings window to keep it above overlay
    private var mainHotkeyRef: EventHotKeyRef?
    private var quickSearchHotkeyRef: EventHotKeyRef?
    private var hotkeyEventHandlerInstalled = false
    private var isQuickSearchOpen = false
    private var quickSearchShouldHideOverlayOnClose = false
    private var quickSearchOnlyOverlaySession = false
    private var lastQuickSearchHotkeyAt = Date.distantPast
    private var isModalInteractionActive = false
    private var isInEditMode = false  // Suppress auto-dismiss during editing
    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 lazy var overlayController = OverlayWindowController(
        dependencies: OverlayWindowController.Dependencies(
            shouldStageAsAccessory: { [weak self] in
                self?.shouldStageOverlayAsAccessory ?? false
            },
            isSettingsVisible: { [weak self] in
                self?.isSettingsVisible ?? false
            },
            settingsWindow: { [weak self] in
                self?.settingsWindow
            },
            canHideOverlay: { [weak self] in
                self?.isInEditMode == false
            },
            currentOverlayLevel: { [weak self] in
                self?.currentOverlayLevel ?? Self.overlayDefaultLevel
            },
            overlayLevel: { [weak self] initialQuickSearchSource in
                self?.overlayLevel(initialQuickSearchSource: initialQuickSearchSource) ?? Self.overlayDefaultLevel
            },
            makeContentView: { [weak self] initialQuickSearchSource in
                DismissibleHostingView(
                    rootView: ContentView(
                        hideOverlay: { [weak self] in
                            self?.hideOverlay(force: true)
                        },
                        initialQuickSearchSource: initialQuickSearchSource
                    ),
                    onBackdropTap: { [weak self] in
                        self?.hideOverlay()
                    }
                )
            },
            handleOverlayKeyEvent: { [weak self] event in
                self?.handleOverlayKeyEvent(event) ?? false
            },
            installOverlayKeyMonitor: { [weak self] in
                self?.installOverlayKeyMonitor()
            },
            removeOverlayKeyMonitor: { [weak self] in
                self?.removeOverlayKeyMonitor()
            },
            removeQuickSearchMouseMonitor: { [weak self] in
                self?.removeQuickSearchExternalMouseMonitor()
                self?.quickSearchShouldHideOverlayOnClose = false
                self?.quickSearchOnlyOverlaySession = false
            },
            detachSettingsWindow: { [weak self] window in
                self?.detachSettingsWindow(window)
            },
            prepareSettingsWindow: { [weak self] window in
                self?.prepareSettingsWindow(window)
            },
            refreshChromeState: { [weak self] activate, avoidSpaceSwitch in
                self?.refreshLauncherChromeState(activate: activate, avoidSpaceSwitch: avoidSpaceSwitch)
            },
            onWillHide: {
                TagDatabase.flushPendingCategorySchemeBackupBatch()
            },
            onDidHide: {
                NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
            },
            onDidShow: {
                NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
            }
        )
    )

    private var overlayWindow: NSWindow? {
        overlayController.window
    }

    private var overlayGeneration: Int {
        overlayController.generation
    }

    private var overlayAvoidsSpaceSwitch: Bool {
        get { overlayController.avoidsSpaceSwitch }
        set { overlayController.avoidsSpaceSwitch = newValue }
    }

    private var isOverlayVisible: Bool {
@@ -74,6 +153,10 @@

    private var requiresForegroundOwnership: Bool {
        isOverlayVisible || isSettingsVisible
    }

    private var shouldStageOverlayAsAccessory: Bool {
        !isSettingsVisible && !UserDefaults.standard.bool(forKey: Self.showDockIconKey)
    }

    private var currentOverlayLevel: NSWindow.Level {
@@ -112,6 +195,7 @@
        observeAppNoteEditing()
        observeQuickSearch()
        observePreferencesRequests()
        observeExternalActivationRequests()
        observeApplicationMenuChanges()
        observeChromeSettings()
        observeLanguageChanges()
@@ -127,7 +211,7 @@
    /// 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()
        showOrFocusOverlay()
        return false  // Suppress default "unhide all windows" behavior
    }

@@ -138,6 +222,11 @@
        TagDatabase.flushPendingCategorySchemeBackupBatch()
        removeOverlayKeyMonitor()
        removeQuickSearchExternalMouseMonitor()
        DistributedNotificationCenter.default().removeObserver(
            self,
            name: Self.externalActivationNotification,
            object: Self.externalActivationObject
        )
    }

    /// Ensure defaultGroupName is always the language-neutral key "Other".
@@ -240,13 +329,21 @@
        }
    }

    private func refreshLauncherChromeState(activate: Bool = false) {
    private func refreshLauncherChromeState(activate: Bool = false, avoidSpaceSwitch: Bool = false) {
        let showDock = UserDefaults.standard.bool(forKey: Self.showDockIconKey)
        lastShowDockIcon = showDock

        let desiredPolicy: NSApplication.ActivationPolicy = requiresForegroundOwnership
        let shouldStayAccessoryForCurrentFullscreenSpace = isOverlayVisible
            && (avoidSpaceSwitch || overlayAvoidsSpaceSwitch)
        let shouldStayAccessoryForQuickOnlySearch = isOverlayVisible
            && quickSearchOnlyOverlaySession
            && !showDock
        let desiredPolicy: NSApplication.ActivationPolicy = shouldStayAccessoryForCurrentFullscreenSpace
            ? .accessory
            : (shouldStayAccessoryForQuickOnlySearch ? .accessory
            : (requiresForegroundOwnership
            ? .regular
            : (showDock ? .regular : .accessory)
            : (showDock ? .regular : .accessory)))
        if NSApp.activationPolicy() != desiredPolicy {
            NSApp.setActivationPolicy(desiredPolicy)
        }
@@ -256,7 +353,9 @@
            NSApp.presentationOptions = desiredPresentation
        }

        if activate && requiresForegroundOwnership {
        if activate && requiresForegroundOwnership
            && !shouldStayAccessoryForCurrentFullscreenSpace
            && !shouldStayAccessoryForQuickOnlySearch {
            let keyWindow = isSettingsVisible ? settingsWindow : (isOverlayVisible ? overlayWindow : nil)
            claimLauncherForeground(
                keyWindow: keyWindow,
@@ -267,13 +366,14 @@
    }

    private func handleApplicationDidResignActive() {
        guard !isOverlayVisible else {
            return
        }

        if isQuickSearchOpen {
            NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
        }

        guard !isOverlayVisible else {
            return
        }
        if !requiresForegroundOwnership {
            refreshLauncherChromeState()
        }
@@ -306,7 +406,7 @@
        guard supportsLaunchAtLogin else { return }
        let plist: [String: Any] = [
            "Label": Self.launchAgentLabel,
            "ProgramArguments": ["open", Bundle.main.bundlePath, "--hide"],
            "ProgramArguments": Self.expectedLaunchAgentProgramArguments(),
            "RunAtLoad": true,
        ]
        let dir = Self.launchAgentURL.deletingLastPathComponent()
@@ -314,10 +414,16 @@
        (plist as NSDictionary).write(to: Self.launchAgentURL, atomically: true)

        let uid = getuid()
        let bootoutTask = Process()
        bootoutTask.launchPath = "/bin/launchctl"
        bootoutTask.arguments = ["bootout", "gui/\(uid)/\(Self.launchAgentLabel)"]
        try? bootoutTask.run()
        bootoutTask.waitUntilExit()

        let task = Process()
        task.launchPath = "/bin/launchctl"
        task.arguments = ["bootstrap", "gui/\(uid)", Self.launchAgentURL.path]
        task.launch()
        try? task.run()
    }

    static func disableLaunchAtLogin() {
@@ -326,8 +432,23 @@
        let task = Process()
        task.launchPath = "/bin/launchctl"
        task.arguments = ["bootout", "gui/\(uid)/\(Self.launchAgentLabel)"]
        task.launch()
        try? task.run()
        try? FileManager.default.removeItem(at: Self.launchAgentURL)
    }

    private static func launchAgentProgramArguments() -> [String]? {
        guard let plist = NSDictionary(contentsOf: Self.launchAgentURL) as? [String: Any] else {
            return nil
        }
        return plist["ProgramArguments"] as? [String]
    }

    private static func expectedLaunchAgentProgramArguments() -> [String] {
        let executablePath = Bundle.main.executablePath
            ?? Bundle.main.bundleURL
                .appendingPathComponent("Contents/MacOS/\(AppIdentity.displayName)")
                .path
        return [executablePath, "--hide"]
    }

    /// On first launch, enable login item by default via LaunchAgent.
@@ -340,7 +461,14 @@
            return
        }
        let key = "launchAtLogin"
        if !AppDefaults.hasStoredValue(for: key) && UserDefaults.standard.bool(forKey: key) {
        guard UserDefaults.standard.bool(forKey: key) else {
            Self.disableLaunchAtLogin()
            return
        }

        let expectedArguments = Self.expectedLaunchAgentProgramArguments()
        if !AppDefaults.hasStoredValue(for: key)
            || Self.launchAgentProgramArguments() != expectedArguments {
            Self.enableLaunchAtLogin()
        }
    }
@@ -427,7 +555,7 @@
    }

    func menuWillOpen(_ menu: NSMenu) {
        statusMenuScreenForNextOverlay = screenContainingCurrentPointer()
        statusMenuScreenForNextOverlay = overlayController.screenContainingCurrentPointer()
            ?? statusItem?.button?.window?.screen
            ?? NSScreen.main
            ?? NSScreen.screens.first
@@ -538,6 +666,7 @@
            }

            self.configureApplicationMenu()
            self.configureHelpMenu()
            if retries > 0 && self.applicationMenuNeedsCleanup() {
                self.configureApplicationMenuWhenAvailable(retries: retries - 1)
            }
@@ -656,6 +785,42 @@
        }
    }

    private func configureHelpMenu() {
        guard let mainMenu = NSApp.mainMenu else { return }
        NSApp.helpMenu = nil

        for item in mainMenu.items.reversed() {
            let isHelpMenu = item.identifier == Self.helpMenuItemIdentifier
                || item.title.localizedCaseInsensitiveContains("help")
                || item.title == tr("menu.help")
                || item.submenu?.title.localizedCaseInsensitiveContains("help") == true
                || item.submenu?.title == tr("menu.help")
            if isHelpMenu {
                mainMenu.removeItem(item)
            }
        }

        let menuItem = NSMenuItem(title: tr("menu.help"), action: nil, keyEquivalent: "")
        let helpMenu = NSMenu(title: tr("menu.help"))
        menuItem.identifier = Self.helpMenuItemIdentifier
        menuItem.submenu = helpMenu

        let downloadItem = NSMenuItem()
        downloadItem.identifier = Self.downloadHelpMenuItemIdentifier
        downloadItem.title = tr("help.downloadPDF")
        downloadItem.action = #selector(openLocalizedHelp(_:))
        downloadItem.target = self
        downloadItem.keyEquivalent = ""
        downloadItem.keyEquivalentModifierMask = []
        downloadItem.isEnabled = true
        helpMenu.addItem(downloadItem)
        mainMenu.addItem(menuItem)
    }

    @objc private func openLocalizedHelp(_ sender: Any? = nil) {
        NSWorkspace.shared.open(HelpDocument.currentURL)
    }

    private func removeMenuBarItem() {
        guard let statusItem else { return }
        NSStatusBar.system.removeStatusItem(statusItem)
@@ -677,11 +842,11 @@
    }

    private func performToggleOverlay(preferredScreen: NSScreen?) {
        if overlayWindow?.isVisible == true {
            hideOverlay(force: true)
        } else {
            showOverlay(preferredScreen: preferredScreen)
        }
        overlayController.toggle(preferredScreen: preferredScreen)
    }

    private func showOrFocusOverlay(preferredScreen: NSScreen? = nil) {
        overlayController.showOrFocus(preferredScreen: preferredScreen)
    }

    private func showOverlay(
@@ -689,103 +854,101 @@
        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
        if initialQuickSearchSource == QuickSearchOpenSource.globalHidden {
            isQuickSearchOpen = true
            quickSearchShouldHideOverlayOnClose = true
            quickSearchOnlyOverlaySession = true
        }

        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
        overlayController.show(
            initialQuickSearchSource: initialQuickSearchSource,
            preferredScreen: preferredScreen,
            stagedForAllSpaces: stagedForAllSpaces
        )
        overlayGeneration &+= 1
        overlayWindow = window
        installOverlayKeyMonitor()
        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()

        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(force: true)
                return nil
            }
            if self.shouldOpenQuickSearch(for: event) {
                NotificationCenter.default.post(
                    name: .tagLauncherQuickSearchRequested,
                    object: nil,
                    userInfo: ["source": QuickSearchOpenSource.mainOverlay]
                )
            if self.handleOverlayKeyEvent(event) {
                return nil
            }
            return event
        }
    }

    @discardableResult
    private func handleOverlayKeyEvent(_ event: NSEvent) -> Bool {
        guard event.type == .keyDown else { return false }

        if event.keyCode == UInt16(kVK_Escape),
           isQuickSearchOpen || quickSearchOnlyOverlaySession {
            return handleOverlayEscapeKey()
        }

        guard shouldHandleOverlayKeyEvent(event) else { return false }

        if event.keyCode == UInt16(kVK_Escape) {
            return handleOverlayEscapeKey()
        }
        if shouldOpenQuickSearch(for: event) {
            requestQuickSearch(source: QuickSearchOpenSource.mainOverlay)
            return true
        }
        return false
    }

    private func handleOverlayEscapeKey() -> Bool {
        if isQuickSearchOpen || quickSearchOnlyOverlaySession {
            dismissQuickSearchFromKeyboard()
            return true
        }
        guard !isSettingsVisible,
              !isEditingAppNote,
              !isModalInteractionActive
        else { return false }
        hideOverlay(force: true)
        return true
    }

    private func dismissQuickSearchFromKeyboard() {
        let shouldHideOverlayAfterDismiss = quickSearchShouldHideOverlayOnClose || quickSearchOnlyOverlaySession
        isQuickSearchOpen = false
        removeQuickSearchExternalMouseMonitor()
        updateOverlayLevelForTextInput()
        NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
        if shouldHideOverlayAfterDismiss {
            quickSearchShouldHideOverlayOnClose = false
            quickSearchOnlyOverlaySession = false
            DispatchQueue.main.async { [weak self] in
                self?.hideOverlay(force: true)
            }
        }
    }

    private func requestQuickSearch(source: String) {
        isQuickSearchOpen = true
        quickSearchShouldHideOverlayOnClose = quickSearchShouldHideOverlayOnClose
            || source == QuickSearchOpenSource.globalHidden
        quickSearchOnlyOverlaySession = quickSearchOnlyOverlaySession
            || source == QuickSearchOpenSource.globalHidden
        promoteOverlayToForegroundInput()
        updateOverlayLevelForTextInput()
        installQuickSearchExternalMouseMonitor()
        DispatchQueue.main.async {
            NotificationCenter.default.post(
                name: .tagLauncherQuickSearchRequested,
                object: nil,
                userInfo: ["source": source]
            )
        }
    }

    private func shouldHandleOverlayKeyEvent(_ event: NSEvent) -> Bool {
        guard overlayWindow?.isVisible == true else { return false }
        if !isSettingsVisible && NSApp.isActive {
            return true
        }
        if event.window == overlayWindow { return true }
        return event.window == nil && NSApp.keyWindow == overlayWindow
    }
@@ -801,26 +964,7 @@
              !isModalInteractionActive
        else { return false }

        guard let firstResponder = overlayWindow?.firstResponder else { return true }
        if firstResponder is NSText || firstResponder is NSTextField {
            return false
        }
        if let responderView = firstResponder as? NSView,
           viewOrAncestorHandlesSpace(responderView) {
            return false
        }
        return true
    }

    private func viewOrAncestorHandlesSpace(_ view: NSView) -> Bool {
        var current: NSView? = view
        while let candidate = current {
            if candidate is NSButton || candidate is NSSegmentedControl || candidate is NSSlider {
                return true
            }
            current = candidate.superview
        }
        return false
    }

    private func removeOverlayKeyMonitor() {
@@ -830,58 +974,8 @@
        }
    }

    private func makeOverlayWindow(on screen: NSScreen, initialQuickSearchSource: String? = nil) -> NSWindow {
        let panel = OverlayPanel(
            contentRect: screen.frame,
            styleMask: [.borderless, .fullSizeContentView, .nonactivatingPanel],
            backing: .buffered,
            defer: false
        )
        panel.isFloatingPanel = true
        panel.hidesOnDeactivate = false
        // This combination keeps the overlay on the pointer display, including fullscreen Spaces.
        panel.collectionBehavior = [
            .canJoinAllSpaces,
            .fullScreenAuxiliary,
            .stationary,
            .transient,
            .ignoresCycle
        ]
        panel.isOpaque = false
        panel.backgroundColor = NSColor.black.withAlphaComponent(0.001)
        panel.hasShadow = false
        panel.titlebarAppearsTransparent = true
        panel.titleVisibility = .hidden
        panel.isReleasedWhenClosed = false
        panel.contentView = DismissibleHostingView(
            rootView: ContentView(
                hideOverlay: { [weak self] in
                    self?.hideOverlay(force: true)
                },
                initialQuickSearchSource: initialQuickSearchSource
            ),
            onBackdropTap: { [weak self] in
                self?.hideOverlay()
            }
        )
        return panel
    }

    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)
        }
        overlayWindow?.orderOut(nil)
        removeOverlayKeyMonitor()
        removeQuickSearchExternalMouseMonitor()
        refreshLauncherChromeState()
        NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
        if discardWindow {
            overlayWindow = nil
        }
        overlayController.hide(force: force, discardWindow: discardWindow)
    }

    // MARK: - Global Hotkeys
@@ -981,16 +1075,31 @@
    }

    private func showQuickSearchFromGlobalHotkey() {
        if overlayWindow?.isVisible == true {
            guard !isSettingsVisible else { return }
            refreshLauncherChromeState(activate: true)
            NotificationCenter.default.post(
                name: .tagLauncherQuickSearchRequested,
                object: nil,
                userInfo: ["source": QuickSearchOpenSource.globalVisible]
            )
        let now = Date()
        if overlayWindow?.isVisible == true, isQuickSearchOpen || quickSearchOnlyOverlaySession {
            lastQuickSearchHotkeyAt = now
            dismissQuickSearchFromKeyboard()
            return
        }

        if now.timeIntervalSince(lastQuickSearchHotkeyAt) < 0.28 {
            promoteOverlayToForegroundInput()
            updateOverlayLevelForTextInput()
            return
        }
        lastQuickSearchHotkeyAt = now

        if overlayWindow?.isVisible == true {
            refreshLauncherChromeState(
                activate: !overlayAvoidsSpaceSwitch,
                avoidSpaceSwitch: overlayAvoidsSpaceSwitch
            )
            requestQuickSearch(source: QuickSearchOpenSource.globalVisible)
            return
        }
        isQuickSearchOpen = true
        quickSearchShouldHideOverlayOnClose = true
        quickSearchOnlyOverlaySession = true
        showOverlay(initialQuickSearchSource: QuickSearchOpenSource.globalHidden)
    }

@@ -1035,6 +1144,19 @@
                return
            }

            if self.isMenuTrackingWindow(keyWindow) {
                return
            }

            if self.isAppOwnedDocumentWindow(keyWindow) {
                self.prepareSettingsWindow(keyWindow)
                return
            }

            if NSApp.windows.contains(keyWindow) {
                return
            }

            // Settings/Preferences window -> float it above overlay for real-time preview.
            if self.isSettingsWindowCandidate(keyWindow) {
                self.prepareSettingsWindow(keyWindow)
@@ -1047,7 +1169,8 @@

    /// Settings must always appear centered over the current overlay view and float above it.
    private func prepareSettingsWindow(_ window: NSWindow) {
        let settingsSize = NSSize(width: 880, height: 460)
        dismissQuickSearchIfNeeded()
        let settingsSize = NSSize(width: 1000, height: 480)
        window.identifier = NSUserInterfaceItemIdentifier("TagLauncherPreferencesWindow")
        window.minSize = settingsSize
        window.maxSize = settingsSize
@@ -1070,12 +1193,20 @@

        var behavior = window.collectionBehavior
        behavior.remove(.canJoinAllSpaces)
        behavior.formUnion([.fullScreenAuxiliary, .moveToActiveSpace])
        if overlayAvoidsSpaceSwitch {
            behavior.remove(.moveToActiveSpace)
            behavior.formUnion([.fullScreenAuxiliary, .stationary, .transient, .ignoresCycle])
        } else {
            behavior.formUnion([.fullScreenAuxiliary, .moveToActiveSpace])
        }
        window.collectionBehavior = behavior
        window.makeKeyAndOrderFront(nil)
        window.orderFrontRegardless()
        settingsWindow = window
        refreshLauncherChromeState(activate: true)
        refreshLauncherChromeState(
            activate: !overlayAvoidsSpaceSwitch,
            avoidSpaceSwitch: overlayAvoidsSpaceSwitch
        )
    }

    private func attachSettingsWindow(_ window: NSWindow, to overlayWindow: NSWindow) {
@@ -1092,12 +1223,47 @@
    private func isSettingsWindowCandidate(_ window: NSWindow) -> Bool {
        if window == settingsWindow { return true }
        if window.identifier?.rawValue == "TagLauncherPreferencesWindow" { return true }
        if isAppOwnedDocumentWindow(window) { return true }
        guard NSApp.windows.contains(window),
              window != overlayWindow,
              window.isVisible,
              !(window is NSPanel)
        else { return false }
        return true
        return settingsWindowTitleCandidates().contains(normalizedWindowTitle(window.title))
    }

    private func isAppOwnedDocumentWindow(_ window: NSWindow) -> Bool {
        NSApp.windows.contains(window)
            && window != overlayWindow
            && window.isVisible
            && !(window is NSPanel)
            && !isMenuTrackingWindow(window)
            && window.styleMask.contains(.titled)
    }

    private func isMenuTrackingWindow(_ window: NSWindow) -> Bool {
        let className = NSStringFromClass(type(of: window))
        return className.localizedCaseInsensitiveContains("Menu")
            || className.localizedCaseInsensitiveContains("Popup")
    }

    private func settingsWindowTitleCandidates() -> Set<String> {
        let keys = [
            "menu.preferences",
            "settings.language",
            "settings.general",
            "quickSearch.hotkeys",
            "settings.tags",
            "settings.data",
            "settings.about"
        ]
        return Set(keys.map { normalizedWindowTitle(tr($0)) })
    }

    private func normalizedWindowTitle(_ title: String) -> String {
        title
            .replacingOccurrences(of: "…", with: "")
            .trimmingCharacters(in: .whitespacesAndNewlines)
    }

    private func isSettingsOwnedPanel(_ window: NSWindow) -> Bool {
@@ -1119,24 +1285,7 @@
    }

    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)
        })
        overlayController.screenUnderMouse()
    }

    /// Clean up settingsWindow reference when the Settings window closes.
@@ -1150,9 +1299,18 @@
                  let closingWindow = notification.object as? NSWindow,
                  closingWindow == self.settingsWindow
            else { return }
            let shouldRefocusOverlay = self.isOverlayVisible
            let preferredScreen = self.overlayWindow?.screen
            self.detachSettingsWindow(closingWindow)
            self.settingsWindow = nil
            self.refreshLauncherChromeState()
            self.refreshLauncherChromeState(
                activate: shouldRefocusOverlay && !self.overlayAvoidsSpaceSwitch,
                avoidSpaceSwitch: self.overlayAvoidsSpaceSwitch
            )
            guard shouldRefocusOverlay else { return }
            DispatchQueue.main.asyncAfter(deadline: .now() + 0.12) { [weak self] in
                self?.showOrFocusOverlay(preferredScreen: preferredScreen)
            }
        }
    }

@@ -1184,6 +1342,21 @@
    }

    private func promoteOverlayToForegroundInput() {
        if overlayAvoidsSpaceSwitch {
            refreshLauncherChromeState(activate: false, avoidSpaceSwitch: true)
            guard let overlayWindow else { return }
            overlayWindow.makeKeyAndOrderFront(nil)
            overlayWindow.orderFrontRegardless()
            return
        }
        if quickSearchOnlyOverlaySession && !UserDefaults.standard.bool(forKey: Self.showDockIconKey) {
            refreshLauncherChromeState(activate: false)
            guard let overlayWindow else { return }
            NSApp.activate(ignoringOtherApps: true)
            overlayWindow.makeKeyAndOrderFront(nil)
            overlayWindow.orderFrontRegardless()
            return
        }
        beginLauncherForegroundOwnership()
        guard let overlayWindow else { return }
        overlayWindow.makeKeyAndOrderFront(nil)
@@ -1197,7 +1370,13 @@
            queue: .main
        ) { [weak self] notification in
            guard let self else { return }
            self.isQuickSearchOpen = (notification.userInfo?["active"] as? Bool) ?? false
            let active = (notification.userInfo?["active"] as? Bool) ?? false
            let hideOverlayOnClose = (notification.userInfo?["hideOverlayOnClose"] as? Bool) ?? false
            self.isQuickSearchOpen = active
            if active, hideOverlayOnClose {
                self.quickSearchShouldHideOverlayOnClose = true
                self.quickSearchOnlyOverlaySession = true
            }
            if self.isQuickSearchOpen {
                self.promoteOverlayToForegroundInput()
            }
@@ -1206,6 +1385,11 @@
                self.installQuickSearchExternalMouseMonitor()
            } else {
                self.removeQuickSearchExternalMouseMonitor()
                if hideOverlayOnClose || self.quickSearchShouldHideOverlayOnClose {
                    self.quickSearchShouldHideOverlayOnClose = false
                    self.quickSearchOnlyOverlaySession = false
                    self.hideOverlay(force: true)
                }
            }
        }

@@ -1227,6 +1411,7 @@
    }

    private func installQuickSearchExternalMouseMonitor() {
        installQuickSearchLocalMouseMonitor()
        guard quickSearchExternalMouseMonitor == nil else { return }
        quickSearchExternalMouseMonitor = NSEvent.addGlobalMonitorForEvents(
            matching: [.leftMouseDown, .rightMouseDown, .otherMouseDown]
@@ -1238,7 +1423,25 @@
        }
    }

    private func installQuickSearchLocalMouseMonitor() {
        guard quickSearchLocalMouseMonitor == nil else { return }
        quickSearchLocalMouseMonitor = NSEvent.addLocalMonitorForEvents(
            matching: [.leftMouseDown, .rightMouseDown, .otherMouseDown]
        ) { [weak self] event in
            guard let self, self.isQuickSearchOpen else { return event }
            if event.window === self.overlayWindow {
                NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
                return nil
            }
            return event
        }
    }

    private func removeQuickSearchExternalMouseMonitor() {
        if let quickSearchLocalMouseMonitor {
            NSEvent.removeMonitor(quickSearchLocalMouseMonitor)
            self.quickSearchLocalMouseMonitor = nil
        }
        if let quickSearchExternalMouseMonitor {
            NSEvent.removeMonitor(quickSearchExternalMouseMonitor)
            self.quickSearchExternalMouseMonitor = nil
@@ -1264,9 +1467,29 @@
        }
    }

    private func observeExternalActivationRequests() {
        DistributedNotificationCenter.default().addObserver(
            self,
            selector: #selector(handleExternalActivationRequest(_:)),
            name: Self.externalActivationNotification,
            object: Self.externalActivationObject
        )
    }

    @objc private func handleExternalActivationRequest(_ notification: Notification) {
        let shouldShowOverlay = notification.userInfo?["showOverlay"] as? Bool ?? true
        guard shouldShowOverlay else { return }
        showOrFocusOverlay()
    }

    @objc private func openPreferences(_ sender: Any? = nil) {
        dismissQuickSearchIfNeeded()
        TagDatabase.flushPendingCategorySchemeBackupBatch()
        beginLauncherForegroundOwnership()
        if overlayAvoidsSpaceSwitch {
            refreshLauncherChromeState(activate: false, avoidSpaceSwitch: true)
        } else {
            beginLauncherForegroundOwnership()
        }
        // Don't hide overlay — keep it visible for real-time setting preview.
        if let overlayWindow, overlayWindow.isVisible {
            overlayWindow.makeKeyAndOrderFront(nil)
@@ -1278,7 +1501,7 @@
            return
        }

        let settingsSize = NSSize(width: 880, height: 460)
        let settingsSize = NSSize(width: 1000, height: 480)
        let window = NSWindow(
            contentRect: NSRect(origin: .zero, size: settingsSize),
            styleMask: [.titled, .closable],
@@ -1292,6 +1515,16 @@
        prepareSettingsWindow(window)
    }

    private func dismissQuickSearchIfNeeded() {
        guard isQuickSearchOpen else { return }
        isQuickSearchOpen = false
        removeQuickSearchExternalMouseMonitor()
        updateOverlayLevelForTextInput()
        quickSearchShouldHideOverlayOnClose = false
        quickSearchOnlyOverlaySession = false
        NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
    }

    @objc private func switchLanguage(_ sender: NSMenuItem) {
        guard let code = sender.representedObject as? String else { return }
        L10n.switchTo(code)