feat(keybinds): live keybind reminder overlay

Modelled on window-switcher: a Scope with a 1x1 keepalive PanelWindow
plus a LazyLoader'd overlay, opened via IpcHandler (SUPER+k is bound
in a different repo). hyprctl binds -j is asked fresh on every opening
so the list matches whatever Hyprland has loaded, with Binds.group()
from task 1 turning it into the grid's {name, rows} groups.

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

4 files changed, 229 insertions, 0 deletions

diff --git a/keybinds/Keybinds.qml b/keybinds/Keybinds.qml
new file mode 100644
index 0000000..6e7ada9
--- /dev/null
+++ b/keybinds/Keybinds.qml
@@ -0,0 +1,164 @@
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import Quickshell
+import Quickshell.Io
+import Quickshell.Wayland
+import QtQuick
+import "Binds.js" as Binds
+
+Scope {
+    id: root
+
+    property bool open: false
+    property string monitor: "DP-1"
+    property var groups: []
+    // Non-empty while loading or after a failure; the grid shows only when
+    // this is empty, so a stale list from the last opening never shows.
+    property string status: "Loading..."
+
+    readonly property var screenObj:
+        Quickshell.screens.find(s => s.name === root.monitor) ?? Quickshell.screens[0]
+
+    function toggle() { root.open = !root.open; }
+    function close() { root.open = false; }
+
+    // Asked afresh on every opening, so the list is what Hyprland has loaded
+    // right now: an edit to keybindings.lua shows after `hyprctl reload`, and
+    // not before, which is when it becomes true.
+    onOpenChanged: if (open) {
+        root.status = "Loading...";
+        // A Process already running ignores running = true.
+        proc.running = false;
+        proc.running = true;
+    }
+
+    Process {
+        id: proc
+        command: ["hyprctl", "binds", "-j"]
+        stdout: StdioCollector {
+            onStreamFinished: {
+                try {
+                    root.groups = Binds.group(JSON.parse(text));
+                    root.status = "";
+                } catch (e) {
+                    root.status = "hyprctl binds -j gave nothing readable";
+                }
+            }
+        }
+    }
+
+    // A config with no visible window exits, reporting nothing. This 1x1
+    // click-through window holds the shell open while the overlay is hidden.
+    PanelWindow {
+        anchors { top: true; left: true }
+        implicitWidth: 1
+        implicitHeight: 1
+        color: "transparent"
+        exclusionMode: ExclusionMode.Ignore
+        mask: Region {}
+        WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
+    }
+
+    LazyLoader {
+        active: root.open
+
+        PanelWindow {
+            screen: root.screenObj
+            anchors { top: true; left: true; right: true; bottom: true }
+            color: "transparent"
+            exclusionMode: ExclusionMode.Ignore
+            WlrLayershell.layer: WlrLayer.Overlay
+            WlrLayershell.namespace: "quickshell-keybinds"
+            WlrLayershell.keyboardFocus: WlrKeyboardFocus.Exclusive
+
+            // Keys reach a focused item, not a window.
+            Item {
+                anchors.fill: parent
+                focus: true
+                Keys.onEscapePressed: root.close()
+
+                Rectangle {
+                    anchors.fill: parent
+                    color: Qt.rgba(Theme.base.r, Theme.base.g, Theme.base.b, 0.82)
+
+                    MouseArea {
+                        anchors.fill: parent
+                        onClicked: root.close()
+                    }
+
+                    Text {
+                        anchors.centerIn: parent
+                        visible: root.status !== ""
+                        text: root.status
+                        color: Theme.text
+                        font.family: Theme.fontFamily
+                        font.pixelSize: 22
+                    }
+
+                    Flow {
+                        anchors.centerIn: parent
+                        width: parent.width * 0.9
+                        spacing: 40
+                        visible: root.status === ""
+
+                        Repeater {
+                            model: root.groups
+
+                            Column {
+                                required property var modelData
+                                width: 440
+                                spacing: 4
+
+                                Text {
+                                    text: modelData.name
+                                    color: Theme.accent
+                                    font.family: Theme.fontFamily
+                                    font.pixelSize: 18
+                                    font.bold: true
+                                    bottomPadding: 6
+                                }
+
+                                Repeater {
+                                    model: modelData.rows
+
+                                    // Fixed widths summing to the column's:
+                                    // a Row sizes to its children.
+                                    Row {
+                                        required property var modelData
+                                        spacing: 12
+
+                                        Text {
+                                            width: 240
+                                            elide: Text.ElideLeft
+                                            text: modelData.keys
+                                            color: Theme.subtext
+                                            font.family: Theme.fontFamily
+                                            font.pixelSize: 14
+                                        }
+                                        Text {
+                                            width: 188
+                                            elide: Text.ElideRight
+                                            text: modelData.label
+                                            color: Theme.text
+                                            font.family: Theme.fontFamily
+                                            font.pixelSize: 14
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/keybinds/README.md b/keybinds/README.md
new file mode 100644
index 0000000..05d4277
--- /dev/null
+++ b/keybinds/README.md
@@ -0,0 +1,38 @@
+# keybinds
+
+Every Hyprland keybind with what it does, grouped, over a dimmed screen.
+SUPER+k opens it, Escape or a click closes it.
+
+The list is `hyprctl binds -j`, asked on every opening, so it is what Hyprland
+has loaded: binds generated in Lua loops included, and an edit to
+`keybindings.lua` shows once `hyprctl reload` makes it real, not before.
+There is no cache to go stale.
+
+`hyprctl` reports every Lua action as `__lua` with an opaque number, so the
+text comes from each bind's `description` option, written `Group: Label`:
+
+    hl.bind("SUPER + w", hl.dsp.exec_cmd(P.browser), { description = "Apps: Browser" })
+
+The part before `: ` is the heading. A bind with no description is listed
+last under "Undescribed", so a missing one shows instead of vanishing.
+
+## Running
+
+    qs -p ./keybinds
+    qs -p ./keybinds ipc call keybinds toggle
+
+## Blur
+
+Optional, in the Hyprland config:
+
+    hl.layer_rule({
+        name         = "blur-keybinds",
+        match        = { namespace = "^(quickshell-keybinds)$" },
+        blur         = true,
+        xray         = false,
+        ignore_alpha = 0.1,
+    })
+
+## Check
+
+    node keybinds/test_binds.js
diff --git a/keybinds/Theme.qml b/keybinds/Theme.qml
new file mode 120000
index 0000000..3d2e40f
--- /dev/null
+++ b/keybinds/Theme.qml
@@ -0,0 +1 @@
+../shared/Theme.qml
\ No newline at end of file
diff --git a/keybinds/shell.qml b/keybinds/shell.qml
new file mode 100644
index 0000000..7c34bfd
--- /dev/null
+++ b/keybinds/shell.qml
@@ -0,0 +1,26 @@
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import Quickshell
+import Quickshell.Io
+
+ShellRoot {
+    Keybinds { id: keybinds }
+
+    // Bound to SUPER + k in Hyprland:
+    // `qs -p <this dir> ipc call keybinds toggle`
+    IpcHandler {
+        target: "keybinds"
+        function toggle() { keybinds.toggle(); }
+        function show() { keybinds.open = true; }
+        function close() { keybinds.close(); }
+    }
+}