feat(desktop): pair bluetooth devices

Quickshell has no BlueZ agent and no generic D-Bus module, so a pairing
that needs a passkey confirmed cannot be done from QML. bluetoothctl
registers its own agent, so pairing is the one shell-out; adapter state,
scanning, connecting and forgetting all stay native.

The timeout is the ceiling: a device bluetoothctl cannot auto-confirm
fails visibly rather than hanging the page.

3 files changed, 117 insertions, 0 deletions

diff --git a/desktop/modules/bluetooth/BluetoothModule.qml b/desktop/modules/bluetooth/BluetoothModule.qml
index 84ac9a4..80f80b9 100644
--- a/desktop/modules/bluetooth/BluetoothModule.qml
+++ b/desktop/modules/bluetooth/BluetoothModule.qml
@@ -25,6 +25,7 @@ Module {
     alwaysActive: true
 
     readonly property var adapter: Bluetooth.defaultAdapter
+    readonly property Pairing pairing: Pairing {}
     readonly property var devices: Bluetooth.devices ? Bluetooth.devices.values : []
     readonly property var connectedDevices: devices.filter(d => d.connected)
     readonly property var pairedDevices: devices.filter(d => d.paired && !d.connected)
@@ -44,6 +45,20 @@ Module {
 
     property Process notifyProc: Process {}
 
+    // Pairing runs through bluetoothctl; on success connect natively, on
+    // failure notify, since the drawer may have closed by then.
+    property Connections pairingConn: Connections {
+        target: mod.pairing
+        function onFinished(address, ok) {
+            if (!ok) {
+                mod.notify("Bluetooth", "Pairing failed: " + mod.pairing.error);
+                return;
+            }
+            const d = mod.devices.find(x => x.address === address);
+            if (d) d.connect();
+        }
+    }
+
     tileContent: Component { BluetoothTile { bt: mod } }
 
     page: Component {
diff --git a/desktop/modules/bluetooth/BluetoothPage.qml b/desktop/modules/bluetooth/BluetoothPage.qml
index c608d82..26cb0ef 100644
--- a/desktop/modules/bluetooth/BluetoothPage.qml
+++ b/desktop/modules/bluetooth/BluetoothPage.qml
@@ -124,4 +124,56 @@ Column {
             width: page.width
         }
     }
+
+    // --- Available (found while scanning, not yet paired) ---
+
+    Text {
+        width: page.width
+        visible: page.bt.availableDevices.length > 0
+        text: "Available"
+        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2; bold: true }
+        color: Theme.subtext
+    }
+
+    Repeater {
+        model: page.bt.availableDevices
+
+        Rectangle {
+            required property var modelData
+
+            width: page.width
+            implicitHeight: availText.implicitHeight + 16
+            radius: 8
+            color: Qt.alpha(Theme.surface, 0.35)
+
+            Text {
+                id: availText
+                anchors { left: parent.left; leftMargin: 10; verticalCenter: parent.verticalCenter }
+                width: parent.width - pairBtn.width - 28
+                elide: Text.ElideRight
+                text: page.bt.pairing.busy && page.bt.pairing.address === modelData.address
+                    ? "Pairing…"
+                    : (modelData.name || modelData.deviceName || modelData.address)
+                font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2 }
+                color: Theme.text
+            }
+
+            Button {
+                id: pairBtn
+                anchors { right: parent.right; rightMargin: 8; verticalCenter: parent.verticalCenter }
+                text: "Pair"
+                enabled: !page.bt.pairing.busy
+                onClicked: page.bt.pairing.pair(modelData.address)
+            }
+        }
+    }
+
+    Text {
+        width: page.width
+        visible: page.bt.pairing.error !== ""
+        wrapMode: Text.Wrap
+        text: page.bt.pairing.error
+        font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 }
+        color: Theme.red
+    }
 }
diff --git a/desktop/modules/bluetooth/Pairing.qml b/desktop/modules/bluetooth/Pairing.qml
new file mode 100644
index 0000000..83fc9c2
--- /dev/null
+++ b/desktop/modules/bluetooth/Pairing.qml
@@ -0,0 +1,50 @@
+// 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.Io
+import QtQuick
+
+// The one action that is not native. Quickshell ships no BlueZ agent and no
+// generic D-Bus module, so a device that needs a passkey or PIN confirmed
+// cannot be paired from QML. bluetoothctl registers its own agent and handles
+// the prompt, so pairing goes through it and everything else stays native.
+//
+// ponytail: one-shot bluetoothctl with a timeout, keyed on the exit code. If
+// a device needs input bluetoothctl cannot auto-confirm, pairing times out
+// and the error surfaces; upgrade to driving interactive bluetoothctl only
+// when a real device needs it.
+QtObject {
+    id: root
+
+    property string address: ""
+    property string error: ""
+    readonly property bool busy: proc.running
+
+    signal finished(string address, bool ok)
+
+    function pair(address) {
+        root.address = address;
+        root.error = "";
+        proc.command = ["bluetoothctl", "--timeout", "20", "pair", address];
+        proc.running = false;
+        proc.running = true;
+    }
+
+    property Process proc: Process {
+        stdout: StdioCollector { id: out }
+        stderr: StdioCollector { id: err }
+        onExited: code => {
+            const ok = code === 0;
+            if (!ok) root.error = (err.text.trim() || out.text.trim() || ("bluetoothctl exited " + code));
+            root.finished(root.address, ok);
+        }
+    }
+}