From 04affa132b7269ddc36d4be6aeee508515723fdc Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Sat, 12 Sep 2026 10:25:04 +0200 Subject: docs: add mail-overview to the inventory and its traps to the notes Four of the notes generalise beyond this component. Two were measured while building it: notmuch fails two different ways and only the rejected-query case is detectable, the misparsed-query case returning a plausible wrong number with exit 0; and notmuch deduplicates by message id, so one message with two file paths is counted twice by a path glob and per-account counts then sum above the total. Two more were bugs found only by running the thing. Xapian replaces files on commit, so a watch on a filename dies with it and the watch belongs on the directory. And an INI section body is not everything up to the next bracket, because values can contain brackets themselves: folders named [Gmail]/Bozze ended a section before its label and three of five accounts quietly displayed their raw key instead. The Blur section gains the exclusion-zone note with its measured geometry, since mail-overview is the first panel here that sits below waybar rather than over it. The "Both" phrasing that assumed two components is now plural. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01WWL8JYHu7yhAdtx5pU9PMU --- AGENTS.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index cbd9139..4ef879f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,20 +11,21 @@ them runs alone, and running one does not require the others. volume-osd/ volume for output and input, plus what is playing vm-manager/ libvirt drawer: state, live stats, snapshots appearance/ wallpaper picker and colour scheme switcher + mail-overview/ notmuch unread counts per account, waybar icon and drawer -Both are started from `~/.config/hypr/sections/autostart.lua` and keep running +They are started from `~/.config/hypr/sections/autostart.lua` and keep running for the whole session. ## The rule that bites first -**A quickshell config with no visible window exits.** Both components here are +**A quickshell config with no visible window exits.** These components are hidden most of the time, so each holds itself open with a 1x1 transparent `PanelWindow` with `mask: Region {}`, which is click-through and draws nothing. Without it the shell loads, logs `Configuration Loaded`, reports no error, and quits. The symptom is never an error message: it is a keybind that appears to do nothing, or a panel that never paints. This was removed once during -development because a process check was measuring the wrong thing, and both +development because a process check was measuring the wrong thing, and two components broke in exactly that way. Any new component needs the same window. ## Verifying, and how not to @@ -76,6 +77,26 @@ changing that component. The ones that generalise: - **Assigning `running = true` to a `Process` that is already running does nothing.** Reusing one `Process` for a sequence of commands needs `running = false` immediately before each start. +- **`notmuch` fails two different ways and only one is detectable.** A + rejected query prints nothing and exits 1; a query Xapian merely misparses + returns a plausible wrong number and exits 0 (`tag:unread and ((` gave 41). + Validate the output as an integer, which catches the first, where empty + output would otherwise render as an empty inbox. Nothing catches the second, + so keep such queries as fixed strings. +- **notmuch deduplicates by message id, so one message can have several + paths.** A message that arrived at two configured addresses is counted by + both accounts under a `path:` glob, and per-account counts then sum above the + total. The `account-*` tag is a property of the message, so it is singular. +- **Xapian replaces files on commit.** A watch held on a filename inside the + database directory dies with the file; watch the directory for + `close_write,moved_to` instead, and debounce, because one commit touches + several files. +- **An INI section body is not "everything up to the next `[`".** Values can + themselves contain brackets: `qtmaildir.conf` has folders named + `[Gmail]/Bozze`, which ended a section before its `label` and made three of + five accounts silently display their raw key. Walk lines instead. A first fix + using a lazy quantifier and a lookahead dropped every label, which is the + argument for the boring version. - **libvirt's own memory and disk figures are not what they look like.** `balloon.current` is memory allocated to the VM and reads full forever; `block.allocation` is qcow2 growth on the host, not usage inside the guest. @@ -108,6 +129,14 @@ frosting needs its own `hl.layer_rule` and a distinct `WlrLayershell.namespace`. Without the rule it still works, rendering flat translucent. +A panel that should sit below waybar rather than over it wants +`exclusionMode: ExclusionMode.Normal` on its window, which respects waybar's +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 three use +`ExclusionMode.Ignore` and cover the whole screen. + ## Reloading | | How | -- cgit v1.2.3