Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#401 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

  • #402 by @postoso — closed without merging

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
35/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
swift
Domain
accessibility

Research direction

The remaining work is in the DynamicNotchKit dependency at Sources/DynamicNotchKit/Utility/DynamicNotchPanel.swift; start by reading its canBecomeKey and canBecomeMain overrides. The issue says both should return false and the panel should be hidden from the accessibility tree. Done means the notch overlay no longer takes focus or appears to VoiceOver; coordinate this dependency change separately from the fixes already described for the main app.

Written by the indexing model from the issue text.

Description

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 #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
Dominant language
Swift
Stars
11.9k
Forks
863
Avg merge
1d 13h
Merged PRs (30d)
27

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from altic-dev/FluidVoice

All issues in altic-dev/FluidVoice

Similar issues

More Swift issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.