Skip to content

Instantly share code, notes, and snippets.

@louzt
Last active May 19, 2026 07:07
Show Gist options
  • Select an option

  • Save louzt/1c5230a2e9471faf9ce4243314361fa1 to your computer and use it in GitHub Desktop.

Select an option

Save louzt/1c5230a2e9471faf9ce4243314361fa1 to your computer and use it in GitHub Desktop.
Privacy-preserving niri state observability for Wayland wallpaper workflows

Wayland Desktop State Observability with niri

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.

Why This Matters

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 All instead 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]
Loading

Data Contract

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

Actionable Warnings

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

Multi-Monitor Wallpaper Case Study

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]
Loading

The useful fix pattern was a state contract:

  • normalize list-shaped and object-shaped compositor output JSON
  • refuse All unless 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

Compatibility Tags

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]
Loading

Link To The Public PR Trail

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.

Example Commands

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-run

Reporting Rule

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment