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

280 KB
Raw Blame
import AppKit
import ApplicationServices
import Combine
import CryptoKit
import Foundation
import ServiceManagement
import SwiftUI
#if canImport(FluidAudio)
import FluidAudio
#endif

// swiftlint:disable file_length type_body_length
final class SettingsStore: ObservableObject {
    enum UpdateKeys {
        static let autoUpdateCheckEnabled = "AutoUpdateCheckEnabled"
        static let showUpdatePopups = "ShowUpdatePopups"
        static let popupPreferenceRevision = "UpdatePopupPreferenceRevision"
        static let betaReleasesEnabled = "BetaReleasesEnabled"
        static let channelPreferenceRevision = "UpdateChannelPreferenceRevision"
        static let lastUpdateCheckDate = "LastUpdateCheckDate"
        static let updatePromptSnoozedUntil = "UpdatePromptSnoozedUntil"
        static let snoozedUpdateVersion = "SnoozedUpdateVersion"
    }

    static let microphonePriorityMigrationVersion = 4

    static let shared = SettingsStore()
    private static let automaticWhisperLanguageCode = "auto"
    static let transcriptionPreviewCharLimitRange: ClosedRange<Int> = 50...800
    static let transcriptionPreviewCharLimitStep = 50
    static let defaultTranscriptionPreviewCharLimit = 150
    static let privateAIContextTokenLimitRange: ClosedRange<Int> = 2048...8192
    static let privateAIContextTokenLimitStep = 512
    static let defaultPrivateAIContextTokenLimit = 4096
    static let privateAIDictationSystemOverheadTokens = 1280
    static let privateAIDictationMinimumOutputTokens = 256
    static let privateAIDictationRoundTripTokenCost = 2.75
    private static let privateAIDenseSegmentByteThreshold = 12
    private static let privateAIDenseBytesPerToken = 2
    static let privateAIBackendPreferenceDefaultsKey = "FluidIntelligenceBackendPreference"
    private static let forcedOnboardingResetIntroducedAt = Date(timeIntervalSince1970: 1_782_091_732)
    private let defaults = UserDefaults.standard
    private let keychain = KeychainService.shared
    private(set) var launchAtStartupEnabled = false
    private(set) var launchAtStartupErrorMessage: String?
    private(set) var launchAtStartupStatusMessage =
        "FluidVoice reflects the actual macOS login item state. Unsigned or development builds may fail to enable this."

    private init() {
        self.migrateTranscriptionStartSoundIfNeeded()
        self.ensureDebugLoggingDefaults()
        self.migrateProviderAPIKeysIfNeeded()
        self.scrubSavedProviderAPIKeys()
        self.migrateExplicitDictationPromptsIfNeeded()
        self.migrateDictationPromptProfilesIfNeeded()
        self.migrateLegacyDictationAIPreferenceIfNeeded()
        self.migrateSecondaryPromptShortcutIfNeeded()
        Self.migrateModifierOnlyCancelShortcutIfNeeded(defaults: self.defaults)
        self.retireLegacySecondaryPromptShortcutIfNeeded()
        self.normalizePromptSelectionsIfNeeded()
        self.makeEditModeIndependentIfNeeded()
        self.purgeRetiredAppleIntelligenceState()
        self.repairForcedOnboardingResetIfNeeded()
        self.migrateOverlayBottomOffsetTo50IfNeeded()
        self.migratePrivateAIContextDefaultTo4KIfNeeded()
        Self.migrateTextInsertionModeToReliablePasteIfNeeded(defaults: self.defaults)
        self.refreshLaunchAtStartupStatus(clearError: true, logMismatch: false)
    }

    static func clampPrivateAIContextTokenLimit(_ value: Int) -> Int {
        min(max(value, self.privateAIContextTokenLimitRange.lowerBound), self.privateAIContextTokenLimitRange.upperBound)
    }

    static func estimatedPrivateAIDictationWords(for contextTokenLimit: Int) -> Int {
        let availableTokens = max(0, Self.clampPrivateAIContextTokenLimit(contextTokenLimit) - Self.privateAIDictationSystemOverheadTokens)
        let inputTokens = Double(availableTokens) / Self.privateAIDictationRoundTripTokenCost
        return max(100, Int((inputTokens * 0.75 / 50).rounded(.up)) * 50)
    }

    struct PrivateAIDictationTokenBudget: Equatable {
        let maxOutputTokens: Int
        let hasSufficientHeadroom: Bool
    }

    static func privateAIDictationTokenBudget(forInputText inputText: String, contextTokenLimit: Int) -> PrivateAIDictationTokenBudget {
        let estimatedInputTokens = self.estimatedPrivateAIInputTokens(for: inputText)
        let requestedOutputTokens = max(
            Self.privateAIDictationMinimumOutputTokens,
            Int((Double(estimatedInputTokens) * 1.15).rounded(.up)) + 64
        )
        let availableOutputTokens = Self.clampPrivateAIContextTokenLimit(contextTokenLimit)
            - Self.privateAIDictationSystemOverheadTokens
            - estimatedInputTokens
        return PrivateAIDictationTokenBudget(
            maxOutputTokens: min(requestedOutputTokens, max(Self.privateAIDictationMinimumOutputTokens, availableOutputTokens)),
            hasSufficientHeadroom: availableOutputTokens >= requestedOutputTokens
        )
    }

    private static func estimatedPrivateAIInputTokens(for inputText: String) -> Int {
        let segments = inputText.split { $0.isWhitespace || $0.isNewline }
        let wordBasedEstimate = Int((Double(segments.count) / 0.75).rounded(.up))
        // Keep the existing prose estimate, but charge long unbroken input by UTF-8 size so
        // URLs, identifiers, and languages without whitespace cannot look like a single token.
        let denseSegmentEstimate = segments.reduce(into: 0) { estimate, segment in
            let byteCount = segment.utf8.count
            if byteCount > Self.privateAIDenseSegmentByteThreshold {
                estimate += (byteCount + Self.privateAIDenseBytesPerToken - 1)
                    / Self.privateAIDenseBytesPerToken
            } else {
                estimate += 1
            }
        }
        return max(1, max(wordBasedEstimate, denseSegmentEstimate))
    }

    static func privateAIMaxOutputTokens(forInputText inputText: String, contextTokenLimit: Int) -> Int {
        self.privateAIDictationTokenBudget(
            forInputText: inputText,
            contextTokenLimit: contextTokenLimit
        ).maxOutputTokens
    }

    enum PrivateAIBackendPreference: String, Codable, CaseIterable, Identifiable {
        case auto
        case llama
        case mlx

        var id: String {
            self.rawValue
        }

        /// Default backend when no preference is stored.
        /// Apple Silicon → MLX (fastest Fluid-1 path). Intel → llama.cpp.
        static var systemDefault: PrivateAIBackendPreference {
            CPUArchitecture.isAppleSilicon ? .mlx : .llama
        }

        var displayName: String {
            switch self {
            case .auto: return Self.systemDefault.displayName
            case .llama: return "llama.cpp (Compatibility)"
            case .mlx: return "MLX (Recommended)"
            }
        }

        var detail: String {
            switch self {
            case .auto:
                return Self.systemDefault.detail
            case .llama:
                return CPUArchitecture.isAppleSilicon
                    ? "Optional and slower than MLX. Replaces MLX after verification."
                    : "Recommended compatibility backend for Intel Macs."
            case .mlx:
                return "Recommended and faster than llama.cpp. Replaces it after verification."
            }
        }
    }

    // MARK: - Prompt Profiles (Unified)

    enum PromptMode: String, Codable, CaseIterable, Identifiable {
        case dictate
        case edit
        case write // legacy persisted value (decoded as .edit)
        case rewrite // legacy persisted value (decoded as .edit)

        var id: String {
            self.rawValue
        }

        static var visiblePromptModes: [PromptMode] {
            [.dictate, .edit]
        }

        var normalized: PromptMode {
            switch self {
            case .dictate:
                return .dictate
            case .edit, .write, .rewrite:
                return .edit
            }
        }

        var displayName: String {
            switch self.normalized {
            case .dictate:
                return "Dictate"
            case .edit:
                return "Edit"
            case .write, .rewrite:
                return "Edit"
            }
        }

        init(from decoder: Decoder) throws {
            let container = try decoder.singleValueContainer()
            let raw = (try? container.decode(String.self).lowercased()) ?? Self.dictate.rawValue
            switch raw {
            case "dictate":
                self = .dictate
            case "edit", "write", "rewrite":
                self = .edit
            default:
                self = .dictate
            }
        }

        func encode(to encoder: Encoder) throws {
            var container = encoder.singleValueContainer()
            try container.encode(self.normalized.rawValue)
        }
    }

    enum DictationShortcutSlot: String, Codable, CaseIterable, Identifiable {
        case primary
        case secondary

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .primary:
                return "Primary Dictation Shortcut"
            case .secondary:
                return "Secondary Dictation Shortcut"
            }
        }
    }

    enum MicrophoneSelectionMode: String, Codable, CaseIterable, Identifiable {
        case system
        case manual

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .system:
                return "Use macOS Default"
            case .manual:
                return "Use Preferred Microphone"
            }
        }
    }

    struct MicrophonePriorityEntry: Codable, Hashable, Identifiable {
        let uid: String
        var name: String

        var id: String {
            self.uid
        }
    }

    /// Shared user-facing names; persisted selection IDs remain independent.
    enum DictationModeLabels {
        static let externalDefault = "Default"
        static let smart = "Smart"
        static let smartWithModel = "\(smart) — Fluid-1"
    }

    enum DictationPromptSelection: Equatable {
        case off, `default`, privateAI
        case profile(String)
    }

    struct DictationPromptProfile: Codable, Identifiable, Hashable {
        let id: String
        var name: String
        var prompt: String
        var mode: PromptMode
        var includeContext: Bool
        var usesExplicitDictationPrompt = true
        var usesLegacyEmptyPromptFallback = false
        var legacyEmptyShortcutUsesBasePrompt = false
        var createdAt: Date
        var updatedAt: Date

        private enum CodingKeys: String, CodingKey {
            case id
            case name
            case prompt
            case mode
            case includeContext
            case usesExplicitDictationPrompt
            case usesLegacyEmptyPromptFallback
            case legacyEmptyShortcutUsesBasePrompt
            case createdAt
            case updatedAt
        }

        init(
            id: String = UUID().uuidString,
            name: String,
            prompt: String,
            mode: PromptMode = .dictate,
            includeContext: Bool = false,
            createdAt: Date = Date(),
            updatedAt: Date = Date()
        ) {
            self.id = id
            self.name = name
            self.prompt = prompt
            self.mode = mode
            self.includeContext = includeContext
            self.createdAt = createdAt
            self.updatedAt = updatedAt
        }

        init(from decoder: Decoder) throws {
            let container = try decoder.container(keyedBy: CodingKeys.self)
            self.id = try container.decode(String.self, forKey: .id)
            self.name = try container.decode(String.self, forKey: .name)
            self.prompt = try container.decode(String.self, forKey: .prompt)
            self.mode = try (container.decodeIfPresent(PromptMode.self, forKey: .mode) ?? .dictate).normalized
            self.includeContext = try container.decodeIfPresent(Bool.self, forKey: .includeContext) ?? false
            self.usesExplicitDictationPrompt = try container.decodeIfPresent(Bool.self, forKey: .usesExplicitDictationPrompt) ?? false
            self.usesLegacyEmptyPromptFallback = try container.decodeIfPresent(Bool.self, forKey: .usesLegacyEmptyPromptFallback) ?? false
            self.legacyEmptyShortcutUsesBasePrompt = try container.decodeIfPresent(Bool.self, forKey: .legacyEmptyShortcutUsesBasePrompt) ?? false
            self.createdAt = try container.decode(Date.self, forKey: .createdAt)
            self.updatedAt = try container.decode(Date.self, forKey: .updatedAt)
        }
    }

    struct AppPromptBinding: Codable, Identifiable, Hashable {
        let id: String
        var mode: PromptMode
        var appBundleID: String
        var appName: String
        var promptID: String?
        var createdAt: Date
        var updatedAt: Date

        private enum CodingKeys: String, CodingKey {
            case id
            case mode
            case appBundleID
            case appName
            case promptID
            case createdAt
            case updatedAt
        }

        init(
            id: String = UUID().uuidString,
            mode: PromptMode,
            appBundleID: String,
            appName: String,
            promptID: String?,
            createdAt: Date = Date(),
            updatedAt: Date = Date()
        ) {
            self.id = id
            self.mode = mode.normalized
            self.appBundleID = Self.normalizeBundleID(appBundleID)
            let trimmedName = appName.trimmingCharacters(in: .whitespacesAndNewlines)
            self.appName = trimmedName.isEmpty ? self.appBundleID : trimmedName
            let trimmedPromptID = promptID?.trimmingCharacters(in: .whitespacesAndNewlines)
            self.promptID = (trimmedPromptID?.isEmpty == true) ? nil : trimmedPromptID
            self.createdAt = createdAt
            self.updatedAt = updatedAt
        }

        init(from decoder: Decoder) throws {
            let container = try decoder.container(keyedBy: CodingKeys.self)
            self.id = try container.decode(String.self, forKey: .id)
            self.mode = try (container.decodeIfPresent(PromptMode.self, forKey: .mode) ?? .dictate).normalized
            let rawBundleID = try container.decodeIfPresent(String.self, forKey: .appBundleID) ?? ""
            self.appBundleID = Self.normalizeBundleID(rawBundleID)
            let rawName = try container.decodeIfPresent(String.self, forKey: .appName) ?? ""
            let trimmedName = rawName.trimmingCharacters(in: .whitespacesAndNewlines)
            self.appName = trimmedName.isEmpty ? self.appBundleID : trimmedName
            let rawPromptID = try container.decodeIfPresent(String.self, forKey: .promptID)
            let trimmedPromptID = rawPromptID?.trimmingCharacters(in: .whitespacesAndNewlines)
            self.promptID = (trimmedPromptID?.isEmpty == true) ? nil : trimmedPromptID
            self.createdAt = try container.decodeIfPresent(Date.self, forKey: .createdAt) ?? Date()
            self.updatedAt = try container.decodeIfPresent(Date.self, forKey: .updatedAt) ?? Date()
        }

        private static func normalizeBundleID(_ value: String) -> String {
            value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
        }
    }

    struct DictationPromptConfiguration: Codable, Equatable {
        var shortcut: HotkeyShortcut?
        var providerID: String
        var modelName: String

        init(shortcut: HotkeyShortcut? = nil, providerID: String = "", modelName: String = "") {
            self.shortcut = shortcut
            self.providerID = providerID
            self.modelName = modelName
        }
    }

    enum PromptResolutionSource: String {
        case appBindingProfile
        case appBindingDefault
        case selectedProfile
        case defaultOverride
        case builtInDefault
    }

    struct PromptResolution {
        let source: PromptResolutionSource
        let profile: DictationPromptProfile?
        let appBinding: AppPromptBinding?
        let promptBody: String
        let systemPrompt: String
    }

    /// User-defined dictation prompt profiles (named system prompts for dictation enhancement).
    /// The built-in default prompt is not stored here.
    var dictationPromptProfiles: [DictationPromptProfile] {
        get {
            guard let data = self.defaults.data(forKey: Keys.dictationPromptProfiles),
                  let decoded = try? JSONDecoder().decode([DictationPromptProfile].self, from: data)
            else {
                return []
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue.map {
                Self.migrateExplicitDictationPrompt($0, legacySendOnly: self.defaults.bool(forKey: Keys.sendCustomPromptOnly))
            }) {
                self.defaults.set(encoded, forKey: Keys.dictationPromptProfiles)
            } else {
                // If encoding fails, avoid writing corrupt data.
                self.defaults.removeObject(forKey: Keys.dictationPromptProfiles)
            }
        }
    }

    /// Per-app prompt routing rules keyed by mode + app bundle identifier.
    /// `promptID == nil` means force Default prompt for that mode in the matched app.
    var appPromptBindings: [AppPromptBinding] {
        get {
            guard let data = self.defaults.data(forKey: Keys.appPromptBindings),
                  let decoded = try? JSONDecoder().decode([AppPromptBinding].self, from: data)
            else {
                return []
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue) {
                self.defaults.set(encoded, forKey: Keys.appPromptBindings)
            } else {
                self.defaults.removeObject(forKey: Keys.appPromptBindings)
            }
        }
    }

    var dictationPromptConfigurations: [String: DictationPromptConfiguration] {
        get {
            guard let data = self.defaults.data(forKey: Keys.dictationPromptConfigurations),
                  let decoded = try? JSONDecoder().decode([String: DictationPromptConfiguration].self, from: data)
            else {
                return [:]
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue) {
                self.defaults.set(encoded, forKey: Keys.dictationPromptConfigurations)
            } else {
                self.defaults.removeObject(forKey: Keys.dictationPromptConfigurations)
            }
        }
    }

    /// Selected dictation prompt profile ID. `nil` means "Default".
    var selectedDictationPromptID: String? {
        get {
            let value = self.defaults.string(forKey: Keys.selectedDictationPromptID)
            return value?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == true ? nil : value
        }
        set {
            objectWillChange.send()
            if let id = newValue?.trimmingCharacters(in: .whitespacesAndNewlines), !id.isEmpty {
                self.defaults.set(id, forKey: Keys.selectedDictationPromptID)
            } else {
                self.defaults.removeObject(forKey: Keys.selectedDictationPromptID)
            }
        }
    }

    var isDictationPromptOff: Bool {
        get { self.defaults.bool(forKey: Keys.dictationPromptOff) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.dictationPromptOff)
        }
    }

    var isEditPromptOff: Bool {
        get { self.defaults.bool(forKey: Keys.editPromptOff) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.editPromptOff)
        }
    }

    var dictationPromptSelection: DictationPromptSelection {
        self.dictationPromptSelection(for: .primary)
    }

    func setDictationPromptSelection(_ selection: DictationPromptSelection) {
        self.setDictationPromptSelection(selection, for: .primary)
    }

    func dictationPromptSelection(for slot: DictationShortcutSlot, privateAIAvailable: Bool? = nil) -> DictationPromptSelection {
        if self.isDictationPromptOff(for: slot) { return .off }
        if let promptID = self.selectedDictationPromptID(for: slot) {
            if promptID == PrivateAIProviderPromptFormat.promptSelectionID {
                return (privateAIAvailable ?? PrivateAIProviderPromptFormat.isAvailable(settings: self)) ? .privateAI : .default
            }
            return .profile(promptID)
        }
        return .default
    }

    func setDictationPromptSelection(_ selection: DictationPromptSelection, for slot: DictationShortcutSlot) {
        let selectedID: String?
        switch selection {
        case .off, .default:
            selectedID = nil
        case .privateAI:
            selectedID = PrivateAIProviderPromptFormat.promptSelectionID
        case let .profile(promptID):
            selectedID = promptID
        }
        self.setDictationPromptOff(selection == .off, for: slot)
        self.setSelectedDictationPromptID(selectedID, for: slot)
    }

    func dictationPromptConfigurationKey(for selection: DictationPromptSelection) -> String? {
        switch selection {
        case .off:
            return nil
        case .privateAI:
            return "__privateAI__"
        case .default:
            return "__default__"
        case let .profile(promptID):
            let trimmed = promptID.trimmingCharacters(in: .whitespacesAndNewlines)
            return trimmed.isEmpty ? nil : "profile:\(trimmed)"
        }
    }

    func dictationPromptSelection(forConfigurationKey key: String) -> DictationPromptSelection? {
        if key == "__privateAI__" {
            return .privateAI
        }
        if key == "__default__" {
            return .default
        }
        if key.hasPrefix("profile:") {
            let id = String(key.dropFirst("profile:".count))
            guard self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode.normalized == .dictate }) else { return nil }
            return .profile(id)
        }
        return nil
    }

    func dictationPromptConfiguration(for selection: DictationPromptSelection) -> DictationPromptConfiguration {
        guard let key = self.dictationPromptConfigurationKey(for: selection) else {
            return DictationPromptConfiguration()
        }
        var configuration = self.dictationPromptConfigurations[key] ?? DictationPromptConfiguration()
        if configuration.shortcut?.requiresModifierForRecording == true { configuration.shortcut = nil }
        return configuration
    }

    func setDictationPromptConfiguration(_ configuration: DictationPromptConfiguration, for selection: DictationPromptSelection) {
        guard let key = self.dictationPromptConfigurationKey(for: selection) else { return }
        let providerID = configuration.providerID.trimmingCharacters(in: .whitespacesAndNewlines)
        let modelName = configuration.modelName.trimmingCharacters(in: .whitespacesAndNewlines)
        var configurations = self.dictationPromptConfigurations
        if configuration.shortcut == nil, providerID.isEmpty, modelName.isEmpty {
            configurations.removeValue(forKey: key)
        } else {
            configurations[key] = DictationPromptConfiguration(
                shortcut: configuration.shortcut,
                providerID: providerID,
                modelName: modelName
            )
        }
        self.dictationPromptConfigurations = configurations
    }

    func removeDictationPromptConfiguration(for selection: DictationPromptSelection) {
        guard let key = self.dictationPromptConfigurationKey(for: selection) else { return }
        var configurations = self.dictationPromptConfigurations
        configurations.removeValue(forKey: key)
        self.dictationPromptConfigurations = configurations
    }

    func dictationPromptShortcutAssignments() -> [(selection: DictationPromptSelection, shortcut: HotkeyShortcut)] {
        self.dictationPromptConfigurations.compactMap { key, configuration in
            guard let shortcut = configuration.shortcut, !shortcut.requiresModifierForRecording else { return nil }
            if key == "__default__" {
                return (.default, shortcut)
            }
            if key == "__privateAI__" {
                return (.privateAI, shortcut)
            }
            if key.hasPrefix("profile:") {
                let id = String(key.dropFirst("profile:".count))
                guard self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode.normalized == .dictate }) else { return nil }
                return (.profile(id), shortcut)
            }
            return nil
        }
    }

    /// Convenience: currently selected profile, or nil if Default/invalid selection.
    var selectedDictationPromptProfile: DictationPromptProfile? {
        self.selectedPromptProfile(for: .dictate)
    }

    /// Selected edit prompt profile ID. `nil` means "Default Edit".
    var selectedEditPromptID: String? {
        get {
            if let value = self.defaults.string(forKey: Keys.selectedEditPromptID),
               value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
            {
                return value
            }
            if let legacyRewrite = self.defaults.string(forKey: Keys.selectedRewritePromptID),
               legacyRewrite.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
            {
                return legacyRewrite
            }
            if let legacyWrite = self.defaults.string(forKey: Keys.selectedWritePromptID),
               legacyWrite.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
            {
                return legacyWrite
            }
            return nil
        }
        set {
            objectWillChange.send()
            if let id = newValue?.trimmingCharacters(in: .whitespacesAndNewlines), !id.isEmpty {
                self.defaults.set(id, forKey: Keys.selectedEditPromptID)
            } else {
                self.defaults.removeObject(forKey: Keys.selectedEditPromptID)
            }
            // Normalize to the new key only.
            self.defaults.removeObject(forKey: Keys.selectedWritePromptID)
            self.defaults.removeObject(forKey: Keys.selectedRewritePromptID)
        }
    }

    /// Legacy alias retained for compatibility.
    var selectedWritePromptID: String? {
        get { self.selectedEditPromptID }
        set { self.selectedEditPromptID = newValue }
    }

    /// Legacy alias retained for compatibility.
    var selectedRewritePromptID: String? {
        get { self.selectedEditPromptID }
        set { self.selectedEditPromptID = newValue }
    }

    func selectedPromptID(for mode: PromptMode) -> String? {
        switch mode.normalized {
        case .dictate:
            if self.selectedDictationPromptID == PrivateAIProviderPromptFormat.promptSelectionID,
               !PrivateAIProviderPromptFormat.isAvailable(settings: self) { return nil }
            return self.selectedDictationPromptID
        case .edit:
            return self.selectedEditPromptID
        case .write, .rewrite:
            return self.selectedEditPromptID
        }
    }

    func selectedDictationPromptID(for slot: DictationShortcutSlot) -> String? {
        switch slot {
        case .primary:
            return self.selectedDictationPromptID
        case .secondary:
            return self.promptModeSelectedPromptID
        }
    }

    func setSelectedDictationPromptID(_ id: String?, for slot: DictationShortcutSlot) {
        switch slot {
        case .primary:
            self.selectedDictationPromptID = id
        case .secondary:
            self.promptModeSelectedPromptID = id
        }
    }

    func isDictationPromptOff(for slot: DictationShortcutSlot) -> Bool {
        switch slot {
        case .primary:
            return self.isDictationPromptOff
        case .secondary:
            return self.isSecondaryDictationPromptOff
        }
    }

    func setDictationPromptOff(_ isOff: Bool, for slot: DictationShortcutSlot) {
        switch slot {
        case .primary:
            self.isDictationPromptOff = isOff
        case .secondary:
            self.isSecondaryDictationPromptOff = isOff
        }
    }

    func isPromptOff(for mode: PromptMode) -> Bool {
        switch mode.normalized {
        case .dictate:
            return self.isDictationPromptOff
        case .edit, .write, .rewrite:
            return self.isEditPromptOff
        }
    }

    func setPromptOff(_ isOff: Bool, for mode: PromptMode) {
        switch mode.normalized {
        case .dictate:
            self.setDictationPromptSelection(isOff ? .off : .default)
        case .edit, .write, .rewrite:
            self.isEditPromptOff = isOff
        }
    }

    func selectedDictationPromptProfile(for slot: DictationShortcutSlot) -> DictationPromptProfile? {
        guard let id = self.selectedDictationPromptID(for: slot) else { return nil }
        return self.dictationPromptProfiles.first(where: { $0.id == id && $0.mode.normalized == .dictate })
    }

    func resolvedDictationPromptSelection(for slot: DictationShortcutSlot, appBundleID: String?, privateAIAvailable: Bool? = nil) -> DictationPromptSelection {
        if let manual = DictationAppSession.shared.choice(for: slot, appID: appBundleID) { return manual }
        let selection = self.dictationPromptSelection(for: slot, privateAIAvailable: privateAIAvailable)
        guard selection != .off else { return .off }
        let appOnly = self.promptRoutingScope(for: .dictate) == .selectedAppsOnly
        guard appOnly || Self.dictationSelectionSupportsAppOverride(selection) else { return selection }
        guard let binding = self.appPromptBinding(for: .dictate, appBundleID: appBundleID) else {
            return appOnly ? .off : selection
        }
        guard let id = binding.promptID,
              self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode.normalized == .dictate })
        else { return .default }
        return .profile(id)
    }

    private func manualDictationPromptBody(_ selection: DictationPromptSelection, system: Bool) -> String {
        if selection == .off { return "" }
        if case let .profile(id) = selection,
           let profile = self.dictationPromptProfiles.first(where: { $0.id == id && $0.mode.normalized == .dictate })
        {
            let body = Self.customPromptBody(profile.prompt, mode: .dictate)
            if !body.isEmpty || !profile.usesLegacyEmptyPromptFallback {
                return system ? self.systemPrompt(forCustomProfileBody: body, mode: .dictate) : body
            }
        }
        let fallback = self.defaultPromptResolution(for: .dictate, source: .defaultOverride, appBinding: nil)
        return system ? fallback.systemPrompt : fallback.promptBody
    }

    func resolvedDictationPromptProfile(for slot: DictationShortcutSlot, appBundleID: String?, privateAIAvailable: Bool? = nil) -> DictationPromptProfile? {
        switch self.resolvedDictationPromptSelection(for: slot, appBundleID: appBundleID, privateAIAvailable: privateAIAvailable) {
        case .off:
            return nil
        case let .profile(promptID):
            return self.dictationPromptProfiles.first(where: { $0.id == promptID && $0.mode.normalized == .dictate })
        case .default, .privateAI:
            guard DictationAppSession.shared.choice(for: slot, appID: appBundleID) == nil else { return nil }
            guard let binding = self.appPromptBinding(for: .dictate, appBundleID: appBundleID) else { return nil }
            let promptID = binding.promptID
            return self.dictationPromptProfiles.first {
                $0.id == promptID && $0.mode.normalized == .dictate
            }
        }
    }

    func isAppDictationPromptBindingActive(for slot: DictationShortcutSlot, appBundleID: String?, privateAIAvailable: Bool? = nil) -> Bool {
        guard DictationAppSession.shared.choice(for: slot, appID: appBundleID) == nil else { return false }
        let selection = self.dictationPromptSelection(for: slot, privateAIAvailable: privateAIAvailable)
        guard Self.dictationSelectionSupportsAppOverride(selection) else { return false }
        return self.hasAppPromptBinding(for: .dictate, appBundleID: appBundleID)
    }

    static func dictationSelectionSupportsAppOverride(_ selection: DictationPromptSelection) -> Bool {
        selection == .default || selection == .privateAI
    }

    func dictationOverlayLabel(for slot: DictationShortcutSlot, appBundleID: String?) -> String {
        let selection = self.resolvedDictationPromptSelection(for: slot, appBundleID: appBundleID)
        guard selection != .off else { return "Basic" }
        let route = DictationProviderRoute.resolve(settings: self, dictationSlot: slot, appBundleID: appBundleID)
        let mode = self.dictationPromptDisplayName(for: slot, appBundleID: appBundleID)
        let modelName = PrivateAIModelRegistry.model(id: route.model)?.displayName ?? route.model
        let model = modelName.replacingOccurrences(of: "Fluid-1 ", with: "")
        // An unroutable selection runs no cleanup at all, so it reads as Basic rather than
        // as a long "· Unavailable" line that overflows the pill.
        return model.isEmpty ? "Basic" : "\(mode) · \(model)"
    }

    func dictationPromptDisplayName(for slot: DictationShortcutSlot, appBundleID: String?, privateAIAvailable: Bool? = nil) -> String {
        switch self.resolvedDictationPromptSelection(for: slot, appBundleID: appBundleID, privateAIAvailable: privateAIAvailable) {
        case .off:
            return "Basic"
        case .default:
            if let profile = self.resolvedDictationPromptProfile(for: slot, appBundleID: appBundleID, privateAIAvailable: privateAIAvailable) {
                let name = profile.name.trimmingCharacters(in: .whitespacesAndNewlines)
                return name.isEmpty ? "Untitled" : name
            }
            return "Default"
        case .privateAI:
            if self.isAppDictationPromptBindingActive(for: slot, appBundleID: appBundleID, privateAIAvailable: privateAIAvailable) {
                if let profile = self.resolvedDictationPromptProfile(for: slot, appBundleID: appBundleID, privateAIAvailable: privateAIAvailable) {
                    let name = profile.name.trimmingCharacters(in: .whitespacesAndNewlines)
                    return name.isEmpty ? "Untitled" : name
                }
                return "Default"
            }
            return DictationModeLabels.smart
        case let .profile(promptID):
            guard let profile = self.dictationPromptProfiles.first(where: { $0.id == promptID && $0.mode.normalized == .dictate }) else {
                return "Default"
            }
            let name = profile.name.trimmingCharacters(in: .whitespacesAndNewlines)
            return name.isEmpty ? "Untitled" : name
        }
    }

    func setSelectedPromptID(_ id: String?, for mode: PromptMode) {
        switch mode.normalized {
        case .dictate:
            if let id {
                self.setDictationPromptSelection(.profile(id))
            } else {
                self.setDictationPromptSelection(.default)
            }
        case .edit:
            self.isEditPromptOff = false
            self.selectedEditPromptID = id
        case .write, .rewrite:
            self.isEditPromptOff = false
            self.selectedEditPromptID = id
        }
    }

    func promptProfiles(for mode: PromptMode) -> [DictationPromptProfile] {
        let target = mode.normalized
        return self.dictationPromptProfiles.filter { $0.mode.normalized == target }
    }

    func selectedPromptProfile(for mode: PromptMode) -> DictationPromptProfile? {
        guard let id = self.selectedPromptID(for: mode) else { return nil }
        let target = mode.normalized
        return self.dictationPromptProfiles.first(where: { $0.id == id && $0.mode.normalized == target })
    }

    func appPromptBindings(for mode: PromptMode) -> [AppPromptBinding] {
        let target = mode.normalized
        return self.appPromptBindings.filter { $0.mode.normalized == target }
    }

    func appPromptBinding(for mode: PromptMode, appBundleID: String?) -> AppPromptBinding? {
        guard let normalizedBundleID = Self.normalizeAppBundleID(appBundleID) else { return nil }
        let target = mode.normalized
        return self.appPromptBindings.first {
            $0.mode.normalized == target &&
                $0.appBundleID == normalizedBundleID
        }
    }

    func hasAppPromptBinding(for mode: PromptMode, appBundleID: String?) -> Bool {
        self.appPromptBinding(for: mode, appBundleID: appBundleID) != nil
    }

    func upsertAppPromptBinding(
        for mode: PromptMode,
        appBundleID: String,
        appName: String,
        promptID: String?
    ) {
        guard let normalizedBundleID = Self.normalizeAppBundleID(appBundleID) else { return }

        let normalizedMode = mode.normalized
        let trimmedName = appName.trimmingCharacters(in: .whitespacesAndNewlines)
        let resolvedName = trimmedName.isEmpty ? normalizedBundleID : trimmedName
        let cleanedPromptID = promptID?.trimmingCharacters(in: .whitespacesAndNewlines)
        let resolvedPromptID = (cleanedPromptID?.isEmpty == true) ? nil : cleanedPromptID
        let now = Date()

        var bindings = self.appPromptBindings
        if let idx = bindings.firstIndex(where: {
            $0.mode.normalized == normalizedMode &&
                $0.appBundleID == normalizedBundleID
        }) {
            bindings[idx].mode = normalizedMode
            bindings[idx].appName = resolvedName
            bindings[idx].promptID = resolvedPromptID
            bindings[idx].updatedAt = now
        } else {
            bindings.append(
                AppPromptBinding(
                    mode: normalizedMode,
                    appBundleID: normalizedBundleID,
                    appName: resolvedName,
                    promptID: resolvedPromptID,
                    createdAt: now,
                    updatedAt: now
                )
            )
        }

        self.appPromptBindings = bindings
    }

    func removeAppPromptBinding(id: String) {
        var bindings = self.appPromptBindings
        bindings.removeAll { $0.id == id }
        self.appPromptBindings = bindings
    }

    func removeAppPromptBinding(for mode: PromptMode, appBundleID: String?) {
        guard let normalizedBundleID = Self.normalizeAppBundleID(appBundleID) else { return }
        let normalizedMode = mode.normalized
        var bindings = self.appPromptBindings
        bindings.removeAll {
            $0.mode.normalized == normalizedMode &&
                $0.appBundleID == normalizedBundleID
        }
        self.appPromptBindings = bindings
    }

    /// Re-run prompt/profile normalization after profile mutations.
    func reconcilePromptStateAfterProfileChanges() {
        self.normalizePromptSelectionsIfNeeded()
        self.normalizeDictationPromptConfigurationsIfNeeded()
    }

    private static func normalizeAppBundleID(_ value: String?) -> String? {
        guard let value else { return nil }
        let normalized = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
        return normalized.isEmpty ? nil : normalized
    }

    /// Optional override for the built-in default dictation system prompt.
    /// - nil: use the built-in default prompt
    /// - empty string: use an empty system prompt
    /// - otherwise: use the provided text as the default prompt
    var defaultDictationPromptOverride: String? {
        get {
            // Distinguish "not set" from "set to empty string"
            guard self.defaults.object(forKey: Keys.defaultDictationPromptOverride) != nil else {
                return nil
            }
            return self.defaults.string(forKey: Keys.defaultDictationPromptOverride) ?? ""
        }
        set {
            objectWillChange.send()
            if let value = newValue {
                self.defaults.set(value, forKey: Keys.defaultDictationPromptOverride) // allow empty
            } else {
                self.defaults.removeObject(forKey: Keys.defaultDictationPromptOverride)
            }
        }
    }

    /// Optional override for the built-in default edit system prompt.
    var defaultEditPromptOverride: String? {
        get {
            if self.defaults.object(forKey: Keys.defaultEditPromptOverride) != nil {
                return self.defaults.string(forKey: Keys.defaultEditPromptOverride) ?? ""
            }
            if self.defaults.object(forKey: Keys.defaultRewritePromptOverride) != nil {
                return self.defaults.string(forKey: Keys.defaultRewritePromptOverride) ?? ""
            }
            if self.defaults.object(forKey: Keys.defaultWritePromptOverride) != nil {
                return self.defaults.string(forKey: Keys.defaultWritePromptOverride) ?? ""
            }
            return nil
        }
        set {
            objectWillChange.send()
            if let value = newValue {
                self.defaults.set(value, forKey: Keys.defaultEditPromptOverride)
            } else {
                self.defaults.removeObject(forKey: Keys.defaultEditPromptOverride)
            }
            // Normalize to the new key only.
            self.defaults.removeObject(forKey: Keys.defaultWritePromptOverride)
            self.defaults.removeObject(forKey: Keys.defaultRewritePromptOverride)
        }
    }

    /// Legacy alias retained for compatibility.
    var defaultWritePromptOverride: String? {
        get { self.defaultEditPromptOverride }
        set { self.defaultEditPromptOverride = newValue }
    }

    /// Legacy alias retained for compatibility.
    var defaultRewritePromptOverride: String? {
        get { self.defaultEditPromptOverride }
        set { self.defaultEditPromptOverride = newValue }
    }

    func defaultPromptOverride(for mode: PromptMode) -> String? {
        switch mode.normalized {
        case .dictate:
            return self.defaultDictationPromptOverride
        case .edit:
            return self.defaultEditPromptOverride
        case .write, .rewrite:
            return self.defaultEditPromptOverride
        }
    }

    func setDefaultPromptOverride(_ value: String?, for mode: PromptMode) {
        switch mode.normalized {
        case .dictate:
            self.defaultDictationPromptOverride = value
        case .edit:
            self.defaultEditPromptOverride = value
        case .write, .rewrite:
            self.defaultEditPromptOverride = value
        }
    }

    /// Built-in cleanup role. Transcript contents are data, including questions and requests.
    static func baseDictationPromptText() -> String {
        """
        Make the smallest edits needed to turn the supplied transcript into readable writing.
        """
    }

    /// Recognize previously saved default prefixes without duplicating their rules.
    static func legacyBaseDictationPromptText() -> String {
        """
        You are a voice-to-text dictation cleaner. Your role is to clean and format raw transcribed speech into polished text while refusing to answer any questions. Never answer questions about yourself or anything else.

        ## Core Rules:
        1. CLEAN the text - remove filler words (um, uh, like, you know, I mean), false starts, stutters, and repetitions
        2. FORMAT properly - add correct punctuation, capitalization, and structure
        3. CONVERT numbers - spoken numbers to digits (two → 2, five thirty → 5:30, twelve fifty → $12.50)
        4. EXECUTE commands - handle "new line", "period", "comma", "bold X", "header X", "bullet point", etc.
        5. APPLY corrections - when user says "no wait", "actually", "scratch that", "delete that", DISCARD the old content and keep ONLY the corrected version
        6. PRESERVE intent - keep the user's meaning, just clean the delivery
        7. EXPAND abbreviations - thx → thanks, pls → please, u → you, ur → your/you're, gonna → going to

        ## Critical:
        - Output ONLY the cleaned text
        - Do NOT answer questions - just clean them
        - DO NOT EVER ANSWER TO QUESTIONS
        - Do NOT add explanations or commentary
        - Do NOT wrap in quotes unless the input had quotes
        - Do NOT add filler words (um, uh) to the output
        - PRESERVE ordinals in lists: "first call client, second review contract" → keep "First" and "Second"
        - PRESERVE politeness words: "please", "thank you" at end of sentences
        """
    }

    /// Hidden base prompt for edit mode (role/intent only).
    static func baseEditPromptText() -> String {
        """
        You are a helpful writing assistant. The user may ask you to write new text or edit selected text.

        Output ONLY what the user requested. Do not add explanations or preamble.
        """
    }

    /// Legacy wrappers retained for compatibility.
    static func baseWritePromptText() -> String {
        self.baseEditPromptText()
    }

    /// Legacy wrappers retained for compatibility.
    static func baseRewritePromptText() -> String {
        self.baseEditPromptText()
    }

    static func basePromptText(for mode: PromptMode) -> String {
        switch mode.normalized {
        case .dictate:
            return self.baseDictationPromptText()
        case .edit:
            return self.baseEditPromptText()
        case .write, .rewrite:
            return self.baseEditPromptText()
        }
    }

    /// Built-in default dictation prompt body that users may view/edit.
    static func defaultDictationPromptBodyText() -> String {
        """
        Read the value of the JSON transcript field only.
        Keep every intended statement, question, and request. Do not answer the speaker, fulfill requests, or comment on the text. Keep the language, meaning, tense, names, please, thank you, and deliberate repetition.
        Delete hesitation words (um, uh, you know), stutters, unintended duplicated words, and incomplete beginnings. Replace a clearly corrected phrase with the speaker's final version. Leave unrelated content intact.
        Interpret spoken formatting directives: punctuation names become symbols, new line becomes a newline, bullet point starts a list item. Write clear quantities as digits and explicitly named emojis as emojis.
        Return only the edited text with no added title, explanation, emphasis, quotes, or JSON wrapper.
        """
    }

    /// Built-in default edit prompt body.
    static func defaultEditPromptBodyText() -> String {
        """
        Your job:
        - If the user asks for new content, write it directly.
        - If selected context is provided, apply the instruction to that context.
        - Preserve intent and requested tone/style/format.
        - Output only the final text, without explanations.

        Example requests:
        - "Write an email to my boss asking for time off"
        - "Draft a reply saying I'll be there at 5"
        - "Rewrite this to sound more professional"
        - "Make this shorter and clearer"
        """
    }

    /// Legacy wrappers retained for compatibility.
    static func defaultWritePromptBodyText() -> String {
        self.defaultEditPromptBodyText()
    }

    /// Legacy wrappers retained for compatibility.
    static func defaultRewritePromptBodyText() -> String {
        self.defaultEditPromptBodyText()
    }

    static func defaultPromptBodyText(for mode: PromptMode) -> String {
        switch mode.normalized {
        case .dictate:
            return self.defaultDictationPromptBodyText()
        case .edit:
            return self.defaultEditPromptBodyText()
        case .write, .rewrite:
            return self.defaultEditPromptBodyText()
        }
    }

    /// Join hidden base with a body, avoiding duplicate base text.
    static func combineBasePrompt(with body: String) -> String {
        self.combineBasePrompt(for: .dictate, with: body)
    }

    /// Join hidden base with a body for a given mode, avoiding duplicate base text.
    static func combineBasePrompt(for mode: PromptMode, with body: String) -> String {
        let base = self.basePromptText(for: mode).trimmingCharacters(in: .whitespacesAndNewlines)
        let trimmedBody = body.trimmingCharacters(in: .whitespacesAndNewlines)

        // If body already starts with base, return as-is to avoid double-prepending.
        if trimmedBody.lowercased().hasPrefix(base.lowercased()) {
            return trimmedBody
        }

        // If body is empty, return just the base.
        guard !trimmedBody.isEmpty else { return base }

        return "\(base)\n\n\(trimmedBody)"
    }

    /// Remove the hidden base prompt prefix if it was persisted previously.
    static func stripBaseDictationPrompt(from text: String) -> String {
        self.stripBasePrompt(for: .dictate, from: text)
    }

    /// Remove a hidden base prompt prefix for a given mode if it was persisted previously.
    static func stripBasePrompt(for mode: PromptMode, from text: String) -> String {
        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
        let bases = mode.normalized == .dictate
            ? [self.baseDictationPromptText(), self.legacyBaseDictationPromptText()]
            : [self.basePromptText(for: mode)]
        for base in bases {
            if let range = trimmed.range(of: base, options: [.anchored, .caseInsensitive]) {
                return String(trimmed[range.upperBound...]).trimmingCharacters(in: .whitespacesAndNewlines)
            }
        }

        return trimmed
    }

    /// Built-in default dictation system prompt shared across the app.
    static func defaultDictationPromptText() -> String {
        self.defaultSystemPromptText(for: .dictate)
    }

    static func defaultSystemPromptText(for mode: PromptMode) -> String {
        self.combineBasePrompt(for: mode, with: self.defaultPromptBodyText(for: mode))
    }

    static func contextTemplateText() -> String {
        """
        Use the following selected context to improve your response:
        {context}
        """
    }

    static func runtimeContextBlock(context: String, template: String) -> String {
        let trimmedContext = context.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmedContext.isEmpty else { return "" }
        if template.contains("{context}") {
            return template.replacingOccurrences(of: "{context}", with: trimmedContext)
        }
        return "\(template)\n\(trimmedContext)"
    }

    func promptResolution(for mode: PromptMode, appBundleID: String? = nil) -> PromptResolution {
        let normalizedMode = mode.normalized

        if normalizedMode == .edit, self.isEditPromptOff {
            return self.defaultPromptResolution(
                for: normalizedMode,
                source: .builtInDefault,
                appBinding: nil,
                allowDefaultOverride: false
            )
        }

        if let binding = self.appPromptBinding(for: normalizedMode, appBundleID: appBundleID) {
            if let promptID = binding.promptID,
               let profile = self.dictationPromptProfiles.first(where: {
                   $0.id == promptID &&
                       $0.mode.normalized == normalizedMode
               })
            {
                let body = Self.customPromptBody(profile.prompt, mode: normalizedMode)
                if !body.isEmpty || (profile.mode.normalized == .dictate && !profile.usesLegacyEmptyPromptFallback) {
                    return PromptResolution(
                        source: .appBindingProfile,
                        profile: profile,
                        appBinding: binding,
                        promptBody: body,
                        systemPrompt: self.systemPrompt(forCustomProfileBody: body, mode: normalizedMode)
                    )
                }
            }

            return self.defaultPromptResolution(
                for: normalizedMode,
                source: .appBindingDefault,
                appBinding: binding
            )
        }

        if self.promptRoutingScope(for: normalizedMode) == .selectedAppsOnly {
            return self.defaultPromptResolution(
                for: normalizedMode,
                source: .builtInDefault,
                appBinding: nil,
                allowDefaultOverride: false
            )
        }

        if let profile = self.selectedPromptProfile(for: normalizedMode) {
            let body = Self.customPromptBody(profile.prompt, mode: normalizedMode)
            if !body.isEmpty || (profile.mode.normalized == .dictate && !profile.usesLegacyEmptyPromptFallback) {
                return PromptResolution(
                    source: .selectedProfile,
                    profile: profile,
                    appBinding: nil,
                    promptBody: body,
                    systemPrompt: self.systemPrompt(forCustomProfileBody: body, mode: normalizedMode)
                )
            }
        }

        return self.defaultPromptResolution(for: normalizedMode, source: .defaultOverride, appBinding: nil)
    }

    func resolvedPromptProfile(for mode: PromptMode, appBundleID: String? = nil) -> DictationPromptProfile? {
        self.promptResolution(for: mode, appBundleID: appBundleID).profile
    }

    func effectiveDictationPromptBody(for slot: DictationShortcutSlot, appBundleID: String? = nil) -> String {
        if let manual = DictationAppSession.shared.choice(for: slot, appID: appBundleID) {
            return self.manualDictationPromptBody(manual, system: false)
        }
        if self.promptRoutingScope(for: .dictate) == .selectedAppsOnly {
            guard self.dictationPromptSelection(for: slot) != .off else { return "" }
            return self.effectivePromptBody(for: .dictate, appBundleID: appBundleID)
        }

        switch self.dictationPromptSelection(for: slot) {
        case .off:
            return ""
        case .default, .privateAI:
            return self.effectivePromptBody(for: .dictate, appBundleID: appBundleID)
        case let .profile(promptID):
            guard let profile = self.dictationPromptProfiles.first(where: { $0.id == promptID && $0.mode.normalized == .dictate }) else {
                return self.effectivePromptBody(for: .dictate, appBundleID: appBundleID)
            }
            let body = Self.customPromptBody(profile.prompt, mode: .dictate)
            if !body.isEmpty || (profile.mode.normalized == .dictate && !profile.usesLegacyEmptyPromptFallback) {
                return body
            }
            return self.effectivePromptBody(for: .dictate, appBundleID: appBundleID)
        }
    }

    func effectiveDictationSystemPrompt(for slot: DictationShortcutSlot, appBundleID: String? = nil) -> String {
        if let manual = DictationAppSession.shared.choice(for: slot, appID: appBundleID) {
            return self.manualDictationPromptBody(manual, system: true)
        }
        if self.promptRoutingScope(for: .dictate) == .selectedAppsOnly {
            guard self.dictationPromptSelection(for: slot) != .off else { return "" }
            return self.effectiveSystemPrompt(for: .dictate, appBundleID: appBundleID)
        }

        switch self.dictationPromptSelection(for: slot) {
        case .off, .default, .privateAI:
            return self.effectiveSystemPrompt(for: .dictate, appBundleID: appBundleID)
        case let .profile(promptID):
            guard let profile = self.dictationPromptProfiles.first(where: { $0.id == promptID && $0.mode.normalized == .dictate }) else {
                return self.effectiveSystemPrompt(for: .dictate, appBundleID: appBundleID)
            }
            let body = Self.customPromptBody(profile.prompt, mode: .dictate)
            if !body.isEmpty || (profile.mode.normalized == .dictate && !profile.usesLegacyEmptyPromptFallback) {
                return self.systemPrompt(forCustomProfileBody: body, mode: .dictate)
            }
            return self.effectiveSystemPrompt(for: .dictate, appBundleID: appBundleID)
        }
    }

    func effectivePromptBody(for mode: PromptMode, appBundleID: String? = nil) -> String {
        self.promptResolution(for: mode, appBundleID: appBundleID).promptBody
    }

    func effectiveSystemPrompt(for mode: PromptMode, appBundleID: String? = nil) -> String {
        self.promptResolution(for: mode, appBundleID: appBundleID).systemPrompt
    }

    func effectivePromptSource(for mode: PromptMode, appBundleID: String? = nil) -> PromptResolutionSource {
        self.promptResolution(for: mode, appBundleID: appBundleID).source
    }

    /// Literal placeholder that gets substituted with the raw transcription
    /// when composing the user message for a dictation enhancement call.
    static let transcriptPlaceholder = "${transcript}"

    /// Compatibility renderer for explicitly authored `${transcript}` templates.
    /// Normal dictation requests use DictationPromptRequest to keep instructions separate.
    static func renderDictationUserMessage(promptText: String, transcript: String) -> String {
        DictationPromptRequest.renderTemplate(promptText: promptText, transcript: transcript)
    }

    private func defaultPromptResolution(
        for mode: PromptMode,
        source: PromptResolutionSource,
        appBinding: AppPromptBinding?,
        allowDefaultOverride: Bool = true
    ) -> PromptResolution {
        if allowDefaultOverride, let override = self.defaultPromptOverride(for: mode) {
            let trimmedOverride = override.trimmingCharacters(in: .whitespacesAndNewlines)
            if trimmedOverride.isEmpty {
                return PromptResolution(
                    source: source,
                    profile: nil,
                    appBinding: appBinding,
                    promptBody: "",
                    systemPrompt: override
                )
            }

            let body = Self.stripBasePrompt(for: mode, from: trimmedOverride)
            return PromptResolution(
                source: source,
                profile: nil,
                appBinding: appBinding,
                promptBody: body,
                systemPrompt: Self.combineBasePrompt(for: mode, with: body)
            )
        }

        let defaultBody = Self.defaultPromptBodyText(for: mode)
        let fallbackSource: PromptResolutionSource = source == .defaultOverride ? .builtInDefault : source
        return PromptResolution(
            source: fallbackSource,
            profile: nil,
            appBinding: appBinding,
            promptBody: defaultBody,
            systemPrompt: Self.combineBasePrompt(for: mode, with: defaultBody)
        )
    }

    private func systemPrompt(forCustomProfileBody body: String, mode: PromptMode) -> String {
        let normalizedMode = mode.normalized
        let trimmedBody = body.trimmingCharacters(in: .whitespacesAndNewlines)
        if normalizedMode == .dictate {
            return body
        }
        return Self.combineBasePrompt(for: normalizedMode, with: trimmedBody)
    }

    /// Use the same explicit custom prompt for shortcut and app-based selection.
    func shortcutOverrideSystemPrompt(for profile: DictationPromptProfile, mode: PromptMode = .dictate) -> String? {
        if mode.normalized == .dictate, profile.usesLegacyEmptyPromptFallback {
            return profile.legacyEmptyShortcutUsesBasePrompt ? Self.baseDictationPromptText() : nil
        }
        return self.systemPrompt(
            forCustomProfileBody: Self.customPromptBody(profile.prompt, mode: mode),
            mode: mode
        )
    }

    // MARK: - Model Reasoning Configuration

    /// Configuration for model-specific reasoning/thinking parameters
    struct ModelReasoningConfig: Codable, Equatable {
        /// The parameter name to use (e.g., "reasoning_effort", "enable_thinking", "thinking")
        var parameterName: String

        /// The value to use for the parameter (e.g., "low", "medium", "high", "none", "true")
        var parameterValue: String

        /// Whether this config is enabled (allows disabling without deleting)
        var isEnabled: Bool

        init(parameterName: String = "reasoning_effort", parameterValue: String = "low", isEnabled: Bool = true) {
            self.parameterName = parameterName
            self.parameterValue = parameterValue
            self.isEnabled = isEnabled
        }

        /// Common presets for different model types
        static let openAIGPT5 = ModelReasoningConfig(
            parameterName: "reasoning_effort",
            parameterValue: "low",
            isEnabled: true
        )
        static let openAIO1 = ModelReasoningConfig(
            parameterName: "reasoning_effort",
            parameterValue: "medium",
            isEnabled: true
        )
        static let groqGPTOSS = ModelReasoningConfig(
            parameterName: "reasoning_effort",
            parameterValue: "low",
            isEnabled: true
        )
        static let deepSeekReasoner = ModelReasoningConfig(
            parameterName: "enable_thinking",
            parameterValue: "true",
            isEnabled: true
        )
        static let disabled = ModelReasoningConfig(parameterName: "", parameterValue: "", isEnabled: false)
    }

    struct SavedProvider: Codable, Identifiable, Hashable {
        let id: String
        let name: String
        let baseURL: String
        let apiKey: String
        let models: [String]

        init(id: String = UUID().uuidString, name: String, baseURL: String, apiKey: String = "", models: [String] = []) {
            self.id = id
            self.name = name
            self.baseURL = baseURL
            self.apiKey = apiKey
            self.models = models
        }
    }

    var enableAIProcessing: Bool {
        get { self.defaults.bool(forKey: Keys.enableAIProcessing) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.enableAIProcessing)
        }
    }

    /// Show the main window when macOS launches FluidVoice at login (default: ON, matching
    /// current behavior). When off, login launches boot silently in the menu bar. Manual
    /// launches always show the window. Default-true semantics so existing installs keep
    /// their current behavior.
    var showMainWindowAtLoginLaunch: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.showMainWindowAtLoginLaunch)
            if value == nil { return true }
            return self.defaults.bool(forKey: Keys.showMainWindowAtLoginLaunch)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.showMainWindowAtLoginLaunch)
        }
    }

    /// Label speakers ("Speaker 1", "Speaker 2") in file transcriptions (default: OFF).
    var fileTranscriptionSpeakerLabelsEnabled: Bool {
        get { self.defaults.bool(forKey: Keys.fileTranscriptionSpeakerLabelsEnabled) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.fileTranscriptionSpeakerLabelsEnabled)
        }
    }

    /// Expected speaker count hint for file transcription diarization. 0 = auto-detect.
    var fileTranscriptionExpectedSpeakerCount: Int {
        get { self.defaults.integer(forKey: Keys.fileTranscriptionExpectedSpeakerCount) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.fileTranscriptionExpectedSpeakerCount)
        }
    }

    /// Detailed anonymous analytics toggle (default: ON). The daily activity signal is always enabled.
    /// Uses default-true semantics so existing installs upgrading to analytics do not default to OFF.
    var shareDetailedAnalytics: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.shareAnonymousAnalytics)
            if value == nil { return true }
            return self.defaults.bool(forKey: Keys.shareAnonymousAnalytics)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.shareAnonymousAnalytics)
        }
    }

    var privateAIInterestCaptured: Bool {
        get { self.defaults.bool(forKey: Keys.privateAIInterestCaptured) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.privateAIInterestCaptured)
        }
    }

    var availableModels: [String] {
        get { (self.defaults.array(forKey: Keys.availableAIModels) as? [String]) ?? [] }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.availableAIModels)
        }
    }

    var availableModelsByProvider: [String: [String]] {
        get { (self.defaults.dictionary(forKey: Keys.availableModelsByProvider) as? [String: [String]]) ?? [:] }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.availableModelsByProvider)
        }
    }

    var enableDebugLogs: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.enableDebugLogs)
            if value == nil { return true }
            return self.defaults.bool(forKey: Keys.enableDebugLogs)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.enableDebugLogs)
        }
    }

    private func ensureDebugLoggingDefaults() {
        if self.defaults.object(forKey: Keys.enableDebugLogs) == nil {
            self.defaults.set(true, forKey: Keys.enableDebugLogs)
        }
    }

    var selectedModel: String? {
        get { self.defaults.string(forKey: Keys.selectedAIModel) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.selectedAIModel)
        }
    }

    var selectedModelByProvider: [String: String] {
        get { (self.defaults.dictionary(forKey: Keys.selectedModelByProvider) as? [String: String]) ?? [:] }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.selectedModelByProvider)
        }
    }

    var providerAPIKeys: [String: String] {
        get { (try? self.keychain.fetchAllKeys()) ?? [:] }
        set {
            objectWillChange.send()
            do {
                _ = try self.saveProviderAPIKeys(newValue)
            } catch {
                self.logProviderAPIKeyPersistenceFailure(error)
            }
        }
    }

    @discardableResult
    func saveProviderAPIKeys(_ values: [String: String]) throws -> [String: String] {
        let trimmed = self.sanitizeAPIKeys(values)
        try self.keychain.storeAllKeys(trimmed)
        return try self.keychain.fetchAllKeys()
    }

    /// Securely retrieve API key for a provider, handling custom prefix logic
    func getAPIKey(for providerID: String) -> String? {
        let keys = self.providerAPIKeys
        // Try exact match first
        if let key = keys[providerID] { return key }

        // Try canonical key format (custom:ID)
        let canonical = self.canonicalProviderKey(for: providerID)
        return keys[canonical]
    }

    var selectedProviderID: String {
        get { self.availableSelectedProviderID(for: self.defaults.string(forKey: Keys.selectedProviderID)) }
        set {
            objectWillChange.send()
            let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
            if trimmed.isEmpty {
                self.defaults.removeObject(forKey: Keys.selectedProviderID)
            } else {
                self.defaults.set(trimmed, forKey: Keys.selectedProviderID)
            }
        }
    }

    func purgeRetiredAppleIntelligenceState() {
        let retiredProviderIDs = Set(["apple-intelligence", "apple-intelligence-disabled"])
        let rawSelectedProviderID = self.defaults.string(forKey: Keys.selectedProviderID)?
            .trimmingCharacters(in: .whitespacesAndNewlines)

        if let rawSelectedProviderID, retiredProviderIDs.contains(rawSelectedProviderID) {
            self.selectedProviderID = ""
            self.selectedModel = nil
        }

        if retiredProviderIDs.contains(self.commandModeSelectedProviderID) {
            self.commandModeSelectedProviderID = ""
            self.commandModeSelectedModel = nil
        }
        if retiredProviderIDs.contains(self.rewriteModeSelectedProviderID) {
            self.rewriteModeSelectedProviderID = ""
            self.rewriteModeSelectedModel = nil
        }

        var fingerprints = self.verifiedProviderFingerprints
        var availableModels = self.availableModelsByProvider
        var selectedModels = self.selectedModelByProvider
        for providerID in retiredProviderIDs {
            fingerprints.removeValue(forKey: providerID)
            availableModels.removeValue(forKey: providerID)
            selectedModels.removeValue(forKey: providerID)
            fingerprints.removeValue(forKey: "custom:\(providerID)")
            availableModels.removeValue(forKey: "custom:\(providerID)")
            selectedModels.removeValue(forKey: "custom:\(providerID)")
        }
        if fingerprints != self.verifiedProviderFingerprints {
            self.verifiedProviderFingerprints = fingerprints
        }
        if availableModels != self.availableModelsByProvider {
            self.availableModelsByProvider = availableModels
        }
        if selectedModels != self.selectedModelByProvider {
            self.selectedModelByProvider = selectedModels
        }

        let configurations = self.dictationPromptConfigurations.compactMapValues { configuration in
            let providerID = configuration.providerID.trimmingCharacters(in: .whitespacesAndNewlines)
            guard retiredProviderIDs.contains(providerID) else { return configuration }
            guard configuration.shortcut != nil else { return nil }
            return DictationPromptConfiguration(shortcut: configuration.shortcut)
        }
        if configurations != self.dictationPromptConfigurations {
            self.dictationPromptConfigurations = configurations
        }
    }

    var privateAIPrefixKVCacheEnabled: Bool {
        get { self.defaults.object(forKey: PrivateAIProviderFeature.shared.prefixCacheDefaultsKey) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: PrivateAIProviderFeature.shared.prefixCacheDefaultsKey)
        }
    }

    /// How long the local model may sit unused before its memory is released.
    enum PrivateAIIdleUnload: Int, Codable, CaseIterable, Identifiable {
        case never = 0
        case tenMinutes = 10
        case thirtyMinutes = 30
        case oneHour = 60

        var id: Int { self.rawValue }

        var title: String {
            switch self {
            case .never: "Never"
            case .tenMinutes: "10 minutes"
            case .thirtyMinutes: "30 minutes"
            case .oneHour: "1 hour"
            }
        }

        var delay: Duration? {
            self == .never ? nil : .seconds(self.rawValue * 60)
        }
    }

    /// The chosen quiet period. A local-testing override shortens it without
    /// adding a UI option: `defaults write com.FluidApp.app
    /// PrivateAIProviderIdleUnloadTestSeconds -int 60`.
    var privateAIIdleUnloadDelay: Duration? {
        guard let delay = self.privateAIIdleUnload.delay else { return nil }
        let testSeconds = self.defaults.integer(forKey: Keys.privateAIIdleUnloadTestSeconds)
        return testSeconds > 0 ? .seconds(testSeconds) : delay
    }

    /// Experimental. `.never` by default: the model stays loaded as before.
    var privateAIIdleUnload: PrivateAIIdleUnload {
        get { PrivateAIIdleUnload(rawValue: self.defaults.integer(forKey: Keys.privateAIIdleUnloadMinutes)) ?? .never }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.privateAIIdleUnloadMinutes)
        }
    }

    var privateAIBoostEnabled: Bool {
        get { self.defaults.object(forKey: PrivateAIProviderFeature.shared.boostDefaultsKey) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: PrivateAIProviderFeature.shared.boostDefaultsKey)
        }
    }

    var privateAIBackendPreference: PrivateAIBackendPreference {
        get {
            let rawValue = self.defaults.string(forKey: Keys.privateAIBackendPreference)?
                .trimmingCharacters(in: .whitespacesAndNewlines)
                .lowercased()
            var preference = rawValue.flatMap(PrivateAIBackendPreference.init(rawValue:))
                ?? PrivateAIBackendPreference.systemDefault
            if preference == .auto {
                preference = PrivateAIBackendPreference.systemDefault
            }
            if preference == .mlx, CPUArchitecture.isIntel {
                return .llama
            }
            return preference
        }
        set {
            objectWillChange.send()
            var preference = newValue == .auto ? PrivateAIBackendPreference.systemDefault : newValue
            if preference == .mlx, CPUArchitecture.isIntel {
                preference = .llama
            }
            self.defaults.set(preference.rawValue, forKey: Keys.privateAIBackendPreference)
        }
    }

    var privateAIContextTokenLimit: Int {
        get {
            let value = self.defaults.integer(forKey: Keys.privateAIContextTokenLimit)
            return Self.clampPrivateAIContextTokenLimit(value == 0 ? Self.defaultPrivateAIContextTokenLimit : value)
        }
        set {
            objectWillChange.send()
            self.defaults.set(Self.clampPrivateAIContextTokenLimit(newValue), forKey: Keys.privateAIContextTokenLimit)
        }
    }

    private func migratePrivateAIContextDefaultTo4KIfNeeded() {
        guard self.defaults.bool(forKey: Keys.privateAIContextDefaultMigratedTo4K) == false else { return }
        let storedValue = self.defaults.object(forKey: Keys.privateAIContextTokenLimit) as? Int
        if storedValue == nil || storedValue == Self.privateAIContextTokenLimitRange.lowerBound {
            self.defaults.set(Self.defaultPrivateAIContextTokenLimit, forKey: Keys.privateAIContextTokenLimit)
        }
        self.defaults.set(true, forKey: Keys.privateAIContextDefaultMigratedTo4K)
    }

    var savedProviders: [SavedProvider] {
        get {
            guard let data = defaults.data(forKey: Keys.savedProviders),
                  let decoded = try? JSONDecoder().decode([SavedProvider].self, from: data) else { return [] }
            return decoded
        }
        set {
            objectWillChange.send()
            let sanitized = newValue.map { provider -> SavedProvider in
                if provider.apiKey.isEmpty { return provider }
                return SavedProvider(
                    id: provider.id,
                    name: provider.name,
                    baseURL: provider.baseURL,
                    apiKey: "",
                    models: provider.models
                )
            }
            if let encoded = try? JSONEncoder().encode(sanitized) {
                self.defaults.set(encoded, forKey: Keys.savedProviders)
            }
        }
    }

    /// Check if the current AI provider is fully configured (API key/baseURL + selected model)
    var isAIConfigured: Bool {
        let providerID = self.selectedProviderID

        // Get base URL to check for local endpoints
        var baseURL = ""
        if let saved = self.savedProviders.first(where: { $0.id == providerID }) {
            baseURL = saved.baseURL
        } else {
            baseURL = ModelRepository.shared.defaultBaseURL(for: providerID)
        }

        let isLocal = ModelRepository.shared.isLocalEndpoint(baseURL)

        // Check for API key and selected model
        let key = self.canonicalProviderKey(for: providerID)
        let hasApiKey = !(self.providerAPIKeys[key]?.isEmpty ?? true)

        let selectedModel = self.selectedModelByProvider[key]
        let hasSelectedModel = !(selectedModel?.isEmpty ?? true)
        let hasDefaultModel = !ModelRepository.shared.defaultModels(for: providerID).isEmpty
        let hasModel = hasSelectedModel || hasDefaultModel

        return (isLocal || hasApiKey) && hasModel
    }

    /// The base URL for the currently selected AI provider
    var activeBaseURL: String {
        let providerID = self.selectedProviderID
        if let saved = self.savedProviders.first(where: { $0.id == providerID }) {
            return saved.baseURL
        }
        return ModelRepository.shared.defaultBaseURL(for: providerID)
    }

    var hotkeyShortcut: HotkeyShortcut {
        get {
            self.primaryDictationShortcuts.first ?? Self.defaultPrimaryDictationShortcut
        }
        set {
            objectWillChange.send()
            let shortcuts = Self.normalizedPrimaryDictationShortcuts([newValue])
            self.storePrimaryDictationShortcuts(shortcuts)
            if let first = shortcuts.first { self.storeLegacyHotkeyShortcut(first) }
        }
    }

    var primaryDictationShortcutDisplayString: String {
        let displays = self.primaryDictationShortcuts
            .map(\.displayString)
            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
            .filter { !$0.isEmpty }
        return displays.isEmpty ? "Off" : displays.joined(separator: " / ")
    }

    var primaryDictationShortcuts: [HotkeyShortcut] {
        get {
            let fallback = self.legacyHotkeyShortcut
            if let data = defaults.data(forKey: Keys.primaryDictationShortcutsKey),
               let shortcuts = try? JSONDecoder().decode([HotkeyShortcut].self, from: data)
            {
                return Self.normalizedPrimaryDictationShortcuts(shortcuts)
            }
            return Self.normalizedPrimaryDictationShortcuts([fallback])
        }
        set {
            objectWillChange.send()
            let shortcuts = Self.normalizedPrimaryDictationShortcuts(newValue)
            self.storePrimaryDictationShortcuts(shortcuts)
            if let first = shortcuts.first { self.storeLegacyHotkeyShortcut(first) }
        }
    }

    private static var defaultPrimaryDictationShortcut: HotkeyShortcut {
        HotkeyShortcut(keyCode: 61, modifierFlags: [])
    }

    private var legacyHotkeyShortcut: HotkeyShortcut {
        if let data = defaults.data(forKey: Keys.hotkeyShortcutKey),
           let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data)
        {
            return shortcut
        }
        return Self.defaultPrimaryDictationShortcut
    }

    private static func normalizedPrimaryDictationShortcuts(
        _ shortcuts: [HotkeyShortcut]
    ) -> [HotkeyShortcut] {
        var unique: [HotkeyShortcut] = []
        for shortcut in shortcuts where !shortcut.requiresModifierForRecording && !unique.contains(shortcut) {
            unique.append(shortcut)
        }
        return unique
    }

    private func storePrimaryDictationShortcuts(_ shortcuts: [HotkeyShortcut]) {
        if let data = try? JSONEncoder().encode(shortcuts) {
            self.defaults.set(data, forKey: Keys.primaryDictationShortcutsKey)
        }
    }

    private func storeLegacyHotkeyShortcut(_ shortcut: HotkeyShortcut) {
        if let data = try? JSONEncoder().encode(shortcut) {
            self.defaults.set(data, forKey: Keys.hotkeyShortcutKey)
        }
    }

    var pressAndHoldMode: Bool {
        get { self.defaults.object(forKey: Keys.hotkeyMode) != nil ? self.hotkeyMode == .hold : self.defaults.bool(forKey: Keys.pressAndHoldMode) } set { self.hotkeyMode = newValue ? .hold : .toggle }
    }

    var hotkeyMode: HotkeyActivationMode {
        get { self.defaults.string(forKey: Keys.hotkeyMode).flatMap(HotkeyActivationMode.init(rawValue:)) ?? (self.defaults.bool(forKey: Keys.pressAndHoldMode) ? .hold : .toggle) }
        set { objectWillChange.send(); self.defaults.set(newValue.rawValue, forKey: Keys.hotkeyMode); self.defaults.set(newValue == .hold, forKey: Keys.pressAndHoldMode) }
    }

    var holdSpaceToMute: Bool {
        get { self.defaults.bool(forKey: Keys.holdSpaceToMute) }
        set {
            self.objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.holdSpaceToMute)
            NotificationCenter.default.post(name: .init("HoldSpaceToMuteChanged"), object: nil)
        }
    }

    var enableStreamingPreview: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.enableStreamingPreview)
            return value as? Bool ?? true // Default to true (enabled)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.enableStreamingPreview)
        }
    }

    /// Reuses finalized Parakeet windows so long recordings only process their remaining tail at stop.
    /// Experimental and enabled by default; users can fall back to full-buffer finalization.
    var experimentalParakeetUnifiedFinalEnabled: Bool {
        get { self.defaults.object(forKey: Keys.experimentalParakeetUnifiedFinalEnabled) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.experimentalParakeetUnifiedFinalEnabled)
        }
    }

    /// Opt in to restoring the field captured at recording start.
    var returnDictationToStartingField: Bool {
        get { self.defaults.bool(forKey: Keys.returnDictationToStartingField) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.returnDictationToStartingField)
        }
    }

    /// Shows ASR and AI performance details by default; users can hide them.
    var showHistoryPerformanceMetrics: Bool {
        get { self.defaults.object(forKey: Keys.showHistoryPerformanceMetrics) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.showHistoryPerformanceMetrics)
        }
    }

    /// Lets the bundled `fv-serve` command read saved meetings. Off until the user turns it on;
    /// the command reads this same key from the app's preferences.
    var fluidServeMeetingAccessEnabled: Bool {
        get { self.defaults.bool(forKey: FluidServeMeetings.accessDefaultsKey) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: FluidServeMeetings.accessDefaultsKey)
        }
    }

    /// Set when the user copied the skill instructions for an agent FluidVoice cannot see (Cursor,
    /// Gemini and others). It keeps meetings shared after the Claude Code and Codex skills are removed,
    /// until the user stops it.
    var fluidServeOtherAgentsShared: Bool {
        get { self.defaults.bool(forKey: "FluidServeOtherAgentsShared") }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: "FluidServeOtherAgentsShared")
        }
    }

    /// Skips clearly silent recordings up to four seconds before invoking ASR.
    /// Opt-in so quiet speech keeps the existing transcription behavior by default.
    var skipSilentRecordingsEnabled: Bool {
        get { self.defaults.object(forKey: Keys.skipSilentRecordingsEnabled) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.skipSilentRecordingsEnabled)
        }
    }

    var enableAIStreaming: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.enableAIStreaming)
            return value as? Bool ?? true // Default to true (enabled)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.enableAIStreaming)
        }
    }

    /// Direct Core Audio is the required capture backend. Legacy persisted
    /// preferences are intentionally ignored because AVAudioEngine can block or
    /// crash while audio devices are changing.
    var experimentalDirectAudioCaptureEnabled: Bool {
        true
    }

    var copyTranscriptionToClipboard: Bool {
        get { self.defaults.bool(forKey: Keys.copyTranscriptionToClipboard) }
        set { self.defaults.set(newValue, forKey: Keys.copyTranscriptionToClipboard) }
    }

    var preferredInputDeviceUID: String? {
        get { self.defaults.string(forKey: Keys.preferredInputDeviceUID) }
        set { self.defaults.set(newValue, forKey: Keys.preferredInputDeviceUID) }
    }

    var microphonePriority: [MicrophonePriorityEntry] {
        get {
            guard let data = self.defaults.data(forKey: Keys.microphonePriority),
                  let entries = try? JSONDecoder().decode([MicrophonePriorityEntry].self, from: data)
            else { return [] }
            return Self.normalizedMicrophonePriority(entries)
        }
        set {
            let entries = Self.normalizedMicrophonePriority(newValue)
            guard entries != self.microphonePriority else { return }
            objectWillChange.send()
            if let data = try? JSONEncoder().encode(entries) {
                self.defaults.set(data, forKey: Keys.microphonePriority)
            } else {
                self.defaults.removeObject(forKey: Keys.microphonePriority)
            }
            if let firstUID = entries.first?.uid {
                self.preferredInputDeviceUID = firstUID
            }
        }
    }

    var suppressedMicrophoneUIDs: Set<String> {
        get { Set(self.defaults.stringArray(forKey: Keys.suppressedMicrophoneUIDs) ?? []) }
        set {
            if newValue.isEmpty {
                self.defaults.removeObject(forKey: Keys.suppressedMicrophoneUIDs)
            } else {
                self.defaults.set(newValue.sorted(), forKey: Keys.suppressedMicrophoneUIDs)
            }
        }
    }

    var meetingRecordingDefaults: MeetingRecordingDefaults {
        get {
            guard let data = self.defaults.data(forKey: Keys.meetingRecordingDefaults),
                  let saved = try? JSONDecoder().decode(MeetingRecordingDefaults.self, from: data)
            else {
                return .unconfigured
            }
            return saved
        }
        set {
            guard let data = try? JSONEncoder().encode(newValue) else {
                return
            }
            self.defaults.set(data, forKey: Keys.meetingRecordingDefaults)
        }
    }

    /// Picker recency is separate from the saved recording source.
    var meetingRecentApplication: MeetingApplicationIdentity? {
        get {
            guard let data = self.defaults.data(forKey: Keys.meetingRecentApplication) else { return nil }
            return try? JSONDecoder().decode(MeetingApplicationIdentity.self, from: data)
        }
        set {
            guard var application = newValue else {
                self.defaults.removeObject(forKey: Keys.meetingRecentApplication)
                return
            }
            application.windowID = nil
            application.displayID = nil
            guard let data = try? JSONEncoder().encode(application) else { return }
            self.defaults.set(data, forKey: Keys.meetingRecentApplication)
        }
    }

    var meetingAudioRetentionPolicy: MeetingAudioRetentionPolicy {
        get {
            guard let raw = self.defaults.string(forKey: Keys.meetingAudioRetentionPolicy),
                  let policy = MeetingAudioRetentionPolicy(rawValue: raw)
            else { return .days7 }
            return policy
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.meetingAudioRetentionPolicy)
        }
    }

    /// Which meeting transcription backend final processing should use.
    ///
    /// An absent preference resolves to the current production default. A stored value is handed
    /// through verbatim, including an ID this build does not know: the pipeline rejects an unknown
    /// selection loudly rather than quietly transcribing with a different backend than the one
    /// that was chosen. An explicit legacy selection therefore remains a reliable rollback switch.
    var meetingTranscriptionBackendID: MeetingBackendID {
        get {
            guard let raw = self.defaults.string(forKey: Keys.meetingTranscriptionBackendID)
            else { return .productionDefault }
            return MeetingBackendID(rawValue: raw)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.meetingTranscriptionBackendID)
        }
    }

    /// Feature availability is separate from the user's meeting detection preferences.
    @MainActor var fluidMeetEnabled: Bool {
        get { self.defaults.object(forKey: Keys.fluidMeetEnabled) as? Bool ?? true }
        set {
            guard newValue != self.fluidMeetEnabled else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.fluidMeetEnabled)
            NotificationCenter.default.post(name: .fluidMeetEnabledChanged, object: nil)
        }
    }

    /// Tier 1 native (Zoom/Teams/Webex) meeting auto-detection (default: ON).
    var meetingAutoDetectEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.meetingAutoDetectEnabled)
            if value == nil { return true }
            return self.defaults.bool(forKey: Keys.meetingAutoDetectEnabled)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.meetingAutoDetectEnabled)
        }
    }

    /// Tier 2 browser-tab meeting auto-detection. On unless the user turned it off: Google Meet
    /// only exists in a browser. It reads the frontmost tab's URL, which is never stored or sent.
    var meetingAutoDetectBrowserEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.meetingAutoDetectBrowserEnabled)
            if value == nil { return true }
            return self.defaults.bool(forKey: Keys.meetingAutoDetectBrowserEnabled)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.meetingAutoDetectBrowserEnabled)
        }
    }

    var preferredOutputDeviceUID: String? {
        get { self.defaults.string(forKey: Keys.preferredOutputDeviceUID) }
        set { self.defaults.set(newValue, forKey: Keys.preferredOutputDeviceUID) }
    }

    var storedMicSelectionModeForMigration: MicrophoneSelectionMode {
        guard let rawValue = self.defaults.string(forKey: Keys.microphoneSelectionMode),
              let mode = MicrophoneSelectionMode(rawValue: rawValue)
        else { return .system }
        return mode
    }

    var hasStoredMicSelectionModeForMigration: Bool {
        self.defaults.object(forKey: Keys.microphoneSelectionMode) != nil
    }

    var microphoneSelectionMode: MicrophoneSelectionMode {
        get {
            guard let rawValue = self.defaults.string(forKey: Keys.microphoneSelectionMode),
                  let mode = MicrophoneSelectionMode(rawValue: rawValue)
            else { return .manual }
            return mode
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.microphoneSelectionMode)
        }
    }

    func recordInputDeviceSelection(_ uid: String, name: String? = nil) {
        guard uid.isEmpty == false else { return }

        var suppressedUIDs = self.suppressedMicrophoneUIDs
        suppressedUIDs.remove(uid)
        self.suppressedMicrophoneUIDs = suppressedUIDs

        var entries = self.microphonePriority.filter { $0.uid != uid }
        let existingName = self.microphonePriority.first { $0.uid == uid }?.name
        entries.insert(
            MicrophonePriorityEntry(uid: uid, name: name ?? existingName ?? "Microphone"),
            at: 0
        )
        self.microphonePriority = entries
        self.microphoneSelectionMode = .manual
    }

    func reconcileMicrophonePriority(with devices: [AudioDevice.Device]) {
        var entries = self.microphonePriority
        let preferredUID = self.preferredInputDeviceUID
        let suppressedUIDs = self.suppressedMicrophoneUIDs

        if entries.isEmpty,
           let preferredUID,
           preferredUID.isEmpty == false
        {
            let name = devices.first { $0.uid == preferredUID }?.name ?? "Previously selected microphone"
            entries.append(MicrophonePriorityEntry(uid: preferredUID, name: name))
        }

        var knownUIDs = Set(entries.map(\.uid))
        let newEntries = devices.compactMap { device -> MicrophonePriorityEntry? in
            guard suppressedUIDs.contains(device.uid) == false,
                  knownUIDs.insert(device.uid).inserted
            else { return nil }
            return MicrophonePriorityEntry(uid: device.uid, name: device.name)
        }
        if newEntries.isEmpty == false {
            // Keep the user's first choice stable while making a newly connected
            // microphone the immediate fallback. Its position remains persisted
            // when the device later disconnects.
            entries.insert(contentsOf: newEntries, at: min(1, entries.count))
        }

        let namesByUID = Dictionary(
            devices.map { ($0.uid, $0.name) },
            uniquingKeysWith: { current, _ in current }
        )
        entries = entries.map { entry in
            MicrophonePriorityEntry(uid: entry.uid, name: namesByUID[entry.uid] ?? entry.name)
        }
        self.microphonePriority = entries
    }

    func removeMicrophoneFromPriority(uid: String, isConnected: Bool) {
        guard uid.isEmpty == false else { return }

        var suppressedUIDs = self.suppressedMicrophoneUIDs
        if isConnected {
            suppressedUIDs.insert(uid)
        } else {
            suppressedUIDs.remove(uid)
        }
        self.suppressedMicrophoneUIDs = suppressedUIDs

        let entries = self.microphonePriority.filter { $0.uid != uid }
        self.microphonePriority = entries
        if entries.isEmpty {
            self.preferredInputDeviceUID = nil
        }
    }

    func restoreRemovedMicrophones(with devices: [AudioDevice.Device]) {
        self.suppressedMicrophoneUIDs = []
        self.reconcileMicrophonePriority(with: devices)
    }

    func reorderMicrophonePriority(fromOffsets: IndexSet, toOffset: Int) {
        var entries = self.microphonePriority
        entries.move(fromOffsets: fromOffsets, toOffset: toOffset)
        self.microphonePriority = entries
    }

    func moveMicrophonePriority(uid: String, before targetUID: String) {
        guard uid != targetUID else { return }
        var entries = self.microphonePriority
        guard let sourceIndex = entries.firstIndex(where: { $0.uid == uid }),
              let targetIndex = entries.firstIndex(where: { $0.uid == targetUID })
        else { return }

        let entry = entries.remove(at: sourceIndex)
        let adjustedTargetIndex = sourceIndex < targetIndex ? targetIndex - 1 : targetIndex
        entries.insert(entry, at: adjustedTargetIndex)
        self.microphonePriority = entries
    }

    func moveMicrophonePriority(uid: String, by offset: Int) {
        var entries = self.microphonePriority
        guard let sourceIndex = entries.firstIndex(where: { $0.uid == uid }) else { return }
        let destination = min(max(sourceIndex + offset, 0), entries.count - 1)
        guard destination != sourceIndex else { return }
        entries.swapAt(sourceIndex, destination)
        self.microphonePriority = entries
    }

    private static func normalizedMicrophonePriority(
        _ entries: [MicrophonePriorityEntry]
    ) -> [MicrophonePriorityEntry] {
        var seen = Set<String>()
        return entries.filter { entry in
            entry.uid.isEmpty == false && seen.insert(entry.uid).inserted
        }
    }

    var microphoneSelectionMigrationVersion: Int {
        get { self.defaults.integer(forKey: Keys.microphoneSelectionMigrationVersion) }
        set { self.defaults.set(newValue, forKey: Keys.microphoneSelectionMigrationVersion) }
    }

    var visualizerNoiseThreshold: Double {
        get {
            let value = self.defaults.double(forKey: Keys.visualizerNoiseThreshold)
            return value == 0.0 ? 0.4 : value // Default to 0.4 if not set
        }
        set {
            // Clamp between 0.0 and 0.95 to avoid division by zero issues in visualizers
            let clamped = max(min(newValue, 0.95), 0.0)
            self.defaults.set(clamped, forKey: Keys.visualizerNoiseThreshold)
        }
    }

    // MARK: - Overlay Position

    /// Size options for the recording overlay
    enum OverlaySize: String, CaseIterable, Codable {
        case pill
        case small
        case medium
        case large

        var displayName: String {
            switch self {
            case .pill: return "Pill"
            case .small: return "Small"
            case .medium: return "Medium"
            case .large: return "Large"
            }
        }
    }

    enum OverlayMaterial: String, CaseIterable, Codable {
        case original
        case smokedGlass
        case clearGlass
        case velvet
        case aurora

        var displayName: String {
            switch self {
            case .original: return "Original"
            case .smokedGlass: return "Smoked Glass"
            case .clearGlass: return "Clear Glass"
            case .velvet: return "Velvet"
            case .aurora: return "Aurora"
            }
        }
    }

    static let overlayGlassOpacityRange = 0.25...1.0
    static let defaultOverlayGlassOpacity = 0.8

    /// Keep cosmetic dismissal out of the stop path unless explicitly enabled.
    var overlayClosingAnimationEnabled: Bool {
        get { self.defaults.bool(forKey: "OverlayClosingAnimationEnabled") }
        set {
            guard newValue != self.overlayClosingAnimationEnabled else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: "OverlayClosingAnimationEnabled")
        }
    }

    enum OverlayTint: String, CaseIterable, Codable {
        case ocean, violet, rose, mint, amber
    }

    var overlayTint: OverlayTint {
        get { OverlayTint(rawValue: self.defaults.string(forKey: "OverlayTint") ?? "") ?? .ocean }
        set {
            guard newValue != self.overlayTint else { return }
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: "OverlayTint")
        }
    }

    /// Off removes the pill's circling edge light entirely.
    var overlayEdgeLightEnabled: Bool {
        get { (self.defaults.object(forKey: "OverlayEdgeLightEnabled") as? Bool) ?? true }
        set {
            guard newValue != self.overlayEdgeLightEnabled else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: "OverlayEdgeLightEnabled")
        }
    }

    var overlayHighlight: Double {
        get {
            let value = (self.defaults.object(forKey: "OverlayHighlight") as? NSNumber)?.doubleValue ?? 0.5
            return value.isFinite ? min(max(value, 0), 1) : 0.5
        }
        set {
            let value = newValue.isFinite ? min(max(newValue, 0), 1) : 0.5
            guard value != self.overlayHighlight else { return }
            objectWillChange.send()
            self.defaults.set(value, forKey: "OverlayHighlight")
        }
    }

    /// Position options for the recording overlay
    enum OverlayPosition: String, CaseIterable, Codable {
        case top // Top of screen (notch area or floating)
        case bottom // Bottom of screen

        var displayName: String {
            switch self {
            case .top: return "Top of Screen"
            case .bottom: return "Bottom of Screen"
            }
        }
    }

    /// Internal presentation modes for the top notch overlay.
    /// This is intentionally separate from bottom overlay sizing.
    enum NotchPresentationMode: String, CaseIterable, Codable {
        case standard
        case minimal

        var displayName: String {
            switch self {
            case .standard:
                return "Standard Notch"
            case .minimal:
                return "Compact"
            }
        }
    }

    /// Where the recording overlay appears (default: bottom)
    var overlayPosition: OverlayPosition {
        get {
            guard let raw = self.defaults.string(forKey: Keys.overlayPosition),
                  let position = OverlayPosition(rawValue: raw)
            else {
                return .bottom // Default to bottom (menu overlay)
            }
            return position
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.overlayPosition)
            NotificationCenter.default.post(name: NSNotification.Name("OverlayPositionChanged"), object: nil)
        }
    }

    /// Internal-only top notch presentation mode. No public settings UI yet.
    var notchPresentationMode: NotchPresentationMode {
        get {
            guard let raw = self.defaults.string(forKey: Keys.notchPresentationMode),
                  let mode = NotchPresentationMode(rawValue: raw)
            else {
                return .standard
            }
            return mode
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.notchPresentationMode)
        }
    }

    /// Vertical offset for the bottom overlay (distance from bottom of screen/dock)
    var overlayBottomOffset: Double {
        get {
            let value = self.defaults.double(forKey: Keys.overlayBottomOffset)
            return value == 0.0 ? 50.0 : value // Default to 50.0
        }
        set {
            objectWillChange.send()
            // Clamp between a safe range (20px to 1000px)
            // Even though slider is 20-500, we clamp for safety
            let clamped = max(min(newValue, 1000.0), 10.0)
            self.defaults.set(clamped, forKey: Keys.overlayBottomOffset)

            // Post notification for live update if overlay is visible
            NotificationCenter.default.post(name: NSNotification.Name("OverlayOffsetChanged"), object: nil)
        }
    }

    /// The size of the recording overlay (default: medium)
    var overlaySize: OverlaySize {
        get {
            guard let raw = self.defaults.string(forKey: Keys.overlaySize),
                  let size = OverlaySize(rawValue: raw)
            else {
                return .medium // Default to medium
            }
            return size
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.overlaySize)

            // Post notification for live update if overlay is visible
            NotificationCenter.default.post(name: NSNotification.Name("OverlaySizeChanged"), object: nil)
        }
    }

    var overlayMaterial: OverlayMaterial {
        get {
            guard let raw = self.defaults.string(forKey: Keys.overlayMaterial),
                  let material = OverlayMaterial(rawValue: raw)
            else {
                return .smokedGlass
            }
            return material
        }
        set {
            guard newValue != self.overlayMaterial else { return }
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.overlayMaterial)
        }
    }

    var overlayGlassOpacity: Double {
        get {
            guard self.defaults.object(forKey: Keys.overlayGlassOpacity) != nil else {
                return Self.defaultOverlayGlassOpacity
            }
            return Self.normalizedOverlayGlassOpacity(self.defaults.double(forKey: Keys.overlayGlassOpacity))
        }
        set {
            let normalized = Self.normalizedOverlayGlassOpacity(newValue)
            guard normalized != self.overlayGlassOpacity else { return }
            objectWillChange.send()
            self.defaults.set(normalized, forKey: Keys.overlayGlassOpacity)
        }
    }

    private static func normalizedOverlayGlassOpacity(_ value: Double) -> Double {
        guard value.isFinite else { return self.defaultOverlayGlassOpacity }
        return min(max(value, self.overlayGlassOpacityRange.lowerBound), self.overlayGlassOpacityRange.upperBound)
    }

    var meetingOverlayPreference: MeetingOverlayPreference {
        get {
            guard let raw = self.defaults.string(forKey: Keys.meetingOverlayPreference),
                  let preference = MeetingOverlayPreference(rawValue: raw)
            else {
                return .pill
            }
            return preference
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.meetingOverlayPreference)
        }
    }

    /// How many recent transcription characters show in overlays (default: 150)
    var transcriptionPreviewCharLimit: Int {
        get {
            let stored = self.defaults.object(forKey: Keys.transcriptionPreviewCharLimit) as? NSNumber
            let value = stored?.intValue ?? Self.defaultTranscriptionPreviewCharLimit
            return Self.normalizedTranscriptionPreviewCharLimit(value)
        }
        set {
            let clamped = Self.normalizedTranscriptionPreviewCharLimit(newValue)
            guard clamped != self.transcriptionPreviewCharLimit else { return }

            objectWillChange.send()
            self.defaults.set(clamped, forKey: Keys.transcriptionPreviewCharLimit)
            NotificationCenter.default.post(
                name: NSNotification.Name("TranscriptionPreviewCharLimitChanged"),
                object: nil
            )
        }
    }

    private static func normalizedTranscriptionPreviewCharLimit(_ value: Int) -> Int {
        let range = Self.transcriptionPreviewCharLimitRange
        let clamped = max(range.lowerBound, min(range.upperBound, value))
        let offset = clamped - range.lowerBound
        let snappedOffset = Int((Double(offset) / Double(Self.transcriptionPreviewCharLimitStep)).rounded())
            * Self.transcriptionPreviewCharLimitStep
        return max(range.lowerBound, min(range.upperBound, range.lowerBound + snappedOffset))
    }

    // MARK: - Preferences Settings

    enum AccentColorOption: String, CaseIterable, Identifiable, Codable {
        case cyan = "Cyan"
        case green = "Green"
        case blue = "Blue"
        case purple = "Purple"
        case orange = "Orange"

        var id: String {
            self.rawValue
        }

        var hex: String {
            switch self {
            case .cyan: return "#3AC8C6"
            case .green: return "#22C55E"
            case .blue: return "#3B82F6"
            case .purple: return "#A855F7"
            case .orange: return "#F59E0B"
            }
        }
    }

    enum ThemePreference: String, CaseIterable, Identifiable, Codable {
        case system
        case light
        case dark

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .system: return "System"
            case .light: return "Light"
            case .dark: return "Dark"
            }
        }

        var systemImageName: String {
            switch self {
            case .system: return "circle.lefthalf.filled"
            case .light: return "sun.max"
            case .dark: return "moon"
            }
        }

        var preferredColorScheme: ColorScheme? {
            switch self {
            case .system: return nil
            case .light: return .light
            case .dark: return .dark
            }
        }
    }

    enum TranscriptionStartSound: String, CaseIterable, Identifiable, Codable {
        case none
        case fluidSfx0 = "fluid_sfx_0"
        case fluidSfx1 = "fluid_sfx_1"
        case fluidSfx2 = "fluid_sfx_2"
        case fluidSfx3 = "fluid_sfx_3"
        case fluidSfx4 = "fluid_sfx_4"

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .none: return "None"
            case .fluidSfx0: return "Fluid SFX 0"
            case .fluidSfx1: return "Fluid SFX 1"
            case .fluidSfx2: return "Fluid SFX 2"
            case .fluidSfx3: return "Fluid SFX 3"
            case .fluidSfx4: return "Fluid SFX 4"
            }
        }

        var startSoundFileName: String? {
            switch self {
            case .none: return nil
            case .fluidSfx0: return "FV_start_0"
            case .fluidSfx1: return "FV_start"
            case .fluidSfx2: return "FV_start_2"
            case .fluidSfx3: return "sfx_3"
            case .fluidSfx4: return "sfx_4"
            }
        }

        var stopSoundFileName: String? {
            switch self {
            case .fluidSfx0: return "FV_end_0"
            case .none, .fluidSfx1, .fluidSfx2, .fluidSfx3, .fluidSfx4: return nil
            }
        }
    }

    var accentColorOption: AccentColorOption {
        get {
            guard let raw = self.defaults.string(forKey: Keys.accentColorOption),
                  let option = AccentColorOption(rawValue: raw)
            else {
                return .cyan
            }
            return option
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.accentColorOption)
        }
    }

    var accentColor: Color {
        Color(hex: self.accentColorOption.hex) ?? Color(red: 0.227, green: 0.784, blue: 0.776)
    }

    var themePreference: ThemePreference {
        get {
            guard let raw = self.defaults.string(forKey: Keys.themePreference),
                  let preference = ThemePreference(rawValue: raw)
            else {
                return .system
            }
            return preference
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.themePreference)
        }
    }

    var enableTranscriptionSounds: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.enableTranscriptionSounds)
            return value as? Bool ?? true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.enableTranscriptionSounds)
        }
    }

    var transcriptionSoundVolume: Float {
        get {
            let value = self.defaults.object(forKey: Keys.transcriptionSoundVolume)
            return (value as? Float) ?? 1.0
        }
        set {
            objectWillChange.send()
            let clamped = max(0.0, min(1.0, newValue))
            self.defaults.set(clamped, forKey: Keys.transcriptionSoundVolume)
        }
    }

    var transcriptionStartSound: TranscriptionStartSound {
        get {
            self.migrateTranscriptionStartSoundIfNeeded()
            guard let raw = self.defaults.string(forKey: Keys.transcriptionStartSound),
                  let option = TranscriptionStartSound(rawValue: raw)
            else {
                return .fluidSfx0
            }
            return option
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.transcriptionStartSound)
        }
    }

    var launchAtStartup: Bool {
        get { self.launchAtStartupEnabled }
        set {
            self.setLaunchAtStartup(newValue)
        }
    }

    func applyLaunchAtStartupStatus(enabled: Bool, statusMessage: String, errorMessage: String?) {
        objectWillChange.send()
        self.launchAtStartupEnabled = enabled
        self.launchAtStartupStatusMessage = statusMessage
        self.launchAtStartupErrorMessage = errorMessage
    }

    func applyLaunchAtStartupErrorMessage(_ message: String?) {
        objectWillChange.send()
        self.launchAtStartupErrorMessage = message
    }

    // MARK: - Initialization Methods

    func initializeAppSettings() {
        #if os(macOS)
        self.refreshLaunchAtStartupStatus(clearError: true)

        // Apply dock visibility setting on app launch
        let dockVisible = self.showInDock
        DebugLogger.shared.info("Initializing app with dock visibility: \(dockVisible)", source: "SettingsStore")

        // Set activation policy based on saved preference
        DispatchQueue.main.async {
            NSApp.setActivationPolicy(dockVisible ? .regular : .accessory)
        }
        #endif
    }

    var showInDock: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.showInDock)
            return value as? Bool ?? true // Default to true if not set
        }
        set {
            self.defaults.set(newValue, forKey: Keys.showInDock)
            // Update dock visibility
            self.updateDockVisibility(newValue)
        }
    }

    /// Issue #162 wording: hide app from Dock and Cmd+Tab when enabled.
    /// Backed by existing `showInDock` storage to keep this change minimal.
    var hideFromDockAndAppSwitcher: Bool {
        get { !self.showInDock }
        set { self.showInDock = !newValue }
    }

    var autoUpdateCheckEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.autoUpdateCheckEnabled)
            return value as? Bool ?? true // Default to enabled
        }
        set {
            guard newValue != self.autoUpdateCheckEnabled else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.autoUpdateCheckEnabled)
        }
    }

    var showUpdatePopups: Bool {
        get { self.defaults.object(forKey: Keys.showUpdatePopups) as? Bool ?? true }
        set {
            guard newValue != self.showUpdatePopups else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.showUpdatePopups)
            let revision = self.defaults.integer(forKey: UpdateKeys.popupPreferenceRevision)
            self.defaults.set(revision &+ 1, forKey: UpdateKeys.popupPreferenceRevision)
            Task { @MainActor in
                SimpleUpdater.shared.automaticUpdatePopupPreferenceDidChange(isEnabled: newValue)
            }
        }
    }

    var lastUpdateCheckDate: Date? {
        get {
            return self.defaults.object(forKey: Keys.lastUpdateCheckDate) as? Date
        }
        set {
            guard newValue != self.lastUpdateCheckDate else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.lastUpdateCheckDate)
        }
    }

    // MARK: - Update Check Helper

    func shouldCheckForUpdates() -> Bool {
        guard self.autoUpdateCheckEnabled else { return false }

        guard let lastCheck = lastUpdateCheckDate else {
            // Never checked before, should check
            return true
        }

        // Check if more than 1 hour has passed
        let hourInSeconds: TimeInterval = 60 * 60
        return Date().timeIntervalSince(lastCheck) >= hourInSeconds
    }

    func updateLastCheckDate() {
        self.lastUpdateCheckDate = Date()
    }

    // MARK: - Update Prompt Snooze

    /// Date until which update prompts are snoozed (user clicked "Later")
    var updatePromptSnoozedUntil: Date? {
        get { self.defaults.object(forKey: Keys.updatePromptSnoozedUntil) as? Date }
        set { self.defaults.set(newValue, forKey: Keys.updatePromptSnoozedUntil) }
    }

    /// The version that was snoozed (to allow prompting for newer versions)
    var snoozedUpdateVersion: String? {
        get { self.defaults.string(forKey: Keys.snoozedUpdateVersion) }
        set { self.defaults.set(newValue, forKey: Keys.snoozedUpdateVersion) }
    }

    /// Check if we should show the update prompt for a given version
    /// Returns false if user snoozed this version within the last 24 hours
    func shouldShowUpdatePrompt(forVersion version: String) -> Bool {
        // If a different (newer) version is available, always show
        if let snoozedVersion = snoozedUpdateVersion, snoozedVersion != version {
            return true
        }

        // Check if snooze period has expired
        guard let snoozedUntil = updatePromptSnoozedUntil else {
            return true // Never snoozed, show prompt
        }

        return Date() >= snoozedUntil
    }

    /// Snooze update prompts for 24 hours for the given version
    func snoozeUpdatePrompt(forVersion version: String) {
        let snoozeUntil = Date().addingTimeInterval(24 * 60 * 60) // 24 hours
        self.updatePromptSnoozedUntil = snoozeUntil
        self.snoozedUpdateVersion = version
        DebugLogger.shared.info("Update prompt snoozed for version \(version) until \(snoozeUntil)", source: "SettingsStore")
    }

    /// Clear the snooze (e.g., when update is installed)
    func clearUpdateSnooze() {
        self.updatePromptSnoozedUntil = nil
        self.snoozedUpdateVersion = nil
    }

    var playgroundUsed: Bool {
        get { self.defaults.bool(forKey: Keys.playgroundUsed) }
        set { self.defaults.set(newValue, forKey: Keys.playgroundUsed) }
    }

    var onboardingCompleted: Bool {
        get {
            if self.defaults.object(forKey: Keys.onboardingCompleted) == nil {
                return true
            }
            return self.defaults.bool(forKey: Keys.onboardingCompleted)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.onboardingCompleted)
            if newValue {
                self.defaults.set(false, forKey: Keys.manualOnboardingResetRequested)
                self.defaults.removeObject(forKey: Keys.manualOnboardingResetRequestedAt)
            }
        }
    }

    var onboardingCurrentStep: Int {
        get {
            let raw = self.defaults.integer(forKey: Keys.onboardingCurrentStep)
            return max(0, min(5, raw))
        }
        set {
            objectWillChange.send()
            let clamped = max(0, min(5, newValue))
            self.defaults.set(clamped, forKey: Keys.onboardingCurrentStep)
        }
    }

    var onboardingAISkipped: Bool {
        get { self.defaults.bool(forKey: Keys.onboardingAISkipped) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.onboardingAISkipped)
        }
    }

    var onboardingPlaygroundValidated: Bool {
        get { self.defaults.bool(forKey: Keys.onboardingPlaygroundValidated) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.onboardingPlaygroundValidated)
        }
    }

    var onboardingPlaygroundSkipped: Bool {
        get { self.defaults.bool(forKey: Keys.onboardingPlaygroundSkipped) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.onboardingPlaygroundSkipped)
        }
    }

    var onboardingSelectedLanguageID: String {
        get {
            let stored = self.defaults.string(forKey: Keys.onboardingSelectedLanguageID)?
                .trimmingCharacters(in: .whitespacesAndNewlines)
            if let stored, !stored.isEmpty {
                return stored
            }
            return "en"
        }
        set {
            objectWillChange.send()
            let normalized = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
            self.defaults.set(normalized.isEmpty ? "en" : normalized, forKey: Keys.onboardingSelectedLanguageID)
        }
    }

    var selectedAppleSpeechLocaleIdentifier: String {
        get {
            let stored = self.defaults.string(forKey: Keys.selectedAppleSpeechLocaleIdentifier)?
                .trimmingCharacters(in: .whitespacesAndNewlines)
            if let stored, !stored.isEmpty {
                return stored
            }
            return Locale.current.identifier.replacingOccurrences(of: "_", with: "-")
        }
        set {
            objectWillChange.send()
            let normalized = newValue
                .trimmingCharacters(in: .whitespacesAndNewlines)
                .replacingOccurrences(of: "_", with: "-")
            self.defaults.set(normalized.isEmpty ? "en-US" : normalized, forKey: Keys.selectedAppleSpeechLocaleIdentifier)
        }
    }

    var selectedAppleSpeechLocale: Locale {
        Locale(identifier: self.selectedAppleSpeechLocaleIdentifier)
    }

    var shouldShowOnboarding: Bool {
        !self.onboardingCompleted
    }

    var analyticsOnboardingOrigin: AnalyticsOnboardingOrigin {
        self.defaults.bool(forKey: Keys.manualOnboardingResetRequested) ? .manualRestart : .firstRun
    }

    var shouldPromptAccessibilityOnLaunch: Bool {
        !self.shouldShowOnboarding
    }

    func bootstrapOnboardingState(isTrueFirstOpen: Bool) {
        guard self.defaults.object(forKey: Keys.onboardingCompleted) == nil else { return }

        objectWillChange.send()

        let hasLegacyUsageSignals = self.hasLegacyUsageSignals()
        let shouldShowForThisInstall = isTrueFirstOpen && !hasLegacyUsageSignals

        if shouldShowForThisInstall {
            self.defaults.set(false, forKey: Keys.onboardingCompleted)
            self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
            self.defaults.set(false, forKey: Keys.onboardingAISkipped)
            self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
            self.defaults.set(false, forKey: Keys.onboardingPlaygroundSkipped)
            self.defaults.set("en", forKey: Keys.onboardingSelectedLanguageID)
        } else {
            self.defaults.set(true, forKey: Keys.onboardingCompleted)
            self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
            self.defaults.set(false, forKey: Keys.onboardingAISkipped)
            self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
            self.defaults.set(false, forKey: Keys.onboardingPlaygroundSkipped)
            self.defaults.set("en", forKey: Keys.onboardingSelectedLanguageID)
        }
    }

    func resetOnboardingProgress() {
        objectWillChange.send()
        self.defaults.set(false, forKey: Keys.onboardingCompleted)
        self.defaults.set(true, forKey: Keys.manualOnboardingResetRequested)
        self.defaults.set(Date(), forKey: Keys.manualOnboardingResetRequestedAt)
        self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
        self.defaults.set(false, forKey: Keys.onboardingAISkipped)
        self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
        self.defaults.set(false, forKey: Keys.onboardingPlaygroundSkipped)
        self.defaults.set("en", forKey: Keys.onboardingSelectedLanguageID)
        self.defaults.set(false, forKey: Keys.playgroundUsed)
    }

    private func repairForcedOnboardingResetIfNeeded() {
        // 1.6.2 briefly used OnboardingGeneration to force every install through onboarding.
        // Restore existing users who were reset by that migration while keeping fresh installs intact.
        let hadOpenedBeforeForcedReset = AnalyticsIdentityStore.shared.firstOpenAt.map {
            $0 < Self.forcedOnboardingResetIntroducedAt
        } ?? false
        let hasExistingInstallSignal = self.hasLegacyUsageSignals() || hadOpenedBeforeForcedReset
        let hasCurrentManualReset = self.defaults.bool(forKey: Keys.manualOnboardingResetRequested)
            && self.defaults.object(forKey: Keys.manualOnboardingResetRequestedAt) != nil
        guard self.defaults.object(forKey: Keys.onboardingGeneration) != nil,
              self.defaults.bool(forKey: Keys.onboardingCompleted) == false,
              !hasCurrentManualReset,
              hasExistingInstallSignal
        else { return }

        objectWillChange.send()
        self.defaults.set(true, forKey: Keys.onboardingCompleted)
        self.defaults.set(false, forKey: Keys.manualOnboardingResetRequested)
        self.defaults.removeObject(forKey: Keys.manualOnboardingResetRequestedAt)
        self.defaults.set(0, forKey: Keys.onboardingCurrentStep)
        self.defaults.set(false, forKey: Keys.onboardingAISkipped)
        self.defaults.set(false, forKey: Keys.onboardingPlaygroundValidated)
        self.defaults.set(false, forKey: Keys.onboardingPlaygroundSkipped)
    }

    private func hasLegacyUsageSignals() -> Bool {
        if self.defaults.object(forKey: Keys.playgroundUsed) != nil { return true }
        if self.defaults.object(forKey: Keys.hotkeyShortcutKey) != nil { return true }
        if self.defaults.object(forKey: Keys.primaryDictationShortcutsKey) != nil { return true }
        if let rawSpeechModel = self.defaults.string(forKey: Keys.selectedSpeechModel),
           rawSpeechModel != SpeechModel.defaultModel.rawValue
        {
            return true
        }
        if self.defaults.object(forKey: Keys.selectedProviderID) != nil { return true }
        if self.defaults.object(forKey: Keys.customDictionaryEntries) != nil { return true }
        if !self.savedProviders.isEmpty { return true }
        return false
    }

    // MARK: - Command Mode Settings

    var commandModeSelectedModel: String? {
        get { self.defaults.string(forKey: Keys.commandModeSelectedModel) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.commandModeSelectedModel)
        }
    }

    var commandModeSelectedProviderID: String {
        get { self.defaults.string(forKey: Keys.commandModeSelectedProviderID) ?? "" }
        set {
            objectWillChange.send()
            let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
            if trimmed.isEmpty {
                self.defaults.removeObject(forKey: Keys.commandModeSelectedProviderID)
            } else {
                self.defaults.set(trimmed, forKey: Keys.commandModeSelectedProviderID)
            }
        }
    }

    // MARK: - Prompt Mode Settings (Transcribe with Prompt)

    var promptModeShortcutEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.promptModeShortcutEnabled)
            return (value as? Bool ?? false) && !self.promptModeHotkeyShortcut.requiresModifierForRecording
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.promptModeShortcutEnabled)
        }
    }

    var promptModeHotkeyShortcut: HotkeyShortcut {
        get {
            if let data = defaults.data(forKey: Keys.promptModeHotkeyShortcut),
               let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data)
            {
                return shortcut
            }
            // Default to Right Shift key (keyCode: 60, no modifiers) — avoids conflict with Command Mode (Right Command, keyCode 54)
            return HotkeyShortcut(keyCode: 60, modifierFlags: [])
        }
        set {
            objectWillChange.send()
            if let data = try? JSONEncoder().encode(newValue) {
                self.defaults.set(data, forKey: Keys.promptModeHotkeyShortcut)
            }
        }
    }

    var promptModeSelectedPromptID: String? {
        get {
            let value = self.defaults.string(forKey: Keys.promptModeSelectedPromptID)
            return value?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == true ? nil : value
        }
        set {
            objectWillChange.send()
            if let id = newValue?.trimmingCharacters(in: .whitespacesAndNewlines), !id.isEmpty {
                self.defaults.set(id, forKey: Keys.promptModeSelectedPromptID)
            } else {
                self.defaults.removeObject(forKey: Keys.promptModeSelectedPromptID)
            }
        }
    }

    var isSecondaryDictationPromptOff: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.secondaryDictationPromptOff)
            return value as? Bool ?? false
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.secondaryDictationPromptOff)
        }
    }

    var commandModeShortcutEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.commandModeShortcutEnabled)
            return (value as? Bool ?? false) && self.commandModeHotkeyShortcut?.requiresModifierForRecording != true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.commandModeShortcutEnabled)
        }
    }

    var commandModeHotkeyShortcut: HotkeyShortcut? {
        get {
            if let data = defaults.data(forKey: Keys.commandModeHotkeyShortcut),
               let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data)
            {
                return shortcut
            }
            return nil
        }
        set {
            objectWillChange.send()
            guard let newValue else {
                self.defaults.removeObject(forKey: Keys.commandModeHotkeyShortcut)
                return
            }
            if let data = try? JSONEncoder().encode(newValue) {
                self.defaults.set(data, forKey: Keys.commandModeHotkeyShortcut)
            }
        }
    }

    var cancelRecordingHotkeyShortcut: HotkeyShortcut? {
        get {
            if let data = defaults.data(forKey: Keys.cancelRecordingHotkeyShortcut) {
                do { return try JSONDecoder().decode(HotkeyShortcut?.self, from: data) } catch {}
            }
            return HotkeyShortcut(keyCode: 53, modifierFlags: [])
        }
        set {
            objectWillChange.send()
            // Old backups can still contain a modifier-only Cancel binding.
            let shortcut = newValue?.isModifierOnlyShortcut == true ? HotkeyShortcut(keyCode: 53, modifierFlags: []) : newValue
            if let data = try? JSONEncoder().encode(shortcut) {
                self.defaults.set(data, forKey: Keys.cancelRecordingHotkeyShortcut)
            }
        }
    }

    static func migrateModifierOnlyCancelShortcutIfNeeded(defaults: UserDefaults) {
        guard let data = defaults.data(forKey: Keys.cancelRecordingHotkeyShortcut),
              let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data),
              shortcut.isModifierOnlyShortcut,
              let replacement = try? JSONEncoder().encode(HotkeyShortcut(keyCode: 53, modifierFlags: []))
        else { return }
        defaults.set(replacement, forKey: Keys.cancelRecordingHotkeyShortcut)
    }

    /// Unassigned by default. Meeting recording never claims a shortcut until explicitly configured.
    var meetingRecordingHotkeyShortcut: HotkeyShortcut? {
        get {
            guard let data = self.defaults.data(forKey: Keys.meetingRecordingHotkeyShortcut),
                  let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data),
                  shortcut.isMeetingRecordingShortcut else { return nil }
            return shortcut
        }
        set {
            objectWillChange.send()
            guard let newValue, newValue.isMeetingRecordingShortcut,
                  let data = try? JSONEncoder().encode(newValue)
            else {
                self.defaults.removeObject(forKey: Keys.meetingRecordingHotkeyShortcut)
                return
            }
            self.defaults.set(data, forKey: Keys.meetingRecordingHotkeyShortcut)
        }
    }

    // MARK: - Paste Last Transcription Settings

    /// Whether the "Paste Last Transcription" global hotkey is active. Opt-in and off by default.
    var pasteLastTranscriptionShortcutEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.pasteLastTranscriptionShortcutEnabled)
            return value as? Bool ?? false
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.pasteLastTranscriptionShortcutEnabled)
        }
    }

    /// The shortcut that re-inserts the most recent transcription into the focused field.
    /// Unbound (nil) by default so it never collides with an existing shortcut until the user assigns one.
    var pasteLastTranscriptionHotkeyShortcut: HotkeyShortcut? {
        get {
            if let data = defaults.data(forKey: Keys.pasteLastTranscriptionHotkeyShortcut),
               let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data)
            {
                return shortcut
            }
            return nil
        }
        set {
            objectWillChange.send()
            guard let newValue else {
                self.defaults.removeObject(forKey: Keys.pasteLastTranscriptionHotkeyShortcut)
                return
            }
            if let data = try? JSONEncoder().encode(newValue) {
                self.defaults.set(data, forKey: Keys.pasteLastTranscriptionHotkeyShortcut)
            }
        }
    }

    var commandModeConfirmBeforeExecute: Bool {
        get {
            // Default to true (safer - ask before running commands)
            let value = self.defaults.object(forKey: Keys.commandModeConfirmBeforeExecute)
            return value as? Bool ?? true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.commandModeConfirmBeforeExecute)
        }
    }

    // MARK: - Rewrite Mode Settings

    var rewriteModeHotkeyShortcut: HotkeyShortcut {
        get {
            if let data = defaults.data(forKey: Keys.rewriteModeHotkeyShortcut),
               let shortcut = try? JSONDecoder().decode(HotkeyShortcut.self, from: data)
            {
                return shortcut
            }
            // Default to Option+R (keyCode: 15 is R, with Option modifier)
            return HotkeyShortcut(keyCode: 15, modifierFlags: [.option])
        }
        set {
            objectWillChange.send()
            if let data = try? JSONEncoder().encode(newValue) {
                self.defaults.set(data, forKey: Keys.rewriteModeHotkeyShortcut)
            }
        }
    }

    var rewriteModeSelectedModel: String? {
        get { self.defaults.string(forKey: Keys.rewriteModeSelectedModel) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.rewriteModeSelectedModel)
        }
    }

    var rewriteModeSelectedProviderID: String {
        get { self.defaults.string(forKey: Keys.rewriteModeSelectedProviderID) ?? "" }
        set {
            objectWillChange.send()
            let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
            if trimmed.isEmpty {
                self.defaults.removeObject(forKey: Keys.rewriteModeSelectedProviderID)
            } else {
                self.defaults.set(trimmed, forKey: Keys.rewriteModeSelectedProviderID)
            }
        }
    }

    var rewriteModeLinkedToGlobal: Bool {
        get {
            // Default to true - sync with global settings by default
            let value = self.defaults.object(forKey: Keys.rewriteModeLinkedToGlobal)
            return value as? Bool ?? true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.rewriteModeLinkedToGlobal)
        }
    }

    // MARK: - Model Reasoning Configuration

    /// Per-model reasoning configuration storage
    /// Key format: "provider:model" (e.g., "openai:gpt-5.1", "groq:gpt-oss-120b")
    var modelReasoningConfigs: [String: ModelReasoningConfig] {
        get {
            guard let data = defaults.data(forKey: Keys.modelReasoningConfigs),
                  let decoded = try? JSONDecoder().decode([String: ModelReasoningConfig].self, from: data)
            else {
                return [:]
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue) {
                self.defaults.set(encoded, forKey: Keys.modelReasoningConfigs)
            }
        }
    }

    /// Get reasoning config for a specific model, with smart defaults for known models
    func getReasoningConfig(forModel model: String, provider: String) -> ModelReasoningConfig? {
        let key = "\(provider):\(model)"

        // First check if user has a custom config
        if let customConfig = modelReasoningConfigs[key] {
            return customConfig.isEnabled ? customConfig : nil
        }

        // Apply smart defaults for known model patterns
        let modelLower = model.lowercased()

        // OpenAI gpt-5.x models
        if modelLower.hasPrefix("gpt-5") || modelLower.contains("gpt-5.") {
            return .openAIGPT5
        }

        // OpenAI o-series reasoning models
        if modelLower.hasPrefix("o1") || modelLower.hasPrefix("o3") || modelLower.hasPrefix("o4") {
            return .openAIO1
        }

        // Groq gpt-oss models
        if modelLower.contains("gpt-oss") || modelLower.hasPrefix("openai/") {
            return .groqGPTOSS
        }

        // DeepSeek reasoner models
        if modelLower.contains("deepseek"), modelLower.contains("reasoner") {
            return .deepSeekReasoner
        }

        // No reasoning config needed for standard models (gpt-4.x, claude, llama, etc.)
        return nil
    }

    /// Set reasoning config for a specific model
    func setReasoningConfig(_ config: ModelReasoningConfig?, forModel model: String, provider: String) {
        let key = "\(provider):\(model)"
        var configs = self.modelReasoningConfigs

        if let config = config {
            configs[key] = config
        } else {
            configs.removeValue(forKey: key)
        }

        self.modelReasoningConfigs = configs
    }

    /// Check if a model has a custom (user-defined) reasoning config
    func hasCustomReasoningConfig(forModel model: String, provider: String) -> Bool {
        let key = "\(provider):\(model)"
        return self.modelReasoningConfigs[key] != nil
    }

    var rewriteModeShortcutEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.rewriteModeShortcutEnabled)
            return (value as? Bool ?? true) && !self.rewriteModeHotkeyShortcut.requiresModifierForRecording
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.rewriteModeShortcutEnabled)
        }
    }

    /// Invalidates old captures even when the switch changes off and back on.
    private(set) var editModeScreenContextRevision: UInt64 = 0

    /// Lets on-device Edit Mode use the text in the front window. On until turned off.
    var editModeReadsScreen: Bool {
        get { self.defaults.object(forKey: Keys.editModeReadsScreen) as? Bool ?? true }
        set {
            guard newValue != self.editModeReadsScreen else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.editModeReadsScreen)
            self.editModeScreenContextRevision &+= 1
        }
    }

    /// Global check if a model is a reasoning model (requires special params/max_completion_tokens)
    func isReasoningModel(_ model: String) -> Bool {
        // Drop a provider/namespace prefix (e.g. OpenRouter's "openai/") so the
        // family checks below match prefixed reasoning IDs like "openai/o3"
        // without also matching every non-reasoning "openai/*" model (e.g.
        // "openai/gpt-4o"), which would strip its temperature control.
        var modelLower = model.lowercased()
        if let slash = modelLower.firstIndex(of: "/") {
            modelLower = String(modelLower[modelLower.index(after: slash)...])
        }
        return modelLower.hasPrefix("gpt-6") ||
            modelLower.hasPrefix("gpt-5") ||
            modelLower.contains("gpt-5.") ||
            modelLower.hasPrefix("o1") ||
            modelLower.hasPrefix("o3") ||
            modelLower.hasPrefix("o4") ||
            modelLower.contains("gpt-oss") ||
            (modelLower.contains("deepseek") && modelLower.contains("reasoner"))
    }

    /// Whether the model rejects the `temperature` parameter.
    /// Order: reasoning models, then support learned from `/models` metadata or a past
    /// HTTP 400 (`ModelTemperatureSupport`), then a version check for Anthropic models that
    /// have deprecated temperature (Opus 4.7+, every Claude 5 model, Fable/Mythos — Sonnet 4.6
    /// and older still accept it).
    func isTemperatureUnsupported(_ model: String, baseURL: String, support: ModelTemperatureSupport = .shared) -> Bool {
        if self.isReasoningModel(model) { return true }
        if let supported = support.isSupported(model, baseURL: baseURL) { return !supported }
        // Normalize version separators so dotted IDs (e.g. OpenRouter's
        // anthropic/claude-opus-4.8) match the hyphenated forms below.
        let modelLower = model.lowercased().replacingOccurrences(of: ".", with: "-")
        if modelLower.contains("claude-fable") || modelLower.contains("claude-mythos") { return true }
        // Compare versions instead of listing model IDs: each new Claude release
        // otherwise fails with HTTP 400 until its ID is added here.
        guard let version = Self.claudeVersion(in: modelLower) else { return false }
        if version.major >= 5 { return true }
        return version.family == "opus" && version.major == 4 && version.minor >= 7
    }

    /// The minor group is capped at two digits so a date suffix
    /// (claude-sonnet-4-20250514) is not read as a minor version.
    private static let claudeVersionRegex = try? NSRegularExpression(
        pattern: #"claude-(opus|sonnet|haiku)-(\d+)(?:-(\d{1,2}))?(?!\d)"#
    )

    /// Family and version of a family-first Claude ID (claude-haiku-5-5). Older
    /// version-first IDs (claude-3-5-haiku) return nil; they all accept temperature.
    private static func claudeVersion(in modelLower: String) -> (family: String, major: Int, minor: Int)? {
        let range = NSRange(modelLower.startIndex..., in: modelLower)
        guard let match = self.claudeVersionRegex?.firstMatch(in: modelLower, range: range),
              let familyRange = Range(match.range(at: 1), in: modelLower),
              let majorRange = Range(match.range(at: 2), in: modelLower),
              let major = Int(modelLower[majorRange])
        else { return nil }
        let minor = Range(match.range(at: 3), in: modelLower).flatMap { Int(modelLower[$0]) } ?? 0
        return (String(modelLower[familyRange]), major, minor)
    }

    /// Whether to display thinking tokens in the UI (Command Mode, Rewrite Mode)
    /// If false, thinking tokens are extracted but not shown to user
    var showThinkingTokens: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.showThinkingTokens)
            return value as? Bool ?? true // Default to true (show thinking)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.showThinkingTokens)
        }
    }

    /// Stored verification fingerprints per provider key (hash of baseURL + apiKey).
    var verifiedProviderFingerprints: [String: String] {
        get {
            guard let data = self.defaults.data(forKey: Keys.verifiedProviderFingerprints),
                  let decoded = try? JSONDecoder().decode([String: String].self, from: data)
            else {
                return [:]
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue) {
                self.defaults.set(encoded, forKey: Keys.verifiedProviderFingerprints)
            } else {
                self.defaults.removeObject(forKey: Keys.verifiedProviderFingerprints)
            }
        }
    }

    /// Stored verification fingerprints per private model ID. Provider-level fingerprints remain
    /// for backward compatibility, while this map allows Dictation and Edit Mode to use different
    /// installed models without invalidating each other.
    var verifiedPrivateAIModelFingerprints: [String: String] {
        get {
            guard let data = self.defaults.data(forKey: Keys.verifiedPrivateAIModelFingerprints),
                  let decoded = try? JSONDecoder().decode([String: String].self, from: data)
            else {
                return [:]
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue) {
                self.defaults.set(encoded, forKey: Keys.verifiedPrivateAIModelFingerprints)
            } else {
                self.defaults.removeObject(forKey: Keys.verifiedPrivateAIModelFingerprints)
            }
        }
    }

    // MARK: - Stats Settings

    /// User's typing speed in words per minute (for time saved calculation)
    var userTypingWPM: Int {
        get {
            let value = self.defaults.integer(forKey: Keys.userTypingWPM)
            return value > 0 ? value : 40 // Default to 40 WPM
        }
        set {
            objectWillChange.send()
            self.defaults.set(max(1, min(200, newValue)), forKey: Keys.userTypingWPM) // Clamp 1-200
        }
    }

    /// When enabled, weekends (Saturday/Sunday) don't break the usage streak
    var weekendsDontBreakStreak: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.weekendsDontBreakStreak)
            return value as? Bool ?? true // Default to true (weekends don't break streak)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.weekendsDontBreakStreak)
        }
    }

    // MARK: - Custom Dictation Prompt

    /// Custom system prompt for dictation mode. When empty, uses the default built-in prompt.
    var customDictationPrompt: String {
        get { self.defaults.string(forKey: Keys.customDictationPrompt) ?? "" }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.customDictationPrompt)
        }
    }

    /// Whether to save transcription history for stats tracking
    /// When disabled, transcriptions are not stored and stats won't update
    var saveTranscriptionHistory: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.saveTranscriptionHistory)
            return value as? Bool ?? true // Default to true (save history)
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.saveTranscriptionHistory)
        }
    }

    /// Stores actual microphone audio locally alongside dictation history.
    var saveAudioWithTranscriptionHistory: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.saveAudioWithTranscriptionHistory)
            return value as? Bool ?? false
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.saveAudioWithTranscriptionHistory)
        }
    }

    var audioHistoryBudgetGB: Double {
        get {
            let value = self.defaults.double(forKey: Keys.audioHistoryBudgetGB)
            return value > 0 ? max(0.1, value) : 4.0
        }
        set {
            objectWillChange.send()
            self.defaults.set(max(0.1, newValue), forKey: Keys.audioHistoryBudgetGB)
        }
    }

    var audioHistoryBudgetBytes: Int64 {
        DictationAudioHistoryStore.bytes(forGigabytes: self.audioHistoryBudgetGB)
    }

    /// Whether to show a native notification when AI post-processing fails and raw text is used
    var notifyAIProcessingFailures: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.notifyAIProcessingFailures)
            return value as? Bool ?? true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.notifyAIProcessingFailures)
        }
    }

    /// Whether transient microphone selection and availability alerts are shown.
    var showMicrophoneChangeAlerts: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.showMicrophoneChangeAlerts)
            return value as? Bool ?? true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.showMicrophoneChangeAlerts)
        }
    }

    /// Whether a card is shown when a paste could not be confirmed in the target field.
    /// Enabled by default for strong unchanged-field results; explicit user choices persist.
    var showPasteCheckAlerts: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.showPasteCheckAlerts)
            return value as? Bool ?? true
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.showPasteCheckAlerts)
        }
    }

    func makeBackupPayload() -> SettingsBackupPayload {
        SettingsBackupPayload(
            selectedProviderID: self.selectedProviderID,
            selectedModelByProvider: self.selectedModelByProvider,
            savedProviders: self.savedProviders,
            modelReasoningConfigs: self.modelReasoningConfigs,
            privateAIPrefixKVCacheEnabled: self.privateAIPrefixKVCacheEnabled,
            privateAIBoostEnabled: self.privateAIBoostEnabled,
            privateAIBackendPreference: self.privateAIBackendPreference,
            privateAIContextTokenLimit: self.privateAIContextTokenLimit,
            selectedSpeechModel: self.selectedSpeechModel,
            selectedWhisperLanguageCode: Self.whisperLanguageBackupValue(for: self.selectedWhisperLanguageCode),
            selectedCohereLanguage: self.selectedCohereLanguage,
            selectedNemotronLanguage: self.selectedNemotronLanguage,
            selectedAppleSpeechLocaleIdentifier: self.selectedAppleSpeechLocaleIdentifier,
            meetingTranscriptionBackendID: self.meetingTranscriptionBackendID.rawValue,
            hotkeyShortcut: self.hotkeyShortcut,
            primaryDictationShortcuts: self.primaryDictationShortcuts,
            promptModeHotkeyShortcut: self.promptModeHotkeyShortcut,
            promptModeShortcutEnabled: self.promptModeShortcutEnabled,
            promptModeSelectedPromptID: self.promptModeSelectedPromptID,
            secondaryDictationPromptOff: self.isSecondaryDictationPromptOff,
            commandModeHotkeyShortcut: self.commandModeHotkeyShortcut,
            commandModeShortcutEnabled: self.commandModeShortcutEnabled,
            commandModeSelectedModel: self.commandModeSelectedModel,
            commandModeSelectedProviderID: self.commandModeSelectedProviderID,
            commandModeConfirmBeforeExecute: self.commandModeConfirmBeforeExecute,
            commandModeLinkedToGlobal: self.commandModeLinkedToGlobal,
            rewriteModeHotkeyShortcut: self.rewriteModeHotkeyShortcut,
            rewriteModeShortcutEnabled: self.rewriteModeShortcutEnabled,
            rewriteModeSelectedModel: self.rewriteModeSelectedModel,
            rewriteModeSelectedProviderID: self.rewriteModeSelectedProviderID,
            rewriteModeLinkedToGlobal: self.rewriteModeLinkedToGlobal,
            meetingRecordingHotkeyShortcut: self.meetingRecordingHotkeyShortcut,
            meetingRecordingShortcutEnabled: self.meetingRecordingHotkeyShortcut != nil,
            cancelRecordingHotkeyShortcut: self.cancelRecordingHotkeyShortcut,
            pasteLastTranscriptionHotkeyShortcut: self.pasteLastTranscriptionHotkeyShortcut,
            pasteLastTranscriptionShortcutEnabled: self.pasteLastTranscriptionShortcutEnabled,
            showThinkingTokens: self.showThinkingTokens,
            hideFromDockAndAppSwitcher: self.hideFromDockAndAppSwitcher,
            showMainWindowAtLoginLaunch: self.showMainWindowAtLoginLaunch,
            accentColorOption: self.accentColorOption,
            transcriptionStartSound: self.transcriptionStartSound,
            transcriptionSoundVolume: self.transcriptionSoundVolume,
            transcriptionSoundIndependentVolume: false,
            autoUpdateCheckEnabled: self.autoUpdateCheckEnabled,
            showUpdatePopups: self.showUpdatePopups,
            betaReleasesEnabled: self.betaReleasesEnabled,
            enableDebugLogs: self.enableDebugLogs,
            shareAnonymousAnalytics: self.shareDetailedAnalytics,
            pressAndHoldMode: self.pressAndHoldMode,
            hotkeyMode: self.hotkeyMode,
            holdSpaceToMute: self.holdSpaceToMute,
            enableStreamingPreview: self.enableStreamingPreview,
            experimentalParakeetUnifiedFinalEnabled: self.experimentalParakeetUnifiedFinalEnabled,
            returnDictationToStartingField: self.returnDictationToStartingField,
            showHistoryPerformanceMetrics: self.showHistoryPerformanceMetrics,
            skipSilentRecordingsEnabled: self.skipSilentRecordingsEnabled,
            enableAIStreaming: self.enableAIStreaming,
            copyTranscriptionToClipboard: self.copyTranscriptionToClipboard,
            textInsertionMode: self.textInsertionMode,
            spokenSendEnabled: self.spokenSendEnabled,
            spokenSendImmediatelyEnabled: self.spokenSendImmediatelyEnabled,
            spokenSendPhrase: self.spokenSendPhrase,
            spokenSendKey: self.spokenSendKey,
            preferredInputDeviceUID: self.preferredInputDeviceUID,
            microphonePriority: self.microphonePriority,
            suppressedMicrophoneUIDs: self.suppressedMicrophoneUIDs.sorted(),
            preferredOutputDeviceUID: self.preferredOutputDeviceUID,
            // Kept in the backup schema for compatibility with older builds.
            // Current builds always resolve microphones from the priority list.
            microphoneSelectionMode: .manual,
            visualizerNoiseThreshold: self.visualizerNoiseThreshold,
            overlayPosition: self.overlayPosition,
            overlayBottomOffset: self.overlayBottomOffset,
            overlaySize: self.overlaySize,
            overlayMaterial: self.overlayMaterial,
            overlayGlassOpacity: self.overlayGlassOpacity,
            overlayTint: self.overlayTint,
            overlayHighlight: self.overlayHighlight,
            overlayClosingAnimationEnabled: self.overlayClosingAnimationEnabled,
            meetingOverlayPreference: self.meetingOverlayPreference,
            transcriptionPreviewCharLimit: self.transcriptionPreviewCharLimit,
            userTypingWPM: self.userTypingWPM,
            saveTranscriptionHistory: self.saveTranscriptionHistory,
            saveAudioWithTranscriptionHistory: self.saveAudioWithTranscriptionHistory,
            audioHistoryBudgetGB: self.audioHistoryBudgetGB,
            notifyAIProcessingFailures: self.notifyAIProcessingFailures,
            showMicrophoneChangeAlerts: self.showMicrophoneChangeAlerts,
            showPasteCheckAlerts: self.showPasteCheckAlerts,
            weekendsDontBreakStreak: self.weekendsDontBreakStreak,
            fillerWords: self.fillerWords,
            removeFillerWordsEnabled: self.removeFillerWordsEnabled,
            autoConvertPunctuationEnabled: self.autoConvertPunctuationEnabled,
            literalDictationFormattingEnabled: self.literalDictationFormattingEnabled,
            punctuationDictionaryPrefix: self.punctuationDictionaryPrefix,
            punctuationDictionaryRules: self.punctuationDictionaryRules,
            spokenFormattingActionRules: self.spokenFormattingActionRules,
            gaavModeEnabled: self.gaavModeEnabled,
            gaavLowercaseFirstLetterEnabled: self.gaavLowercaseFirstLetterEnabled,
            gaavRemoveTrailingPeriodEnabled: self.gaavRemoveTrailingPeriodEnabled,
            continuousDictationModeEnabled: self.continuousDictationModeEnabled,
            continuousDictationSpacingEnabled: self.continuousDictationSpacingEnabled,
            contextAwareCapitalizationEnabled: self.contextAwareCapitalizationEnabled,
            pauseMediaDuringTranscription: self.pauseMediaDuringTranscription,
            automaticDictionaryLearningEnabled: self.automaticDictionaryLearningEnabled,
            automaticDictionarySuggestionFrequency: self.automaticDictionarySuggestionFrequency,
            pronunciationMatchingEnabled: self.pronunciationMatchingEnabled,
            vocabularyBoostingEnabled: self.vocabularyBoostingEnabled,
            customDictionaryEntries: self.customDictionaryEntries,
            selectedDictationPromptID: self.selectedDictationPromptID,
            dictationPromptOff: self.isDictationPromptOff,
            dictationPromptRoutingScope: self.dictationPromptRoutingScope,
            editPromptOff: self.isEditPromptOff,
            selectedEditPromptID: self.selectedEditPromptID,
            editPromptRoutingScope: self.editPromptRoutingScope,
            defaultDictationPromptOverride: self.defaultDictationPromptOverride,
            defaultEditPromptOverride: self.defaultEditPromptOverride,
            fileTranscriptionSpeakerLabelsEnabled: self.fileTranscriptionSpeakerLabelsEnabled,
            fileTranscriptionExpectedSpeakerCount: self.fileTranscriptionExpectedSpeakerCount,
            meetingRecordingDefaults: self.meetingRecordingDefaults,
            privateAIIdleUnload: self.privateAIIdleUnload,
            dictationPromptConfigurations: self.dictationPromptConfigurations
        )
    }

    func restore(from payload: SettingsBackupPayload) {
        self.restore(from: payload, promptProfiles: self.dictationPromptProfiles, appPromptBindings: self.appPromptBindings)
    }

    func restore(
        from payload: SettingsBackupPayload,
        promptProfiles: [DictationPromptProfile],
        appPromptBindings: [AppPromptBinding]
    ) {
        self.savedProviders = payload.savedProviders
        self.selectedProviderID = payload.selectedProviderID
        self.selectedModelByProvider = payload.selectedModelByProvider
        self.modelReasoningConfigs = payload.modelReasoningConfigs
        if let privateAIPrefixKVCacheEnabled = payload.privateAIPrefixKVCacheEnabled {
            self.privateAIPrefixKVCacheEnabled = privateAIPrefixKVCacheEnabled
        }
        if let privateAIBoostEnabled = payload.privateAIBoostEnabled {
            self.privateAIBoostEnabled = privateAIBoostEnabled
        }
        if let privateAIBackendPreference = payload.privateAIBackendPreference {
            self.privateAIBackendPreference = privateAIBackendPreference
        }
        if let privateAIContextTokenLimit = payload.privateAIContextTokenLimit {
            self.privateAIContextTokenLimit = privateAIContextTokenLimit
        }
        if let privateAIIdleUnload = payload.privateAIIdleUnload {
            self.privateAIIdleUnload = privateAIIdleUnload
        }
        self.selectedSpeechModel = payload.selectedSpeechModel
        if let selectedWhisperLanguageCode = payload.selectedWhisperLanguageCode {
            self.selectedWhisperLanguageCode = Self.whisperLanguageCode(fromBackupValue: selectedWhisperLanguageCode)
        }
        self.selectedCohereLanguage = payload.selectedCohereLanguage
        if let selectedNemotronLanguage = payload.selectedNemotronLanguage {
            self.selectedNemotronLanguage = selectedNemotronLanguage
        }
        if let selectedAppleSpeechLocaleIdentifier = payload.selectedAppleSpeechLocaleIdentifier {
            self.selectedAppleSpeechLocaleIdentifier = selectedAppleSpeechLocaleIdentifier
        }
        // A backup predating this setting represents an absent selection, which resolves to the
        // current phase's local default. Unknown stored IDs remain intact and visibly unavailable.
        self.meetingTranscriptionBackendID = payload.meetingTranscriptionBackendID.map {
            MeetingBackendID(rawValue: $0)
        } ?? .productionDefault
        if let meetingRecordingDefaults = payload.meetingRecordingDefaults {
            self.meetingRecordingDefaults = meetingRecordingDefaults
        }
        self.primaryDictationShortcuts = payload.primaryDictationShortcuts ?? [payload.hotkeyShortcut]
        self.promptModeHotkeyShortcut = payload.promptModeHotkeyShortcut
        self.promptModeShortcutEnabled = payload.promptModeShortcutEnabled
        self.commandModeHotkeyShortcut = payload.commandModeHotkeyShortcut
        self.commandModeShortcutEnabled = payload.commandModeShortcutEnabled
        self.commandModeSelectedModel = payload.commandModeSelectedModel
        self.commandModeSelectedProviderID = payload.commandModeSelectedProviderID
        self.commandModeConfirmBeforeExecute = payload.commandModeConfirmBeforeExecute
        self.commandModeLinkedToGlobal = payload.commandModeLinkedToGlobal
        self.rewriteModeHotkeyShortcut = payload.rewriteModeHotkeyShortcut
        self.rewriteModeShortcutEnabled = payload.rewriteModeShortcutEnabled
        self.rewriteModeSelectedModel = payload.rewriteModeSelectedModel
        self.rewriteModeSelectedProviderID = payload.rewriteModeSelectedProviderID
        self.rewriteModeLinkedToGlobal = payload.rewriteModeLinkedToGlobal
        if let enabled = payload.meetingRecordingShortcutEnabled {
            self.meetingRecordingHotkeyShortcut = enabled ? payload.meetingRecordingHotkeyShortcut : nil
        }
        self.cancelRecordingHotkeyShortcut = payload.cancelRecordingHotkeyShortcut
        // Both guarded so restoring an older backup (which predates these fields) doesn't wipe a
        // currently-configured shortcut or leave the feature enabled with no shortcut bound.
        if let pasteLastTranscriptionHotkeyShortcut = payload.pasteLastTranscriptionHotkeyShortcut {
            self.pasteLastTranscriptionHotkeyShortcut = pasteLastTranscriptionHotkeyShortcut
        }
        if let pasteLastTranscriptionShortcutEnabled = payload.pasteLastTranscriptionShortcutEnabled {
            self.pasteLastTranscriptionShortcutEnabled = pasteLastTranscriptionShortcutEnabled
        }
        self.showThinkingTokens = payload.showThinkingTokens
        self.hideFromDockAndAppSwitcher = payload.hideFromDockAndAppSwitcher
        self.showMainWindowAtLoginLaunch = payload.showMainWindowAtLoginLaunch ?? true
        self.accentColorOption = payload.accentColorOption
        self.transcriptionStartSound = payload.transcriptionStartSound
        self.transcriptionSoundVolume = payload.transcriptionSoundVolume
        self.autoUpdateCheckEnabled = payload.autoUpdateCheckEnabled
        if let showUpdatePopups = payload.showUpdatePopups {
            self.showUpdatePopups = showUpdatePopups
        }
        self.betaReleasesEnabled = payload.betaReleasesEnabled
        self.enableDebugLogs = payload.enableDebugLogs
        self.shareDetailedAnalytics = payload.shareAnonymousAnalytics
        self.hotkeyMode = payload.hotkeyMode ?? (payload.pressAndHoldMode ? .hold : .toggle)
        self.holdSpaceToMute = payload.holdSpaceToMute ?? false
        self.enableStreamingPreview = payload.enableStreamingPreview
        if let experimentalParakeetUnifiedFinalEnabled = payload.experimentalParakeetUnifiedFinalEnabled {
            self.experimentalParakeetUnifiedFinalEnabled = experimentalParakeetUnifiedFinalEnabled
        }
        if let returnDictationToStartingField = payload.returnDictationToStartingField {
            self.returnDictationToStartingField = returnDictationToStartingField
        }
        if let showHistoryPerformanceMetrics = payload.showHistoryPerformanceMetrics {
            self.showHistoryPerformanceMetrics = showHistoryPerformanceMetrics
        }
        if let skipSilentRecordingsEnabled = payload.skipSilentRecordingsEnabled {
            self.skipSilentRecordingsEnabled = skipSilentRecordingsEnabled
        }
        self.enableAIStreaming = payload.enableAIStreaming
        self.copyTranscriptionToClipboard = payload.copyTranscriptionToClipboard
        self.textInsertionMode = payload.textInsertionMode
        if let spokenSendEnabled = payload.spokenSendEnabled {
            self.spokenSendEnabled = spokenSendEnabled
        }
        if let spokenSendImmediatelyEnabled = payload.spokenSendImmediatelyEnabled {
            self.spokenSendImmediatelyEnabled = spokenSendImmediatelyEnabled
        }
        if let spokenSendPhrase = payload.spokenSendPhrase {
            self.spokenSendPhrase = spokenSendPhrase
        }
        if let spokenSendKey = payload.spokenSendKey {
            self.spokenSendKey = spokenSendKey
        }
        self.preferredInputDeviceUID = payload.preferredInputDeviceUID
        self.suppressedMicrophoneUIDs = Set(payload.suppressedMicrophoneUIDs ?? [])
        if let microphonePriority = payload.microphonePriority {
            self.microphonePriority = microphonePriority
        } else {
            self.microphonePriority = []
        }
        self.preferredOutputDeviceUID = payload.preferredOutputDeviceUID
        if payload.microphonePriority != nil {
            self.microphoneSelectionMode = .manual
            self.microphoneSelectionMigrationVersion = Self.microphonePriorityMigrationVersion
        } else if payload.microphoneSelectionMode == .system {
            self.microphoneSelectionMode = .system
            self.microphoneSelectionMigrationVersion = 0
        } else {
            self.microphoneSelectionMode = .manual
        }
        self.visualizerNoiseThreshold = payload.visualizerNoiseThreshold
        self.overlayPosition = payload.overlayPosition
        self.overlayBottomOffset = payload.overlayBottomOffset
        self.overlaySize = payload.overlaySize
        if let overlayMaterial = payload.overlayMaterial {
            self.overlayMaterial = overlayMaterial
        }
        if let overlayGlassOpacity = payload.overlayGlassOpacity {
            self.overlayGlassOpacity = overlayGlassOpacity
        }
        if let overlayTint = payload.overlayTint {
            self.overlayTint = overlayTint
        }
        if let overlayHighlight = payload.overlayHighlight {
            self.overlayHighlight = overlayHighlight
        }
        if let enabled = payload.overlayClosingAnimationEnabled {
            self.overlayClosingAnimationEnabled = enabled
        }
        if let meetingOverlayPreference = payload.meetingOverlayPreference {
            self.meetingOverlayPreference = meetingOverlayPreference
        }
        self.transcriptionPreviewCharLimit = payload.transcriptionPreviewCharLimit
        self.userTypingWPM = payload.userTypingWPM
        self.saveTranscriptionHistory = payload.saveTranscriptionHistory
        if let saveAudioWithTranscriptionHistory = payload.saveAudioWithTranscriptionHistory {
            self.saveAudioWithTranscriptionHistory = saveAudioWithTranscriptionHistory
        }
        if let audioHistoryBudgetGB = payload.audioHistoryBudgetGB {
            self.audioHistoryBudgetGB = audioHistoryBudgetGB
        }
        if let notifyAIProcessingFailures = payload.notifyAIProcessingFailures {
            self.notifyAIProcessingFailures = notifyAIProcessingFailures
        }
        if let showMicrophoneChangeAlerts = payload.showMicrophoneChangeAlerts {
            self.showMicrophoneChangeAlerts = showMicrophoneChangeAlerts
        }
        if let showPasteCheckAlerts = payload.showPasteCheckAlerts {
            self.showPasteCheckAlerts = showPasteCheckAlerts
        }
        self.weekendsDontBreakStreak = payload.weekendsDontBreakStreak
        self.fillerWords = payload.fillerWords
        self.removeFillerWordsEnabled = payload.removeFillerWordsEnabled
        if let autoConvertPunctuationEnabled = payload.autoConvertPunctuationEnabled {
            self.autoConvertPunctuationEnabled = autoConvertPunctuationEnabled
        }
        if let literalDictationFormattingEnabled = payload.literalDictationFormattingEnabled {
            self.literalDictationFormattingEnabled = literalDictationFormattingEnabled
        }
        if let punctuationDictionaryPrefix = payload.punctuationDictionaryPrefix {
            self.punctuationDictionaryPrefix = punctuationDictionaryPrefix
        }
        if let punctuationDictionaryRules = payload.punctuationDictionaryRules {
            self.punctuationDictionaryRules = punctuationDictionaryRules
        }
        if let spokenFormattingActionRules = payload.spokenFormattingActionRules {
            self.spokenFormattingActionRules = spokenFormattingActionRules
        }
        let restoredGaavModeEnabled = payload.gaavModeEnabled
        let restoredContinuousDictationModeEnabled = payload.continuousDictationModeEnabled ?? false
        self.gaavModeEnabled = restoredGaavModeEnabled
        self.gaavLowercaseFirstLetterEnabled = payload.gaavLowercaseFirstLetterEnabled ?? restoredGaavModeEnabled
        self.gaavRemoveTrailingPeriodEnabled = payload.gaavRemoveTrailingPeriodEnabled ?? restoredGaavModeEnabled
        self.continuousDictationModeEnabled = restoredContinuousDictationModeEnabled
        self.continuousDictationSpacingEnabled = payload.continuousDictationSpacingEnabled ?? restoredContinuousDictationModeEnabled
        self.contextAwareCapitalizationEnabled = payload.contextAwareCapitalizationEnabled ?? restoredContinuousDictationModeEnabled
        self.pauseMediaDuringTranscription = payload.pauseMediaDuringTranscription
        if let automaticDictionaryLearningEnabled = payload.automaticDictionaryLearningEnabled {
            self.automaticDictionaryLearningEnabled = automaticDictionaryLearningEnabled
        }
        if let automaticDictionarySuggestionFrequency = payload.automaticDictionarySuggestionFrequency {
            self.automaticDictionarySuggestionFrequency = automaticDictionarySuggestionFrequency
        }
        if let pronunciationMatchingEnabled = payload.pronunciationMatchingEnabled {
            self.pronunciationMatchingEnabled = pronunciationMatchingEnabled
        }
        self.vocabularyBoostingEnabled = payload.vocabularyBoostingEnabled
        self.customDictionaryEntries = payload.customDictionaryEntries

        self.dictationPromptProfiles = promptProfiles
        if let configurations = payload.dictationPromptConfigurations {
            self.dictationPromptConfigurations = configurations
        }
        self.appPromptBindings = appPromptBindings
        self.selectedDictationPromptID = payload.selectedDictationPromptID
        self.isDictationPromptOff = payload.dictationPromptOff ?? self.isDictationPromptOff
        self.dictationPromptRoutingScope = payload.dictationPromptRoutingScope ?? .allApps
        self.isEditPromptOff = payload.editPromptOff ?? self.isEditPromptOff
        self.editPromptRoutingScope = payload.editPromptRoutingScope ?? .allApps
        self.selectedEditPromptID = payload.selectedEditPromptID
        self.defaultDictationPromptOverride = payload.defaultDictationPromptOverride
        self.defaultEditPromptOverride = payload.defaultEditPromptOverride
        if let fileTranscriptionSpeakerLabelsEnabled = payload.fileTranscriptionSpeakerLabelsEnabled {
            self.fileTranscriptionSpeakerLabelsEnabled = fileTranscriptionSpeakerLabelsEnabled
        }
        if let fileTranscriptionExpectedSpeakerCount = payload.fileTranscriptionExpectedSpeakerCount {
            self.fileTranscriptionExpectedSpeakerCount = fileTranscriptionExpectedSpeakerCount
        }
        self.promptModeSelectedPromptID = payload.promptModeSelectedPromptID
        self.isSecondaryDictationPromptOff = payload.secondaryDictationPromptOff ?? false
        self.normalizePromptSelectionsIfNeeded()
        // Validate imported mappings only after profile migration/normalization.
        // Legacy backups do not own the newer map, so leave it intact when absent.
        if payload.dictationPromptConfigurations != nil {
            self.normalizeDictationPromptConfigurationsIfNeeded()
        }
        self.purgeRetiredAppleIntelligenceState()
        self.makeEditModeIndependentIfNeeded()
    }

    // MARK: - Private Methods

    private func logProviderAPIKeyPersistenceFailure(_ error: Error) {
        DebugLogger.shared.error(
            "Failed to persist provider API keys: \(error.localizedDescription)",
            source: "SettingsStore"
        )
    }

    private func migrateTranscriptionStartSoundIfNeeded() {
        guard let legacyEnabled = self.defaults.object(forKey: Keys.enableTranscriptionSounds) as? Bool else { return }
        if legacyEnabled == false {
            self.defaults.set(TranscriptionStartSound.none.rawValue, forKey: Keys.transcriptionStartSound)
        }
        self.defaults.removeObject(forKey: Keys.enableTranscriptionSounds)
    }

    private func migrateProviderAPIKeysIfNeeded() {
        self.defaults.removeObject(forKey: Keys.providerAPIKeyIdentifiers)

        var merged = (try? self.keychain.fetchAllKeys()) ?? [:]
        var didMutate = false

        if let legacyDefaults = defaults.dictionary(forKey: Keys.providerAPIKeys) as? [String: String],
           legacyDefaults.isEmpty == false
        {
            merged.merge(self.sanitizeAPIKeys(legacyDefaults)) { _, new in new }
            didMutate = true
        }
        self.defaults.removeObject(forKey: Keys.providerAPIKeys)

        if let legacyKeychain = try? keychain.legacyProviderEntries(),
           legacyKeychain.isEmpty == false
        {
            merged.merge(self.sanitizeAPIKeys(legacyKeychain)) { _, new in new }
            didMutate = true
            try? self.keychain.removeLegacyEntries(providerIDs: Array(legacyKeychain.keys))
        }

        if didMutate {
            do {
                _ = try self.saveProviderAPIKeys(merged)
            } catch {
                self.logProviderAPIKeyPersistenceFailure(error)
            }
        }
    }

    static func customPromptBody(_ text: String, mode: PromptMode) -> String {
        mode.normalized == .dictate ? text : self.stripBasePrompt(for: mode, from: text)
    }

    static func migrateExplicitDictationPrompt(
        _ profile: DictationPromptProfile, legacySendOnly: Bool
    ) -> DictationPromptProfile {
        guard profile.mode.normalized == .dictate, !profile.usesExplicitDictationPrompt else { return profile }
        var migrated = profile
        let body = self.stripBasePrompt(for: .dictate, from: profile.prompt)
        // Empty legacy styles used the default fallback; keep that behavior.
        migrated.prompt = legacySendOnly || body.isEmpty ? body : self.combineBasePrompt(for: .dictate, with: body)
        migrated.usesExplicitDictationPrompt = true
        migrated.usesLegacyEmptyPromptFallback = body.isEmpty
        migrated.legacyEmptyShortcutUsesBasePrompt = body.isEmpty && !legacySendOnly
        return migrated
    }

    private func migrateExplicitDictationPromptsIfNeeded() {
        let profiles = self.dictationPromptProfiles
        guard profiles.contains(where: { $0.mode.normalized == .dictate && !$0.usesExplicitDictationPrompt }) else { return }
        self.dictationPromptProfiles = profiles
    }

    private func migrateDictationPromptProfilesIfNeeded() {
        // Migration path from legacy single prompt to multi-prompt profiles.
        // If user had a legacy custom dictation prompt, convert it to a profile and select it.
        let legacyPrompt = self.customDictationPrompt.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !legacyPrompt.isEmpty else { return }

        // If profiles already exist, just clear the legacy prompt so we don't keep two sources of truth.
        if self.dictationPromptProfiles.isEmpty == false {
            self.customDictationPrompt = ""
            // If selection points to nowhere, reset to default to avoid confusion.
            if let id = self.selectedDictationPromptID,
               self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode == .dictate }) == false
            {
                self.selectedDictationPromptID = nil
            }
            return
        }

        var profile = DictationPromptProfile(
            name: "My Custom Prompt",
            prompt: legacyPrompt,
            createdAt: Date(),
            updatedAt: Date()
        )
        profile.usesExplicitDictationPrompt = false
        self.dictationPromptProfiles = [profile]
        self.selectedDictationPromptID = profile.id
        self.customDictationPrompt = ""
        DebugLogger.shared.info("Migrated legacy custom dictation prompt to a prompt profile", source: "SettingsStore")
    }

    private func migrateLegacyDictationAIPreferenceIfNeeded() {
        guard self.defaults.object(forKey: Keys.dictationPromptOff) == nil else { return }

        let hasSelectedCustomDictationPrompt = self.selectedDictationPromptID.flatMap { id in
            self.dictationPromptProfiles.first(where: { $0.id == id && $0.mode == .dictate })
        } != nil

        let shouldStartOff: Bool
        if hasSelectedCustomDictationPrompt {
            shouldStartOff = false
        } else if self.defaults.object(forKey: Keys.enableAIProcessing) != nil {
            shouldStartOff = !self.defaults.bool(forKey: Keys.enableAIProcessing)
        } else {
            shouldStartOff = true
        }

        self.defaults.set(shouldStartOff, forKey: Keys.dictationPromptOff)
    }

    private func migrateSecondaryPromptShortcutIfNeeded() {
        guard self.defaults.bool(forKey: Keys.secondaryPromptShortcutRemoved) == false else { return }
        self.defaults.set(false, forKey: Keys.promptModeShortcutEnabled)
        self.defaults.set(true, forKey: Keys.secondaryDictationPromptOff)
        self.defaults.removeObject(forKey: Keys.promptModeSelectedPromptID)
        self.defaults.set(true, forKey: Keys.secondaryPromptShortcutRemoved)
    }

    private func retireLegacySecondaryPromptShortcutIfNeeded() {
        guard self.defaults.bool(forKey: Keys.legacySecondaryPromptShortcutRetired) == false else { return }

        self.defaults.set(false, forKey: Keys.promptModeShortcutEnabled)
        self.defaults.set(true, forKey: Keys.secondaryDictationPromptOff)
        self.defaults.removeObject(forKey: Keys.promptModeHotkeyShortcut)
        self.defaults.removeObject(forKey: Keys.promptModeSelectedPromptID)
        self.defaults.set(true, forKey: Keys.legacySecondaryPromptShortcutRetired)
    }

    private func normalizePromptSelectionsIfNeeded() {
        if self.defaults.object(forKey: Keys.secondaryDictationPromptOff) == nil {
            self.defaults.set(false, forKey: Keys.secondaryDictationPromptOff)
        }

        // One-time migration to unified edit keys.
        if self.defaults.object(forKey: Keys.selectedEditPromptID) == nil,
           let migratedSelectedEditID = self.selectedEditPromptID
        {
            self.defaults.set(migratedSelectedEditID, forKey: Keys.selectedEditPromptID)
            self.defaults.removeObject(forKey: Keys.selectedWritePromptID)
            self.defaults.removeObject(forKey: Keys.selectedRewritePromptID)
        }

        if self.defaults.object(forKey: Keys.defaultEditPromptOverride) == nil,
           let migratedEditOverride = self.defaultEditPromptOverride
        {
            self.defaults.set(migratedEditOverride, forKey: Keys.defaultEditPromptOverride)
            self.defaults.removeObject(forKey: Keys.defaultWritePromptOverride)
            self.defaults.removeObject(forKey: Keys.defaultRewritePromptOverride)
        }

        // Persist profile mode normalization to the new user-facing modes.
        var normalizedProfiles = self.dictationPromptProfiles
        var didChangeProfiles = false
        for idx in normalizedProfiles.indices {
            let normalizedMode = normalizedProfiles[idx].mode.normalized
            if normalizedProfiles[idx].mode != normalizedMode {
                normalizedProfiles[idx].mode = normalizedMode
                didChangeProfiles = true
            }
        }
        normalizedProfiles.removeAll { profile in
            let name = profile.name.trimmingCharacters(in: .whitespacesAndNewlines)
            let prompt = Self.stripBasePrompt(for: profile.mode, from: profile.prompt)
                .trimmingCharacters(in: .whitespacesAndNewlines)
            let isLegacyPlaceholder = profile.mode.normalized == .dictate &&
                name.caseInsensitiveCompare("Blocked") == .orderedSame &&
                prompt.caseInsensitiveCompare("Blocked prompt") == .orderedSame
            let isAccidentalPrivateAIProfile = profile.mode.normalized == .dictate &&
                name.caseInsensitiveCompare(PrivateAIProviderFeature.displayName) == .orderedSame &&
                prompt.isEmpty
            if isLegacyPlaceholder || isAccidentalPrivateAIProfile {
                didChangeProfiles = true
            }
            return isLegacyPlaceholder || isAccidentalPrivateAIProfile
        }
        if didChangeProfiles {
            self.dictationPromptProfiles = normalizedProfiles
        }

        let privateAIPromptID = PrivateAIProviderPromptFormat.promptSelectionID

        if let id = self.selectedDictationPromptID,
           !(PrivateFeatures.privateAIProvider && id == privateAIPromptID),
           self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode == .dictate }) == false
        {
            self.selectedDictationPromptID = nil
        }

        if let id = self.selectedEditPromptID,
           self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode.normalized == .edit }) == false
        {
            self.selectedEditPromptID = nil
        }

        if let id = self.promptModeSelectedPromptID,
           !(PrivateFeatures.privateAIProvider && id == privateAIPromptID),
           self.dictationPromptProfiles.contains(where: { $0.id == id && $0.mode.normalized == .dictate }) == false
        {
            self.promptModeSelectedPromptID = nil
        }

        let validPromptIDsByMode: [PromptMode: Set<String>] = [
            .dictate: Set(self.dictationPromptProfiles.filter { $0.mode.normalized == .dictate }.map(\.id)),
            .edit: Set(self.dictationPromptProfiles.filter { $0.mode.normalized == .edit }.map(\.id)),
        ]

        var normalizedBindings: [AppPromptBinding] = []
        var dedupe: [String: AppPromptBinding] = [:]
        var didMutateBindings = false

        for binding in self.appPromptBindings {
            let normalizedMode = binding.mode.normalized
            guard let normalizedBundleID = Self.normalizeAppBundleID(binding.appBundleID) else {
                didMutateBindings = true
                continue
            }

            var cleaned = binding
            if cleaned.mode != normalizedMode {
                cleaned.mode = normalizedMode
                didMutateBindings = true
            }
            if cleaned.appBundleID != normalizedBundleID {
                cleaned.appBundleID = normalizedBundleID
                didMutateBindings = true
            }

            let trimmedName = cleaned.appName.trimmingCharacters(in: .whitespacesAndNewlines)
            let resolvedName = trimmedName.isEmpty ? normalizedBundleID : trimmedName
            if cleaned.appName != resolvedName {
                cleaned.appName = resolvedName
                didMutateBindings = true
            }

            if let promptID = cleaned.promptID,
               validPromptIDsByMode[normalizedMode]?.contains(promptID) != true
            {
                cleaned.promptID = nil
                didMutateBindings = true
            }

            let dedupeKey = "\(normalizedMode.rawValue)|\(normalizedBundleID)"
            if let existing = dedupe[dedupeKey] {
                // Keep the most recently updated binding when duplicates exist.
                if cleaned.updatedAt >= existing.updatedAt {
                    dedupe[dedupeKey] = cleaned
                }
                didMutateBindings = true
            } else {
                dedupe[dedupeKey] = cleaned
            }
        }

        normalizedBindings = Array(dedupe.values).sorted { lhs, rhs in
            if lhs.mode.normalized != rhs.mode.normalized {
                return lhs.mode.normalized.rawValue < rhs.mode.normalized.rawValue
            }
            if lhs.appName.localizedCaseInsensitiveCompare(rhs.appName) != .orderedSame {
                return lhs.appName.localizedCaseInsensitiveCompare(rhs.appName) == .orderedAscending
            }
            return lhs.appBundleID < rhs.appBundleID
        }

        if didMutateBindings || normalizedBindings.count != self.appPromptBindings.count {
            self.appPromptBindings = normalizedBindings
        }
    }

    private func normalizeDictationPromptConfigurationsIfNeeded() {
        let validKeys = Set(
            ["__default__", "__privateAI__"] + self.dictationPromptProfiles
                .filter { $0.mode.normalized == .dictate }
                .map { "profile:\($0.id)" }
        )
        var configurations = self.dictationPromptConfigurations
        let originalCount = configurations.count
        configurations = configurations.filter { key, configuration in
            validKeys.contains(key) &&
                (
                    configuration.shortcut != nil ||
                        !configuration.providerID.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ||
                        !configuration.modelName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
                )
        }
        if configurations.count != originalCount {
            self.dictationPromptConfigurations = configurations
        }
    }

    private func migrateOverlayBottomOffsetTo50IfNeeded() {
        if self.defaults.bool(forKey: Keys.overlayBottomOffsetMigratedTo50) {
            return
        }

        self.defaults.set(50.0, forKey: Keys.overlayBottomOffset)
        self.defaults.set(true, forKey: Keys.overlayBottomOffsetMigratedTo50)
        NotificationCenter.default.post(name: NSNotification.Name("OverlayOffsetChanged"), object: nil)
    }

    private func scrubSavedProviderAPIKeys() {
        guard let data = defaults.data(forKey: Keys.savedProviders),
              var decoded = try? JSONDecoder().decode([SavedProvider].self, from: data) else { return }

        var didModify = false
        for index in decoded.indices {
            let provider = decoded[index]
            let trimmed = provider.apiKey.trimmingCharacters(in: .whitespacesAndNewlines)
            guard trimmed.isEmpty == false else { continue }

            let keyID = self.canonicalProviderKey(for: provider.id)
            do {
                try self.keychain.storeKey(trimmed, for: keyID)
                didModify = true
            } catch {
                DebugLogger.shared
                    .error(
                        "Failed to migrate API key for \(provider.name): \(error.localizedDescription)",
                        source: "SettingsStore"
                    )
            }

            decoded[index] = SavedProvider(
                id: provider.id,
                name: provider.name,
                baseURL: provider.baseURL,
                apiKey: "",
                models: provider.models
            )
        }

        if didModify,
           let encoded = try? JSONEncoder().encode(decoded)
        {
            self.defaults.set(encoded, forKey: Keys.savedProviders)
        }

        // No need to track migrated IDs; consolidated storage keeps them together.
    }

    private func canonicalProviderKey(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
        }
        if trimmed.hasPrefix("custom:") {
            return trimmed
        }
        return "custom:\(trimmed)"
    }

    private func verifiedProviderIDsForCurrentConfiguration() -> [String] {
        var providerIDs = ModelRepository.builtInProviderIDs + self.savedProviders.map(\.id)
        if PrivateFeatures.privateAIProvider {
            providerIDs.append(PrivateAIProviderFeature.shared.providerID)
        }

        var seenProviderKeys = Set<String>()
        return providerIDs.filter { providerID in
            let key = self.canonicalProviderKey(for: providerID)
            guard !key.isEmpty, seenProviderKeys.insert(key).inserted else { return false }
            return self.isVerifiedProviderForCurrentConfiguration(providerID)
        }
    }

    private func isVerifiedProviderForCurrentConfiguration(_ providerID: String) -> Bool {
        let trimmed = providerID.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty else { return false }

        if PrivateFeatures.privateAIProvider,
           trimmed == PrivateAIProviderFeature.shared.providerID
        {
            return PrivateAIProviderPromptFormat.verifiedModelID(settings: self) != nil
        }

        let key = self.canonicalProviderKey(for: trimmed)
        guard let stored = self.verifiedProviderFingerprints[key] else { return false }

        let baseURL = self.providerBaseURLForVerification(for: trimmed)
        let apiKey = (self.getAPIKey(for: trimmed) ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
        guard ModelRepository.shared.isLocalEndpoint(baseURL) || !apiKey.isEmpty else { return false }

        return self.providerFingerprint(baseURL: baseURL, apiKey: apiKey) == stored
    }

    private func providerBaseURLForVerification(for providerID: String) -> String {
        let savedProviderID = providerID.hasPrefix("custom:") ?
            String(providerID.dropFirst("custom:".count)) : providerID
        if let saved = self.savedProviders.first(where: { $0.id == savedProviderID }) {
            return saved.baseURL.trimmingCharacters(in: .whitespacesAndNewlines)
        }
        if ModelRepository.shared.isBuiltIn(providerID) {
            return ModelRepository.shared.defaultBaseURL(for: providerID).trimmingCharacters(in: .whitespacesAndNewlines)
        }
        return ""
    }

    private func providerFingerprint(baseURL: String, apiKey: String) -> String? {
        let trimmedBaseURL = baseURL.trimmingCharacters(in: .whitespacesAndNewlines)
        let trimmedAPIKey = apiKey.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmedBaseURL.isEmpty else { return nil }

        let input = "\(trimmedBaseURL)|\(trimmedAPIKey)"
        let digest = SHA256.hash(data: Data(input.utf8))
        return digest.map { String(format: "%02x", $0) }.joined()
    }

    private func syncLinkedProviderSelections(to providerID: String) {
        let trimmed = providerID.trimmingCharacters(in: .whitespacesAndNewlines)

        if self.commandModeLinkedToGlobal {
            let linkedProviderID = self.isPrivateAIProviderID(trimmed) ? "" : trimmed
            self.commandModeSelectedProviderID = linkedProviderID
            self.commandModeSelectedModel = self.modelSelection(for: linkedProviderID)
        }
    }

    private func isPrivateAIProviderID(_ providerID: String) -> Bool {
        PrivateFeatures.privateAIProvider &&
            providerID.trimmingCharacters(in: .whitespacesAndNewlines) == PrivateAIProviderFeature.shared.providerID
    }

    private func modelSelection(for providerID: String) -> String? {
        guard !providerID.isEmpty else { return nil }

        if PrivateFeatures.privateAIProvider,
           providerID == PrivateAIProviderFeature.shared.providerID,
           let modelID = PrivateAIProviderPromptFormat.verifiedModelID(settings: self)
        {
            return modelID
        }

        let key = self.canonicalProviderKey(for: providerID)
        if let selected = self.selectedModelByProvider[key],
           !selected.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
        {
            return selected
        }

        let savedProviderID = providerID.hasPrefix("custom:") ?
            String(providerID.dropFirst("custom:".count)) : providerID
        if let savedModel = self.savedProviders.first(where: { $0.id == savedProviderID })?.models.first,
           !savedModel.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
        {
            return savedModel
        }

        return ModelRepository.shared.defaultModels(for: providerID).first
    }

    func availableModels(for providerID: String, task: PrivateAIModelTask) -> [String] {
        if self.isPrivateAIProviderID(providerID) {
            return ModelRepository.shared.defaultModels(for: providerID, task: task)
        }

        if let configured = ModelRepository.shared.providerKeys(for: providerID).lazy
            .compactMap({ self.availableModelsByProvider[$0] })
            .first(where: { !$0.isEmpty })
        {
            return configured
        }

        let savedProviderID = providerID.hasPrefix("custom:") ?
            String(providerID.dropFirst("custom:".count)) : providerID
        if let configured = self.savedProviders.first(where: { $0.id == savedProviderID })?.models,
           !configured.isEmpty
        {
            return configured
        }

        return ModelRepository.shared.defaultModels(for: providerID)
    }

    /// Keep a legacy linked choice once, then let Edit Mode own its provider/model.
    /// Also runs after restoring an older backup; an empty route stays visibly unconfigured.
    func makeEditModeIndependentIfNeeded() {
        guard self.rewriteModeLinkedToGlobal else { return }
        let linkedProviderID = self.effectiveRewriteModeProviderID.trimmingCharacters(in: .whitespacesAndNewlines)
        let storedProviderID = self.rewriteModeSelectedProviderID.trimmingCharacters(in: .whitespacesAndNewlines)
        // Basic dictation has no cleanup provider; it must not erase an existing Edit choice.
        let providerID = linkedProviderID.isEmpty
            ? (storedProviderID.isEmpty ? self.selectedProviderID : storedProviderID)
            : linkedProviderID
        let linkedModelID = self.effectiveRewriteModeSelectedModel
        let modelID = ModelRepository.eligibleModel(
            preferred: linkedModelID.isEmpty ? self.rewriteModeSelectedModel : linkedModelID,
            from: self.availableModels(for: providerID, task: .edit)
        )
        self.objectWillChange.send()
        Self.makeEditModeIndependent(defaults: self.defaults, providerID: providerID, modelID: modelID)
    }

    static func makeEditModeIndependent(defaults: UserDefaults, providerID: String, modelID: String?) {
        guard defaults.object(forKey: Keys.rewriteModeLinkedToGlobal) as? Bool != false else { return }
        defaults.set(providerID, forKey: Keys.rewriteModeSelectedProviderID)
        defaults.set(modelID, forKey: Keys.rewriteModeSelectedModel)
        defaults.set(false, forKey: Keys.rewriteModeLinkedToGlobal)
    }

    var effectiveRewriteModeProviderID: String {
        guard self.rewriteModeLinkedToGlobal else { return self.rewriteModeSelectedProviderID }
        // "Same as dictation" follows what the main shortcut really uses. On the on-device
        // style that is the local provider, whatever selectedProviderID holds.
        let selection = self.dictationPromptSelection(for: .primary)
        return DictationDefaultProvider.providerID(
            selection: selection,
            configuration: self.dictationPromptConfiguration(for: selection),
            selectedProviderID: self.selectedProviderID,
            privateProviderID: PrivateAIProviderFeature.shared.providerID
        )
    }

    var effectiveRewriteModeSelectedModel: String {
        let providerID = self.effectiveRewriteModeProviderID
        let models = self.availableModels(for: providerID, task: .edit)
        let preferred: String? = if self.rewriteModeLinkedToGlobal {
            ModelRepository.shared.providerKeys(for: providerID).lazy
                .compactMap { self.selectedModelByProvider[$0] }
                .first { !$0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }
                ?? self.selectedModel
        } else {
            self.rewriteModeSelectedModel
        }
        return ModelRepository.eligibleModel(preferred: preferred, from: models) ?? ""
    }

    func analyticsAIModelDescriptor(for mode: AnalyticsUsageMode) -> AnalyticsModelDescriptor? {
        let providerID: String
        let selectedModel: String?
        switch mode {
        case .edit:
            providerID = self.effectiveRewriteModeProviderID
            selectedModel = self.effectiveRewriteModeSelectedModel
        case .command:
            providerID = self.commandModeLinkedToGlobal ? self.selectedProviderID : self.commandModeSelectedProviderID
            selectedModel = self.commandModeLinkedToGlobal ? self.modelSelection(for: providerID) : self.commandModeSelectedModel
        case .dictation, .meeting:
            providerID = self.selectedProviderID
            selectedModel = self.modelSelection(for: providerID)
        }
        guard !providerID.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return nil }
        return AnalyticsModelDescriptor(provider: providerID, model: selectedModel ?? "unknown")
    }

    private func availableSelectedProviderID(for rawValue: String?) -> String {
        let trimmed = rawValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
        guard !trimmed.isEmpty else { return "" }
        let providerID = trimmed
        if ModelRepository.shared.isBuiltIn(providerID) { return providerID }
        if PrivateFeatures.privateAIProvider,
           providerID == PrivateAIProviderFeature.shared.providerID
        {
            return providerID
        }

        let savedProviderID = providerID.hasPrefix("custom:") ?
            String(providerID.dropFirst("custom:".count)) : providerID
        if self.savedProviders.contains(where: { $0.id == savedProviderID }) {
            return savedProviderID
        }

        return ""
    }

    private func sanitizeAPIKeys(_ values: [String: String]) -> [String: String] {
        values.reduce(into: [String: String]()) { partialResult, pair in
            let sanitizedValue = pair.value.trimmingCharacters(in: .whitespacesAndNewlines)
            guard sanitizedValue.isEmpty == false else { return }
            partialResult[pair.key] = sanitizedValue
        }
    }

    private func updateDockVisibility(_ visible: Bool) {
        #if os(macOS)
        // IMPORTANT: This is a simplified implementation for development
        // In production, consider these approaches:
        // 1. Use LSUIElement in Info.plist to control default dock visibility
        // 2. Implement a proper helper app or service for dock management
        // 3. Use NSApplication.shared.setActivationPolicy() for better control

        // For now, we'll try multiple approaches with fallbacks

        DebugLogger.shared.debug(
            "Attempting to update dock visibility to: \(visible ? "visible" : "hidden")",
            source: "SettingsStore"
        )

        // Method 1: Try the deprecated TransformProcessType (may not work on all systems)
        let transformState = visible ? ProcessApplicationTransformState(kProcessTransformToForegroundApplication)
            : ProcessApplicationTransformState(kProcessTransformToUIElementApplication)

        var psn = ProcessSerialNumber(highLongOfPSN: 0, lowLongOfPSN: UInt32(kCurrentProcess))
        let result = TransformProcessType(&psn, transformState)

        if result == 0 {
            DebugLogger.shared.info("✓ Dock visibility updated using TransformProcessType", source: "SettingsStore")
        } else {
            DebugLogger.shared
                .warning(
                    "⚠️ TransformProcessType failed (error: \(result)). This is expected on some macOS versions.",
                    source: "SettingsStore"
                )
            DebugLogger.shared.debug(
                "   The setting is saved and will be applied when possible.",
                source: "SettingsStore"
            )
        }

        // Method 2: Try to notify the system of the change
        // This may help with some system caches
        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
            NSApp.setActivationPolicy(visible ? .regular : .accessory)
            DebugLogger.shared.info(
                "✓ Activation policy updated to: \(visible ? "regular" : "accessory")",
                source: "SettingsStore"
            )
        }

        // Store the intended state for reference
        UserDefaults.standard.set(visible, forKey: "IntendedDockVisibility")
        DebugLogger.shared.info("✓ Dock visibility preference saved: \(visible)", source: "SettingsStore")
        #endif
    }

    // MARK: - Filler Words

    static let defaultFillerWords = [
        "um",
        "uh",
        "er",
        "ah",
        "eh",
        "umm",
        "uhh",
        "err",
        "ahh",
        "ehh",
        "hmm",
        "hm",
        "mm",
        "mmm",
        "erm",
        "urm",
        "ugh",
    ]

    var fillerWords: [String] {
        get {
            if let stored = defaults.array(forKey: Keys.fillerWords) as? [String] {
                return stored
            }
            return Self.defaultFillerWords
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.fillerWords)
        }
    }

    var removeFillerWordsEnabled: Bool {
        get { self.defaults.object(forKey: Keys.removeFillerWordsEnabled) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.removeFillerWordsEnabled)
        }
    }

    var autoConvertPunctuationEnabled: Bool {
        get { self.defaults.object(forKey: Keys.autoConvertPunctuationEnabled) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.autoConvertPunctuationEnabled)
        }
    }

    var literalDictationFormattingEnabled: Bool {
        get { self.defaults.object(forKey: Keys.literalDictationFormattingEnabled) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.literalDictationFormattingEnabled)
        }
    }

    static let defaultPunctuationDictionaryPrefix = "literal"

    enum SpokenFormattingAction: String, Codable, CaseIterable, Identifiable {
        case newLine
        case newParagraph
        case tab
        case space

        var id: Self {
            self
        }

        var title: String {
            switch self {
            case .newLine: return "New Line"
            case .newParagraph: return "New Paragraph"
            case .tab: return "Tab"
            case .space: return "Space"
            }
        }

        var displaySymbol: String {
            switch self {
            case .newLine: return "⏎"
            case .newParagraph: return "¶"
            case .tab: return "⇥"
            case .space: return "␣"
            }
        }

        var output: String {
            switch self {
            case .newLine: return "\n"
            case .newParagraph: return "\n\n"
            case .tab: return "\t"
            case .space: return " "
            }
        }
    }

    struct SpokenFormattingActionRule: Codable, Identifiable, Hashable {
        var action: SpokenFormattingAction
        var aliases: [String]
        var isEnabled: Bool

        var id: SpokenFormattingAction {
            self.action
        }

        init(action: SpokenFormattingAction, aliases: [String], isEnabled: Bool = true) {
            self.action = action
            self.aliases = PunctuationDictionaryRule.normalizedAliases(aliases)
            self.isEnabled = isEnabled && !self.aliases.isEmpty
        }
    }

    static let defaultSpokenFormattingActionRules: [SpokenFormattingActionRule] = [
        SpokenFormattingActionRule(action: .newLine, aliases: ["new line", "next line"]),
        SpokenFormattingActionRule(action: .newParagraph, aliases: ["new paragraph", "next paragraph"]),
        SpokenFormattingActionRule(action: .tab, aliases: ["tab"]),
        SpokenFormattingActionRule(action: .space, aliases: ["space"]),
    ]

    static let defaultPunctuationDictionaryRules: [PunctuationDictionaryRule] = [
        PunctuationDictionaryRule(aliases: ["comma"], symbol: ","),
        PunctuationDictionaryRule(aliases: ["period", "full stop"], symbol: "."),
        PunctuationDictionaryRule(aliases: ["dot"], symbol: "."),
        PunctuationDictionaryRule(aliases: ["question mark", "questionmark"], symbol: "?"),
        PunctuationDictionaryRule(aliases: ["exclamation mark", "exclamation point", "bang"], symbol: "!"),
        PunctuationDictionaryRule(aliases: ["colon"], symbol: ":"),
        PunctuationDictionaryRule(aliases: ["semicolon", "semi colon"], symbol: ";"),
        PunctuationDictionaryRule(aliases: ["ellipsis", "dot dot dot", "three dots"], symbol: "..."),
        PunctuationDictionaryRule(aliases: ["slash", "forward slash", "forwardslash"], symbol: "/"),
        PunctuationDictionaryRule(aliases: ["backslash", "back slash"], symbol: "\\"),
        PunctuationDictionaryRule(aliases: ["hyphen"], symbol: "-"),
        PunctuationDictionaryRule(aliases: ["dash", "minus sign"], symbol: "-"),
        PunctuationDictionaryRule(aliases: ["em dash", "long dash"], symbol: "—"),
        PunctuationDictionaryRule(aliases: ["en dash"], symbol: "–"),
        PunctuationDictionaryRule(
            aliases: ["open parenthesis", "open parentheses", "left parenthesis", "left parentheses", "open paren", "left paren"],
            symbol: "("
        ),
        PunctuationDictionaryRule(
            aliases: ["close parenthesis", "close parentheses", "right parenthesis", "right parentheses", "close paren", "right paren"],
            symbol: ")"
        ),
        PunctuationDictionaryRule(aliases: ["open bracket", "left bracket", "open square bracket", "left square bracket"], symbol: "["),
        PunctuationDictionaryRule(aliases: ["close bracket", "right bracket", "close square bracket", "right square bracket"], symbol: "]"),
        PunctuationDictionaryRule(
            aliases: ["open brace", "left brace", "open curly brace", "left curly brace", "open curly bracket", "left curly bracket"],
            symbol: "{"
        ),
        PunctuationDictionaryRule(
            aliases: ["close brace", "right brace", "close curly brace", "right curly brace", "close curly bracket", "right curly bracket"],
            symbol: "}"
        ),
        PunctuationDictionaryRule(aliases: ["open angle bracket", "left angle bracket", "less than sign"], symbol: "<"),
        PunctuationDictionaryRule(aliases: ["close angle bracket", "right angle bracket", "greater than sign"], symbol: ">"),
        PunctuationDictionaryRule(aliases: ["quote", "quotes", "quotation mark", "double quote"], symbol: "\""),
        PunctuationDictionaryRule(aliases: ["open quote", "opening quote", "open double quote", "opening double quote"], symbol: "\""),
        PunctuationDictionaryRule(aliases: ["close quote", "closing quote", "close double quote", "closing double quote"], symbol: "\""),
        PunctuationDictionaryRule(aliases: ["single quote"], symbol: "'"),
        PunctuationDictionaryRule(aliases: ["apostrophe"], symbol: "'"),
        PunctuationDictionaryRule(aliases: ["at the rate", "at sign", "commercial at"], symbol: "@"),
        PunctuationDictionaryRule(aliases: ["ampersand", "and sign"], symbol: "&"),
        PunctuationDictionaryRule(aliases: ["plus sign", "plus"], symbol: "+"),
        PunctuationDictionaryRule(aliases: ["equals sign", "equal sign", "equal", "equals"], symbol: "="),
        PunctuationDictionaryRule(aliases: ["percent sign", "percentage sign", "percent"], symbol: "%"),
        PunctuationDictionaryRule(aliases: ["dollar sign", "dollar"], symbol: "$"),
        PunctuationDictionaryRule(aliases: ["hash", "hash sign", "hashtag", "pound sign", "number sign"], symbol: "#"),
        PunctuationDictionaryRule(aliases: ["asterisk", "star symbol"], symbol: "*"),
        PunctuationDictionaryRule(aliases: ["underscore"], symbol: "_"),
        PunctuationDictionaryRule(aliases: ["pipe", "vertical bar"], symbol: "|"),
        PunctuationDictionaryRule(aliases: ["tilde"], symbol: "~"),
        PunctuationDictionaryRule(aliases: ["caret"], symbol: "^"),
        PunctuationDictionaryRule(aliases: ["backtick", "back tick"], symbol: "`"),
    ]

    struct PunctuationDictionaryRule: Codable, Identifiable, Hashable {
        let id: UUID
        var aliases: [String]
        var symbol: String

        init(aliases: [String], symbol: String) {
            self.id = UUID()
            self.aliases = Self.normalizedAliases(aliases)
            self.symbol = Self.normalizedSymbol(symbol) ?? symbol
        }

        init(id: UUID, aliases: [String], symbol: String) {
            self.id = id
            self.aliases = Self.normalizedAliases(aliases)
            self.symbol = Self.normalizedSymbol(symbol) ?? symbol
        }

        static func normalizedAlias(_ value: String) -> String? {
            let alias = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
            return alias.isEmpty ? nil : alias
        }

        static func normalizedAliases(_ values: [String]) -> [String] {
            var seen: Set<String> = []
            var aliases: [String] = []
            aliases.reserveCapacity(values.count)

            for value in values {
                guard let alias = self.normalizedAlias(value), !seen.contains(alias) else { continue }
                seen.insert(alias)
                aliases.append(alias)
            }

            return aliases
        }

        static func normalizedSymbol(_ value: String) -> String? {
            let symbol = value.trimmingCharacters(in: .whitespacesAndNewlines)
            return symbol.isEmpty ? nil : symbol
        }
    }

    static func normalizedPunctuationDictionaryPrefix(_ value: String) -> String? {
        let prefix = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
        return prefix.isEmpty ? nil : prefix
    }

    var punctuationDictionaryPrefix: String {
        get {
            guard let stored = self.defaults.string(forKey: Keys.punctuationDictionaryPrefix),
                  let normalized = Self.normalizedPunctuationDictionaryPrefix(stored)
            else {
                return Self.defaultPunctuationDictionaryPrefix
            }
            return normalized
        }
        set {
            objectWillChange.send()
            self.defaults.set(
                Self.normalizedPunctuationDictionaryPrefix(newValue) ?? Self.defaultPunctuationDictionaryPrefix,
                forKey: Keys.punctuationDictionaryPrefix
            )
        }
    }

    var punctuationDictionaryRules: [PunctuationDictionaryRule] {
        get {
            guard let data = defaults.data(forKey: Keys.punctuationDictionaryRules),
                  let decoded = try? JSONDecoder().decode([PunctuationDictionaryRule].self, from: data)
            else {
                return Self.defaultPunctuationDictionaryRules
            }
            return decoded.compactMap { rule in
                let aliases = PunctuationDictionaryRule.normalizedAliases(rule.aliases)
                guard !aliases.isEmpty,
                      let symbol = PunctuationDictionaryRule.normalizedSymbol(rule.symbol)
                else {
                    return nil
                }
                return PunctuationDictionaryRule(id: rule.id, aliases: aliases, symbol: symbol)
            }
        }
        set {
            objectWillChange.send()
            let normalizedRules = newValue.compactMap { rule -> PunctuationDictionaryRule? in
                let aliases = PunctuationDictionaryRule.normalizedAliases(rule.aliases)
                guard !aliases.isEmpty,
                      let symbol = PunctuationDictionaryRule.normalizedSymbol(rule.symbol)
                else {
                    return nil
                }
                return PunctuationDictionaryRule(id: rule.id, aliases: aliases, symbol: symbol)
            }
            if let encoded = try? JSONEncoder().encode(normalizedRules) {
                self.defaults.set(encoded, forKey: Keys.punctuationDictionaryRules)
            }
        }
    }

    var spokenFormattingActionRules: [SpokenFormattingActionRule] {
        get {
            guard let data = defaults.data(forKey: Keys.spokenFormattingActionRules),
                  let decoded = try? JSONDecoder().decode([SpokenFormattingActionRule].self, from: data)
            else {
                return Self.defaultSpokenFormattingActionRules
            }

            var rulesByAction: [SpokenFormattingAction: SpokenFormattingActionRule] = [:]
            for rule in decoded where rulesByAction[rule.action] == nil {
                rulesByAction[rule.action] = rule
            }
            let orderedRules = SpokenFormattingAction.allCases.map { action in
                guard let rule = rulesByAction[action] else {
                    return Self.defaultSpokenFormattingActionRules.first { $0.action == action }
                        ?? SpokenFormattingActionRule(action: action, aliases: [], isEnabled: false)
                }
                return SpokenFormattingActionRule(
                    action: action,
                    aliases: rule.aliases,
                    isEnabled: rule.isEnabled
                )
            }
            return self.removingDuplicateSpokenFormattingAliases(from: orderedRules)
        }
        set {
            objectWillChange.send()
            var rulesByAction: [SpokenFormattingAction: SpokenFormattingActionRule] = [:]
            for rule in newValue where rulesByAction[rule.action] == nil {
                rulesByAction[rule.action] = rule
            }
            let orderedRules = SpokenFormattingAction.allCases.map { action in
                guard let rule = rulesByAction[action] else {
                    return SpokenFormattingActionRule(action: action, aliases: [], isEnabled: false)
                }
                return SpokenFormattingActionRule(
                    action: action,
                    aliases: rule.aliases,
                    isEnabled: rule.isEnabled
                )
            }
            let normalizedRules = self.removingDuplicateSpokenFormattingAliases(from: orderedRules)
            if let encoded = try? JSONEncoder().encode(normalizedRules) {
                self.defaults.set(encoded, forKey: Keys.spokenFormattingActionRules)
            }
        }
    }

    private func removingDuplicateSpokenFormattingAliases(
        from rules: [SpokenFormattingActionRule]
    ) -> [SpokenFormattingActionRule] {
        var claimedAliases = Set(self.punctuationDictionaryRules.flatMap(\.aliases))
        return rules.map { rule in
            let uniqueAliases = rule.aliases.filter { claimedAliases.insert($0).inserted }
            return SpokenFormattingActionRule(
                action: rule.action,
                aliases: uniqueAliases,
                isEnabled: rule.isEnabled
            )
        }
    }

    // MARK: - GAAV Mode

    /// Legacy combined GAAV setting. New behavior uses the split formatting toggles below.
    var gaavModeEnabled: Bool {
        get { self.defaults.object(forKey: Keys.gaavModeEnabled) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.gaavModeEnabled)
        }
    }

    var gaavLowercaseFirstLetterEnabled: Bool {
        get {
            self.defaults.object(forKey: Keys.gaavLowercaseFirstLetterEnabled) as? Bool ?? self.gaavModeEnabled
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.gaavLowercaseFirstLetterEnabled)
        }
    }

    var gaavRemoveTrailingPeriodEnabled: Bool {
        get {
            self.defaults.object(forKey: Keys.gaavRemoveTrailingPeriodEnabled) as? Bool ?? self.gaavModeEnabled
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.gaavRemoveTrailingPeriodEnabled)
        }
    }

    // MARK: - Continuous Dictation Mode

    /// Legacy combined continuous-dictation setting. New behavior uses the split toggles below.
    var continuousDictationModeEnabled: Bool {
        get { self.defaults.object(forKey: Keys.continuousDictationModeEnabled) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.continuousDictationModeEnabled)
        }
    }

    var continuousDictationSpacingEnabled: Bool {
        get {
            self.defaults.object(forKey: Keys.continuousDictationSpacingEnabled) as? Bool ?? self.continuousDictationModeEnabled
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.continuousDictationSpacingEnabled)
        }
    }

    var contextAwareCapitalizationEnabled: Bool {
        get {
            self.defaults.object(forKey: Keys.contextAwareCapitalizationEnabled) as? Bool ?? self.continuousDictationModeEnabled
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.contextAwareCapitalizationEnabled)
        }
    }

    var needsDictationFormattingContext: Bool {
        self.continuousDictationSpacingEnabled || self.contextAwareCapitalizationEnabled
    }

    // MARK: - Dictation Screen Context

    /// One opt-in for cursor and window text, with local OCR when needed.
    var dictationScreenContextEnabled: Bool {
        get { self.defaults.bool(forKey: Keys.dictationScreenContextEnabled) }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.dictationScreenContextEnabled)
        }
    }

    // MARK: - Media Playback Control

    /// When enabled, automatically pauses system media playback when transcription starts.
    /// Only resumes if FluidVoice was the one that paused it.
    var pauseMediaDuringTranscription: Bool {
        get { self.defaults.object(forKey: Keys.pauseMediaDuringTranscription) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.pauseMediaDuringTranscription)
        }
    }

    // MARK: - Custom Dictionary

    /// A custom dictionary entry that maps multiple misheard/alternate spellings to a correct replacement.
    /// For example: ["fluid voice", "fluid boys"] -> "FluidVoice"
    nonisolated struct CustomDictionaryEntry: Codable, Identifiable, Hashable, Sendable {
        let id: UUID
        /// Words/phrases to look for (case-insensitive matching)
        var triggers: [String]
        /// The correct replacement text
        var replacement: String

        init(triggers: [String], replacement: String) {
            self.id = UUID()
            self.triggers = triggers.map { $0.trimmingCharacters(in: .whitespaces).lowercased() }
            self.replacement = replacement
        }

        init(id: UUID, triggers: [String], replacement: String) {
            self.id = id
            self.triggers = triggers.map { $0.trimmingCharacters(in: .whitespaces).lowercased() }
            self.replacement = replacement
        }

        /// Trims padding around visible replacement text while preserving an intentional
        /// all-whitespace payload such as a newline, space, or tab.
        static func sanitizedReplacement(_ text: String) -> String {
            let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
            return trimmed.isEmpty ? text : trimmed
        }
    }

    var vocabularyBoostingEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.vocabularyBoostingEnabled)
            return value as? Bool ?? false
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.vocabularyBoostingEnabled)
            NotificationCenter.default.post(name: .parakeetVocabularyDidChange, object: nil)
        }
    }

    enum AutomaticDictionarySuggestionFrequency: Int, Codable, CaseIterable, Identifiable {
        case first = 1
        case second = 2
        case third = 3

        var id: Int { self.rawValue }

        var displayName: String {
            switch self {
            case .first: "1 correction"
            case .second: "2 corrections"
            case .third: "3 corrections"
            }
        }
    }

    var automaticDictionaryLearningEnabled: Bool {
        get { self.defaults.object(forKey: Keys.automaticDictionaryLearningEnabled) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.automaticDictionaryLearningEnabled)
        }
    }

    var automaticDictionarySuggestionFrequency: AutomaticDictionarySuggestionFrequency {
        get {
            let stored = self.defaults.integer(forKey: Keys.automaticDictionarySuggestionFrequency)
            return AutomaticDictionarySuggestionFrequency(rawValue: stored) ?? .first
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.automaticDictionarySuggestionFrequency)
        }
    }

    var pronunciationMatchingEnabled: Bool {
        get { self.defaults.object(forKey: Keys.pronunciationMatchingEnabled) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.pronunciationMatchingEnabled)
        }
    }

    /// Custom dictionary entries for word replacement
    var customDictionaryEntries: [CustomDictionaryEntry] {
        get {
            guard let data = defaults.data(forKey: Keys.customDictionaryEntries),
                  let decoded = try? JSONDecoder().decode([CustomDictionaryEntry].self, from: data)
            else {
                return []
            }
            return decoded
        }
        set {
            objectWillChange.send()
            if let encoded = try? JSONEncoder().encode(newValue) {
                self.defaults.set(encoded, forKey: Keys.customDictionaryEntries)
            }
        }
    }

    // MARK: - Speech Model (Unified ASR Model Selection)

    /// Unified speech recognition model selection.
    /// Replaces the old TranscriptionProviderOption + WhisperModelSize dual-setting.
    enum SpeechModel: String, CaseIterable, Identifiable, Codable {
        /// Temporarily disabled in UI/runtime while Parakeet word boosting work is prioritized.
        /// Flip to `true` in a future round to re-enable Qwen without deleting implementation.
        static let qwenPreviewEnabled = false

        // MARK: - FluidAudio Models (Apple Silicon Only)

        case parakeetTDT = "parakeet-tdt"
        case parakeetTDTv2 = "parakeet-tdt-v2"
        case fluidParakeetMini = "fluid-parakeet-mini"
        case fluidParakeetPico = "fluid-parakeet-pico"
        case fluidParakeetPro = "fluid-parakeet-pro"
        case parakeetRealtime = "parakeet-realtime"
        case qwen3Asr = "qwen3-asr"
        case cohereTranscribeSixBit = "cohere-transcribe-6bit"
        case nemotronOffline = "nemotron-3.5-offline"
        case nemotronStreaming = "nemotron-3.5-streaming"
        case nemotronStreaming320 = "nemotron-3.5-streaming-320"

        // MARK: - Apple Native

        case appleSpeech = "apple-speech"
        case appleSpeechAnalyzer = "apple-speech-analyzer"

        // MARK: - Whisper Models (Universal)

        case whisperTiny = "whisper-tiny"
        case whisperBase = "whisper-base"
        case whisperSmall = "whisper-small"
        case whisperMedium = "whisper-medium"
        case whisperLargeTurbo = "whisper-large-turbo"
        case whisperLarge = "whisper-large"

        // MARK: - Other transcribe.cpp Models

        case qwen3Asr17B = "qwen3-asr-1.7b"

        var parakeetDescriptor: ParakeetSpeechModelCatalog.Descriptor? {
            ParakeetSpeechModelCatalog.descriptor(forModelID: self.rawValue)
        }

        /// Relative product ratings for display and sorting, not benchmark accuracy.
        var hasPerformanceRatings: Bool {
            guard let descriptor = self.parakeetDescriptor else { return true }
            return descriptor.performanceRatings != nil
        }

        var id: String {
            rawValue
        }

        // MARK: - Display Properties

        var displayName: String {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.displayName ?? self.rawValue
            case .parakeetRealtime: return "Parakeet Flash (Beta)"
            case .qwen3Asr: return "Qwen3 ASR (Beta)"
            case .cohereTranscribeSixBit: return "Cohere Transcribe"
            case .nemotronOffline: return "Nemotron 3.5 Multilingual"
            case .nemotronStreaming: return "Nemotron Speech 3.5 - Ultra Fast Low Latency"
            case .nemotronStreaming320: return "Nemotron Speech 3.5 - Ultra Fast Low Latency"
            case .appleSpeech: return "Apple ASR Legacy"
            case .appleSpeechAnalyzer: return "Apple Speech - macOS 26+"
            case .whisperTiny: return "Whisper Tiny"
            case .whisperBase: return "Whisper Base"
            case .whisperSmall: return "Whisper Small"
            case .whisperMedium: return "Whisper Medium"
            case .whisperLargeTurbo: return "Whisper Large Turbo"
            case .whisperLarge: return "Whisper Large"
            case .qwen3Asr17B: return "Qwen3 ASR 1.7B"
            }
        }

        var languageSupport: String {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.languageSupport ?? "English Only"
            case .parakeetRealtime: return "English Only (Live Streaming)"
            case .qwen3Asr, .qwen3Asr17B: return "30 Languages"
            case .cohereTranscribeSixBit: return "14 Languages (Select Manually)"
            case .nemotronOffline, .nemotronStreaming, .nemotronStreaming320: return "Around 40 Languages"
            case .appleSpeech: return "System Languages"
            case .appleSpeechAnalyzer: return "EN, ES, FR, DE, IT, JA, KO, PT, ZH"
            case .whisperTiny, .whisperBase, .whisperSmall, .whisperMedium, .whisperLargeTurbo, .whisperLarge:
                return "99 Languages"
            }
        }

        var downloadSize: String {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.downloadSize ?? ""
            case .parakeetRealtime: return "~428.4 MiB"
            case .qwen3Asr: return "~2.0 GiB"
            case .cohereTranscribeSixBit: return "~1.54 GiB"
            case .nemotronOffline: return "~530.8 MiB"
            case .nemotronStreaming: return "~668.2 MiB"
            case .nemotronStreaming320: return "~668.2 MiB"
            case .appleSpeech: return "Built-in"
            case .appleSpeechAnalyzer: return "Built-in"
            case .whisperTiny: return "~43.9 MiB"
            case .whisperBase: return "~81.0 MiB"
            case .whisperSmall: return "~257.3 MiB"
            case .whisperMedium: return "~793.0 MiB"
            case .whisperLargeTurbo: return "~845.3 MiB"
            case .whisperLarge: return "~1.55 GiB"
            case .qwen3Asr17B: return "~2.03 GiB"
            }
        }

        var expectedDownloadBytes: Int64 {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.expectedDownloadBytes ?? 0
            case .parakeetRealtime: return 449_190_189
            case .qwen3Asr: return 2000 * 1024 * 1024
            case .cohereTranscribeSixBit: return 1_650_748_785
            case .nemotronOffline: return 556_552_620
            case .nemotronStreaming, .nemotronStreaming320: return 700_685_415
            case .whisperTiny: return 45_981_088
            case .whisperBase: return 84_962_880
            case .whisperSmall: return 269_751_136
            case .whisperMedium: return 831_538_144
            case .whisperLargeTurbo: return 886_381_728
            case .whisperLarge: return 1_668_741_440
            case .qwen3Asr17B: return 2_185_030_624
            case .appleSpeech, .appleSpeechAnalyzer: return 0
            }
        }

        var requiresAppleSilicon: Bool {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro, .parakeetRealtime, .qwen3Asr, .qwen3Asr17B, .cohereTranscribeSixBit, .nemotronOffline, .nemotronStreaming, .nemotronStreaming320: return true
            default: return false
            }
        }

        var isWhisperModel: Bool {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro, .parakeetRealtime, .qwen3Asr, .qwen3Asr17B, .cohereTranscribeSixBit, .nemotronOffline, .nemotronStreaming, .nemotronStreaming320, .appleSpeech,
                 .appleSpeechAnalyzer: return false
            default: return true
            }
        }

        /// The GGUF filename for transcribe.cpp Whisper models.
        var whisperModelFile: String? {
            switch self {
            case .whisperTiny: return "whisper-tiny-Q8_0.gguf"
            case .whisperBase: return "whisper-base-Q8_0.gguf"
            case .whisperSmall: return "whisper-small-Q8_0.gguf"
            case .whisperMedium: return "whisper-medium-Q8_0.gguf"
            case .whisperLargeTurbo: return "whisper-large-v3-turbo-Q8_0.gguf"
            case .whisperLarge: return "whisper-large-v3-Q8_0.gguf"
            case .qwen3Asr17B: return "Qwen3-ASR-1.7B-Q8_0.gguf"
            default: return nil
            }
        }

        var legacyWhisperModelFile: String? {
            switch self {
            case .whisperTiny: return "ggml-tiny.bin"
            case .whisperBase: return "ggml-base.bin"
            case .whisperSmall: return "ggml-small.bin"
            case .whisperMedium: return "ggml-medium.bin"
            case .whisperLargeTurbo: return "ggml-large-v3-turbo.bin"
            case .whisperLarge: return "ggml-large-v3.bin"
            default: return nil
            }
        }

        static let legacyWhisperModelFiles: Set<String> = [
            "ggml-tiny.bin",
            "ggml-base.bin",
            "ggml-small.bin",
            "ggml-medium.bin",
            "ggml-large-v3-turbo.bin",
            "ggml-large-v3.bin",
        ]

        /// The short model name for whisper.cpp internal usage
        var whisperModelName: String? {
            switch self {
            case .whisperTiny: return "tiny"
            case .whisperBase: return "base"
            case .whisperSmall: return "small"
            case .whisperMedium: return "medium"
            case .whisperLargeTurbo: return "large-v3-turbo"
            case .whisperLarge: return "large-v3"
            default: return nil
            }
        }

        // MARK: - Architecture Filtering

        /// Requires macOS 26 (Tahoe) or later
        var requiresMacOS26: Bool {
            switch self {
            case .appleSpeechAnalyzer: return true
            default: return false
            }
        }

        /// Requires macOS 15 or later.
        var requiresMacOS15: Bool {
            switch self {
            case .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro, .qwen3Asr, .cohereTranscribeSixBit: return true
            default: return false
            }
        }

        /// Returns models available for the current Mac's architecture and OS
        static var availableModels: [SpeechModel] {
            allCases.filter { model in
                if model == .whisperLargeTurbo, !CPUArchitecture.isAppleSilicon {
                    return false
                }
                if model == .whisperLarge, !CPUArchitecture.isAppleSilicon {
                    return false
                }
                if model == .qwen3Asr, !Self.qwenPreviewEnabled {
                    return false
                }
                if model == .nemotronStreaming320 {
                    return false
                }
                // Filter by Apple Silicon requirement
                if model.requiresAppleSilicon, !CPUArchitecture.isAppleSilicon {
                    return false
                }
                // Filter by macOS 15 requirement
                if model.requiresMacOS15, #unavailable(macOS 15.0) {
                    return false
                }
                // Filter by macOS 26 requirement
                if model.requiresMacOS26 {
                    if #available(macOS 26.0, *) {
                        return true
                    } else {
                        return false
                    }
                }
                return true
            }
        }

        /// Default model for the current architecture
        static var defaultModel: SpeechModel {
            CPUArchitecture.isAppleSilicon ? .parakeetTDT : .whisperBase
        }

        // MARK: - UI Card Metadata

        /// Human-readable marketing name for the card UI
        var humanReadableName: String {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.humanReadableName ?? self.rawValue
            case .parakeetRealtime: return "Flash Dictation"
            case .qwen3Asr: return "Qwen3 - Multilingual"
            case .cohereTranscribeSixBit: return "Cohere - High Accuracy"
            case .nemotronOffline: return "Nemotron 3.5 Multilingual"
            case .nemotronStreaming: return "Nemotron Speech 3.5 - Ultra Fast Low Latency"
            case .nemotronStreaming320: return "Nemotron Speech 3.5 - Ultra Fast Low Latency"
            case .appleSpeech: return "Apple ASR Legacy"
            case .appleSpeechAnalyzer: return "Apple Speech - macOS 26+"
            case .whisperTiny: return "Fast & Light"
            case .whisperBase: return "Standard Choice"
            case .whisperSmall: return "Balanced Speed & Accuracy"
            case .whisperMedium: return "Medium Quality"
            case .whisperLargeTurbo: return "Higher Quality but Faster"
            case .whisperLarge: return "Maximum Accuracy"
            case .qwen3Asr17B: return "Qwen3 - Multilingual 1.7B"
            }
        }

        /// One-line description for the card UI
        var cardDescription: String {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
                return self.parakeetDescriptor?.cardDescription ?? ""
            case .parakeetRealtime:
                return "English-only streaming local dictation with low-latency partial text and end-of-utterance detection."
            case .qwen3Asr:
                return "Qwen3 multilingual ASR via FluidAudio. Higher quality, heavier memory footprint."
            case .cohereTranscribeSixBit:
                return "High-accuracy multilingual transcription. Select the language manually before dictation for best results."
            case .nemotronOffline:
                return "Slower but more accurate NVIDIA Nemotron 3.5 transcription. Supports 40 language-locales with auto or manual language selection."
            case .nemotronStreaming:
                return "NVIDIA Nemotron 3.5 streaming-capable transcription. Supports 40 language-locales with auto or manual language selection."
            case .nemotronStreaming320:
                return "NVIDIA Nemotron 3.5 streaming-capable transcription. Supports 40 language-locales with auto or manual language selection."
            case .appleSpeech:
                return "Built-in macOS speech recognition. No model download required."
            case .appleSpeechAnalyzer:
                return "Advanced and modern on-device recognition for newer macOS devices."
            case .whisperTiny:
                return "Minimal resource usage. Best for older Macs or battery life."
            case .whisperBase:
                return "Good balance of speed and accuracy. Works on any Mac."
            case .whisperSmall:
                return "Better accuracy than Base. Moderate resource usage."
            case .whisperMedium:
                return "High accuracy for demanding tasks. Requires more memory."
            case .whisperLargeTurbo:
                return "Near-maximum accuracy with optimized speed."
            case .whisperLarge:
                return "Best possible accuracy. Large download and memory usage."
            case .qwen3Asr17B:
                return "Automatically detects 30 languages. Transcribes on your Mac after you stop recording."
            }
        }

        /// Minimum recommended RAM in GB for this model to run safely
        var requiredMemoryGB: Double {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro, .parakeetRealtime:
                return 4.0
            case .qwen3Asr:
                return 8.0
            case .cohereTranscribeSixBit:
                return 8.0
            case .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
                return 8.0
            case .appleSpeech, .appleSpeechAnalyzer:
                return 2.0 // Built-in, minimal overhead
            case .whisperTiny:
                return 2.0
            case .whisperBase:
                return 3.0
            case .whisperSmall:
                return 4.0
            case .whisperMedium:
                return 5.0
            case .whisperLargeTurbo:
                return 6.0
            case .whisperLarge:
                return 8.0
            case .qwen3Asr17B:
                return 6.0
            }
        }

        /// Warning text for models with high memory requirements, nil if no warning needed
        var memoryWarning: String? {
            switch self {
            case .qwen3Asr:
                return "⚠️ Requires 8GB+ RAM. Best on newer Apple Silicon Macs."
            case .whisperLarge:
                return "⚠️ Requires 10GB+ RAM. May crash on systems with limited memory."
            case .whisperLargeTurbo:
                return "⚠️ Requires 8GB+ RAM. May be unstable on some systems."
            case .whisperMedium:
                return "Requires 6GB+ RAM for stable operation."
            default:
                return nil
            }
        }

        /// Speed rating (1-5, higher is faster)
        var speedRating: Int {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.performanceRatings?.speedRating ?? 0
            case .parakeetRealtime: return 5
            case .qwen3Asr: return 3
            case .cohereTranscribeSixBit: return 3
            case .nemotronOffline: return 3
            case .nemotronStreaming, .nemotronStreaming320: return 4
            case .appleSpeech: return 4
            case .appleSpeechAnalyzer: return 4
            case .whisperTiny: return 4
            case .whisperBase: return 4
            case .whisperSmall: return 3
            case .whisperMedium: return 2
            case .whisperLargeTurbo: return 3
            case .whisperLarge: return 1
            case .qwen3Asr17B: return 3
            }
        }

        /// Accuracy rating (1-5, higher is more accurate)
        var accuracyRating: Int {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.performanceRatings?.accuracyRating ?? 0
            case .parakeetRealtime: return 4
            case .qwen3Asr: return 4
            case .cohereTranscribeSixBit: return 5
            case .nemotronOffline: return 5
            case .nemotronStreaming, .nemotronStreaming320: return 4
            case .appleSpeech: return 4
            case .appleSpeechAnalyzer: return 4
            case .whisperTiny: return 2
            case .whisperBase: return 3
            case .whisperSmall: return 4
            case .whisperMedium: return 4
            case .whisperLargeTurbo: return 5
            case .whisperLarge: return 5
            case .qwen3Asr17B: return 5
            }
        }

        /// Exact speed percentage (0.0 - 1.0) for the liquid bars
        var speedPercent: Double {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.performanceRatings?.speedPercent ?? 0
            case .parakeetRealtime: return 1.0
            case .qwen3Asr: return 0.45
            case .cohereTranscribeSixBit: return 0.85
            case .nemotronOffline: return 0.85
            case .nemotronStreaming, .nemotronStreaming320: return 1.0
            case .appleSpeech: return 0.60
            case .appleSpeechAnalyzer: return 0.85
            case .whisperTiny: return 0.90
            case .whisperBase: return 0.80
            case .whisperSmall: return 0.60
            case .whisperMedium: return 0.40
            case .whisperLargeTurbo: return 0.65
            case .whisperLarge: return 0.20
            case .qwen3Asr17B: return 0.50
            }
        }

        /// Exact accuracy percentage (0.0 - 1.0) for the liquid bars
        var accuracyPercent: Double {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return self.parakeetDescriptor?.performanceRatings?.accuracyPercent ?? 0
            case .parakeetRealtime: return 0.75
            case .qwen3Asr: return 0.90
            case .cohereTranscribeSixBit: return 0.98
            case .nemotronOffline: return 0.90
            case .nemotronStreaming, .nemotronStreaming320: return 0.85
            case .appleSpeech: return 0.60
            case .appleSpeechAnalyzer: return 0.80
            case .whisperTiny: return 0.40
            case .whisperBase: return 0.60
            case .whisperSmall: return 0.70
            case .whisperMedium: return 0.80
            case .whisperLargeTurbo: return 0.95
            case .whisperLarge: return 1.00
            case .qwen3Asr17B: return 1.00
            }
        }

        /// Optional badge text for the card (e.g., "FluidVoice Pick")
        var badgeText: String? {
            switch self {
            case .parakeetTDT: return "FluidVoice Pick"
            case .parakeetTDTv2: return "FluidVoice Pick"
            case .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro: return "New"
            case .parakeetRealtime: return "Beta"
            case .qwen3Asr: return "Beta"
            case .qwen3Asr17B: return nil
            case .cohereTranscribeSixBit: return "New"
            case .nemotronOffline, .nemotronStreaming, .nemotronStreaming320: return "New + Beta"
            case .appleSpeechAnalyzer: return "New"
            default: return nil
            }
        }

        /// Optimization level for Apple Silicon (for display)
        var appleSiliconOptimized: Bool {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro, .parakeetRealtime, .qwen3Asr, .cohereTranscribeSixBit, .nemotronOffline, .nemotronStreaming, .nemotronStreaming320, .appleSpeechAnalyzer:
                return true
            default:
                return false
            }
        }

        /// Whether this model supports real-time streaming/chunk processing.
        /// Large Whisper models are too slow for streaming, so they only do final transcription on stop.
        var supportsStreaming: Bool {
            switch self {
            case .qwen3Asr, .qwen3Asr17B, .whisperMedium, .whisperLargeTurbo, .whisperLarge:
                return false // Too slow for real-time chunk processing
            default:
                return true // All other models support streaming
            }
        }

        var supportsPronunciationMatching: Bool {
            #if arch(arm64)
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
                return true
            default:
                return false
            }
            #else
            return false
            #endif
        }

        /// Preview update cadence for real-time transcription.
        /// Models without native incremental decoding should use a slower interval.
        var streamingPreviewIntervalSeconds: Double {
            switch self {
            case .parakeetRealtime:
                return 0.2
            case .nemotronStreaming, .nemotronStreaming320:
                return 0.32
            case .cohereTranscribeSixBit:
                return 1.0
            default:
                return 0.6
            }
        }

        /// Minimum audio required before attempting a preview decode.
        /// Cohere performs better with a slightly larger prefix than the default 1 second.
        var minimumStreamingPreviewSeconds: Double {
            switch self {
            case .parakeetRealtime:
                return 0.2
            case .nemotronStreaming, .nemotronStreaming320:
                return 0.64
            case .cohereTranscribeSixBit:
                return 1.5
            default:
                return 1.0
            }
        }

        /// Provider category for tab grouping
        enum Provider: String, CaseIterable {
            case nvidia = "NVIDIA"
            case apple = "Apple"
            case openai = "OpenAI"
            case qwen = "Qwen"
            case cohere = "Cohere"
        }

        /// Which provider this model belongs to
        var provider: Provider {
            switch self {
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro, .parakeetRealtime, .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
                return .nvidia
            case .appleSpeech, .appleSpeechAnalyzer:
                return .apple
            case .qwen3Asr, .qwen3Asr17B:
                return .qwen
            case .cohereTranscribeSixBit:
                return .cohere
            case .whisperTiny, .whisperBase, .whisperSmall, .whisperMedium, .whisperLargeTurbo, .whisperLarge:
                return .openai
            }
        }

        /// Get models filtered by provider
        static func models(for provider: Provider) -> [SpeechModel] {
            self.availableModels.filter { $0.provider == provider }
        }

        /// Whether this model is built-in or already downloaded on disk
        var isInstalled: Bool {
            switch self {
            case .appleSpeech, .appleSpeechAnalyzer:
                return true
            case .parakeetTDT, .parakeetTDTv2, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
                #if canImport(FluidAudio)
                guard let descriptor = self.parakeetDescriptor else { return false }
                return Self.parakeetModelsExist(descriptor: descriptor)
                #else
                return false
                #endif
            case .parakeetRealtime:
                #if canImport(FluidAudio)
                return Self.parakeetRealtimeModelsExist()
                #else
                return false
                #endif
            case .qwen3Asr:
                #if canImport(FluidAudio) && ENABLE_QWEN
                if #available(macOS 15.0, *) {
                    return Qwen3AsrModels.modelsExist(at: Qwen3AsrModels.defaultCacheDirectory())
                }
                return false
                #else
                return false
                #endif
            case .cohereTranscribeSixBit:
                guard
                    let spec = self.externalCoreMLSpec,
                    let directory = SettingsStore.shared.externalCoreMLArtifactsDirectory(for: self)
                else {
                    return false
                }
                return spec.validatesInstalledArtifacts(at: directory)
            case .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
                let hint: String
                switch self {
                case .nemotronOffline:
                    hint = "nemotron-3.5-asr-offline-6bit-CoreML"
                default:
                    hint = "nemotron-3.5-asr-streaming320-int8-CoreML"
                }
                let directory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
                    .appendingPathComponent(hint, isDirectory: true)
                #if arch(arm64)
                return directory.map { NemotronProvider.artifactsAreComplete(at: $0) } ?? false
                #else
                return false
                #endif
            default:
                // Whisper models
                guard let whisperFile = self.whisperModelFile else { return false }
                let directory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
                    .appendingPathComponent("WhisperModels")
                let modelURL = directory?.appendingPathComponent(whisperFile)
                guard
                    let modelURL,
                    let attributes = try? FileManager.default.attributesOfItem(atPath: modelURL.path),
                    let size = attributes[.size] as? NSNumber,
                    size.int64Value > 0
                else {
                    return false
                }
                return size.int64Value == self.expectedDownloadBytes
            }
        }

        #if canImport(FluidAudio)
        private static func parakeetModelsExist(descriptor: ParakeetSpeechModelCatalog.Descriptor) -> Bool {
            let modelsDirectory = AsrModels.defaultCacheDirectory().deletingLastPathComponent()
            let directory = descriptor.cacheDirectory(in: modelsDirectory)
            return descriptor.artifactsAreComplete(at: directory)
        }

        private static func parakeetRealtimeModelsExist() -> Bool {
            let modelsDirectory = AsrModels.defaultCacheDirectory().deletingLastPathComponent()
            let modelDirectory = modelsDirectory
                .appendingPathComponent("parakeet-eou-streaming", isDirectory: true)
                .appendingPathComponent(Repo.parakeetEou160.folderName, isDirectory: true)

            return ModelNames.ParakeetEOU.requiredModels.allSatisfy { modelName in
                let artifact = modelDirectory.appendingPathComponent(modelName)
                return HuggingFaceModelDownloader.artifactIsComplete(
                    at: artifact,
                    isDirectory: modelName.hasSuffix(".mlmodelc")
                )
            }
        }
        #endif

        /// Brand/provider name for the model (NVIDIA, Apple, OpenAI)
        var brandName: String {
            switch self {
            case .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
                return "FluidVoice"
            case .parakeetTDT, .parakeetTDTv2, .parakeetRealtime, .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
                return "NVIDIA"
            case .qwen3Asr, .qwen3Asr17B:
                return "Qwen"
            case .cohereTranscribeSixBit:
                return "Cohere"
            case .appleSpeech, .appleSpeechAnalyzer:
                return "Apple"
            case .whisperTiny, .whisperBase, .whisperSmall, .whisperMedium, .whisperLargeTurbo, .whisperLarge:
                return "OpenAI"
            }
        }

        /// Whether this model uses Apple's SF Symbol for branding (apple.logo)
        var usesAppleLogo: Bool {
            switch self {
            case .appleSpeech, .appleSpeechAnalyzer: return true
            default: return false
            }
        }

        /// Brand color for the provider badge
        var brandColorHex: String {
            switch self {
            case .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
                return "#1A75FF" // FluidBrandColors.blue
            case .parakeetTDT, .parakeetTDTv2, .parakeetRealtime, .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
                return "#76B900"
            case .qwen3Asr, .qwen3Asr17B:
                return "#E67E22"
            case .cohereTranscribeSixBit:
                return "#FA6B3C"
            case .appleSpeech, .appleSpeechAnalyzer:
                return "#A2AAAD" // Apple Gray
            case .whisperTiny, .whisperBase, .whisperSmall, .whisperMedium, .whisperLargeTurbo, .whisperLarge:
                return "#10A37F" // OpenAI Teal
            }
        }
    }

    // MARK: - Transcription Provider (ASR)

    /// Available transcription providers
    enum TranscriptionProviderOption: String, CaseIterable, Identifiable {
        case auto
        case fluidAudio
        case whisper

        var id: String {
            rawValue
        }

        var displayName: String {
            switch self {
            case .auto: return "Automatic (Recommended)"
            case .fluidAudio: return "FluidAudio (Apple Silicon)"
            case .whisper: return "Whisper (Intel/Universal)"
            }
        }

        var description: String {
            switch self {
            case .auto: return "Uses FluidAudio on Apple Silicon, Whisper on Intel"
            case .fluidAudio: return "Fast CoreML-based transcription optimized for M-series chips"
            case .whisper: return "whisper.cpp - CPU-based, works on any Mac"
            }
        }
    }

    /// Selected transcription provider - defaults to "auto" which picks based on architecture
    var selectedTranscriptionProvider: TranscriptionProviderOption {
        get {
            guard let rawValue = defaults.string(forKey: Keys.selectedTranscriptionProvider),
                  let option = TranscriptionProviderOption(rawValue: rawValue)
            else {
                return .auto
            }
            return option
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.selectedTranscriptionProvider)
        }
    }

    /// Selected Whisper model size - defaults to "base"
    var whisperModelSize: WhisperModelSize {
        get {
            guard let rawValue = defaults.string(forKey: Keys.whisperModelSize),
                  let size = WhisperModelSize(rawValue: rawValue)
            else {
                return .base
            }
            return size
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.whisperModelSize)
        }
    }
}

// swiftlint:enable type_body_length

private extension SettingsStore {
    /// Keys
    enum Keys {
        static let enableAIProcessing = "EnableAIProcessing"
        static let showMainWindowAtLoginLaunch = "ShowMainWindowAtLoginLaunch"
        static let fileTranscriptionSpeakerLabelsEnabled = "FileTranscriptionSpeakerLabelsEnabled"
        static let fileTranscriptionExpectedSpeakerCount = "FileTranscriptionExpectedSpeakerCount"
        static let dictationPromptOff = "DictationPromptOff"
        static let enableDebugLogs = "EnableDebugLogs"
        static let availableAIModels = "AvailableAIModels"
        static let availableModelsByProvider = "AvailableModelsByProvider"
        static let selectedAIModel = "SelectedAIModel"
        static let selectedModelByProvider = "SelectedModelByProvider"
        static let selectedProviderID = "SelectedProviderID"
        static let privateAIPrefixKVCacheEnabled = "PrivateAIProviderPrefixKVCacheEnabled"
        static let privateAIBoostEnabled = "PrivateAIProviderBoostEnabled"
        static let privateAIIdleUnloadMinutes = "PrivateAIProviderIdleUnloadMinutes"
        static let privateAIIdleUnloadTestSeconds = "PrivateAIProviderIdleUnloadTestSeconds"
        static let privateAIBackendPreference = SettingsStore.privateAIBackendPreferenceDefaultsKey
        static let privateAIContextTokenLimit = "PrivateAIProviderContextTokenLimit"
        static let privateAIContextDefaultMigratedTo4K = "PrivateAIProviderContextDefaultMigratedTo4K"
        static let providerAPIKeys = "ProviderAPIKeys"
        static let providerAPIKeyIdentifiers = "ProviderAPIKeyIdentifiers"
        static let savedProviders = "SavedProviders"
        static let verifiedProviderFingerprints = "VerifiedProviderFingerprints"
        static let verifiedPrivateAIModelFingerprints = "VerifiedPrivateAIModelFingerprints"
        static let shareAnonymousAnalytics = "ShareAnonymousAnalytics"
        static let privateAIInterestCaptured = "PrivateAIProviderInterestCaptured"
        static let hotkeyShortcutKey = "HotkeyShortcutKey"
        static let primaryDictationShortcutsKey = "PrimaryDictationShortcuts"
        static let preferredInputDeviceUID = "PreferredInputDeviceUID"
        static let microphonePriority = "MicrophonePriority"
        static let suppressedMicrophoneUIDs = "SuppressedMicrophoneUIDs"
        static let preferredOutputDeviceUID = "PreferredOutputDeviceUID"
        static let meetingRecordingDefaults = "MeetingRecordingDefaults"
        static let meetingRecentApplication = "MeetingRecentApplication"
        static let meetingAudioRetentionPolicy = "MeetingAudioRetentionPolicy"
        static let meetingTranscriptionBackendID = "MeetingTranscriptionBackendID"
        static let fluidMeetEnabled = "FluidMeetEnabled"
        static let meetingAutoDetectEnabled = "MeetingAutoDetectEnabled"
        static let meetingAutoDetectBrowserEnabled = "MeetingAutoDetectBrowserEnabled"
        static let microphoneSelectionMode = "MicrophoneSelectionMode"
        // Keep the original persisted key so existing installs migrate in place.
        static let microphoneSelectionMigrationVersion = "AppOnlyMicrophoneSelectionMigrationVersion"
        static let showMicrophoneChangeAlerts = "ShowMicrophoneChangeAlerts"
        static let showPasteCheckAlerts = "ShowPasteCheckAlerts"
        static let visualizerNoiseThreshold = "VisualizerNoiseThreshold"
        static let launchAtStartup = "LaunchAtStartup"
        static let showInDock = "ShowInDock"
        static let accentColorOption = "AccentColorOption"
        static let themePreference = "ThemePreference"
        static let enableTranscriptionSounds = "EnableTranscriptionSounds"
        static let transcriptionStartSound = "TranscriptionStartSound"
        static let transcriptionSoundVolume = "TranscriptionSoundVolume"
        static let pressAndHoldMode = "PressAndHoldMode"
        static let hotkeyMode = "HotkeyMode"
        static let holdSpaceToMute = "HoldSpaceToMute"
        static let enableStreamingPreview = "EnableStreamingPreview"
        static let experimentalParakeetUnifiedFinalEnabled = "ExperimentalParakeetUnifiedFinalEnabled"
        static let returnDictationToStartingField = "ReturnDictationToStartingField"
        static let showHistoryPerformanceMetrics = "ShowHistoryPerformanceMetrics"
        static let skipSilentRecordingsEnabled = "SkipSilentRecordingsEnabled"
        static let enableAIStreaming = "EnableAIStreaming"
        static let copyTranscriptionToClipboard = "CopyTranscriptionToClipboard"
        static let textInsertionMode = "TextInsertionMode"
        static let spokenSendEnabled = "SpokenSendEnabled"
        static let spokenSendImmediatelyEnabled = "SpokenSendImmediatelyEnabled"
        static let spokenSendPhrase = "SpokenSendPhrase"
        static let spokenSendKey = "SpokenSendKey"
        static let reliablePasteMigrationV1 = "TextInsertionModeMigratedToReliablePasteV1"
        static let autoUpdateCheckEnabled = UpdateKeys.autoUpdateCheckEnabled
        static let showUpdatePopups = UpdateKeys.showUpdatePopups
        static let betaReleasesEnabled = UpdateKeys.betaReleasesEnabled
        static let lastUpdateCheckDate = UpdateKeys.lastUpdateCheckDate
        static let updatePromptSnoozedUntil = UpdateKeys.updatePromptSnoozedUntil
        static let snoozedUpdateVersion = UpdateKeys.snoozedUpdateVersion
        static let playgroundUsed = "PlaygroundUsed"
        static let onboardingCompleted = "OnboardingCompleted"
        static let onboardingGeneration = "OnboardingGeneration"
        static let manualOnboardingResetRequested = "ManualOnboardingResetRequested"
        static let manualOnboardingResetRequestedAt = "ManualOnboardingResetRequestedAt"
        static let onboardingCurrentStep = "OnboardingCurrentStep"
        static let onboardingAISkipped = "OnboardingAISkipped"
        static let onboardingPlaygroundValidated = "OnboardingPlaygroundValidated"
        static let onboardingPlaygroundSkipped = "OnboardingPlaygroundSkipped"
        static let onboardingSelectedLanguageID = "OnboardingSelectedLanguageID"

        // Command Mode Keys
        static let commandModeSelectedModel = "CommandModeSelectedModel"
        static let commandModeSelectedProviderID = "CommandModeSelectedProviderID"
        static let commandModeHotkeyShortcut = "CommandModeHotkeyShortcut"
        static let commandModeConfirmBeforeExecute = "CommandModeConfirmBeforeExecute"
        static let meetingRecordingHotkeyShortcut = "MeetingRecordingHotkeyShortcut"
        static let cancelRecordingHotkeyShortcut = "CancelRecordingHotkeyShortcut"
        static let pasteLastTranscriptionHotkeyShortcut = "PasteLastTranscriptionHotkeyShortcut"
        static let pasteLastTranscriptionShortcutEnabled = "PasteLastTranscriptionShortcutEnabled"
        static let commandModeLinkedToGlobal = "CommandModeLinkedToGlobal"
        static let commandModeShortcutEnabled = "CommandModeShortcutEnabled"

        // Prompt Mode Keys (Transcribe with Prompt)
        static let promptModeHotkeyShortcut = "PromptModeHotkeyShortcut"
        static let promptModeShortcutEnabled = "PromptModeShortcutEnabled"
        static let promptModeSelectedPromptID = "PromptModeSelectedPromptID"
        static let secondaryDictationPromptOff = "SecondaryDictationPromptOff"
        static let secondaryPromptShortcutRemoved = "SecondaryPromptShortcutRemoved"
        static let legacySecondaryPromptShortcutRetired = "LegacySecondaryPromptShortcutRetired"
        static let dictationPromptConfigurations = "DictationPromptConfigurations"

        // Rewrite Mode Keys
        static let rewriteModeHotkeyShortcut = "RewriteModeHotkeyShortcut"
        static let rewriteModeSelectedModel = "RewriteModeSelectedModel"
        static let rewriteModeSelectedProviderID = "RewriteModeSelectedProviderID"
        static let rewriteModeLinkedToGlobal = "RewriteModeLinkedToGlobal"

        // Model Reasoning Config Keys
        static let modelReasoningConfigs = "ModelReasoningConfigs"
        static let rewriteModeShortcutEnabled = "RewriteModeShortcutEnabled"
        static let editModeReadsScreen = "EditModeReadsScreen"
        static let showThinkingTokens = "ShowThinkingTokens"

        // Stats Keys
        static let userTypingWPM = "UserTypingWPM"
        static let saveTranscriptionHistory = "SaveTranscriptionHistory"
        static let saveAudioWithTranscriptionHistory = "SaveAudioWithTranscriptionHistory"
        static let audioHistoryBudgetGB = "AudioHistoryBudgetGB"
        static let notifyAIProcessingFailures = "NotifyAIProcessingFailures"

        // Filler Words
        static let fillerWords = "FillerWords"
        static let removeFillerWordsEnabled = "RemoveFillerWordsEnabled"
        static let autoConvertPunctuationEnabled = "AutoConvertPunctuationEnabled"
        static let literalDictationFormattingEnabled = "LiteralDictationFormattingEnabled"
        static let punctuationDictionaryPrefix = "PunctuationDictionaryPrefix"
        static let punctuationDictionaryRules = "PunctuationDictionaryRules"
        static let spokenFormattingActionRules = "SpokenFormattingActionRules"

        /// GAAV Mode (removes capitalization and trailing punctuation)
        static let gaavModeEnabled = "GAAVModeEnabled"
        static let gaavLowercaseFirstLetterEnabled = "GAAVLowercaseFirstLetterEnabled"
        static let gaavRemoveTrailingPeriodEnabled = "GAAVRemoveTrailingPeriodEnabled"

        /// Continuous Dictation Mode (append trailing space + smart caps for chaining)
        static let continuousDictationModeEnabled = "ContinuousDictationModeEnabled"
        static let continuousDictationSpacingEnabled = "ContinuousDictationSpacingEnabled"
        static let contextAwareCapitalizationEnabled = "ContextAwareCapitalizationEnabled"
        static let dictationScreenContextEnabled = "DictationScreenContextEnabled"

        // Custom Dictionary
        static let customDictionaryEntries = "CustomDictionaryEntries"
        static let automaticDictionaryLearningEnabled = "AutomaticDictionaryLearningEnabled"
        static let automaticDictionarySuggestionFrequency = "AutomaticDictionarySuggestionFrequency"
        static let vocabularyBoostingEnabled = "VocabularyBoostingEnabled"
        static let pronunciationMatchingEnabled = "PronunciationMatchingEnabled"

        // Transcription Provider (ASR)
        static let selectedTranscriptionProvider = "SelectedTranscriptionProvider"
        static let whisperModelSize = "WhisperModelSize"

        /// Unified Speech Model (replaces above two)
        static let selectedSpeechModel = "SelectedSpeechModel"
        static let selectedWhisperLanguageCode = "SelectedWhisperLanguageCode"
        static let selectedCohereLanguage = "SelectedCohereLanguage"
        static let selectedNemotronLanguage = "SelectedNemotronLanguage"
        static let selectedAppleSpeechLocaleIdentifier = "SelectedAppleSpeechLocaleIdentifier"
        static let externalCoreMLArtifactsDirectories = "ExternalCoreMLArtifactsDirectories"

        // Overlay Position
        static let overlayPosition = "OverlayPosition"
        static let notchPresentationMode = "NotchPresentationMode"
        static let overlayBottomOffset = "OverlayBottomOffset"
        static let overlayBottomOffsetMigratedTo50 = "OverlayBottomOffsetMigratedTo50"
        static let overlaySize = "OverlaySize"
        static let overlayMaterial = "OverlayMaterial"
        static let overlayGlassOpacity = "OverlayGlassOpacity"
        static let meetingOverlayPreference = "MeetingOverlayPreference"
        static let transcriptionPreviewCharLimit = "TranscriptionPreviewCharLimit"

        /// Media Playback Control
        static let pauseMediaDuringTranscription = "PauseMediaDuringTranscription"

        /// Custom Dictation Prompt
        static let customDictationPrompt = "CustomDictationPrompt"

        // Dictation Prompt Profiles (multi-prompt system)
        static let dictationPromptProfiles = "DictationPromptProfiles"
        static let appPromptBindings = "AppPromptBindings"
        static let selectedDictationPromptID = "SelectedDictationPromptID"
        static let sendCustomPromptOnly = "SendCustomPromptOnly"
        static let editPromptOff = "EditPromptOff"
        static let selectedEditPromptID = "SelectedEditPromptID"
        static let selectedWritePromptID = "SelectedWritePromptID" // legacy fallback key
        static let selectedRewritePromptID = "SelectedRewritePromptID" // legacy fallback key

        // Default Dictation Prompt Override (optional)
        // nil   => use built-in default prompt
        // ""    => use empty system prompt
        // other => use custom default prompt text
        static let defaultDictationPromptOverride = "DefaultDictationPromptOverride"
        static let defaultEditPromptOverride = "DefaultEditPromptOverride"
        static let defaultWritePromptOverride = "DefaultWritePromptOverride" // legacy fallback key
        static let defaultRewritePromptOverride = "DefaultRewritePromptOverride" // legacy fallback key

        /// Streak Settings
        static let weekendsDontBreakStreak = "WeekendsDontBreakStreak"
    }
}

extension SettingsStore {
    enum SpokenSendKey: String, CaseIterable, Identifiable, Codable {
        case enter
        case shiftEnter
        case commandEnter

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .enter:
                return "Enter"
            case .shiftEnter:
                return "Shift + Enter"
            case .commandEnter:
                return "Command + Enter"
            }
        }

        var eventFlags: CGEventFlags {
            switch self {
            case .enter:
                return []
            case .shiftEnter:
                return .maskShift
            case .commandEnter:
                return .maskCommand
            }
        }
    }

    var spokenSendEnabled: Bool {
        get { self.defaults.object(forKey: Keys.spokenSendEnabled) as? Bool ?? false }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.spokenSendEnabled)
        }
    }

    var spokenSendImmediatelyEnabled: Bool {
        get { self.defaults.object(forKey: Keys.spokenSendImmediatelyEnabled) as? Bool ?? true }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.spokenSendImmediatelyEnabled)
        }
    }

    var spokenSendPhrase: String {
        get { self.defaults.string(forKey: Keys.spokenSendPhrase) ?? "send it" }
        set {
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.spokenSendPhrase)
        }
    }

    var spokenSendKey: SpokenSendKey {
        get {
            guard let raw = self.defaults.string(forKey: Keys.spokenSendKey),
                  let key = SpokenSendKey(rawValue: raw)
            else {
                return .enter
            }
            return key
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.spokenSendKey)
        }
    }

    static func migrateTextInsertionModeToReliablePasteIfNeeded(defaults: UserDefaults) {
        guard !defaults.bool(forKey: Keys.reliablePasteMigrationV1) else { return }
        defaults.set(TextInsertionMode.reliablePaste.rawValue, forKey: Keys.textInsertionMode)
        defaults.set(true, forKey: Keys.reliablePasteMigrationV1)
    }

    enum TextInsertionMode: String, CaseIterable, Identifiable, Codable {
        case reliablePaste
        case standard

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .standard:
                return "Direct Paste"
            case .reliablePaste:
                return "Clipboard Paste (Recommended)"
            }
        }

        var description: String {
            switch self {
            case .standard:
                return "Posts text directly without changing the clipboard. Some editors may reject or truncate it."
            case .reliablePaste:
                return "Fast, compatible insertion using a temporary clipboard entry that is restored after paste."
            }
        }
    }

    var textInsertionMode: TextInsertionMode {
        get {
            guard let raw = self.defaults.string(forKey: Keys.textInsertionMode),
                  let mode = TextInsertionMode(rawValue: raw)
            else {
                return .reliablePaste
            }
            return mode
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.textInsertionMode)
        }
    }

    var betaReleasesEnabled: Bool {
        get {
            let value = self.defaults.object(forKey: Keys.betaReleasesEnabled)
            return value as? Bool ?? false // Default to stable-only updates
        }
        set {
            guard newValue != self.betaReleasesEnabled else { return }
            objectWillChange.send()
            self.defaults.set(newValue, forKey: Keys.betaReleasesEnabled)
            let revision = self.defaults.integer(forKey: UpdateKeys.channelPreferenceRevision)
            self.defaults.set(revision &+ 1, forKey: UpdateKeys.channelPreferenceRevision)
            self.lastUpdateCheckDate = nil
            self.clearUpdateSnooze()
            Task { @MainActor in
                SimpleUpdater.shared.updateChannelDidChange()
            }
        }
    }

    /// Available Whisper model sizes
    enum WhisperModelSize: String, CaseIterable, Identifiable {
        case tiny = "ggml-tiny.bin"
        case base = "ggml-base.bin"
        case small = "ggml-small.bin"
        case medium = "ggml-medium.bin"
        case large = "ggml-large-v3.bin"

        var id: String {
            rawValue
        }

        var displayName: String {
            switch self {
            case .tiny: return "Tiny (~75 MB)"
            case .base: return "Base (~142 MB)"
            case .small: return "Small (~466 MB)"
            case .medium: return "Medium (~1.5 GB)"
            case .large: return "Large (~2.9 GB)"
            }
        }

        var description: String {
            switch self {
            case .tiny: return "Fastest, lower accuracy"
            case .base: return "Good balance of speed and accuracy"
            case .small: return "Better accuracy, slower"
            case .medium: return "High accuracy, requires more memory"
            case .large: return "Best accuracy, large download"
            }
        }
    }
}

extension SettingsStore.SpeechModel {
    var supportedLanguageCodes: String? {
        switch self {
        case .parakeetTDT, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
            return "BG, HR, CS, DA, NL, EN, ET, FI, FR, DE, EL, HU, IT, LV, LT, MT, PL, PT, RO, SK, SL, ES, SV, RU, UK"
        case .parakeetRealtime:
            return "EN"
        case .cohereTranscribeSixBit:
            return "AR, DE, EL, EN, ES, FR, IT, JA, KO, NL, PL, PT, VI, ZH"
        case .qwen3Asr, .qwen3Asr17B:
            // https://huggingface.co/Qwen/Qwen3-ASR-1.7B#released-models-description-and-download
            return "ZH, EN, YUE, AR, DE, FR, ES, PT, ID, IT, KO, RU, TH, VI, JA, TR, HI, MS, NL, SV, DA, FI, PL, CS, FIL, FA, EL, HU, MK, RO"
        case .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
            return "40 language-locales"
        case .appleSpeechAnalyzer:
            return "EN, ES, FR, DE, IT, JA, KO, PT, ZH"
        default:
            return nil
        }
    }

    var supportedLanguageNames: String? {
        switch self {
        case .parakeetTDT, .fluidParakeetMini, .fluidParakeetPico, .fluidParakeetPro:
            return """
            Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, Spanish, Swedish, Russian, and Ukrainian
            """
        case .cohereTranscribeSixBit:
            return "Arabic, German, Greek, English, Spanish, French, Italian, Japanese, Korean, Dutch, Polish, Portuguese, Vietnamese, and Mandarin Chinese"
        case .qwen3Asr, .qwen3Asr17B:
            return "Chinese, English, Cantonese, Arabic, German, French, Spanish, Portuguese, Indonesian, Italian, Korean, Russian, Thai, " +
                "Vietnamese, Japanese, Turkish, Hindi, Malay, Dutch, Swedish, Danish, Finnish, Polish, Czech, Filipino, Persian, Greek, " +
                "Hungarian, Macedonian, and Romanian"
        case .nemotronOffline, .nemotronStreaming, .nemotronStreaming320:
            return "Spanish, Italian, Portuguese, Hindi, Korean, English, German, French, Russian, Turkish, Vietnamese, Dutch, Japanese, Arabic, " +
                "Ukrainian; Polish, Norwegian Bokmal, Finnish, Mandarin, Czech, Bulgarian, Slovak, Swedish, Croatian, Romanian, Estonian, " +
                "Danish, and Hungarian are Alpha; Greek, Hebrew, Lithuanian, Slovenian, Latvian, Maltese, Thai, and Norwegian Nynorsk are Experimental."
        default:
            return nil
        }
    }
}

extension SettingsStore {
    enum CohereLanguage: String, CaseIterable, Identifiable, Codable {
        case arabic = "ar"
        case german = "de"
        case greek = "el"
        case english = "en"
        case spanish = "es"
        case french = "fr"
        case italian = "it"
        case japanese = "ja"
        case korean = "ko"
        case dutch = "nl"
        case polish = "pl"
        case portuguese = "pt"
        case vietnamese = "vi"
        case mandarinChinese = "zh"

        var id: String {
            self.rawValue
        }

        var displayName: String {
            switch self {
            case .arabic: return "Arabic"
            case .german: return "German"
            case .greek: return "Greek"
            case .english: return "English"
            case .spanish: return "Spanish"
            case .french: return "French"
            case .italian: return "Italian"
            case .japanese: return "Japanese"
            case .korean: return "Korean"
            case .dutch: return "Dutch"
            case .polish: return "Polish"
            case .portuguese: return "Portuguese"
            case .vietnamese: return "Vietnamese"
            case .mandarinChinese: return "Mandarin Chinese"
            }
        }

        var tokenString: String {
            "<|\(self.rawValue)|>"
        }
    }

    // MARK: - Unified Speech Model Selection

    /// The selected speech recognition model.
    /// This unified setting replaces the old TranscriptionProviderOption + WhisperModelSize combination.
    var selectedSpeechModel: SpeechModel {
        get {
            // Check if already using new system
            if let rawValue = defaults.string(forKey: Keys.selectedSpeechModel),
               let model = SpeechModel(rawValue: rawValue)
            {
                // If Qwen was previously selected, transparently fall back while preview is disabled.
                if model == .qwen3Asr, !SpeechModel.qwenPreviewEnabled {
                    return SpeechModel.defaultModel
                }
                if model == .nemotronStreaming320 {
                    return .nemotronStreaming
                }
                let requiresAppleSiliconWhisper = model == .whisperLargeTurbo || model == .whisperLarge
                if requiresAppleSiliconWhisper, !CPUArchitecture.isAppleSilicon {
                    return .whisperBase
                }
                // Validate model is available on this architecture
                if model.requiresAppleSilicon && !CPUArchitecture.isAppleSilicon {
                    return .whisperBase
                }
                if model.requiresMacOS15, #unavailable(macOS 15.0) {
                    return .whisperBase
                }
                if model.requiresMacOS26, #unavailable(macOS 26.0) {
                    return .whisperBase
                }
                return model
            }

            // Migration: Convert old settings to new SpeechModel
            return self.migrateToSpeechModel()
        }
        set {
            objectWillChange.send()
            let model = newValue == .nemotronStreaming320 ? SpeechModel.nemotronStreaming : newValue
            self.defaults.set(model.rawValue, forKey: Keys.selectedSpeechModel)
        }
    }

    /// The language Whisper should transcribe, or `nil` to detect it from each recording.
    /// Existing installs keep automatic detection until the user selects a language.
    var selectedWhisperLanguageCode: String? {
        get {
            Self.whisperLanguageCode(fromStoredValue: self.defaults.string(forKey: Keys.selectedWhisperLanguageCode))
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue ?? Self.automaticWhisperLanguageCode, forKey: Keys.selectedWhisperLanguageCode)
        }
    }

    static func whisperLanguageCode(fromStoredValue value: String?) -> String? {
        guard let value, value != self.automaticWhisperLanguageCode else { return nil }
        return VoiceEngineLanguageCatalog.whisperLanguage(forCode: value) == nil ? nil : value
    }

    static func whisperLanguageBackupValue(for languageCode: String?) -> String {
        languageCode ?? self.automaticWhisperLanguageCode
    }

    static func whisperLanguageCode(fromBackupValue value: String) -> String? {
        value == self.automaticWhisperLanguageCode ? nil : value
    }

    var selectedCohereLanguage: CohereLanguage {
        get {
            if let rawValue = self.defaults.string(forKey: Keys.selectedCohereLanguage),
               let language = CohereLanguage(rawValue: rawValue)
            {
                return language
            }
            return .english
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.selectedCohereLanguage)
        }
    }

    var selectedNemotronLanguage: NemotronLanguage {
        get {
            if let rawValue = self.defaults.string(forKey: Keys.selectedNemotronLanguage),
               let language = NemotronLanguage.supportedLanguage(rawValue: rawValue)
            {
                return language
            }
            return .english
        }
        set {
            objectWillChange.send()
            self.defaults.set(newValue.rawValue, forKey: Keys.selectedNemotronLanguage)
        }
    }

    /// Read only the persisted choice; callers can resolve the fallback off the main thread.
    func storedExternalCoreMLArtifactsPath(for model: SpeechModel) -> String? {
        let paths = self.defaults.dictionary(forKey: Keys.externalCoreMLArtifactsDirectories) as? [String: String] ?? [:]
        guard let path = paths[model.rawValue], !path.isEmpty else { return nil }
        return path
    }

    func externalCoreMLArtifactsDirectory(for model: SpeechModel) -> URL? {
        guard let spec = model.externalCoreMLSpec else { return nil }
        let paths = self.defaults.dictionary(forKey: Keys.externalCoreMLArtifactsDirectories) as? [String: String] ?? [:]
        if let storedPath = paths[model.rawValue], storedPath.isEmpty == false {
            return URL(fileURLWithPath: storedPath, isDirectory: true)
        }

        let cachesDirectory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first
        let fallback = cachesDirectory?.appendingPathComponent(spec.artifactFolderHint, isDirectory: true)
        guard let fallback else { return nil }
        if FileManager.default.fileExists(atPath: fallback.path) {
            return fallback
        }
        return nil
    }

    func setExternalCoreMLArtifactsDirectory(_ directory: URL?, for model: SpeechModel) {
        guard model.requiresExternalArtifacts else { return }
        objectWillChange.send()
        var paths = self.defaults.dictionary(forKey: Keys.externalCoreMLArtifactsDirectories) as? [String: String] ?? [:]
        if let directory {
            paths[model.rawValue] = directory.standardizedFileURL.path
        } else {
            paths.removeValue(forKey: model.rawValue)
        }
        self.defaults.set(paths, forKey: Keys.externalCoreMLArtifactsDirectories)
    }

    /// Migrates old TranscriptionProviderOption + WhisperModelSize settings to new SpeechModel
    private func migrateToSpeechModel() -> SpeechModel {
        let oldProvider = self.defaults.string(forKey: Keys.selectedTranscriptionProvider) ?? "auto"
        let oldWhisperSize = self.defaults.string(forKey: Keys.whisperModelSize) ?? "ggml-base.bin"

        let newModel: SpeechModel

        switch oldProvider {
        case "whisper":
            // Map old whisper size to new model
            switch oldWhisperSize {
            case "ggml-tiny.bin": newModel = .whisperTiny
            case "ggml-base.bin": newModel = .whisperBase
            case "ggml-small.bin": newModel = .whisperSmall
            case "ggml-medium.bin": newModel = .whisperMedium
            case "ggml-large-v3.bin": newModel = CPUArchitecture.isAppleSilicon ? .whisperLarge : .whisperBase
            default: newModel = .whisperBase
            }
        case "fluidAudio":
            newModel = CPUArchitecture.isAppleSilicon ? .parakeetTDT : .whisperBase
        default: // "auto"
            newModel = SpeechModel.defaultModel
        }

        // Persist the migrated value
        self.defaults.set(newModel.rawValue, forKey: Keys.selectedSpeechModel)
        DebugLogger.shared.info("Migrated speech model settings: \(oldProvider)/\(oldWhisperSize) -> \(newModel.rawValue)", source: "SettingsStore")

        return newModel
    }
}

extension Notification.Name {
    static let fluidMeetEnabledChanged = Notification.Name("FluidMeetEnabledChanged")
}