fix(hotkeys): bind Delete to the backspace key on Linux, as on macOS and Windows (#1624)

Author: y3owk1n

docs/CONFIGURATION.md

@@ -359,6 +359,9 @@ right either way.
 | Navigation | `Up`, `Down`, `Left`, `Right`, `Home`, `End`, `PageUp`, `PageDown`, `Insert` (Linux and Windows only)   |
 | Function   | `F1`–`F24` (`F21`–`F24` on Linux and Windows only)                                                      |
 
+`Delete` and `Backspace` both name the backspace key, the one that erases to the
+left, on every platform. The forward-delete key has no hotkey name.
+
 See [CLI.md](CLI.md#neru-action-feed) for a full key reference with key codes and platform behavior.
 
 Multi-key sequences (e.g. `gg`, `ab`) are supported for per-mode hotkeys with a 500ms timeout.

internal/adapter/eventtap/linux/global_hotkey_cgo.go

@@ -42,7 +42,7 @@ func NewGlobalHotkeyListener(logger *zap.Logger) *GlobalHotkeyListener {
 // 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)
+	signature := canonicalBindingSignature(chord)
 	if signature == "" || press == nil {
 		return
 	}

internal/adapter/eventtap/linux/global_hotkey_keys.go

@@ -19,14 +19,36 @@ const (
 	canonicalKeyTab       = "tab"
 	canonicalKeyEscape    = "escape"
 	canonicalKeyBackspace = "backspace"
+
+	// canonicalKeyDelete is the spelling a configured "Delete" arrives as. It
+	// is a binding-side name only: canonicalBindingBaseKey folds it to
+	// canonicalKeyBackspace, so no stored chord ever carries it.
+	canonicalKeyDelete = "delete"
 )
 
+// canonicalBindingSignature is canonicalChordSignature for a chord read from
+// the config, the side that can spell "Delete". In [hotkeys] that name means
+// the backspace key on every platform — kVK_Delete on macOS, VK_BACK on
+// Windows, XK_BackSpace on X11 — so it is folded to the signature a press of
+// that key produces. A live press never takes this fold: the forward-delete
+// key keeps the "delete" signature, which no configured chord can carry, and
+// so matches nothing, as it does on the other platforms.
+func canonicalBindingSignature(chord string) string {
+	return chordSignature(chord, canonicalBindingBaseKey)
+}
+
 // canonicalChordSignature normalizes a chord such as "Ctrl+Shift+G" or the
 // evdev-decoded "Shift+Ctrl+g" into a stable signature like "ctrl+shift+g":
 // modifiers lowercased, de-duplicated and sorted, base key lowercased/normalized.
 // This lets the config side and the live keyboard side match regardless of the
 // order or casing each produced.
 func canonicalChordSignature(chord string) string {
+	return chordSignature(chord, canonicalBaseKey)
+}
+
+// chordSignature is the normalization both signatures share; baseKey is how
+// the non-modifier key is spelled.
+func chordSignature(chord string, baseKey func(string) string) string {
 	chord = strings.TrimSpace(chord)
 	if chord == "" {
 		return ""
@@ -37,7 +59,7 @@ func canonicalChordSignature(chord string) string {
 		return ""
 	}
 
-	base := canonicalBaseKey(parts[len(parts)-1])
+	base := baseKey(parts[len(parts)-1])
 	if base == "" {
 		return ""
 	}
@@ -82,6 +104,17 @@ func canonicalModifierToken(token string) string {
 	}
 }
 
+// canonicalBindingBaseKey is canonicalBaseKey plus the fold
+// canonicalBindingSignature describes: "Delete" names the backspace key.
+func canonicalBindingBaseKey(base string) string {
+	switch strings.ToLower(strings.TrimSpace(base)) {
+	case canonicalKeyDelete:
+		return canonicalKeyBackspace
+	default:
+		return canonicalBaseKey(base)
+	}
+}
+
 // canonicalBaseKey normalizes the non-modifier key. Single characters are
 // lowercased; common named keys are folded to one spelling.
 func canonicalBaseKey(base string) string {

internal/adapter/eventtap/linux/global_hotkey_keys_test.go

@@ -42,3 +42,42 @@ func TestCanonicalChordSignatureMatchesAcrossSides(t *testing.T) {
 		t.Fatal("config and live spellings of Ctrl+Shift+G do not match")
 	}
 }
+
+// TestCanonicalBindingSignature_DeleteNamesTheBackspaceKey pins what a
+// configured "Delete" binds on the Wayland listener: the backspace key, as on
+// macOS and Windows and the X11 grab. The config side folds the name, and the
+// live side does not, so a press of the forward-delete key — which the
+// decoder also spells "Delete" — keeps a signature no configured chord carries.
+func TestCanonicalBindingSignature_DeleteNamesTheBackspaceKey(t *testing.T) {
+	const wantModifiedDelete = "ctrl+shift+" + canonicalKeyBackspace
+
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"config delete", evdevKeyNameDelete, canonicalKeyBackspace},
+		{"config delete with modifiers", "Ctrl+Shift+Delete", wantModifiedDelete},
+		{"config backspace", evdevKeyNameBackspace, canonicalKeyBackspace},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := canonicalBindingSignature(tc.in); got != tc.want {
+				t.Fatalf("canonicalBindingSignature(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+
+	live := canonicalChordSignature(evdevKeyNameDelete)
+	if live == canonicalBindingSignature(evdevKeyNameDelete) {
+		t.Fatalf(
+			"a live forward-delete press canonicalizes to %q, the signature a configured Delete binds",
+			live,
+		)
+	}
+
+	if got := canonicalChordSignature(evdevKeyNameBackspace); got != canonicalKeyBackspace {
+		t.Fatalf("live backspace press canonicalizes to %q, want %q", got, canonicalKeyBackspace)
+	}
+}

internal/adapter/hotkeys/linux/x11_cgo.go

@@ -398,11 +398,14 @@ func parseX11Hotkey(display *C.Display, keyString string) (C.uint, C.uint, error
 // coincidence of spelling, not a contract.
 //
 // "Backspace" is the same story with a sharper edge: X11 spells it "BackSpace",
-// so it resolved through neither path, and the repair that suggests itself —
-// folding the name through the vocabulary's aliases — grabs the wrong physical
-// key, for the reason x11CanonicalKeyName below sets out. Delete and Insert are
-// mapped alongside it rather than left to their matching spellings, so a reader
-// sees the three editing keys and their distinct keysyms in one place.
+// so it resolved through neither path. "Delete" reaches the same keysym on
+// purpose: in [hotkeys] the name means the backspace key on every platform —
+// kVK_Delete on macOS, VK_BACK on Windows — and X11's own "Delete", the
+// forward-delete key, is what a config file would have grabbed here alone.
+// The forward-delete key has no hotkey name; one that all three platforms can
+// bind is the way to add it, not a Linux-only meaning for this one. Insert is
+// mapped alongside the pair rather than left to its matching spelling, so a
+// reader sees the editing keys in one place.
 //
 // The rest fall through to XStringToKeysym: punctuation, and F1-F24, where
 // X11's own name for the key is the name Neru writes. Those are pinned by test
@@ -429,10 +432,8 @@ func x11KeysymFor(key string) C.KeySym {
 		return C.XK_Tab
 	case keyvocab.KeyEscape:
 		return C.XK_Escape
-	case keyvocab.KeyBackspace:
+	case keyvocab.KeyBackspace, keyvocab.KeyDelete:
 		return C.XK_BackSpace
-	case keyvocab.KeyDelete:
-		return C.XK_Delete
 	case keyvocab.KeyInsert:
 		return C.XK_Insert
 	case keyvocab.KeyUp:
@@ -468,12 +469,13 @@ func x11KeysymFor(key string) C.KeySym {
 // strings reaching this adapter were already canonicalized — config's
 // CanonicalHotkeyForPlatform display-cases the base key without folding
 // aliases — and it is what a grab needs: a grab names a physical key, and the
-// vocabulary's aliases cross keys that X11 keeps apart. Folding "Backspace" to
-// "Delete" the way the taps do would resolve XK_Delete and grab the
-// forward-delete key for a binding written "Backspace". So a named key keeps
-// its own spelling here — "Enter" does not become "Return", though both are
-// mapped above — and only "esc", which the vocabulary deliberately keeps out of
-// the named-key set, resolves through its alias.
+// switch above is where each name is given one. Folding "Backspace" to
+// "Delete" the way the taps do and then handing "Delete" to XStringToKeysym
+// is how a binding written "Backspace" once grabbed the forward-delete key.
+// So a named key keeps its own spelling here — "Enter" does not become
+// "Return", though both are mapped above — and only "esc", which the
+// vocabulary deliberately keeps out of the named-key set, resolves through
+// its alias.
 func x11CanonicalKeyName(key string) string {
 	if display, isNamed := keyvocab.NamedKeyDisplay(key); isNamed {
 		return display

internal/adapter/hotkeys/linux/x11_keysym_test.go

@@ -33,7 +33,6 @@ const (
 	x11KeysymInsert    = 0xFF63 // XK_Insert
 	x11KeysymF1        = 0xFFBE // XK_F1
 	x11KeysymF24       = 0xFFD5 // XK_F24
-	x11KeysymDelete    = 0xFFFF // XK_Delete
 	x11KeysymJ         = 0x006A // XK_j
 )
 
@@ -73,10 +72,10 @@ func TestX11KeysymFor_NavigationKeys(t *testing.T) {
 // TestX11KeysymFor_EditingKeys pins Backspace, Delete and Insert, and pins them
 // together because the first two are the pair a hotkey can get wrong without
 // noticing. X11 spells the erase-left key "BackSpace", so Neru's "Backspace"
-// resolves only when the lookup maps it; and the vocabulary makes "Backspace"
-// an alias of "Delete", so a lookup that folded aliases would grab X11's
-// forward-delete key instead. Both spellings must reach their own keysym, and
-// neither may reach the other's.
+// resolves only when the lookup maps it; and X11 spells the forward-delete key
+// "Delete", so Neru's "Delete" — the backspace key, as on macOS and Windows —
+// resolves to the right key only when the lookup maps it too. Both spellings
+// must reach XK_BackSpace, and neither may reach XK_Delete.
 func TestX11KeysymFor_EditingKeys(t *testing.T) {
 	t.Parallel()
 
@@ -87,8 +86,8 @@ func TestX11KeysymFor_EditingKeys(t *testing.T) {
 	}{
 		{name: "backspace", key: keyvocab.KeyBackspace, want: x11KeysymBackSpace},
 		{name: "lowercased backspace", key: "backspace", want: x11KeysymBackSpace},
-		{name: "delete", key: keyvocab.KeyDelete, want: x11KeysymDelete},
-		{name: "lowercased delete", key: "delete", want: x11KeysymDelete},
+		{name: "delete", key: keyvocab.KeyDelete, want: x11KeysymBackSpace},
+		{name: "lowercased delete", key: "delete", want: x11KeysymBackSpace},
 		{name: "insert", key: keyvocab.KeyInsert, want: x11KeysymInsert},
 		{name: "lowercased insert", key: "insert", want: x11KeysymInsert},
 	}

internal/architecture/doc.go

@@ -41,6 +41,9 @@
 //     by naming it, and every test name or test file it names resolves.
 //   - hint_placement_vocabulary_test.go — the hint placement vocabulary is the
 //     same on both sides of the Go/Objective-C boundary.
+//   - hotkey_delete_key_test.go — every platform's [hotkeys] table resolves
+//     "Delete" and "Backspace" to one physical key, the backspace key, so a
+//     config file binds the same key on all three.
 //   - justfile_doc_test.go — every recipe just --list shows declares its own
 //     one-line summary, rather than inheriting whichever line of the comment
 //     block above it just happens to read.