companion: shown or hidden survives a restart, with a settings switch

SUPER+\ only flipped a property, so every restart of the desktop shell
brought her back. Whether she is shown is now `companion` in Prefs.qml,
set by the IPC and by a switch on a new Settings > Desktop > Companion
page. Prefs gains `ready`, so she waits for the file rather than showing
at the default and then vanishing; the greeting now plays on every
appearance, the one at login included.

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

5 files changed, 93 insertions, 20 deletions

diff --git a/desktop/Prefs.qml b/desktop/Prefs.qml
index 0ed6ee9..6340b91 100644
--- a/desktop/Prefs.qml
+++ b/desktop/Prefs.qml
@@ -45,6 +45,17 @@ Singleton {
         root.write(Object.assign({}, root.doc, { assistant: a }));
     }
 
+    // Whether the desktop companion is shown: SUPER+\ and the Companion
+    // settings page both set it, so it survives a restart. ready is false
+    // until the file has been read, so she does not show and then vanish.
+    property bool companion: true
+    property bool ready: false
+    function setCompanion(on) {
+        if (on === root.companion) return;
+        root.companion = on;
+        root.write(Object.assign({}, root.doc, { companion: on }));
+    }
+
     // The settings window's sidebar width, dragged by its edge.
     readonly property int sidebarMin: 160
     readonly property int sidebarMax: 420
@@ -103,6 +114,8 @@ Singleton {
         const w = parsed.settings ? parsed.settings.sidebar : undefined;
         root.settingsSidebar = typeof w === "number" && w >= root.sidebarMin && w <= root.sidebarMax
             ? Math.round(w) : 200;
+        root.companion = parsed.companion !== false;
+        root.ready = true;
     }
 
     FileView {
@@ -117,6 +130,6 @@ Singleton {
         onFileChanged: reload()
         onLoaded: root.reparse()
         // Missing file: the defaults, and nothing written.
-        onLoadFailed: { root.doc = {}; root.pinnedIp = ""; root.presets = null; root.settingsSidebar = 200; root.assistantModel = ""; }
+        onLoadFailed: { root.doc = {}; root.pinnedIp = ""; root.presets = null; root.settingsSidebar = 200; root.assistantModel = ""; root.companion = true; root.ready = true; }
     }
 }
diff --git a/desktop/companion/Companion.qml b/desktop/companion/Companion.qml
index e6d21e2..12dd009 100644
--- a/desktop/companion/Companion.qml
+++ b/desktop/companion/Companion.qml
@@ -30,8 +30,18 @@ PanelWindow {
 
     readonly property string art: Quickshell.env("HOME") + "/.local/share/keystone/companion/2b/frames"
 
-    // SUPER+\, through the IPC below.
-    property bool present: true
+    // SUPER+\ (the IPC below) and the Companion settings page, through Prefs,
+    // so it survives a restart.
+    readonly property bool present: Prefs.ready && Prefs.companion
+    onPresentChanged: {
+        if (root.present) {
+            root.destructAt = 0;          // the skirt is back
+            root.now = Date.now();
+            greet.restart();
+        } else {
+            root.stopMonologue();
+        }
+    }
 
     // The monitor she is on trails the focused one: a change plays her exit
     // here first, and only then moves the window (settled, below).
@@ -298,20 +308,8 @@ PanelWindow {
 
     // --- showing and hiding ----------------------------------------------
 
-    function appear() {
-        if (root.present) return;
-        root.present = true;
-        root.destructAt = 0;          // the skirt is back
-        root.now = Date.now();
-        greet.restart();
-    }
-    function dismiss() {
-        if (!root.present) return;
-        root.stopMonologue();
-        bubble.hide();
-        root.present = false;
-    }
-    // After the drop-in has landed.
+    // After the drop-in has landed, on every appearance, the one at login
+    // included.
     Timer {
         id: greet
         interval: 450
@@ -324,9 +322,9 @@ PanelWindow {
     //   qs -p <desktop> ipc call companion toggle     -> SUPER+\
     IpcHandler {
         target: "companion"
-        function toggle() { if (root.present) root.dismiss(); else root.appear(); }
-        function show() { root.appear(); }
-        function hide() { root.dismiss(); }
+        function toggle() { Prefs.setCompanion(!Prefs.companion); }
+        function show() { Prefs.setCompanion(true); }
+        function hide() { Prefs.setCompanion(false); }
     }
 
     // The exit has played on the old monitor: move, and the entrance plays.
diff --git a/desktop/companion/README.md b/desktop/companion/README.md
index cfa3ffc..4582b64 100644
--- a/desktop/companion/README.md
+++ b/desktop/companion/README.md
@@ -18,6 +18,10 @@ The design, with what was measured on the way, is
 `Figure.qml` is not `Sprite.qml` because QtQuick has a `Sprite` type, and
 it wins over the directory's own file (see AGENTS.md).
 
+Whether she is shown is `companion` in `Prefs.qml`, so it survives a
+restart: SUPER+\ and the switch on Settings > Desktop > Companion
+(`desktop/modules/companion/`) both set it.
+
 ## Art
 
 Not in the repo: the character is Square Enix's and this repo is GPLv2.
diff --git a/desktop/modules/companion/CompanionModule.qml b/desktop/modules/companion/CompanionModule.qml
new file mode 100644
index 0000000..ea6b13d
--- /dev/null
+++ b/desktop/modules/companion/CompanionModule.qml
@@ -0,0 +1,56 @@
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import QtQuick
+import "../.."
+
+// The desktop companion's one setting: whether she is shown. The same
+// preference SUPER+\ toggles, so the switch follows the key.
+Module {
+    name: "companion"
+    label: "Companion"
+    // nf-md-account_heart, present in Inconsolata Nerd Font.
+    icon: "\u{F0899}"
+    settings: true
+    group: "Desktop"
+    keywords: ["companion", "2b", "mascot", "character", "show", "hide"]
+
+    page: Component {
+        Page {
+            title: "Companion"
+            Item {
+                width: parent.width
+                height: 34
+                Text {
+                    id: lbl
+                    anchors { left: parent.left; verticalCenter: parent.verticalCenter }
+                    width: 160
+                    text: "Shown"
+                    color: Theme.subtext
+                    font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 }
+                }
+                Switch {
+                    id: sw
+                    anchors { left: lbl.right; leftMargin: 8; verticalCenter: parent.verticalCenter }
+                    checked: Prefs.companion
+                    onToggled: on => Prefs.setCompanion(on)
+                }
+                Text {
+                    anchors { left: sw.right; leftMargin: 10; right: parent.right; verticalCenter: parent.verticalCenter }
+                    elide: Text.ElideRight
+                    text: "Also SUPER+\\. Kept across restarts."
+                    color: Theme.overlay
+                    font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 5 }
+                }
+            }
+        }
+    }
+}
diff --git a/desktop/shell.qml b/desktop/shell.qml
index de190e8..4b4f47f 100644
--- a/desktop/shell.qml
+++ b/desktop/shell.qml
@@ -25,6 +25,7 @@ import "modules/qtmaildir"
 import "modules/sbbuilder"
 import "modules/bluetooth"
 import "modules/clipboard"
+import "modules/companion"
 import "modules/git"
 import "modules/kdeconnect"
 import "modules/mail"
@@ -86,6 +87,7 @@ ShellRoot {
             IconsModule {},
             SunsetModule {},
             IdleModule {},
+            CompanionModule {},
             NotificationsModule {},
             AutostartModule {},
             ObsScenesModule {},