diff options
| -rw-r--r-- | docs/superpowers/plans/2026-09-15-status-registry.md | 1216 |
1 files changed, 1216 insertions, 0 deletions
diff --git a/docs/superpowers/plans/2026-09-15-status-registry.md b/docs/superpowers/plans/2026-09-15-status-registry.md new file mode 100644 index 0000000..b598129 --- /dev/null +++ b/docs/superpowers/plans/2026-09-15-status-registry.md @@ -0,0 +1,1216 @@ +# Status Registry Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A `status` singleton and drawer module owning desktop modes (`dnd`, `presentation`) as files in `$XDG_RUNTIME_DIR`, with a `statusctl` CLI so anything on the system can read, set and watch them. + +**Architecture:** One `pragma Singleton` in `shared/Status.qml`, symlinked into `desktop/`, holding a `FileView` per mode with `atomicWrites` and `watchChanges`. Modes are booleans; `presentation` additionally asserts an `IdleInhibitor`, pauses breaktimer through a `Process`, and drives `dnd` while recording the prior value. A thin drawer module renders a tile and a page over the singleton. `~/bin/statusctl` reads and writes the same files directly, so it works when the shell is down. + +**Tech Stack:** Quickshell 0.3.1, Qt6 QML, `Quickshell.Io.FileView`, `Quickshell.Wayland.IdleInhibitor`, bash, `inotifywait` (inotify-tools 4.23.9.0). + +**Spec:** `docs/superpowers/specs/2026-09-15-status-registry-design.md` + +--- + +## Global Constraints + +- Quickshell 0.3.1, Qt6 QML. Run configs with `qs -p ./desktop`. The running process is `qs`: `pkill -x qs`, `pgrep -cx qs`, never `pkill -f` (it kills the calling shell). +- GPLv2 only. Every new `.qml` file begins with this exact header, no exceptions: + +```qml +// 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. +``` + +Shell scripts use the same notice with `#` comment markers, after the shebang. + +- Module files live under `desktop/modules/status/` and reference root types (`Module`, `Page`, `Switch`, `Theme`), so each uses `import "../.."`. +- Inject the module into its tile and page under a short name, never `mod`. A component property named the same as the enclosing object's `id` binds to itself and arrives undefined. This module uses `st`. +- Reusing a `Process` needs `running = false` immediately before `running = true`. +- No em dashes anywhere. No home paths in committed files; `~` in documentation only. Nerd Font glyphs are written as `\uXXXX` in QML and their bytes verified with `git diff`. +- Every glyph must exist in Inconsolata Nerd Font and mean what it says. Check the font cmap rather than trusting a codepoint. +- Smoke-check command, harness owns the process and the log is read, never a later `pgrep`: + +```bash +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: `clean`. This briefly starts a second drawer instance; it dies with the timeout. + +## Verified Facts (probed on this machine, 2026-09-15) + +Do not re-probe these; they are measured, not assumed. + +- `$XDG_RUNTIME_DIR` is `/run/user/1000`, a tmpfs (`mode=700,uid=1000` in `/proc/mounts`). A reboot clears it. +- `elogind` runs here (PID present, `pam_elogind.so` in the PAM stack for `login`, `sddm`, `xdm`, `kde`, `loginctl list-sessions` shows a tracked session on seat0). `man 8 pam_elogind` documents removing the runtime directory at last logout but also says the module no-ops when the system was not booted with elogind as init, which on Slackware it is not. Do not claim logout clears the files. +- The compositor advertises `zwp_idle_inhibit_manager_v1` version 1 (`wayland-info`). waybar's built-in `idle_inhibitor` already drives it, so hypridle honours the Wayland path. No D-Bus inhibit needed. +- `inotifywait` is `/usr/bin/inotifywait`, version 4.23.9.0. +- No `statusctl` or `notifyctl` on PATH, no `status.*` in the runtime directory, no colliding names in `~/bin`. +- `breaktimer.sh` accepts `start stop pause resume toggle status`, keeps `running|paused` in `$XDG_RUNTIME_DIR/breaktimer.state`, and is autostarted from `autostart.lua`. The registry must never write that file, only call the verbs. +- `Theme` carries `base surface text subtext red green yellow surfaceAlt overlay accent`, plus `fontFamily`, `fontSize` (16) and `iconFamily`. +- Inconsolata Nerd Font lives in `~/.fonts/i/InconsolataNerdFont-Regular.ttf`, not under + `/usr/share/fonts` or `~/.local/share/fonts`. A cmap search that misses `~/.fonts` reports + every codepoint absent, which reads as a missing glyph rather than a bad search. The font + carries 11326 codepoints and `\uf205` is among them, confirmed with fontTools. +- The keepalive `PanelWindow` in `desktop/shell.qml` currently has **no `id`**. Task 3 adds one; `IdleInhibitor.window` needs a non-null reference. + +## Unverified, confirm during implementation + +Two claims come from the documentation and have not been observed running. Record what actually happens in the task report, and add an `AGENTS.md` trap in Task 8 for whichever bites. + +- `FileView` with `watchChanges: true` is documented to fire `fileChanged` on its own `setText()`. If so, the singleton sees its own writes and must not re-enter. Task 1 handles this with a value comparison rather than a re-entrancy flag; confirm the comparison is actually needed. +- `IdleInhibitor` is documented to need a non-null `window` to do anything. Confirm that assigning the keepalive window is sufficient and that `hyprctl clients` count changes. + +--- + +## File Structure + +| file | responsibility | +|---|---| +| `shared/Status.qml` (create) | The singleton. Mode files, read/write, effects, the DND restore rule. | +| `desktop/Status.qml` (create, symlink) | Resolves the singleton for the drawer, matching `Theme.qml`. | +| `desktop/shell.qml` (modify) | Give the keepalive window an `id`; register `StatusModule`. | +| `desktop/modules/status/StatusModule.qml` (create) | Registration, tile and page components. | +| `desktop/modules/status/StatusTile.qml` (create) | Active mode count as the tile state line. | +| `desktop/modules/status/StatusPage.qml` (create) | One row per mode with a `Switch`. | +| `desktop/modules/status/StatusRow.qml` (create) | One mode row: label, description, switch. | +| `desktop/modules/status/README.md` (create) | Module notes, per repo convention. | +| `~/bin/statusctl` (create, outside repo) | CLI: get, set, toggle, watch. | +| `desktop/modules/status/statusctl` (create) | The tracked copy of the CLI, installed to `~/bin` by the user. | +| `desktop/modules/status/test-statusctl.sh` (create) | The one runnable check. | + +`statusctl` lives in the repo and is copied to `~/bin` by the user, the same arrangement as `mail-notify.sh` and `waybar-mail.sh` under `modules/mail/`. + +--- + +### Task 1: The singleton, DND only + +**Files:** +- Create: `shared/Status.qml` +- Create: `desktop/Status.qml` (symlink) + +**Interfaces:** +- Consumes: `Quickshell.Io.FileView`. +- Produces: singleton `Status` with `readonly property bool dnd`, `function setMode(name, on)`, `function toggleMode(name)`, `readonly property int activeCount`. Tasks 2 through 6 use all of these. + +- [ ] **Step 1: Write `shared/Status.qml` with the dnd mode only** + +```qml +// 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. + +pragma Singleton + +import Quickshell +import Quickshell.Io +import QtQuick + +// Desktop modes as state. One file per mode under $XDG_RUNTIME_DIR, holding +// "0" or "1"; a missing file means off. The runtime directory is tmpfs, so a +// reboot resets every mode with no cleanup code here. +// +// The files are the interface, not this singleton: statusctl reads and writes +// them directly so it works while the shell is down, and the FileView watch +// means an external write repaints the drawer with no polling. +Singleton { + id: root + + readonly property string dir: Quickshell.env("XDG_RUNTIME_DIR") || "/tmp" + + readonly property bool dnd: dndFile.value + + // Number of modes currently on. The tile shows this. + readonly property int activeCount: (root.dnd ? 1 : 0) + + function setMode(name, on) { + if (name === "dnd") dndFile.write(on); + } + + function toggleMode(name) { + if (name === "dnd") dndFile.write(!root.dnd); + } + + // One mode file. Reads "1" as true and anything else, including a missing + // file, as false. + component ModeFile: FileView { + id: mf + + property bool value: false + + // FileView is documented to fire fileChanged on its own setText, so a + // write would re-enter this handler. Comparing before assigning makes + // that harmless: the reparse yields the value just written and the + // binding does not change. + function reparse() { + const t = mf.text().trim(); + const v = (t === "1"); + if (v !== mf.value) mf.value = v; + } + + function write(on) { + const s = on ? "1\n" : "0\n"; + mf.value = on; + mf.setText(s); + } + + watchChanges: true + printErrors: false + onFileChanged: mf.reload() + onLoaded: mf.reparse() + // A missing file is the off state, not an error worth logging. + onLoadFailed: mf.value = false + } + + ModeFile { id: dndFile; path: root.dir + "/status.dnd" } +} +``` + +- [ ] **Step 2: Create the symlink** + +```bash +ln -s ../shared/Status.qml desktop/Status.qml +ls -l desktop/Status.qml +``` + +Expected: `desktop/Status.qml -> ../shared/Status.qml`. + +- [ ] **Step 3: Smoke check that the singleton parses** + +```bash +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: `clean`. The singleton is not referenced by anything yet, so this only proves it compiles when resolved. + +- [ ] **Step 4: Commit** + +```bash +git add shared/Status.qml desktop/Status.qml +git commit -m "feat(desktop): add the status singleton with the dnd mode + +Modes live as files under XDG_RUNTIME_DIR, one per mode, holding 0 or 1, +with a missing file meaning off. That directory is tmpfs, so a reboot +resets every mode and no cleanup code is needed. + +FileView covers both directions: atomicWrites for the write, watchChanges +for the watch, so an external writer repaints the drawer with no polling. +The documented behaviour is that a FileView fires its own fileChanged on +setText, so the reparse compares before assigning and a self-write is a +no-op rather than a loop." +``` + +--- + +### Task 2: The statusctl CLI + +**Files:** +- Create: `desktop/modules/status/statusctl` +- Test: `desktop/modules/status/test-statusctl.sh` + +**Interfaces:** +- Consumes: the file format from Task 1 (`0`/`1`, missing means off). +- Produces: `statusctl <mode> get|set|toggle|watch`. Task 7 installs it and wires waybar to `watch` and `toggle`. + +- [ ] **Step 1: Write the failing test** + +```bash +mkdir -p desktop/modules/status +cat > desktop/modules/status/test-statusctl.sh <<'SCRIPT' +#!/bin/bash +# +# 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. +# +# The one runnable check for statusctl. It points XDG_RUNTIME_DIR at a +# temporary directory, so nothing here touches the live modes. +# +# Usage: ./test-statusctl.sh (exit 0 = all passed) + +set -u + +here="$(cd "$(dirname "$0")" && pwd)" +ctl="$here/statusctl" +tmp="$(mktemp -d)" +trap 'rm -rf "$tmp"' EXIT +export XDG_RUNTIME_DIR="$tmp" + +pass=0 +fail=0 + +check() { + local label="$1" want="$2" got="$3" + if [[ "$want" == "$got" ]]; then + printf 'ok %s\n' "$label" + pass=$((pass + 1)) + else + printf 'FAIL %s: want %q, got %q\n' "$label" "$want" "$got" + fail=$((fail + 1)) + fi +} + +# A mode with no file reads as off. +check "missing file reads 0" "0" "$("$ctl" dnd get)" + +# set writes the file and get reads it back. +"$ctl" dnd set 1 +check "set 1 writes the file" "1" "$(cat "$tmp/status.dnd" | tr -d '[:space:]')" +check "get after set 1" "1" "$("$ctl" dnd get)" + +# toggle flips it. +"$ctl" dnd toggle +check "toggle from 1" "0" "$("$ctl" dnd get)" +"$ctl" dnd toggle +check "toggle from 0" "1" "$("$ctl" dnd get)" + +# set 0 writes rather than removing, so a reader sees an explicit off. +"$ctl" dnd set 0 +check "set 0 writes the file" "0" "$("$ctl" dnd get)" + +# An unknown mode is an error, not a silent success: a typo must not look +# like a mode that is off. +"$ctl" nosuch get >/dev/null 2>&1 +check "unknown mode exits non-zero" "1" "$?" + +# watch prints a line on change, and the class reflects the value. The +# atomic write arrives as a rename, which is why the watch needs moved_to. +out="$tmp/watch.out" +"$ctl" presentation watch > "$out" 2>/dev/null & +watcher=$! +sleep 0.3 +"$ctl" presentation set 1 +sleep 0.5 +kill "$watcher" 2>/dev/null +wait "$watcher" 2>/dev/null +check "watch reports activated" "1" "$(grep -c '"class": *"activated"' "$out")" + +# A missing file is reported as down, distinct from a mode that is off. +rm -f "$tmp/status.presentation" +out2="$tmp/watch2.out" +"$ctl" presentation watch > "$out2" 2>/dev/null & +watcher2=$! +sleep 0.5 +kill "$watcher2" 2>/dev/null +wait "$watcher2" 2>/dev/null +check "watch reports down when absent" "1" "$(grep -c '"class": *"down"' "$out2")" + +printf '\n%d passed, %d failed\n' "$pass" "$fail" +[[ "$fail" -eq 0 ]] +SCRIPT +chmod +x desktop/modules/status/test-statusctl.sh +``` + +- [ ] **Step 2: Run it to verify it fails** + +```bash +bash desktop/modules/status/test-statusctl.sh +``` + +Expected: every check fails, because `statusctl` does not exist. The first line reads `FAIL missing file reads 0`. + +- [ ] **Step 3: Write `statusctl`** + +```bash +cat > desktop/modules/status/statusctl <<'SCRIPT' +#!/bin/bash +# +# 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. +# +# Read, set and watch desktop modes. The modes are files under +# XDG_RUNTIME_DIR holding 0 or 1; a missing file means off. +# +# This talks to the files, not to the shell, so it works while quickshell is +# down. Setting a mode that way records the state without firing its effects; +# the shell sees the change through its own watch and reasserts them. +# +# statusctl <mode> get prints 0 or 1 +# statusctl <mode> set 0|1 +# statusctl <mode> toggle +# statusctl <mode> watch waybar JSON on every change + +set -u + +MODES="dnd presentation" +DIR="${XDG_RUNTIME_DIR:-/tmp}" + +usage() { + printf 'usage: %s <%s> <get|set 0|1|toggle|watch>\n' \ + "${0##*/}" "$(printf '%s' "$MODES" | tr ' ' '|')" >&2 + exit 1 +} + +[[ $# -ge 2 ]] || usage + +mode="$1" +action="$2" + +# A typo must fail loudly rather than read as a mode that happens to be off. +case " $MODES " in + *" $mode "*) ;; + *) printf '%s: unknown mode: %s\n' "${0##*/}" "$mode" >&2; exit 1 ;; +esac + +file="$DIR/status.$mode" + +read_mode() { + local v + v="$(cat "$file" 2>/dev/null | tr -d '[:space:]')" + [[ "$v" == "1" ]] && printf '1' || printf '0' +} + +# Write through a temporary file and rename, so no reader ever sees a +# half-written value. This is also what FileView does on the QML side, and it +# is why a watcher has to listen for moved_to as well as close_write. +write_mode() { + local want="$1" tmp + tmp="$(mktemp "$DIR/.status.$mode.XXXXXX")" || exit 1 + printf '%s\n' "$want" > "$tmp" + mv -f "$tmp" "$file" +} + +emit() { + local state="$1" + printf '{"text": "", "alt": "%s", "class": "%s", "tooltip": "%s"}\n' \ + "$state" "$state" "$(tooltip "$state")" +} + +tooltip() { + case "$1" in + activated) printf '%s: on' "$mode" ;; + deactivated) printf '%s: off' "$mode" ;; + down) printf '%s: no state file' "$mode" ;; + esac +} + +state_now() { + [[ -e "$file" ]] || { printf 'down'; return; } + [[ "$(read_mode)" == "1" ]] && printf 'activated' || printf 'deactivated' +} + +case "$action" in + get) + read_mode + printf '\n' + ;; + set) + [[ $# -eq 3 ]] || usage + case "$3" in + 0|1) write_mode "$3" ;; + *) usage ;; + esac + ;; + toggle) + [[ "$(read_mode)" == "1" ]] && write_mode 0 || write_mode 1 + ;; + watch) + emit "$(state_now)" + # Watch the directory rather than the file: an atomic write replaces + # the file, so a watch held on the old inode dies with it. This is the + # same trap the mail watcher hit with Xapian. + inotifywait -q -m -e close_write,moved_to,delete --format '%f' "$DIR" 2>/dev/null | + while read -r changed; do + [[ "$changed" == "status.$mode" ]] || continue + emit "$(state_now)" + done + ;; + *) + usage + ;; +esac +SCRIPT +chmod +x desktop/modules/status/statusctl +``` + +- [ ] **Step 4: Run the test to verify it passes** + +```bash +bash desktop/modules/status/test-statusctl.sh +``` + +Expected: `8 passed, 0 failed`, exit 0. + +- [ ] **Step 5: Commit** + +```bash +git add desktop/modules/status/statusctl desktop/modules/status/test-statusctl.sh +git commit -m "feat(desktop): add the statusctl CLI and its check + +statusctl reads and writes the mode files directly rather than going +through the shell, so it works while quickshell is down. Setting a mode +that way records the state without firing its effects; the shell sees the +change through its own watch and reasserts them. + +The watch listens on the directory, not the file: an atomic write replaces +the file, so a watch held on the old inode dies with it. Same trap the mail +watcher hit with Xapian, and the reason moved_to is in the event list. + +An unknown mode exits non-zero rather than reading as off, so a typo +cannot masquerade as a mode that happens to be disabled." +``` + +--- + +### Task 3: Give the keepalive window an id + +**Files:** +- Modify: `desktop/shell.qml:26-34` + +**Interfaces:** +- Produces: `keepalive`, referenced by `IdleInhibitor.window` in Task 4. Nothing else changes. + +- [ ] **Step 1: Add the id** + +In `desktop/shell.qml`, the keepalive `PanelWindow` currently opens with `visible: true`. Add an `id` as its first line and extend the comment: + +```qml + // Quickshell exits once no window is visible, and the drawer is closed + // most of the time. See AGENTS.md. + // + // It is also the window the idle inhibitor attaches to: IdleInhibitor + // needs a non-null window, and this is the one window that exists for + // the whole life of the shell. + PanelWindow { + id: keepalive + visible: true + implicitWidth: 1 + implicitHeight: 1 + color: "transparent" + exclusionMode: ExclusionMode.Ignore + mask: Region {} + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None + } +``` + +- [ ] **Step 2: Smoke check** + +```bash +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: `clean`. + +- [ ] **Step 3: Commit** + +```bash +git add desktop/shell.qml +git commit -m "refactor(desktop): name the keepalive window + +IdleInhibitor needs a non-null window and this is the only one that lives +for the whole session, so presentation mode attaches to it. Naming it is a +prerequisite for that and changes nothing else." +``` + +--- + +### Task 4: Presentation mode and its effects + +**Files:** +- Modify: `shared/Status.qml` +- Modify: `desktop/shell.qml` (pass the keepalive window to the singleton) + +**Interfaces:** +- Consumes: `keepalive` from Task 3, `breaktimer.sh`. +- Produces: `Status.presentation`, `Status.inhibitWindow` (write-once from `shell.qml`), and the DND restore rule. Tasks 5 and 6 render these. + +- [ ] **Step 1: Add the presentation mode, the effects, and the restore rule** + +Replace the body of `shared/Status.qml` after the header with this. The `ModeFile` component is unchanged from Task 1; the additions are the second `ModeFile`, `inhibitWindow`, the `IdleInhibitor`, the breaktimer `Process`, and the `setMode` logic. + +```qml +pragma Singleton + +import Quickshell +import Quickshell.Io +import Quickshell.Wayland +import QtQuick + +// Desktop modes as state. One file per mode under $XDG_RUNTIME_DIR, holding +// "0" or "1"; a missing file means off. The runtime directory is tmpfs, so a +// reboot resets every mode with no cleanup code here. +// +// The files are the interface, not this singleton: statusctl reads and writes +// them directly so it works while the shell is down, and the FileView watch +// means an external write repaints the drawer with no polling. It also means +// a mode set from outside still fires its effects, because the watch reaches +// the same handler a tile click would. +Singleton { + id: root + + readonly property string dir: Quickshell.env("XDG_RUNTIME_DIR") || "/tmp" + + readonly property bool dnd: dndFile.value + readonly property bool presentation: presFile.value + + readonly property int activeCount: (root.dnd ? 1 : 0) + (root.presentation ? 1 : 0) + + // Set once by shell.qml. IdleInhibitor does nothing with a null window, + // and the singleton has no window of its own to offer. + property var inhibitWindow: null + + // What dnd was before presentation mode turned it on, so turning + // presentation mode off restores it rather than clearing it. Held here + // rather than in a file: it is meaningful only while presentation mode is + // on, and presentation mode does not survive a reboot. + property bool dndBeforePresentation: false + + function setMode(name, on) { + if (name === "dnd") { + dndFile.write(on); + } else if (name === "presentation") { + presFile.write(on); + } + } + + function toggleMode(name) { + if (name === "dnd") root.setMode("dnd", !root.dnd); + else if (name === "presentation") root.setMode("presentation", !root.presentation); + } + + // Effects follow the mode rather than the setter, so a mode set by + // statusctl while the drawer is closed asserts them too. + onPresentationChanged: { + if (root.presentation) { + root.dndBeforePresentation = root.dnd; + root.setMode("dnd", true); + root.runBreaktimer("pause"); + } else { + root.setMode("dnd", root.dndBeforePresentation); + root.runBreaktimer("resume"); + } + } + + function runBreaktimer(verb) { + breakProc.command = ["breaktimer.sh", verb]; + breakProc.running = false; + breakProc.running = true; + } + + // breaktimer owns its own state file; this only calls its verbs. Two + // writers on that file would race with its daemon loop, which rewrites it + // on every phase change. + Process { id: breakProc } + + // Wayland idle inhibit. The compositor advertises + // zwp_idle_inhibit_manager_v1 and hypridle honours it, so no D-Bus path + // is needed even though elogind runs here. + IdleInhibitor { + window: root.inhibitWindow + enabled: root.presentation && root.inhibitWindow !== null + } + + component ModeFile: FileView { + id: mf + + property bool value: false + + // FileView is documented to fire fileChanged on its own setText, so a + // write would re-enter this handler. Comparing before assigning makes + // that harmless: the reparse yields the value just written and the + // binding does not change. + function reparse() { + const t = mf.text().trim(); + const v = (t === "1"); + if (v !== mf.value) mf.value = v; + } + + function write(on) { + const s = on ? "1\n" : "0\n"; + mf.value = on; + mf.setText(s); + } + + watchChanges: true + printErrors: false + onFileChanged: mf.reload() + onLoaded: mf.reparse() + // A missing file is the off state, not an error worth logging. + onLoadFailed: mf.value = false + } + + ModeFile { id: dndFile; path: root.dir + "/status.dnd" } + ModeFile { id: presFile; path: root.dir + "/status.presentation" } +} +``` + +- [ ] **Step 2: Hand the keepalive window to the singleton** + +In `desktop/shell.qml`, inside the `PanelWindow` from Task 3, add a completion handler as its last line before the closing brace: + +```qml + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None + + // The singleton has no window of its own and IdleInhibitor needs one. + Component.onCompleted: Status.inhibitWindow = keepalive + } +``` + +- [ ] **Step 3: Smoke check** + +```bash +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: `clean`. + +- [ ] **Step 4: Confirm the effects fire, with the live shell** + +This needs the user's running shell, not the transient smoke instance. Ask the user to restart their drawer (`pkill -x qs` then the three `qs` lines from `autostart.lua`, or a logout), then run: + +```bash +statusctl_path=desktop/modules/status/statusctl +bash "$statusctl_path" presentation set 1 +sleep 1 +echo "dnd now: $(bash "$statusctl_path" dnd get) (expect 1)" +~/bin/breaktimer.sh status +hyprctl clients | grep -ci inhibit +bash "$statusctl_path" presentation set 0 +sleep 1 +echo "dnd now: $(bash "$statusctl_path" dnd get) (expect 0)" +~/bin/breaktimer.sh status +``` + +Expected: `dnd now: 1`, breaktimer reports `paused`, the inhibitor count rises by one, then `dnd now: 0` and breaktimer reports `running`. Record the actual inhibitor counts in the task report; if the count does not change, the `IdleInhibitor` assumption is wrong and Task 8 gets a trap saying so. + +- [ ] **Step 5: Commit** + +```bash +git add shared/Status.qml desktop/shell.qml +git commit -m "feat(desktop): add presentation mode and its effects + +Presentation mode sets DND, asserts a Wayland idle inhibitor and pauses +breaktimer. The effects hang off the mode property rather than the setter, +so a mode set with statusctl while the drawer is closed asserts them too. + +DND has two writers once presentation mode exists, so turning presentation +off restores the value DND had before rather than clearing it, or an +afternoon of hand-set DND would vanish when a talk ends. That prior value +lives in the singleton, not in a file: it means nothing once presentation +mode is off, and presentation mode does not survive a reboot. + +breaktimer owns its own state file and is driven only through its verbs. +Two writers on that file would race with its daemon loop." +``` + +--- + +### Task 5: The module, tile and row + +**Files:** +- Create: `desktop/modules/status/StatusModule.qml` +- Create: `desktop/modules/status/StatusTile.qml` +- Create: `desktop/modules/status/StatusRow.qml` + +**Interfaces:** +- Consumes: `Status`, the `Module`, `Tile`, `Switch`, `Theme` root types. +- Produces: `StatusModule` with `name: "status"`, injected into its children as `st`. Task 6 adds the page and registers the module. + +- [ ] **Step 1: Create `StatusModule.qml`** + +```qml +// 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 "../.." + +// Always active: the singleton holds the modes and their effects, and those +// have to be asserted whether or not anyone has opened the drawer. The module +// itself is thin, a tile and a page over Status. +Module { + id: mod + + name: "status" + label: "Status" + alwaysActive: true + + // A toggle glyph, present in Inconsolata Nerd Font. + icon: "\uf205" + + // The tile renders in its accent while any mode is on. + active: Status.activeCount > 0 + + tileContent: Component { StatusTile { st: mod } } + + page: Component { + Page { + title: "Status" + StatusPage { width: parent.width } + } + } +} +``` + +- [ ] **Step 2: Create `StatusTile.qml`** + +```qml +// 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 "../.." + +// Injected as st, never mod: a property named the same as the enclosing +// object's id binds to itself and arrives undefined. See AGENTS.md. +Text { + required property var st + + width: parent ? parent.width : implicitWidth + elide: Text.ElideRight + font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 } + color: Status.activeCount > 0 ? Theme.text : Theme.subtext + text: Status.presentation ? "Presenting" + : Status.dnd ? "Do not disturb" + : "All clear" +} +``` + +- [ ] **Step 3: Create `StatusRow.qml`** + +```qml +// 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 "../.." + +// One mode: a label, a line saying what it does, and a switch. +Item { + id: row + + required property string mode + required property string label + required property string description + required property bool value + + implicitHeight: Math.max(texts.implicitHeight, sw.implicitHeight) + 16 + + Column { + id: texts + anchors { + left: parent.left + right: sw.left; rightMargin: 12 + verticalCenter: parent.verticalCenter + } + spacing: 2 + + Text { + text: row.label + font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2; bold: true } + color: Theme.text + } + + Text { + width: parent.width + wrapMode: Text.WordWrap + text: row.description + font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 } + color: Theme.subtext + } + } + + Switch { + id: sw + anchors { right: parent.right; verticalCenter: parent.verticalCenter } + checked: row.value + onToggled: Status.toggleMode(row.mode) + } +} +``` + +- [ ] **Step 4: Smoke check** + +```bash +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: `clean`. `StatusPage` does not exist yet, but the page `Component` is lazily loaded, so nothing instantiates it. + +- [ ] **Step 5: Commit** + +```bash +git add desktop/modules/status/StatusModule.qml desktop/modules/status/StatusTile.qml desktop/modules/status/StatusRow.qml +git commit -m "feat(desktop): add the status module, tile and row + +The module is thin because the singleton owns the modes: it is a tile and +a page over Status, always active so the effects hold whether or not the +drawer has been opened. + +Injected as st rather than mod, since a component property named the same +as the enclosing object's id binds to itself and arrives undefined." +``` + +--- + +### Task 6: The page, and register the module + +**Files:** +- Create: `desktop/modules/status/StatusPage.qml` +- Modify: `desktop/shell.qml` (import and module registry) + +**Interfaces:** +- Consumes: `StatusRow`, `Status`. +- Produces: the finished module in the drawer grid. + +- [ ] **Step 1: Create `StatusPage.qml`** + +```qml +// 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 "../.." + +// One row per mode. Adding a mode is one file in the singleton and one row +// here, which is the point of a registry rather than two toggles. +Column { + id: page + + spacing: 4 + + StatusRow { + width: page.width + mode: "dnd" + label: "Do not disturb" + description: "Silences notification popups. Critical ones still appear." + value: Status.dnd + } + + Rectangle { + width: page.width + height: 1 + color: Qt.alpha(Theme.text, 0.08) + } + + StatusRow { + width: page.width + mode: "presentation" + label: "Presentation" + description: "Do not disturb, no screen lock, breaktimer paused." + value: Status.presentation + } +} +``` + +- [ ] **Step 2: Register the module in `desktop/shell.qml`** + +Add the import beside the others, keeping them alphabetical: + +```qml +import "modules/sound" +import "modules/status" +import "modules/vm" +``` + +Add the module to the registry. Status goes last before `VmModule`, so the grid reads Sound, Network, Bluetooth, KdeConnect, Mail, Appearance, Status, Machines: + +```qml + modules: [ + SoundModule {}, + NetworkModule {}, + BluetoothModule {}, + KdeConnectModule {}, + MailModule {}, + AppearanceModule {}, + StatusModule {}, + VmModule {}, + ] +``` + +- [ ] **Step 3: Smoke check** + +```bash +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: `clean`. + +- [ ] **Step 4: Confirm the page renders and the switches drive the modes** + +Hot reload does not pick up a new component file until something that imports the directory reloads, and `shell.qml` was just edited, so the rescan has happened. Ask the user to open the drawer, open the Status page, and confirm: two rows with switches, the tile reads "All clear" when both are off, toggling Do not disturb makes the tile read "Do not disturb", toggling Presentation makes it read "Presenting" and flips the DND switch on as well. + +Then confirm the file side agrees: + +```bash +cat /run/user/1000/status.dnd /run/user/1000/status.presentation +``` + +Expected: the values match what the switches show. + +- [ ] **Step 5: Commit** + +```bash +git add desktop/modules/status/StatusPage.qml desktop/shell.qml +git commit -m "feat(desktop): add the status page and register the module + +One row per mode. Adding a mode is one file in the singleton and one row +here, which is what a registry buys over two separate toggles." +``` + +--- + +### Task 7: Install the CLI and swap the waybar module + +**Files:** +- Modify outside the repo: `~/bin/statusctl` (user installs), the live waybar configuration (user applies) + +**Interfaces:** +- Consumes: `statusctl` from Task 2. +- Produces: nothing executable in the repo. + +- [ ] **Step 1: Ask the user to install the CLI** + +The repo copy is the source; `~/bin` is not in this repository. Ask the user to run: + +```bash +install -m 755 desktop/modules/status/statusctl ~/bin/statusctl +statusctl dnd get +``` + +Expected: `0` or `1`, not a "command not found". + +- [ ] **Step 2: Ask the user to replace the waybar idle_inhibitor module** + +waybar's built-in `idle_inhibitor` owns its own inhibitor object and cannot indicate a mode owned elsewhere. Left running alongside the registry it asserts a second, independent inhibitor, and idle then resumes only when both release. + +Ask the user to create `~/.config/waybar/modules/custom/presentation.jsonc`: + +```jsonc +{ + "custom/presentation": { + "exec": "~/bin/statusctl presentation watch", + "return-type": "json", + "on-click": "~/bin/statusctl presentation toggle", + "format": "{icon}", + "format-icons": { + "activated": " ", + "deactivated": " ", + "down": " " + }, + "tooltip": true + } +} +``` + +The two glyphs are the ones the built-in module already uses, copied from `~/.config/waybar/modules/idle_inhibitor.jsonc` so the bar does not change appearance. They carry trailing variation selectors; copy the bytes rather than retyping them. + +Then in `~/.config/waybar/config.jsonc`: replace the `idle_inhibitor.jsonc` include with the new file, and replace `"idle_inhibitor"` in the module list with `"custom/presentation"`. Reload waybar. + +Record in the task report which lines changed, so the change is traceable. + +- [ ] **Step 3: Confirm the bar and the drawer agree** + +Ask the user to click the waybar glyph and confirm the drawer's Status page switch follows, then toggle the drawer switch and confirm the bar glyph follows. This is the whole point of the file being the interface, and it is the one check that exercises both directions. + +- [ ] **Step 4: Confirm only one inhibitor is asserted** + +```bash +hyprctl clients | grep -ci inhibit +``` + +Ask the user to run this with presentation mode off, then on. Expected: the count rises by exactly one, not two. Two would mean the built-in waybar module is still running. + +--- + +### Task 8: README, traps, final check + +**Files:** +- Create: `desktop/modules/status/README.md` +- Modify: `AGENTS.md` + +**Interfaces:** +- Consumes: the finished module. +- Produces: nothing executable. + +- [ ] **Step 1: Write `desktop/modules/status/README.md`** + +```markdown +# status + +Desktop modes as state: `dnd` and `presentation`, owned by the `Status` +singleton and stored as files under `$XDG_RUNTIME_DIR`. + +## The files are the interface + + $XDG_RUNTIME_DIR/status.dnd + $XDG_RUNTIME_DIR/status.presentation + +Each holds `0` or `1`; a missing file means off. That directory is tmpfs, so a +reboot resets every mode and there is no cleanup code. A shell restart does +not: the files outlive the process and the singleton reads them back. + +Anything can read a mode with `cat`. `statusctl` is the convenience, not the +mechanism, which is why it keeps working while quickshell is down. + +## statusctl + + statusctl <mode> get prints 0 or 1 + statusctl <mode> set 0|1 + statusctl <mode> toggle + statusctl <mode> watch waybar JSON on every change + +The repo copy is the source; the user installs it to `~/bin`. `watch` watches +the directory rather than the file, because an atomic write replaces the file +and a watch on the old inode dies with it. + +Setting a mode with `statusctl` records the state without firing its effects. +The shell sees the change through its own `FileView` watch and asserts them, +so the effects follow either way. If the shell is down, the state is recorded +and reasserted when it returns. + +## Effects + +`dnd` has none of its own. It is state the notification daemon reads. + +`presentation` sets `dnd`, asserts a Wayland idle inhibitor, and pauses +breaktimer. Turning it off restores `dnd` to the value it had before rather +than clearing it, so hand-set DND survives a presentation. + +breaktimer owns `$XDG_RUNTIME_DIR/breaktimer.state`. This module calls +`breaktimer.sh pause|resume` and never writes that file: its daemon loop +rewrites it on every phase change, and two writers would race. + +## Waybar + +`custom/presentation` reads `statusctl presentation watch`. It replaces +waybar's built-in `idle_inhibitor`, which cannot be kept alongside it: that +module owns its own inhibitor object, so both would have to be released +before the screen could lock. + +## The check + + ./test-statusctl.sh + +Points `XDG_RUNTIME_DIR` at a temporary directory, so it never touches live +modes. Covers the file format, the atomic write, the toggle, the unknown-mode +error and both watch states. +``` + +- [ ] **Step 2: Add the traps to `AGENTS.md`** + +Append to the per-component notes list, plus whichever of the two unverified claims actually bit during Task 4: + +```markdown +- **A `FileView` that writes the file it watches sees its own write.** + `watchChanges` fires `fileChanged` on `setText()` as well as on an external + change, so a handler that writes in response to a change loops. The status + registry compares the reparsed value against the current one and assigns + only on a difference, which makes the self-write a no-op. +- **`IdleInhibitor` needs a non-null `window`.** It has no window of its own + and does nothing without one. A singleton therefore cannot assert an + inhibitor unaided: `shell.qml` hands it the keepalive `PanelWindow`, which + is the one window that exists for the whole session. +``` + +- [ ] **Step 3: Run every check** + +```bash +bash desktop/modules/status/test-statusctl.sh +bash desktop/modules/mail/test-mail-notify.sh +bash desktop/modules/kdeconnect/test-kdeconnect-state.sh +timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean" +``` + +Expected: statusctl `8 passed, 0 failed`; mail 16 of 16; kdeconnect 5 of 5; `clean`. + +- [ ] **Step 4: Confirm the process count** + +```bash +pgrep -cx qs +``` + +Expected: the shells the user has running, normally three. Run this after the smoke check has returned, never against a detached process from an earlier call. + +- [ ] **Step 5: Ask the user for the final visual pass** + +Ask the user to confirm: the Status tile sits between Appearance and Machines; it reads "All clear", "Do not disturb" or "Presenting" as the modes change; the page has two rows with working switches; turning Presentation on flips DND on and turning it off restores DND to what it was; the waybar glyph and the drawer switch follow each other. + +- [ ] **Step 6: Commit** + +```bash +git add desktop/modules/status/README.md AGENTS.md +git commit -m "docs(status): document the module and record its traps + +A FileView fires its own fileChanged on setText, so a handler that writes +in response to a change loops unless it compares first. IdleInhibitor has +no window of its own and does nothing without one, so the singleton is +handed the keepalive window by shell.qml. + +Both were read from the documentation while designing and confirmed while +implementing." +``` + +--- + +## Notes for the implementer + +**Do not write `breaktimer.state`.** The breaktimer daemon rewrites it on every phase change. Call `breaktimer.sh pause|resume` and let it own its file. + +**The effects hang off the mode property, not the setter.** This is deliberate: `statusctl presentation set 1` writes a file the shell is watching, and the effects must fire from that path as well as from a tile click. If you move the effects into `setMode`, a mode set from the CLI records state and does nothing. + +**The glyph in `StatusModule.qml` is `\uf205`.** It is present in Inconsolata Nerd Font, confirmed against the cmap, so the only open question is whether it reads as a toggle at tile size. Confirm that visually with the user; if it does not, pick another and check the cmap at the path in Verified Facts. + +**`statusctl watch` emits an immediate line before entering the loop.** waybar needs a value at startup, not only on the first change. |