Phosphor

Phosphor

Phosphor is a suite of focused Qt6 / Wayland libraries for building window-management tools. Each library owns a single responsibility; the suite is designed to be consumed à la carte, so you pull in only what you need.

The suite currently ships with PlasmaZones, the reference consumer, and the headers live under libs/phosphor-*/include/ in that repository. These docs are generated from those public headers, with each library's hand-written design notes coming from its README.md.

Libraries

The suite is organized into seven categories — click a library name for its design + examples page, or a namespace for the auto-generated API surface.

Foundations Layout Engines Rendering Surfaces Shell Services

Foundations

Low-level shared infrastructure every other layer builds on.

Library	Namespace	Responsibility
`phosphor-identity`	PhosphorIdentity	Stable cross-process identity formats (WindowId, ScreenId, VirtualScreenId)
`phosphor-geometry`	PhosphorGeometry	Pure-function geometry helpers shared by both engines
`phosphor-dbus`	PhosphorDBus	Generic, service-agnostic D-Bus client utilities
`phosphor-protocol`	PhosphorProtocol	Shared D-Bus service names, wire types, helpers
`phosphor-config`	PhosphorConfig	Pluggable configuration backends with schema + migration
`phosphor-fsloader`	PhosphorFsLoader	Watched-directory + metadata-pack loader skeleton
`phosphor-shortcuts`	Phosphor::Shortcuts	Pluggable global-shortcut backends
`phosphor-workspaces`	PhosphorWorkspaces	Virtual desktop and activity tracking
`phosphor-registry`	PhosphorRegistry	Factory-by-name registry plus plugin loader for UI extension seams
`phosphor-ipc`	PhosphorIpc	Typed JSON-over-Unix-socket invocation channel (phosphorctl)
`phosphor-scripting`	PhosphorScripting	Generic sandboxed Luau host with CPU and heap guards
`phosphor-context-resolver`	PhosphorContext	Frozen-snapshot gate over the mode / desktop / activity cascade

Layout

Zone and tile data models — the what of placement.

Library	Namespace	Responsibility
`phosphor-layout-api`	PhosphorLayout	Layout description interfaces + provider registry
`phosphor-zones`	PhosphorZones	Manual zone data model, registry, and ILayoutSource
`phosphor-tiles`	PhosphorTiles	Tiling algorithms, sandboxed Luau, and TilingState

Engines

Placement runtime — the how of placement.

Library	Namespace	Responsibility
`phosphor-engine`	PhosphorEngine	Unified placement-engine surface + shared service contracts
`phosphor-snap-engine`	PhosphorSnapEngine	Manual zone-based placement engine
`phosphor-tile-engine`	PhosphorTileEngine	Automatic-tiling placement engine
`phosphor-placement`	PhosphorPlacement	Window tracking, auto-snap, resnap, rotation, empty-zone queries
`phosphor-window-rules`	PhosphorWindowRules	Unified window/context rule engine with one match language and cache

Rendering

Shader and animation pipeline.

Library	Namespace	Responsibility
`phosphor-shaders`	PhosphorShaders	Shader-effect registry, base UBO layout, uniform extension contract
`phosphor-rendering`	PhosphorRendering	ShaderEffect / ShaderNodeRhi / runtime GLSL → SPIR-V
`phosphor-animation`	PhosphorAnimation	Motion runtime + shader-transition runtime with JSON profiles
`phosphor-audio`	PhosphorAudio	Audio spectrum input for audio-reactive shaders
`phosphor-theme`	PhosphorTheme	Active design-token store with hot reload and matugen retint

Surfaces

Wayland integration, layer-shell primitives, and screen topology.

Library	Namespace	Responsibility
`phosphor-wayland`	PhosphorWayland	Custom QPA plugin + LayerSurface wrapper
`phosphor-layer`	PhosphorLayer	Layer-shell surface primitives: factory, registry, coordinator
`phosphor-surfaces`	PhosphorSurfaces	Surface manager with QML loading and Vulkan wiring
`phosphor-screens`	Phosphor::Screens	Physical + virtual screen topology resolver
`phosphor-compositor`	PhosphorCompositor	Plugin SDK for hosting the daemon in non-KWin Wayland compositors
`phosphor-popout`	PhosphorPopout	Central arbiter for transient popout lifetime, focus, and exclusivity

Shell

Higher-level shell infrastructure on top of the surface stack — panel windows, the settings-app framework, named UI-pattern recipes, and per-screen overlay hosts.

Library	Namespace	Responsibility
`phosphor-shell`	PhosphorShell	Quickshell-style declarative QML framework for layer-shell shells
`phosphor-control`	PhosphorControl	Settings-app framework: staged pages, dirty tracking, search, D-Bus bridge
`phosphor-overlay`	PhosphorOverlay	Per-screen layer-shell shell hosts with named slot vocabulary
`phosphor-shell-patterns`	PhosphorShellPatterns	Named UI-pattern Role recipes (wallpaper, panel, modal, toast)

Services

Per-domain D-Bus and platform-integration libraries a desktop shell pulls in piecewise. The old monolithic phosphor-services split into these focused libs.

Library	Namespace	Responsibility
`phosphor-service-sni`	PhosphorServiceSni	StatusNotifierItem system-tray host with dbusmenu menus
`phosphor-service-notifications`	PhosphorServiceNotifications	Freedesktop notification server and live history
`phosphor-service-mpris`	PhosphorServiceMpris	MPRIS2 media-player discovery, status, and transport control
`phosphor-service-upower`	PhosphorServiceUPower	Battery and power-device status via UPower
`phosphor-service-network`	PhosphorServiceNetwork	NetworkManager device and connectivity state
`phosphor-service-bluetooth`	PhosphorServiceBluetooth	BlueZ adapter and device state with device pairing
`phosphor-service-pipewire`	PhosphorServicePipeWire	Native PipeWire mixer for sinks, sources, and streams
`phosphor-service-brightness`	PhosphorServiceBrightness	Display and keyboard backlight brightness control
`phosphor-service-session`	PhosphorServiceSession	logind session manager, power actions, and sleep inhibitors
`phosphor-service-lock`	PhosphorServiceLock	PAM authentication and Wayland session-lock lifecycle
`phosphor-service-idle`	PhosphorServiceIdle	Multi-stage Wayland idle monitoring and inhibition
`phosphor-service-polkit`	PhosphorServicePolkit	PolicyKit authentication agent for the session
`phosphor-service-clipboard`	PhosphorServiceClipboard	De-duplicated, persistent clipboard history
`phosphor-service-icontheme`	PhosphorServiceIconTheme	XDG icon-theme lookup plus a QML image provider

Where to start

• Browsing by name? → Classes — alphabetical class index across every library.
• Browsing by namespace? → Namespaces — one entry per Phosphor* library.
• Browsing by header? → Files — every header under libs/phosphor-*/include/ grouped by library directory.
• D-Bus interfaces? → D-Bus APIs — every interface PlasmaZones exposes on the session bus, generated from dbus/*.xml.
• Looking for a specific symbol? → use the search box in the upper corner (indexes class names, method names, and file names).

Conventions

All Phosphor libraries share a handful of cross-cutting conventions so anything you learn in one library transfers to the others:

• Namespaces mirror library names — libs/phosphor-identity/include/PhosphorIdentity/WindowId.h declares PhosphorIdentity::WindowId. The Phosphor prefix is elided when sorting the class index (you won't see a hundred classes starting with Phosphor...).
• Public API in include/, implementation in src/ — everything under libs/phosphor-*/include/ is the stable surface you can link against. src/ and any _p.h/internal/ headers are intentionally excluded from this reference.
• Per-library README is the design page — each library's README.md is the source of truth for its responsibility, key types, examples, and design notes; the build pipeline (scripts/readme-to-doxypage.py) stitches them in here.
• Qt idioms throughout — Q_OBJECT, Q_PROPERTY with READ/WRITE/NOTIFY, parent-based ownership, signals in past tense (layoutChanged), slots in imperative (saveLayout). Macros are stripped by the preprocessor before Doxygen parses, so class declarations read cleanly in the generated HTML.
• Interface-first for anything pluggable — config storage, shortcut backends, wallpaper providers, render backends are all declared as abstract I* interfaces with one or more concrete implementations. That makes it easy to drop in a different persistence layer or shortcut router without touching the consumers.

License

All Phosphor libraries: LGPL-2.1-or-later. Consumers (including PlasmaZones) link against them under that license.