Make credential setup keyboard-safe and verifiable

Registers the components and schema key the codex agent needs for the
Sound page and per-application notification rules, so its branches
compile against a manifest that already holds them rather than each
carrying a conflicting edit to the same file.

An absent notification rule is permissive rather than denying: a newly
installed application must be able to notify without an entry being
written for it first.

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

config/dot/quickshell/config/PreferenceSchema.qml

@@ -521,6 +521,21 @@ Singleton {
             detail: "Resolution, scale, and rotation per connected display"
         },
 
+        // ── Per-application notification rules ──────────────────────────────
+        // { "<appId>": { enabled, showOnLockScreen, showContentOnLockScreen } }
+        //
+        // Absent means "no rule", which is not the same as a rule that allows
+        // everything: a new application must be able to notify without needing
+        // an entry written for it first. services/Notifs.qml treats a missing
+        // entry as permissive and Do Not Disturb remains an override on top,
+        // rather than being duplicated per application.
+        {
+            key: "notificationAppRules", type: "json", def: ({}), group: "notifications",
+            internal: true,
+            label: "Application notification rules",
+            detail: "Per-application notification and lock-screen visibility preferences"
+        },
+
         // ── Internal ────────────────────────────────────────────────────────
         {
             key: "lastPage", type: "string", def: "home", group: "internal",

config/dot/quickshell/connectivity-harness.qml

@@ -0,0 +1,28 @@
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+import qs.services
+
+ShellRoot {
+    IpcHandler {
+        target: "connectivity-test"
+
+        function status(): string {
+            return JSON.stringify({
+                wifiDevice: Connectivity.wifiDevice ? Connectivity.wifiDevice.name : "",
+                wiredDevice: Connectivity.wiredDevice ? Connectivity.wiredDevice.name : "",
+                wiredConnected: !!(Connectivity.wiredDevice && Connectivity.wiredDevice.connected),
+                networks: Connectivity.networks.length,
+                activeSsid: Connectivity.activeNetwork ? Connectivity.activeNetwork.name : "",
+                activeStrength: Connectivity.activeNetwork ? Connectivity.activeNetwork.signalStrength : -1,
+                activeLabel: Connectivity.activeNetwork ? Connectivity.signalLabel(Connectivity.activeNetwork.signalStrength) : "",
+                adapter: Connectivity.adapter ? true : false,
+                btDevices: Connectivity.bluetoothDevices.length
+            });
+        }
+
+        function labelFor(strength: real): string { return Connectivity.signalLabel(strength); }
+        function setActive(on: bool): void { Connectivity.active = on; }
+    }
+}

config/dot/quickshell/modules/quicksettings/AudioDeviceList.qml

@@ -6,6 +6,7 @@ import QtQuick
 import Quickshell
 import Quickshell.Services.Pipewire
 import qs.config
+import qs.services
 
 Item {
     id: root
@@ -16,23 +17,12 @@ Item {
 
     implicitHeight: list.implicitHeight
 
-    readonly property var nodes: {
-        return Pipewire.nodes.values.filter(n => {
-            if (n.isStream)
-                return false;
-            // Sources have to be filtered on the type flags: !isSink also
-            // matches video nodes (webcams show up here otherwise).
-            return root.output ? n.isSink : (n.type & PwNodeType.AudioSource) === PwNodeType.AudioSource;
-        });
-    }
+    readonly property var nodes: root.output ? AudioDevices.outputs : AudioDevices.inputs
 
-    readonly property var current: root.output ? Pipewire.defaultAudioSink : Pipewire.defaultAudioSource
+    readonly property var current: AudioDevices.current(root.output)
 
     function select(node): void {
-        if (root.output)
-            Pipewire.preferredDefaultAudioSink = node;
-        else
-            Pipewire.preferredDefaultAudioSource = node;
+        AudioDevices.select(root.output, node)
     }
 
     ScrollColumn {
@@ -52,7 +42,7 @@ Item {
                 implicitHeight: 38
                 icon: root.output ? "audio-speakers-symbolic" : "audio-input-microphone-symbolic"
                 iconFallback: "audio-card-symbolic"
-                label: nodeRow.modelData.description || nodeRow.modelData.nickname || nodeRow.modelData.name
+                label: AudioDevices.label(nodeRow.modelData)
                 selected: nodeRow.modelData === root.current
                 onClicked: root.select(nodeRow.modelData)
             }

config/dot/quickshell/modules/settings/AudioBalance.qml

@@ -0,0 +1,72 @@
+import QtQuick
+import Quickshell
+import Quickshell.Services.Pipewire
+import qs.config
+import qs.widgets
+
+SettingRow {
+    id: root
+
+    property var node: null
+
+    label: "Balance"
+    detail: "Adjust the left and right channels"
+    controlWidth: 270
+    visible: root.available
+    divider: false
+
+    PwObjectTracker {
+        objects: root.node ? [root.node] : []
+    }
+
+    function channelIndex(channel): int {
+        if (!root.node?.audio)
+            return -1;
+        const channels = root.node.audio.channels;
+        for (let index = 0; index < channels.length; index++) {
+            if (channels[index] === channel)
+                return index;
+        }
+        return -1;
+    }
+
+    readonly property int leftIndex: root.channelIndex(PwAudioChannel.FrontLeft)
+    readonly property int rightIndex: root.channelIndex(PwAudioChannel.FrontRight)
+    readonly property bool available: root.node?.audio
+        && root.leftIndex >= 0 && root.rightIndex >= 0
+        && root.node.audio.volumes.length > Math.max(root.leftIndex, root.rightIndex)
+
+    readonly property real position: {
+        if (!root.available)
+            return 0.5;
+        const left = root.node.audio.volumes[root.leftIndex];
+        const right = root.node.audio.volumes[root.rightIndex];
+        const level = Math.max(left, right);
+        if (level <= 0.001)
+            return 0.5;
+        return right >= left ? 0.5 + (1 - left / level) * 0.5
+                             : 0.5 - (1 - right / level) * 0.5;
+    }
+
+    function setBalance(value: real): void {
+        if (!root.available)
+            return;
+        const next = Array.from(root.node.audio.volumes);
+        const level = Math.max(next[root.leftIndex], next[root.rightIndex], 0.001);
+        if (value < 0.5) {
+            next[root.leftIndex] = level;
+            next[root.rightIndex] = level * value * 2;
+        } else {
+            next[root.leftIndex] = level * (1 - value) * 2;
+            next[root.rightIndex] = level;
+        }
+        root.node.audio.volumes = next;
+    }
+
+    ValueSlider {
+        anchors.fill: parent
+        value: root.position
+        icon: "audio-speakers-symbolic"
+        onMoved: value => root.setBalance(value)
+    }
+}

config/dot/quickshell/modules/settings/BluetoothPanel.qml

@@ -0,0 +1,95 @@
+// Bluetooth, at page size.
+//
+// Paired devices first, because reconnecting to something you already own is
+// what you are here for nine times out of ten; discovered devices follow.
+// Battery is shown where BlueZ reports it, which is the one thing people
+// routinely open a terminal for.
+
+import QtQuick
+import Quickshell
+import Quickshell.Bluetooth
+import qs.config
+import qs.services
+
+Column {
+    id: root
+
+    spacing: 0
+
+    function primaryAction(device: var): void {
+        if (device.connected) {
+            device.disconnect();
+            return;
+        }
+        if (device.paired) {
+            device.connect();
+            return;
+        }
+        device.pair();
+    }
+
+    function stateLabel(device: var): string {
+        if (device.pairing)
+            return "Pairing…";
+        if (device.connected)
+            return device.batteryAvailable
+                ? `Connected · ${Math.round(device.battery * 100)}% battery`
+                : "Connected";
+        if (device.paired)
+            return "Paired";
+        return device.address || "Not paired";
+    }
+
+    Repeater {
+        model: Connectivity.bluetoothDevices
+
+        SettingRow {
+            id: entry
+
+            required property var modelData
+            required property int index
+
+            width: parent.width
+            label: entry.modelData.name || entry.modelData.address || "Unknown device"
+            detail: root.stateLabel(entry.modelData)
+            divider: entry.index < Connectivity.bluetoothDevices.length - 1
+            controlWidth: 200
+            activatable: !entry.modelData.pairing
+            onActivated: root.primaryAction(entry.modelData)
+
+            Row {
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                spacing: 7
+
+                SettingsButton {
+                    anchors.verticalCenter: parent.verticalCenter
+                    enabled: !entry.modelData.pairing
+                    text: entry.modelData.connected
+                        ? "Disconnect"
+                        : (entry.modelData.paired ? "Connect" : "Pair")
+                    onClicked: root.primaryAction(entry.modelData)
+                }
+
+                SettingsButton {
+                    anchors.verticalCenter: parent.verticalCenter
+                    visible: entry.modelData.paired
+                    text: "Forget"
+                    onClicked: entry.modelData.forget()
+                }
+            }
+        }
+    }
+
+    SettingRow {
+        width: parent.width
+        visible: Connectivity.bluetoothDevices.length === 0
+        label: !Connectivity.adapter
+            ? "No Bluetooth adapter"
+            : (Connectivity.adapter.enabled ? "Looking for devices…" : "Bluetooth is off")
+        detail: Connectivity.adapter && !Connectivity.adapter.enabled
+            ? "Turn it on above to discover devices"
+            : "Put the device into pairing mode to make it appear"
+        divider: false
+    }
+}

config/dot/quickshell/modules/settings/ConnectivityPage.qml

@@ -1,92 +1,124 @@
+// Network & Devices.
+//
+// Wi-Fi and Bluetooth are handled here rather than delegated. Everything goes
+// through Quickshell.Networking and Quickshell.Bluetooth -- NetworkManager and
+// BlueZ over DBus -- and nothing shells out to nmcli or bluetoothctl. That was
+// the founding requirement for this desktop: never having to drop to a terminal
+// to join a network.
+//
+// Scanning follows this page being on screen. Wi-Fi scanning and especially
+// Bluetooth discovery hold the radio, and doing either for a list nobody is
+// looking at is battery and airtime spent on nothing.
+
 import QtQuick
+import Quickshell
 import Quickshell.Networking
-import Quickshell.Bluetooth
 import qs.config
 import qs.services
-import qs.modules.quicksettings
 
 SettingsPage {
     id: root
 
     title: "Network & Devices"
-    lede: "Connect graphically—no terminal workflow required."
+    lede: Connectivity.activeNetwork
+        ? "Connected to " + Connectivity.activeNetwork.name
+        : "Wi-Fi, Bluetooth, and the things Fedora owns."
 
-    readonly property var wifiDevice: {
-        for (const device of Networking.devices.values) {
-            if (device.type === DeviceType.Wifi)
-                return device;
-        }
-        return null;
-    }
-    readonly property var bluetoothAdapter: Bluetooth.defaultAdapter
+    // Drive the scanners only while this page is the one being shown.
+    Component.onCompleted: Connectivity.active = true
+    Component.onDestruction: Connectivity.active = false
 
     SettingsCard {
-        title: "Wi‑Fi"
-        subtitle: Networking.wifiEnabled ? "Available networks" : "Wireless networking is off"
+        title: "Wired"
+        visible: Connectivity.wiredDevice !== null
+
+        TextRow {
+            label: "Ethernet"
+            detail: Connectivity.wiredDevice ? Connectivity.wiredDevice.name : ""
+            value: Connectivity.wiredDevice && Connectivity.wiredDevice.connected ? "Connected" : "Not connected"
+            divider: false
+        }
+    }
+
+    SettingsCard {
+        title: "Wi-Fi"
+        // A Wi-Fi switch reading "On" above the words "No Wi-Fi adapter" is a
+        // contradiction; with no radio the card simply does not belong.
+        visible: Connectivity.wifiDevice !== null
+        subtitle: "Networks are re-scanned while this page is open."
 
         SettingRow {
-            label: "Wi‑Fi"
-            detail: root.wifiDevice ? "Managed by NetworkManager" : "No wireless adapter found"
+            label: "Wi-Fi"
+            detail: Connectivity.wifiEnabled ? "On" : "Off"
             controlWidth: 48
+            divider: Connectivity.wifiEnabled
 
             SettingsToggle {
                 anchors.right: parent.right
                 anchors.verticalCenter: parent.verticalCenter
-                checked: Networking.wifiEnabled
-                enabled: Networking.wifiHardwareEnabled
+                checked: Connectivity.wifiEnabled
+                enabled: Connectivity.wifiAvailable
                 onToggled: value => Networking.wifiEnabled = value
             }
         }
 
-        WifiList {
+        WifiPanel {
             width: parent.width
-            device: root.wifiDevice
-            active: true
-            maxHeight: 240
-        }
-
-        ActionRow {
-            label: "Advanced network settings"
-            detail: "VPN, wired profiles, DNS, and connection details"
-            divider: false
-            action: "Open panel"
-            onTriggered: SystemSettings.openGnomePanel("network")
+            visible: Connectivity.wifiEnabled
         }
     }
 
     SettingsCard {
         title: "Bluetooth"
-        subtitle: root.bluetoothAdapter?.enabled ? "Nearby and paired devices" : "Bluetooth is off"
+        visible: Connectivity.adapter !== null
+        subtitle: "Discovery runs while this page is open."
 
         SettingRow {
             label: "Bluetooth"
-            detail: root.bluetoothAdapter ? "Pair and reconnect without leaving Settings" : "No Bluetooth adapter found"
+            detail: Connectivity.adapter
+                ? (Connectivity.adapter.enabled ? "On" : "Off")
+                : "Unavailable"
             controlWidth: 48
+            divider: !!(Connectivity.adapter && Connectivity.adapter.enabled)
 
             SettingsToggle {
                 anchors.right: parent.right
                 anchors.verticalCenter: parent.verticalCenter
-                checked: root.bluetoothAdapter?.enabled ?? false
-                enabled: root.bluetoothAdapter !== null
+                checked: !!(Connectivity.adapter && Connectivity.adapter.enabled)
+                enabled: Connectivity.adapter !== null
                 onToggled: value => {
-                    if (root.bluetoothAdapter)
-                        root.bluetoothAdapter.enabled = value;
+                    if (Connectivity.adapter)
+                        Connectivity.adapter.enabled = value;
                 }
             }
         }
 
-        BluetoothList {
+        BluetoothPanel {
             width: parent.width
-            active: true
-            maxHeight: 220
+            visible: !!(Connectivity.adapter && Connectivity.adapter.enabled)
         }
+    }
+
+    SettingsCard {
+        title: "Owned by Fedora"
+        subtitle: "VPNs, per-connection routing, printers, and online accounts are configured by GNOME's panels, which are installed and searchable."
 
         ActionRow {
-            label: "Advanced Bluetooth settings"
-            detail: "Device details and system-level options"
+            label: "Network connections"
+            detail: "VPN, proxies, and per-connection settings"
+            action: "Open"
+            onTriggered: SystemSettings.openGnomePanel("network")
+        }
+        ActionRow {
+            label: "Printers"
+            action: "Open"
+            onTriggered: SystemSettings.openGnomePanel("printers")
+        }
+        ActionRow {
+            label: "Online accounts"
+            action: "Open"
             divider: false
-            action: "Open panel"
-            onTriggered: SystemSettings.openGnomePanel("bluetooth")
+            onTriggered: SystemSettings.openGnomePanel("online-accounts")
         }
     }
 }

config/dot/quickshell/modules/settings/HomeFavoriteCard.qml

@@ -9,93 +9,61 @@ Rectangle {
     required property string sourceName
     required property int index
     required property bool featured
+    required property bool canMoveEarlier
+    required property bool canMoveLater
 
     signal aliasCommitted(string id, string alias)
     signal removeRequested(string id)
     signal moveRequested(string id, int targetIndex)
 
-    readonly property bool dragging: dragHandler.active
-
     implicitHeight: 108
     radius: Theme.cardRadius
-    color: root.dragging
-        ? Theme.mix(Theme.bgDark, Theme.accent, 0.09)
-        : Theme.alpha(Theme.bgDark, 0.7)
-    border.width: root.dragging ? 2 : 1
-    border.color: root.dragging
-        ? Theme.alpha(Theme.accent, 0.82)
-        : Theme.alpha(Theme.fg, 0.07)
-    z: root.dragging ? 10 : 0
-
-    transform: Translate {
-        x: root.dragging ? dragHandler.translation.x : 0
-        y: root.dragging ? dragHandler.translation.y : 0
-    }
+    color: Theme.alpha(Theme.bgDark, 0.7)
+    border.width: 1
+    border.color: Theme.alpha(Theme.fg, 0.07)
 
     PrismEdge {
         anchors.top: parent.top
         anchors.left: parent.left
         anchors.right: parent.right
         inset: root.radius
-        opacity: root.dragging ? 0.82 : 0.2
+        opacity: 0.2
     }
 
-    Rectangle {
-        id: dragHandle
+    Column {
+        id: reorderControls
         anchors.left: parent.left
-        anchors.leftMargin: 11
+        anchors.leftMargin: 8
         anchors.verticalCenter: parent.verticalCenter
         width: 30
-        height: 42
-        radius: 9
-        activeFocusOnTab: true
-        color: root.dragging || activeFocus
-            ? Theme.alpha(Theme.accent, 0.14)
-            : (handleMouse.containsMouse ? Theme.alpha(Theme.fg, 0.09) : Theme.alpha(Theme.fg, 0.045))
-        border.width: activeFocus ? 2 : 1
-        border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.06)
+        spacing: 4
 
-        Text {
-            anchors.centerIn: parent
-            text: "⠿"
-            color: root.dragging ? Theme.accent : Theme.fgDim
-            font.family: Theme.fontFamily
-            font.pixelSize: 16
+        SettingsButton {
+            width: 30
+            height: 29
+            text: "↑"
+            enabled: root.canMoveEarlier
+            activeFocusOnTab: enabled
+            onClicked: root.moveRequested(root.favorite.id, root.index - 1)
+            Keys.onReturnPressed: if (enabled) root.moveRequested(root.favorite.id, root.index - 1)
+            Keys.onSpacePressed: if (enabled) root.moveRequested(root.favorite.id, root.index - 1)
         }
 
-        MouseArea {
-            id: handleMouse
-            anchors.fill: parent
-            hoverEnabled: true
-            acceptedButtons: Qt.NoButton
-            cursorShape: Qt.SizeAllCursor
-        }
-
-        DragHandler {
-            id: dragHandler
-            target: null
-            onActiveChanged: {
-                if (!active)
-                    root.commitDrag();
-            }
-        }
-
-        Keys.onPressed: event => {
-            if (event.key === Qt.Key_Left || event.key === Qt.Key_Up) {
-                root.moveRequested(root.favorite.id, Math.max(0, root.index - 1));
-                event.accepted = true;
-            } else if (event.key === Qt.Key_Right || event.key === Qt.Key_Down) {
-                const grid = root.GridView.view;
-                const lastIndex = grid ? grid.count - 1 : root.index;
-                root.moveRequested(root.favorite.id, Math.min(lastIndex, root.index + 1));
-                event.accepted = true;
-            }
+        SettingsButton {
+            width: 30
+            height: 29
+            text: "↓"
+            enabled: root.canMoveLater
+            activeFocusOnTab: enabled
+            onClicked: root.moveRequested(root.favorite.id, root.index + 1)
+            Keys.onReturnPressed: if (enabled) root.moveRequested(root.favorite.id, root.index + 1)
+            Keys.onSpacePressed: if (enabled) root.moveRequested(root.favorite.id, root.index + 1)
         }
     }
 
     Rectangle {
         id: aliasFrame
-        anchors.left: dragHandle.right
+        anchors.left: reorderControls.right
         anchors.leftMargin: 10
         anchors.right: removeButton.left
         anchors.rightMargin: 12
@@ -188,16 +156,4 @@ Rectangle {
         Keys.onReturnPressed: root.removeRequested(root.favorite.id)
         Keys.onSpacePressed: root.removeRequested(root.favorite.id)
     }
-
-    function commitDrag(): void {
-        const grid = root.GridView.view;
-        if (!grid || grid.count <= 0)
-            return;
-        const centerX = root.x + dragHandler.translation.x + root.width / 2;
-        const centerY = root.y + dragHandler.translation.y + root.height / 2;
-        const modelCount = grid.count;
-        const column = Math.max(0, Math.min(1, Math.floor(centerX / grid.cellWidth)));
-        const row = Math.max(0, Math.floor(centerY / grid.cellHeight));
-        root.moveRequested(root.favorite.id, Math.min(modelCount - 1, row * 2 + column));
-    }
 }

config/dot/quickshell/modules/settings/HomePhonePage.qml

@@ -43,10 +43,200 @@ SettingsPage {
         return "Home Assistant is unavailable";
     }
 
+    function saveHomeAssistantConfig(): void {
+        HomeAssistantConfig.save(
+            homeUrlInput.text,
+            homeEntitiesInput.text,
+            homeTokenInput.text
+        );
+    }
+
+    Connections {
+        target: HomeAssistantConfig
+
+        function onConfigurationSaved(): void {
+            homeTokenInput.clear();
+            homeUrlInput.text = HomeAssistantConfig.url;
+            homeEntitiesInput.text = HomeAssistantConfig.entities.join(", ");
+        }
+    }
+
     SettingsCard {
         title: "Home Assistant"
         subtitle: root.homeStatus()
 
+        SettingRow {
+            label: "Connection"
+            detail: HomeAssistantConfig.tokenConfigured
+                ? "A long-lived access token is stored privately"
+                : "Paste a long-lived access token to connect"
+            value: HomeAssistantConfig.configured ? "Configured" : "Not configured"
+        }
+
+        SettingRow {
+            label: "Server URL"
+            detail: "The local or remote address of Home Assistant"
+            controlWidth: 330
+
+            Rectangle {
+                anchors.fill: parent
+                radius: Theme.pillRadius
+                color: Theme.alpha(Theme.fg, 0.07)
+                border.width: homeUrlInput.activeFocus ? 2 : 1
+                border.color: homeUrlInput.activeFocus
+                    ? Theme.alpha(Theme.accent, 0.55) : "transparent"
+
+                TextInput {
+                    id: homeUrlInput
+                    anchors.fill: parent
+                    anchors.leftMargin: 12
+                    anchors.rightMargin: 12
+                    activeFocusOnTab: true
+                    text: HomeAssistantConfig.url
+                    color: Theme.fg
+                    selectionColor: Theme.alpha(Theme.accent, 0.5)
+                    selectedTextColor: Theme.fg
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSize
+                    verticalAlignment: TextInput.AlignVCenter
+                    clip: true
+
+                    Text {
+                        anchors.fill: parent
+                        visible: homeUrlInput.text === ""
+                        text: "https://homeassistant.local:8123"
+                        color: Theme.fgMuted
+                        font: homeUrlInput.font
+                        verticalAlignment: Text.AlignVCenter
+                        elide: Text.ElideRight
+                    }
+                }
+            }
+        }
+
+        SettingRow {
+            label: "Access token"
+            detail: HomeAssistantConfig.tokenConfigured
+                ? "Stored · leave blank to keep it"
+                : "Create one in your Home Assistant profile"
+            controlWidth: 330
+
+            PasswordField {
+                id: homeTokenInput
+                anchors.fill: parent
+                placeholder: HomeAssistantConfig.tokenConfigured
+                    ? "Stored token" : "Long-lived access token"
+                onAccepted: root.saveHomeAssistantConfig()
+            }
+        }
+
+        Column {
+            width: parent.width
+            spacing: 7
+            topPadding: 10
+            bottomPadding: 12
+
+            Text {
+                width: parent.width
+                text: "Light entities"
+                color: Theme.fg
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSize
+                font.weight: Font.Medium
+            }
+
+            Text {
+                width: parent.width
+                text: "Comma-separated entity IDs. These define the discoverable light catalog."
+                color: Theme.fgDim
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                wrapMode: Text.WordWrap
+            }
+
+            Rectangle {
+                width: parent.width
+                height: 72
+                radius: 10
+                color: Theme.alpha(Theme.fg, 0.055)
+                border.width: homeEntitiesInput.activeFocus ? 2 : 1
+                border.color: homeEntitiesInput.activeFocus
+                    ? Theme.alpha(Theme.accent, 0.55) : Theme.alpha(Theme.fg, 0.06)
+
+                TextEdit {
+                    id: homeEntitiesInput
+                    anchors.fill: parent
+                    anchors.margins: 10
+                    activeFocusOnTab: true
+                    text: HomeAssistantConfig.entities.join(", ")
+                    color: Theme.fg
+                    selectionColor: Theme.alpha(Theme.accent, 0.5)
+                    selectedTextColor: Theme.fg
+                    font.family: Theme.fontMono
+                    font.pixelSize: Theme.fontSizeSmall
+                    wrapMode: TextEdit.Wrap
+                    clip: true
+
+                    Text {
+                        anchors.fill: parent
+                        visible: homeEntitiesInput.text === ""
+                        text: "light.living_room, light.kitchen"
+                        color: Theme.fgMuted
+                        font: homeEntitiesInput.font
+                        wrapMode: Text.WordWrap
+                    }
+                }
+            }
+        }
+
+        Text {
+            width: parent.width
+            visible: HomeAssistantConfig.lastError !== ""
+            text: HomeAssistantConfig.lastError
+            color: Theme.danger
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+            wrapMode: Text.WordWrap
+            bottomPadding: 9
+        }
+
+        SettingRow {
+            label: "Private configuration"
+            detail: "Saved with owner-only permissions in Panama's private environment file"
+            controlWidth: 216
+
+            Row {
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                spacing: 8
+
+                SettingsButton {
+                    id: clearTokenButton
+                    text: "Clear token"
+                    enabled: HomeAssistantConfig.tokenConfigured && !HomeAssistantConfig.busy
+                    activeFocusOnTab: enabled
+                    border.width: activeFocus ? 2 : 1
+                    border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                    onClicked: HomeAssistantConfig.clearToken()
+                    Keys.onReturnPressed: if (enabled) HomeAssistantConfig.clearToken()
+                    Keys.onSpacePressed: if (enabled) HomeAssistantConfig.clearToken()
+                }
+
+                SettingsButton {
+                    id: saveHomeConfigButton
+                    text: HomeAssistantConfig.busy ? "Saving…" : "Save"
+                    tone: "accent"
+                    enabled: !HomeAssistantConfig.busy
+                    activeFocusOnTab: enabled
+                    border.width: activeFocus ? 2 : 0
+                    border.color: activeFocus ? Theme.fg : "transparent"
+                    onClicked: root.saveHomeAssistantConfig()
+                    Keys.onReturnPressed: if (enabled) root.saveHomeAssistantConfig()
+                    Keys.onSpacePressed: if (enabled) root.saveHomeAssistantConfig()
+                }
+            }
+        }
+
         SettingRow {
             label: "Light catalog"
             detail: "Panama reads light state through the Home Assistant helper."
@@ -122,6 +312,8 @@ SettingsPage {
                 })
                 sourceName: modelData.sourceName
                 featured: index < 4
+                canMoveEarlier: index > 0
+                canMoveLater: index < favoritesGrid.count - 1
                 onAliasCommitted: (id, alias) => HomePreferences.setAlias(id, alias)
                 onMoveRequested: (id, targetIndex) => HomePreferences.move(id, targetIndex)
                 onRemoveRequested: id => HomePreferences.remove(id)

config/dot/quickshell/modules/settings/NotificationsPage.qml

@@ -50,6 +50,70 @@ SettingsPage {
         SliderRow { setting: "maxVisibleToasts"; divider: false }
     }
 
+    SettingsCard {
+        title: "Application rules"
+        subtitle: "Apps appear here after they send a notification."
+
+        TextRow {
+            visible: Notifs.applications.length === 0
+            label: "No applications remembered yet"
+            detail: "Application controls will appear after the first notification arrives."
+            divider: false
+        }
+
+        Repeater {
+            model: Notifs.applications
+
+            Column {
+                required property var modelData
+
+                readonly property var app: modelData
+
+                width: parent.width
+
+                SettingRow {
+                    label: app.name
+                    detail: app.id
+                    controlWidth: 48
+
+                    SettingsToggle {
+                        anchors.right: parent.right
+                        anchors.verticalCenter: parent.verticalCenter
+                        checked: Notifs.appRule(app.id).enabled
+                        onToggled: value => Notifs.setAppRule(app.id, { enabled: value })
+                    }
+                }
+
+                SettingRow {
+                    label: "Show on lock screen"
+                    detail: "Allow this app's notifications on the lock screen"
+                    controlWidth: 48
+
+                    SettingsToggle {
+                        anchors.right: parent.right
+                        anchors.verticalCenter: parent.verticalCenter
+                        checked: Notifs.appRule(app.id).showOnLockScreen
+                        onToggled: value => Notifs.setAppRule(app.id, { showOnLockScreen: value })
+                    }
+                }
+
+                SettingRow {
+                    label: "Show content on lock screen"
+                    detail: "Show message details when this app is visible there"
+                    divider: false
+                    controlWidth: 48
+
+                    SettingsToggle {
+                        anchors.right: parent.right
+                        anchors.verticalCenter: parent.verticalCenter
+                        checked: Notifs.appRule(app.id).showContentOnLockScreen
+                        onToggled: value => Notifs.setAppRule(app.id, { showContentOnLockScreen: value })
+                    }
+                }
+            }
+        }
+    }
+
     SettingsCard {
         title: "Focus sessions"
         subtitle: "A focus session binds quiet mode and Caffeine to the current workspace."

config/dot/quickshell/modules/settings/PasswordField.qml

@@ -0,0 +1,106 @@
+// A password entry with a reveal toggle.
+//
+// Deliberately not the clipboard popover's SearchField with different text: a
+// Wi-Fi key typed into a field that echoes it is readable by anyone behind you,
+// and a search glyph in front of a password prompt is simply wrong. Masked by
+// default, revealable while held, because the reason people want to see it is
+// to check a character they just typed.
+
+import QtQuick
+import qs.config
+
+Rectangle {
+    id: root
+
+    property alias text: input.text
+    property string placeholder: "Password"
+    property bool revealed: false
+
+    signal accepted
+
+    implicitHeight: 32
+    radius: Theme.pillRadius
+    color: Theme.alpha(Theme.fg, 0.07)
+    // Not left at 0 so the focus ring has something to animate. See the note in
+    // modules/clipboard/SearchField.qml.
+    border.width: 1
+    border.color: input.activeFocus ? Theme.alpha(Theme.accent, 0.55) : "transparent"
+
+    Behavior on border.color {
+        ColorAnimation { duration: Theme.durFast }
+    }
+
+    function grab(): void {
+        input.forceActiveFocus();
+    }
+
+    function clear(): void {
+        input.text = "";
+        root.revealed = false;
+    }
+
+    TextInput {
+        id: input
+
+        anchors.left: parent.left
+        anchors.leftMargin: 13
+        anchors.right: revealButton.left
+        anchors.rightMargin: 8
+        anchors.verticalCenter: parent.verticalCenter
+
+        activeFocusOnTab: true
+        color: Theme.fg
+        selectionColor: Theme.alpha(Theme.accent, 0.5)
+        selectedTextColor: Theme.fg
+        font.family: Theme.fontFamily
+        font.pixelSize: Theme.fontSize
+        echoMode: root.revealed ? TextInput.Normal : TextInput.Password
+        passwordCharacter: "•"
+        clip: true
+
+        onAccepted: root.accepted()
+
+        Text {
+            anchors.fill: parent
+            verticalAlignment: Text.AlignVCenter
+            visible: input.text === ""
+            text: root.placeholder
+            color: Theme.fgMuted
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSize
+            elide: Text.ElideRight
+        }
+    }
+
+    Rectangle {
+        id: revealButton
+
+        anchors.right: parent.right
+        anchors.rightMargin: 5
+        anchors.verticalCenter: parent.verticalCenter
+        width: 26
+        height: 24
+        radius: 7
+        color: revealHover.hovered ? Theme.alpha(Theme.fg, 0.12) : "transparent"
+        border.width: 0
+        visible: input.text !== ""
+
+        Text {
+            anchors.centerIn: parent
+            // Nerd Font eye / eye-slash. fontMono is used for icon glyphs only.
+            text: root.revealed ? "\u{F070}" : "\u{F06E}"
+            font.family: Theme.fontMono
+            font.pixelSize: 12
+            color: root.revealed ? Theme.accent : Theme.fgMuted
+        }
+
+        HoverHandler {
+            id: revealHover
+            cursorShape: Qt.PointingHandCursor
+        }
+
+        TapHandler {
+            onTapped: root.revealed = !root.revealed
+        }
+    }
+}

config/dot/quickshell/modules/settings/SoundDeviceList.qml

@@ -0,0 +1,40 @@
+import QtQuick
+import Quickshell.Services.Pipewire
+import qs.config
+import qs.services
+
+Column {
+    id: root
+
+    property bool output: true
+    readonly property var nodes: AudioDevices.nodes(root.output)
+    readonly property var current: AudioDevices.current(root.output)
+
+    width: parent ? parent.width : 620
+    spacing: 8
+
+    Repeater {
+        model: root.nodes
+
+        SoundDeviceRow {
+            required property var modelData
+
+            width: root.width
+            node: modelData
+            output: root.output
+            selected: modelData === root.current
+        }
+    }
+
+    Text {
+        width: parent.width
+        visible: root.nodes.length === 0
+        text: Pipewire.ready ? "No audio devices found" : "Discovering audio devices…"
+        color: Theme.fgDim
+        font.family: Theme.fontFamily
+        font.pixelSize: Theme.fontSize
+        horizontalAlignment: Text.AlignHCenter
+        topPadding: 18
+        bottomPadding: 18
+    }
+}

config/dot/quickshell/modules/settings/SoundDeviceRow.qml

@@ -0,0 +1,168 @@
+import QtQuick
+import Quickshell
+import Quickshell.Services.Pipewire
+import qs.config
+import qs.widgets
+import qs.services
+import qs.modules.quicksettings
+
+Rectangle {
+    id: root
+
+    required property var node
+    property bool output: true
+    property bool selected: false
+
+    implicitHeight: root.output || !root.selected ? 88 : 105
+    radius: Theme.cardRadius
+    color: root.selected ? Theme.alpha(Theme.accent, 0.09) : Theme.alpha(Theme.fg, 0.025)
+    border.width: 1
+    border.color: root.selected ? Theme.alpha(Theme.accent, 0.34) : Theme.alpha(Theme.fg, 0.07)
+
+    PwObjectTracker {
+        objects: root.node ? [root.node] : []
+    }
+
+    PwNodePeakMonitor {
+        id: inputPeak
+        node: root.node
+        enabled: !root.output && root.selected
+    }
+
+    readonly property real volume: root.node?.audio?.volume ?? 0
+    readonly property bool muted: root.node?.audio?.muted ?? false
+
+    function iconName(): string {
+        if (!root.output)
+            return root.muted ? "microphone-sensitivity-muted-symbolic" : "audio-input-microphone-symbolic";
+        if (root.muted || root.volume <= 0.001)
+            return "audio-volume-muted-symbolic";
+        if (root.volume < 0.34)
+            return "audio-volume-low-symbolic";
+        if (root.volume < 0.67)
+            return "audio-volume-medium-symbolic";
+        return "audio-volume-high-symbolic";
+    }
+
+    Row {
+        id: heading
+        anchors.left: parent.left
+        anchors.right: parent.right
+        anchors.top: parent.top
+        anchors.leftMargin: 12
+        anchors.rightMargin: 10
+        anchors.topMargin: 8
+        height: 28
+        spacing: 10
+
+        ThemedIcon {
+            anchors.verticalCenter: parent.verticalCenter
+            size: 20
+            icon: root.output ? "audio-speakers-symbolic" : "audio-input-microphone-symbolic"
+            iconFallback: "audio-card-symbolic"
+            tint: root.selected ? Theme.accent : Theme.fg
+        }
+
+        Column {
+            width: Math.max(0, parent.width - 20 - useButton.width - parent.spacing * 2)
+            anchors.verticalCenter: parent.verticalCenter
+            spacing: 1
+
+            Text {
+                width: parent.width
+                text: AudioDevices.label(root.node)
+                color: Theme.fg
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSize
+                font.weight: root.selected ? Font.DemiBold : Font.Medium
+                elide: Text.ElideRight
+            }
+
+            Text {
+                width: parent.width
+                visible: root.node.nickname && root.node.nickname !== AudioDevices.label(root.node)
+                text: root.node.nickname ?? ""
+                color: Theme.fgDim
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                elide: Text.ElideRight
+            }
+        }
+
+        SettingsButton {
+            id: useButton
+            anchors.verticalCenter: parent.verticalCenter
+            width: root.selected ? 78 : 64
+            text: root.selected ? "Default" : "Use"
+            enabled: !root.selected
+            onClicked: AudioDevices.select(root.output, root.node)
+        }
+    }
+
+    IconButton {
+        id: muteButton
+        anchors.left: parent.left
+        anchors.leftMargin: 8
+        anchors.top: heading.bottom
+        anchors.topMargin: 7
+        size: 30
+        iconSize: 17
+        icon: root.iconName()
+        iconFallback: root.output ? "audio-volume-high-symbolic" : "audio-input-microphone-symbolic"
+        onClicked: {
+            if (root.node?.audio)
+                root.node.audio.muted = !root.node.audio.muted;
+        }
+    }
+
+    ValueSlider {
+        id: volumeSlider
+        anchors.left: muteButton.right
+        anchors.leftMargin: 7
+        anchors.right: volumeText.left
+        anchors.rightMargin: 10
+        anchors.verticalCenter: muteButton.verticalCenter
+        value: root.muted ? 0 : root.volume
+        onMoved: value => {
+            if (!root.node?.audio)
+                return;
+            root.node.audio.muted = false;
+            root.node.audio.volume = value;
+        }
+    }
+
+    Text {
+        id: volumeText
+        anchors.right: parent.right
+        anchors.rightMargin: 12
+        anchors.verticalCenter: muteButton.verticalCenter
+        width: 38
+        text: Math.round(root.volume * 100) + "%"
+        color: Theme.fgDim
+        font.family: Theme.fontMono
+        font.features: Theme.tabularFigures
+        font.pixelSize: Theme.fontSizeSmall
+        horizontalAlignment: Text.AlignRight
+    }
+
+    Rectangle {
+        anchors.left: volumeSlider.left
+        anchors.right: volumeText.right
+        anchors.top: muteButton.bottom
+        anchors.topMargin: 5
+        height: 5
+        radius: height / 2
+        visible: !root.output && root.selected
+        color: Theme.alpha(Theme.fg, 0.10)
+
+        Rectangle {
+            anchors.left: parent.left
+            anchors.top: parent.top
+            anchors.bottom: parent.bottom
+            width: parent.width * Math.max(0, Math.min(1, inputPeak.peak))
+            radius: parent.radius
+            color: inputPeak.peak > 0.88 ? Theme.danger : Theme.accentSecondary
+
+        }
+    }
+}

config/dot/quickshell/modules/settings/SoundPage.qml

@@ -1,8 +1,6 @@
 import QtQuick
-import Quickshell.Services.Pipewire
 import qs.config
 import qs.services
-import qs.modules.quicksettings
 
 SettingsPage {
     title: "Sound"
@@ -10,43 +8,58 @@ SettingsPage {
 
     SettingsCard {
         title: "Output"
-        subtitle: Pipewire.defaultAudioSink?.description ?? "No output device"
+        subtitle: AudioDevices.current(true)?.description ?? "No output device"
 
-        AudioSlider {
-            width: parent.width
-            node: Pipewire.defaultAudioSink
-            output: true
-        }
-        Rectangle {
-            width: parent.width
-            height: 1
-            color: Theme.alpha(Theme.fg, 0.06)
-        }
-        AudioDeviceList {
+        SoundDeviceList {
             width: parent.width
             output: true
-            maxHeight: 190
+        }
+
+        AudioBalance {
+            width: parent.width
+            node: AudioDevices.current(true)
         }
     }
 
     SettingsCard {
         title: "Input"
-        subtitle: Pipewire.defaultAudioSource?.description ?? "No input device"
+        subtitle: AudioDevices.current(false)?.description ?? "No input device"
 
-        AudioSlider {
-            width: parent.width
-            node: Pipewire.defaultAudioSource
-            output: false
-        }
-        Rectangle {
-            width: parent.width
-            height: 1
-            color: Theme.alpha(Theme.fg, 0.06)
-        }
-        AudioDeviceList {
+        SoundDeviceList {
             width: parent.width
             output: false
-            maxHeight: 160
+        }
+    }
+
+    SettingsCard {
+        title: "Sound feedback"
+        subtitle: "Use the same event preferences as GTK and GNOME applications."
+
+        SettingRow {
+            label: "Event sounds"
+            detail: "Play alerts and interface event sounds"
+            controlWidth: 42
+
+            SettingsToggle {
+                anchors.fill: parent
+                checked: SoundFeedback.eventSounds
+                enabled: !SoundFeedback.busy
+                onToggled: checked => SoundFeedback.setEventSounds(checked)
+            }
+        }
+
+        SettingRow {
+            label: "Input feedback"
+            detail: "Play sounds for supported typing and input events"
+            controlWidth: 42
+            divider: false
+
+            SettingsToggle {
+                anchors.fill: parent
+                checked: SoundFeedback.inputFeedback
+                enabled: !SoundFeedback.busy
+                onToggled: checked => SoundFeedback.setInputFeedback(checked)
+            }
         }
     }
 

config/dot/quickshell/modules/settings/WifiPanel.qml

@@ -0,0 +1,177 @@
+// Wi-Fi, at page size.
+//
+// The quick settings version is a popover: a compact list you glance at. This
+// is the one you sit in front of when a network is not behaving, so each row
+// carries what you would otherwise open a terminal to find out — signal,
+// security, and whether it is a network this machine already knows.
+//
+// Joining a secured network reveals an inline password field rather than
+// failing silently, which is the one interaction the popover already got right
+// and is worth keeping identical.
+
+import QtQuick
+import Quickshell
+import Quickshell.Networking
+import qs.config
+import qs.services
+import qs.widgets
+
+Column {
+    id: root
+
+    spacing: 0
+
+    // SSID whose password field is open, and the last failure.
+    property string passwordFor: ""
+    property string failedSsid: ""
+    property string failedText: ""
+
+    function activate(network: var): void {
+        root.failedSsid = "";
+        if (network.connected)
+            return;
+        if (network.known || !Connectivity.isSecured(network)) {
+            root.passwordFor = "";
+            network.connect();
+            return;
+        }
+        root.passwordFor = root.passwordFor === network.name ? "" : network.name;
+    }
+
+    Repeater {
+        model: Connectivity.networks
+
+        Column {
+            id: entry
+
+            required property var modelData
+            required property int index
+
+            width: parent.width
+
+            SettingRow {
+                width: parent.width
+
+                label: entry.modelData.name || "Hidden network"
+                detail: {
+                    const bits = [];
+                    if (entry.modelData.connected)
+                        bits.push("Connected");
+                    else if (entry.modelData.known)
+                        bits.push("Saved");
+                    bits.push(Connectivity.signalLabel(entry.modelData.signalStrength));
+                    bits.push(Connectivity.securityLabel(entry.modelData));
+                    return bits.join(" · ");
+                }
+                divider: entry.index < Connectivity.networks.length - 1 || root.passwordFor === entry.modelData.name
+                controlWidth: 190
+                activatable: !entry.modelData.connected
+                onActivated: root.activate(entry.modelData)
+
+                Row {
+                    anchors.right: parent.right
+                    anchors.verticalCenter: parent.verticalCenter
+                    spacing: 7
+
+                    Text {
+                        anchors.verticalCenter: parent.verticalCenter
+                        visible: entry.modelData.connected
+                        text: "Connected"
+                        color: Theme.accent
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSize
+                        font.weight: Font.DemiBold
+                    }
+
+                    SettingsButton {
+                        anchors.verticalCenter: parent.verticalCenter
+                        visible: entry.modelData.connected
+                        text: "Disconnect"
+                        onClicked: entry.modelData.disconnect()
+                    }
+
+                    SettingsButton {
+                        anchors.verticalCenter: parent.verticalCenter
+                        visible: !entry.modelData.connected
+                        text: entry.modelData.known ? "Connect" : "Join"
+                        onClicked: root.activate(entry.modelData)
+                    }
+                }
+            }
+
+            // The password field for this network, when it is the one being
+            // joined. Inline rather than a dialog: a dialog over a tiled window
+            // is a worse place to type than the row you just clicked.
+            Item {
+                width: parent.width
+                height: root.passwordFor === entry.modelData.name ? 54 : 0
+                visible: height > 0
+                clip: true
+
+                onVisibleChanged: {
+                    if (visible)
+                        password.grab();
+                    else
+                        password.clear();
+                }
+
+                PasswordField {
+                    id: password
+                    anchors.left: parent.left
+                    anchors.right: joinButton.left
+                    anchors.rightMargin: 8
+                    anchors.verticalCenter: parent.verticalCenter
+                    placeholder: "Password for " + (entry.modelData.name || "network")
+                    onAccepted: joinButton.join()
+                }
+
+                SettingsButton {
+                    id: joinButton
+                    anchors.right: parent.right
+                    anchors.verticalCenter: parent.verticalCenter
+                    text: "Join"
+
+                    function join(): void {
+                        entry.modelData.connect(password.text);
+                        root.passwordFor = "";
+                        password.text = "";
+                    }
+
+                    onClicked: joinButton.join()
+                }
+            }
+
+            Text {
+                width: parent.width
+                visible: root.failedSsid === entry.modelData.name
+                leftPadding: 2
+                bottomPadding: 8
+                text: root.failedText
+                color: Theme.warn
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+            }
+
+            Connections {
+                target: entry.modelData
+                function onConnectionFailed(reason): void {
+                    root.failedSsid = entry.modelData.name;
+                    root.failedText = Connectivity.connectionFailureText(reason);
+                    root.passwordFor = entry.modelData.name;
+                }
+            }
+        }
+    }
+
+    SettingRow {
+        width: parent.width
+        visible: Connectivity.networks.length === 0
+        label: !Connectivity.wifiDevice
+            ? "No Wi-Fi adapter"
+            : (Connectivity.wifiEnabled ? "Looking for networks…" : "Wi-Fi is off")
+        detail: Connectivity.wifiDevice && !Connectivity.wifiEnabled
+            ? "Turn it on above to see what is nearby"
+            : ""
+        divider: false
+    }
+}

config/dot/quickshell/modules/settings/qmldir

@@ -37,3 +37,9 @@ DockAppPicker 1.0 DockAppPicker.qml
 ShortcutCapture 1.0 ShortcutCapture.qml
 ChoiceGrid 1.0 ChoiceGrid.qml
 DisplayModePicker 1.0 DisplayModePicker.qml
+WifiPanel 1.0 WifiPanel.qml
+BluetoothPanel 1.0 BluetoothPanel.qml
+PasswordField 1.0 PasswordField.qml
+AudioBalance 1.0 AudioBalance.qml
+SoundDeviceList 1.0 SoundDeviceList.qml
+SoundDeviceRow 1.0 SoundDeviceRow.qml

config/dot/quickshell/scripts/panama-home-assistant

@@ -192,8 +192,17 @@ def resolve_config(
     env: Mapping[str, str] | None = None,
     legacy: Callable[[], Config] = load_legacy_config,
 ) -> Config:
-    private_env = read_panama_env()
-    private_env.update(dict(os.environ if env is None else env))
+    # An explicitly supplied environment is the WHOLE environment. Reading the
+    # user's private env file underneath it makes callers -- tests especially --
+    # depend on whatever happens to be in that file: adding a real
+    # PANAMA_HOME_ASSISTANT_ENTITIES to it silently overrode a fixture that was
+    # asserting the legacy fallback. Production passes env=None and still gets
+    # the file.
+    if env is None:
+        private_env = read_panama_env()
+        private_env.update(dict(os.environ))
+    else:
+        private_env = dict(env)
 
     url_value = private_env.get("PANAMA_HOME_ASSISTANT_URL", "").strip()
     token_value = private_env.get("PANAMA_HOME_ASSISTANT_TOKEN", "").strip()

config/dot/quickshell/scripts/panama-home-assistant-config

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+
+"""Read and atomically update Panama's private Home Assistant settings.
+
+Secret values are accepted only as a single JSON object on stdin and are never
+returned. The command line therefore remains safe to inspect with ps(1).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import pathlib
+import re
+import shlex
+import sys
+import tempfile
+import urllib.parse
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+KEY_URL = "PANAMA_HOME_ASSISTANT_URL"
+KEY_TOKEN = "PANAMA_HOME_ASSISTANT_TOKEN"
+KEY_ENTITIES = "PANAMA_HOME_ASSISTANT_ENTITIES"
+TARGET_KEYS = (KEY_URL, KEY_TOKEN, KEY_ENTITIES)
+ASSIGNMENT = re.compile(
+    r"^(?P<prefix>\s*(?:export\s+)?)(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*=(?P<value>.*)$"
+)
+ENTITY_ID = re.compile(r"^[a-z_]+\.[a-z0-9_]+$")
+DEFAULT_ENV = pathlib.Path(__file__).resolve().parents[3] / "bash/env"
+
+
+class ConfigError(RuntimeError):
+    """An error code safe to display without including submitted values."""
+
+
+def env_path() -> pathlib.Path:
+    override = os.environ.get("PANAMA_HOME_ASSISTANT_ENV_FILE", "")
+    return pathlib.Path(override) if override else DEFAULT_ENV
+
+
+def parse_assignment(raw: str) -> str | None:
+    try:
+        parsed = shlex.split(raw, comments=True, posix=True)
+    except ValueError:
+        return None
+    return parsed[0] if len(parsed) == 1 else None
+
+
+def read_values(path: pathlib.Path) -> dict[str, str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except FileNotFoundError:
+        return {}
+    except OSError as error:
+        raise ConfigError("read-failed") from error
+
+    values: dict[str, str] = {}
+    for line in lines:
+        match = ASSIGNMENT.match(line)
+        if not match or match.group("key") not in TARGET_KEYS:
+            continue
+        value = parse_assignment(match.group("value"))
+        if value is not None:
+            values[match.group("key")] = value
+    return values
+
+
+def normalize_url(value: Any) -> str:
+    if not isinstance(value, str):
+        raise ConfigError("invalid-url")
+    normalized = value.strip().rstrip("/")
+    if not normalized:
+        return ""
+    parsed = urllib.parse.urlsplit(normalized)
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+    ):
+        raise ConfigError("invalid-url")
+    return normalized
+
+
+def normalize_token(value: Any) -> str:
+    if not isinstance(value, str) or "\x00" in value or "\n" in value or "\r" in value:
+        raise ConfigError("invalid-token")
+    return value.strip()
+
+
+def normalize_entities(value: Any) -> tuple[str, ...]:
+    if isinstance(value, str):
+        candidates: Sequence[Any] = re.split(r"[,\n]", value)
+    elif isinstance(value, list):
+        candidates = value
+    else:
+        raise ConfigError("invalid-entities")
+
+    entities: list[str] = []
+    for candidate in candidates:
+        if not isinstance(candidate, str):
+            raise ConfigError("invalid-entities")
+        entity_id = candidate.strip()
+        if not entity_id:
+            continue
+        if not ENTITY_ID.fullmatch(entity_id):
+            raise ConfigError("invalid-entities")
+        if entity_id not in entities:
+            entities.append(entity_id)
+    return tuple(entities)
+
+
+def public_state(values: Mapping[str, str]) -> dict[str, object]:
+    try:
+        url = normalize_url(values.get(KEY_URL, ""))
+        entities = list(normalize_entities(values.get(KEY_ENTITIES, "")))
+        error = ""
+    except ConfigError as config_error:
+        url = ""
+        entities = []
+        error = str(config_error)
+    token_configured = bool(values.get(KEY_TOKEN, "").strip())
+    return {
+        "ok": error == "",
+        "configured": bool(url and token_configured),
+        "tokenConfigured": token_configured,
+        "url": url,
+        "entities": entities,
+        "error": error,
+    }
+
+
+def render_updated(original: str, updates: Mapping[str, str]) -> str:
+    lines = original.splitlines(keepends=True)
+    rendered: list[str] = []
+    replaced: set[str] = set()
+
+    for line in lines:
+        content = line.rstrip("\r\n")
+        ending = line[len(content) :]
+        match = ASSIGNMENT.match(content)
+        key = match.group("key") if match else ""
+        if key not in updates:
+            rendered.append(line)
+            continue
+        if key in replaced:
+            continue
+        rendered.append(f"export {key}={shlex.quote(updates[key])}{ending or os.linesep}")
+        replaced.add(key)
+
+    if rendered and not rendered[-1].endswith(("\n", "\r")):
+        rendered[-1] += os.linesep
+    for key in TARGET_KEYS:
+        if key in updates and key not in replaced:
+            rendered.append(f"export {key}={shlex.quote(updates[key])}{os.linesep}")
+    return "".join(rendered)
+
+
+def atomic_write(path: pathlib.Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=".env.", dir=path.parent)
+    temporary = pathlib.Path(temporary_name)
+    try:
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        os.chmod(path, 0o600)
+        directory_fd = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def read_payload() -> dict[str, Any]:
+    line = sys.stdin.buffer.readline(1_048_577)
+    if not line or len(line) > 1_048_576:
+        raise ConfigError("invalid-payload")
+    try:
+        payload = json.loads(line)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ConfigError("invalid-payload") from error
+    if not isinstance(payload, dict):
+        raise ConfigError("invalid-payload")
+    return payload
+
+
+def write_payload(path: pathlib.Path, payload: Mapping[str, Any]) -> dict[str, object]:
+    allowed = {"url", "token", "entities"}
+    if not set(payload).issubset(allowed) or not payload:
+        raise ConfigError("invalid-payload")
+
+    updates: dict[str, str] = {}
+    if "url" in payload:
+        updates[KEY_URL] = normalize_url(payload["url"])
+    if "token" in payload:
+        updates[KEY_TOKEN] = normalize_token(payload["token"])
+    if "entities" in payload:
+        updates[KEY_ENTITIES] = ",".join(normalize_entities(payload["entities"]))
+
+    lock_path = path.with_name("." + path.name + ".lock")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        os.fchmod(lock_fd, 0o600)
+        fcntl.flock(lock_fd, fcntl.LOCK_EX)
+        try:
+            original = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            original = ""
+        except OSError as error:
+            raise ConfigError("read-failed") from error
+        atomic_write(path, render_updated(original, updates))
+    finally:
+        os.close(lock_fd)
+
+    result = public_state(read_values(path))
+    result["ok"] = True
+    result["error"] = ""
+    return result
+
+
+def compact_json(value: Mapping[str, object]) -> str:
+    return json.dumps(value, separators=(",", ":"))
+
+
+def main() -> None:
+    command = sys.argv[1] if len(sys.argv) > 1 else "status"
+    if len(sys.argv) > 2 or command not in {"status", "write"}:
+        raise ConfigError("usage")
+    path = env_path()
+    result = public_state(read_values(path)) if command == "status" else write_payload(path, read_payload())
+    print(compact_json(result))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except ConfigError as error:
+        print(compact_json({"ok": False, "error": str(error)}))
+        raise SystemExit(1) from error
+    except OSError:
+        print(compact_json({"ok": False, "error": "write-failed"}))
+        raise SystemExit(1)

config/dot/quickshell/scripts/panama-settings-backup

@@ -572,6 +572,28 @@ def command_restore(arguments: list[str]) -> None:
         home_present = False
         home_data = None
 
+    # Display geometry is never restored from a snapshot. Applying it requires
+    # the visible confirmation/recovery flow in Displays.qml; a settings-file
+    # restore followed by `hyprctl reload` must not bypass that safety boundary.
+    # Preserve the currently confirmed generation when it is readable, and
+    # otherwise remove the snapshot's geometry so startup uses shipped policy.
+    try:
+        current_desktop = read_json(SETTINGS, "The current settings file") \
+            if is_present(SETTINGS) else {}
+    except BackupError:
+        current_desktop = {}
+
+    if isinstance(current_desktop, dict) and "displays" in current_desktop:
+        # Even a Home-only snapshot must retain the confirmed monitor layout.
+        # In that case the restored desktop file contains only the protected
+        # geometry; every ordinary desktop preference remains absent/default.
+        desktop_present = True
+        desktop_data = dict(desktop_data) if desktop_data is not None else {}
+        desktop_data["displays"] = current_desktop["displays"]
+    elif desktop_present and desktop_data is not None:
+        desktop_data = dict(desktop_data)
+        desktop_data.pop("displays", None)
+
     # Restoring remains undoable, but a corrupt current file must not prevent a
     # known-good snapshot from recovering the desktop.
     save_snapshot(require_any=False, validate=False)

config/dot/quickshell/services/AudioDevices.qml

@@ -0,0 +1,43 @@
+pragma Singleton
+
+// Shared PipeWire device discovery and default selection. Quick Settings and
+// Panama Settings intentionally use this same boundary so they cannot disagree
+// about what counts as an input or which node should become the default.
+
+import Quickshell
+import Quickshell.Services.Pipewire
+import QtQuick
+
+Singleton {
+    id: root
+
+    readonly property var outputs: Pipewire.nodes.values.filter(node =>
+        !node.isStream && node.isSink)
+
+    readonly property var inputs: Pipewire.nodes.values.filter(node =>
+        !node.isStream
+        && (node.type & PwNodeType.AudioSource) === PwNodeType.AudioSource)
+
+    function nodes(output: bool): var {
+        return output ? root.outputs : root.inputs;
+    }
+
+    function current(output: bool): var {
+        return output ? Pipewire.defaultAudioSink : Pipewire.defaultAudioSource;
+    }
+
+    function select(output: bool, node: var): void {
+        if (!node)
+            return;
+        if (output)
+            Pipewire.preferredDefaultAudioSink = node;
+        else
+            Pipewire.preferredDefaultAudioSource = node;
+    }
+
+    function label(node: var): string {
+        if (!node)
+            return "Unknown device";
+        return node.description || node.nickname || node.name || "Unknown device";
+    }
+}

config/dot/quickshell/services/Connectivity.qml

@@ -0,0 +1,144 @@
+pragma Singleton
+
+// Network and Bluetooth state for the settings page.
+//
+// The hard parts -- scanning, joining, pairing -- already work in the quick
+// settings panel through Quickshell.Networking and Quickshell.Bluetooth, which
+// speak to NetworkManager and BlueZ over DBus. Nothing here shells out to nmcli
+// or bluetoothctl, and nothing should: the founding requirement for this
+// desktop was never having to drop to a terminal to join a network.
+//
+// This exists so the page does not have to reach into those modules for the
+// same derived values the panel already computes, and so scanning is driven by
+// whether the page is actually on screen. Scanning while nobody is looking is
+// radio time and battery spent on a list that is not being read.
+
+import Quickshell
+import Quickshell.Networking
+import Quickshell.Bluetooth
+import QtQuick
+
+Singleton {
+    id: root
+
+    // Set by the page while it is visible; drives both scanners.
+    property bool active: false
+
+    readonly property var wifiDevice: {
+        for (const device of Networking.devices.values) {
+            if (device.type === DeviceType.Wifi)
+                return device;
+        }
+        return null;
+    }
+
+    readonly property var wiredDevice: {
+        for (const device of Networking.devices.values) {
+            if (device.type === DeviceType.Wired)
+                return device;
+        }
+        return null;
+    }
+
+    readonly property var adapter: Bluetooth.defaultAdapter
+
+    readonly property bool wifiEnabled: Networking.wifiEnabled
+    readonly property bool wifiAvailable: Networking.wifiHardwareEnabled
+
+    // Current network, then saved, then by signal -- the order GNOME uses,
+    // which is the order you actually look for things in.
+    readonly property var networks: {
+        if (!root.wifiDevice || !root.wifiDevice.networks)
+            return [];
+        const list = root.wifiDevice.networks.values.slice();
+        list.sort((a, b) => {
+            if (a.connected !== b.connected)
+                return a.connected ? -1 : 1;
+            if (a.known !== b.known)
+                return a.known ? -1 : 1;
+            return b.signalStrength - a.signalStrength;
+        });
+        return list;
+    }
+
+    readonly property var savedNetworks: root.networks.filter(network => network.known)
+
+    readonly property var bluetoothDevices: {
+        if (!Bluetooth.devices)
+            return [];
+        const list = Bluetooth.devices.values.slice();
+        list.sort((a, b) => {
+            if (a.connected !== b.connected)
+                return a.connected ? -1 : 1;
+            if (a.paired !== b.paired)
+                return a.paired ? -1 : 1;
+            return String(a.name || "").localeCompare(String(b.name || ""));
+        });
+        return list;
+    }
+
+    readonly property var activeNetwork: root.networks.find(network => network.connected) ?? null
+
+    function isSecured(network: var): bool {
+        return network.security !== WifiSecurityType.Open
+            && network.security !== WifiSecurityType.Owe
+            && network.security !== WifiSecurityType.Unknown;
+    }
+
+    function securityLabel(network: var): string {
+        if (!root.isSecured(network))
+            return "Open";
+        switch (network.security) {
+        case WifiSecurityType.Wep: return "WEP";
+        case WifiSecurityType.Wpa: return "WPA";
+        case WifiSecurityType.Wpa2: return "WPA2";
+        case WifiSecurityType.Wpa3: return "WPA3";
+        case WifiSecurityType.Enterprise: return "Enterprise";
+        }
+        return "Secured";
+    }
+
+    // Four bars is what people read signal as, so bucket rather than showing a
+    // percentage that changes every scan and means nothing to anyone.
+    //
+    // signalStrength is 0.0-1.0, NOT a percentage. Treating it as 0-100 puts
+    // every network including the connected one in the bottom bucket, which is
+    // exactly as useless as showing nothing. Thresholds match the icon buckets
+    // in modules/quicksettings/WifiList.qml so the two never disagree.
+    function signalLabel(strength: real): string {
+        if (strength >= 0.8) return "Excellent";
+        if (strength >= 0.55) return "Good";
+        if (strength >= 0.3) return "Fair";
+        if (strength > 0.05) return "Weak";
+        return "No signal";
+    }
+
+    function connectionFailureText(reason: var): string {
+        switch (reason) {
+        case ConnectionFailReason.WifiAuthTimeout:
+        case ConnectionFailReason.Authentication:
+            return "Wrong password";
+        case ConnectionFailReason.WifiNetworkLost:
+            return "Network out of range";
+        }
+        return "Could not connect";
+    }
+
+    // Scanning follows visibility. NetworkManager keeps scanning as long as it
+    // is asked to, and Bluetooth discovery is worse -- it holds the radio.
+    function syncScanners(): void {
+        if (root.wifiDevice)
+            root.wifiDevice.scannerEnabled = root.active && root.wifiEnabled;
+
+        if (root.adapter && root.adapter.enabled) {
+            const shouldDiscover = root.active;
+            if (root.adapter.discovering !== shouldDiscover)
+                root.adapter.discovering = shouldDiscover;
+        }
+    }
+
+    onActiveChanged: root.syncScanners()
+    onWifiDeviceChanged: root.syncScanners()
+    onWifiEnabledChanged: root.syncScanners()
+    onAdapterChanged: root.syncScanners()
+}

config/dot/quickshell/services/Displays.qml

@@ -41,6 +41,7 @@ Singleton {
     property bool revertVerificationActive: false
     property int operationGeneration: 0
     property int revertGeneration: -1
+    property bool externalChangeBlocked: false
     property int secondsLeft: 0
 
     readonly property bool awaitingConfirmation: root.pendingOutput !== ""
@@ -271,6 +272,10 @@ Singleton {
     // Applies immediately and starts the countdown. Nothing is stored yet: the
     // settings file is only written by confirm().
     function apply(output: string, mode: string, scale: real, transform: int): bool {
+        if (root.externalChangeBlocked) {
+            root.lastError = "Wait for Settings to finish restoring before changing a display.";
+            return false;
+        }
         if (root.busy) {
             root.lastError = "Wait for the current display operation to finish.";
             return false;

config/dot/quickshell/services/HomeAssistantConfig.qml

@@ -0,0 +1,120 @@
+pragma Singleton
+
+// Redacted Home Assistant configuration state. The helper is the only object
+// that touches the private env file; QML never receives the stored token.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+Singleton {
+    id: root
+
+    readonly property string helperPath: Quickshell.shellDir + "/scripts/panama-home-assistant-config"
+
+    property string url: ""
+    property var entities: []
+    property bool tokenConfigured: false
+    property bool configured: false
+    property string lastError: ""
+    property string pendingPayload: ""
+    property var refreshHomeAssistant: function() { HomeAssistant.refresh(); }
+    readonly property bool busy: statusProc.running || writeProc.running
+
+    signal configurationSaved
+
+    function errorMessage(code: string): string {
+        switch (code) {
+        case "invalid-url": return "Enter an HTTP or HTTPS Home Assistant URL.";
+        case "invalid-token": return "The access token contains unsupported characters.";
+        case "invalid-entities": return "Entity IDs must look like light.living_room.";
+        case "read-failed": return "The private configuration file could not be read.";
+        case "write-failed": return "The private configuration file could not be saved.";
+        case "invalid-payload": return "The configuration could not be validated.";
+        default: return code ? "Home Assistant configuration is unavailable." : "";
+        }
+    }
+
+    function applyResult(text: string, saved: bool): void {
+        let result = null;
+        try {
+            result = JSON.parse(text);
+        } catch (error) {
+            result = { ok: false, error: "invalid-response" };
+        }
+        if (result.ok !== true) {
+            root.lastError = root.errorMessage(String(result.error || "invalid-response"));
+            return;
+        }
+        root.url = String(result.url || "");
+        root.entities = Array.isArray(result.entities) ? result.entities : [];
+        root.tokenConfigured = result.tokenConfigured === true;
+        root.configured = result.configured === true;
+        root.lastError = "";
+        if (saved) {
+            root.configurationSaved();
+            root.refreshHomeAssistant();
+        }
+    }
+
+    function refresh(): void {
+        if (!statusProc.running && !writeProc.running)
+            statusProc.running = true;
+    }
+
+    // An empty token means "keep the stored token". Clearing is an explicit
+    // separate action so editing the URL can never erase a secret by accident.
+    function save(url: string, entitiesText: string, token: string): bool {
+        if (root.busy)
+            return false;
+        const payload = { url: url, entities: entitiesText };
+        if (token.trim() !== "")
+            payload.token = token;
+        return root.startWrite(payload);
+    }
+
+    function clearToken(): bool {
+        if (root.busy || !root.tokenConfigured)
+            return false;
+        return root.startWrite({ token: "" });
+    }
+
+    function startWrite(payload: var): bool {
+        root.lastError = "";
+        root.pendingPayload = JSON.stringify(payload);
+        writeProc.running = true;
+        return true;
+    }
+
+    Process {
+        id: statusProc
+        command: [root.helperPath, "status"]
+        stdout: StdioCollector {
+            onStreamFinished: root.applyResult(this.text, false)
+        }
+        onExited: (code, status) => {
+            if (code !== 0 && root.lastError === "")
+                root.lastError = "Home Assistant configuration could not be loaded.";
+        }
+    }
+
+    Process {
+        id: writeProc
+        command: [root.helperPath, "write"]
+        stdinEnabled: true
+        stdout: StdioCollector {
+            onStreamFinished: root.applyResult(this.text, true)
+        }
+        onStarted: {
+            writeProc.write(root.pendingPayload + "\n");
+            root.pendingPayload = "";
+        }
+        onExited: (code, status) => {
+            root.pendingPayload = "";
+            if (code !== 0 && root.lastError === "")
+                root.lastError = "Home Assistant configuration could not be saved.";
+        }
+    }
+
+    Component.onCompleted: root.refresh()
+}

config/dot/quickshell/services/Notifs.qml

@@ -37,6 +37,39 @@ Singleton {
     // Cleared when the notification centre is opened. The bar binds to this.
     property int unreadCount: 0
 
+    // Kept separate from the persisted map so this version can safely run
+    // before the matching schema entry lands. A later accepted write folds the
+    // complete map into DesktopPreferences and clears this fallback.
+    property var fallbackAppRules: ({})
+
+    // Display metadata is intentionally session-only. The durable shape stays
+    // just the per-application rule map, while a fresh notification gives the
+    // settings page a human-readable name straight away.
+    property var rememberedApplications: ({})
+
+    readonly property var persistedAppRules: {
+        const stored = DesktopPreferences.get("notificationAppRules");
+        return stored && typeof stored === "object" && !Array.isArray(stored) ? stored : {};
+    }
+
+    // The schema change is the persistence boundary. This branch keeps a
+    // session fallback only so it remains usable while that companion change
+    // is being integrated; it intentionally makes no restart guarantee then.
+    readonly property bool appRulesSchemaAvailable: PreferenceSchema.has("notificationAppRules")
+
+    readonly property var appRules: Object.assign({}, root.persistedAppRules, root.fallbackAppRules)
+
+    readonly property var applications: {
+        // byId()/heuristicLookup() do not make a binding by themselves. This
+        // read updates persisted app labels once DesktopEntries finishes scan.
+        const entries = DesktopEntries.applications.values;
+        const remembered = root.rememberedApplications;
+        return Object.keys(root.appRules).map(appId => ({
+            id: appId,
+            name: root.applicationLabel(appId, entries, remembered)
+        })).sort((a, b) => a.name.localeCompare(b.name));
+    }
+
     // Arrival times, keyed by notification id — the protocol carries no
     // timestamp. Deliberately formatted once at arrival rather than shown as
     // "5 minutes ago", which would need a clock ticking behind every card.
@@ -49,6 +82,79 @@ Singleton {
 
     readonly property bool hasNotifications: root.history.length > 0
 
+    function notificationAppId(notification: var): string {
+        const desktopEntry = String(notification.desktopEntry ?? "").trim();
+        return desktopEntry || String(notification.appName ?? "").trim() || "Notifications";
+    }
+
+    function applicationLabel(appId: string, entries: var, remembered: var): string {
+        const desktopId = appId.endsWith(".desktop") ? appId.slice(0, -8) : appId;
+        const entry = DesktopEntries.byId(appId)
+            || DesktopEntries.byId(desktopId)
+            || DesktopEntries.heuristicLookup(appId)
+            || DesktopEntries.heuristicLookup(desktopId);
+        return entry?.name || remembered[appId]?.name || appId;
+    }
+
+    function normalizedAppRule(rule: var): var {
+        const source = rule && typeof rule === "object" && !Array.isArray(rule) ? rule : {};
+        return {
+            enabled: source.enabled !== false,
+            showOnLockScreen: source.showOnLockScreen !== false,
+            showContentOnLockScreen: source.showContentOnLockScreen !== false
+        };
+    }
+
+    function appRule(appId: string): var {
+        return root.normalizedAppRule(root.appRules[appId]);
+    }
+
+    function setAppRule(appId: string, patch: var): bool {
+        if (!appId)
+            return false;
+
+        const current = root.appRule(appId);
+        const next = {};
+        for (const knownAppId of Object.keys(root.appRules))
+            next[knownAppId] = root.appRule(knownAppId);
+        next[appId] = {
+            enabled: patch.enabled === undefined ? current.enabled : patch.enabled === true,
+            showOnLockScreen: patch.showOnLockScreen === undefined ? current.showOnLockScreen : patch.showOnLockScreen === true,
+            showContentOnLockScreen: patch.showContentOnLockScreen === undefined ? current.showContentOnLockScreen : patch.showContentOnLockScreen === true
+        };
+
+        if (root.appRulesSchemaAvailable && DesktopPreferences.set("notificationAppRules", next))
+            root.fallbackAppRules = {};
+        else
+            root.fallbackAppRules = next;
+        return true;
+    }
+
+    function rememberApplication(notification: var): string {
+        const appId = root.notificationAppId(notification);
+        const next = Object.assign({}, root.rememberedApplications);
+        next[appId] = {
+            name: String(notification.appName ?? "").trim() || appId
+        };
+        root.rememberedApplications = next;
+
+        if (root.appRules[appId] === undefined)
+            root.setAppRule(appId, {});
+        return appId;
+    }
+
+    // These policy getters deliberately accept Notification objects, so a lock
+    // screen can use the same source of truth without duplicating app matching.
+    function shouldShowOnLockScreen(notification: var): bool {
+        const rule = root.appRule(root.notificationAppId(notification));
+        return rule.enabled && rule.showOnLockScreen;
+    }
+
+    function shouldShowContentOnLockScreen(notification: var): bool {
+        const rule = root.appRule(root.notificationAppId(notification));
+        return rule.enabled && rule.showOnLockScreen && rule.showContentOnLockScreen;
+    }
+
     // history grouped by app, in most-recent-app-first order — the shape
     // NotificationCenter.qml renders directly.
     readonly property var groups: {
@@ -85,13 +191,20 @@ Singleton {
         actionIconsSupported: true
         inlineReplySupported: true
 
-        onNotification: notification => {
+        onNotification: notification => root.handleNotification(notification)
+    }
+
+    function handleNotification(notification: var): void {
             // Replayed from before a shell reload. Letting these through would
             // re-toast and re-list everything on every edit, so they are left
             // untracked and allowed to die.
             if (notification.lastGeneration)
                 return;
 
+            const appId = root.rememberApplication(notification);
+            if (!root.appRule(appId).enabled)
+                return;
+
             // Without this the object is destroyed the instant this returns.
             notification.tracked = true;
             root.arrivals[notification.id] = new Date();
@@ -108,12 +221,11 @@ Singleton {
 
             if (!root.doNotDisturb)
                 root.popups = [notification].concat(root.popups);
-        }
     }
 
     // ── Mutation ────────────────────────────────────────────────────────────
 
-    function pushHistory(n: Notification): void {
+    function pushHistory(n: var): void {
         const next = [n].concat(root.history);
 
         // Anything past the cap is released, otherwise it stays tracked
@@ -166,7 +278,7 @@ Singleton {
 
     // Called from the `closed` signal — the object is on its way out, so this
     // only ever removes references, never touches the notification.
-    function forget(n: Notification): void {
+    function forget(n: var): void {
         delete root.arrivals[n.id];
         if (root.history.indexOf(n) !== -1)
             root.history = root.history.filter(x => x !== n);

config/dot/quickshell/services/SettingsBackup.qml

@@ -38,6 +38,10 @@ Singleton {
     property var initializeHome: function(ids) { HomePreferences.initialize(ids); }
     property var aliasHome: function(id, alias) { HomePreferences.setAlias(id, alias); }
     property var reloadDesktop: function() { DesktopPreferences.reload(); }
+    property var readDisplays: function() { return DesktopPreferences.get("displays"); }
+    property var protectDisplays: function(value) { return DesktopPreferences.set("displays", value); }
+    property var displayBusy: function() { return Displays.busy || Displays.awaitingConfirmation; }
+    property var setDisplayBlocked: function(blocked) { Displays.externalChangeBlocked = blocked; }
     property var applyCompositor: function() { SystemSettings.applyPersistedDisplayPolicy(); }
     property var reloadKeybinds: function() { Keybinds.applyReload(); }
     property var keybindsReloading: function() { return Keybinds.reloading; }
@@ -47,6 +51,7 @@ Singleton {
     }
     property var applyWallpaper: function(path) { Wallpaper.set(path); }
     property var reloadShell: function() { Quickshell.reload(false); }
+    property var protectedDisplays: ({})
 
     readonly property bool busy: listQuery.running || actionRun.running
         || applyRestoredState.running || settleReload.running
@@ -81,6 +86,10 @@ Singleton {
                 root.lastError = actionRun.restoring
                     ? "That snapshot could not be restored."
                     : "The settings could not be backed up.";
+                if (actionRun.restoring) {
+                    root.setDisplayBlocked(false);
+                    root.protectedDisplays = ({});
+                }
                 return;
             }
             root.lastAction = actionRun.restoring ? "restored" : "saved";
@@ -89,6 +98,10 @@ Singleton {
                 root.lastError = homeReloaded
                     ? ""
                     : "Desktop settings were restored, but Home favourites could not be reloaded.";
+                if (!homeReloaded) {
+                    root.setDisplayBlocked(false);
+                    root.protectedDisplays = ({});
+                }
             } else
                 root.lastError = "";
             root.refresh();
@@ -124,6 +137,8 @@ Singleton {
             // from leaving restored Home state stale indefinitely.
             if ((!root.keybindsReloading() && !root.systemBusy()) || attempts >= 30) {
                 stop();
+                root.setDisplayBlocked(false);
+                root.protectedDisplays = ({});
                 root.reloadShell();
             }
         }
@@ -162,6 +177,8 @@ Singleton {
         if (!root.reloadHomeState(text))
             return false;
         root.reloadDesktop();
+        if (!root.protectDisplays(root.protectedDisplays))
+            return false;
         applyRestoredState.restart();
         return true;
     }
@@ -222,10 +239,18 @@ Singleton {
     function restore(name: string): bool {
         if (actionRun.running)
             return false;
+        if (root.displayBusy()) {
+            root.lastError = "Finish the current display change before restoring settings.";
+            return false;
+        }
         if (!root.snapshots.some(snapshot => snapshot.name === name)) {
             root.lastError = "That snapshot is not in the list.";
             return false;
         }
+        const currentDisplays = root.readDisplays();
+        root.protectedDisplays = JSON.parse(JSON.stringify(
+            currentDisplays && typeof currentDisplays === "object" ? currentDisplays : {}));
+        root.setDisplayBlocked(true);
         actionRun.restoring = true;
         actionRun.exec([root.helperPath, "restore", name]);
         return true;

config/dot/quickshell/services/SoundFeedback.qml

@@ -0,0 +1,97 @@
+pragma Singleton
+
+// GNOME and GTK applications already honour these desktop sound preferences.
+// Panama controls the same durable keys so moving between sessions does not
+// create two competing notions of whether event feedback is enabled.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+Singleton {
+    id: root
+
+    property bool eventSounds: true
+    property bool inputFeedback: false
+    property string lastError: ""
+    readonly property bool busy: eventRead.running || inputRead.running
+        || eventWrite.running || inputWrite.running
+
+    function parsedBoolean(text: string, fallback: bool): bool {
+        const value = text.trim();
+        if (value === "true")
+            return true;
+        if (value === "false")
+            return false;
+        return fallback;
+    }
+
+    function refresh(): void {
+        if (!eventRead.running)
+            eventRead.running = true;
+        if (!inputRead.running)
+            inputRead.running = true;
+    }
+
+    function setEventSounds(enabled: bool): void {
+        root.eventSounds = enabled;
+        eventWrite.command = ["gsettings", "set", "org.gnome.desktop.sound", "event-sounds", String(enabled)];
+        eventWrite.running = true;
+    }
+
+    function setInputFeedback(enabled: bool): void {
+        root.inputFeedback = enabled;
+        inputWrite.command = ["gsettings", "set", "org.gnome.desktop.sound", "input-feedback-sounds", String(enabled)];
+        inputWrite.running = true;
+    }
+
+    Process {
+        id: eventRead
+        command: ["gsettings", "get", "org.gnome.desktop.sound", "event-sounds"]
+        stdout: StdioCollector {
+            onStreamFinished: root.eventSounds = root.parsedBoolean(this.text, root.eventSounds)
+        }
+        onExited: (code, status) => {
+            if (code !== 0)
+                root.lastError = "Event sound preferences could not be read.";
+        }
+    }
+
+    Process {
+        id: inputRead
+        command: ["gsettings", "get", "org.gnome.desktop.sound", "input-feedback-sounds"]
+        stdout: StdioCollector {
+            onStreamFinished: root.inputFeedback = root.parsedBoolean(this.text, root.inputFeedback)
+        }
+        onExited: (code, status) => {
+            if (code !== 0)
+                root.lastError = "Input feedback preferences could not be read.";
+        }
+    }
+
+    Process {
+        id: eventWrite
+        onExited: (code, status) => {
+            if (code !== 0) {
+                root.lastError = "Event sound preferences could not be changed.";
+                root.refresh();
+            } else {
+                root.lastError = "";
+            }
+        }
+    }
+
+    Process {
+        id: inputWrite
+        onExited: (code, status) => {
+            if (code !== 0) {
+                root.lastError = "Input feedback preferences could not be changed.";
+                root.refresh();
+            } else {
+                root.lastError = "";
+            }
+        }
+    }
+
+    Component.onCompleted: root.refresh()
+}

config/dot/quickshell/services/SystemSettings.qml

@@ -33,6 +33,16 @@ Singleton {
     property string quickshellVersion: "0.3.0"
     property string lastError: ""
 
+    // Explicit seams keep reset sequencing testable without changing the live
+    // keymap, wallpaper, or display from an isolated contract harness.
+    property var displayBusy: function() { return Displays.busy || Displays.awaitingConfirmation; }
+    property var readDisplays: function() { return DesktopPreferences.get("displays"); }
+    property var protectDisplays: function(value) { return DesktopPreferences.set("displays", value); }
+    property var setDisplayBlocked: function(blocked) { Displays.externalChangeBlocked = blocked; }
+    property var reloadKeybinds: function() { Keybinds.applyReload(); }
+    property var keybindsReloading: function() { return Keybinds.reloading; }
+    property var applyWallpaper: function(path) { Wallpaper.set(path); }
+
     readonly property bool busy: monitorQuery.running || serviceQuery.running || versionQuery.running
         || configWrite.running || configVerify.running || bluebubblesQuery.running
 
@@ -196,6 +206,11 @@ Singleton {
     }
 
     // ── Applying options ────────────────────────────────────────────────────
+    // Test harnesses may replace the external compositor boundary while still
+    // exercising validation, commit routing, persistence, and reset replay.
+    // Production leaves this unset and always uses the verified Hyprland path.
+    property var compositorApplyOverride: null
+
     // `values` maps schema keys to values, e.g. { vrrPolicy: 3, gapsOut: 12 }.
     // The whole batch is validated before anything is sent, so one bad value
     // rejects the batch rather than half-applying it.
@@ -217,6 +232,9 @@ Singleton {
         if (Object.keys(requested).length === 0)
             return false;
 
+        if (root.compositorApplyOverride !== null)
+            return root.compositorApplyOverride(requested);
+
         // A write in flight is queued rather than refused. Options are applied
         // and verified one batch at a time, but the callers are a settings UI
         // and a startup replay of every compositor-backed preference -- they
@@ -389,8 +407,22 @@ Singleton {
     //
     // Compositor-backed values are re-applied afterwards, since resetting the
     // stored value does not by itself tell Hyprland anything.
-    function restoreDefaults(): void {
+    function restoreDefaults(): bool {
+        if (root.displayBusy()) {
+            root.lastError = "Finish the current display change before restoring defaults.";
+            return false;
+        }
+
+        const currentDisplays = root.readDisplays();
+        const protectedDisplays = JSON.parse(JSON.stringify(
+            currentDisplays && typeof currentDisplays === "object" ? currentDisplays : {}));
+        root.setDisplayBlocked(true);
         DesktopPreferences.resetDesktopDefaults();
+        if (!root.protectDisplays(protectedDisplays)) {
+            root.setDisplayBlocked(false);
+            root.lastError = "The current display setting could not be protected during reset.";
+            return false;
+        }
 
         // Home accessories keep their own store (panama-home.json), so a reset
         // that only cleared the schema store would silently leave a customised
@@ -401,12 +433,33 @@ Singleton {
         HomePreferences.resetHomeDefaults();
 
         resettleTimer.restart();
+        return true;
     }
 
     Timer {
         id: resettleTimer
         interval: 60
-        onTriggered: root.applyPersistedDisplayPolicy()
+        onTriggered: {
+            root.applyPersistedDisplayPolicy();
+            root.reloadKeybinds();
+            root.applyWallpaper(String(DesktopPreferences.get("wallpaperPath") ?? ""));
+            resetRelease.attempts = 0;
+            resetRelease.restart();
+        }
+    }
+
+    Timer {
+        id: resetRelease
+        property int attempts: 0
+        interval: 100
+        repeat: true
+        onTriggered: {
+            attempts++;
+            if ((!root.keybindsReloading() && !root.busy) || attempts >= 50) {
+                stop();
+                root.setDisplayBlocked(false);
+            }
+        }
     }
 
     function setAutoHdr(enabled: bool): void {

config/dot/quickshell/services/Wallpaper.qml

@@ -33,6 +33,7 @@ Singleton {
     property bool scanning: false
 
     readonly property string configured: DesktopPreferences.get("wallpaperPath")
+    readonly property string shippedPath: `${Quickshell.env("HOME")}/Pictures/Wallpapers/faroe_islands.jpg`
 
     // Directories searched for wallpapers, in order. Screenshots are
     // deliberately excluded: a folder of 300 screenshots is not a wallpaper
@@ -85,6 +86,7 @@ Singleton {
         id: apply
 
         property string requested: ""
+        property string storedValue: ""
         property var remaining: []
 
         onExited: (exitCode, exitStatus) => {
@@ -100,7 +102,7 @@ Singleton {
                 return;
             }
             root.lastError = "";
-            DesktopPreferences.set("wallpaperPath", apply.requested);
+            DesktopPreferences.set("wallpaperPath", apply.storedValue);
             root.refreshActive();
         }
     }
@@ -140,19 +142,16 @@ Singleton {
     // Applies to every connected output. Returns false when the path is not one
     // the schema will accept, so a caller can report the refusal.
     function set(path: string): bool {
-        if (PreferenceSchema.coerce("wallpaperPath", path) === undefined) {
+        const effectivePath = path === "" ? root.shippedPath : path;
+        if (PreferenceSchema.coerce("wallpaperPath", effectivePath) === undefined) {
             root.lastError = "That file path cannot be used as a wallpaper.";
             return false;
         }
         if (apply.running)
             return false;
 
-        apply.requested = path;
-        // "" clears the preference without touching what is on screen.
-        if (path === "") {
-            DesktopPreferences.set("wallpaperPath", "");
-            return true;
-        }
+        apply.requested = effectivePath;
+        apply.storedValue = path;
 
         const outputs = Quickshell.screens.map(screen => screen.name).filter(name => !!name);
         if (outputs.length === 0) {
@@ -161,7 +160,7 @@ Singleton {
         }
 
         apply.remaining = outputs.slice(1);
-        apply.exec(["hyprctl", "hyprpaper", "wallpaper", `${outputs[0]},${path}`]);
+        apply.exec(["hyprctl", "hyprpaper", "wallpaper", `${outputs[0]},${effectivePath}`]);
         return true;
     }
 

config/dot/quickshell/settings-backup-harness.qml

@@ -13,6 +13,9 @@ ShellRoot {
     property var calls: []
     property bool homeInitialized: false
     property var homeFavorites: []
+    property bool displayOperationBusy: false
+    property bool displayBlocked: false
+    property var displayGeneration: ({ "DP-2": { mode: "4500x3000@60", scale: 1.5, transform: 0 } })
 
     function record(name: string): void {
         const next = root.calls.slice();
@@ -43,6 +46,17 @@ ShellRoot {
                 favorite.id === id ? { id: id, alias: alias } : favorite);
         };
         SettingsBackup.reloadDesktop = function() { root.record("desktop.reload"); };
+        SettingsBackup.readDisplays = function() { return root.displayGeneration; };
+        SettingsBackup.protectDisplays = function(value) {
+            root.record("display.protect:" + JSON.stringify(value));
+            root.displayGeneration = value;
+            return true;
+        };
+        SettingsBackup.displayBusy = function() { return root.displayOperationBusy; };
+        SettingsBackup.setDisplayBlocked = function(blocked) {
+            root.record("display.block:" + blocked);
+            root.displayBlocked = blocked;
+        };
         SettingsBackup.applyCompositor = function() { root.record("system.apply"); };
         SettingsBackup.reloadKeybinds = function() { root.record("keybinds.reload"); };
         SettingsBackup.keybindsReloading = function() { return false; };
@@ -59,17 +73,29 @@ ShellRoot {
             root.calls = [];
             root.homeInitialized = false;
             root.homeFavorites = [];
+            root.displayOperationBusy = false;
+            root.displayBlocked = false;
+            SettingsBackup.protectedDisplays = root.displayGeneration;
         }
 
         function apply(output: string): bool {
             return SettingsBackup.handleRestoreOutput(output);
         }
 
+        function restoreWhileDisplayBusy(): bool {
+            root.displayOperationBusy = true;
+            SettingsBackup.snapshots = [{ name: "settings-20260818-010203004.json" }];
+            return SettingsBackup.restore("settings-20260818-010203004.json");
+        }
+
         function status(): string {
             return JSON.stringify({
                 calls: root.calls,
                 initialized: root.homeInitialized,
-                favorites: root.homeFavorites
+                favorites: root.homeFavorites,
+                displayBlocked: root.displayBlocked,
+                displays: root.displayGeneration,
+                lastError: SettingsBackup.lastError
             });
         }
     }

config/dot/quickshell/settings-system-harness.qml

@@ -6,6 +6,48 @@ import qs.config
 import qs.services
 
 ShellRoot {
+    id: root
+
+    property var resetCalls: []
+    property var appliedBatches: []
+    property bool displayBlocked: false
+
+    function recordReset(name: string): void {
+        const next = root.resetCalls.slice();
+        next.push(name);
+        root.resetCalls = next;
+    }
+
+    Component.onCompleted: {
+        // Keep compositor verification entirely inside the isolated harness.
+        // Production applyOptions is covered separately by the Hyprland write
+        // contract; this seam proves commit/reset routing without changing the
+        // desktop that is running the test.
+        if (Quickshell.env("PANAMA_SETTINGS_TEST_ISOLATE_COMPOSITOR") === "1") {
+            SystemSettings.compositorApplyOverride = function(requested) {
+                const batches = root.appliedBatches.slice();
+                batches.push(requested);
+                root.appliedBatches = batches;
+                for (const key in requested)
+                    DesktopPreferences.set(key, requested[key]);
+                return true;
+            };
+        }
+        SystemSettings.displayBusy = function() { return false; };
+        SystemSettings.readDisplays = function() { return DesktopPreferences.get("displays"); };
+        SystemSettings.protectDisplays = function(value) {
+            root.recordReset("display.protect");
+            return DesktopPreferences.set("displays", value);
+        };
+        SystemSettings.setDisplayBlocked = function(blocked) {
+            root.recordReset("display.block:" + blocked);
+            root.displayBlocked = blocked;
+        };
+        SystemSettings.reloadKeybinds = function() { root.recordReset("keybinds.reload"); };
+        SystemSettings.keybindsReloading = function() { return false; };
+        SystemSettings.applyWallpaper = function(path) { root.recordReset("wallpaper.set:" + path); };
+    }
+
     IpcHandler {
         target: "settings-system-test"
 
@@ -52,7 +94,22 @@ ShellRoot {
             });
         }
 
-        function restoreDefaults(): void { SystemSettings.restoreDefaults(); }
+        function restoreDefaults(): bool {
+            root.resetCalls = [];
+            return SystemSettings.restoreDefaults();
+        }
+
+        function resetState(): string {
+            return JSON.stringify({
+                calls: root.resetCalls,
+                displayBlocked: root.displayBlocked,
+                appliedBatches: root.appliedBatches
+            });
+        }
+
+        function applyState(): string {
+            return JSON.stringify(root.appliedBatches);
+        }
 
         function panelAllowed(panel: string): bool {
             return SystemSettings.isGnomePanelAllowed(panel);

config/dot/quickshell/sound-page-harness.qml

@@ -0,0 +1,34 @@
+// Read-only contract harness for the Sound page. It instantiates every device
+// row against the real PipeWire graph but exposes no mutating IPC methods.
+
+import Quickshell
+import Quickshell.Io
+import Quickshell.Services.Pipewire
+import QtQuick
+import qs.services
+import qs.modules.settings
+
+ShellRoot {
+    SoundPage {
+        width: 760
+        height: 900
+    }
+
+    PwObjectTracker {
+        objects: AudioDevices.outputs.concat(AudioDevices.inputs)
+    }
+
+    IpcHandler {
+        target: "sound-page-test"
+
+        function status(): string {
+            return JSON.stringify({
+                ready: Pipewire.ready,
+                outputs: AudioDevices.outputs.length,
+                inputs: AudioDevices.inputs.length,
+                defaultOutput: AudioDevices.label(AudioDevices.current(true)),
+                defaultInput: AudioDevices.label(AudioDevices.current(false))
+            });
+        }
+    }
+}

tests/quickshell/HomeAssistantConfigHarness.qml

@@ -0,0 +1,56 @@
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+import qs.services
+
+ShellRoot {
+    id: root
+
+    property int refreshCalls: 0
+
+    FileView {
+        id: tokenFile
+        path: Quickshell.env("PANAMA_TEST_TOKEN_FILE")
+        blockLoading: true
+        printErrors: false
+    }
+
+    Component.onCompleted: {
+        HomeAssistant.fixtureMode = true;
+        HomeAssistantConfig.refreshHomeAssistant = function() { root.refreshCalls++; };
+    }
+
+    IpcHandler {
+        target: "home-assistant-config-test"
+
+        function save(url: string, entities: string): bool {
+            return HomeAssistantConfig.save(url, entities, "");
+        }
+
+        function saveWithToken(url: string, entities: string): bool {
+            return HomeAssistantConfig.save(url, entities, tokenFile.text());
+        }
+
+        function clearToken(): bool {
+            return HomeAssistantConfig.clearToken();
+        }
+
+        function refresh(): void {
+            HomeAssistantConfig.refresh();
+        }
+
+        function status(): string {
+            return JSON.stringify({
+                url: HomeAssistantConfig.url,
+                entities: HomeAssistantConfig.entities,
+                tokenConfigured: HomeAssistantConfig.tokenConfigured,
+                configured: HomeAssistantConfig.configured,
+                busy: HomeAssistantConfig.busy,
+                lastError: HomeAssistantConfig.lastError,
+                pendingPayloadEmpty: HomeAssistantConfig.pendingPayload === "",
+                refreshCalls: root.refreshCalls
+            });
+        }
+    }
+}

tests/quickshell/NotificationAppRulesHarness.qml

@@ -0,0 +1,126 @@
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+import qs.config
+import qs.services
+
+ShellRoot {
+    id: root
+
+    function notification(idValue: int, desktopEntryValue: string, appNameValue: string): var {
+        const closeHandlers = [];
+        return {
+            id: idValue,
+            desktopEntry: desktopEntryValue,
+            appName: appNameValue,
+            appIcon: "",
+            transient: false,
+            lastGeneration: false,
+            tracked: false,
+            dismissed: false,
+            closed: {
+                connect: callback => closeHandlers.push(callback)
+            },
+            dismiss: function() {
+                this.dismissed = true;
+                for (const callback of closeHandlers)
+                    callback();
+            }
+        };
+    }
+
+    function resetNotifications(): void {
+        Notifs.history = [];
+        Notifs.popups = [];
+        Notifs.unreadCount = 0;
+        Notifs.doNotDisturb = false;
+    }
+
+    function reset(): void {
+        root.resetNotifications();
+        Notifs.fallbackAppRules = {};
+        Notifs.rememberedApplications = {};
+        DesktopPreferences.set("notificationAppRules", {});
+    }
+
+    IpcHandler {
+        target: "notification-app-rules-test"
+
+        function exercise(): string {
+            root.reset();
+
+            const signal = root.notification(1, "org.signal.Signal.desktop", "Signal");
+            Notifs.handleNotification(signal);
+            const appId = Notifs.notificationAppId(signal);
+            const initialRules = DesktopPreferences.get("notificationAppRules");
+
+            const fallback = root.notification(6, "", "Fallback Terminal");
+            Notifs.handleNotification(fallback);
+            const fallbackId = Notifs.notificationAppId(fallback);
+            const fallbackApplication = Notifs.applications.find(app => app.id === fallbackId);
+
+            root.resetNotifications();
+            Notifs.setAppRule(appId, { enabled: false });
+            const muted = root.notification(2, "org.signal.Signal.desktop", "Signal");
+            Notifs.handleNotification(muted);
+            const mutedResult = {
+                tracked: muted.tracked,
+                history: Notifs.history.length,
+                popups: Notifs.popups.length,
+                unread: Notifs.unreadCount
+            };
+
+            root.reset();
+            Notifs.doNotDisturb = true;
+            const dnd = root.notification(3, "org.signal.Signal.desktop", "Signal");
+            Notifs.handleNotification(dnd);
+
+            Notifs.setAppRule("org.privacy.App.desktop", {
+                showOnLockScreen: false,
+                showContentOnLockScreen: false
+            });
+            const privateNotification = root.notification(4, "org.privacy.App.desktop", "Private");
+
+            return JSON.stringify({
+                appId: appId,
+                initialRules: initialRules,
+                fallback: {
+                    id: fallbackId,
+                    application: fallbackApplication
+                },
+                muted: mutedResult,
+                dnd: {
+                    tracked: dnd.tracked,
+                    history: Notifs.history.length,
+                    popups: Notifs.popups.length,
+                    unread: Notifs.unreadCount
+                },
+                privacy: {
+                    visible: Notifs.shouldShowOnLockScreen(privateNotification),
+                    content: Notifs.shouldShowContentOnLockScreen(privateNotification)
+                }
+            });
+        }
+
+        function persist(): string {
+            root.reset();
+            const notification = root.notification(5, "org.persist.App.desktop", "Persist");
+            Notifs.handleNotification(notification);
+            Notifs.setAppRule("org.persist.App.desktop", {
+                enabled: false,
+                showOnLockScreen: true,
+                showContentOnLockScreen: false
+            });
+            return JSON.stringify(DesktopPreferences.get("notificationAppRules"));
+        }
+
+        function restored(): string {
+            return JSON.stringify(DesktopPreferences.get("notificationAppRules"));
+        }
+
+        function applications(): string {
+            return JSON.stringify(Notifs.applications);
+        }
+    }
+}

tests/quickshell/connectivity-contract.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+# Network & Devices reads real NetworkManager and BlueZ state.
+#
+# Both of the bugs this contract exists to prevent were silent. Neither logged
+# anything; both produced a page that looked fine and told the user something
+# false:
+#
+#   * the device lookups used enum names that do not exist
+#     (NetworkDeviceType.Wifi rather than DeviceType.Wifi), so they returned
+#     null and the page reported "No Wi-Fi adapter" on a machine whose Wi-Fi was
+#     connected;
+#   * signalStrength is 0.0-1.0, not a percentage, so thresholds written for
+#     0-100 put every network including the connected one in the bottom bucket.
+#
+# So this compares what the service resolves against what NetworkManager itself
+# reports, rather than merely checking the service does not crash.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+harness="$repo_dir/config/dot/quickshell/connectivity-harness.qml"
+
+fail() {
+    printf 'connectivity contract: %s\n' "$1" >&2
+    exit 1
+}
+
+command -v nmcli >/dev/null || fail 'nmcli is needed to check the service against reality'
+
+run() { qs -p "$harness" "$@"; }
+harness_pid=""
+
+cleanup() {
+    run ipc call connectivity-test setActive false >/dev/null 2>&1 || true
+    # By PID: never `pkill -f connectivity-harness`, which also matches the
+    # shell running this script.
+    [[ -n "$harness_pid" ]] && kill "$harness_pid" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+qs -p "$harness" --daemonize >/dev/null
+for _ in $(seq 1 40); do
+    run ipc show 2>/dev/null | rg -q '^target connectivity-test$' && break
+    sleep 0.1
+done
+run ipc show 2>/dev/null | rg -q '^target connectivity-test$' || fail 'test IPC target did not start'
+harness_pid="$(run list | awk '/Process ID:/ { print $3; exit }')"
+
+# Scanning only runs while the page says it is visible.
+run ipc call connectivity-test setActive true >/dev/null
+sleep 3
+
+state="$(run ipc call connectivity-test status)"
+
+# ── Devices the service finds must match the ones NetworkManager reports ─────
+nm_wifi="$(nmcli -t -f DEVICE,TYPE device | awk -F: '$2 == "wifi" { print $1; exit }')"
+nm_wired="$(nmcli -t -f DEVICE,TYPE,STATE device | awk -F: '$2 == "ethernet" && $3 == "connected" { print $1; exit }')"
+
+if [[ -n "$nm_wifi" ]]; then
+    [[ "$(jq -r .wifiDevice <<<"$state")" == "$nm_wifi" ]] \
+        || fail "NetworkManager reports Wi-Fi device '$nm_wifi' but the service found '$(jq -r .wifiDevice <<<"$state")'"
+fi
+if [[ -n "$nm_wired" ]]; then
+    [[ "$(jq -r .wiredConnected <<<"$state")" == "true" ]] \
+        || fail "NetworkManager reports '$nm_wired' connected but the service says it is not"
+fi
+
+# ── Signal strength is a ratio, and the labels must reflect that ─────────────
+while IFS='|' read -r value expect; do
+    got="$(run ipc call connectivity-test labelFor "$value")"
+    [[ "$got" == "$expect" ]] || fail "signal $value labelled '$got', expected '$expect'"
+done <<'CASES'
+1.0|Excellent
+0.85|Excellent
+0.6|Good
+0.4|Fair
+0.1|Weak
+0.0|No signal
+CASES
+
+# If a network is connected, it must not be described as the weakest possible
+# thing -- that was the visible symptom of reading the ratio as a percentage.
+active_ssid="$(jq -r .activeSsid <<<"$state")"
+if [[ -n "$active_ssid" ]]; then
+    strength="$(jq -r .activeStrength <<<"$state")"
+    awk -v s="$strength" 'BEGIN { exit !(s >= 0 && s <= 1) }' \
+        || fail "signalStrength $strength is outside 0.0-1.0; the label buckets assume a ratio"
+fi
+
+# ── Bluetooth ────────────────────────────────────────────────────────────────
+if [[ "$(bluetoothctl list 2>/dev/null | wc -l)" -gt 0 ]]; then
+    [[ "$(jq -r .adapter <<<"$state")" == "true" ]] \
+        || fail 'an adapter is present but the service did not find it'
+fi
+
+trap - EXIT
+cleanup
+printf 'connectivity contract: PASS\n'

tests/quickshell/fixtures/org.persist.App.desktop

@@ -0,0 +1,5 @@
+[Desktop Entry]
+Type=Application
+Name=Persisted Fixture App
+Exec=/usr/bin/true
+Icon=applications-system

tests/quickshell/home-assistant-config-contract.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$repo_dir/config/dot/quickshell/scripts/panama-home-assistant-config"
+service="$repo_dir/config/dot/quickshell/services/HomeAssistantConfig.qml"
+page="$repo_dir/config/dot/quickshell/modules/settings/HomePhonePage.qml"
+password_field="$repo_dir/config/dot/quickshell/modules/settings/PasswordField.qml"
+harness_fixture="$repo_dir/tests/quickshell/HomeAssistantConfigHarness.qml"
+work="$(mktemp -d /tmp/panama-ha-config.XXXXXX)"
+env_file="$work/env"
+
+fail() {
+    printf 'Home Assistant config contract: %s\n' "$1" >&2
+    exit 1
+}
+
+cleanup() {
+    if declare -F qs_for_test >/dev/null; then
+        qs_for_test kill >/dev/null 2>&1 || true
+    fi
+    rm -rf "$work"
+}
+trap cleanup EXIT
+
+[[ -x "$helper" ]] || fail 'credential helper is missing or not executable'
+[[ -f "$service" ]] || fail 'credential service is missing'
+[[ -f "$harness_fixture" ]] || fail 'credential runtime harness is missing'
+
+rg -Fq 'stdinEnabled: true' "$service" || fail 'credential writes do not use process stdin'
+rg -Fq 'writeProc.write(root.pendingPayload + "\n")' "$service" || fail 'credential payload is not written over stdin'
+rg -Fq 'root.pendingPayload = ""' "$service" || fail 'credential payload remains in service memory after write'
+if rg -q 'command:.*(token|pendingPayload)' "$service"; then
+    fail 'credential data can reach a process command line'
+fi
+rg -Fq 'PasswordField {' "$page" || fail 'Home Assistant token is not entered through the masked field'
+rg -Fq 'activeFocusOnTab: true' "$password_field" || fail 'masked credential field is not keyboard reachable'
+rg -Fq 'HomeAssistantConfig.save(' "$page" || fail 'Home Assistant configuration cannot be saved from Settings'
+rg -Fq 'HomeAssistantConfig.clearToken()' "$page" || fail 'stored Home Assistant token cannot be cleared'
+rg -Fq 'id: clearTokenButton' "$page" || fail 'clear-token action has no keyboard control identity'
+rg -Fq 'id: saveHomeConfigButton' "$page" || fail 'save action has no keyboard control identity'
+rg -Fq 'activeFocusOnTab: enabled' "$page" || fail 'credential actions are not in tab order'
+rg -Fq 'Keys.onReturnPressed:' "$page" || fail 'credential actions have no keyboard activation'
+
+cat >"$env_file" <<'EOF'
+# Existing private shell settings must survive byte-for-byte.
+export KEEP_ME='untouched value'
+export JIRA_CREDENTIALS='unrelated-secret'
+export PANAMA_HOME_ASSISTANT_URL='https://old.example.test'
+export PANAMA_HOME_ASSISTANT_TOKEN='old-token'
+export PANAMA_HOME_ASSISTANT_ENTITIES='light.old'
+EOF
+chmod 0644 "$env_file"
+
+run_helper() {
+    PANAMA_HOME_ASSISTANT_ENV_FILE="$env_file" "$helper" "$@"
+}
+
+status="$(run_helper status)" || fail 'status failed for a valid private env file'
+jq -e '.configured == true and .tokenConfigured == true
+    and .url == "https://old.example.test"
+    and .entities == ["light.old"] and (has("token") | not)' \
+    <<<"$status" >/dev/null || fail "status exposed or misread credentials: $status"
+if rg -q 'old-token|unrelated-secret' <<<"$status"; then
+    fail 'status output leaked a secret'
+fi
+
+secret='ha-secret-must-never-appear-in-ps-or-output'
+payload="$work/payload.json"
+jq -cn --arg token "$secret" '{
+    url: "https://home.example.test/",
+    token: $token,
+    entities: ["light.kitchen", "light.desk", "light.kitchen"]
+}' >"$payload"
+
+# Keep stdin open long enough to prove the token is absent from the helper's
+# process arguments. The secret lives only in the private payload file/stdin.
+fifo="$work/input.fifo"
+mkfifo "$fifo"
+PANAMA_HOME_ASSISTANT_ENV_FILE="$env_file" "$helper" write <"$fifo" >"$work/write.out" 2>"$work/write.err" &
+helper_pid=$!
+for _ in $(seq 1 30); do
+    kill -0 "$helper_pid" 2>/dev/null && break
+    sleep 0.05
+done
+if ps -o args= -p "$helper_pid" | rg -Fq "$secret"; then
+    fail 'token appeared in the credential helper process arguments'
+fi
+cp "$payload" "$fifo"
+wait "$helper_pid" || fail 'stdin credential write failed'
+
+write_result="$(cat "$work/write.out")"
+jq -e '.ok == true and .configured == true and .tokenConfigured == true
+    and .url == "https://home.example.test"
+    and .entities == ["light.kitchen", "light.desk"] and (has("token") | not)' \
+    <<<"$write_result" >/dev/null || fail "write returned unsafe or incorrect state: $write_result"
+if rg -q "$secret|old-token|unrelated-secret" "$work/write.out" "$work/write.err"; then
+    fail 'credential helper output leaked a secret'
+fi
+
+[[ "$(stat -c '%a' "$env_file")" == "600" ]] || fail 'private env file is not mode 0600'
+rg -Fxq "export KEEP_ME='untouched value'" "$env_file" || fail 'unrelated env content changed'
+rg -Fxq "export JIRA_CREDENTIALS='unrelated-secret'" "$env_file" || fail 'unrelated secret changed'
+rg -Fq "$secret" "$env_file" || fail 'new token was not stored'
+
+# Omitting token preserves it; an explicit empty token clears it.
+printf '%s\n' '{"url":"https://new.example.test","entities":"light.office, light.hall"}' \
+    | run_helper write >/dev/null || fail 'non-secret update failed'
+rg -Fq "$secret" "$env_file" || fail 'blank token field unexpectedly erased the stored token'
+
+printf '%s\n' '{"token":""}' | run_helper write >/dev/null || fail 'token clear failed'
+cleared="$(run_helper status)"
+jq -e '.configured == false and .tokenConfigured == false
+    and .url == "https://new.example.test"
+    and .entities == ["light.office", "light.hall"]' \
+    <<<"$cleared" >/dev/null || fail "cleared state is wrong: $cleared"
+
+before_hash="$(sha256sum "$env_file" | cut -d' ' -f1)"
+printf '%s\n' '{"url":"file:///etc/passwd"}' | run_helper write >/dev/null 2>&1 \
+    && fail 'invalid URL was accepted'
+after_hash="$(sha256sum "$env_file" | cut -d' ' -f1)"
+[[ "$before_hash" == "$after_hash" ]] || fail 'rejected input still modified the private env file'
+
+# Exercise the actual QML Process.write() boundary with a pre-existing token.
+# The IPC carries only non-secret fields; the helper must preserve the token.
+config_path="$work/quickshell"
+harness="$config_path/home-assistant-config-harness.qml"
+cp -a "$repo_dir/config/dot/quickshell" "$config_path"
+cp "$harness_fixture" "$harness"
+printf '%s\n' \
+    "export PANAMA_HOME_ASSISTANT_URL='https://qml-old.example.test'" \
+    "export PANAMA_HOME_ASSISTANT_TOKEN=''" \
+    "export PANAMA_HOME_ASSISTANT_ENTITIES='light.old'" >"$env_file"
+chmod 0600 "$env_file"
+qml_token_file="$work/qml-token"
+printf '%s' 'qml-private-token' >"$qml_token_file"
+chmod 0600 "$qml_token_file"
+
+qs_for_test() {
+    PANAMA_HOME_ASSISTANT_ENV_FILE="$env_file" \
+        PANAMA_TEST_TOKEN_FILE="$qml_token_file" \
+        XDG_CONFIG_HOME="$work/config" XDG_STATE_HOME="$work/state" \
+        qs -p "$harness" "$@"
+}
+
+stop_harness() {
+    qs_for_test kill >/dev/null 2>&1 || true
+}
+
+qs_for_test --daemonize >/dev/null
+for _ in $(seq 1 60); do
+    qs_for_test ipc show 2>/dev/null | rg -q '^target home-assistant-config-test$' && break
+    sleep 0.1
+done
+qs_for_test ipc show 2>/dev/null | rg -q '^target home-assistant-config-test$' \
+    || fail 'credential QML harness did not start'
+
+for _ in $(seq 1 60); do
+    qml_status="$(qs_for_test ipc call home-assistant-config-test status)"
+    jq -e '.busy == false and .url == "https://qml-old.example.test"' <<<"$qml_status" >/dev/null && break
+    sleep 0.1
+done
+jq -e '.configured == false and .tokenConfigured == false and .pendingPayloadEmpty == true' \
+    <<<"$qml_status" >/dev/null || fail "QML service did not load redacted state: $qml_status"
+
+qs_for_test ipc call home-assistant-config-test saveWithToken \
+    https://qml-new.example.test 'light.office,light.hall' >/dev/null \
+    || fail 'QML service refused a private token-file update'
+for _ in $(seq 1 60); do
+    qml_status="$(qs_for_test ipc call home-assistant-config-test status)"
+    jq -e '.busy == false and .configured == true and .tokenConfigured == true
+        and .refreshCalls > 0' <<<"$qml_status" >/dev/null && break
+    sleep 0.1
+done
+jq -e '.configured == true and .tokenConfigured == true
+    and .url == "https://qml-new.example.test"
+    and .entities == ["light.office", "light.hall"]
+    and .pendingPayloadEmpty == true and .lastError == "" and .refreshCalls > 0' \
+    <<<"$qml_status" >/dev/null || fail "QML secret stdin save did not settle safely: $qml_status"
+rg -Fq 'qml-private-token' "$env_file" || fail 'QML secret stdin save did not store the token'
+if ps -o args= -p "$(qs_for_test list | awk '/Process ID:/ {print $3; exit}')" | rg -Fq 'qml-private-token'; then
+    fail 'QML token appeared in the shell process arguments'
+fi
+
+qs_for_test ipc call home-assistant-config-test save \
+    https://qml-final.example.test 'light.bedroom,light.hall' >/dev/null \
+    || fail 'QML service refused a non-secret update'
+for _ in $(seq 1 60); do
+    qml_status="$(qs_for_test ipc call home-assistant-config-test status)"
+    jq -e '.busy == false and .url == "https://qml-final.example.test"
+        and .entities == ["light.bedroom", "light.hall"]' <<<"$qml_status" >/dev/null && break
+    sleep 0.1
+done
+jq -e '.configured == true and .tokenConfigured == true
+    and .pendingPayloadEmpty == true and .lastError == ""' \
+    <<<"$qml_status" >/dev/null || fail "QML stdin save did not settle safely: $qml_status"
+rg -Fq 'qml-private-token' "$env_file" || fail 'QML non-secret save erased the stored token'
+
+qs_for_test ipc call home-assistant-config-test clearToken >/dev/null \
+    || fail 'QML service refused token clear'
+for _ in $(seq 1 60); do
+    qml_status="$(qs_for_test ipc call home-assistant-config-test status)"
+    jq -e '.busy == false and .tokenConfigured == false' <<<"$qml_status" >/dev/null && break
+    sleep 0.1
+done
+jq -e '.configured == false and .tokenConfigured == false
+    and .pendingPayloadEmpty == true and .lastError == ""' \
+    <<<"$qml_status" >/dev/null || fail "QML token clear did not settle safely: $qml_status"
+if rg -Fq 'qml-private-token' "$env_file"; then
+    fail 'QML token clear left the old token in the private env file'
+fi
+stop_harness
+
+trap - EXIT
+cleanup
+printf 'Home Assistant config contract: PASS\n'

tests/quickshell/home-assistant-helper-contract.sh

@@ -13,6 +13,20 @@ helper="$project_root/config/dot/quickshell/scripts/panama-home-assistant"
 [[ -x "$helper" ]] || fail 'helper is missing or not executable'
 
 catalog="$($helper catalog)"
+
+# This asserts a LIVE, authenticated Home Assistant. An absent credential is not
+# a defect in Panama, so it skips rather than fails -- otherwise the suite is red
+# on any machine that has not been given a token, and a red suite that is
+# expected to be red stops being read.
+#
+# A configured-but-broken bridge still fails, which is the case worth catching.
+if [[ "$(jq -r '.configured' <<<"$catalog")" != "true" ]]; then
+    printf 'Home Assistant helper contract: SKIP (no token configured)\n'
+    printf '  Set PANAMA_HOME_ASSISTANT_TOKEN in config/bash/env to exercise this.\n'
+    printf '  Reason reported by the helper: %s\n' "$(jq -r '.error // "unknown"' <<<"$catalog")"
+    exit 0
+fi
+
 jq -e '
   .ok == true and .configured == true and .error == "" and
   (.entities | type == "array" and length > 0) and

tests/quickshell/home-phone-settings-contract.sh

@@ -105,13 +105,21 @@ assert_contains 'Opens BlueBubbles' "$home_page"
 if rg -Fq 'index: model.index' "$home_page"; then
     fail 'HomePhonePage.qml reads an undefined model.index instead of the delegate index'
 fi
-if rg -qi 'token|bearer|api/states' "$home_page"; then
-    fail 'HomePhonePage.qml crosses the credential or REST privacy boundary'
+if rg -qi 'bearer|api/states' "$home_page"; then
+    fail 'HomePhonePage.qml crosses the Home Assistant REST boundary'
 fi
 assert_contains 'signal aliasCommitted(string id, string alias)' "$favorite_card"
 assert_contains 'signal removeRequested(string id)' "$favorite_card"
 assert_contains 'signal moveRequested(string id, int targetIndex)' "$favorite_card"
-assert_contains 'DragHandler {' "$favorite_card"
+assert_contains 'text: "↑"' "$favorite_card"
+assert_contains 'text: "↓"' "$favorite_card"
+assert_contains 'enabled: root.canMoveEarlier' "$favorite_card"
+assert_contains 'enabled: root.canMoveLater' "$favorite_card"
+if rg -Fq 'DragHandler {' "$favorite_card"; then
+    fail 'Home light cards still expose the broken drag affordance'
+fi
+assert_contains 'canMoveEarlier: index > 0' "$home_page"
+assert_contains 'canMoveLater: index < favoritesGrid.count - 1' "$home_page"
 assert_contains 'onEditingFinished:' "$favorite_card"
 assert_contains 'text: "Control Center"' "$favorite_card"
 assert_contains 'activeFocusOnTab: true' "$favorite_card"

tests/quickshell/home-preferences-contract.sh

@@ -96,6 +96,8 @@ assert_reset_persists_without_debounce() {
 initial_ids=' ["light.kitchen","light.hall","light.desk"]'
 expected='{"initialized":true,"favorites":[{"id":"light.desk","alias":""},{"id":"light.kitchen","alias":"Island"}],"saveError":""}'
 expected_file='{"initialized":true,"favorites":[{"id":"light.desk","alias":""},{"id":"light.kitchen","alias":"Island"}]}'
+reordered_expected='{"initialized":true,"favorites":[{"id":"light.desk","alias":""},{"id":"light.kitchen","alias":"Island"},{"id":"light.hall","alias":""}],"saveError":""}'
+reordered_file='{"initialized":true,"favorites":[{"id":"light.desk","alias":""},{"id":"light.kitchen","alias":"Island"},{"id":"light.hall","alias":""}]}'
 empty_expected='{"initialized":true,"favorites":[],"saveError":""}'
 empty_file='{"initialized":true,"favorites":[]}'
 reset_expected='{"initialized":false,"favorites":[],"saveError":""}'
@@ -106,6 +108,12 @@ start_harness
 qs_for_harness ipc call home-pref-test initialize "$initial_ids" >/dev/null
 qs_for_harness ipc call home-pref-test alias light.kitchen '  Island  ' >/dev/null
 qs_for_harness ipc call home-pref-test move light.desk 0 >/dev/null
+wait_for_status "$reordered_expected"
+wait_for_file_content "$reordered_file"
+stop_harness
+start_harness
+wait_for_status "$reordered_expected"
+
 qs_for_harness ipc call home-pref-test remove light.hall >/dev/null
 wait_for_status "$expected"
 wait_for_file_content "$expected_file"

tests/quickshell/notification-app-rules-contract.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+service="$repo_dir/config/dot/quickshell/services/Notifs.qml"
+page="$repo_dir/config/dot/quickshell/modules/settings/NotificationsPage.qml"
+harness_fixture="$repo_dir/tests/quickshell/NotificationAppRulesHarness.qml"
+desktop_entry_fixture="$repo_dir/tests/quickshell/fixtures/org.persist.App.desktop"
+
+fail() {
+    printf 'notification application rules contract: %s\n' "$1" >&2
+    exit 1
+}
+
+[[ -f "$service" ]] || fail 'notification service is missing'
+[[ -f "$page" ]] || fail 'notification settings page is missing'
+[[ -f "$harness_fixture" ]] || fail 'runtime harness fixture is missing'
+[[ -f "$desktop_entry_fixture" ]] || fail 'runtime desktop entry fixture is missing'
+
+SERVICE_PATH="$service" PAGE_PATH="$page" bun -e '
+const source = await Bun.file(process.env.SERVICE_PATH).text();
+const page = await Bun.file(process.env.PAGE_PATH).text();
+
+function fail(message) {
+    console.error(`notification application rules contract: ${message}`);
+    process.exit(1);
+}
+
+function functionBody(name) {
+    const start = source.indexOf(`function ${name}(`);
+    if (start === -1)
+        fail(`missing ${name}()`);
+    const open = source.indexOf("{", start);
+    let depth = 0;
+    for (let index = open; index < source.length; index++) {
+        if (source[index] === "{") depth++;
+        if (source[index] === "}" && --depth === 0)
+            return source.slice(open + 1, index);
+    }
+    fail(`${name}() is unterminated`);
+}
+
+const notificationAppId = Function("notification", functionBody("notificationAppId"));
+const normalizedAppRule = Function("rule", functionBody("normalizedAppRule"));
+
+const identityFixtures = [
+    { notification: { desktopEntry: "org.signal.Signal.desktop", appName: "Signal" }, expected: "org.signal.Signal.desktop" },
+    { notification: { desktopEntry: "", appName: "Terminal" }, expected: "Terminal" },
+    { notification: { desktopEntry: "", appName: "" }, expected: "Notifications" }
+];
+for (const fixture of identityFixtures) {
+    const actual = notificationAppId(fixture.notification);
+    if (actual !== fixture.expected)
+        fail(`stable app identity expected ${fixture.expected}, got ${actual}`);
+}
+
+const defaultRule = normalizedAppRule({});
+if (JSON.stringify(defaultRule) !== JSON.stringify({ enabled: true, showOnLockScreen: true, showContentOnLockScreen: true }))
+    fail(`missing rule fields did not default safely: ${JSON.stringify(defaultRule)}`);
+
+const explicitRule = normalizedAppRule({ enabled: false, showOnLockScreen: false, showContentOnLockScreen: false });
+if (JSON.stringify(explicitRule) !== JSON.stringify({ enabled: false, showOnLockScreen: false, showContentOnLockScreen: false }))
+    fail(`explicit rule was not preserved: ${JSON.stringify(explicitRule)}`);
+
+for (const required of ["rememberApplication", "appRule", "setAppRule", "handleNotification", "shouldShowOnLockScreen", "shouldShowContentOnLockScreen"]) {
+    functionBody(required);
+}
+
+const handler = source.indexOf("function handleNotification(notification: var)");
+const tracked = source.indexOf("notification.tracked = true", handler);
+const muted = source.indexOf("!root.appRule(appId).enabled", handler);
+if (handler === -1 || tracked === -1 || muted === -1 || muted > tracked)
+    fail("muted applications are not rejected before tracking/history/unread/toast work");
+if (!source.includes("root.handleNotification(notification)"))
+    fail("NotificationServer does not delegate delivery to the callable handler");
+if (!source.includes("PreferenceSchema.has(\"notificationAppRules\")"))
+    fail("the schema dependency is not explicit");
+if (!source.includes("DesktopPreferences.get(\"notificationAppRules\")"))
+    fail("rules are not read through DesktopPreferences");
+if (!source.includes("DesktopPreferences.set(\"notificationAppRules\", next)"))
+    fail("rules are not written through DesktopPreferences");
+if (!source.includes("next[knownAppId] = root.appRule(knownAppId)"))
+    fail("persisted rules are not normalized to the required three-field shape");
+if (!source.includes("root.fallbackAppRules = next"))
+    fail("missing-schema preference writes do not retain an in-memory fallback");
+if (!source.includes("if (!root.doNotDisturb)"))
+    fail("global DND popup override was removed");
+for (const required of [
+    "DesktopEntries.applications.values",
+    "DesktopEntries.byId(appId)",
+    "DesktopEntries.heuristicLookup(appId)"
+]) {
+    if (!source.includes(required))
+        fail(`persisted desktop entry ids are not reactively resolved through ${required}`);
+}
+
+for (const required of [
+    "Notifs.applications",
+    "Notifs.appRule(app.id).enabled",
+    "showOnLockScreen",
+    "showContentOnLockScreen",
+    "Notifs.setAppRule"
+]) {
+    if (!page.includes(required))
+        fail(`settings page is missing ${required}`);
+}
+
+console.log("notification application rules contract: PASS");
+'
+
+state_home="$(mktemp -d /tmp/panama-notification-rules-state.XXXXXX)"
+config_home="$(mktemp -d /tmp/panama-notification-rules-config.XXXXXX)"
+data_home="$(mktemp -d /tmp/panama-notification-rules-data.XXXXXX)"
+config_path="$state_home/quickshell"
+harness="$config_path/notification-app-rules-harness.qml"
+shell_log="$state_home/notification-app-rules.log"
+
+cleanup() {
+    if [[ -n "${bus_pid:-}" ]]; then
+        kill "$bus_pid" >/dev/null 2>&1 || true
+    fi
+    rm -rf "$state_home" "$config_home" "$data_home"
+}
+trap cleanup EXIT
+
+cp -a "$repo_dir/config/dot/quickshell" "$config_path"
+cp "$harness_fixture" "$harness"
+mkdir -p "$data_home/applications"
+cp "$desktop_entry_fixture" "$data_home/applications/org.persist.App.desktop"
+
+# This is intentionally a copy-local integration dependency. The production
+# schema is Claude's change; the runtime contract proves persistence only once
+# that key exists and never stages a schema edit from this branch.
+perl -0pi -e 's@(\n        // ── Capture)@\n        {\n            key: "notificationAppRules", type: "json", def: {}, group: "notifications", internal: true\n        },$1@' \
+    "$config_path/config/PreferenceSchema.qml"
+rg -q 'key: "notificationAppRules", type: "json"' "$config_path/config/PreferenceSchema.qml" \
+    || fail 'temporary schema integration key was not installed'
+
+mapfile -t dbus_info < <(dbus-daemon --session --fork --print-address=1 --print-pid=1)
+bus_address="${dbus_info[0]:-}"
+bus_pid="${dbus_info[1]:-}"
+[[ -n "$bus_address" && "$bus_pid" =~ ^[0-9]+$ ]] || fail 'private D-Bus session did not start'
+
+qs_for_test() {
+    DBUS_SESSION_BUS_ADDRESS="$bus_address" \
+        XDG_STATE_HOME="$state_home" XDG_CONFIG_HOME="$config_home" \
+        XDG_DATA_HOME="$data_home" XDG_DATA_DIRS="$data_home" \
+        qs -p "$harness" "$@"
+}
+
+stop_harness() {
+    qs_for_test kill >/dev/null 2>&1 || true
+    for _ in $(seq 1 40); do
+        ! qs_for_test ipc show >/dev/null 2>&1 && return
+        sleep 0.1
+    done
+    fail 'isolated notification harness did not stop cleanly'
+}
+
+start_harness() {
+    qs_for_test --daemonize >"$shell_log" 2>&1
+    for _ in $(seq 1 40); do
+        qs_for_test ipc show 2>/dev/null | rg -q '^target notification-app-rules-test$' && return
+        sleep 0.1
+    done
+    sed -n '1,240p' "$shell_log" >&2
+    fail 'isolated notification harness did not start'
+}
+
+start_harness
+exercise="$(qs_for_test ipc call notification-app-rules-test exercise)"
+jq -e '
+    .appId == "org.signal.Signal.desktop" and
+    .initialRules == {
+        "org.signal.Signal.desktop": {
+            enabled: true,
+            showOnLockScreen: true,
+            showContentOnLockScreen: true
+        }
+    } and
+    .muted == { tracked: false, history: 0, popups: 0, unread: 0 } and
+    .dnd == { tracked: true, history: 1, popups: 0, unread: 1 } and
+    .privacy == { visible: false, content: false } and
+    .fallback == {
+        id: "Fallback Terminal",
+        application: { id: "Fallback Terminal", name: "Fallback Terminal" }
+    }
+' <<<"$exercise" >/dev/null || fail "runtime notification policy fixture failed: $exercise"
+
+persisted="$(qs_for_test ipc call notification-app-rules-test persist)"
+jq -e '. == {
+    "org.persist.App.desktop": {
+        enabled: false,
+        showOnLockScreen: true,
+        showContentOnLockScreen: false
+    }
+}' <<<"$persisted" >/dev/null || fail "runtime persistence fixture wrote the wrong shape: $persisted"
+
+settings_file="$config_home/panama/settings.json"
+for _ in $(seq 1 40); do
+    [[ -f "$settings_file" ]] && jq -e '.notificationAppRules["org.persist.App.desktop"].enabled == false' "$settings_file" >/dev/null && break
+    sleep 0.1
+done
+[[ -f "$settings_file" ]] || fail 'runtime persistence fixture did not write settings.json'
+
+wait_for_persisted_application() {
+    local expected="$1"
+    local applications=""
+    for _ in $(seq 1 80); do
+        applications="$(qs_for_test ipc call notification-app-rules-test applications)"
+        if jq -e '.[] | select(.id == "org.persist.App.desktop" and .name == "Persisted Fixture App")' \
+            <<<"$applications" >/dev/null; then
+            [[ "$applications" == *"$expected"* ]] && printf '%s' "$applications" && return
+        fi
+        sleep 0.1
+    done
+    fail "persisted desktop entry did not resolve to a friendly name: $applications"
+}
+
+before_restart_applications="$(wait_for_persisted_application 'Persisted Fixture App')"
+
+stop_harness
+start_harness
+restored="$(qs_for_test ipc call notification-app-rules-test restored)"
+[[ "$restored" == "$persisted" ]] || fail "notification rules did not survive isolated restart: $restored"
+after_restart_applications="$(wait_for_persisted_application 'Persisted Fixture App')"
+[[ "$before_restart_applications" == *'"id":"org.persist.App.desktop","name":"Persisted Fixture App"'* ]] \
+    || fail "persisted application name was wrong before restart: $before_restart_applications"
+[[ "$after_restart_applications" == *'"id":"org.persist.App.desktop","name":"Persisted Fixture App"'* ]] \
+    || fail "persisted application name was wrong after restart: $after_restart_applications"
+stop_harness
+
+printf 'notification application rules runtime contract: PASS\n'

tests/quickshell/settings-backup-contract.sh

@@ -48,19 +48,21 @@ run save >/dev/null 2>&1 && fail 'backing up a missing settings file reported su
 [[ "$(run list)" == "[]" ]] || fail 'an empty backup directory did not list as empty'
 
 # ── A snapshot round-trips ───────────────────────────────────────────────────
-printf '{"gapsOut":24,"windowRounding":6}' >"$settings"
+printf '{"gapsOut":24,"windowRounding":6,"displays":{"DP-2":{"mode":"3840x2160@60","scale":2,"transform":0}}}' >"$settings"
 mkdir -p "$(dirname "$home")"
 printf '{"initialized":true,"favorites":[{"id":"light.desk","alias":"Desk"}]}' >"$home"
 run save >/dev/null || fail 'save failed on a valid settings file'
 name="$(run list | jq -r '.[0].name')"
 [[ "$name" =~ ^settings-[0-9]{8}-[0-9]{9}\.json$ ]] || fail "unexpected snapshot name: $name"
-[[ "$(run list | jq -r '.[0].keys')" == "2" ]] || fail 'snapshot key count is wrong'
+[[ "$(run list | jq -r '.[0].keys')" == "3" ]] || fail 'snapshot key count is wrong'
 
-printf '{"gapsOut":99}' >"$settings"
+printf '{"gapsOut":99,"displays":{"DP-2":{"mode":"4500x3000@60","scale":1.5,"transform":0}}}' >"$settings"
 printf '{"initialized":false,"favorites":[]}' >"$home"
 restore_result="$(run restore "$name")" || fail 'restore failed'
 [[ "$(jq -r .gapsOut "$settings")" == "24" ]] || fail 'restore did not bring back the snapshot contents'
 [[ "$(jq -r .windowRounding "$settings")" == "6" ]] || fail 'restore lost a key'
+[[ "$(jq -r '.displays["DP-2"].scale' "$settings")" == "1.5" ]] \
+    || fail 'restore bypassed display confirmation by applying snapshot geometry'
 [[ "$(jq -r '.favorites[0].id' "$home")" == "light.desk" ]] || fail 'restore did not bring back Home favourites'
 [[ "$(jq -r '.favorites[0].alias' "$home")" == "Desk" ]] || fail 'restore lost a Home alias'
 jq -e '.home.present == true and .home.data.favorites[0].id == "light.desk"' <<<"$restore_result" >/dev/null \
@@ -77,16 +79,20 @@ absent_result="$(run restore "$absent_name")" || fail 'restore failed for a snap
 jq -e '.home.present == false and (.home | has("data") | not)' <<<"$absent_result" >/dev/null \
     || fail 'restore did not return absent Home state for the live service to reload'
 
-# Desktop absence is symmetric: a Home-only snapshot removes a desktop file
-# created later and restores the Home store.
+# Desktop absence is symmetric for ordinary preferences, but confirmed display
+# geometry is protected state: it must survive even a Home-only snapshot.
 rm -f "$settings"
 printf '{"initialized":true,"favorites":[{"id":"light.porch","alias":"Porch"}]}' >"$home"
 run save >/dev/null || fail 'save failed when desktop settings were absent'
 desktop_absent_name="$(run list | jq -r '.[0].name')"
-printf '{"gapsOut":47}' >"$settings"
+printf '{"gapsOut":47,"windowRounding":9,"displays":{"DP-2":{"mode":"4500x3000@60","scale":1.5,"transform":0}}}' >"$settings"
 printf '{"initialized":false,"favorites":[]}' >"$home"
 run restore "$desktop_absent_name" >/dev/null || fail 'Home-only snapshot restore failed'
-[[ ! -e "$settings" ]] || fail 'restore did not preserve the snapshot’s absent desktop state'
+[[ -e "$settings" ]] || fail 'Home-only restore discarded confirmed display geometry'
+[[ "$(jq -r '.displays["DP-2"].scale' "$settings")" == "1.5" ]] \
+    || fail 'Home-only restore changed confirmed display geometry'
+[[ "$(jq 'keys == ["displays"]' "$settings")" == "true" ]] \
+    || fail 'Home-only restore retained ordinary desktop preferences'
 [[ "$(jq -r '.favorites[0].id' "$home")" == "light.porch" ]] \
     || fail 'Home-only snapshot did not restore Home state'
 assert_transaction_clean

tests/quickshell/settings-backup-live-contract.sh

@@ -43,6 +43,8 @@ for mapping in \
     'HomePreferences.initialize(ids);' \
     'HomePreferences.setAlias(id, alias);' \
     'DesktopPreferences.reload();' \
+    'DesktopPreferences.set("displays", value);' \
+    'Displays.externalChangeBlocked = blocked;' \
     'SystemSettings.applyPersistedDisplayPolicy();' \
     'Keybinds.applyReload();' \
     'Wallpaper.set(path);' \
@@ -82,9 +84,11 @@ jq -e '
         "home.alias:light.desk=Desk",
         "home.alias:light.office=Office",
         "desktop.reload",
+        "display.protect:{\"DP-2\":{\"mode\":\"4500x3000@60\",\"scale\":1.5,\"transform\":0}}",
         "system.apply",
         "keybinds.reload",
         "wallpaper.set:/tmp/restored-wallpaper.jpg",
+        "display.block:false",
         "shell.reload"
     ]
     and .initialized == true
@@ -118,15 +122,26 @@ jq -e '
     .calls == [
         "home.reset",
         "desktop.reload",
+        "display.protect:{\"DP-2\":{\"mode\":\"4500x3000@60\",\"scale\":1.5,\"transform\":0}}",
         "system.apply",
         "keybinds.reload",
         "wallpaper.set:/tmp/restored-wallpaper.jpg",
+        "display.block:false",
         "shell.reload"
     ]
     and .initialized == false
     and .favorites == []
 ' <<<"$status" >/dev/null || fail "absent Home handoff was wrong: $status"
 
+# Restore refuses before launching the helper while a display apply/recovery is
+# active, so no snapshot can race the confirmation boundary.
+qs_test ipc call settings-backup-behavior reset >/dev/null
+[[ "$(qs_test ipc call settings-backup-behavior restoreWhileDisplayBusy)" == "false" ]] \
+    || fail 'snapshot restore started during an active display operation'
+status="$(qs_test ipc call settings-backup-behavior status)"
+jq -e '.calls == [] and (.lastError | contains("display change"))' <<<"$status" >/dev/null \
+    || fail "display-busy restore refusal was not clean: $status"
+
 trap - EXIT
 cleanup
 printf 'settings backup live contract: PASS\n'

tests/quickshell/settings-commit-reset-contract.sh

@@ -20,10 +20,12 @@ set -euo pipefail
 repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 harness="$repo_dir/config/dot/quickshell/settings-system-harness.qml"
 system_settings="$repo_dir/config/dot/quickshell/services/SystemSettings.qml"
+wallpaper_service="$repo_dir/config/dot/quickshell/services/Wallpaper.qml"
 
 # Preferences are committed to $XDG_CONFIG_HOME, and the Home store lives under
 # $XDG_STATE_HOME. Both are isolated so this contract cannot touch the real
-# desktop's settings; the compositor is the live one and is restored below.
+# desktop's settings. The harness replaces the compositor write seam as well,
+# so interruption cannot leave the daily desktop modified.
 config_home="$(mktemp -d /tmp/panama-commit-config.XXXXXX)"
 state_home="$(mktemp -d /tmp/panama-commit-state.XXXXXX)"
 
@@ -37,22 +39,30 @@ rg -Fq 'HomePreferences.resetHomeDefaults();' "$system_settings" \
 if rg -q 'HomePreferences\.(favorites|initialized)\s*=' "$system_settings"; then
     fail 'restoreDefaults mutates Home aliases instead of using resetHomeDefaults'
 fi
+rg -Fq 'root.protectDisplays(protectedDisplays)' "$system_settings" \
+    || fail 'restoreDefaults can apply unconfirmed display geometry during reload'
+rg -Fq 'Keybinds.applyReload();' "$system_settings" \
+    || fail 'restoreDefaults does not replay shipped keybindings'
+rg -Fq 'root.applyWallpaper(String(DesktopPreferences.get("wallpaperPath") ?? ""));' "$system_settings" \
+    || fail 'restoreDefaults does not visibly reapply the shipped wallpaper'
+rg -Fq 'const effectivePath = path === "" ? root.shippedPath : path;' "$wallpaper_service" \
+    || fail 'clearing wallpaper preference leaves the old image visible'
+rg -Fq 'property string storedValue:' "$wallpaper_service" \
+    || fail 'the shipped wallpaper cannot remain represented by the default empty preference'
 
 qs_for_harness() {
-    XDG_CONFIG_HOME="$config_home" XDG_STATE_HOME="$state_home" qs -p "$harness" "$@"
+    XDG_CONFIG_HOME="$config_home" XDG_STATE_HOME="$state_home" \
+        PANAMA_SETTINGS_TEST_ISOLATE_COMPOSITOR=1 qs -p "$harness" "$@"
 }
 
-original_rounding="$(hyprctl -j getoption decoration:rounding | jq -r .int)"
-original_gaps="$(hyprctl -j getoption general:gaps_out | jq -r .css | awk '{print $1}')"
-
 restore() {
-    hyprctl eval "hl.config({ decoration = { rounding = $original_rounding }, general = { gaps_out = $original_gaps } })" >/dev/null 2>&1 || true
     qs_for_harness kill >/dev/null 2>&1 || true
     rm -rf "$config_home" "$state_home"
 }
 trap restore EXIT
 
-XDG_CONFIG_HOME="$config_home" XDG_STATE_HOME="$state_home" qs -p "$harness" --daemonize >/dev/null
+XDG_CONFIG_HOME="$config_home" XDG_STATE_HOME="$state_home" \
+    PANAMA_SETTINGS_TEST_ISOLATE_COMPOSITOR=1 qs -p "$harness" --daemonize >/dev/null
 for _ in $(seq 1 40); do
     qs_for_harness ipc show 2>/dev/null | rg -q '^target settings-system-test$' && break
     sleep 0.1
@@ -65,17 +75,13 @@ qs_for_harness ipc show 2>/dev/null | rg -q '^target settings-system-test$' || f
 [[ "$(qs_for_harness ipc call settings-system-test stored showSeconds)" == "false" ]] \
     || fail 'a local key was not stored'
 
-# ── A compositor key reaches Hyprland, then is stored ────────────────────────
-target_rounding=$(( original_rounding == 11 ? 13 : 11 ))
+# ── A compositor key reaches the verified apply boundary, then is stored ────
+target_rounding=11
 [[ "$(qs_for_harness ipc call settings-system-test commit windowRounding "$target_rounding")" == "true" ]] \
     || fail 'commitPreference refused a compositor key'
-
-for _ in $(seq 1 40); do
-    [[ "$(hyprctl -j getoption decoration:rounding | jq -r .int)" == "$target_rounding" ]] && break
-    sleep 0.1
-done
-[[ "$(hyprctl -j getoption decoration:rounding | jq -r .int)" == "$target_rounding" ]] \
-    || fail "a compositor-backed commit did not reach Hyprland (rounding=$(hyprctl -j getoption decoration:rounding | jq -r .int))"
+apply_state="$(qs_for_harness ipc call settings-system-test applyState)"
+jq -e '.[-1].windowRounding == 11' <<<"$apply_state" >/dev/null \
+    || fail "a compositor-backed commit did not reach the apply boundary: $apply_state"
 [[ "$(qs_for_harness ipc call settings-system-test stored windowRounding)" == "$target_rounding" ]] \
     || fail 'a verified compositor commit was not stored'
 
@@ -92,6 +98,9 @@ before="$(qs_for_harness ipc call settings-system-test stored windowRounding)"
 # ── Reset spans every store, not just the schema one ─────────────────────────
 qs_for_harness ipc call settings-system-test seedHome >/dev/null
 qs_for_harness ipc call settings-system-test commit dockHideDelayMs 900 >/dev/null
+display_fixture='{"DP-2":{"mode":"4500x3000@60","scale":1.5,"transform":0}}'
+[[ "$(qs_for_harness ipc call settings-system-test commit displays "$display_fixture")" == "true" ]] \
+    || fail 'the protected display fixture did not apply'
 sleep 0.4
 
 home_before="$(qs_for_harness ipc call settings-system-test homeState)"
@@ -100,24 +109,33 @@ jq -e '.count == 1 and .initialized == true' <<<"$home_before" >/dev/null \
 [[ "$(qs_for_harness ipc call settings-system-test stored dockHideDelayMs)" == "900" ]] \
     || fail 'the dock fixture did not apply'
 
-qs_for_harness ipc call settings-system-test restoreDefaults >/dev/null
+[[ "$(qs_for_harness ipc call settings-system-test restoreDefaults)" == "true" ]] \
+    || fail 'restoreDefaults refused a safe reset'
 sleep 0.6
 
+reset_state="$(qs_for_harness ipc call settings-system-test resetState)"
+jq -e '.calls == [
+    "display.block:true",
+    "display.protect",
+    "keybinds.reload",
+    "wallpaper.set:",
+    "display.block:false"
+] and .displayBlocked == false' <<<"$reset_state" >/dev/null \
+    || fail "reset did not safely replay non-reactive state: $reset_state"
+
 [[ "$(qs_for_harness ipc call settings-system-test stored dockHideDelayMs)" == "250" ]] \
     || fail 'reset did not restore a schema default'
+[[ "$(qs_for_harness ipc call settings-system-test stored displays | jq -cS .)" == "$(jq -cS . <<<"$display_fixture")" ]] \
+    || fail 'reset replaced confirmed display geometry without confirmation'
 
 home_after="$(qs_for_harness ipc call settings-system-test homeState)"
 jq -e '.count == 0 and .initialized == false' <<<"$home_after" >/dev/null \
     || fail "reset left the Home accessory store customised: $home_after"
 
-# Resetting a stored value does not by itself tell Hyprland anything, so the
-# reset must re-apply compositor-backed defaults too.
-for _ in $(seq 1 40); do
-    [[ "$(hyprctl -j getoption decoration:rounding | jq -r .int)" == "18" ]] && break
-    sleep 0.1
-done
-[[ "$(hyprctl -j getoption decoration:rounding | jq -r .int)" == "18" ]] \
-    || fail "reset did not re-apply the compositor default (rounding=$(hyprctl -j getoption decoration:rounding | jq -r .int))"
+# Resetting a stored value does not itself apply compositor policy, so the last
+# isolated batch must contain the shipped default.
+jq -e '.appliedBatches[-1].windowRounding == 18' <<<"$reset_state" >/dev/null \
+    || fail "reset did not re-apply the compositor default: $reset_state"
 
 trap - EXIT
 restore

tests/quickshell/sound-page-contract.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+
+# The Sound page is a first-class PipeWire control surface, not a launcher for
+# another settings app. This contract keeps the real device plumbing shared
+# with Quick Settings and verifies the controls that must remain available.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+sound_page="$repo_dir/config/dot/quickshell/modules/settings/SoundPage.qml"
+device_list="$repo_dir/config/dot/quickshell/modules/settings/SoundDeviceList.qml"
+device_row="$repo_dir/config/dot/quickshell/modules/settings/SoundDeviceRow.qml"
+balance="$repo_dir/config/dot/quickshell/modules/settings/AudioBalance.qml"
+audio_devices="$repo_dir/config/dot/quickshell/services/AudioDevices.qml"
+sound_feedback="$repo_dir/config/dot/quickshell/services/SoundFeedback.qml"
+quick_devices="$repo_dir/config/dot/quickshell/modules/quicksettings/AudioDeviceList.qml"
+harness="$repo_dir/config/dot/quickshell/sound-page-harness.qml"
+config_home="$(mktemp -d /tmp/panama-sound-config.XXXXXX)"
+state_home="$(mktemp -d /tmp/panama-sound-state.XXXXXX)"
+
+fail() {
+    printf 'sound page contract: %s\n' "$1" >&2
+    exit 1
+}
+
+qs_for_harness() {
+    XDG_CONFIG_HOME="$config_home" XDG_STATE_HOME="$state_home" qs -p "$harness" "$@"
+}
+
+cleanup() {
+    qs_for_harness kill >/dev/null 2>&1 || true
+    rm -rf "$config_home" "$state_home"
+}
+trap cleanup EXIT
+
+for file in "$sound_page" "$device_list" "$device_row" "$balance" "$audio_devices" "$sound_feedback" "$quick_devices"; do
+    [[ -f "$file" ]] || fail "missing ${file#"$repo_dir/"}"
+done
+
+# One shared source of truth owns device discovery and default selection.
+rg -Fq 'pragma Singleton' "$audio_devices" || fail 'audio device service is not a singleton'
+rg -Fq 'Singleton {' "$audio_devices" || fail 'audio device service has no singleton root'
+rg -Fq 'PwNodeType.AudioSource' "$audio_devices" || fail 'audio sources are not filtered by PipeWire type'
+rg -Fq 'Pipewire.preferredDefaultAudioSink = node;' "$audio_devices" || fail 'output selection does not reach PipeWire'
+rg -Fq 'Pipewire.preferredDefaultAudioSource = node;' "$audio_devices" || fail 'input selection does not reach PipeWire'
+rg -Fq 'AudioDevices.outputs' "$quick_devices" || fail 'Quick Settings does not share output discovery'
+rg -Fq 'AudioDevices.inputs' "$quick_devices" || fail 'Quick Settings does not share input discovery'
+rg -Fq 'AudioDevices.select(root.output, node)' "$quick_devices" || fail 'Quick Settings does not share device selection'
+
+# Every hardware row binds its node before reading/writing audio state.
+rg -Fq 'PwObjectTracker {' "$device_row" || fail 'device rows do not bind PipeWire objects'
+rg -Fq 'root.node.audio.muted = !root.node.audio.muted;' "$device_row" || fail 'device mute is not writable'
+rg -Fq 'root.node.audio.volume = value;' "$device_row" || fail 'per-device volume is not writable'
+rg -Fq 'PwNodePeakMonitor {' "$device_row" || fail 'input rows have no level monitor'
+rg -Fq 'enabled: !root.output && root.selected' "$device_row" || fail 'input monitoring is not scoped to the selected source'
+
+# Stereo hardware gets a real channel balance control.
+rg -Fq 'PwAudioChannel.FrontLeft' "$balance" || fail 'balance does not identify the left channel'
+rg -Fq 'PwAudioChannel.FrontRight' "$balance" || fail 'balance does not identify the right channel'
+rg -Fq 'root.node.audio.volumes = next;' "$balance" || fail 'balance does not write per-channel volume'
+
+[[ "$(rg -c 'SoundDeviceList \{' "$sound_page")" -eq 2 ]] || fail 'Sound page does not expose output and input device lists'
+rg -Fq 'AudioBalance {' "$sound_page" || fail 'Sound page has no output balance control'
+rg -Fq 'SystemSettings.openGnomePanel("sound")' "$sound_page" || fail 'advanced GNOME Sound handoff was removed'
+rg -Fq 'SoundFeedback.setEventSounds(checked)' "$sound_page" || fail 'event sounds are not controllable'
+rg -Fq 'SoundFeedback.setInputFeedback(checked)' "$sound_page" || fail 'input feedback sounds are not controllable'
+rg -Fq 'org.gnome.desktop.sound' "$sound_feedback" || fail 'sound feedback does not use the desktop sound schema'
+
+# Native bindings are the supported path. Shelling out would race the service
+# that owns these same objects and regress Quick Settings coherence.
+if rg -q '\b(Process|pactl|wpctl)\b' "$audio_devices" "$device_list" "$device_row" "$balance"; then
+    fail 'Sound controls bypass the Quickshell PipeWire service'
+fi
+
+printf 'sound page static contract: PASS\n'
+
+# Instantiate the complete page against the real, read-only PipeWire graph.
+# Merely constructing these controls must never change a default or volume.
+qs_for_harness --daemonize >/dev/null
+for _ in $(seq 1 60); do
+    qs_for_harness ipc show 2>/dev/null | rg -q '^target sound-page-test$' && break
+    sleep 0.1
+done
+qs_for_harness ipc show 2>/dev/null | rg -q '^target sound-page-test$' \
+    || fail 'Sound page harness did not start'
+
+for _ in $(seq 1 60); do
+    status="$(qs_for_harness ipc call sound-page-test status)"
+    [[ "$(jq -r .ready <<<"$status")" == "true" ]] && break
+    sleep 0.1
+done
+jq -e '.ready == true and .outputs > 0 and .inputs > 0
+    and (.defaultOutput | length > 0) and (.defaultInput | length > 0)' \
+    <<<"$status" >/dev/null \
+    || fail "real PipeWire graph was not represented: $status"
+
+trap - EXIT
+cleanup
+printf 'sound page runtime: PASS (%s outputs, %s inputs)\n' \
+    "$(jq -r .outputs <<<"$status")" "$(jq -r .inputs <<<"$status")"