Freeze 7.6.0 release candidate and move docs out of repo

Ariver

2026-05-22 8478c55e513bbbb4b1676d1d9207f7feb2509465

 Apptag/ApptagApp.swift

@@ -29,23 +29,53 @@

final class AppDelegate: NSObject, NSApplicationDelegate {
    private static let showDockIconKey = "showDockIcon"
    private static let statusItemAutosaveName = "com.apptag.launcher.statusItem"
    private static let statusItemAutosaveName = AppIdentity.statusItemAutosaveName
    private static let statusItemButtonIdentifier = NSUserInterfaceItemIdentifier("TagLauncherStatusItemButton")
    private static let statusItemAccessibilityLabel = "TagLauncher"
    private static let statusItemAccessibilityLabel = AppIdentity.displayName
    private static let showAppListMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherShowAppListMenuItem")
    private static let showAppListShortcutGlyphs = "⌥⇧␣"
    private static let overlayDefaultLevel = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
    private static let overlayTextInputLevel = NSWindow.Level.modalPanel
    private static let overlayDefaultLevel = NSWindow.Level.normal
    private static let overlayTextInputLevel = NSWindow.Level.normal

    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 isOverlayVisible: Bool {
        overlayWindow?.isVisible == true
    }

    private var isSettingsVisible: Bool {
        settingsWindow?.isVisible == true
    }

    private var requiresForegroundOwnership: Bool {
        isOverlayVisible || isSettingsVisible
    }

    private var currentOverlayLevel: NSWindow.Level {
        if isEditingAppNote || isQuickSearchOpen {
            return Self.overlayTextInputLevel
        }
        return Self.overlayDefaultLevel
    }

    private func overlayLevel(initialQuickSearchSource: String? = nil) -> NSWindow.Level {
        if initialQuickSearchSource != nil {
            return Self.overlayTextInputLevel
        }
        return currentOverlayLevel
    }

    static func refreshChromeSettings() {
        (NSApp.delegate as? AppDelegate)?.syncChromeSettings(force: true)
@@ -61,11 +91,13 @@
        migrateDefaultGroupName()
        TagDatabase.seedDefaultTags()
        syncChromeSettings(force: true)
        registerHotkey()
        observeHotkeyStatusChanges()
        registerConfiguredHotkeys()
        observeOtherWindows()
        observeSettingsClose()
        observeEditMode()
        observeAppNoteEditing()
        observeQuickSearch()
        observePreferencesRequests()
        observeApplicationMenuChanges()
        observeChromeSettings()
@@ -81,7 +113,12 @@
    }

    func applicationWillTerminate(_ notification: Notification) {
        hideOverlay(force: true, discardWindow: true)
        unregisterHotkey(for: .main)
        unregisterHotkey(for: .quickSearch)
        TagDatabase.flushPendingCategorySchemeBackupBatch()
        removeOverlayKeyMonitor()
        removeQuickSearchExternalMouseMonitor()
    }

    /// Ensure defaultGroupName is always the language-neutral key "Other".
@@ -117,13 +154,59 @@
        let dockChanged = lastShowDockIcon != showDock

        if force || dockChanged {
            NSApp.setActivationPolicy(showDock ? .regular : .accessory)
            lastShowDockIcon = showDock
            refreshLauncherChromeState()
        }

        if force {
            setupMenuBar()
        }
    }

    private func beginLauncherForegroundOwnership(activate: Bool = true) {
        if NSApp.activationPolicy() != .regular {
            NSApp.setActivationPolicy(.regular)
        }
        if activate {
            NSApp.activate(ignoringOtherApps: true)
            configureApplicationMenuWhenAvailable(retries: 4)
        }
    }

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

        let desiredPolicy: NSApplication.ActivationPolicy = requiresForegroundOwnership
            ? .regular
            : (showDock ? .regular : .accessory)
        if NSApp.activationPolicy() != desiredPolicy {
            NSApp.setActivationPolicy(desiredPolicy)
        }

        let desiredPresentation: NSApplication.PresentationOptions = isOverlayVisible ? [.hideDock] : []
        if NSApp.presentationOptions != desiredPresentation {
            NSApp.presentationOptions = desiredPresentation
        }

        if activate && requiresForegroundOwnership {
            NSApp.activate(ignoringOtherApps: true)
            configureApplicationMenuWhenAvailable(retries: 4)
        }
    }

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

        guard isOverlayVisible else {
            refreshLauncherChromeState()
            return
        }

        // Once another app takes the menu bar, don't leave the overlay stranded onscreen.
        hideOverlay(force: true)
    }

    /// Keep app chrome in sync when language changes from any entry point.
@@ -139,7 +222,7 @@

    // MARK: - Launch at Login (LaunchAgent, zero permissions)

    private static let launchAgentLabel = "com.apptag.launcher"
    private static let launchAgentLabel = AppIdentity.launchAgentLabel
    static var supportsLaunchAtLogin: Bool {
        ProcessInfo.processInfo.environment["APP_SANDBOX_CONTAINER_ID"] == nil
    }
@@ -333,7 +416,10 @@
    }

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

    private func observeApplicationMenuChanges() {
@@ -496,13 +582,13 @@

    @objc private func toggleOverlay() {
        if overlayWindow?.isVisible == true {
            hideOverlay()
            hideOverlay(force: true)
        } else {
            showOverlay()
        }
    }

    private func showOverlay() {
    private func showOverlay(initialQuickSearchSource: String? = nil) {
        // Use the screen under the mouse cursor — works in fullscreen spaces
        let mousePoint = NSEvent.mouseLocation
        guard let screen = NSScreen.screens.first(where: {
@@ -510,32 +596,113 @@
        }) ?? NSScreen.main ?? NSScreen.screens.first else { return }

        let window: NSWindow
        let createdWindow: Bool
        if let existingWindow = overlayWindow {
            window = existingWindow
            createdWindow = false
        } else {
            window = makeOverlayWindow(on: screen)
            window = makeOverlayWindow(on: screen, initialQuickSearchSource: initialQuickSearchSource)
            overlayWindow = window
            createdWindow = true
        }

        window.setFrame(screen.frame, display: true)
        window.level = isEditingAppNote ? Self.overlayTextInputLevel : Self.overlayDefaultLevel

        installOverlayKeyMonitor()
        beginLauncherForegroundOwnership()

        let targetFrame = screen.frame
        let targetLevel = overlayLevel(initialQuickSearchSource: initialQuickSearchSource)
        let canReuseVisibleWindow = !createdWindow
            && window.isVisible
            && NSEqualRects(window.frame, targetFrame)
            && window.level == targetLevel

        if canReuseVisibleWindow {
            if !window.isKeyWindow {
                window.makeKeyAndOrderFront(nil)
            }
            refreshLauncherChromeState(activate: true)
            if let initialQuickSearchSource {
                NotificationCenter.default.post(
                    name: .tagLauncherQuickSearchRequested,
                    object: nil,
                    userInfo: ["source": initialQuickSearchSource]
                )
            }
            return
        }

        window.setFrame(targetFrame, display: true)
        window.level = targetLevel

        if let initialQuickSearchSource, !createdWindow {
            NotificationCenter.default.post(
                name: .tagLauncherQuickSearchRequested,
                object: nil,
                userInfo: ["source": initialQuickSearchSource]
            )
        }

        window.makeKeyAndOrderFront(nil)
        window.orderFrontRegardless()
        refreshLauncherChromeState(activate: true)
        NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
    }

    private func installOverlayKeyMonitor() {
        guard overlayKeyMonitor == nil else { return }
        overlayKeyMonitor = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
            guard let self else { return event }
            if event.keyCode == 53 { // Escape
                self?.hideOverlay()
                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]
                )
                return nil
            }
            return event
        }
    }

    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 }

        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() {
@@ -545,10 +712,10 @@
        }
    }

    private func makeOverlayWindow(on screen: NSScreen) -> NSWindow {
    private func makeOverlayWindow(on screen: NSScreen, initialQuickSearchSource: String? = nil) -> NSWindow {
        let panel = OverlayPanel(
            contentRect: screen.frame,
            styleMask: [.borderless, .fullSizeContentView, .nonactivatingPanel],
            styleMask: [.borderless, .fullSizeContentView],
            backing: .buffered,
            defer: false
        )
@@ -568,9 +735,12 @@
        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()
            }
@@ -578,7 +748,7 @@
        return panel
    }

    private func hideOverlay(force: Bool = false) {
    private func hideOverlay(force: Bool = false, discardWindow: Bool = false) {
        guard force || !isInEditMode else { return }
        TagDatabase.flushPendingCategorySchemeBackupBatch()
        if let settingsWindow, settingsWindow.parent == overlayWindow {
@@ -586,53 +756,92 @@
        }
        overlayWindow?.orderOut(nil)
        removeOverlayKeyMonitor()
        if force {
        removeQuickSearchExternalMouseMonitor()
        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
            },
@@ -641,6 +850,40 @@
            selfPtr,
            nil
        )
    }

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

    private func showQuickSearchFromGlobalHotkey() {
        guard overlayWindow?.isVisible != true else { 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
@@ -699,6 +942,7 @@
        window.makeKeyAndOrderFront(nil)
        window.orderFrontRegardless()
        settingsWindow = window
        refreshLauncherChromeState(activate: true)
    }

    private func attachSettingsWindow(_ window: NSWindow, to overlayWindow: NSWindow) {
@@ -752,6 +996,7 @@
            else { return }
            self.detachSettingsWindow(closingWindow)
            self.settingsWindow = nil
            self.refreshLauncherChromeState()
        }
    }

@@ -766,7 +1011,7 @@
        }
    }

    /// Lower the overlay while editing app notes so IME candidate windows are not hidden behind it.
    /// Lower the overlay while text input is active so IME and cursor services are not hidden behind it.
    private func observeAppNoteEditing() {
        NotificationCenter.default.addObserver(
            forName: .tagLauncherAppNoteEditingChanged,
@@ -779,9 +1024,61 @@
        }
    }

    private func observeQuickSearch() {
        NotificationCenter.default.addObserver(
            forName: .tagLauncherQuickSearchVisibilityChanged,
            object: nil,
            queue: .main
        ) { [weak self] notification in
            guard let self else { return }
            self.isQuickSearchOpen = (notification.userInfo?["active"] as? Bool) ?? false
            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 = isEditingAppNote ? Self.overlayTextInputLevel : Self.overlayDefaultLevel
        overlayWindow.level = currentOverlayLevel
        if let settingsWindow, settingsWindow.parent == overlayWindow {
            settingsWindow.level = overlayWindow.level
        }
@@ -800,12 +1097,12 @@

    @objc private func openPreferences() {
        TagDatabase.flushPendingCategorySchemeBackupBatch()
        beginLauncherForegroundOwnership()
        // Don't hide overlay — keep it visible for real-time setting preview.
        if let overlayWindow, overlayWindow.isVisible {
            overlayWindow.makeKeyAndOrderFront(nil)
            overlayWindow.orderFrontRegardless()
        }
        NSApp.activate(ignoringOtherApps: true)

        if let settingsWindow {
            prepareSettingsWindow(settingsWindow)
@@ -836,15 +1133,25 @@

final class DismissibleHostingView<Content: View>: NSHostingView<Content> {
    private let onBackdropTap: () -> Void
    private var suppressBackdropDismiss = false
    private var modalInteractionObserver: NSObjectProtocol?

    @MainActor required init(rootView: Content) {
        self.onBackdropTap = {}
        super.init(rootView: rootView)
        observeModalInteractionChanges()
    }

    init(rootView: Content, onBackdropTap: @escaping () -> Void) {
        self.onBackdropTap = onBackdropTap
        super.init(rootView: rootView)
        observeModalInteractionChanges()
    }

    deinit {
        if let modalInteractionObserver {
            NotificationCenter.default.removeObserver(modalInteractionObserver)
        }
    }

    @available(*, unavailable)
@@ -857,6 +1164,10 @@
            return
        }
        if hit == self {
            if suppressBackdropDismiss {
                super.mouseDown(with: event)
                return
            }
            onBackdropTap()
            return
        }
@@ -879,6 +1190,16 @@
        super.mouseDown(with: event)
    }

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

    private func findTextFieldContainer(in view: NSView) -> TextFieldContainer? {
        if let container = view as? TextFieldContainer { return container }
        for sub in view.subviews {