repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(nuguland): document architecture revamp

28b43b4347db158a2dbc4e715f7a7fe29d9792a7

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (1)

quickshell/nuguland/NUGULAND-ARCHITECTURE-AND-AGENT-REVAMP.md

Added
new file mode 100644
1 +# nuguland architecture and agent revamp
3 +## purpose
5 +This document records the architecture research for Nuguland and the proposed changes that should make Quickshell development more effective with coding agents.
7 +It compares Nuguland with the `quattro` branch of Omarchy, which also uses Quickshell. The goal is not to copy Omarchy, but to identify the conventions that make its code easier to inspect, modify, and validate.
9 +## research basis
11 +Inspected:
13 +- installed Quickshell 0.3.1;
14 +- Quickshell 0.3.1 documentation;
15 +- the Nuguland source tree and its project instructions;
16 +- Nuguland's nested niri UI-test contract;
17 +- Omarchy's `quattro` branch, especially `shell/README.md`, `shell/plugins/README.md`, `shell/plugins/bar/README.md`, the plugin registry, shared UI components, and shell tests.
19 +Primary references:
21 +- <https://quickshell.org/docs/v0.3.1/guide/introduction/>
22 +- <https://quickshell.org/docs/v0.3.1/guide/qml-language/>
23 +- <https://quickshell.org/docs/v0.3.1/guide/size-position/>
24 +- <https://quickshell.org/docs/v0.3.1/guide/install-setup/#language-server>
25 +- <https://quickshell.org/docs/v0.3.1/types/Quickshell.Io/IpcHandler/>
26 +- Omarchy `quattro`: <https://github.com/basecamp/omarchy/tree/quattro/shell>
28 +## verdict
30 +Both Nuguland and Omarchy Quattro use the same fundamental Quickshell architecture: one long-running QML process with a `ShellRoot`, services, windows, and reactive state.
32 +Quattro does not appear more successful because Quickshell itself is different. It is easier for agents because it offers better **agent affordances**:
34 +- feature-local directories;
35 +- repeated manifest and entry-point conventions;
36 +- explicit shared UI modules;
37 +- fewer central registration edits;
38 +- named feature tests;
39 +- a canonical configuration model.
41 +Nuguland has stronger isolation, stronger static checks, and more trustworthy interaction evidence. Its main weakness is change locality. A local feature change often requires understanding and editing several central files.
43 +The recommended response is therefore:
45 +> Preserve Nuguland's service boundaries and test rigor. Adopt Quattro's locality, conventions, and feature contracts without importing its complete plugin ecosystem.
47 +## Quickshell mental model
49 +Quickshell is a QML runtime with native desktop integrations. It is not an opinionated application architecture. The project author decides how services, UI, configuration, and lifecycle are organized.
51 +A typical shell has this shape:
53 +```text
54 +shell.qml
55 + ├── long-lived services and state owners
56 + ├── IPC handlers
57 + ├── per-screen window instances
58 + ├── shared UI components
59 + └── feature surfaces
60 +```
62 +### root object and object graph
64 +Quickshell loads `shell.qml` and creates one QML object graph. QML properties are reactive bindings. When a dependency changes, dependent expressions are reevaluated.
66 +A root object does not have to be a particular Quickshell type. `ShellRoot` is useful for shell-level settings and composition. `Scope` is useful for long-lived non-visual objects.
68 +### windows and surfaces
70 +- `PanelWindow` is for bars, layer-shell panels, and overlays.
71 +- `FloatingWindow` is for ordinary desktop windows.
72 +- `PopupWindow` is for popup surfaces attached to another Quickshell window.
73 +- `WlrLayershell` controls layer-shell behavior on supported Wayland compositors.
75 +A window's actual size and position belong to the window or its container. Its implicit size expresses desired size.
77 +### screens and lifetime
79 +`Variants` creates instances from a model. `Quickshell.screens` is commonly used to create one bar or overlay per output.
81 +Services should normally live outside screen variants. Otherwise every monitor can create duplicate processes, timers, native service instances, or state owners.
83 +`Loader` controls deferred creation and destruction. A loaded item does not exist before the loader has created it. Any state that must survive loader recreation belongs in a longer-lived owner.
85 +### I/O and IPC
87 +Quickshell provides native QML-facing boundaries such as:
89 +- `Process` and `StdioCollector` for subprocesses;
90 +- `FileView` for file state and watching;
91 +- PipeWire, MPRIS, UPower, notifications, Polkit, PAM, and other service modules;
92 +- `IpcHandler` for typed external calls and properties.
94 +IPC functions should declare argument and return types explicitly. IPC is a public boundary, not a substitute for ordinary internal object ownership.
96 +### geometry rules
98 +The key layout rule is:
100 +```text
101 +implicit size flows from children to parents
102 +actual size flows from parents to children
103 +```
105 +Avoid these common errors:
107 +- using `childrenRect` to determine a container's implicit size when children are anchored to that container;
108 +- combining a layout, anchors, and explicit coordinates for the same axis;
109 +- setting a managed child's size instead of letting its container own it;
110 +- assuming invisible or unloaded content contributes useful geometry.
112 +### editor and tooling
114 +Quickshell recommends Qt's QML language server. A `.qmlls.ini` file next to `shell.qml` lets Quickshell generate machine-specific language-server configuration. The generated file should remain ignored.
116 +`PanelWindow` has known static-tooling limitations. A language-server failure to resolve it is not proof that valid runtime QML is broken. Use the matching Qt version, `qmllint`, the actual Quickshell runtime, and isolated compositor tests.
118 +## current Nuguland architecture
120 +Nuguland has a single shell composition root with injected services. Important parts include:
122 +```text
123 +shell.qml
124 + ├── services: audio, brightness, network, niri, power, media, vault, ...
125 + ├── bar windows
126 + ├── OSD and notification surfaces
127 + ├── privilege and lock surfaces
128 + ├── SurfaceManager
129 + └── PopoutHost
130 +```
132 +Current strengths:
134 +- service and panel separation already exists for important features;
135 +- dependencies use typed `required property` injection;
136 +- pure JavaScript logic has Node tests;
137 +- Rust has dedicated tests and strict clippy checks;
138 +- QML linting uses Qt 6 and zero warnings;
139 +- the UI runner uses nested niri, headless Weston, synthetic services, a private bus, retained logs, and screenshots;
140 +- the project explicitly separates static, load, interaction, and visual evidence.
142 +Current friction:
144 +- the source tree is mostly flat;
145 +- `shell.qml` contains substantial composition and IPC wiring;
146 +- `Bar.qml` contains broad feature knowledge;
147 +- `SurfaceManager.qml` owns lifecycle, geometry, panel state, and feature-specific sizing;
148 +- `PopoutHost.qml` has many service dependencies;
149 +- popup selection uses central switch cases and inline component declarations;
150 +- `popoutCatalog.js` describes popup content but does not author all registration;
151 +- UI code frequently consumes dynamic `stateJson()` snapshots;
152 +- a feature change can require synchronized edits across host, bar, catalog, service wiring, and fixtures.
154 +The problem is not simply file length. Quattro's shell and bar are also large. The more important problem is **change fanout**: how many unrelated places must be understood and kept consistent for one feature.
156 +## Quattro architecture
158 +Omarchy Quattro keeps one long-running `ShellRoot`, but organizes the feature surface around plugins:
160 +```text
161 +shell/
162 + shell.qml
163 + services/
164 + PluginRegistry.qml
165 + BarWidgetRegistry.qml
166 + service APIs
167 + plugins/
168 + bar/
169 + panels/
170 + overlays/
171 + menus/
172 + services/
173 + Ui/
174 + Commons/
175 +```
177 +Each plugin has a manifest with:
179 +- schema version;
180 +- stable ID;
181 +- display metadata;
182 +- declared kinds;
183 +- entry points;
184 +- optional bar-widget settings and defaults.
186 +The host discovers plugins, loads services, summons panels, injects APIs, and reads one versioned `shell.json` configuration.
188 +The useful ideas are:
190 +- feature directories are the default unit of work;
191 +- entry points are conventional and discoverable;
192 +- configuration is canonical and versioned;
193 +- common panel lifecycle is shared;
194 +- common styling and controls are in explicit modules;
195 +- JavaScript model logic is kept separately testable;
196 +- manifest entry points can be loaded as a generic contract test.
198 +The ideas that should not be copied without a real requirement are:
200 +- a third-party plugin marketplace;
201 +- dynamic capability facades everywhere;
202 +- unsandboxed user code as a distribution model;
203 +- broad `var` service APIs;
204 +- mixing native service ownership and visual presentation merely because a plugin makes it convenient.
206 +Quattro's own source demonstrates that its plugin facades are not a complete QML sandbox. Visual plugins share the host scene, and plugin code has user-level process and file access.
208 +## why agents struggle with Nuguland
210 +### QML has hidden semantics
212 +Agents often approach QML as if it were imperative UI code or web layout code. This causes:
214 +- imperative assignments that replace bindings;
215 +- duplicate state owners;
216 +- geometry binding loops;
217 +- invalid assumptions about `id` scope;
218 +- focus bugs after loader recreation;
219 +- missing handling for asynchronous service updates;
220 +- incorrect assumptions about when a component exists.
222 +### central wiring increases context cost
224 +The agent must inspect the service, the panel, the surface manager, the popup host, the bar caller, the relevant specification, and the isolated fixture. This is correct for safety, but expensive for every iteration.
226 +### dynamic snapshots hide contracts
228 +`stateJson()` is useful for diagnostics and external boundaries, but it hides the actual shape of the internal API from QML tooling and from agents. A consumer can silently depend on a missing, renamed, or differently typed field.
230 +### strict proof reveals more failures
232 +Nuguland requires:
234 +- zero-warning lint;
235 +- isolated runtime loading;
236 +- actual pointer and keyboard interaction;
237 +- focus and dismissal behavior;
238 +- retained logs;
239 +- rendered screenshots;
240 +- visual review.
242 +This makes Nuguland more honest, but it can make it look less successful than a project where runtime paths are conditional or visual output is only captured.
244 +## target architecture
246 +The target is a feature-oriented structure with explicit host boundaries, not necessarily a plugin marketplace.
248 +A feature should trend toward:
250 +```text
251 +features/audio/
252 + Service.qml
253 + Panel.qml
254 + Model.js
255 + feature.json
256 + README.md
257 + tests/
258 +```
260 +Equivalent names are acceptable. The responsibilities are the invariant.
262 +### service
264 +The service owns:
266 +- native Quickshell integrations;
267 +- mutable system state;
268 +- subprocesses and file I/O;
269 +- command execution;
270 +- external updates;
271 +- stable typed properties and intent methods.
273 +The service does not own visual geometry or panel focus.
275 +### model
277 +The model owns pure transformations:
279 +- classification;
280 +- filtering;
281 +- sorting;
282 +- formatting;
283 +- normalization;
284 +- state-to-label decisions.
286 +The model should be directly testable without QML or a compositor.
288 +### panel
290 +The panel owns:
292 +- presentation;
293 +- local cursor and focus state;
294 +- user intent emission;
295 +- empty, unavailable, pending, error, and long-content states;
296 +- keyboard and pointer behavior.
298 +The panel does not import native services when a Nuguland service already owns them.
300 +### host
302 +The host owns:
304 +- surface creation;
305 +- screen selection;
306 +- popup placement;
307 +- lifecycle transitions;
308 +- focus entry and return;
309 +- outside dismissal;
310 +- shared animation policy;
311 +- dependency injection.
313 +The host should not contain feature-specific rendering or feature-specific service logic.
315 +### descriptor
317 +A small descriptor should eventually author or validate:
319 +- stable feature ID;
320 +- bar or popup entry point;
321 +- preferred and minimum dimensions;
322 +- supported surface kind;
323 +- fixture name;
324 +- optional user settings schema;
325 +- empty-state sizing policy.
327 +The descriptor should remove duplicated registration rather than become a second source of truth.
329 +## artifact rules
331 +The optimal Quickshell artifact is a self-contained vertical slice, not the smallest possible QML file.
333 +Use these rules:
335 +1. Keep one long-lived shell process per session.
336 +2. Keep services outside per-screen variants unless duplication is intentional.
337 +3. Use `PanelWindow` for layer-shell surfaces and `FloatingWindow` for ordinary windows.
338 +4. Use typed `required property` injection across component boundaries.
339 +5. Keep one mutable state owner for each concern.
340 +6. Keep one geometry owner per axis.
341 +7. Use shared controls and theme tokens.
342 +8. Keep pure logic outside QML where possible.
343 +9. Use JSON for IPC and diagnostics, not as the default internal API.
344 +10. Use loaders for expensive or infrequently used surfaces.
345 +11. Use `keepLoaded`-style retention only when state or protocol lifetime requires it.
346 +12. Avoid repeated polling when event-driven service state is available.
347 +13. Snapshot unstable native collections before feeding them into repeaters when the service requires it.
348 +14. Do not use `childrenRect` as a general sizing shortcut.
349 +15. Do not weaken linting, isolation, or visual proof to make an agent iteration green.
351 +## agent playbook
353 +Every Quickshell task should begin with a bounded contract:
355 +```text
356 +Feature:
357 +Primary user action:
358 +Observable result:
360 +State owner:
361 +Geometry owner:
362 +Service boundary:
363 +Caller:
364 +Surface host:
366 +States:
367 +- normal
368 +- empty
369 +- unavailable
370 +- disabled
371 +- pending
372 +- failure
373 +- long content
375 +Input:
376 +- pointer behavior
377 +- keyboard behavior
378 +- focus entry
379 +- focus return
380 +- Escape
381 +- outside click
383 +Proof:
384 +- pure logic test
385 +- QML load test
386 +- interaction fixture
387 +- screenshots
388 +- full project gate
389 +```
391 +The recommended agent sequence is:
393 +1. Inspect the installed `qs` version.
394 +2. Read the matching Quickshell documentation and installed type metadata.
395 +3. Read project instructions and the relevant specification.
396 +4. Trace caller, surface host, panel, service, and existing fixture.
397 +5. Declare state ownership and geometry ownership before editing.
398 +6. Implement or test pure model logic first.
399 +7. Implement one complete interaction.
400 +8. Run static and load checks.
401 +9. Run the named isolated interaction fixture.
402 +10. Inspect screenshots and logs.
403 +11. Run the full repository gate.
405 +The agent should not begin by proposing a repository-wide rewrite. It should begin with one complete feature slice and measure whether the new convention reduces change fanout.
407 +## validation contract
409 +Evidence levels must remain separate:
411 +### static
413 +Examples:
415 +- Qt 6 `qmllint`;
416 +- QML formatting;
417 +- JavaScript syntax and unit tests;
418 +- Rust formatting, clippy, and tests;
419 +- shell checks;
420 +- shader freshness and compilation checks.
422 +Static checks do not prove that a surface loads or renders correctly.
424 +### load
426 +Load the actual Quickshell entry point or an isolated feature fixture. Check complete stdout and stderr for:
428 +- import failures;
429 +- binding loops;
430 +- type errors;
431 +- creation failures;
432 +- runtime warnings.
434 +### interaction
436 +Exercise the real QML surface inside nested niri:
438 +- pointer activation;
439 +- keyboard activation;
440 +- Tab and reverse Tab where applicable;
441 +- arrow keys;
442 +- Escape;
443 +- outside dismissal;
444 +- focus return;
445 +- external service updates;
446 +- empty and unavailable states;
447 +- asynchronous success and failure.
449 +### visual
451 +Capture and review the real rendered surface at supported output sizes and scales. Check:
453 +- clipping;
454 +- alignment;
455 +- hierarchy;
456 +- typography;
457 +- focus visibility;
458 +- state feedback;
459 +- long-content behavior;
460 +- animation and dismissal geometry.
462 +A screenshot capture is evidence of rendering, not automatic visual approval.
464 +## recommended migration strategy
466 +### phase 1: audio pilot
468 +Use audio as the reference slice because it already has:
470 +- a service and panel split;
471 +- pure JavaScript logic;
472 +- typed service injection;
473 +- production task-fixture coverage;
474 +- pointer, keyboard, external-update, and disabled-state cases.
476 +The pilot should introduce only the minimum feature-local convention and descriptor needed to reduce host edits.
478 +Measure:
480 +- central files touched by a feature change;
481 +- context files required before editing;
482 +- number of synchronized registration points;
483 +- number of source-regex assertions;
484 +- iterations before clean isolated evidence;
485 +- iterations before full lint passes.
487 +### phase 2: descriptor-backed registration
489 +Make one descriptor authoritative for popup identity, dimensions, entry point, fixture, and user-facing metadata. Add a generic contract test that loads every descriptor entry point with fixture dependencies.
491 +Do not remove existing checks until the descriptor has equivalent coverage.
493 +### phase 3: host decomposition
495 +Reduce the responsibilities of `SurfaceManager` and `PopoutHost` without changing the one-process model.
497 +Candidate boundaries:
499 +- popup lifecycle and focus controller;
500 +- pure surface layout functions;
501 +- feature panel state retention;
502 +- descriptor-backed content registry;
503 +- service composition root.
505 +### phase 4: typed internal service APIs
507 +Replace internal `stateJson()` consumption with typed readonly properties or QML models where practical. Keep JSON at IPC and diagnostics boundaries.
509 +### phase 5: feature-oriented test commands
511 +Add named public targets equivalent to:
513 +```text
514 +just test audio
515 +just load-test audio
516 +just ui-test audio
517 +```
519 +The exact commands must remain consistent with the repository's justfile contract. The purpose is a short, discoverable feedback loop, not a second test system.
521 +## non-goals
523 +This revamp does not currently require:
525 +- a third-party plugin marketplace;
526 +- dynamic capability facades;
527 +- a new theme system;
528 +- a rewrite of all QML files;
529 +- weakening the nested compositor sandbox;
530 +- replacing service ownership with UI-owned native integrations;
531 +- making every feature independently distributable.
533 +## success criteria
535 +The revamp is successful when an agent can implement a bounded feature by inspecting one feature directory, its descriptor, its caller, its service boundary, and its named fixture, without learning the entire shell first.
537 +The architecture must still preserve:
539 +- one authoritative state owner;
540 +- safe service boundaries;
541 +- deterministic isolated runtime tests;
542 +- zero-warning project checks;
543 +- real interaction evidence;
544 +- reviewed rendered output;
545 +- explicit security and lifecycle behavior.