phosphor-shell

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

Responsibility

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.

Key types

Type	Purpose
ShellEngine	Top-level lifecycle: QML engine, config discovery, hot reload.
ShellLoader	Discovers and loads the user's QML config from XDG paths.
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	Decodes the desktop wallpaper off the GUI thread; reached from QML via ShellGlobal.wallpaper.
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	ext-foreign-toplevel-list-v1 consumer (window list for taskbars).

QML module

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:

• ShaderBackground — animated shader surface (from phosphor-rendering).
• IdleInhibitor, IdleNotifier — idle inhibition and idle detection (from phosphor-wayland).
• ForeignToplevel — one entry of the Toplevels window list (uncreatable; vended by Toplevels).

Dependencies

• Qt6::Core, Qt6::Gui, Qt6::Quick, Qt6::Qml
• `phosphor-layer`, `phosphor-rendering`, `phosphor-shaders`, `phosphor-wayland`

The shell binary is gated behind the BUILD_PHOSPHOR_SHELL CMake option (default OFF). The example under examples/phosphor-shell/ is the working reference for consumers.

See also

• `phosphor-services` — system tray, MPRIS media, and UPower power services.
• `phosphor-layer` — Role vocabulary the window types compose from.
• `phosphor-shell-patterns` — named Role recipes the panels use.