# Hyprland Lua Migration

Hyprland 0.55 moved configuration toward Lua. DMS now follows that path for new
Hyprland setup and migration.

This guide covers what changes, where files live, and how to check that your
session is using the new config.

## Quick Summary

DMS now deploys Hyprland as:

```text
~/.config/hypr/hyprland.lua
~/.config/hypr/dms/*.lua
```

The old hyprlang files are moved out of the active config tree:

```text
~/.config/hypr/hyprland.conf
~/.config/hypr/dms/*.conf
```

Backups are stored here:

```text
~/.config/hypr/.dms-backups/<timestamp>/
```

## What `dms setup` Does

When Hyprland is selected, `dms setup` writes a Lua main config and DMS Lua
fragments.

| File | Purpose |
| --- | --- |
| `hyprland.lua` | Main Hyprland config. |
| `dms/colors.lua` | Theme colors. |
| `dms/outputs.lua` | Monitors and display settings. |
| `dms/layout.lua` | Layout, gaps, borders, and decoration. |
| `dms/cursor.lua` | Cursor settings. |
| `dms/binds.lua` | DMS-managed default shortcuts. |
| `dms/binds-user.lua` | User shortcut overrides. |
| `dms/windowrules.lua` | Window rules. |

`dms/binds.lua` is managed by DMS and may be refreshed by setup. Put custom
keyboard shortcuts in `dms/binds-user.lua`, or use the Keyboard Shortcuts page in
DMS Settings.

Stock configs include a 3-finger horizontal touchpad gesture for workspace
switching (`hl.gesture` in `dms/binds.lua`) and basic touchpad settings
(`tap_to_click`, `natural_scroll` in `hyprland.lua`). To customize or disable
gestures, add your own `hl.gesture(...)` lines to `dms/binds-user.lua`, or unset
a stock gesture with `action = "unset"` matching the original fingers,
direction, and modifiers.

Most other existing non-empty Lua fragments are preserved.

## Legacy Config Migration

During migration, DMS moves legacy active files into the backup folder so
Hyprland does not see both config formats at once.

DMS also migrates legacy `monitor = ...` lines from `hyprland.conf` into
`dms/outputs.lua` when `outputs.lua` is empty or missing. If you already have a
custom `outputs.lua`, DMS leaves it alone.

## DMS Settings Support

DMS Settings now targets Lua files for Hyprland:

| Settings page | Lua file |
| --- | --- |
| Keyboard Shortcuts | `dms/binds-user.lua` |
| Displays | `dms/outputs.lua` |
| Theme Colors | `dms/colors.lua` |
| Cursor | `dms/cursor.lua` |
| Window Rules | `dms/windowrules.lua` |

The main config should include the DMS fragments:

```lua
require("dms.colors")
require("dms.outputs")
require("dms.layout")
require("dms.cursor")
require("dms.binds")
require("dms.binds-user")
require("dms.windowrules")
```

### Keyboard Shortcuts: Delete and Reset

The Keyboard Shortcuts page exposes two actions on any DMS-managed bind:

- **Delete** — removes the shortcut entirely. For default DMS shortcuts (from
  `dms/binds.lua`), this saves an `hl.unbind("KEY")` line into
  `dms/binds-user.lua` so the removal sticks across `dms setup` runs.
- **Reset to default** — only visible when you are editing a user override of
  a DMS default. It drops your override so the original DMS default re-applies.

Binds from your own `hyprland.lua` (outside the `dms/` folder) are read-only
in Settings — DMS does not write into files it does not manage.

## Starting Hyprland

For the Lua config to be active, Hyprland must start with:

```sh
Hyprland -c ~/.config/hypr/hyprland.lua
```

If Hyprland warns that it is using an autogenerated config, or the warning
mentions `hyprland.conf`, the session is not using the DMS Lua config yet.

## Verify Everything

After updating DMS, run:

```sh
dms setup
hyprctl reload
hyprctl configerrors
```

If the current session was not started from `hyprland.lua`, restart Hyprland with
the Lua config and check again.

Useful file checks:

```sh
test -f ~/.config/hypr/hyprland.lua
test ! -f ~/.config/hypr/hyprland.conf
ls ~/.config/hypr/dms
```

The live `dms` folder should contain Lua files like `binds.lua`,
`binds-user.lua`, `outputs.lua`, and `windowrules.lua`.

Note: Hyprland 0.55 still auto-generates `hyprland.conf` if you launch it
without `-c ~/.config/hypr/hyprland.lua`. DMS sweeps any stray
`hyprland.conf` into `.dms-backups/<timestamp>/` on the next `dms run`
startup, so the second check above is the right long-term state. If you see
`hyprland.conf` persist between `dms run` invocations, the session was not
started from `hyprland.lua` — restart Hyprland with the `-c` flag (or update
your session/desktop entry to include it).

## Troubleshooting

If shortcuts do not work, confirm `hyprland.lua` includes both:

```lua
require("dms.binds")
require("dms.binds-user")
```

If `hyprctl configerrors` reports errors in `dms/binds.lua`, rerun `dms setup`
with the latest DMS binary so the DMS-managed shortcut file is refreshed.

If a migrated monitor setup looks wrong, compare:

```text
~/.config/hypr/dms/outputs.lua
~/.config/hypr/.dms-backups/<timestamp>/
```

Your previous config should be available in the timestamped backup folder.

## Reference Map

```text
~/.config/hypr/
|-- hyprland.lua             # Main DMS Hyprland config
|-- .dms-backups/            # Timestamped backups from setup/migration
`-- dms/
    |-- colors.lua           # Theme colors
    |-- outputs.lua          # Monitor/output config
    |-- layout.lua           # Layout, gaps, borders, decoration
    |-- cursor.lua           # Cursor settings
    |-- binds.lua            # DMS-managed default shortcuts
    |-- binds-user.lua       # User shortcut overrides
    `-- windowrules.lua      # DMS-managed window rules
```

Legacy files such as `hyprland.conf` and `dms/*.conf` should live in
`.dms-backups/<timestamp>/` after migration, not in the active config tree.

## Maintainer Note

Embedded source files live in `core/internal/config/embedded/` and use names like
`hypr-binds.lua`. Installed user files use shorter names like `dms/binds.lua`.

After changing Hyprland config deployment or parsing, run:

```sh
cd core
go test ./internal/config ./internal/keybinds/providers ./internal/windowrules/providers
go test ./...
```