Shortcuts you invent, rules you write, gestures you own - all still just data

Claude-Session: https://claude.ai/code/session_01Ms2FbjQy31TVf3CEvQhGM8

config/dot/hypr/keybinds.lua

@@ -12,6 +12,7 @@
 -- ─────────────────────────────────────────────────────────────────────────────
 
 local prefs = require("prefs")
+local actions = require("actions")
 
 local mod = "SUPER"
 
@@ -574,6 +575,52 @@ bind("XF86WWW", hl.dsp.exec_cmd(browser), { description = "Browser" })
 bind("XF86Mail", hl.dsp.exec_cmd(mail), { description = "Mail" })
 bind("XF86Search", hl.dsp.exec_cmd(launcher), { description = "Launcher" })
 
+-- ── Custom shortcuts ────────────────────────────────────────────────────────
+--
+-- Shortcuts the user invented, from `customBinds` in settings.json. Each entry
+-- is { chord, kind, target, label } -- data, never a command. actions.lua turns
+-- the kind/target pair into a dispatcher through whitelist tables; an entry it
+-- does not recognise resolves to nil and is silently not emitted.
+--
+-- Emitted LAST, and through hl.bind rather than the `bind` wrapper above. Two
+-- separate reasons, both about keeping the two rebinding mechanisms apart:
+--
+--   * `keybindOverrides` is keyed by a SHIPPED chord. A custom bind has no
+--     shipped chord -- it is rebound by rewriting its own entry -- so putting
+--     one through `bind` would let an override for some shipped key silently
+--     move a custom one that happened to share a chord.
+--   * last means a custom chord that collides with a shipped one loses, which
+--     is checked explicitly below rather than left to Hyprland's ordering.
+--
+-- Settings prevents a collision upstream; this is the second lock, because the
+-- file is hand-editable and losing a shipped key to a typo is not acceptable.
+category("Custom")
+
+local function custom_bind(chord, dispatcher, label)
+    categories[chord] = current_category
+    return hl.bind(chord, dispatcher, { description = label })
+end
+
+for _, entry in ipairs(prefs.get("customBinds", {})) do
+    if type(entry) == "table" then
+        local chord = entry.chord
+        local label = entry.label
+
+        -- A description is not decoration: keybinds-contract fails a build
+        -- with a description-less bind, and the cheatsheet and Shortcuts page
+        -- both list what they find. A nameless shortcut is unfindable.
+        if valid_chord(chord)
+            and type(label) == "string" and label ~= ""
+            and categories[chord] == nil
+        then
+            local dispatcher = actions.dispatcher(entry)
+            if dispatcher ~= nil then
+                custom_bind(chord, dispatcher, label)
+            end
+        end
+    end
+end
+
 write_categories()
 
 return true