VoiceOver: dictation overlay steals focus and Cmd+Tab becomes sluggish

[Alshekhi]

Summary

FluidVoice is unusable with VoiceOver enabled. Two distinct problems make it impossible to keep working in another app while dictating:

1. Overlay panels announce to VoiceOver and can shift focus — when dictation starts, VoiceOver announces the overlay window and the user loses their place in the working app.
2. Cmd+Tab becomes sluggish — app switching takes noticeably longer while FluidVoice is running, even when idle (not recording). This affects all app switching, not just switching to/from FluidVoice.

As a VoiceOver user, I deleted the app entirely before finding the repository and investigating.

Status — PR #590

PR #590 implements the two fixes that live in the main app (the default bottom overlay path):

• ✅ Root cause 1 (overlay panels visible to VoiceOver) — fixed in BottomOverlayView.swift.
• ✅ Root cause 3 (CGEvent tap latency on system shortcuts) — fixed in GlobalHotkeyManager.swift. The fast-path was refined during review: it is scoped to Cmd+Tab / Cmd+Space (the ANSI-only backtick keycode was dropped because it differs on ISO layouts), it is skipped when the chord matches a configured Fluid shortcut so real bindings are never swallowed, and it preserves the modifier-only bookkeeping. The snippet under Root Cause 3 below is the original illustration, not the final implementation.
• ⏳ Root cause 2 (DynamicNotchKit panel steals focus) — not in Fix VoiceOver: hide recording overlays and pass through system hotkeys #590. That fix belongs in the separate DynamicNotchKit dependency repo and only affects the non-default notch overlay, so it is tracked separately. This issue stays open until the DynamicNotchKit fix is also handled.

Environment

• macOS 26.5.1 (Sequoia)
• VoiceOver enabled
• FluidVoice 1.6.0 (build 12)
• Overlay position: Bottom (default)

Root Causes

1. Overlay panels visible to VoiceOver

The four floating NSPanel instances in BottomOverlayView.swift (main overlay, prompt selector, mode selector, actions selector) do not hide themselves from the accessibility tree. VoiceOver discovers and announces them, which can shift focus away from the user's working app.

Fix: Add setAccessibilityElement(false) and setAccessibilityRole(.unknown) to all panel creation sites, and add .accessibilityHidden(true) to the BottomOverlayView SwiftUI body.

2. DynamicNotchKit panel steals focus

DynamicNotchPanel.swift in the DynamicNotchKit dependency overrides canBecomeKey and canBecomeMain to return true. When the notch overlay is used, this allows the panel to become the key window and activate the app.

Fix: Change both overrides to return false. Also add setAccessibilityElement(false) and setAccessibilityRole(.unknown).

3. CGEvent tap adds latency to system shortcuts

GlobalHotkeyManager.swift creates a CGEvent tap at .headInsertEventTap that intercepts all keyDown, keyUp, and flagsChanged events system-wide. The callback does significant work (modifier tracking, shortcut matching, spawning async tasks for PostTranscriptionEditTracker) before passing non-matching events through.

With VoiceOver also intercepting keyboard events, both handlers run on every keystroke. System shortcuts like Cmd+Tab pass through both the event tap callback and VoiceOver's processing, adding noticeable latency.

Fix: Add an early return at the top of handleKeyEvent that immediately passes through system shortcuts (Cmd+Tab, Cmd+Shift+Tab, Cmd+Space, Cmd+`) before any processing:

// Fast path: pass through system shortcuts to avoid adding latency
// to app switching, especially with VoiceOver.
if type == .keyDown || type == .keyUp {
    let flags = event.flags
    if flags.contains(.maskCommand) {
        let kc = UInt16(event.getIntegerValueField(.keyboardEventKeycode))
        // Tab(48), Space(49), Backtick(50)
        if kc == 48 || kc == 49 || kc == 50 {
            return Unmanaged.passUnretained(event)
        }
    }
}

Steps to Reproduce

1. Enable VoiceOver (Cmd+F5)
2. Open any app (e.g. TextEdit) and start typing
3. Press the FluidVoice dictation shortcut
4. Problem 1: VoiceOver announces the overlay, focus may shift
5. Stop dictation, then try Cmd+Tab between apps
6. Problem 2: Cmd+Tab feels sluggish/delayed compared to when FluidVoice is not running

Expected Behavior

• Dictation overlay should be invisible to VoiceOver — no announcements, no focus changes
• Cmd+Tab and other system shortcuts should have zero added latency from FluidVoice's event tap

Files to Change

• Sources/Fluid/Views/BottomOverlayView.swift — 4 panel creation sites + SwiftUI body
• Sources/Fluid/Services/GlobalHotkeyManager.swift — handleKeyEvent method
• DynamicNotchKit dependency: Sources/DynamicNotchKit/Utility/DynamicNotchPanel.swift