feat: Custom dictation trigger — bind a keyboard chord or an extra mouse button

[claude]

Requested by Mez, Griffin Sharp, Alex Kroman · Slack thread

What & why

Adds a fourth "Custom…" option to Settings > General > Shortcut > Dictation key that lets the user bind a keyboard chord (modifiers plus a key, e.g. ⌃⌥D) or an extra mouse button (Mouse 3 and up) as the dictation trigger, with press-to-capture UX and the exact same push-to-talk / tap-to-toggle semantics as the built-in modifier triggers. It also removes fn as a built-in option.

Before: the dictation key could only be one of three lone modifiers — right ⌘, right ⌥, or fn.
After: the menu offers right ⌘ / right ⌥ plus Custom…, which opens a sheet that records the next chord or extra-button click. The picker then names what's bound ("⌃⌥D", "Mouse 4"), and the ready screen, menu bar, and permissions footer render it live. Default stays right ⌘; nothing migrates.

Scope history (all maintainer-directed, in the linked thread): v1 allowed F-keys + mouse buttons → F-keys removed, mouse-only → chords added back as chords (not bare F-keys) and fn removed. Removed paths were deleted, not left dormant, per the repo's cleanup discipline.

Settled decision updated — @alexkroman authorized this

AGENTS.md's settled-decisions table named "a key+modifier chord" as a don't-reintroduce item. Alex, who authored that decision, asked for chords in the PR thread, so the row and its rationale now record that chords are supported and why. What has not changed:

• No package — no KeyboardShortcuts, no SPM dependency for key handling. That ban is untouched, its import KeyboardShortcuts rule still fires, and its skill anchor is verbatim as before; only the table row's wording (and the rule's pinned slice of it) moved, updated together so check-invariants.sh --self-test passes.
• The tap stays .listenOnly — an active tap would make macOS wait on Blurt before delivering every keystroke system-wide. So a bound chord is not swallowed: an app that already owns ⌃⌥D still acts on it. Rather than hide that, TriggerBinding.passThroughNote states it in the Settings footer and the capture sheet says it up front.
• Still one control, never a bare key — a bare key would type into the focused app on every dictation.

What the recorder refuses

Input	Result
Bare key (no modifiers)	Refused — "Hold at least one modifier… a key on its own would type into whatever app is focused"
A modifier as the key half (⌃ + ⌘, Caps Lock, fn)	Refused — pick a real key, or right ⌘ / right ⌥ from the menu
⌘Q, ⌘W, ⌘H, ⌘⇥, ⌘Space, ⌃⌘Q	Refused — they'd fire their system action underneath the dictation (and macOS eats ⌘⇥/⌘Space before any monitor sees them, so they could never be captured anyway)
Left / right click	Never arrives (not otherMouseDown)
Esc	Cancels the sheet, always
Wheel click (Mouse 3)	Allowed, with a caution — see below

"Is Mouse 3 always the middle click?" — yes, and the off-by-one is now pinned

The stored value is the raw 0-based CGEvent/NSEvent buttonNumber: 0 left, 1 right, 2 wheel/middle, 3+ side buttons; only 2 and up are bindable. The display name is 1-based, the way mice and their drivers number buttons for users — so stored 2 renders as "Mouse 3" and is the middle (wheel) click. That is now stated in the doc comments, asserted by a label test (mouseButton(2).label == "Mouse 3"), and consistent across UI, tests, logs, and this description. Because browsers and terminals act on the wheel click and the tap swallows nothing, it is not hard-blocked but carries its own passThroughNote ("Mouse 3 is the wheel click… apps that use it will still act on it"); side buttons get no caution because almost nothing claims them.

fn removal and migration

fn is the one modifier macOS itself claims (dictation, emoji picker, the F-key row), so it never belonged in a list of keys a solo press could own. TriggerKey is now right ⌘ / right ⌥ only and its secondary-fn mask bit is gone (chords read the generic modifier masks instead). A persisted fn (keycode 63) migrates to right ⌥, not to the generic right-⌘ fallback — it's the other right-side modifier, so those users keep a one-key trigger on the same side of the keyboard. Pinned by persistedFunctionKeyMigratesToRightOption.

How

• TriggerBinding: .modifier(TriggerKey) / .chord(keyCode:modifiers:) / .mouseButton(Int), all in the existing single Int slot BlurtTriggerKeyCode — modifiers as bare keycodes (zero migration), mouse buttons at 0x10000 + button, chords packed as 0x20000 | (modifiers << 8) | keyCode (keycode low byte, four modifier bits above; keycodes are 16-bit so the tags can't collide — pinned by a disjointness test). One slot keeps the @AppStorage live-render pattern. ChordModifiers is a side-agnostic OptionSet with a persisted bit layout and glyphs in Apple's ⌃⌥⇧⌘ order. fromPersisted stays the single decode-with-default rule (garbage → right ⌘; a structurally invalid packed chord counts as garbage). Capture policy is engine logic: chordBinding(forKeyCode:modifiers:) returns Result<TriggerBinding, ChordRefusal> so the reason survives into the sheet's copy.
• DictationKeyRouter: .keyDown(keyCode:modifiers:) / .keyUp(keyCode:) / .flagsChanged(…, modifiers:) / mouse events, routed per binding family through one shared edge filter. A chord fires only on the exact required modifier set and ends on the key's keyUp or the release of any required modifier (the realistic ⌃⌥D release order is ⌃ first — waiting for D's keyUp would strand a hold recording). Combo cancel remains modifier-bindings-only: a chord's own modifiers are part of the trigger, and typing during a latched dictation is just typing. DictationKeyGate is still untouched, so hold ≥ 1 s = push-to-talk and shorter = tap-to-latch behave identically for all three families.
• DictationEventDecoder: the CGEvent → router-event reduction (engine-side so it's testable), now also mapping flags → ChordModifiers via the generic masks (⌃ is ⌃; Caps Lock and fn deliberately excluded) and dropping autorepeat key-downs.
• DictationKeyTap: mask keyDown | keyUp | flagsChanged | otherMouseDown | otherMouseUp (fixed at creation; the router ignores what the binding doesn't need, so rebinding never recreates the tap), .listenOnly, and dropped-event recovery per family — for a chord, keyState and the required modifiers via flagsState.
• UI: the capture sheet shows held modifiers live (⌃⌥…) as the chord forms, states the pass-through up front, and turns each engine refusal into one sentence; mouse capture is unchanged (local + global otherMouseDown monitors). The Shortcut footer appends passThroughNote for the bound binding.
• Developer-mode capture log: ~/Library/Logs/Blurt/capture-events.jsonl records every event the recorder sees — accepted or refused, chords included — with kind, outcome token (captured, refused-bare-key, refused-modifier-only, refused-reserved-chord, refused-button, cancelled), button number, keycode, flags, autorepeat. Third file of the existing log, sharing its gate/queue/encoder; off by default, nothing on disk.
• Tests: chord round-trips for every modifier set, namespace disjointness, invalid-packing fallbacks, capture policy + reserved chords, glyph labels, fn migration, pass-through notes; a chord router suite (hold/tap, exact-modifier matching, partial-modifier release, autorepeat dedup, no-combo rule, latched survival, recovery, cross-family rebind); real-CGEvent chord decode fixtures (flag combinations including device side bits, Caps Lock/fn exclusion, autorepeat drop, partial release). All pure — no event taps, no audio.

Notes for review:

• No new app-target files (xcodegen isn't available here and project.pbxproj must not be hand-edited) — the capture sheet lives in HotkeyStepView.swift; new engine files are fine.
• A local NSEvent monitor can't see chords macOS reserves — the same reason those are refused rather than discouraged. Documented in the sheet's doc comment.
• No XCUITest for chord capture (the runner can't synthesize a chord into a sheet reliably); the decoder fixtures plus router/gate suites cover the logic.

How it was tested

Authored in a Linux sandbox — no macOS toolchain, so CI on macos-26 is the authority on green. scripts/check.sh --portable passes locally (repo-integrity guards, settled-decision invariants incl. --self-test, shell portability, actionlint/zizmor/prettier/markdownlint/shellcheck/shfmt, evals, release.test.sh). The pre-chord revision (ed121cf) was fully green on CI — required check, gate, compile, format-patch, CodeQL, Aikido; CI is running on the chord head now and I'm watching it.

• scripts/check.sh passes (or CI will, if I'm not on a Mac) — portable subset green locally; CI runs the Swift side
• I read AGENTS.md and this doesn't reintroduce anything deliberately removed — it updates one settled decision at the maintainer's explicit request; see above
• Docs updated if behavior changed

[claude]

Closing this unmerged at the maintainer's request — the work grew beyond the intended scope.

---

Generated by Claude Code