hyprland-hdmi-revive/docs/architecture.md

Architecture

The workaround resets the display below the compositor by briefly leaving the active graphical VT. It is intended for one local Hyprland session on seat0.

1. A systemd user service runs udevadm monitor --kernel --property --subsystem-match=drm. The watcher owns a per-user lock.
2. Each HOTPLUG=1 line causes a loginctl lookup for the current UID, Wayland, active state, seat0 and a valid VT. A known different desktop is excluded.
3. Events inside the cooldown are ignored. The clock is Bash's elapsed seconds; timestamps are not read from shared files or affected by wall-clock changes.
4. The synchronous recovery helper locks, independently identifies the active session, waits for HDMI settling, checks the Hyprland IPC output and refreshes DPMS/focus. hyprctl -j status selects Lua or legacy hyprlang dispatch syntax; versions without the query use legacy commands. Dispatches must return ok with exit status zero, otherwise their error is logged and recovery aborts. The instance signature comes from the Hyprland startup hook.
5. Before switching, the helper rechecks session identity and VT and checks sudo permission for both directions. It rechecks session identity after those calls.
6. The helper sets an EXIT/signal trap, switches to VT2 (when graphical VT=1) or VT1 (otherwise), and returns to the detected graphical VT.
7. Failed returns and catchable signals cause an emergency return attempt. Success is logged only after the final DPMS/focus refresh succeeds.
8. The watcher logs the helper's actual exit status and starts the cooldown at completion. Unexpected event-stream EOF always returns nonzero to systemd.

Shared validation and session detection live in lib/common.sh. Runtime state is restricted to a user-owned mode-0700 XDG_RUNTIME_DIR/revive-monitor. Root is used only for chvt; user scripts are never invoked through sudo.

The session check is not atomic with the kernel VT switch. The temporary VT can contain another console, and the workaround can briefly expose it. Multi-seat setups, multiple concurrent desktops for one user and hardware that emits no DRM event are outside the supported design. See README for cooldown tradeoffs.