crazy-macs/tag-launcher.git

			@@ -6,13 +6,23 @@

			@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: 420)
			.defaultSize(width: 880, height: 460)
			.commands {
			CommandGroup(replacing: .systemServices) { }
			CommandGroup(replacing: .appVisibility) { }
			CommandGroup(replacing: .help) { }
			}
			}
			}

			@@ -21,35 +31,139 @@
			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 {
			private var statusItem: NSStatusItem!
			final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
			private static let showDockIconKey = "showDockIcon"
			private static let statusItemAutosaveName = AppIdentity.statusItemAutosaveName
			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 quickSearchExternalMouseMonitor: Any?
			private var settingsWindow: NSWindow? // Track Settings window to keep it above overlay
			private var hotkeyRef: EventHotKeyRef?
			private var mainHotkeyRef: EventHotKeyRef?
			private var quickSearchHotkeyRef: EventHotKeyRef?
			private var hotkeyEventHandlerInstalled = false
			private var isQuickSearchOpen = false
			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 overlayAvoidsSpaceSwitch = false
			private var suppressReopenUntil = Date.distantPast

			private struct OverlayPlacementContext {
			let screen: NSScreen
			let frame: NSRect
			}

			private struct ForeignWindowFrame {
			let owner: String
			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 shouldStageOverlayAsAccessory: Bool {
			!isSettingsVisible && !UserDefaults.standard.bool(forKey: Self.showDockIconKey)
			}

			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)
			}

			static func openPreferencesWindow() {
			(NSApp.delegate as? AppDelegate)?.openPreferences()
			}

			func applicationDidFinishLaunching(_ notification: Notification) {
			AppDefaults.register()
			L10n.setup()
			migrateDefaultGroupName()
			TagDatabase.seedDefaultTags()
			let showDock = UserDefaults.standard.bool(forKey: "showDockIcon")
			NSApp.setActivationPolicy(showDock ? .regular : .accessory)
			setupMenuBar()
			registerHotkey()
			syncChromeSettings(force: true)
			observeHotkeyStatusChanges()
			registerConfiguredHotkeys()
			observeOtherWindows()
			observeSettingsClose()
			observeEditMode()
			observeDockSetting()
			observeAppNoteEditing()
			observeQuickSearch()
			observePreferencesRequests()
			observeExternalActivationRequests()
			observeApplicationMenuChanges()
			observeChromeSettings()
			observeLanguageChanges()
			setupLaunchAtLogin()
			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 {
			showOverlay()
			guard Date() >= suppressReopenUntil else { return false }
			showOrFocusOverlay()
			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()
			DistributedNotificationCenter.default().removeObserver(
			self,
			name: Self.externalActivationNotification,
			object: Self.externalActivationObject
			)
			}

			/// Ensure defaultGroupName is always the language-neutral key "Other".
			@@ -70,14 +184,129 @@
			// User has set a custom name — keep it
			}

			/// Observe Show in Dock changes so it takes effect immediately.
			private func observeDockSetting() {
			/// Observe Dock visibility changes so they take effect immediately.
			private func observeChromeSettings() {
			NotificationCenter.default.addObserver(
			forName: UserDefaults.didChangeNotification,
			object: nil, queue: .main
			) { _ in
			let show = UserDefaults.standard.bool(forKey: "showDockIcon")
			NSApp.setActivationPolicy(show ? .regular : .accessory)
			) { [weak self] _ in
			self?.syncChromeSettings()
			}
			}

			private func syncChromeSettings(force: Bool = false) {
			let showDock = UserDefaults.standard.bool(forKey: Self.showDockIconKey)
			let dockChanged = lastShowDockIcon != showDock

			if force \|\| dockChanged {
			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, avoidSpaceSwitch: Bool = false) {
			let showDock = UserDefaults.standard.bool(forKey: Self.showDockIconKey)
			lastShowDockIcon = showDock

			let shouldStayAccessoryForCurrentFullscreenSpace = isOverlayVisible
			&& (avoidSpaceSwitch \|\| overlayAvoidsSpaceSwitch)
			let desiredPolicy: NSApplication.ActivationPolicy = shouldStayAccessoryForCurrentFullscreenSpace
			? .accessory
			: (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 && !shouldStayAccessoryForCurrentFullscreenSpace {
			let keyWindow = isSettingsVisible ? settingsWindow : (isOverlayVisible ? overlayWindow : nil)
			claimLauncherForeground(
			keyWindow: keyWindow,
			retries: isOverlayVisible && !isSettingsVisible ? 5 : 0,
			overlayGeneration: isOverlayVisible ? overlayGeneration : nil
			)
			}
			}

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

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

			if !requiresForegroundOwnership {
			refreshLauncherChromeState()
			}
			}

			@@ -88,12 +317,16 @@
			object: nil, queue: .main
			) { [weak self] _ in
			self?.setupMenuBar()
			self?.configureApplicationMenuWhenAvailable()
			}
			}

			// 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
			}

			private static var launchAgentURL: URL {
			FileManager.default.homeDirectoryForCurrentUser
			@@ -101,9 +334,10 @@
			}

			static func enableLaunchAtLogin() {
			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()
			@@ -111,27 +345,61 @@
			(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() {
			guard supportsLaunchAtLogin else { return }
			let uid = getuid()
			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.
			/// Does NOT require App Management permission.
			private func setupLaunchAtLogin() {
			guard Self.supportsLaunchAtLogin else {
			if UserDefaults.standard.object(forKey: "launchAtLogin") == nil {
			UserDefaults.standard.set(false, forKey: "launchAtLogin")
			}
			return
			}
			let key = "launchAtLogin"
			if UserDefaults.standard.object(forKey: key) == nil {
			UserDefaults.standard.set(true, 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()
			}
			}
			@@ -139,30 +407,36 @@
			// MARK: - Menu Bar

			private func setupMenuBar() {
			// Remove old status item if re-creating (language switch, etc.)
			if let existing = statusItem {
			NSStatusBar.system.removeStatusItem(existing)
			if statusItem == nil {
			statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
			} else {
			statusItem?.length = NSStatusItem.squareLength
			}
			statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
			guard let statusItem else { return }
			statusItem.autosaveName = Self.statusItemAutosaveName
			statusItem.isVisible = true

			if let button = statusItem.button {
			button.image = NSImage(
			systemSymbolName: "tag.fill",
			accessibilityDescription: "TagLauncher"
			)
			button.identifier = Self.statusItemButtonIdentifier
			button.setAccessibilityIdentifier(Self.statusItemAutosaveName)
			button.setAccessibilityLabel(Self.statusItemAccessibilityLabel)
			button.image = makeMenuBarIcon()
			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.addItem(
			NSMenuItem(
			title: "\(tr("menu.show")) ⇧⌥Space",
			action: #selector(toggleOverlay),
			keyEquivalent: ""
			)
			menu.delegate = self
			let showItem = NSMenuItem(
			title: showAppListMenuTitle,
			action: #selector(toggleOverlayFromStatusMenu(_:)),
			keyEquivalent: ""
			)
			showItem.target = self
			menu.addItem(showItem)
			menu.addItem(.separator())

			// Version display
			@@ -179,9 +453,10 @@
			menu.addItem(.separator())
			let prefsItem = NSMenuItem(
			title: tr("menu.preferences"),
			action: #selector(openPreferences),
			action: #selector(openPreferences(_:)),
			keyEquivalent: ","
			)
			prefsItem.target = self
			prefsItem.keyEquivalentModifierMask = .command
			menu.addItem(prefsItem)
			menu.addItem(.separator())
			@@ -210,42 +485,571 @@
			statusItem.menu = menu
			}

			// MARK: - Overlay Window
			func menuWillOpen(_ menu: NSMenu) {
			statusMenuScreenForNextOverlay = screenContainingCurrentPointer()
			?? statusItem?.button?.window?.screen
			?? NSScreen.main
			?? NSScreen.screens.first
			}

			@objc private func toggleOverlay() {
			if overlayWindow?.isVisible == true {
			hideOverlay()
			} else {
			showOverlay()
			func menuDidClose(_ menu: NSMenu) {
			DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) { [weak self] in
			self?.statusMenuScreenForNextOverlay = nil
			}
			}

			private func showOverlay() {
			// 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 }
			private func makeMenuBarIcon() -> NSImage {
			let menuBarIconSize = NSSize(width: 19, height: 19)
			if let url = Bundle.main.url(forResource: "TagLauncherMenuBarIcon", withExtension: "svg"),
			let image = NSImage(contentsOf: url) {
			image.size = menuBarIconSize
			image.isTemplate = true
			image.accessibilityDescription = "TagLauncher"
			return image
			}

			overlayWindow?.orderOut(nil)
			overlayWindow = makeOverlayWindow(on: screen)
			overlayWindow?.setFrame(screen.frame, display: true)
			overlayWindow?.level = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
			let image = NSImage(size: menuBarIconSize)
			image.lockFocus()
			defer { image.unlockFocus() }

			// Local key monitor: catch Escape while overlay is up
			NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
			NSGraphicsContext.current?.shouldAntialias = true
			NSColor.black.withAlphaComponent(0.88).setStroke()
			NSColor.black.withAlphaComponent(0.88).setFill()

			let scale = image.size.width / 220.0
			func rectFromSVG(x: CGFloat, y: CGFloat, width: CGFloat, height: CGFloat) -> NSRect {
			NSRect(
			x: x * scale,
			y: (220.0 - y - height) * scale,
			width: width * scale,
			height: height * scale
			)
			}

			let outline = NSBezierPath(
			roundedRect: rectFromSVG(x: 15, y: 15, width: 190, height: 190),
			xRadius: 44 * scale,
			yRadius: 44 * scale
			)
			outline.lineWidth = 11 * scale
			outline.stroke()

			for rect in [
			rectFromSVG(x: 49, y: 134, width: 27, height: 27),
			rectFromSVG(x: 92, y: 134, width: 27, height: 27),
			rectFromSVG(x: 49, y: 91, width: 27, height: 27),
			rectFromSVG(x: 92, y: 91, width: 27, height: 27),
			rectFromSVG(x: 49, y: 48, width: 27, height: 27),
			rectFromSVG(x: 92, y: 48, width: 27, height: 27)
			] {
			NSBezierPath(roundedRect: rect, xRadius: 8 * scale, yRadius: 8 * scale).fill()
			}

			for rect in [
			rectFromSVG(x: 132, y: 133, width: 47, height: 28),
			rectFromSVG(x: 132, y: 90.5, width: 47, height: 28),
			rectFromSVG(x: 132, y: 48, width: 47, height: 28)
			] {
			NSBezierPath(roundedRect: rect, xRadius: 12 * scale, yRadius: 12 * scale).fill()
			}

			image.isTemplate = true
			image.accessibilityDescription = "TagLauncher"
			return image
			}

			private var showAppListMenuTitle: String {
			if LauncherHotkeyRegistrationStore.state(for: .main) == .failed {
			return tr("menu.showShortcutUnavailable")
			}
			return "\(tr("menu.showAppList")) \(LauncherHotkey.main.displayString)"
			}

			private func observeApplicationMenuChanges() {
			NotificationCenter.default.addObserver(
			forName: NSApplication.didBecomeActiveNotification,
			object: NSApp, queue: .main
			) { [weak self] _ in
			self?.configureApplicationMenuWhenAvailable(retries: 4)
			}

			NotificationCenter.default.addObserver(
			forName: NSMenu.didAddItemNotification,
			object: nil, queue: .main
			) { [weak self] notification in
			guard let self,
			!self.isConfiguringApplicationMenu,
			let menu = notification.object as? NSMenu,
			menu === NSApp.mainMenu?.items.first?.submenu
			else { return }
			self.configureApplicationMenuWhenAvailable(retries: 2)
			}
			}

			private func configureApplicationMenuWhenAvailable(retries: Int = 20) {
			DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) { [weak self] in
			guard let self else { return }
			guard NSApp.mainMenu?.items.first?.submenu != nil else {
			if retries > 0 {
			self.configureApplicationMenuWhenAvailable(retries: retries - 1)
			}
			return
			}

			self.configureApplicationMenu()
			self.configureHelpMenu()
			if retries > 0 && self.applicationMenuNeedsCleanup() {
			self.configureApplicationMenuWhenAvailable(retries: retries - 1)
			}
			}
			}

			private func configureApplicationMenu() {
			guard !isConfiguringApplicationMenu else { return }
			guard let appMenu = NSApp.mainMenu?.items.first?.submenu else { return }

			isConfiguringApplicationMenu = true
			defer { isConfiguringApplicationMenu = false }

			removeUnusedDefaultItems(from: appMenu)
			configurePreferencesMenuItem(in: appMenu)
			upsertShowAppListItem(in: appMenu)
			normalizeSeparators(in: appMenu)
			}

			private func applicationMenuNeedsCleanup() -> Bool {
			guard let appMenu = NSApp.mainMenu?.items.first?.submenu else { return true }
			let hasUnusedDefaultItems = appMenu.items.contains(where: isUnusedDefaultApplicationMenuItem)
			let hasShowAppListItem = appMenu.items.contains {
			$0.identifier == Self.showAppListMenuItemIdentifier
			}
			return hasUnusedDefaultItems \|\| !hasShowAppListItem
			}

			private func removeUnusedDefaultItems(from menu: NSMenu) {
			for item in menu.items.reversed() where isUnusedDefaultApplicationMenuItem(item) {
			menu.removeItem(item)
			}
			}

			private func isUnusedDefaultApplicationMenuItem(_ item: NSMenuItem) -> Bool {
			if let servicesMenu = NSApp.servicesMenu, item.submenu === servicesMenu {
			return true
			}
			return item.action == #selector(NSApplication.hide(_:))
			\|\| item.action == #selector(NSApplication.hideOtherApplications(_:))
			\|\| item.action == #selector(NSApplication.unhideAllApplications(_:))
			}

			private func upsertShowAppListItem(in menu: NSMenu) {
			if let existingItem = menu.items.first(where: { $0.identifier == Self.showAppListMenuItemIdentifier }) {
			configureShowAppListItem(existingItem)
			return
			}

			let item = NSMenuItem()
			item.identifier = Self.showAppListMenuItemIdentifier
			configureShowAppListItem(item)

			if let settingsIndex = menu.items.firstIndex(where: { isSettingsMenuItem($0) }) {
			menu.insertItem(item, at: settingsIndex + 1)
			} else if let firstSeparatorIndex = menu.items.firstIndex(where: { $0.isSeparatorItem }) {
			menu.insertItem(item, at: firstSeparatorIndex)
			} else {
			menu.addItem(item)
			}
			}

			private func configureShowAppListItem(_ item: NSMenuItem) {
			item.title = showAppListMenuTitle
			item.action = #selector(toggleOverlayFromStatusMenu(_:))
			item.target = self
			item.keyEquivalent = ""
			item.keyEquivalentModifierMask = []
			item.isEnabled = true
			}

			private func configurePreferencesMenuItem(in menu: NSMenu) {
			let item: NSMenuItem
			if let existingItem = menu.items.first(where: { isSettingsMenuItem($0) }) {
			item = existingItem
			} else {
			item = NSMenuItem()
			if let firstSeparatorIndex = menu.items.firstIndex(where: { $0.isSeparatorItem }) {
			menu.insertItem(item, at: firstSeparatorIndex)
			} else {
			menu.addItem(item)
			}
			}

			item.title = tr("menu.preferences")
			item.action = #selector(openPreferences(_:))
			item.target = self
			item.keyEquivalent = ","
			item.keyEquivalentModifierMask = .command
			item.isEnabled = true
			}

			private func isSettingsMenuItem(_ item: NSMenuItem) -> Bool {
			item.action == Selector(("showSettingsWindow:"))
			\|\| item.action == #selector(openPreferences(_:))
			\|\| item.title == tr("menu.preferences")
			}

			private func normalizeSeparators(in menu: NSMenu) {
			var indexesToRemove: [Int] = []
			var previousWasSeparator = false

			for (index, item) in menu.items.enumerated() {
			guard item.isSeparatorItem else {
			previousWasSeparator = false
			continue
			}
			if index == 0 \|\| index == menu.items.count - 1 \|\| previousWasSeparator {
			indexesToRemove.append(index)
			}
			previousWasSeparator = true
			}

			for index in indexesToRemove.reversed() {
			menu.removeItem(at: index)
			}
			}

			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)
			self.statusItem = nil
			}

			// MARK: - Overlay Window

			@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 performToggleOverlay(preferredScreen: NSScreen?) {
			if overlayWindow?.isVisible == true {
			hideOverlay(force: true)
			} else {
			showOverlay(preferredScreen: preferredScreen)
			}
			}

			private func showOrFocusOverlay(preferredScreen: NSScreen? = nil) {
			let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen)
			let shouldAvoidSpaceSwitch = placement.map { hasFullscreenWindowOnScreen($0.screen) } ?? false
			if let overlayWindow, overlayWindow.isVisible {
			overlayAvoidsSpaceSwitch = shouldAvoidSpaceSwitch
			moveOverlayToCurrentPlacement(preferredScreen: preferredScreen)
			overlayWindow.level = currentOverlayLevel
			refreshLauncherChromeState(activate: !shouldAvoidSpaceSwitch, avoidSpaceSwitch: shouldAvoidSpaceSwitch)
			overlayWindow.makeKeyAndOrderFront(nil)
			overlayWindow.orderFrontRegardless()
			if let settingsWindow, settingsWindow.isVisible {
			prepareSettingsWindow(settingsWindow)
			}
			return
			}
			showOverlay(preferredScreen: preferredScreen)
			}

			private func moveOverlayToCurrentPlacement(preferredScreen: NSScreen?) {
			guard let overlayWindow,
			let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen),
			overlayWindow.frame != placement.frame
			else { return }
			overlayWindow.setFrame(placement.frame, display: true)
			}

			private func showOverlay(
			initialQuickSearchSource: String? = nil,
			preferredScreen: NSScreen? = nil,
			stagedForAllSpaces: Bool = false
			) {
			guard let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen) else { return }

			let shouldAvoidSpaceSwitch = hasFullscreenWindowOnScreen(placement.screen)
			let shouldStageAsAccessory = shouldStageOverlayAsAccessory \|\| shouldAvoidSpaceSwitch

			if !stagedForAllSpaces && shouldStageAsAccessory {
			// Let the all-spaces panel attach to the pointer's display before the app reclaims focus.
			if NSApp.activationPolicy() != .accessory {
			NSApp.setActivationPolicy(.accessory)
			}
			if NSApp.isActive {
			NSApp.deactivate()
			}
			DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) { [weak self] in
			self?.showOverlay(
			initialQuickSearchSource: initialQuickSearchSource,
			preferredScreen: placement.screen,
			stagedForAllSpaces: true
			)
			}
			return
			}

			if overlayWindow?.isVisible == true {
			hideOverlay(force: true)
			} else if let existingWindow = overlayWindow {
			existingWindow.orderOut(nil)
			overlayWindow = nil
			}
			overlayAvoidsSpaceSwitch = shouldAvoidSpaceSwitch

			let window = makeOverlayWindow(
			on: placement.screen,
			initialQuickSearchSource: initialQuickSearchSource
			)
			overlayGeneration &+= 1
			overlayWindow = window
			installOverlayKeyMonitor()
			if shouldStageAsAccessory {
			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: !shouldAvoidSpaceSwitch, avoidSpaceSwitch: shouldAvoidSpaceSwitch)
			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 {
			DispatchQueue.main.asyncAfter(deadline: .now() + 0.12, execute: finishForegroundClaim)
			} else {
			finishForegroundClaim()
			}
			}

			private func hasFullscreenWindowOnScreen(_ screen: NSScreen) -> Bool {
			let screenFrame = screen.frame
			let windowFrames = foreignLayerZeroWindows(on: screenFrame)

			if windowFrames.contains(where: { isSingleFullscreenWindow($0.frame, on: screenFrame) }) {
			return true
			}

			return hasSplitViewFullscreenWindows(windowFrames, on: screenFrame)
			}

			private func foreignLayerZeroWindows(on screenFrame: NSRect) -> [ForeignWindowFrame] {
			let windows = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] ?? []
			return windows.compactMap { info in
			guard let owner = info[kCGWindowOwnerName as String] as? String,
			owner != AppIdentity.displayName,
			owner != "Window Server",
			owner != "Dock",
			owner != "loginwindow",
			let layer = info[kCGWindowLayer as String] as? Int,
			layer == 0,
			let bounds = info[kCGWindowBounds as String] as? NSDictionary
			else { return nil }

			let frame = NSRect(
			x: cgWindowDimension(bounds, "X"),
			y: cgWindowDimension(bounds, "Y"),
			width: cgWindowDimension(bounds, "Width"),
			height: cgWindowDimension(bounds, "Height")
			)
			guard frame.intersects(screenFrame) else { return nil }
			return ForeignWindowFrame(owner: owner, frame: frame)
			}
			}

			private func isSingleFullscreenWindow(_ windowFrame: NSRect, on screenFrame: NSRect) -> Bool {
			let widthMatches = abs(windowFrame.width - screenFrame.width) <= 12
			let heightMatches = windowFrame.height >= screenFrame.height * 0.88
			let horizontallyAligned = abs(windowFrame.midX - screenFrame.midX) <= 12
			let verticallyAligned = abs(windowFrame.maxY - screenFrame.maxY) <= 32
			return widthMatches && heightMatches && horizontallyAligned && verticallyAligned
			}

			private func hasSplitViewFullscreenWindows(_ windows: [ForeignWindowFrame], on screenFrame: NSRect) -> Bool {
			let clippedWindows = windows.map {
			ForeignWindowFrame(owner: $0.owner, frame: $0.frame.intersection(screenFrame))
			}
			let tallWindows = clippedWindows
			.filter { window in
			let frame = window.frame
			return frame.height >= screenFrame.height * 0.86
			&& frame.width >= screenFrame.width * 0.20
			&& frame.width <= screenFrame.width * 0.86
			&& abs(frame.maxY - screenFrame.maxY) <= 32
			}
			.sorted { $0.frame.minX < $1.frame.minX }

			guard tallWindows.count >= 2 else { return false }

			for startIndex in tallWindows.indices {
			var union = tallWindows[startIndex].frame
			var lastMaxX = union.maxX

			for window in tallWindows.dropFirst(startIndex + 1) {
			let gap = window.frame.minX - lastMaxX
			if gap < -32 \|\| gap > 48 {
			break
			}
			union = union.union(window.frame)
			lastMaxX = max(lastMaxX, window.frame.maxX)

			let touchesLeft = abs(union.minX - screenFrame.minX) <= 32
			let touchesRight = abs(union.maxX - screenFrame.maxX) <= 32
			let coversWidth = union.width >= screenFrame.width * 0.92
			let coversHeight = union.height >= screenFrame.height * 0.86
			if touchesLeft && touchesRight && coversWidth && coversHeight {
			return true
			}
			}
			}

			return false
			}

			private func cgWindowDimension(_ bounds: NSDictionary, _ key: String) -> CGFloat {
			if let value = bounds[key] as? CGFloat {
			return value
			}
			if let value = bounds[key] as? NSNumber {
			return CGFloat(truncating: value)
			}
			return 0
			}

			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
			self?.hideOverlay()
			if self.isQuickSearchOpen {
			self.isQuickSearchOpen = false
			self.removeQuickSearchExternalMouseMonitor()
			self.updateOverlayLevelForTextInput()
			NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
			return nil
			}
			self.hideOverlay(force: true)
			return nil
			}
			if self.shouldOpenQuickSearch(for: event) {
			self.requestQuickSearch(source: QuickSearchOpenSource.mainOverlay)
			return nil
			}
			return event
			}

			overlayWindow?.makeKeyAndOrderFront(nil)
			overlayWindow?.orderFrontRegardless()
			}

			private func makeOverlayWindow(on screen: NSScreen) -> NSWindow {
			private func requestQuickSearch(source: String) {
			isQuickSearchOpen = true
			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
			}

			private func shouldOpenQuickSearch(for event: NSEvent) -> Bool {
			guard event.keyCode == UInt16(kVK_Space),
			!event.isARepeat,
			event.modifierFlags.intersection(.deviceIndependentFlagsMask).isEmpty,
			overlayWindow?.isVisible == true,
			!isQuickSearchOpen,
			!isInEditMode,
			!isEditingAppNote,
			!isModalInteractionActive
			else { return false }

			return true
			}

			private func removeOverlayKeyMonitor() {
			if let monitor = overlayKeyMonitor {
			NSEvent.removeMonitor(monitor)
			overlayKeyMonitor = nil
			}
			}

			private func makeOverlayWindow(on screen: NSScreen, initialQuickSearchSource: String? = nil) -> NSWindow {
			let panel = OverlayPanel(
			contentRect: screen.frame,
			styleMask: [.borderless, .fullSizeContentView, .nonactivatingPanel],
			@@ -254,23 +1058,28 @@
			)
			panel.isFloatingPanel = true
			panel.hidesOnDeactivate = false
			// Keep the overlay publishable above fullscreen Spaces without asking
			// AppKit to migrate an all-spaces window between 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
			panel.isReleasedWhenClosed = false
			panel.contentView = DismissibleHostingView(
			rootView: ContentView(hideOverlay: { [weak self] in
			self?.hideOverlay(force: true)
			}),
			rootView: ContentView(
			hideOverlay: { [weak self] in
			self?.hideOverlay(force: true)
			},
			initialQuickSearchSource: initialQuickSearchSource
			),
			onBackdropTap: { [weak self] in
			self?.hideOverlay()
			}
			@@ -278,56 +1087,102 @@
			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)
			}
			overlayWindow?.orderOut(nil)
			if force {
			removeOverlayKeyMonitor()
			removeQuickSearchExternalMouseMonitor()
			overlayAvoidsSpaceSwitch = false
			refreshLauncherChromeState()
			NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
			if discardWindow {
			overlayWindow = nil
			}
			}

			// MARK: - Global Hotkey (Shift+Option+Space)
			// MARK: - Global Hotkeys

			/// Carbon RegisterEventHotKey. If it fails (sandbox, etc.), falls back to menu bar only.
			private func registerHotkey() {
			private func registerConfiguredHotkeys() {
			installHotkeyEventHandlerIfNeeded()
			registerFixedHotkey(.main)
			registerFixedHotkey(.quickSearch)
			}

			private func registerFixedHotkey(_ kind: LauncherHotkeyKind) {
			unregisterHotkey(for: kind)
			let hotkey = kind.hotkey

			var hotkeyID = EventHotKeyID()
			hotkeyID.signature = OSType(0x41505447) // 'APTG'
			hotkeyID.id = 1
			hotkeyID.id = kind.eventID

			let modifiers = UInt32(shiftKey \| optionKey)

			var ref: EventHotKeyRef?
			var newRef: EventHotKeyRef?
			let status = RegisterEventHotKey(
			UInt32(kVK_Space),
			modifiers,
			hotkey.keyCode,
			hotkey.modifiers,
			hotkeyID,
			GetApplicationEventTarget(),
			0,
			&ref
			&newRef
			)
			hotkeyRef = ref

			if status != noErr {
			print("[TagLauncher] Hotkey registration failed: \(status). Falling back to menu bar only.")
			return
			if status == noErr, let newRef {
			setHotkeyRef(newRef, for: kind)
			LauncherHotkeyRegistrationStore.setActive(for: kind)
			} else {
			setHotkeyRef(nil, for: kind)
			LauncherHotkeyRegistrationStore.setFailed(status, for: kind)
			print("[TagLauncher] Fixed hotkey registration failed for \(kind.rawValue): \(status)")
			}
			}

			private func observeHotkeyStatusChanges() {
			NotificationCenter.default.addObserver(
			forName: .tagLauncherHotkeyRegistrationChanged,
			object: nil,
			queue: .main
			) { [weak self] _ in
			self?.setupMenuBar()
			self?.configureApplicationMenuWhenAvailable(retries: 2)
			}
			}

			private func installHotkeyEventHandlerIfNeeded() {
			guard !hotkeyEventHandlerInstalled else { return }
			hotkeyEventHandlerInstalled = true

			var eventSpec = EventTypeSpec(
			eventClass: OSType(kEventClassKeyboard),
			eventKind: UInt32(kEventHotKeyPressed)
			)

			let selfPtr = Unmanaged.passUnretained(self).toOpaque()

			InstallEventHandler(
			GetApplicationEventTarget(),
			{ (_, _, userData) -> OSStatus in
			guard let userData else { return noErr }
			{ (_, event, userData) -> OSStatus in
			guard let event, let userData else { return noErr }
			var hotkeyID = EventHotKeyID()
			let status = GetEventParameter(
			event,
			EventParamName(kEventParamDirectObject),
			EventParamType(typeEventHotKeyID),
			nil,
			MemoryLayout<EventHotKeyID>.size,
			nil,
			&hotkeyID
			)
			guard status == noErr else { return noErr }

			let delegate = Unmanaged<AppDelegate>
			.fromOpaque(userData)
			.takeUnretainedValue()
			DispatchQueue.main.async {
			delegate.toggleOverlay()
			delegate.handleHotkeyEvent(id: hotkeyID.id)
			}
			return noErr
			},
			@@ -336,6 +1191,47 @@
			selfPtr,
			nil
			)
			}

			private func handleHotkeyEvent(id: UInt32) {
			if id == LauncherHotkeyKind.quickSearch.eventID {
			showQuickSearchFromGlobalHotkey()
			} else {
			performToggleOverlay(preferredScreen: nil)
			}
			}

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

			private func hotkeyRef(for kind: LauncherHotkeyKind) -> EventHotKeyRef? {
			switch kind {
			case .main: return mainHotkeyRef
			case .quickSearch: return quickSearchHotkeyRef
			}
			}

			private func setHotkeyRef(_ ref: EventHotKeyRef?, for kind: LauncherHotkeyKind) {
			switch kind {
			case .main: mainHotkeyRef = ref
			case .quickSearch: quickSearchHotkeyRef = ref
			}
			}

			private func unregisterHotkey(for kind: LauncherHotkeyKind) {
			if let ref = hotkeyRef(for: kind) {
			UnregisterEventHotKey(ref)
			setHotkeyRef(nil, for: kind)
			}
			}

			// MARK: - Preferences
			@@ -354,8 +1250,25 @@
			!self.isInEditMode
			else { return }

			// Settings/Preferences window → float it above overlay for real-time preview
			if self.isSettingsOwnedPanel(keyWindow) {
			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)
			return
			}
			@@ -366,10 +1279,11 @@

			/// 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: max(window.frame.height, 420))
			window.minSize = NSSize(width: 880, height: 420)
			window.maxSize = NSSize(width: 880, height: CGFloat.greatestFiniteMagnitude)
			if abs(window.frame.width - settingsSize.width) > 0.5 \|\| window.frame.height < settingsSize.height {
			let settingsSize = NSSize(width: 880, height: 460)
			window.identifier = NSUserInterfaceItemIdentifier("TagLauncherPreferencesWindow")
			window.minSize = settingsSize
			window.maxSize = settingsSize
			if abs(window.frame.width - settingsSize.width) > 0.5 \|\| abs(window.frame.height - settingsSize.height) > 0.5 {
			window.setFrame(
			NSRect(origin: window.frame.origin, size: settingsSize),
			display: false
			@@ -378,16 +1292,96 @@

			if let overlayWindow, overlayWindow.isVisible {
			center(window, over: overlayWindow.frame)
			window.level = NSWindow.Level(rawValue: overlayWindow.level.rawValue + 1)
			attachSettingsWindow(window, to: overlayWindow)
			window.level = overlayWindow.level
			} else if let screen = screenUnderMouse() {
			center(window, over: screen.visibleFrame)
			window.level = .floating
			detachSettingsWindow(window)
			}

			window.collectionBehavior.formUnion([.moveToActiveSpace, .fullScreenAuxiliary])
			var behavior = window.collectionBehavior
			behavior.remove(.canJoinAllSpaces)
			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: !overlayAvoidsSpaceSwitch,
			avoidSpaceSwitch: overlayAvoidsSpaceSwitch
			)
			}

			private func attachSettingsWindow(_ window: NSWindow, to overlayWindow: NSWindow) {
			if window.parent != overlayWindow {
			window.parent?.removeChildWindow(window)
			overlayWindow.addChildWindow(window, ordered: .above)
			}
			}

			private func detachSettingsWindow(_ window: NSWindow) {
			window.parent?.removeChildWindow(window)
			}

			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 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 {
			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) {
			@@ -400,10 +1394,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.
			@@ -417,7 +1425,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(
			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)
			}
			}
			}

			@@ -432,23 +1451,155 @@
			}
			}

			@objc private func openPreferences() {
			// Don't hide overlay — keep it visible for real-time setting preview.
			NSApp.sendAction(Selector(("showSettingsWindow:")), to: nil, from: nil)
			prepareSettingsWindowWhenAvailable(retries: 5)
			/// Keep text-input overlays at the launcher level so Quick Search stays visible in fullscreen Spaces.
			private func observeAppNoteEditing() {
			NotificationCenter.default.addObserver(
			forName: .tagLauncherAppNoteEditingChanged,
			object: nil,
			queue: .main
			) { [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 prepareSettingsWindowWhenAvailable(retries: Int) {
			DispatchQueue.main.asyncAfter(deadline: .now() + 0.03) { [weak self] in
			private func promoteOverlayToForegroundInput() {
			if overlayAvoidsSpaceSwitch {
			refreshLauncherChromeState(activate: false, avoidSpaceSwitch: true)
			guard let overlayWindow else { return }
			overlayWindow.makeKeyAndOrderFront(nil)
			overlayWindow.orderFrontRegardless()
			return
			}
			beginLauncherForegroundOwnership()
			guard let overlayWindow else { return }
			overlayWindow.makeKeyAndOrderFront(nil)
			overlayWindow.orderFrontRegardless()
			}

			private func observeQuickSearch() {
			NotificationCenter.default.addObserver(
			forName: .tagLauncherQuickSearchVisibilityChanged,
			object: nil,
			queue: .main
			) { [weak self] notification in
			guard let self else { return }
			let candidates = NSApp.windows.filter { window in
			window != self.overlayWindow && window.isVisible
			self.isQuickSearchOpen = (notification.userInfo?["active"] as? Bool) ?? false
			if self.isQuickSearchOpen {
			self.promoteOverlayToForegroundInput()
			}
			candidates.forEach { self.prepareSettingsWindow($0) }
			if candidates.isEmpty && retries > 0 {
			self.prepareSettingsWindowWhenAvailable(retries: retries - 1)
			self.updateOverlayLevelForTextInput()
			if self.isQuickSearchOpen {
			self.installQuickSearchExternalMouseMonitor()
			} else {
			self.removeQuickSearchExternalMouseMonitor()
			}
			}

			NotificationCenter.default.addObserver(
			forName: .tagLauncherModalInteractionChanged,
			object: nil,
			queue: .main
			) { [weak self] notification in
			self?.isModalInteractionActive = (notification.userInfo?["active"] as? Bool) ?? false
			}

			NotificationCenter.default.addObserver(
			forName: NSApplication.didResignActiveNotification,
			object: NSApp,
			queue: .main
			) { [weak self] _ in
			self?.handleApplicationDidResignActive()
			}
			}

			private func installQuickSearchExternalMouseMonitor() {
			guard quickSearchExternalMouseMonitor == nil else { return }
			quickSearchExternalMouseMonitor = NSEvent.addGlobalMonitorForEvents(
			matching: [.leftMouseDown, .rightMouseDown, .otherMouseDown]
			) { [weak self] _ in
			DispatchQueue.main.async {
			guard self?.isQuickSearchOpen == true else { return }
			NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
			}
			}
			}

			private func removeQuickSearchExternalMouseMonitor() {
			if let quickSearchExternalMouseMonitor {
			NSEvent.removeMonitor(quickSearchExternalMouseMonitor)
			self.quickSearchExternalMouseMonitor = nil
			}
			}

			private func updateOverlayLevelForTextInput() {
			guard let overlayWindow else { return }
			overlayWindow.level = currentOverlayLevel
			if let settingsWindow, settingsWindow.parent == overlayWindow {
			settingsWindow.level = overlayWindow.level
			}
			}

			/// The overlay buttons live inside SwiftUI; use an app-level notification like edit mode does.
			private func observePreferencesRequests() {
			NotificationCenter.default.addObserver(
			forName: .tagLauncherOpenPreferencesRequested,
			object: nil,
			queue: .main
			) { [weak self] _ in
			self?.openPreferences()
			}
			}

			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) {
			TagDatabase.flushPendingCategorySchemeBackupBatch()
			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)
			overlayWindow.orderFrontRegardless()
			}

			if let settingsWindow {
			prepareSettingsWindow(settingsWindow)
			return
			}

			let settingsSize = NSSize(width: 880, height: 460)
			let window = NSWindow(
			contentRect: NSRect(origin: .zero, size: settingsSize),
			styleMask: [.titled, .closable],
			backing: .buffered,
			defer: false
			)
			window.title = tr("menu.preferences").replacingOccurrences(of: "…", with: "")
			window.contentView = NSHostingView(rootView: PreferencesView())
			window.isReleasedWhenClosed = false
			settingsWindow = window
			prepareSettingsWindow(window)
			}

			@objc private func switchLanguage(_ sender: NSMenuItem) {
			@@ -461,19 +1612,46 @@

			final class DismissibleHostingView<Content: View>: NSHostingView<Content> {
			private let onBackdropTap: () -> Void
			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)
			installWindowServerAnchorLayer()
			observeBackdropDismissSuppressionChanges()
			}

			init(rootView: Content, onBackdropTap: @escaping () -> Void) {
			self.onBackdropTap = onBackdropTap
			super.init(rootView: rootView)
			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)
			@@ -482,7 +1660,19 @@
			return
			}
			if hit == self {
			if quickSearchSuppressesBackdropDismiss {
			NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
			return
			}
			if suppressBackdropDismiss {
			super.mouseDown(with: event)
			return
			}
			onBackdropTap()
			return
			}
			if let floatingButton = findFloatingIconButton(at: event.locationInWindow, in: self) {
			floatingButton.mouseDown(with: event)
			return
			}
			// Recursively search hit subtree for TextFieldContainer or NSTextField.
			@@ -497,12 +1687,25 @@
			tf.mouseDown(with: event)
			return
			}
			// Forward to any other NSControl we find
			if let control = findNSControl(in: hit) {
			control.mouseDown(with: event)
			return
			}
			super.mouseDown(with: event)
			}

			private func observeBackdropDismissSuppressionChanges() {
			modalInteractionObserver = NotificationCenter.default.addObserver(
			forName: .tagLauncherModalInteractionChanged,
			object: nil,
			queue: .main
			) { [weak self] notification in
			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
			}
			}

			private func findTextFieldContainer(in view: NSView) -> TextFieldContainer? {
			@@ -521,313 +1724,18 @@
			return nil
			}

			private func findNSControl(in view: NSView) -> NSControl? {
			if let control = view as? NSControl { return control }
			for sub in view.subviews {
			if let found = findNSControl(in: sub) { return found }
			private func findFloatingIconButton(at windowPoint: NSPoint, in view: NSView) -> FloatingIconButtonView? {
			for subview in view.subviews.reversed() where !subview.isHidden {
			if let found = findFloatingIconButton(at: windowPoint, in: subview) {
			return found
			}
			}
			guard let floatingButton = view as? FloatingIconButtonView else { return nil }
			let localPoint = floatingButton.convert(windowPoint, from: nil)
			if floatingButton.bounds.contains(localPoint) {
			return floatingButton
			}
			return nil
			}
			}

			// MARK: - Preferences View

			struct PreferencesView: View {
			private let settingsWindowWidth: CGFloat = 880
			private let settingsContentWidth: CGFloat = 820
			private let settingsLabelWidth: CGFloat = 160
			private let widePickerWidth: CGFloat = 650
			private let compactPickerWidth: CGFloat = 320

			@AppStorage("tagFontSize") private var tagFontSize: Double = 18
			@AppStorage("iconSize") private var iconSize: Double = 56
			@AppStorage("tagPosition") private var tagPosition = "left"
			@AppStorage("defaultGroupName") private var defaultGroupName = "Other"
			@AppStorage("displayMode") private var displayMode = "flat"
			@AppStorage("hideAppNames") private var hideAppNames = false
			@AppStorage("showDockIcon") private var showDockIcon = false
			@AppStorage("launchAtLogin") private var launchAtLogin = true
			@State private var selectedLanguage = L10n.currentCode
			@State private var languageRefreshID = UUID()
			@State private var isRefreshingLanguage = false
			@State private var allApps: [AppInfo] = []
			@State private var tagColors: [String: Int] = [:]

			private func scanApps() {
			DispatchQueue.global(qos: .userInitiated).async {
			var apps = AppIndexer.scan()
			let store = TagDatabase.load()
			apps = TagEditor.annotate(apps: apps)
			let colors = store.tags.mapValues { $0.color }
			DispatchQueue.main.async {
			allApps = apps
			tagColors = colors
			}
			}
			}

			private func exportTags() {
			let panel = NSSavePanel()
			panel.title = tr("settings.export")
			panel.nameFieldStringValue = "TagLauncher-tags.json"
			panel.allowedContentTypes = [.json]
			panel.begin { response in
			guard response == .OK, let url = panel.url else { return }
			do {
			try TagDatabase.exportTo(url)
			} catch {
			fputs("[TagLauncher] Export failed: \(error)\n", stderr)
			}
			}
			}

			private func importTags() {
			let panel = NSOpenPanel()
			panel.title = tr("settings.import")
			panel.allowedContentTypes = [.json]
			panel.allowsMultipleSelection = false
			panel.begin { response in
			guard response == .OK, let url = panel.url else { return }
			do {
			_ = try TagDatabase.importFrom(url)
			scanApps()
			} catch {
			fputs("[TagLauncher] Import failed: \(error)\n", stderr)
			// Show alert on failure
			let alert = NSAlert()
			alert.messageText = tr("settings.importFailed")
			alert.informativeText = error.localizedDescription
			alert.alertStyle = .warning
			alert.runModal()
			}
			}
			}

			private var appVersion: String {
			Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "?"
			}
			private var buildVersion: String {
			Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "?"
			}

			var body: some View {
			ZStack {
			TabView {
			// Tab 1: Language
			Form {
			Section {
			Picker(tr("settings.languagePicker"), selection: $selectedLanguage) {
			ForEach(L10n.supported, id: \.code) { language in
			Text(language.name).tag(language.code)
			}
			}
			.pickerStyle(.radioGroup)
			} header: {
			Text(tr("settings.language"))
			} footer: {
			Text(tr("settings.languageDesc"))
			}
			}
			.tabItem { Label(tr("settings.language"), systemImage: "globe") }
			.padding()

			// Tab 2: General
			VStack(alignment: .leading, spacing: 0) {
			// Toggle row — centered as a rectangular block
			HStack(spacing: 20) {
			Toggle(tr("settings.launchAtLogin"), isOn: $launchAtLogin)
			.onChange(of: launchAtLogin) { _, enabled in
			if enabled {
			AppDelegate.enableLaunchAtLogin()
			} else {
			AppDelegate.disableLaunchAtLogin()
			}
			}
			Toggle(tr("settings.showInDock"), isOn: $showDockIcon)
			Toggle(tr("settings.hideAppNames"), isOn: $hideAppNames)
			}
			.frame(maxWidth: .infinity, alignment: .center)
			.padding(.bottom, 16)

			Divider()
			.padding(.bottom, 16)

			// Two-column layout: each row label (right-aligned) + controls (left-aligned)
			// All pickers and descriptions share the same left edge
			VStack(spacing: 16) {
			HStack(alignment: .top, spacing: 16) {
			Text(tr("settings.appListStyle"))
			.frame(width: settingsLabelWidth, alignment: .trailing)
			VStack(alignment: .leading, spacing: 4) {
			Picker("", selection: $displayMode) {
			Text(tr("settings.flat")).tag("flat")
			Text(tr("settings.container")).tag("container")
			Text(tr("settings.coloredContainer")).tag("coloredContainer")
			Text(tr("settings.gridContainer")).tag("gridContainer")
			Text(tr("settings.coloredGridContainer")).tag("coloredGridContainer")
			}
			.pickerStyle(.segmented)
			.frame(width: widePickerWidth, alignment: .leading)
			Text(tr("settings.flatDesc"))
			.font(.caption).foregroundStyle(.secondary)
			.fixedSize(horizontal: false, vertical: true)
			}
			}
			HStack(alignment: .top, spacing: 16) {
			Text(tr("settings.tagPosition"))
			.frame(width: settingsLabelWidth, alignment: .trailing)
			VStack(alignment: .leading, spacing: 4) {
			Picker("", selection: $tagPosition) {
			Text(tr("settings.left")).tag("left")
			Text(tr("settings.right")).tag("right")
			Text(tr("settings.top")).tag("top")
			}
			.pickerStyle(.segmented)
			.frame(width: compactPickerWidth, alignment: .leading)
			Text(tr("settings.tagPosDesc"))
			.font(.caption).foregroundStyle(.secondary)
			.fixedSize(horizontal: false, vertical: true)
			}
			}
			HStack(alignment: .top, spacing: 16) {
			Text(tr("settings.tagFontSize"))
			.frame(width: settingsLabelWidth, alignment: .trailing)
			VStack(alignment: .leading, spacing: 4) {
			Picker("", selection: $tagFontSize) {
			ForEach([16.0, 18.0, 20.0, 22.0, 24.0, 26.0], id: \.self) { size in
			Text("\(Int(size))").tag(size)
			}
			}
			.pickerStyle(.segmented)
			.frame(width: compactPickerWidth, alignment: .leading)
			Text(tr("settings.tagFontDesc"))
			.font(.caption).foregroundStyle(.secondary)
			.fixedSize(horizontal: false, vertical: true)
			}
			}
			HStack(alignment: .top, spacing: 16) {
			Text(tr("settings.iconSize"))
			.frame(width: settingsLabelWidth, alignment: .trailing)
			VStack(alignment: .leading, spacing: 4) {
			Picker("", selection: $iconSize) {
			ForEach([40.0, 48.0, 56.0, 64.0, 72.0, 80.0], id: \.self) { size in
			Text("\(Int(size))").tag(size)
			}
			}
			.pickerStyle(.segmented)
			.frame(width: compactPickerWidth, alignment: .leading)
			Text(tr("settings.iconSizeDesc"))
			.font(.caption).foregroundStyle(.secondary)
			.fixedSize(horizontal: false, vertical: true)
			}
			}
			}
			}
			.frame(maxWidth: settingsContentWidth, alignment: .center)
			.padding()
			.tabItem { Label(tr("settings.general"), systemImage: "gearshape") }

			// Tab 3: Tags
			VStack(spacing: 0) {
			TagEditorView(
			tagColors: $tagColors,
			excludedTagNames: ["Mac自带", defaultGroupName],
			onRefresh: { scanApps() }
			)
			}
			.padding(.leading, 16)
			.tabItem { Label(tr("settings.tags"), systemImage: "tag.fill") }
			.onAppear { scanApps() }

			// Tab 4: Data
			Form {
			Section {
			HStack(spacing: 12) {
			Button(tr("settings.export")) { exportTags() }
			.buttonStyle(.bordered)
			Button(tr("settings.import")) { importTags() }
			.buttonStyle(.bordered)
			}
			Text(tr("settings.backupDesc"))
			.font(.caption)
			.foregroundStyle(.secondary)
			} header: {
			Text(tr("settings.backup"))
			}
			}
			.tabItem { Label(tr("settings.data"), systemImage: "externaldrive.fill") }
			.padding()

			// Tab 5: About
			Form {
			Section {
			HStack {
			if let icon = NSImage(named: NSImage.applicationIconName) {
			Image(nsImage: icon)
			.resizable()
			.frame(width: 128, height: 128)
			}
			VStack(alignment: .leading, spacing: 4) {
			Text("TagLauncher")
			.font(.title2)
			.fontWeight(.semibold)
			Text(tr("app.description"))
			.font(.body)
			.foregroundStyle(.secondary)
			Text("\(tr("app.version")) \(appVersion) (\(tr("app.build")) \(buildVersion))")
			.font(.callout)
			.foregroundStyle(.tertiary)

			Divider()
			.padding(.vertical, 4)

			Text("万物之中，希望最美")
			.font(.caption)
			.foregroundStyle(.secondary)
			Text("永桔@2026-18602102518")
			.font(.caption)
			.foregroundStyle(.secondary)
			}
			}
			.padding(.leading, 100)
			}
			}
			.tabItem { Label(tr("settings.about"), systemImage: "info.circle") }
			.padding()
			}
			.id(languageRefreshID)
			.onChange(of: selectedLanguage) { _, code in
			L10n.switchTo(code)
			}
			.onReceive(NotificationCenter.default.publisher(for: .appLanguageDidChange)) { notification in
			if let code = notification.userInfo?["code"] as? String {
			selectedLanguage = code
			}
			showLanguageRefresh()
			}

			if isRefreshingLanguage {
			ZStack {
			Color(nsColor: .windowBackgroundColor)
			.opacity(0.84)
			Image(systemName: "arrow.clockwise")
			.font(.system(size: 30, weight: .regular))
			.symbolRenderingMode(.hierarchical)
			.foregroundStyle(.secondary)
			}
			.transition(.opacity)
			}
			}
			.frame(minWidth: settingsWindowWidth, maxWidth: settingsWindowWidth, minHeight: 420)
			}

			private func showLanguageRefresh() {
			isRefreshingLanguage = true
			languageRefreshID = UUID()
			DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) {
			withAnimation(.easeOut(duration: 0.18)) {
			isRefreshingLanguage = false
			}
			}
			}
			}