# Hyprland Configuration - uwsm Integration

## Architecture

Session management uses **UWSM** (Universal Wayland Session Manager) wrapping Hyprland in systemd user services.

```
greetd → tuigreet → uwsm start → systemd user session → Hyprland
                                    ↓
              systemd units: hyprpaper, waybar, dunst, hypridle, hyprlauncher, cliphist
              XDG autostart: Nextcloud, JetBrains Toolbox, Flameshot, etc.
```

## Session Services

All session services are managed via systemd user units (`~/.config/systemd/user/*.service`):

| Service | Purpose | Status |
|---------|---------|--------|
| `hyprpaper.service` | Wallpaper daemon | active |
| `waybar.service` | Status bar | active |
| `dunst.service` | Notification daemon | active |
| `hypridle.service` | Idle/screenlock control | active |
| `hyprlauncher.service` | App launcher daemon | active |
| `cliphist.service` | Clipboard history store | active |

### Management Commands

```bash
# Check all session services
systemctl --user list-units | grep -E 'hypr|waybar|dunst|cliphist'

# Restart a specific service
systemctl --user restart waybar.service

# View logs
journalctl --user -u waybar.service -f
```

## Launchers

| Component | Tool | Keybind |
|-----------|------|---------|
| App Launcher | hyprlauncher | SUPER+D |
| Keybind Menu | hyprlauncher -o (piped) | SUPER+CTRL+K |

hypr launcher config: `~/.config/hypr/hyprlauncher.conf`
- `desktop_launch_prefix = uwsm app --` (proper systemd scoping)
- Cache enabled for frequency-based sorting
- Finders: desktop (default), math (=), unicode (.), font (')

## Login Manager

**greetd** with **tuigreet** on VT 1.
Config: `/etc/greetd/config.toml`
Default command: `tuigreet --time --remember --asterisks --cmd 'uwsm start -e -D Hyprland hyprland.desktop'`

### Wayland Session Override (start-hyprland)

The package provides `/usr/share/wayland-sessions/hyprland.desktop` with
`Exec=Hyprland` (direct binary), but Hyprland 0.53+ requires launching through
`start-hyprland` (watchdog parent process) for crash diagnostics and proper
signal handling. Otherwise a warning banner appears on login.

A local override at `~/.local/share/wayland-sessions/hyprland.desktop` sets
`Exec=start-hyprland`, which uwsm then manages inside the systemd session.
XDG_DATA_DIRS priority ensures the override wins without touching system files.
Managed by Ansible role `hyprland` — see `docs/adr/0004-start-hyprland-override.md`.

## Key Categories

| Category | Modifier | Keys | Action |
|----------|----------|------|--------|
| Focus | SUPER | H/J/K/L, Arrows | Move focus |
| Move Window | SUPER+SHIFT | H/J/K/L, Arrows | Move window |
| Resize Window | SUPER+ALT | H/J/K/L | Resize active window |
| Windows | SUPER | F, SPACE, TAB, `, P, J | Window actions |
| Apps | SUPER | Q, B, E, D | Launch apps |
| Workspaces | SUPER | 1-9 | Switch/move workspaces |
| Lock | SUPER+CTRL | L | Lock screen |

See `~/.config/hypr/cheatsheet.txt` for the full reference.