From 54f028ed563daed9b49bf1fabee9d47060335304 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 14 Sep 2026 12:36:03 +0200 Subject: docs: the desktop shell and what the merge changed Five components become three, and the Theme symlink count with them. Two new notes: a pragma Singleton in a subdirectory resolves through a plain directory import with no qmldir, and Virsh.sampling gates only the stats poll, not the lifecycle stream that keeps the tile correct while the page is closed. --- AGENTS.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index ee37cf7..67603e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,12 +6,11 @@ Guidance for agents working in this repository. Quickshell components for a Hyprland desktop, one per directory, each a complete shell in its own right. They are not modules of a single bar: any of -them runs alone, and running one does not require the others. +them runs alone, and running one does not require the others. One of them, +`desktop/`, is itself a host for modules. - volume-osd/ volume for output and input, plus what is playing - vm-manager/ libvirt drawer: state, live stats, snapshots + desktop/ the drawer: sound, mail, VMs, appearance appearance/ wallpaper picker and colour scheme switcher - mail-overview/ notmuch unread counts per account, waybar icon and drawer window-switcher/ open windows as live previews in a grid, on ALT+TAB They are started from `~/.config/hypr/sections/autostart.lua` and keep running @@ -137,6 +136,14 @@ changing that component. The ones that generalise: not `(0, 0)`. An aspect ratio guard has to test for a positive height: the obvious rewrites, `!== 0` or a truthiness check, all pass on `-1` and produce a negative ratio. +- **A `pragma Singleton` in a subdirectory needs no `qmldir`.** A plain + directory import resolves it, the same way quickshell resolves the + `Theme.qml` symlink. Tested while merging the components: the control was a + reference to an undefined type, which warns `ReferenceError: is not + defined`, and the singleton case produced no such warning. +- **`Virsh.sampling` gates the 2s stats poll, not the whole service.** The + lifecycle event stream runs unconditionally, which is what keeps the VM list + and the tile's dots current while the page is closed. ## Theme @@ -163,7 +170,7 @@ they never had. A symlink rather than a shared import path because a singleton outside the config directory needs a `qmldir`, which is the same friction that keeps the palette parsed rather than imported; quickshell follows the link and resolves the singleton with no qmldir and no consumer change. Editing any -component's `Theme.qml` edits all five. Do not replace a link with a copy. +component's `Theme.qml` edits all three. Do not replace a link with a copy. ## Blur @@ -179,11 +186,11 @@ A panel that should sit below waybar rather than over it wants exclusive zone without the component knowing the bar's height. Measured with `hyprctl layers`: waybar at `y=-540 h=42`, a `Normal` overlay on the same screen at `y=-498 h=1038`, starting exactly where the bar ends, so the -backdrop never dims it. `mail-overview` does this; the other four use -`ExclusionMode.Ignore` and cover the whole screen. +backdrop never dims it. The `desktop` drawer does this; components that cover +the whole screen use `ExclusionMode.Ignore`. -`window-switcher` is the fifth, with namespace `quickshell-window-switcher` and -a `blur-window-switcher` rule of its own. +`window-switcher` has namespace `quickshell-window-switcher` and a +`blur-window-switcher` rule of its own. ## Reloading -- cgit v1.2.3