1 +#
nuguland architecture and agent revamp 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.
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.
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>
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:
55 + ├── long-lived services and state owners
57 + ├── per-screen window instances
58 + ├── shared UI components
59 + └── feature surfaces
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.
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.
98 +The key layout rule is:
101 +implicit size flows from children to parents
102 +actual size flows from parents to children
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:
124 + ├── services: audio, brightness, network, niri, power, media, vault, ...
126 + ├── OSD and notification surfaces
127 + ├── privilege and lock surfaces
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.
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:
165 + BarWidgetRegistry.qml
177 +Each plugin has a manifest with:
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 234 +- zero-warning lint;
235 +- isolated runtime loading;
236 +- actual pointer and keyboard interaction;
237 +- focus and dismissal behavior;
239 +- rendered screenshots;
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:
260 +Equivalent names are acceptable. The responsibilities are the invariant.
266 +- native Quickshell integrations;
267 +- mutable system state;
268 +- subprocesses and file I/O;
269 +- command execution;
271 +- stable typed properties and intent methods.
273 +The service does not own visual geometry or panel focus.
277 +The model owns pure transformations:
284 +- state-to-label decisions.
286 +The model should be directly testable without QML or a compositor.
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.
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.
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;
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.
331 +The optimal Quickshell artifact is a self-contained vertical slice, not the smallest possible QML file.
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.
353 +Every Quickshell task should begin with a bounded contract:
357 +Primary user action:
386 +- interaction fixture
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:
417 +- JavaScript syntax and unit tests;
418 +- Rust formatting, clippy, and tests;
420 +- shader freshness and compilation checks.
422 +Static checks do not prove that a surface loads or renders correctly.
426 +Load the actual Quickshell entry point or an isolated feature fixture. Check complete stdout and stderr for:
431 +- creation failures;
436 +Exercise the real QML surface inside nested niri:
438 +- pointer activation;
439 +- keyboard activation;
440 +- Tab and reverse Tab where applicable;
443 +- outside dismissal;
445 +- external service updates;
446 +- empty and unavailable states;
447 +- asynchronous success and failure.
451 +Capture and review the real rendered surface at supported output sizes and scales. Check:
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.
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:
515 +just load-test audio
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.
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.
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.