# Desktop Hyprland This host uses Hyprland 0.56's native Lua configuration, managed by UWSM. The shared `illustris` input is pinned to `github:illustris/flake` and provides the common NixOS and Home Manager Hyprland modules. The dailyDriver profile imports the home module. This directory keeps only the host's NVIDIA options, display/HDR/HDMI recovery extension, and their tests. The shared controller, bindings, panel, scripts and package patches live in `homeConfigurations/modules/hyprland` in that flake and are also used by Yoga. ## 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 shared 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 ```sh 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 nix build --inputs-from . illustris#checks.x86_64-linux.hyprland shared_hyprland=$(nix flake metadata --inputs-from . --json illustris | jq -r '.path + "/homeConfigurations/modules/hyprland"') XDG_RUNTIME_DIR=$(mktemp -d) HYPRLAND_INSTANCE_SIGNATURE=test \ lua modules/hyprland/test.lua "$shared_hyprland" ``` 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.