feat(hotkeys): repeat a held global hotkey on Linux and Windows (#1621)

Author: y3owk1n

docs/CROSS_PLATFORM.md

@@ -526,7 +526,7 @@ compositor infer the drag.
 | **In-mode capture**   | `CGEventTapCreate`     | `XGrabKeyboard`         | evdev proxy (lifetime `EVIOCGRAB` + uinput re-emit), wl-keyboard fallback | `WH_KEYBOARD_LL`        |
 | **Global hotkeys**    | Per-key CGEventTap     | `XGrabKey`              | Chord matcher on the evdev proxy         | `RegisterHotKey`        |
 | **CGO needed**        | Yes                    | Yes                     | Yes                                      | No                      |
-| **Press/release**     | ✅ separate callbacks  | ✅ KeyPress/KeyRelease  | ⚠️ press-only in some configs            | ✅ `WM_HOTKEY` flags    |
+| **Press/release**     | ✅ separate callbacks  | ✅ KeyPress/KeyRelease  | ✅ evdev press/release                   | ✅ press, then `GetAsyncKeyState` poll |
 | **Modifier passthrough** | ✅                  | ❌ grab is all-or-nothing | ✅ evdev only                          | ✅ hook forwards per event |
 | **`PostModifierEvent`** | ✅                   | ✅                      | ✅ (`zwp_virtual_keyboard_v1`)           | ✅ `SendInput`          |
 | **Sticky modifiers**  | ✅                     | ✅                      | ✅                                       | ✅                      |
@@ -537,6 +537,23 @@ There is no separate Wayland hotkey file. The Wayland path lives in the common
 `hotkeys/linux/manager.go`, which delegates to the evdev listener in the
 eventtap package.
 
+**A held global hotkey.** Every manager implements `HotkeyReleaseRegistrar`,
+and reports a hold as one press and one release however long it lasts, which is
+what `[held_repeat]` repeats between. macOS folds autorepeat in the per-hotkey
+tap. The evdev proxy fires the release when the chord's key comes up, whether or
+not the modifier is still down by then. X11 asks the server for detectable
+autorepeat on both of its connections (`XkbSetDetectableAutoRepeat`), so a held
+key is repeated `KeyPress` events and one `KeyRelease` rather than the
+release/press pairs that would end the hold at the server's repeat rate; the
+in-mode tap needs the same, or the mode's own held repeat stops after its first
+tick. `RegisterHotKey` reports the press only, so the Windows registry registers
+with `MOD_NOREPEAT` and reads the key through `GetAsyncKeyState` every 10 ms
+from the `WM_HOTKEY` until it reads up. The poll runs only while a hotkey is
+held; the other source of releases, the `WH_KEYBOARD_LL` hook, sits on every
+keystroke for as long as it is installed, and installing it for the daemon's
+lifetime would put a hook procedure on the idle path to pay for a release only a
+held hotkey needs.
+
 **A global chord while a mode is active.** A `[hotkeys]` binding keeps working
 from inside a mode on macOS, Windows and Linux Wayland, and each gets there its
 own way, because whichever mechanism can see the chord has to be the only one

internal/adapter/eventtap/linux/evdev_proxy_cgo.go

@@ -66,7 +66,18 @@ type evdevProxy struct {
 	pointerNode   *proxyNode
 	heldByAnother func(*proxyNode) bool
 
-	bindings atomic.Pointer[map[string]func()]
+	bindings atomic.Pointer[map[string]hotkeyBinding]
+
+	// heldHotkeys is the release callback owed for each key whose press
+	// matched a chord and is still down, by key code. Owned by the run
+	// goroutine. It is what lets a binding repeat while its key is held: the
+	// press fires once, at match time, and the release fires when this key
+	// comes up, whichever consumer the events reached in between.
+	heldHotkeys map[uint16]func()
+
+	// dispatch runs the matched bindings' callbacks, in order, off this
+	// goroutine.
+	dispatch *HotkeyDispatcher
 
 	control chan proxyCommand
 	done    chan struct{}
@@ -80,6 +91,13 @@ type proxyCommand struct {
 	ack     chan struct{}
 }
 
+// hotkeyBinding is what the idle matcher fires for a chord: press when the
+// chord's key goes down, release (which may be nil) when that key comes up.
+type hotkeyBinding struct {
+	press   func()
+	release func()
+}
+
 var (
 	sharedProxyMu sync.Mutex
 	sharedProxy   *evdevProxy
@@ -161,11 +179,13 @@ func newEvdevProxy(logger *zap.Logger) (*evdevProxy, error) {
 		control:       make(chan proxyCommand),
 		done:          make(chan struct{}),
 		heldByAnother: (*proxyNode).heldByAnother,
+		heldHotkeys:   make(map[uint16]func()),
+		dispatch:      NewHotkeyDispatcher(),
 	}
 
 	proxy.forwarding.Store(uinputFd >= 0)
 
-	empty := map[string]func(){}
+	empty := map[string]hotkeyBinding{}
 	proxy.bindings.Store(&empty)
 
 	go proxy.run()
@@ -200,8 +220,8 @@ func (p *evdevProxy) alive() bool {
 
 // setBindings replaces the chords the idle matcher fires on. The map is read
 // on the run goroutine without a lock, so it is swapped whole and never edited.
-func (p *evdevProxy) setBindings(bindings map[string]func()) {
-	copied := make(map[string]func(), len(bindings))
+func (p *evdevProxy) setBindings(bindings map[string]hotkeyBinding) {
+	copied := make(map[string]hotkeyBinding, len(bindings))
 	maps.Copy(copied, bindings)
 
 	p.bindings.Store(&copied)
@@ -412,6 +432,7 @@ func (p *evdevProxy) handleKey(event waylandEvdevEvent) {
 	case evdevValueRelease:
 		p.capture.feedKey(code, false)
 		p.trackGlobal(code, false)
+		p.releaseHotkey(code)
 
 		forwarded := p.rule.release(code)
 		if forwarded {
@@ -439,7 +460,8 @@ func (p *evdevProxy) trackGlobal(code uint16, isDown bool) {
 }
 
 // matchHotkey fires the binding for the chord a press completes, if there is
-// one, and reports whether it did.
+// one, and reports whether it did. A press fires once per hold: the kernel
+// reports a held key as repeats, not presses, so none of those reach here.
 func (p *evdevProxy) matchHotkey(code uint16) bool {
 	bindings := *p.bindings.Load()
 	if len(bindings) == 0 {
@@ -456,18 +478,36 @@ func (p *evdevProxy) matchHotkey(code uint16) bool {
 		return false
 	}
 
-	callback := bindings[signature]
-	if callback == nil {
+	binding, bound := bindings[signature]
+	if !bound || binding.press == nil {
 		return false
 	}
 
 	p.logger.Debug("Global hotkey matched", zap.String("chord", signature))
 
-	go callback()
+	if binding.release != nil {
+		p.heldHotkeys[code] = binding.release
+	}
+
+	p.dispatch.Dispatch(binding.press)
 
 	return true
 }
 
+// releaseHotkey fires the release owed for a key whose press matched a chord.
+// It is keyed by the key alone, not the chord: the binder needs the release
+// whether or not the modifier is still down when the key comes up.
+func (p *evdevProxy) releaseHotkey(code uint16) {
+	release, held := p.heldHotkeys[code]
+	if !held {
+		return
+	}
+
+	delete(p.heldHotkeys, code)
+
+	p.dispatch.Dispatch(release)
+}
+
 // emit re-emits one event on the proxy keyboard.
 func (p *evdevProxy) emit(event waylandEvdevEvent) {
 	var raw C.struct_input_event

internal/adapter/eventtap/linux/evdev_proxy_test.go

@@ -36,17 +36,19 @@ func newTestProxy() *evdevProxy {
 		done:     make(chan struct{}),
 	}
 
-	empty := map[string]func(){}
+	empty := map[string]hotkeyBinding{}
 	proxy.bindings.Store(&empty)
+	proxy.heldHotkeys = make(map[uint16]func())
+	proxy.dispatch = NewHotkeyDispatcher()
 
 	return proxy
 }
 
 func bindTestChord(proxy *evdevProxy) chan struct{} {
 	fired := make(chan struct{}, 4)
 
-	proxy.setBindings(map[string]func(){
-		canonicalChordSignature(testChord): func() { fired <- struct{}{} },
+	proxy.setBindings(map[string]hotkeyBinding{
+		canonicalChordSignature(testChord): {press: func() { fired <- struct{}{} }},
 	})
 
 	return fired
@@ -189,6 +191,54 @@ func TestForwardRule_IgnoresCodesOutsideTheKeyRange(t *testing.T) {
 	}
 }
 
+// A held chord is one press and one release to the binder, which is what lets
+// it repeat the binding for as long as the key is down: the kernel's repeats
+// fire nothing, and the release comes when the key comes up, whether or not
+// the modifier is still held by then.
+func TestEvdevProxy_AHeldChordFiresPressOnceAndReleaseWhenItsKeyComesUp(t *testing.T) {
+	t.Parallel()
+
+	proxy := newTestProxy()
+	pressed := make(chan struct{}, 4)
+	released := make(chan struct{}, 4)
+
+	proxy.setBindings(map[string]hotkeyBinding{
+		canonicalChordSignature(testChord): {
+			press:   func() { pressed <- struct{}{} },
+			release: func() { released <- struct{}{} },
+		},
+	})
+
+	proxy.handle(keyEvent(evdevKeyLeftMeta, evdevValuePress))
+	proxy.handle(keyEvent(evdevKeySemicolon, evdevValuePress))
+
+	if !waitFired(t, pressed) {
+		t.Fatal("the chord did not match")
+	}
+
+	proxy.handle(keyEvent(evdevKeySemicolon, evdevValueRepeat))
+	proxy.handle(keyEvent(evdevKeySemicolon, evdevValueRepeat))
+
+	select {
+	case <-pressed:
+		t.Fatal(
+			"a repeat fired the press again; the binder would restart its repeat from the delay",
+		)
+	case <-released:
+		t.Fatal("the release fired while the key was still down")
+	case <-time.After(50 * time.Millisecond):
+	}
+
+	// The modifier comes up first, so the key's release is no longer the
+	// chord. The release is owed to the key, not the chord.
+	proxy.handle(keyEvent(evdevKeyLeftMeta, evdevValueRelease))
+	proxy.handle(keyEvent(evdevKeySemicolon, evdevValueRelease))
+
+	if !waitFired(t, released) {
+		t.Fatal("the key came up and no release fired; the binder would repeat forever")
+	}
+}
+
 // A matched chord is withheld from the focused app, the way the macOS tap
 // consumes it, while the modifier that was already down when it matched stays
 // the compositor's and is released to it.
@@ -612,7 +662,7 @@ func TestGlobalHotkeyListener_StopDetachesTheBindings(t *testing.T) {
 
 	proxy := newTestProxy()
 	listener := NewGlobalHotkeyListener(nil)
-	listener.SetBinding(testChord, func() {})
+	listener.SetBinding(testChord, func() {}, nil)
 
 	listener.mu.Lock()
 	listener.proxy = proxy

internal/adapter/eventtap/linux/global_hotkey_cgo.go

@@ -20,7 +20,7 @@ type GlobalHotkeyListener struct {
 	logger *zap.Logger
 
 	mu       sync.Mutex
-	bindings map[string]func()
+	bindings map[string]hotkeyBinding
 	proxy    *evdevProxy
 	running  bool
 }
@@ -34,22 +34,23 @@ func NewGlobalHotkeyListener(logger *zap.Logger) *GlobalHotkeyListener {
 
 	return &GlobalHotkeyListener{
 		logger:   logger.Named("hotkeys.evdev"),
-		bindings: make(map[string]func()),
+		bindings: make(map[string]hotkeyBinding),
 	}
 }
 
-// SetBinding registers a callback for a chord string (e.g. "Ctrl+Shift+G").
-// Safe to call before or after Start.
-func (l *GlobalHotkeyListener) SetBinding(chord string, callback func()) {
+// SetBinding registers the callbacks for a chord string (e.g. "Ctrl+Shift+G"):
+// press when the chord's key goes down, release (nil for none) when it comes
+// up. Safe to call before or after Start.
+func (l *GlobalHotkeyListener) SetBinding(chord string, press, release func()) {
 	signature := canonicalChordSignature(chord)
-	if signature == "" || callback == nil {
+	if signature == "" || press == nil {
 		return
 	}
 
 	l.mu.Lock()
 	defer l.mu.Unlock()
 
-	l.bindings[signature] = callback
+	l.bindings[signature] = hotkeyBinding{press: press, release: release}
 	l.publishLocked()
 }
 
@@ -58,7 +59,7 @@ func (l *GlobalHotkeyListener) ClearBindings() {
 	l.mu.Lock()
 	defer l.mu.Unlock()
 
-	l.bindings = make(map[string]func())
+	l.bindings = make(map[string]hotkeyBinding)
 	l.publishLocked()
 }
 

internal/adapter/eventtap/linux/global_hotkey_nocgo.go

@@ -21,7 +21,7 @@ func NewGlobalHotkeyListener(_ *zap.Logger) *GlobalHotkeyListener {
 }
 
 // SetBinding is a no-op without cgo.
-func (l *GlobalHotkeyListener) SetBinding(_ string, _ func()) {}
+func (l *GlobalHotkeyListener) SetBinding(_ string, _, _ func()) {}
 
 // ClearBindings is a no-op without cgo.
 func (l *GlobalHotkeyListener) ClearBindings() {}

internal/adapter/eventtap/linux/hotkey_dispatch.go

@@ -0,0 +1,82 @@
+//go:build linux
+
+package linux
+
+import "sync"
+
+// HotkeyDispatcher runs hotkey callbacks off the goroutine that reads key
+// events, one at a time, in the order they were queued.
+//
+// Off that goroutine because a callback takes the mode handler's lock, and the
+// handler waits on the reader while holding it (the proxy's session ack, the
+// X11 loop's exit), so running it inline could deadlock. In order because a
+// goroutine per callback has none: a release and the press that follows it
+// could run swapped, and the release would then cancel the repeat the new
+// press had just started, leaving a held key that stops repeating.
+//
+// The queue is unbounded rather than dropping under pressure, because a
+// release is the one thing that ends a held key's repeat: dropped, the repeat
+// would outlive the key. What queues is two callbacks per hotkey press, so
+// even a handler stuck for the length of a hold grows it by a few entries.
+type HotkeyDispatcher struct {
+	mu      sync.Mutex
+	ready   *sync.Cond
+	queue   []func()
+	stopped bool
+}
+
+// NewHotkeyDispatcher starts a dispatcher.
+func NewHotkeyDispatcher() *HotkeyDispatcher {
+	dispatcher := &HotkeyDispatcher{}
+	dispatcher.ready = sync.NewCond(&dispatcher.mu)
+
+	go dispatcher.run()
+
+	return dispatcher
+}
+
+// Dispatch queues callback. It never blocks the reader.
+func (d *HotkeyDispatcher) Dispatch(callback func()) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	if d.stopped {
+		return
+	}
+
+	d.queue = append(d.queue, callback)
+	d.ready.Signal()
+}
+
+// Stop ends the dispatcher once it has run what is queued. It does not wait,
+// because a queued callback may be waiting on a lock the owner holds.
+func (d *HotkeyDispatcher) Stop() {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	d.stopped = true
+	d.ready.Signal()
+}
+
+func (d *HotkeyDispatcher) run() {
+	for {
+		d.mu.Lock()
+
+		for len(d.queue) == 0 && !d.stopped {
+			d.ready.Wait()
+		}
+
+		if len(d.queue) == 0 {
+			d.mu.Unlock()
+
+			return
+		}
+
+		callback := d.queue[0]
+		d.queue[0] = nil
+		d.queue = d.queue[1:]
+		d.mu.Unlock()
+
+		callback()
+	}
+}