uttrflow / uttrflow/uttrflow-swift
Secure keyboard entry silently stops the dictation shortcut, and nothing tells the user why
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What happens
The dictation shortcut is read from a listen-only `CGEventTap` on key down, key up and modifier changes (`Sources/UttrflowInput/SystemKeyboard.swift:125-139`, used by `ActivationMonitor`, `Sources/UttrflowInput/ActivationMonitor.swift:16`). The default binding is ⌥Space (`Sources/UttrflowCore/Keyboard/ShortcutSet.swift:18`), a key press.
While any process has Secure Event Input enabled, macOS does not pass key down and key up events to event taps. Processes that enable it:
- any password field while it has focus;
- a terminal with its "secure keyboard entry" option on, for as long as that terminal is frontmost (in some terminals, for as long as the option is on);
- apps that turn it on and forget to turn it off, which leaves it on system-wide.
Nothing in the source asks:
```
$ git grep -n "SecureEventInput" -- Sources
(no output)
```
So in those states pressing ⌥Space does nothing. The tap is not disabled, so the re-enable logic never fires and nothing is logged. No notice or menu-bar state explains it. The claimed shortcuts are the exception: they are Carbon hot keys (`AppDelegate.swift:698`), which still work, so the clipboard panel opens while dictation does not.
## Why it matters
Developers who dictate commands are the people most likely to have secure keyboard entry on in their terminal. What they see is "dictation stopped working in my terminal", and when the setting leaks it stops working everywhere, with no clue. `Docs/shortcuts.md` does not mention it.
## How to reproduce
1. Open a terminal that has a secure keyboard entry option and turn it on.
2. With that terminal frontmost, press the dictation shortcut. Nothing happens.
3. Turn the option off and press the shortcut again. Dictation starts.
4. `ioreg -l -w 0 | grep SecureInput` shows which process holds secure input while the option is on.
## Acceptance criteria
- When the shortcut cannot be delivered because secure input is on (`IsSecureEventInputEnabled()` is true while the app is trying to listen), the user is told in words, once per episode. The menu bar item and the floating button's hover both say something like: "Another app has turned on secure keyboard entry, so the shortcut can't be heard. Turn it off in that app, or start dictation from the menu bar."
- `IsSecureEventInputEnabled()` is not polled on a timer (see the energy budget in `Docs/performance.md`). It is checked on app activation changes and when the menu is opened.
- Start Dictation from the menu bar still works while secure input is on, and a test covers the notice through a seam over the secure-input check.
- `Docs/shortcuts.md` documents the limitation and which bindings are affected.
Contributor guide
Research direction
Start with Sources/UttrflowInput/SystemKeyboard.swift:125-139 and Sources/UttrflowInput/ActivationMonitor.swift:16, then inspect Sources/UttrflowCore/Keyboard/ShortcutSet.swift:18 and AppDelegate.swift:698. Trace app activation and menu-opening paths, and use a seam over IsSecureEventInputEnabled() for the test. Done means the notice appears once per episode, menu-started dictation still works, and Docs/shortcuts.md documents the affected bindings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, swift
- Domain
- desktop, documentation, testing
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100