repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): define companion architecture

4e79c4ec0b7aace9d45855994e1321c8f7d1f593

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

docs/super/plans/2026-06-17-quickshell-hypr-companions-phase-1-foundation.md

Modified
11 11 **Roadmap:** [`docs/super/roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md`](../roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md)
13 +**Architecture Spec:** [`docs/super/specs/2026-06-17-quickshell-hypr-companions-architecture.md`](../specs/2026-06-17-quickshell-hypr-companions-architecture.md)
13 15 **Phase:** Phase 1: Quickshell Foundation and Nugu Theme Service

docs/super/roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md

Modified
4 4 # Quickshell Hypr Companions Roadmap
6 6 > **For agentic workers:** Use /skill:writing-plans to create one detailed implementation plan per phase. Start with Phase 1 and proceed sequentially unless the user explicitly changes the order.
8 8 **Goal:** Reimplement the current Hypr companion app surface in one Quickshell config with verified feature parity, same Nugu style/dark-light behavior, simpler Hypr Lua config, and obsolete Ironbar/Mako/Hyprtoolkit frontends retired only after proof.
10 -**Design Spec:** [`docs/super/inventory/2026-06-17-quickshell-hypr-companion-baseline.md`](../inventory/2026-06-17-quickshell-hypr-companion-baseline.md)
10 +**Design Spec:** [`docs/super/specs/2026-06-17-quickshell-hypr-companions-architecture.md`](../specs/2026-06-17-quickshell-hypr-companions-architecture.md)
12 +**Baseline Inventory:** [`docs/super/inventory/2026-06-17-quickshell-hypr-companion-baseline.md`](../inventory/2026-06-17-quickshell-hypr-companion-baseline.md)
12 14 **Planning Strategy:** This is a multi-daemon desktop shell migration. Splitting by live-retirable surfaces keeps the current desktop usable after every phase: first create a Quickshell shell that changes nothing, then replace Ironbar, then Mako, then launchers/OSDs, then simplify Hypr and retire services. Each phase has a live parity gate before any old app is removed.

docs/super/specs/2026-06-17-quickshell-hypr-companions-architecture.md

Added
new file mode 100644
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)
8 +## Non-negotiables
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.
23 +## Scope decisions
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. |
39 +## Runtime shape
41 +One named config:
43 +```text
44 +~/.config/quickshell/nugu/
45 +├── shell.qml
46 +├── Theme.qml
47 +├── Diagnostics.qml
48 +├── services/
49 +│ ├── Commands.qml
50 +│ ├── Hypr.qml
51 +│ ├── Notifications.qml
52 +│ ├── Clipboard.qml
53 +│ ├── SystemStats.qml
54 +│ └── Inhibit.qml
55 +├── bar/
56 +│ ├── Bar.qml
57 +│ ├── Section.qml
58 +│ └── widgets/*.qml
59 +├── notifications/
60 +│ ├── NotificationDaemon.qml
61 +│ ├── NotificationPopup.qml
62 +│ └── NotificationList.qml
63 +├── launcher/
64 +│ ├── Launcher.qml
65 +│ ├── Dmenu.qml
66 +│ └── AppRow.qml
67 +├── clipboard/
68 +│ └── ClipboardPicker.qml
69 +├── power/
70 +│ └── PowerMenu.qml
71 +└── osd/
72 + ├── Osd.qml
73 + └── OsdSurface.qml
74 +```
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.
78 +Root process:
80 +```qml
81 +Scope {
82 + Theme { id: theme }
83 + Commands { id: commands }
84 + Hypr { id: hypr }
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 { ... }
93 + Launcher { ... }
94 + ClipboardPicker { ... }
95 + PowerMenu { ... }
96 + OsdSurface { ... }
98 +```
100 +## Public IPC contract
102 +Hypr binds should eventually call stable Quickshell IPC methods, not internal component names.
104 +Namespace: `nugu`
106 +| Method | Purpose | Replaces |
107 +| --- | --- | --- |
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
127 +### Theme service
129 +Inputs:
131 +- `hypr/generated/nugu.json` for palette data during early phases.
132 +- `~/.cache/nugu/mode` for current mode during early phases.
134 +Responsibilities:
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.
140 +Later migration:
142 +- Move mode state to `${XDG_STATE_HOME:-~/.local/state}/nugu/mode` only when Hypr/WezTerm/scripts are migrated together.
144 +### Hypr service
146 +Inputs:
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.
151 +Responsibilities:
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.
157 +Hard rule:
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
175 +Phase 2 bridge:
177 +- The bar can call `makoctl restore`/`makoctl dismiss --all` while Mako still owns notifications.
179 +Phase 3 native:
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
187 +Initial backend:
189 +- `cliphist list`
190 +- `cliphist decode`
191 +- `wl-copy`
193 +Responsibilities:
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.
199 +### Inhibit service
201 +Responsibilities:
203 +- Durations: `00:30:00`, `01:00:00`, `02:00:00`, `inf`.
204 +- Default `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.
213 +## Bar architecture
215 +Per-monitor `PanelWindow`:
217 +- top, left, right anchors
218 +- height `30`
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
226 +Sections:
228 +```text
229 +start: workspaces | clipboard | bindmode
230 +center: music | clock
231 +end: notifications | wifi | bluetooth | tray | cpu | volume | brightness | battery | inhibit | power
232 +```
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.
240 +Popup stack:
242 +- anchor top-right
243 +- overlay layer
244 +- width `360`
245 +- height max `160`
246 +- max visible `4`
247 +- margin `8`, outer-margin `14`
248 +- padding `12,14`
249 +- border `2`, critical border `3`
250 +- radius `12`
251 +- icon max `48`, icon radius `7`
252 +- font `IBM Plex Sans 10`
254 +Timeouts:
256 +- low `2500ms`
257 +- normal `6500ms`
258 +- critical persistent
260 +Actions:
262 +- left: invoke default action
263 +- middle: dismiss group
264 +- right: dismiss
266 +Grouping/overflow:
268 +- grouped format: `%a · %g\n<b>%s</b>\n%b`
269 +- hidden format: `+%h more notifications`
271 +## Launcher architecture
273 +Phase 4 target:
275 +- Open centered/overlay Quickshell window.
276 +- Search desktop entries.
277 +- Launch selected entry.
278 +- Escape closes.
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
287 +Phase 4 target:
289 +- Same actions as Ironbar popup:
290 + - poweroff
291 + - reboot
292 + - logout
293 + - sleep
294 + - lock
295 +- Lock and sleep may execute directly during tests.
296 +- Poweroff/reboot require confirmation by default.
297 +- Commands remain explicit and inspectable.
299 +## Dark/light flow
301 +Early phases:
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.
307 +Retirement phase:
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.
316 +Phase checks:
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
326 +Retirement checks:
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.