# Notification Settings 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 settings window page that configures notifyd's timeouts and caps and the balloon shell's placement, DND rule and muted apps, through one file. **Architecture:** `~/.config/notifyd/config.json` is read by notifyd (timeouts, caps; re-read on `notifyctl reload`) and by both quickshell processes through `shared/Notify.qml` (watched `FileView`). A pure `NotifyConfig.js` library resolves defaults and decides suppression, so both shells and the node test agree. The page edits a draft held by its `Module` and saves with `cat >` then `notifyctl reload`. **Tech Stack:** Go 1.27 stdlib + godbus (notifyd repo, `~/Programming/GIT/notifyd`), Quickshell 0.3.1 QML, node for the JS check. Spec: `docs/superpowers/specs/2026-10-19-notification-settings-design.md`. Two repos. Paths under `notifyd:` are relative to `~/Programming/GIT/notifyd`, the rest to this repo. Every commit is GPG-signed (default config, never disable) and ends with the `Co-Authored-By` trailer the session gives. No home paths in committed files: write `~`. --- ## File map notifyd: - Create `internal/notify/config.go`: `Config`, `Timeouts`, `DefaultConfig`, `ConfigPath`, `LoadConfig`. - Create `internal/notify/config_test.go`. - Modify `internal/notify/policy.go`: timeouts come from a `Timeouts` argument. - Modify `internal/notify/policy_test.go`: new signature. - Modify `internal/notify/store.go`: caps become fields with `SetCaps`. - Modify `internal/notify/store_test.go`: a `SetCaps` case. - Modify `internal/notify/service.go`: holds a `Config`, loads at `Start`, `reload()`. - Modify `internal/notify/control.go`: `Reload` method. - Modify `cmd/notifyctl/main.go`: `reload` verb. - Modify `README.md`. quickshell: - Create `shared/NotifyConfig.js` + links `desktop/NotifyConfig.js`, `notifications/NotifyConfig.js`. - Create `shared/test_notify_config.js`. - Modify `shared/Notify.qml`: `config`, `rawConfig`, `configPath`. - Modify `notifications/Balloons.qml`: screen and corner from config. - Modify `notifications/NotificationBalloon.qml`: suppression through `NotifyConfig.withheld`. - Create `desktop/modules/notifications/NotificationsModule.qml`, `NotificationsPage.qml`, `README.md`. - Modify `desktop/shell.qml`: import + module entry. - Modify `notifications/README.md`, `AGENTS.md`. --- ### Task 1: notifyd config loader **Files:** - Create: `notifyd:internal/notify/config.go` - Test: `notifyd:internal/notify/config_test.go` - [ ] **Step 1: Write the failing test** `notifyd:internal/notify/config_test.go` (license header as in every file in the repo, copy from `store.go` lines 1-10): ```go package notify import ( "os" "path/filepath" "testing" ) func writeConfig(t *testing.T, body string) string { t.Helper() p := filepath.Join(t.TempDir(), "config.json") if err := os.WriteFile(p, []byte(body), 0o600); err != nil { t.Fatal(err) } return p } func TestLoadConfigMissingFileIsDefaults(t *testing.T) { got := LoadConfig(filepath.Join(t.TempDir(), "absent.json")) if got != DefaultConfig() { t.Errorf("got %+v, want defaults", got) } } func TestLoadConfigMalformedIsDefaults(t *testing.T) { got := LoadConfig(writeConfig(t, `{"liveCap": 5,`)) if got != DefaultConfig() { t.Errorf("got %+v, want defaults", got) } } func TestLoadConfigPartialMergesOverDefaults(t *testing.T) { got := LoadConfig(writeConfig(t, `{"timeouts": {"low": 3}, "historyCap": 50, "muted": ["x"]}`)) want := DefaultConfig() want.Timeouts.Low = 3 want.HistoryCap = 50 if got != want { t.Errorf("got %+v, want %+v", got, want) } } func TestLoadConfigWrongTypeKeepsThatDefault(t *testing.T) { got := LoadConfig(writeConfig(t, `{"liveCap": "many", "historyCap": 7}`)) if got.LiveCap != 20 || got.HistoryCap != 7 { t.Errorf("got live %d history %d, want 20 and 7", got.LiveCap, got.HistoryCap) } } func TestLoadConfigClamps(t *testing.T) { got := LoadConfig(writeConfig(t, `{"liveCap": 0, "historyCap": 1000, "timeouts": {"normal": -4}}`)) if got.LiveCap != 1 || got.HistoryCap != 100 || got.Timeouts.Normal != 10 { t.Errorf("got %+v", got) } } ``` - [ ] **Step 2: Run, expect failure** Run: `cd ~/Programming/GIT/notifyd && go test ./internal/notify/ -run LoadConfig` Expected: build failure, `undefined: LoadConfig`. - [ ] **Step 3: Implement** `notifyd:internal/notify/config.go` (license header first): ```go package notify import ( "encoding/json" "errors" "log" "os" "path/filepath" ) // Timeouts are the balloon lifetimes in seconds per urgency, used only when a // client leaves the choice to the server. 0 means never expires. type Timeouts struct { Low int `json:"low"` Normal int `json:"normal"` Critical int `json:"critical"` } // Config is the daemon's share of ~/.config/notifyd/config.json. The file // also carries the balloon shell's keys (placement, DND, mute); they are not // declared here and the decoder ignores them. type Config struct { Timeouts Timeouts `json:"timeouts"` LiveCap int `json:"liveCap"` HistoryCap int `json:"historyCap"` } // DefaultConfig is the behaviour before the file existed. func DefaultConfig() Config { return Config{Timeouts: Timeouts{Low: 10, Normal: 10, Critical: 0}, LiveCap: 20, HistoryCap: 20} } // ConfigPath is $XDG_CONFIG_HOME/notifyd/config.json, ~/.config when unset. func ConfigPath() string { dir, err := os.UserConfigDir() if err != nil { dir = filepath.Join(homeDir(), ".config") } return filepath.Join(dir, "notifyd", "config.json") } // LoadConfig never fails: a hand typo must not stop the daemon. A missing // file or broken JSON is the defaults; a key of the wrong type keeps its // default while the rest of the file applies, which is what encoding/json // does on an UnmarshalTypeError. Out-of-range values clamp. func LoadConfig(path string) Config { def := DefaultConfig() data, err := os.ReadFile(path) if err != nil { if !errors.Is(err, os.ErrNotExist) { log.Printf("notifyd: config: %v", err) } return def } c := def if err := json.Unmarshal(data, &c); err != nil { var typeErr *json.UnmarshalTypeError if !errors.As(err, &typeErr) { log.Printf("notifyd: config %s: %v, using defaults", path, err) return def } log.Printf("notifyd: config %s: %v", path, err) } c.LiveCap = clamp(c.LiveCap, 1, 100) c.HistoryCap = clamp(c.HistoryCap, 1, 100) if c.Timeouts.Low < 0 { c.Timeouts.Low = def.Timeouts.Low } if c.Timeouts.Normal < 0 { c.Timeouts.Normal = def.Timeouts.Normal } if c.Timeouts.Critical < 0 { c.Timeouts.Critical = def.Timeouts.Critical } return c } func clamp(v, lo, hi int) int { return min(max(v, lo), hi) } ``` `homeDir()` is in `icons.go:216`; reuse it. - [ ] **Step 4: Run, expect pass** Run: `go test ./internal/notify/ -run LoadConfig -v` Expected: 5 PASS. If `TestLoadConfigWrongTypeKeepsThatDefault` fails because `historyCap` was not applied, the decoder stopped at the type error: decode into `map[string]json.RawMessage` and unmarshal each known key separately instead. - [ ] **Step 5: Commit** ```bash git add internal/notify/config.go internal/notify/config_test.go git commit -m "feat(notify): read timeouts and caps from config.json A missing or broken file is the defaults, so a hand typo never stops the daemon; a key of the wrong type keeps its default while the rest applies." ``` --- ### Task 2: timeouts from config **Files:** - Modify: `notifyd:internal/notify/policy.go:25-50` - Modify: `notifyd:internal/notify/policy_test.go:42-63` - [ ] **Step 1: Update the test to the new signature** Replace `TestEffectiveTimeoutMS` in `policy_test.go`: ```go func TestEffectiveTimeoutMS(t *testing.T) { def := DefaultConfig().Timeouts custom := Timeouts{Low: 3, Normal: 7, Critical: 60} cases := []struct { name string expire int32 u Urgency t Timeouts want int64 }{ {"minus one uses low default", -1, Low, def, 10_000}, {"minus one uses normal default", -1, Normal, def, 10_000}, {"minus one critical never", -1, Critical, def, 0}, {"minus one uses configured low", -1, Low, custom, 3_000}, {"minus one uses configured critical", -1, Critical, custom, 60_000}, {"zero never", 0, Normal, custom, 0}, {"explicit wins", 3_000, Normal, custom, 3_000}, {"sub second exact", 1, Normal, def, 1}, } for _, c := range cases { t.Run(c.name, func(t *testing.T) { if got := EffectiveTimeoutMS(c.expire, c.u, c.t); got != c.want { t.Errorf("EffectiveTimeoutMS(%d, %q) = %d, want %d", c.expire, c.u, got, c.want) } }) } } ``` - [ ] **Step 2: Run, expect failure** Run: `go test ./internal/notify/ -run EffectiveTimeout` Expected: `too many arguments in call to EffectiveTimeoutMS`. - [ ] **Step 3: Implement** In `policy.go`, replace `DefaultTimeoutMS` and `EffectiveTimeoutMS`: ```go // DefaultTimeoutMS is the balloon lifetime for an urgency when the client // leaves the choice to the server (expire_timeout -1), from the config's // seconds. 0 is never. func DefaultTimeoutMS(u Urgency, t Timeouts) int64 { switch u { case Low: return int64(t.Low) * 1000 case Critical: return int64(t.Critical) * 1000 default: return int64(t.Normal) * 1000 } } // EffectiveTimeoutMS resolves the client's expire_timeout per the freedesktop // spec: -1 means the server decides (the configured default), 0 means never, // and anything positive is milliseconds and wins. The spec is precise about // the direction and libnotify's default is -1, so getting it backwards would // make every plain notify-send immortal. func EffectiveTimeoutMS(expire int32, u Urgency, t Timeouts) int64 { switch { case expire == -1: return DefaultTimeoutMS(u, t) case expire == 0: return 0 default: return int64(expire) } } ``` Note the `default` branch: an unknown urgency is normal, matching `UrgencyFromHints`. In `service.go`, add a config to `Service` (guarded by the existing `mu`): ```go type Service struct { conn *dbus.Conn store *Store dir string mu sync.Mutex timers map[uint32]*time.Timer cfg Config } ``` In `NewService`, set `cfg: DefaultConfig()` in the literal. In `Notify`, replace `ms := EffectiveTimeoutMS(expireTimeout, u)` with: ```go s.mu.Lock() timeouts := s.cfg.Timeouts s.mu.Unlock() ms := EffectiveTimeoutMS(expireTimeout, u, timeouts) ``` - [ ] **Step 4: Run all tests** Run: `go test ./...` Expected: all PASS. - [ ] **Step 5: Commit** ```bash git add internal/notify/policy.go internal/notify/policy_test.go internal/notify/service.go git commit -m "feat(notify): take the per-urgency default timeout from config" ``` --- ### Task 3: caps as store fields **Files:** - Modify: `notifyd:internal/notify/store.go:39-56, 226-235` - Test: `notifyd:internal/notify/store_test.go` - [ ] **Step 1: Write the failing test** Append to `store_test.go`: ```go func TestSetCapsAppliesAtNextAdd(t *testing.T) { s, _ := newTestStore() for i := 0; i < 5; i++ { id, _ := s.Add(popup("a"), "", 0) s.Dismiss(id, 2) } for i := 0; i < 4; i++ { s.Add(popup("a"), "", 0) } s.SetCaps(2, 3) // Lowering a cap drops nothing by itself. if got := len(s.historySnapshot()); got != 5 { t.Fatalf("history after SetCaps = %d, want 5", got) } s.Add(popup("a"), "", 0) if got := len(s.order); got != 2 { t.Errorf("live = %d, want 2", got) } if got := len(s.historySnapshot()); got != 3 { t.Errorf("history = %d, want 3", got) } } ``` - [ ] **Step 2: Run, expect failure** Run: `go test ./internal/notify/ -run SetCaps` Expected: `s.SetCaps undefined`. - [ ] **Step 3: Implement** In `store.go`, delete the `liveCap`/`historyCap` const block. Add fields to `Store` after `history`: ```go liveCap int historyCap int ``` In `NewStore`, add to the literal: ```go liveCap: DefaultConfig().LiveCap, historyCap: DefaultConfig().HistoryCap, ``` Add after `ClearHistory`: ```go // SetCaps changes the queue and history bounds. Nothing is trimmed here: a // reload must not silently drop live notifications, so a lowered cap applies // at the next add. func (s *Store) SetCaps(live, history int) { s.mu.Lock() defer s.mu.Unlock() s.liveCap = live s.historyCap = history } ``` In `fileLocked` replace both `historyCap` with `s.historyCap`; in `evictLocked` replace `liveCap` with `s.liveCap`. - [ ] **Step 4: Run all tests** Run: `go test ./...` Expected: all PASS, including the existing `TestQueueCapEvictsToHistory` and `TestHistoryRingCapsAtTwenty`. - [ ] **Step 5: Commit** ```bash git add internal/notify/store.go internal/notify/store_test.go git commit -m "feat(notify): make the queue and history caps settable A lowered cap applies at the next add rather than at once, so reloading the config never drops a notification the user has not seen." ``` --- ### Task 4: load at start, `notifyctl reload` **Files:** - Modify: `notifyd:internal/notify/service.go` (`Start`, new `reload`) - Modify: `notifyd:internal/notify/control.go` - Modify: `notifyd:cmd/notifyctl/main.go` - [ ] **Step 1: Implement** In `service.go`, add after `Start`: ```go // reload re-reads the config file and applies it. Timers already armed keep // their old lifetime; the next notification gets the new one. func (s *Service) reload() { c := LoadConfig(ConfigPath()) s.mu.Lock() s.cfg = c s.mu.Unlock() s.store.SetCaps(c.LiveCap, c.HistoryCap) } ``` In `Start`, call `s.reload()` immediately before `s.store.Reset()`. In `control.go`, append: ```go // Reload re-reads ~/.config/notifyd/config.json. The settings page calls it // after a save; a bad file is logged and read as defaults, never an error. func (c *control) Reload() *dbus.Error { c.svc.reload() return nil } ``` In `cmd/notifyctl/main.go`, add to the usage text after `clear-history`: ``` reload re-read ~/.config/notifyd/config.json ``` and to the switch before `default:`: ```go case "reload": callControl("Reload") ``` - [ ] **Step 2: Build and test** Run: `go vet ./... && go test ./...` Expected: no vet output, all PASS. - [ ] **Step 3: Check against a throwaway daemon is not possible here** The live daemon owns the bus name, so a second one cannot start. The live check is Task 9, step 4. Confirm only that a missing daemon is reported: `go run ./cmd/notifyctl reload; echo $?` against the *installed* (old) daemon prints `notifyctl: ... Unknown method` style error and `1`. That is the "daemon not reachable" path the page reports. - [ ] **Step 4: Commit** ```bash git add internal/notify/service.go internal/notify/control.go cmd/notifyctl/main.go git commit -m "feat(notifyctl): add reload, re-reading the config file The daemon also reads the file at start. Armed timers keep their lifetime; the next notification gets the new default." ``` --- ### Task 5: notifyd README **Files:** - Modify: `notifyd:README.md` (new section before `## License`) - [ ] **Step 1: Add the section** ```markdown ## Configuration `~/.config/notifyd/config.json` (`$XDG_CONFIG_HOME` is honoured). Every key is optional and the defaults are the behaviour without the file: { "timeouts": { "low": 10, "normal": 10, "critical": 0 }, "liveCap": 20, "historyCap": 20 } Timeouts are seconds, 0 is never, and apply only when a client sends `expire_timeout -1`. Caps clamp to 1..100; a lowered cap applies at the next notification. A broken file is logged and read as the defaults. The daemon reads it at start and on `notifyctl reload`. The quickshell settings page writes it; the same file carries the balloon shell's keys (`balloons`, `dndPassCritical`, `muted`), which the daemon ignores. ``` - [ ] **Step 2: Commit and push** ```bash git add README.md git commit -m "docs: document config.json and notifyctl reload" git push ``` - [ ] **Step 3: Hand the install to the user** Do not replace the running daemon from a tool call. Tell the user to run, from their terminal: cd ~/Programming/GIT/notifyd go build -o ~/bin/notifyd ./cmd/notifyd && go build -o ~/bin/notifyctl ./cmd/notifyctl pkill -x notifyd; setsid -f notifyd and confirm with `notifyctl reload; echo $?` → `0`. --- ### Task 6: `NotifyConfig.js`, shared resolver **Files:** - Create: `shared/NotifyConfig.js` - Create links: `desktop/NotifyConfig.js`, `notifications/NotifyConfig.js` → `../shared/NotifyConfig.js` - Test: `shared/test_notify_config.js` - [ ] **Step 1: Write the failing test** `shared/test_notify_config.js` (license header as `desktop/modules/git/test_git.js`): ```js // Run: node shared/test_notify_config.js // NotifyConfig.js is a QML library, so its .pragma line is stripped before // node evaluates it. const fs = require("fs"); const assert = require("assert"); const src = fs.readFileSync(__dirname + "/NotifyConfig.js", "utf8") .replace(/^\.pragma library$/m, ""); const C = new Function(src + "\nreturn { defaults, resolve, withheld };")(); // Nothing, or garbage, is the defaults. assert.deepStrictEqual(C.resolve(undefined), C.defaults()); assert.deepStrictEqual(C.resolve("x"), C.defaults()); // Partial merges; wrong types and bad values keep their defaults. const r = C.resolve({ timeouts: { low: 3, normal: "x" }, liveCap: 500, historyCap: 0, balloons: { corner: "middle", screen: "HDMI-A-1" }, dndPassCritical: false, muted: ["a", 3, "b"] }); assert.deepStrictEqual(r.timeouts, { low: 3, normal: 10, critical: 0 }); assert.strictEqual(r.liveCap, 100); assert.strictEqual(r.historyCap, 1); assert.deepStrictEqual(r.balloons, { screen: "HDMI-A-1", corner: "bottom-right" }); assert.strictEqual(r.dndPassCritical, false); assert.deepStrictEqual(r.muted, ["a", "b"]); // Suppression: muted always, DND per dndPassCritical. const n = (app, urgency) => ({ app, urgency }); const cfg = C.resolve({ muted: ["spam"] }); assert.strictEqual(C.withheld(cfg, n("spam", "critical"), false), true); assert.strictEqual(C.withheld(cfg, n("ok", "normal"), false), false); assert.strictEqual(C.withheld(cfg, n("ok", "normal"), true), true); assert.strictEqual(C.withheld(cfg, n("ok", "critical"), true), false); assert.strictEqual(C.withheld(C.resolve({ dndPassCritical: false }), n("ok", "critical"), true), true); console.log("ok"); ``` - [ ] **Step 2: Run, expect failure** Run: `node shared/test_notify_config.js` Expected: `ENOENT ... NotifyConfig.js`. - [ ] **Step 3: Implement** `shared/NotifyConfig.js` (license header as `desktop/modules/git/Git.js`): ```js .pragma library // ~/.config/notifyd/config.json, resolved over its defaults. notifyd reads // the same file for timeouts and caps (its config.go clamps the same way); // the balloon keys are this side's alone. Tested by test_notify_config.js. const corners = ["top-left", "top-right", "bottom-left", "bottom-right"]; function defaults() { return { timeouts: { low: 10, normal: 10, critical: 0 }, liveCap: 20, historyCap: 20, balloons: { screen: "DP-1", corner: "bottom-right" }, dndPassCritical: true, muted: [], }; } function seconds(v, d) { return Number.isInteger(v) && v >= 0 ? v : d; } function cap(v, d) { return Number.isInteger(v) ? Math.min(Math.max(v, 1), 100) : d; } // Never throws: anything that is not the right shape reads as its default. function resolve(raw) { const d = defaults(); if (!raw || typeof raw !== "object") return d; const t = raw.timeouts || {}; const b = raw.balloons || {}; return { timeouts: { low: seconds(t.low, d.timeouts.low), normal: seconds(t.normal, d.timeouts.normal), critical: seconds(t.critical, d.timeouts.critical), }, liveCap: cap(raw.liveCap, d.liveCap), historyCap: cap(raw.historyCap, d.historyCap), balloons: { screen: typeof b.screen === "string" && b.screen !== "" ? b.screen : d.balloons.screen, corner: corners.indexOf(b.corner) >= 0 ? b.corner : d.balloons.corner, }, dndPassCritical: typeof raw.dndPassCritical === "boolean" ? raw.dndPassCritical : d.dndPassCritical, muted: Array.isArray(raw.muted) ? raw.muted.filter(a => typeof a === "string") : d.muted, }; } // Whether a balloon is held back by mute or DND. Drawer and snooze are the // balloon's own checks; this is only what the config decides. function withheld(cfg, n, dnd) { if (cfg.muted.indexOf(n.app) >= 0) return true; return dnd && !(n.urgency === "critical" && cfg.dndPassCritical); } ``` Then the links: ```bash ln -s ../shared/NotifyConfig.js desktop/NotifyConfig.js ln -s ../shared/NotifyConfig.js notifications/NotifyConfig.js ``` - [ ] **Step 4: Run, expect pass** Run: `node shared/test_notify_config.js` Expected: `ok`. - [ ] **Step 5: Commit** ```bash git add shared/NotifyConfig.js shared/test_notify_config.js desktop/NotifyConfig.js notifications/NotifyConfig.js git commit -m "notifications: resolve notifyd's config.json in a shared library One resolver for both shells and the settings page, with the defaults that reproduce today's behaviour, and the mute/DND decision beside it so the node check covers it." ``` --- ### Task 7: `Notify.qml` reads the config **Files:** - Modify: `shared/Notify.qml` - [ ] **Step 1: Implement** Add after `import QtQuick`: ```qml import "NotifyConfig.js" as NC ``` `Notify.qml` is reached through the links in `desktop/` and `notifications/`, and a relative import resolves beside the link, which is why Task 6 created a link in each. If the shell logs `NotifyConfig.js: No such file`, the import resolved against `shared/` instead; then the links are unnecessary and harmless. Add properties after `property bool dnd: false`: ```qml // ~/.config/notifyd/config.json, shared with the daemon (timeouts, caps) // and written by the settings page. rawConfig is the parsed file as is, // so a save keeps keys this version does not know; config is it resolved // over the defaults, which is what everything reads. readonly property string configPath: (Quickshell.env("XDG_CONFIG_HOME") || Quickshell.env("HOME") + "/.config") + "/notifyd/config.json" property var rawConfig: ({}) readonly property var config: NC.resolve(root.rawConfig) ``` Add a `FileView` after `snoozeFile`: ```qml FileView { id: configFile path: root.configPath watchChanges: true printErrors: false onFileChanged: reload() onLoaded: { try { root.rawConfig = JSON.parse(configFile.text() || "{}"); } catch (e) { root.rawConfig = {}; } } onLoadFailed: root.rawConfig = {} } ``` Hot reload does not follow the `shared/` symlink (AGENTS.md, Reloading), so the running shells pick this up only through the edits in Task 8 (notifications) and Task 9 (desktop). Nothing to check yet. - [ ] **Step 2: Commit** ```bash git add shared/Notify.qml git commit -m "notifications: read notifyd's config.json in the Notify singleton" ``` --- ### Task 8: balloons use placement, mute and DND **Files:** - Modify: `notifications/Balloons.qml:17, 71-80` - Modify: `notifications/NotificationBalloon.qml:28-40` - [ ] **Step 1: Placement** `Balloons.qml` reads `Notify.config` and needs no new import. Replace the header comment `// The balloon stack, bottom-right of DP-1, over conky.` with: ```qml // The balloon stack, in the corner and on the screen notifyd's config.json // names (bottom-right of DP-1 by default), over conky. ``` Inside `PanelWindow { id: win`, replace the `screen:`, `anchors`, `margins` lines with: ```qml readonly property var place: Notify.config.balloons readonly property bool atTop: place.corner.startsWith("top") readonly property bool atLeft: place.corner.endsWith("left") screen: Quickshell.screens.find(s => s.name === place.screen) ?? Quickshell.screens[0] anchors { top: atTop; bottom: !atTop; left: atLeft; right: !atLeft } margins { top: 12; bottom: 12; left: 12; right: 12 } ``` In the `Column`, replace `anchors { bottom: parent.bottom; right: parent.right }` with nothing: the window is sized to the column, so the column's anchors do nothing. Delete that line. - [ ] **Step 2: Suppression** In `NotificationBalloon.qml`, add `import "NotifyConfig.js" as NC` after the existing imports. Replace the comment and `visible` block (lines 28-40) with: ```qml // Driven by the shell's tick. The balloon drops itself once its expiry // passes, or while a suppression says so: the drawer and snooze withhold // everything; a muted app and DND are config.json's call (DND passes // critical unless dndPassCritical is off). The drawer still lists what // was withheld, because a list the user opened is not an interruption. visible: { if (Notify.drawerOpen) return false; if (Notify.snoozeUntil > b.now) return false; if (NC.withheld(Notify.config, b.notification, Notify.dnd)) return false; if (b.notification.expires !== 0 && b.now >= b.notification.expires) return false; return true; } ``` - [ ] **Step 3: Verify defaults unchanged** Check reload: `qs log -p notifications --log-times | tail -5` shows `Reloading configuration` after the edit and no `ReferenceError`/`TypeError`. If none followed, ask the user to run `./reload.sh notifications`. Run: `notify-send -u low test "default placement"`. Ask the user: balloon bottom-right of DP-1, gone after 10s? - [ ] **Step 4: Verify config drives it** ```bash mkdir -p ~/.config/notifyd printf '{"balloons":{"corner":"top-left"},"muted":["mutetest"]}\n' > ~/.config/notifyd/config.json notify-send -a mutetest muted "should not pop" notify-send -a other placed "top-left" ``` Ask the user: no balloon for `mutetest`, `other` at top-left of DP-1, and `mutetest` listed in the drawer. If the balloon stays bottom-right, a live layer surface did not re-anchor (cf. AGENTS.md, a hot reload does not resize a layer surface): check whether it moves once the stack empties and a new notification maps it; if not, bind `visible` to also go false when `place` changes and note that in a comment. Then `rm ~/.config/notifyd/config.json`. - [ ] **Step 5: Commit** ```bash git add notifications/Balloons.qml notifications/NotificationBalloon.qml git commit -m "notifications: place, mute and DND balloons from config.json Screen and corner come from the shared config. Mute and the DND rule go through NotifyConfig.withheld, so the settings page's node check covers the same decision the balloon makes." ``` --- ### Task 9: settings page **Files:** - Create: `desktop/modules/notifications/NotificationsModule.qml` - Create: `desktop/modules/notifications/NotificationsPage.qml` - Modify: `desktop/shell.qml` (import list, `modules:` list after `IdleModule {},`) - [ ] **Step 1: The module, holding the draft** `desktop/modules/notifications/NotificationsModule.qml` (QML license header as `desktop/modules/git/GitModule.qml`): ```qml import Quickshell.Io import QtQuick import "../.." // notifyd's config.json: the daemon's timeouts and caps, and the balloon // shell's placement, DND rule and muted apps. The draft lives here, not in // the page, so the sidebar's unsaved mark survives the page unloading. Module { id: nm name: "notifications" label: "Notifications" // nf-fa-bell, present in Inconsolata Nerd Font. icon: "" settings: true group: "Desktop" keywords: ["notifyd", "timeout", "history", "queue", "mute", "dnd", "corner", "monitor", "balloon"] property var draft: Notify.config property string notice: "" dirty: JSON.stringify(nm.draft) !== JSON.stringify(Notify.config) readonly property bool valid: [nm.draft.liveCap, nm.draft.historyCap].every(v => v >= 1 && v <= 100) // Not over unsaved edits. function refresh() { if (!nm.dirty) nm.draft = Notify.config; } function discard() { nm.draft = Notify.config; nm.notice = ""; } function edit(patch) { nm.draft = Object.assign({}, nm.draft, patch); } // Unknown keys in the file survive. The text goes on stdin to cat (the // notes pattern: the exit code is the outcome); 1 is the write, 2 the // reload, so a stopped daemon reads as saved-but-not-applied. // Written in onStarted, then stdinEnabled cleared to give cat its EOF: // the sequence notes' bodyWriter uses (NotesModule.qml). function save() { nm.notice = ""; nm.saver.data = JSON.stringify(Object.assign({}, Notify.rawConfig, nm.draft), null, 2) + "\n"; nm.saver.stdinEnabled = true; nm.saver.running = false; nm.saver.running = true; } property Process saver: Process { property string data: "" command: ["sh", "-c", 'mkdir -p "$(dirname "$1")" && cat > "$1" || exit 1; notifyctl reload || exit 2', "sh", Notify.configPath] onStarted: { nm.saver.write(nm.saver.data); nm.saver.stdinEnabled = false; } onExited: code => nm.notice = code === 0 ? "saved" : code === 2 ? "saved; notifyd not reachable, it reads the file at its next start" : "could not write " + Notify.configPath } page: Component { Page { title: "Notifications" actions: Component { SaveBar { dirty: nm.dirty; valid: nm.valid; note: "caps are 1 to 100" onSave: nm.save(); onDiscard: nm.discard() } } NotificationsPage { width: parent.width; mod: nm } } } } ``` The save does not `refresh()` the draft: the `FileView` reloads, `Notify.config` changes, and `dirty` goes false on its own when they match. - [ ] **Step 2: The page** `desktop/modules/notifications/NotificationsPage.qml` (license header): ```qml import Quickshell import QtQuick import "../.." import "../appearance" import "../qtmaildir" // The rows of the notifications settings page. Everything edits mod.draft. Column { id: pg // Not "nm": a property named like the injecting id binds to itself. required property QtObject mod readonly property var d: mod.draft spacing: 8 function setTimeout(key, v) { pg.mod.edit({ timeouts: Object.assign({}, pg.d.timeouts, { [key]: v }) }); } Heading { text: "Timeouts" } Text { width: pg.width; wrapMode: Text.Wrap text: "Seconds a balloon stays when the app leaves it to the daemon. An app's own timeout still wins." color: Theme.overlay font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 } } Repeater { model: [["low", "Low"], ["normal", "Normal"], ["critical", "Critical"]] Row { required property var modelData spacing: 10 Text { width: 90; anchors.verticalCenter: parent.verticalCenter text: modelData[1]; color: Theme.text font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 } } Field { anchors.verticalCenter: parent.verticalCenter visible: pg.d.timeouts[modelData[0]] !== 0 value: String(pg.d.timeouts[modelData[0]]) placeholder: "seconds" onEdited: { const n = parseInt(value, 10); if (n > 0) pg.setTimeout(modelData[0], n); } } Toggle { anchors.verticalCenter: parent.verticalCenter label: "never" checked: pg.d.timeouts[modelData[0]] === 0 onToggled: pg.setTimeout(modelData[0], checked ? 0 : 10) } } } Heading { text: "Limits" } Repeater { model: [["liveCap", "On screen"], ["historyCap", "History"]] Row { required property var modelData spacing: 10 Text { width: 90; anchors.verticalCenter: parent.verticalCenter text: modelData[1]; color: Theme.text font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 } } Field { anchors.verticalCenter: parent.verticalCenter value: String(pg.d[modelData[0]]) border.color: pg.d[modelData[0]] >= 1 && pg.d[modelData[0]] <= 100 ? Qt.alpha(Theme.text, 0.12) : Theme.red onEdited: pg.mod.edit({ [modelData[0]]: parseInt(value, 10) || 0 }) } } } Heading { text: "Placement" } Flow { width: pg.width; spacing: 6 Repeater { model: Quickshell.screens.map(s => s.name) Button { required property string modelData text: modelData border.color: pg.d.balloons.screen === modelData ? Theme.accent : Qt.alpha(Theme.text, 0.2) onClicked: pg.mod.edit({ balloons: Object.assign({}, pg.d.balloons, { screen: modelData }) }) } } } // The four corners as a miniature screen: click the one balloons go to. Grid { columns: 2; spacing: 4 Repeater { model: ["top-left", "top-right", "bottom-left", "bottom-right"] Rectangle { required property string modelData width: 60; height: 34; radius: 5 color: pg.d.balloons.corner === modelData ? Qt.alpha(Theme.accent, 0.6) : Qt.alpha(Theme.surface, 0.6) border.width: 1; border.color: Qt.alpha(Theme.text, 0.15) MouseArea { anchors.fill: parent; cursorShape: Qt.PointingHandCursor onClicked: pg.mod.edit({ balloons: Object.assign({}, pg.d.balloons, { corner: modelData }) }) } } } } Heading { text: "Suppression" } Toggle { label: "Critical notifications still pop up under Do Not Disturb" checked: pg.d.dndPassCritical onToggled: pg.mod.edit({ dndPassCritical: checked }) } Text { width: pg.width; wrapMode: Text.Wrap text: "Muted apps get no balloon. They still appear in the drawer and in history." color: Theme.overlay font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 } } Flow { width: pg.width; spacing: 6 Repeater { model: pg.d.muted Button { required property string modelData text: modelData; icon: "" onClicked: pg.mod.edit({ muted: pg.d.muted.filter(a => a !== modelData) }) } } } // Apps seen in the queue and history, not yet muted, one click to add. Flow { width: pg.width; spacing: 6 Repeater { model: [...new Set(Notify.queue.concat(Notify.history).map(n => n.app))] .filter(a => a && pg.d.muted.indexOf(a) < 0).sort() Button { required property string modelData text: modelData; icon: "" onClicked: pg.mod.edit({ muted: pg.d.muted.concat([modelData]) }) } } } Field { width: 200 placeholder: "mute another app by name" onEdited: { const a = value.trim(); if (a !== "" && pg.d.muted.indexOf(a) < 0) pg.mod.edit({ muted: pg.d.muted.concat([a]) }); value = ""; } } Text { width: pg.width; wrapMode: Text.Wrap visible: pg.mod.notice !== "" text: pg.mod.notice color: pg.mod.notice === "saved" ? Theme.green : Theme.yellow font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 3 } } } ``` Glyphs: `` (times), `` (plus), `` (bell) are Font Awesome codepoints in Inconsolata Nerd Font; confirm with `fc-query` on the installed font, e.g. `python3 -c` with fontTools if present, or `fc-list ':charset=f0f3' family | grep -i inconsolata`. A missing glyph means picking another, not keeping it. `Field` here is `modules/appearance/Field.qml` and `Toggle` `modules/appearance/Toggle.qml`; `Heading` is `modules/qtmaildir/Heading.qml`. No file in this directory imports `QtQuick.Controls`, so `Button` is the drawer's `Button.qml`. - [ ] **Step 3: Register it** In `desktop/shell.qml`, add `import "modules/notifications"` in alphabetical place (after `import "modules/notes"`), and `NotificationsModule {},` after `IdleModule {},`. This edit is also what makes the running shell re-index the new directory and pick up the `shared/Notify.qml` change (AGENTS.md, Reloading). - [ ] **Step 4: Check it loads** Run: `qs log -p desktop --log-times | tail -20` Expected: `Reloading configuration` after the edit time, no `TypeError`, `ReferenceError` or `is not a type`. If no reload line followed, ask the user to run `./reload.sh desktop`. Ask the user to open settings, Desktop → Notifications, and check: the four sections render with today's defaults, an edit marks the page unsaved, Discard reverts, Save writes `~/.config/notifyd/config.json` and shows "saved". Then: set Low to 3s, save, `notify-send -u low t "3s"`, balloon gone after 3s (needs the new daemon from Task 5). - [ ] **Step 5: Commit** ```bash git add desktop/modules/notifications desktop/shell.qml git commit -m "desktop: notifications settings page Edits notifyd's config.json as a draft behind the SaveBar and runs notifyctl reload after the write; a stopped daemon is reported as saved but not applied, since it reads the file at its next start. Muting offers the apps already seen in the queue and history." ``` --- ### Task 10: docs **Files:** - Create: `desktop/modules/notifications/README.md` - Modify: `notifications/README.md` - Modify: `AGENTS.md` ("What this is" block) - [ ] **Step 1: Module README** `desktop/modules/notifications/README.md`: ```markdown # notifications (settings page) Edits `~/.config/notifyd/config.json`, the one file behind both the daemon and the balloon shell: | key | read by | | --- | --- | | `timeouts`, `liveCap`, `historyCap` | notifyd, at start and on `notifyctl reload` | | `balloons`, `dndPassCritical`, `muted` | both shells, through `Notify.config` | `shared/NotifyConfig.js` resolves the file over its defaults and holds the mute/DND decision. Check: `node shared/test_notify_config.js`. Save writes the file with `cat` (unknown keys kept) then runs `notifyctl reload`. If notifyd is not running the file is still written and the page says so; the daemon reads it when it starts. Snooze is not here: the status tile has it. ``` - [ ] **Step 2: Balloon README** In `notifications/README.md`, replace the "Suppression lives here" section body with: ```markdown The daemon does not know about DND, snooze or mute. This component withholds balloons: `status.dnd` suppresses low and normal (and critical too when `dndPassCritical` is off), a muted app is always withheld, and `notifyd/snooze` suppresses everything. The drawer's reserved space lists every live notification anyway. Placement, mute and the DND rule come from `~/.config/notifyd/config.json`, edited from the settings window (Desktop → Notifications). ``` And in "The files are the interface" add the line: ``` ~/.config/notifyd/config.json settings, shared with the daemon ``` - [ ] **Step 3: AGENTS.md** In the "What this is" block, the `desktop/` description's settings list, change `sunset, idle (the former appearance shell), autostart,` to `sunset, idle (the former appearance shell), notifications, autostart,`. - [ ] **Step 4: Commit and push** ```bash git add desktop/modules/notifications/README.md notifications/README.md AGENTS.md git commit -m "docs: the notification settings page and config.json" git push ```