Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
feat(mobile): Add hardware-keyboard dictation shortcut for iPad (#2363)
Chad Pihac43eb089186a
diff --git a/.github/workflows/mobile-ci.yml b/.github/workflows/mobile-ci.ymlindex 7248338bd..0b74c65d2 100644--- a/.github/workflows/mobile-ci.yml+++ b/.github/workflows/mobile-ci.yml@@ -109,6 +109,8 @@ jobs:persist-credentials: false- name: Run native provider transport testsrun: python3 openwhispr-mobile/modules/background-uploader/tests/run-provider-transport-tests.py+ - name: Run hotkey dictation logic tests+ run: python3 openwhispr-mobile/plugins/hotkey-dictation/tests/run-hotkey-logic-tests.py- name: Run Live Activity resolver testsrun: sh openwhispr-mobile/modules/live-activity/tests/run-resolver-tests.shdiff --git a/openwhispr-mobile/app.base.json b/openwhispr-mobile/app.base.jsonindex 94e15e621..272f3c27e 100644--- a/openwhispr-mobile/app.base.json+++ b/openwhispr-mobile/app.base.json@@ -79,6 +79,7 @@"./plugins/keyboard-extension/withKeyboardExtension","./plugins/activity-extension/withActivityExtension","./plugins/settings-bundle/withSettingsBundle",+ "./plugins/hotkey-dictation/withHotkeyDictation","./plugins/speaker-diarization/withSpeakerDiarization","expo-web-browser","expo-image",diff --git a/openwhispr-mobile/app/(account)/_layout.tsx b/openwhispr-mobile/app/(account)/_layout.tsxindex 70b441673..171788d34 100644--- a/openwhispr-mobile/app/(account)/_layout.tsx+++ b/openwhispr-mobile/app/(account)/_layout.tsx@@ -58,6 +58,10 @@ export default function AccountLayout() {name="keyboard-tone"options={{ title: 'Keyboard Tone', headerLargeTitle: false }}/>+ <Stack.Screen+ name="hardware-keyboard"+ options={{ title: 'Hardware Keyboard', headerLargeTitle: false }}+ /><Stack.Screenname="cleanup-prompt"options={{ title: 'Cleanup Prompt', headerLargeTitle: false }}diff --git a/openwhispr-mobile/app/(account)/hardware-keyboard.tsx b/openwhispr-mobile/app/(account)/hardware-keyboard.tsxnew file mode 100644index 000000000..4b6162066--- /dev/null+++ b/openwhispr-mobile/app/(account)/hardware-keyboard.tsx@@ -0,0 +1 @@+export { HardwareKeyboardShortcutScreen as default } from '@/screens/HardwareKeyboardShortcutScreen';diff --git a/openwhispr-mobile/modules/app-group-storage/ios/AppGroupStorageModule.swift b/openwhispr-mobile/modules/app-group-storage/ios/AppGroupStorageModule.swiftindex 8ab40c394..4ab414f24 100644--- a/openwhispr-mobile/modules/app-group-storage/ios/AppGroupStorageModule.swift+++ b/openwhispr-mobile/modules/app-group-storage/ios/AppGroupStorageModule.swift@@ -1,6 +1,7 @@import ExpoModulesCoreimport UIKitimport AVFoundation+import GameControllerpublic class AppGroupStorageModule: Module {private var appBundleId: String {@@ -11,6 +12,7 @@ public class AppGroupStorageModule: Module {}private let stopRequestedKey = "keyboard_stop_requested"private let stopRequestedAtMsKey = "keyboard_stop_requested_at_ms"+ private let hotkeyJsReadyAtMsKey = "hotkey_js_ready_at_ms"private let transcriptionStatusKey = "keyboard_transcription_status"private let transcriptionErrorKey = "keyboard_transcription_error"private let transcriptionStatusUpdatedAtMsKey = "keyboard_transcription_status_updated_at_ms"@@ -122,6 +124,7 @@ public class AppGroupStorageModule: Module {private let warmMicIdleTimeoutSeconds: TimeInterval = 10 * 60 // 10 min, tunable (spec §3)private let dictationModeEnabledKey = "dictation_mode_enabled"private var backgroundTaskId: UIBackgroundTaskIdentifier = .invalid+ private var hardwareKeyboardObserverTokens: [NSObjectProtocol] = []private var isObservingStopNotification: Bool = falseprivate var isObservingStartNotification: Bool = false@@ -149,7 +152,8 @@ public class AppGroupStorageModule: Module {"onRecordingError","onBackgroundRecordingStarted","onKeyboardStatusChanged",- "onAgentAction"+ "onAgentAction",+ "onHardwareKeyboardChanged")OnCreate {@@ -161,6 +165,7 @@ public class AppGroupStorageModule: Module {self.addForegroundObserver()self.addBackgroundObserver()self.addAudioSessionObservers()+ self.addHardwareKeyboardObservers()DispatchQueue.main.async {if UIApplication.shared.applicationState == .active {self.startForegroundHeartbeat()@@ -228,6 +233,23 @@ public class AppGroupStorageModule: Module {}}+ // Called by useKeyboardHandoff once its recording listeners are subscribed.+ // The hotkey's cold start (plugins/hotkey-dictation) waits for this stamp, and+ // only trusts one carrying this process's pid: a crash skips the hook's+ // cleanup, and the next launch's intent can read before OnCreate clears it.+ Function("markHotkeyJsReady") { () -> Void in+ guard let defaults = UserDefaults(suiteName: self.appGroupId) else { return }+ let nowMs = Int(Date().timeIntervalSince1970 * 1000)+ defaults.set("\(getpid()):\(nowMs)", forKey: self.hotkeyJsReadyAtMsKey)+ defaults.synchronize()+ }++ // Drives the one-time "Using a keyboard?" nudge toward the hardware-keyboard+ // dictation shortcut (plugins/hotkey-dictation).+ Function("isHardwareKeyboardConnected") { () -> Bool in+ return GCKeyboard.coalesced != nil+ }+Function("getActiveInputModes") { () -> [String] in// Reads the user's currently installed iOS keyboards. Each returned// tag looks like "en-US", "he-IL", "emoji", etc. Used by the@@ -284,6 +306,7 @@ public class AppGroupStorageModule: Module {self.removeForegroundObserver()self.removeBackgroundObserver()self.removeAudioSessionObservers()+ self.removeHardwareKeyboardObservers()self.stopForegroundHeartbeat()self.stopWarmMicIdleTimer()self.stopKeepAliveHeartbeat()@@ -313,6 +336,9 @@ public class AppGroupStorageModule: Module {defaults.set("idle", forKey: transcriptionStatusKey)defaults.removeObject(forKey: transcriptionErrorKey)defaults.removeObject(forKey: transcriptionStatusUpdatedAtMsKey)+ // Hotkey dictation (plugins/hotkey-dictation): a fresh process has no JS+ // listeners yet, so a ready stamp from a previous process must not survive.+ defaults.removeObject(forKey: hotkeyJsReadyAtMsKey)// Agent one-shot / per-job keys: cleared on every launch so stale requests// from a previous session are never replayed. Config-mirror keys// (keyboard_agent_enabled / applicable / name / share_context) are NOT@@ -1653,6 +1679,24 @@ public class AppGroupStorageModule: Module {logMarker("foregroundObserver.added")}+ private func addHardwareKeyboardObservers() {+ guard hardwareKeyboardObserverTokens.isEmpty else { return }+ let center = NotificationCenter.default+ for name in [NSNotification.Name.GCKeyboardDidConnect, .GCKeyboardDidDisconnect] {+ let token = center.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in+ self?.sendEvent("onHardwareKeyboardChanged", ["connected": GCKeyboard.coalesced != nil])+ }+ hardwareKeyboardObserverTokens.append(token)+ }+ }++ private func removeHardwareKeyboardObservers() {+ for token in hardwareKeyboardObserverTokens {+ NotificationCenter.default.removeObserver(token)+ }+ hardwareKeyboardObserverTokens = []+ }+private func removeForegroundObserver() {guard let token = foregroundObserverToken else { return }NotificationCenter.default.removeObserver(token)diff --git a/openwhispr-mobile/modules/app-group-storage/src/index.ts b/openwhispr-mobile/modules/app-group-storage/src/index.tsindex c7204c8f0..6383639c7 100644--- a/openwhispr-mobile/modules/app-group-storage/src/index.ts+++ b/openwhispr-mobile/modules/app-group-storage/src/index.ts@@ -19,6 +19,8 @@ interface AppGroupStorageModule {stopNativeRecording(): void;endProcessingTask(): void;armWarmMic(): void;+ isHardwareKeyboardConnected(): boolean;+ markHotkeyJsReady(): void;}export interface SpeechActivityAnalysis {@@ -64,6 +66,7 @@ type AppGroupStorageEvents = {trigger?: string;}) => void;onAgentAction: () => void;+ onHardwareKeyboardChanged: (event: { connected: boolean }) => void;};const NativeModule: AppGroupStorageModule | null =@@ -167,6 +170,22 @@ export const AppGroupStorage = {if (!NativeModule) return;NativeModule.armWarmMic();},++ /** True while a hardware keyboard (e.g. a Magic Keyboard) is attached. */+ isHardwareKeyboardConnected(): boolean {+ if (!NativeModule) return false;+ return NativeModule.isHardwareKeyboardConnected();+ },++ /**+ * Tells the hardware-keyboard hotkey (plugins/hotkey-dictation) that this+ * process's recording listeners are subscribed. The native side stamps the+ * process id, so a stamp left by a process that died never counts.+ */+ markHotkeyJsReady(): void {+ if (!NativeModule) return;+ NativeModule.markHotkeyJsReady();+ },};export function addRecordingStoppedListener(@@ -223,6 +242,13 @@ export function addAgentActionListener(callback: () => void): EventSubscriptionreturn NativeModuleEvents.addListener('onAgentAction', callback);}+export function addHardwareKeyboardChangedListener(+ callback: (event: { connected: boolean }) => void,+): EventSubscription | null {+ if (!NativeModuleEvents) return null;+ return NativeModuleEvents.addListener('onHardwareKeyboardChanged', callback);+}+export const APP_GROUP_KEYS = {KEYBOARD_PENDING_TRANSCRIPT: 'keyboard_pending_transcript',KEYBOARD_PENDING_TRANSCRIPT_JOB_ID: 'keyboard_pending_transcript_job_id',@@ -246,6 +272,10 @@ export const APP_GROUP_KEYS = {KEYBOARD_RECORDING_TONE_JOB_ID: 'keyboard_recording_tone_job_id',KEYBOARD_TONE_APPLICABLE: 'keyboard_tone_applicable',BACKGROUND_SESSION_READY: 'background_session_ready',+ // Hotkey dictation: "<pid>:<ms>", stamped by markHotkeyJsReady once+ // useKeyboardHandoff's recording listeners are subscribed; the hotkey's cold+ // start waits for it. Native clears it at launch.+ HOTKEY_JS_READY_AT_MS: 'hotkey_js_ready_at_ms',// Agent mode — config mirrors (app → keyboard; persisted across launches like tone keys)KEYBOARD_AGENT_ENABLED: 'keyboard_agent_enabled',KEYBOARD_AGENT_APPLICABLE: 'keyboard_agent_applicable',diff --git a/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDeliveryWatcher.swift b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDeliveryWatcher.swiftnew file mode 100644index 000000000..55e832441--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDeliveryWatcher.swift@@ -0,0 +1,81 @@+import Foundation+import UIKit++/// Watches a hotkey recording from the moment it starts until its transcript is+/// copied. Starting at the recording (not at the stop press) means a hotkey+/// dictation is delivered however it ends: a second press, an audio interruption,+/// or a stop from the app. The delivery clock only runs once the recording has+/// ended. Lives for the process; one job at a time (decidePress refuses a new+/// start while `isWatching`). Main thread only.+final class HotkeyDeliveryWatcher {+ static let shared = HotkeyDeliveryWatcher()++ private var jobId: String?+ private var session: HotkeyDictationSession?+ private var deadlineMs: Int?+ private var timer: Timer?+ private var isObserving = false++ private init() {}++ var isWatching: Bool { jobId != nil }++ func watch(jobId: String, session: HotkeyDictationSession) {+ self.jobId = jobId+ self.session = session+ deadlineMs = nil+ startObserving(bundleId: session.bundleId)+ timer?.invalidate()+ // Fallback for a missed Darwin post; the observers make the common case instant.+ timer = Timer.scheduledTimer(withTimeInterval: 0.5, repeats: true) { _ in+ HotkeyDeliveryWatcher.shared.check()+ }+ HotkeyDictationSession.log.info("delivery.watch jobId=\(jobId, privacy: .public)")+ check()+ }++ func check() {+ guard let jobId, let session else { return }+ var outcome = session.readDelivery(jobId: jobId)+ let nowMs = HotkeyDictationSession.nowMs()+ deadlineMs = HotkeyDecision.nextDeliveryDeadline(current: deadlineMs, outcome: outcome, nowMs: nowMs)+ if outcome == .recording || outcome == .pending {+ guard let deadlineMs, nowMs >= deadlineMs else { return }+ outcome = HotkeyDecision.timeoutOutcome+ }+ if case .copy(let text) = outcome {+ UIPasteboard.general.string = text+ session.consumeTranscript()+ HotkeyDictationSession.log.info("delivery.copied chars=\(text.count, privacy: .public)")+ } else {+ HotkeyDictationSession.log.info("delivery.ended outcome=\(String(describing: outcome), privacy: .public)")+ }+ finish(banner: HotkeyDecision.banner(for: outcome))+ }++ private func finish(banner: HotkeyBanner?) {+ timer?.invalidate()+ timer = nil+ jobId = nil+ session = nil+ deadlineMs = nil+ if let banner { HotkeyFeedback.show(banner) }+ }++ private func startObserving(bundleId: String) {+ guard !isObserving else { return }+ isObserving = true+ let callback: CFNotificationCallback = { _, _, _, _, _ in+ DispatchQueue.main.async { HotkeyDeliveryWatcher.shared.check() }+ }+ for suffix in [HotkeyNotification.transcriptReady, HotkeyNotification.keyboardStatusChanged] {+ CFNotificationCenterAddObserver(+ CFNotificationCenterGetDarwinNotifyCenter(),+ Unmanaged.passUnretained(self).toOpaque(),+ callback,+ HotkeyNotification.name(suffix, bundleId: bundleId) as CFString,+ nil,+ .deliverImmediately)+ }+ }+}diff --git a/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationIntent.swift b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationIntent.swiftnew file mode 100644index 000000000..5e761e695--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationIntent.swift@@ -0,0 +1,102 @@+import AppIntents+import Foundation++/// Bound by the user to a key combo under Accessibility → Keyboards → Full+/// Keyboard Access → Commands → Shortcuts. iPadOS hides third-party keyboards+/// while a hardware keyboard is attached, so this is how an iPad user with a+/// Magic Keyboard dictates into other apps; the result goes to the clipboard.+/// Returns no dialog: a result card needs a manual Done, and pressing the combo+/// again would re-run the intent instead of dismissing it.+struct ToggleHotkeyDictationIntent: AppIntent {+ static var title: LocalizedStringResource = "Toggle OpenWhispr Dictation"+ static var description = IntentDescription(+ "Starts dictation. Run it again to stop and copy the transcript to the clipboard.")+ static var openAppWhenRun: Bool = false++ func perform() async throws -> some IntentResult {+ guard let session = HotkeyDictationSession() else {+ HotkeyDictationSession.log.error("press.noAppGroup")+ return .result()+ }+ // Deliberately not an AudioRecordingIntent: App Intents calls fatalError when one+ // returns with an active audio session and no Live Activity, the dictation-mode+ // warm mic keeps the session active, and a background launch cannot start a Live+ // Activity. A cold start is still attempted; if iOS refuses the background mic,+ // the press ends with the "Open OpenWhispr" banner.+ let action = await HotkeyPressCoordinator.shared.claim(session: session)+ HotkeyDictationSession.log.info("press action=\(String(describing: action), privacy: .public)")++ switch action {+ case .stop:+ // A hotkey recording is already watched from its start; a keyboard dictation+ // this press stops is left to the keyboard to deliver.+ session.stop()+ HotkeyFeedback.playEnd()+ case .ignoreStarting:+ break+ case .ignoreBusy:+ HotkeyFeedback.show(.stillTranscribing)+ case .startWarm:+ await finishStart(jobId: await session.startWarm(), session: session)+ case .startCold:+ let result = await HotkeyDecision.runColdStart(ColdStartDeps(+ isJsReady: { session.isJsReady },+ startWarm: { await session.startWarm() },+ sleepMs: HotkeyDictationSession.sleepMs,+ nowMs: HotkeyDictationSession.nowMs))+ HotkeyDictationSession.log.info("coldStart result=\(String(describing: result), privacy: .public)")+ var jobId: String?+ if case .started(let startedJobId) = result { jobId = startedJobId }+ await finishStart(jobId: jobId, session: session)+ }+ return .result()+ }++ /// Hands a started recording to the watcher before releasing the start slot, so+ /// no press can slip between the two and be misread as idle.+ private func finishStart(jobId: String?, session: HotkeyDictationSession) async {+ await MainActor.run {+ if let jobId {+ HotkeyDeliveryWatcher.shared.watch(jobId: jobId, session: session)+ }+ HotkeyPressCoordinator.shared.releaseStart()+ }+ if jobId != nil {+ HotkeyFeedback.playBegin()+ } else {+ HotkeyFeedback.show(.openApp)+ }+ }+}++/// Decides a press and, for a start, claims the start slot in one main-actor step,+/// so two presses in flight at once (e.g. a second press during the cold JS wait)+/// can never both start a recording.+@MainActor+final class HotkeyPressCoordinator {+ static let shared = HotkeyPressCoordinator()++ private var startInProgress = false++ private init() {}++ func claim(session: HotkeyDictationSession) -> PressAction {+ let action = HotkeyDecision.decidePress(session.snapshot(+ deliveryPending: HotkeyDeliveryWatcher.shared.isWatching,+ startInProgress: startInProgress))+ if action == .startWarm || action == .startCold { startInProgress = true }+ return action+ }++ func releaseStart() { startInProgress = false }+}++struct OpenWhisprAppShortcuts: AppShortcutsProvider {+ static var appShortcuts: [AppShortcut] {+ AppShortcut(+ intent: ToggleHotkeyDictationIntent(),+ phrases: ["Toggle \(.applicationName) dictation"],+ shortTitle: "Toggle Dictation",+ systemImageName: "mic")+ }+}diff --git a/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationLogic.swift b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationLogic.swiftnew file mode 100644index 000000000..82b0c6f6b--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationLogic.swift@@ -0,0 +1,210 @@+import Foundation++/// App Group keys shared with the keyboard extension (KeyboardViewController.swift)+/// and AppGroupStorageModule.swift. The values must stay identical to theirs:+/// the hotkey drives the keyboard's recording handshake, it doesn't have its own.+enum HotkeyKeys {+ static let pendingTranscript = "keyboard_pending_transcript"+ static let pendingTranscriptJobId = "keyboard_pending_transcript_job_id"+ static let orphanedRawTranscript = "keyboard_orphaned_raw_transcript"+ static let orphanedRawTranscriptJobId = "keyboard_orphaned_raw_transcript_job_id"+ static let recordingJobId = "keyboard_recording_job_id"+ static let recordingActive = "keyboard_recording_active"+ static let audioLevel = "keyboard_audio_level"+ static let stopRequested = "keyboard_stop_requested"+ static let stopRequestedAtMs = "keyboard_stop_requested_at_ms"+ static let backgroundSessionReady = "background_session_ready"+ static let backgroundSessionHeartbeat = "background_session_heartbeat"+ static let transcriptionStatus = "keyboard_transcription_status"+ static let transcriptionError = "keyboard_transcription_error"+ static let transcriptionStatusUpdatedAtMs = "keyboard_transcription_status_updated_at_ms"+ /// "<pid>:<ms>", written through AppGroupStorageModule.markHotkeyJsReady once+ /// useKeyboardHandoff's recording listeners are subscribed.+ static let hotkeyJsReadyAtMs = "hotkey_js_ready_at_ms"+}++enum HotkeyNotification {+ static let startRecording = "startRecording"+ static let stopRecording = "stopRecording"+ static let keyboardStatusChanged = "keyboardStatusChanged"+ static let transcriptReady = "transcriptReady"++ static func name(_ suffix: String, bundleId: String) -> String { "\(bundleId).\(suffix)" }+}++struct HotkeySnapshot: Equatable {+ var recordingActive: Bool+ var sessionReady: Bool+ var heartbeatAgeMs: Int?+ var status: String?+ var statusAgeMs: Int?+ /// In-process: a hotkey recording is being watched until its transcript is delivered.+ var deliveryPending: Bool+ /// In-process: a hotkey start is in flight (cold JS wait, or waiting for the recording flag).+ var startInProgress: Bool+ /// This process's JS listeners are subscribed (pid-scoped stamp). Until then the+ /// shared flags may still describe a process that was just killed.+ var jsReady: Bool+}++enum PressAction: Equatable {+ case stop, ignoreStarting, ignoreBusy, startWarm, startCold+}++enum DeliveryOutcome: Equatable {+ case copy(String), noSpeech, failed, pending, recording+}++/// Only the newest banner's removal timer may clear it; an older banner's timer+/// must not remove the one that replaced it.+struct BannerGenerations {+ private var current = 0++ mutating func next() -> Int {+ current += 1+ return current+ }++ func isCurrent(_ generation: Int) -> Bool { generation == current }+}++enum HotkeyBanner: Equatable {+ case copied, stillTranscribing, openApp, noSpeech, failed++ var body: String {+ switch self {+ case .copied: return "Copied — press ⌘V to paste"+ case .stillTranscribing: return "Still transcribing…"+ case .openApp: return "Open OpenWhispr to turn on dictation mode"+ case .noSpeech: return "No speech detected"+ case .failed: return "Couldn't transcribe — open OpenWhispr"+ }+ }+}++enum ColdStartResult: Equatable {+ case started(jobId: String), jsNotReady, startFailed+}++struct ColdStartDeps {+ var isJsReady: () -> Bool+ /// The started recording's job id, or nil when it didn't start.+ var startWarm: () async -> String?+ var sleepMs: (Int) async -> Void+ var nowMs: () -> Int+}++enum HotkeyDecision {+ /// The host app stamps its heartbeat every second while alive.+ static let heartbeatFreshMs = 5_000+ /// A busy status older than this is a leftover from a dead job.+ static let busyStatusMaxAgeMs = 300_000+ static let warmStartTimeoutMs = 2_000+ static let jsReadyTimeoutMs = 8_000+ static let deliveryTimeoutMs = 300_000+ static let pollMs = 100+ static let busyStatuses: Set<String> = ["transcribing", "cleaning", "agent_generating"]+ static let timeoutOutcome: DeliveryOutcome = .failed++ static func isHeartbeatFresh(_ snapshot: HotkeySnapshot) -> Bool {+ guard let age = snapshot.heartbeatAgeMs else { return false }+ return age <= heartbeatFreshMs+ }++ static func isRecording(_ snapshot: HotkeySnapshot) -> Bool {+ snapshot.recordingActive && isHeartbeatFresh(snapshot)+ }++ static func isWarm(_ snapshot: HotkeySnapshot) -> Bool {+ snapshot.sessionReady && isHeartbeatFresh(snapshot)+ }++ static func decidePress(_ snapshot: HotkeySnapshot) -> PressAction {+ // A start in flight owns the hotkey until it has seen its recording begin; a stop+ // slipped in here would end that recording before the starting press notices.+ if snapshot.startInProgress { return .ignoreStarting }+ // Shared flags are trusted only once this process's JS is listening: a killed+ // process leaves "ready"/"recording" and a fresh heartbeat behind for up to 5 s.+ // Recording comes before deliveryPending, which is also true while a hotkey+ // recording runs (the watcher is armed at start).+ if snapshot.jsReady && isRecording(snapshot) { return .stop }+ if snapshot.deliveryPending { return .ignoreBusy }+ if snapshot.jsReady {+ let busyStatus = snapshot.status.map { busyStatuses.contains($0) } ?? false+ let statusFresh = snapshot.statusAgeMs.map { $0 <= busyStatusMaxAgeMs } ?? false+ if busyStatus && statusFresh { return .ignoreBusy }+ if isWarm(snapshot) { return .startWarm }+ }+ return .startCold+ }++ /// The ready stamp is "<pid>:<ms>". A stamp left by a process that died without+ /// running the hook's cleanup must not make a fresh process look ready.+ static func isJsReadyStamp(_ raw: String?, pid: Int32) -> Bool {+ guard let raw, let separator = raw.firstIndex(of: ":") else { return false }+ return Int32(raw[raw.startIndex..<separator]) == pid+ }++ /// The delivery clock runs only once the recording has ended (by any path), so a+ /// long dictation never times out while it is still being spoken.+ static func nextDeliveryDeadline(current: Int?, outcome: DeliveryOutcome, nowMs: Int) -> Int? {+ if outcome == .recording { return nil }+ return current ?? nowMs + deliveryTimeoutMs+ }++ /// `recordingActive` is the live recording flag (fresh heartbeat) and the only+ /// source of `.recording`: the shared status can be overwritten with "idle" by a+ /// previous job's delayed JS cleanup, or left at "recording" after a failure,+ /// which would otherwise pause the delivery timeout forever.+ static func deliveryOutcome(+ jobId: String,+ pendingTranscript: String?,+ pendingJobId: String?,+ status: String?,+ recordingActive: Bool+ ) -> DeliveryOutcome {+ if let text = pendingTranscript, !text.isEmpty, pendingJobId == jobId { return .copy(text) }+ if recordingActive { return .recording }+ switch status {+ case "no_speech": return .noSpeech+ // "idle" after a stop means the job ended without leaving a transcript for us.+ case "error", "setup_required", "idle": return .failed+ default: return .pending+ }+ }++ static func banner(for outcome: DeliveryOutcome) -> HotkeyBanner? {+ switch outcome {+ case .copy: return .copied+ case .noSpeech: return .noSpeech+ case .failed: return .failed+ case .pending, .recording: return nil+ }+ }++ static func waitUntil(+ timeoutMs: Int,+ pollMs: Int = HotkeyDecision.pollMs,+ nowMs: () -> Int,+ sleepMs: (Int) async -> Void,+ _ check: () -> Bool+ ) async -> Bool {+ let deadline = nowMs() + timeoutMs+ while true {+ if check() { return true }+ if nowMs() >= deadline { return false }+ await sleepMs(pollMs)+ }+ }++ /// Cold start never records before JS is listening: on a background launch the+ /// native start/stop events would otherwise fire before useKeyboardHandoff+ /// subscribes, losing the route snapshot and, for short dictations, the audio.+ static func runColdStart(_ deps: ColdStartDeps) async -> ColdStartResult {+ let ready = await waitUntil(+ timeoutMs: jsReadyTimeoutMs, nowMs: deps.nowMs, sleepMs: deps.sleepMs, deps.isJsReady)+ guard ready else { return .jsNotReady }+ guard let jobId = await deps.startWarm() else { return .startFailed }+ return .started(jobId: jobId)+ }+}diff --git a/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationSession.swift b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationSession.swiftnew file mode 100644index 000000000..71f915f29--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyDictationSession.swift@@ -0,0 +1,124 @@+import Foundation+import os.log++/// The App Group handshake the keyboard extension uses (KeyboardHandoffProvider+/// requestStart/requestStop in KeyboardViewController.swift), driven from the+/// hotkey intent so hotkey recordings take exactly the keyboard's recording path.+final class HotkeyDictationSession {+ static let log = Logger(+ subsystem: Bundle.main.bundleIdentifier ?? "com.gizmolabs.openwhispr",+ category: "HotkeyDictation")++ let bundleId: String+ private let defaults: UserDefaults++ init?() {+ let bundleId = Bundle.main.bundleIdentifier ?? "com.gizmolabs.openwhispr"+ guard let defaults = UserDefaults(suiteName: "group.\(bundleId)") else { return nil }+ self.bundleId = bundleId+ self.defaults = defaults+ }++ static func nowMs() -> Int { Int(Date().timeIntervalSince1970 * 1000) }++ static func sleepMs(_ ms: Int) async {+ try? await Task.sleep(nanoseconds: UInt64(ms) * 1_000_000)+ }++ private func ageMs(_ key: String) -> Int? {+ guard let raw = defaults.string(forKey: key), let stampMs = Double(raw) else { return nil }+ return Self.nowMs() - Int(stampMs)+ }++ /// `deliveryPending` and `startInProgress` are in-process state (the intent and the+ /// watcher share the app process), so no App Group key can leave them stuck.+ func snapshot(deliveryPending: Bool, startInProgress: Bool) -> HotkeySnapshot {+ HotkeySnapshot(+ recordingActive: defaults.string(forKey: HotkeyKeys.recordingActive) == "1",+ sessionReady: defaults.string(forKey: HotkeyKeys.backgroundSessionReady) == "1",+ heartbeatAgeMs: ageMs(HotkeyKeys.backgroundSessionHeartbeat),+ status: defaults.string(forKey: HotkeyKeys.transcriptionStatus),+ statusAgeMs: ageMs(HotkeyKeys.transcriptionStatusUpdatedAtMs),+ deliveryPending: deliveryPending,+ startInProgress: startInProgress,+ jsReady: isJsReady)+ }++ var isJsReady: Bool {+ HotkeyDecision.isJsReadyStamp(+ defaults.string(forKey: HotkeyKeys.hotkeyJsReadyAtMs), pid: getpid())+ }++ var isRecording: Bool {+ HotkeyDecision.isRecording(snapshot(deliveryPending: false, startInProgress: false))+ }++ /// Mirrors KeyboardHandoffProvider.requestStart, then waits for the app's start+ /// observer to report the recording. Returns the recording's job id, or nil when+ /// it didn't start.+ func startWarm() async -> String? {+ let startedAt = Self.nowMs()+ let jobId = "\(startedAt)-\(UUID().uuidString)"+ defaults.set("0", forKey: HotkeyKeys.stopRequested)+ defaults.removeObject(forKey: HotkeyKeys.stopRequestedAtMs)+ defaults.set("0", forKey: HotkeyKeys.recordingActive)+ defaults.removeObject(forKey: HotkeyKeys.audioLevel)+ defaults.removeObject(forKey: HotkeyKeys.pendingTranscript)+ defaults.removeObject(forKey: HotkeyKeys.pendingTranscriptJobId)+ defaults.removeObject(forKey: HotkeyKeys.orphanedRawTranscript)+ defaults.removeObject(forKey: HotkeyKeys.orphanedRawTranscriptJobId)+ defaults.set(jobId, forKey: HotkeyKeys.recordingJobId)+ defaults.set("recording", forKey: HotkeyKeys.transcriptionStatus)+ defaults.set(String(startedAt), forKey: HotkeyKeys.transcriptionStatusUpdatedAtMs)+ defaults.removeObject(forKey: HotkeyKeys.transcriptionError)+ // Flush before the post: the app's start handler records under whatever job id it reads.+ defaults.synchronize()+ post(HotkeyNotification.startRecording)++ let started = await HotkeyDecision.waitUntil(+ timeoutMs: HotkeyDecision.warmStartTimeoutMs, nowMs: Self.nowMs, sleepMs: Self.sleepMs+ ) { self.isRecording }+ Self.log.info(+ "start jobId=\(jobId, privacy: .public) started=\(started, privacy: .public) latencyMs=\(Self.nowMs() - startedAt, privacy: .public)")+ return started ? jobId : nil+ }++ /// Mirrors KeyboardHandoffProvider.requestStop.+ func stop() {+ let stoppedAt = String(Self.nowMs())+ defaults.set("1", forKey: HotkeyKeys.stopRequested)+ defaults.set(stoppedAt, forKey: HotkeyKeys.stopRequestedAtMs)+ defaults.set("transcribing", forKey: HotkeyKeys.transcriptionStatus)+ defaults.set(stoppedAt, forKey: HotkeyKeys.transcriptionStatusUpdatedAtMs)+ defaults.synchronize()+ post(HotkeyNotification.stopRecording)+ }++ func readDelivery(jobId: String) -> DeliveryOutcome {+ HotkeyDecision.deliveryOutcome(+ jobId: jobId,+ pendingTranscript: defaults.string(forKey: HotkeyKeys.pendingTranscript),+ pendingJobId: defaults.string(forKey: HotkeyKeys.pendingTranscriptJobId),+ status: defaults.string(forKey: HotkeyKeys.transcriptionStatus),+ recordingActive: isRecording)+ }++ /// Takes the transcript off the keyboard's pending slot so the OpenWhispr+ /// keyboard never inserts it a second time the next time it opens.+ func consumeTranscript() {+ defaults.removeObject(forKey: HotkeyKeys.pendingTranscript)+ defaults.removeObject(forKey: HotkeyKeys.pendingTranscriptJobId)+ defaults.set("idle", forKey: HotkeyKeys.transcriptionStatus)+ defaults.set(String(Self.nowMs()), forKey: HotkeyKeys.transcriptionStatusUpdatedAtMs)+ defaults.removeObject(forKey: HotkeyKeys.transcriptionError)+ defaults.synchronize()+ post(HotkeyNotification.keyboardStatusChanged)+ }++ private func post(_ suffix: String) {+ CFNotificationCenterPostNotification(+ CFNotificationCenterGetDarwinNotifyCenter(),+ CFNotificationName(HotkeyNotification.name(suffix, bundleId: bundleId) as CFString),+ nil, nil, true)+ }+}diff --git a/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyFeedback.swift b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyFeedback.swiftnew file mode 100644index 000000000..6535ec38c--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/ios/HotkeyFeedback.swift@@ -0,0 +1,45 @@+import AudioToolbox+import Foundation+import UserNotifications++/// Status for a dictation started from a hardware-keyboard shortcut. iPad has no+/// Dynamic Island, so the Live Activity is invisible while typing: chimes carry+/// start/stop, and a banner reports the result without taking focus.+enum HotkeyFeedback {+ private static let bannerId = "hotkey-dictation-status"+ private static let bannerLifetime: TimeInterval = 4+ /// Main thread only.+ private static var generations = BannerGenerations()++ /// iOS's own begin/end-recording sounds.+ static func playBegin() { AudioServicesPlaySystemSound(1113) }+ static func playEnd() { AudioServicesPlaySystemSound(1114) }++ /// Replaces the previous banner, then clears it from Notification Center.+ /// Skipped without notification permission; the chimes still play.+ static func show(_ banner: HotkeyBanner) {+ let center = UNUserNotificationCenter.current()+ center.getNotificationSettings { settings in+ let allowed: Set<UNAuthorizationStatus> = [.authorized, .provisional, .ephemeral]+ guard allowed.contains(settings.authorizationStatus) else {+ HotkeyDictationSession.log.info("banner.skippedNoPermission")+ return+ }+ DispatchQueue.main.async {+ let generation = generations.next()+ let content = UNMutableNotificationContent()+ content.title = "OpenWhispr"+ content.body = banner.body+ content.threadIdentifier = bannerId+ content.interruptionLevel = .active+ center.removeDeliveredNotifications(withIdentifiers: [bannerId])+ center.add(UNNotificationRequest(identifier: bannerId, content: content, trigger: nil))+ // A newer banner reuses the identifier; its own timer clears it.+ DispatchQueue.main.asyncAfter(deadline: .now() + bannerLifetime) {+ guard generations.isCurrent(generation) else { return }+ center.removeDeliveredNotifications(withIdentifiers: [bannerId])+ }+ }+ }+ }+}diff --git a/openwhispr-mobile/plugins/hotkey-dictation/tests/HotkeyDictationLogicTests.swift b/openwhispr-mobile/plugins/hotkey-dictation/tests/HotkeyDictationLogicTests.swiftnew file mode 100644index 000000000..1b123bd47--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/tests/HotkeyDictationLogicTests.swift@@ -0,0 +1,194 @@+import Foundation++/// Deterministic clock for the async sequencing helpers: sleeping advances time.+final class FakeClock {+ var now = 0+ func sleep(_ ms: Int) async { now += ms }+}++@main+struct HotkeyDictationLogicTests {+ static func snapshot(+ recordingActive: Bool = false,+ sessionReady: Bool = false,+ heartbeatAgeMs: Int? = 1_000,+ status: String? = "idle",+ statusAgeMs: Int? = 1_000,+ deliveryPending: Bool = false,+ startInProgress: Bool = false,+ jsReady: Bool = true+ ) -> HotkeySnapshot {+ HotkeySnapshot(+ recordingActive: recordingActive,+ sessionReady: sessionReady,+ heartbeatAgeMs: heartbeatAgeMs,+ status: status,+ statusAgeMs: statusAgeMs,+ deliveryPending: deliveryPending,+ startInProgress: startInProgress,+ jsReady: jsReady)+ }++ static func outcome(+ pendingTranscript: String? = nil,+ pendingJobId: String? = nil,+ status: String?,+ recordingActive: Bool = false+ ) -> DeliveryOutcome {+ HotkeyDecision.deliveryOutcome(+ jobId: "a",+ pendingTranscript: pendingTranscript,+ pendingJobId: pendingJobId,+ status: status,+ recordingActive: recordingActive)+ }++ static func main() async {+ // decidePress — a live recording stops, even while its delivery is being watched.+ precondition(HotkeyDecision.decidePress(snapshot(recordingActive: true, heartbeatAgeMs: 5_000)) == .stop)+ precondition(HotkeyDecision.decidePress(snapshot(+ recordingActive: true, status: "transcribing", deliveryPending: true)) == .stop)++ // A start in flight owns the hotkey: a second press is ignored silently, even once+ // the recording flag is up, so it can never stop the recording before the starting+ // press sees it or start a second one.+ precondition(HotkeyDecision.decidePress(snapshot(recordingActive: true, startInProgress: true)) == .ignoreStarting)+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: true, startInProgress: true)) == .ignoreStarting)+ precondition(HotkeyDecision.decidePress(snapshot(startInProgress: true)) == .ignoreStarting)+ precondition(HotkeyDecision.decidePress(snapshot(+ sessionReady: true, status: "transcribing", startInProgress: true)) == .ignoreStarting)++ // Shared flags are only trusted once this process's JS is ready: a killed process+ // leaves them fresh for up to 5 s.+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: true, jsReady: false)) == .startCold)+ precondition(HotkeyDecision.decidePress(snapshot(recordingActive: true, jsReady: false)) == .startCold)+ precondition(HotkeyDecision.decidePress(snapshot(+ sessionReady: true, status: "transcribing", jsReady: false)) == .startCold)++ // A recording flag with a stale heartbeat is a leftover, not a recording.+ precondition(HotkeyDecision.decidePress(snapshot(recordingActive: true, heartbeatAgeMs: 5_001)) == .startCold)+ precondition(HotkeyDecision.decidePress(snapshot(recordingActive: true, heartbeatAgeMs: nil)) == .startCold)++ // Busy statuses refuse a new start while fresh; so does a delivery still in flight.+ for status in ["transcribing", "cleaning", "agent_generating"] {+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: true, status: status)) == .ignoreBusy)+ }+ precondition(HotkeyDecision.decidePress(snapshot(+ sessionReady: true, status: "transcribing", statusAgeMs: 300_000)) == .ignoreBusy)+ precondition(HotkeyDecision.decidePress(snapshot(+ sessionReady: true, status: "transcribing", statusAgeMs: 300_001)) == .startWarm)+ precondition(HotkeyDecision.decidePress(snapshot(+ sessionReady: true, status: "transcribing", statusAgeMs: nil)) == .startWarm)+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: true, deliveryPending: true)) == .ignoreBusy)++ // Warm vs cold.+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: true)) == .startWarm)+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: true, heartbeatAgeMs: 5_001)) == .startCold)+ precondition(HotkeyDecision.decidePress(snapshot(sessionReady: false)) == .startCold)++ // deliveryOutcome — the transcript for this job is copied.+ precondition(outcome(pendingTranscript: "hello", pendingJobId: "a", status: "ready") == .copy("hello"))+ precondition(outcome(pendingTranscript: "hello", pendingJobId: "b", status: "ready") == .pending)+ precondition(outcome(pendingTranscript: "", pendingJobId: "a", status: "ready") == .pending)+ precondition(outcome(status: "transcribing") == .pending)+ precondition(outcome(status: "no_speech") == .noSpeech)+ for status in ["error", "setup_required", "idle"] {+ precondition(outcome(status: status) == .failed)+ }++ // The live recording flag decides `.recording`, whatever the shared status says:+ // a previous job's delayed JS cleanup can write "idle" during the next recording,+ // and a "recording" status left without a live flag must not pause the timeout.+ precondition(outcome(status: "idle", recordingActive: true) == .recording)+ precondition(outcome(status: "no_speech", recordingActive: true) == .recording)+ precondition(outcome(status: "recording", recordingActive: false) == .pending)++ // The delivery clock is paused while recording and starts once the recording ends.+ precondition(HotkeyDecision.nextDeliveryDeadline(current: nil, outcome: .recording, nowMs: 1_000) == nil)+ precondition(HotkeyDecision.nextDeliveryDeadline(current: 9_999, outcome: .recording, nowMs: 1_000) == nil)+ precondition(HotkeyDecision.nextDeliveryDeadline(current: nil, outcome: .pending, nowMs: 1_000)+ == 1_000 + HotkeyDecision.deliveryTimeoutMs)+ precondition(HotkeyDecision.nextDeliveryDeadline(current: 5_000, outcome: .pending, nowMs: 9_000) == 5_000)++ // Banners: a timeout reads as a failure and frees the hotkey.+ precondition(HotkeyDecision.timeoutOutcome == .failed)+ precondition(HotkeyDecision.banner(for: .copy("x")) == .copied)+ precondition(HotkeyDecision.banner(for: .noSpeech) == .noSpeech)+ precondition(HotkeyDecision.banner(for: .failed) == .failed)+ precondition(HotkeyDecision.banner(for: .pending) == nil)+ precondition(HotkeyDecision.banner(for: .recording) == nil)+ precondition(HotkeyBanner.copied.body == "Copied — press ⌘V to paste")+ precondition(HotkeyBanner.stillTranscribing.body == "Still transcribing…")+ precondition(HotkeyBanner.openApp.body == "Open OpenWhispr to turn on dictation mode")+ precondition(HotkeyBanner.noSpeech.body == "No speech detected")+ precondition(HotkeyBanner.failed.body == "Couldn't transcribe — open OpenWhispr")++ // Only the newest banner's timer may clear it.+ do {+ var generations = BannerGenerations()+ let first = generations.next()+ let second = generations.next()+ precondition(!generations.isCurrent(first))+ precondition(generations.isCurrent(second))+ }++ // The JS-ready stamp only counts when this process wrote it.+ precondition(HotkeyDecision.isJsReadyStamp("4242:1790000000000", pid: 4242))+ precondition(!HotkeyDecision.isJsReadyStamp("4241:1790000000000", pid: 4242))+ precondition(!HotkeyDecision.isJsReadyStamp("1790000000000", pid: 4242))+ precondition(!HotkeyDecision.isJsReadyStamp(nil, pid: 4242))+ precondition(!HotkeyDecision.isJsReadyStamp("", pid: 4242))++ // runColdStart: JS ready at t=250 → start; start never runs before ready.+ do {+ let clock = FakeClock()+ var calls: [String] = []+ let result = await HotkeyDecision.runColdStart(ColdStartDeps(+ isJsReady: { clock.now >= 250 },+ startWarm: {+ precondition(clock.now >= 250, "start posted before JS was ready")+ calls.append("start")+ return "job"+ },+ sleepMs: clock.sleep,+ nowMs: { clock.now }))+ precondition(result == .started(jobId: "job"))+ precondition(calls == ["start"])+ }+ // runColdStart: JS never ready → nothing started, gives up after 8 s.+ do {+ let clock = FakeClock()+ var calls: [String] = []+ let result = await HotkeyDecision.runColdStart(ColdStartDeps(+ isJsReady: { false },+ startWarm: { calls.append("start"); return "job" },+ sleepMs: clock.sleep,+ nowMs: { clock.now }))+ precondition(result == .jsNotReady)+ precondition(calls.isEmpty)+ precondition(clock.now >= HotkeyDecision.jsReadyTimeoutMs)+ }+ // runColdStart: ready but the recording never starts.+ do {+ let clock = FakeClock()+ let result = await HotkeyDecision.runColdStart(ColdStartDeps(+ isJsReady: { true },+ startWarm: { nil },+ sleepMs: clock.sleep,+ nowMs: { clock.now }))+ precondition(result == .startFailed)+ }+ // waitUntil returns true as soon as the check passes, false at the deadline.+ do {+ let clock = FakeClock()+ let hit = await HotkeyDecision.waitUntil(+ timeoutMs: 2_000, nowMs: { clock.now }, sleepMs: clock.sleep) { clock.now >= 300 }+ precondition(hit && clock.now == 300)+ let miss = await HotkeyDecision.waitUntil(+ timeoutMs: 2_000, nowMs: { clock.now }, sleepMs: clock.sleep) { false }+ precondition(!miss)+ }++ print("HotkeyDictationLogicTests passed")+ }+}diff --git a/openwhispr-mobile/plugins/hotkey-dictation/tests/run-hotkey-logic-tests.py b/openwhispr-mobile/plugins/hotkey-dictation/tests/run-hotkey-logic-tests.pynew file mode 100644index 000000000..c3cbfc9d8--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/tests/run-hotkey-logic-tests.py@@ -0,0 +1,20 @@+"""Compile and run the hotkey dictation decision tests (Foundation only, no simulator)."""+from pathlib import Path+import subprocess+import tempfile+++def main():+ plugin = Path(__file__).resolve().parents[1]+ with tempfile.TemporaryDirectory(prefix="hotkey-logic-") as output:+ executable = str(Path(output) / "tests")+ subprocess.run([+ "swiftc", "-swift-version", "5", "-o", executable,+ str(plugin / "ios/HotkeyDictationLogic.swift"),+ str(plugin / "tests/HotkeyDictationLogicTests.swift"),+ ], check=True)+ subprocess.run([executable], check=True)+++if __name__ == "__main__":+ main()diff --git a/openwhispr-mobile/plugins/hotkey-dictation/withHotkeyDictation.js b/openwhispr-mobile/plugins/hotkey-dictation/withHotkeyDictation.jsnew file mode 100644index 000000000..6e2c4f703--- /dev/null+++ b/openwhispr-mobile/plugins/hotkey-dictation/withHotkeyDictation.js@@ -0,0 +1,96 @@+/**+ * Expo config plugin that compiles the hotkey dictation Swift sources into the+ * main app target.+ *+ * Why the app target and not a module pod: App Intents metadata (and the+ * AppShortcutsProvider that surfaces the action in Shortcuts) is extracted from+ * the app target's own sources, and the intent must run in the app's process,+ * where the warm-mic session lives.+ */++const { withDangerousMod, withXcodeProject } = require('expo/config-plugins');+const fs = require('fs');+const path = require('path');++const SOURCE_DIR = path.join(__dirname, 'ios');++function sourceFiles() {+ return fs+ .readdirSync(SOURCE_DIR)+ .filter((name) => name.endsWith('.swift'))+ .sort();+}++function findMainGroupKey(xcodeProject, projectName) {+ const groups = xcodeProject.hash.project.objects.PBXGroup || {};+ for (const key of Object.keys(groups)) {+ if (key.endsWith('_comment')) continue;+ const group = groups[key];+ if (group?.name === projectName || group?.path === projectName) return key;+ }+ return null;+}++function findMainTargetUuid(xcodeProject, projectName) {+ const targets = xcodeProject.pbxNativeTargetSection() || {};+ for (const key of Object.keys(targets)) {+ if (key.endsWith('_comment')) continue;+ if ((targets[key]?.name ?? '').replace(/"/g, '') === projectName) return key;+ }+ return null;+}++function hasFileReference(xcodeProject, fileName) {+ const refs = xcodeProject.pbxFileReferenceSection() || {};+ return Object.keys(refs).some((key) => {+ if (key.endsWith('_comment')) return false;+ const ref = refs[key];+ return (ref?.path ?? ref?.name ?? '').replace(/"/g, '').endsWith(`/${fileName}`);+ });+}++module.exports = function withHotkeyDictation(config) {+ config = withDangerousMod(config, [+ 'ios',+ async (cfg) => {+ const projectName = cfg.modRequest.projectName ?? 'OpenWhispr';+ for (const fileName of sourceFiles()) {+ fs.copyFileSync(+ path.join(SOURCE_DIR, fileName),+ path.join(cfg.modRequest.platformProjectRoot, projectName, fileName),+ );+ }+ return cfg;+ },+ ]);++ config = withXcodeProject(config, (cfg) => {+ const xcodeProject = cfg.modResults;+ const projectName = cfg.modRequest.projectName ?? 'OpenWhispr';+ const groupKey = findMainGroupKey(xcodeProject, projectName);+ const targetUuid = findMainTargetUuid(xcodeProject, projectName);+ if (!groupKey || !targetUuid) {+ console.warn('[hotkey-dictation] Could not find the main group or target');+ return cfg;+ }+ for (const fileName of sourceFiles()) {+ if (hasFileReference(xcodeProject, fileName)) continue;+ // Same shape as AppDelegate.swift: a <group>-relative path under the unpathed main group.+ const file = xcodeProject.addSourceFile(+ `${projectName}/${fileName}`,+ { target: targetUuid, lastKnownFileType: 'sourcecode.swift' },+ groupKey,+ );+ // The xcode lib leaks undefined fields as literal "undefined" strings; an+ // explicitFileType of "undefined" would override the Swift file type.+ const ref = file && xcodeProject.pbxFileReferenceSection()[file.fileRef];+ if (ref) {+ delete ref.explicitFileType;+ delete ref.includeInIndex;+ }+ }+ return cfg;+ });++ return config;+};diff --git a/openwhispr-mobile/src/components/features/HardwareKeyboardNudgeBanner.tsx b/openwhispr-mobile/src/components/features/HardwareKeyboardNudgeBanner.tsxnew file mode 100644index 000000000..aa0a145b7--- /dev/null+++ b/openwhispr-mobile/src/components/features/HardwareKeyboardNudgeBanner.tsx@@ -0,0 +1,75 @@+import { useCallback } from 'react';+import { Platform, Pressable, View } from 'react-native';+import { router } from 'expo-router';+import { Text } from '@/components/ui/Text';+import { SystemIcon } from '@/components/ui/SystemIcon';+import { useHardwareKeyboardConnected } from '@/hooks/useHardwareKeyboardConnected';+import { useConfigStore } from '@/store/useConfigStore';+import { safeHaptics } from '@/lib/utils';++/**+ * One-time Home card shown the first time a hardware keyboard is attached,+ * pointing at the hardware-keyboard dictation shortcut. Opening the guide or+ * dismissing both count as seen.+ */+export function HardwareKeyboardNudgeBanner() {+ const connected = useHardwareKeyboardConnected();+ const config = useConfigStore((state) => state.config);+ const updateConfig = useConfigStore((state) => state.updateConfig);++ const markSeen = useCallback(() => {+ updateConfig({ hardwareKeyboardNudgeDismissedAt: new Date().toISOString() });+ }, [updateConfig]);++ const open = useCallback(() => {+ safeHaptics('selection');+ markSeen();+ router.push('/(account)/hardware-keyboard');+ }, [markSeen]);++ const dismiss = useCallback(() => {+ safeHaptics('light');+ markSeen();+ }, [markSeen]);++ // No config yet means we can't know it was dismissed; wait rather than flash.+ if (Platform.OS !== 'ios' || !connected || !config || config.hardwareKeyboardNudgeDismissedAt) {+ return null;+ }++ return (+ <View+ className="mt-3 flex-row items-center gap-2 rounded-xl border border-separator bg-secondarySystemGroupedBackground p-3"+ style={{ borderCurve: 'continuous' }}+ testID="hardware-keyboard-nudge"+ >+ <Pressable+ onPress={open}+ accessibilityRole="button"+ accessibilityLabel="Using a keyboard? Dictate into any app with a shortcut"+ accessibilityHint="Shows how to set up the hardware keyboard shortcut"+ testID="hardware-keyboard-nudge-cta"+ className="min-w-0 flex-1 flex-row items-center gap-3"+ style={({ pressed }) => ({ opacity: pressed ? 0.85 : 1 })}+ >+ <View className="h-9 w-9 items-center justify-center rounded-lg bg-tertiarySystemFill">+ <SystemIcon name="command" mdName="Command" size={20} color="brand" />+ </View>+ <Text className="min-w-0 flex-1 text-[15px] font-medium text-label">+ Using a keyboard? Dictate into any app with a shortcut+ </Text>+ <SystemIcon name="chevron.right" mdName="ChevronRight" size={14} color="tertiaryLabel" />+ </Pressable>+ <Pressable+ onPress={dismiss}+ accessibilityRole="button"+ accessibilityLabel="Dismiss hardware keyboard tip"+ testID="hardware-keyboard-nudge-dismiss"+ className="h-8 w-8 items-center justify-center rounded-full"+ style={({ pressed }) => ({ opacity: pressed ? 0.6 : 1 })}+ >+ <SystemIcon name="xmark" mdName="X" size={14} color="secondaryLabel" />+ </Pressable>+ </View>+ );+}diff --git a/openwhispr-mobile/src/components/features/__tests__/HardwareKeyboardNudgeBanner.test.tsx b/openwhispr-mobile/src/components/features/__tests__/HardwareKeyboardNudgeBanner.test.tsxnew file mode 100644index 000000000..a6ce26e86--- /dev/null+++ b/openwhispr-mobile/src/components/features/__tests__/HardwareKeyboardNudgeBanner.test.tsx@@ -0,0 +1,75 @@+import React from 'react';+import { fireEvent, render, screen } from '@testing-library/react-native';++const mockRouterPush = jest.fn();+const mockUpdateConfig = jest.fn(async () => undefined);+let mockConnected = true;+let mockConfig: Record<string, unknown> | null = {};++jest.mock('expo-router', () => ({+ router: { push: (...args: unknown[]) => mockRouterPush(...args) },+}));+jest.mock('@/components/ui/Text', () => ({ Text: require('react-native').Text }));+jest.mock('@/components/ui/SystemIcon', () => ({ SystemIcon: () => null }));+jest.mock('@/lib/utils', () => ({+ ...jest.requireActual('@/lib/utils'),+ safeHaptics: jest.fn(),+}));+jest.mock('@/hooks/useHardwareKeyboardConnected', () => ({+ useHardwareKeyboardConnected: () => mockConnected,+}));+jest.mock('@/store/useConfigStore', () => ({+ useConfigStore: (selector: (state: unknown) => unknown) =>+ selector({ config: mockConfig, updateConfig: mockUpdateConfig }),+}));++import { HardwareKeyboardNudgeBanner } from '../HardwareKeyboardNudgeBanner';++beforeEach(() => {+ jest.clearAllMocks();+ mockConnected = true;+ mockConfig = {};+});++describe('HardwareKeyboardNudgeBanner', () => {+ it('shows when a hardware keyboard is connected and it was never dismissed', () => {+ render(<HardwareKeyboardNudgeBanner />);+ expect(screen.getByTestId('hardware-keyboard-nudge')).toBeTruthy();+ });++ it('stays hidden without a hardware keyboard', () => {+ mockConnected = false;+ render(<HardwareKeyboardNudgeBanner />);+ expect(screen.queryByTestId('hardware-keyboard-nudge')).toBeNull();+ });++ it('stays hidden once dismissed', () => {+ mockConfig = { hardwareKeyboardNudgeDismissedAt: '2026-09-25T00:00:00.000Z' };+ render(<HardwareKeyboardNudgeBanner />);+ expect(screen.queryByTestId('hardware-keyboard-nudge')).toBeNull();+ });++ it('stays hidden until the config has loaded', () => {+ mockConfig = null;+ render(<HardwareKeyboardNudgeBanner />);+ expect(screen.queryByTestId('hardware-keyboard-nudge')).toBeNull();+ });++ it('opens the guide and marks the nudge seen', () => {+ render(<HardwareKeyboardNudgeBanner />);+ fireEvent.press(screen.getByTestId('hardware-keyboard-nudge-cta'));+ expect(mockRouterPush).toHaveBeenCalledWith('/(account)/hardware-keyboard');+ expect(mockUpdateConfig).toHaveBeenCalledWith({+ hardwareKeyboardNudgeDismissedAt: expect.any(String),+ });+ });++ it('dismisses without navigating', () => {+ render(<HardwareKeyboardNudgeBanner />);+ fireEvent.press(screen.getByTestId('hardware-keyboard-nudge-dismiss'));+ expect(mockRouterPush).not.toHaveBeenCalled();+ expect(mockUpdateConfig).toHaveBeenCalledWith({+ hardwareKeyboardNudgeDismissedAt: expect.any(String),+ });+ });+});diff --git a/openwhispr-mobile/src/hooks/__tests__/useHardwareKeyboardConnected.test.ts b/openwhispr-mobile/src/hooks/__tests__/useHardwareKeyboardConnected.test.tsnew file mode 100644index 000000000..45891826f--- /dev/null+++ b/openwhispr-mobile/src/hooks/__tests__/useHardwareKeyboardConnected.test.ts@@ -0,0 +1,44 @@+import { act, renderHook } from '@testing-library/react-native';++let mockConnected = false;+let mockListener: ((event: { connected: boolean }) => void) | undefined;+const mockRemove = jest.fn();++jest.mock('../../../modules/app-group-storage/src', () => ({+ AppGroupStorage: { isHardwareKeyboardConnected: () => mockConnected },+ addHardwareKeyboardChangedListener: (listener: (event: { connected: boolean }) => void) => {+ mockListener = listener;+ return { remove: mockRemove };+ },+}));++import { useHardwareKeyboardConnected } from '../useHardwareKeyboardConnected';++beforeEach(() => {+ mockConnected = false;+ mockListener = undefined;+ mockRemove.mockClear();+});++describe('useHardwareKeyboardConnected', () => {+ it('starts from the native state', () => {+ mockConnected = true;+ const { result } = renderHook(() => useHardwareKeyboardConnected());+ expect(result.current).toBe(true);+ });++ it('follows connect and disconnect events', () => {+ const { result } = renderHook(() => useHardwareKeyboardConnected());+ expect(result.current).toBe(false);+ act(() => mockListener?.({ connected: true }));+ expect(result.current).toBe(true);+ act(() => mockListener?.({ connected: false }));+ expect(result.current).toBe(false);+ });++ it('unsubscribes on unmount', () => {+ const { unmount } = renderHook(() => useHardwareKeyboardConnected());+ unmount();+ expect(mockRemove).toHaveBeenCalled();+ });+});diff --git a/openwhispr-mobile/src/hooks/__tests__/useKeyboardHandoff.fullAccessRoute.test.ts b/openwhispr-mobile/src/hooks/__tests__/useKeyboardHandoff.fullAccessRoute.test.tsindex 0deb917c2..4ccbd6419 100644--- a/openwhispr-mobile/src/hooks/__tests__/useKeyboardHandoff.fullAccessRoute.test.ts+++ b/openwhispr-mobile/src/hooks/__tests__/useKeyboardHandoff.fullAccessRoute.test.ts@@ -51,6 +51,7 @@ jest.mock('../../../modules/app-group-storage/src', () => ({startNativeRecording: jest.fn(() => true),returnToPreviousApp: jest.fn(),stopNativeRecording: jest.fn(),+ markHotkeyJsReady: jest.fn(),},APP_GROUP_KEYS: {KEYBOARD_RECORDING_JOB_ID: 'keyboard_recording_job_id',@@ -64,6 +65,7 @@ jest.mock('../../../modules/app-group-storage/src', () => ({KEYBOARD_CANCEL_REQUESTED: 'keyboard_cancel_requested',KEYBOARD_COMPRESSED_AUDIO_UNSUPPORTED: 'keyboard_compressed_audio_unsupported',KEYBOARD_COMPRESSED_AUDIO_UNSUPPORTED_AT_MS: 'keyboard_compressed_audio_unsupported_at_ms',+ HOTKEY_JS_READY_AT_MS: 'hotkey_js_ready_at_ms',},addRecordingStoppedListener: (listener: (event: RecordingStoppedEvent) => Promise<void>) => {mockRecordingStoppedListener = listener;@@ -180,6 +182,7 @@ const storage = AppGroupStorage as unknown as {startNativeRecording: jest.Mock;stopNativeRecording: jest.Mock;returnToPreviousApp: jest.Mock;+ markHotkeyJsReady: jest.Mock;};function mountWithInitialUrl(url: string) {@@ -770,3 +773,28 @@ describe('provider job lifecycle', () => {expect(storage.setKeyboardStatus).toHaveBeenCalledWith('agent_error', 'agent_setup_required');});});++describe('useKeyboardHandoff — hotkey readiness', () => {+ // The hotkey's cold start waits for this key before it records, so it must+ // only appear once both recording listeners exist.+ it('marks JS ready only after the recording listeners are subscribed', () => {+ mockBackgroundStartedListener = undefined;+ let listenersAtReady: [boolean, boolean] | undefined;+ // The native side stamps the process id, so a stamp left by a dead process+ // never makes a fresh launch look ready.+ storage.markHotkeyJsReady.mockImplementation(() => {+ listenersAtReady = [!!mockRecordingStoppedListener, !!mockBackgroundStartedListener];+ });++ mountWithInitialUrl('');++ expect(storage.markHotkeyJsReady).toHaveBeenCalledTimes(1);+ expect(listenersAtReady).toEqual([true, true]);+ });++ it('clears the ready key on unmount', () => {+ const { unmount } = mountWithInitialUrl('');+ unmount();+ expect(storage.removeItem).toHaveBeenCalledWith('hotkey_js_ready_at_ms');+ });+});diff --git a/openwhispr-mobile/src/hooks/useHardwareKeyboardConnected.ts b/openwhispr-mobile/src/hooks/useHardwareKeyboardConnected.tsnew file mode 100644index 000000000..b13c292b9--- /dev/null+++ b/openwhispr-mobile/src/hooks/useHardwareKeyboardConnected.ts@@ -0,0 +1,18 @@+import { useEffect, useState } from 'react';+import {+ AppGroupStorage,+ addHardwareKeyboardChangedListener,+} from '../../modules/app-group-storage/src';++export function useHardwareKeyboardConnected(): boolean {+ const [connected, setConnected] = useState(() => AppGroupStorage.isHardwareKeyboardConnected());++ useEffect(() => {+ const subscription = addHardwareKeyboardChangedListener(({ connected: next }) =>+ setConnected(next),+ );+ return () => subscription?.remove();+ }, []);++ return connected;+}diff --git a/openwhispr-mobile/src/hooks/useKeyboardHandoff.ts b/openwhispr-mobile/src/hooks/useKeyboardHandoff.tsindex 625d17277..11422f73e 100644--- a/openwhispr-mobile/src/hooks/useKeyboardHandoff.ts+++ b/openwhispr-mobile/src/hooks/useKeyboardHandoff.ts@@ -1170,6 +1170,11 @@ export function useKeyboardHandoff() {// dropped poke is handled by handlePendingHandoffIntent.const agentActionSub = addAgentActionListener(() => runAgentAction('poke'));+ // The hardware-keyboard hotkey (plugins/hotkey-dictation) waits for this+ // before a cold-start recording, so native never records before the+ // started/stopped listeners above exist.+ AppGroupStorage.markHotkeyJsReady();+runOrphanCleanup('mount');const orphanPoll = setInterval(() => {runOrphanCleanup('watchdog');@@ -1205,6 +1210,7 @@ export function useKeyboardHandoff() {bgStartedSub?.remove();statusSub?.remove();agentActionSub?.remove();+ AppGroupStorage.removeItem(APP_GROUP_KEYS.HOTKEY_JS_READY_AT_MS);urlSub.remove();appStateSub.remove();clearInterval(orphanPoll);diff --git a/openwhispr-mobile/src/screens/HardwareKeyboardShortcutScreen.tsx b/openwhispr-mobile/src/screens/HardwareKeyboardShortcutScreen.tsxnew file mode 100644index 000000000..ab4560236--- /dev/null+++ b/openwhispr-mobile/src/screens/HardwareKeyboardShortcutScreen.tsx@@ -0,0 +1,164 @@+import React, { useCallback, useEffect, useState } from 'react';+import { AppState, Linking, View } from 'react-native';+import {+ SettingsRow,+ SettingsSection,+ SettingsTextFieldRow,+} from '@/components/ui/SettingsSection';+import { SettingsScreen } from '@/components/ui/SettingsScreen';+import { SettingsSwitch } from '@/components/ui/SettingsSwitch';+import { SystemIcon } from '@/components/ui/SystemIcon';+import { Text } from '@/components/ui/Text';+import {+ getNotificationStatus,+ requestNotifications,+ type NotificationStatus,+} from '@/lib/notifications';+import { LiveActivity } from '../../modules/live-activity/src';++export const SHORTCUTS_CREATE_URL = 'shortcuts://create-shortcut';+export const SHORTCUTS_APP_URL = 'shortcuts://';+const SUGGESTED_COMBO = '⌃⌥D';++// iOS can refuse the editor deep link. The Shortcuts app itself is enough, since+// step 2 says which action to add, and a refusal must never become an error screen.+async function openShortcuts(): Promise<void> {+ try {+ await Linking.openURL(SHORTCUTS_CREATE_URL);+ } catch {+ await Linking.openURL(SHORTCUTS_APP_URL).catch(() => undefined);+ }+}++/**+ * Setup for dictating from a hardware keyboard (plugins/hotkey-dictation).+ * iPadOS hides third-party keyboards while a hardware keyboard is attached, so+ * the path is a Shortcuts action bound to a Full Keyboard Access command, with+ * the transcript delivered on the clipboard. Apple doesn't allow deep links into+ * Accessibility settings, so steps 3 and 4 are written out.+ */+export function HardwareKeyboardShortcutScreen() {+ const [dictationMode, setDictationMode] = useState(() => LiveActivity.isDictationModeEnabled());+ const [notificationStatus, setNotificationStatus] = useState<NotificationStatus | null>(null);+ const [tryText, setTryText] = useState('');++ const refreshNotificationStatus = useCallback(() => {+ getNotificationStatus()+ .then(setNotificationStatus)+ .catch(() => setNotificationStatus('unavailable'));+ }, []);++ // Re-read on return from Settings, where a denied user may have allowed them.+ useEffect(() => {+ refreshNotificationStatus();+ const subscription = AppState.addEventListener('change', (state) => {+ if (state === 'active') refreshNotificationStatus();+ });+ return () => subscription.remove();+ }, [refreshNotificationStatus]);++ const handleNotifications = useCallback(async () => {+ if (notificationStatus === 'denied') {+ await Linking.openSettings();+ return;+ }+ setNotificationStatus(await requestNotifications());+ }, [notificationStatus]);++ const needsNotifications =+ notificationStatus === 'undetermined' || notificationStatus === 'denied';+ const tried = tryText.trim().length > 0;++ return (+ <SettingsScreen>+ <Text className="px-4 pb-2 text-[15px] text-secondaryLabel">+ Press a key combination in any app to start dictating, press it again to stop, then press ⌘V+ to paste.+ </Text>+ <SettingsSection title="1. Dictation mode">+ <SettingsRow+ iconStyle="line"+ icon="waveform"+ mdIcon="Activity"+ title="Dictation mode"+ description="Keep this on so the shortcut starts recording instantly."+ rightElement={+ <SettingsSwitch+ testID="hardware-keyboard-dictation-mode"+ value={dictationMode}+ onValueChange={(next) => {+ LiveActivity.setDictationMode(next);+ setDictationMode(next);+ }}+ />+ }+ showChevron={false}+ />+ </SettingsSection>+ <SettingsSection title="2. Add the shortcut">+ <SettingsRow+ iconStyle="line"+ icon="square.stack.3d.up"+ mdIcon="Layers"+ title="Open Shortcuts"+ description="Add the “Toggle OpenWhispr Dictation” action, then tap Done."+ onPress={openShortcuts}+ />+ </SettingsSection>+ <SettingsSection title="3. Turn on Full Keyboard Access">+ <SettingsRow+ iconStyle="line"+ icon="keyboard"+ mdIcon="Keyboard"+ title="Settings → Accessibility → Keyboards & Typing → Full Keyboard Access"+ description="Turn the Full Keyboard Access switch on. The shortcut does nothing while it is off."+ showChevron={false}+ />+ </SettingsSection>+ <SettingsSection title="4. Assign a key combination">+ <SettingsRow+ iconStyle="line"+ icon="command"+ mdIcon="Command"+ title="Commands → Shortcuts → Toggle OpenWhispr Dictation"+ description={`Press the keys you want to use. ${SUGGESTED_COMBO} (Control-Option-D) is free by default.`}+ showChevron={false}+ />+ </SettingsSection>+ {needsNotifications ? (+ <SettingsSection title="5. Allow notifications">+ <SettingsRow+ iconStyle="line"+ icon="bell.badge"+ mdIcon="BellRing"+ title={notificationStatus === 'denied' ? 'Open Settings' : 'Allow notifications'}+ description="Shows “Copied — press ⌘V to paste” after each dictation."+ onPress={handleNotifications}+ />+ </SettingsSection>+ ) : null}+ <SettingsSection title="Try it">+ <SettingsTextFieldRow+ icon="text.cursor"+ mdIcon="TextCursorInput"+ placeholder={`Press ${SUGGESTED_COMBO}, speak, press it again, then ⌘V`}+ value={tryText}+ onChangeText={setTryText}+ testID="hardware-keyboard-try-it"+ trailing={+ tried ? (+ <View testID="hardware-keyboard-try-it-done">+ <SystemIcon+ name="checkmark.circle.fill"+ mdName="CircleCheck"+ size={20}+ color="systemGreen"+ />+ </View>+ ) : null+ }+ />+ </SettingsSection>+ </SettingsScreen>+ );+}diff --git a/openwhispr-mobile/src/screens/HomeScreen.tsx b/openwhispr-mobile/src/screens/HomeScreen.tsxindex fffa75e26..31ae01edc 100644--- a/openwhispr-mobile/src/screens/HomeScreen.tsx+++ b/openwhispr-mobile/src/screens/HomeScreen.tsx@@ -46,6 +46,7 @@ import { TranscriptModal } from '@/components/features/TranscriptModal';import { RecordingOverlay } from '@/components/features/RecordingOverlay';import { ParakeetNudgeBanner } from '@/components/features/ParakeetNudgeBanner';import { KeyboardFullAccessBanner } from '@/components/features/KeyboardFullAccessBanner';+import { HardwareKeyboardNudgeBanner } from '@/components/features/HardwareKeyboardNudgeBanner';import { SwipeableCard } from '@/components/ui/SwipeableCard';import { Glass } from '@/components/ui/Glass';import { CloudIcon } from '@/components/ui/CloudIcon';@@ -587,6 +588,7 @@ export default function HomeScreen() {<DictationModeControl onModeChange={handleDictationModeChange} /></View><KeyboardFullAccessBanner />+ <HardwareKeyboardNudgeBanner />{activeMode === 'cloud' ? (<UsageLimitBanner usage={usage} onPress={handleUsageWarningPress} />) : null}diff --git a/openwhispr-mobile/src/screens/PreferencesScreen.tsx b/openwhispr-mobile/src/screens/PreferencesScreen.tsxindex 93ecc6bfe..c6863ed44 100644--- a/openwhispr-mobile/src/screens/PreferencesScreen.tsx+++ b/openwhispr-mobile/src/screens/PreferencesScreen.tsx@@ -1,4 +1,5 @@import React, { useState } from 'react';+import { Platform } from 'react-native';import { router } from 'expo-router';import { SettingsRow, SettingsSection } from '@/components/ui/SettingsSection';import { SettingsScreen } from '@/components/ui/SettingsScreen';@@ -98,6 +99,16 @@ export default function PreferencesScreen() {}showChevron={false}/>+ {Platform.OS === 'ios' ? (+ <SettingsRow+ iconStyle="line"+ icon="command"+ mdIcon="Command"+ title="Hardware keyboard shortcut"+ description="Dictate into any app from a Magic Keyboard or other hardware keyboard"+ onPress={() => router.push('/(account)/hardware-keyboard')}+ />+ ) : null}</SettingsSection></SettingsScreen>);diff --git a/openwhispr-mobile/src/screens/__tests__/HardwareKeyboardShortcutScreen.test.tsx b/openwhispr-mobile/src/screens/__tests__/HardwareKeyboardShortcutScreen.test.tsxnew file mode 100644index 000000000..8ab0bdb11--- /dev/null+++ b/openwhispr-mobile/src/screens/__tests__/HardwareKeyboardShortcutScreen.test.tsx@@ -0,0 +1,119 @@+import React from 'react';+import { AppState, Linking } from 'react-native';+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react-native';++const mockGetStatus = jest.fn();+const mockRequest = jest.fn();+const mockSetDictationMode = jest.fn();++jest.mock('@/components/ui/Text', () => ({ Text: require('react-native').Text }));+jest.mock('@/components/ui/SystemIcon', () => ({ SystemIcon: () => null }));+jest.mock('@/lib/notifications', () => ({+ getNotificationStatus: () => mockGetStatus(),+ requestNotifications: () => mockRequest(),+}));+jest.mock('../../../modules/live-activity/src', () => ({+ LiveActivity: {+ isDictationModeEnabled: () => false,+ setDictationMode: (enabled: boolean) => mockSetDictationMode(enabled),+ },+}));++import {+ HardwareKeyboardShortcutScreen,+ SHORTCUTS_APP_URL,+ SHORTCUTS_CREATE_URL,+} from '../HardwareKeyboardShortcutScreen';++beforeEach(() => {+ jest.clearAllMocks();+ mockGetStatus.mockResolvedValue('granted');+ jest.spyOn(AppState, 'addEventListener').mockReturnValue({ remove: jest.fn() } as never);+ jest.spyOn(Linking, 'openURL').mockResolvedValue(true);+ jest.spyOn(Linking, 'openSettings').mockResolvedValue(undefined);+});++afterEach(() => {+ jest.restoreAllMocks();+});++describe('HardwareKeyboardShortcutScreen', () => {+ it('opens the Shortcuts editor for step 2', async () => {+ render(<HardwareKeyboardShortcutScreen />);+ fireEvent.press(screen.getByText('Open Shortcuts'));+ expect(Linking.openURL).toHaveBeenCalledWith(SHORTCUTS_CREATE_URL);+ await waitFor(() => expect(mockGetStatus).toHaveBeenCalled());+ });++ it('falls back to the Shortcuts app when the editor link cannot open', async () => {+ (Linking.openURL as jest.Mock)+ .mockRejectedValueOnce(new Error('Unable to open URL: shortcuts://create-shortcut'))+ .mockResolvedValueOnce(true);+ render(<HardwareKeyboardShortcutScreen />);+ await act(async () => {+ fireEvent.press(screen.getByText('Open Shortcuts'));+ });+ expect(Linking.openURL).toHaveBeenNthCalledWith(1, SHORTCUTS_CREATE_URL);+ expect(Linking.openURL).toHaveBeenNthCalledWith(2, SHORTCUTS_APP_URL);+ });++ it('does not throw when Shortcuts cannot be opened at all', async () => {+ (Linking.openURL as jest.Mock).mockRejectedValue(new Error('Unable to open URL'));+ render(<HardwareKeyboardShortcutScreen />);+ await act(async () => {+ fireEvent.press(screen.getByText('Open Shortcuts'));+ });+ expect(Linking.openURL).toHaveBeenCalledTimes(2);+ });++ it('turns dictation mode on from step 1', async () => {+ render(<HardwareKeyboardShortcutScreen />);+ fireEvent(screen.getByTestId('hardware-keyboard-dictation-mode'), 'valueChange', true);+ expect(mockSetDictationMode).toHaveBeenCalledWith(true);+ await waitFor(() => expect(mockGetStatus).toHaveBeenCalled());+ });++ it('stresses that the Full Keyboard Access switch must be on', async () => {+ render(<HardwareKeyboardShortcutScreen />);+ expect(screen.getByText(/The shortcut does nothing while it is off/)).toBeTruthy();+ await waitFor(() => expect(mockGetStatus).toHaveBeenCalled());+ });++ it('hides the notifications step once notifications are allowed', async () => {+ render(<HardwareKeyboardShortcutScreen />);+ await waitFor(() => expect(mockGetStatus).toHaveBeenCalled());+ expect(screen.queryByText('Allow notifications')).toBeNull();+ expect(screen.queryByText('Open Settings')).toBeNull();+ });++ it('asks for notification permission when undetermined', async () => {+ mockGetStatus.mockResolvedValue('undetermined');+ mockRequest.mockResolvedValue('granted');+ render(<HardwareKeyboardShortcutScreen />);+ const allow = await screen.findByText('Allow notifications');+ await act(async () => {+ fireEvent.press(allow);+ });+ expect(mockRequest).toHaveBeenCalled();+ expect(screen.queryByText('Allow notifications')).toBeNull();+ });++ it('sends a denied user to Settings instead of re-prompting', async () => {+ mockGetStatus.mockResolvedValue('denied');+ render(<HardwareKeyboardShortcutScreen />);+ const openSettings = await screen.findByText('Open Settings');+ await act(async () => {+ fireEvent.press(openSettings);+ });+ expect(Linking.openSettings).toHaveBeenCalled();+ expect(mockRequest).not.toHaveBeenCalled();+ });++ it('checks off the try-it step once text is pasted', async () => {+ render(<HardwareKeyboardShortcutScreen />);+ expect(screen.queryByTestId('hardware-keyboard-try-it-done')).toBeNull();+ fireEvent.changeText(screen.getByTestId('hardware-keyboard-try-it'), 'Hello from the hotkey');+ expect(screen.getByTestId('hardware-keyboard-try-it-done')).toBeTruthy();+ await waitFor(() => expect(mockGetStatus).toHaveBeenCalled());+ });+});diff --git a/openwhispr-mobile/src/screens/__tests__/HomeScreen.proCompletion.test.tsx b/openwhispr-mobile/src/screens/__tests__/HomeScreen.proCompletion.test.tsxindex 84ae60002..8591cd189 100644--- a/openwhispr-mobile/src/screens/__tests__/HomeScreen.proCompletion.test.tsx+++ b/openwhispr-mobile/src/screens/__tests__/HomeScreen.proCompletion.test.tsx@@ -143,6 +143,9 @@ jest.mock('@/components/features/ParakeetNudgeBanner', () => ({ ParakeetNudgeBanjest.mock('@/components/features/KeyboardFullAccessBanner', () => ({KeyboardFullAccessBanner: () => null,}));+jest.mock('@/components/features/HardwareKeyboardNudgeBanner', () => ({+ HardwareKeyboardNudgeBanner: () => null,+}));jest.mock('@/components/ui/SwipeableCard', () => ({SwipeableCard: ({ children }: { children: React.ReactNode }) => children,}));diff --git a/openwhispr-mobile/src/screens/__tests__/PreferencesScreen.hardwareKeyboard.test.tsx b/openwhispr-mobile/src/screens/__tests__/PreferencesScreen.hardwareKeyboard.test.tsxnew file mode 100644index 000000000..ce61f9400--- /dev/null+++ b/openwhispr-mobile/src/screens/__tests__/PreferencesScreen.hardwareKeyboard.test.tsx@@ -0,0 +1,31 @@+import React from 'react';+import { fireEvent, render, screen } from '@testing-library/react-native';++const mockRouterPush = jest.fn();++jest.mock('expo-router', () => ({+ router: { push: (...args: unknown[]) => mockRouterPush(...args) },+}));+jest.mock('@/components/ui/Text', () => ({ Text: require('react-native').Text }));+jest.mock('@/components/ui/SystemIcon', () => ({ SystemIcon: () => null }));+jest.mock('@/store/useConfigStore', () => ({+ useConfigStore: (selector: (state: unknown) => unknown) => selector({ config: null }),+}));+jest.mock('@/hooks/useConfigToggle', () => ({ useConfigToggle: () => jest.fn() }));+jest.mock('../../../modules/live-activity/src', () => ({+ LiveActivity: { isDictationModeEnabled: () => false, setDictationMode: jest.fn() },+}));++import PreferencesScreen from '../PreferencesScreen';++beforeEach(() => {+ jest.clearAllMocks();+});++describe('PreferencesScreen — hardware keyboard shortcut', () => {+ it('offers the setup guide in the Keyboard section', () => {+ render(<PreferencesScreen />);+ fireEvent.press(screen.getByText('Hardware keyboard shortcut'));+ expect(mockRouterPush).toHaveBeenCalledWith('/(account)/hardware-keyboard');+ });+});diff --git a/openwhispr-mobile/src/types/index.ts b/openwhispr-mobile/src/types/index.tsindex cfafa8709..f0e96cd26 100644--- a/openwhispr-mobile/src/types/index.ts+++ b/openwhispr-mobile/src/types/index.ts@@ -29,6 +29,9 @@ export interface UserConfig {// faster on-device model / download the faster model for a qualifying language.parakeetAutoLanguageNudgeDismissedAt?: string;parakeetUpgradeNudgeDismissedAt?: string;+ // One-time Home nudge toward the hardware-keyboard dictation shortcut, shown+ // the first time a hardware keyboard is attached.+ hardwareKeyboardNudgeDismissedAt?: string;keyboardTone?: KeyboardTone;// Apple Foundation Models local generation for notes. Default on; users can// disable it from AI Models.