Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

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.yml
index 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 tests
run: 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 tests
run: sh openwhispr-mobile/modules/live-activity/tests/run-resolver-tests.sh
diff --git a/openwhispr-mobile/app.base.json b/openwhispr-mobile/app.base.json
index 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.tsx
index 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.Screen
name="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.tsx
new file mode 100644
index 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.swift
index 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 ExpoModulesCore
import UIKit
import AVFoundation
+import GameController
public 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 = false
private 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.ts
index 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): EventSubscription
return 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.swift
new file mode 100644
index 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.swift
new file mode 100644
index 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.swift
new file mode 100644
index 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.swift
new file mode 100644
index 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.swift
new file mode 100644
index 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.swift
new file mode 100644
index 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.py
new file mode 100644
index 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.js
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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', () => ({ ParakeetNudgeBan
jest.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.tsx
new file mode 100644
index 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.ts
index 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.