Architecture
The compositor owns the desktop. Core provides the world runtime and brokers its authority. Everything else connects through explicit contracts.
Keep the render pass predictable
Section titled “Keep the render pass predictable”The plugin reads immutable frame state and draws prepared resources. Capture refresh, cursor changes, focus, workspace transitions and uploads run in a verified safe phase after the outer compositor frame. CPU workers decode assets; they never access compositor objects or GL. The simulation tick runs once per presented frame, queued outside the render pass, and moves by that frame’s real time. Pass tracking recovers when the compositor starts a pass and never finishes it (for example when a frame fails to allocate after a monitor change).
Read the contracts
Section titled “Read the contracts”| Boundary | Decision |
|---|---|
| Repositories and ownership | RFC-0001 |
| Processes, threads and frame graph | RFC-0002 |
| IPC, state, grants and failure | RFC-0003 |
| World content and validation | RFC-0004 |
| Pixels and input | RFC-0005 |
| Interaction and controllers | RFC-0006 |
| Extension hosts and SDK | RFC-0007 |
| Replaceable shells | RFC-0008 |
| Optional world-rendering process and power policy | RFC-0009 |
| World-supplied HUD styles (proposed) | Amendment to RFC-0004/0008 |
Rendering on a laptop
Section titled “Rendering on a laptop”The world renders below output resolution and is upscaled with FSR 1; dynamic resolution adjusts the scale in 1/16 steps to hold the frame rate. When nothing in view changes, core re-presents the last world frame instead of rendering a new one, and workspace walls recompose only when their windows change. A frame-rate target below the display rate renders on every second (or nth) presentation, evenly. Walls with windows are composed at the monitor’s resolution with mipmaps, so their text stays sharp. On machines with a discrete GPU, an optional worker supervised by hypruned can render the world there and return frames over DMA-BUF, under a power budget scaled to that GPU and with immediate local fallback; it also works when the compositor itself runs on an NVIDIA GPU. It is off by default (RFC-0009). Native application windows are always composited locally. The progress page has the measurements.
Honest failure boundaries
Section titled “Honest failure boundaries”A shell crash releases overlay input, and a restarted shell renews its credentials and resyncs from a snapshot. A daemon crash triggers the plugin’s desktop recovery watchdog. A malformed world fails staging before activation. Extensions will run as separate supervised processes and can’t execute inside the compositor; the host isn’t built yet. A plugin bug can still crash Hyprland, which is why that boundary stays small and is built and tested against exact compositor releases (Supported Hyprland versions).
Machine-readable contracts
Section titled “Machine-readable contracts”The schema repository owns the machine-readable definitions. The schema reference renders every published version of the world manifest, IPC protocol, input keymap, extension manifest and screen type descriptor, with diffs between versions and the raw JSON to download. Runtime validation uses pinned local copies, never the network.