fix(mac): prevent Option release deadlock and HUD layout storm

The hold-to-talk release path called AsyncStream.Continuation.finish()
while holding MacAudioRecorder's NSLock; onTermination re-entered the
same lock on the main thread and froze the app. Finish snapshot sinks
outside the lock and guard the audio tap once stop() begins.

The dictation HUD no longer reassigns its hosting view and forces a
synchronous relayout on every view-model tick; it uses a fixed panel
size and SwiftUI @ObservedObject refresh instead.

Adds OSGKeyboardMacTests with a regression test that fails under the
old lock re-entry pattern.

OSGKeyboardMac/MacAudioRecorder.swift

@@ -36,6 +36,12 @@ final class MacAudioRecorder: @unchecked Sendable {
     private let lock = NSLock()
     private var samples: [Float] = []
     private var snapshotContinuation: AsyncStream<AudioBufferSnapshot>.Continuation?
+    /// Identifies the live snapshot sink. `AsyncStream.Continuation` is not
+    /// equatable, so a termination handler compares generations to tell "my
+    /// stream ended" from "a newer stream already replaced me".
+    private var snapshotGeneration = 0
+    /// Guarded by `lock`: the audio tap runs on the render thread and must stop
+    /// appending the moment `stop()` begins tearing the engine down.
     private var isRunning = false
     /// Hard cap on accumulated audio: 10 minutes @16 kHz ≈ 38 MB of Float32.
     /// Recording is push-to-talk, but a stuck hotkey (or a latched Option
@@ -87,24 +93,65 @@ final class MacAudioRecorder: @unchecked Sendable {
     /// The stream is finished automatically in `stop()`.
     func makeSnapshotStream() -> AsyncStream<AudioBufferSnapshot> {
         AsyncStream { continuation in
-            lock.withLock {
-                snapshotContinuation?.finish()
-                snapshotContinuation = continuation
-            }
+            let generation = installSnapshotSink(continuation)
             continuation.onTermination = { [weak self] _ in
-                self?.lock.withLock {
-                    self?.snapshotContinuation = nil
-                }
+                self?.clearSnapshotSink(ifGeneration: generation)
             }
         }
     }
 
-    private func startEngine() throws {
+    /// Publishes `continuation` as the live sink and returns its generation.
+    ///
+    /// `finish()` invokes `onTermination` **synchronously on the calling
+    /// thread**, and that handler takes `lock`. Since `NSLock` is not
+    /// reentrant, any `finish()` made while holding `lock` deadlocks the
+    /// caller — on the main thread that freezes the whole app. So the outgoing
+    /// continuation is only handed over here and finished after the unlock.
+    private func installSnapshotSink(
+        _ continuation: AsyncStream<AudioBufferSnapshot>.Continuation
+    ) -> Int {
+        let (previous, generation) = lock.withLock {
+            let previous = snapshotContinuation
+            snapshotGeneration += 1
+            snapshotContinuation = continuation
+            return (previous, snapshotGeneration)
+        }
+        previous?.finish()
+        return generation
+    }
+
+    /// Detaches the sink only if it is still the one this generation installed,
+    /// so a late termination from a replaced stream cannot mute the live one.
+    private func clearSnapshotSink(ifGeneration generation: Int) {
         lock.withLock {
-            samples.removeAll(keepingCapacity: true)
-            snapshotContinuation?.finish()
+            guard snapshotGeneration == generation else { return }
             snapshotContinuation = nil
         }
+    }
+
+    #if DEBUG
+    /// Test seam: whether a live snapshot sink is currently attached. Lets the
+    /// regression tests assert that replacing a stream leaves the *new* sink in
+    /// place, which is otherwise invisible from outside.
+    var hasLiveSnapshotSink: Bool {
+        lock.withLock { snapshotContinuation != nil }
+    }
+    #endif
+
+    /// Hands the live sink out for finishing outside the lock. See
+    /// `installSnapshotSink` for why `finish()` must never run under `lock`.
+    private func detachSnapshotSink() -> AsyncStream<AudioBufferSnapshot>.Continuation? {
+        lock.withLock {
+            let detached = snapshotContinuation
+            snapshotContinuation = nil
+            return detached
+        }
+    }
+
+    private func startEngine() throws {
+        let stale = detachSnapshotSink()
+        lock.withLock { samples.removeAll(keepingCapacity: true) }
+        stale?.finish()
 
         let input = engine.inputNode
         let inputFormat = input.outputFormat(forBus: 0)
@@ -118,22 +165,33 @@ final class MacAudioRecorder: @unchecked Sendable {
         }
         engine.prepare()
         try engine.start()
-        isRunning = true
+        lock.withLock { isRunning = true }
     }
 
     /// Stops capture and returns the accumulated 16 kHz mono samples.
     func stop() -> [Float] {
-        guard isRunning else { return [] }
+        // Retire the tap first: `removeTap` / `engine.stop()` can still drain a
+        // buffer in flight, and a callback that appends into a torn-down engine
+        // is what logged `kAudioUnitErr_InvalidElement (-10877)`.
+        let wasRunning = lock.withLock {
+            guard isRunning else { return false }
+            isRunning = false
+            return true
+        }
+        guard wasRunning else { return [] }
+
         engine.inputNode.removeTap(onBus: 0)
         engine.stop()
-        isRunning = false
-        return lock.withLock {
-            snapshotContinuation?.finish()
-            snapshotContinuation = nil
+
+        let sink = detachSnapshotSink()
+        let out = lock.withLock {
             let out = samples
             samples.removeAll(keepingCapacity: false)
             return out
         }
+        // Outside the lock: `finish()` re-enters via `onTermination`.
+        sink?.finish()
+        return out
     }
 
     private func appendResampled(_ buffer: AVAudioPCMBuffer) {
@@ -166,16 +224,18 @@ final class MacAudioRecorder: @unchecked Sendable {
         let rms = (sumSquares / Float(frameCount)).squareRoot()
         let normalized = min(1, max(0, rms * 12))
 
-        lock.withLock {
+        let sink: AsyncStream<AudioBufferSnapshot>.Continuation? = lock.withLock {
+            guard isRunning else { return nil }
             samples.append(contentsOf: chunk)
             if samples.count > Self.maxSampleCount + Self.trimHysteresisSamples {
                 samples.removeFirst(samples.count - Self.maxSampleCount)
             }
             let factor: Float = normalized > smoothedLevel ? 0.5 : 0.15
             smoothedLevel += (normalized - smoothedLevel) * factor
-            snapshotContinuation?.yield(
-                AudioBufferSnapshot(samples: chunk, sampleRate: 16_000)
-            )
+            return snapshotContinuation
         }
+        // Yielded outside the lock so the render thread never holds it across a
+        // consumer hand-off, and never while the sink might terminate.
+        sink?.yield(AudioBufferSnapshot(samples: chunk, sampleRate: 16_000))
     }
 }

OSGKeyboardMac/MacDictationOverlayController.swift

@@ -22,7 +22,9 @@ final class MacDictationOverlayController {
     private var wasBusy = false
 
     private let bottomMargin: CGFloat = 36
-    private let fallbackSize = NSSize(width: 400, height: 52)
+    /// The pill is a fixed size, so the panel never needs to resize while the
+    /// transcript grows — see `MacDictationOverlayView.panelSize`.
+    private let panelSize = MacDictationOverlayView.panelSize
 
     // MARK: - User-draggable position (persisted across launches)
 
@@ -33,8 +35,6 @@ final class MacDictationOverlayController {
     /// pill grows / shrinks with the live transcript (symmetric resize).
     private var customCenterX: CGFloat = 0
     private var customOriginY: CGFloat = 0
-    /// The origin we last set programmatically (kept for clamping / bookkeeping).
-    private var lastProgrammaticOrigin: NSPoint?
     /// Cursor + window origin captured at the start of a manual drag, so we can
     /// follow the absolute cursor and stay immune to the window moving under it.
     private var dragCursorStart: NSPoint?
@@ -72,15 +72,11 @@ final class MacDictationOverlayController {
         }
         .store(in: &cancellables)
 
-        // Keep waveform / app name / copy fresh while visible.
-        viewModel.objectWillChange
-            .receive(on: RunLoop.main)
-            .sink { [weak self] _ in
-                guard let self, self.panel?.isVisible == true else { return }
-                self.refreshContent(viewModel: viewModel)
-                self.resizeToFit()
-            }
-            .store(in: &cancellables)
+        // Waveform / app name / copy refresh through the view's own
+        // `@ObservedObject` binding. Re-driving them from `objectWillChange`
+        // used to reassign `rootView` and force a synchronous relayout ~20×/s
+        // (the level timer's cadence), which deadlocked AppKit layout during
+        // the state storm that fires when the hold-to-talk key is released.
 
         NotificationCenter.default.publisher(for: NSApplication.didChangeScreenParametersNotification)
             .receive(on: RunLoop.main)
@@ -121,8 +117,9 @@ final class MacDictationOverlayController {
 
     private func present(viewModel: MacDictationViewModel) {
         ensurePanel(viewModel: viewModel)
+        // Once per show, not per state change: picks up an appearance or UI
+        // language switch made since the pill was last visible.
         refreshContent(viewModel: viewModel)
-        resizeToFit()
         reposition()
 
         guard let panel else { return }
@@ -144,11 +141,11 @@ final class MacDictationOverlayController {
         if panel != nil { return }
 
         let host = NSHostingView(rootView: makeRoot(viewModel: viewModel))
-        host.frame = NSRect(origin: .zero, size: fallbackSize)
+        host.frame = NSRect(origin: .zero, size: panelSize)
         hosting = host
 
         let panel = NSPanel(
-            contentRect: NSRect(origin: .zero, size: fallbackSize),
+            contentRect: NSRect(origin: .zero, size: panelSize),
             styleMask: [.borderless, .nonactivatingPanel],
             backing: .buffered,
             defer: false
@@ -188,40 +185,11 @@ final class MacDictationOverlayController {
         )
     }
 
-    private func resizeToFit() {
-        guard let panel, let hosting else { return }
-        hosting.layoutSubtreeIfNeeded()
-        let fitting = hosting.fittingSize
-        // Bounds include the 32pt horizontal transparent margin around the pill
-        // (16 per side) that gives the shadow room, so the pill body itself
-        // still spans ~300–520.
-        let width = fitting.width.isFinite && fitting.width > 1
-            ? min(max(fitting.width, 332), 552)
-            : fallbackSize.width
-        let height = fitting.height.isFinite && fitting.height > 1
-            ? max(fitting.height, fallbackSize.height)
-            : fallbackSize.height
-        var frame = panel.frame
-        // Grow / shrink around the anchor center so the pill stays put: the
-        // dragged center when custom, otherwise its current center.
-        let targetMidX = hasCustomPosition ? customCenterX : frame.midX
-        frame.size = NSSize(width: width, height: height)
-        if targetMidX.isFinite {
-            frame.origin.x = targetMidX - width / 2
-        }
-        if let visible = (NSScreen.main ?? NSScreen.screens.first)?.visibleFrame {
-            frame.origin = clampedOrigin(frame.origin, size: frame.size, in: visible)
-        }
-        lastProgrammaticOrigin = frame.origin
-        panel.setFrame(frame, display: true)
-        hosting.frame = NSRect(origin: .zero, size: frame.size)
-    }
-
     private func reposition() {
         guard let panel else { return }
         let screen = NSScreen.main ?? NSScreen.screens.first
         guard let visible = screen?.visibleFrame else { return }
-        let size = panel.frame.size
+        let size = panelSize
         // Respect the user's dragged spot; otherwise snap to bottom-center.
         let desired: NSPoint
         if hasCustomPosition {
@@ -232,9 +200,7 @@ final class MacDictationOverlayController {
                 y: visible.minY + bottomMargin
             )
         }
-        let origin = clampedOrigin(desired, size: size, in: visible)
-        lastProgrammaticOrigin = origin
-        panel.setFrameOrigin(origin)
+        panel.setFrameOrigin(clampedOrigin(desired, size: size, in: visible))
     }
 
     /// Keep the panel fully inside the screen's visible frame so a dragged /
@@ -266,9 +232,7 @@ final class MacDictationOverlayController {
         )
         let size = panel.frame.size
         let visible = (NSScreen.main ?? NSScreen.screens.first)?.visibleFrame
-        let origin = visible.map { clampedOrigin(target, size: size, in: $0) } ?? target
-        lastProgrammaticOrigin = origin
-        panel.setFrameOrigin(origin)
+        panel.setFrameOrigin(visible.map { clampedOrigin(target, size: size, in: $0) } ?? target)
     }
 
     /// Persist the dragged spot as center-X + bottom-left Y.
@@ -287,7 +251,6 @@ final class MacDictationOverlayController {
     private func resetPositionToDefault() {
         hasCustomPosition = false
         clearPersistedPosition()
-        resizeToFit()
         reposition()
     }
 

OSGKeyboardMac/MacDictationOverlayView.swift

@@ -17,6 +17,22 @@ struct MacDictationOverlayView: View {
     var onResetPosition: (() -> Void)?
     @Environment(\.themePalette) private var palette
 
+    /// Pill body width. Wide enough for dot + live badge + a 320pt transcript
+    /// line + waveform + stop button at `Spacing.sm` gaps.
+    static let pillWidth: CGFloat = 500
+    /// Transparent margin around the pill, sized to contain the shadow's reach
+    /// (radius 14 + y 5). The panel is sized to pill + margin, and the shadow
+    /// would otherwise clip into hard translucent-black corners.
+    static let shadowMargin = EdgeInsets(top: 12, leading: 16, bottom: 20, trailing: 16)
+    /// Total panel size the hosting `NSPanel` should use.
+    static var panelSize: CGSize {
+        CGSize(
+            width: pillWidth + shadowMargin.leading + shadowMargin.trailing,
+            // 28pt content + 11pt vertical padding on each side.
+            height: 28 + 22 + shadowMargin.top + shadowMargin.bottom
+        )
+    }
+
     private var lang: AppUILanguage { viewModel.config.uiLanguage }
 
     private var isBusy: Bool {
@@ -46,19 +62,17 @@ struct MacDictationOverlayView: View {
         .frame(height: 28)
         .padding(.horizontal, Spacing.md)
         .padding(.vertical, 11)
-        .frame(minWidth: 300, idealWidth: 400, maxWidth: 520)
-        .fixedSize(horizontal: true, vertical: true)
+        // Fixed width, not intrinsic: the hosting panel is sized from this
+        // constant once, so a growing transcript never asks AppKit to resize
+        // the window mid-update. Long text truncates in `primaryLine` instead.
+        .frame(width: Self.pillWidth)
         .background(palette.surface, in: Capsule(style: .continuous))
         .overlay(
             Capsule(style: .continuous)
                 .stroke(palette.dividerStrong, lineWidth: 0.5)
         )
         .shadow(color: Color.black.opacity(0.22), radius: 14, y: 5)
-        // Transparent margin large enough to contain the shadow's reach
-        // (radius 14 + y 5). The panel is sized to `fittingSize`, which ignores
-        // shadow, so without this room the borderless window clips the shadow
-        // into hard translucent-black corners.
-        .padding(EdgeInsets(top: 12, leading: 16, bottom: 20, trailing: 16))
+        .padding(Self.shadowMargin)
         .contentShape(Capsule(style: .continuous))
         // Manual drag: `isMovableByWindowBackground` doesn't work on a
         // non-activating panel, so we move the panel ourselves. The controller