Quickshell-style declarative QML framework for layer-shell desktop shells. Provides the shell lifecycle (XDG config discovery, QML engine management) and the user-facing QML window types that create layer-shell surfaces.
The infrastructure layer between phosphor-wayland / phosphor-layer (which know how to make a layer-shell surface) and the consumer QML config that describes what the shell should look like. A shell binary constructs a ShellEngine, points it at an XDG-located config tree, and the engine instantiates the user's QML which declares PanelWindow, PopupWindow, and friends. Each window type creates the appropriate layer-shell surface through phosphor-layer underneath, so the QML author writes panels without touching wlr-protocol primitives.
ShellEngine also drives hot reload: it watches the config tree and the screen topology, rebuilds the QML engine on change, and saves/restores PersistentProperties state across the reload.
The API mirrors Quickshell where it matters (PanelWindow, Variants, LazyLoader, PersistentProperties, Process, FileView) so existing configs port with minimal rework.
| Type | Purpose |
|---|---|
| ShellEngine | Top-level lifecycle: QML engine, config discovery, hot reload. |
| ShellLoader | Discovers the app's shell.qml under <shellName>/ in the XDG config and data paths, falling back to a bundled shell URL the app supplies. The app names itself. |
| PanelWindow | Layer-shell-backed panel window with edge anchoring and exclusive zone. |
| PopupWindow | xdg-popup positioned against an anchor item, with in-place reposition. |
| FloatingWindow | XDG-toplevel window for non-shell auxiliary UI. |
| Variants | Lazy per-screen instantiation of declarative content. |
| LazyLoader | Defer-instantiation helper for expensive QML trees. |
| PersistentProperties | QML-friendly persistence of property values across launches and hot reloads. |
| Process | Sandboxed subprocess runner exposed to QML. |
| FileView | Watched-file reader for QML config-driven panels (/proc, /sys, config files). |
| SystemClock | Timer-driven clock (hours/minutes/seconds/date) with configurable tick precision. |
| WallpaperService | The shell's per-screen wallpaper store, decoded off the GUI thread. Reached from QML via ShellGlobal.wallpaper; ShellEngine keeps it in <config>/<shellName>/wallpaper.json. |
| Environment | Cross-platform env-var, locale, and runtime-dir helpers. |
| ShellGlobal | QML context object (PhosphorShell) with shell-wide config and runtime state. |
| ScreenModel | Reactive list of physical screens for per-screen Variants. |
| Toplevels | zwlr-foreign-toplevel-management-v1 consumer (window list for taskbars). |
| Workspaces | ext-workspace-v1 consumer (workspace list and switching for pagers). supported follows the global. |
ShellEngine registers the Phosphor.Shell import. Alongside the types above it re-exports a few from sibling libraries, so shell QML needs a single import:
An app passes its own name to ShellLoader and to ShellEngine::Deps::shellName; nothing here assumes a particular shell. Lambent is one, and its shell/ tree is a working reference for consumers.