1 +#
Quickshell Hypr Companions Architecture — 2026-06-17 3 +Goal: replace current Hypr companion UI frontends with one Quickshell config while preserving feature parity, Nugu styling, dark/light behavior, and rollback safety.
5 +Source inventory: [`../inventory/2026-06-17-quickshell-hypr-companion-baseline.md`](../inventory/2026-06-17-quickshell-hypr-companion-baseline.md)
6 +Roadmap: [`../roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md`](../roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md)
10 +- Same current user-visible features before any retirement.
11 +- Same style semantics:
12 + - mono/status font: `IBM Plex Mono`
13 + - UI sans: `IBM Plex Sans`
14 + - active UI: `ui.focus` background, `content.backdrop` foreground
15 + - hover/accent UI: `ui.accent` background, `content.backdrop` foreground
16 + - muted UI text: `ui.minor` over `ui.backdrop`
17 + - borders/accent lines: `ui.accent`
18 +- Dark/light mode from Nugu. No one-mode-only components.
19 +- Existing Ironbar/Mako/Hyprtoolkit frontends stay until parity is live-verified.
20 +- Hypr config gets simpler only after Quickshell IPC replacements exist.
21 +- No package/service uninstall in migration phases; retirement means removing live references and disabling user services in dotfiles.
25 +These decisions keep the objective broad without replacing security/session primitives prematurely.
27 +| Area | Decision | Reason | Revisit gate |
28 +| --- | --- | --- | --- |
29 +| `hyprlock` | Keep in primary migration. Quickshell may trigger it and style parity can be reviewed later. | Lockscreen replacement is security-sensitive; current goal is companion UI simplification first. | Phase 6 explicit approval. |
30 +| `hypridle` | Keep. | Current idle/suspend policy is simple and compositor-session native. | Phase 6 explicit approval. |
31 +| `hyprpaper` | Keep. | Wallpaper is not a current companion UI bottleneck; Nugu switcher already drives it. | Phase 6 explicit approval. |
32 +| `hyprsunset` | Keep. | Independent blue-light schedule, not dark/light mode. | Phase 6 explicit approval. |
33 +| `hyprpolkitagent` | Keep. | Security-sensitive agent; not in current feature parity matrix. | Phase 6 explicit approval. |
34 +| `cliphist` | Keep storage daemon initially; replace `hyprlauncher --dmenu` frontend first. | Storage daemon is tiny and stable; frontend is the user-visible companion app. | After launcher/clipboard parity, compare native Quickshell storage complexity/perf. |
35 +| `wl-clip-persist` | Keep. | Tiny, purpose-built clipboard ownership helper. | Only if Quickshell natively proves simpler. |
36 +| Destructive power actions | Add Quickshell confirmation before actual poweroff/reboot. Preserve current commands behind confirmation. | Current Ironbar one-click destructive buttons are risky; confirmation improves behavior without losing capability. | User can request one-click later. |
37 +| Launcher parity | Desktop app search/launch and dmenu-style selection are required. Arbitrary command runner is optional unless discovered in current usage. | Current binds use `hyprlauncher` for app launch and dmenu clipboard only. | Add command mode if user asks or current config evidence appears. |
44 +~/.config/quickshell/nugu/
51 +│ ├── Notifications.qml
53 +│ ├── SystemStats.qml
60 +│ ├── NotificationDaemon.qml
61 +│ ├── NotificationPopup.qml
62 +│ └── NotificationList.qml
68 +│ └── ClipboardPicker.qml
76 +Phase 1 may place `Theme.qml` and `Diagnostics.qml` at the top level. Later phases may move services into subdirs if it reduces file size. Do not create deep structure before there is real code for it.
83 + Commands { id: commands }
85 + Notifications { id: notifications }
86 + Clipboard { id: clipboard }
87 + Inhibit { id: inhibit }
89 + IpcHandler { target: "nugu" /* stable public API */ }
91 + Variants { model: Quickshell.screens; delegate: Bar { ... } }
92 + NotificationDaemon { ... }
94 + ClipboardPicker { ... }
100 +##
Public IPC contract 102 +Hypr binds should eventually call stable Quickshell IPC methods, not internal component names.
106 +| Method | Purpose | Replaces |
108 +| `showLauncher()` | App launcher. | `hyprlauncher` on `SUPER+Space`. |
109 +| `showClipboard()` | Clipboard picker using `cliphist` backend first. | `cliphist list | hyprlauncher --dmenu | ...`. |
110 +| `showPower()` | Power/logout menu with confirmation for destructive actions. | `hyprshutdown --dry-run` and Ironbar power popup. |
111 +| `dismissNotifications()` | Dismiss visible/history notifications where appropriate. | `makoctl dismiss --all`. |
112 +| `restoreNotification()` | Restore last notification/history item. | `makoctl restore`. |
113 +| `osdVolumeUp()` / `osdVolumeDown()` / `osdMute()` | Audio key handling + OSD. | `hypr_osd.lua` volume commands. |
114 +| `osdMicMute()` | Mic mute + OSD. | `hypr_osd.lua` mic command. |
115 +| `osdBrightnessUp()` / `osdBrightnessDown()` | Brightness key handling + OSD. | `hypr_osd.lua` brightness commands. |
116 +| `mediaNext()` / `mediaPrev()` / `mediaToggle()` | MPRIS control + OSD. | `playerctl` helpers. |
117 +| `sessionLock()` | Lock OSD then `hyprlock`. | `hypr_osd.lua` lock. |
118 +| `sessionSuspend()` | Lock/suspend OSD then existing commands. | `hypr_osd.lua` suspend. |
119 +| `reloadHypr()` | Reload Hyprland and show Quickshell status. | `hyprctl reload` + `hyprctl notify`. |
120 +| `captureRegion()` / `captureWindow()` / `captureOutput()` / `captureAnnotate()` / `pickColor()` | Run existing capture/color commands and show status. | screenshot/color `hypr_osd.lua` wrappers. |
121 +| `themeReload()` / `themeSet(mode)` / `themeToggle()` | Reload or switch Nugu view. | part of `hypr/scripts/theme.nu`, later. |
123 +IPC method names are stable. Component internals can change.
125 +##
Service responsibilities 131 +- `hypr/generated/nugu.json` for palette data during early phases.
132 +- `~/.cache/nugu/mode` for current mode during early phases.
136 +- Expose `mode`, `palette`, `content`, `ui`, `error`, `warning`, `info`, `debug`.
137 +- Provide `reload()` and `setMode(mode)` for IPC and tests.
138 +- Keep Nugu semantic names unchanged.
142 +- Move mode state to `${XDG_STATE_HOME:-~/.local/state}/nugu/mode` only when Hypr/WezTerm/scripts are migrated together.
148 +- Prefer `Quickshell.Hyprland` for workspaces/toplevels/focused workspace if local API covers all needs.
149 +- Fall back to Hypr socket2 only for missing state such as bind mode.
153 +- Workspace list/active/occupied state for `1..5,9`.
154 +- Dispatch workspace focus commands.
155 +- Provide bind mode text if Hypr emits it; otherwise empty.
159 +- Delete `ironbar/scripts/workspaces-watch.py` only after this service proves active/occupied updates without polling.
161 +###
Commands service 163 +Boundary for external commands:
165 +- TUI apps: `wezterm start --class <name> -- <name>` using existing `modules.apps.lua` semantics until a cleaner shared command source exists.
166 +- Keep process calls narrow and explicit.
167 +- No new shell wrapper scripts.
169 +External commands allowed initially:
171 +- `wezterm`, `impala`, `bluetui`, `btm`, `wiremix`, `hyprshot`, `satty`, `hyprpicker`, `hyprlock`, `loginctl`, `systemctl`, `brightnessctl`, `iwctl`, `cliphist`, `wl-copy`.
173 +###
Notification service 177 +- The bar can call `makoctl restore`/`makoctl dismiss --all` while Mako still owns notifications.
181 +- Own `NotificationServer`.
182 +- Keep visible max `4`, history max `80`, Mako-equivalent timeouts/actions/history.
183 +- Provide status count/icon to bar without shell polling.
185 +###
Clipboard service 195 +- Display max 5 in bar shortcut context only if bar UI needs it.
196 +- Picker frontend supports selecting a history row to restore clipboard.
197 +- Empty history has a styled empty state.
203 +- Durations: `00:30:00`, `01:00:00`, `02:00:00`, `inf`.
205 +- Left toggles, right cycles.
206 +- Display ` {duration}` when on, ` {duration}` when off.
208 +Implementation preference:
210 +- Use Quickshell/Wayland idle inhibitor if available and verified.
211 +- Do not alter `hypridle.conf` during bar parity.
215 +Per-monitor `PanelWindow`:
217 +- top, left, right anchors
219 +- reserves top space
220 +- horizontal padding `20`
221 +- transparent-ish `ui.backdrop`
222 +- `2px` bottom border in `ui.accent`
223 +- `IBM Plex Mono`, `12px`
224 +- radius `7` for buttons/popups
229 +start: workspaces | clipboard | bindmode
230 +center: music | clock
231 +end: notifications | wifi | bluetooth | tray | cpu | volume | brightness | battery | inhibit | power
234 +Widget contracts come from the exact extraction table in the inventory.
236 +##
Notification architecture 238 +Use a Quickshell `NotificationServer` only when Mako is stopped during Phase 3 tests.
247 +- margin `8`, outer-margin `14`
249 +- border `2`, critical border `3`
251 +- icon max `48`, icon radius `7`
252 +- font `IBM Plex Sans 10`
258 +- critical persistent
262 +- left: invoke default action
263 +- middle: dismiss group
268 +- grouped format: `%a · %g\n<b>%s</b>\n%b`
269 +- hidden format: `+%h more notifications`
271 +##
Launcher architecture 275 +- Open centered/overlay Quickshell window.
276 +- Search desktop entries.
277 +- Launch selected entry.
279 +- Also expose dmenu-like mode for clipboard selection.
281 +Out of initial scope:
283 +- Full shell command runner unless required by user or discovered current config.
285 +##
Power architecture 289 +- Same actions as Ironbar popup:
295 +- Lock and sleep may execute directly during tests.
296 +- Poweroff/reboot require confirmation by default.
297 +- Commands remain explicit and inspectable.
303 +1. `hypr/scripts/theme.nu` remains the mode writer.
304 +2. Quickshell Theme reads the same `~/.cache/nugu/mode` and palette JSON.
305 +3. Quickshell updates live via IPC `themeReload()`/`themeSet(mode)` or file-watch later.
309 +- Remove Ironbar/Mako theme writes only after those apps are retired.
310 +- Keep GTK color-scheme and Hypr reload logic until a simpler replacement is planned.
312 +##
Verification architecture 314 +Every retirement candidate needs evidence before disabling old services.
318 +- config parse: `qs -p quickshell/nugu/shell.qml`
319 +- service syntax: `systemd-analyze --user verify hypr/systemd/quickshell.service`
320 +- logs: `journalctl --user -u quickshell.service`
321 +- old service rollback: `systemctl --user restart ironbar.service mako.service`
322 +- visual: screenshots in dark and light mode
323 +- interaction matrix: each widget/button/scroll/keybind
324 +- process/perf: compare `ps`/systemd RSS and CPU for old vs new
328 +- `grep` proves no remaining live-path references to retired frontend.
329 +- Old service stopped/disabled and Quickshell still passes interaction matrix.
330 +- Human visual approval for same style/better looks.
332 +##
Architecture self-review 334 +- The full objective remains broad: all current companion UI frontends are covered, and deep replacements are explicitly deferred to Phase 6 rather than excluded.
335 +- Every current Ironbar surface has a destination in the bar architecture.
336 +- Every current Mako behavior has a destination in the notification architecture.
337 +- Hypr simplification is sequenced after IPC exists, not before.
338 +- Old services remain until verified parity, preserving rollback.