# 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.