Skip to content

Fastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows, iOS testflight! Android, Linux waitlist open! A local Wispr Flow alternative. Follow https://x.com/fluidvoiceapp for more

293 KB
Raw Blame
//
//  ContentView.swift
//  fluid
//
//  Created by Barathwaj Anandan on 7/30/25.
//

import AppKit
import AVFoundation
import Combine
import CoreAudio
import CoreGraphics
import Security
import SwiftUI

// MARK: - AI Processing Errors

nonisolated enum AIProcessingError: LocalizedError {
    case noVerifiedProvider
    case missingAPIKey(provider: String)
    case missingModel(provider: String)
    case emptyResponse
    case dictationExceedsAIContextWindow

    var errorDescription: String? {
        switch self {
        case .noVerifiedProvider:
            return "No verified AI provider selected"
        case let .missingAPIKey(provider):
            return "API key not set for \(provider)"
        case let .missingModel(provider):
            return "No model selected for \(provider)"
        case .emptyResponse:
            return "AI returned an empty response"
        case .dictationExceedsAIContextWindow:
            return "Dictation exceeded the AI context window"
        }
    }

    /// Configuration errors the user can fix in AI Settings.
    var isConfigurationError: Bool {
        switch self {
        case .noVerifiedProvider, .missingAPIKey, .missingModel:
            return true
        case .emptyResponse, .dictationExceedsAIContextWindow:
            return false
        }
    }
}

nonisolated enum DictationAIFailurePresentationPolicy {
    static func shouldPresent(shouldPersistOutputs: Bool, fallbackReason: String?) -> Bool {
        shouldPersistOutputs && fallbackReason != nil
    }

    static func notificationMessage(for error: Error) -> String {
        if let aiError = error as? AIProcessingError, aiError.isConfigurationError {
            return "\(aiError.localizedDescription). Open AI Settings to configure a provider."
        }
        return error.localizedDescription
    }
}

nonisolated enum DictationStreamingFallbackPolicy {
    static func shouldRetryWithoutStreaming(after error: Error) -> Bool {
        if error is CancellationError || error is URLError {
            return false
        }
        guard let llmError = error as? LLMError else { return true }
        switch llmError {
        case .networkError, .timeout, .invalidURL, .encodingError, .invalidRequest:
            return false
        case .invalidResponse, .httpError:
            return true
        }
    }
}

final nonisolated class DictationAIStreamPreviewBuffer: @unchecked Sendable {
    typealias Publisher = @MainActor @Sendable (String) -> Void

    private let lock = NSLock()
    private let minimumUpdateInterval: TimeInterval
    private let publisher: Publisher
    private var bufferedText = ""
    private var lastPublishedText = ""
    private var nextEligibleUIUpdate: TimeInterval
    private var isUIUpdateScheduled = false

    init(
        minimumUpdateInterval: TimeInterval = 0.033,
        initialUpdateDelay: TimeInterval = 0.5,
        publisher: @escaping Publisher = { text in
            NotchOverlayManager.shared.updateTranscriptionText(text)
        }
    ) {
        self.minimumUpdateInterval = minimumUpdateInterval
        self.nextEligibleUIUpdate = ProcessInfo.processInfo.systemUptime + initialUpdateDelay
        self.publisher = publisher
    }

    func append(_ chunk: String) {
        guard !chunk.isEmpty else { return }
        let shouldSchedule = self.lock.withLock {
            self.bufferedText += chunk
            guard !self.isUIUpdateScheduled,
                  ProcessInfo.processInfo.systemUptime >= self.nextEligibleUIUpdate
            else {
                return false
            }
            self.isUIUpdateScheduled = true
            return true
        }
        guard shouldSchedule else { return }

        Task { @MainActor [weak self] in
            self?.publishScheduledUpdate()
        }
    }

    @MainActor
    func flush() {
        guard let text = self.takeTextForPublishing(requiresScheduledUpdate: false) else { return }
        self.publisher(text)
    }

    @MainActor
    private func publishScheduledUpdate() {
        guard let text = self.takeTextForPublishing(requiresScheduledUpdate: true) else { return }
        self.publisher(text)
    }

    private func takeTextForPublishing(requiresScheduledUpdate: Bool) -> String? {
        self.lock.withLock {
            if requiresScheduledUpdate, !self.isUIUpdateScheduled {
                return nil
            }
            self.isUIUpdateScheduled = false
            self.nextEligibleUIUpdate = ProcessInfo.processInfo.systemUptime + self.minimumUpdateInterval
            guard self.bufferedText != self.lastPublishedText else { return nil }
            self.lastPublishedText = self.bufferedText
            return self.bufferedText
        }
    }
}

enum PrimaryDictationShortcutEdit: Hashable {
    case add
    case replace(Int)

    var replacementIndex: Int? {
        if case let .replace(index) = self { return index }
        return nil
    }
}

enum ShortcutRecordingTarget: Hashable {
    case primaryDictation(PrimaryDictationShortcutEdit)
    case secondaryDictation
    case command
    case edit
    case cancel
    case pasteLast
    case meeting
    case dictationPrompt(String)
    case newPrompt

    var title: String {
        switch self {
        case .primaryDictation:
            return "Primary Dictation Shortcut"
        case .secondaryDictation:
            return "Secondary Dictation Shortcut"
        case .command:
            return "Command Mode"
        case .edit:
            return "Edit Mode"
        case .cancel:
            return "Cancel Recording"
        case .meeting:
            return "Start / Stop Meeting"
        case .pasteLast:
            return "Paste Last Transcription"
        case .dictationPrompt:
            return "Prompt Shortcut"
        case .newPrompt:
            return "New Prompt Shortcut"
        }
    }

    var enablesFeatureOnAssignment: Bool {
        switch self {
        case .secondaryDictation, .command, .edit, .pasteLast:
            return true
        case .primaryDictation, .cancel, .meeting, .dictationPrompt, .newPrompt:
            return false
        }
    }

    var promptConfigurationKey: String? {
        if case let .dictationPrompt(key) = self { return key }
        return nil
    }

    var allowsMouseShortcut: Bool {
        switch self {
        case .primaryDictation, .pasteLast:
            return true
        case .secondaryDictation, .command, .edit, .cancel, .meeting, .dictationPrompt, .newPrompt:
            return false
        }
    }

    var isPrimaryDictation: Bool {
        if case .primaryDictation = self { return true }
        return false
    }

    var primaryDictationReplacementIndex: Int? {
        if case let .primaryDictation(edit) = self {
            return edit.replacementIndex
        }
        return nil
    }
}

// MARK: - Minimal FluidAudio ASR Service (finalized text, macOS)

// MARK: - Saved Provider Model

// Removed deprecated inline service and model

// NOTE: Streaming and AI response parsing is now handled by LLMClient

// swiftlint:disable type_body_length file_length
struct ContentView: View {
    private static let aiProcessingStatusDelayNanoseconds: UInt64 = 500_000_000

    private enum ActiveRecordingMode: String {
        case none
        case dictate
        case promptMode
        case edit
        case command
    }

    enum DictationOutputRoute: String {
        case normal
        case onboardingSandbox
        case historyOnly

        var savesHistory: Bool { self != .onboardingSandbox }
        var deliversText: Bool { self == .normal }
        var publishesEditorResult: Bool { self != .historyOnly }
    }

    @EnvironmentObject private var appServices: AppServices
    @StateObject private var meetingHistorySnapshot = MeetingHistorySnapshot()
    @StateObject private var mouseTracker = MousePositionTracker()
    @StateObject private var commandModeService = CommandModeService()
    @StateObject private var rewriteModeService = RewriteModeService()
    @EnvironmentObject private var menuBarManager: MenuBarManager
    @ObservedObject private var settings = SettingsStore.shared

    /// Computed properties to access shared services from AppServices container
    /// This maintains backward compatibility with the existing code while
    /// removing the duplicate service instances that cause startup crashes.
    private var asr: ASRService {
        #if DEBUG
        if let fixture = self.dictationModeSwitchASRForTesting { return fixture }
        #endif
        return self.appServices.asr
    }

    private var audioObserver: AudioHardwareObserver {
        self.appServices.audioObserver
    }

    @Environment(\.theme) private var theme
    @Environment(\.accessibilityReduceMotion) private var accessibilityReduceMotion
    @State private var hotkeyManager: GlobalHotkeyManager? = nil
    @State private var hotkeyManagerInitialized: Bool = false
    @State private var processingDictationLifecycleID: UInt64?
    @State private var pendingVoiceCommandLifecycleID: UInt64?
    @State private var cancelledOutputLifecycleID: UInt64?
    @State private var isSavingCancelledRecording = false

    @State private var appear = false
    @State private var accessibilityEnabled = false
    @State private var primaryDictationShortcuts: [HotkeyShortcut] = SettingsStore.shared.primaryDictationShortcuts
    @State private var promptModeHotkeyShortcut: HotkeyShortcut = SettingsStore.shared.promptModeHotkeyShortcut
    @State private var commandModeHotkeyShortcut: HotkeyShortcut? = SettingsStore.shared.commandModeHotkeyShortcut
    @State private var rewriteModeHotkeyShortcut: HotkeyShortcut = SettingsStore.shared.rewriteModeHotkeyShortcut
    @State private var cancelRecordingHotkeyShortcut: HotkeyShortcut? = SettingsStore.shared.cancelRecordingHotkeyShortcut
    @State private var pasteLastTranscriptionHotkeyShortcut: HotkeyShortcut? = SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut
    @State private var isPasteLastTranscriptionShortcutEnabled: Bool = SettingsStore.shared.pasteLastTranscriptionShortcutEnabled
    @State private var isPromptModeShortcutEnabled: Bool = SettingsStore.shared.promptModeShortcutEnabled
    @State private var isCommandModeShortcutEnabled: Bool = SettingsStore.shared.commandModeShortcutEnabled
    @State private var isRewriteModeShortcutEnabled: Bool = SettingsStore.shared.rewriteModeShortcutEnabled
    @State private var isRecordingForRewrite: Bool = false // Track if current recording is for rewrite mode
    @State private var isRecordingForCommand: Bool = false // Track if current recording is for command mode
    @State private var promptModeOverrideText: String? // System prompt text to use when in prompt mode
    @State private var activeDictationShortcutSlot: SettingsStore.DictationShortcutSlot? = nil
    @State private var activeRecordingMode: ActiveRecordingMode = .none
    @State private var pendingAIReprocessText: String? = nil
    @State private var activeShortcutRecordingTarget: ShortcutRecordingTarget? = nil
    @State private var currentRecordingModifierKeyCodes: Set<UInt16> = []
    @State private var pendingModifierKeyCodes: Set<UInt16> = []
    @State private var pendingModifierFlags: NSEvent.ModifierFlags = []
    @State private var pendingModifierKeyCode: UInt16?
    @State private var pendingModifierOnly = false
    @State private var shortcutRecordingMessage: String? = nil
    @State private var shortcutCaptureMonitor: Any?
    @FocusState private var isTranscriptionFocused: Bool

    @State private var selectedSidebarItem: SidebarItem?
    @State private var previousSidebarItem: SidebarItem? = nil // Track previous for mode transitions
    @State private var settingsNavigation = SettingsNavigationState()
    @State private var settingsSearchQuery = ""
    @State private var settingsSearchScrollRequest = 0
    /// A settings row chosen from the sidebar search, highlighted like a settings
    /// search match until the user searches or leaves settings.
    @State private var settingsRevealTarget: SettingsSearchTarget?
    @ObservedObject private var appSearch = AppSearchService.shared
    @State private var appSearchCursor: AppSearchHit.Target?
    /// A dictionary, vocabulary, punctuation or prompt row chosen from the sidebar
    /// search. The screen it belongs to opens that row and clears this.
    @State private var appSearchRevealTarget: AppSearchHit.Target?
    @State private var appSearchExpanded: Set<AppSearchKind> = []

    @State private var isHelpEntryHovered = false
    @State private var isSettingsEntryHovered = false
    @State private var isSettingsBackHovered = false
    @FocusState private var isSettingsSearchFocused: Bool
    @State private var playgroundUsed: Bool = SettingsStore.shared.playgroundUsed
    @State private var showsFluidIntelligenceDemo = false
    @State private var showsReleaseHighlights = false
    @State private var recordingAppInfo: (name: String, bundleId: String, windowTitle: String)? = nil
    @State private var recordingPrecedingText: String = ""
    @State private var dictationContextCapture: DictationContextCapture?
    @State private var recordingFocusTarget: TypingService.CapturedFocusTarget? = nil

    // Command Mode State
    // @State private var showCommandMode: Bool = false

    // Audio Settings Tab State
    @State private var visualizerNoiseThreshold: Double = SettingsStore.shared.visualizerNoiseThreshold
    @State private var inputDevices: [AudioDevice.Device] = []
    @State private var outputDevices: [AudioDevice.Device] = []
    // Populated by gated audio initialization; querying Core Audio while SwiftUI
    // constructs this view can race AttributeGraph metadata processing.
    @State private var selectedInputUID: String = ""
    @State private var selectedOutputUID: String = SettingsStore.shared.preferredOutputDeviceUID ?? ""

    // AI Prompts Tab State
    @State private var aiInputText: String = ""
    @State private var aiOutputText: String = ""
    @State private var isCallingAI: Bool = false
    @State private var openAIBaseURL: String = ""

    @State private var enableDebugLogs: Bool = SettingsStore.shared.enableDebugLogs
    @State private var hotkeyMode: HotkeyActivationMode = SettingsStore.shared.hotkeyMode
    @State private var enableStreamingPreview: Bool = SettingsStore.shared.enableStreamingPreview
    @State private var copyToClipboard: Bool = SettingsStore.shared.copyTranscriptionToClipboard

    // Preferences Tab State
    @State private var launchAtStartup: Bool = SettingsStore.shared.launchAtStartup
    @State private var showInDock: Bool = SettingsStore.shared.showInDock
    @State private var showRestartPrompt: Bool = false
    @State private var didOpenAccessibilityPane: Bool = false
    private let accessibilityRestartFlagKey = "FluidVoice_AccessibilityRestartPending"
    private let hasAutoRestartedForAccessibilityKey = "FluidVoice_HasAutoRestartedForAccessibility"
    @State private var accessibilityPollingTask: Task<Void, Never>?
    @State private var accessibilityGuidePanel: NSPanel?
    @State private var accessibilityGuideMonitorTask: Task<Void, Never>?
    @State private var accessibilityGuideRequestID: UUID?
    @State private var prewarmDictationTask: Task<Void, Never>?
    @State private var overlayLifecycleID: UInt64 = 0
    @State private var spokenSendAutoStopTask: Task<Void, Never>?
    @State private var spokenSendAutoStopTriggered = false
    @State private var spokenSendArming = SpokenSendArmingState()
    @State private var spokenSendCountdownStartedAt: TimeInterval?
    @State private var spokenSendLastVoiceActivityAt: TimeInterval = 0
    @State private var spokenSendVoiceActivityCancellable: AnyCancellable?

    private var isRecordingAnyShortcutCapture: Bool {
        self.activeShortcutRecordingTarget != nil
    }

    // MARK: - Voice Recognition Model Management

    // Models scoped by provider (name -> [models])
    @State private var availableModelsByProvider: [String: [String]] = [:]
    @State private var selectedModelByProvider: [String: String] = [:]
    @State private var availableModels: [String] = [] // derived from currentProvider
    @State private var selectedModel: String = "" // derived from currentProvider
    @State private var showingAddModel: Bool = false
    @State private var newModelName: String = ""

    // Model Reasoning Configuration
    @State private var showingReasoningConfig: Bool = false
    @State private var editingReasoningParamName: String = "reasoning_effort"
    @State private var editingReasoningParamValue: String = "low"
    @State private var editingReasoningEnabled: Bool = false

    // MARK: - Provider Management

    @State private var providerAPIKeys: [String: String] = [:] // [providerKey: apiKey]
    @State private var currentProvider: String = "" // canonical key: "openai" | "groq" | "custom:<id>"

    @State private var savedProviders: [SettingsStore.SavedProvider] = []
    @State private var selectedProviderID: String = SettingsStore.shared.selectedProviderID
    @State private var columnVisibility: NavigationSplitViewVisibility = .all
    @State private var toolbarTrailingInset: CGFloat = 80

    #if DEBUG
    private var dictationModeSwitchASRForTesting: ASRService?
    private var dictationModeSwitchOnReadyForTesting: ((ContentView) -> Void)?

    /// Install real SwiftUI state while avoiding the app page's startup/hardware observers.
    static func dictationModeSwitchFixture(
        asr: ASRService,
        hasActiveMode: Bool = true,
        onReady: @escaping (ContentView) -> Void
    ) -> ContentView {
        let commandFixture = CommandModeService()
        var view = ContentView()
        view._commandModeService = StateObject(wrappedValue: commandFixture)
        view.dictationModeSwitchASRForTesting = asr
        view.dictationModeSwitchOnReadyForTesting = onReady
        view._activeRecordingMode = State(initialValue: hasActiveMode ? .edit : .none)
        view._isRecordingForRewrite = State(initialValue: hasActiveMode)
        return view
    }

    func beginDictationModeSwitchForTesting(selection: SettingsStore.DictationPromptSelection? = nil) -> Task<Void, Never>? {
        if let selection { return self.beginDictationRecording(for: selection, mode: .promptMode) }
        return self.beginDictationRecording(for: .primary, mode: .dictate)
    }

    func beginCommandModeSwitchForTesting() async {
        await self.beginCommandRecording()
    }

    func beginRewriteModeSwitchForTesting() async {
        await self.beginRewriteRecording()
    }

    func blockDictationModeSwitchForTesting(savingCancellation: Bool = false, processing: Bool = false) {
        self.isSavingCancelledRecording = savingCancellation
        self.processingDictationLifecycleID = processing ? self.overlayLifecycleID : nil
    }

    var dictationModeSwitchStateForTesting: (mode: String, slot: SettingsStore.DictationShortcutSlot?, generation: UInt64) {
        (self.activeRecordingMode.rawValue, self.activeDictationShortcutSlot, self.overlayLifecycleID)
    }
    #endif

    @ViewBuilder
    var body: some View {
        #if DEBUG
        if let onReady = self.dictationModeSwitchOnReadyForTesting {
            Color.clear.onAppear { onReady(self) }
        } else {
            self.appBody
        }
        #else
        self.appBody
        #endif
    }

    private var appBody: some View {
        let layout = AnyView(
            Group {
                if self.settings.shouldShowOnboarding {
                    self.onboardingOnlyView
                } else {
                    NavigationSplitView(columnVisibility: self.$columnVisibility) {
                        self.sidebarContent
                            .frame(minWidth: 264, maxWidth: 360)
                            .navigationSplitViewColumnWidth(min: 264, ideal: 300, max: 360)
                            .toolbar(removing: .sidebarToggle)
                    } detail: {
                        self.detailView
                            .onGeometryChange(for: CGFloat.self) { geometry in
                                (geometry.size.width * 0.1).rounded()
                            } action: { inset in
                                self.toolbarTrailingInset = inset
                            }
                    }
                    .navigationSplitViewStyle(.balanced)
                }
            }
        )

        let tracked = layout.withMouseTracking(self.mouseTracker)
        let env = tracked.environmentObject(self.mouseTracker)
        let nav = env.onChange(of: self.menuBarManager.requestedNavigationDestination) { _, destination in
            self.handleMenuBarNavigation(destination)
        }
        let sized = nav.fluidWindowSizing(self.windowSizing)

        let observed = self.applyShortcutStateChanges(to: sized)
        let withToolbar = self.applyMainWindowToolbar(to: observed)

        return withToolbar
            .environment(\.fluidToolbarTrailingInset, self.toolbarTrailingInset)
            .onReceive(NotificationCenter.default.publisher(for: NSApplication.didBecomeActiveNotification)) { _ in
                self.refreshAccessibilityPermissionState()
            }
            .onReceive(NotificationCenter.default.publisher(for: .openCustomDictionaryFromVoiceEngine)) { _ in
                self.navigateToApp(.customDictionary)
            }
            .onReceive(NotificationCenter.default.publisher(for: .openScreenContextSettings)) { _ in
                self.openSettings(.experimental)
            }
            .onReceive(NotificationCenter.default.publisher(for: .fluidMeetEnabledChanged)) { _ in
                if self.settings.fluidMeetEnabled, self.appServices.isUIReady {
                    self.menuBarManager.configure(meetingCoordinator: self.appServices.meetingSessionCoordinator)
                } else if !self.settings.fluidMeetEnabled, self.selectedSidebarItem == .meetingTranscription {
                    self.selectedSidebarItem = .welcome
                }
            }
            .onReceive(NotificationCenter.default.publisher(for: .appNavigationRequested)) { _ in
                self.handlePendingAppNavigation()
            }
            .onReceive(NotificationCenter.default.publisher(for: .dictationPromptShortcutsChanged)) { _ in
                self.hotkeyManager?.updatePromptShortcutAssignments(SettingsStore.shared.dictationPromptShortcutAssignments())
            }
            // Local UI diagnostics, same defaults gate as GlobalHotkeyManager+DebugTrigger.
            .onReceive(DistributedNotificationCenter.default().publisher(for: Notification.Name("com.FluidApp.debug.toggleSidebar"))) { _ in
                guard UserDefaults.standard.bool(forKey: "FluidDebugRemoteToggleEnabled") else { return }
                self.toggleSidebar()
            }
            .onReceive(DistributedNotificationCenter.default().publisher(for: Notification.Name("com.FluidApp.debug.openSettings"))) { _ in
                guard UserDefaults.standard.bool(forKey: "FluidDebugRemoteToggleEnabled") else { return }
                self.menuBarManager.openPreferencesFromUI()
            }
            .onReceive(NotificationCenter.default.publisher(for: .settingsBackupDidRestore)) { _ in
                self.reloadSettingsStateAfterBackupRestore()
            }
            .onReceive(self.asr.$partialTranscription) { text in
                self.handleSpokenSendPartialTranscription(text)
            }
            .overlay(alignment: .center) {}
            .modifier(ReleaseHighlightsPresenter(
                requested: self.$showsReleaseHighlights,
                isEligible: !self.settings.shouldShowOnboarding && !self.showsFluidIntelligenceDemo &&
                    !self.asr.isRunningOrStarting && self.asr.activeExclusiveActivity == nil &&
                    !self.asr.showError && !self.showRestartPrompt,
                onExplore: self.navigateToApp
            ))
            .sheet(isPresented: self.$showsFluidIntelligenceDemo) {
                FluidIntelligenceDemoView(
                    asr: self.asr,
                    onStart: { _ = self.startRecording() },
                    onStop: { await self.stopAndProcessTranscription() },
                    onCancel: { _ = self.handleCancelShortcut() },
                    onSetup: {
                        self.showsFluidIntelligenceDemo = false
                        self.navigateToApp(.aiEnhancements)
                    },
                    runExample: { text, model in
                        try await self.processTextWithAI(text, overrideProviderID: PrivateAIProviderFeature.shared.providerID, overrideModel: model, dictationSlot: .primary)
                    }
                )
            }
            .alert(
                self.asr.errorTitle,
                isPresented: Binding(
                    get: { self.asr.showError },
                    set: { self.asr.showError = $0 }
                )
            ) {
                Button("OK", role: .cancel) {}
            } message: {
                Text(self.asr.errorMessage)
            }
            .onChange(of: self.audioObserver.changeTick) { _, _ in
                // Hardware change detected → refresh device lists
                self.refreshDevices()

                if let sysOut = AudioDevice.getDefaultOutputDevice()?.uid {
                    self.selectedOutputUID = sysOut
                }
            }
            .onChange(of: self.audioObserver.inputAvailabilityTick) { _, _ in
                self.refreshInputDevices()
            }
            .onChange(of: self.settings.dictationScreenContextEnabled) { _, enabled in
                if !enabled { self.cancelDictationContextCapture() }
            }
            .onChange(of: self.settings.editModeScreenContextRevision) { _, _ in
                self.rewriteModeService.cancelOutdatedWindowCapture()
            }
            .onDisappear {
                Task { await self.asr.stopWithoutTranscription() }
                self.cancelPrewarmDictationIfNeeded()
                self.cancelDictationContextCapture()
                // Note: Overlay lifecycle is now managed by MenuBarManager
                // Note: NotchContentState handlers capture self (a struct value copy) and are
                // intentionally kept alive so the overlay remains fully functional when the
                // settings window is closed. No retain cycle risk since ContentView is a value type.

                // Stop accessibility polling
                self.finishAccessibilityPermissionFlow()
                self.removeShortcutCaptureMonitor()
            }
            .onChange(of: self.primaryDictationShortcuts) { _, newValue in
                SettingsStore.shared.primaryDictationShortcuts = newValue
                let storedShortcuts = SettingsStore.shared.primaryDictationShortcuts
                if storedShortcuts != newValue {
                    self.primaryDictationShortcuts = storedShortcuts
                    return
                }

                let display = storedShortcuts.map(\.displayString).joined(separator: ", ")
                DebugLogger.shared.debug("Primary dictation shortcuts changed to \(display)", source: "ContentView")
                self.hotkeyManager?.updatePrimaryShortcuts(storedShortcuts)

                // Update initialization status after shortcut change
                DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
                    self.hotkeyManagerInitialized = self.hotkeyManager?.validateEventTapHealth() ?? false
                    DebugLogger.shared.debug(
                        "Hotkey manager initialized: \(self.hotkeyManagerInitialized)",
                        source: "ContentView"
                    )
                }
            }
            .onChange(of: self.selectedSidebarItem) { _, newValue in
                self.handleModeTransition(from: self.previousSidebarItem, to: newValue)
                self.previousSidebarItem = newValue
            }
    }

    private func applyShortcutStateChanges<Content: View>(to view: Content) -> some View {
        view
            .onAppear {
                self.handleContentAppear()
            }
            .onChange(of: self.accessibilityEnabled) { _, enabled in
                if enabled {
                    self.finishAccessibilityPermissionFlow()
                }

                if enabled && self.hotkeyManager != nil && !self.hotkeyManagerInitialized {
                    DebugLogger.shared.debug("Accessibility enabled, reinitializing hotkey manager", source: "ContentView")
                    self.hotkeyManager?.reinitialize()
                }
            }
            .onChange(of: self.selectedModel) { _, newValue in
                if newValue != "__ADD_MODEL__" {
                    self.selectedModelByProvider[self.currentProvider] = newValue
                    SettingsStore.shared.selectedModelByProvider = self.selectedModelByProvider
                }
            }
            .onChange(of: self.selectedProviderID) { _, newValue in
                SettingsStore.shared.selectedProviderID = newValue
            }
            .onChange(of: self.activeShortcutRecordingTarget) { _, _ in
                self.hotkeyManager?.resetModifierOnlyShortcutTracking()
            }
            .onChange(of: self.commandModeHotkeyShortcut) { _, newValue in
                SettingsStore.shared.commandModeHotkeyShortcut = newValue
                self.hotkeyManager?.updateCommandModeShortcut(newValue)
            }
            .onChange(of: self.isPromptModeShortcutEnabled) { newValue in
                self.handlePromptShortcutEnabledChange(newValue)
            }
            .onChange(of: self.isCommandModeShortcutEnabled) { newValue in
                self.handleCommandShortcutEnabledChange(newValue)
            }
            .onChange(of: self.isRewriteModeShortcutEnabled) { newValue in
                self.handleRewriteShortcutEnabledChange(newValue)
            }
            .onChange(of: self.cancelRecordingHotkeyShortcut) { _, newValue in
                SettingsStore.shared.cancelRecordingHotkeyShortcut = newValue
            }
            .onChange(of: self.pasteLastTranscriptionHotkeyShortcut) { _, newValue in
                SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut = newValue
                self.hotkeyManager?.refreshMouseShortcutTapIfNeeded()
            }
            .onChange(of: self.isPasteLastTranscriptionShortcutEnabled) { newValue in
                self.handlePasteLastTranscriptionShortcutEnabledChange(newValue)
            }
    }

    private func handlePasteLastTranscriptionShortcutEnabledChange(_ isEnabled: Bool) {
        SettingsStore.shared.pasteLastTranscriptionShortcutEnabled = isEnabled
        self.hotkeyManager?.refreshMouseShortcutTapIfNeeded()
        if !isEnabled, self.activeShortcutRecordingTarget == .pasteLast {
            self.clearShortcutRecordingMode()
        }
    }

    private func handlePromptShortcutEnabledChange(_ isEnabled: Bool) {
        SettingsStore.shared.promptModeShortcutEnabled = isEnabled
        self.hotkeyManager?.updatePromptModeShortcutEnabled(isEnabled)

        if !isEnabled {
            if self.activeShortcutRecordingTarget == .secondaryDictation {
                self.clearShortcutRecordingMode()
            }

            if self.activeRecordingMode == .promptMode {
                if self.asr.isRunning {
                    Task { await self.asr.stopWithoutTranscription() }
                }
                self.cancelPrewarmDictationIfNeeded()
                self.cancelDictationContextCapture()
                self.clearActiveRecordingMode()
                self.menuBarManager.setOverlayMode(.dictation)
            }
        }
    }

    private func handleCommandShortcutEnabledChange(_ isEnabled: Bool) {
        SettingsStore.shared.commandModeShortcutEnabled = isEnabled
        self.hotkeyManager?.updateCommandModeShortcutEnabled(isEnabled)

        if !isEnabled {
            if self.activeShortcutRecordingTarget == .command {
                self.clearShortcutRecordingMode()
            }

            if self.activeRecordingMode == .command {
                if self.asr.isRunning {
                    Task { await self.asr.stopWithoutTranscription() }
                }
                self.cancelPrewarmDictationIfNeeded()
                self.cancelDictationContextCapture()
                self.clearActiveRecordingMode()
                self.menuBarManager.setOverlayMode(.dictation)
            }
        }
    }

    private func handleRewriteShortcutEnabledChange(_ isEnabled: Bool) {
        SettingsStore.shared.rewriteModeShortcutEnabled = isEnabled
        self.hotkeyManager?.updateRewriteModeShortcutEnabled(isEnabled)

        if !isEnabled {
            if self.activeShortcutRecordingTarget == .edit {
                self.clearShortcutRecordingMode()
            }

            if self.activeRecordingMode == .edit {
                if self.asr.isRunning {
                    Task { await self.asr.stopWithoutTranscription() }
                }
                self.cancelPrewarmDictationIfNeeded()
                self.cancelDictationContextCapture()
                self.clearActiveRecordingMode()
                self.rewriteModeService.clearState()
                self.menuBarManager.setOverlayMode(.dictation)
            }
        }
    }

    private func handleContentAppear() {
        self.appear = true
        self.refreshAccessibilityPermissionState()

        Task {
            await AudioStartupGate.shared.scheduleOpenAfterInitialUISettled()
        }

        self.handleMenuBarNavigation(self.menuBarManager.requestedNavigationDestination)
        if UserDefaults.standard.bool(forKey: self.accessibilityRestartFlagKey) {
            UserDefaults.standard.set(false, forKey: self.accessibilityRestartFlagKey)
            self.showRestartPrompt = false
        }

        if self.accessibilityEnabled {
            self.finishAccessibilityPermissionFlow()
        }

        if self.selectedSidebarItem == nil, !self.settingsNavigation.isPresented {
            self.selectedSidebarItem = .welcome
        }
        self.handlePendingAppNavigation()

        if !self.accessibilityEnabled {
            UserDefaults.standard.set(false, forKey: self.hasAutoRestartedForAccessibilityKey)
        }

        self.menuBarManager.initializeMenuBar()
        self.scheduleDelayedAudioInitialization()
        self.configureNotchCallbacks()
        self.startAccessibilityPolling()
        self.initializeHotkeyManagerIfNeeded()

        Task {
            try? await Task.sleep(nanoseconds: 1_000_000_000)
            await self.preloadASRModel()
        }

        self.loadProviderState()
        self.installShortcutCaptureMonitor()
    }

    private func scheduleDelayedAudioInitialization() {
        DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) {
            DebugLogger.shared.info("🚦 Startup delay complete, signaling UI ready...", source: "ContentView")
            self.appServices.signalUIReady()
            if self.settings.fluidMeetEnabled {
                self.menuBarManager.configure(
                    meetingCoordinator: self.appServices.meetingSessionCoordinator
                )
            }

            Task { @MainActor in
                await AudioStartupGate.shared.scheduleOpenAfterInitialUISettled()
                await AudioStartupGate.shared.waitUntilOpen()

                DebugLogger.shared.info("🔊 Starting gated audio initialization...", source: "ContentView")
                self.audioObserver.startObserving()
                await self.asr.initialize()
                self.menuBarManager.configure(asrService: self.appServices.asr)
                self.refreshDevices()

                if self.selectedOutputUID.isEmpty, let defOut = AudioDevice.getDefaultOutputDevice()?.uid {
                    self.selectedOutputUID = defOut
                }

                if let prefOut = SettingsStore.shared.preferredOutputDeviceUID,
                   !prefOut.isEmpty,
                   outputDevices.first(where: { $0.uid == prefOut }) != nil
                {
                    self.selectedOutputUID = prefOut
                }

                DebugLogger.shared.info("✅ Audio subsystems initialized", source: "ContentView")
            }
        }
    }

    private func configureNotchCallbacks() {
        NotchOverlayManager.shared.onNotchClicked = {
            guard NotchOverlayManager.shared.canHandleNotchCommandTap else { return }
            if NotchOverlayManager.shared.canShowExpandedCommandOutput,
               !NotchContentState.shared.commandConversationHistory.isEmpty
            {
                NotchOverlayManager.shared.showExpandedCommandOutput()
            }
        }

        NotchOverlayManager.shared.onCommandFollowUp = { [weak commandModeService] text in
            guard NotchOverlayManager.shared.allowsCommandNotchActions, let commandModeService else { return false }
            let accepted = await commandModeService.processFollowUpCommand(text)
            if !accepted, commandModeService.pendingCommand != nil {
                self.asr.errorTitle = "Command Awaiting Approval"
                self.asr.errorMessage = "Approve or cancel the pending command before sending a follow-up. Your text has been kept."
                self.asr.showError = true
            }
            return accepted
        }

        NotchOverlayManager.shared.onNewChat = { [weak commandModeService] in
            guard NotchOverlayManager.shared.allowsCommandNotchActions else { return }
            commandModeService?.createNewChat()
        }

        NotchOverlayManager.shared.onSwitchChat = { [weak commandModeService] chatID in
            guard NotchOverlayManager.shared.allowsCommandNotchActions else { return }
            commandModeService?.switchToChat(id: chatID)
        }

        NotchOverlayManager.shared.onClearChat = { [weak commandModeService] in
            guard NotchOverlayManager.shared.allowsCommandNotchActions else { return }
            commandModeService?.deleteCurrentChat()
        }
    }

    private func loadProviderState() {
        self.selectedProviderID = SettingsStore.shared.selectedProviderID
        self.updateCurrentProvider()

        self.enableDebugLogs = SettingsStore.shared.enableDebugLogs
        self.availableModelsByProvider = SettingsStore.shared.availableModelsByProvider
        self.selectedModelByProvider = SettingsStore.shared.selectedModelByProvider
        self.providerAPIKeys = SettingsStore.shared.providerAPIKeys
        self.savedProviders = SettingsStore.shared.savedProviders

        var normalized: [String: [String]] = [:]
        for (key, models) in self.availableModelsByProvider {
            let lower = key.lowercased()
            let newKey = ModelRepository.shared.isBuiltIn(lower) ? lower : (key.hasPrefix("custom:") ? key : "custom:\(key)")
            let clean = Array(Set(models.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) })).sorted()
            if !clean.isEmpty {
                normalized[newKey] = clean
            }
        }
        self.availableModelsByProvider = normalized
        SettingsStore.shared.availableModelsByProvider = normalized

        var normalizedSel: [String: String] = [:]
        for (key, model) in self.selectedModelByProvider {
            let lower = key.lowercased()
            let newKey = ModelRepository.shared.isBuiltIn(lower) ? lower : (key.hasPrefix("custom:") ? key : "custom:\(key)")
            if let list = normalized[newKey], list.contains(model) {
                normalizedSel[newKey] = model
            }
        }
        self.selectedModelByProvider = normalizedSel
        SettingsStore.shared.selectedModelByProvider = normalizedSel

        if let saved = savedProviders.first(where: { $0.id == selectedProviderID }) {
            self.availableModels = saved.models
            self.openAIBaseURL = saved.baseURL
        } else if let stored = availableModelsByProvider[currentProvider], !stored.isEmpty {
            self.availableModels = stored
        } else {
            self.availableModels = ModelRepository.shared.defaultModels(for: self.providerKey(for: self.selectedProviderID))
        }

        if let sel = selectedModelByProvider[currentProvider], availableModels.contains(sel) {
            self.selectedModel = sel
        } else if let first = availableModels.first {
            self.selectedModel = first
        }
    }

    private func installShortcutCaptureMonitor() {
        self.removeShortcutCaptureMonitor()
        self.shortcutCaptureMonitor = NSEvent.addLocalMonitorForEvents(
            matching: [.keyDown, .flagsChanged, .leftMouseDown, .rightMouseDown, .otherMouseDown]
        ) { event in
            self.handleShortcutCaptureEvent(event)
        }
    }

    private func removeShortcutCaptureMonitor() {
        guard let monitor = self.shortcutCaptureMonitor else { return }
        NSEvent.removeMonitor(monitor)
        self.shortcutCaptureMonitor = nil
    }

    private func handleShortcutCaptureEvent(_ event: NSEvent) -> NSEvent? {
        let eventModifiers = event.modifierFlags.intersection(HotkeyShortcut.shortcutModifierMask)
        let isRecordingAnyShortcut = self.isRecordingAnyShortcutCapture
        let recordingTarget = self.activeShortcutRecordingTarget

        if event.type == .keyDown {
            return self.handleShortcutKeyDownEvent(event, modifiers: eventModifiers, isRecordingAnyShortcut: isRecordingAnyShortcut, recordingTarget: recordingTarget)
        } else if event.type == .flagsChanged {
            return self.handleShortcutFlagsChangedEvent(event, modifiers: eventModifiers.intersection(HotkeyShortcut.relevantModifierMask), isRecordingAnyShortcut: isRecordingAnyShortcut, recordingTarget: recordingTarget)
        } else if event.type == .leftMouseDown || event.type == .rightMouseDown || event.type == .otherMouseDown {
            return self.handleShortcutMouseDownEvent(event, modifiers: eventModifiers, isRecordingAnyShortcut: isRecordingAnyShortcut, recordingTarget: recordingTarget)
        }

        return event
    }

    private func handleShortcutKeyDownEvent(
        _ event: NSEvent,
        modifiers eventModifiers: NSEvent.ModifierFlags,
        isRecordingAnyShortcut: Bool,
        recordingTarget: ShortcutRecordingTarget?
    ) -> NSEvent? {
        guard isRecordingAnyShortcut else {
            if self.cancelRecordingHotkeyShortcut?.matches(keyCode: event.keyCode, modifiers: eventModifiers) == true,
               self.handleCancelShortcut()
            {
                return nil
            }
            self.shortcutRecordingMessage = nil
            self.resetPendingShortcutState()
            return event
        }

        let keyCode = event.keyCode
        if keyCode == 53, eventModifiers.isEmpty, recordingTarget != .cancel {
            DebugLogger.shared.debug("NSEvent monitor: Escape pressed, cancelling shortcut recording", source: "ContentView")
            self.clearShortcutRecordingMode()
            return nil
        }

        let newShortcut = HotkeyShortcut(keyCode: keyCode, modifierFlags: eventModifiers)
        if recordingTarget != .cancel, recordingTarget != .pasteLast, newShortcut.requiresModifierForRecording {
            self.shortcutRecordingMessage = "\(newShortcut.displayString) needs a modifier key"
            self.resetPendingShortcutState()
            return nil
        }
        DebugLogger.shared.debug("NSEvent monitor: Recording new shortcut: \(newShortcut.displayString)", source: "ContentView")

        if let recordingTarget,
           let conflictMessage = self.shortcutConflictMessage(for: newShortcut, target: recordingTarget)
        {
            self.shortcutRecordingMessage = conflictMessage
            self.resetPendingShortcutState()
            DebugLogger.shared.debug("NSEvent monitor: Shortcut conflict while recording: \(conflictMessage)", source: "ContentView")
            return nil
        }

        self.shortcutRecordingMessage = nil
        if let recordingTarget {
            self.assignRecordedShortcut(newShortcut, to: recordingTarget)
        }
        self.resetPendingShortcutState()
        DebugLogger.shared.debug("NSEvent monitor: Finished recording shortcut", source: "ContentView")
        return nil
    }

    private func handleShortcutMouseDownEvent(
        _ event: NSEvent,
        modifiers eventModifiers: NSEvent.ModifierFlags,
        isRecordingAnyShortcut: Bool,
        recordingTarget: ShortcutRecordingTarget?
    ) -> NSEvent? {
        guard isRecordingAnyShortcut else {
            self.shortcutRecordingMessage = nil
            self.resetPendingShortcutState()
            return event
        }

        let newShortcut = HotkeyShortcut(mouseButton: event.buttonNumber, modifierFlags: eventModifiers)
        DebugLogger.shared.debug("NSEvent monitor: Recording new mouse shortcut: \(newShortcut.displayString)", source: "ContentView")

        if newShortcut.isUnmodifiedLeftOrRightClick, let mouseButton = newShortcut.mouseButton {
            self.shortcutRecordingMessage = "\(HotkeyShortcut.mouseButtonToString(mouseButton)) needs a modifier key"
            self.resetPendingShortcutState()
            return event
        }

        if let recordingTarget,
           let conflictMessage = self.shortcutConflictMessage(for: newShortcut, target: recordingTarget)
        {
            self.shortcutRecordingMessage = conflictMessage
            self.resetPendingShortcutState()
            DebugLogger.shared.debug("NSEvent monitor: Mouse shortcut conflict while recording: \(conflictMessage)", source: "ContentView")
            return nil
        }

        self.shortcutRecordingMessage = nil
        if let recordingTarget {
            self.assignRecordedShortcut(newShortcut, to: recordingTarget)
        }
        self.resetPendingShortcutState()
        DebugLogger.shared.debug("NSEvent monitor: Finished recording mouse shortcut", source: "ContentView")
        return nil
    }

    private func handleShortcutFlagsChangedEvent(
        _ event: NSEvent,
        modifiers eventModifiers: NSEvent.ModifierFlags,
        isRecordingAnyShortcut: Bool,
        recordingTarget: ShortcutRecordingTarget?
    ) -> NSEvent? {
        guard isRecordingAnyShortcut else {
            self.shortcutRecordingMessage = nil
            self.resetPendingShortcutState()
            return event
        }

        let changedModifierFlag = HotkeyShortcut.modifierFlag(forKeyCode: event.keyCode)

        if eventModifiers.isEmpty {
            if self.pendingModifierOnly, let modifierKeyCode = pendingModifierKeyCode {
                let newShortcut = HotkeyShortcut(
                    keyCode: modifierKeyCode,
                    modifierFlags: self.pendingModifierFlags,
                    modifierKeyCodes: Array(self.pendingModifierKeyCodes)
                )
                DebugLogger.shared.debug("NSEvent monitor: Recording modifier-only shortcut: \(newShortcut.displayString)", source: "ContentView")

                if let recordingTarget,
                   let conflictMessage = self.shortcutConflictMessage(for: newShortcut, target: recordingTarget)
                {
                    self.shortcutRecordingMessage = conflictMessage
                    self.resetPendingShortcutState()
                    DebugLogger.shared.debug("NSEvent monitor: Modifier shortcut conflict while recording: \(conflictMessage)", source: "ContentView")
                    return nil
                }

                self.shortcutRecordingMessage = nil
                if let recordingTarget {
                    self.assignRecordedShortcut(newShortcut, to: recordingTarget)
                }
                self.resetPendingShortcutState()
                DebugLogger.shared.debug("NSEvent monitor: Finished recording modifier shortcut", source: "ContentView")
                return nil
            }

            self.resetPendingShortcutState()
            DebugLogger.shared.debug("NSEvent monitor: Modifiers released without recording, continuing to wait", source: "ContentView")
            return nil
        }

        if let changedModifierFlag {
            let isRelease = self.currentRecordingModifierKeyCodes.contains(event.keyCode)

            if isRelease {
                self.currentRecordingModifierKeyCodes.remove(event.keyCode)
            } else if eventModifiers.contains(changedModifierFlag) {
                self.currentRecordingModifierKeyCodes.insert(event.keyCode)
                self.pendingModifierKeyCodes.insert(event.keyCode)
                self.pendingModifierFlags = self.pendingModifierFlags.union(eventModifiers)
                self.pendingModifierKeyCode = event.keyCode
                self.pendingModifierOnly = true
                DebugLogger.shared.debug("NSEvent monitor: Modifier key pressed during recording, pending modifiers: \(self.pendingModifierFlags)", source: "ContentView")
            }
        }
        return nil
    }

    // MARK: - Analytics helpers

    private func currentDictationAIModelInfo(
        dictationSlot: SettingsStore.DictationShortcutSlot? = nil,
        appBundleID: String? = nil
    ) -> (provider: String?, model: String?) {
        let route = DictationProviderRoute.resolve(
            settings: SettingsStore.shared,
            dictationSlot: dictationSlot,
            appBundleID: appBundleID
        )
        let providerOut = route.providerKey.isEmpty ? nil : route.providerKey
        let modelOut = route.model.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? nil : route.model
        return (provider: providerOut, model: modelOut)
    }

    private func currentTranscriptionModelInfo() -> (provider: String, model: String) {
        let selectedModel = SettingsStore.shared.selectedSpeechModel
        return (
            provider: selectedModel.provider.rawValue.lowercased(),
            model: selectedModel.rawValue
        )
    }

    private func recordDictationUsage(
        shouldUseAI: Bool,
        dictationSlot: SettingsStore.DictationShortcutSlot?,
        appBundleID: String,
        snapshot: DictationStopSnapshot? = nil
    ) -> (provider: String?, model: String?) {
        let postProcessing = snapshot.map { (provider: Optional($0.route.providerKey), model: Optional($0.route.model)) } ?? self.currentDictationAIModelInfo(
            dictationSlot: dictationSlot,
            appBundleID: appBundleID
        )
        AnalyticsService.shared.recordUsage(
            mode: .dictation,
            transcriptionModel: self.settings.selectedSpeechModel.analyticsDescriptor,
            aiModel: shouldUseAI ? AnalyticsModelDescriptor(
                provider: postProcessing.provider ?? "unknown",
                model: postProcessing.model ?? "unknown"
            ) : nil
        )
        return postProcessing
    }

    // MARK: - Mode Transition Handler

    /// Centralized handler for sidebar mode transitions to ensure proper cleanup and state management
    private func handleModeTransition(from oldValue: SidebarItem?, to newValue: SidebarItem?) {
        DebugLogger.shared.debug("Mode transition: \(String(describing: oldValue)) → \(String(describing: newValue))", source: "ContentView")

        if oldValue != newValue {
            self.clearShortcutRecordingMode()
        }

        // Clean up state from the previous mode
        if let old = oldValue {
            switch old {
            case .commandMode:
                // Close expanded command output notch if visible
                if NotchOverlayManager.shared.hasCommandOutputToDismiss {
                    DebugLogger.shared.debug("Closing expanded command notch on mode transition", source: "ContentView")
                    NotchOverlayManager.shared.hideExpandedCommandOutput()
                }
                // Note: We don't clear command history here - user may want to return to it

            case .rewriteMode:
                // Clear rewrite state when leaving
                self.rewriteModeService.clearState()

            default:
                break
            }
        }

        // Set up state for the new mode
        if let new = newValue {
            switch new {
            case .commandMode:
                self.menuBarManager.setOverlayMode(.command)

            case .rewriteMode:
                self.menuBarManager.setOverlayMode(.edit)

            default:
                // For all other views, set to dictation mode
                self.menuBarManager.setOverlayMode(.dictation)
            }
        } else {
            // If newValue is nil, default to dictation
            self.menuBarManager.setOverlayMode(.dictation)
        }
    }

    @MainActor
    private func handleMenuBarNavigation(_ destination: MenuBarNavigationDestination?) {
        guard let destination else { return }
        guard !self.settings.shouldShowOnboarding else { return }

        switch destination {
        case .customDictionary:
            self.navigateToApp(.customDictionary)
        case .microphoneSettings:
            self.openSettings(.audio)
        case .settings:
            self.openSettings(.general)
        case .meetingTranscription:
            self.navigateToApp(.meetingTranscription)
        case .preferences:
            self.openSettings(.general)
        case .aiSettings:
            self.navigateToApp(.aiEnhancements)
        case .cleanupStyles:
            self.navigateToApp(.cleanupStyles)
        }
    }

    private func handlePendingAppNavigation() {
        guard let destination = AppNavigationRouter.shared.consumePendingDestination() else { return }

        switch destination {
        case .aiEnhancements:
            self.navigateToApp(.aiEnhancements)
        case .history:
            self.navigateToApp(.history)
        case .dictationShortcuts:
            self.openSettings(.shortcuts)
        case .meetingTranscription:
            self.navigateToApp(.meetingTranscription)
        }
    }

    private func navigateToApp(_ destination: SidebarItem) {
        guard destination != .meetingTranscription || self.settings.fluidMeetEnabled else {
            self.openSettings(.fluidMeet)
            return
        }
        self.clearShortcutRecordingMode()
        self.resetSettingsSearch()
        self.settingsNavigation.leaveForApp()
        self.selectedSidebarItem = destination
    }

    private func openSettings(_ section: SettingsSection) {
        self.clearShortcutRecordingMode()
        self.resetSettingsSearch()
        self.settingsNavigation.present(section, returningTo: self.selectedSidebarItem)
    }

    private func closeSettings() {
        self.clearShortcutRecordingMode()
        self.resetSettingsSearch()
        let destination = self.settingsNavigation.dismiss()
        self.selectedSidebarItem = destination == .meetingTranscription && !self.settings.fluidMeetEnabled ? .welcome : destination
    }

    private func resetSettingsSearch() {
        self.settingsSearchQuery = ""
        self.settingsRevealTarget = nil
        self.settingsSearchScrollRequest += 1
    }

    private func resetPendingShortcutState() {
        self.currentRecordingModifierKeyCodes = []
        self.pendingModifierKeyCodes = []
        self.pendingModifierFlags = []
        self.pendingModifierKeyCode = nil
        self.pendingModifierOnly = false
    }

    func shortcutConflictMessage(for shortcut: HotkeyShortcut, target: ShortcutRecordingTarget) -> String? {
        if target == .cancel, shortcut.isModifierOnlyShortcut {
            return "Modifier-only keys can't cancel recording. Use Esc or include a regular key."
        }
        if target == .meeting, !shortcut.isMeetingRecordingShortcut {
            return "Use a keyboard key with a modifier for meeting recording"
        }
        if shortcut.isMouseShortcut {
            guard target.allowsMouseShortcut else {
                return "Mouse clicks can only be assigned to Primary Dictation or Paste Last Transcription"
            }

            if shortcut.isUnmodifiedLeftOrRightClick, let mouseButton = shortcut.mouseButton {
                return "\(HotkeyShortcut.mouseButtonToString(mouseButton)) needs a modifier key"
            }
        }

        let replacingPrimaryIndex = target.primaryDictationReplacementIndex
        for (index, configuredShortcut) in self.primaryDictationShortcuts.enumerated() where replacingPrimaryIndex != index {
            if configuredShortcut.hasSameTrigger(as: shortcut) {
                return "Duplicate with Primary Dictation Shortcut"
            }
            if shortcut.conflictsWith(configuredShortcut, includingKeyboardModifierPrefixes: target == .meeting) {
                return "Overlaps Primary Dictation Shortcut — use a different modifier key"
            }
        }

        var configuredShortcuts: [(ShortcutRecordingTarget, HotkeyShortcut)] = []
        if self.isRewriteModeShortcutEnabled {
            configuredShortcuts.append((.edit, self.rewriteModeHotkeyShortcut))
        }
        if self.isPromptModeShortcutEnabled {
            configuredShortcuts.append((.secondaryDictation, self.promptModeHotkeyShortcut))
        }
        if self.isCommandModeShortcutEnabled, let shortcut = self.commandModeHotkeyShortcut {
            configuredShortcuts.append((.command, shortcut))
        }
        if self.isPasteLastTranscriptionShortcutEnabled, let shortcut = self.pasteLastTranscriptionHotkeyShortcut {
            configuredShortcuts.append((.pasteLast, shortcut))
        }
        let optionalConfiguredShortcuts: [(ShortcutRecordingTarget, HotkeyShortcut?)] = [
            (.meeting, SettingsStore.shared.meetingRecordingHotkeyShortcut),
            (.cancel, self.cancelRecordingHotkeyShortcut),
        ]

        for (otherTarget, configuredShortcut) in configuredShortcuts where otherTarget != target {
            if configuredShortcut.hasSameTrigger(as: shortcut) {
                return "Duplicate with \(otherTarget.title)"
            }
            if shortcut.conflictsWith(configuredShortcut, includingKeyboardModifierPrefixes: target == .meeting || otherTarget == .meeting) {
                return "Overlaps \(otherTarget.title) — use a different modifier key"
            }
        }
        for (otherTarget, configuredShortcut) in optionalConfiguredShortcuts where otherTarget != target {
            guard let configuredShortcut else { continue }
            if configuredShortcut.hasSameTrigger(as: shortcut) {
                return "Duplicate with \(otherTarget.title)"
            }
            if shortcut.conflictsWith(configuredShortcut, includingKeyboardModifierPrefixes: target == .meeting || otherTarget == .meeting) {
                return "Overlaps \(otherTarget.title) — use a different modifier key"
            }
        }

        let targetPromptKey = target.promptConfigurationKey
        for assignment in SettingsStore.shared.dictationPromptShortcutAssignments() {
            guard let key = SettingsStore.shared.dictationPromptConfigurationKey(for: assignment.selection),
                  key != targetPromptKey
            else {
                continue
            }
            if assignment.shortcut.hasSameTrigger(as: shortcut) {
                return "Duplicate with Prompt Shortcut"
            }
            if shortcut.conflictsWith(assignment.shortcut, includingKeyboardModifierPrefixes: target == .meeting) {
                return "Overlaps Prompt Shortcut — use a different modifier key"
            }
        }

        return nil
    }

    private func assignRecordedShortcut(_ shortcut: HotkeyShortcut, to target: ShortcutRecordingTarget) {
        self.applyRecordedShortcut(shortcut, to: target)
        if target.enablesFeatureOnAssignment {
            self.setShortcutTargetEnabled(true, for: target)
        }
        self.setShortcutRecording(false, for: target)
    }

    private func applyRecordedShortcut(_ shortcut: HotkeyShortcut, to target: ShortcutRecordingTarget) {
        switch target {
        case let .primaryDictation(edit):
            self.applyPrimaryDictationShortcut(shortcut, edit: edit)
        case .secondaryDictation:
            self.promptModeHotkeyShortcut = shortcut
            SettingsStore.shared.promptModeHotkeyShortcut = shortcut
            self.hotkeyManager?.updatePromptModeShortcut(shortcut)
        case .command:
            self.commandModeHotkeyShortcut = shortcut
            SettingsStore.shared.commandModeHotkeyShortcut = shortcut
            self.hotkeyManager?.updateCommandModeShortcut(shortcut)
        case .edit:
            self.rewriteModeHotkeyShortcut = shortcut
            SettingsStore.shared.rewriteModeHotkeyShortcut = shortcut
            self.hotkeyManager?.updateRewriteModeShortcut(shortcut)
        case .meeting:
            SettingsStore.shared.meetingRecordingHotkeyShortcut = shortcut
        case .cancel:
            self.cancelRecordingHotkeyShortcut = shortcut
            SettingsStore.shared.cancelRecordingHotkeyShortcut = shortcut
        case .pasteLast:
            // The hotkey manager reads this shortcut directly from SettingsStore, so no manager update is needed.
            self.pasteLastTranscriptionHotkeyShortcut = shortcut
            SettingsStore.shared.pasteLastTranscriptionHotkeyShortcut = shortcut
        case let .dictationPrompt(key):
            guard let selection = SettingsStore.shared.dictationPromptSelection(forConfigurationKey: key) else { return }
            var configuration = SettingsStore.shared.dictationPromptConfiguration(for: selection)
            configuration.shortcut = shortcut
            SettingsStore.shared.setDictationPromptConfiguration(configuration, for: selection)
            self.hotkeyManager?.updatePromptShortcutAssignments(SettingsStore.shared.dictationPromptShortcutAssignments())
        case .newPrompt:
            NotificationCenter.default.post(
                name: .newPromptShortcutRecorded,
                object: nil,
                userInfo: ["shortcut": shortcut]
            )
        }
    }

    private func applyPrimaryDictationShortcut(_ shortcut: HotkeyShortcut, edit: PrimaryDictationShortcutEdit) {
        var shortcuts = self.primaryDictationShortcuts
        switch edit {
        case .add:
            shortcuts.append(shortcut)
        case let .replace(index):
            if shortcuts.indices.contains(index) {
                shortcuts[index] = shortcut
            } else {
                shortcuts.append(shortcut)
            }
        }
        self.primaryDictationShortcuts = shortcuts
    }

    private func setShortcutTargetEnabled(_ enabled: Bool, for target: ShortcutRecordingTarget) {
        switch target {
        case .secondaryDictation:
            self.isPromptModeShortcutEnabled = enabled
            SettingsStore.shared.promptModeShortcutEnabled = enabled
            self.hotkeyManager?.updatePromptModeShortcutEnabled(enabled)
        case .command:
            self.isCommandModeShortcutEnabled = enabled
            SettingsStore.shared.commandModeShortcutEnabled = enabled
            self.hotkeyManager?.updateCommandModeShortcutEnabled(enabled)
        case .edit:
            self.isRewriteModeShortcutEnabled = enabled
            SettingsStore.shared.rewriteModeShortcutEnabled = enabled
            self.hotkeyManager?.updateRewriteModeShortcutEnabled(enabled)
        case .pasteLast:
            self.isPasteLastTranscriptionShortcutEnabled = enabled
            SettingsStore.shared.pasteLastTranscriptionShortcutEnabled = enabled
        case .primaryDictation, .cancel, .meeting, .dictationPrompt, .newPrompt:
            break
        }
    }

    private func setShortcutRecording(_ isRecording: Bool, for target: ShortcutRecordingTarget) {
        if isRecording {
            self.activeShortcutRecordingTarget = target
        } else if self.activeShortcutRecordingTarget == target {
            self.activeShortcutRecordingTarget = nil
        }
    }

    private func clearShortcutRecordingMode() {
        self.activeShortcutRecordingTarget = nil
        self.shortcutRecordingMessage = nil
        self.resetPendingShortcutState()
    }

    private func openIssueReportingPage() {
        guard let url = URL(string: "https://github.com/altic-dev/Fluid-oss/issues/new/choose") else { return }
        NSWorkspace.shared.open(url)
    }

    private func openHelpDocumentation() {
        guard let url = URL(string: "https://docs.altic.dev/") else { return }
        NSWorkspace.shared.open(url)
    }

    private var sidebarContent: some View {
        ZStack {
            // Keep both sidebars mounted so navigation feedback never waits on view construction.
            self.appSidebarView
                .opacity(self.settingsNavigation.isPresented ? 0 : 1)
                .offset(x: self.settingsNavigation.isPresented ? -self.sidebarTransitionDistance : 0)
                .allowsHitTesting(!self.settingsNavigation.isPresented)
                .accessibilityHidden(self.settingsNavigation.isPresented)

            // No flat backdrop: the settings sidebar shows the same system material as the app one.
            self.settingsSidebarView
                .opacity(self.settingsNavigation.isPresented ? 1 : 0)
                .offset(x: self.settingsNavigation.isPresented ? 0 : self.sidebarTransitionDistance)
                .allowsHitTesting(self.settingsNavigation.isPresented)
                .accessibilityHidden(!self.settingsNavigation.isPresented)
        }
        .clipped()
        .tint(self.theme.palette.accent)
        .animation(self.modeTransitionAnimation, value: self.settingsNavigation.isPresented)
    }

    private var appSidebarView: some View {
        VStack(spacing: 0) {
            SidebarSearchField(
                text: self.$appSearch.query,
                placeholder: "Search",
                isActive: !self.settingsNavigation.isPresented,
                onCommand: self.handleAppSearchCommand
            )
            .padding(.horizontal, self.theme.metrics.spacing.md)
            .padding(.top, self.theme.metrics.spacing.sm)
            .padding(.bottom, self.theme.metrics.spacing.sm)

            Group {
                if self.isAppSearchActive {
                    AppSearchResultsView(
                        service: self.appSearch,
                        cursor: self.$appSearchCursor,
                        expanded: self.$appSearchExpanded,
                        open: self.open(searchHit:)
                    )
                } else {
                    self.appSidebarSections
                }
            }
            .frame(maxHeight: .infinity)
            .clipped()

            // Reserve real layout space for the footer. A safe-area inset can let
            // the native sidebar list draw its last rows beneath these controls.
            VStack(spacing: 0) {
                self.helpEntryButton
                self.settingsEntryButton
            }
            .fixedSize(horizontal: false, vertical: true)
        }
        .onChange(of: self.appSearch.groups) {
            self.appSearchCursor = nil
            self.appSearchExpanded = []
        }
    }

    private var isAppSearchActive: Bool {
        !self.appSearch.query.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
    }

    private var appSidebarSections: some View {
        List(selection: self.$selectedSidebarItem) {
            Section {
                self.sidebarNavigationLink(.welcome, title: "Dashboard", systemImage: "house.fill")
                self.sidebarNavigationLink(.history, title: "History", systemImage: "clock.arrow.circlepath")
                self.sidebarNavigationLink(.stats, title: "Stats", systemImage: "chart.bar.fill")
            } header: {
                self.sidebarSectionHeader("Activity")
            }

            Section {
                self.sidebarNavigationLink(.voiceEngine, title: "Voice Engine", systemImage: "waveform")
                self.sidebarNavigationLink(.aiEnhancements, title: "AI Settings", systemImage: "cpu")
                self.sidebarNavigationLink(.cleanupStyles, title: "Cleanup Styles", systemImage: "wand.and.stars")
                self.sidebarNavigationLink(.customDictionary, title: "Custom Dictionary", systemImage: "text.book.closed.fill")
            } header: {
                self.sidebarSectionHeader("Configure")
            }

            Section {
                self.sidebarNavigationLink(.commandMode, title: "Command Mode", systemImage: "terminal.fill")
                self.sidebarNavigationLink(.fileTranscription, title: "File Transcription", systemImage: "doc.text.fill")
                if self.settings.fluidMeetEnabled {
                    self.sidebarNavigationLink(
                        .meetingTranscription,
                        title: "FluidMeet",
                        systemImage: "person.2.fill"
                    )
                }
            } header: {
                self.sidebarSectionHeader("Use")
            }

            Section {
                self.sidebarNavigationLink(.changelog, title: "Change logs", systemImage: "doc.text.magnifyingglass")
                self.sidebarNavigationLink(.feedback, title: "Feedback", systemImage: "envelope.fill")
            } header: {
                self.sidebarSectionHeader("Help")
            }
        }
        .listStyle(.sidebar)
        .accentColor(self.theme.palette.accent)
        .animation(nil, value: self.selectedSidebarItem)
    }

    // MARK: - App search

    /// Up and Down move the cursor through the visible rows, Return opens the
    /// cursor or the first row. Anything else is left to the field.
    private func handleAppSearchCommand(_ selector: Selector) -> Bool {
        let hits = AppSearchResultsView.visibleHits(self.appSearch.groups, expanded: self.appSearchExpanded)
        guard !hits.isEmpty else { return false }
        let position = hits.firstIndex { $0.target == self.appSearchCursor }
        switch selector {
        case #selector(NSResponder.moveDown(_:)):
            self.appSearchCursor = hits[min((position ?? -1) + 1, hits.count - 1)].target
        case #selector(NSResponder.moveUp(_:)):
            self.appSearchCursor = hits[max((position ?? hits.count) - 1, 0)].target
        case #selector(NSResponder.insertNewline(_:)):
            self.open(searchHit: hits[position ?? 0])
        default:
            return false
        }
        return true
    }

    private func open(searchHit hit: AppSearchHit) {
        switch hit.target {
        case let .history(id):
            TranscriptionHistoryStore.shared.selectEntryFromSearch(id: id)
            self.navigateToApp(.history)
        case let .transcript(id):
            FileTranscriptionHistoryStore.shared.selectedEntryID = id
            self.appSearchRevealTarget = hit.target
            self.navigateToApp(.fileTranscription)
        case let .chat(id):
            self.commandModeService.switchToChat(id: id)
            self.navigateToApp(.commandMode)
        case .dictionaryEntry, .vocabulary, .punctuation:
            self.appSearchRevealTarget = hit.target
            self.navigateToApp(.customDictionary)
        case .prompt:
            self.appSearchRevealTarget = hit.target
            self.navigateToApp(.cleanupStyles)
        case let .settings(target):
            self.openSettings(target.section)
            self.settingsRevealTarget = target
        }
        self.appSearch.query = ""
    }

    private var settingsSidebarView: some View {
        VStack(spacing: 0) {
            Button {
                self.closeSettings()
            } label: {
                HStack(spacing: self.theme.metrics.spacing.sm) {
                    Image(systemName: "chevron.left")
                        .font(.fluidSystem(size: 11, weight: .semibold))
                        .frame(width: 18, height: 28)

                    Text("Back to app")
                        .font(self.theme.typography.sidebarItem)

                    Spacer(minLength: 0)
                }
                .foregroundStyle(.secondary)
                .padding(.horizontal, self.theme.metrics.spacing.md)
                .padding(.top, self.theme.metrics.spacing.sm)
                .padding(.bottom, self.theme.metrics.spacing.xs)
                .frame(maxWidth: .infinity, minHeight: 36, alignment: .leading)
                .contentShape(Rectangle())
            }
            .buttonStyle(SidebarChromeButtonStyle(
                isHovered: self.isSettingsBackHovered,
                reduceMotion: self.accessibilityReduceMotion
            ))
            .onHover { self.isSettingsBackHovered = $0 }
            .help("Back to FluidVoice")
            .accessibilityLabel("Back to FluidVoice")

            SidebarSearchField(
                text: Binding(
                    get: { self.settingsSearchQuery },
                    set: { self.updateSettingsSearchQuery($0) }
                ),
                placeholder: "Search Settings",
                isActive: self.settingsNavigation.isPresented
            )
            .padding(.horizontal, self.theme.metrics.spacing.md)
            .padding(.top, self.theme.metrics.spacing.xs)
            .padding(.bottom, self.theme.metrics.spacing.sm)

            List(selection: Binding(
                get: { self.settingsNavigation.selectedSection },
                set: { newValue in
                    guard let newValue else { return }
                    if self.settingsNavigation.isLeaving(.shortcuts, for: newValue) {
                        self.clearShortcutRecordingMode()
                    }
                    self.settingsNavigation.selectedSection = newValue
                    self.settingsSearchScrollRequest += 1
                }
            )) {
                ForEach(self.filteredSettingsSections) { section in
                    let isSelected = self.settingsNavigation.selectedSection == section
                    NavigationLink(value: section) {
                        HStack(spacing: self.theme.metrics.spacing.sm) {
                            Image(systemName: section.systemImage)
                                .symbolRenderingMode(.hierarchical)
                                .foregroundStyle(isSelected ? Color.white.opacity(0.9) : Color.secondary)
                                .frame(width: 18)

                            Text(section.title)
                                .foregroundStyle(isSelected ? Color.white : Color.primary)
                        }
                        .font(self.theme.typography.sidebarItem)
                    }
                    .sidebarOptionHover(
                        isSelected: isSelected,
                        reduceMotion: self.accessibilityReduceMotion
                    )
                }
            }
            .listStyle(.sidebar)
            .accentColor(self.theme.palette.accent)
            .animation(nil, value: self.settingsNavigation.selectedSection)
        }
    }

    private var isSettingsSearchActive: Bool {
        !self.settingsSearchQuery.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
    }

    private var settingsSearchResults: [SettingsSearchResult] {
        if let target = self.settingsRevealTarget {
            return [SettingsSearchResult(target: target, score: 0)]
        }
        return self.availableSettingsSearchResults(for: self.settingsSearchQuery)
    }

    private var filteredSettingsSections: [SettingsSection] {
        guard self.isSettingsSearchActive else { return SettingsSection.allCases }
        let matchingSections = Set(self.settingsSearchResults.map(\.section))
        return SettingsSection.allCases.filter(matchingSections.contains)
    }

    private func updateSettingsSearchQuery(_ query: String) {
        self.settingsSearchQuery = query
        self.settingsRevealTarget = nil
        self.settingsSearchScrollRequest += 1

        guard !query.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return }
        let results = self.availableSettingsSearchResults(for: query)
        self.settingsNavigation.selectedSection = SettingsSearchIndex.preferredSection(
            current: self.settingsNavigation.selectedSection,
            results: results
        )
    }

    private func availableSettingsSearchResults(for query: String) -> [SettingsSearchResult] {
        SettingsSearchIndex.results(
            for: query,
            availability: SettingsSearchAvailability(
                microphoneAuthorized: self.asr.micStatus == .authorized,
                accessibilityEnabled: self.accessibilityEnabled,
                savesTranscriptionHistory: SettingsStore.shared.saveTranscriptionHistory,
                savesAudioWithTranscriptionHistory: SettingsStore.shared.saveAudioWithTranscriptionHistory,
                overlayAtBottom: self.settings.overlayPosition == .bottom,
                privateAIAvailable: PrivateAIProviderFeature.shared.isAvailable
            )
        )
    }

    private var settingsEntryButton: some View {
        Button {
            self.openSettings(.general)
        } label: {
            HStack(spacing: self.theme.metrics.spacing.sm) {
                Image(systemName: "gearshape")
                    .symbolRenderingMode(.hierarchical)
                    .foregroundStyle(.secondary)
                    .frame(width: 18)

                Text("Settings")

                Spacer(minLength: self.theme.metrics.spacing.sm)

                Image(systemName: "chevron.right")
                    .font(.fluidSystem(size: 10, weight: .semibold))
                    .foregroundStyle(.tertiary)
            }
            .font(self.theme.typography.sidebarItem)
            .padding(.horizontal, self.theme.metrics.spacing.md)
            .frame(maxWidth: .infinity, minHeight: 48, alignment: .leading)
            .contentShape(Rectangle())
        }
        .buttonStyle(SidebarChromeButtonStyle(
            isHovered: self.isSettingsEntryHovered,
            reduceMotion: self.accessibilityReduceMotion
        ))
        .onHover { self.isSettingsEntryHovered = $0 }
        .help("Settings")
        .accessibilityLabel("Settings")
    }

    private var helpEntryButton: some View {
        Menu {
            Button("Documentation", systemImage: "book") { self.openHelpDocumentation() }
            Button("What’s new", systemImage: "gift") { self.showsReleaseHighlights = true }
                .disabled(self.asr.isRunningOrStarting || self.asr.activeExclusiveActivity != nil || NotchContentState.shared.isProcessing)
            if PrivateAIProviderFeature.shared.isAvailable {
                Button("Try Fluid Intelligence", systemImage: "sparkles") { self.showsFluidIntelligenceDemo = true }
                    .disabled(self.asr.isRunningOrStarting || NotchContentState.shared.isProcessing || DictationPromptTestCoordinator.shared.isActive)
            }
            Button("Replay onboarding", systemImage: "arrow.counterclockwise") {
                guard !self.asr.isRunning, !self.asr.isStarting, !NotchContentState.shared.isProcessing else { return }
                self.settings.resetOnboardingProgress()
                self.playgroundUsed = false
            }
            .disabled(self.asr.isRunning || self.asr.isStarting || NotchContentState.shared.isProcessing)
        } label: {
            HStack(spacing: self.theme.metrics.spacing.sm) {
                Image(systemName: "questionmark.circle")
                    .symbolRenderingMode(.hierarchical)
                    .foregroundStyle(.secondary)
                    .frame(width: 18)

                Text("Help")

                Spacer(minLength: self.theme.metrics.spacing.sm)

                Image(systemName: "chevron.up.chevron.down")
                    .font(.fluidSystem(size: 10, weight: .semibold))
                    .foregroundStyle(.tertiary)
            }
            .font(self.theme.typography.sidebarItem)
            .padding(.horizontal, self.theme.metrics.spacing.md)
            .frame(maxWidth: .infinity, minHeight: 40, alignment: .leading)
            .contentShape(Rectangle())
        }
        .menuStyle(.button)
        .menuIndicator(.hidden)
        .buttonStyle(SidebarChromeButtonStyle(
            isHovered: self.isHelpEntryHovered,
            reduceMotion: self.accessibilityReduceMotion
        ))
        .onHover { self.isHelpEntryHovered = $0 }
        .help("Open FluidVoice Help")
        .accessibilityLabel("Help")
        .accessibilityHint("What’s new, documentation, Fluid Intelligence demo, and replay onboarding")
    }

    private var modeTransitionAnimation: Animation {
        let duration = self.settingsNavigation.isPresented ? 0.16 : 0.1
        return self.accessibilityReduceMotion
            ? .easeOut(duration: 0.08)
            : .snappy(duration: duration, extraBounce: 0)
    }

    private var sidebarTransitionDistance: CGFloat {
        self.accessibilityReduceMotion ? 0 : 8
    }

    private func sidebarSectionHeader(_ title: String) -> some View {
        Text(title)
            .font(self.theme.typography.sidebarSection)
            .foregroundStyle(.secondary)
            .textCase(nil)
            .padding(.top, self.theme.metrics.spacing.sm)
            .padding(.bottom, self.theme.metrics.spacing.xs)
    }

    private func sidebarNavigationLink(_ item: SidebarItem, title: String, systemImage: String) -> some View {
        let isSelected = self.selectedSidebarItem == item
        return NavigationLink(value: item) {
            HStack(spacing: self.theme.metrics.spacing.sm) {
                Image(nsImage: SidebarSymbolCache.image(named: systemImage))
                    .renderingMode(.template)
                    .resizable()
                    .scaledToFit()
                    .foregroundStyle(isSelected ? Color.white.opacity(0.9) : Color.secondary)
                    .frame(width: 16, height: 16)
                    .accessibilityHidden(true)

                Text(title)
                    .foregroundStyle(isSelected ? Color.white : Color.primary)
            }
            .font(self.theme.typography.sidebarItem)
            .padding(.vertical, self.theme.metrics.spacing.xs / 2)
        }
        .sidebarOptionHover(
            isSelected: isSelected,
            reduceMotion: self.accessibilityReduceMotion
        )
    }

    private var themePreferenceButton: some View {
        Button {
            self.settings.themePreference = self.nextThemePreference(after: self.settings.themePreference)
        } label: {
            Image(systemName: self.settings.themePreference.systemImageName)
                .fluidToolbarIcon()
        }
        .help("Theme: \(self.settings.themePreference.displayName)")
        .accessibilityLabel("Theme")
    }

    private func nextThemePreference(after preference: SettingsStore.ThemePreference) -> SettingsStore.ThemePreference {
        switch preference {
        case .system: return .light
        case .light: return .dark
        case .dark: return .system
        }
    }

    private var todayStatsButton: some View {
        TodayStatsToolbarButton(typingWPM: self.settings.userTypingWPM) {
            self.navigateToApp(.stats)
        }
    }

    private var detailView: some View {
        ZStack {
            self.theme.palette.contentBackground
                .ignoresSafeArea()

            // Preserve the app destination so Back never waits on expensive detail initialization.
            self.appDetailContent
                .environment(\.fluidPageToolbarVisible, self.pagePresentation.showsPageActions)
                .opacity(self.settingsNavigation.isPresented ? 0 : 1)
                .offset(x: self.settingsNavigation.isPresented ? -6 : 0)
                .allowsHitTesting(!self.settingsNavigation.isPresented)
                .accessibilityHidden(self.settingsNavigation.isPresented)

            if self.settingsNavigation.isPresented {
                self.preferencesView
                    .transition(self.settingsDetailTransition)
            }
        }
        .animation(self.modeTransitionAnimation, value: self.settingsNavigation.isPresented)
        .navigationTitle(self.pagePresentation.title)
    }

    private var pagePresentation: AppPagePresentation {
        AppPagePresentation(destination: self.selectedSidebarItem, settings: self.settingsNavigation)
    }

    private var settingsDetailTransition: AnyTransition {
        if self.accessibilityReduceMotion {
            return .opacity
        }
        return .offset(x: 8).combined(with: .opacity)
    }

    private var appDetailContent: AnyView {
        switch self.selectedSidebarItem ?? .welcome {
        case .welcome:
            return AnyView(self.welcomeView)
        case .voiceEngine:
            return AnyView(VoiceEngineSettingsScreen(
                appServices: self.appServices,
                theme: self.theme
            ))
        case .aiEnhancements, .cleanupStyles:
            return AnyView(AIEnhancementSettingsScreen(
                menuBarManager: self.menuBarManager,
                theme: self.theme,
                selectedConfigurationSection: self.aiEnhancementConfigurationSectionBinding,
                activeShortcutRecordingTarget: self.$activeShortcutRecordingTarget,
                shortcutRecordingMessage: self.$shortcutRecordingMessage,
                revealTarget: self.$appSearchRevealTarget
            ))
        case .fileTranscription:
            return AnyView(self.fileTranscriptionView)
        case .meetingTranscription:
            return AnyView(self.meetingTranscriptionView)
        case .customDictionary:
            return AnyView(CustomDictionaryView(revealTarget: self.$appSearchRevealTarget))
        case .stats:
            return AnyView(self.statsView)
        case .feedback:
            return AnyView(FeedbackView())
        case .changelog:
            return AnyView(ChangelogView())
        case .commandMode:
            return AnyView(self.commandModeView)
        case .rewriteMode:
            return AnyView(self.rewriteModeView)
        case .history:
            return AnyView(TranscriptionHistoryView())
        }
    }

    private var aiEnhancementConfigurationSectionBinding: Binding<AIEnhancementConfigurationSection> {
        Binding(
            get: {
                self.selectedSidebarItem?.aiEnhancementConfigurationSection ?? .providers
            },
            set: { section in
                guard self.selectedSidebarItem != section.sidebarItem else { return }
                self.navigateToApp(section.sidebarItem)
            }
        )
    }

    private var onboardingOnlyView: some View {
        OnboardingFlowView(
            currentStep: Binding(
                get: { self.settings.onboardingCurrentStep },
                set: { self.settings.onboardingCurrentStep = $0 }
            ),
            accessibilityEnabled: self.accessibilityEnabled,
            accessibilitySetupInProgress: self.didOpenAccessibilityPane,
            markAISkipped: {
                self.settings.onboardingAISkipped = true
                self.settings.setDictationPromptSelection(.off)
            },
            finishOnboarding: {
                self.completeOnboardingIfPossible()
            },
            finishOnboardingAtGettingStarted: {
                self.completeOnboardingIfPossible(selecting: .welcome)
            },
            openAccessibilitySettings: self.openAccessibilitySettings,
            restartApp: self.restartApp,
            menuBarManager: self.menuBarManager,
            activeShortcutRecordingTarget: self.$activeShortcutRecordingTarget,
            shortcutRecordingMessage: self.$shortcutRecordingMessage,
            theme: self.theme
        )
        .environmentObject(self.appServices)
        .ignoresSafeArea(.container, edges: .top)
    }

    // MARK: - Welcome Guide

    private var welcomeView: some View {
        WelcomeView(
            selectedSidebarItem: self.$selectedSidebarItem,
            accessibilityEnabled: self.accessibilityEnabled,
            openAccessibilitySettings: self.openAccessibilitySettings,
            openFluidIntelligenceDemo: { self.showsFluidIntelligenceDemo = true },
            openShortcutSettings: { self.openSettings(.shortcuts) }
        )
    }

    // MARK: - Microphone Permission View (Kept inline for RecordingView)

    private var microphonePermissionView: some View {
        VStack(alignment: .leading, spacing: 12) {
            HStack(spacing: 12) {
                // Status indicator
                Circle()
                    .fill(self.asr.micStatus == .authorized ? self.theme.palette.success : self.theme.palette.warning)
                    .frame(width: 10, height: 10)

                VStack(alignment: .leading, spacing: 4) {
                    Text(self.labelFor(status: self.asr.micStatus))
                        .fontWeight(.medium)
                        .foregroundStyle(self.asr.micStatus == .authorized ? self.theme.palette.primaryText : self.theme.palette.warning)

                    if self.asr.micStatus != .authorized {
                        Text("Microphone access is required for voice recording")
                            .font(self.theme.typography.caption)
                            .foregroundStyle(.secondary)
                    }
                }
                Spacer()

                self.microphoneActionButton
            }

            // Step-by-step instructions when microphone is not authorized
            if self.asr.micStatus != .authorized {
                self.microphoneInstructionsView
            }
        }
    }

    /// Drawn inside the sidebar rather than as a toolbar item, so no macOS version can
    /// wrap it in its own glass capsule. Sits up in the title bar band, just right of the
    /// traffic lights, well clear of the detail toolbar's glass group.
    /// Same height, font and corner as the section rows below it, so it reads as part of the list.
    private var settingsSearchRow: some View {
        HStack(spacing: self.theme.metrics.spacing.sm) {
            Image(systemName: "magnifyingglass")
                .font(.fluidSystem(size: 13, weight: .medium))
                .foregroundStyle(.secondary)
                .frame(width: 16, height: 16)
            TextField("Search Settings", text: Binding(
                get: { self.settingsSearchQuery },
                set: { self.updateSettingsSearchQuery($0) }
            ))
            .textFieldStyle(.plain)
            .font(self.theme.typography.sidebarItem)
            .focused(self.$isSettingsSearchFocused)
            if !self.settingsSearchQuery.isEmpty {
                Button {
                    self.updateSettingsSearchQuery("")
                } label: {
                    Image(systemName: "xmark.circle.fill")
                        .font(.fluidSystem(size: 12))
                        .foregroundStyle(.secondary)
                }
                .buttonStyle(.plain)
                .accessibilityLabel("Clear search")
            }
        }
        .padding(.horizontal, 8)
        .padding(.vertical, 6)
        .background(
            RoundedRectangle(cornerRadius: 6, style: .continuous)
                .fill(Color.primary.opacity(self.isSettingsSearchFocused ? 0.10 : 0.06))
        )
        .overlay(
            RoundedRectangle(cornerRadius: 6, style: .continuous)
                .strokeBorder(self.theme.palette.accent.opacity(self.isSettingsSearchFocused ? 0.5 : 0), lineWidth: 1)
        )
        .animation(.easeOut(duration: 0.12), value: self.isSettingsSearchFocused)
        .onChange(of: self.settingsNavigation.isPresented) { _, presented in
            if !presented { self.isSettingsSearchFocused = false }
        }
        .accessibilityLabel("Search Settings")
    }

    private func toggleSidebar() {
        withAnimation(self.accessibilityReduceMotion ? nil : .easeInOut(duration: 0.2)) {
            self.columnVisibility = self.columnVisibility == .detailOnly ? .all : .detailOnly
        }
    }

    private var windowSizing: FluidWindowSizing {
        let window = self.theme.metrics.window
        if self.settings.shouldShowOnboarding {
            return .minimum(width: window.onboardingMinWidth, height: window.onboardingMinHeight)
        }
        // Let SwiftUI and the screen choose the upper size; a hard cap can
        // fight the hosting view's content bounds while switching pages.
        return .minimum(width: window.mainMinWidth, height: window.mainMinHeight)
    }

    @ViewBuilder
    private func applyMainWindowToolbar<Content: View>(to content: Content) -> some View {
        if self.settings.shouldShowOnboarding {
            content
        } else {
            content
                .toolbar {
                    // Keep one navigation control alive in both sidebar states. An overlay
                    // belongs to the sidebar content and shifts below AppKit-hosted title bars.
                    ToolbarItem(placement: .navigation) {
                        Button(action: self.toggleSidebar) {
                            Image(systemName: "sidebar.left")
                                .fluidToolbarIcon()
                        }
                        .buttonStyle(.automatic)
                        .help(self.columnVisibility == .detailOnly ? "Show sidebar" : "Hide sidebar")
                        .accessibilityLabel(self.columnVisibility == .detailOnly ? "Show sidebar" : "Hide sidebar")
                    }
                    ToolbarItemGroup(placement: .primaryAction) {
                        UpdateAvailableToolbarButton()

                        self.todayStatsButton
                            .buttonStyle(.automatic)

                        self.themePreferenceButton
                            .buttonStyle(.automatic)

                        Button(action: self.openIssueReportingPage) {
                            Image(systemName: "ladybug.fill")
                                .fluidToolbarIcon()
                        }
                        .buttonStyle(.automatic)
                        .help("Report an issue")
                        .accessibilityLabel("Report an issue")
                    }
                    if !self.hasPageToolbarActions {
                        FluidToolbarEdgeSpace(width: self.toolbarTrailingInset)
                    }
                }
                .toolbar(removing: .sidebarToggle)
        }
    }

    private var hasPageToolbarActions: Bool {
        guard !self.settingsNavigation.isPresented else { return false }
        return switch self.selectedSidebarItem ?? .welcome {
        case .stats, .commandMode, .customDictionary, .changelog: true
        default: false
        }
    }

    private var microphoneActionButton: some View {
        Group {
            if self.asr.micStatus == .notDetermined {
                Button {
                    self.asr.requestMicAccess()
                } label: {
                    HStack(spacing: 6) {
                        Image(systemName: "mic.fill")
                        Text("Grant Access")
                            .fontWeight(.medium)
                    }
                }
                .buttonStyle(GlassButtonStyle())
                .buttonHoverEffect()
            } else if self.asr.micStatus == .denied {
                Button {
                    self.asr.openSystemSettingsForMic()
                } label: {
                    HStack(spacing: 6) {
                        Image(systemName: "gear")
                        Text("Open Settings")
                            .fontWeight(.medium)
                    }
                }
                .buttonStyle(GlassButtonStyle())
                .buttonHoverEffect()
            }
        }
    }

    private var microphoneInstructionsView: some View {
        VStack(alignment: .leading, spacing: 8) {
            HStack(spacing: 8) {
                Image(systemName: "info.circle.fill")
                    .foregroundStyle(self.theme.palette.accent)
                    .font(self.theme.typography.caption)
                Text("How to enable microphone access:")
                    .font(self.theme.typography.caption)
                    .fontWeight(.medium)
                    .foregroundStyle(.secondary)
            }

            VStack(alignment: .leading, spacing: 4) {
                if self.asr.micStatus == .notDetermined {
                    self.instructionStep(number: "1", text: "Click **Grant Access** above")
                    self.instructionStep(number: "2", text: "Choose **Allow** in the system dialog")
                } else if self.asr.micStatus == .denied {
                    self.instructionStep(number: "1", text: "Click **Open Settings** above")
                    self.instructionStep(number: "2", text: "Find **FluidVoice** in the microphone list")
                    self.instructionStep(number: "3", text: "Toggle **FluidVoice ON** to allow access")
                }
            }
            .padding(.leading, 4)
        }
        .padding(12)
        .background(self.theme.palette.accent.opacity(0.12))
        .cornerRadius(8)
    }

    private func instructionStep(number: String, text: String) -> some View {
        HStack(spacing: 8) {
            Text(number + ".")
                .font(self.theme.typography.captionSmall)
                .foregroundStyle(self.theme.palette.accent)
                .fontWeight(.semibold)
                .frame(width: 16)
            Text(text)
                .font(self.theme.typography.caption)
                .foregroundStyle(.primary)
        }
    }

    // MARK: - Preferences View

    @ViewBuilder
    private var preferencesView: some View {
        if self.isSettingsSearchActive, self.settingsSearchResults.isEmpty {
            ContentUnavailableView {
                Label("No Settings Found", systemImage: "magnifyingglass")
            } description: {
                Text("No settings match “\(self.settingsSearchQuery)”.")
            }
            .frame(maxWidth: .infinity, maxHeight: .infinity)
            .accessibilityElement(children: .combine)
        } else {
            SettingsView(
                selectedSection: self.settingsNavigation.selectedSection ?? .general,
                searchResults: self.settingsSearchResults,
                searchScrollRequest: self.settingsSearchScrollRequest,
                microphonePreferenceCoordinator: self.appServices.microphonePreferenceCoordinator,
                appear: self.$appear,
                visualizerNoiseThreshold: self.$visualizerNoiseThreshold,
                selectedInputUID: self.$selectedInputUID,
                selectedOutputUID: self.$selectedOutputUID,
                inputDevices: self.$inputDevices,
                outputDevices: self.$outputDevices,
                accessibilityEnabled: self.$accessibilityEnabled,
                primaryDictationShortcuts: self.$primaryDictationShortcuts,
                activeShortcutRecordingTarget: self.$activeShortcutRecordingTarget,
                shortcutRecordingMessage: self.$shortcutRecordingMessage,
                commandModeShortcut: self.$commandModeHotkeyShortcut,
                rewriteShortcut: self.$rewriteModeHotkeyShortcut,
                cancelRecordingShortcut: self.$cancelRecordingHotkeyShortcut,
                pasteLastTranscriptionShortcut: self.$pasteLastTranscriptionHotkeyShortcut,
                commandModeShortcutEnabled: self.$isCommandModeShortcutEnabled,
                rewriteShortcutEnabled: self.$isRewriteModeShortcutEnabled,
                pasteLastTranscriptionShortcutEnabled: self.$isPasteLastTranscriptionShortcutEnabled,
                hotkeyManagerInitialized: self.$hotkeyManagerInitialized,
                hotkeyMode: self.$hotkeyMode,
                enableStreamingPreview: self.$enableStreamingPreview,
                copyToClipboard: self.$copyToClipboard,
                hotkeyManager: self.hotkeyManager,
                menuBarManager: self.menuBarManager,
                startRecording: { _ = self.startRecording() },
                refreshDevices: self.refreshDevices,
                openAccessibilitySettings: self.openAccessibilitySettings,
                restartApp: self.restartApp,
                revealAppInFinder: self.revealAppInFinder,
                openApplicationsFolder: self.openApplicationsFolder
            )
        }
    }

    private var recordingView: some View {
        RecordingView(
            appear: self.$appear,
            stopAndProcessTranscription: { await self.stopAndProcessTranscription() },
            startRecording: { _ = self.startRecording() }
        )
    }

    private var commandModeView: some View {
        CommandModeView(
            service: self.commandModeService,
            isActive: !self.settingsNavigation.isPresented,
            onClose: {
                self.navigateToApp(.welcome)
            }
        )
    }

    private var rewriteModeView: some View {
        RewriteModeView(service: self.rewriteModeService, onClose: {
            self.navigateToApp(.welcome)
        })
    }

    // MARK: - File and Meeting Transcription

    private var fileTranscriptionView: some View {
        FileTranscriptionView(
            asrService: self.asr,
            transcriptionService: self.appServices.fileTranscriptionService,
            revealTarget: self.$appSearchRevealTarget
        )
    }

    private var meetingTranscriptionView: some View {
        MeetingTranscriptionView(
            coordinator: self.appServices.meetingSessionCoordinator,
            asrService: self.asr,
            historySnapshot: self.meetingHistorySnapshot,
            onOpenVoiceEngine: { self.selectedSidebarItem = .voiceEngine }
        )
    }

    // MARK: - Stats View

    private var statsView: some View {
        StatsView()
    }

    // Audio settings merged into SettingsView

    private func refreshDevices() {
        // Query CoreAudio off the main thread — during device topology changes, synchronous
        // CoreAudio calls on main can deadlock while the HAL is still settling.
        DispatchQueue.global(qos: .userInitiated).async {
            let inputs = AudioDevice.listInputDevicesRefreshingLiveness()
            let outputs = AudioDevice.listOutputDevices()
            let defaultInputUID = AudioDevice.getDefaultInputDevice()?.uid
            DispatchQueue.main.async {
                self.inputDevices = inputs
                self.outputDevices = outputs
                if let selectedInput = self.appServices.microphonePreferenceCoordinator
                    .reconcileMicrophoneSelection(
                        availableInputs: inputs,
                        defaultInputUID: defaultInputUID
                    )
                {
                    self.selectedInputUID = selectedInput.uid
                }
            }
        }
    }

    private func refreshInputDevices() {
        DispatchQueue.global(qos: .userInitiated).async {
            let inputs = AudioDevice.listInputDevicesRefreshingLiveness()
            let defaultInputUID = AudioDevice.getDefaultInputDevice()?.uid
            DispatchQueue.main.async {
                self.inputDevices = inputs
                if let selectedInput = self.appServices.microphonePreferenceCoordinator
                    .reconcileMicrophoneSelection(
                        availableInputs: inputs,
                        defaultInputUID: defaultInputUID
                    )
                {
                    self.selectedInputUID = selectedInput.uid
                }
            }
        }
    }

    // MARK: - Model Management Functions

    private func saveModels() {
        SettingsStore.shared.availableModels = self.availableModels
    }

    // MARK: - Provider Management Functions

    private func providerKey(for providerID: String) -> String {
        let trimmed = providerID.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty else { return "" }

        // Built-in providers use their ID directly
        if ModelRepository.shared.isBuiltIn(trimmed) { return trimmed }
        // Saved providers use their stable id with "custom:" prefix (if not already present)
        if trimmed.hasPrefix("custom:") { return trimmed }
        return "custom:\(trimmed)"
    }

    private func updateCurrentProvider() {
        // Map baseURL to canonical key for built-ins; else keep existing
        let url = self.openAIBaseURL.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
        if url.contains("openai.com") { self.currentProvider = "openai"; return }
        if url.contains("groq.com") { self.currentProvider = "groq"; return }
        // For saved/custom, keep current or derive from selectedProviderID
        self.currentProvider = self.providerKey(for: self.selectedProviderID)
    }

    private func saveSavedProviders() {
        let storedProviders = SettingsStore.shared.savedProviders
        if self.savedProviders.isEmpty, !storedProviders.isEmpty {
            DebugLogger.shared.warning(
                "Skipped stale empty savedProviders write from ContentView.",
                source: "ContentView"
            )
            return
        }
        SettingsStore.shared.savedProviders = self.savedProviders
    }

    // MARK: - App Detection and Context-Aware Prompts

    private func getCurrentAppInfo() -> (name: String, bundleId: String, windowTitle: String) {
        if let frontmostApp = NSWorkspace.shared.frontmostApplication {
            let name = frontmostApp.localizedName ?? "Unknown"
            let bundleId = frontmostApp.bundleIdentifier ?? "unknown"
            let title = self.getFrontmostWindowTitle(ownerPid: frontmostApp.processIdentifier) ?? ""
            return (name: name, bundleId: bundleId, windowTitle: title)
        }
        return (name: "Unknown", bundleId: "unknown", windowTitle: "")
    }

    private func isSpokenSendBlockedApp(
        _ appInfo: (name: String, bundleId: String, windowTitle: String)
    ) -> Bool {
        let identity = "\(appInfo.name) \(appInfo.bundleId)".lowercased()
        return identity.contains("terminal")
            || identity.contains("iterm")
            || identity.contains("warp")
            || identity.contains("ghostty")
            || identity.contains("kitty")
            || identity.contains("alacritty")
    }

    private func deliverSpokenSend(
        _ outputPlan: DictationLiteralOutputPlan,
        targetPID: pid_t?,
        textReadyAt: TimeInterval,
        toggleStopRequestedAt: TimeInterval?,
        preserveTranscriptOnClipboard: Bool,
        stopSnapshot: DictationStopSnapshot? = nil,
        isOutputValid: @escaping @MainActor () -> Bool = { true }
    ) async -> TypingService.DeliveryOutcome {
        let sendsExistingDraft = outputPlan.plainText.isEmpty
        let outcome = await self.asr.typeOutputPlanToActiveFieldAndWait(
            outputPlan,
            preferredTargetPID: targetPID,
            textReadyAt: textReadyAt,
            toggleStopRequestedAt: toggleStopRequestedAt,
            postInsertionKey: self.settings.spokenSendKey,
            requiredFocusTarget: stopSnapshot == nil ? self.recordingFocusTarget : stopSnapshot?.focusTarget,
            preserveTranscriptOnClipboard: preserveTranscriptOnClipboard,
            isOutputValid: isOutputValid
        )
        guard isOutputValid() else { return outcome }
        if outcome.didDispatchAction {
            NotchContentState.shared.setSpokenSendIndicatorState(.sent)
            try? await Task.sleep(nanoseconds: 350_000_000)
            return outcome
        }

        NotchContentState.shared.setSpokenSendIndicatorState(.failed)
        DebugLogger.shared.warning(
            "Spoken Send skipped because delivery safety checks did not pass",
            source: "ContentView"
        )
        let message = outcome.didInsert
            ? "Text inserted — send skipped"
            : sendsExistingDraft ? "Couldn't send" : "Couldn't insert or send"
        NotchOverlayManager.shared.updateTranscriptionText(message)
        try? await Task.sleep(nanoseconds: 650_000_000)
        return outcome
    }

    /// Best-effort frontmost window title lookup for the current app
    private func getFrontmostWindowTitle(ownerPid: pid_t) -> String? {
        let options: CGWindowListOption = [.optionOnScreenOnly, .excludeDesktopElements]
        guard let windowInfo = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] else {
            return nil
        }
        for info in windowInfo {
            guard let pid = info[kCGWindowOwnerPID as String] as? pid_t, pid == ownerPid else { continue }
            if let name = info[kCGWindowName as String] as? String, name.isEmpty == false {
                return name
            }
        }
        return nil
    }

    private func captureRecordingTargetContext() {
        // Capture the focused target PID BEFORE any overlay/UI changes.
        // Used to restore focus when the user interacts with overlay dropdowns.
        let targetContext = TypingService.captureRecordingTargetContext()
        if let targetContext, let element = targetContext.element {
            self.recordingFocusTarget = TypingService.CapturedFocusTarget(
                pid: targetContext.pid,
                window: targetContext.window,
                element: element
            )
        } else {
            self.recordingFocusTarget = TypingService.captureSystemFocusTarget()
        }
        NotchContentState.shared.recordingTargetContext = targetContext
        NotchContentState.shared.recordingTargetPID = targetContext?.pid
            ?? self.recordingFocusTarget?.pid
            ?? NSWorkspace.shared.frontmostApplication?.processIdentifier

        let info = self.getCurrentAppInfo()
        self.recordingAppInfo = info
        self.rewriteModeService.setPromptAppBundleID(info.bundleId)
        DebugLogger.shared.debug(
            "Captured recording app context: app=\(info.name), bundleId=\(info.bundleId), title=\(info.windowTitle)",
            source: "ContentView"
        )
    }

    private func captureRecordingFormattingContextIfNeeded() {
        // Capture text before the caret only when formatting needs focused-field context.
        if SettingsStore.shared.needsDictationFormattingContext {
            self.recordingPrecedingText = TypingService.textBeforeCursorInFocusedField()
            DebugLogger.shared.debug(
                "Captured preceding text for continuous dictation (chars=\(self.recordingPrecedingText.count))",
                source: "ContentView"
            )
        } else {
            self.recordingPrecedingText = ""
        }
    }

    private func captureRecordingContext() {
        self.captureRecordingTargetContext()
        self.captureRecordingFormattingContextIfNeeded()
    }

    /// Starts reading the text around the cursor when the dictation model was
    /// trained to use it. Every other model skips this entirely.
    private func startDictationContextCaptureIfNeeded(for slot: SettingsStore.DictationShortcutSlot) {
        self.cancelDictationContextCapture()
        let route = DictationProviderRoute.resolve(
            settings: .shared,
            dictationSlot: slot,
            appBundleID: self.recordingAppInfo?.bundleId
        )
        guard self.settings.dictationScreenContextEnabled, route.usesPrivateAI,
              PrivateAIIntegrationService.readsDictationContext(model: route.model),
              let target = NotchContentState.shared.recordingTargetContext,
              target.pid != ProcessInfo.processInfo.processIdentifier
        else { return }
        self.dictationContextCapture = DictationContextCapture.start(
            target: target,
            textBeforeCursor: self.settings.needsDictationFormattingContext ? self.recordingPrecedingText : nil,
            settings: .shared
        )
    }

    private func cancelDictationContextCapture() {
        self.dictationContextCapture?.cancel()
        self.dictationContextCapture = nil
    }

    private func attachDictationContext(_ capture: DictationContextCapture, to stopSnapshot: inout DictationStopSnapshot?) async {
        // Context must belong to the exact destination field and a supported local model.
        guard self.settings.dictationScreenContextEnabled,
              let snapshot = stopSnapshot, snapshot.usesAI, snapshot.route.usesPrivateAI,
              PrivateAIIntegrationService.readsDictationContext(model: snapshot.route.model),
              let target = snapshot.target, capture.matches(target)
        else {
            capture.cancel()
            return
        }
        let startedAt = ProcessInfo.processInfo.systemUptime
        let context = await capture.result(timeout: .milliseconds(300))
        guard self.settings.dictationScreenContextEnabled else { return }
        stopSnapshot?.typingContext = context
        self.appBench(
            "dictation_context waitMs=\(Int(((ProcessInfo.processInfo.systemUptime - startedAt) * 1000).rounded())) "
                + "beforeCursorChars=\(context?.textBeforeCursor?.count ?? 0) screenLines=\(context?.screenText?.count ?? 0)"
        )
    }

    private func captureDictationStopSnapshot(slot: SettingsStore.DictationShortcutSlot) -> DictationStopSnapshot {
        let current = TypingService.captureRecordingTargetContext()
        let ownPID = ProcessInfo.processInfo.processIdentifier
        let isOverlay = current?.pid == ownPID && (NSApp.keyWindow == nil || NSApp.keyWindow is NSPanel)
        let useOriginal = self.settings.returnDictationToStartingField || isOverlay
        let target = DictationStopSnapshot.selectTarget(
            current: current,
            original: NotchContentState.shared.recordingTargetContext,
            returnToStartingField: self.settings.returnDictationToStartingField,
            ownOverlayFocused: isOverlay
        )
        let app = target.flatMap { NSRunningApplication(processIdentifier: $0.pid) }
        // Window title and preceding text need WindowServer and Accessibility
        // round-trips; completeDictationStopSnapshot fills them after the
        // microphone has stopped.
        let info = (
            name: app?.localizedName ?? "Unknown",
            bundleId: target?.bundleIdentifier ?? "unknown",
            windowTitle: ""
        )
        if !useOriginal { DictationAppSession.shared.activate(target?.bundleIdentifier) }
        let label = self.settings.dictationOverlayLabel(for: slot, appBundleID: info.bundleId)
        if NotchContentState.shared.stopSnapshotLabel != label {
            NotchContentState.shared.stopSnapshotLabel = label
        }
        return .capture(
            target: target,
            appInfo: info,
            slot: slot,
            precedingText: useOriginal ? self.recordingPrecedingText : "",
            readsContextFromFocusedField: !useOriginal
        )
    }

    private func completeDictationStopSnapshot(_ stopSnapshot: inout DictationStopSnapshot?) {
        guard var snapshot = stopSnapshot else { return }
        let windowTitle = snapshot.target.flatMap { self.getFrontmostWindowTitle(ownerPid: $0.pid) }
        var precedingText: String?
        if snapshot.readsContextFromFocusedField,
           self.settings.needsDictationFormattingContext,
           let target = snapshot.target,
           TypingService.currentFocusedPID() == target.pid
        {
            precedingText = TypingService.textBeforeCursorInFocusedField()
        }
        snapshot.completeContext(windowTitle: windowTitle, precedingText: precedingText)
        stopSnapshot = snapshot
    }

    private func prepareStoppedDictationDelivery(_ text: String, keepBackup: Bool, snapshot: DictationStopSnapshot?, needsRestoration: Bool, isOutputValid: @escaping @MainActor () -> Bool = { true }) async -> Bool {
        if let snapshot { return await snapshot.prepareDelivery(text, keepBackup: keepBackup, isOutputValid: isOutputValid) }
        return await self.prepareRecordingTargetForDelivery(text, keepBackup: keepBackup, needsRestoration: needsRestoration, isOutputValid: isOutputValid)
    }

    private func showStoppedDictationDeliveryFailure(_ failure: TextDeliveryFailure, transcript: String, snapshot: DictationStopSnapshot?) {
        if let snapshot {
            // Retry retains its captured-target behavior, now for the field selected at stop.
            NotchContentState.shared.recordingTargetContext = snapshot.target
            NotchContentState.shared.recordingTargetPID = snapshot.target?.pid
        }
        self.showTextDeliveryFailure(failure, transcript: transcript)
    }

    private func resolveTypingTargetPID(returnToStartingField: Bool = true) -> (pid: pid_t?, shouldRestoreOriginalFocus: Bool) {
        let startedAt = ProcessInfo.processInfo.systemUptime
        let context = NotchContentState.shared.recordingTargetContext
        let focusedPID = TypingService.currentFocusedPID()
        let pidFinishedAt = ProcessInfo.processInfo.systemUptime
        let checksElement = returnToStartingField && context?.pid == focusedPID && context?.element != nil
        let elementIsFocused = !checksElement || context.map { TypingService.isCapturedFocusStillActive($0) } == true
        let target = DictationTargetPolicy.resolve(
            returnToStartingField: returnToStartingField,
            focusedPID: focusedPID,
            ownPID: ProcessInfo.processInfo.processIdentifier,
            originalPID: context?.pid ?? NotchContentState.shared.recordingTargetPID,
            originalFieldIsFocused: context != nil && context?.pid == focusedPID && elementIsFocused
        )
        let finishedAt = ProcessInfo.processInfo.systemUptime
        self.appBench(
            "focus_target_check totalMs=\((finishedAt - startedAt) * 1000) pidMs=\((pidFinishedAt - startedAt) * 1000) " +
                "elementMs=\((finishedAt - pidFinishedAt) * 1000) elementChecked=\(checksElement) returnToStartingField=\(returnToStartingField)"
        )
        return target
    }

    // MARK: - Commented out app-specific prompts - using general processing only

    /*
     private func getContextualPrompt(for appInfo: (name: String, bundleId: String, windowTitle: String)) -> String {
         let appName = appInfo.name
         let bundleId = appInfo.bundleId.lowercased()
         let windowTitle = appInfo.windowTitle.lowercased()

         // Code editors and IDEs
         if bundleId.contains("xcode") || bundleId.contains("vscode") || bundleId.contains("sublime") ||
            bundleId.contains("atom") || bundleId.contains("jetbrains") || bundleId.contains("cursor") ||
            bundleId.contains("vim") || bundleId.contains("emacs") || appName.lowercased().contains("code")
         {
             return "Clean up this transcribed text for code editor \(appName). Make the smallest necessary mechanical edits; do not add or invent content or answer questions. Remove fillers and false starts. Correct programming terms and obvious transcription errors. Preserve meaning and tone."
         }

         // Email applications
         else if bundleId.contains("mail") || bundleId.contains("outlook") || bundleId.contains("thunderbird") ||
                 bundleId.contains("airmail") || bundleId.contains("spark")
         {
             return "Clean up this transcribed text for email app \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix grammar, punctuation, and capitalization while preserving meaning and tone."
         }

         // Messaging and chat applications
         else if bundleId.contains("messages") || bundleId.contains("slack") || bundleId.contains("discord") ||
                 bundleId.contains("telegram") || bundleId.contains("whatsapp") || bundleId.contains("signal") ||
                 bundleId.contains("teams") || bundleId.contains("zoom")
         {
             return "Clean up this transcribed text for messaging app \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix basic grammar and clarity while keeping the casual tone."
         }

         // Document editors and word processors
         else if bundleId.contains("pages") || bundleId.contains("word") || bundleId.contains("docs") ||
                 bundleId.contains("writer") || bundleId.contains("notion") || bundleId.contains("bear") ||
                 bundleId.contains("ulysses") || bundleId.contains("scrivener")
         {
             return "Clean up this transcribed text for document editor \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix grammar, punctuation, and structure while preserving meaning."
         }

         // Note-taking applications
         else if bundleId.contains("notes") || bundleId.contains("obsidian") || bundleId.contains("roam") ||
                 bundleId.contains("logseq") || bundleId.contains("evernote") || bundleId.contains("onenote")
         {
             return "Clean up this transcribed text for note-taking app \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix grammar and organize into clear, readable notes without adding information."
         }

         // Browsers (various web apps). Include: Safari, Chrome, Firefox, Edge, Arc, Brave, Dia, Comet
         else if bundleId.contains("safari") || bundleId.contains("chrome") || bundleId.contains("firefox") ||
                 bundleId.contains("edge") || bundleId.contains("arc") || bundleId.contains("brave") ||
                 bundleId.contains("dia") || bundleId.contains("comet") ||
                 appName.lowercased().contains("safari") || appName.lowercased().contains("chrome") ||
                 appName.lowercased().contains("arc") || appName.lowercased().contains("brave") ||
                 appName.lowercased().contains("dia") || appName.lowercased().contains("comet")
         {
             // Infer common web apps from window title for better context
             if let inferred = inferWebContext(from: windowTitle, appName: appName) {
                 return inferred
             }
             return "Clean up this transcribed text for web browser \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix grammar and basic formatting while preserving meaning."
         }

         // Terminal and command line tools
         else if bundleId.contains("terminal") || bundleId.contains("iterm") || bundleId.contains("console") ||
                 appName.lowercased().contains("terminal")
         {
             return "Clean up this transcribed text for terminal \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix command syntax, file paths, and technical terms without adding options or commands."
         }

         // Social media and creative apps
         else if bundleId.contains("twitter") || bundleId.contains("facebook") || bundleId.contains("instagram") ||
                 bundleId.contains("tiktok") || bundleId.contains("linkedin")
         {
             return "Clean up this transcribed text for social media app \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix basic grammar while keeping the natural, engaging tone."
         }

         // Default fallback
         else
         {
             return "Clean up this transcribed text for \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix grammar, punctuation, and formatting while preserving meaning and tone."
         }
     }
     */

    /*
     /// Infer web-app specific prompt from a browser window title
     private func inferWebContext(from windowTitle: String, appName: String) -> String? {
         let title = windowTitle
         // Email (Gmail, Outlook Web)
         if title.contains("gmail") || title.contains("inbox") || title.contains("outlook") {
             return "Clean up this transcribed text for email app \(appName) (web). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix grammar, punctuation, and capitalization while preserving meaning."
         }
         // Messaging (Slack, Discord, Teams, Telegram, WhatsApp)
         if title.contains("slack") || title.contains("discord") || title.contains("teams") || title.contains("telegram") || title.contains("whatsapp") {
             return "Clean up this transcribed text for messaging app \(appName) (web). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Fix basic grammar and clarity while keeping the casual tone."
         }
         // Documents (Google Docs/Sheets, Notion, Confluence)
         if title.contains("google docs") || title.contains("docs") || title.contains("notion") || title.contains("confluence") || title.contains("google sheets") || title.contains("sheet") {
             return "Clean up this transcribed text for a document editor in \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Improve grammar, structure, and readability without adding information."
         }
         // Code (GitHub, Stack Overflow, online IDEs)
         if title.contains("github") || title.contains("stack overflow") || title.contains("stackexchange") || title.contains("replit") || title.contains("codesandbox") {
             return "Clean up this transcribed text for code-related context in \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Correct programming terms and obvious errors without adding explanations."
         }
         // Project/issue tracking (Jira, Linear, Asana)
         if title.contains("jira") || title.contains("linear") || title.contains("asana") || title.contains("clickup") {
             return "Clean up this transcribed text for project management context in \(appName). Make minimal edits only; do not add or invent content or answer questions. Remove fillers and false starts. Keep the text concise and clear without adding commentary."
         }
         return nil
     }
     */

    // NOTE: Thinking token filtering is now handled by LLMClient.stripThinkingTags()

    // MARK: - Modular AI Processing

    private struct AITextProcessingResult {
        let text: String
        let tokensPerSecond: Double?
        let fluidIntelligenceLatencyMilliseconds: Int?
    }

    private func processTextWithAI(
        _ inputText: String,
        overrideSystemPrompt: String? = nil,
        overrideProviderID: String? = nil,
        overrideModel: String? = nil,
        dictationSlot: SettingsStore.DictationShortcutSlot? = nil,
        streamHandler: PrivateAIStreamHandler? = nil,
        benchmarkID: String? = nil
    ) async throws -> String {
        try await self.processTextWithAIMetrics(
            inputText,
            overrideSystemPrompt: overrideSystemPrompt,
            overrideProviderID: overrideProviderID,
            overrideModel: overrideModel,
            dictationSlot: dictationSlot,
            streamHandler: streamHandler,
            benchmarkID: benchmarkID
        ).text
    }

    private func processTextWithAIMetrics(
        _ inputText: String,
        overrideSystemPrompt: String? = nil,
        overrideProviderID: String? = nil,
        overrideModel: String? = nil,
        dictationSlot: SettingsStore.DictationShortcutSlot? = nil,
        streamHandler: PrivateAIStreamHandler? = nil,
        benchmarkID: String? = nil,
        stopSnapshot: DictationStopSnapshot? = nil
    ) async throws -> AITextProcessingResult {
        guard let summaryActivity = MeetingSummaryActivityCoordinator.shared.beginProcessing() else {
            throw MeetingModelResidencyError.busy
        }
        defer { MeetingSummaryActivityCoordinator.shared.endProcessing(summaryActivity) }

        let routeStartedAt = ProcessInfo.processInfo.systemUptime
        let appInfo = stopSnapshot?.appInfo ?? self.recordingAppInfo ?? self.getCurrentAppInfo()
        let route: DictationProviderRoute
        if let stopSnapshot {
            route = stopSnapshot.route
        } else if let overrideProviderID, let overrideModel {
            route = DictationProviderRoute.resolve(
                settings: SettingsStore.shared,
                providerID: overrideProviderID,
                model: overrideModel
            )
        } else {
            route = DictationProviderRoute.resolve(
                settings: SettingsStore.shared,
                dictationSlot: dictationSlot,
                appBundleID: appInfo.bundleId
            )
        }
        self.appBench(
            "ai_route_resolved elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - routeStartedAt) * 1000).rounded()))"
        )
        let currentSelectedProviderID = route.providerID
        let derivedCurrentProvider = route.providerKey
        let derivedBaseURL = route.baseURL
        let derivedSelectedModel = route.model

        guard !derivedCurrentProvider.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
            throw AIProcessingError.noVerifiedProvider
        }
        if derivedSelectedModel.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
            throw AIProcessingError.missingModel(provider: derivedCurrentProvider)
        }

        DebugLogger.shared.debug("processTextWithAI using provider=\(derivedCurrentProvider), model=\(derivedSelectedModel)", source: "ContentView")

        let isDictationCall = overrideSystemPrompt != nil || dictationSlot != nil
        let isPrivateAIProvider = route.usesPrivateAI
        let usePrivateAIProvider = !(stopSnapshot?.hasCustomPrompt ?? (overrideSystemPrompt != nil)) &&
            isDictationCall &&
            (isPrivateAIProvider || PrivateAIIntegrationService.shouldHandleDictation(model: derivedSelectedModel))

        if usePrivateAIProvider {
            if self.shouldTracePromptProcessing {
                self.logDictationPromptTrace("Private AI Provider task", value: "dictationEnhancement")
                self.logDictationPromptTrace("Input transcription (Q)", value: inputText)
                self.logDictationPromptTrace("Selected context text", value: "<none (dictation mode)>")
                if let typingContext = stopSnapshot?.typingContext {
                    // Sizes only: the typed and screen text are never logged.
                    self.logDictationPromptTrace(
                        "Dictation context",
                        value: "beforeCursorChars=\(typingContext.textBeforeCursor?.count ?? 0) screenLines=\(typingContext.screenText?.count ?? 0)"
                    )
                }
            }

            self.appBench("ai_private_call")
            let fluidIntelligenceStartedAt = ProcessInfo.processInfo.systemUptime
            let response = try await PrivateAIIntegrationService.shared.enhanceDictation(
                inputText,
                runtime: PrivateAIIntegrationService.RuntimeConfiguration(
                    selectedProviderID: currentSelectedProviderID,
                    providerKey: derivedCurrentProvider,
                    baseURL: derivedBaseURL,
                    model: derivedSelectedModel,
                    apiKey: route.apiKey,
                    localModelPath: PrivateAIIntegrationService.configuredLocalModelPath,
                    usesStablePromptPrefixKVCache: SettingsStore.shared.privateAIPrefixKVCacheEnabled,
                    usesFluid1Boost: SettingsStore.shared.privateAIBoostEnabled,
                    contextTokenLimit: SettingsStore.shared.privateAIContextTokenLimit
                ),
                context: PrivateAIIntegrationService.AppContext(
                    appName: appInfo.name,
                    bundleID: appInfo.bundleId,
                    windowTitle: appInfo.windowTitle,
                    appVersion: Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String,
                    textBeforeCursor: stopSnapshot?.typingContext?.textBeforeCursor,
                    screenText: stopSnapshot?.typingContext?.screenText
                ),
                streamHandler: streamHandler
            )
            self.appBench("ai_private_return")
            self.settings.recordFluidIntelligenceUse(output: response.outputText)

            if self.shouldTracePromptProcessing {
                self.logDictationPromptTrace("Model answer (A)", value: response.outputText)
            }
            let tokensPerSecond = response.tokensPerSecond.flatMap { value in
                value.isFinite && value > 0 ? value : nil
            }
            let fluidIntelligenceLatencyMilliseconds = Int(
                ((ProcessInfo.processInfo.systemUptime - fluidIntelligenceStartedAt) * 1000).rounded()
            )
            return AITextProcessingResult(
                text: response.outputText,
                tokensPerSecond: tokensPerSecond,
                fluidIntelligenceLatencyMilliseconds: fluidIntelligenceLatencyMilliseconds
            )
        }

        // Resolve the effective prompt once so every provider path honors
        // transient overrides such as "Transcribe with Prompt".
        let promptText: String = {
            if let stopSnapshot { return stopSnapshot.systemPrompt }
            if let overrideSystemPrompt { return overrideSystemPrompt }
            return self.buildSystemPrompt(appInfo: appInfo, dictationSlot: dictationSlot)
        }()

        // Keep cleanup instructions separate from transcript data. Explicit
        // ${transcript} templates retain their authored single-turn layout.
        let request = isDictationCall
            ? DictationPromptRequest(promptText: promptText, transcript: inputText)
            : DictationPromptRequest(systemPrompt: promptText, userContent: inputText)
        let systemPrompt = request.systemPrompt
        let userMessageContent = request.userContent

        // Skip API key validation for local endpoints
        let isLocal = self.isLocalEndpoint(derivedBaseURL)
        let apiKey = route.apiKey

        if !isLocal {
            guard !apiKey.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines).isEmpty else {
                throw AIProcessingError.missingAPIKey(provider: derivedCurrentProvider)
            }
        }

        DebugLogger.shared.debug("Using app context for AI: app=\(appInfo.name), bundleId=\(appInfo.bundleId), title=\(appInfo.windowTitle)", source: "ContentView")
        if self.shouldTracePromptProcessing {
            let activeSlot = dictationSlot ?? self.currentDictationShortcutSlot(for: self.activeRecordingMode) ?? .primary
            let selectedProfile = SettingsStore.shared.resolvedDictationPromptProfile(
                for: activeSlot,
                appBundleID: appInfo.bundleId
            )
            let selectedPromptName: String = {
                if SettingsStore.shared.dictationPromptSelection(for: activeSlot) == .off {
                    return "Off"
                }
                if let profile = selectedProfile {
                    return profile.name.isEmpty ? "Untitled Prompt" : profile.name
                }
                return "Default"
            }()
            self.logDictationPromptTrace("Selected prompt profile", value: selectedPromptName)
            self.logDictationPromptTrace(
                "Prompt body (custom/default body)",
                value: SettingsStore.shared.effectiveDictationPromptBody(for: activeSlot, appBundleID: appInfo.bundleId)
            )
            self.logDictationPromptTrace("Built-in default system prompt (baseline)", value: SettingsStore.defaultSystemPromptText(for: .dictate))
            self.logDictationPromptTrace("Prompt override in use", value: (overrideSystemPrompt?.isEmpty == false) ? "yes" : "no")
            if let overrideSystemPrompt, !overrideSystemPrompt.isEmpty {
                self.logDictationPromptTrace("Override system prompt", value: overrideSystemPrompt)
            }
            self.logDictationPromptTrace("Final system prompt sent to model", value: systemPrompt)
            self.logDictationPromptTrace("Input transcription (Q)", value: inputText)
            if userMessageContent != inputText {
                self.logDictationPromptTrace("Final user message sent to model", value: userMessageContent)
            }
            self.logDictationPromptTrace("Selected context text", value: "<none (dictation mode)>")
        }

        // Check if this model doesn't support the temperature parameter
        let isTemperatureUnsupported = SettingsStore.shared.isTemperatureUnsupported(derivedSelectedModel, baseURL: derivedBaseURL)

        // Get reasoning config for this model (uses per-model settings or auto-detection)
        // This handles custom parameters like reasoning_effort, enable_thinking, etc.
        let providerKey = self.providerKey(for: currentSelectedProviderID)
        let reasoningConfig = SettingsStore.shared.getReasoningConfig(forModel: derivedSelectedModel, provider: providerKey)

        // Build extra parameters from reasoning config
        var extraParams: [String: Any] = [:]
        if let config = reasoningConfig, config.isEnabled {
            if config.parameterName == "enable_thinking" {
                // DeepSeek uses boolean
                extraParams = [config.parameterName: config.parameterValue == "true"]
            } else {
                // OpenAI/Groq use string values (reasoning_effort, etc.)
                extraParams = [config.parameterName: config.parameterValue]
            }
            DebugLogger.shared.debug(
                "Added reasoning param: \(config.parameterName)=\(config.parameterValue)",
                source: "ContentView"
            )
        }

        let messages = request.messages

        let enableStreaming = streamHandler != nil

        // Build LLMClient configuration
        var config = LLMClient.Config(
            messages: messages,
            model: derivedSelectedModel,
            baseURL: derivedBaseURL,
            apiKey: apiKey,
            streaming: enableStreaming,
            tools: [],
            temperature: isTemperatureUnsupported ? nil : 0.2,
            extraParameters: extraParams,
            benchmarkID: benchmarkID
        )
        if enableStreaming {
            config.onContentChunk = { chunk in
                streamHandler?(chunk)
            }
        }

        DebugLogger.shared.info("Using LLMClient for transcription (streaming=\(enableStreaming))", source: "ContentView")

        let response: LLMClient.Response
        if enableStreaming {
            do {
                response = try await LLMClient.shared.call(config)
            } catch {
                guard DictationStreamingFallbackPolicy.shouldRetryWithoutStreaming(after: error) else {
                    self.appBench("ai_streaming_fallback_skipped reason=transport_or_cancel")
                    throw error
                }
                self.appBench("ai_streaming_fallback_start")
                DebugLogger.shared.warning(
                    "Streaming dictation post-processing failed; retrying without streaming: \(error.localizedDescription)",
                    source: "ContentView"
                )
                let fallbackConfig = LLMClient.Config(
                    messages: messages,
                    model: derivedSelectedModel,
                    baseURL: derivedBaseURL,
                    apiKey: apiKey,
                    streaming: false,
                    tools: [],
                    temperature: isTemperatureUnsupported ? nil : 0.2,
                    extraParameters: extraParams,
                    benchmarkID: benchmarkID
                )
                response = try await LLMClient.shared.call(fallbackConfig)
            }
        } else {
            response = try await LLMClient.shared.call(config)
        }

        // Log thinking if present (for debugging)
        if let thinking = response.thinking {
            DebugLogger.shared.debug("LLM thinking tokens extracted (\(thinking.count) chars)", source: "ContentView")
            if self.shouldTracePromptProcessing {
                self.logDictationPromptTrace("Model thinking", value: thinking)
            }
        }

        if self.shouldTracePromptProcessing {
            self.logDictationPromptTrace("Model answer (A)", value: response.content)
        }

        guard !response.content.isEmpty else {
            throw AIProcessingError.emptyResponse
        }
        return AITextProcessingResult(
            text: response.content,
            tokensPerSecond: nil,
            fluidIntelligenceLatencyMilliseconds: nil
        )
    }

    // MARK: - Streaming Response Handler (DEPRECATED - Now handled by LLMClient)

    // This method is no longer used - LLMClient.call() handles streaming internally

    // MARK: - Stop and Process Transcription

    private func stopAndProcessTranscription(route: DictationOutputRoute = .normal, toggleStopRequestedAt: TimeInterval? = nil) async {
        guard self.processingDictationLifecycleID == nil else { return }
        let outputLifecycleID = self.overlayLifecycleID
        self.processingDictationLifecycleID = outputLifecycleID
        defer {
            if self.processingDictationLifecycleID == outputLifecycleID {
                self.processingDictationLifecycleID = nil
            }
        }
        var closeTrace = OverlayCloseTrace("content.stopCallback")
        defer { closeTrace.finish() }
        let lifecycle = self.overlayLifecycleID
        defer {
            if self.overlayLifecycleID == lifecycle { NotchContentState.shared.stopSnapshotLabel = nil }
        }
        let pipelineID = UUID().uuidString
        await DebugLogger.$pipelineID.withValue(pipelineID) {
            await self.processStoppedTranscription(route: route, pipelineID: pipelineID, toggleStopRequestedAt: toggleStopRequestedAt)
        }
    }

    // Keep the ordered dictation delivery path intact during integration.

    // swiftlint:disable:next function_body_length
    private func processStoppedTranscription(route: DictationOutputRoute, pipelineID: String, toggleStopRequestedAt: TimeInterval?) async {
        let contextCapture = self.dictationContextCapture
        defer {
            contextCapture?.cancel()
            if self.dictationContextCapture === contextCapture { self.dictationContextCapture = nil }
        }
        guard let summaryActivity = MeetingSummaryActivityCoordinator.shared.beginProcessing() else {
            MeetingSummaryActivityCoordinator.presentBusyError()
            return
        }
        defer { MeetingSummaryActivityCoordinator.shared.endProcessing(summaryActivity) }

        let pipelineStartedAt = ProcessInfo.processInfo.systemUptime
        let expectedOverlayLifecycleID = self.overlayLifecycleID
        self.appBench("pipeline_begin id=\(pipelineID) route=\(route.rawValue) toggleStopRequestedAt=\(toggleStopRequestedAt.map { String($0) } ?? "nil") loadAvg1m=\(self.benchmarkLoadAverage())")
        defer {
            self.appBench("pipeline_handler_return id=\(pipelineID) elapsedMs=\((ProcessInfo.processInfo.systemUptime - pipelineStartedAt) * 1000) deliveryMayBePending=true")
        }
        DebugLogger.shared.info("Output route selected: \(route.rawValue)", source: "ContentView")
        self.appBench("stop_path_enter route=\(route.rawValue)")
        let isOnboardingTryout = route == .onboardingSandbox && self.isOnboardingVoicePlaygroundStepActive

        // Check if we're in rewrite or command mode
        let modeAtStop = self.activeRecordingMode
        let wasRewriteMode = modeAtStop == .edit || self.isRecordingForRewrite
        let wasCommandMode = modeAtStop == .command || self.isRecordingForCommand
        let activeDictationSlot = self.currentDictationShortcutSlot(for: modeAtStop)
        let promptOverride = self.promptModeOverrideText
        let promptTest = DictationPromptTestCoordinator.shared
        let promptTestSessionID = promptTest.isActive ? promptTest.sessionID : nil
        var stopSnapshot = route.savesHistory && !wasRewriteMode && !wasCommandMode && !promptTest.isActive
            ? self.captureDictationStopSnapshot(slot: activeDictationSlot ?? .primary) : nil
        let shouldUseAIOnStop = stopSnapshot?.usesAI ?? activeDictationSlot.map {
            DictationAIPostProcessingGate.isConfigured(for: $0, appBundleID: self.recordingAppInfo?.bundleId)
        } ?? DictationAIPostProcessingGate.isConfigured(for: .primary, appBundleID: self.recordingAppInfo?.bundleId)
        let shouldHideOverlayOnStop = route == .historyOnly || self.cancelledOutputLifecycleID == expectedOverlayLifecycleID || (route == .normal && !wasRewriteMode && !wasCommandMode
            && !promptTest.isActive && !shouldUseAIOnStop && !self.settings.spokenSendEnabled)
        DebugLogger.shared.info(
            "Routing decision snapshot | activeMode=\(modeAtStop.rawValue) | rewrite=\(wasRewriteMode) | command=\(wasCommandMode) | overlay=\(NotchContentState.shared.mode.rawValue)",
            source: "ContentView"
        )

        self.clearActiveRecordingMode()
        let stopOverlay = self.prepareOverlayForASRStop(shouldHideOverlayOnStop: shouldHideOverlayOnStop, lifecycleID: expectedOverlayLifecycleID)
        let stopUIInvalidationHold = self.holdStopUIInvalidation(whileProcessing: !stopOverlay.didRequestHide)
        defer { self.releaseStopUIInvalidation(stopUIInvalidationHold) }

        // Stop the ASR service and wait for transcription to complete
        // The processing indicator will stay visible during this phase
        let asrStopStartedAt = ProcessInfo.processInfo.systemUptime
        self.appBench("asr_stop_call")
        // Play the stop cue as soon as the audio engine has stopped, before the
        // (potentially slow) final transcription pass. Scoped to dictation only —
        // Command/Edit modes call asr.stop() without this callback.
        let transcribedText = await asr.stop(
            onCaptureStopped: {
                TranscriptionSoundPlayer.shared.playStopSound()
            },
            onFinalTranscriptionStarted: stopOverlay.onFinalTranscriptionStarted
        )
        self.appBench("asr_stop_return elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - asrStopStartedAt) * 1000).rounded()))")
        self.completeDictationStopSnapshot(&stopSnapshot)
        if let contextCapture, self.overlayLifecycleID == expectedOverlayLifecycleID,
           self.cancelledOutputLifecycleID != expectedOverlayLifecycleID, !Task.isCancelled
        {
            await self.attachDictationContext(contextCapture, to: &stopSnapshot)
        }
        let audioSnapshot = self.asr.consumeLastCompletedAudioSnapshot()
        let dictionaryLearningRecording = self.asr.consumeDictionaryLearningRecording()
        let transcriptionDurationMilliseconds = self.asr.consumeLastFinalTranscriptionDurationMs()
        let parakeetProcessingDurationMilliseconds = self.asr.consumeLastFinalParakeetProcessingMs()
        DebugLogger.shared.info(
            "Stop transcription result | chars=\(transcribedText.count) | empty=\(transcribedText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)",
            source: "ContentView"
        )

        guard transcribedText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false else {
            // Empty results have no delivery callback, so clear their stale
            // preview before the existing empty-result dismissal path runs.
            NotchOverlayManager.shared.updateTranscriptionText("")
            DebugLogger.shared.debug("Transcription returned empty text", source: "ContentView")
            if isOnboardingTryout {
                if self.asr.lastStopOutcome == .failed {
                    AnalyticsService.shared.recordOnboardingTryoutAttemptResult(
                        outcome: .error,
                        failureStage: .transcription
                    )
                } else {
                    AnalyticsService.shared.recordOnboardingTryoutAttemptResult(outcome: .empty)
                }
            }
            if route == .normal, !wasRewriteMode, !wasCommandMode, !promptTest.isActive {
                self.recordEmptyDictationPerformance(startedAt: pipelineStartedAt, asrMs: transcriptionDurationMilliseconds)
            }
            // Finish the same short exit transition even when no text is emitted.
            if !stopOverlay.didRequestHide {
                await self.menuBarManager.finishProcessingAndHideOverlay()
            }
            return
        }

        let cancelledAtASRStop = route == .historyOnly || self.cancelledOutputLifecycleID == expectedOverlayLifecycleID
        if cancelledAtASRStop, promptTestSessionID != nil || route == .onboardingSandbox { return }

        // Prompt Test Mode: reroute dictation hotkey output into the prompt editor (no typing/clipboard/history).
        if !cancelledAtASRStop, await self.routePromptTestResult(transcribedText, sessionID: promptTestSessionID, lifecycleID: expectedOverlayLifecycleID) {
            return
        }

        if NotchOverlayManager.shared.isBottomOverlayVisible {
            BottomOverlayWindowController.shared.beginReleaseTransition()
        }

        // If this was a rewrite recording, process the rewrite instead of typing
        if wasRewriteMode {
            guard !cancelledAtASRStop else {
                self.rewriteModeService.clearState()
                return
            }
            DebugLogger.shared.info("Processing rewrite instruction (\(transcribedText.count) chars)", source: "ContentView")
            AnalyticsService.shared.recordModelUsage(
                role: .transcription,
                mode: .edit,
                descriptor: self.settings.selectedSpeechModel.analyticsDescriptor
            )
            let appInfo = self.recordingAppInfo ?? self.getCurrentAppInfo()
            await self.processRewriteWithVoiceInstruction(transcribedText, appInfo: appInfo, lifecycleID: expectedOverlayLifecycleID)
            return
        }

        // If this was a command recording, process the command
        if wasCommandMode {
            guard !cancelledAtASRStop else { return }
            DebugLogger.shared.info("Processing command (\(transcribedText.count) chars)", source: "ContentView")
            AnalyticsService.shared.recordModelUsage(
                role: .transcription,
                mode: .command,
                descriptor: self.settings.selectedSpeechModel.analyticsDescriptor
            )
            await self.processCommandWithVoice(transcribedText, lifecycleID: expectedOverlayLifecycleID)
            return
        }

        var finalText: String
        var aiFallbackReason: String?
        var postProcessingModel: String?
        var aiProcessingDurationMilliseconds: Int?
        var aiTokensPerSecond: Double?
        var aiFallbackNotificationError: String?
        let appInfo = stopSnapshot?.appInfo ?? self.recordingAppInfo ?? self.getCurrentAppInfo()
        let punctuationFormattedText = ASRService.applySpokenPunctuationFormatting(
            transcribedText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        let spokenSendParse = SpokenSendParser.parseArmed(
            punctuationFormattedText,
            phrase: self.settings.spokenSendPhrase,
            enabled: !cancelledAtASRStop && route.deliversText && self.settings.spokenSendEnabled,
            wasArmed: self.spokenSendArming.wasArmed
        )
        self.updateSpokenSendIndicatorForFinalParse(shouldSend: spokenSendParse.shouldSend)
        let normalizedTranscribedText = spokenSendParse.text
        var sendsExistingDraft = spokenSendParse.shouldSend &&
            normalizedTranscribedText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty

        let practiceModelID = route == .onboardingSandbox && self.settings.onboardingCurrentStep == 5
            ? PrivateAIProviderPromptFormat.verifiedModelID(settings: self.settings) : nil
        let shouldUseAI = !sendsExistingDraft && (practiceModelID != nil || (stopSnapshot?.usesAI ?? DictationAIPostProcessingGate.isConfigured(
            for: activeDictationSlot ?? .primary,
            appBundleID: appInfo.bundleId
        )))
        let transcriptionModelInfo = self.currentTranscriptionModelInfo()
        let postProcessingModelInfo = self.recordDictationUsage(
            shouldUseAI: shouldUseAI,
            dictationSlot: activeDictationSlot,
            appBundleID: appInfo.bundleId,
            snapshot: stopSnapshot
        )

        if shouldUseAI {
            DebugLogger.shared.debug("Routing transcription through AI post-processing", source: "ContentView")
            postProcessingModel = postProcessingModelInfo.model
            let postProcessingInputChars = normalizedTranscribedText.count
            let postProcessingStart = ProcessInfo.processInfo.systemUptime
            let processingFeedback = self.makeAIProcessingFeedback(lifecycleID: expectedOverlayLifecycleID)
            let refiningStatusTask = processingFeedback.statusTask
            defer { refiningStatusTask.cancel() }

            let streamPreview = processingFeedback.streamPreview
            let streamHandler: PrivateAIStreamHandler = { chunk in
                streamPreview.append(chunk)
            }

            do {
                self.logAIProcessCall(pipelineID, postProcessingModelInfo, postProcessingInputChars)
                let result = try await self.processTextWithAIMetrics(
                    normalizedTranscribedText,
                    overrideSystemPrompt: promptOverride,
                    overrideProviderID: practiceModelID == nil ? nil : PrivateAIProviderFeature.shared.providerID,
                    overrideModel: practiceModelID,
                    dictationSlot: activeDictationSlot,
                    streamHandler: streamHandler,
                    benchmarkID: pipelineID,
                    stopSnapshot: stopSnapshot
                )
                refiningStatusTask.cancel()
                finalText = result.text
                self.appBench("ai_process_return id=\(pipelineID)")
                aiTokensPerSecond = result.tokensPerSecond
                streamPreview.flush()
                self.appBench("ai_preview_flushed id=\(pipelineID)")
            } catch {
                refiningStatusTask.cancel()
                self.appBench("ai_process_fail id=\(pipelineID)")
                // Fall back to the raw transcription so the user still gets
                // their words typed instead of an error string.
                DebugLogger.shared.error(
                    "AI post-processing failed, falling back to raw transcription: \(error.localizedDescription)",
                    source: "ContentView"
                )
                aiFallbackReason = error.localizedDescription
                aiFallbackNotificationError = DictationAIFailurePresentationPolicy.notificationMessage(for: error)
                finalText = normalizedTranscribedText
            }
            let postProcessingLatencyMs = Int(
                ((ProcessInfo.processInfo.systemUptime - postProcessingStart) * 1000).rounded()
            )
            aiProcessingDurationMilliseconds = postProcessingLatencyMs
            let postProcessingProviderName = postProcessingModelInfo.provider ?? "unknown"
            let postProcessingModelName = postProcessingModelInfo.model ?? "unknown"
            DebugLogger.shared.info(
                "Dictation AI post-processing finished in \(postProcessingLatencyMs)ms "
                    + "provider=\(postProcessingProviderName) model=\(postProcessingModelName) "
                    + "inputChars=\(postProcessingInputChars) fallback=\(aiFallbackReason != nil)",
                source: "ContentView"
            )
        } else {
            finalText = normalizedTranscribedText
        }

        // Normalize literal command and mention syntax after AI cleanup and before final user preferences.
        finalText = ASRService.applyDictationLiteralFormatting(
            finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        // Apply GAAV formatting as the FINAL step (after AI post-processing)
        // This ensures the user's preference for no capitalization/period is respected
        finalText = ASRService.applyGAAVFormatting(finalText)
        // Apply Continuous Dictation Mode after GAAV so smart caps use the field
        // context captured at recording start, and the trailing space enables chaining.
        finalText = ASRService.applyContinuousDictationFormatting(finalText, precedingText: stopSnapshot?.precedingText ?? self.recordingPrecedingText)
        finalText = ASRService.applyTerminalLiteralAutocompleteSpacing(
            finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        self.recordingPrecedingText = ""
        let outputRoute: DictationOutputRoute = route == .normal && self.cancelledOutputLifecycleID == expectedOverlayLifecycleID ? .historyOnly : route
        if outputRoute == .historyOnly, sendsExistingDraft {
            // Keep the spoken words recoverable when Escape cancels a send-only draft.
            sendsExistingDraft = false
            finalText = ASRService.applyGAAVFormatting(punctuationFormattedText)
        }
        if outputRoute.publishesEditorResult, self.cancelledOutputLifecycleID != expectedOverlayLifecycleID { self.asr.finalText = finalText }
        if route == .onboardingSandbox,
           self.cancelledOutputLifecycleID != expectedOverlayLifecycleID,
           self.isOnboardingVoicePlaygroundStepActive,
           !finalText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
        {
            AnalyticsService.shared.finishOnboardingTryout(
                outcome: .success,
                failureStage: aiFallbackReason == nil ? nil : .postProcessing
            )
            self.settings.onboardingPlaygroundValidated = true
            self.settings.playgroundUsed = true
            self.playgroundUsed = true
        }

        DebugLogger.shared.info("Transcription finalized (chars: \(finalText.count))", source: "ContentView")
        let finalTextReadyAt = ProcessInfo.processInfo.systemUptime
        self.recordCompletedDictationPerformance(
            route: route,
            pipelineStartedAt: pipelineStartedAt,
            readyAt: finalTextReadyAt,
            transcriptionDurationMilliseconds: transcriptionDurationMilliseconds,
            aiProcessingDurationMilliseconds: aiProcessingDurationMilliseconds,
            fluidModel: AnalyticsFluidIntelligenceModel(modelID: postProcessingModel),
            tokensPerSecond: aiTokensPerSecond,
            outcome: aiFallbackReason == nil ? "success" : "ai_fallback"
        )
        let finalOutputPlan = ASRService.makeDictationLiteralOutputPlan(
            for: finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        self.appBench("transcription_finalized chars=\(finalText.count)")
        self.appBench("text_ready chars=\(finalText.count)")
        self.appBench("pipeline_text_ready id=\(pipelineID) stopToReadyMs=\((finalTextReadyAt - pipelineStartedAt) * 1000)")

        let shouldPersistOutputs = outputRoute.savesHistory
        let shouldDeliverOutputs = outputRoute.deliversText
        if !shouldPersistOutputs {
            DebugLogger.shared.info(
                "Sandbox route active: suppressing clipboard/history/external typing side effects",
                source: "ContentView"
            )
        }

        let shouldShowAIProcessingFailure = DictationAIFailurePresentationPolicy.shouldPresent(
            shouldPersistOutputs: shouldDeliverOutputs,
            fallbackReason: aiFallbackReason
        )
        if !shouldShowAIProcessingFailure {
            self.pendingAIReprocessText = nil
        }

        let isFluidFrontmost = stopSnapshot
            .map { $0.target?.pid == ProcessInfo.processInfo.processIdentifier } ?? (NSWorkspace.shared.frontmostApplication?.bundleIdentifier == Bundle.main.bundleIdentifier)

        // Save to transcription history (transcription mode only, if enabled)
        if shouldPersistOutputs, !sendsExistingDraft, SettingsStore.shared.saveTranscriptionHistory {
            let historyEntryID = UUID()
            let historyTimestamp = Date()
            TranscriptionHistoryStore.shared.addEntry(
                id: historyEntryID,
                timestamp: historyTimestamp,
                rawText: outputRoute.deliversText && spokenSendParse.shouldSend ? normalizedTranscribedText : transcribedText,
                processedText: finalText,
                appName: appInfo.name,
                windowTitle: appInfo.windowTitle,
                wasAIProcessed: postProcessingModel != nil && aiFallbackReason == nil,
                processingModel: postProcessingModel,
                transcriptionDurationMilliseconds: transcriptionDurationMilliseconds,
                parakeetProcessingDurationMilliseconds: parakeetProcessingDurationMilliseconds,
                aiProcessingDurationMilliseconds: aiProcessingDurationMilliseconds,
                aiTokensPerSecond: aiTokensPerSecond,
                aiProcessingError: aiFallbackReason
            )
            self.persistDictationAudioIfNeeded(
                audioSnapshot,
                entryID: historyEntryID,
                timestamp: historyTimestamp,
                model: transcriptionModelInfo.model
            )
        }
        // When FluidVoice itself is frontmost, the bound editor already receives `finalText`.
        let shouldCopyToClipboard = shouldDeliverOutputs &&
            !sendsExistingDraft &&
            SettingsStore.shared.copyTranscriptionToClipboard
        let shouldTypeExternally = shouldDeliverOutputs && !isFluidFrontmost

        // Send-only stops normally have no History row. Recover their words if
        // Escape arrives after the output decision but before delivery completes.
        func saveCancelledSendOnlyHistory() {
            guard sendsExistingDraft, self.settings.saveTranscriptionHistory else { return }
            let id = UUID()
            let timestamp = Date()
            TranscriptionHistoryStore.shared.addEntry(
                id: id,
                timestamp: timestamp,
                rawText: transcribedText,
                processedText: ASRService.applyGAAVFormatting(punctuationFormattedText),
                appName: appInfo.name,
                windowTitle: appInfo.windowTitle,
                wasAIProcessed: false,
                processingModel: nil,
                transcriptionDurationMilliseconds: transcriptionDurationMilliseconds
            )
            self.persistDictationAudioIfNeeded(audioSnapshot, entryID: id, timestamp: timestamp, model: transcriptionModelInfo.model)
        }

        var didTypeExternally = false
        var didFailTextDelivery = false

        self.appBench("typing_decision snapshotTarget=\(stopSnapshot != nil) external=\(shouldTypeExternally)")

        // A sidebar search field that was already focused when recording began gets
        // the text through its field editor, which also fires change notifications.
        // So does an in-app editor that opted in with `DictationTextTarget`.
        if isFluidFrontmost, shouldDeliverOutputs, !sendsExistingDraft,
           let focusTarget = self.recordingFocusTarget,
           focusTarget.pid == ProcessInfo.processInfo.processIdentifier,
           TypingService.isExactFocusTargetActive(focusTarget),
           let window = NSApp.keyWindow,
           let editor = window.firstResponder as? NSTextView,
           SidebarSearchField.owns(editor, in: window) || DictationTextTarget.accepts(editor)
        {
            editor.insertText(finalText, replacementRange: editor.selectedRange())
        }

        if shouldTypeExternally {
            let typingTarget = stopSnapshot.map { (pid: $0.target?.pid, shouldRestoreOriginalFocus: true) }
                ?? self.resolveTypingTargetPID(returnToStartingField: self.settings.returnDictationToStartingField)
            let spokenSendRequested = spokenSendParse.shouldSend
            let sendFocus = stopSnapshot == nil ? self.recordingFocusTarget : stopSnapshot?.focusTarget
            let targetMatchesRecordingFocus = typingTarget.pid != nil
                && typingTarget.pid == sendFocus?.pid
            let spokenSendAllowed = spokenSendRequested
                && aiFallbackReason == nil
                && (sendsExistingDraft || !finalText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
                && targetMatchesRecordingFocus
                && (typingTarget.shouldRestoreOriginalFocus || sendFocus.map { TypingService.isExactFocusTargetActive($0) } == true)
                && !self.isSpokenSendBlockedApp(appInfo)
            // Dispatch insertion as soon as the destination app is ready; the
            // overlay hides asynchronously after output so it cannot delay paste.
            let focusReady = await self.prepareStoppedDictationDelivery(
                finalText,
                keepBackup: shouldCopyToClipboard,
                snapshot: stopSnapshot,
                needsRestoration: typingTarget.shouldRestoreOriginalFocus,
                isOutputValid: { self.cancelledOutputLifecycleID != expectedOverlayLifecycleID }
            )
            // Escape can arrive while focus restoration is suspended; History is already saved.
            guard self.cancelledOutputLifecycleID != expectedOverlayLifecycleID else {
                saveCancelledSendOnlyHistory()
                return
            }

            if spokenSendAllowed {
                NotchContentState.shared.setSpokenSendIndicatorState(.sending)
                NotchOverlayManager.shared.updateTranscriptionText("Sending")
            }

            let deliveryResult: TextDeliveryResult
            if !focusReady {
                deliveryResult = .recoverableFailure(.targetRestoreFailed)
            } else if spokenSendAllowed {
                self.appBench(
                    "text_ready_to_type_request elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - finalTextReadyAt) * 1000).rounded()))"
                )
                let deliveryOutcome = await self.deliverSpokenSend(
                    finalOutputPlan,
                    targetPID: typingTarget.pid,
                    textReadyAt: finalTextReadyAt,
                    toggleStopRequestedAt: toggleStopRequestedAt,
                    preserveTranscriptOnClipboard: shouldCopyToClipboard,
                    stopSnapshot: stopSnapshot,
                    isOutputValid: { self.cancelledOutputLifecycleID != expectedOverlayLifecycleID }
                )
                self.logPipelineCompletion(
                    outcome: String(describing: deliveryOutcome),
                    pipelineID: pipelineID,
                    pipelineStartedAt: pipelineStartedAt,
                    textReadyAt: finalTextReadyAt
                )
                didTypeExternally = deliveryOutcome.didInsert
                deliveryResult = deliveryOutcome.didInsert || deliveryOutcome.didDispatchAction
                    ? .commandPosted
                    : .recoverableFailure(.pasteCommandFailed)
            } else {
                self.appBench(
                    "text_ready_to_type_request elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - finalTextReadyAt) * 1000).rounded()))"
                )
                deliveryResult = await self.asr.typeOutputPlanToActiveField(
                    finalOutputPlan,
                    preferredTargetPID: typingTarget.pid,
                    textReadyAt: finalTextReadyAt,
                    toggleStopRequestedAt: toggleStopRequestedAt,
                    tracksDictionaryCorrections: true,
                    preserveTranscriptOnClipboard: shouldCopyToClipboard,
                    isOutputValid: { self.cancelledOutputLifecycleID != expectedOverlayLifecycleID }
                )
                didTypeExternally = deliveryResult.wasDispatched
                self.handleTypingDelivery(
                    deliveryResult.wasDispatched ? .inserted : .insertionFailed,
                    pipelineID: pipelineID,
                    pipelineStartedAt: pipelineStartedAt,
                    textReadyAt: finalTextReadyAt,
                    shouldHideOverlay: deliveryResult.wasDispatched && !shouldShowAIProcessingFailure && !stopOverlay.didRequestHide && !spokenSendRequested,
                    expectedOverlayLifecycleID: expectedOverlayLifecycleID
                )
            }

            guard self.overlayLifecycleID == expectedOverlayLifecycleID, self.cancelledOutputLifecycleID != expectedOverlayLifecycleID else {
                if self.cancelledOutputLifecycleID == expectedOverlayLifecycleID { saveCancelledSendOnlyHistory() }
                self.appBench("delivery_ui_skipped reason=stale_recording")
                return
            }
            if spokenSendRequested, !spokenSendAllowed {
                NotchContentState.shared.setSpokenSendIndicatorState(.failed)
                DebugLogger.shared.warning(
                    "Spoken Send skipped because delivery safety checks did not pass",
                    source: "ContentView"
                )
                if aiFallbackReason == nil {
                    NotchOverlayManager.shared.updateTranscriptionText("Text inserted — send skipped")
                    try? await Task.sleep(nanoseconds: 650_000_000)
                }
            }
            guard self.overlayLifecycleID == expectedOverlayLifecycleID else { return }
            NotchContentState.shared.setSpokenSendIndicatorState(.hidden)

            if case let .recoverableFailure(failure) = deliveryResult {
                didFailTextDelivery = true
                self.showStoppedDictationDeliveryFailure(failure, transcript: finalText, snapshot: stopSnapshot)
            } else if !shouldShowAIProcessingFailure, !stopOverlay.didRequestHide {
                self.hideOverlayAfterOutput()
            }
            // Delivery UI must complete before correction tracking queries Accessibility.
            if didTypeExternally, !spokenSendAllowed {
                AutomaticDictionaryCorrectionTracker.shared.beginObservingInsertion(
                    finalOutputPlan.plainText,
                    targetPID: typingTarget.pid,
                    learningRecording: dictionaryLearningRecording
                )
                self.appBench("dictionary_tracking_scheduled afterDeliveryUI=true")
            }
        }

        if !shouldTypeExternally {
            await PasteDeliveryCoordinator.shared.copyBackup(finalText, enabled: shouldCopyToClipboard, isOutputValid: { self.cancelledOutputLifecycleID != expectedOverlayLifecycleID })
        }

        guard self.cancelledOutputLifecycleID != expectedOverlayLifecycleID || outputRoute == .historyOnly else { return }

        // Submit raw fallback delivery before failure UI or notification work can
        // compete with it on the main actor. Sandbox runs never present either.
        if shouldShowAIProcessingFailure {
            self.pendingAIReprocessText = spokenSendParse.shouldSend ? normalizedTranscribedText : transcribedText
            NotchContentState.shared.showAIProcessingFailure()
            self.menuBarManager.finishProcessingKeepingOverlayVisible()
            if let aiFallbackNotificationError {
                NotificationService.showAIProcessingFallback(error: aiFallbackNotificationError)
            }
        }

        if !didTypeExternally, !shouldShowAIProcessingFailure, !didFailTextDelivery, !stopOverlay.didRequestHide {
            self.hideOverlayAfterOutput()
        }
        if !shouldTypeExternally {
            self.logPipelineCompletion(
                outcome: outputRoute == .historyOnly ? "history_only" : (shouldPersistOutputs ? "internal_editor" : "sandbox"),
                pipelineID: pipelineID,
                pipelineStartedAt: pipelineStartedAt,
                textReadyAt: finalTextReadyAt
            )
        }
    }

    private func processDictationPromptTest(_ transcribedText: String, lifecycleID: UInt64) async {
        let promptTest = DictationPromptTestCoordinator.shared
        let sessionID = promptTest.sessionID
        promptTest.lastTranscriptionText = transcribedText
        promptTest.lastOutputText = ""
        promptTest.lastError = ""
        guard DictationAIPostProcessingGate.isProviderConfigured(
            providerID: promptTest.draftProviderID,
            model: promptTest.draftModel
        ) else {
            promptTest.lastError = "AI post-processing is not configured. Configure a provider/model (and API key for non-local endpoints) to test prompts."
            if self.overlayLifecycleID == lifecycleID {
                self.menuBarManager.setProcessing(false)
            }
            return
        }
        promptTest.isProcessing = true
        let refiningStatusTask = self.makeAIProcessingFeedback(lifecycleID: lifecycleID).statusTask
        defer {
            refiningStatusTask.cancel()
            if self.overlayLifecycleID == lifecycleID {
                self.menuBarManager.setProcessing(false)
            }
            if promptTest.sessionID == sessionID { promptTest.isProcessing = false }
        }
        do {
            let result = try await self.processTextWithAI(
                transcribedText,
                overrideSystemPrompt: promptTest.usesBuiltInPrompt ? nil : promptTest.draftPromptText,
                overrideProviderID: promptTest.draftProviderID,
                overrideModel: promptTest.draftModel,
                dictationSlot: promptTest.usesBuiltInPrompt ? .primary : nil
            )
            let appInfo = self.recordingAppInfo ?? self.getCurrentAppInfo()
            let literalFormattedResult = ASRService.applyDictationLiteralFormatting(
                result,
                appName: appInfo.name,
                bundleID: appInfo.bundleId,
                windowTitle: appInfo.windowTitle
            )
            guard promptTest.acceptsResult(for: sessionID), self.cancelledOutputLifecycleID != lifecycleID else { return }
            promptTest.lastOutputText = ASRService.applyGAAVFormatting(literalFormattedResult)
        } catch {
            guard promptTest.acceptsResult(for: sessionID), self.cancelledOutputLifecycleID != lifecycleID else { return }
            DebugLogger.shared.error("Prompt test AI call failed: \(error.localizedDescription)", source: "ContentView")
            promptTest.lastError = error.localizedDescription
        }
    }

    private func routePromptTestResult(_ text: String, sessionID: UUID?, lifecycleID: UInt64) async -> Bool {
        guard let sessionID else { return false }
        // A closed/replaced practice session must never fall through to external typing.
        guard DictationPromptTestCoordinator.shared.acceptsResult(for: sessionID) else {
            if self.overlayLifecycleID == lifecycleID { self.menuBarManager.setProcessing(false) }
            return true
        }
        await self.processDictationPromptTest(text, lifecycleID: lifecycleID)
        return true
    }

    private func makeAIProcessingFeedback(
        lifecycleID: UInt64
    ) -> (statusTask: Task<Void, Never>, streamPreview: DictationAIStreamPreviewBuffer) {
        // Fast local cleanup should finish before transient SwiftUI work can queue
        // ahead of its result. Slow providers still receive visible status feedback.
        let statusTask = scheduleDeferredMainActorOperation(
            afterNanoseconds: Self.aiProcessingStatusDelayNanoseconds
        ) {
            guard self.overlayLifecycleID == lifecycleID, self.cancelledOutputLifecycleID != lifecycleID else {
                self.appBench("processing_ui_skipped status=Refining reason=stale_lifecycle")
                return
            }
            self.menuBarManager.flushDeferredStoppedRecordingState()
            self.menuBarManager.setProcessing(true)
            self.appBench("processing_ui_request status=Refining trigger=delayed_status")
            NotchOverlayManager.shared.updateTranscriptionText("Refining")
            self.appBench("processing_ui_requested status=Refining trigger=delayed_status")
        }
        let streamPreview = DictationAIStreamPreviewBuffer { text in
            guard self.overlayLifecycleID == lifecycleID, self.cancelledOutputLifecycleID != lifecycleID else { return }
            NotchOverlayManager.shared.updateTranscriptionText(text)
        }
        return (statusTask, streamPreview)
    }

    private func prepareOverlayForASRStop(
        shouldHideOverlayOnStop: Bool, lifecycleID: UInt64
    ) -> (didRequestHide: Bool, onFinalTranscriptionStarted: (@MainActor () -> Void)?) {
        if shouldHideOverlayOnStop {
            DebugLogger.shared.debug("Hiding dictation overlay at stop path", source: "ContentView")
            self.hideOverlayAsync(reason: "stop_path")
            return (true, nil)
        }

        guard self.asr.isFinalTranscriptionReady else {
            DebugLogger.shared.debug("Showing transcription processing state", source: "ContentView")
            self.appBench("processing_ui_request status=Transcribing")
            self.menuBarManager.setProcessing(true)
            NotchOverlayManager.shared.updateTranscriptionText("Transcribing")
            self.appBench("processing_ui_requested status=Transcribing")
            return (false, nil)
        }

        // Own the overlay before isRunning changes, but publish processing UI
        // only after final ASR has entered its executor.
        self.menuBarManager.reserveProcessingOverlay()
        self.appBench("processing_ui_reserved trigger=warm_final_asr")
        let onFinalTranscriptionStarted: @MainActor () -> Void = {
            guard self.overlayLifecycleID == lifecycleID, self.cancelledOutputLifecycleID != lifecycleID else { return }
            self.menuBarManager.flushDeferredStoppedRecordingState()
            self.appBench("processing_ui_request status=Transcribing trigger=final_executor")
            self.menuBarManager.setProcessing(true)
            NotchOverlayManager.shared.updateTranscriptionText("Transcribing")
            self.appBench("processing_ui_requested status=Transcribing trigger=final_executor")
        }
        return (false, onFinalTranscriptionStarted)
    }

    private func holdStopUIInvalidation(whileProcessing: Bool) -> UInt64? {
        whileProcessing ? self.asr.holdStopUIInvalidationForOutputPipeline() : nil
    }

    private func releaseStopUIInvalidation(_ generation: UInt64?) {
        guard let generation else { return }
        self.asr.releaseStopUIInvalidationForOutputPipeline(generation)
    }

    private func hideOverlayForDispatchedPaste(shouldHide: Bool, lifecycleID: UInt64) {
        guard shouldHide, self.overlayLifecycleID == lifecycleID else { return }
        self.appBench("overlay_hide_request reason=paste_dispatched")
        self.menuBarManager.beginProcessingCompletionAndHideOverlay()
    }

    private func handleTypingDelivery(
        _ outcome: TypingService.DeliveryOutcome,
        pipelineID: String,
        pipelineStartedAt: TimeInterval,
        textReadyAt: TimeInterval,
        shouldHideOverlay: Bool,
        expectedOverlayLifecycleID: UInt64
    ) {
        self.logPipelineCompletion(
            outcome: String(describing: outcome),
            pipelineID: pipelineID,
            pipelineStartedAt: pipelineStartedAt,
            textReadyAt: textReadyAt
        )
        guard shouldHideOverlay else { return }
        guard self.overlayLifecycleID == expectedOverlayLifecycleID else {
            self.appBench(
                "overlay_hide_skipped reason=delivery_complete staleLifecycle=\(expectedOverlayLifecycleID) currentLifecycle=\(self.overlayLifecycleID)"
            )
            return
        }
        // Preserve delivery-timed dismissal for the send-suppressed status path.
        // Ordinary dictation already hid in the dispatch turn and returns above.
        self.appBench("overlay_hide_request reason=delivery_complete outcome=\(outcome)")
        self.menuBarManager.beginProcessingCompletionAndHideOverlay()
    }

    private func logPipelineCompletion(
        outcome: String,
        pipelineID: String,
        pipelineStartedAt: TimeInterval,
        textReadyAt: TimeInterval
    ) {
        let finishedAt = ProcessInfo.processInfo.systemUptime
        DebugLogger.shared.info(
            "PIPELINE_SUMMARY id=\(pipelineID) t=\(finishedAt) " +
                "stopToReadyMs=\((textReadyAt - pipelineStartedAt) * 1000) readyToDeliveryMs=\((finishedAt - textReadyAt) * 1000) " +
                "totalMs=\((finishedAt - pipelineStartedAt) * 1000) outcome=\(outcome)",
            source: "AppBenchmark"
        )
    }

    private func recordCompletedDictationPerformance(
        route: DictationOutputRoute,
        pipelineStartedAt: TimeInterval,
        readyAt: TimeInterval = ProcessInfo.processInfo.systemUptime,
        transcriptionDurationMilliseconds: Int?,
        aiProcessingDurationMilliseconds: Int?,
        fluidModel: AnalyticsFluidIntelligenceModel?,
        tokensPerSecond: Double?,
        outcome: String
    ) {
        guard route == .normal else { return }
        let readyMilliseconds = Int(((readyAt - pipelineStartedAt) * 1000).rounded())
        DebugLogger.shared.info(
            DictationPerformanceLogSummary.line(
                asrMilliseconds: transcriptionDurationMilliseconds,
                aiMilliseconds: aiProcessingDurationMilliseconds,
                readyMilliseconds: readyMilliseconds,
                outcome: outcome
            ),
            source: "AppBenchmark"
        )
        AnalyticsService.shared.recordBetaDictationPerformance(
            fluidModel: fluidModel,
            tokensPerSecond: tokensPerSecond
        )
    }

    private func recordEmptyDictationPerformance(startedAt: TimeInterval, asrMs: Int?) {
        self.recordCompletedDictationPerformance(
            route: .normal,
            pipelineStartedAt: startedAt,
            transcriptionDurationMilliseconds: asrMs,
            aiProcessingDurationMilliseconds: nil,
            fluidModel: nil,
            tokensPerSecond: nil,
            outcome: self.asr.lastStopOutcome == .failed ? "asr_failed" : "empty"
        )
    }

    private func hideOverlayAfterOutput() {
        self.hideOverlayAsync(reason: "after_output")
    }

    private func updateSpokenSendIndicatorForFinalParse(shouldSend: Bool) {
        if shouldSend, NotchContentState.shared.spokenSendIndicatorState == .sending {
            return
        }
        NotchContentState.shared.setSpokenSendIndicatorState(shouldSend ? .detected : .hidden)
    }

    private func showTextDeliveryFailure(_ failure: TextDeliveryFailure, transcript: String) {
        let failure = failure != .emptyText && !AXIsProcessTrusted() ? TextDeliveryFailure.accessibilityNotTrusted : failure
        DebugLogger.shared.warning("Text delivery failed: \(failure.rawValue)", source: "ContentView")
        NotchContentState.shared.recordTextDeliveryFailure(failure, transcript: transcript)
        guard failure.userFacingMessage != nil else {
            self.hideOverlayAfterOutput()
            return
        }
        self.menuBarManager.finishProcessingKeepingOverlayVisible()
    }

    /// Shows why Edit Mode can't run, for a few seconds. A missing model only happens
    /// when Edit Mode is set to run on this Mac, so only then is there a Download button.
    private func showEditModeFailure(_ message: String) {
        let needsModel = message == EditModeRoute.modelMissing.failureMessage
        self.menuBarManager.setOverlayMode(.edit)
        self.advanceOverlayLifecycle()
        let expectedOverlayLifecycleID = self.overlayLifecycleID
        self.menuBarManager.showRecordingOverlayImmediately()
        NotchContentState.shared.showAIProcessingFailure(
            message: message,
            canRetry: false,
            downloadAction: needsModel ? {
                EditModeModelController.shared.download()
                self.menuBarManager.openAISettings()
            } : nil
        )
        self.menuBarManager.finishProcessingKeepingOverlayVisible()

        Task { @MainActor in
            try? await Task.sleep(for: .seconds(needsModel ? 10 : 6))
            guard self.overlayLifecycleID == expectedOverlayLifecycleID else { return }
            NotchContentState.shared.clearAIProcessingFailure()
            await self.menuBarManager.finishProcessingAndHideOverlay()
        }
    }

    private func advanceOverlayLifecycle() {
        self.cancelDictationContextCapture()
        self.spokenSendAutoStopTask?.cancel()
        self.spokenSendAutoStopTask = nil
        self.stopSpokenSendVoiceActivityMonitoring()
        self.spokenSendAutoStopTriggered = false
        self.spokenSendArming.reset()
        self.spokenSendCountdownStartedAt = nil
        self.spokenSendLastVoiceActivityAt = ProcessInfo.processInfo.systemUptime
        self.overlayLifecycleID &+= 1
        NotchContentState.shared.clearAIProcessingFailure()
        NotchContentState.shared.clearTextDeliveryFailure()
    }

    private func handleSpokenSendPartialTranscription(_ text: String) {
        guard self.settings.spokenSendEnabled else { return }
        let isDictationMode = self.activeRecordingMode == .dictate || self.activeRecordingMode == .promptMode
        let isEligible = isDictationMode &&
            self.cancelledOutputLifecycleID != self.overlayLifecycleID &&
            self.currentDictationOutputRouteForHotkeyStop() == .normal &&
            self.asr.isRunning &&
            !self.spokenSendAutoStopTriggered
        let isArmed = self.spokenSendArming.update(
            partial: text,
            isEligible: isEligible,
            phrase: self.settings.spokenSendPhrase
        )

        guard self.settings.spokenSendImmediatelyEnabled else {
            if isEligible {
                NotchContentState.shared.setSpokenSendIndicatorState(isArmed ? .detected : .hidden)
            }
            return
        }

        guard isArmed else {
            self.spokenSendAutoStopTask?.cancel()
            self.spokenSendAutoStopTask = nil
            self.stopSpokenSendVoiceActivityMonitoring()
            self.spokenSendCountdownStartedAt = nil
            if !self.spokenSendAutoStopTriggered,
               NotchContentState.shared.spokenSendIndicatorState == .countingDown
            {
                NotchContentState.shared.setSpokenSendIndicatorState(.hidden)
            }
            return
        }

        guard self.spokenSendAutoStopTask == nil else {
            return
        }

        let expectedOverlayLifecycleID = self.overlayLifecycleID
        let countdownStartedAt = ProcessInfo.processInfo.systemUptime
        self.spokenSendCountdownStartedAt = countdownStartedAt
        self.spokenSendLastVoiceActivityAt = countdownStartedAt
        self.startSpokenSendVoiceActivityMonitoring()
        let expectedCountdownID = NotchContentState.shared.beginSpokenSendCountdown()
        self.spokenSendAutoStopTask = Task { @MainActor in
            // Keep one countdown across harmless streaming refinements such as punctuation or casing.
            try? await Task.sleep(nanoseconds: SpokenSendParser.immediateStopSettleNanoseconds)
            let quietDuration = ProcessInfo.processInfo.systemUptime - self.spokenSendLastVoiceActivityAt
            guard !Task.isCancelled,
                  self.overlayLifecycleID == expectedOverlayLifecycleID,
                  NotchContentState.shared.spokenSendCountdownID == expectedCountdownID,
                  self.asr.isRunning,
                  self.activeRecordingMode == .dictate || self.activeRecordingMode == .promptMode,
                  self.currentDictationOutputRouteForHotkeyStop() == .normal,
                  !self.spokenSendAutoStopTriggered,
                  SpokenSendParser.canCompleteImmediateStop(
                      self.asr.partialTranscription,
                      phrase: self.settings.spokenSendPhrase,
                      spokenSendEnabled: self.settings.spokenSendEnabled,
                      sendImmediatelyEnabled: self.settings.spokenSendImmediatelyEnabled,
                      quietDuration: quietDuration,
                      armedText: self.spokenSendArming.armedText
                  )
            else {
                if self.overlayLifecycleID == expectedOverlayLifecycleID,
                   NotchContentState.shared.spokenSendCountdownID == expectedCountdownID
                {
                    self.spokenSendAutoStopTask = nil
                    self.stopSpokenSendVoiceActivityMonitoring()
                    self.spokenSendCountdownStartedAt = nil
                    if NotchContentState.shared.spokenSendIndicatorState == .countingDown {
                        NotchContentState.shared.setSpokenSendIndicatorState(.hidden)
                    }
                }
                return
            }

            self.spokenSendAutoStopTask = nil
            self.stopSpokenSendVoiceActivityMonitoring()
            self.spokenSendCountdownStartedAt = nil
            self.spokenSendAutoStopTriggered = true
            NotchContentState.shared.setSpokenSendIndicatorState(.sending)
            DebugLogger.shared.info("Spoken Send countdown completed; stopping dictation", source: "ContentView")
            await self.stopAndProcessTranscription(route: .normal)
        }
    }

    private func handleSpokenSendAudioLevel(_ level: CGFloat) {
        guard SpokenSendParser.isMeaningfulVoiceActivity(level) else { return }

        let activityAt = ProcessInfo.processInfo.systemUptime
        self.spokenSendLastVoiceActivityAt = activityAt
        guard let countdownStartedAt = self.spokenSendCountdownStartedAt,
              SpokenSendParser.shouldCancelCountdownForVoiceActivity(
                  countdownStartedAt: countdownStartedAt,
                  voiceActivityAt: activityAt
              ),
              self.spokenSendAutoStopTask != nil
        else {
            return
        }

        self.spokenSendAutoStopTask?.cancel()
        self.spokenSendAutoStopTask = nil
        self.stopSpokenSendVoiceActivityMonitoring()
        self.spokenSendCountdownStartedAt = nil
        if NotchContentState.shared.spokenSendIndicatorState == .countingDown {
            NotchContentState.shared.setSpokenSendIndicatorState(.hidden)
        }
    }

    private func startSpokenSendVoiceActivityMonitoring() {
        guard self.spokenSendVoiceActivityCancellable == nil else { return }
        self.spokenSendVoiceActivityCancellable = self.asr.audioLevelPublisher
            .receive(on: RunLoop.main)
            .sink { level in
                self.handleSpokenSendAudioLevel(level)
            }
    }

    private func stopSpokenSendVoiceActivityMonitoring() {
        self.spokenSendVoiceActivityCancellable?.cancel()
        self.spokenSendVoiceActivityCancellable = nil
    }

    private func hideOverlayAsync(reason: String) {
        let expectedOverlayLifecycleID = self.overlayLifecycleID
        self.appBench("overlay_hide_request reason=\(reason) lifecycle=\(expectedOverlayLifecycleID)")
        Task { @MainActor in
            guard self.overlayLifecycleID == expectedOverlayLifecycleID else {
                self.appBench(
                    "overlay_hide_skipped reason=\(reason) staleLifecycle=\(expectedOverlayLifecycleID) currentLifecycle=\(self.overlayLifecycleID)"
                )
                return
            }

            let overlayHideStartedAt = ProcessInfo.processInfo.systemUptime
            await self.menuBarManager.finishProcessingAndHideOverlay()
            self.appBench(
                "overlay_hidden reason=\(reason) elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - overlayHideStartedAt) * 1000).rounded()))"
            )
        }
    }

    private func persistDictationAudioIfNeeded(
        _ snapshot: DictationAudioSnapshot?,
        entryID: UUID,
        timestamp: Date,
        model: String
    ) {
        guard SettingsStore.shared.saveTranscriptionHistory,
              SettingsStore.shared.saveAudioWithTranscriptionHistory,
              let snapshot = snapshot
        else {
            return
        }
        let saveGeneration = TranscriptionHistoryStore.shared.audioSaveGeneration

        Task.detached(priority: .utility) {
            let result: (metadata: DictationAudioMetadata?, error: String?) = {
                do {
                    let metadata = try DictationAudioHistoryStore.shared.save(
                        snapshot: snapshot,
                        entryID: entryID,
                        timestamp: timestamp,
                        model: model
                    )
                    return (metadata, nil)
                } catch {
                    return (nil, error.localizedDescription)
                }
            }()

            await MainActor.run {
                if let metadata = result.metadata {
                    TranscriptionHistoryStore.shared.attachAudio(
                        metadata,
                        to: entryID,
                        expectedSaveGeneration: saveGeneration
                    )
                } else if let error = result.error {
                    DebugLogger.shared.error("Failed to save dictation audio: \(error)", source: "ContentView")
                }
            }
            if let metadata = result.metadata {
                DictationAudioHistoryStore.shared.completePendingSave(fileName: metadata.fileName)
            }
        }
    }

    private var isOnboardingVoicePlaygroundStepActive: Bool {
        let onboardingPlaygroundStep = 4
        return !self.settings.onboardingCompleted &&
            self.settings.onboardingCurrentStep == onboardingPlaygroundStep
    }

    private var isOnboardingSandboxRouteActive: Bool {
        let onboardingAIEnhancementStep = 5
        return self.isOnboardingVoicePlaygroundStepActive ||
            (!self.settings.onboardingCompleted && self.settings.onboardingCurrentStep == onboardingAIEnhancementStep)
    }

    private func currentDictationOutputRouteForHotkeyStop() -> DictationOutputRoute {
        let isDictationMode = self.activeRecordingMode == .dictate || self.activeRecordingMode == .promptMode

        if OnboardingDictationOutputPolicy.usesSandbox(
            onboardingPracticeActive: self.isOnboardingSandboxRouteActive,
            isDictation: isDictationMode,
            targetProcessID: NotchContentState.shared.recordingTargetPID,
            fluidVoiceProcessID: ProcessInfo.processInfo.processIdentifier
        ) {
            return .onboardingSandbox
        }
        return .normal
    }

    private func reprocessLastDictation() {
        if let pendingText = self.pendingAIReprocessText?.trimmingCharacters(in: .whitespacesAndNewlines),
           !pendingText.isEmpty
        {
            DebugLogger.shared.info("Actions: Reprocessing pending failed dictation", source: "ContentView")
            Task { @MainActor in
                await self.reprocessDictationText(pendingText)
            }
            return
        }

        guard let last = TranscriptionHistoryStore.shared.entries.first else {
            DebugLogger.shared.info("Actions: Reprocess requested but history is empty", source: "ContentView")
            return
        }

        let rawText = last.rawText.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !rawText.isEmpty else {
            DebugLogger.shared.info("Actions: Reprocess skipped because latest history raw text is empty", source: "ContentView")
            return
        }

        DebugLogger.shared.info("Actions: Reprocessing latest dictation history entry", source: "ContentView")
        Task { @MainActor in
            await self.reprocessDictationText(rawText)
        }
    }

    private func copyLastDictationFromHistory() {
        guard let text = TranscriptionHistoryStore.shared.latestClipboardText else {
            DebugLogger.shared.info("Actions: Copy requested but no transcription is available", source: "ContentView")
            return
        }

        _ = ClipboardService.copyToClipboard(text)
        DebugLogger.shared.info("Actions: Copied latest transcription to clipboard", source: "ContentView")
    }

    /// Re-inserts the most recent transcription into the focused text field using the same
    /// clipboard-free insertion path as live dictation. Unlike copy, this never touches the
    /// system clipboard, and unlike reprocess, it pastes the existing text verbatim (no new
    /// history entry, no reformatting). Useful when the original auto-insert dropped the tail.
    private func pasteLastDictationFromHistory() {
        guard let last = TranscriptionHistoryStore.shared.entries.first else {
            DebugLogger.shared.info("Actions: Paste requested but history is empty", source: "ContentView")
            return
        }

        // Prefer the processed text (what was actually delivered, possibly AI-enhanced),
        // falling back to raw for older entries or when enhancement was off.
        let processed = last.processedText.trimmingCharacters(in: .whitespacesAndNewlines)
        let raw = last.rawText.trimmingCharacters(in: .whitespacesAndNewlines)
        let text = processed.isEmpty ? raw : processed
        guard !text.isEmpty else {
            DebugLogger.shared.info("Actions: Paste skipped because latest history text is empty", source: "ContentView")
            return
        }

        Task { @MainActor in
            // Only one paste may be pending at a time. Because the paste waits for the modifier keys
            // to release, a quick double/triple-tap of the chord would otherwise queue several Tasks
            // that all insert at once on release. This collapses them to a single paste while still
            // allowing a deliberate repeat (press, it lands, then press again).
            guard !Self.isPasteLastInProgress else {
                DebugLogger.shared.info("Actions: Paste skipped - a paste is already pending", source: "ContentView")
                return
            }
            Self.isPasteLastInProgress = true
            defer { Self.isPasteLastInProgress = false }

            // The hotkey fires on key-down while its own modifier keys (e.g. ⌘⌃) are still
            // physically held. Synthesizing text in that state makes the target app treat the
            // characters as keyboard shortcuts and drop them, so the paste lands once the keys are
            // released — effectively "paste when you let go". The timeout is generous so a normal
            // hold (or a quick repeated press) still pastes on release; it only aborts if a modifier
            // is genuinely stuck, rather than typing a corrupted/destructive shortcut sequence.
            guard await Self.waitForHotkeyModifiersReleased(timeout: 5) else {
                DebugLogger.shared.info("Actions: Paste aborted - modifier keys still held after timeout", source: "ContentView")
                return
            }

            // Re-check here rather than only at the hotkey trigger: the overlay menu entry point
            // has no pre-check, and the wait above may have elapsed since the trigger fired.
            guard !self.asr.isRunning else {
                DebugLogger.shared.info("Actions: Paste skipped - recording in progress", source: "ContentView")
                return
            }

            // Paste Last is a new insertion at the current cursor, independent of
            // the previous recording's saved target. Never restore that older focus here.
            guard let targetPID = TypingService.currentFocusedPID(), targetPID != ProcessInfo.processInfo.processIdentifier else {
                DebugLogger.shared.info("Actions: Paste skipped - no external target field available", source: "ContentView")
                return
            }
            let appInfo = self.getCurrentAppInfo()
            let outputPlan = ASRService.makeDictationLiteralOutputPlan(
                for: text,
                appName: appInfo.name,
                bundleID: appInfo.bundleId,
                windowTitle: appInfo.windowTitle
            )
            let result = await self.asr.typeOutputPlanToActiveField(
                outputPlan,
                preferredTargetPID: targetPID
            )
            if case let .recoverableFailure(failure) = result {
                self.showTextDeliveryFailure(failure, transcript: text)
            } else {
                DebugLogger.shared.info("Actions: Pasted latest transcription into focused field", source: "ContentView")
            }
        }
    }

    @MainActor
    private func retryTextDelivery(_ transcript: String) async {
        guard !transcript.isEmpty else { return }

        self.menuBarManager.setProcessing(true)
        NotchOverlayManager.shared.updateTranscriptionText("Inserting")
        let typingTarget = self.resolveTypingTargetPID()
        if typingTarget.shouldRestoreOriginalFocus,
           !(await self.prepareRecordingTargetForDelivery(transcript, keepBackup: SettingsStore.shared.copyTranscriptionToClipboard))
        {
            self.showTextDeliveryFailure(.targetRestoreFailed, transcript: transcript)
            return
        }

        let result = await self.asr.typeTextToActiveField(
            transcript,
            preferredTargetPID: typingTarget.pid,
            preserveTranscriptOnClipboard: SettingsStore.shared.copyTranscriptionToClipboard
        )
        if case let .recoverableFailure(failure) = result {
            self.showTextDeliveryFailure(failure, transcript: transcript)
        } else {
            self.hideOverlayAfterOutput()
        }
    }

    /// Guards against overlapping paste insertions: only one "paste last transcription" may be
    /// pending at a time (see pasteLastDictationFromHistory). A rapid re-tap while one is still
    /// waiting for the modifier keys to release is ignored rather than queuing a duplicate insert.
    /// Only ever touched on the main actor.
    private static var isPasteLastInProgress = false

    /// Polls until the keyboard modifier keys are released, returning `true` once they are, or
    /// `false` if the timeout elapses with keys still held. Used before synthesizing a paste so the
    /// inserted characters aren't swallowed as modifier+key shortcuts.
    private static func waitForHotkeyModifiersReleased(timeout: TimeInterval) async -> Bool {
        let relevant: CGEventFlags = [.maskCommand, .maskControl, .maskAlternate, .maskShift, .maskSecondaryFn]
        let start = Date()
        while Date().timeIntervalSince(start) < timeout {
            let flags = CGEventSource.flagsState(.combinedSessionState)
            if flags.isDisjoint(with: relevant) {
                return true
            }
            try? await Task.sleep(nanoseconds: 15_000_000) // 15ms
        }
        return false
    }

    private func undoLastAIProcessingFromHistory() {
        guard let last = TranscriptionHistoryStore.shared.entries.first else {
            DebugLogger.shared.info("Actions: Undo AI requested but history is empty", source: "ContentView")
            return
        }

        let rawText = last.rawText.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !rawText.isEmpty else {
            DebugLogger.shared.info("Actions: Undo AI skipped because latest history raw text is empty", source: "ContentView")
            return
        }

        guard last.wasAIProcessed else {
            DebugLogger.shared.info("Actions: Undo AI skipped because latest entry was not AI processed", source: "ContentView")
            return
        }

        DebugLogger.shared.info("Actions: Restoring latest transcription raw text (undo AI)", source: "ContentView")
        Task { @MainActor in
            await self.applyHistoryTextOutput(rawText, saveToHistory: true)
        }
    }

    private func applyHistoryTextOutput(_ text: String, saveToHistory: Bool) async {
        // Keep hotkey/recording state deterministic before applying output text.
        if self.asr.isRunning {
            DebugLogger.shared.info("Actions: stopping active recording before history action output", source: "ContentView")
            await self.asr.stopWithoutTranscription()
            self.cancelPrewarmDictationIfNeeded()
            self.cancelDictationContextCapture()
        }

        let appInfo = self.getCurrentAppInfo()
        let literalFormattedText = ASRService.applyDictationLiteralFormatting(
            text,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        let gaavText = ASRService.applyGAAVFormatting(literalFormattedText)
        let precedingText = SettingsStore.shared.needsDictationFormattingContext
            ? TypingService.textBeforeCursorInFocusedField()
            : ""
        var finalText = ASRService.applyContinuousDictationFormatting(gaavText, precedingText: precedingText)
        finalText = ASRService.applyTerminalLiteralAutocompleteSpacing(
            finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        let outputPlan = ASRService.makeDictationLiteralOutputPlan(
            for: finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )

        if saveToHistory, SettingsStore.shared.saveTranscriptionHistory {
            TranscriptionHistoryStore.shared.addEntry(
                rawText: text,
                processedText: finalText,
                appName: appInfo.name,
                windowTitle: appInfo.windowTitle,
                wasAIProcessed: false
            )
        }

        let frontmostApp = NSWorkspace.shared.frontmostApplication
        let isFluidFrontmost = frontmostApp?.bundleIdentifier == Bundle.main.bundleIdentifier

        let targetContext = TypingService.captureRecordingTargetContext()
        NotchContentState.shared.recordingTargetContext = targetContext
        NotchContentState.shared.recordingTargetPID = targetContext?.pid

        let shouldTypeExternally = !isFluidFrontmost
        if shouldTypeExternally {
            let typingTarget = self.resolveTypingTargetPID()
            if typingTarget.shouldRestoreOriginalFocus {
                guard await self.prepareRecordingTargetForDelivery(finalText, keepBackup: SettingsStore.shared.copyTranscriptionToClipboard) else {
                    self.showTextDeliveryFailure(.targetRestoreFailed, transcript: finalText)
                    return
                }
            }
            let result = await self.asr.typeOutputPlanToActiveField(
                outputPlan,
                preferredTargetPID: typingTarget.pid,
                preserveTranscriptOnClipboard: SettingsStore.shared.copyTranscriptionToClipboard
            )
            if case let .recoverableFailure(failure) = result {
                self.showTextDeliveryFailure(failure, transcript: finalText)
            }
        } else {
            await PasteDeliveryCoordinator.shared.copyBackup(finalText, enabled: SettingsStore.shared.copyTranscriptionToClipboard)
        }
    }

    private func reprocessDictationText(_ transcribedText: String) async {
        // If live recording is still active, stop it first so reprocess does not
        // leave ASR running in the background (which causes the next hotkey press
        // to behave like a stop instead of start).
        if self.asr.isRunning {
            DebugLogger.shared.info("Actions: stopping active recording before reprocess", source: "ContentView")
            await self.asr.stopWithoutTranscription()
            self.cancelPrewarmDictationIfNeeded()
            self.cancelDictationContextCapture()
        }

        self.setActiveRecordingMode(.dictate)
        self.menuBarManager.setProcessing(true)
        NotchOverlayManager.shared.updateTranscriptionText("Reprocessing...")

        var aiFallbackReason: String?
        var postProcessingModel: String?
        var aiProcessingDurationMilliseconds: Int?
        var aiTokensPerSecond: Double?
        var aiFallbackNotificationError: String?
        let appInfo = self.getCurrentAppInfo()
        let normalizedTranscribedText = ASRService.applySpokenPunctuationFormatting(
            transcribedText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        var finalText = normalizedTranscribedText
        let shouldUseAI = DictationAIPostProcessingGate.isConfigured(for: .primary, appBundleID: appInfo.bundleId)
        if shouldUseAI {
            postProcessingModel = self.currentDictationAIModelInfo(
                dictationSlot: .primary,
                appBundleID: appInfo.bundleId
            ).model
            let postProcessingStart = ProcessInfo.processInfo.systemUptime
            do {
                let result = try await self.processTextWithAIMetrics(
                    normalizedTranscribedText,
                    dictationSlot: .primary
                )
                finalText = result.text
                aiTokensPerSecond = result.tokensPerSecond
            } catch {
                DebugLogger.shared.error(
                    "AI reprocess failed, falling back to raw transcription: \(error.localizedDescription)",
                    source: "ContentView"
                )
                aiFallbackReason = error.localizedDescription
                aiFallbackNotificationError = DictationAIFailurePresentationPolicy.notificationMessage(for: error)
                finalText = normalizedTranscribedText
            }
            aiProcessingDurationMilliseconds = Int(
                ((ProcessInfo.processInfo.systemUptime - postProcessingStart) * 1000).rounded()
            )
        }

        finalText = ASRService.applyDictationLiteralFormatting(
            finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        finalText = ASRService.applyGAAVFormatting(finalText)
        let precedingText = SettingsStore.shared.needsDictationFormattingContext
            ? TypingService.textBeforeCursorInFocusedField()
            : ""
        finalText = ASRService.applyContinuousDictationFormatting(finalText, precedingText: precedingText)
        finalText = ASRService.applyTerminalLiteralAutocompleteSpacing(
            finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )
        self.recordingPrecedingText = ""
        let outputPlan = ASRService.makeDictationLiteralOutputPlan(
            for: finalText,
            appName: appInfo.name,
            bundleID: appInfo.bundleId,
            windowTitle: appInfo.windowTitle
        )

        if SettingsStore.shared.saveTranscriptionHistory {
            TranscriptionHistoryStore.shared.addEntry(
                rawText: transcribedText,
                processedText: finalText,
                appName: appInfo.name,
                windowTitle: appInfo.windowTitle,
                wasAIProcessed: postProcessingModel != nil && aiFallbackReason == nil,
                processingModel: postProcessingModel,
                aiProcessingDurationMilliseconds: aiProcessingDurationMilliseconds,
                aiTokensPerSecond: aiTokensPerSecond,
                aiProcessingError: aiFallbackReason
            )
        }
        let shouldShowAIProcessingFailure = DictationAIFailurePresentationPolicy.shouldPresent(
            shouldPersistOutputs: true,
            fallbackReason: aiFallbackReason
        )
        if !shouldShowAIProcessingFailure {
            self.pendingAIReprocessText = nil
        }

        let targetContext = TypingService.captureRecordingTargetContext()
        NotchContentState.shared.recordingTargetContext = targetContext
        NotchContentState.shared.recordingTargetPID = targetContext?.pid

        let frontmostApp = NSWorkspace.shared.frontmostApplication
        let isFluidFrontmost = frontmostApp?.bundleIdentifier?.contains("fluid") == true
        let shouldTypeExternally = !isFluidFrontmost || self.isTranscriptionFocused == false
        if shouldTypeExternally {
            let typingTarget = self.resolveTypingTargetPID()
            if typingTarget.shouldRestoreOriginalFocus {
                guard await self.prepareRecordingTargetForDelivery(finalText, keepBackup: SettingsStore.shared.copyTranscriptionToClipboard) else {
                    self.showTextDeliveryFailure(.targetRestoreFailed, transcript: finalText)
                    return
                }
            }
            let result = await self.asr.typeOutputPlanToActiveField(
                outputPlan,
                preferredTargetPID: typingTarget.pid,
                preserveTranscriptOnClipboard: SettingsStore.shared.copyTranscriptionToClipboard
            )
            if case let .recoverableFailure(failure) = result {
                self.showTextDeliveryFailure(failure, transcript: finalText)
                return
            }
        } else {
            await PasteDeliveryCoordinator.shared.copyBackup(finalText, enabled: SettingsStore.shared.copyTranscriptionToClipboard)
        }

        NotchOverlayManager.shared.updateTranscriptionText("")
        if shouldShowAIProcessingFailure {
            self.pendingAIReprocessText = transcribedText
            NotchContentState.shared.showAIProcessingFailure()
            self.menuBarManager.finishProcessingKeepingOverlayVisible()
            if let aiFallbackNotificationError {
                NotificationService.showAIProcessingFallback(error: aiFallbackNotificationError)
            }
        } else {
            self.hideOverlayAfterOutput()
        }

        self.clearActiveRecordingMode()
    }

    // MARK: - Rewrite Mode Voice Processing

    private func processRewriteWithVoiceInstruction(
        _ instruction: String,
        appInfo: (name: String, bundleId: String, windowTitle: String),
        lifecycleID: UInt64
    ) async {
        let isOutputValid: @MainActor () -> Bool = { self.overlayLifecycleID == lifecycleID && self.cancelledOutputLifecycleID != lifecycleID }
        guard isOutputValid() else { return }
        defer {
            if !isOutputValid() { self.rewriteModeService.clearState() }
        }
        self.rewriteModeService.setPromptAppBundleID(appInfo.bundleId)
        let hasOriginalText = !self.rewriteModeService.originalText.isEmpty
        DebugLogger.shared.info(
            "Processing \(hasOriginalText ? "rewrite" : "write/improve") - instruction length: \(instruction.count), originalText length: \(self.rewriteModeService.originalText.count)",
            source: "ContentView"
        )

        // Show processing animation
        self.menuBarManager.setProcessing(true)

        // Process the request - service handles both cases:
        // - With originalText: rewrites existing text based on instruction
        // - Without originalText: improves/refines the spoken text
        await self.rewriteModeService.processRewriteRequest(instruction)
        guard isOutputValid() else { return }

        // If rewrite was successful, type the result
        if !self.rewriteModeService.rewrittenText.isEmpty {
            DebugLogger.shared.info("Rewrite successful, typing result (chars: \(self.rewriteModeService.rewrittenText.count))", source: "ContentView")

            // Type the rewritten text
            let typingTarget = self.resolveTypingTargetPID()
            if typingTarget.shouldRestoreOriginalFocus {
                guard await self.prepareRecordingTargetForDelivery(self.rewriteModeService.rewrittenText, keepBackup: SettingsStore.shared.copyTranscriptionToClipboard, isOutputValid: isOutputValid) else {
                    guard isOutputValid() else { return }
                    self.showTextDeliveryFailure(
                        .targetRestoreFailed,
                        transcript: self.rewriteModeService.rewrittenText
                    )
                    return
                }
            }
            let deliveryResult = await self.asr.typeTextToActiveField(
                self.rewriteModeService.rewrittenText,
                preferredTargetPID: typingTarget.pid,
                preserveTranscriptOnClipboard: SettingsStore.shared.copyTranscriptionToClipboard,
                isOutputValid: isOutputValid
            )
            guard isOutputValid() else { return }
            if case let .recoverableFailure(failure) = deliveryResult {
                self.showTextDeliveryFailure(failure, transcript: self.rewriteModeService.rewrittenText)
                return
            }

            // Clear the rewrite service state for next use
            self.rewriteModeService.clearState()
            self.hideOverlayAfterOutput()
        } else {
            DebugLogger.shared.error("Rewrite failed - no result", source: "ContentView")
            if let message = self.rewriteModeService.lastErrorMessage {
                self.showEditModeFailure(message)
            } else {
                await self.menuBarManager.finishProcessingAndHideOverlay()
            }
        }
    }

    private func setActiveRecordingMode(_ mode: ActiveRecordingMode) {
        if mode == .command || mode == .edit { self.cancelDictationContextCapture() }
        if mode != .dictate, mode != .promptMode {
            self.clearActiveDictationShortcutState()
        }
        self.activeRecordingMode = mode
        switch mode {
        case .none, .dictate, .promptMode:
            self.isRecordingForCommand = false
            self.isRecordingForRewrite = false
        case .edit:
            self.isRecordingForCommand = false
            self.isRecordingForRewrite = true
        case .command:
            self.isRecordingForCommand = true
            self.isRecordingForRewrite = false
        }
    }

    private func clearActiveRecordingMode() {
        self.setActiveRecordingMode(.none)
    }

    /// Cancel an in-flight prewarm. Called on abort / new recording start — NOT on
    /// a normal stop, because AI post-processing runs after stop and benefits from
    /// the warm prefix cache the prewarm prime.
    private func cancelPrewarmDictationIfNeeded() {
        self.prewarmDictationTask?.cancel()
        self.prewarmDictationTask = nil
    }

    private func handleLivePromptModeSwitch(_ mode: SettingsStore.PromptMode) {
        guard !NotchContentState.shared.isProcessing else { return }
        switch mode.normalized {
        case .dictate:
            guard self.activeRecordingMode != .dictate || NotchContentState.shared.mode != .dictation else { return }
            self.setActiveRecordingMode(.dictate)
            self.rewriteModeService.clearState()
            self.menuBarManager.setOverlayMode(.dictation)
        case .edit:
            guard self.activeRecordingMode != .edit || NotchContentState.shared.mode == .dictation else { return }
            self.setActiveRecordingMode(.edit)
            let hasOriginal = !self.rewriteModeService.originalText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
            let hasContext = !self.rewriteModeService.selectedContextText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
            if !hasOriginal, !hasContext {
                let captured = self.rewriteModeService.captureSelectedText()
                DebugLogger.shared.info("Live switch to Edit Text attempted context capture: \(captured)", source: "ContentView")
                if !captured {
                    self.rewriteModeService.startWithoutSelection()
                }
            }
            self.startReadingEditWindow()
            self.menuBarManager.setOverlayMode(.edit)
        case .write, .rewrite:
            guard self.activeRecordingMode != .edit || NotchContentState.shared.mode == .dictation else { return }
            self.setActiveRecordingMode(.edit)
            let hasOriginal = !self.rewriteModeService.originalText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
            let hasContext = !self.rewriteModeService.selectedContextText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
            if !hasOriginal, !hasContext {
                let captured = self.rewriteModeService.captureSelectedText()
                DebugLogger.shared.info("Live switch to Edit Text attempted context capture: \(captured)", source: "ContentView")
                if !captured {
                    self.rewriteModeService.startWithoutSelection()
                }
            }
            self.startReadingEditWindow()
            self.menuBarManager.setOverlayMode(.edit)
        }
    }

    /// Reads the front window for on-device Edit Mode. An API never gets it.
    private func startReadingEditWindow() {
        guard self.settings.editModeReadsScreen,
              self.settings.effectiveRewriteModeProviderID == PrivateAIProviderFeature.shared.providerID,
              let target = NotchContentState.shared.recordingTargetContext,
              target.pid != ProcessInfo.processInfo.processIdentifier
        else {
            self.rewriteModeService.stopReadingWindow()
            return
        }
        self.rewriteModeService.startReadingWindow(target: target)
    }

    private func handleLiveOverlayModeSwitch(_ mode: OverlayMode) {
        guard !NotchContentState.shared.isProcessing else { return }
        switch mode {
        case .dictation:
            self.handleLivePromptModeSwitch(.dictate)
        case .edit, .write, .rewrite:
            self.handleLivePromptModeSwitch(.edit)
        case .command:
            guard self.activeRecordingMode != .command || NotchContentState.shared.mode != .command else { return }
            self.rewriteModeService.clearState()
            self.setActiveRecordingMode(.command)
            self.menuBarManager.setOverlayMode(.command)
        }
    }

    // MARK: - Command Mode Voice Processing

    private func processCommandWithVoice(_ command: String, lifecycleID: UInt64) async {
        let isOutputValid: @MainActor () -> Bool = { self.overlayLifecycleID == lifecycleID && self.cancelledOutputLifecycleID != lifecycleID }
        guard isOutputValid() else { return }
        DebugLogger.shared.info("Processing voice command (\(command.count) chars)", source: "ContentView")

        // Show processing animation
        self.menuBarManager.setProcessing(true)

        // Process the command through CommandModeService
        // This stores the conversation history and executes any terminal commands
        await self.commandModeService.processUserCommand(command, notifyInvalidRequest: true, isOutputValid: isOutputValid)
        guard isOutputValid() else {
            self.commandModeService.cancelInvalidPendingCommand()
            return
        }
        self.pendingVoiceCommandLifecycleID = self.commandModeService.pendingCommand == nil ? nil : lifecycleID

        // Hide processing animation
        self.menuBarManager.setProcessing(false)

        DebugLogger.shared.info("Command processed, conversation stored in Command Mode", source: "ContentView")
    }

    /// Capture app context at start to avoid mismatches if the user switches apps mid-session
    private func startRecording() -> Task<Void, Never>? {
        guard !self.isSavingCancelledRecording, self.processingDictationLifecycleID == nil else { return nil }
        // Browsing the demo must not send dictation to a previously focused app.
        guard !self.showsFluidIntelligenceDemo || (DictationPromptTestCoordinator.shared.isActive && !DictationPromptTestCoordinator.shared.isProcessing) else { return nil }
        guard !self.presentExclusiveActivityBlockIfNeeded() else { return nil }
        let model = SettingsStore.shared.selectedSpeechModel
        DebugLogger.shared.info(
            "ContentView: startRecording() for model=\(model.displayName), supportsStreaming=\(model.supportsStreaming)",
            source: "ContentView"
        )
        guard !self.asr.isRunningOrStarting else {
            DebugLogger.shared.debug("ContentView: start ignored because capture is already active", source: "ContentView")
            return nil
        }
        self.advanceOverlayLifecycle()
        self.setActiveRecordingMode(.dictate)
        let shouldShowDictationOverlay = !self.isRecordingForCommand
            && !self.isRecordingForRewrite
            && self.asr.micStatus == .authorized
        let shouldPlayStartSound = !self.isRecordingForCommand
            && !self.isRecordingForRewrite
            && self.asr.micStatus == .authorized

        // Ensure normal dictation mode is set (command/rewrite modes set their own)
        if shouldShowDictationOverlay {
            self.menuBarManager.setOverlayMode(.dictation)
            self.menuBarManager.showRecordingOverlayImmediately()
            DebugLogger.shared.benchmark(
                "APP_BENCH",
                message: "overlay_phase phase=connecting",
                source: "AppBenchmark"
            )
        }

        let captureOverlayLifecycleID = self.overlayLifecycleID
        let captureTask = Task {
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: .dictate)
                return
            }
            let startOutcome = await self.asr.start(onCaptureStarted: {
                if shouldPlayStartSound {
                    TranscriptionSoundPlayer.shared.playStartSound()
                }
                self.captureRecordingContext()
                self.startDictationContextCaptureIfNeeded(for: .primary)
                self.prewarmPrivateAIDictationIfNeeded(for: .primary)
                DebugLogger.shared.benchmark(
                    "APP_BENCH",
                    message: "overlay_phase phase=recording trigger=first_pcm",
                    source: "AppBenchmark"
                )
            })
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: .dictate)
                return
            }
            if startOutcome == .failed {
                self.cancelDictationContextCapture()
                self.menuBarManager.hideRecordingOverlayImmediately(reason: "asr_start_failed")
            }
        }

        // Pre-load model in background while recording (avoids 10s freeze on stop)
        let warmupGeneration = MeetingModelResidencyCoordinator.shared.warmupGeneration
        Task {
            guard MeetingModelResidencyCoordinator.shared.canRunWarmup(warmupGeneration) else { return }
            do {
                DebugLogger.shared.debug("ContentView: pre-load model task started", source: "ContentView")
                try await self.asr.ensureAsrReady()
                DebugLogger.shared.debug("Model pre-loaded during recording", source: "ContentView")
            } catch {
                DebugLogger.shared.error("Failed to pre-load model: \(error)", source: "ContentView")
            }
        }
        return captureTask
    }

    private func awaitCaptureStart(_ captureTask: Task<Void, Never>?) async {
        guard let captureTask else { return }
        await withTaskCancellationHandler {
            await captureTask.value
        } onCancel: {
            captureTask.cancel()
        }
    }

    private func clearCancelledCaptureStart(lifecycleID: UInt64, mode: ActiveRecordingMode) {
        guard self.overlayLifecycleID == lifecycleID,
              !self.asr.isRunningOrStarting,
              self.activeRecordingMode == mode || self.activeRecordingMode == .none
        else { return }
        self.cancelPrewarmDictationIfNeeded()
        self.cancelDictationContextCapture()
        self.clearActiveRecordingMode()
        self.menuBarManager.hideRecordingOverlayImmediately(reason: "capture_start_cancelled")
    }

    private func presentExclusiveActivityBlockIfNeeded() -> Bool {
        guard let activity = self.asr.activeExclusiveActivity else { return false }
        let message = "Wait for the active \(activity.displayName) to finish."
        self.asr.errorTitle = "Dictation Unavailable"
        self.asr.errorMessage = message
        self.asr.showError = true
        AccessibilityNotification.Announcement("Dictation unavailable. \(message)").post()
        DebugLogger.shared.info(
            "ContentView: dictation start blocked by \(activity.rawValue)",
            source: "ContentView"
        )
        return true
    }

    private func prewarmPrivateAIDictationIfNeeded(for slot: SettingsStore.DictationShortcutSlot) {
        let appBundleID = self.asr.isRunningOrStarting ? self.recordingAppInfo?.bundleId : DictationAppSession.shared.appID
        self.prewarmDictationTask?.cancel()
        self.prewarmDictationTask = nil
        guard let verification = DictationProviderRoute.privateAIWarmupVerification(
            settings: .shared,
            slot: slot,
            appBundleID: appBundleID
        ) else { return }

        let warmupGeneration = MeetingModelResidencyCoordinator.shared.warmupGeneration
        self.prewarmDictationTask = Task {
            defer {
                if !Task.isCancelled { self.prewarmDictationTask = nil }
            }
            guard !Task.isCancelled, MeetingModelResidencyCoordinator.shared.canRunWarmup(warmupGeneration) else { return }
            let modelID = await Task.detached(priority: .utility) { verification.verifiedModelID() }.value
            guard modelID != nil, !Task.isCancelled,
                  MeetingModelResidencyCoordinator.shared.canRunWarmup(warmupGeneration) else { return }
            DebugLogger.shared.debug(
                "ContentView: AI dictation prewarm started slot=\(slot.rawValue)",
                source: "ContentView"
            )
            await PrivateAIIntegrationService.shared.prewarmDictation()
            DebugLogger.shared.debug(
                "AI dictation prewarm complete slot=\(slot.rawValue)",
                source: "ContentView"
            )
        }
    }

    /// Restores only the window and element captured when recording started.
    private func prepareRecordingTargetForDelivery(_ transcript: String, keepBackup: Bool, needsRestoration: Bool = true, isOutputValid: @escaping @MainActor () -> Bool = { true }) async -> Bool {
        guard isOutputValid() else { return false }
        guard needsRestoration else { return true }
        return await PasteDeliveryCoordinator.shared.prepareForDelivery(transcript, preserveTranscriptOnClipboard: keepBackup, isOutputValid: isOutputValid) {
            await self.restoreFocusToRecordingTarget(isOutputValid: isOutputValid)
        }
    }

    private func restoreFocusToRecordingTarget(isOutputValid: @escaping @MainActor () -> Bool = { true }) async -> Bool {
        guard let context = NotchContentState.shared.recordingTargetContext else { return false }
        let pid = context.pid
        let startedAt = ProcessInfo.processInfo.systemUptime
        self.appBench("focus_restore_start targetPID=\(pid)")
        let result = await TypingService.prepareTargetForDelivery(context, isOutputValid: isOutputValid)
        self.appBench(
            "focus_restore_result result=\(result.rawValue) elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - startedAt) * 1000).rounded()))"
        )
        DebugLogger.shared.debug(
            "Restore focus result: \(result.rawValue), targetPID: \(pid)",
            source: "ContentView"
        )
        self.appBench("focus_restore_settle_done delayMs=0")
        return result.isReady
    }

    // MARK: - ASR Model Management

    /// Manual download trigger - downloads models when user clicks button
    private func downloadModels() async {
        DebugLogger.shared.debug("User initiated model download", source: "ContentView")

        do {
            try await self.asr.ensureAsrReady()
            DebugLogger.shared.info("Model download completed successfully", source: "ContentView")
        } catch {
            DebugLogger.shared.error("Failed to download models: \(error)", source: "ContentView")
        }
    }

    /// Delete models from disk
    private func deleteModels() async {
        DebugLogger.shared.debug("User initiated model deletion", source: "ContentView")

        do {
            try await self.asr.clearModelCache()
            DebugLogger.shared.info("Models deleted successfully", source: "ContentView")
        } catch {
            DebugLogger.shared.error("Failed to delete models: \(error)", source: "ContentView")
        }
    }

    // MARK: - ASR Model Preloading

    private func preloadASRModel() async {
        // DEPRECATED: No longer auto-loads on startup - models downloaded manually
        DebugLogger.shared.debug("Skipping auto-preload - models downloaded manually via UI", source: "ContentView")
    }

    // MARK: - Model Management

    private func addNewModel() {
        guard !self.newModelName.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines).isEmpty else { return }

        let modelName = self.newModelName.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
        let key = self.providerKey(for: self.selectedProviderID)

        // Get current list or start fresh if empty
        var list = self.availableModelsByProvider[key] ?? self.availableModels
        if list.isEmpty {
            list = []
        }

        // Add the new model if not already in list
        if !list.contains(modelName) {
            list.append(modelName)
        }

        // Update state
        self.availableModelsByProvider[key] = list
        SettingsStore.shared.availableModelsByProvider = self.availableModelsByProvider

        // Update saved provider if exists
        if let providerIndex = savedProviders.firstIndex(where: { $0.id == selectedProviderID }) {
            let updatedProvider = SettingsStore.SavedProvider(
                id: self.savedProviders[providerIndex].id,
                name: self.savedProviders[providerIndex].name,
                baseURL: self.savedProviders[providerIndex].baseURL,
                models: list
            )
            self.savedProviders[providerIndex] = updatedProvider
            self.saveSavedProviders()
        }

        // Update UI state
        self.availableModels = list
        self.selectedModel = modelName
        self.selectedModelByProvider[key] = modelName
        SettingsStore.shared.selectedModelByProvider = self.selectedModelByProvider

        // Close the add model UI
        self.showingAddModel = false
        self.newModelName = ""
    }

    private func beginCommandRecording() async {
        guard self.canBeginDictationRecording() else { return }
        DebugLogger.shared.info("Command mode triggered", source: "ContentView")
        DictationStopSnapshot.captureStartingContext(reusingCapture: self.canSwitchActiveDictationCaptureMode) {
            self.captureRecordingContext()
        }

        // Set flag so stopAndProcessTranscription knows to process as command
        self.setActiveRecordingMode(.command)

        // Set overlay mode to command
        self.menuBarManager.setOverlayMode(.command)

        guard !self.asr.isRunningOrStarting else { return }

        self.advanceOverlayLifecycle()

        // Start recording immediately for the command
        DebugLogger.shared.info(
            "Starting voice recording for command",
            source: "ContentView"
        )
        let captureOverlayLifecycleID = self.overlayLifecycleID
        let captureTask = Task {
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: .command)
                return
            }
            let startOutcome = await self.asr.start(onCaptureStarted: {
                TranscriptionSoundPlayer.shared.playStartSound()
                self.appBench("overlay_phase phase=recording trigger=first_pcm mode=command")
            })
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: .command)
                return
            }
            if startOutcome == .failed {
                self.menuBarManager.hideRecordingOverlayImmediately(
                    reason: "command_asr_start_failed"
                )
            }
        }
        await self.awaitCaptureStart(captureTask)
    }

    private func beginRewriteRecording() async {
        guard self.canBeginDictationRecording() else { return }

        let editProviderID = SettingsStore.shared.effectiveRewriteModeProviderID
        let editRoute = await Task.detached(priority: .userInitiated) {
            EditModeRoute.current(providerID: editProviderID)
        }.value
        // The check above left the main thread, so what it allowed may have changed.
        guard self.canBeginDictationRecording() else { return }
        if let message = editRoute.failureMessage {
            // A dictation in progress keeps going; only a fresh press has an overlay to use.
            if !self.canSwitchActiveDictationCaptureMode { self.showEditModeFailure(message) }
            return
        }
        if case .local = editRoute {
            // Ready by the time the user stops speaking; never delays the recording.
            Task { await PrivateAIIntegrationService.shared.prewarmEdit() }
        }

        DictationStopSnapshot.captureStartingContext(reusingCapture: self.canSwitchActiveDictationCaptureMode) {
            self.captureRecordingContext()
        }

        // Try to capture text first while still in the other app
        let captured = self.rewriteModeService.captureSelectedText()
        DebugLogger.shared.info("Rewrite mode triggered, text captured: \(captured)", source: "ContentView")

        if !captured {
            // No text selected - start in "write mode" where user speaks
            // what to write
            DebugLogger.shared
                .info(
                    "No text selected - starting in write/improve mode",
                    source: "ContentView"
                )
            self.rewriteModeService.startWithoutSelection()
            // Set overlay mode to edit
            self.menuBarManager.setOverlayMode(.edit)
        } else {
            // Text was selected - edit mode (with selected context)
            self.menuBarManager.setOverlayMode(.edit)
        }
        self.startReadingEditWindow()

        // Set flag so stopAndProcessTranscription knows to process as rewrite
        self.setActiveRecordingMode(.edit)

        guard !self.asr.isRunningOrStarting else { return }

        self.advanceOverlayLifecycle()

        // Start recording immediately for the edit instruction
        DebugLogger.shared.info("Starting voice recording for edit mode", source: "ContentView")
        let captureOverlayLifecycleID = self.overlayLifecycleID
        let captureTask = Task {
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: .edit)
                return
            }
            let startOutcome = await self.asr.start(onCaptureStarted: {
                TranscriptionSoundPlayer.shared.playStartSound()
                self.appBench("overlay_phase phase=recording trigger=first_pcm mode=edit")
            })
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: .edit)
                return
            }
            if startOutcome == .failed {
                self.menuBarManager.hideRecordingOverlayImmediately(
                    reason: "edit_asr_start_failed"
                )
            }
        }
        await self.awaitCaptureStart(captureTask)
    }

    private func initializeHotkeyManagerIfNeeded() {
        NotchContentState.shared.onPromptModeSwitchRequested = { mode in
            self.handleLivePromptModeSwitch(mode)
        }
        NotchContentState.shared.onOverlayModeSwitchRequested = { mode in
            self.handleLiveOverlayModeSwitch(mode)
        }
        NotchContentState.shared.onReprocessLastRequested = {
            self.reprocessLastDictation()
        }
        NotchContentState.shared.onCopyLastRequested = {
            self.copyLastDictationFromHistory()
        }
        NotchContentState.shared.onPasteLastRequested = {
            self.pasteLastDictationFromHistory()
        }
        NotchContentState.shared.onRetryTextDeliveryRequested = { transcript in
            Task { @MainActor in
                await self.retryTextDelivery(transcript)
            }
        }
        NotchContentState.shared.onUndoLastAIRequested = {
            self.undoLastAIProcessingFromHistory()
        }
        NotchContentState.shared.onOpenPreferencesRequested = {
            self.menuBarManager.openPreferencesFromUI()
        }
        NotchContentState.shared.onCancelRequested = {
            _ = self.handleCancelShortcut()
        }
        NotchContentState.shared.onDictationPromptSelectionRequested = { selection in
            guard selection != .privateAI || PrivateAIProviderPromptFormat.isAvailable() else { return }
            let slot = self.activeDictationShortcutSlot ?? .primary
            DictationAppSession.shared.select(selection, slot: slot, appID: DictationAppSession.shared.appID)
            self.applyDictationShortcutSelectionContext(for: slot)
            self.prewarmPrivateAIDictationIfNeeded(for: slot)
        }

        guard self.hotkeyManager == nil else { return }

        self.hotkeyManager = GlobalHotkeyManager(
            asrService: self.asr,
            primaryShortcuts: self.primaryDictationShortcuts,
            promptModeShortcut: self.promptModeHotkeyShortcut,
            commandModeShortcut: self.commandModeHotkeyShortcut,
            rewriteModeShortcut: self.rewriteModeHotkeyShortcut,
            promptShortcutAssignments: SettingsStore.shared.dictationPromptShortcutAssignments(),
            promptModeShortcutEnabled: self.isPromptModeShortcutEnabled,
            commandModeShortcutEnabled: self.isCommandModeShortcutEnabled,
            rewriteModeShortcutEnabled: self.isRewriteModeShortcutEnabled,
            startRecordingCallback: {
                DebugLogger.shared.debug("ContentView: startRecordingCallback invoked by hotkey", source: "ContentView")
                await self.awaitCaptureStart(self.startRecording())
            },
            dictationModeCallback: {
                DebugLogger.shared.info("Dictate mode triggered", source: "ContentView")
                DebugLogger.shared.debug(
                    "ContentView: selected model for dictate hotkey=\(SettingsStore.shared.selectedSpeechModel.displayName)",
                    source: "ContentView"
                )
                await self.awaitCaptureStart(self.beginDictationRecording(for: .primary, mode: .dictate))
            },
            stopAndProcessCallback: { toggleStopRequestedAt in
                let route = self.currentDictationOutputRouteForHotkeyStop()
                DebugLogger.shared.info("Hotkey stop callback using route: \(route.rawValue)", source: "ContentView")
                await self.stopAndProcessTranscription(
                    route: route,
                    toggleStopRequestedAt: toggleStopRequestedAt
                )
            },
            promptModeCallback: {
                DebugLogger.shared.info("Prompt mode triggered", source: "ContentView")
                await self.awaitCaptureStart(self.beginDictationRecording(for: .secondary, mode: .promptMode))
            },
            promptSelectionCallback: { selection in
                DebugLogger.shared.info("Prompt selection shortcut triggered", source: "ContentView")
                await self.awaitCaptureStart(self.beginDictationRecording(for: selection, mode: .promptMode))
            },
            commandModeCallback: {
                await self.beginCommandRecording()
            },
            rewriteModeCallback: {
                await self.beginRewriteRecording()
            },
            isDictateRecordingProvider: {
                self.activeRecordingMode == .dictate
            },
            isPromptModeRecordingProvider: {
                self.activeRecordingMode == .promptMode
            },
            isCommandRecordingProvider: {
                self.activeRecordingMode == .command
            },
            isRewriteRecordingProvider: {
                self.activeRecordingMode == .edit
            },
            isShortcutCaptureActiveProvider: {
                self.isRecordingAnyShortcutCapture
            },
            shortcutCaptureHandler: {
                self.handleShortcutCaptureEvent($0)
            }
        )
        self.hotkeyManager?.registerDebugToggleTriggerIfEnabled()

        self.hotkeyManagerInitialized = self.hotkeyManager?.validateEventTapHealth() ?? false

        self.hotkeyManager?.setHotkeyMode(self.hotkeyMode)

        // Set cancel callback for Escape key handling (closes transient UI, resets recording state)
        // Distinguishes suggestion dismissal from recording cancellation.
        self.hotkeyManager?.setCancelCallback {
            self.handleCancelShortcutResult()
        }

        self.hotkeyManager?.setMeetingRecordingCallback {
            Task { @MainActor in
                await self.menuBarManager.toggleMeetingRecordingFromShortcut {
                    MeetingRecordingSourcePromptController.shared.handleShortcut()
                }
            }
        }

        // Re-insert the most recent transcription on demand (no clipboard involved).
        self.hotkeyManager?.setPasteLastTranscriptionCallback {
            self.pasteLastDictationFromHistory()
        }

        // Monitor initialization status
        Task {
            // Give some time for initialization
            try? await Task.sleep(nanoseconds: 3_000_000_000) // 3 seconds

            await MainActor.run {
                self.hotkeyManagerInitialized = self.hotkeyManager?.validateEventTapHealth() ?? false
                DebugLogger.shared.debug("Initial hotkey manager health check: \(self.hotkeyManagerInitialized)", source: "ContentView")

                // If still not initialized and accessibility is enabled, try reinitializing
                if !self.hotkeyManagerInitialized && self.accessibilityEnabled {
                    self.hotkeyManagerInitialized = self.hotkeyManager?.validateEventTapHealth() ?? false
                    DebugLogger.shared.debug("Initial hotkey manager health check: \(self.hotkeyManagerInitialized)", source: "ContentView")

                    // If still not initialized and accessibility is enabled, try reinitializing
                    if !self.hotkeyManagerInitialized && self.accessibilityEnabled {
                        DebugLogger.shared.debug("Hotkey manager not healthy, attempting reinitalization", source: "ContentView")
                        self.hotkeyManager?.reinitialize()
                    }
                }
            }
        }
    }

    @discardableResult
    private func handleCancelShortcut() -> Bool {
        self.handleCancelShortcutResult() != .unhandled
    }

    private func handleCancelShortcutResult() -> GlobalHotkeyManager.CancelHandlingResult {
        if self.isSavingCancelledRecording { return .cancelled }
        var handled = false

        if DictionaryCorrectionOverlayController.shared.isPresented {
            DictionaryCorrectionOverlayController.shared.dismiss()
            return .dismissedOverlay
        }
        if NotchOverlayManager.shared.hasCommandOutputToDismiss {
            NotchOverlayManager.shared.hideExpandedCommandOutput()
            NotchOverlayManager.shared.onCommandOutputDismiss?()
            handled = true
        }

        if let lifecycleID = self.pendingVoiceCommandLifecycleID {
            self.cancelledOutputLifecycleID = lifecycleID
            self.pendingVoiceCommandLifecycleID = nil
            handled = self.commandModeService.cancelInvalidPendingCommand() || handled
        }

        if let lifecycleID = self.processingDictationLifecycleID {
            self.cancelDictationContextCapture()
            // A stop already owns the audio; suppress its pending output without stopping again.
            self.cancelledOutputLifecycleID = lifecycleID
            handled = true
        } else if self.asr.isRunningOrStarting {
            let preservesHistory = self.settings.saveTranscriptionHistory && self.asr.isRunning && !self.asr.isDictionaryTrainingCaptureActive
                && (self.activeRecordingMode == .dictate || self.activeRecordingMode == .promptMode)
                && !self.isRecordingForRewrite && !self.isRecordingForCommand
                && self.currentDictationOutputRouteForHotkeyStop() != .onboardingSandbox
                && !DictationPromptTestCoordinator.shared.isActive && !self.showsFluidIntelligenceDemo
            if preservesHistory {
                self.isSavingCancelledRecording = true
                self.cancelledOutputLifecycleID = self.overlayLifecycleID
                let manager = self.hotkeyManager
                let stopLockStartedAt = manager?.traceStopLocked()
                Task {
                    defer {
                        self.isSavingCancelledRecording = false
                        if let stopLockStartedAt { manager?.traceStopUnlocked(since: stopLockStartedAt) }
                    }
                    await self.stopAndProcessTranscription(route: .historyOnly)
                }
            } else {
                let isOnboardingTryout = self.isOnboardingVoicePlaygroundStepActive
                Task {
                    await self.asr.stopWithoutTranscription()
                    if isOnboardingTryout {
                        AnalyticsService.shared.recordOnboardingTryoutAttemptResult(outcome: .cancelled)
                    }
                }
                if self.activeRecordingMode == .edit || self.isRecordingForRewrite {
                    self.rewriteModeService.clearState()
                }
                self.clearActiveRecordingMode()
            }
            self.cancelPrewarmDictationIfNeeded()
            self.cancelDictationContextCapture()
            handled = true
        } else if self.activeRecordingMode != .none {
            self.cancelPrewarmDictationIfNeeded()
            self.cancelDictationContextCapture()
            self.clearActiveRecordingMode()
            handled = true
        }

        if handled || NotchOverlayManager.shared.isBottomOverlayVisible || NotchOverlayManager.shared.isOverlayVisible {
            self.menuBarManager.beginProcessingCompletionAndHideOverlay()
            handled = true
        }
        if self.selectedSidebarItem == .rewriteMode {
            self.navigateToApp(.welcome)
            handled = true
        }
        if handled {
            self.spokenSendAutoStopTask?.cancel()
            self.spokenSendAutoStopTask = nil
            self.stopSpokenSendVoiceActivityMonitoring()
            self.spokenSendCountdownStartedAt = nil
            self.hotkeyManager?.resetModifierOnlyShortcutTracking(reason: .cancel)
        }
        return handled ? .cancelled : .unhandled
    }

    // MARK: - Model Management Helpers

    private func isCustomModel(_ model: String) -> Bool {
        // Non-removable defaults are the provider's default models
        return !ModelRepository.shared.defaultModels(for: self.currentProvider).contains(model)
    }

    /// Check if the current model has a reasoning config (either custom or auto-detected)
    private func hasReasoningConfigForCurrentModel() -> Bool {
        let providerKey = self.providerKey(for: self.selectedProviderID)

        // Check for custom config first
        if SettingsStore.shared.hasCustomReasoningConfig(forModel: self.selectedModel, provider: providerKey) {
            if let config = SettingsStore.shared.getReasoningConfig(forModel: selectedModel, provider: providerKey) {
                return config.isEnabled
            }
        }

        // Check for auto-detected models
        let modelLower = self.selectedModel.lowercased()
        return modelLower.hasPrefix("gpt-5") || modelLower.contains("gpt-5.") ||
            modelLower.hasPrefix("o1") || modelLower.hasPrefix("o3") ||
            modelLower.contains("gpt-oss") || modelLower.hasPrefix("openai/") ||
            (modelLower.contains("deepseek") && modelLower.contains("reasoner"))
    }

    private func removeModel(_ model: String) {
        // Don't remove if it's currently selected
        if self.selectedModel == model {
            // Switch to first available model that's not the one being removed
            if let firstOther = availableModels.first(where: { $0 != model }) {
                self.selectedModel = firstOther
            }
        }

        // Remove from current provider's model list
        self.availableModels.removeAll { $0 == model }

        // Update the stored models for this provider
        let key = self.providerKey(for: self.selectedProviderID)
        self.availableModelsByProvider[key] = self.availableModels
        SettingsStore.shared.availableModelsByProvider = self.availableModelsByProvider

        // If this is a saved custom provider, update its models array too
        if let providerIndex = savedProviders.firstIndex(where: { $0.id == selectedProviderID }) {
            let updatedProvider = SettingsStore.SavedProvider(
                id: self.savedProviders[providerIndex].id,
                name: self.savedProviders[providerIndex].name,
                baseURL: self.savedProviders[providerIndex].baseURL,
                models: self.availableModels
            )
            self.savedProviders[providerIndex] = updatedProvider
            self.saveSavedProviders()
        }

        // Update selected model mapping for this provider
        self.selectedModelByProvider[key] = self.selectedModel
        SettingsStore.shared.selectedModelByProvider = self.selectedModelByProvider
    }

    // Deprecated: hotkey persistence is handled via SettingsStore
}

// SidebarItem enum moved to top of file

// AudioDevice and AudioHardwareObserver moved to Services/AudioDeviceService.swift

// MARK: - ContentView Playground & Onboarding Helpers

extension ContentView {
    private func buildSystemPrompt(
        appInfo: (name: String, bundleId: String, windowTitle: String),
        dictationSlot: SettingsStore.DictationShortcutSlot? = nil
    ) -> String {
        if let slot = dictationSlot ?? self.currentDictationShortcutSlot(for: self.activeRecordingMode) {
            return SettingsStore.shared.effectiveDictationSystemPrompt(for: slot, appBundleID: appInfo.bundleId)
        }
        return SettingsStore.shared.effectiveSystemPrompt(for: .dictate, appBundleID: appInfo.bundleId)
    }

    private var shouldTracePromptProcessing: Bool {
        self.forcePromptTraceToConsole ||
            UserDefaults.standard.bool(forKey: "EnableDebugLogs")
    }

    private var forcePromptTraceToConsole: Bool {
        ProcessInfo.processInfo.environment["FLUID_PROMPT_TRACE"] == "1"
    }

    private func logDictationPromptTrace(_ title: String, value: String) {
        let line = "[PromptTrace][Dictate] \(title):\n\(value)"
        if self.forcePromptTraceToConsole {
            print(line)
        }
        DebugLogger.shared.debug(line, source: "ContentView")
    }

    private func customPromptAnalyticsProperties(promptSource: String, overrideEmpty: Bool?) -> [String: Any] {
        let providerID = SettingsStore.shared.selectedProviderID
        let providerKey = self.providerKey(for: providerID)
        let selectedModel = SettingsStore.shared.selectedModelByProvider[providerKey] ?? SettingsStore.shared.selectedModel ?? ""
        let isCustomProvider = !ModelRepository.shared.isBuiltIn(providerID)
        let providerName = isCustomProvider ? "Custom Provider" : ModelRepository.shared.displayName(for: providerID)

        var properties: [String: Any] = [
            "prompt_source": promptSource,
            "provider_id": isCustomProvider ? "custom" : providerID,
            "provider_name": providerName,
            "provider_type": isCustomProvider ? "custom" : "built_in",
        ]
        if !selectedModel.isEmpty {
            properties["model"] = isCustomProvider ? "custom" : selectedModel
        }
        if let overrideEmpty {
            properties["override_empty"] = overrideEmpty
        }
        return properties
    }

    private func isLocalEndpoint(_ urlString: String) -> Bool {
        ModelRepository.shared.isLocalEndpoint(urlString)
    }

    private func currentDictationShortcutSlot(for mode: ActiveRecordingMode) -> SettingsStore.DictationShortcutSlot? {
        switch mode {
        case .dictate:
            return self.activeDictationShortcutSlot ?? .primary
        case .promptMode:
            return self.activeDictationShortcutSlot ?? .secondary
        case .none, .edit, .command:
            return nil
        }
    }

    private func clearActiveDictationShortcutState() {
        self.activeDictationShortcutSlot = nil
        self.promptModeOverrideText = nil
        NotchContentState.shared.activeDictationShortcutSlot = nil
        NotchContentState.shared.promptModeOverrideProfileName = nil
        NotchContentState.shared.promptModeOverrideProfileID = nil
        NotchContentState.shared.isPromptModeActive = false
    }

    private func applyDictationShortcutSelectionContext(for slot: SettingsStore.DictationShortcutSlot) {
        let settings = SettingsStore.shared
        NotchContentState.shared.stopSnapshotLabel = nil
        self.activeDictationShortcutSlot = slot
        NotchContentState.shared.activeDictationShortcutSlot = slot
        NotchContentState.shared.isPromptModeActive = (slot == .secondary)

        switch settings.resolvedDictationPromptSelection(for: slot, appBundleID: DictationAppSession.shared.appID) {
        case .off, .default:
            self.promptModeOverrideText = nil
            NotchContentState.shared.promptModeOverrideProfileName = nil
            NotchContentState.shared.promptModeOverrideProfileID = nil
        case .privateAI:
            self.promptModeOverrideText = nil
            NotchContentState.shared.promptModeOverrideProfileName = PrivateAIProviderFeature.displayName
            NotchContentState.shared.promptModeOverrideProfileID = PrivateAIProviderPromptFormat.promptSelectionID
        case let .profile(profileID):
            guard let profile = settings.dictationPromptProfiles.first(where: {
                $0.id == profileID && $0.mode.normalized == .dictate
            }) else {
                self.promptModeOverrideText = nil
                NotchContentState.shared.promptModeOverrideProfileName = nil
                NotchContentState.shared.promptModeOverrideProfileID = nil
                return
            }

            self.promptModeOverrideText = settings.shortcutOverrideSystemPrompt(for: profile, mode: .dictate)
            NotchContentState.shared.promptModeOverrideProfileName = profile.name
            NotchContentState.shared.promptModeOverrideProfileID = profile.id
        }
    }

    private var canSwitchActiveDictationCaptureMode: Bool {
        self.activeRecordingMode != .none && self.asr.canSwitchOwnedDictationCaptureMode
    }

    private func clearOwnCaptureBlockErrorIfNeeded() {
        if self.asr.showError, self.asr.errorTitle == "Dictation Unavailable",
           self.asr.errorMessage == "Wait for the active dictation to finish."
        { self.asr.showError = false }
    }

    private func canBeginDictationRecording() -> Bool {
        guard !self.isSavingCancelledRecording, self.processingDictationLifecycleID == nil else { return false }
        if self.canSwitchActiveDictationCaptureMode {
            self.clearOwnCaptureBlockErrorIfNeeded()
            return true
        }
        guard !self.presentExclusiveActivityBlockIfNeeded() else { return false }
        return !self.asr.isRunningOrStarting && !self.asr.isDictionaryTrainingCaptureActive
    }

    private func beginDictationRecording(
        for slot: SettingsStore.DictationShortcutSlot,
        mode: ActiveRecordingMode,
        startMethod: AnalyticsOnboardingTryoutStartMethod = .hotkey
    ) -> Task<Void, Never>? {
        guard self.canBeginDictationRecording() else { return nil }
        let switchesOwnedCapture = self.canSwitchActiveDictationCaptureMode
        let previousMode = self.activeRecordingMode
        DebugLogger.shared.debug("Begin dictation recording for slot \(slot.rawValue)", source: "ContentView")
        DebugLogger.shared.debug("CLOSE_DETAIL nextStartRequested uptime=\(ProcessInfo.processInfo.systemUptime)", source: "StopTiming")
        self.appBench("begin_recording slot=\(slot.rawValue) mode=\(mode.rawValue)")
        if !switchesOwnedCapture, self.isOnboardingVoicePlaygroundStepActive {
            self.asr.finalText = ""
            self.settings.onboardingPlaygroundValidated = false
            self.settings.onboardingPlaygroundSkipped = false
            self.settings.playgroundUsed = false
            self.playgroundUsed = false
        }
        self.applyDictationShortcutSelectionContext(for: slot)
        self.setActiveRecordingMode(mode)
        self.rewriteModeService.clearState()

        if switchesOwnedCapture {
            self.menuBarManager.setOverlayMode(.dictation)
            DebugLogger.shared.info(
                "Dictation capture mode switched from=\(previousMode.rawValue) to=\(mode.rawValue) slot=\(slot.rawValue)",
                source: "ContentView"
            )
            return nil
        }
        guard !self.asr.isRunningOrStarting else {
            self.appBench("asr_start_skipped reason=already_running_or_starting")
            return nil
        }
        let isOnboardingTryout = self.isOnboardingVoicePlaygroundStepActive && mode == .dictate
        if isOnboardingTryout {
            AnalyticsService.shared.recordOnboardingTryoutAttemptStarted(startMethod: startMethod)
        }
        self.advanceOverlayLifecycle()
        if self.asr.micStatus == .authorized {
            self.appBench("overlay_mode_request mode=Dictation")
            self.menuBarManager.setOverlayMode(.dictation)
            self.menuBarManager.showRecordingOverlayImmediately()
            self.appBench("overlay_mode_requested mode=Dictation")
            self.appBench("overlay_phase phase=connecting")
        }
        let captureOverlayLifecycleID = self.overlayLifecycleID
        return Task {
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: mode)
                return
            }
            let asrStartStartedAt = ProcessInfo.processInfo.systemUptime
            DebugLogger.shared.benchmark("APP_BENCH", message: "asr_start_call", source: "AppBenchmark")
            let startOutcome = await self.asr.start(onCaptureStarted: {
                if SettingsStore.shared.enableTranscriptionSounds {
                    TranscriptionSoundPlayer.shared.playStartSound()
                }
                self.captureRecordingContext()
                self.startDictationContextCaptureIfNeeded(for: slot)
                self.prewarmPrivateAIDictationIfNeeded(for: slot)
                self.appBench("overlay_phase phase=recording trigger=first_pcm")
            })
            guard !Task.isCancelled else {
                self.clearCancelledCaptureStart(lifecycleID: captureOverlayLifecycleID, mode: mode)
                return
            }
            if startOutcome == .failed {
                self.cancelDictationContextCapture()
                self.menuBarManager.hideRecordingOverlayImmediately(reason: "asr_start_failed")
                if isOnboardingTryout {
                    AnalyticsService.shared.recordOnboardingTryoutAttemptResult(
                        outcome: .error,
                        failureStage: .audioStart
                    )
                }
            }
            DebugLogger.shared.benchmark(
                "APP_BENCH",
                message: "asr_start_return elapsedMs=\(Int(((ProcessInfo.processInfo.systemUptime - asrStartStartedAt) * 1000).rounded()))",
                source: "AppBenchmark"
            )
        }
    }

    private func beginDictationRecording(for selection: SettingsStore.DictationPromptSelection, mode: ActiveRecordingMode) -> Task<Void, Never>? {
        guard self.canBeginDictationRecording() else { return nil }
        let settings = SettingsStore.shared
        settings.setDictationPromptSelection(selection, for: .secondary)
        return self.beginDictationRecording(for: .secondary, mode: mode)
    }

    private func benchmarkLoadAverage() -> String {
        var loadAverages = [Double](repeating: 0, count: 3)
        let loadSampleCount = getloadavg(&loadAverages, 3)
        return loadSampleCount > 0 ? String(format: "%.1f", loadAverages[0]) : "nil"
    }

    private func appBench(_ message: @autoclosure () -> String) {
        DebugLogger.shared.benchmark("APP_BENCH", message: message(), source: "AppBenchmark")
    }

    private func logAIProcessCall(
        _ pipelineID: String,
        _ modelInfo: (provider: String?, model: String?),
        _ inputChars: Int
    ) {
        let provider = (modelInfo.provider ?? "unknown").replacingOccurrences(of: " ", with: "_")
        let model = (modelInfo.model ?? "unknown").replacingOccurrences(of: " ", with: "_")
        self.appBench(
            "ai_process_call id=\(pipelineID) provider=\(provider) model=\(model) inputChars=\(inputChars)"
        )
    }

    private func callOpenAIChat() async {
        guard !self.isCallingAI else { return }
        await MainActor.run { self.isCallingAI = true }
        defer { Task { await MainActor.run { isCallingAI = false } } }

        do {
            let result = try await processTextWithAI(aiInputText)
            await MainActor.run { self.aiOutputText = result }
        } catch {
            DebugLogger.shared.error("callOpenAIChat failed: \(error.localizedDescription)", source: "ContentView")
            await MainActor.run { self.aiOutputText = "Error: \(error.localizedDescription)" }
        }
    }

    private func getModelStatusText() -> String {
        if self.asr.isLoadingModel {
            return "Loading model into memory... (30-60 sec)"
        } else if self.asr.isDownloadingModel {
            return "Downloading model... Please wait."
        } else if self.asr.isAsrReady {
            return "Model is ready to use!"
        } else if self.asr.modelsExistOnDisk {
            return "Model cached. Will load on first use."
        } else {
            return "Model will download when needed."
        }
    }

    private var onboardingVoiceModelReady: Bool {
        self.asr.isAsrReady
    }

    private var onboardingMicrophoneReady: Bool {
        self.asr.micStatus == .authorized
    }

    private var onboardingAccessibilityReady: Bool {
        self.accessibilityEnabled
    }

    private var onboardingAIReady: Bool {
        self.settings.onboardingAISkipped || DictationAIPostProcessingGate.isOnboardingChoiceConfigured()
    }

    private var onboardingPlaygroundReady: Bool {
        self.settings.onboardingPlaygroundValidated || self.settings.onboardingPlaygroundSkipped
    }

    @MainActor
    private func revealAppInFinder() {
        let appPath = Bundle.main.bundlePath
        NSWorkspace.shared.activateFileViewerSelecting([URL(fileURLWithPath: appPath)])
    }

    private func openApplicationsFolder() {
        NSWorkspace.shared.open(URL(fileURLWithPath: "/Applications"))
    }
}

// MARK: - ContentView Accessibility & Lifecycle Helpers

extension ContentView {
    func completeOnboardingIfPossible(selecting target: SidebarItem? = nil) {
        let missingRequirements = self.missingOnboardingCompletionRequirements()
        guard missingRequirements.isEmpty else {
            self.presentOnboardingCompletionBlocked(missingRequirements)
            return
        }

        self.completeOnboarding(selecting: target)
    }

    private func completeOnboarding(selecting target: SidebarItem? = nil) {
        self.settings.onboardingCompleted = true
        self.navigateToApp(target ?? .welcome)
    }

    private func missingOnboardingCompletionRequirements() -> [String] {
        var missing: [String] = []

        if !self.onboardingVoiceModelReady {
            missing.append("voice model")
        }
        if !self.onboardingMicrophoneReady {
            missing.append("microphone access")
        }
        if !self.onboardingAccessibilityReady {
            missing.append("Accessibility access")
        }
        if !self.onboardingAIReady {
            missing.append("AI choice")
        }
        if !self.onboardingPlaygroundReady {
            missing.append("test or skip")
        }

        return missing
    }

    private func presentOnboardingCompletionBlocked(_ missingRequirements: [String]) {
        let missingText = missingRequirements.joined(separator: ", ")
        DebugLogger.shared.warning(
            "Onboarding completion blocked; missing=\(missingText)",
            source: "ContentView"
        )
        self.asr.errorTitle = "Setup Isn't Complete"
        self.asr.errorMessage = "Finish \(missingText) to continue."
        self.asr.showError = true
    }

    func labelFor(status: AVAuthorizationStatus) -> String {
        switch status {
        case .authorized: return "Microphone: Authorized"
        case .denied: return "Microphone: Denied"
        case .restricted: return "Microphone: Restricted"
        case .notDetermined: return "Microphone: Not Determined"
        @unknown default: return "Microphone: Unknown"
        }
    }

    func checkAccessibilityPermissions() -> Bool {
        return AXIsProcessTrusted()
    }

    @discardableResult
    private func refreshAccessibilityPermissionState() -> Bool {
        let trusted = self.checkAccessibilityPermissions()
        let newlyGranted = trusted && !self.accessibilityEnabled
        if trusted != self.accessibilityEnabled {
            self.accessibilityEnabled = trusted
        }
        if newlyGranted,
           UserDefaults.standard.bool(forKey: self.accessibilityRestartFlagKey),
           !UserDefaults.standard.bool(forKey: self.hasAutoRestartedForAccessibilityKey)
        {
            UserDefaults.standard.set(true, forKey: self.hasAutoRestartedForAccessibilityKey)
            DebugLogger.shared.info("Auto-restarting app after accessibility grant", source: "ContentView")
            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
                self.restartApp()
            }
        }
        return trusted
    }

    func openAccessibilitySettings() {
        let requestID = UUID()
        self.accessibilityGuideRequestID = requestID

        if let url = URL(string: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility") {
            NSWorkspace.shared.open(url)
        }
        self.didOpenAccessibilityPane = true
        UserDefaults.standard.set(true, forKey: self.accessibilityRestartFlagKey)
        self.startAccessibilityPolling()
        self.positionWindowBesideSystemSettings(requestID: requestID)
        self.showAccessibilityGuidePanel(requestID: requestID)
        self.activateSystemSettingsSoon(requestID: requestID)
    }

    private func positionWindowBesideSystemSettings(requestID: UUID) {
        DispatchQueue.main.asyncAfter(deadline: .now() + 0.45) {
            guard self.accessibilityGuideRequestID == requestID else { return }
            guard let window = NSApp.windows.first(where: { $0.isVisible && $0.title == "FluidVoice" }) ?? NSApp.keyWindow else {
                return
            }

            let screen = self.systemSettingsWindowFrame()
                .flatMap { settingsFrame in
                    NSScreen.screens.first { $0.frame.intersects(settingsFrame) }
                } ?? window.screen ?? NSScreen.main
            guard let screen else { return }

            let visibleFrame = screen.visibleFrame
            let currentSize = window.frame.size
            let guideWidth = min(currentSize.width, max(640, visibleFrame.width * 0.42))
            let guideHeight = min(currentSize.height, visibleFrame.height - 56)
            let targetSize = NSSize(width: guideWidth, height: guideHeight)

            let settingsFrame = self.systemSettingsWindowFrame()
            let gap: CGFloat = 20
            let targetX: CGFloat
            if let settingsFrame, settingsFrame.maxX + gap + targetSize.width <= visibleFrame.maxX {
                targetX = settingsFrame.maxX + gap
            } else if let settingsFrame, settingsFrame.minX - gap - targetSize.width >= visibleFrame.minX {
                targetX = settingsFrame.minX - gap - targetSize.width
            } else {
                targetX = visibleFrame.maxX - targetSize.width - 24
            }

            let targetY: CGFloat
            if let settingsFrame {
                targetY = min(
                    visibleFrame.maxY - targetSize.height - 16,
                    max(visibleFrame.minY + 16, settingsFrame.maxY - targetSize.height)
                )
            } else {
                targetY = visibleFrame.midY - (targetSize.height / 2)
            }

            window.setFrame(
                NSRect(origin: NSPoint(x: targetX, y: targetY), size: targetSize),
                display: true,
                animate: true
            )
            window.orderBack(nil)
        }
    }

    private func systemSettingsWindowFrame() -> NSRect? {
        guard let windowList = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] else {
            return nil
        }

        for info in windowList {
            guard (info[kCGWindowOwnerName as String] as? String) == "System Settings",
                  let bounds = info[kCGWindowBounds as String] as? [String: Any],
                  let x = bounds["X"] as? CGFloat,
                  let y = bounds["Y"] as? CGFloat,
                  let width = bounds["Width"] as? CGFloat,
                  let height = bounds["Height"] as? CGFloat,
                  width > 0,
                  height > 0
            else {
                continue
            }

            for screen in NSScreen.screens {
                let convertedFrame = NSRect(
                    x: x,
                    y: screen.frame.maxY - y - height,
                    width: width,
                    height: height
                )
                if screen.frame.intersects(convertedFrame) {
                    return convertedFrame
                }
            }

            let convertedY = (NSScreen.main?.frame.maxY ?? 0) - y - height
            return NSRect(x: x, y: convertedY, width: width, height: height)
        }

        return nil
    }

    private func showAccessibilityGuidePanel(requestID: UUID) {
        DispatchQueue.main.asyncAfter(deadline: .now() + 0.65) {
            guard self.accessibilityGuideRequestID == requestID else { return }
            guard !self.refreshAccessibilityPermissionState() else {
                self.finishAccessibilityPermissionFlow()
                return
            }

            let settingsFrame = self.systemSettingsWindowFrame()
            let screen = settingsFrame
                .flatMap { frame in NSScreen.screens.first { $0.frame.intersects(frame) } } ?? NSScreen.main
            guard let screen else { return }

            let visibleFrame = screen.visibleFrame
            let panelWidth = min(max((settingsFrame?.width ?? visibleFrame.width * 0.48) * 0.86, 520), 760)
            let panelHeight: CGFloat = 132
            let gap: CGFloat = 14

            let panelX: CGFloat
            let panelY: CGFloat
            if let settingsFrame {
                panelX = min(
                    visibleFrame.maxX - panelWidth - 16,
                    max(visibleFrame.minX + 16, settingsFrame.midX - (panelWidth / 2))
                )
                panelY = max(visibleFrame.minY + 16, settingsFrame.minY - panelHeight - gap)
            } else {
                panelX = visibleFrame.midX - (panelWidth / 2)
                panelY = visibleFrame.minY + 120
            }

            let frame = NSRect(x: panelX, y: panelY, width: panelWidth, height: panelHeight)
            let panel = self.accessibilityGuidePanel ?? NSPanel(
                contentRect: frame,
                styleMask: [.borderless, .nonactivatingPanel],
                backing: .buffered,
                defer: false
            )

            panel.level = .floating
            panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
            panel.isOpaque = false
            panel.backgroundColor = .clear
            panel.hasShadow = true
            panel.hidesOnDeactivate = false
            panel.contentView = NSHostingView(
                rootView: AccessibilitySettingsFloatingGuideView(
                    appURL: self.draggableAccessibilityAppURL,
                    appName: self.accessibilityAppDisplayName,
                    onReturnToApp: {
                        self.cancelAccessibilityPermissionFlow()
                    },
                    onClose: {
                        self.cancelAccessibilityPermissionFlow()
                    }
                )
            )
            panel.setFrame(frame, display: true, animate: self.accessibilityGuidePanel != nil)
            panel.orderFrontRegardless()
            self.accessibilityGuidePanel = panel
            self.startAccessibilityGuidePanelMonitor()
            self.activateSystemSettingsSoon(requestID: requestID)
        }
    }

    private func activateSystemSettingsSoon(requestID: UUID) {
        for delay in [0.25, 0.85, 1.45] {
            DispatchQueue.main.asyncAfter(deadline: .now() + delay) {
                guard self.accessibilityGuideRequestID == requestID else { return }
                self.activateSystemSettings()
            }
        }
    }

    private func activateSystemSettings() {
        if let app = NSWorkspace.shared.runningApplications.first(where: { $0.bundleIdentifier == "com.apple.SystemSettings" }) ??
            NSWorkspace.shared.runningApplications.first(where: { $0.bundleIdentifier == "com.apple.systempreferences" }) ??
            NSWorkspace.shared.runningApplications.first(where: { $0.localizedName == "System Settings" })
        {
            app.activate(options: [])
        }
    }

    private func cancelAccessibilityPermissionFlow() {
        self.finishAccessibilityPermissionFlow()
        NSApp.activate(ignoringOtherApps: true)
        (NSApp.windows.first { $0.isVisible && $0.title == "FluidVoice" } ?? NSApp.keyWindow)?
            .makeKeyAndOrderFront(nil)
    }

    private func finishAccessibilityPermissionFlow() {
        self.accessibilityGuideRequestID = nil
        self.didOpenAccessibilityPane = false
        self.showRestartPrompt = false
        UserDefaults.standard.set(false, forKey: self.accessibilityRestartFlagKey)
        self.closeAccessibilityGuidePanel()
        self.stopAccessibilityPolling()
    }

    private func closeAccessibilityGuidePanel() {
        self.accessibilityGuideMonitorTask?.cancel()
        self.accessibilityGuideMonitorTask = nil
        self.accessibilityGuidePanel?.close()
        self.accessibilityGuidePanel = nil
    }

    private func startAccessibilityGuidePanelMonitor() {
        self.accessibilityGuideMonitorTask?.cancel()
        self.accessibilityGuideMonitorTask = Task {
            var missingSettingsCount = 0

            while !Task.isCancelled {
                try? await Task.sleep(nanoseconds: 900_000_000)

                let isTrusted = AXIsProcessTrusted()
                let settingsFrame = await MainActor.run {
                    self.systemSettingsWindowFrame()
                }

                if isTrusted {
                    await MainActor.run {
                        self.refreshAccessibilityPermissionState()
                        self.finishAccessibilityPermissionFlow()
                    }
                    return
                }

                if settingsFrame == nil {
                    missingSettingsCount += 1
                } else {
                    missingSettingsCount = 0
                }

                if missingSettingsCount >= 3 {
                    await MainActor.run {
                        self.cancelAccessibilityPermissionFlow()
                    }
                    return
                }
            }
        }
    }

    private var draggableAccessibilityAppURL: URL {
        let runningAppURL = Bundle.main.bundleURL
        if runningAppURL.pathExtension == "app",
           FileManager.default.fileExists(atPath: runningAppURL.path)
        {
            return runningAppURL
        }

        let installedURL = URL(fileURLWithPath: "/Applications/FluidVoice.app")
        if FileManager.default.fileExists(atPath: installedURL.path) {
            return installedURL
        }
        return Bundle.main.bundleURL
    }

    private var accessibilityAppDisplayName: String {
        Bundle.main.fluidAppDisplayName
    }

    func restartApp() {
        // Clear pending flag and hide prompt before restarting
        UserDefaults.standard.set(false, forKey: self.accessibilityRestartFlagKey)
        self.showRestartPrompt = false
        AppDelegate.restartAfterSaving()
    }

    func startAccessibilityPolling() {
        // Keep polling until macOS reports the current process is trusted. The restart guard
        // only prevents restart loops; it must not prevent the UI from noticing permission changes.
        guard !self.accessibilityEnabled else { return }

        // Cancel any existing polling task
        self.accessibilityPollingTask?.cancel()

        // Start background polling
        self.accessibilityPollingTask = Task {
            while !Task.isCancelled {
                try? await Task.sleep(nanoseconds: 2_000_000_000) // Poll every 2 seconds

                // Check if permission was granted
                let nowTrusted = AXIsProcessTrusted()
                if nowTrusted && !self.accessibilityEnabled {
                    await MainActor.run {
                        DebugLogger.shared.info("Accessibility permission granted", source: "ContentView")
                        self.refreshAccessibilityPermissionState()
                        self.finishAccessibilityPermissionFlow()
                    }
                    break // Stop polling after triggering restart
                }
            }
        }
    }

    private func stopAccessibilityPolling() {
        self.accessibilityPollingTask?.cancel()
        self.accessibilityPollingTask = nil
    }
}

// swiftlint:enable type_body_length

@MainActor
private enum SidebarSymbolCache {
    private static let symbolNames = [
        "waveform",
        "brain",
        "cpu",
        "wand.and.stars",
        "text.book.closed.fill",
        "terminal.fill",
        "doc.text.fill",
        "person.2.fill",
        "clock.arrow.circlepath",
        "chart.bar.fill",
        "house.fill",
        "doc.text.magnifyingglass",
        "envelope.fill",
    ]

    private static let images: [String: NSImage] = {
        let configuration = NSImage.SymbolConfiguration(pointSize: 14, weight: .regular)
            .applying(.preferringHierarchical())
        var images: [String: NSImage] = [:]

        for name in symbolNames {
            guard let image = NSImage(systemSymbolName: name, accessibilityDescription: nil)?
                .withSymbolConfiguration(configuration)
            else { continue }

            image.isTemplate = true
            image.cacheMode = .always
            images[name] = image
        }

        return images
    }()

    static func image(named name: String) -> NSImage {
        self.images[name] ?? NSImage(systemSymbolName: "questionmark", accessibilityDescription: nil) ?? NSImage()
    }
}

private struct SidebarChromeButtonStyle: ButtonStyle {
    let isHovered: Bool
    let reduceMotion: Bool

    func makeBody(configuration: Configuration) -> some View {
        let scale = self.reduceMotion || !configuration.isPressed ? 1 : 0.985

        configuration.label
            .foregroundStyle(.primary)
            .background(
                RoundedRectangle(cornerRadius: 6, style: .continuous)
                    .fill(Color.primary.opacity(self.backgroundOpacity(isPressed: configuration.isPressed)))
            )
            .scaleEffect(scale)
            .animation(.easeOut(duration: self.reduceMotion ? 0.08 : 0.1), value: configuration.isPressed)
            .animation(.easeOut(duration: 0.1), value: self.isHovered)
    }

    private func backgroundOpacity(isPressed: Bool) -> Double {
        if isPressed {
            return 0.12
        }
        return self.isHovered ? 0.08 : 0
    }
}

extension View {
    func sidebarOptionHover(isSelected: Bool, reduceMotion: Bool) -> some View {
        modifier(SidebarOptionHoverModifier(isSelected: isSelected, reduceMotion: reduceMotion))
    }
}

private struct SidebarOptionHoverModifier: ViewModifier {
    let isSelected: Bool
    let reduceMotion: Bool

    @Environment(\.theme) private var theme
    @State private var isHovered = false

    func body(content: Content) -> some View {
        content
            .frame(maxWidth: .infinity, minHeight: 28, alignment: .leading)
            .padding(.horizontal, 5)
            .padding(.vertical, 3)
            .background(
                RoundedRectangle(cornerRadius: 6, style: .continuous)
                    .fill(self.backgroundColor)
            )
            .padding(.horizontal, -5)
            .padding(.vertical, -3)
            .contentShape(Rectangle())
            .onHover { self.isHovered = $0 }
            .animation(.easeOut(duration: self.reduceMotion ? 0.08 : 0.12), value: self.isHovered)
    }

    private var backgroundColor: Color {
        if self.isSelected {
            return self.theme.palette.accent
        }
        return Color.primary.opacity(self.isHovered ? 0.08 : 0)
    }
}

private struct AccessibilitySettingsFloatingGuideView: View {
    let appURL: URL
    let appName: String
    let onReturnToApp: () -> Void
    let onClose: () -> Void

    @Environment(\.accessibilityReduceMotion) private var reduceMotion
    @State private var isArrowRaised = false
    @State private var isTokenHovered = false

    private var appIcon: NSImage {
        NSWorkspace.shared.icon(forFile: self.appURL.path)
    }

    var body: some View {
        VStack(spacing: 12) {
            HStack(spacing: 12) {
                Image(systemName: "arrow.up")
                    .font(.fluidSystem(size: 30, weight: .bold))
                    .foregroundStyle(FluidOnboardingLandingColors.blue)
                    .offset(y: self.reduceMotion ? 0 : (self.isArrowRaised ? -8 : 4))
                    .animation(
                        self.reduceMotion ? nil : .easeInOut(duration: 0.85).repeatForever(autoreverses: true),
                        value: self.isArrowRaised
                    )

                Text("Drag \(self.appName) into the Accessibility apps list as shown")
                    .font(.fluidSystem(size: 15, weight: .semibold))
                    .foregroundStyle(.white.opacity(0.78))
                    .lineLimit(1)

                Spacer()

                Button {
                    self.onClose()
                } label: {
                    Image(systemName: "xmark")
                        .font(.fluidSystem(size: 11, weight: .bold))
                        .foregroundStyle(.white.opacity(0.58))
                        .frame(width: 26, height: 26)
                        .background(Circle().fill(Color.white.opacity(0.075)))
                        .contentShape(Circle())
                }
                .buttonStyle(.plain)
                .focusable(false)
                .help("Close guide")
            }

            HStack(spacing: 12) {
                Button {
                    self.onReturnToApp()
                } label: {
                    Image(systemName: "chevron.left")
                        .font(.fluidSystem(size: 15, weight: .bold))
                        .foregroundStyle(.white.opacity(0.72))
                        .frame(width: 34, height: 34)
                        .background(Circle().fill(Color.white.opacity(0.075)))
                        .contentShape(Circle())
                }
                .buttonStyle(.plain)
                .focusable(false)
                .help("Return to \(self.appName)")

                Image(nsImage: self.appIcon)
                    .resizable()
                    .frame(width: 34, height: 34)
                    .clipShape(RoundedRectangle(cornerRadius: 8, style: .continuous))

                Text(self.appName)
                    .font(.fluidSystem(size: 16, weight: .semibold))
                    .foregroundStyle(.white.opacity(0.92))

                Spacer()

                Image(systemName: "line.3.horizontal")
                    .font(.fluidSystem(size: 14, weight: .bold))
                    .foregroundStyle(.white.opacity(0.38))
            }
            .padding(.horizontal, 16)
            .frame(maxWidth: .infinity)
            .frame(height: 56)
            .background(
                RoundedRectangle(cornerRadius: 10, style: .continuous)
                    .fill(Color.white.opacity(self.isTokenHovered ? 0.095 : 0.055))
                    .overlay(
                        RoundedRectangle(cornerRadius: 10, style: .continuous)
                            .stroke(Color.white.opacity(self.isTokenHovered ? 0.16 : 0.08), lineWidth: 1)
                    )
            )
            .contentShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
            .onHover { isHovered in
                if self.reduceMotion {
                    self.isTokenHovered = isHovered
                } else {
                    withAnimation(.easeOut(duration: 0.14)) {
                        self.isTokenHovered = isHovered
                    }
                }
            }
            .onDrag {
                NSItemProvider(object: self.appURL as NSURL)
            }
            .accessibilityLabel("Drag \(self.appName) to the Accessibility list")
        }
        .padding(.horizontal, 20)
        .padding(.vertical, 16)
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .background(
            RoundedRectangle(cornerRadius: 18, style: .continuous)
                .fill(Color(red: 0.11, green: 0.11, blue: 0.13).opacity(0.96))
                .overlay(
                    RoundedRectangle(cornerRadius: 18, style: .continuous)
                        .stroke(Color.white.opacity(0.14), lineWidth: 1)
                )
        )
        .onAppear {
            guard !self.reduceMotion else { return }
            self.isArrowRaised = true
        }
    }
}

private extension ContentView {
    func reloadSettingsStateAfterBackupRestore() {
        self.primaryDictationShortcuts = SettingsStore.shared.primaryDictationShortcuts
        self.promptModeHotkeyShortcut = SettingsStore.shared.promptModeHotkeyShortcut
        self.commandModeHotkeyShortcut = SettingsStore.shared.commandModeHotkeyShortcut
        self.rewriteModeHotkeyShortcut = SettingsStore.shared.rewriteModeHotkeyShortcut
        self.cancelRecordingHotkeyShortcut = SettingsStore.shared.cancelRecordingHotkeyShortcut
        self.isPromptModeShortcutEnabled = SettingsStore.shared.promptModeShortcutEnabled
        self.isCommandModeShortcutEnabled = SettingsStore.shared.commandModeShortcutEnabled
        self.isRewriteModeShortcutEnabled = SettingsStore.shared.rewriteModeShortcutEnabled
        self.playgroundUsed = SettingsStore.shared.playgroundUsed
        self.visualizerNoiseThreshold = SettingsStore.shared.visualizerNoiseThreshold
        self.selectedOutputUID = SettingsStore.shared.preferredOutputDeviceUID ?? ""
        self.enableDebugLogs = SettingsStore.shared.enableDebugLogs
        self.hotkeyMode = SettingsStore.shared.hotkeyMode
        self.enableStreamingPreview = SettingsStore.shared.enableStreamingPreview
        self.copyToClipboard = SettingsStore.shared.copyTranscriptionToClipboard
        self.launchAtStartup = SettingsStore.shared.launchAtStartup
        self.showInDock = SettingsStore.shared.showInDock
        self.availableModelsByProvider = SettingsStore.shared.availableModelsByProvider
        self.selectedModelByProvider = SettingsStore.shared.selectedModelByProvider
        self.savedProviders = SettingsStore.shared.savedProviders
        self.selectedProviderID = SettingsStore.shared.selectedProviderID

        self.hotkeyManager?.updatePrimaryShortcuts(self.primaryDictationShortcuts)
        self.hotkeyManager?.updatePromptModeShortcut(self.promptModeHotkeyShortcut)
        self.hotkeyManager?.updatePromptModeShortcutEnabled(self.isPromptModeShortcutEnabled)
        self.hotkeyManager?.updatePromptShortcutAssignments(SettingsStore.shared.dictationPromptShortcutAssignments())
        self.hotkeyManager?.updateCommandModeShortcut(self.commandModeHotkeyShortcut)
        self.hotkeyManager?.updateCommandModeShortcutEnabled(self.isCommandModeShortcutEnabled)
        self.hotkeyManager?.updateRewriteModeShortcut(self.rewriteModeHotkeyShortcut)
        self.hotkeyManager?.updateRewriteModeShortcutEnabled(self.isRewriteModeShortcutEnabled)

        self.currentProvider = self.providerKey(for: self.selectedProviderID)
        if let saved = self.savedProviders.first(where: { $0.id == self.selectedProviderID }) {
            self.availableModels = saved.models
            self.openAIBaseURL = saved.baseURL
        } else if let stored = self.availableModelsByProvider[self.currentProvider], !stored.isEmpty {
            self.availableModels = stored
            self.openAIBaseURL = ModelRepository.shared.defaultBaseURL(for: self.selectedProviderID)
        } else {
            self.availableModels = ModelRepository.shared.defaultModels(for: self.currentProvider)
            self.openAIBaseURL = ModelRepository.shared.defaultBaseURL(for: self.selectedProviderID)
        }

        if let restoredSelectedModel = self.selectedModelByProvider[self.currentProvider],
           self.availableModels.contains(restoredSelectedModel)
        {
            self.selectedModel = restoredSelectedModel
        } else if let firstModel = self.availableModels.first {
            self.selectedModel = firstModel
        }

        self.refreshDevices()
    }
}

private struct UpdateAvailableToolbarButton: View {
    @Environment(\.theme) private var theme
    @ObservedObject private var updater = SimpleUpdater.shared

    var body: some View {
        if let version = self.updater.availableUpdateVersion {
            Button {
                self.updater.showAvailableUpdate()
            } label: {
                Image(systemName: "arrow.down.circle.fill")
                    .fluidToolbarIcon()
                    .foregroundStyle(self.theme.palette.accent)
            }
            .buttonStyle(.automatic)
            .disabled(self.updater.isCheckingForUpdates || self.updater.isUpdateInProgress)
            .help("Update available: \(version). View update.")
            .accessibilityLabel("Update available: \(version)")
            .accessibilityHint("View update details")
        }
    }
}

private struct TodayStatsToolbarButton: View {
    @ObservedObject private var historyStore = TranscriptionHistoryStore.shared

    let typingWPM: Int
    let action: () -> Void

    var body: some View {
        let summary = self.historyStore.todaySummary
        let timeSaved = summary.formattedTimeSaved(typingWPM: self.typingWPM)
        let hasActivity = summary.words > 0

        return Button(action: self.action) {
            HStack(spacing: 4) {
                Image(systemName: hasActivity ? "waveform" : "chart.bar.fill")
                if hasActivity {
                    Text("\(summary.words) words")
                    Text("·")
                        .foregroundStyle(.secondary)
                    Text(timeSaved)
                } else {
                    Text("Today")
                }
            }
            .font(.fluidSystem(size: 12, weight: .medium))
        }
        .help(hasActivity ? "Today: \(summary.words) words · \(timeSaved) saved - view stats" : "View your stats")
        .accessibilityLabel("Today stats")
    }
}

// MARK: - Card Animation Modifier

struct CardAppearAnimation: ViewModifier {
    let delay: Double
    @Binding var appear: Bool

    func body(content: Content) -> some View {
        content
            .scaleEffect(self.appear ? 1.0 : 0.96)
            .opacity(self.appear ? 1.0 : 0)
            .animation(.spring(response: 0.8, dampingFraction: 0.75, blendDuration: 0.2).delay(self.delay), value: self.appear)
    }
}