Phosphor is the library layer of the Phosphor desktop: focused Qt6 / Wayland libraries for window placement, rendering, layer-shell surfaces and desktop shell services. Each library owns a single responsibility, so you pull in only what you need.
The libraries live in two repositories, core libraries in phosphor-libs and shell libraries in phosphor-shell-libs, each under libs/. These docs are generated from their public headers, with each library's hand-written design notes coming from its README.md where it has one.
The libraries are organized into categories. Click a library name for its design and examples page, or a namespace for the generated API surface. This section is generated from the website's catalogue (src/data/libraries.ts) by scripts/mainpage-libraries.mjs.
Foundations Layout Engines Rendering Surfaces Shell Services
Identity, configuration, D-Bus, IPC, scripting and registries. The plumbing everything else uses.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-config | PhosphorConfig | Pluggable configuration backends with schema + migration. |
| phosphor-context-resolver | PhosphorContext | Frozen-snapshot gate over the mode, desktop, and activity cascade. |
| phosphor-dbus | PhosphorDBus | Generic, service-agnostic D-Bus client utilities. |
| phosphor-fsloader | PhosphorFsLoader | Watched-directory + metadata-pack loader skeleton. |
| phosphor-geometry | PhosphorGeometry | Pure-function geometry helpers shared by both engines. |
| phosphor-identity | PhosphorIdentity | Stable cross-process identity formats. |
| phosphor-ipc | PhosphorIpc | Typed JSON-over-Unix-socket invocation channel for the shell. |
| phosphor-protocol | PhosphorProtocol | Shared D-Bus service names, wire types, and client helpers. |
| phosphor-registry | PhosphorRegistry | Factory-by-name registry and plugin loader for shell extension seams. |
| phosphor-scripting | PhosphorScripting | Generic sandboxed Luau host with CPU and heap guards. |
| phosphor-shortcuts | PhosphorShortcuts | Pluggable global-shortcut backends. |
| phosphor-workspaces | PhosphorWorkspaces | Virtual desktop and activity tracking. |
Data models for zones, tiling layouts and the sources that provide them.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-layout-api | PhosphorLayout | Layout description interfaces + provider registry. |
| phosphor-tiles | PhosphorTiles | Tiling algorithms (Luau via pluau), the registry, and TilingState. |
| phosphor-zones | PhosphorZones | Manual zone data model, registry, and ILayoutSource. |
The snapping, tiling and scrolling engines, with shared placement policy and window rules.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-engine | PhosphorEngine | Unified placement-engine surface + shared service contracts. |
| phosphor-placement | PhosphorPlacement | Window-zone tracking, floating state, auto-snap, and resnap. |
| phosphor-rules | PhosphorRules | Unified window/context rule engine with one match language and cache. |
| phosphor-scroll-engine | PhosphorScrollEngine | Scrolling-strip placement engine. |
| phosphor-snap-engine | PhosphorSnapEngine | Manual zone-based placement engine. |
| phosphor-tile-engine | PhosphorTileEngine | Automatic-tiling placement engine. |
Shaders, animation, audio input and window decoration rendering.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-animation | PhosphorAnimation | Motion runtime + shader-transition runtime with JSON profiles. |
| phosphor-audio | PhosphorAudio | Audio spectrum input for audio-reactive shaders. |
| phosphor-pointer | PhosphorPointerShaders | Pointer shader packs: trails, halos, and click ripples around the cursor. |
| phosphor-rendering | PhosphorRendering | ShaderEffect / ShaderNodeRhi / runtime GLSL → SPIR-V. |
| phosphor-shaders | PhosphorShaders | Shader-effect registry, base UBO layout, uniform extension contract. |
| phosphor-surface | PhosphorSurfaceShaders | Per-window shader effects and window decoration profiles. |
| phosphor-surface-quick | PhosphorSurfaceQuick | Qt Quick host for surface shader packs. |
| phosphor-theme | PhosphorTheme | Active design-token store with hot reload and matugen retint. |
Wayland and layer-shell surfaces, screens, and the bridge to the compositor.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-compositor | PhosphorCompositor | Compositor-plugin SDK — the plugin side of the daemon / plugin split. |
| phosphor-layer | PhosphorLayer | Layer-shell surface primitives: Surface, factory, registry, coordinator. |
| phosphor-popout | PhosphorPopout | Central arbiter for transient popout lifetime, focus, and exclusivity. |
| phosphor-screens | PhosphorScreens | Physical and virtual screen topology resolver. |
| phosphor-surfaces | PhosphorSurfaces | Surface manager with QML loading and Vulkan wiring. |
| phosphor-wayland | PhosphorWayland | Custom QPA plugin + LayerSurface wrapper. |
Building blocks for a desktop shell: theme, popouts, widgets and the shell surfaces.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-control | PhosphorControl | Reusable Qt6/QML/Kirigami settings-app framework. |
| phosphor-overlay | PhosphorOverlay | Per-screen layer-shell shell hosts with named slot vocabulary. |
| phosphor-shell | PhosphorShell | Quickshell-style declarative QML framework for layer-shell desktop shells. |
| phosphor-shell-bar | Phosphor.Bar (QML) | The spectrum-rail bar surface and its built-in widgets. |
| phosphor-shell-control-center | Phosphor.ControlCenter (QML) | Quick-settings rails for Wi-Fi, Bluetooth, audio, brightness, and idle. |
| phosphor-shell-dashboard | Phosphor.Dashboard (QML) | Full-screen dashboard and keybind cheatsheet drawn on the placement map. |
| phosphor-shell-launcher | PhosphorShellLauncher | Spotlight-style launcher over apps, windows, clipboard, arithmetic, and commands. |
| phosphor-shell-lock | PhosphorShellLock | Lockscreen surface that draws the layout you left as outlines. |
| phosphor-shell-notifications | Phosphor.Notifications (QML) | Toast framework for notification popups. |
| phosphor-shell-osd | Phosphor.OSD (QML) | On-screen-display framework for volume, brightness, and friends. |
| phosphor-shell-patterns | PhosphorShellPatterns | Named UI-pattern recipes on top of phosphor-layer Role. |
| phosphor-shell-picker | PhosphorShellPicker | Wallpaper and theme strip that previews palettes on the live desktop. |
| phosphor-shell-polkit | Phosphor.Polkit (QML) | PolicyKit authentication prompt attached to the requesting window. |
| phosphor-shell-power | Phosphor.Power (QML) | Session menu for lock, suspend, hibernate, log out, restart, and shut down. |
| phosphor-shell-widgets | Phosphor.Widgets (QML) | Material 3 QML atoms every shell surface composes from. |
System services the shell binds to, from the tray and battery to polkit and the session.
| Library | Namespace | Responsibility |
|---|---|---|
| phosphor-service-bluetooth | PhosphorServiceBluetooth | BlueZ adapter and device state with device pairing. |
| phosphor-service-brightness | PhosphorServiceBrightness | Display and keyboard backlight brightness control. |
| phosphor-service-clipboard | PhosphorServiceClipboard | De-duplicated, persistent clipboard history. |
| phosphor-service-icontheme | PhosphorServiceIconTheme | XDG icon-theme lookup and a QML image provider. |
| phosphor-service-idle | PhosphorServiceIdle | Multi-stage Wayland idle monitoring and inhibition. |
| phosphor-service-lock | PhosphorServiceLock | PAM authentication and Wayland session-lock lifecycle. |
| phosphor-service-mpris | PhosphorServiceMpris | MPRIS2 media-player discovery, status, and transport control. |
| phosphor-service-network | PhosphorServiceNetwork | NetworkManager device and connectivity state. |
| phosphor-service-notifications | PhosphorServiceNotifications | Freedesktop notification server and live history. |
| phosphor-service-pipewire | PhosphorServicePipeWire | Native PipeWire mixer for sinks, sources, and streams. |
| phosphor-service-polkit | PhosphorServicePolkit | PolicyKit authentication agent for the session. |
| phosphor-service-session | PhosphorServiceSession | logind session manager, power actions, and sleep inhibitors. |
| phosphor-service-sni | PhosphorServiceSni | StatusNotifierItem system-tray host with dbusmenu menus. |
| phosphor-service-upower | PhosphorServiceUPower | Battery and power-device status via UPower. |
All Phosphor libraries share a handful of cross-cutting conventions so anything you learn in one library transfers to the others:
All Phosphor libraries: LGPL-2.1-or-later. Consumers (including PlasmaZones) link against them under that license.