Flow-Style Voice Dictation App for macOS and Windows

OpenDictate — Product & Technical Specification #

An open source, system-wide AI dictation app that turns speech into clean, context-formatted text in any macOS or Windows app.

Overview #

Typing is slower than speaking. Built-in operating system dictation produces raw, unformatted text that ignores context, so every dictated sentence has to be cleaned up by hand — punctuation, capitalization, filler words, tone. The polished commercial tools that solve this are closed source, subscription-priced, and route every word a user speaks through a vendor's servers.

OpenDictate solves the same problem with a different shape. It is a system-wide dictation app: the user presses a global hotkey anywhere in the operating system, speaks, and cleanly formatted text appears in whatever application had focus — an email, a Slack message, a code comment, a terminal, a web form. No per-application plugin. The text is punctuated, de-filled, and tone-matched to where it is going: formal in a document, casual in a chat window. A second hotkey opens Command Mode, where the user speaks an instruction against selected text — "make this shorter", "translate to French", "turn this into bullet points" — and the selection is rewritten in place.

The product is fully open source under the MIT license and has no hosted backend of any kind. There are no accounts, no billing, no company servers, and nothing to sign up for. Users supply their own API keys for a speech-to-text provider and a language-model provider; those keys are encrypted into the operating system keychain and are transmitted only to the provider that issued them. The complete list of network destinations the application will ever contact is three: the user's chosen speech provider, the user's chosen language provider, and the update feed — which can be switched off. Settings move between a user's own machines through a local export file, not a sync service.

This specification is written to be executed cold by an AI coding agent or a small engineering team, without clarifying questions. Every default is chosen, every validation rule is stated, every error path is defined, and every cross-cutting concern has exactly one canonical section that the others reference rather than restate. Where a judgement call was required, the call has been made and recorded in Section 40.10 rather than left open.

Scope boundary. Version 1.0 covers macOS and Windows desktop only. Mobile applications, meeting transcription and notetaking, team and enterprise administration, offline on-device processing, wake-word activation, custom-trained models, and a browser extension are all explicitly out of scope and are treated as non-goals throughout — see Section 2.4 for the reasoning behind each exclusion.

How to read this document #

The Parts below map to the order of work: decide (1–3), set up (4–6), build the operating-system layer (7–11), the speech and AI pipeline (12–16), storage and personalization (17–23), the interface (24–29), then harden and ship (30–37). Sections 38–39 drive execution, with 40 as reference. Sections 30, 31, 32 and 40 are the canonical sources for the error model, performance budgets, security posture, and the error-code, settings, language and shortcut registries — other sections cite them by number and never redefine them.

Table of Contents #

Part I — Foundation

1. Before You Start — Customization Q&A
2. Project Overview & Vision
3. Product Requirements & User Stories
4. Technology Stack & Architecture
5. Repository Structure & Code Conventions
6. Process Model, IPC & Application Lifecycle

Part II — Operating System Integration

1. Global Hotkey & Activation System
2. Audio Capture & Streaming Pipeline
3. Active Application & Context Detection
4. Text Insertion Engine
5. OS Permissions & Platform Differences

Part III — Speech & AI Pipeline

1. Speech-to-Text Provider Layer
2. LLM Formatting & Cleanup Engine
3. Context-Aware Tone Adaptation
4. Command Mode
5. Prompt Templates & Model Contracts

Part IV — Data, Personalization & Privacy

1. Local Data Model & Persistence
2. API Key & Secret Management
3. Personal Dictionary
4. Voice Snippets
5. Multi-Language Support
6. Dictation History & Privacy Controls
7. Settings Export & Import

Part V — Interface & Experience

1. Design System & Visual Language
2. Tray / Menu Bar & Recording HUD
3. Settings & Preferences UI
4. Onboarding & First-Run Experience
5. Accessibility
6. Notifications, Empty States & Error Surfaces

Part VI — Quality, Security & Operations

1. Error Handling, Resilience & Degraded Modes
2. Performance & Latency Budgets
3. Security & Privacy Architecture
4. Logging & Diagnostics
5. Testing Strategy
6. Build, Packaging, Signing & Distribution
7. Auto-Update
8. Open Source Project Governance & CI

Part VII — Execution

1. Milestones & Execution Plan
2. Executor Instructions
3. Appendices & Canonical Registries

1. Before You Start — Customization Q&A #

If you change nothing, the defaults below are the spec. Every default is already wired into the sections that follow; changing one means updating the referenced section(s) before you build against it.

2. Project Overview & Vision #

2.1 Problem statement #

Typing is the bottleneck between a thought and a written artifact. Most knowledge workers speak at 130–170 words per minute and type at 40–60, yet the dictation tools bundled with macOS and Windows haven't closed that gap: they transcribe phonemes to raw text and stop. The user still says "period," still manually capitalizes sentence starts the OS gets wrong, still deletes "um," "like," and restarted sentences, and still gets identical robotic phrasing whether messaging a friend on Slack or drafting a client-facing email. The cognitive tax of speaking cleanly enough for raw ASR to be usable defeats dictation's speed advantage.

A newer generation of tools — Wispr Flow chief among them — has solved the formatting half of this problem by piping raw transcripts through an LLM cleanup pass before insertion. But that category is closed-source, subscription-priced, and routes both audio and text through the vendor's own servers and account system — a non-starter for privacy-conscious users, organizations with data-handling policies, and anyone who doesn't want a recurring bill for a feature that is fundamentally "call two APIs and paste the result."

OpenDictate closes that gap without the trust and cost tradeoffs: an open-source, system-wide dictation layer that streams speech to a transcription API, cleans and formats the result with an LLM, and inserts the finished text into whatever application has focus — using API keys and provider accounts the user already controls. OpenDictate operates no servers of its own.

2.2 Personas #

2.2.1 Dana, Knowledge Worker #

Dana runs marketing operations at a 40-person startup, moving all day between Gmail, Slack, Notion, and Google Docs. She holds Fn in Gmail to dictate paragraphs a polished Mail tone preset formats as a formal reply; in Slack the same hotkey applies the casual preset, keeping phrasing loose rather than formalizing it. Drafting a campaign brief in Notion, she runs Command Mode on a paragraph — "make this a bulleted list" — and it restructures in place. Dana's job-to-be-done: turn spoken thought into finished, context-appropriate written communication faster than typing, without sounding like a transcript.

2.2.2 Marcus, Developer #

Marcus is a backend engineer who dictates commit messages, code comments, and design notes: sustained typing after eight hours at the keyboard is fatiguing, and talking through a problem helps him think. He dictates into his terminal — git commit -m plus a dictated sentence — and inline VS Code comments. The terminal is the hard case: some shells/emulators expose no accessibility text-insertion target and reject clipboard paste for certain prompts, so OpenDictate's synthetic-keystroke fallback matters for him specifically. He also dictates daily notes into a scratch Markdown file; the neutral tone preset (Section 14 maps Code/Terminal to neutral, not a separate preset) strips LLM-added softening filler ("I think we could maybe possibly..." becomes "we should"). Marcus's job-to-be-done: dictate reliably into every text surface a developer uses, including ones that don't play nicely with the OS clipboard, without injecting a corporate-email tone into code comments.

2.2.3 Priya, Privacy-Conscious Professional #

Priya is a therapist who also handles her practice's billing correspondence and client intake notes. She won't use a dictation tool that phones a company's server with clients' names and circumstances attached, nor pay a subscription for something used maybe twenty minutes a day. She read OpenDictate's source, confirmed the only three network destinations it ever contacts (Section 32), configured her own Deepgram and OpenAI keys, and enabled Privacy Mode so nothing is retained locally either. Her job-to-be-done: get the productivity benefit of AI dictation while retaining full, verifiable control over where her spoken and written data goes — including the option to keep zero history on disk.

2.3 Product thesis #

Dictation quality is now bottlenecked by formatting and context, not transcription accuracy — commodity STT APIs from Deepgram, OpenAI, and Groq already transcribe speech more accurately than most users articulate it. The differentiator is the layer on top: removing disfluencies, resolving self-corrections, matching tone to the destination app, and letting the user issue voice commands over the result. That layer is a thin orchestration problem — audio in, two API calls, text out — that needs no company, backend, or subscription to deliver. OpenDictate's thesis: this category should be a free, auditable, MIT-licensed utility that individuals configure with their own API keys, the same way git doesn't require GitHub and a text editor doesn't require a cloud account.

2.4 Non-goals #

• iOS and Android mobile apps. v1 is built on Electron's accessibility/text-injection APIs, with no mobile-OS equivalent without a fundamentally different native app per platform; deferred to a later, separately-scoped phase.
• Meeting transcription / notetaker product. Continuous multi-speaker, multi-hour transcription with diarization and summarization has different latency, storage, and consent needs than short push-to-talk dictation, and would pull the codebase toward recording-everything defaults conflicting with Section 32's privacy posture.
• Team or enterprise admin features (SSO, SCIM, audit logs, shared team dictionaries, MDM). Require a hosted backend and account system, which OpenDictate deliberately does not have.
• Offline or fully local/on-device processing (no bundled local ASR model). A bundled local model (e.g., Whisper.cpp) would meaningfully increase install size, require per-platform GPU/CPU acceleration engineering, and be materially less accurate than hosted STT on constrained hardware; offline-dictation users are already served by the OS's built-in option.
• Wake-word ("hands-free") activation. Always-listening wake-word detection requires continuous microphone access and on-device keyword-spotting, conflicting with the "audio only streamed from memory during an active recording, never persisted or continuously sampled" privacy stance, and raises the idle CPU/battery budget in Section 31.
• Custom-trained proprietary speech or language models. Training and hosting custom models requires infrastructure, a training pipeline, and ongoing MLOps investment contradicting the zero-backend, zero-cost-to-maintainer model; commodity provider APIs are treated as interchangeable, swappable adapters instead.
• Browser extension. Would only solve dictation inside the browser, duplicating the text-insertion problem Section 10 already solves system-wide, while adding a second distribution channel, review process, and permission model for a strict subset of the desktop app's coverage.
• Centrally hosted backend, billing, subscriptions, or paid tiers. The foundational differentiation from Wispr Flow and superwhisper stated in Section 0; a hosted component would require OpenDictate to operate and pay for servers, which the project has no business model to sustain.

2.5 Success criteria #

2.6 Competitive landscape #

OpenDictate does not attempt to out-feature Wispr Flow or superwhisper on polish in v1; it competes on trust (auditable source, verifiable network destinations), cost (zero recurring fee beyond metered API usage), and provider flexibility (swap vendors without waiting on their roadmap).

2.7 Open-source strategy #

Why MIT. Chosen over a copyleft license (GPL/AGPL) for maximum adoption and the lowest barrier to forking, embedding, or building a commercial derivative — including a supported/hosted version, which OpenDictate itself will never build but doesn't want to prevent others from building. It also removes ambiguity for companies whose legal teams review dependency licenses (Section 4.7's allowlist policy inherits this same bias).

Why BYO-keys. The only model consistent with "no centrally hosted backend": a shared-key model would require OpenDictate to operate a billing relationship, rate-limit shared usage, and hold a pool of provider credentials — a security and cost liability the project has no revenue to cover. BYO-keys also means the user's provider account already enforces its own abuse controls, spend limits, and data-handling terms.

What BYO-keys costs a typical user per month. These are cost assumptions, not guarantees — provider pricing changes over time and varies by region. Figures below use list pricing believed accurate as of this document's writing; treat them as a worked example, not a hardcoded promise shown to users.

Assumptions: a "typical usage" user dictates 20 minutes/day, 22 working days/month, for 440 minutes/month. At ~130 wpm that's ≈57,200 words ≈76,000 transcript tokens through LLM cleanup, plus a comparable output-token count (cleanup roughly preserves length), plus system-prompt overhead of 300 input tokens × ~130 sessions/month (~3.4 min/session) ≈39,000 additional input tokens.

• STT cost (Deepgram nova-3, default): $0.0043/minute × 440 minutes ≈ $1.89/month.
• LLM cost (OpenAI gpt-4.1-mini, default): $0.40/M input + $1.60/M output tokens → ≈115,000 input tokens × $0.40/M ≈ $0.05, plus ≈76,000 output tokens × $1.60/M ≈ $0.12 → ≈ $0.17/month.
• Total: approximately $2.06/month — under a cup of coffee, versus Wispr Flow's materially higher paid-tier subscription regardless of usage. Heavy users (60+ min/day) scale roughly linearly and stay under $10/month on the default pairing; Groq's STT/LLM combo (priced lower than Deepgram/OpenAI at writing time) can push this well under $1/month, at a quality tradeoff users can evaluate by switching providers in Settings.

These numbers set expectations during onboarding (Section 27 shows a non-binding estimate on the API key screen) — never a hard billing calculation, since OpenDictate never sees the user's actual provider invoice.

3. Product Requirements & User Stories #

3.1 Functional requirement register #

Requirements are grouped by the 13 core features from Section 0. Every requirement carries a stable ID (FR-NNN), a priority (P0 = required for v1 GA, P1 = required within the first two point releases after GA, P2 = desirable, may ship later), and Given/When/Then acceptance criteria.

3.1.1 System-wide dictation activation #

• FR-001 — Given the app is running with the accessibility/input-monitoring permission granted, When the user is focused in any third-party text field and presses the configured push-to-talk shortcut, Then recording starts within the latency budget in Section 31 regardless of which application has focus.
• FR-002 — Given the Hotkeys settings panel is open, When the user clicks "Change" next to a shortcut and presses a new key combination, Then the new combination is validated, saved, and takes effect immediately without an app restart.
• FR-003 — Given toggle mode is enabled for the primary shortcut, When the user presses the shortcut once, Then recording starts and continues until the shortcut is pressed again or a 3-minute idle-silence auto-stop triggers (Section 8).
• FR-004 — Given a shortcut fails OS-level registration, When the app attempts to register it at startup or after a rebind, Then a toast notification names the conflicting combination and offers "Choose a different shortcut" as a direct action.
• FR-005 — Given the focused control is AXSecureTextField (macOS) or has the ES_PASSWORD style / UIA IsPassword flag (Windows), When the user presses the activation shortcut, Then no recording starts and a HUD message reads "OpenDictate can't dictate into password fields."

3.1.2 Real-time transcription and auto-formatting #

• FR-006 — Given a dictation session is active and the STT provider is a streaming-capable one, When partial results arrive over the WebSocket, Then the HUD updates its live caption within one frame of receipt.
• FR-007 — Given the user said "send it to, uh, send it to Jordan tomorrow, I mean Friday", When cleanup runs, Then the inserted text reads "Send it to Jordan on Friday." with the filler and the self-correction resolved.
• FR-008 — Given the configured LLM provider returns a 5xx error or does not respond within the cleanup timeout (Section 30), When finalization proceeds, Then the raw STT transcript, capitalization-fixed if the provider returned it, inserts instead and an LLM_TIMEOUT or LLM_PROVIDER_ERROR code is logged.
• FR-009 — Given the spoken transcript contains no mention of a delivery date, When cleanup runs, Then the output never introduces a date, name, or fact absent from the transcript.
• FR-010 — Given a dictation completed via the raw fallback path, When the text is inserted, Then the HUD briefly shows a "cleanup skipped" indicator distinct from the normal success state.

3.1.3 Context-aware tone adaptation #

• FR-011 — Given Slack is the frontmost app when the user starts dictating, When context detection runs, Then the app resolves the bundle id com.tinyspeck.slackmacgap (macOS) or process name slack.exe (Windows) to the chat category before the recording finishes.
• FR-012 — Given the chat category is mapped to the casual tone preset, When cleanup runs for a Slack dictation, Then contractions and informal phrasing are preserved rather than formalized.
• FR-013 — Given the user sets a per-app override for Slack to formal (e.g., for a work-only Slack workspace), When they later dictate into Slack, Then the formal override applies instead of the chat category default, and the override survives an app restart.
• FR-014 — Given the frontmost app's identifier is not present in the built-in category map, When context detection runs, Then the app is treated as neutral and no error is raised.

3.1.4 Command Mode #

• FR-015 — Given the user has selected a paragraph in a Google Doc (browser) and presses the Command Mode shortcut, When they say "make this shorter", Then the selection is replaced with a condensed version within the same latency budget class as a normal dictation.
• FR-016 — Given the target app does not expose AXSelectedText/TextPattern selection read, When Command Mode is invoked, Then the app falls back to Cmd+C/Ctrl+C capture with clipboard snapshot/restore around the copy, per the same restore mechanics as Section 10 strategy 2.
• FR-017 — Given the instruction is "turn into bullet points", When the LLM returns a bulleted rewrite, Then the rewrite is inserted using strategy 1→2→3 exactly as a normal dictation would be.
• FR-018 — Given no selection exists in the frontmost app, When Command Mode is invoked, Then the HUD shows "Select text first" and no API calls are made.
• FR-019 — Given the user says "translate this to French" over an English selection, When the LLM applies the instruction, Then the replacement text is in French regardless of the session's configured dictation language.

3.1.5 Personal dictionary #

• FR-020 — Given the user dictates "meet with Sian tomorrow" and it transcribes as "meet with Sean tomorrow", When one of Section 19.3's three signals (spoken correction, history edit, or re-dictation) fires within the 10-second window, Then the app adds "Sian" as a candidate dictionary entry pending review in the Dictionary settings panel's review list, not a toast.
• FR-021 — Given the Dictionary settings panel is open, When the user clicks "Add entry" and enters a term, Then the entry is saved to SQLite immediately and available to the next dictation session without a restart.
• FR-022 — Given the dictionary contains "Sian" and the active STT provider is Deepgram (which supports keyword biasing), When a session starts, Then "Sian" is passed in the provider's biasing parameter; given the provider is one that does not support biasing, Then the term list is included in the LLM cleanup system prompt instead (Section 16).
• FR-023 — Given the user deleted "Sean" from the dictionary, When an older settings export containing "Sean" is later imported, Then the merge logic respects the local deleted_at tombstone and does not resurrect the entry (see Section 23 for the canonical merge algorithm).
• FR-024 — (acceptance criteria covered by NFR-004 below).

3.1.6 Voice snippets #

• FR-025 — Given the user creates a snippet with trigger "my email signature" and expansion "Best,\nDana Reyes\nHead of Marketing", When they save it, Then it is stored immediately and active for the next session.
• FR-026 — Given the raw transcript is "send them my email signature please and let me know", When snippet matching runs against the raw text, Then the mid-utterance match is replaced, producing "send them Best,\nDana Reyes\nHead of Marketing please and let me know", before that combined text is passed into LLM cleanup.
• FR-027 — Given the raw transcript is "um my email signature", When snippet matching runs against the raw text before cleanup, Then the match succeeds directly against the unparaphrased raw wording, and LLM cleanup subsequently removes "um" from the surrounding text without affecting the already-expanded snippet.
• FR-028 — Given a snippet expansion is "Filed on {{date}}", When it expands, Then {{date}} resolves to the local date formatted per the user's OS locale at expansion time.
• FR-029 — Given a snippet "my signature" already exists, When the user attempts to save a second snippet also triggered by "My Signature", Then the save is rejected with an inline "This trigger phrase is already in use" message.

3.1.7 Multi-language dictation #

• FR-030 — Given the configured STT provider is Deepgram, When the user opens the language picker, Then the list reflects Deepgram's currently supported language set fetched from the provider capability descriptor (Section 12), not a hardcoded OpenDictate list.
• FR-031 — Given the tray icon is clicked, When the user selects "Language: Spanish" from the quick menu, Then subsequent dictations use Spanish without visiting Settings.
• FR-032 — Given auto-detect is enabled and the provider supports it, When the user dictates in French without changing any setting, Then the transcript returns in French and the detected language is shown in the HUD after the session.
• FR-033 — Given a recording is in progress in English, When the user changes the default language setting in another window, Then the app closes the current streaming connection and opens a new one with the new language code, buffering captured audio locally during the ~100–200 ms reconnect gap so no spoken words are dropped, and the remainder of the same in-progress recording is transcribed in the new language (Section 21.5).
• FR-034 — Given the user dictates in German with no Command Mode instruction, When cleanup runs, Then the output remains German.

3.1.8 Local privacy controls #

• FR-035 — Given Privacy Mode is on, When a dictation completes successfully, Then no row is written to the history_entries table, and the History panel shows its empty state.
• FR-036 — Given a recording session is cancelled mid-utterance, When the capture renderer receives the cancel signal, Then all buffered PCM frames are discarded from memory and no temp file was ever created for them.
• FR-037 — Given the user clicks "Clear all history" in Settings → Privacy, When they confirm the destructive-action dialog, Then all history_entries rows are hard-deleted in one transaction and the action cannot be undone.
• FR-038 — Given the user opens Settings → Privacy, When they read the "Network access" panel, Then it lists exactly: the configured STT provider, the configured LLM provider, and the GitHub Releases update endpoint — matching Section 32 verbatim.

3.1.9 API key and provider configuration #

• FR-039 — Given the user pastes an API key into the Deepgram field during onboarding, When they click "Verify", Then the app makes one minimal-cost authenticated request to Deepgram and shows a green check or a specific rejection reason (invalid format, 401, network error) inline.
• FR-040 — Given a key has been saved, When the user opens a diagnostics export (Section 33), Then the key value never appears anywhere in the exported bundle, only a masked reference like dg_****.
• FR-041 — Given the user switches the LLM provider from OpenAI to Anthropic, When they later switch back to OpenAI, Then the previously entered OpenAI key is still present and does not need to be re-entered.
• FR-042 — Given the user wants to use gpt-4.1 instead of the default gpt-4.1-mini, When they edit the Model field in Settings → Providers, Then the new model ID is used on the next request with no other code change required.
• FR-043 — Given the OpenAI key returns HTTP 401, When a cleanup request fails during a dictation, Then the raw-transcript fallback (FR-008) inserts and a toast reads "Your OpenAI API key was rejected — check Settings → Providers" with a direct link to that panel.

3.1.10 Settings export and import #

• FR-044 — Given the user clicks "Export settings" in Settings → General, When the save dialog completes, Then a single .json file is written containing dictionary entries, snippets, tone presets, and hotkey bindings.
• FR-045 — Given the export file is opened in a text editor, When the user searches for any of their configured API key values, Then no match is found anywhere in the file.
• FR-046 — Given the user imports an export from their laptop onto their desktop machine which already has some dictionary entries, When the import runs in default (merge) mode, Then entries are merged per Section 23's conflict rules rather than the desktop's existing entries being wiped.
• FR-047 — Given an export file was created by app version 1.1 with schemaVersion: 2 and the importing app is version 1.4 on schemaVersion: 3, When import runs, Then a migration step upgrades the parsed structure before merge, and an export file from a newer schema version than the importing app supports is rejected with a clear "update OpenDictate to import this file" message.

3.1.11 Setup and preferences UI #

• FR-048 — Given the app has just launched, When the user looks at their screen, Then only a tray/menu-bar icon is visible — no Dock icon bounce or taskbar window appears.
• FR-049 — Given Settings is open, When the user clicks "Audio" in the left nav, Then a live input-level meter animates in response to actual microphone input while the selected device is active, And a "Record a test clip" control captures a short sample and plays it back through the system output so the user can confirm the full capture path works end to end (Section 26.11).
• FR-050 — Given this is the user's first launch, When the app finishes starting, Then the onboarding walkthrough (Section 27) opens automatically and does not reopen automatically on subsequent launches, but remains reachable via Settings → About → "Re-run onboarding".
• FR-051 — Given the user resizes Settings and closes it on the "Providers" panel, When they reopen Settings later, Then it opens at the same size and position, on the "Providers" panel.
• FR-052 — Given the user changes the tone preset for Slack, When they close Settings without clicking any explicit save control, Then the change is already persisted and active.

3.1.12 Speech-to-text engine integration #

• FR-053 — Given a contributor wants to add a new STT provider, When they follow the recipe in Section 5.5, Then no existing provider's file needs to change beyond the registry entry.
• FR-054 — Given the active provider is Groq (batch-only), When a dictation is recording, Then the HUD shows a pulsing waveform with no live partial-text caption, then the full transcript appears at once on finalize.
• FR-055 — Given the selected microphone's native rate is 48 kHz, When the AudioWorklet processes frames, Then the frames posted to main are already downsampled to 16 kHz mono PCM16.
• FR-056 — Given Deepgram returns a connection drop mid-stream, When the provider adapter detects the disconnect, Then it attempts one reconnect with buffered audio replay before surfacing a STT_CONNECTION_LOST error to the state machine.
• FR-057 — Given the active STT provider is openai-stt (batch HTTP, no keyword biasing), When Settings → Dictionary is viewed, Then the "provider term biasing" indicator shows as unsupported for the current provider without hiding the dictionary itself (it still feeds the LLM prompt per FR-022).

3.1.13 AI cleanup and command engine #

• FR-058 — Given a contributor wants to add a new LLM provider, When they follow the recipe in Section 5.5, Then only a new adapter file and registry entry are needed, with no changes to the cleanup or Command Mode call sites.
• FR-059 — Given the cleanup prompt template is updated to improve filler-word handling, When the version bumps, Then the change is traceable to one file (Section 16) rather than scattered string literals.
• FR-060 — Given the LLM provider does not respond within 2,000 ms (Section 31 budget), When the timeout fires, Then the request is aborted client-side and FR-008's raw fallback path activates.
• FR-061 — Given a dictation just completed, When the cleanup request is constructed, Then its payload contains only text (transcript, tone preset id, relevant dictionary terms, app category), never an audio blob or file reference.
• FR-062 — Given both a normal dictation and a Command Mode invocation use the OpenAI adapter, When each constructs its request, Then they use CLEANUP_PROMPT_TEMPLATE and COMMAND_PROMPT_TEMPLATE respectively (Section 16), never a shared inline string.

3.2 Non-functional requirement register #

3.3 End-to-end user journeys #

3.3.1 First launch #

1. User double-clicks the downloaded .dmg/.exe, runs the installer, launches OpenDictate.
2. macOS Gatekeeper or Windows SmartScreen shows a first-run warning if unsigned (Section 1 row 14); user proceeds via "Open Anyway"/"Run anyway".
3. App starts, no Dock/taskbar icon, tray icon appears, onboarding window opens automatically (FR-050).
4. Onboarding step 1: welcome screen states the three network destinations verbatim (Section 32).
5. Onboarding step 2: OS permission requests — accessibility/input monitoring (Section 11) and microphone — with an "Open System Settings" deep link if not yet granted.
6. Onboarding step 3: STT and LLM API key entry, each validated live (FR-039); defaults pre-filled as Deepgram/OpenAI with links to each provider's key-creation page.
7. Onboarding step 4: Privacy Mode explanation and toggle, default off (Section 1 row 9).
8. Onboarding step 5: hotkey confirmation screen showing the OS-appropriate default (Section 1 rows 4–5), inline "try it now" test box.
9. Onboarding completes; window closes; tray icon shows idle state.
10. User presses the default hotkey in the test box (also reachable via Settings → About → "Re-run onboarding") or any real app, confirming first successful dictation.

3.3.2 Dictate into Slack #

1. User has Slack focused, a message compose box selected.
2. User holds the push-to-talk hotkey; HUD appears bottom-center (Section 1 row 7) within the mic-capturing latency budget.
3. Context detection resolves Slack's bundle id to the chat category, tone preset casual.
4. User speaks; interim captions stream into the HUD.
5. User releases the hotkey; recording finalizes, STT returns the final raw transcript.
6. LLM cleanup runs with the casual preset, preserving contractions and informal phrasing.
7. Snippet matching runs against the cleaned text (no match here).
8. Insertion strategy 1 (accessibility) is attempted against Slack's Electron-based input; if unsupported, strategy 2 (clipboard paste with restore) runs instead.
9. Text appears in the Slack compose box; HUD returns to idle.
10. A later dictionary-correction event (user retypes a misheard name) queues as a candidate entry (FR-020).

3.3.3 Dictate a long email #

1. User is composing in Mail/Outlook; app category resolves to email, tone preset formal.
2. User toggles dictation on (toggle mode) rather than holding push-to-talk, since the email is long.
3. User dictates several paragraphs, pausing naturally; captions keep streaming without timing out (idle-silence auto-stop is 3 minutes of continuous silence, not per-pause).
4. User says a self-correction mid-paragraph ("send the proposal by — actually make that Thursday not Wednesday").
5. User presses the toggle hotkey again to stop.
6. STT finalizes; cleanup resolves the self-correction and applies formal tone (full sentences, no contractions, salutation punctuation preserved as dictated).
7. Insertion strategy 1 (Mail/Outlook both expose good AX/UIA support) succeeds directly, no clipboard touch.
8. HUD shows success state; email body contains the full formatted draft, ready for a final read-through.

3.3.4 Fix a misheard name #

1. User dictates "meeting with Siobhan at 3", transcribed/cleaned as "meeting with Chevonne at 3".
2. Within the 10-second signal window (Section 19.3), the user re-dictates "Siobhan" (or speaks a correction, or edits the History entry) — one of Section 19.3's three signals fires.
3. OpenDictate records "Siobhan" as a candidate dictionary entry; since it cannot reliably observe edits made directly inside a third-party app, no accessibility diffing of the target app's content is attempted (Section 19.3).
4. The candidate appears in the Dictionary settings panel's review list, not an in-context toast.
5. User opens the review list and confirms the candidate; it's saved to the dictionary immediately (FR-021 path, auto-populated).
6. The next dictation containing "Siobhan" passes it as an STT biasing hint (if supported) and an LLM spelling constraint, transcribing it correctly going forward.

3.3.5 Command Mode on selected text #

1. User has a paragraph selected in a Google Doc open in a browser.
2. User presses the Command Mode shortcut (distinct from the dictation shortcut, Settings → Hotkeys).
3. App reads the current selection via accessibility read, falling back to clipboard-copy capture if unsupported by the browser's DOM-based text rendering (FR-016).
4. HUD shows a distinct "Command Mode" visual state.
5. User speaks "make this shorter and turn it into three bullet points."
6. STT transcribes the instruction; it's sent with the captured selection text to the LLM using COMMAND_PROMPT_TEMPLATE (Section 16).
7. LLM returns the rewritten selection.
8. The rewrite replaces the original selection using the same insertion strategy chain as normal dictation (strategy 1 first).
9. HUD returns to idle; the paragraph is now three bullet points.

3.3.6 Running out of API credit #

1. User's OpenAI account runs out of prepaid credit mid-day.
2. User dictates normally; STT succeeds (different provider/account).
3. Cleanup request to OpenAI returns HTTP 402/insufficient_quota.
4. Error classifies as non-retryable (LLM_QUOTA_EXCEEDED, Section 40); raw-transcript fallback inserts immediately (FR-008) so the user is never blocked from getting some text.
5. A dismissible toast reads "OpenAI is out of credit — cleanup is paused. Text is inserting without AI formatting until you add credit or switch providers." with a link to Settings → Providers.
6. Every subsequent dictation inserts raw-fallback text (with STT-native punctuation where available) until the condition clears, without repeating the toast more than once per 30 minutes.
7. User adds credit or switches the LLM provider to Groq in Settings → Providers.
8. Next dictation succeeds through full cleanup again; the degraded-mode indicator clears from the HUD.

3.3.7 Switching language mid-flow #

1. User is dictating in English by default.
2. Mid-day, user needs to dictate a WhatsApp message in Spanish to a family member.
3. User clicks the tray icon, selects "Language: Spanish" from the quick language menu (FR-031) — no need to open full Settings.
4. User dictates in Spanish; STT returns Spanish text since the pinned language, not auto-detect, is now Spanish.
5. Cleanup prompt is instructed to preserve Spanish (FR-034), not translate to English.
6. User finishes the Spanish message, then switches the tray language back to English for the next dictation.
7. The language setting persists as the new default until changed again — it's not session-scoped or auto-reverting.

3.3.8 Moving to a second machine #

1. User has OpenDictate configured on their laptop with a populated dictionary, several snippets, and custom hotkeys.
2. User installs OpenDictate on a new desktop machine and completes onboarding with fresh API keys (keys are never exported, FR-045).
3. On the laptop, user runs Settings → General → "Export settings", saving opendictate-export.json to a shared location (e.g., a personal cloud drive folder, entirely outside OpenDictate's control).
4. On the desktop, user runs Settings → General → "Import settings", selects the file.
5. Import runs schema-version migration if needed (FR-047), then merges dictionary and snippets per Section 23's conflict rules (default merge mode, FR-046) rather than overwriting the desktop's onboarding defaults.
6. The desktop now has the laptop's dictionary and snippets; its own API keys (entered fresh in step 2) remain untouched since keys were never part of the export.

3.3.9 Rotating a key #

1. User's Deepgram key was potentially exposed; they rotate it from the Deepgram dashboard, generating a new key.
2. User opens Settings → Providers → Deepgram, clicks "Update key", pastes the new key.
3. App runs the same live validation as onboarding (FR-039) against the new key.
4. On success, the new key immediately replaces the old one in the safeStorage-encrypted store; the old value is overwritten, not retained anywhere.
5. Next dictation uses the new key with no further action required; no app restart needed (FR-052).

3.3.10 Dictating into a terminal #

1. Marcus (Section 2.2.2) is in iTerm2/Windows Terminal composing a git commit -m message.
2. He types git commit -m ", positions the cursor after the opening quote, then holds the push-to-talk hotkey.
3. Context detection resolves the terminal to the terminal category, tone preset neutral (Section 14 maps Code/Terminal to neutral, not a separate preset).
4. He dictates the commit message; cleanup applies neutral tone (no softening filler, imperative mood preserved as spoken).
5. Insertion strategy 1 (accessibility) is attempted; most terminal emulators expose no usable AX/UIA text-insertion target, so it falls to strategy 2 (clipboard paste).
6. If the terminal/shell blocks bracketed-paste or mangles pasted content (detected via a paste-then-verify check), strategy 3 (synthetic keystrokes) types the text character-by-character instead.
7. The commit message appears inside the quotes; he closes the quote manually and runs the command.

3.3.11 A snippet trigger #

1. Dana finishes dictating an email body ending in "...let me know if you have questions, my email signature".
2. STT transcribes the full utterance; cleanup cleans punctuation and filler across the whole thing.
3. The snippet matcher runs against the cleaned text's trailing content and finds "my email signature" matches Dana's defined trigger.
4. The matched trailing phrase is stripped and replaced with the stored expansion, including a {{date}} token resolved to today's date if her signature template includes one.
5. The combined text (email body + expanded signature) inserts as a single operation, not two, avoiding a visible seam or double-paste flicker.

3.3.12 Recovering from a network drop mid-utterance #

1. User is dictating a long paragraph over a streaming STT connection (Deepgram WebSocket).
2. Wi-Fi drops for roughly 2 seconds mid-utterance.
3. The STT adapter's WebSocket close/error event fires; buffered local audio frames keep accumulating in memory (not discarded), not sent into the void.
4. Adapter attempts one automatic reconnect with exponential backoff starting at 250 ms (Section 30); on reconnect, it replays the buffered-but-unsent frames so no spoken words are lost.
5. If reconnect succeeds within the retry budget (Section 30), the session continues transparently — the user may not even notice beyond a brief HUD "reconnecting" flicker.
6. If reconnect fails after the retry budget is exhausted, the session finalizes with whatever transcript was received before the drop, cleanup runs on that partial transcript, and a toast tells the user the dictation may be incomplete and invites review.

4. Technology Stack & Architecture #

4.1 Canonical stack #

Row-by-row justification:

• Electron 33.x. Only cross-platform shell mature enough to expose OS accessibility APIs (via a native addon), global hotkeys, tray/menu-bar integration, and a full browser-grade UI runtime from one codebase spanning macOS and Windows.
• TypeScript 5.6, strict everywhere. One language across main, preload, renderer, and shared packages removes a serialization-boundary class of bugs; noUncheckedIndexedAccess catches array/record-access mistakes common in IPC payload and dictionary/snippet lookups.
• electron-vite 2.x. Three independently configured build targets (main, preload, each renderer) with fast HMR, without hand-rolling separate Webpack configs per process.
• React 19, function components + hooks only. Matches the shadcn/ui and Radix ecosystem, avoids class-component lifecycle complexity; improved concurrent rendering keeps the always-on-top HUD renderer cheap.
• Tailwind CSS 4 + CSS variables. Utility classes keep styling co-located and reviewable in PRs; CSS variables are the mechanism Section 24's theming (light/dark/system) hooks into, no runtime CSS-in-JS cost.
• Radix UI + shadcn/ui. Radix supplies accessible, unstyled primitives satisfying NFR-006/NFR-007 out of the box; shadcn/ui's copy-into-repo pattern keeps component source directly editable, not hidden behind an opaque dependency.
• Zustand 5 for renderer state. Minimal boilerplate vs. Redux; its subscription model fits a renderer mirroring main-pushed state rather than owning business logic — main is the single source of truth (Section 4.2).
• Zod 3, one shared schema package. Every IPC payload, settings value, and export file validates against the same schema definitions imported by main and renderer, so a schema change can't silently drift between sides.
• better-sqlite3 11.x, synchronous, main-process only. Safe since SQLite access only happens on main's Node event loop, never a renderer; synchronous I/O avoids async-driver overhead for sub-millisecond local queries and simplifies transactions (Section 17).
• Electron safeStorage. Delegates secret encryption to the OS's own credential facilities (Keychain/DPAPI) instead of inventing a key-derivation scheme, directly satisfying NFR-008.
• electron-log 5.x. Rotating file transport and log-level control out of the box; its transport pipeline is where the secret-redaction filter (Section 33) installs globally so no call site can accidentally log a raw key.
• electron-builder 25.x. The de facto standard for signed/notarized macOS .dmg and Windows NSIS/portable builds from one config file, with first-class electron-updater integration.
• electron-updater against GitHub Releases. A free, already-existing artifact host for an open-source repo, no dedicated update server needed — consistent with Section 0's no-hosted-backend decision.
• Vitest 2.x. Shares Vite's transform pipeline with electron-vite, so unit tests run the same TypeScript/JSX transforms as the app build, no separate ts-jest config.
• Playwright 1.4x with _electron. The only E2E framework with a maintained first-class Electron driver capable of driving multiple BrowserWindows and asserting real OS-level window behavior.
• ESLint 9 flat config + Prettier 3. Current major versions of both at writing time; flat config is ESLint's supported forward path.
• @opendictate/native via node-addon-api / N-API + prebuildify. N-API is Node's ABI-stable native addon interface, so prebuilt binaries keep working across Node/Electron bumps without per-user recompiling; prebuildify bundles prebuilt binaries per target arch/platform into the npm package so no one needs a local native toolchain.
• pnpm 9 workspaces. Strict, content-addressed node_modules linking catches phantom-dependency bugs at install time, not production; its workspace protocol (workspace:*) makes internal versioning explicit.

Considered and rejected: Tauri (Rust) — the accessibility/text-injection native ecosystem is far more mature in Node. Native Swift + WinUI dual codebases — 2x maintenance for a solo/OSS project.

4.2 C4 architecture #

4.2.1 System context #

                     ┌───────────────────────────────────────┐
                     │              OpenDictate               │
                     │   (desktop app, user's own machine)    │
                     └───────────────────────────────────────┘
                        │                  │              │
                        │ audio→text       │ text ops     │ update check
                        ▼                  ▼              ▼
              ┌──────────────────┐  ┌──────────────┐  ┌─────────────────┐
              │  STT Provider     │  │ LLM Provider │  │ GitHub Releases  │
              │  (Deepgram/OpenAI │  │ (OpenAI/     │  │ (update feed,    │
              │  /Groq/Azure/...) │  │ Anthropic/   │  │  user-disableable│
              │  — user's account │  │ Groq/...)    │  │  in Settings)    │
              └──────────────────┘  │ — user's acct│  └─────────────────┘
                                     └──────────────┘
        ▲
        │ text insertion / selection read
        ▼
┌──────────────────────┐
│  Focused OS app       │
│  (Slack, Mail, VS Code,│
│   Terminal, browser…) │
└──────────────────────┘

No other network endpoints exist. There is no OpenDictate-operated server anywhere in this diagram — see Section 32.

4.2.2 Container diagram #

┌─────────────────────────────────────────────────────────────────────┐
│ OpenDictate desktop app (single installed application)                │
│                                                                         │
│  ┌───────────────┐   IPC   ┌────────────────┐   IPC   ┌─────────────┐ │
│  │ Main process   │◄───────►│ Renderer:      │         │ Renderer:   │ │
│  │ (Node.js,      │◄────────┼─settings       │         │ hud         │ │
│  │  Electron main)│   IPC   └────────────────┘         └─────────────┘ │
│  │                │                                                    │
│  │ - Lifecycle/tray                                                   │
│  │ - Global hotkeys      ◄───────────────┐                            │
│  │ - Dictation state machine             │ IPC (audio frames)         │
│  │ - Provider adapters (STT/LLM) ┐       │                            │
│  │ - SQLite (better-sqlite3)     │  ┌────┴────────┐                   │
│  │ - safeStorage (keychain)      │  │ Renderer:    │                   │
│  │ - Native addon bridge         │  │ capture      │                   │
│  │   (@opendictate/native)       │  │ (hidden,      │                   │
│  └────────────────────────────────┘  │  getUserMedia+AudioWorklet)   │
│           │                          └──────────────┘                 │
│           ▼                                                            │
│  ┌────────────────────┐                                                │
│  │ @opendictate/native │  N-API addon: hotkeys, AX/UIA read+insert,   │
│  │ (native addon)      │  focused-app detection, secure-field detect  │
│  └────────────────────┘                                                │
└─────────────────────────────────────────────────────────────────────┘

4.2.3 Component diagram (main process) #

┌───────────────────────────────────────────────────────────────────┐
│ Main process                                                        │
│                                                                       │
│  AppLifecycle ── owns app.whenReady/quit, single-instance lock       │
│       │                                                              │
│  TrayController ── tray icon, quick menu (language, privacy toggle)  │
│       │                                                              │
│  WindowManager ── creates/owns settings, hud, capture BrowserWindows │
│       │                                                              │
│  HotkeyManager ── registers/unregisters global shortcuts (Section 7) │
│       │                                                              │
│  DictationStateMachine ── IDLE→...→COOLDOWN (Section 6.5)            │
│       │            │             │              │                   │
│       ▼            ▼             ▼              ▼                   │
│  AudioSession   ContextDetector  SttOrchestrator LlmOrchestrator     │
│  (buffers PCM   (Section 9)      (Section 12)    (Section 13/15/16)  │
│   from capture)                                                      │
│       │                                                              │
│  InsertionEngine ── strategy chain (Section 10)                      │
│       │                                                              │
│  Repositories ── DictionaryRepo, SnippetRepo, HistoryRepo,           │
│                   SettingsRepo, ProviderKeyRepo (Section 17)         │
│       │                                                              │
│  Db ── better-sqlite3 connection + migrations                        │
│       │                                                              │
│  SecretStore ── safeStorage wrapper (Section 18)                     │
│       │                                                              │
│  NativeBridge ── typed wrapper over @opendictate/native (Section 4.5)│
│       │                                                              │
│  UpdateController ── electron-updater wiring (Section 36)            │
└───────────────────────────────────────────────────────────────────┘

4.3 Runtime data flow — one dictation, keypress to inserted text #

Numbered sequence naming the owning process/component at each step:

1. [Main / HotkeyManager] OS-level global hotkey callback fires on push-to-talk key-down.
2. [Main / DictationStateMachine] Transitions IDLE → ARMED, then ARMED → RECORDING once the capture path confirms readiness (guard conditions in Section 6.5).
3. [Main / NativeBridge] Calls into @opendictate/native to read the frontmost app's bundle id/process name and secure-field status (INJECT_getFocusedElementInfo) before recording starts, enforcing FR-005's hard block.
4. [Main / WindowManager] Shows/positions the hud window (created hidden at app start, Section 6.6) at the HUD position default (Section 1 row 7).
5. [Main → Renderer:capture, IPC] Sends audio:start-capture with the resolved device id from Settings.
6. [Renderer:capture] Opens getUserMedia, wires an AudioWorklet that downsamples to 16 kHz mono PCM16, and posts frame buffers to main via audio:frame IPC (binary ArrayBuffer transfer, not JSON).
7. [Main / AudioSession] Buffers incoming frames and forwards them, chunked, to the SttOrchestrator.
8. [Main / SttOrchestrator → STT Provider] Opens (or reuses) a streaming connection to the configured STT provider and streams frames as they arrive; interim results return over the same connection.
9. [Main → Renderer:hud, IPC] Each interim result is pushed as dictation:state-changed / dictation:interim-transcript so the HUD renders live captions.
10. [Main / HotkeyManager] Key-up on the push-to-talk key (or the toggle-mode second press) fires.
11. [Main / DictationStateMachine] Transitions RECORDING → FINALIZING; signals Renderer:capture to stop capture and SttOrchestrator to close the stream and await the final transcript.
12. [Main / SttOrchestrator] Receives the provider's final transcript payload; the machine moves FINALIZING → FORMATTING once the final STT text is in hand (full transition table in Section 6.5, where TRANSCRIBING covers steps 7–12).
13. [Main / SnippetRepo + matcher] Runs snippet matching (FR-026/FR-027) against the raw STT transcript, expanding any matched trigger phrase found anywhere in the utterance before cleanup runs (Section 19.6/20.4).
14. [Main / ContextDetector] Resolves the app category and tone preset captured in step 3 into a TonePreset value (Section 14).
15. [Main / LlmOrchestrator → LLM Provider] Sends the cleanup request (snippet-expanded transcript, tone preset, relevant dictionary terms, language) using CLEANUP_PROMPT_TEMPLATE (Section 16).
16. [Main / LlmOrchestrator] Receives the cleaned text, or times out per NFR-001/FR-060, in which case the raw (snippet-expanded) STT transcript is used instead (FR-008).
17. [Main / DictationStateMachine] Transitions FORMATTING → INSERTING.
18. [Main / InsertionEngine → NativeBridge] Attempts strategy 1 (accessibility direct insert) via @opendictate/native; on failure, strategy 2 (clipboard snapshot, write, synthetic paste, restore); on failure, strategy 3 (synthetic keystrokes) — full decision logic in Section 10.
19. [Main / HistoryRepo] Writes a history entry (unless Privacy Mode is on, FR-035) in the same logical operation, after insertion is confirmed.
20. [Main / DictationStateMachine] Transitions INSERTING → COOLDOWN → IDLE.
21. [Main → Renderer:hud, IPC] Pushes the final dictation:state-changed event; HUD plays its success animation and hides after its configured dwell time.

4.4 Threading / async model #

• The main process runs a single Node.js event loop. I/O (SQLite, provider HTTP/WebSocket calls, native addon calls) is either genuinely async (network) or fast synchronous work not blocking the loop beyond single-digit milliseconds; any native addon call expected to exceed ~5 ms uses N-API's AsyncWorker to run on Node's libuv thread pool instead of the main JS thread.
• Audio frame delivery from capture to main happens on every AudioWorklet callback (128-sample quanta at 16 kHz ≈ every 8 ms); the IPC payload transfers as an ArrayBuffer (structured clone with transfer, not copy) to avoid GC pressure from many small allocations per second.
• Streaming STT connections use Node's native ws client (or the provider SDK's own) on the main event loop; since only one concurrent recording session exists by design (Section 6.5), this never becomes a concurrency bottleneck.
• LLM HTTP requests use fetch (Node 20's built-in undici-backed implementation) with an AbortController wired to the FR-060 timeout budget.
• No worker_threads in v1 — the workload (network-bound STT/LLM calls, occasional SQLite/native-addon calls) doesn't justify a worker pool. A future CPU-bound bottleneck (e.g., audio resampling on low-end Windows hardware) is already covered: resampling runs in the capture renderer's AudioWorklet, on its own dedicated real-time audio thread by Web Audio API design, isolated from the renderer's main thread and the Electron main process.
• Renderers (settings, hud, capture) are each a normal Chromium renderer process with its own JS thread; React 19's concurrent features handle UI responsiveness within each, but there's no cross-renderer shared memory — all cross-process state flows through the typed IPC surface (Section 6.3).

4.5 Native addon surface — @opendictate/native #

Every exported function, its TypeScript signature, and its per-OS behavior. The package's root export is a single object implementing NativeAddon; all functions are synchronous from the caller's perspective except where marked, backed internally by N-API AsyncWorker for anything not trivially fast.

export interface NativeAddon {
  hotkeys: HotkeyModule;
  accessibility: AccessibilityModule;
  focus: FocusModule;
  insertion: InsertionModule;
  permissions: PermissionsModule;
}

interface HotkeyModule {
  register(id: string, accelerator: string, mode: 'keydown-keyup' | 'press'): boolean;
  unregister(id: string): void;
  unregisterAll(): void;
  onEvent(callback: (event: HotkeyEvent) => void): void;
}
interface HotkeyEvent { id: string; phase: 'down' | 'up'; timestampMs: number; }

• macOS: implemented via a low-level CGEventTap listening for key-down/key-up matching the registered accelerator, required because Fn-only and other modifier-only bindings are not expressible through Electron's built-in globalShortcut API. Requires Accessibility permission (Section 11).
• Windows: implemented via a low-level keyboard hook (SetWindowsHookEx with WH_KEYBOARD_LL), which similarly supports modifier-only chords that globalShortcut cannot.

interface AccessibilityModule {
  isTrusted(): boolean;
  requestTrust(): void; // macOS: opens the AX permission prompt; Windows: no-op, always trusted
}

• macOS: wraps AXIsProcessTrusted() / AXIsProcessTrustedWithOptions with the prompt option.
• Windows: UI Automation requires no special app-level trust grant beyond normal process permissions; isTrusted() always returns true.

interface FocusModule {
  getFocusedElementInfo(): FocusedElementInfo;
}
interface FocusedElementInfo {
  appBundleId: string | null;   // macOS bundle id, or Windows exe path as a stable substitute
  appName: string;
  isSecureField: boolean;
  supportsDirectRead: boolean;
  supportsDirectInsert: boolean;
}

• macOS: resolves the frontmost app via NSWorkspace.frontmostApplication, then walks the AX tree from AXFocusedUIElement to classify the role (AXSecureTextField → isSecureField: true) and probes for AXValue/AXSelectedText attribute support.
• Windows: resolves the foreground window via GetForegroundWindow, then uses UI Automation's IUIAutomation::GetFocusedElement to classify via UIA_IsPasswordPropertyId and probe TextPattern/ValuePattern support.

interface InsertionModule {
  tryDirectInsert(text: string): InsertResult;             // strategy 1
  readSelection(): SelectionReadResult;                     // for Command Mode (FR-016)
  readClipboardSnapshot(): ClipboardSnapshot;                // strategy 2 support
  writeClipboard(text: string): void;
  restoreClipboard(snapshot: ClipboardSnapshot): void;
  synthesizePasteKeystroke(): void;                          // Cmd+V / Ctrl+V
  synthesizeTypedText(text: string): void;                   // strategy 3
}
interface InsertResult { success: boolean; reason?: 'unsupported' | 'no-focus' | 'error'; }
interface SelectionReadResult { success: boolean; text: string | null; usedClipboardFallback: boolean; }
interface ClipboardSnapshot { formats: Record<string, string | Buffer>; }

• macOS tryDirectInsert: sets AXValue (whole-field replace context) or AXSelectedText (cursor-position insert context) on the focused AXUIElement; returns unsupported if the element doesn't expose a settable value attribute.
• Windows tryDirectInsert: uses UI Automation TextPattern.SetValue where the pattern is a ValuePattern, or manipulates the TextRange via TextPattern at the caret; returns unsupported similarly.
• synthesizePasteKeystroke: macOS via CGEventKeyboardSetUnicodeString-driven Cmd+V posted through CGEventPost; Windows via SendInput with VK_CONTROL+V.
• synthesizeTypedText: macOS posts one CGEventKeyboardSetUnicodeString event per character (handles full Unicode, not limited to US keyboard layout scancodes); Windows posts one SendInput KEYEVENTF_UNICODE event per character. Both are throttled to avoid overwhelming slow target apps (Section 10 defines the per-character delay).

interface PermissionsModule {
  getMicrophoneStatus(): 'granted' | 'denied' | 'not-determined' | 'restricted';
  requestMicrophone(): Promise<'granted' | 'denied'>;
  openSystemSettings(pane: 'accessibility' | 'microphone' | 'input-monitoring'): void;
}

• macOS: wraps AVCaptureDevice.authorizationStatus/requestAccess for microphone; openSystemSettings opens the relevant x-apple.systempreferences: pane URL.
• Windows: wraps the Windows privacy capability APIs for microphone; openSystemSettings opens ms-settings:privacy-microphone. Accessibility/input-monitoring has no Windows equivalent gate (see Section 11), so openSystemSettings('accessibility') is a no-op on Windows.

4.6 Dependency inventory #

4.7 Supply-chain policy #

• Lockfile is committed and authoritative. pnpm-lock.yaml is committed at the repo root; CI runs pnpm install --frozen-lockfile and fails the build if the lockfile is out of sync with package.json files.
• Pinned versions for security-sensitive packages. electron, better-sqlite3, node-addon-api, and anything touching the native addon or secret storage are pinned to an exact version (no ^/~ range); all others use caret ranges, bumped deliberately via Dependabot/Renovate PRs, never floating.
• License allowlist. CI runs a license-check step against an allowlist of MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, and 0BSD. Any dependency (direct or transitive) resolving to GPL, AGPL, LGPL, SSPL, or Unlicense/unknown fails CI and blocks merge, since a copyleft or non-standard license would contaminate the MIT distribution guarantee.
• Dependency review on every PR. A GitHub Actions dependency-review step runs on any PR changing a lockfile, flagging new packages, license changes, and known-vulnerable versions (GitHub Advisory Database) before merge.
• No install-time scripts trusted by default. pnpm's config sets dangerouslyAllowAllBuilds: false (or the pnpm 9 onlyBuiltDependencies allowlist), so a new dependency's native build/postinstall script never runs without explicit maintainer opt-in — the standard defense against a compromised transitive dependency running arbitrary code at install.
• Native addon binaries are built in CI, not accepted from third parties. @opendictate/native's prebuilt binaries come from the project's own CI matrix (macOS arm64/x64, Windows x64); none is ever pulled from an external, unaudited source.

5. Repository Structure & Code Conventions #

5.1 Monorepo tree #

opendictate/
├── apps/
│   └── desktop/
│       ├── src/
│       │   ├── main/
│       │   │   ├── index.ts                  # app entry, single-instance lock, app.whenReady
│       │   │   ├── lifecycle/
│       │   │   │   ├── app-lifecycle.ts       # cold start, sleep/wake, quit sequencing (Section 6.6)
│       │   │   │   └── single-instance.ts     # requestSingleInstanceLock wiring
│       │   │   ├── windows/
│       │   │   │   ├── window-manager.ts      # creates/owns settings, hud, capture windows
│       │   │   │   ├── settings-window.ts
│       │   │   │   ├── hud-window.ts
│       │   │   │   └── capture-window.ts
│       │   │   ├── tray/
│       │   │   │   └── tray-controller.ts     # tray icon + quick menu (Section 25)
│       │   │   ├── hotkeys/
│       │   │   │   └── hotkey-manager.ts      # global shortcut registration (Section 7)
│       │   │   ├── dictation/
│       │   │   │   ├── state-machine.ts       # IDLE..COOLDOWN (Section 6.5)
│       │   │   │   ├── audio-session.ts       # PCM buffering from capture renderer
│       │   │   │   └── command-mode.ts        # Command Mode orchestration (Section 15)
│       │   │   ├── context/
│       │   │   │   └── context-detector.ts    # focused-app → category → tone (Section 9, 14)
│       │   │   ├── providers/
│       │   │   │   ├── stt/
│       │   │   │   │   ├── stt-provider.ts    # SttProvider interface + registry
│       │   │   │   │   ├── deepgram.adapter.ts
│       │   │   │   │   ├── openai.adapter.ts
│       │   │   │   │   ├── groq.adapter.ts
│       │   │   │   │   ├── azure.adapter.ts
│       │   │   │   │   └── openai-compatible.adapter.ts
│       │   │   │   └── llm/
│       │   │   │       ├── llm-provider.ts    # LlmProvider interface + registry
│       │   │   │       ├── openai.adapter.ts
│       │   │   │       ├── anthropic.adapter.ts
│       │   │   │       ├── groq.adapter.ts
│       │   │   │       ├── openrouter.adapter.ts
│       │   │   │       └── openai-compatible.adapter.ts
│       │   │   ├── insertion/
│       │   │   │   └── insertion-engine.ts    # strategy chain (Section 10)
│       │   │   ├── native/
│       │   │   │   └── native-bridge.ts       # typed wrapper over @opendictate/native
│       │   │   ├── db/
│       │   │   │   ├── db.ts                  # better-sqlite3 connection + pragmas
│       │   │   │   ├── migrations/            # numbered .sql migration files
│       │   │   │   └── repositories/
│       │   │   │       ├── dictionary.repo.ts
│       │   │   │       ├── snippet.repo.ts
│       │   │   │       ├── history.repo.ts
│       │   │   │       ├── settings.repo.ts
│       │   │   │       └── provider-key.repo.ts
│       │   │   ├── secrets/
│       │   │   │   └── secret-store.ts        # safeStorage wrapper (Section 18)
│       │   │   ├── update/
│       │   │   │   └── update-controller.ts   # electron-updater wiring (Section 36)
│       │   │   ├── ipc/
│       │   │   │   ├── register-handlers.ts   # wires every ipcMain.handle channel
│       │   │   │   └── handlers/              # one file per IPC domain (dictation, settings, ...)
│       │   │   └── logging/
│       │   │       └── logger.ts              # electron-log setup + redaction filter
│       │   ├── preload/
│       │   │   └── index.ts                   # contextBridge surface (Section 6.4)
│       │   └── renderer/
│       │       ├── settings/
│       │       │   ├── main.tsx
│       │       │   ├── App.tsx
│       │       │   ├── panels/                # Hotkeys, Audio, Providers, Dictionary, ...
│       │       │   └── stores/                # Zustand stores mirroring main state
│       │       ├── hud/
│       │       │   ├── main.tsx
│       │       │   └── App.tsx
│       │       └── capture/
│       │           ├── main.ts                # no UI — audio-only worker window
│       │           └── audio-worklet.ts
│       ├── resources/                          # icons, tray images, entitlements
│       ├── electron-builder.yml
│       ├── electron.vite.config.ts
│       ├── package.json
│       └── tsconfig.json
├── packages/
│   ├── core/
│   │   ├── src/
│   │   │   ├── prompts/                        # CLEANUP_PROMPT_TEMPLATE etc. (Section 16)
│   │   │   ├── errors/                          # AppError, error registry (Section 40)
│   │   │   └── ipc-envelope.ts                  # IpcResult<T> (Section 6.3)
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── native/
│   │   ├── src/                                 # C++ N-API source
│   │   ├── prebuilds/                           # prebuildify output, committed via CI artifact
│   │   ├── binding.gyp
│   │   ├── index.d.ts                           # NativeAddon interface (Section 4.5)
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── shared/
│   │   ├── src/
│   │   │   ├── schemas/                         # Zod schemas: settings, dictionary, snippets, ...
│   │   │   └── types/                           # inferred TS types from schemas
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── ui/
│       ├── src/
│       │   ├── components/                      # shadcn/ui-derived components
│       │   └── theme/                            # CSS variable definitions (Section 24)
│       ├── package.json
│       └── tsconfig.json
├── e2e/
│   ├── fixtures/                                 # mocked STT/LLM provider servers for tests
│   └── tests/
├── scripts/
│   ├── build-native.ts
│   └── check-licenses.ts
├── .github/
│   └── workflows/                                # ci.yml, release.yml (Section 37)
├── docs/
│   └── benchmarks/                               # accuracy benchmark records (Section 2.5)
├── pnpm-workspace.yaml
├── package.json
├── tsconfig.base.json
├── eslint.config.js
├── .prettierrc.json
└── README.md

5.2 tsconfig.base.json #

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "forceConsistentCasingInFileNames": true,
    "verbatimModuleSyntax": true,
    "paths": {
      "@opendictate/core": ["packages/core/src/index.ts"],
      "@opendictate/core/*": ["packages/core/src/*"],
      "@opendictate/native": ["packages/native/index.d.ts"],
      "@opendictate/shared": ["packages/shared/src/index.ts"],
      "@opendictate/shared/*": ["packages/shared/src/*"],
      "@opendictate/ui": ["packages/ui/src/index.ts"],
      "@opendictate/ui/*": ["packages/ui/src/*"]
    }
  }
}

Each package/app tsconfig.json extends this with "extends": "../../tsconfig.base.json" and adds only its own include/outDir/jsx fields; renderer packages additionally set "jsx": "react-jsx" and "lib": ["ES2022", "DOM", "DOM.Iterable"].

5.3 ESLint 9 flat config (eslint.config.js, repo root) #

// @ts-check
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import reactHooks from 'eslint-plugin-react-hooks';
import importPlugin from 'eslint-plugin-import';

export default tseslint.config(
  { ignores: ['**/dist/**', '**/prebuilds/**', '**/node_modules/**'] },
  js.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    plugins: { 'react-hooks': reactHooks, import: importPlugin },
    rules: {
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/consistent-type-imports': 'error',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      'import/order': ['error', {
        groups: ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
        pathGroups: [{ pattern: '@opendictate/**', group: 'internal' }],
        'newlines-between': 'always',
        alphabetize: { order: 'asc' },
      }],
      'no-console': ['error', { allow: ['warn', 'error'] }],
    },
  },
  {
    files: ['**/*.tsx'],
    rules: { '@typescript-eslint/no-misused-promises': ['error', { checksVoidReturn: false }] },
  },
);

5.4 Prettier (.prettierrc.json) #

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always",
  "plugins": ["prettier-plugin-tailwindcss"]
}

5.5 Conventions #

• Import ordering and path aliases. Enforced by the import/order rule above: built-ins, external packages, @opendictate/* internal packages, relative imports — alphabetized within each group, blank line between groups. Never use deep relative paths (../../../../packages/shared/src/schemas) to reach another workspace package — always the @opendictate/* alias.
• Naming rules. camelCase for variables/functions, PascalCase for types/interfaces/React components, SCREAMING_SNAKE_CASE for module-level constants (CLEANUP_PROMPT_TEMPLATE, DEFAULT_HISTORY_RETENTION_DAYS). Files are kebab-case.ts except React components (PascalCase.tsx, matching default export). IPC channel constants live in packages/shared/src/ipc-channels.ts as SCREAMING_SNAKE_CASE exports whose values are kebab-case channel names (Section 5.4, Section 17).
• Error-handling style. Every function that can fail expectedly (provider call, native addon call, DB write) returns or throws an AppError (Section 30.1, Section 40.1 registry) — never a bare Error, never a raw provider SDK exception past the adapter boundary. IPC handlers catch at the boundary and always resolve with IpcResult<T>, never throw past ipcMain.handle. Native addon calls wrap in try/catch inside native-bridge.ts, mapping platform exceptions to AppError with an INJECT_*/PERM_* code (NFR-018).
• Async style. async/await exclusively — no raw .then() chains in application code (acceptable only inside a thin adapter wrapping a callback-based third-party API). Every fired-and-not-awaited async call must be wrapped as void someAsyncFn() or .catch()-handled, enforced by no-floating-promises.
• JSDoc policy. Required on every exported function in packages/core, packages/native's .d.ts, and every IPC handler — one-line summary plus @param/@returns only where the type signature alone doesn't make usage obvious. Optional on internal, non-exported helpers.
• Conventional Commits. type(scope): summary, types limited to feat, fix, refactor, test, docs, chore, perf, build, ci; scope is package/feature area (feat(dictionary): add phonetic hint field). A commit-msg hook (simple-git-hooks + commitlint) enforces the format.
• Branch strategy. Trunk-based on main; feature branches named type/short-description (feat/voice-snippets-placeholders); no long-lived release branches — releases are tags cut from main (Section 37).
• PR checklist (enforced via PR template): description of the change and why; linked issue if any; pnpm lint, pnpm typecheck, pnpm test passing locally; new/changed IPC channels documented in Section 40's registry; screenshots/GIF for UI changes; note on which platforms were manually tested for native-addon-touching changes.
• Code review rules. At least one approving review before merge to main (branch protection); author cannot approve their own PR; changes touching packages/native, secrets/, or providers/ require a second reviewer familiar with that area if more than one maintainer is active, flagged via CODEOWNERS; CI (lint, typecheck, unit tests, license check) must be green before merge, no admin override.

5.6 Recipe — add a new STT provider #

1. Create apps/desktop/src/main/providers/stt/<id>.adapter.ts implementing the SttProvider interface from stt-provider.ts (methods: capabilities(), startSession(config), sendAudioFrame(frame), finalize(), cancel()).
2. Populate capabilities() truthfully (supportsStreaming, supportsLanguageAutoDetect, supportsKeywordBiasing, supportedLanguages) — Settings UI (FR-057) reads this to hide unsupported controls, so an inaccurate descriptor is a UI bug too.
3. Add the provider's default model id and connection mode to the registry table in stt-provider.ts (mirrors Section 12); never hardcode a model list elsewhere — model is always a user-editable string, this is just the default.
4. Add a Zod schema for the provider's credential/config shape (usually an API key, sometimes region/endpoint) to packages/shared/src/schemas/providers.ts.
5. Add the provider to the STT dropdown in renderer/settings/panels/ProvidersPanel.tsx — a data addition (step 3's registry, re-exported), not new component logic.
6. Add a LIVE_VALIDATE implementation for FR-039's key-verification flow — the minimal-cost authenticated health-check call the provider recommends.
7. Map the provider's HTTP/WebSocket errors to the STT_* namespace in Section 40; never invent a code outside that namespace.
8. Write adapter unit tests in apps/desktop/src/main/providers/stt/__tests__/<id>.adapter.test.ts against a mocked HTTP/WebSocket server (Vitest + msw, or a hand-rolled mock WS server for streaming providers).
9. Add the provider to the E2E fixture matrix in e2e/fixtures/ so at least one E2E dictation-flow test exercises it.
10. No other adapter file changes. If a second adapter's file needs touching, stt-provider.ts is missing an abstraction — revisit before shipping.

5.7 Recipe — add a new LLM provider #

1. Create apps/desktop/src/main/providers/llm/<id>.adapter.ts implementing LlmProvider (methods: capabilities(), complete(request), where request carries the prompt template id, variables, and the FR-060 timeout budget).
2. Populate capabilities() (supportsStreaming for future use, maxContextTokens, whether a baseUrl override is needed for OpenAI-compatible mode).
3. Add the provider's default model id to the registry in llm-provider.ts, mirroring Section 13; model id remains user-editable.
4. Add the credential schema to packages/shared/src/schemas/providers.ts.
5. Add the provider to the LLM dropdown in ProvidersPanel.tsx.
6. Implement LIVE_VALIDATE for FR-039's key-verification flow.
7. Map provider errors to the LLM_* namespace in Section 40 (quota/402 → LLM_QUOTA_EXCEEDED, timeout → LLM_TIMEOUT, 401 → LLM_AUTH_FAILED, 5xx/network → LLM_PROVIDER_ERROR).
8. Confirm the adapter works unmodified with both CLEANUP_PROMPT_TEMPLATE and COMMAND_PROMPT_TEMPLATE (Section 16) — it must not special-case which template it received; template selection is the caller's responsibility.
9. Write adapter unit tests against a mocked HTTP server covering success, timeout, 401, 402/quota, 5xx, and malformed-response-body cases.
10. Add the provider to the E2E fixture matrix. No changes to cleanup or command-mode call sites are needed or permitted.

6. Process Model, IPC & Application Lifecycle #

6.1 The four processes #

6.1.1 Main process #

The main process solely owns canonical application state and every capability requiring OS-level privilege or a persistent connection: application lifecycle (app.whenReady, quit sequencing, single-instance lock), the tray icon and quick menu, global hotkey registration, the native addon bridge, the dictation state machine, all provider (STT/LLM) network calls, the SQLite connection, the safeStorage-backed secret store, and the update controller. No renderer holds a direct handle to any of these — every interaction crosses the typed IPC surface in Section 6.3. It never renders UI itself; its only visible surface is the tray icon and the windows it creates.

6.1.2 Renderer: settings #

A standard BrowserWindow hosting the Settings/Preferences UI (Section 26), created once at startup and kept hidden (show: false) until opened from the tray or onboarding. Closing it hides it (event.preventDefault() on close, then hide()) rather than destroying it, so reopening is instant and in-progress renderer state (e.g., a mid-edit form) survives an unrelated tray action. It mirrors main-process state into Zustand stores via settings:changed, dictionary:changed, snippets:changed, and history:changed push events rather than polling.

6.1.3 Renderer: hud #

A small, frameless, always-on-top, transparent BrowserWindow (frame: false, transparent: true, alwaysOnTop: true, hasShadow: false, skipTaskbar: true) rendering the recording state indicator (Section 25). Created once at startup, positioned per Section 1 row 7, stays hidden (showInactive(), never show(), never stealing focus) until a session begins, and is click-through (setIgnoreMouseEvents(true, { forward: true })) while idle. It's interactive only for a rare actionable error requiring a click (e.g., "Add to dictionary?" in Section 3.3.4) — the addon toggles setIgnoreMouseEvents(false) and reverts immediately after.

6.1.4 Renderer: capture #

A permanently hidden BrowserWindow (show: false, no UI ever rendered) whose only job is audio capture: it holds the getUserMedia handle and an AudioWorklet that downsamples the device's native audio to 16 kHz mono PCM16 and posts frames to main over audio:frame. It's a separate renderer, not capture-in-main, because getUserMedia/Web Audio only exist in a renderer's web platform context, not Node.js; hidden and UI-less, it costs negligible extra memory over a bare renderer and never appears in any window list.

6.1.5 Preload #

Every renderer loads a preload script with contextIsolation: true, nodeIntegration: false, and sandbox: true. Its only job is exposing a narrow, typed window.api surface via contextBridge.exposeInMainWorld, wrapping every IPC channel — no renderer script calls ipcRenderer directly, and none has access to Node built-ins (fs, child_process, etc.) or Electron main-process modules. See Section 6.4 for the concrete surface.

6.2 Canonical IPC envelope #

// packages/core/src/ipc-envelope.ts
export type IpcResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: SerializedAppError };

export interface SerializedAppError {
  code: AppErrorCode;       // see Section 40 registry
  userMessage: string;
  retryable: boolean;
  remediation?: string;
}

Every ipcMain.handle handler returns Promise<IpcResult<T>> and never throws past its own boundary — internal errors are caught and mapped to SerializedAppError before resolving. Every window.api.* preload method returns Promise<IpcResult<T>> unchanged, so the renderer pattern-matches on .ok rather than try/catch for expected failure paths (catch is reserved for genuinely unexpected preload/transport failures). Channel names follow domain:verb for renderer-initiated request/response pairs (ipcMain.handle / ipcRenderer.invoke) and domain:event for main-initiated pushes (webContents.send / ipcRenderer.on).

6.3 Full typed IPC channel registry #

This registry (63 channels) is the authoritative list; Section 40 restates only the error-code namespace summary and cross-references this table rather than duplicating it.

Namespace extension note. This registry's error codes introduce two namespaces beyond the context record's originally approved set — DICTATION_* (dictation-session-lifecycle errors, e.g. DICTATION_INVALID_STATE) and DIAG_* (diagnostics-bundle errors, e.g. DIAG_BUNDLE_FAILED) — each scoped narrowly to the IPC channels above. Section 40's registry inherits both as approved extensions.

Export/import paths are always main-resolved, never renderer-supplied. export:settings, import:preview, and import:settings take no targetPath/sourcePath field from the renderer. The export:settings handler opens dialog.showSaveDialog itself and writes to whatever path the user picks; import:preview/import:settings open dialog.showOpenDialog and read from the picked path. A renderer-supplied path is never accepted on either channel — otherwise import:preview would be an arbitrary-file-read primitive and export:settings an arbitrary-file-write primitive, since the renderer's only trust boundary is the fixed IPC contract, not the path string.

6.4 Preload contextBridge surface #

// apps/desktop/src/preload/index.ts
import { contextBridge, ipcRenderer } from 'electron';
import type { IpcResult } from '@opendictate/core';
import type {
  AppSettings, SettingsPatch, DictationStateSnapshot, DictionaryEntry,
  Snippet, HistoryEntry, ProviderConfig, SttProviderDescriptor, LlmProviderDescriptor,
  PermissionStatus, AudioDevice, HotkeyBindings, OnboardingProgress, UpdateStatus,
  UpdateCheckResult, ImportPreview, ImportResult,
} from '@opendictate/shared';

const api = {
  dictation: {
    start: (mode: 'push-to-talk' | 'toggle'): Promise<IpcResult<{ sessionId: string }>> =>
      ipcRenderer.invoke('dictation:start', { mode }),
    stop: (sessionId: string): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('dictation:stop', { sessionId }),
    cancel: (sessionId: string): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('dictation:cancel', { sessionId }),
    getState: (): Promise<IpcResult<DictationStateSnapshot>> =>
      ipcRenderer.invoke('dictation:get-state'),
    commandModeStart: (): Promise<IpcResult<{ sessionId: string }>> =>
      ipcRenderer.invoke('dictation:command-mode-start'),
    commandModeCancel: (sessionId: string): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('dictation:command-mode-cancel', { sessionId }),
    onStateChanged: (cb: (s: DictationStateSnapshot) => void): (() => void) => {
      const listener = (_: unknown, s: DictationStateSnapshot) => cb(s);
      ipcRenderer.on('dictation:state-changed', listener);
      return () => ipcRenderer.removeListener('dictation:state-changed', listener);
    },
    onInterimTranscript: (cb: (p: { sessionId: string; text: string }) => void): (() => void) => {
      const listener = (_: unknown, p: { sessionId: string; text: string }) => cb(p);
      ipcRenderer.on('dictation:interim-transcript', listener);
      return () => ipcRenderer.removeListener('dictation:interim-transcript', listener);
    },
  },
  settings: {
    get: (): Promise<IpcResult<AppSettings>> => ipcRenderer.invoke('settings:get'),
    update: (patch: SettingsPatch): Promise<IpcResult<AppSettings>> =>
      ipcRenderer.invoke('settings:update', patch),
    resetDefaults: (section: string): Promise<IpcResult<AppSettings>> =>
      ipcRenderer.invoke('settings:reset-defaults', { section }),
    onChanged: (cb: (s: AppSettings) => void): (() => void) => {
      const listener = (_: unknown, s: AppSettings) => cb(s);
      ipcRenderer.on('settings:changed', listener);
      return () => ipcRenderer.removeListener('settings:changed', listener);
    },
  },
  dictionary: {
    list: (query?: string, limit?: number, offset?: number): Promise<IpcResult<DictionaryEntry[]>> =>
      ipcRenderer.invoke('dictionary:list', { query, limit, offset }),
    add: (entry: Omit<DictionaryEntry, 'id' | 'createdAt' | 'updatedAt'>): Promise<IpcResult<DictionaryEntry>> =>
      ipcRenderer.invoke('dictionary:add', entry),
    update: (entry: Partial<DictionaryEntry> & { id: string }): Promise<IpcResult<DictionaryEntry>> =>
      ipcRenderer.invoke('dictionary:update', entry),
    delete: (id: string): Promise<IpcResult<void>> => ipcRenderer.invoke('dictionary:delete', { id }),
    confirmCandidate: (candidateId: string, accept: boolean): Promise<IpcResult<DictionaryEntry | null>> =>
      ipcRenderer.invoke('dictionary:confirm-candidate', { candidateId, accept }),
    onChanged: (cb: (p: { reason: 'add' | 'update' | 'delete' }) => void): (() => void) => {
      const listener = (_: unknown, p: { reason: 'add' | 'update' | 'delete' }) => cb(p);
      ipcRenderer.on('dictionary:changed', listener);
      return () => ipcRenderer.removeListener('dictionary:changed', listener);
    },
  },
  snippets: {
    list: (): Promise<IpcResult<Snippet[]>> => ipcRenderer.invoke('snippets:list'),
    create: (s: Omit<Snippet, 'id' | 'createdAt' | 'updatedAt'>): Promise<IpcResult<Snippet>> =>
      ipcRenderer.invoke('snippets:create', s),
    update: (s: Partial<Snippet> & { id: string }): Promise<IpcResult<Snippet>> =>
      ipcRenderer.invoke('snippets:update', s),
    delete: (id: string): Promise<IpcResult<void>> => ipcRenderer.invoke('snippets:delete', { id }),
    onChanged: (cb: (p: { reason: 'create' | 'update' | 'delete' }) => void): (() => void) => {
      const listener = (_: unknown, p: { reason: 'create' | 'update' | 'delete' }) => cb(p);
      ipcRenderer.on('snippets:changed', listener);
      return () => ipcRenderer.removeListener('snippets:changed', listener);
    },
  },
  history: {
    list: (opts: { limit?: number; offset?: number; since?: number }): Promise<IpcResult<HistoryEntry[]>> =>
      ipcRenderer.invoke('history:list', opts),
    get: (id: string): Promise<IpcResult<HistoryEntry>> => ipcRenderer.invoke('history:get', { id }),
    deleteEntry: (id: string): Promise<IpcResult<void>> => ipcRenderer.invoke('history:delete-entry', { id }),
    clearAll: (): Promise<IpcResult<{ deletedCount: number }>> => ipcRenderer.invoke('history:clear-all'),
    onChanged: (cb: (p: { reason: 'insert' | 'delete' | 'clear' }) => void): (() => void) => {
      const listener = (_: unknown, p: { reason: 'insert' | 'delete' | 'clear' }) => cb(p);
      ipcRenderer.on('history:changed', listener);
      return () => ipcRenderer.removeListener('history:changed', listener);
    },
  },
  providers: {
    listStt: (): Promise<IpcResult<SttProviderDescriptor[]>> => ipcRenderer.invoke('providers:list-stt'),
    listLlm: (): Promise<IpcResult<LlmProviderDescriptor[]>> => ipcRenderer.invoke('providers:list-llm'),
    getConfig: (): Promise<IpcResult<ProviderConfig>> => ipcRenderer.invoke('providers:get-config'),
    setActive: (kind: 'stt' | 'llm', providerId: string, model: string): Promise<IpcResult<ProviderConfig>> =>
      ipcRenderer.invoke('providers:set-active', { kind, providerId, model }),
    validateKey: (kind: 'stt' | 'llm', providerId: string, apiKey: string): Promise<IpcResult<{ valid: boolean; reason?: string }>> =>
      ipcRenderer.invoke('providers:validate-key', { kind, providerId, apiKey }),
  },
  keys: {
    save: (kind: 'stt' | 'llm', providerId: string, apiKey: string): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('keys:save', { kind, providerId, apiKey }),
    delete: (kind: 'stt' | 'llm', providerId: string): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('keys:delete', { kind, providerId }),
    hasKey: (kind: 'stt' | 'llm', providerId: string): Promise<IpcResult<{ present: boolean }>> =>
      ipcRenderer.invoke('keys:has-key', { kind, providerId }),
  },
  permissions: {
    getStatus: (): Promise<IpcResult<PermissionStatus>> => ipcRenderer.invoke('permissions:get-status'),
    requestMicrophone: (): Promise<IpcResult<{ status: 'granted' | 'denied' }>> =>
      ipcRenderer.invoke('permissions:request-microphone'),
    openSystemSettings: (pane: 'accessibility' | 'microphone' | 'input-monitoring'): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('permissions:open-system-settings', { pane }),
    onChanged: (cb: (s: PermissionStatus) => void): (() => void) => {
      const listener = (_: unknown, s: PermissionStatus) => cb(s);
      ipcRenderer.on('permissions:changed', listener);
      return () => ipcRenderer.removeListener('permissions:changed', listener);
    },
  },
  audio: {
    listDevices: (): Promise<IpcResult<AudioDevice[]>> => ipcRenderer.invoke('audio:list-devices'),
    testRecord: (deviceId: string, durationMs: number): Promise<IpcResult<{ clipId: string }>> =>
      ipcRenderer.invoke('audio:test-record', { deviceId, durationMs }),
    testPlayback: (clipId: string): Promise<IpcResult<void>> =>
      ipcRenderer.invoke('audio:test-playback', { clipId }),
    onLevelChanged: (cb: (p: { rms: number }) => void): (() => void) => {
      const listener = (_: unknown, p: { rms: number }) => cb(p);
      ipcRenderer.on('audio:level-changed', listener);
      return () => ipcRenderer.removeListener('audio:level-changed', listener);
    },
  },
  update: {
    check: (): Promise<IpcResult<UpdateCheckResult>> => ipcRenderer.invoke('update:check'),
    download: (): Promise<IpcResult<void>> => ipcRenderer.invoke('update:download'),
    installAndRestart: (): Promise<IpcResult<void>> => ipcRenderer.invoke('update:install-and-restart'),
    onStatusChanged: (cb: (s: UpdateStatus) => void): (() => void) => {
      const listener = (_: unknown, s: UpdateStatus) => cb(s);
      ipcRenderer.on('update:status-changed', listener);
      return () => ipcRenderer.removeListener('update:status-changed', listener);
    },
  },
  onboarding: {
    getProgress: (): Promise<IpcResult<OnboardingProgress>> => ipcRenderer.invoke('onboarding:get-progress'),
    completeStep: (step: string): Promise<IpcResult<OnboardingProgress>> =>
      ipcRenderer.invoke('onboarding:complete-step', { step }),
    replay: (): Promise<IpcResult<void>> => ipcRenderer.invoke('onboarding:replay'),
  },
  // targetPath/sourcePath are never accepted from the renderer on either channel below — the
  // main-process handler always resolves the path itself via dialog.showSaveDialog (export) or
  // dialog.showOpenDialog (import). A renderer-supplied path is never wired up, since that would
  // make import:preview an arbitrary-file-read primitive and export:settings an arbitrary-file-
  // write primitive.
  export: {
    settings: (): Promise<IpcResult<{ path: string }>> => ipcRenderer.invoke('export:settings'),
  },
  import: {
    preview: (): Promise<IpcResult<ImportPreview>> => ipcRenderer.invoke('import:preview'),
    settings: (mode: 'merge' | 'replace'): Promise<IpcResult<ImportResult>> =>
      ipcRenderer.invoke('import:settings', { mode }),
  },
  diagnostics: {
    copyBundle: (): Promise<IpcResult<{ copied: true }>> => ipcRenderer.invoke('diagnostics:copy-bundle'),
    openLogFolder: (): Promise<IpcResult<void>> => ipcRenderer.invoke('diagnostics:open-log-folder'),
  },
  hotkeys: {
    get: (): Promise<IpcResult<HotkeyBindings>> => ipcRenderer.invoke('hotkeys:get'),
    set: (patch: Partial<HotkeyBindings>): Promise<IpcResult<HotkeyBindings>> =>
      ipcRenderer.invoke('hotkeys:set', patch),
    startCapture: (): Promise<IpcResult<void>> => ipcRenderer.invoke('hotkeys:start-capture'),
    onConflict: (cb: (p: { accelerator: string }) => void): (() => void) => {
      const listener = (_: unknown, p: { accelerator: string }) => cb(p);
      ipcRenderer.on('hotkeys:conflict', listener);
      return () => ipcRenderer.removeListener('hotkeys:conflict', listener);
    },
  },
} as const;

contextBridge.exposeInMainWorld('api', api);

export type OpenDictateApi = typeof api;

Every renderer's global.d.ts declares interface Window { api: OpenDictateApi } by importing the exported type, giving full autocomplete and type-checking on window.api.* calls with zero any. The api object above maps all 63 registered channels except audio:start-capture, audio:stop-capture, and audio:frame — those three M→R(capture)/R(capture)→M channels are used internally between main and the hidden capture renderer (Section 6.1.4), bound in capture's own separate, narrower preload script instead.

6.5 Master dictation state machine #

States: IDLE, ARMED, RECORDING, FINALIZING, TRANSCRIBING, FORMATTING, INSERTING, ERROR, COOLDOWN.

ARMED is the brief guard state between hotkey-down and confirmed mic readiness (permission, secure-field, device checks) — it exists so a failure before audio starts (e.g., FR-005's secure-field block) never has to unwind a RECORDING state. TRANSCRIBING covers stream-close to receipt of the STT provider's final transcript, distinct from FINALIZING (the local stop-capture handshake before the stream even closes).

Only one session may be active at a time; a hotkey press while any state other than IDLE is current is treated as dictation.cancel for the in-flight session (RECORDING/ARMED) or, from FINALIZING through INSERTING, rejected outright per the rows above (brief "still finishing the last one" HUD indication, press discarded) — never queued or stacked.

6.6 Application lifecycle #

6.6.1 Cold start sequence (with target timings) #

Total cold start to "hotkey is live and can start a recording" target: under 150 ms on reference hardware (a mid-tier 2021+ machine) — well inside a user's patience before first use, and distinct from the steady-state per-dictation latency budget in Section 31 governing every dictation once the app is already running.

6.6.2 Warm resume #

Because settings and hud windows are hidden rather than destroyed on close, "resume" is simply clicking the tray icon or pressing the hotkey — no separate warm-start code path exists; the app is either running (tray icon present, hotkeys live) or not running at all, with no background-daemon/foreground-app split.

6.6.3 Sleep / wake #

On powerMonitor.on('suspend'): if a session is active (any state other than IDLE), force-cancel it per the system.sleep transition (Section 6.5) — buffered audio discarded, STT stream closed without awaiting a result, HUD hides immediately (sleep mid-recording produces unusable, gapped audio regardless of provider). On powerMonitor.on('resume'): re-verify microphone/accessibility permission (macOS can silently revoke Accessibility trust after some OS updates) and re-register global hotkeys (some Windows configs drop low-level hooks across sleep/wake); a mismatch triggers silent re-registration, not a user-facing error, unless re-registration itself fails.

6.6.4 Display change #

On screen.on('display-added'), display-removed, or display-metrics-changed: the hud window's position is recomputed relative to the display containing the OS cursor (Section 1 row 7) next time it's shown — not while invisible, avoiding unnecessary work on multi-monitor setups where displays connect/disconnect frequently (e.g., docking a laptop). The settings window, if visible, is nudged back on-screen if a display removal would leave it entirely off the remaining display bounds.

6.6.5 Quit #

Triggered via tray menu "Quit OpenDictate", Cmd+Q when a window is focused (macOS), or OS shutdown/logoff. Sequence: force-cancel any active session (app.quit-requested) → unregister all global hotkeys → close the native addon's event tap/hook → flush and close SQLite → close all BrowserWindow instances → app.quit(). macOS: no Dock icon, app.dock never shown, so there's no "windows closed but still running" ambiguity — quit is always explicit via the tray menu; closing Settings alone never quits (app.on('window-all-closed') is a no-op).

6.6.6 Crash recovery #

If main itself crashes (extremely rare, guarded by NFR-013/NFR-018's error-boundary discipline), the OS simply ends the process — no supervisor process exists in v1, matching the four-process model's lack of a fifth "watchdog" (Section 4.2). If a renderer crashes (webContents.on('render-process-gone')), main recreates that BrowserWindow: hud/capture recreate silently and immediately (no unsaved state); settings shows a small inline banner on next open ("Settings reloaded after an unexpected error") if visible during the crash, losing no canonical data since its Zustand stores rehydrate from main via the same *:get/*:changed channels used at first load.

6.6.7 Single-instance lock #

Enforced via app.requestSingleInstanceLock() at the very start of the main entry point, before any window or hotkey is created. A second launch attempt hits app.on('second-instance') in the already-running instance, which shows and focuses settings rather than doing nothing, so the user always gets visible feedback the app was already running.

6.6.8 Launch at login #

A Settings → General toggle wraps app.setLoginItemSettings({ openAtLogin: true, openAsHidden: true }) (macOS) / the equivalent Windows registry-run-key mechanism electron-builder's NSIS target wires up; openAsHidden: true ensures a login launch never flashes a visible window, landing in the same hidden-tray-icon steady state as any other cold start once onboarding is complete. Defaults to on after onboarding (a dictation app needing manual relaunch every login has little ongoing value), with an explicit toggle to turn it off.

6.7 Window management rules #

• Exactly one instance of each of the three window types (settings, hud, capture) exists for the app's lifetime — none are ever duplicated, none fully destroyed and recreated except via the crash-recovery path in Section 6.6.6.
• hud is always alwaysOnTop: true at the screen-saver level (macOS) / topmost (Windows) so it stays visible over full-screen applications during a dictation, since users frequently dictate while the target app (a video call, a full-screen editor) is itself full-screen.
• settings is a normal window otherwise (resizable, minimizable, standard title-bar controls) and the only one that ever appears in the OS window-switcher (Cmd+Tab / Alt-Tab); hud and capture are excluded (skipTaskbar: true and the macOS equivalent) since they aren't user-addressable surfaces.
• No window is ever created with Node integration enabled; every BrowserWindow's webPreferences sets contextIsolation: true, nodeIntegration: false, sandbox: true, and a preload path — no exception for capture despite needing raw device access, since getUserMedia is a standard web platform API available without Node integration.

6.8 Cross-references #

The canonical error model and full error-code registry are defined once in Section 40 and referenced by code (AppErrorCode) rather than restated. The SQLite schema backing the repositories above (dictionary, snippets, history, settings, provider keys) is defined once in Section 17. The safeStorage-backed secret store's key-wrapping details live in Section 18. Provider adapter internals (STT/LLM request/response shapes) are defined once in Sections 12 and 13; this section only establishes the process boundary and IPC contract they're invoked through.

7. Global Hotkey & Activation System #

7.1 Activation modes #

OpenDictate supports exactly two activation modes, both always configured — a user has a binding for each, though only one is "active" at a time via dictation.activationMode:

• Push-to-talk (PTT) — held down; recording starts on key-down, stops on key-up, triggering stop → finalize immediately with no confirmation step. PTT is the default activation mode (dictation.activationMode: "push-to-talk").
• Toggle — pressed once to start recording, again to stop and finalize. A toggle session can also auto-stop via the silence-timeout VAD path or max-utterance cap (both Section 8.6), or be cancelled with Esc (Section 7.9).

Both bindings (hotkeys.pushToTalk, hotkeys.toggle) exist simultaneously in settings, so switching dictation.activationMode never discards the other mode's combo. Only the active binding is "live" (registered with the OS/uiohook); the other is dormant, re-registered instantly on mode switch (Section 26 owns the settings UI; this section owns binding semantics and capture mechanism).

Only one dictation session may be active system-wide at any time, regardless of mode. The canonical state machine — IDLE, ARMED, RECORDING, FINALIZING, TRANSCRIBING, FORMATTING, INSERTING, ERROR, COOLDOWN — is defined once, in Section 6.5; this section defines only the raw input events driving transitions: IDLE/ARMED → RECORDING on activation, RECORDING → FINALIZING on release/second-press/auto-stop.

7.2 Default bindings per OS #

This table is the canonical source for every OpenDictate hotkey default on both platforms — Section 17.9 seed data, Section 26.4, Section 40.2, Section 40.6, and Milestone M3 must match it exactly. Accelerator strings are spelled out per OS; the Electron CommandOrControl alias is never used, since it resolves to Cmd on macOS and Ctrl on Windows and caused a Cmd-vs-Ctrl divergence found in review.

Fn/Right Ctrl are PTT defaults for being rarely used in typing and physically distinct from OS combos; Command+Shift+Space/Control+Super+Space are toggle defaults for not colliding with the 7.5 reserved tables on a stock install; Command+Shift+K/Control+Shift+K is the Command Mode default, chosen close to the toggle combo (+K vs. +Space) to read as "the other dictation hotkey."

7.3 Capture mechanism: uiohook-napi + Electron globalShortcut #

Two capture mechanisms work together, each covering a gap the other cannot:

uiohook-napi (bundled in @opendictate/native, wrapping the libuiohook C library via N-API) installs a low-level, system-wide input hook — CGEventTap on macOS, WH_KEYBOARD_LL via SetWindowsHookEx on Windows — delivering raw key-down and key-up events with full modifier state, for every key, regardless of focus. Required for:

1. Push-to-talk, a hold-and-release gesture — globalShortcut fires only on an accelerator's down-edge with no key-up event, so PTT release detection is impossible with it alone.
2. Modifier-only bindings (Fn alone, Right Ctrl alone) — globalShortcut accelerators require at least one non-modifier key or an enumerated combination; a bare modifier can't be registered through that API.
3. Double-tap gestures — need timing analysis across two discrete down/up cycles of the same key, requiring raw event access.

Electron globalShortcut is the registration path for toggle-mode standard accelerator combos (e.g. Cmd+Shift+Space), preferred as primary since it uses the OS's own hotkey-registration API (Carbon RegisterEventHotKey on macOS, RegisterHotKey on Windows), which unlike uiohook doesn't require Accessibility/Input Monitoring on macOS — a Microphone-only user still gets a working toggle hotkey. uiohook-napi runs in parallel at all times (required for PTT and double-tap detection) and acts as fallback for toggle combos if globalShortcut registration fails (Section 7.8), matching the combo against the raw uiohook stream, at the cost of requiring Accessibility/Input Monitoring.

Both engines feed a single internal HotkeyManager in the main process, the sole component emitting normalized hotkey:* domain events to the dictation state machine; renderers never touch either capture API directly.

Keystroke data is never logged or persisted, beyond transient hotkey-matching state. uiohook-napi's raw hook is, architecturally, a system-wide keylogger — it sees every key regardless of focus, for as long as the app runs. Per Section 32.1's threat model, the Accessibility/Input Monitoring permissions OpenDictate requires are the same class a real keylogger would request. That capability stays structurally scoped to hotkey-matching only, symmetric to the audio guarantee in 8.10:

1. No filesystem imports in the hotkey path. HotkeyManager and every module under apps/main/src/hotkeys/** have zero dependency on fs/node:fs or any file-writing API, enforced by an ESLint rule scoped to that path (same family as 8.10's audio-path ban).
2. No logging of key identity or sequence. A second ESLint rule bans any log.*() call under apps/main/src/hotkeys/** from taking a key, keys, or HotkeyRecordEvent-shaped argument; log lines may carry only counts, timings, and error codes. A unit test intercepts the hotkey module's logger calls and fails if any argument is a raw key name, key code, or HotkeyRecordEvent/pressedKeys value — same enforcement pattern as 8.10's audio.
3. Retained state is transient and bounded. The only in-memory key state is the pressedKeys: Set<string> (auto-repeat suppression, 7.7) and the recorder UI's live chip buffer (7.4) — both scoped to the current hold/recording session, discarded on key-up/recorder-close, and never serialized, written to SQLite, or included in the diagnostics bundle (Section 33).

7.4 Hotkey recorder UI contract #

Settings → Hotkeys → "Change" next to a binding opens the recorder:

1. The input area enters a recording visual state (pulsing border) with placeholder text "Press keys…". The recorder requires Input Monitoring (macOS) granted before starting — if not, the button becomes "Grant Input Monitoring access", opening the deep link from 11.4; no partial/best-effort recording is attempted, since silently missing key-up events would produce corrupted bindings.
2. While recording, every uiohook key-down updates a live chip row showing the currently-held keys in canonical order (modifiers first — Ctrl, Alt, Shift, Cmd/Win — then the non-modifier key, e.g. Ctrl + Shift + D).
3. Finalization happens on whichever comes first:
   • All keys release after at least one non-modifier key (or an explicitly-enabled modifier-only target, see below) was held — the combo at maximum simultaneous key-down is captured as the binding.
   • 2,000 ms elapse with no new key-down and no keys held (covers a user who pressed and released a single key slowly).
4. Modifier-only targets aren't entered by pressing one modifier in the normal recorder — a separate "Use a modifier key alone (e.g. double-tap)" toggle switches to gesture-capture mode, recording a single modifier key paired with a double-tap requirement (7.6), preventing accidental binding of a bare modifier via a combo-press mistake.
5. Validation runs immediately on finalization, before Save is enabled:
   • Reject if the combo matches an entry in the OS-reserved table (7.5). Inline error: "This shortcut is reserved by macOS and can't be used" (or "by Windows").
   • Reject if the combo is already assigned to the other OpenDictate action (e.g. editing PTT and picking Toggle's combo). Inline error offers "Swap bindings?" as a one-click resolution.
   • Reject a single unmodified letter, digit, arrow, or punctuation key with no modifier (breaks normal typing in every application) unless the modifier-only gesture path (step 4) is active.
   • Escape can never be part of a recorded combo — it's reserved universally as the cancel gesture (7.9), and pressing it while recording aborts the recorder rather than being captured as input (see 7.9).
   • Function keys F1–F10 are allowed with a soft warning ("this key may be mapped to a hardware function like brightness or volume on some keyboards and may not reach OpenDictate"), since OS-level media-key remapping intercepts them before uiohook sees them on some laptop firmware; F11/F12 are hard-blocked on macOS only (Mission Control / Show Desktop, see 7.5).
6. Save commits the binding, re-registers it live with the HotkeyManager, and immediately unregisters the previous combo. Cancel (explicit button, or Esc per 7.9) reverts to the previously saved binding, no side effects.

7.5 OS-reserved shortcuts and conflict detection #

The recorder statically rejects any combo in the tables below — shortcuts the OS consumes below any application (in most cases below uiohook's hook point), so even if HotkeyManager could register them, the OS action would fire instead of, or in addition to, OpenDictate's, producing confusing dual behavior. Rejection beats a silent partial-failure.

macOS reserved combos:

Windows reserved combos:

Conflict detection is static and recording-time only — OpenDictate doesn't attempt runtime detection of "another app also wants this combo" beyond the registration failure path in 7.8, since no cross-platform API enumerates other apps' registered hotkeys in advance.

7.6 Modifier-only bindings (double-tap gestures) #

Double-tap gestures apply only to the opt-in alternate toggle bindings (7.2) and any modifier-only PTT-adjacent gesture configured via the recorder's gesture mode (7.4 step 4). Detection state machine, per candidate key:

• Tap validity window: a physical press counts as a "tap" only if down-to-up duration is ≤ 300 ms. Longer holds are an ordinary hold of that modifier (doing nothing unless that key is also the bound PTT key) and cancel any in-progress double-tap sequence.
• Inter-tap gap: the gap between tap 1's key-up and tap 2's key-down must be ≥ 40 ms (filters key-bounce/contact chatter misread as two taps) and ≤ 350 ms (recognition window); outside it, the sequence resets and tap 2 becomes a fresh tap 1.
• Firing point: once tap 2's key-down is observed within the valid window, the gesture fires immediately, not waiting for tap 2's key-up, keeping latency in line with the no-added-delay principle in 7.7.
• Triple-tap and beyond: a third key-down within 350 ms of a just-fired gesture is ignored entirely (not queued, not a new gesture start) for 400 ms after firing, preventing a fast triple-press from firing the toggle twice.

7.7 Debounce, repeat-suppression, and hold thresholds #

• No artificial delay on primary activation. For an ordinary single-key or combo PTT binding, recording starts on the first raw key-down event with zero added debounce, required to hit the 80 ms p50 / 150 ms p95 "hotkey press → mic capturing" budget in Section 31. A minimum-hold requirement would add latency to every legitimate press, so none applies to primary activation.
• OS auto-repeat suppression is stateful, not time-based: HotkeyManager maintains a pressedKeys: Set<string> keyed by uiohook's raw key code. A key-down for a code already in the set is dropped unconditionally — collapsing the OS's repeated key-down-while-held stream (platforms repeat at different rates depending on OS keyboard-repeat settings) into a single logical "key became down" transition, with no timing window to tune. The code is removed on the corresponding key-up.
• Minimum-hold-to-count (300 ms tap ceiling, 40–350 ms inter-tap gap) applies only to double-tap recognition (7.6), never to ordinary PTT/toggle activation.
• Debounce for the recorder UI (7.4) uses the same stateful pressedKeys dedupe, so the live chip display never flickers from OS auto-repeat while a key is held.

7.8 Failure handling #

7.9 Cancel gestures #

7.10 Behavior when the target application changes mid-recording #

Audio capture is entirely application-agnostic — bound to a microphone device, not a window — so switching focus to a different application (Alt-Tab/Cmd-Tab, clicking another window) while a PTT key is held or a toggle session is active does not interrupt recording. What governs where the resulting text goes:

• AppContext (Section 9) is resolved twice per session: at session-start (tints the HUD, pre-selects a tone preset for live formatting, Section 14) and, authoritatively, at session-stop. The stop-time resolution determines the insertion target (Section 10) — text is always inserted into whichever application is frontmost when the user finishes speaking, not whichever was frontmost at start.
• If focus has moved to one of OpenDictate's own windows (Settings, or the HUD itself gaining focus) by stop-time, insertion is impossible by definition (the app can't inject text into its own non-text-field chrome); treated identically to the total-insertion-failure path in Section 10.9 — clipboard-only with a persistent notification.
• If focus has moved to a secure field (Section 9.6) by stop-time, the session still completes transcription/formatting (text isn't lost), but insertion is hard-blocked exactly as at session-start, falling through to the clipboard-only path with a notice explaining why automatic insertion was skipped.

7.11 Event → action table #

7.12 IPC surface and types #

Channel naming follows the domain:verb / domain:event convention from Section 4.3, using the hotkey domain:

export interface HotkeyBinding {
  keys: string[];            // canonical order: modifiers first (Ctrl, Alt, Shift, Cmd/Win), then base key
  isModifierOnlyGesture: boolean; // true for double-tap-style bindings (7.6)
  doubleTapWindowMs?: number;     // present only when isModifierOnlyGesture is true; fixed at 350
}

export interface HotkeyRecordEvent {
  type: 'keydown' | 'keyup';
  key: string;               // normalized key name, e.g. "Fn", "RightControl", "D"
  isModifier: boolean;
  timestampMs: number;
}

7.13 Acceptance criteria #

8. Audio Capture & Streaming Pipeline #

8.1 Canonical capture path, end to end #

The hidden capture BrowserWindow (Section 4.2) is created once at launch and kept alive for the app's lifetime — never destroyed and recreated per session — to avoid getUserMedia/AudioContext cold-start latency and to support the pre-roll buffer (8.5), which needs the pipeline already running before the hotkey fires.

1. Main's HotkeyManager (Section 7) emits a hotkey:start-derived signal that the dictation state machine (Section 6) turns into AudioPipeline.beginSession().
2. Main sends control IPC audio:start to the capture renderer (JSON payload: target device ID, session ID, provider mode streaming/batch).
3. The capture renderer's preload-exposed window.api.audio.start(deviceId) resolves the already-open MediaStream (opened at arm-time, see 8.5) or opens a fresh one if fastStart.enabled is false, via navigator.mediaDevices.getUserMedia({ audio: { deviceId: { exact: deviceId }, channelCount: 1, echoCancellation: false, noiseSuppression: true, autoGainControl: true } }).
4. An AudioContext is constructed with { sampleRate: <device native rate> } (never forced to 16000 — that would force double resampling); the track connects via audioContext.createMediaStreamSource(stream).
5. audioContext.audioWorklet.addModule('pcm-frame-processor.js') registers the processor (8.3); an AudioWorkletNode is created and connected downstream of the source node (no connection to destination — capture never plays audio back except in the explicit mic-test flow, 8.8).
6. The worklet's process() callback runs once per 128-sample render quantum (Web Audio's fixed block size, independent of the target 20 ms framing), performs anti-alias filtering and downsampling (8.3), and accumulates output into 320-sample (20 ms @ 16 kHz) PCM16LE frames, posted via port.postMessage.
7. The renderer's main-thread workletNode.port.onmessage listener forwards each frame buffer, unmodified, over a pre-established MessageChannelMain port (opened once at audio:start, not per-frame) to main — bypassing ipcMain to avoid control-channel contention and the structured-clone overhead of default IPC serialization for a 50-frames/second binary stream.
8. Main's AudioPipeline receives each frame on the MessagePort, timestamps it, runs VAD (8.6) and clip-detection (8.9) bookkeeping, and forwards it either to the active streaming SttProvider adapter's WebSocket or the batch-mode accumulation buffer (8.11), depending on provider mode (Section 12 (STT) / Section 13 (LLM)).
9. On session stop (any path in the 7.11 event table), main sends audio:stop over the same control channel; the renderer disconnects the worklet node from the source (but does not stop the MediaStreamTrack when fastStart.enabled is true — it stays open, feeding only the pre-roll ring buffer, ready for the next session) and flushes any partial final frame (zero-padded to 320 samples if fewer are available).

8.2 Audio format and resampling #

Canonical wire format for every downstream consumer (streaming providers, the batch accumulation buffer, the pre-roll ring): 16 kHz, mono, PCM16 little-endian, 20 ms frames (320 samples = 640 bytes per frame). Fixed, not user-configurable: matches what every v1 STT provider (Section 12) accepts without server-side resampling loss, keeping buffer-sizing calculations in this section exact.

Devices rarely expose 16 kHz natively — macOS CoreAudio and Windows WASAPI shared-mode typically default to 48000 Hz (44100 Hz still seen on some older/USB interfaces). Rather than let the browser resample at unspecified quality when AudioContext's rate mismatches the device, AudioContext is constructed at the device's native rate and OpenDictate downsamples in the worklet:

1. Anti-alias low-pass filter — a 31-tap linear-phase FIR filter with cutoff at roughly half the target Nyquist (~7500 Hz at typical 48 kHz source rate), applied to every input sample before decimation, preventing frequencies above 8 kHz folding into audible artifacts once downsampled to 16 kHz.
2. Fractional-ratio decimation via linear interpolation — the source-to-target ratio is rarely an integer (48000/16000 = 3.0, but 44100/16000 = 2.75625), so output samples are generated by walking a fractional read cursor across the filtered input stream, linearly interpolating between the two nearest filtered samples at each output instant — handling both integer and non-integer ratios with one code path.

8.3 The AudioWorklet processor #

// resources/audio/pcm-frame-processor.js
// Downsamples mic input to 16 kHz mono PCM16LE, emitting one 20 ms
// (320-sample / 640-byte) frame per postMessage call.

const FIR_LOWPASS_31 = new Float32Array([
  -0.0013, -0.0021, -0.0011, 0.0025, 0.0071, 0.0087, 0.0032, -0.0095,
  -0.0238, -0.0294, -0.0159, 0.0227, 0.0790, 0.1382, 0.1803, 0.1959,
  0.1803, 0.1382, 0.0790, 0.0227, -0.0159, -0.0294, -0.0238, -0.0095,
  0.0032, 0.0087, 0.0071, 0.0025, -0.0011, -0.0021, -0.0013,
]); // 31-tap linear-phase FIR, cutoff ~7.5 kHz @ 48 kHz source, designed offline

class PcmFrameProcessor extends AudioWorkletProcessor {
  constructor() {
    super();
    this.targetRate = 16000;
    this.sourceRate = sampleRate; // AudioWorkletGlobalScope global
    this.ratio = this.sourceRate / this.targetRate; // e.g. 3.0 @48k, 2.75625 @44.1k
    this.frameSamples = 320; // 20 ms @ 16 kHz
    this.outBuffer = new Int16Array(this.frameSamples);
    this.outIndex = 0;
    this.delay = new Float32Array(FIR_LOWPASS_31.length);
    this.prevFiltered = 0;
    this.cursor = 0; // fractional position, in source samples, of the next output sample
    this.inputIndex = 0;
  }

  lowpass(sample) {
    this.delay.copyWithin(1, 0, this.delay.length - 1);
    this.delay[0] = sample;
    let acc = 0;
    for (let i = 0; i < FIR_LOWPASS_31.length; i++) acc += this.delay[i] * FIR_LOWPASS_31[i];
    return acc;
  }

  process(inputs) {
    const channel = inputs[0] && inputs[0][0];
    if (!channel || channel.length === 0) return true;

    for (let i = 0; i < channel.length; i++) {
      const filtered = this.lowpass(channel[i]);

      while (this.cursor < this.inputIndex + 1) {
        const frac = this.cursor - this.inputIndex;
        const interpolated = this.prevFiltered + (filtered - this.prevFiltered) * frac;
        const clamped = Math.max(-1, Math.min(1, interpolated));
        this.outBuffer[this.outIndex++] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
        if (this.outIndex === this.frameSamples) {
          const frame = this.outBuffer.slice();
          this.port.postMessage({ type: 'pcm-frame', buffer: frame.buffer }, [frame.buffer]);
          this.outIndex = 0;
        }
        this.cursor += this.ratio;
      }
      this.prevFiltered = filtered;
      this.inputIndex++;
    }
    return true;
  }
}

registerProcessor('pcm-frame-processor', PcmFrameProcessor);

The processor allocates nothing in the hot per-sample loop beyond the Int16Array slice taken at frame completion (the buffer is transferred, not copied, avoiding two live references to the same ArrayBuffer); outBuffer is a fixed allocation reused for the object's lifetime.

Valid source-rate range for FIR_LOWPASS_31: coefficients are designed offline for a ~7.5 kHz cutoff against a 48 kHz source rate (the most common native rate, per 8.2), applied uniformly regardless of actual native rate, including other rates seen in the wild (44.1 kHz, 96 kHz). At 44.1 kHz the cutoff shifts slightly but anti-aliasing stays adequate (44.1/2 = 22.05 kHz of headroom, well above the design cutoff); at 96 kHz the fixed 31-tap filter's relative cutoff is well below optimal, degrading anti-alias performance versus a rate-matched filter. Accepted approximation, not a correctness bug — decimation to 16 kHz remains correct at every observed rate — but a future revision recalculating coefficients per detected source rate would tighten this.

8.4 Ring buffer sizing and back-pressure #

Two buffers exist in the main process, each sized for a different purpose:

• Streaming jitter ring buffer — capacity 2 seconds (200 frames, 64,000 bytes). Absorbs backpressure between frame arrival and the WebSocket send. If bufferedAmount exceeds 256 KB, the pipeline pauses direct forwarding and routes new frames into this ring instead; once bufferedAmount drains below the threshold, buffered frames flush in order. If the ring fills (2 s of sustained backpressure — normal networking rarely sustains this; bufferedAmount typically drains in tens of ms), the oldest frames drop with an AUDIO_BACKPRESSURE_DROP warning (non-fatal safety valve against unbounded memory growth, not normal operation).
• Batch-mode accumulation buffer — a single pre-allocated Int16Array sized to the max utterance cap: 16,000 samples/sec × 120 s = 1,920,000 samples = 3,840,000 bytes (~3.75 MB), written via an append cursor. Allocated lazily when a batch-provider session begins (Section 12 defines batch vs. streaming providers) and dereferenced after the consuming HTTP call completes or session cancellation.

8.5 Pre-roll buffer #

Human reaction time and OS input-event scheduling can lose the first 100–300 ms of speech relative to when a user physically starts pressing a hotkey (users also start speaking a fraction of a second before fully committing the key-down). OpenDictate maintains a continuously-overwritten 300 ms pre-roll buffer (15 frames of 20 ms each) whenever the app is in the "armed" state.

Armed state: with fastStart.enabled (default true), the capture pipeline — MediaStream, AudioContext, worklet — stays alive continuously for the app's lifetime, not just during an active session. The OS-level microphone-active indicator (orange/green dot on macOS, mic icon in the Windows system tray) therefore stays visible whenever OpenDictate runs, not just while dictating; disclosed in onboarding (Section 27) and in Settings → Privacy, with a toggle to disable it. With fastStart.enabled: false, the pipeline is created fresh on every hotkey press (no pre-roll available; session-start latency shifts toward the 150 ms p95 budget in Section 31 rather than the 80 ms p50) — for privacy-sensitive users who prefer the mic inactive between sessions.

Maintenance: while armed, the capture renderer keeps a 15-slot circular buffer of the most recent 20 ms frames (post-filter, post-resample), continuously overwritten. On audio:start, before appending new frames, main copies this ring's contents in chronological order and prepends them as the new session's first frames — so a hotkey press arriving mid-syllable still yields a clean utterance start.

8.6 Voice activity detection #

Energy-based VAD, computed once per 20 ms frame in the main process (not the worklet — VAD state is session-scoped and belongs with AudioPipeline's session state):

• Normalize each Int16 sample to [-1, 1] (divide by 32768), compute RMS: rms = sqrt(sum(sample_i^2) / n).
• Speech threshold: rms >= 0.02 (≈ -34 dBFS) marks a frame as speech; below that, silence.
• Speech-start debounce: 2 consecutive speech frames (40 ms) required before the session's internal state flips from "silence" to "speech" — filters single-frame transients (cough, click) from prematurely counting as utterance start for timeout purposes. Affects only VAD bookkeeping, never the recording start/stop signal (still the hotkey event per Section 7).
• Silence-timeout auto-stop (toggle mode only — PTT stop is always the explicit key release): once at least one speech frame has occurred, 1,500 ms of continuous silence auto-triggers stop+finalize, identical to an explicit second toggle press.
• No-speech auto-cancel (toggle mode only): if zero speech frames are observed within the first 3,000 ms of a toggle session, the session auto-cancels (discarded, no insertion, no history entry) with a subtle HUD hint "No speech detected." PTT has no fixed duration to time out against, but a symmetric guard applies at key-release: a PTT hold of ≥ 250 ms released with zero speech frames for the entire hold auto-cancels identically (no STT/LLM call, nothing inserted) — see Section 7.9. Otherwise a user holding PTT while thinking silently would submit near-silence to the configured (often paid) STT provider with no defined outcome.
• Max utterance length cap: 120,000 ms (120 s) hard ceiling regardless of mode or VAD state. At the cap, the session force-stops and finalizes with whatever was captured; the mic closes and any speech after the cap goes uncaptured. A HUD toast — "Recording stopped — 120s limit reached" — is shown so the cutoff isn't mistaken for a bug.

8.7 Device enumeration, selection, hot-swap, and Bluetooth #

Device list is sourced from navigator.mediaDevices.enumerateDevices() filtered to kind === 'audioinput'. The setting audio.inputDeviceId defaults to the sentinel "default" — track the OS default communications device dynamically, rather than pinning to whatever was default at settings-save time; selecting an explicit device pins the pipeline to that deviceId.

Hot-swap: the capture renderer listens on navigator.mediaDevices.ondevicechange and re-enumerates each event. If the active, explicitly-pinned device disappears:

1. If a session is in progress, check whether the MediaStreamTrack is still alive (track.readyState !== 'ended') — some disconnects leave the track open for a short grace period. If alive, recording continues uninterrupted.
2. If the track has ended (typically a physically unplugged USB/3.5mm mic), the session stops immediately: finalized with captured speech, or cancelled silently if none. A toast — "Microphone disconnected — switched to <fallback device>" — shows, and the pipeline falls back to the "default" sentinel for subsequent sessions (the explicit pin isn't restored automatically even if the device reconnects; the user must re-select it).

Mic seized by a competing app (distinct from physical disconnect): a competing app forcing exclusive-mode audio (WASAPI exclusive mode on Windows, or a Bluetooth profile switch on either OS) can leave track.readyState reporting "live" while the track delivers zero or near-zero-amplitude samples, undetectable by the check above. A dedicated stall check runs alongside VAD (8.6): if 50 consecutive frames (1,000 ms) report exactly rms === 0 while the device is still enumerated as connected and the session is RECORDING, the pipeline treats this like the track-ended branch — session stops (finalized with speech captured before the stall, or cancelled if none), a toast shows ("Microphone may be in use by another app — dictation stopped"), and hot-swap recovery applies next session. Runs only during an active session, not while armed, since a silent pre-roll during idle armed time is normal.

Microphone permission revoked mid-recording: unlike Accessibility/Input Monitoring revocation (7.8, which doesn't interrupt an in-flight session), revoking Microphone access mid-RECORDING immediately invalidates the MediaStreamTrack on both platforms — the OS tears down the capture grant, surfacing as track.readyState transitioning to "ended" (or, on some driver/OS combinations, an abrupt getUserMedia error). Handled by the same track-ended branch: session force-stops, finalizing with captured speech or cancelling silently if none; the toast is replaced with a permission-specific message ("Microphone access was turned off — dictation stopped") via cross-checking PermissionStatus (Section 11.9) when the track ends. No further session starts until permission shows granted again (11.3).

Bluetooth: mic access from a Bluetooth headset forces the OS to renegotiate into HFP/HSP (vs. the higher-quality A2DP profile for music), narrowing mic bandwidth (typically 8–16 kHz effective, noisier than most wired/built-in mics) and audibly degrading other audio through the same device. OpenDictate detects likely Bluetooth devices via label heuristics on MediaDeviceInfo.label (case-insensitive match against "bluetooth", "airpods", "buds", "hands-free", "hfp") and shows a one-time-per-device-id banner in Settings → Microphone: "Bluetooth microphones may reduce accuracy and cause other audio to sound degraded while dictating. A wired or built-in microphone is recommended." Selection is never blocked — advisory only.

8.8 Microphone test UI contract #

Settings → Microphone provides:

• Live level meter — a horizontal bar updating at the 20 ms frame cadence, driven by the same RMS calculation as VAD (8.6). Below roughly -18 dBFS peak over a trailing 3 s window, a "too quiet — try moving closer to the mic" hint appears. A red clip indicator lights whenever any raw sample this session reached |amplitude| >= 0.98 ("clipping detected — move away from the mic or lower input gain").
• "Test — record 5 seconds and play back" — records 5 s of audio into an in-memory Blob (renderer-only, never written to disk or transmitted), plays it back through an <audio> element with a countdown ring so the user can hear mic quality before committing to a device. The test buffer is dereferenced the moment the panel closes or a new test starts, so it never lingers as a retained recording.

8.9 Gain normalization and clipping detection #

OpenDictate applies no client-side AGC or dynamic-range compression beyond getUserMedia's constraints — autoGainControl: true and noiseSuppression: true are set (via Chromium's built-in WebRTC audio processing), while echoCancellation defaults to false (targets speaker-loopback scenarios inapplicable to hold-to-talk, mic-only capture, and costs CPU; exposed as an Advanced Audio setting for users dictating with speakers playing audio). Deliberate: most streaming STT providers (Deepgram, Azure) normalize server-side; client-side gain manipulation risks pumping or distorting speech, measurably reducing STT accuracy.

Clipping detection is purely observational: each worklet frame is flagged clipped: true in its metadata if any raw sample that frame had |amplitude| >= 0.98. Recording is never interrupted for clipping (too disruptive), but if more than 5% of a session's frames were flagged, a single non-blocking toast appears after insertion — "Audio was clipping — try lowering your mic input volume" — rate-limited to once per 10 minutes to avoid nagging on a consistently-hot source.

8.10 Audio never touches disk #

This guarantee is structural, not just behavioral:

1. No filesystem imports in the audio path. The AudioPipeline module (main process) and every capture-renderer module have zero dependency on fs/node:fs or file-writing APIs, enforced by an ESLint rule scoped to apps/main/src/audio/** and apps/capture-renderer/** banning those imports plus electron-log's file transport.
2. Buffers are heap-only and short-lived. The pre-roll ring, streaming jitter ring, and batch accumulation buffer are plain ArrayBuffer/Int16Array instances on the V8 heap (or the Worklet realm for the pre-roll ring's renderer-side copy) — never serialized to any persistence layer. The batch buffer is explicitly nulled immediately after the consuming STT HTTP call resolves (success, failure, or cancellation) rather than left for GC to reclaim.
3. Logging never carries payload. Every log line from the audio pipeline (Section 33 owns logging) carries only metadata — frame counts, session duration, RMS statistics, error codes — never a Buffer, ArrayBuffer, or base64-encoded payload. A unit test asserts this by intercepting the logger's call sites in the audio module, failing if any argument is a binary type.

Section 7.3 defines the symmetric guarantee for the other raw-input capability this app holds — keystroke data — via the identical ESLint-rule-plus-unit-test pattern; uiohook-napi and the audio capture path are the two places OpenDictate holds keylogger/wiretap-equivalent access, and both need a mechanical, not just prose, backstop.

8.11 Chunking and framing: streaming vs. batch providers #

• Streaming providers (Deepgram, Azure — Section 12 (STT) / Section 13 (LLM)): each 20 ms / 640-byte PCM16 frame forwards to the provider's WebSocket the instant it's produced, with no client-side batching or delay — matching both providers' expectation of small, near-real-time frames and enabling the 350 ms p50 "first interim transcript token" budget in Section 31.
• Batch providers (OpenAI batch, Groq, openai-compatible — Section 12 (STT) / Section 13 (LLM)): frames accumulate into the pre-allocated 3.84 MB buffer (8.4) via an append cursor for the entire utterance. At session stop, the accumulated span is wrapped in a 44-byte in-memory RIFF/WAVE header (PCM16LE, 16000 Hz, mono — never via a temporary file) and sent as a single multipart/form-data HTTP request body.

8.12 Memory budget #

Worst case — an active batch-provider session at the 120 s cap — adds roughly 3.9 MB to the heap, negligible against the 180 MB p50 / 260 MB p95 idle RAM budget in Section 31, dominated by baseline Electron/Chromium overhead of the always-alive hidden capture renderer, not PCM buffer contents.

8.13 IPC surface and types #

The audio domain covers control and diagnostics traffic; the raw PCM frame stream runs over the dedicated MessageChannelMain port from audio:start (8.1), described separately below rather than as a channel row.

export interface AudioDeviceInfo {
  deviceId: string;           // "default" sentinel or a concrete device id
  label: string;
  isDefault: boolean;
  isLikelyBluetooth: boolean; // heuristic result from 8.7
}

export interface AudioSessionMetrics {
  sessionId: string;
  durationMs: number;
  totalFrames: number;
  speechFrames: number;
  clippedFrames: number;
  peakRms: number;
  hitMaxUtteranceCap: boolean;
  providerMode: 'streaming' | 'batch';
}

8.14 Acceptance criteria #

9. Active Application & Context Detection #

9.1 macOS detection mechanism #

• Frontmost application: NSWorkspace.shared.frontmostApplication, via a small native helper in @opendictate/native (N-API binding over Objective-C), returns bundleIdentifier, localizedName, and processIdentifier. No special permission required.
• Focused UI element: AXUIElementCreateApplication(pid) then AXUIElementCopyAttributeValue(app, kAXFocusedUIElementAttribute, &focusedElement) yields the focused control: kAXRoleAttribute (e.g. AXTextField, AXTextArea, AXComboBox, or a role nested inside an AXWebArea for web content), kAXTitleAttribute, kAXSelectedTextAttribute (current selection, used by Command Mode), and kAXValueAttribute (field's full text, when exposed).
• Surrounding-text extraction: reads kAXValueAttribute with kAXSelectedTextRangeAttribute to locate the caret, then extracts a bounded window around it (9.3's budget) rather than the full document — for latency and privacy (9.9).
• Requires Accessibility permission (Section 11.1); without it this mechanism is unavailable and the 9.8 failure path applies.

9.2 Windows detection mechanism #

• Foreground window: GetForegroundWindow() (user32), then GetWindowThreadProcessId for the owning process, then QueryFullProcessImageName for the exe path/name. Insufficient for packaged/UWP apps — many present as the generic host ApplicationFrameHost.exe — so the AUMID (Application User Model ID) is also read via IPropertyStore/System.AppUserModel.ID, giving a stable per-app identifier independent of the host process.
• UI Automation (UIA): IUIAutomation::GetFocusedElement() returns an IUIAutomationElement; CurrentControlType (UIA_EditControlTypeId, UIA_DocumentControlTypeId, etc.) and CurrentName are read from it.
• TextPattern (UIA_TextPatternId) exposes GetSelection() for the current selection and DocumentRange() for the full document range, from which a bounded window around the caret is extracted (symmetric to 9.1).
• No macOS-style consent prompt gates UIA access for a standard desktop app; Section 11.2 covers narrower cases where a sandboxed app restricts UIA text access.

9.3 The canonical AppContext type #

export interface AppContext {
  platform: 'macos' | 'windows';
  appId: string;              // bundleIdentifier (macOS) or normalized exe/AUMID (Windows)
  appName: string;            // human-readable, e.g. "Slack"
  processId: number;
  windowTitle: string | null;
  category: AppCategory;
  focusedElement: {
    role: string | null;      // AX role or UIA ControlType, normalized (see 9.4)
    isEditable: boolean;
    isSecure: boolean;        // secure text entry — see 9.6
    selectedText: string | null;
    surroundingText: SurroundingText | null;
  } | null;
  browserContext: {
    url: string | null;       // populated only for known browsers when extractable
    tabTitle: string | null;
  } | null;
  capturedAtMs: number;        // epoch ms this snapshot was taken
}

export interface SurroundingText {
  beforeCursor: string;        // up to CONTEXT_CHAR_BUDGET_BEFORE chars
  afterCursor: string;         // up to CONTEXT_CHAR_BUDGET_AFTER chars
  truncatedBefore: boolean;
  truncatedAfter: boolean;
}

export type AppCategory =
  | 'email' | 'chat' | 'docs' | 'code' | 'terminal'
  | 'notes' | 'browser' | 'other';

Character budget constants: CONTEXT_CHAR_BUDGET_BEFORE = 500, CONTEXT_CHAR_BUDGET_AFTER = 200 — asymmetric because preceding text drives tone-continuity and capitalization decisions (Section 10.7, Section 14) more than trailing text. Fixed constants (not user-facing in v1), recorded in the Section 40 registry.

9.4 App classification: seeded mapping table #

appId (bundle identifier on macOS, normalized executable name on Windows) is looked up in a built-in table shipped with the app — the seed for AppCategory. User overrides in Settings → App Rules (Section 26 owns that UI) layer on top and always win.

Maintenance cadence: several rows pin version-specific identifiers (e.g. com.sublimetext.4, com.microsoft.teams2) that break silently once a vendor ships a new major version under a new identifier (Sublime Text 5, a future Teams rebrand). No live update mechanism exists in v1; corrections ship only with app releases. A per-release review against each vendor's current identifiers (Section 35) is required, not optional — unmatched apps degrade gracefully via the 9.5 heuristic meanwhile, not to a hard failure.

9.5 Unknown apps and browser URL/tab-title classification #

Unknown appId (not in the seed table or a user override): classified by substring-matching the identifier/name against a keyword list, in fixed priority order to avoid ambiguous double matches — email > chat > terminal > code > notes > docs > browser > other:

Every unmatched appId is recorded to a local "category feedback" table (appId + heuristic result, no other metadata) for review/correction in Settings → App Rules; purely local, never transmitted (Section 32).

Browser tab sub-classification: when appId matches a known browser (Chrome, Safari, Firefox, Edge, Arc, Brave), OpenDictate reads the active tab's URL:

• macOS: reads the browser's address-bar AXTextField (via the toolbar's AX children, kAXRoleAttribute == AXTextField near the top of the window) and its kAXValueAttribute — avoiding AppleScript/JXA automation, which needs a separate Automation permission and is slower.
• Windows: locates the address-bar edit control via a TreeWalker over the UIA tree, matching known AutomationId values used by Chromium browsers' omnibox controls (e.g. "addressEditBox" on Edge/Chrome-derived UIA trees).

If obtained, the URL's hostname is matched against a small built-in table that overrides the generic browser category for that tab:

If the URL cannot be extracted (address bar not found, or the AX/UIA call fails), the tab is classified as plain browser with browserContext.url set to null.

9.6 Secure-field detection and the hard block #

Mechanism for the never-dictate-into-secure-fields policy; Section 11 owns the Accessibility/UIA permission grants it depends on.

macOS, checked in this order before any session is allowed to start:

1. IsSecureEventInputEnabled() — true whenever any application (not just the frontmost one) has enabled secure input, which macOS activates automatically for password fields in Safari, System Settings, Keychain Access, and Terminal sudo prompts.
2. The focused AXUIElement's kAXRoleAttribute equals AXSecureTextField — a belt-and-suspenders check for apps that mark a field secure without triggering OS-level secure input.

Either condition blocks.

Windows: the focused element's window style bits include ES_PASSWORD, or its UIA IsPassword property (UIA_IsPasswordPropertyId) is true. Either condition blocks.

Secondary heuristic layer (best-effort defense in depth): the OS-native flags above catch only fields the OS or app itself marked secure. They miss common sensitive input: OTP/2FA entry (typically six plain <input type="text"> boxes), SSN/CVV/PIN/routing/account-number fields built as ordinary text inputs, and custom (especially Electron) masked controls that set neither flag. To close this gap, the field-context data already resolved for classification (9.1/9.2 — focused element name/kAXTitleAttribute/CurrentName, placeholder text, and any associated label) is matched case-insensitively as a substring against a fixed keyword set: ssn, social security, cvv, cvc, otp, one-time, verification code, security code, pin, passcode, routing, account number — mirroring 9.5's heuristic style. A match sets isSecure: true as if a native flag had tripped, blocking the session via the same path below. Best-effort, not a guarantee: a field with no accessible name/label/placeholder, or vocabulary outside the keyword set, won't be caught — documented to users as such.

The identical pre-flight check — both OS-native flags and the secondary heuristic — also gates Command Mode's selection-read path (Section 15.3), not only insertion. Otherwise a password in a field tripping neither native flag could be read via accessibility APIs as an ordinary selection and sent to an LLM provider as part of a Command Mode instruction. Section 15.3 invokes this check before its copy-then-read-then-restore capture; a positive result blocks the read as it blocks recording, surfacing Command Mode's own "can't run a command on a password field" message instead of the HUD lock icon below.

Block behavior: the check runs synchronously in the dictation state machine's pre-flight (Section 6.5) before the mic opens — the hotkey event never reaches AudioPipeline.beginSession() if it fails. The HUD shows a lock icon with "Can't dictate into a password field" for 1.5 s, then auto-dismisses. INJECT_SECURE_FIELD_BLOCKED is logged locally with metadata only (the app's category, never field name, window title, or app identity beyond what's already resolved).

9.7 Caching and refresh cadence #

AppContext resolves fresh at exactly two points per session — session-start (HUD tinting, tone-preset selection) and session-stop (authoritative for insertion targeting, Section 7.10) — and isn't polled continuously outside a session, respecting the < 0.5% idle CPU budget in Section 31. Tone-relevant context is deliberately not re-polled mid-speech even for longer sessions, since switching presets mid-utterance would produce inconsistent formatting; only the two checkpoints apply. Surrounding-text extraction runs only at session-start (feeding capitalization-continuation and Command Mode) and is skipped when context.surroundingTextEnabled is false.

Relationship to the 9.6 secure-field pre-flight: the secure-field check isn't a third, separate resolution — it reads focusedElement.isSecure off the same session-start AppContext resolution (and symmetrically off session-stop, when checking whether focus moved into a secure field before insertion, 7.10). No independent poll exists; it's a synchronous read of a field already resolved at each checkpoint.

9.8 Failure behavior #

If Accessibility (macOS) or the relevant UIA pattern (Windows) is unavailable — permission not granted, or the focused element doesn't implement the needed interface (common in canvas-rendered editors and some game-engine apps with no AX/UIA tree) — process-level fields (appId, appName, category, windowTitle) still resolve normally: they come from NSWorkspace/GetForegroundWindow-level APIs, independent of AX/UIA. Only focusedElement becomes null. Downstream effects:

• Tone adaptation (Section 14) falls back to the per-category default preset; no capitalization-continuation signal is available.
• Command Mode (Section 15), which requires selectedText, cannot operate and shows "Select some text first" if invoked with no AX/UIA selection reachable.
• Text insertion (Section 10) treats a null focusedElement as a signal to skip Strategy 1 (accessibility direct insert) and go straight to Strategy 2 (clipboard paste), saving a doomed Strategy 1 round-trip.

9.9 Privacy #

Exactly what is captured: appId, appName, window title, the focused element's role/ editable/secure flags, selected text (only while Command Mode processes a command, held in memory for that call), and surrounding text bounded by the 500/200-character budget (9.3).

What is persisted: none of the above field-level data reaches the transcript history database. Section 22 (owner of the history schema) stores only appId, appName, and category alongside a history entry, for the "grouped by app" view — surrounding text and selected text are never persisted to SQLite under any setting.

Retention: in-memory only, for the duration of the LLM formatting or Command Mode call that consumed it; references clear immediately once that call resolves — succeeded, failed, or cancelled.

User control: context.surroundingTextEnabled (Settings → Privacy) defaults to true (materially improves capitalization-continuity and tone-matching) and can be disabled; the app then degrades gracefully via the 9.8 failure path rather than breaking dictation outright.

9.10 IPC surface and types #

AppContext resolution stays in the main process (Section 4.2 — main owns all canonical state), never exposed to a renderer as a live poll; the context channels below exist only for the Settings → App Rules UI (Section 26 owns the UI) and diagnostics.

export interface AppRuleOverride {
  appId: string;
  category: AppCategory;
  source: 'user';    // always 'user' — distinguishes overrides from seed-table/heuristic entries in the merged list
  createdAt: number;  // epoch ms
}

9.11 Acceptance criteria #

10. Text Insertion Engine #

10.1 Three-strategy chain overview #

The canonical three-strategy ordered chain: the first strategy whose preconditions are met and whose native call reports success wins; every later strategy is skipped.

10.2 Strategy 1: Accessibility direct insert #

Preconditions: focusedElement is non-null (Section 9), its role indicates an editable text control, and the underlying attribute is confirmed settable at write time.

macOS: AXUIElementIsAttributeSettable(element, kAXValueAttribute) (or kAXSelectedTextAttribute) is checked immediately before writing. Replacing a selection sets kAXSelectedTextAttribute directly — the standard AX idiom; the caret lands after the inserted text. Inserting at an empty caret reads the current kAXValueAttribute, splices the new text in at the offset given by kAXSelectedTextRangeAttribute, writes it back, then sets kAXSelectedTextRangeAttribute to place the caret immediately after the inserted span.

Windows: attempted only when the focused element supports ValuePattern (IUIAutomationValuePattern::SetValue) — covers legacy Win32 edit controls and many WinForms controls, not controls exposing only TextPattern (unreliable for arbitrary programmatic insertion). Where only TextPattern is available, Strategy 1 is skipped outright. Windows coverage under this strategy is narrower than macOS by design — a known, accepted platform asymmetry.

Latency: under 10 ms typical — one synchronous native call, no clipboard I/O, no synthetic dispatch.

Failure modes and detection: the attribute is reported not-settable (kAXErrorAttributeUnsupported on macOS, UIA_E_NOTSUPPORTED on Windows); the element goes stale between focus-check and write (a sub-100 ms race if focus changed — mitigated by re-reading the focused element before the write and aborting to Strategy 2 on any mismatch); or the call throws for any other reason (e.g. the field became read-only between check and write). The native addon returns a discriminated result { ok: boolean; code?: string } rather than throwing across the native boundary — any ok: false triggers immediate fallback to Strategy 2, with no retry inside Strategy 1.

10.3 Strategy 2: Clipboard paste with restore (default, always-available path) #

Preconditions: effectively none beyond "the OS has a clipboard and can receive a synthetic paste keystroke" — true for any target.

Steps:

1. Snapshot the current clipboard across every commonly-used format present: plain text (public.utf8-plain-text / CF_UNICODETEXT), rich text (public.rtf / registered CF_RTF, when present), HTML (public.html / CF_HTML, when present), and file-list (public.file-url / CF_HDROP, when present) — captured into one in-memory snapshot, never persisted.
2. Write the formatted transcript to the clipboard as plain text, plus HTML with equivalent structure whenever the LLM formatting pass (Section 13) produced rich structure (e.g. a bullet list from Command Mode) — rich-text-aware targets get structure, plain-text targets get clean text, from the same write.
3. Synthesize Cmd+V (macOS, CGEventCreateKeyboardEvent) or Ctrl+V (Windows, SendInput with a VK_CONTROL+V down/up sequence) targeted at the currently focused window.
4. After a 300 ms default delay (insertion.clipboardRestoreDelayMs, user-configurable 150–1000 ms in Advanced settings), restore the original snapshot, subject to the race mitigation in 10.5.

Latency: ~15–30 ms for steps 1–3 combined (clipboard I/O plus synthetic event dispatch); the paste is consumed by the target app well inside the 300 ms hold window in virtually all cases — 300 ms is a safety margin against slow clipboard-observing code in some Electron apps, not the paste's own latency.

Failure modes and detection: no OS confirms a dispatched paste keystroke was actually consumed — "failure" detection here is limited to dispatch-level errors: the clipboard write API itself failing (rare; Windows can transiently fail OpenClipboard under clipboard contention, retried up to 3 times with 10 ms backoff before falling through to Strategy 3), or the captured target window handle no longer matching the actual foreground window immediately before dispatch. Beyond dispatch-level errors, Strategy 2 is considered successful once dispatched; a target app silently ignoring the paste is a known, undetectable-by-design limitation (Section 30).

10.4 Strategy 3: Synthetic keystrokes #

Character-by-character injection, used as the fallback of last resort.

macOS: CGEventKeyboardSetUnicodeString on a CGEventCreateKeyboardEvent(source, 0, true/false) down/up pair per character. This API takes UTF-16 code units directly, injecting the already-composed Unicode character rather than simulating the physical key that would produce it — keyboard-layout and dead-key composition are bypassed by construction.

Windows: SendInput with INPUT_KEYBOARD structures using the KEYEVENTF_UNICODE flag and wScan set to the UTF-16 code unit — likewise bypassing VkKeyScan/virtual-key mapping, equally keyboard-layout independent.

Surrogate pairs (emoji, and many CJK-extension characters outside the Basic Multilingual Plane) are sent as two consecutive UTF-16 code units, each dispatched as its own down/up event, in order — both platform APIs handle this natively, since the mechanism is raw UTF-16 injection.

Dead keys are a non-issue here: the final composed character is injected directly, so no dead-key-triggering key sequence is ever simulated.

Per-character delay: a fixed 2 ms default between characters (insertion.keystrokeDelayMs, recorded in the Section 40 registry), empirically enough to avoid dropped events in most target apps' input queues without making longer dictations feel sluggish. A 200-character utterance takes roughly 400 ms of dispatch time under this delay plus native-call overhead (~0.3 ms/character), for a combined ~2.3 ms/character — why this strategy is the fallback of last resort, not a default. Unlike the fixed 2 ms system default, keystrokeDelayMs is exposed to the same per-app override mechanism as clipboardRestoreDelayMs (10.6): a per-app entry may raise it for input-queue-sensitive targets (terminals, spreadsheet grids) Strategy 3 is force-routed to, per the dedicated override rows in 10.6.

Failure modes: essentially none at the injection-API level (the OS's lowest-level input-injection primitives); the only realistic failure is the target not being focused or not accepting input at dispatch time, detected the same way as Strategy 2 (window-handle mismatch check).

Newline/carriage-return neutralization before dispatch into a Code or Terminal target (security — testable rule): Strategy 3 is literal character-by-character injection with no inherent newline handling — a bare \n/\r is delivered as a literal Enter/Return keypress, not a text character. LLM cleanup/formatting (Section 13) and Command Mode (Section 15) routinely produce multi-line output, and 10.6 force-routes every terminal emulator to Strategy 3. Left unguarded, a multi-line result injected into a focused shell executes whatever text preceded the embedded newline as a command before the remainder types itself in — a shell-command-injection primitive reachable from ordinary dictation, and from a crafted voice-snippet expansion (Section 20.3) spoken while a terminal has focus. The rule, exact and testable:

• Before any Strategy-3 dispatch whose resolved insertion target's AppContext.category (Section 9.3) is code or terminal, every bare \r (CR, U+000D) and \n (LF, U+000A) in the text about to be injected is replaced with a single space — never removed outright, which would silently join the words on either side of the break into one token — immediately before the per-character dispatch loop begins. A space is as safe as deletion (it is not an Enter keypress) and preserves word boundaries, so it is the canonical behavior at both call sites, regardless of why Strategy 3 was reached (a 10.6 forced override, or a Strategy 1/2 fallback into a Code/Terminal target) — mechanism and risk are identical either way.
• Where the target is detected as supporting bracketed-paste mode (queryable on POSIX terminals via the ?2004h/?2004l DEC private mode sequence exchange, which iTerm2, Terminal.app, and modern Windows Terminal all advertise), 10.6's override may instead wrap the dispatched text in the bracketed-paste start/end sequences (ESC[200~ … ESC[201~) rather than neutralizing newlines, since bracketed-paste mode treats embedded newlines as literal pasted text, not Enter keypresses. CR/LF neutralization (single-space replacement) remains the default and mandatory fallback whenever bracketed-paste support cannot be positively confirmed.
• The identical filter runs on voice-snippet expansion text (Section 20.3) before it reaches the insertion engine, not only on LLM-formatted dictation output — an imported "productivity snippets" pack can carry a crafted multi-line payload just as an ordinary utterance can, and the insertion engine cannot distinguish the two sources by the time text reaches Strategy 3.
• Enforced as a single choke point (one function on the Strategy-3 dispatch path, not duplicated per caller), so every current and future caller — dictation, Command Mode, snippet expansion — inherits the guard automatically.

10.5 Clipboard race conditions and mitigations #

10.6 Per-app strategy overrides #

10.7 Insertion semantics #

Replace selection vs. insert at caret: if focusedElement.selectedText (Section 9) was non-empty at insertion time for an ordinary dictation append, the selection is replaced by the new text — the standard "typing over a selection" behavior every text field already implements. Command Mode (Section 15) always replaces the selection it was invoked on, by definition. An empty selection results in a plain insert at the caret.

Trailing space rule: OpenDictate-inserted text never ends with a trailing space of its own. If surrounding-text lookahead (Section 9) shows the character immediately following the caret is non-whitespace and non-punctuation, a single space is appended to prevent word-mashing. If surrounding text is unavailable (the 9.8 failure path), the safer default applies — no automatic trailing space, since a missing space is easier to notice and add than a mashed word is to spot.

Capitalization continuation: primarily handled upstream by the LLM formatting pass (Section 13) using the same surrounding-text context, but the insertion engine performs one final deterministic check independent of LLM behavior: if surroundingText.beforeCursor, trimmed of trailing whitespace, ends in sentence-terminal punctuation (., !, ?) or is empty (start of field), the first letter of the inserted text is forced to uppercase regardless of LLM output.

Undo behavior: Strategy 1 and Strategy 3 both register as ordinary text-edit operations in the target app's undo stack, since AX value-setting and real synthesized keystrokes are indistinguishable from user typing to most standard controls' undo managers. Whether a single Cmd+Z/Ctrl+Z undoes the whole inserted block as one step depends on the target app's own undo-coalescing heuristics (most modern apps group rapid consecutive edits within a short idle window) — best-effort, not a contract. Strategy 2 (paste) reliably registers as a single, predictable undo-able operation in virtually every app — a secondary reason it is the default/preferred fallback, not merely a fallback of convenience.

10.8 Streaming vs. single-shot insertion #

Single-shot insertion is the default (insertion.streamingMode: false). The full, formatted text is inserted exactly once, after the LLM formatting pass (Section 13) completes — not progressively as interim ASR tokens arrive. Progressive insertion would require continuously deleting and re-typing previously-inserted text on every ASR revision or LLM restructuring (e.g. resolving a mid-sentence self-correction per Feature 2 in Section 1) — visually jarring, incompatible with Strategy 1's whole-value-set and Strategy 2's paste-only semantics (both operate on a final string, not a delta stream), and a violation of 10.7's "one clean undo step" property. It also keeps the Section 31 performance budget simple: "final transcript → formatted text ready" is the sole gate before the one insertion call.

Progressive/streaming insertion is an opt-in Advanced setting (insertion.streamingMode, default false) for users who want raw interim text to appear live in the target app as they speak, rather than only in the HUD's live preview (which always shows interim text regardless of this setting — Section 25 owns the HUD). When enabled, it uses only Strategy 3 (synthetic keystrokes) regardless of the normal chain and any 10.6 per-app override, since it requires fine-grained delete-and-retype control over the tail of the inserted text on every revision — control neither Strategy 1's whole-value-set nor Strategy 2's single-paste semantics can express.

10.9 Total insertion failure #

If all three strategies fail — realistically only possible when focus was lost entirely between session-stop and insertion (the target app crashed, the screen locked mid-flow, or the window closed):

1. The formatted transcript is written to the clipboard as a best-effort final act (no restore is scheduled — nothing productive to restore over).
2. A persistent (not auto-dismissing) notification appears: "Couldn't insert text automatically — it's on your clipboard, press Cmd+V / Ctrl+V to paste it. It'll be cleared from your clipboard in 90 seconds."
3. INJECT_ALL_STRATEGIES_FAILED is logged locally with the target app's category only (never content).
4. The transcript is still written to history (Section 22) regardless of insertion outcome — not lost even if the user dismisses the notification without pasting.
5. Auto-clear timeout: unlike the normal Strategy 2 paste-and-restore path (10.3/10.5), there is nothing to "restore" here, so the transcript would sit on the clipboard indefinitely unless bounded — a real exposure window, since dictated content can include names, addresses, or business content, and macOS Universal Clipboard / Windows Clipboard History can propagate it elsewhere instantly. OpenDictate clears it 90 seconds after writing it, provided the clipboard still holds exactly what OpenDictate wrote (checked via the same change-count/sequence-number comparison used for the 10.5 restore-race mitigation, so a user's own intervening copy is never clobbered). 90 seconds comfortably covers the realistic "notice notification, switch window, paste" flow (typically single-digit seconds) with margin for a distracted user, while still bounding exposure of sensitive text; it deliberately does not reuse clipboardRestoreDelayMs (300 ms), which governs a different, much shorter-lived race (10.5), not user-facing retention. If the clear fires (the user hadn't already pasted or copied something else), the persistent notification is replaced with a brief, auto-hiding one: "Clipboard cleared for your privacy." Third-party clipboard-manager persistence of the text during the 90-second window is a known limitation this auto-clear cannot reach; Section 27 (onboarding) and Settings → Privacy disclose this, parallel to the always-on-mic-indicator disclosure in 8.5: "dictated text may briefly touch your OS clipboard; third-party clipboard-manager tools that log clipboard history may capture it before the 90-second auto-clear runs."

10.10 Decision tree #

session-stop
  │
  ▼
resolve target AppContext (fresh, Section 9)
  │
  ▼
secure field? ──yes──▶ abort insertion; keep result in history only; show lock notice (9.6)
  │no
  ▼
per-app override configured? (10.6) ──yes──▶ jump directly to that forced strategy
  │no
  ▼
Strategy 1 — Accessibility direct insert
  │
  ├─ preconditions met, native call ok:true ──▶ DONE (fastest path, no clipboard touch)
  │
  └─ preconditions unmet OR ok:false
       │
       ▼
     Strategy 2 — Clipboard paste + restore
       │
       ├─ dispatched with no dispatch-level error ──▶ considered DONE
       │    (no OS-level positive confirmation exists for any strategy — 10.3/10.4)
       │
       └─ clipboard write failed after 3 retries
            │
            ▼
          Strategy 3 — Synthetic keystrokes
            │
            ├─ dispatch completes ──▶ considered DONE (best-effort)
            │
            └─ focus lost / target window gone mid-dispatch
                 │
                 ▼
               Total failure fallback (10.9): clipboard-only + persistent notification

10.11 IPC surface and types #

Insertion is triggered internally by the dictation state machine (Section 6), not by a renderer call — the main process owns the entire flow from formatted text to inserted text. The insertion domain channels below exist for diagnostics and the Advanced settings that configure it.

export type InsertionStrategy = 'accessibility' | 'clipboard' | 'keystrokes';

export interface InsertionAttempt {
  sessionId: string;
  targetAppId: string;
  strategyUsed: InsertionStrategy | 'fallback-clipboard-only';
  strategiesAttempted: InsertionStrategy[]; // in order, including ones that failed before the winner
  succeeded: boolean;
  latencyMs: number;
  errorCode?: string; // e.g. INJECT_ALL_STRATEGIES_FAILED
}

10.12 Acceptance criteria #

11. OS Permissions & Platform Differences #

11.1 macOS permissions #

11.2 Windows permissions and platform nuances #

11.3 Permission state machine #

States: unknown → checking → granted | denied | not_determined. not_determined is a macOS-only pre-prompt state (user never asked); Windows states collapse to unknown → checking → granted | denied.

        ┌─────────┐
        │ unknown │  (app launch, no check performed yet)
        └────┬────┘
             │ perform status check
             ▼
        ┌───────────┐
        │ checking  │
        └─────┬─────┘
     ┌─────────┼─────────────┐
     ▼         ▼              ▼
┌────────┐ ┌────────┐  ┌────────────────┐
│granted │ │ denied │  │ not_determined │  (macOS only)
└───┬────┘ └───┬────┘  └───────┬────────┘
    │          │                │ user triggers request API
    │          │                ▼
    │          │          ┌───────────┐
    │          │          │ checking  │──▶ granted | denied
    │          │          └───────────┘
    │          │
    │          └─── deep link to Settings; re-check on next trigger (below)
    │
    └── periodic re-check (below); no further action needed

Re-check cadence: on every app launch; on regaining focus of the Settings window (neither OS pushes live notification of privacy-toggle changes to a background app, so focus-regain polling detects grants made while OpenDictate ran in the background); and every 30 seconds while any required permission is non-granted. Polling stops once every required permission reaches granted, so the < 0.5% idle CPU budget (Section 31) is never taxed in steady state.

Permission revoked mid-session: the 30-second poll above only detects revocation between sessions or while idle, not during an active session, since sessions can complete in well under 30 seconds. Each permission is handled per its own failure surface, cross-referenced from Section 7's event table (7.11) and Section 8:

• Microphone, revoked mid-RECORDING: the OS tears down the MediaStreamTrack grant immediately; the audio pipeline sees this as the track ending — handled by Section 8.7's hot-swap/disconnect path (force-stop with whatever was captured, or silent cancel), with a permission-specific toast instead of generic wording.
• Accessibility / Input Monitoring, revoked mid-session (any of RECORDING through INSERTING): does not abort the in-flight session — audio capture, the STT/LLM call, and Strategy 2 insertion (needs neither permission) proceed normally. Only forward-looking behavior is affected: no new uiohook-driven hotkey fires, and Strategy 1 insertion is skipped, until re-granted. See Section 7.8 for full behavior.

Both paths update PermissionStatus (11.9) and the tray/HUD badge the moment loss is detected — never silently absorbed, though the two failure surfaces differ in how disruptive they are to the session underway.

11.4 Deep links to OS settings panes #

All opened via shell.openExternal(...) from the main process, never from a renderer directly, consistent with the process-model boundary in Section 4.2.

Fallback on deep-link failure: macOS x-apple.systempreferences: anchors (Privacy_Accessibility, Privacy_Microphone, Privacy_ListenEvent) have shifted across System Settings redesigns (most recently macOS 13); a future OS changing or removing one is a real risk. shell.openExternal(...) succeeds if the base scheme is registered, even with a stale anchor — it opens System Settings, not necessarily the intended pane; OpenDictate has no API to verify which pane opened. So: if a permission is still denied/not_determined 10 seconds after the deep link opened, the triggering onboarding/Settings UI shows a fallback link to the generic Privacy & Security root pane (x-apple.systempreferences:com.apple.preference.security), labeled "Not seeing the right page? Open Privacy & Security settings" — a stale anchor degrades to one extra click, not a dead end.

11.5 Minimum OS versions #

• macOS 13 Ventura minimum. Electron 33 supports back to macOS 11, but OpenDictate's AX API usage and systemPreferences Input Monitoring status are most reliable from Ventura onward; by v1 ship, Ventura excludes only long-unsupported hardware, letting the codebase skip legacy TCC-prompt-behavior branches.
• Windows 10, version 22H2 minimum, with all Windows 11 versions supported. 22H2 is the last serviced Windows 10 feature update, guarantees WinRT/UIA API parity with Windows 11 for the TextPattern features used in Sections 9–10, and by v1 ship covers the long tail of Windows 10 installs without branches for older, unserviced builds.

11.6 Architecture support #

• macOS: a single universal binary (Apple Silicon arm64 + Intel x64) produced by electron-builder's universal mach-o target, combining two builds. The native addon @opendictate/native ships separate darwin-arm64/darwin-x64 prebuilds (via prebuildify), merged with lipo (Section 35).
• Windows: x64 and arm64 ship as separate installers — no universal-binary equivalent. The native addon ships distinct win32-x64/win32-arm64 prebuilds; on Windows-on-ARM, the native arm64 build runs directly rather than under x64 emulation, since emulated WH_KEYBOARD_LL hooks have historically been unreliable there.

11.7 macOS vs. Windows differences #

11.8 Multi-monitor, virtual desktops, full-screen apps, and fast user switching #

Multi-monitor: HUD position (hud.position, default bottom-center) is computed relative to the display containing the cursor of the focused window at each session start — not pinned to a fixed monitor — so it appears near the user. The tray/menu-bar icon is a single OS-level icon regardless of monitor count.

Virtual desktops / Spaces: the HUD must remain visible regardless of which virtual desktop is active when a session starts. macOS: window.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true }) is set on the HUD window. Windows has no Electron-level API for per-desktop visibility equivalent to Spaces (Desktops are more isolated at the API level; IVirtualDesktopManager isn't exposed by Electron) — the fix: the HUD, shown only transiently during a session, is destroyed and cheaply recreated (< 5 ms) at the start of every session, guaranteeing it appears on whichever desktop is active rather than relying on a persistent window tracking switches.

Full-screen apps: on macOS, a full-screened app gets its own dedicated Space; only a window with the visibleOnFullScreen Cocoa flag set (via the same setVisibleOnAllWorkspaces call above) can render over it — otherwise the HUD is invisible while dictating into, e.g., a full-screen code editor or a video call's caption pane. On Windows, true DirectX/Metal exclusive full-screen surfaces (games, some video players) generally can't be rendered over by any always-on-top window, including the HUD — a documented, accepted limitation: hotkey and insertion may still function even when the HUD can't be seen.

Audio feedback as HUD substitute: since the HUD isn't always visible (the Windows exclusive-full-screen case above), a short, subtle two-tone earcon (< 150 ms) plays on recording-start and recording-stop whenever the OS reports the frontmost surface as exclusive-full-screen. Controlled by hud.audioFeedbackEnabled (default true); also available as a supplementary cue elsewhere, configurable to off.

Fast user switching / multiple sessions: OpenDictate runs entirely per-user: each OS user has an independent app instance, SQLite database, and keychain entries, with no shared state (consistent with the single-user posture in Section 3). When the active OS session is switched away from — fast user switching on macOS, or a session lock/switch on Windows — any in-progress dictation session is immediately hard-cancelled, not finalized: detected via powerMonitor.on('lock-screen') (fired by Electron for screen lock and switch-away, on both platforms), the MediaStreamTrack is explicitly stopped (track.stop()), a hard privacy guarantee the microphone is never left recording while the screen is locked or another user's session is active, and hotkey handling is suspended until powerMonitor.on('unlock-screen') fires and normal operation resumes.

System sleep / wake (powerMonitor.on('suspend') / powerMonitor.on('resume')): handled by the same code path as the lock-screen case above, since OS sleep is strictly more disruptive than a screen lock. On powerMonitor.on('suspend'), any session that is RECORDING, FINALIZING, TRANSCRIBING, FORMATTING, or INSERTING is immediately hard-cancelled (not finalized — the OS is about to suspend the process with no reliable window to complete an in-flight STT/LLM call or insertion): the MediaStreamTrack is stopped, any in-flight STT/LLM request aborted, nothing inserted, and the state machine force-transitions to COOLDOWN → IDLE rather than left non-terminal across the sleep. All hotkey handling (globalShortcut- and uiohook-registered) is suspended for the sleep's duration. On powerMonitor.on('resume'), permission status (11.3) and device enumeration (8.7) force-refresh immediately — not waiting for the next 30-second poll or ondevicechange event — since sleep/wake commonly triggers a USB audio device or Bluetooth headset silently changing identity; hotkey handling resumes only once both refreshes complete. This ensures the app recovers cleanly from sleep/wake mid-recording without a stuck state; no separate handling exists beyond reusing the lock-screen path.

11.9 IPC surface and types #

export type PermissionKind =
  | 'microphone' | 'accessibility' | 'input-monitoring'; // Windows only ever reports 'microphone'

export type PermissionState = 'unknown' | 'checking' | 'granted' | 'denied' | 'not_determined';

export interface PermissionStatus {
  permission: PermissionKind;
  state: PermissionState;
  platform: 'macos' | 'windows';
  lastCheckedMs: number;
}

Error codes this section contributes to the Section 40 canonical registry, PERM_* namespace established in Section 4.4:

11.10 Acceptance criteria #

12. Speech-to-Text Provider Layer #

12.1 Purpose and package location #

The STT provider layer lives in packages/shared/src/stt/, consumed exclusively by the main process (Section 6). It exposes one interface (SttProvider) implemented by five adapters, selected at runtime from the provider registry keyed by id (Section 12/13 table). Adding a sixth provider needs only a new adapter file implementing SttProvider plus one registry entry — no changes to the dictation state machine, audio pipeline (Section 8), or UI code.

12.2 The canonical SttProvider interface #

// packages/shared/src/stt/types.ts

export type SttProviderId = 'deepgram-stt' | 'openai-stt' | 'groq-stt' | 'azure-stt' | 'openai-compatible-stt';

export interface SttCapabilities {
  streaming: boolean;
  batch: boolean;
  interimResults: boolean;
  wordTimestamps: boolean;
  wordConfidence: boolean;
  vocabularyBoost: boolean;
  languageAutoDetect: boolean;
  /** null = provider imposes no hard duration cap per request/connection */
  maxAudioDurationSec: number | null;
  /** 'all' = provider accepts any BCP-47 tag without a fixed catalogue */
  supportedLanguages: 'all' | readonly string[];
}

export interface SttRequestOptions {
  /** BCP-47 tag, or the literal string 'auto' when the user selected auto-detect */
  language: string | 'auto';
  model: string;
  sampleRateHz: 16000;
  encoding: 'pcm16';
  /** Personal-dictionary boost terms, Section 19. Omitted when capabilities.vocabularyBoost is false. */
  vocabulary?: readonly string[];
  /** Always false. OpenDictate never censors the user's own speech. */
  profanityFilter: false;
}

export interface SttWord {
  text: string;
  startMs: number;
  endMs: number;
  confidence: number | null;
}

export interface SttResult {
  text: string;
  words: SttWord[] | null;
  /** BCP-47 tag the provider detected or was told to use; null if unavailable */
  language: string | null;
  isFinal: boolean;
  confidence: number | null;
}

export type SttStreamEvent =
  | { type: 'open' }
  | { type: 'interim'; result: SttResult }
  | { type: 'final'; result: SttResult }
  | { type: 'speech-started' }
  | { type: 'speech-ended' }
  | { type: 'error'; error: AppError }
  | { type: 'close'; code: number; reason: string };

export interface SttStreamHandle {
  /** Push one 20ms PCM16 mono frame captured by the capture renderer (Section 8). */
  sendAudio(frame: Int16Array): void;
  /** Flush buffered audio, request a final result for the trailing segment, then close. */
  finish(): Promise<void>;
  /** Immediate teardown; no further events except a terminal 'close' are guaranteed. */
  abort(): void;
  /** Returns an unsubscribe function. */
  on(listener: (event: SttStreamEvent) => void): () => void;
}

export interface TestConnectionResult {
  ok: boolean;
  latencyMs: number | null;
  modelAvailable: boolean | null;
  error?: AppError;
}

export interface SttProviderConfig {
  apiKey: string;
  baseUrl?: string; // used by 'openai-compatible-stt' and to override regional endpoints
  region?: string;  // used by 'azure-stt'
}

export interface SttProvider {
  readonly id: SttProviderId;
  readonly capabilities: SttCapabilities;

  testConnection(config: SttProviderConfig): Promise<TestConnectionResult>;

  /** Present only when capabilities.streaming is true. */
  startStream?(
    options: SttRequestOptions,
    config: SttProviderConfig,
  ): Promise<SttStreamHandle>;

  /** Present only when capabilities.batch is true. */
  transcribeBatch?(
    audio: Buffer,
    options: SttRequestOptions,
    config: SttProviderConfig,
  ): Promise<SttResult>;
}

Every adapter must set startStream and transcribeBatch to undefined when the corresponding capability is false, rather than throwing at call time — the dictation state machine (Section 6) checks capabilities.streaming/capabilities.batch first, so a mismatched descriptor is caught by the adapter's own unit tests (Section 34), not a runtime guard.

12.3 Provider registry #

// packages/shared/src/stt/registry.ts
export const STT_PROVIDERS: Record<SttProviderId, () => SttProvider> = {
  'deepgram-stt': () => new DeepgramSttProvider(),
  'openai-stt': () => new OpenAiSttProvider(),
  'groq-stt': () => new GroqSttProvider(),
  'azure-stt': () => new AzureSttProvider(),
  'openai-compatible-stt': () => new OpenAiCompatibleSttProvider(),
};

12.4 Adapter: Deepgram (default provider) #

Query parameters the app sets and why:

Response parsing: each WebSocket text frame is a JSON message. The adapter reads channel.alternatives[0].transcript, channel.alternatives[0].words[] (each with word, start, end, confidence), is_final, and speech_final. is_final: true closes out a recognized segment (emitted as a final event); speech_final: true (driven by endpointing above) also emits speech-ended, which starts the formatting pipeline (Section 13) without waiting for hotkey release in toggle mode. is_final: false messages are emitted as interim events. metadata messages with request_id are logged for diagnostics (Section 33) and otherwise ignored. UtteranceEnd messages (sent when Deepgram detects a gap with no new audio) map to speech-ended if no speech_final arrived within 1,500 ms of the last final word, covering background noise that prevents endpointing.

Word-level timestamps and per-word confidence are always requested; capabilities.wordTimestamps and capabilities.wordConfidence are true. Vocabulary boosting via keywords/keyterm above sets capabilities.vocabularyBoost to true; capabilities.languageAutoDetect is true via language=multi.