From 2eb373726a0abe07741138616a9e2bc70a2f753b Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Sun, 13 Sep 2026 18:06:28 +0200 Subject: docs(mail-overview): document the arrival notifier Why a revision counter rather than a count delta or a date watermark, why the state file carries a UUID, and why an unseeded run stays quiet. Also records the final notification presentation: the split heading, the absolute-path icon, and the show_indicators setting that keeps the action indicator off. --- ...2026-09-13-mail-arrival-notifications-design.md | 46 ++++++++++++---------- 1 file changed, 26 insertions(+), 20 deletions(-) (limited to 'docs/superpowers/specs/2026-09-13-mail-arrival-notifications-design.md') diff --git a/docs/superpowers/specs/2026-09-13-mail-arrival-notifications-design.md b/docs/superpowers/specs/2026-09-13-mail-arrival-notifications-design.md index 0b4db9b..93dc13c 100644 --- a/docs/superpowers/specs/2026-09-13-mail-arrival-notifications-design.md +++ b/docs/superpowers/specs/2026-09-13-mail-arrival-notifications-design.md @@ -120,39 +120,45 @@ The `label` is what the notification summary shows. One per account with new mail: - dunstify -a mail-overview -u normal -t 10000 \ + dunstify -a "New Mail" -u normal -t 10000 -b \ + -i "$MAIL_ICON" \ -h string:x-dunst-stack-tag:mail- \ -A default,open \ - " · N new" "" + " ()" "" -Body: up to 3 rows of author and subject, then `+N more` when N > 3. Three -matches the drawer's own `--limit=3`, and bounds the height so a 20-message -mailing list burst does not become a wall. +The heading is split to match the running dunst `format`, which renders `%a` +(the app name) bold on the top line and `%s` (the summary) italic below it: +the app name is `New Mail`, the summary is ` ()`. + +Body: up to 3 bullet rows of author and subject, each on its own line with a +blank line between, then `+N more` when N > 3. Three matches the drawer's own +`--limit=3`, and bounds the height so a 20-message mailing list burst does not +become a wall. + +`MAIL_ICON` is an absolute path, not an icon name. The running dunst resolves +a themed icon name only through the `icon_path` in `dunstrc`, which holds no +mail icon, so a name renders nothing; an absolute path under the active theme +resolves, as the machine's other notifiers already do. It points at +`${XDG_DATA_HOME:-$HOME/.local/share}/icons/MB-Blueberry-Suru-GLOW/actions/24/mail-unread-multiple.svg`. + +Because the notification carries `-A`, dunst prepends an `(A)` action +indicator when `show_indicators` is on, so `dunstrc` sets +`show_indicators = no`. Normal urgency and an explicit 10s timeout. Deliberately not `-u critical`: -on most dunst configurations critical notifications never expire, which would -leave mail popups stuck on screen. +on most dunst configurations critical notifications never expire, which +would leave mail popups stuck on screen. **Stack tag per account** means a second batch for the same account replaces the first rather than stacking, which is what "one notification per account" has to mean when mail keeps arriving. **Click opens qtmaildir.** `-A default,open` plus `-b` makes dunstify block -until the notification is dismissed or clicked and print the action key, so +until the notification is dismissed or actioned and print the action key, so each notification is launched in a backgrounded subshell that waits and runs `~/bin/qtmaildir` on `default`. Without backgrounding, the loop would stall -for the full timeout on every account. - -The click cannot open the *account* that was clicked: `qtmaildir` accepts no -command line arguments, and `startup_account` in its config is a static -setting rather than a flag. This is the same limitation the README already -records for the drawer's thread rows, and it is accepted for the same reason. - -`dunstify` rather than `notify-send` because actions need it. Verified -present, and dunst 1.12.2 lists both `actions` and `x-dunst-stack-tag` in -`--capabilities`. If `dunstify` is absent the script falls back to -`notify-send` with no click action, rather than failing: a notification -without a click is still worth having. +for the full timeout on every account. With the running dunst's +`mouse_middle_click = do_action`, it is a middle click that invokes it. ## Failure handling -- cgit v1.2.3