3 -Nuguland is my niri-native Quickshell desktop shell.
4 -It is a complete personal workflow shell, not a configurable product.
5 -It uses Nugu semantics, IBM Plex fonts, Quickshell services, niri IPC, and DBus-native integrations.
6 -It has one visual language, one workflow shape, one compositor target, and one production gate.
10 -- Nuguland runs as `qs -c nuguland`.
11 -- Nuguland targets niri only.
12 -- Widgets render and forward intent only.
13 -- Widgets never spawn programs, parse files, build command strings, or own backend polling.
14 -- Every widget consumes a service object.
15 -- Services own facts, polling, parsing, commands, timers, cleanup, state, and action routing.
16 -- Process use is confined to niri integration, service backends with no Quickshell-native API, and the test harness.
17 -- Every process has an owner, timeout, stderr capture, exit handling, and cleanup proof.
18 -- No settings app exists.
19 - Personal choices are source constants.
20 - Persisted state exists only for clipboard history and explicitly approved clipboard metadata.
21 -- The final tree contains only files needed to run, style, test, or explain Nuguland.
22 -- Production readiness requires nested niri proof with pointer input, screenshots, animation evidence, service state, and zero leftover processes or temp files.
26 -- Font policy: IBM Plex Sans for UI, IBM Plex Mono for status/time/code-like text, verified Nerd Font glyphs only where text is not enough.
27 -- Color policy: `Theme.qml` consumes generated Nugu data and exposes semantic tokens only.
28 -- Text/content surfaces use `content.*`; chrome, borders, panels, and controls use `ui.*`.
29 -- Active UI uses `ui.focus` background with `content.backdrop` text.
30 -- Hover and accent UI use `ui.accent` background with `content.backdrop` text.
31 -- Muted UI text uses `ui.minor` over `ui.backdrop`.
32 -- Error, warning, info, and debug colors are semantic signal colors, not decoration.
33 -- Critical foreground/background pairs meet WCAG contrast 4.5 or better, with small bar text aimed at 7 or better.
34 -- Motion is short, spatial, and tied to object continuity.
35 - Popouts grow from their visible anchor.
36 - Dismissal reverses the same path.
37 -- Decorative effects never obscure hierarchy, input target, text contrast, or cleanup.
38 -- `logo.svg` is the large Nuguland mark: N-bug icon plus inline lowercase `nugu land` wordmark, derived from the compact rhythm of `bugabinga.min.svg`, using Nugu palette colors and IBM Plex Sans.
39 -- `logo-icon.svg` is the small Nuguland mark: N-bug icon only.
43 -- Use `logo.svg` when width is at least 160 px or text can remain readable: splash, about, diagnostics header, lock/session surfaces, documentation, and large empty states.
44 -- Use `logo-icon.svg` below 160 px width, below 40 px height, in square/circle slots, launcher icons, favicons, tray-like surfaces, buttons, compact bar affordances, and any place text would blur.
45 -- Do not squeeze, crop, re-letter, recolor outside Nugu roles, add outlines, add boxes around the large mark, or separate the wordmark from the icon.
46 -- Keep a visible gap between `nugu` and `land`; `land` stays accent-colored.
48 -##
Reference-derived commitments 50 -These sources define the desired behavior, not a second document set.
51 -Reference comparison notes are production evidence: adopted mechanics include source, Nuguland owner, proof route, and live evidence; rejected mechanics include rejection reason and replacement.
52 -Reference source fingerprints bind extracted mechanics to exact files through `referenceSourceFingerprints` smoke evidence.
53 -Live screenshot comparison binds adopted and rejected concepts through `referenceVisualComparison` smoke evidence; `visualConceptCoverageComplete` means every adopted fingerprinted source has a live proof note.
54 -`referenceAdoptionMatrix` maps every fingerprinted source to a Nuguland owner, runtime contract, and proof marker.
55 -Bar/workflow extraction requires `barWorkflowReferenceCoverage` for workspace, status, tray, idle, scroll-hint, and widened-hit mechanics.
56 -`referenceBoundaryMatrix` records adopt, reduce, and reject decisions for attractive reference mechanics that need Nugu constraints or dependency removal.
57 -Surface workflow reference fingerprints cover nexus search, drawers, window info, shortcuts, cheatsheet, and tooltip hang behavior.
58 -Popout detail reference fingerprints cover content routing, audio, network, battery, clipboard wrapper, network card, quick sliders, and PipeWire mixer mechanics.
59 -Service interaction reference fingerprints cover toasts, battery warnings, idle/logind, quick toggles, notification dock, window actions, action center, region panel, notification fling, screenshot controller, and tray menu view.
60 -Security session reference fingerprints cover lock layout, password input, lock notifications, session wrapper, session content, Polkit shell, Polkit content, Polkit service, lock controller, and PAM session context.
61 -Primitive reference fingerprints cover styled text, icon buttons, split buttons, sliders, toggle rows, vertical fade flickables, elevation shadows, and ripple buttons.
62 -Launcher overview reference fingerprints cover launcher content, app list, action rows, start menu shell, categorized results, task view layout, launcher controller, and fuzzy launch content.
63 -Component scaffold reference fingerprints cover section containers, section headers, property rows, text fields, menus, menu items, loading indicators, and inner borders.
65 -| Area | Source | Keep | Reject |
66 -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
67 -| Bar popout morph | `Nuguland design archive/nuguland-shell/modules/bar/popouts/Wrapper.qml`, `Content.qml`, `AnchorAnim.qml`; `Nuguland design archive/nuguland-dots/dots/.config/quickshell/ii/modules/waffle/bar/BarPopup.qml`; `Nuguland design archive/Nuguland/modules/user/modules/quickshell/shell/bar/Tooltip.qml` | one bar-owned host, named registry, anchor-center sizing, loader lifetime, Escape/focus policy, attached growth from bar item | widget-owned popups, detached cards, manual per-widget coordinates, duplicate hosts |
68 -| Notifications | `Nuguland design archive/nuguland-shell/modules/sidebar/NotifGroupList.qml`, `NotifGroup.qml`, `Notif.qml`, `NotifActionList.qml`; `Nuguland design archive/nuguland-dots/dots/.config/quickshell/ii/services/Notifications.qml`; `Nuguland design archive/Nuguland/modules/user/modules/quickshell/shell/notifications/NotificationManager.qml` | grouped history, compact preview, drag-dismiss, expand/collapse, close/copy/action rows, removal lifecycle lock, isolated smoke fixtures | Material palette, hidden config thresholds, network actions, untested gesture paths |
69 -| Session and power | `Nuguland design archive/nuguland-shell/modules/session/Content.qml`; `Nuguland design archive/nuguland-dots/dots/.config/quickshell/ii/modules/ii/sessionScreen/SessionScreen.qml`; `Nuguland design archive/Nuguland/modules/user/modules/quickshell/shell/bar/power/Power.qml` | keyboard focus, Escape cancel, clear destructive confirmation, test-harness action routing, battery/profile detail | direct one-click destructive execution, decorative GIFs, unsafe kill buttons |
70 -| Launcher | `Nuguland design archive/nuguland-shell/modules/launcher/Content.qml`, `items/ActionItem.qml`, `items/CalcItem.qml`; `Nuguland design archive/nuguland-dots/dots/.config/quickshell/ii/services/LauncherSearch.qml`; `Nuguland design archive/Nuguland/modules/user/modules/quickshell/shell/launcher/Controller.qml` | one scored provider list, prefixes, windows/apps/actions/calculator/clipboard, preview panel, keyboard-first control | command-string plugin soup, web results, OCR/upload/image search |
71 -| Primitives | `Nuguland design archive/nuguland-shell/components/controls/ButtonBase.qml`, `IconButton.qml`, `StyledSlider.qml`, `StateLayer.qml`, `VerticalFadeFlickable.qml`; `Nuguland design archive/Nuguland/modules/user/modules/quickshell/shell/bar/FullwidthMouseArea.qml`, `ClickableIcon.qml`; `Nuguland design archive/nuguland/quickshell/components/bar/Clock.qml`, `WorkspaceCell.qml`, `FastMusicLine.qml` | state layers, full hit geometry, sliders, scroll fades, odometer clock idea, direction-aware workspace motion, tiny media line driven by service state | CAVA, inefficient video wallpaper, heavy shader parallax, fragile debug wrappers, non-IBM fonts |
72 -| Services | `Nuguland design archive/nuguland-shell/services/Players.qml`, `Time.qml`, `Notifs.qml`, `NetworkUsage.qml`, `IdleInhibitor.qml`; `Nuguland design archive/nuguland-dots/dots/.config/quickshell/ii/services/ResourceUsage.qml`, `BluetoothStatus.qml`, `Privacy.qml`; installed Quickshell service qmltypes | one service per domain, native MPRIS/PipeWire/UPower/Bluetooth/Notifications/SystemTray/Polkit/PAM/IdleInhibitor, ref-counted timers | shell pipelines in widgets, per-widget polling, hidden backend processes |
73 -| Screenshot and color | installed `niri msg action screenshot*`, `niri msg pick-color`, niri wiki key-binding and miscellaneous pages | niri-native screenshot UI, focused screen/window capture, absolute smoke paths, pointer control, native color picking | third-party capture/color helpers in live shell |
74 -| Test harness | current `../quickshell/nuguland/smoke.sh`, `nested-niri.sh`; niri `validate`, `-- <COMMAND>`, event stream, layer docs | process-group supervisor, private run dir, generated validated KDL, nested niri only, pointer/key/drag/screenshot proof, zero leftovers | IPC-only proof, host-compositor helpers, fixed `/tmp` logs, lingering DBus helpers |
76 -###
Extracted reference mechanics 78 -- Popout state is a tiny state object: current name, open flag, anchor rect, and modal handoff.
79 - Content lives in one host.
80 - Changing the current name activates one loader, fades the previous loader out, then unloads it.
81 -- Popout sizing follows the active loader: width and height animate from the previous content to the next content.
82 - Opening and closing use the same spatial path in reverse.
83 -- Popout placement is anchored through `PopupWindow` using the visible bar item as source.
84 - The shell slides on the cross-axis, resizes on the growth axis, and clamps to the screen edge before reporting geometry.
85 -- The visual card is not the window.
86 - A transparent popup window owns margins, shadow, masks, focus, and capture policy; the card is an inner content surface that grows through the bar separator.
87 -- `popupInputMaskFrame` follows the animated card geometry; the transparent window is never the hover target.
88 -- Menu focus is owned by the popout host.
89 - Escape closes the active surface unless the active child has an explicit text-entry dialog.
90 - Lost focus and outside click close the popout.
91 - Inside click keeps it open.
92 -- Tooltip/menu continuity keeps the last active item during a short hang time, scales from 0.9 to 1.0, tracks animated y-bounds, and masks hoverable regions instead of spawning a second popup family.
93 -- Bar hit targets are larger than visible text or glyphs.
94 - Wheel events are forwarded after observation so widgets do not swallow compositor navigation by accident.
95 -- Notification groups are keyed by app, sorted by latest notification time, expose active count, app icon or image, highest urgency, relative time, animated expand height, explicit expand/collapse state, and render as one grouped card panel.
96 -- Notification actions are horizontal rows with close, server actions, and copy body.
97 - The visual panel uses a masked horizontal action rail adapted from Nuguland `NotifActionList.qml`.
98 - Drag-dismiss uses a bounded horizontal threshold adapted from Nuguland `NotifGroupList.qml`.
99 - Copy gives local feedback.
100 - Close and discard untrack the server notification and remove shell history without leaking timers.
101 -- Notification toasts and tray history share one notification service.
102 - DND, popup inhibition, unread count, timers, persistence, and discard-all are service state, not widget state.
103 -- Launcher providers share one scored result stream.
104 - Prefixes only select provider intent; results still render in one list with keyboard-first selection and pointer parity.
105 - Widgets never build command strings.
106 - Launcher selected results drive a preview panel with action rows, primary keyboard action, provider-specific facts, provider chips, and bottom-docked search field.
107 -- The clock may use odometer-like digit motion and hard separators.
108 - It must use Nugu roles and IBM Plex, with glow only as a minimal tasteful accent and never as structure.
109 - Clock digits use Nuguland-style vertical odometer motion inside `Bar.qml`.
110 -- Media state comes from native MPRIS players.
111 - Nuguland elects one active player, exposes aliases as source constants, keeps manual selection as explicit private state, and routes play, pause, previous, next, stop, position, metadata, and cover state through `Media.qml`.
112 - The media popout renders one cover/details/progress/transport/player-selector panel adapted from Nuguland media details and Nuguland MPRIS controller mechanics.
113 -- Network rate facts are service-owned, ref-counted, and keep fixed-length history buffers.
114 -- Resource facts parse kernel files inside `Resources.qml`: CPU, memory, swap, disk, and network counters.
115 - Widgets receive percentages, formatted labels, and bounded history arrays; no widget parses files or starts helpers.
116 - Resource cards use bounded hero meters and sparklines adapted from Nuguland performance cards and Nuguland graphs.
117 -- Privacy indicators come from PipeWire link state: active microphone streams, active screen/video capture, and recorder-like privacy state are facts exposed by one service and rendered as semantic warning/info UI.
118 -- Audio popout renders one PipeWire mixer panel: output selector, input selector, sink/source sliders, mute buttons, per-stream rows, and stream target reassignment adapted from Nuguland audio popout plus Nuguland mixer rows.
119 -- Bluetooth state uses the native Quickshell Bluetooth service.
120 - Devices are sorted connected first, paired next, unpaired last, with human names before raw device identifiers.
121 -- Connectivity popout is one combined service-fed panel: Wi-Fi toggle, scan state, active network, sorted network rows, Bluetooth adapter toggle, scan state, connected device rows, battery badges, and device actions.
122 - It adapts Nuguland network popout and Nuguland connections menu while keeping `Network.qml` and `Bluetooth.qml` as separate services.
123 -- Tray items use native SystemTray activation, secondary activation, scroll, and DBusMenu actions.
124 - Right-click menus are hosted by Nuguland popout/menu infrastructure, not by each tray glyph.
125 -- Power and battery state come from UPower display and device records: charge state, percentage, low threshold, external devices, time remaining, health, and power profile controls when available.
126 -- The Nuguland line idea becomes a tiny service-driven media/workspace accent: no external visualizer process, no CAVA, and no decoration loop.
127 -- Efficient shader effects are allowed inside a widget or wallpaper when bounded, measured, and visually subordinate.
128 -- The accepted prototype target is the Nugu aurora style at 15 fps.
129 -- The production shape is a Quickshell background layer with no image wallpaper.
130 -- Idle CPU must drop near zero when the shader is static or fully occluded.
131 -- Pointer movement may wake the shader for a short smoothed reaction window.
132 -- The x230 proof budget is about 3% `qs` CPU for visible 15 fps animation; 30 fps is too expensive and 10 fps is too stuttery.
133 -- Wallpaper video or shader work is allowed only if efficient on x230 and not part of core shell correctness.
134 -- Shader source lives in `shaders/*.frag`.
135 -- Compiled Qt shader blobs live beside source as `*.frag.qsb` and are checked in.
136 -- `just build` compiles every `shaders/*.frag` into its `*.frag.qsb` blob.
137 -- `just lint` and `just check` fail when any shader blob is missing, stale, or orphaned.
138 -- Nuguland runtime never compiles shaders.
139 -- Shader-backed surfaces hide or degrade cleanly when a checked-in blob is unavailable at runtime.
140 -- This lifecycle applies to the aurora backdrop and every future shader.
141 - The line follows MPRIS activity or niri workspace motion using Nugu semantic colors.
142 -- Session UI is a full-screen overlay with exclusive keyboard focus.
143 - It starts on a safe focused action, supports arrow and Tab navigation, Escape or outside click cancels, and destructive actions require confirmation plus harness-routed smoke proof.
144 -- Lock UI uses native session lock plus PAM state.
145 - The password field owns focus, steals focus back, feeds key events to PAM, shows unlocking, failure, fingerprint, battery, time, and safe media state, and tears down cleanly after unlock.
146 -- OSD is a masked overlay with a short service-triggered lifetime.
147 - Audio, microphone, brightness, media, workspace, screenshot, color, and error events select one indicator, restart the expiry timer, and never reserve layout space or block normal input.
148 -- Screenshot UI is a per-screen overlay with normalized cross-screen selection geometry.
149 - Selection state records press, drag, release, normalized rect, completion, copy/save target, and cleanup.
150 - Capture itself uses niri-native screenshot actions.
151 -- Privilege prompt is an isolated full-screen security surface.
152 - It presents the requesting app/action, focused secret input, deny/cancel/confirm controls, Escape cancel, clear error text, no decorative distraction, and native Polkit flow routing.
153 -- Area and screenshot tools reuse the same selection model for rectangular target selection, cursor state, completion flash, cancellation, and smoke-visible geometry.
154 - Live shell code does not use third-party screenshot helpers.
155 -- Clickable primitives expose one Nugu state layer: hover, press, held, disabled, focus-visible, checked, and attention are semantic roles over the same hit geometry.
156 -- Error feedback uses a bounded shake primitive adapted from Nuguland `ErrorShakeAnimation.qml`: short horizontal offsets, no layout displacement after completion, and no long decorative wobble.
157 -- Scrollable lists use top and bottom edge fades to show hidden content without extra chrome; fades disappear when content fits.
158 -- Reveal indicators animate width, height, and margins together; unread badges, mute chips, scroll hints, and status pills never jump layout.
159 - `revealIndicatorPrimitive` is inlined in `Bar.qml` from the Nuguland Revealer.qml mechanic and is used by attention badges before they count as production UI.
160 -- Area selection is one finite state machine: idle, armed, dragging, confirming, completed, cancelled.
161 -- Gesture contracts name press, drag, release, cancel, and commit for every draggable surface; tests prove each named transition.
162 -- `popoutGestureMachine` adapts Nuguland Interactions.qml: popout pointer handling is a service-owned finite state machine with press, drag, release, cancel, and commit paths, independent of compositor-specific hooks.
163 -- Every visual primitive reports pointer parity and keyboard parity in diagnostics before it counts as production-ready.
164 -- Screen-edge drawers define pointer regions separately from visual panels.
165 - Hit regions subtract visible panels from the interactive mask so hover, outside click, and drag handoff never fight layer geometry.
166 -- Quick controls are fixed personal controls: audio, network, Bluetooth, microphone, DND, idle inhibit, screenshot, color, power profile, and session actions.
167 - They render as service-backed toggles with one checked state, one disabled state, and one semantic status line.
168 -- Idle/privacy popout renders one service-fed keep-awake panel adapted from Nuguland IdleInhibit.qml and Nuguland Privacy.qml: active chip, duration chips, activity rows, privacy status, native IdleInhibitor route, and no helper processes.
169 -- Launcher result rows carry provider type, icon role, verb, subtitle, tags, and preview facts.
170 - The list can render app rows, action rows, calculator rows, clipboard rows, and window rows without each provider inventing its own row shape.
171 -- Window cards combine app id, title, workspace, rule hints, preview slot, and action row.
172 - All actions route through `Niri.qml`; the card never shells out and never clones the compositor overview.
173 - The window popout renders one niri window card adapted from Nuguland WindowInfo details/buttons and Nuguland task-view cards: preview slot, details rows, rule hints, action rail, and workspace move affordance.
174 -- MPRIS track changes carry direction metadata for previous and next animation.
175 - Cover, title, artist, album, progress, shuffle, repeat, and active-player changes are facts in `Media.qml`.
176 -- Tray menu expansion keeps one submenu open and collapses siblings.
177 - Separators, check rows, radio rows, disabled rows, nested children, and close propagation are rendered by one menu view.
178 -- Screenshot selection uses dimmed mask, clear cutout, corner handles, dimensions, and toolbar actions.
179 - Selection visuals are pure shell UI; capture is still niri-native.
180 -- Nuguland rope geometry is reduced to bounded selection-corner accents.
181 - Nuguland may use the elastic corner idea for area selection feedback, but never runs a free physics decoration loop.
182 -Physics-like motion must be bounded to direct user feedback, not ambient decoration.
183 -- Clock digits use vertical odometer motion from Nuguland ClockNumber.qml: digit columns roll on the y-axis, separators stay hard, IBM Plex Mono is fixed, and glow/background settings are removed.
185 -##
Shell architecture 189 -`shell.qml` is a small lifecycle manifest:
191 -- Creates the theme, time, niri, service, surface, IPC, and diagnostics objects once.
192 -- Instantiates one bar per screen.
193 -- Instantiates always-on services.
194 -- Defers visual surfaces until opened.
195 -- Passes dependencies through required properties.
196 -- Avoids global singletons except Quickshell-provided services.
200 -- Compositor opacity is owned by niri rules, not by Nugu palette colors.
201 -- Nuguland keeps semantic colors opaque unless a component needs local alpha for state layers, scrims, or effects.
202 -- niri gives Nuguland layer surfaces about 0.90 opacity so the aurora backdrop shows through without Nugu tokens lying.
203 -- WezTerm windows are subtly translucent in niri so the aurora can show through normal terminal work.
204 -- Fullscreen WezTerm must be opaque, but niri 26.04 has no `is-fullscreen` window-rule matcher; this exception remains unresolved unless implemented by a future niri matcher, manual opacity toggle, or app-side fullscreen signal.
208 -- Transient visibility state lives in one surface manager.
209 -- Most state is memory-only or external truth.
210 -- Crash survival policy is minimal: Nuguland restarts clean and re-reads niri, PipeWire, MPRIS, Bluetooth, network, UPower, tray, and notification facts from their owners.
211 -- Nuguland does not restore open panels, typed launcher queries, selected rows, OSD timers, lock input, pending destructive actions, or session actions after a crash.
212 -- Durable private state is explicit and currently limited to clipboard data.
213 -- Clipboard history is durable.
214 -- Clipboard pins are durable if pins remain a feature.
215 -- Private clipboard mode is rejected.
219 -Services expose facts and actions.
220 -Widgets render facts and forward user intent to services.
221 -Widgets do not contain backend logic.
225 -- `Niri.qml`: event stream, JSON queries, actions, screenshots, color picking, overview state, layers, outputs, workspaces, windows, keyboard layouts, DPMS.
226 -- `Time.qml`: shared clock, calendar helpers, relative time.
227 -- `Audio.qml`: PipeWire sinks, sources, streams, volume, mute, default device selection.
228 -- `Media.qml`: MPRIS player election, playback, metadata, progress, cover art.
229 -- `Power.qml`: UPower battery, charging, health, time estimate, power profile if available.
230 -- `Bluetooth.qml`: BlueZ adapter and devices through Quickshell Bluetooth.
231 -- `Network.qml`: Quickshell Networking first.
232 - Any host-specific network command is isolated behind this service and test-proven.
233 -- `Notifications.qml`: Quickshell notification daemon, history, grouping, actions, DND.
234 -- `Tray.qml`: SystemTray and DBusMenu fidelity.
235 -- `Clipboard.qml`: clipboard history and actions behind one backend.
236 -- `Resources.qml`: CPU, memory, swap, disk, and network facts without shell pipelines.
237 -- `Privilege.qml`: Polkit agent state.
238 -- `Lock.qml`: WlSessionLock plus PAM.
239 -- `Idle.qml`: Wayland idle inhibitor.
240 -- `Screenshots.qml`: niri screenshot actions and recent capture records.
241 -- `Diagnostics.qml`: test-visible state, process ownership, service health, assertion data.
243 -##
Authority and launch ownership 245 -Nuguland owns semantic workflow dispatch. niri owns key capture and compositor primitives. systemd owns slice definitions.
246 -UWSM owns scoped process creation.
248 -Source of truth boundaries:
250 -- `niri/cfg/keybinds.kdl` owns physical key combinations only.
251 -- Nuguland owns action IDs, launcher providers, app launch definitions, script/API/shim routes, OSD side effects, and app-to-slice mapping.
252 -- systemd unit files own slice names, dependencies, resource controls, restart policy, and service lifecycle.
253 -- UWSM is the only production app/session scope launcher.
254 -- niri native actions may remain direct only for pure compositor primitives and emergency control: focus, move, resize, fullscreen, overview, screenshot built-ins, keyboard-inhibit escape, quit.
255 -- XDG autostart is owned by the niri/UWSM systemd session through `xdg-desktop-autostart.target`; Nuguland does not reimplement `.desktop` autostart scanning.
256 -- Any named workflow, application launch, hardware key, media/audio/brightness action, shell surface, script, or personal automation enters Nuguland first.
258 -Nuguland exposes one stable command shim: `nuguctl`.
260 -`nuguctl` is not a second brain.
261 -It is a thin CLI adapter from stable names to `qs ipc -c nuguland call ...`. niri keybinds prefer `nuguctl hotkey <id>` over command soup.
262 -The shim does not choose slices, parse desktop files, hold state, render UI, or duplicate service logic.
263 -It forwards to Nuguland and exits with the IPC result.
267 -- Nuguland stores launch records as structured data: id, label, kind, command argv, working directory, environment deltas, slice, startup notification policy, window matching hints, and OSD feedback.
268 -- GUI apps use `app-graphical.slice` unless explicitly classified otherwise.
269 -- Terminals, editors, mail, and development tools use `work.slice`.
270 -- Shell/session control, OSD, media, audio, brightness, screenshot, lock, power, and Nuguland IPC helpers use `session-graphical.slice`.
271 -- Background helpers use `background-graphical.slice`.
272 -- Widgets never construct launch commands.
273 - Widgets request service actions.
274 -- niri keybinds never duplicate app argv or slice choices.
278 -- The quake terminal is a named Nuguland workflow, not a raw niri terminal spawn.
279 -- niri captures the physical grave/backtick key and calls `nuguctl hotkey quake-terminal`.
280 -- Nuguland toggles one persistent WezTerm quake instance.
281 -- The instance uses the WezTerm mux domain so shell state survives hide/show.
282 -- The visible surface drops down from the top and hides upward with short spatial motion.
283 -- The quake terminal uses `work.slice` for the terminal process and `session-graphical.slice` only for the IPC/hotkey shim.
284 -- The workflow record owns app id/class/title hints so niri rules can identify, float, size, place, and style it.
285 -- The terminal must not create unbounded new WezTerm processes on repeated hotkey presses.
289 -`Niri.qml` is the only compositor integration.
293 -- Complete initial state from `niri msg --json event-stream`.
294 -- Incremental state updates from the event stream.
295 -- JSON queries for outputs, workspaces, windows, layers, focused output, focused window, keyboard layouts, overview state, and casts when needed.
296 -- Actions for workspace focus/move, window focus/move/close, column/window sizing, fullscreen, windowed fullscreen, overview open/close, DPMS, keyboard shortcut inhibit, and screen transition.
297 -- Native screenshot actions for interactive, focused screen, and focused window capture.
298 -- Native color picking through `niri msg pick-color`.
300 -The workspace model follows niri directly:
302 -- Workspaces are dynamic, per output, vertically ordered, and include an empty target at the end.
303 -- The bar shows the live stack for each output.
304 -- Wheel input moves up/down through the stack.
305 -- Occupancy comes from live window records.
306 -- Names are displayed when present.
307 -- Empty interior workspaces disappear naturally through niri behavior.
311 -- Persistent bars use the top layer.
312 -- Launchers, modal session surfaces, privilege prompts, notification toasts, screenshot UI, and popouts that must appear above fullscreen use overlay.
313 -- Background and bottom layers are reserved for inert backdrop surfaces.
314 -- Stable namespaces are mandatory for every layer surface.
315 -- niri layer rules own capture blocking, native shadows, corner radius, and layer popup effects.
317 -Nuguland uses niri's built-in overview for window/workspace overview.
318 -Nuguland surfaces may open above it, report its state, or trigger it, but do not clone it.
323 -- Nuguland has one popup shell for all bar widgets.
324 -- Switching from one open popup to another replaces content instantly; the shell itself does not close, morph, resize width, or run outgoing-content animation.
325 -- All bar popups use one golden-ratio width: screen width divided by 1.618, clamped for small and large screens.
326 -- Popup height is content-specific, budgeted per panel, and capped by available screen height below the bar.
327 -- Popup content must not clip under normal x230 height; if content exceeds budget, the panel owns internal scrolling.
328 -- Opening from closed state uses a simple center slide down from the bar plus a fast fade in.
329 -- Closing fades/slides out quickly.
330 -- The popup must feel like one stable surface whose content changes.
331 -- Popups grab focus while open.
332 -- Escape closes the open popup.
333 -- Clicking outside the popup closes it through Quickshell popup focus-grab dismissal.
334 -- Focus-grab must be configured as a stable property before the popup is shown, not toggled with `visible`.
335 -- Qt `Loader` destroys the previous item when `sourceComponent` changes; it is not an item cache.
336 -- If first-open lag remains visible, use persistent per-panel loaders or a stack of instantiated panels and hide inactive panels instead of swapping one Loader source.
340 -The bar is compact, high-contrast, and screen-aware.
344 -- focused window card
352 -- idle/privacy indicators
353 -- diagnostics affordance
357 -- full-width hit geometry larger than the visible glyph/text
358 -- exported anchor rect
359 -- hover, pressed, active, urgent, muted, and loading states
360 -- left, right, middle, wheel, and keyboard semantics when useful
361 -- tooltip text from owned metadata
362 -- pointer-testable state
366 -There is one bar popout host per bar.
370 -- current popout name
371 -- registry of popout content
372 -- anchor rect for each item
373 -- focus and Escape behavior
374 -- outside click behavior
376 -- animated width and height
377 -- animation progress diagnostics
378 -- separator interruption where the popout visually grows through the bar edge
380 -Popouts never position themselves.
381 -Widgets only register anchor geometry and request a named popout.
385 -- media controls and player selection
386 -- calendar and agenda
390 -- battery and power details
395 -Every popout must prove:
397 -- opens from the correct visible bar item
398 -- grows from the anchor
399 -- stays attached while the bar changes size
400 -- closes by Escape and outside click
401 -- remains open on inside click
402 -- has no detached-card appearance
403 -- changes screenshot pixels inside its reported target rect
404 -- cleans its loader after close
408 -Nuguland owns the notification daemon.
412 -- grouped history by app
413 -- compact preview count
419 -- middle-click close
420 -- right-click or keyboard expand/collapse
421 -- vertical drag to expand compact groups
422 -- horizontal drag to dismiss
423 -- removal animation with lifecycle lock
424 -- toast morph from the notification bell anchor
425 -- capture blocking through niri layer rules
427 -Notification smoke uses isolated notification fixtures and proves every gesture, action, dismissal path, and cleanup path.
431 -The launcher is one fast search surface.
437 -- owned shell actions
446 -- exact/name-first ranking
447 -- keyboard-first navigation
449 -- preview side panel where useful
450 -- no network results
451 -- no plugin command strings
452 -- no generated command soup
453 -- app launches come from Nuguland launch records
454 -- app-to-slice mapping lives in Nuguland, not niri keybinds
455 -- window actions go through `Niri.qml`
459 -OSD displays short-lived feedback for:
463 -- brightness if supported
465 -- workspace movement
468 -- errors from owned services
470 -OSD never blocks input and expires automatically.
472 -##
Session and power 474 -Session UI is modal, focused, and keyboard navigable.
483 -- monitor power off/on
485 -Destructive actions require confirmation.
486 -Tests route through `testHarness` with `nativeActionRoute` disabled.
488 -Enter confirms the focused safe or confirmed action.
489 -Pointer and keyboard paths are both tested.
491 -The power popout renders one UPower/session panel adapted from Nuguland session keys, Nuguland session grid confirmation, and Nuguland battery/profile rows: battery hero, external device batteries, power profile selector, keyboard-action grid, and confirmation strip.
495 -The lockscreen uses Quickshell WlSessionLock and PAM.
499 -- focused password input
500 -- clear failure state
501 -- retry without reload
502 -- keyboard layout display
504 -- media transport if safe
505 -- notification summary without leaking sensitive bodies
506 -- clean unlock teardown
508 -Lock tests never expose secrets and never depend on live private data.
512 -The privilege prompt is isolated and security-first:
514 -- explicit app/action text
515 -- focused password input
516 -- clear deny/cancel/confirm buttons
517 -- no decorative distraction
519 -- isolated visual smoke
521 -##
Screenshot and color tools 523 -Screenshots use niri native actions:
525 -- interactive screenshot UI
528 -- explicit save path inside the smoke run dir during tests
529 -- pointer visibility under caller control
530 -- recent capture list
531 -- copy/save/open actions from recorded files
533 -The screenshot popout renders one niri-native capture panel adapted from Nuguland AreaPicker and Nuguland region selector: focused screen/window actions, region selection entry, color pick action, recent capture rows, toolbar action rail, and selection-preview geometry using dim mask, cutout, dimensions, handles, and bounded Nuguland corner accents.
535 -Color picking uses niri native color picking.
536 -The result appears in OSD, clipboard action, and diagnostics.
540 -Clipboard UI provides:
542 -- searchable history
543 -- pinning if retained
545 -- delete action if backend supports it
546 -- private-mode visual state
547 -- launcher provider rows
549 -The clipboard popout renders a single history panel adapted from Nuguland popout wrapping and Nuguland clipboard/list chrome: private-mode chip, search field, pinned-first rows, masked action rail, scroll-edge fades, copy/paste/pin/delete actions, and launcher row parity.
551 -The backend is isolated behind `Clipboard.qml` and must clean helper processes.
555 -Tray support includes full DBusMenu fidelity:
565 -- wheel where the item supports it
566 -- keyboard navigation
568 -Tray menus use the bar popout host and anchor to the tray item.
569 -The tray popout renders one native menu panel adapted from Nuguland TrayItem, Nuguland SysTray/MenuView, and Nuguland overflow grid: item grid, attention status, action/separator/submenu/check/radio/disabled rows, one-expanded-submenu collapse, and close propagation.
573 -Connectivity combines network and Bluetooth into one popout while keeping compact bar indicators.
577 -- network connection name/type/state
578 -- WiFi signal and security when available
579 -- Bluetooth adapter state
580 -- connected devices and battery where available
581 -- loading and error states
583 -Actions are service-owned, bounded, and tested with isolated harness state.
587 -Media uses MPRIS through Quickshell.
591 -- active player election
592 -- play/pause/next/previous
594 -- volume handoff to audio service
595 -- shuffle/repeat if supported
596 -- cover art state with deterministic no-art rendering
597 -- compact bar summary
601 -No audio visualizer dependency.
602 -Any line/curve motif is driven by MPRIS progress or playback state.
604 -##
Resources and battery 606 -Resources use native file/service reads without shell pipelines.
611 -- charging/discharging
613 -- health if available
614 -- external devices if available
615 -- power profile if available
624 -- process summary only if implemented without heavy process churn
628 -Diagnostics is developer-only introspection.
630 -It is not a bar widget.
632 -It is reachable through IPC or explicit developer workflows only.
638 -- event stream status
639 -- process ownership table
641 -- current popout anchor/progress
642 -- notification counts
643 -- screenshot/color picker backend status
646 -- service status grid
647 -- reference contract rail
648 -- surface anchor map
649 -- failure shake slot
651 -It does not mutate visual preferences.
655 -IPC is for tests and owned workflow commands only.
659 -- dispatch `hotkey <id>` through Nuguland action records
660 -- launch an owned app/action by id
661 -- open/close/toggle each major surface
662 -- query service state snapshots
663 -- inject isolated harness data for tests
664 -- trigger screenshot/color pick harness routes
665 -- trigger OSD messages
666 -- query popout geometry and animation progress
667 -- query cleanup/process ownership
669 -IPC must stay small enough to audit manually.
673 -Production proof uses nested niri only.
677 -- creates a unique run dir
678 -- creates private HOME, XDG paths, cache, state, and screenshot path
679 -- writes a minimal generated niri KDL
680 -- validates KDL with `niri validate -c`
681 -- starts nested niri with a supervised Quickshell command
682 -- owns a private process group
683 -- records every child process
684 -- captures stdout/stderr per process
685 -- drives pointer, keyboard, wheel, drag, screenshot, and IPC checks
686 -- captures animation frames, not only final states
687 -- deletes the run dir on success
688 -- keeps evidence on failure
692 -- bar appears on every screen
693 -- every bar popout anchors and morphs correctly
694 -- notification toast anchors and morphs correctly
695 -- launcher opens, searches, focuses, routes harness actions, and closes
696 -- OSD appears and expires
697 -- screenshot actions write into the run dir
698 -- color picker harness route returns a deterministic value
699 -- clipboard UI works with private data
700 -- tray menu renders isolated DBusMenu fixtures
701 -- session destructive actions stay harness-routed and two-step
702 -- lock and privilege prompt instantiate and dismiss in safe mode
704 -- no unowned processes
705 -- no lingering DBus helpers
706 -- no leftover screenshot, clipboard, shell, or temp helpers
707 -- no leftover run dirs on success
711 -Top-level essentials:
719 -- test harness scripts
720 -- PAM files for lock
721 -- generated-data readers needed by Nugu
725 -- stale Markdown inventories
727 -- old source inventories
729 -- split backend abstractions
731 -- alternate visual families
732 -- generated screenshots/logs/temp files
733 -- scratch prototypes
734 -- undocumented helpers
738 -Nuguland is ready when:
740 -- the source tree contains only essential files
741 -- `SPEC.md` is the single design authority
742 -- all widgets are rebuilt against services
743 -- no widget spawns a process
744 -- every process is owned and cleanup-proven
745 -- nested niri smoke passes from a clean run dir
746 -- visual evidence proves every popout and toast morphs from its anchor
747 -- pointer and keyboard evidence covers every surface
748 -- screenshot and color picking use niri native features
749 -- Nugu colors and IBM Plex fonts are consistent everywhere
750 -- destructive actions are two-step and harness-routed in tests
751 -- no stale docs or unused QML remain