1 +#
Quickshell Phase 2C Surface/API Inventory — 2026-06-17 3 +Purpose: freeze API/runtime facts for the last Ironbar-parity slice: tray, clipboard entry point, bind mode, notification bridge, inhibit, power popup, calendar popup, and full visual comparison.
7 +- [`2026-06-17-quickshell-hypr-companion-baseline.md`](2026-06-17-quickshell-hypr-companion-baseline.md)
8 +- [`2026-06-17-quickshell-parity-checklist.md`](2026-06-17-quickshell-parity-checklist.md)
9 +- [`../plans/2026-06-17-quickshell-hypr-companions-phase-2a-bar-shell.md`](../plans/2026-06-17-quickshell-hypr-companions-phase-2a-bar-shell.md)
10 +- [`../plans/2026-06-17-quickshell-hypr-companions-phase-2b-status-widgets.md`](../plans/2026-06-17-quickshell-hypr-companions-phase-2b-status-widgets.md)
12 +##
Local runtime snapshot 14 +Non-mutating commands run:
17 +makoctl list
| grep -c
'^Notification ' 18 +cliphist list
| wc -l
19 +uptime -p
| cut -d
' ' -f2-
21 +hyprctl binds -j
| jq
'submap check' 22 +rg
'submap|bindmode|mode' hypr/modules
30 +cliphist sample count: 224
31 +uptime: 4 days, 5 hours, 55 minutes
32 +hypr raw events available: yes
33 +hypr binds with submap: none
34 +hypr/modules submap/bindmode refs: none
35 +system tray-ish processes: none found by loose grep
40 +- Notification bridge can validate zero-count state immediately; restore/dismiss need test notifications or existing history.
41 +- Clipboard picker has plenty of current `cliphist` history to test list/select.
42 +- Bind mode widget likely remains hidden/empty because no Hypr submaps are configured.
43 +- Tray implementation still matters for parity, but current live process grep did not reveal obvious tray clients; test may need a known tray app.
44 +- Inhibit duration display can be tested without changing `hypridle.conf`.
45 +- Power popup must use dry-run/confirmation for destructive actions.
52 +import Quickshell.Services.SystemTray
53 +import Quickshell.Widgets
56 +Relevant singleton/property:
58 +- `SystemTray.items`: `ObjectModel<SystemTrayItem>`.
60 +Relevant `SystemTrayItem` properties:
62 +- `id`: unique app-ish name.
63 +- `title`: application label.
64 +- `icon`: image source string usable in `Image` or `IconImage`-like display.
65 +- `status`: active/passive/attention enum.
66 +- `tooltipTitle`, `tooltipDescription`.
67 +- `hasMenu`: menu availability.
68 +- `onlyMenu`: activation does nothing; menu is primary.
69 +- `menu`: menu handle usable with `QsMenuAnchor`/`QsMenuOpener`.
73 +- `activate()` for left click.
74 +- `secondaryActivate()` for middle click.
75 +- `display(parentWindow, relativeX, relativeY)` for native menu display.
76 +- `scroll(delta, horizontal)` for tray scroll forwarding.
78 +Implementation recommendation:
80 +- Phase 2C should first use `SystemTrayItem.display(barWindow, x, y)` for right-click/menu behavior because it is direct and documented.
81 +- If native menu display is ugly or insufficient, explore `QsMenuOpener`/custom menu in a later targeted task.
82 +- Icon size target: current Ironbar `14px`.
84 +##
QsMenuOpener API note 86 +`QsMenuOpener` exposes `children` for a `QsMenuHandle`. The fetched v0.3.0 page describes it as a child retriever, not a direct popup opener despite the name.
90 +- `menu`: `QsMenuHandle`.
91 +- `children`: `ObjectModel<QsMenuEntry>`.
95 +- Do not assume `QsMenuOpener` opens menus by itself.
96 +- Prefer `SystemTrayItem.display(...)` for Phase 2C parity unless a custom menu is explicitly needed.
98 +##
Clipboard entry/picker boundary 100 +Current Ironbar clipboard module:
102 +- Bar entry in start section.
104 +- Truncate end length `30`.
106 +Current Hypr bind frontend:
109 +cliphist list
| hyprlauncher --dmenu
| cliphist decode
| wl-copy
112 +Phase 2C bar parity:
114 +- Add a compact clipboard entry point to the bar.
115 +- For bar parity, opening a Quickshell picker/popup is enough; full launcher/dmenu replacement is Phase 4.
116 +- Use `cliphist list` as backend.
117 +- Use `cliphist decode` + `wl-copy` to restore selected text.
121 +- `cliphist list` currently returns 224 rows.
122 +- Do not clear history during tests.
124 +Implementation recommendation:
126 +- Phase 2C should implement a tiny popup/panel with first 5 rows and 30-char end truncation.
127 +- Phase 4 can generalize this into the `SUPER+V` picker.
129 +##
Bind mode surface 131 +Current Ironbar has a `bindmode` module, but current Hypr Lua config has no submaps/bind modes.
135 +- `hyprctl binds -j` showed no non-empty `submap` rows.
136 +- `hypr/modules/*.lua` has no `submap`/`bindmode` references.
140 +- `Hyprland.rawEvent(event)` emits `HyprlandEvent` with `name`, `data`, and `parse(argumentCount)`.
144 +- Phase 2C should add a bind-mode widget that is hidden/empty by default.
145 +- It can listen for raw `submap` events if present later.
146 +- Since there is no current bind mode, parity is hidden state.
148 +##
Notification status bridge 150 +Current Ironbar bridge:
153 + - `makoctl list | grep -c '^Notification '`
156 +- Left click: `makoctl restore`.
157 +- Right click: `makoctl dismiss --all`.
161 +- Keep Mako as notification daemon.
162 +- Implement a Quickshell bridge widget with bounded `makoctl` polling while Mako is still authoritative.
163 +- Native notification status without polling belongs to Phase 3.
165 +Current observed count: `0`.
169 +- With no notifications: ``.
170 +- After `notify-send`: count should become ` N` after poll.
171 +- Left click restore, right click dismiss all.
178 +import Quickshell.Wayland
187 +- `window`: associated window; must be non-null to enable.
188 +- `enabled`: boolean.
192 +- Compositor usually considers a `PanelWindow` important.
193 +- Requires idle-inhibit protocol support.
195 +Current Ironbar inhibit behavior:
197 +- Durations: `00:30:00`, `01:00:00`, `02:00:00`, `inf`.
198 +- Default duration: `inf`.
199 +- On format: ` {duration}`.
200 +- Off format: ` {duration}`.
201 +- Left toggles, right cycles.
203 +Phase 2C implementation recommendation:
205 +- Attach `IdleInhibitor` to the bar `PanelWindow`.
206 +- Keep state in an `InhibitController`/widget property.
207 +- Use a `Timer` for finite durations.
208 +- Do not modify `hypridle.conf`.
212 +- Display state and duration cycle can be tested immediately.
213 +- Actual idle blocking needs a controlled short timeout or manual wait; do not change idle config just for this phase.
215 +##
Power popup surface 217 +Current Ironbar popup actions:
219 +| Label | Current command |
221 +| ` off` | `hyprshutdown --post-cmd "systemctl poweroff"` |
222 +| ` reboot` | `hyprshutdown --post-cmd "systemctl reboot"` |
223 +| ` out` | `hyprshutdown` |
224 +| ` sleep` | `loginctl lock-session && systemctl suspend` |
225 +| ` lock` | `hyprlock` |
227 +Architecture decision already made:
229 +- Poweroff/reboot require confirmation in Quickshell by default.
230 +- Lock can run `hyprlock`.
231 +- Sleep/logout/destructive actions must be dry-run or explicitly approved during verification.
235 +- Current Ironbar popup shows `up {{30000:uptime -p | cut -d ' ' -f2-}}`.
236 +- Observed uptime text: `4 days, 5 hours, 55 minutes`.
238 +Phase 2C recommendation:
240 +- Add popup with same labels and uptime line.
241 +- Use Nugu popup style and `IBM Plex Mono`/Sans as appropriate.
242 +- Use `Commands` service methods for lock/sleep/logout/poweroff/reboot dry-run/confirm boundaries.
244 +##
Clock calendar popup 246 +Current Ironbar clock:
248 +- Center text `%H:%M`.
249 +- Calendar popup styled through GTK CSS.
253 +- Add popup on clock click.
254 +- Preserve existing center text.
255 +- Calendar can be a compact QML month grid if QtQuick Controls calendar is not desirable.
256 +- Must be readable in dark and light mode.
260 +- Popup opens on clock click.
261 +- Today/current/other-month/day-name colors follow Nugu semantics.
262 +- Dark/light screenshots.
264 +##
Full visual comparison 266 +Phase 2C is the end of Ironbar bar parity before retirement. Required outputs:
268 +- Screenshot of current Ironbar dark mode.
269 +- Screenshot of Quickshell bar dark mode.
270 +- Screenshot of current Ironbar light mode if safely switchable.
271 +- Screenshot of Quickshell bar light mode.
272 +- Notes for deviations: either fixed or explicitly accepted.
274 +Do not stop Ironbar permanently in Phase 2C. Use temporary stop only if needed to capture Quickshell without overlap, then restart Ironbar immediately.
276 +##
Phase 2C implementation order recommendation 278 +1. Add popup primitive anchored to bar buttons.
279 +2. Add clock calendar popup.
280 +3. Add clipboard entry popup backed by `cliphist` first 5 rows.
281 +4. Add bind-mode hidden widget / raw-event listener.
282 +5. Add Mako notification bridge widget.
283 +6. Add tray widget using `SystemTray.items` and `item.display(...)`.
284 +7. Add inhibit widget + `IdleInhibitor` attached to bar.
285 +8. Add power popup with confirmation/dry-run boundaries.
286 +9. Run full Ironbar-vs-Quickshell visual/interaction comparison.
287 +10. Record Phase 2C verification.
291 +- Tray menu opening should use `SystemTrayItem.display(...)`; `QsMenuOpener` is not assumed to open menus.
292 +- Bind mode parity is hidden state because no current bind modes exist.
293 +- Notification status remains a Mako bridge until Phase 3; this keeps daemon ownership simple.
294 +- Clipboard storage remains `cliphist`.
295 +- Poweroff/reboot are confirmation-only by default.
296 +- Ironbar remains live through Phase 2C; retirement is Phase 5 only.