AppState.swift

// AppState.swift
// VocaMac
//
// Central observable state for the entire application.
// All UI and services react to changes in AppState.

import Foundation
import SwiftUI
import Combine
import ServiceManagement

// MARK: - Enums

/// Application status representing the current state of the transcription pipeline
enum AppStatus: String {
    case idle          // Ready for input, not recording
    case recording     // Actively capturing microphone audio
    case processing    // Transcribing audio via WhisperKit
    case error         // Something went wrong
}

/// How recording is activated by the user
enum ActivationMode: String, CaseIterable, Codable, Identifiable {
    case pushToTalk       // Hold key to record, release to stop
    case doubleTapToggle  // Double-tap key to start/stop

    var id: String { rawValue }

    var displayName: String {
        switch self {
        case .pushToTalk:      return "Push to Talk (Hold)"
        case .doubleTapToggle: return "Double-Tap Toggle"
        }
    }

    var description: String {
        switch self {
        case .pushToTalk:
            return "Hold the hotkey to record. Release to stop and transcribe."
        case .doubleTapToggle:
            return "Double-tap the hotkey to start recording. Double-tap again to stop."
        }
    }
}

/// Permission status for system permissions
enum PermissionStatus: String {
    case notDetermined
    case granted
    case denied
}

// MARK: - AppState

@MainActor
final class AppState: ObservableObject {

    // MARK: - Published State

    /// Current application status
    @Published var appStatus: AppStatus = .idle

    /// Whether the app is actively recording audio
    @Published var isRecording: Bool = false

    /// Current audio input level (0.0 - 1.0) for visual feedback
    @Published var audioLevel: Float = 0.0

    /// The most recent transcription result
    @Published var lastTranscription: VocaTranscription?

    /// Last Settings → Test Dictation result (shown in the sidebar footer; not injected).
    @Published var settingsTestResultText: String?

    /// Error message to display, if any
    @Published var errorMessage: String?

    /// Currently loaded/active whisper model info
    @Published var currentModel: WhisperModelInfo?

    /// All available models and their statuses
    @Published var availableModels: [WhisperModelInfo] = []

    // Permissions are managed by PermissionManager.
    // These computed properties maintain backward compatibility for views.
    var micPermission: PermissionStatus { permissionManager.micPermission }
    var accessibilityPermission: PermissionStatus { permissionManager.accessibilityPermission }
    var inputMonitoringPermission: PermissionStatus { permissionManager.inputMonitoringPermission }

    /// Detected system capabilities
    @Published var systemCapabilities: SystemCapabilities?

    /// WhisperKit's recommended model for this device
    @Published var deviceRecommendedModel: String?

    // MARK: - User Settings (persisted via UserDefaults)

    @AppStorage("vocamac.hasCompletedOnboarding") var hasCompletedOnboarding: Bool = false
    @AppStorage("vocamac.activationMode") var activationMode: ActivationMode = .pushToTalk
    @AppStorage("vocamac.hotKeyCode") var hotKeyCode: Int = 61  // Right Option
    @AppStorage("vocamac.hotKeyModifiers") var hotKeyModifiers: HotKeyModifiers = []
    @AppStorage("vocamac.doubleTapThreshold") var doubleTapThreshold: Double = 0.4
    @AppStorage("vocamac.silenceThreshold") var silenceThreshold: Double = 0.01
    @AppStorage("vocamac.silenceDuration") var silenceDuration: Double = SilenceDetectionSettings.defaultDuration
    @AppStorage("vocamac.maxRecordingDuration") var maxRecordingDuration: Int = 60
    @AppStorage("vocamac.selectedAudioDeviceID") var selectedAudioDeviceID: String = ""
    @AppStorage("vocamac.selectedAudioDeviceName") var selectedAudioDeviceName: String = ""
    @AppStorage("vocamac.selectedAudioChannel") var selectedAudioChannel: Int = 0
    @AppStorage("vocamac.selectedAudioChannelDeviceID") var selectedAudioChannelDeviceID: String = ""
    @AppStorage("vocamac.selectedAudioChannelCount") var selectedAudioChannelCount: Int = 0
    @AppStorage(PreferenceKey.selectedModelSize) var selectedModelSize: String = ModelSize.tiny.rawValue
    @AppStorage(PreferenceKey.selectedLanguage) var selectedLanguage: String = "auto"
    @AppStorage("vocamac.launchAtLogin") var launchAtLogin: Bool = false
    @AppStorage("vocamac.preserveClipboard") var preserveClipboard: Bool = true
    @AppStorage("vocamac.soundEffectsEnabled") var soundEffectsEnabled: Bool = true
    @AppStorage(PreferenceKey.dictationTone) var dictationTone: DictationTone = .voca
    @AppStorage("vocamac.overlayStyle") var overlayStyle: OverlayStyle = .minimal
    @AppStorage("vocamac.overlayPosition") var overlayPosition: OverlayPosition = .bottom
    /// Legacy preference retained so existing installs that disabled the old
    /// cursor indicator continue to keep the overlay hidden after upgrading.
    @AppStorage("vocamac.showCursorIndicator") var showCursorIndicator: Bool = true
    @AppStorage("vocamac.translationEnabled") var translationEnabled: Bool = false
    @AppStorage("vocamac.customVocabulary") var customVocabulary: String = ""
    @AppStorage("vocamac.logLevel") var logLevel: String = "info"
    @AppStorage(PreferenceKey.appendTrailingSpace) var appendTrailingSpace: Bool = true
    @AppStorage(PreferenceKey.autoCapitalize) var autoCapitalize: Bool = true
    @AppStorage(PreferenceKey.autoPauseEnabled) var autoPauseEnabled: Bool = false
    @AppStorage(PreferenceKey.autoPausePollInterval) var autoPausePollIntervalSeconds: Double = 5
    @AppStorage(PreferenceKey.modelKeepAliveEnabled) var modelKeepAliveEnabled: Bool = false
    @AppStorage(PreferenceKey.modelKeepAliveIdleTimeout) var modelKeepAliveIdleTimeoutSeconds: Double = 300

    /// JSON-encoded `[AutoPauseAppEntry]` list (complex value not stored via `@AppStorage`).
    var autoPauseAppsJSON: String {
        get { UserDefaults.standard.string(forKey: PreferenceKey.autoPauseApps) ?? "[]" }
        set { UserDefaults.standard.set(newValue, forKey: PreferenceKey.autoPauseApps) }
    }

    /// Decoded auto-pause app list. Empty when unset or invalid JSON.
    var autoPauseApps: [AutoPauseAppEntry] {
        get {
            guard let data = autoPauseAppsJSON.data(using: .utf8),
                  let decoded = try? JSONDecoder().decode([AutoPauseAppEntry].self, from: data) else {
                return []
            }
            return decoded
        }
        set {
            if let data = try? JSONEncoder().encode(newValue),
               let json = String(data: data, encoding: .utf8) {
                autoPauseAppsJSON = json
            } else {
                autoPauseAppsJSON = "[]"
            }
            objectWillChange.send()
        }
    }

    /// True while a configured auto-pause app is running and dictation is blocked.
    @Published var isAutoPaused: Bool = false

    /// Set when the last recording could not use the pinned microphone.
    /// Cleared when a recording starts on the requested device.
    @Published var inputDeviceFallbackNotice: String?

    /// True while the audio engine is negotiating its input route. Bluetooth
    /// headsets can take seconds to switch to their microphone, and a stop
    /// arriving in that window has to be deferred rather than blocked on.
    private var isStartingAudio = false

    /// How to finish a start that the user interrupted while it was still
    /// negotiating the route.
    private var pendingStopDuringStart: PendingStopKind?

    private enum PendingStopKind {
        /// Push-to-talk released: keep whatever the engine managed to capture.
        case transcribe
        /// Overlay cancel: throw the recording away.
        case discard
    }

    /// Last reason the speech model was unloaded (nil while a model is loaded).
    @Published var lastModelUnloadReason: ModelUnloadReason?

    /// Display name of the app that triggered the current auto-pause, if any.
    @Published var autoPauseTriggerDisplayName: String?

    /// Approximate process RSS (MB) sampled just before the last unload.
    @Published var processMemoryBeforeUnloadMB: Double?

    /// Approximate process RSS (MB) sampled right after the last unload.
    @Published var processMemoryAfterUnloadMB: Double?

    private var hotKeySafetyTimeout: Double {
        Double(maxRecordingDuration) + 5.0
    }

    /// Persist the microphone VocaMac should use for future recordings.
    /// Passing nil restores the system-default input behavior.
    func selectAudioDevice(_ device: AudioDevice?) {
        let newDeviceID = device?.id ?? ""
        if selectedAudioDeviceID != newDeviceID {
            selectedAudioChannel = 0
            selectedAudioChannelDeviceID = newDeviceID
            selectedAudioChannelCount = device?.channelCount ?? 0
        }
        selectedAudioDeviceID = newDeviceID
        selectedAudioDeviceName = device?.name ?? ""

        if let device {
            syncSelectedAudioChannel(with: device)
        }
    }

    /// Persist the physical interface input selected for a specific device layout.
    func selectAudioChannel(_ channel: Int, for device: AudioDevice) {
        selectedAudioChannelDeviceID = device.id
        selectedAudioChannelCount = device.channelCount
        guard device.channelCount > 0, channel >= 0, channel < device.channelCount else {
            selectedAudioChannel = 0
            return
        }
        selectedAudioChannel = channel
    }

    /// Reset a saved channel when the active device or its channel layout changes.
    func syncSelectedAudioChannel(with device: AudioDevice) {
        let mappingIsCurrent = selectedAudioChannelDeviceID == device.id
            && selectedAudioChannelCount == device.channelCount
        let channelIsValid = selectedAudioChannel >= 0
            && selectedAudioChannel < device.channelCount
        if !mappingIsCurrent || !channelIsValid {
            selectedAudioChannel = 0
        }
        selectedAudioChannelDeviceID = device.id
        selectedAudioChannelCount = device.channelCount
    }

    /// Custom text snippets for expansion
    @Published var snippets: [Snippet] = []

    // MARK: - Services

    let audioEngine: AudioRecording
    let whisperService: SpeechTranscribing
    let textInjector: TextInjecting
    let hotKeyManager: HotKeyMonitoring
    let modelManager: ModelManaging
    let soundManager: SoundPlaying
    let cursorOverlay: CursorOverlayManaging
    let statsManager: StatsManaging
    let snippetExpander: SnippetExpanding
    let updateChecker = UpdateChecker()
    let permissionManager: any PermissionManaging

    /// Polls configured apps and pauses dictation while they run.
    let autoPauseMonitor = AutoPauseMonitor()
    /// Unloads the model after an idle timeout when enabled.
    let modelKeepAlive = ModelKeepAlive()
    /// Sleep/wake recovery hooks.
    let sleepWakeMonitor = SleepWakeMonitor()

    // MARK: - Private

    private var cancellables = Set<AnyCancellable>()
    private var hasStarted = false

    /// Why the model was last unloaded (for logs / UI).
    enum ModelUnloadReason: String {
        case autoPause = "auto_pause"
        case idleKeepAlive = "idle_keepalive"
        case manual = "manual"
    }

    /// Bumped when each load operation starts. Failure restores and success UI
    /// updates only apply when the generation is still current, so a stale
    /// failure cannot undo a newer successful load.
    private var loadGeneration: UInt64 = 0

    /// Serializes model downloads and loads at the AppState boundary. The
    /// engine router also protects its own load/transcribe lifecycle, but UI
    /// actions can otherwise start several downloads or model-management
    /// operations before they reach those lower-level services.
    private let modelOperationSerializer = LoadSerializer()

    /// AudioEngine serializes its own lifecycle internally; this wrapper makes
    /// the intentional background handoff explicit for Dispatch's @Sendable API.
    private struct AudioEngineWorker: @unchecked Sendable {
        let audioEngine: AudioRecording

        func startRecording(
            silenceThreshold: Float,
            silenceDuration: Double,
            maxDuration: TimeInterval,
            preferredInputDeviceID: String?,
            preferredInputChannel: Int,
            preferredInputChannelDeviceID: String?,
            preferredInputChannelCount: Int
        ) -> Bool {
            audioEngine.startRecording(
                silenceThreshold: silenceThreshold,
                silenceDuration: silenceDuration,
                maxDuration: maxDuration,
                preferredInputDeviceID: preferredInputDeviceID,
                preferredInputChannel: preferredInputChannel,
                preferredInputChannelDeviceID: preferredInputChannelDeviceID,
                preferredInputChannelCount: preferredInputChannelCount
            )
        }

        func stopRecording() -> [Float] {
            audioEngine.stopRecording()
        }
    }

    /// Process-level flag that prevents performStartup from running more than
    /// once even when SwiftUI instantiates multiple AppState objects (which it
    /// does during MenuBarExtra scene setup). Instance-level `hasStarted` guards
    /// re-entry on the same object; this static flag guards across all instances.
    ///
    /// Internal (not private) so test teardown can reset it between test cases.
    static var hasStartedGlobally = false

    /// Whether to skip system integration calls (SMAppService, etc.) during init.
    /// Set to `true` in tests to avoid side effects.
    let skipSystemIntegration: Bool

    /// Pre-load memory gate. Production defaults to SystemInfo; tests stub this
    /// so CI free+inactive pages cannot flake medium/large mock loads.
    var modelFitsInMemory: (ModelSize) -> Bool = { SystemInfo.canFitModelInMemory($0) }

    // MARK: - Initialization

    init(
        audioEngine: AudioRecording = AudioEngine(),
        whisperService: SpeechTranscribing = TranscriptionRouter(),
        textInjector: TextInjecting = TextInjector(),
        hotKeyManager: HotKeyMonitoring = HotKeyManager(),
        modelManager: ModelManaging = ModelManager(),
        soundManager: SoundPlaying = SoundManager(),
        cursorOverlay: CursorOverlayManaging,
        statsManager: StatsManaging,
        snippetExpander: SnippetExpanding = SnippetExpander(),
        permissionManager: (any PermissionManaging)? = nil,
        skipSystemIntegration: Bool = false
    ) {
        self.audioEngine = audioEngine
        self.whisperService = whisperService
        self.textInjector = textInjector
        self.hotKeyManager = hotKeyManager
        self.modelManager = modelManager
        self.soundManager = soundManager
        self.cursorOverlay = cursorOverlay
        self.statsManager = statsManager
        self.snippetExpander = snippetExpander
        self.permissionManager = permissionManager ?? PermissionManager(audioEngine: audioEngine, hotKeyManager: hotKeyManager)
        self.skipSystemIntegration = skipSystemIntegration

        VocaLogger.info(.appState, "Initializing... id=\(ObjectIdentifier(self))")
        loadSnippets()
        if !skipSystemIntegration {
            syncLaunchAtLogin()
        }
        setupServices()

        // Forward updateChecker changes so SwiftUI views observing AppState
        // re-render when updateState changes (nested ObservableObject fix).
        updateChecker.objectWillChange
            .receive(on: DispatchQueue.main)
            .sink { [weak self] _ in self?.objectWillChange.send() }
            .store(in: &cancellables)

        // Forward statsManager changes
        statsManager.objectWillChangePublisher
            .receive(on: DispatchQueue.main)
            .sink { [weak self] _ in
                self?.objectWillChange.send()
            }
            .store(in: &cancellables)
    }

    /// Single production AppState instance for the process.
    ///
    /// SwiftUI can recreate the `App` value during scene setup, especially for
    /// menu bar apps. Keeping the production instance outside the `App` value's
    /// stored-property initialization prevents duplicate service graphs, event
    /// taps, audio observers, and stale SwiftUI environment objects.
    @MainActor
    private static let sharedProductionInstance = AppState(
        cursorOverlay: CursorOverlayManager(),
        statsManager: StatsManager()
    )

    /// Convenience factory for creating AppState with all real services.
    /// Needed because CursorOverlayManager is @MainActor and can't be a default parameter.
    @MainActor
    static func production() -> AppState {
        VocaLogger.debug(.appState, "Using production AppState id=\(ObjectIdentifier(sharedProductionInstance))")
        return sharedProductionInstance
    }

    /// Called once from the SwiftUI lifecycle to complete initialization.
    /// Safe to call multiple times and across multiple instances — only the
    /// first call across the entire process takes effect.
    func triggerStartupIfNeeded() {
        guard !hasStarted, !AppState.hasStartedGlobally else {
            VocaLogger.debug(.appState, "triggerStartupIfNeeded called again — skipping (already started)")
            return
        }
        hasStarted = true
        AppState.hasStartedGlobally = true
        Task {
            await performStartup()
        }
    }

    // MARK: - Launch at Login

    /// Sync the persisted launchAtLogin preference with SMAppService.
    /// Called once on init to reconcile state (e.g. if the user toggled it
    /// in System Settings directly, or if the app was re-installed).
    private func syncLaunchAtLogin() {
        let currentStatus = SMAppService.mainApp.status
        let isRegistered = currentStatus == .enabled

        if launchAtLogin && !isRegistered {
            // User wants launch-at-login but it's not registered — register now
            setLaunchAtLogin(true)
        } else if !launchAtLogin && isRegistered {
            // Persisted preference says disabled but system says enabled — unregister
            setLaunchAtLogin(false)
        }
    }

    /// Register or unregister the app as a login item via SMAppService.
    /// Updates the persisted `launchAtLogin` preference to match.
    func setLaunchAtLogin(_ enabled: Bool) {
        do {
            if enabled {
                try SMAppService.mainApp.register()
                VocaLogger.info(.appState, "Registered as login item")
            } else {
                try SMAppService.mainApp.unregister()
                VocaLogger.info(.appState, "Unregistered as login item")
            }
            launchAtLogin = enabled
        } catch {
            VocaLogger.error(.appState, "Failed to \(enabled ? "register" : "unregister") login item: \(error.localizedDescription)")
            // Revert the preference to match the actual system state
            launchAtLogin = SMAppService.mainApp.status == .enabled
        }
    }

    // MARK: - Setup

    private func setupServices() {
        // Detect system capabilities
        systemCapabilities = SystemInfo.detect()

        // Get WhisperKit's device recommendation.
        // WhisperKit's `.default` may not be in the supported list for some
        // devices. If so, fall back to the best supported model instead.
        let recommendation = modelManager.deviceRecommendation()
        VocaLogger.info(.appState, "WhisperKit recommendation — default: \(recommendation.defaultModel), supported: [\(recommendation.supported.joined(separator: ", "))], disabled: [\(recommendation.disabled.joined(separator: ", "))]")
        let defaultIsSupported = recommendation.supported.contains(recommendation.defaultModel)
        if !defaultIsSupported, let bestSupported = recommendation.supported.last {
            deviceRecommendedModel = bestSupported
        } else {
            deviceRecommendedModel = recommendation.defaultModel
        }

        rebuildAvailableModels()

        // Validate that the recommended model maps to a supported ModelSize.
        // If the recommendation points to an unsupported model, fall back to
        // the largest supported model instead.
        if let recommended = deviceRecommendedModel {
            let recommendedSize = modelManager.modelSize(from: recommended)
            let isRecommendedSupported = recommendedSize.map { size in
                availableModels.first(where: { $0.size == size })?.isSupported == true
            } ?? false

            if !isRecommendedSupported {
                // Fall back to the largest supported WhisperKit model — the
                // recommendation badge reflects WhisperKit's per-device tuning,
                // so other engines are not candidates here.
                if let bestSupported = availableModels.last(where: { $0.isSupported && $0.size.engine == .whisperKit }) {
                    deviceRecommendedModel = modelManager.modelIdentifier(for: bestSupported.size)
                } else {
                    // No models are supported — clear the recommendation
                    deviceRecommendedModel = nil
                }
            }
        }

        // Setup audio level reporting
        audioEngine.onAudioLevel = { [weak self] level in
            Task { @MainActor in
                self?.audioLevel = level
                self?.cursorOverlay.updateAudioLevel(level)
            }
        }

        // Setup silence detection callback
        audioEngine.onSilenceDetected = { [weak self] in
            Task { @MainActor in
                guard let self = self else { return }
                if self.activationMode == .doubleTapToggle && self.isRecording {
                    VocaLogger.info(.appState, "Silence detected — auto-stopping recording (double-tap mode)")
                    await self.stopRecordingAndTranscribe()
                }
            }
        }

        // Setup max recording duration callback.
        // AudioEngine fires this when the recording reaches maxRecordingDuration.
        // This is the primary duration limit — the HotKeyManager safety timer
        // (maxRecordingDuration + 5s) acts as a backstop in case this callback
        // fails or the key-up event is lost entirely.
        audioEngine.onMaxDurationReached = { [weak self] in
            Task { @MainActor in
                guard let self = self, self.isRecording else { return }
                VocaLogger.info(.appState, "Max recording duration (\(self.maxRecordingDuration)s) reached — auto-stopping")
                await self.stopRecordingAndTranscribe()
            }
        }

        // Setup audio device change callback.
        // Fires when the microphone is unplugged/replugged, Bluetooth disconnects,
        // or the default audio device changes (e.g., after sleep). AudioEngine has
        // already stopped and reset itself — we just need to recover the app state.
        audioEngine.onAudioDeviceChanged = { [weak self] in
            Task { @MainActor in
                guard let self = self else { return }
                VocaLogger.warning(.appState, "Audio device changed — recovering from interrupted recording")
                self.isRecording = false
                self.audioLevel = 0.0
                self.cursorOverlay.hide()
                self.hotKeyManager.resetKeyState()
                self.appStatus = .idle
                self.errorMessage = nil
            }
        }

        // The pinned microphone could not be configured and recording fell back
        // to another device. Surface it so the user isn't left wondering why the
        // transcript came from the built-in mic.
        audioEngine.onInputDeviceFallback = { [weak self] notice in
            Task { @MainActor in
                guard let self else { return }
                VocaLogger.warning(.appState, notice)
                self.inputDeviceFallbackNotice = notice
            }
        }

        // Setup hotkey callbacks
        hotKeyManager.onRecordingStart = { [weak self] in
            Task { @MainActor in
                await self?.startRecording()
            }
        }

        hotKeyManager.onRecordingStop = { [weak self] in
            Task { @MainActor in
                await self?.stopRecordingAndTranscribe()
            }
        }

        // Wire permission manager: start hotkey listener when permissions granted
        permissionManager.onAllPermissionsGranted = { [weak self] in
            guard let self = self else { return }
            self.hotKeyManager.startListening(
                keyCode: self.hotKeyCode,
                mode: self.activationMode,
                doubleTapThreshold: self.doubleTapThreshold,
                safetyTimeout: self.hotKeySafetyTimeout,
                modifiers: self.hotKeyModifiers
            )
            VocaLogger.info(.appState, "Hotkey listener started after permission grant")
        }

        // Forward PermissionManager state changes to trigger SwiftUI updates
        permissionManager.objectWillChangePublisher
            .sink { [weak self] _ in self?.objectWillChange.send() }
            .store(in: &cancellables)

        // Auto-save snippets when changed. @Published emits on willSet, so
        // persist the emitted array — reading self.snippets here would save
        // the previous state and leave the latest change unsaved.
        $snippets
            .dropFirst()  // skip the subscription replay of the just-loaded value
            .sink { [weak self] snippets in
                self?.saveSnippets(snippets)
            }
            .store(in: &cancellables)

        // Check permissions
        checkPermissions()

        if !skipSystemIntegration {
            setupPowerManagement()
        }
    }

    // MARK: - Power Management

    /// Wire auto-pause, idle unload, and sleep/wake monitors.
    private func setupPowerManagement() {
        autoPauseMonitor.getConfig = { [weak self] in
            guard let self else {
                return (false, [], AutoPauseMonitor.defaultPollIntervalSeconds)
            }
            return (
                self.autoPauseEnabled,
                self.autoPauseApps,
                self.autoPausePollIntervalSeconds
            )
        }
        autoPauseMonitor.onPause = { [weak self] in
            Task { @MainActor in
                await self?.handleAutoPauseEntered()
            }
        }
        autoPauseMonitor.onResume = { [weak self] in
            Task { @MainActor in
                await self?.handleAutoPauseCleared()
            }
        }

        modelKeepAlive.getConfig = { [weak self] in
            guard let self else {
                return (false, ModelKeepAlive.defaultIdleTimeoutSeconds)
            }
            return (self.modelKeepAliveEnabled, self.modelKeepAliveIdleTimeoutSeconds)
        }
        modelKeepAlive.isSafeToUnload = { [weak self] in
            guard let self else { return false }
            return self.appStatus == .idle
                && !self.isAutoPaused
                && self.whisperService.isModelLoaded
        }
        modelKeepAlive.onIdleUnload = { [weak self] in
            Task { @MainActor in
                await self?.unloadActiveModel(reason: .idleKeepAlive)
            }
        }

        sleepWakeMonitor.onWillSleep = { [weak self] in
            self?.modelKeepAlive.cancel()
            if self?.isRecording == true || self?.appStatus == .recording {
                self?.forceRecovery()
            }
        }
        sleepWakeMonitor.onDidWake = { [weak self] in
            guard let self else { return }
            VocaLogger.info(.appState, "Wake recovery: refreshing hotkey health")
            if self.permissionManager.allPermissionsGranted {
                self.syncHotKeyConfiguration()
                if !self.hotKeyManager.isListening {
                    self.hotKeyManager.startListening(
                        keyCode: self.hotKeyCode,
                        mode: self.activationMode,
                        doubleTapThreshold: self.doubleTapThreshold,
                        safetyTimeout: self.hotKeySafetyTimeout,
                        modifiers: self.hotKeyModifiers
                    )
                }
            }
            if !self.isAutoPaused {
                self.modelKeepAlive.bump()
            }
        }

        $appStatus
            .sink { [weak self] status in
                guard let self else { return }
                switch status {
                case .idle:
                    if !self.isAutoPaused {
                        self.modelKeepAlive.bump()
                    }
                case .recording, .processing, .error:
                    self.modelKeepAlive.cancel()
                }
            }
            .store(in: &cancellables)

        autoPauseMonitor.start()
        modelKeepAlive.start()
        sleepWakeMonitor.start()
        if !skipSystemIntegration {
            AudioDeviceMonitor.shared.start()
        }
    }

    /// Unload the resident model and clear active UI flags.
    func unloadActiveModel(reason: ModelUnloadReason) async {
        VocaLogger.info(.appState, "Unloading model (reason=\(reason.rawValue))")
        modelKeepAlive.cancel()
        let beforeMB = ProcessMonitor.currentResidentMemoryMB()
        processMemoryBeforeUnloadMB = beforeMB
        await whisperService.unloadModel()
        // Give the allocator a beat to release pages before sampling again.
        try? await Task.sleep(nanoseconds: 150_000_000)
        let afterMB = ProcessMonitor.currentResidentMemoryMB()
        processMemoryAfterUnloadMB = afterMB
        lastModelUnloadReason = reason
        for i in availableModels.indices {
            availableModels[i].isActive = false
            availableModels[i].isLoading = false
        }
        currentModel = nil
        VocaLogger.info(
            .appState,
            "Unload complete (reason=\(reason.rawValue), RSS \(String(format: "%.0f", beforeMB))→\(String(format: "%.0f", afterMB)) MB)"
        )
    }

    /// Approximate RAM freed by the last unload, when both samples exist.
    var approximateMemoryFreedMB: Double? {
        guard let before = processMemoryBeforeUnloadMB,
              let after = processMemoryAfterUnloadMB,
              before > after else {
            return nil
        }
        return before - after
    }

    /// User-facing summary of why the model is currently unloaded.
    var modelUnloadStatusMessage: String? {
        guard !whisperService.isModelLoaded else { return nil }
        if isAutoPaused {
            if let name = autoPauseTriggerDisplayName, !name.isEmpty {
                return "Paused while \(name) is running. The speech model was unloaded to free memory."
            }
            return "Paused by a listed app. The speech model was unloaded to free memory."
        }
        switch lastModelUnloadReason {
        case .idleKeepAlive:
            return "Model unloaded after idle timeout. Next dictation reloads it."
        case .autoPause:
            return "Model unloaded by auto-pause."
        case .manual:
            return "Model unloaded."
        case .none:
            return nil
        }
    }

    /// Ensure a model is loaded before dictation (lazy reload after idle unload).
    func ensureModelLoaded() async {
        guard !whisperService.isModelLoaded else { return }
        let size = ModelSize(rawValue: selectedModelSize)
            ?? currentModel?.size
            ?? .tiny
        VocaLogger.info(.appState, "Ensuring model loaded: \(size.displayName)")
        await loadModel(size)
    }

    private func handleAutoPauseEntered() async {
        isAutoPaused = true
        autoPauseTriggerDisplayName = autoPauseMonitor.activeTrigger?.displayName
        modelKeepAlive.cancel()

        if isRecording || appStatus == .recording {
            VocaLogger.warning(.appState, "Auto-pause entered while recording: stopping without inject")
            _ = await stopAudioEngine()
            isRecording = false
            audioLevel = 0
            cursorOverlay.hide()
            hotKeyManager.resetKeyState()
            appStatus = .idle
        }

        if whisperService.isModelLoaded {
            await unloadActiveModel(reason: .autoPause)
        } else {
            lastModelUnloadReason = .autoPause
        }
    }

    private func handleAutoPauseCleared() async {
        isAutoPaused = false
        autoPauseTriggerDisplayName = nil
        // Warm-reload so the next hotkey is ready (Linux behavior).
        await ensureModelLoaded()
        modelKeepAlive.bump()
    }

    /// Build the model list shown in Settings and onboarding.
    ///
    /// The base catalog is curated for M-series Macs, then extended with any
    /// exact variants WhisperKit marks supported for the current device.
    /// Models whose engine cannot run on this system at all (e.g. Apple
    /// Speech before macOS 26, Parakeet on Intel) are excluded entirely.
    private func modelCatalog() -> [ModelSize] {
        var catalog = ModelSize.standardCatalog.filter { $0.isAvailableOnThisSystem }

        for size in ModelSize.allCases
        where size.isAvailableOnThisSystem && modelManager.isModelSupported(size) {
            if !catalog.contains(size) {
                catalog.append(size)
            }
        }

        if let selected = ModelSize(rawValue: selectedModelSize),
           !catalog.contains(selected) {
            catalog.append(selected)
        }

        return catalog
    }

    /// Recreate model UI state from the latest catalog and local cache status.
    private func rebuildAvailableModels() {
        availableModels = modelCatalog().map { size in
            WhisperModelInfo(
                size: size,
                filePath: modelManager.modelFolder(for: size),
                isDownloaded: modelManager.isModelDownloaded(size),
                isActive: size.rawValue == selectedModelSize,
                isSupported: modelManager.isModelSupported(size)
            )
        }
    }

    /// Resolve WhisperKit's recommended exact model variant into app metadata.
    private func recommendedModelSize() -> ModelSize? {
        guard let recommended = deviceRecommendedModel,
              let size = modelManager.modelSize(from: recommended),
              modelManager.isModelSupported(size) else {
            return nil
        }
        return size
    }

    /// Pick a supported startup model when the stored preference is no longer valid.
    private func startupFallbackModel(for preferred: ModelSize) -> ModelSize {
        guard !modelManager.isModelSupported(preferred) else {
            return preferred
        }

        // Stay on the engine the user was already using where possible.
        // Without this, the catalog order alone decides the fallback, and a
        // Whisper user could land on a different engine — notably Apple
        // Speech, which always counts as downloaded because macOS owns it.
        if let sameEngine = availableModels.last(where: {
            $0.size.engine == preferred.engine && $0.isSupported && $0.isDownloaded
        })?.size {
            return sameEngine
        }

        if let downloadedSupported = availableModels.last(where: { $0.isSupported && $0.isDownloaded })?.size {
            return downloadedSupported
        }

        if let recommended = recommendedModelSize() {
            return recommended
        }

        return .tiny
    }

    // MARK: - Permission Handling (delegated to PermissionManager)

    func checkPermissions() { permissionManager.checkPermissions() }
    func startPermissionPolling() { permissionManager.startPermissionPolling() }
    func stopPermissionPolling() { permissionManager.stopPermissionPolling() }
    var allPermissionsGranted: Bool { permissionManager.allPermissionsGranted }
    func requestMicrophonePermission() { permissionManager.requestMicrophonePermission() }
    func openMicrophoneSettings() { permissionManager.openMicrophoneSettings() }
    func requestAccessibilityPermission() { permissionManager.requestAccessibilityPermission() }
    func requestInputMonitoringPermission() { permissionManager.requestInputMonitoringPermission() }

    // MARK: - Hotkey Configuration

    /// Apply persisted hotkey settings to the active listener.
    /// `@AppStorage` updates save preferences immediately, but an already-running
    /// event tap also needs its in-memory configuration refreshed.
    func syncHotKeyConfiguration() {
        hotKeyManager.updateConfiguration(
            keyCode: hotKeyCode,
            mode: activationMode,
            doubleTapThreshold: doubleTapThreshold,
            safetyTimeout: hotKeySafetyTimeout,
            modifiers: hotKeyModifiers
        )
        VocaLogger.debug(.appState, "Hotkey configuration synced (keyCode=\(hotKeyCode), modifiers=\(hotKeyModifiers.rawValue), mode=\(activationMode.rawValue))")
    }

    // MARK: - Force Recovery

    /// Forcibly reset the entire recording pipeline to idle state.
    /// This is a last-resort recovery mechanism callable from the menu bar UI.
    /// It unconditionally resets the audio engine, hotkey state, cursor overlay,
    /// and all published state back to idle.
    func forceRecovery() {
        VocaLogger.warning(.appState, "Force recovery: resetting all state to idle (was appStatus=\(appStatus.rawValue), isRecording=\(isRecording))")

        // Reset audio engine unconditionally
        audioEngine.forceReset()

        // Reset hotkey tracking state
        hotKeyManager.resetKeyState()

        // Reset UI state
        isRecording = false
        audioLevel = 0.0
        cursorOverlay.hide()
        appStatus = .idle
        errorMessage = nil
    }

    /// Play start, then stop, for the tone currently selected in Settings.
    /// Off is silence. Preview is not gated by the sound-effects switch.
    func previewDictationTone() async {
        await soundManager.previewStartThenStop()
    }

    // MARK: - Recording Flow

    func startRecording() async {
        // If we're already recording, this is a recovery attempt — the user
        // pressed the hotkey again because a previous key-up was missed.
        // Stop the current recording and transcribe what we have.
        if appStatus == .recording || isRecording {
            VocaLogger.warning(.appState, "startRecording called while already recording — treating as stop (recovery)")
            await stopRecordingAndTranscribe()
            return
        }

        if isAutoPaused {
            let message = "Dictation is paused while a listed app is running."
            VocaLogger.info(.appState, message)
            showTemporaryError(message)
            return
        }

        guard appStatus == .idle else {
            // If stuck in .processing or .error for too long, force recovery
            // so the user can start a fresh recording.
            if appStatus == .error || appStatus == .processing {
                VocaLogger.warning(.appState, "startRecording called in \(appStatus.rawValue) state — force recovering to allow new recording")
                forceRecovery()
                // Don't start recording in the same call — let the user press again
                return
            }
            VocaLogger.warning(.appState, "startRecording called in non-idle state: \(appStatus.rawValue) — ignoring")
            return
        }
        guard micPermission == .granted else {
            errorMessage = "Microphone permission is required. Please grant access in System Settings."
            appStatus = .error
            return
        }

        // Lazy-reload after idle unload (or any other cold start).
        if !whisperService.isModelLoaded {
            appStatus = .processing
            await ensureModelLoaded()
            guard whisperService.isModelLoaded else {
                showTemporaryError("Could not load the speech model. Open Settings → Speech Model and try again.")
                return
            }
            appStatus = .idle
        }

        appStatus = .recording
        isRecording = true
        errorMessage = nil
        inputDeviceFallbackNotice = nil

        // Show the overlay in its connecting state. It only claims to be
        // listening once the audio engine confirms the route is live — on
        // Bluetooth that can be seconds later, and anything said before then is
        // not captured by anyone.
        if showCursorIndicator && overlayStyle != .off {
            cursorOverlay.show(style: overlayStyle, position: overlayPosition)
        }

        // Start recording immediately for instant responsiveness.
        // The start sound is played concurrently — any brief bleed into the
        // mic buffer is negligible and handled well by WhisperKit's noise model.
        isStartingAudio = true
        pendingStopDuringStart = nil
        let didStartRecording = await startAudioEngine(
            silenceThreshold: Float(silenceThreshold),
            silenceDuration: silenceDuration,
            maxDuration: TimeInterval(maxRecordingDuration),
            preferredInputDeviceID: selectedAudioDeviceID.isEmpty ? nil : selectedAudioDeviceID,
            preferredInputChannel: selectedAudioChannel,
            preferredInputChannelDeviceID: selectedAudioChannelDeviceID.isEmpty
                ? nil
                : selectedAudioChannelDeviceID,
            preferredInputChannelCount: selectedAudioChannelCount
        )
        isStartingAudio = false

        // The hotkey was released (or the overlay cancelled) while the route was
        // still coming up. That stop was deferred so it wouldn't block behind the
        // Bluetooth settle; finish it now.
        if let pendingStop = pendingStopDuringStart {
            pendingStopDuringStart = nil
            await finishStartInterruptedByStop(pendingStop, didStartRecording: didStartRecording)
            return
        }

        guard didStartRecording else {
            VocaLogger.warning(.appState, "Audio engine failed to start — resetting recording state")
            isRecording = false
            audioLevel = 0.0
            cursorOverlay.hide()
            hotKeyManager.resetKeyState()
            // Silently dropping back to idle looks like the hotkey did nothing.
            // Tell the user which microphone we tried and where to change it.
            let deviceDescription = selectedAudioDeviceName.isEmpty
                ? "the system default microphone"
                : selectedAudioDeviceName
            showTemporaryError("Could not start \(deviceDescription). Pick a different input in Settings → Audio, or reconnect the device.")
            return
        }

        cursorOverlay.transitionToRecording()

        // Play start sound after mic is active (fire-and-forget).
        // Off is a stored tone and stays silent even when this switch is on.
        if soundEffectsEnabled && isRecording && appStatus == .recording {
            soundManager.playStartSound()
        }
    }

    func stopRecordingAndTranscribe(injectResult: Bool = true) async {
        // Accept stop if we're recording OR if the audio engine thinks
        // it's recording (covers stuck-state recovery scenarios where
        // isRecording and appStatus may be out of sync).
        guard isRecording || appStatus == .recording else { return }

        // A start that is still negotiating its input route holds the audio
        // engine's lifecycle queue. Calling stopRecording() here would block the
        // hotkey path for the whole Bluetooth settle and then hand back an empty
        // buffer — the "No microphone audio detected" report. Ask the engine to
        // abandon the start instead and let startRecording() finish up.
        if isStartingAudio {
            pendingStopDuringStart = .transcribe
            audioEngine.cancelPendingStart()
            return
        }

        let audioData = await stopAudioEngine()
        isRecording = false
        audioLevel = 0.0

        // Play stop sound
        if soundEffectsEnabled {
            soundManager.playStopSound()
        }

        // Transition cursor indicator to processing state (red -> purple)
        // Keeps the overlay visible so the user knows text is on its way
        cursorOverlay.transitionToProcessing()

        guard !audioData.isEmpty else {
            cursorOverlay.hide()
            appStatus = .idle
            return
        }

        guard audioData.contains(where: { abs($0) >= 0.0001 }) else {
            cursorOverlay.hide()
            // Don't keep a route warm when it produced only silence.
            audioEngine.forceReset()
            let message = "No microphone audio detected. Check that the selected microphone is connected and available in Settings → Audio."
            VocaLogger.warning(.appState, message)
            showTemporaryError(message)
            return
        }

        appStatus = .processing

        do {
            let language = selectedLanguage == "auto" ? nil : selectedLanguage
            let result = try await whisperService.transcribe(
                audioData: audioData,
                language: language,
                translate: translationEnabled,
                vocabulary: customVocabulary
            )

            lastTranscription = result

            // Update stats
            statsManager.recordTranscription(result)

            let trimmedText = result.text.trimmingCharacters(in: .whitespacesAndNewlines)
            if !trimmedText.isEmpty {
                // Polish first, expand second. Snippet expansions are literal
                // text the user authored, so auto-capitalization must not
                // rewrite them (an email snippet would become Me@example.com).
                // Trigger matching is case-insensitive, so capitalizing the
                // trigger beforehand still matches.
                let polishedSource = DictationOutputFormatter.apply(
                    trimmedText,
                    autoCapitalize: autoCapitalize,
                    appendTrailingSpace: appendTrailingSpace
                )
                let polished = expandSnippets(in: polishedSource)
                if injectResult {
                    textInjector.inject(
                        text: polished,
                        preserveClipboard: preserveClipboard
                    )
                } else {
                    // Settings Test Dictation: show only in the sidebar footer.
                    settingsTestResultText = polished
                }
            } else {
                VocaLogger.info(.appState, "Transcription produced no usable text (silence or blank audio)")
                if !injectResult {
                    settingsTestResultText = nil
                }
            }

            cursorOverlay.hide()
            appStatus = .idle
        } catch {
            cursorOverlay.hide()
            errorMessage = "Transcription failed: \(error.localizedDescription)"
            appStatus = .error

            // Auto-recover after 3 seconds
            DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) { [weak self] in
                if self?.appStatus == .error {
                    self?.appStatus = .idle
                    self?.errorMessage = nil
                }
            }
        }
    }

    /// Cancels the active recording without sending its audio to a transcription
    /// engine. This is used by the overlay's cancel button.
    func cancelRecording() async {
        guard isRecording || appStatus == .recording else { return }

        if isStartingAudio {
            pendingStopDuringStart = .discard
            audioEngine.cancelPendingStart()
            return
        }

        _ = await stopAudioEngine()
        isRecording = false
        audioLevel = 0.0
        cursorOverlay.hide()
        hotKeyManager.resetKeyState()
        appStatus = .idle
        errorMessage = nil
        VocaLogger.info(.appState, "Recording cancelled from overlay")
    }

    /// Completes a recording the user ended while the microphone was still
    /// connecting. If the engine never reached the capture stage there is
    /// nothing to transcribe — no audio existed before the route came up — so
    /// say so plainly instead of reporting a mysterious silent recording.
    private func finishStartInterruptedByStop(
        _ kind: PendingStopKind,
        didStartRecording: Bool
    ) async {
        guard didStartRecording else {
            VocaLogger.info(.appState, "Recording ended while the microphone was still connecting")
            isRecording = false
            audioLevel = 0.0
            cursorOverlay.hide()
            hotKeyManager.resetKeyState()

            switch kind {
            case .discard:
                appStatus = .idle
                errorMessage = nil
            case .transcribe:
                showTemporaryError("The microphone was still connecting, so nothing was recorded. Bluetooth headsets need a moment — hold the hotkey until the start sound, then speak.")
            }
            return
        }

        // The route came up just as the user let go; treat it as a normal end.
        switch kind {
        case .transcribe:
            await stopRecordingAndTranscribe()
        case .discard:
            await cancelRecording()
        }
    }

    private func startAudioEngine(
        silenceThreshold: Float,
        silenceDuration: Double,
        maxDuration: TimeInterval,
        preferredInputDeviceID: String?,
        preferredInputChannel: Int,
        preferredInputChannelDeviceID: String?,
        preferredInputChannelCount: Int
    ) async -> Bool {
        let worker = AudioEngineWorker(audioEngine: audioEngine)
        return await withCheckedContinuation { continuation in
            DispatchQueue.global(qos: .userInitiated).async {
                let didStart = worker.startRecording(
                    silenceThreshold: silenceThreshold,
                    silenceDuration: silenceDuration,
                    maxDuration: maxDuration,
                    preferredInputDeviceID: preferredInputDeviceID,
                    preferredInputChannel: preferredInputChannel,
                    preferredInputChannelDeviceID: preferredInputChannelDeviceID,
                    preferredInputChannelCount: preferredInputChannelCount
                )
                continuation.resume(returning: didStart)
            }
        }
    }

    private func stopAudioEngine() async -> [Float] {
        let worker = AudioEngineWorker(audioEngine: audioEngine)
        return await withCheckedContinuation { continuation in
            DispatchQueue.global(qos: .userInitiated).async {
                continuation.resume(returning: worker.stopRecording())
            }
        }
    }

    // MARK: - Model Management

    func loadModel(_ size: ModelSize? = nil) async {
        _ = try? await modelOperationSerializer.run { [self] in
            await performLoadModel(size)
        }
    }

    /// Perform one model load after earlier model operations have completed.
    private func performLoadModel(_ size: ModelSize? = nil) async {
        loadGeneration += 1
        let generation = loadGeneration

        let previousLoadedModelName = whisperService.loadedModelName
        let previousModelSize = currentModel?.size
            ?? previousLoadedModelName.flatMap { modelManager.modelSize(from: $0) }
            ?? ModelSize(rawValue: selectedModelSize)
        let hadLoadedModel = whisperService.isModelLoaded

        let modelName: String?
        if let size = size {
            modelName = modelManager.modelIdentifier(for: size)
        } else {
            modelName = nil  // Let WhisperKit auto-select
        }

        // Resolve which ModelSize we're loading. When size is nil (auto-select),
        // we don't know yet — we'll detect it after loading completes.
        let targetSize = size

        // Refuse known-too-large loads before WhisperKit/CoreML can hang the
        // UI spinner under memory pressure (vocamac#250). Leave any already
        // loaded model alone — we never started a load, so do not restore/clear.
        if let targetSize,
           !modelFitsInMemory(targetSize) {
            let needed = String(format: "%.1f", targetSize.ramRequiredGB)
            let failureMessage =
                "Not enough free memory to load \(targetSize.displayName) "
                + "(~\(needed) GB needed). Free RAM or choose a smaller model."
            showTemporaryError(failureMessage)
            VocaLogger.error(.appState, failureMessage)
            return
        }

        // Mark the model as loading in the UI
        if let targetSize = targetSize, let idx = availableModels.firstIndex(where: { $0.size == targetSize }) {
            availableModels[idx].isLoading = true
            availableModels[idx].loadingStatus = "Preparing…"
        }

        do {
            // If model is downloaded locally, pass the folder URL so WhisperKit
            // loads from disk instead of downloading again. WhisperKit handles
            // tokenizer fetching itself — we don't pre-validate those files.
            let folderURL: URL?
            if let targetSize = targetSize, modelManager.isModelDownloaded(targetSize) {
                folderURL = modelManager.modelFolder(for: targetSize)
            } else {
                folderURL = nil
            }

            // Update status: unpacking
            if let targetSize = targetSize, let idx = availableModels.firstIndex(where: { $0.size == targetSize }) {
                availableModels[idx].loadingStatus = "Unpacking model…"
            }

            // Load model with status callback
            try await whisperService.loadModel(name: modelName, folder: folderURL) { [weak self] phase in
                Task { @MainActor in
                    guard let self = self else { return }
                    if let targetSize = targetSize,
                       let idx = self.availableModels.firstIndex(where: { $0.size == targetSize }) {
                        self.availableModels[idx].loadingStatus = phase
                    }
                }
            }

            // Determine which ModelSize was actually loaded.
            // When auto-selecting, WhisperKit chooses the model and we need
            // to detect which one it picked by inspecting the loaded model name.
            let resolvedSize: ModelSize
            if let targetSize = targetSize {
                resolvedSize = targetSize
            } else {
                let loadedName = (whisperService.loadedModelName ?? "").lowercased()
                if let loadedSize = modelManager.modelSize(from: whisperService.loadedModelName ?? "") {
                    resolvedSize = loadedSize
                } else if loadedName.contains("v20240930_turbo") {
                    resolvedSize = .largeV3LatestTurbo
                } else if loadedName.contains("v20240930") {
                    resolvedSize = .largeV3Latest
                } else if loadedName.contains("distil") && loadedName.contains("turbo") {
                    resolvedSize = .distilLargeV3TurboCompact
                } else if loadedName.contains("distil") {
                    resolvedSize = .distilLargeV3Compact
                } else if loadedName.contains("large") && loadedName.contains("turbo") {
                    resolvedSize = .largeV3Turbo
                } else if loadedName.contains("large") {
                    resolvedSize = .largeV3
                } else if loadedName.contains("medium") {
                    resolvedSize = .medium
                } else if loadedName.contains("small") {
                    resolvedSize = .small
                } else if loadedName.contains("base") {
                    resolvedSize = .base
                } else {
                    resolvedSize = .tiny
                }
                VocaLogger.info(.appState, "Auto-selected model resolved to: \(resolvedSize.displayName) (from '\(whisperService.loadedModelName ?? "unknown")')")
            }

            // A newer loadModel started while we were waiting; leave UI to it.
            guard generation == loadGeneration else {
                clearLoadingFlag(for: targetSize)
                return
            }

            // Persist the resolved model as the user's preference
            selectedModelSize = resolvedSize.rawValue

            // Update model states — clear all, then mark the loaded one as active
            for i in availableModels.indices {
                let matches = availableModels[i].size == resolvedSize
                availableModels[i].isActive = matches
                availableModels[i].isLoading = false
                availableModels[i].loadingStatus = "Loading…"
                if matches {
                    // Refresh download status in case the auto-select downloaded it
                    availableModels[i].isDownloaded = modelManager.isModelDownloaded(resolvedSize)
                    currentModel = availableModels[i]
                }
            }

            lastModelUnloadReason = nil
            processMemoryBeforeUnloadMB = nil
            processMemoryAfterUnloadMB = nil
            VocaLogger.info(.appState, "Model ready: \(resolvedSize.displayName)")
        } catch {
            // A newer load superseded this one; do not restore over it.
            guard generation == loadGeneration else {
                clearLoadingFlag(for: targetSize)
                return
            }

            // Clear loading state on error for all models (covers auto-select case)
            for i in availableModels.indices {
                availableModels[i].isLoading = false
                availableModels[i].loadingStatus = "Loading…"
            }

            let modelDisplayName = targetSize?.displayName ?? "model"
            let failureMessage = "Failed to load \(modelDisplayName): \(error.localizedDescription)"
            showTemporaryError(failureMessage)
            VocaLogger.error(.appState, failureMessage)

            await restorePreviousModelIfNeeded(
                afterFailedLoadFor: targetSize,
                previousSize: previousModelSize,
                previousName: previousLoadedModelName,
                hadLoadedModel: hadLoadedModel,
                originalFailureMessage: failureMessage
            )
        }
    }

    /// Clear the loading spinner on a superseded load without touching others.
    private func clearLoadingFlag(for size: ModelSize?) {
        guard let size,
              let idx = availableModels.firstIndex(where: { $0.size == size }) else {
            return
        }
        availableModels[idx].isLoading = false
        availableModels[idx].loadingStatus = "Loading…"
    }

    /// Reload the active model when the transcription language changes and
    /// the engine bakes that language into the loaded model (sherpa-onnx).
    /// Other engines take the language per transcription and need no reload.
    func reloadModelForLanguageChangeIfNeeded() async {
        guard let size = currentModel?.size,
              size.bindsLanguageAtLoadTime,
              whisperService.isModelLoaded else {
            return
        }

        VocaLogger.info(.appState, "Language changed to \(selectedLanguage) — reloading \(size.displayName)")
        await loadModel(size)
    }

    /// Surface a short-lived error state for settings and menu UI.
    private func showTemporaryError(_ message: String) {
        errorMessage = message
        appStatus = .error

        DispatchQueue.main.asyncAfter(deadline: .now() + 5.0) { [weak self] in
            if self?.appStatus == .error, self?.errorMessage == message {
                self?.appStatus = .idle
                self?.errorMessage = nil
            }
        }
    }

    /// Restore the model that was active before a failed switch.
    private func restorePreviousModelIfNeeded(
        afterFailedLoadFor failedSize: ModelSize?,
        previousSize: ModelSize?,
        previousName: String?,
        hadLoadedModel: Bool,
        originalFailureMessage: String
    ) async {
        guard hadLoadedModel,
              let previousSize,
              failedSize != previousSize else {
            clearActiveModelState()
            return
        }

        do {
            VocaLogger.info(.appState, "Restoring previous model: \(previousSize.displayName)")
            let folderURL = modelManager.isModelDownloaded(previousSize)
                ? modelManager.modelFolder(for: previousSize)
                : nil
            let restoreName = previousName ?? modelManager.modelIdentifier(for: previousSize)
            try await whisperService.loadModel(name: restoreName, folder: folderURL)
            markModelActive(previousSize)
            VocaLogger.info(.appState, "Restored previous model: \(previousSize.displayName)")
        } catch {
            clearActiveModelState()
            let restoreFailure = "Previous model could not be restored: \(error.localizedDescription)"
            errorMessage = "\(originalFailureMessage) \(restoreFailure)"
            VocaLogger.error(.appState, restoreFailure)
        }
    }

    /// Synchronize AppState's model metadata after a successful load.
    private func markModelActive(_ size: ModelSize) {
        currentModel = nil
        for i in availableModels.indices {
            let matches = availableModels[i].size == size
            availableModels[i].isActive = matches
            availableModels[i].isLoading = false
            availableModels[i].loadingStatus = "Loading…"
            if matches {
                availableModels[i].isDownloaded = modelManager.isModelDownloaded(size)
                currentModel = availableModels[i]
            }
        }
    }

    /// Clear active model metadata when no model is loaded in WhisperService.
    private func clearActiveModelState() {
        currentModel = nil
        for i in availableModels.indices {
            availableModels[i].isActive = false
            availableModels[i].isLoading = false
            availableModels[i].loadingStatus = "Loading…"
        }
    }

    func downloadModel(_ size: ModelSize) async {
        _ = try? await modelOperationSerializer.run { [self] in
            await performDownloadModel(size)
        }
    }

    /// Perform one model download after earlier model operations have
    /// completed. Keeping the UI updates inside the serialized operation
    /// prevents multiple progress indicators from representing concurrent
    /// writes to the model cache.
    private func performDownloadModel(_ size: ModelSize) async {
        guard let index = availableModels.firstIndex(where: { $0.size == size }) else { return }

        availableModels[index].downloadProgress = 0.0

        do {
            try await modelManager.downloadModel(size: size) { [weak self] progress in
                Task { @MainActor in
                    guard let self = self else { return }
                    if let idx = self.availableModels.firstIndex(where: { $0.size == size }) {
                        // Only update progress if we haven't already completed (1.0)
                        // This prevents race conditions with the simulated progress task
                        if progress >= 1.0 || self.availableModels[idx].downloadProgress != nil {
                            self.availableModels[idx].downloadProgress = progress
                        }
                    }
                }
            }

            // Small delay to let the final progress (1.0) callback settle on MainActor
            try? await Task.sleep(nanoseconds: 100_000_000)  // 100ms

            // Refresh all model statuses to ensure previously downloaded models are preserved
            refreshModelStatuses()
            VocaLogger.info(.appState, "Download complete for \(size.displayName), isDownloaded=\(modelManager.isModelDownloaded(size))")
        } catch {
            if let idx = availableModels.firstIndex(where: { $0.size == size }) {
                availableModels[idx].downloadProgress = nil
            }
            errorMessage = "Download failed: \(error.localizedDescription)"
            VocaLogger.error(.appState, "Download failed for \(size.displayName): \(error.localizedDescription)")
        }
    }

    /// Delete a downloaded model's local files, freeing disk space.
    /// Refuses to delete the currently active model — the user must load a
    /// different model first so the app is never left without a loaded model —
    /// and refuses a model that's mid-download or mid-load, so its files
    /// aren't yanked out from under an in-flight read.
    func deleteModel(_ size: ModelSize) async {
        guard let index = availableModels.firstIndex(where: { $0.size == size }) else { return }
        guard !availableModels[index].isActive else {
            errorMessage = "Can't delete the active model. Load a different model first."
            return
        }
        guard !availableModels[index].isLoading, availableModels[index].downloadProgress == nil else {
            errorMessage = "Can't delete a model that's loading or downloading."
            return
        }

        do {
            try await modelManager.deleteModel(size)
            refreshModelStatuses()
            VocaLogger.info(.appState, "Deleted model \(size.displayName)")
        } catch {
            errorMessage = "Delete failed: \(error.localizedDescription)"
            VocaLogger.error(.appState, "Delete failed for \(size.displayName): \(error.localizedDescription)")
        }
    }

    /// Refresh the download status of all models
    /// This ensures that all previously downloaded models are detected and marked correctly
    private func refreshModelStatuses() {
        for i in availableModels.indices {
            let size = availableModels[i].size
            availableModels[i].isDownloaded = modelManager.isModelDownloaded(size)
            availableModels[i].downloadProgress = nil
            availableModels[i].filePath = modelManager.modelFolder(for: size)
        }
    }

    // MARK: - Startup

    private func installBundledOrFallback(preferred: ModelSize) async -> Bool {
        do {
            return try modelManager.installBundledModelIfAvailable(for: preferred)
        } catch {
            VocaLogger.warning(.appState, "Bundled model install failed for \(preferred.displayName): \(error.localizedDescription)")
            return false
        }
    }

    func performStartup() async {
        // `vocamac.logLevel` was stored but never applied, so the level was
        // pinned at .info and every VocaLogger.debug call — including the
        // input-route tracing that explains a failed start — was discarded.
        if let level = LogLevel(rawValue: logLevel.uppercased()) {
            VocaLogger.setLogLevel(level)
        }
        VocaLogger.info(.appState, "performStartup beginning...")

        // 1. Detect hardware
        systemCapabilities = SystemInfo.detect()
        let sysInfo = systemCapabilities
        VocaLogger.info(.appState, "System: \(sysInfo?.processorName ?? "unknown") | \(sysInfo?.physicalMemoryGB ?? 0) GB RAM | \(sysInfo?.coreCount ?? 0) cores")

        // 2. Check/request permissions
        checkPermissions()
        VocaLogger.info(.appState, "Mic permission: \(micPermission.rawValue) | Accessibility: \(accessibilityPermission.rawValue) | Input Monitoring: \(inputMonitoringPermission.rawValue)")

        // Auto-prompt for microphone permission on first launch
        if micPermission == .notDetermined {
            VocaLogger.info(.appState, "Mic permission not determined — requesting...")
            requestMicrophonePermission()
        }

        // Start polling if any permission is still missing
        startPermissionPolling()

        // 3. Load the user's preferred model.
        // On first launch the preferred model (tiny by default) won't be
        // downloaded yet. We download it explicitly so the UI can show real
        // progress, rather than delegating to WhisperKit's opaque auto-select
        // which provides no progress callbacks and may pick a different model.
        let preferredModel = ModelSize(rawValue: selectedModelSize) ?? .tiny
        var modelToLoad = startupFallbackModel(for: preferredModel)
        if modelToLoad != preferredModel {
            VocaLogger.warning(.appState, "Preferred model \(preferredModel.displayName) is not supported on this device — falling back to \(modelToLoad.displayName)")
            selectedModelSize = modelToLoad.rawValue
            rebuildAvailableModels()
        }

        if !modelManager.isModelDownloaded(modelToLoad) {
            // Try bundled model for the preferred size first
            let installedPreferred = await installBundledOrFallback(preferred: modelToLoad)
            if installedPreferred {
                refreshModelStatuses()
            } else {
                VocaLogger.info(.appState, "Preferred model \(modelToLoad.displayName) not downloaded — downloading now...")
                await downloadModel(modelToLoad)
            }

            // If preferred model still isn't ready, try bundled tiny as a last resort
            if !modelManager.isModelDownloaded(modelToLoad), modelToLoad != .tiny {
                let installedTiny = await installBundledOrFallback(preferred: .tiny)
                if installedTiny {
                    modelToLoad = .tiny
                    refreshModelStatuses()
                    VocaLogger.info(.appState, "Falling back to bundled Tiny model")
                }
            }
        }

        VocaLogger.info(.appState, "Loading model: \(modelToLoad.displayName)...")
        await loadModel(modelToLoad)
        VocaLogger.info(.appState, "Model loaded: \(whisperService.loadedModelName ?? "none")")

        // 4. Always attempt to start hotkey listener
        // The event tap creation itself will fail if permissions aren't granted,
        // and we handle that gracefully in HotKeyManager.
        VocaLogger.info(.appState, "Attempting to start hotkey listener...")
        hotKeyManager.startListening(
            keyCode: hotKeyCode,
            mode: activationMode,
            doubleTapThreshold: doubleTapThreshold,
            safetyTimeout: hotKeySafetyTimeout,
            modifiers: hotKeyModifiers
        )
        if hotKeyManager.isListening {
            VocaLogger.info(.appState, "Hotkey listener active (keyCode=\(hotKeyCode), mode=\(activationMode.rawValue))")
        } else {
            VocaLogger.warning(.appState, "Hotkey listener failed to start. Check Accessibility & Input Monitoring permissions.")
        }

        await updateChecker.checkOnLaunchIfNeeded()

        VocaLogger.info(.appState, "Startup complete!")
    }
    func completeOnboarding() {
        syncHotKeyConfiguration()
        if !isRecording {
            hotKeyManager.resetKeyState()
        }
        hasCompletedOnboarding = true
        VocaLogger.info(.appState, "Onboarding completed")
    }

    // MARK: - Snippets Management

    private func loadSnippets() {
        if let data = UserDefaults.standard.data(forKey: "vocamac.snippets") {
            do {
                snippets = try JSONDecoder().decode([Snippet].self, from: data)
            } catch {
                VocaLogger.error(.appState, "Failed to decode snippets: \(error)")
            }
        }
    }

    func saveSnippets() {
        saveSnippets(snippets)
    }

    private func saveSnippets(_ snippets: [Snippet]) {
        do {
            let encoded = try JSONEncoder().encode(snippets)
            UserDefaults.standard.set(encoded, forKey: "vocamac.snippets")
        } catch {
            VocaLogger.error(.appState, "Failed to encode snippets: \(error)")
        }
    }

    func expandSnippets(in text: String) -> String {
        return snippetExpander.expand(in: text, using: snippets)
    }
}