From 8079f68fef0a0aa007f99625295cd330947ec1e1 Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Thu, 15 Oct 2026 12:48:16 +0200
Subject: feat(desktop): the mouse back button steps out of the drawer

The side button (BTN_SIDE, Qt.BackButton) does what Escape does: closes
the history, then leaves a page for the tiles, then closes the drawer.
Both go through one back(). The first attempt let the press fall through
to the full-surface click catcher under the panel, since nothing above
it accepts that button; it never arrived while a page was open. A
MouseArea on top with z: 1, taking only the back button, works, and
left clicks still pass through it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md          |  5 +++++
 desktop/Drawer.qml | 25 ++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9b809ea..48f7970 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -138,6 +138,11 @@ changing that component. The ones that generalise:
   The pills lose the pointer, so the hide timer would close the island under
   the open menu. `display()` reports no close, so the island holds itself shown
   after it until the pointer returns (a ponytail ceiling in `Island.qml`).
+- **A mouse button nothing accepts does not reliably fall through to a
+  catcher underneath.** The drawer's back button (`BTN_SIDE`, `Qt.BackButton`)
+  never reached a full-surface `MouseArea` below the panel while a page was
+  open. A `MouseArea` on top with `z: 1` and `acceptedButtons: Qt.BackButton`
+  works, and left clicks still pass through it to the items below.
 - **A `WheelHandler` on an `Image` inside the island's status pill never
   fired**; `MouseArea { onWheel }` in the same place works, and `SoundPage`
   already used it. Prefer `MouseArea.onWheel`.
diff --git a/desktop/Drawer.qml b/desktop/Drawer.qml
index 4285506..92c4fca 100644
--- a/desktop/Drawer.qml
+++ b/desktop/Drawer.qml
@@ -68,6 +68,14 @@ Scope {
         root.open = true;
     }
 
+    // One step out: history, then a page, then the drawer itself. Escape
+    // and the mouse's back button.
+    function back() {
+        if (root.history) root.history = false;
+        else if (root.page) root.page = "";
+        else root.close();
+    }
+
     function close() {
         root.open = false;
         // Reset to the grid: a panel that reopens somewhere unexpected is
@@ -114,6 +122,17 @@ Scope {
                 onClicked: root.close()
             }
 
+            // The mouse's back button, anywhere on the surface. On top of
+            // everything and taking only that button, so left clicks pass
+            // through it: a back press left to fall through from below never
+            // arrived, because something on the page took it first.
+            MouseArea {
+                anchors.fill: parent
+                z: 1
+                acceptedButtons: Qt.BackButton
+                onClicked: root.back()
+            }
+
             // Keys reach a focused item, never the window: setting
             // keyboardFocus above is necessary but not sufficient, and
             // Keys.onEscapePressed on a PanelWindow never fires. See AGENTS.md.
@@ -131,11 +150,7 @@ Scope {
                 // content, a key pressed in any focused descendant bubbles up
                 // to it.
                 focus: true
-                Keys.onEscapePressed: {
-                    if (root.history) root.history = false;
-                    else if (root.page) root.page = "";
-                    else root.close();
-                }
+                Keys.onEscapePressed: root.back()
 
                 // Clicks on the panel must not reach the catcher behind it.
                 MouseArea { anchors.fill: parent }
-- 
cgit v1.2.3