feat(window-switcher): the overlay skeleton, and a proven Escape

A fifth component, so the same keepalive window as the other four: a
config with no visible window exits without reporting anything, and this
overlay is hidden almost always.

Escape is handled on a focused Item inside the PanelWindow rather than on
the window, because key events reach a focused item and
Keys.onEscapePressed on a PanelWindow never fires. Proven before the grid
is built on top of it, since keyboard navigation depends on the same
grab.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SYg4wYHq5XNbiVmMeKRb1S

3 files changed, 109 insertions, 0 deletions

diff --git a/window-switcher/Switcher.qml b/window-switcher/Switcher.qml
new file mode 100644
index 0000000..762c190
--- /dev/null
+++ b/window-switcher/Switcher.qml
@@ -0,0 +1,82 @@
+// 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.Wayland
+import QtQuick
+
+Scope {
+    id: root
+
+    property bool open: false
+    readonly property var screenObj: Quickshell.screens.find(s => s.name === "DP-1") ?? null
+
+    function toggle() { root.open = !root.open; }
+    function close() { root.open = false; }
+
+    // A config with no visible window exits, reporting nothing. This 1x1
+    // click-through window is what holds the shell open while the overlay
+    // is hidden, which is almost always.
+    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 {
+            id: win
+            screen: root.screenObj
+            anchors { top: true; left: true; right: true; bottom: true }
+            color: "transparent"
+            exclusionMode: ExclusionMode.Ignore
+            WlrLayershell.layer: WlrLayer.Overlay
+            WlrLayershell.namespace: "window-switcher"
+            WlrLayershell.keyboardFocus: WlrKeyboardFocus.Exclusive
+
+            // Keys reach a focused item, not a window: Keys.onEscapePressed on
+            // the PanelWindow above never fires. This item is what listens.
+            Item {
+                anchors.fill: parent
+                focus: true
+
+                Keys.onEscapePressed: {
+                    console.log("SWITCHER escape");
+                    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
+                        text: "press Escape"
+                        color: Theme.text
+                        font.family: Theme.fontFamily
+                        font.pixelSize: 28
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/window-switcher/Theme.qml b/window-switcher/Theme.qml
new file mode 120000
index 0000000..3d2e40f
--- /dev/null
+++ b/window-switcher/Theme.qml
@@ -0,0 +1 @@
+../shared/Theme.qml
\ No newline at end of file
diff --git a/window-switcher/shell.qml b/window-switcher/shell.qml
new file mode 100644
index 0000000..1581f62
--- /dev/null
+++ b/window-switcher/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 {
+    Switcher { id: switcher }
+
+    // Bound to ALT + TAB in Hyprland:
+    // `qs -p <this dir> ipc call switcher toggle`
+    IpcHandler {
+        target: "switcher"
+        function toggle() { switcher.toggle(); }
+        function show() { switcher.open = true; }
+        function close() { switcher.close(); }
+    }
+}