Performance budgets

What it is

Targets and measurements for the desktop: how much the window server and shell cost when idle, and how fast a key press reaches the screen for the switcher, Control Center, Overview and Search.

Why

The desktop should do nothing when you do nothing, and answer at once when you act. Budgets written down make regressions visible.

How

Every number below lists the script that reproduces it.

Reference

Measured live, release build, Linux host, nested compositor fork, 0.56.2 (patches + plugins) on a 1280x720 headless output, started the product way: wol-session -> start-hyprland -> exec-once wol-shell. When and where: October 2026, recorded with release 0.11.2 (CHANGELOG), on a CachyOS development host, not on the installed WolOS image; the compositor ran nested, so no number below comes from a real DRM output. Re-measure on the image before quoting one as a WolOS figure; the table keeps these until then. Probes: design/tools/perf/build.sh builds dmg (screencopy region hash per frame), vk/vp (virtual keyboard/pointer, STAMP=1 prints send time). Run the scripts inside the session (WAYLAND_DISPLAY, HYPRLAND_INSTANCE_SIGNATURE set, probes on PATH).

Fixes behind these numbers (before -> after):

• Status refresh: 1 s always -> 1 s only while a panel watches, else 10 s with 60 s TTLs. Helpers 14 -> 1 ms/s; wakeups 3-10 -> 1.8/s.
• Volume keys: OSD shows after an on-demand audio read (wol shell show osd), not from polling.
• Control Center: spawned app per open (52/109 ms, +110 MB over 200 opens) -> resident shell panel, built once, watcher stopped on hide.
• blocking pool threads woke at 2 Hz forever -> exit when idle (ADR 0006, tests/idle_threads.rs).
• wolos-perf.conf was installed but never sourced -> sourced from the desktop hyprland.conf.
• wol shell ... spawns from the shell write the socket directly (no CLI fork).

Notes:

• Latency = first frame whose region hash differs after the input stamp; includes compositor frame pacing (60 Hz headless).
• Session start: the nested compositor socket is up at ~0.1 s, but exec-once fires on Event start, emitted on the first rendered monitor frame (Renderer.cpp). The harness creates its headless output from exec-once, so ~2 s goes to the compositor's fallback output. On hardware a DRM monitor renders at once; real-boot number still to measure on the installed image.
• N/A on this host: hypridle (not installed), wold (needs root paths under /var/run). perf/ptrace unavailable; profiling used LD_PRELOAD timer shims and per-thread context switches.
• Helper cost (nmcli, wpctl) was measured on a CachyOS host, not on the installed image; re-measure on the image.