Pin illustris/flake to 9041e13, bringing in display labels and colors, tray-safe Monocle tabs, consistent navigation, temporary title overlays, and the Firefox container activation fix. Update the desktop documentation for the consolidated layouts and shortcuts. Validated with a full desktop system build against the GitHub input.
11 KiB
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.
The bottom bar labels and colors tags by output. Only Monocle shows window tabs; its scrollable strip yields space to the tray and follows the same order as Super+Left/Right. Super+H shows full window-title headers for three seconds. Monocle replaces the old separate Tabs layout and Super+T binding.
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 / R | Grid / Monocle / Scrolling |
| Super+Space | Cycle the three 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+H | Full window-title headers for three seconds |
| 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, Monocle tabs, 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 and shows their tabs in the bottom bar; floating dialogs
stay separate. Its tab order matches Super+Left/Right and Super+J/K, including
after swaps and promotion. Overflow scrolls within the remaining panel space,
keeping the tray visible. Saved Tabs layouts migrate to Monocle on reload.
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
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("monocle")' 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.
Before the Monocle/tab consolidation, 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.