feat(desktop): the module contract

A module provides a tile, a page, both or neither, plus alwaysActive,
which governs the background service rather than the page: the drawer is
closed most of the time and three of four modules have background work.

1 files changed, 49 insertions, 0 deletions

diff --git a/desktop/Module.qml b/desktop/Module.qml
new file mode 100644
index 0000000..645c736
--- /dev/null
+++ b/desktop/Module.qml
@@ -0,0 +1,49 @@
+// 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
+
+// What a module declares to the drawer.
+//
+// A module provides a tile, a page, both, or neither. A tile with no page
+// calls activate() when clicked. A module with neither is a pure background
+// service. A module may also own windows outside the drawer entirely, as
+// sound does with its OSD.
+//
+// Nothing here enforces anything: a module is free to do something unusual.
+// This file is documentation with defaults.
+QtObject {
+    // Identifies the module to IPC: `ipc call drawer open <name>`.
+    required property string name
+
+    // Shown on the tile. A Nerd Font glyph.
+    property string icon: ""
+
+    // Label under the icon. Defaults to the name, capitalised.
+    property string label: name.charAt(0).toUpperCase() + name.slice(1)
+
+    // Whether this module's background service runs while the drawer is
+    // closed. The drawer is closed most of the time, so this is what decides
+    // whether the shell is cheap to run all session. It governs the service
+    // only: pages are lazily loaded either way.
+    property bool alwaysActive: false
+
+    // Rendered inside the tile, below the icon: a short state line. Null for
+    // a tile that says nothing beyond its label.
+    property Component tileContent: null
+
+    // The full-height page behind the tile. Null means the tile is
+    // fire-and-forget and activate() is called instead.
+    property Component page: null
+
+    // What a tile with no page does when clicked.
+    function activate() {}
+}