The codebase, line by line

Every concept above, mapped to where it appears.

SpokeApp.swift

App entry point. @main (macro), App and Scene protocols, MenuBarExtra and Settings scenes, @State ownership of the controller, and an availability gate so the app shows a clear message rather than failing to launch on older macOS.

Concepts: macros, scenes, state ownership.

DictationController.swift

The orchestrator, and the first file to read. An @Observable @MainActor class holding a state enum with an error payload. Wires the hotkey to the pipeline, sequences transcription → polish → insert, and drives the overlay. Note that the overlay appears before the model is ready — perceived latency beats actual latency — and hides before the paste fires, so the pill never flickers over the user's text.

Concepts: enums with payloads, @MainActor, @Observable, Task.

AudioCapture.swift

AVAudioEngine input tap, the sample-rate-zero permission check, RMS metering, and BufferConverter with its ratio-aware capacity and format-change detection.

Concepts: digital audio in full, error handling, closures.

Transcriber.swift

An actor wrapping SpeechAnalyzer. Locale resolution, asset installation, the AsyncStream feeding audio in, the results loop consuming text out, and the volatile-vs-final accumulation logic.

Concepts: actors, AsyncStream, streaming ASR.

TextPolisher.swift

The product. @Generable guided generation, the instructions/prompt security boundary, availability handling with distinct user-facing reasons, and three layers of fallback so a failure never costs the user their words.

Concepts: on-device LLMs in full, macros.

HotkeyMonitor.swift

Global and local NSEvent monitors, .flagsChanged with manual press/release inference, hardware key codes, and the Accessibility permission check.

Concepts: events, TCC.

TextInserter.swift

Pasteboard save → set → synthetic ⌘V → restore. CGEvent synthesis, and the 150 ms delay before restoring the clipboard — long enough for the paste to land, short enough that the user never notices their clipboard was borrowed.

Concepts: CGEvent, sandbox implications.

OverlayController.swift

The trickiest file. Non-activating NSPanel configuration, orderFrontRegardless, caret lookup through the Accessibility API with two fallbacks, and the top-left-to-bottom-left coordinate flip.

Concepts: windows & panels, Accessibility API, coordinate systems.

OverlayView.swift

Pure SwiftUI. Materials for native vibrancy, a ViewBuilder switch over mode, the perceptual square-root curve on the waveform, and .truncationMode(.head) so the newest speech stays visible as text overflows.

Concepts: declarative views, modifiers & layout.