This gist describes a privacy-preserving way to inspect desktop state when wallpapers, transparent terminals, desktop shells, and per-monitor renderers overlap.
It intentionally avoids raw screenshots, local hostnames, private paths, account names, and machine-specific output names. The goal is maintainer-friendly evidence: typed state, sanitized tokens, and clear ownership boundaries.
On a Wayland desktop, several issues can look identical from the screen:
- no renderer on one output
- stale shell wallpaper layer competing with the renderer
- a transparent terminal using old config
- a wallpaper command targeting
Allinstead of a single output - a renderer launched on the right monitor but failing internally
- a video project routed through a scene/web renderer
The right artifact is usually not a screenshot. It is a small state report.
flowchart LR
Niri[niri JSON] --> Report[typed report]
Processes[renderer process list] --> Report
Shell[desktop shell settings] --> Report
Config[terminal/wallpaper config] --> Report
Report --> Warnings[actionable warnings]
Warnings --> SafeEvidence[sanitized issue or PR note]
A useful report contains:
- outputs and their active/focused workspaces
- renderer processes and claimed outputs
- shell background ownership state
- terminal opacity/config freshness
- selected wallpaper project token, type, entry extension, and compatibility tags
- skipped disconnected outputs
- warnings that explain state transitions without private images
missing_renderer_outputs: connected output has no live wallpaper renderer.shell_wallpaper_layer_enabled: shell may still own a competing background layer.terminal_needs_restart_for_glass_config: config changed after the terminal started.wallpaper_global_target: command would target all outputs when per-output isolation is expected.wallpaper_compatibility_risk: selected project depends on web/audio/runtime APIs.wallpaper_restore_skipped_output: saved output is disconnected and was skipped instead of falling back globally.renderer_internal_failure: launcher returned but per-launch log contains renderer failure signatures.
The invariant is simple: one connected output should map to one intended renderer unless a user explicitly chooses a global target.
A failure chain looked like this:
flowchart TD
A[niri outputs JSON shape changed] --> B[helper missed connected outputs]
B --> C[fallback selected global target]
C --> D[backend cleanup affected every renderer]
D --> E[one monitor change replaced others]
E --> F[confusing transparent-terminal background state]
F --> G[typed report separates renderer, shell, terminal, and selection state]
The useful fix pattern was a state contract:
- normalize list-shaped and object-shaped compositor output JSON
- refuse
Allunless explicitly requested - pass the Wallpaper Engine entry file when type detection needs it
- keep a nonblocking single-run lock so timer runs do not overlap
- restore last per-output state before starting random cycles
- skip disconnected outputs with a warning, not a global fallback
- parse launch logs so an internal renderer failure is not recorded as success
Tags are not verdicts. They are routing and debugging hints.
native-video: good candidate for video-native handoff.scene-runtime: likely renderer-dependent scene behavior.scene-audio-reactive: may depend on audio data and timing.web-runtime: depends on embedded browser/runtime behavior.web-audio-reactive: likely expects Wallpaper Engine audio APIs.web-wallpaper-engine-api: expects JavaScript APIs or property listeners.web-pointer-reactive: expects pointer state.web-webgl: may depend on WebGL or Three.js.
flowchart LR
Metadata[project.json] --> Tags[compatibility tags]
AssetScan[bounded asset scan] --> Tags
Tags --> Route[backend decision]
Tags --> Logs[per-launch log context]
Logs --> Maintainer[focused issue or PR comment]
This observability pattern sits beside the upstream work rather than replacing it:
- Waypaper #278 improves metadata truth in the UI.
- Waypaper #279 improves launch logs and failure reporting.
- Waypaper #280 improves video-native routing and renderer cleanup.
- Waypaper #283 makes daemon operation service-managed.
- Waypaper #286 exposes backend filter control.
- linux-wallpaperengine #576 fixes one renderer-side Wayland input class.
- linux-wallpaperengine #574 tracks visualizer runtime/property compatibility.
niri msg -j outputs
niri msg -j workspaces
niri msg -j windows
pgrep -af 'linux-wallpaperengine|mpvpaper|gslapper|swww|awww'
waypaper-video-random --benchmark
waypaper-video-random --restore --dry-runPublish sanitized state transitions, not raw desktop images. A good report says what was connected, what was selected, what command/log path existed, and which layer likely owns the failure.