Quickshell 0.3.1 desktop shell for niri, inside the dorkfiles repo. One long-lived QML process per session: ShellRoot, services, per-screen windows, feature surfaces.
QML domain truths:
bindings are reactive; imperative assignments destroy them;
implicit size flows from children to parents, actual size from parents to children;
one mutable state owner per concern, one geometry owner per axis;
services live outside per-screen Variants unless duplication is intended;
a Loader item does not exist before creation; state that survives reload belongs to a longer-lived owner;
PanelWindow cannot be resolved by static tooling; that is an upstream limitation, not breakage.
Ownership split, invariant:
service — native integrations, system state, subprocesses, typed properties, intent methods; never geometry or focus.
model — pure transformations; testable without QML or compositor.
panel — presentation, local cursor and focus state, intent emission, every content state.
host — surface creation, placement, lifecycle, focus entry and return, dismissal, animation policy, injection; never feature rendering or feature service logic.
Registration, binding target: one typed QML registry entry per feature covers service, panel, bar control, sizing data, and fixture name. IPC handlers stay explicit and typed in shell.qml. The registry is typed QML, never runtime JSON. Geometry data lives in entries; generic geometry computation stays in the host. Lock and privilege keep specialized controllers; the popup host is a default, not a universal lifecycle.
Boundaries: typed required property injection across components; JSON only at IPC and diagnostics edges; startup composition only.
Docs hierarchy
This System, RULES, and the specs under .system/specs/ are authority.
READMEs are human overview and carry no binding rules.
Non-goals
No plugin marketplace, no capability facades, no new theme system, no distribution model, no weakening of isolation or proof.
# SYSTEM
## Nuguland
Quickshell 0.3.1 desktop shell for niri, inside the dorkfiles repo. One long-lived QML process per session: `ShellRoot`, services, per-screen windows, feature surfaces.
QML domain truths:
- bindings are reactive; imperative assignments destroy them;
- implicit size flows from children to parents, actual size from parents to children;
- one mutable state owner per concern, one geometry owner per axis;
- services live outside per-screen `Variants` unless duplication is intended;
- a `Loader` item does not exist before creation; state that survives reload belongs to a longer-lived owner;
- `PanelWindow` cannot be resolved by static tooling; that is an upstream limitation, not breakage.
Ownership split, invariant:
- **service** — native integrations, system state, subprocesses, typed properties, intent methods; never geometry or focus.
- **model** — pure transformations; testable without QML or compositor.
- **panel** — presentation, local cursor and focus state, intent emission, every content state.
- **host** — surface creation, placement, lifecycle, focus entry and return, dismissal, animation policy, injection; never feature rendering or feature service logic.
Registration, binding target: one typed QML registry entry per feature covers service, panel, bar control, sizing data, and fixture name. IPC handlers stay explicit and typed in `shell.qml`. The registry is typed QML, never runtime JSON. Geometry data lives in entries; generic geometry computation stays in the host. Lock and privilege keep specialized controllers; the popup host is a default, not a universal lifecycle.
Boundaries: typed `required property` injection across components; JSON only at IPC and diagnostics edges; startup composition only.
## Docs hierarchy
This System, RULES, and the specs under `.system/specs/` are authority.
READMEs are human overview and carry no binding rules.
## Non-goals
No plugin marketplace, no capability facades, no new theme system, no distribution model, no weakening of isolation or proof.