[howdeploy]

I built the initial version for my own Quickshell lock screen: a live wallpaper, or a separate screensaver client, sits underneath the password form; after authentication, a shader reveals the unlocked desktop. This draft extracts the compositor support into an application-independent API on current main (44e8ce9), extending the already merged output-overlay API from #120.

API and behavior

• COMPOSITOR.session.configureLockBackground({ windowIds, layerIds }) selects exact current runtime IDs and returns the actual protocol lock state. Empty by default; no application IDs, layer namespaces, wallpaper engines, passwords or built-in wave shaders in native code.
• Render selected root surface trees and client subsurfaces underneath the lock surface on TTY and Winit. Exclude unselected desktop content, separately managed popups and SSDs. The existing lock-only input routing remains unchanged.
• Do not show backgrounds or unlock overlays on an output without a live buffered lock surface. Runtime teardown/reload invalidates the selection. Validate ID count/length/content, coalesce unchanged selections, and apply updates at frame boundaries before collecting GPU buffer holds.
• Keep selected window backgrounds eligible for frame processing and GPU buffer holds, including when the ordinary window composition hides them.
• Add placement: "unlock" to output overlays. Require an active protocol lock, a snapshot input, nonpersistent mode and a native deadline <= 3000 ms. Ordinary overlays still close on lock; pause, DPMS and lifecycle/output changes close effects.

The locker owns authentication and releases its protocol lock only after successful authentication and capture readiness. Capture must run from detached tasks so an awaited compositor callback cannot block the next frame. The configuration chooses the shader and reduced-motion fallback. The API itself never authenticates, locks or unlocks.

Security and scope

This is an explicit opt-in visibility policy for trusted configuration. Selecting an application's root exposes that client's pixels, including any UI it draws in that surface tree, while locked. It is not a separate sandbox. The normal blank fallback remains when no roots are selected or the locker disappears. The documentation covers the handoff and remaining review requirements.

No personal Quickshell configuration, IPC service, MateEngine integration, wallpaper decoder or player/library memory patches are included. Configuring by exact runtime IDs avoids hard-coding client names and unintentionally selecting another instance by application ID.

Validation and draft status

The earlier application-specific implementation was built and installed in my local desktop. After correcting a self-deadlock caused by holding the output LayerMap guard across a helper that acquires it again, the user confirmed the animated-wallpaper and screensaver modes worked. This draft keeps that guard released before rendering roots.

That local result does not validate this generic API or the port to current main. I inspected the connected source and diff, but have not run builds, tests, typechecking or graphical/authentication/DPMS checks for this version. A focused native ID-validation/runtime-ownership check is included but has not been run. The installed local compositor has not been replaced by this draft.

Opening for API/security review first. Pending checks include locker death and recovery, wrong/correct authentication, input isolation, startup lock, reload, VT pause, DPMS, multi-output/rotation/hotplug, selected background frame cadence, and snapshot cleanup.

[bea4dev]

thanks! LGTM!