Manage the desktop through native Lua and UWSM with Grid, Monocle, Tabs and Scrolling layouts. Add workspace-local navigation, bounded scrolling focus and a runtime Grid ratio defaulting to 1.20. Configure the HDR OLED and portrait LG, HDMI recovery, NVIDIA suspend handling, independent locking and Plasma fallback. Fix Waybar workspace IPC and provide immediate per-output layout status. Include desktop controls, screenshots, usage documentation and controller/panel regression tests. Use the authorized local illustris flake input.
Desktop Hyprland
This host uses Hyprland 0.56's native Lua configuration, managed by UWSM.
The shared illustris flake points at /home/illustris/src/flake; its old
laptop-oriented Hyprland module is disabled only on this host.
Daily Use
Choose Hyprland (uwsm-managed) in LightDM. From a logged-in TTY, run
uwsm start -e -D Hyprland hyprland.desktop.
Plasma (X11), with the existing XMonad window manager, remains available.
| Shortcut | Action |
|---|---|
| Super+Enter | Customized st, through XWayland |
| Super+D | Application launcher |
| Super+Ctrl+E | Dolphin |
| Super+G / M / T / R | Grid / Monocle / Tabs / Scrolling |
| Super+Space | Cycle those four layouts |
| Super+J / K | Next / previous window or tab |
| Super+arrows | Directional focus within workspace; left/right scroll columns |
| Super+Shift+J / K | Swap window order |
| Super+Shift+Enter / Ctrl+M | Promote / focus first window |
| Super+F | Toggle fullscreen for the selected window |
| Super+Shift+Space / Ctrl+Space | Sink / toggle floating |
| Super+1 through 9 | Bring that workspace to the focused monitor |
| Super+Shift+1 through 9 | Move only the selected window, keeping source focus |
| Super+W / E | Focus OLED / LG |
| Super+Shift+W / E | Move selected window to OLED / LG |
| Super+Ctrl+arrows | Move the workspace to another monitor |
| Super+S / Shift+S | Show scratchpad / send selected window there |
| Super+minus / equal | Narrow / widen scrolling column |
| Super+Ctrl+minus / equal | Lower / raise Grid target width/height ratio |
| Super+Ctrl+Backspace | Reset this workspace's Grid ratio to 1.20:1 |
| Super+V | Clipboard history |
| Print / Shift+Print | Screenshot focused monitor / all monitors |
| Super+Shift+Print | Screenshot a region |
| Super+Shift+L | Lock |
| Super+Shift+Q | Session and display controls, including logout |
| Super+/ | Search shortcut descriptions |
| Super+mouse left / right | Drag / resize a window |
Screenshots go to ~/Pictures/Screenshots and are copied to the clipboard.
The bottom panel exposes workspaces, the layout selector, tasks, media,
volume, network, Bluetooth, idle inhibition, and the tray.
Grid uses the same aspect calculation and remainder distribution as
XMonad's GridVariants. Its default target window width/height is 1.20:1.
Super+Ctrl+minus lowers the ratio, favoring taller windows and splitting into
columns sooner; Super+Ctrl+equal raises it, favoring wider windows and delaying
the split. The range is 0.25 to 4.00 in 0.10 steps, with Backspace resetting it.
Each workspace keeps its own ratio across config reloads. The panel shows
Grid 1.20:1 (or the current ratio) while Grid is selected. Arrow navigation
selects neighbors by position, stops at workspace edges, and keeps every column
reachable. Use Super+W/E to change monitors. Scrolling arrows stop at the first
and last columns and recover window focus if the viewport loses it. Monocle hides
inactive tiled windows. Tabs combine
the workspace's tiled windows into one native group with a visible tab bar;
floating dialogs stay separate. Leaving Tabs dissolves that group. Moving or
floating a tab detaches the selected window before the operation. Tab creation
waits for the layout change to finish so Monocle releases its input restrictions.
Layouts and window order survive config reloads within the compositor session;
new sessions start in Grid. Runtime state is plain data under $XDG_RUNTIME_DIR.
Each monitor's layout label follows its own active workspace, updating directly
from state changes without polling. The Keep Awake: On/Off control pauses or
resumes automatic locking and display sleep; click it to toggle. Its tooltip
explains the current behavior. Manual locking and suspend remain available.
Displays And Sleep
Outputs are matched by their full EDID descriptions, including serials.
The AW3225QF runs at its highest advertised 4K refresh rate (240 Hz), scale 1,
10-bit HDR, with SDR reference luminance 265 nits. The LG runs at 4K/60 Hz,
scale 1, transform 3, SDR/8-bit. In the dual profile, positions are (0,1680)
and (3840,0) so the landscape and portrait displays are bottom aligned.
Unplugging the LG migrates its workspaces; reconnecting leaves them where they
migrated. The OLED-only profile moves its origin to (0,0).
| Shortcut / command | Action |
|---|---|
Super+Shift+Alt+1 / desktopctl dual |
Enable dual monitors |
Super+Shift+Alt+2 / desktopctl solo |
Disable LG, move workspaces onto OLED |
Super+Shift+Alt+H / desktopctl hdr |
Toggle OLED HDR |
Super+Shift+Alt+R / desktopctl wake |
Retrain LG HDMI link |
Hypridle locks at seven minutes and turns outputs off at eight minutes. It locks before suspend and restores outputs after resume. LG recovery runs at login, config reload, reconnect, dual-profile selection, and wake. New links start at 1080p60. After a three-second settling period, recovery disables the output for one second, then steps through 1080p60, 4K30, and 4K60. Each low-clock mode is held for three seconds after the compositor confirms it is active. The complete sequence takes about twelve seconds. Its own output events do not restart it. Selecting OLED-only cancels pending recovery timers immediately; unplugging resets the next connection to 1080p. A modeset timeout stops the ladder and leaves a 1080p recovery rule. It never reenables an intentionally disabled LG. A compositor capture cannot prove the physical LG has acquired its HDMI signal; check the panel after wake. The initial direct 4K60 setup failed on the physical LG despite healthy compositor state; the user confirmed signal acquisition after disabling the output and bringing it up at 1080p60, then confirmed both physical displays showed the lock screen after automatic recovery to 4K60.
NVIDIA full VRAM preservation and its suspend/resume services are enabled.
The module uses NVreg_PreserveVideoMemoryAllocations=1 and /var/tmp storage.
Changing these settings requires a reboot. The previous loaded setting of 2
produced GPU errors and an EGL crash after suspend. With setting 1 loaded,
the compositor survived the live RTC suspend/resume tests with the same PID.
Package Compatibility
Waybar 0.15's workspace button sends legacy dispatcher syntax. A local patch uses native Lua dispatch and selects workspaces on the clicked monitor. Its event reader also fails to reconnect after a disconnected Hyprland socket, leaving the active workspace highlight stuck. A second patch reconnects and resynchronizes module state, with a 250 ms retry delay. Hyprland 0.56's workspace JSON incorrectly reports every Lua layout with the first registered name, so the layout label watches the controller's runtime state through inotify. Atomic file replacements produce immediate updates, and changes on another output do not change this output's label.
The pinned Firefox 154 / GTK build crashes in xdg_output_handle_name during
native Wayland initialization. Its package wrapper selects XWayland only when
XDG_CURRENT_DESKTOP=Hyprland; Plasma retains its existing behavior. Remove
this workaround after testing a fixed package revision. Native Dolphin and
the Hyprland screen-sharing / KDE file-chooser portals are available.
Hyprlock uses Mesa software rendering and shared-memory screen capture. NVIDIA
595's EGL Wayland surface destruction hung after unlocking a resumed session;
the locker spun in eplWlDestroyWindow. The software wrapper avoids that path
for the shortcut, desktop menu, and idle/suspend hooks. The final live test
confirmed automatic locking, compositor survival, restored outputs, and clean
locker exit after resume, with no NVIDIA errors during that cycle.
Idle locking launches Hyprlock through UWSM as a separate session app. Reloading
or restarting hypridle therefore does not kill an active locker; previously its
child process died during system activation, leaving an orphaned lock screen.
Build And Verify
nix build .#nixosConfigurations.desktop.config.system.build.toplevel
sudo nixos-rebuild test --flake .#desktop
env -u HYPRLAND_INSTANCE_SIGNATURE Hyprland --verify-config -c ~/.config/hypr/hyprland.lua
XDG_RUNTIME_DIR=$(mktemp -d) HYPRLAND_INSTANCE_SIGNATURE=test lua modules/hyprland/test.lua
PYTHONDONTWRITEBYTECODE=1 python modules/hyprland/test_panel.py
Use hyprctl eval 'desktop.layout_set("tabbed")' for IPC commands. Legacy
hyprctl keyword and hyprctl dispatch workspace 1 do not work in Lua mode.
Check hyprctl configerrors, hyprctl monitors -j, and
systemctl --user status wayland-wm@hyprland.desktop.service when debugging.
Use uwsm stop to end the session. Hyprland auxiliary services are bound to
wayland-session@hyprland.desktop.target; they stop at logout and stay out of Plasma.
The XMonad and X11 HDMI recovery services stop with the Plasma session.
Live test captures and logs from this setup are preserved in
~/.local/state/hyprland-parity. Temporary build files are in /tmp/hyprland-parity.
Screen captures use WAYLAND_DISPLAY=wayland-1 grim -o DP-1 ... with the actual
socket name from hyprctl instances -j. They validate composition and geometry;
HDR is additionally checked through the compositor format and DRM colorspace.
Live tests passed for all four layouts, selected-tab moves, floating dialogs, clipboard, screenshots, locking, screen sharing, the KDE file chooser, and the Plasma fallback. Post-reboot tests additionally verified a real Waybar click bringing an LG workspace onto the OLED, physical keyboard shortcuts and a scratchpad round trip, dual/solo workspace migration, repeated wake/sink calls, and suspend/resume with the software locker. HDMI controller tests additionally cover delayed mode application, settling and hold times, duplicate wake events, OLED-only cancellation, unplug/replug, and modeset timeouts. Test unlocks used Hyprlock's documented SIGUSR1 mechanism; the PAM prompt and lock input isolation were checked. The user confirmed physical LG signal acquisition after idle wake with the updated recovery sequence; the live trace reached 4K60 in about twelve seconds.
Home Manager preserved the previous Waybar configuration as .hm-bak files.
The preexisting Firefox containers backup was retained as
containers.json.hm-bak.before-hyprland-20261003 to resolve a backup collision.