feat(keybinds): show mnemonic names for obscure keys

Hyprland's key names are its own (mouse:272, XF86Calculator), not what
is printed on the keyboard or how the key is pressed, which defeats a
reminder. A fixed map in Binds.js renames them for display only; an
unlisted key shows as before. SUPER reads as Win for the same reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

3 files changed, 38 insertions, 10 deletions

diff --git a/keybinds/Binds.js b/keybinds/Binds.js
index 697f3c9..2029f36 100644
--- a/keybinds/Binds.js
+++ b/keybinds/Binds.js
@@ -16,14 +16,34 @@
 // Modmask bits, in the order they are written in keybindings.lua.
 // ponytail: CAPS/MOD2/MOD3/MOD5 bits are not decoded and vanish from the
 // combo; add them here if a bind ever uses one.
-const MODS = [[64, "SUPER"], [4, "CTRL"], [8, "ALT"], [1, "SHIFT"]];
+// SUPER shows as Win, the key it is on.
+const MODS = [[64, "Win"], [4, "CTRL"], [8, "ALT"], [1, "SHIFT"]];
 
 function mods(mask) {
     return MODS.filter(m => mask & m[0]).map(m => m[1]);
 }
 
+// Display names for keys whose Hyprland name is hard to remember. A key not
+// listed shows as Hyprland names it. The Fn combos are where the XF86 keys
+// sit on this keyboard, which is how they are pressed.
+const NAMES = Object.assign(Object.create(null), {
+    "mouse:272": "LMB",
+    "mouse:273": "RMB",
+    "mouse_up": "Mouse wheel up",
+    "mouse_down": "Mouse wheel down",
+    "XF86AudioRaiseVolume": "Volume +",
+    "XF86AudioLowerVolume": "Volume -",
+    "XF86AudioMute": "Mute",
+    "XF86AudioPlay": "Play/Pause",
+    "XF86AudioPrev": "Previous song",
+    "XF86AudioNext": "Next song",
+    "XF86Calculator": "Fn+F9",
+    "XF86Mail": "Fn+F10",
+    "XF86Search": "Fn+F11",
+});
+
 function keys(bind) {
-    return mods(bind.modmask).concat([bind.key]).join(" + ");
+    return mods(bind.modmask).concat([NAMES[bind.key] ?? bind.key]).join(" + ");
 }
 
 // A description reads "Group: Label". A bind without one still shows, last,
diff --git a/keybinds/README.md b/keybinds/README.md
index 05d4277..2184f6a 100644
--- a/keybinds/README.md
+++ b/keybinds/README.md
@@ -16,6 +16,10 @@ text comes from each bind's `description` option, written `Group: Label`:
 The part before `: ` is the heading. A bind with no description is listed
 last under "Undescribed", so a missing one shows instead of vanishing.
 
+Key names are Hyprland's unless `NAMES` in `Binds.js` gives a friendlier one
+(`mouse:272` shows as `LMB`, `XF86Calculator` as `Fn+F9`), and SUPER shows as
+Win. Add a line there to rename another.
+
 ## Running
 
     qs -p ./keybinds
diff --git a/keybinds/test_binds.js b/keybinds/test_binds.js
index 81f9108..9acb071 100644
--- a/keybinds/test_binds.js
+++ b/keybinds/test_binds.js
@@ -21,10 +21,14 @@ const src = fs.readFileSync(__dirname + "/Binds.js", "utf8")
 const B = new Function(src + "\nreturn { mods, keys, group };")();
 
 assert.deepStrictEqual(B.mods(0), []);
-assert.deepStrictEqual(B.mods(65), ["SUPER", "SHIFT"]);
+assert.deepStrictEqual(B.mods(65), ["Win", "SHIFT"]);
 assert.deepStrictEqual(B.mods(13), ["CTRL", "ALT", "SHIFT"]);
-assert.strictEqual(B.keys({ modmask: 69, key: "F1" }), "SUPER + CTRL + SHIFT + F1");
-assert.strictEqual(B.keys({ modmask: 0, key: "XF86AudioMute" }), "XF86AudioMute");
+assert.strictEqual(B.keys({ modmask: 69, key: "F1" }), "Win + CTRL + SHIFT + F1");
+assert.strictEqual(B.keys({ modmask: 0, key: "XF86AudioMute" }), "Mute");
+assert.strictEqual(B.keys({ modmask: 64, key: "mouse:272" }), "Win + LMB");
+assert.strictEqual(B.keys({ modmask: 0, key: "F5" }), "F5");
+// A key named like an Object.prototype member is not renamed.
+assert.strictEqual(B.keys({ modmask: 0, key: "constructor" }), "constructor");
 
 assert.deepStrictEqual(B.group([
     { modmask: 64, key: "s", description: "" },
@@ -34,18 +38,18 @@ assert.deepStrictEqual(B.group([
     { modmask: 8, key: "x", description: "No colon here" },
 ]), [
     { name: "Apps", rows: [
-        { keys: "SUPER + w", label: "Browser" },
-        { keys: "SUPER + e", label: "Files" },
+        { keys: "Win + w", label: "Browser" },
+        { keys: "Win + e", label: "Files" },
     ] },
-    { name: "Media", rows: [{ keys: "XF86AudioMute", label: "Mute" }] },
+    { name: "Media", rows: [{ keys: "Mute", label: "Mute" }] },
     { name: "Other", rows: [{ keys: "ALT + x", label: "No colon here" }] },
-    { name: "Undescribed", rows: [{ keys: "SUPER + s", label: "no description" }] },
+    { name: "Undescribed", rows: [{ keys: "Win + s", label: "no description" }] },
 ]);
 
 // A group name matching an Object.prototype property must not resolve to
 // the inherited value instead of creating a new group.
 assert.deepStrictEqual(B.group([
     { modmask: 64, key: "z", description: "toString: Weird" },
-]), [{ name: "toString", rows: [{ keys: "SUPER + z", label: "Weird" }] }]);
+]), [{ name: "toString", rows: [{ keys: "Win + z", label: "Weird" }] }]);
 
 console.log("ok");