189 lines
11 KiB
Markdown
189 lines
11 KiB
Markdown
# Desktop Hyprland
|
|
|
|
This host uses Hyprland 0.56's native Lua configuration, managed by UWSM.
|
|
The shared `illustris` input currently uses `path:/home/illustris/src/flake` for
|
|
local verification; restore `github:illustris/flake` after pushing it. It 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+Tab / Shift+Tab | 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, Super+J/K, and
|
|
Super+Tab/Shift+Tab, 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
|
|
|
|
```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("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.
|