hyprland: keyboard shortcuts and options pages in the settings window

Keyboard shortcuts lists every bind hyprctl reports, joined to the
hl.bind call in ~/.config/hypr that made it: hyprctl gives every Lua
action as an opaque __lua number, so the action and file:line only
exist in the source. The join is by description, then combo, then the
longest literal head of a description built in a loop. List, Source
and Clashes tabs. A combo the source writes as a plain string (or from
file-level string locals) can be changed: hyprctl eval of a do-nothing
bind checks it first, refusing an unknown modifier or keysym, then the
call's first argument is rewritten and Hyprland autoreloads.

Options lists all 353 options from hyprctl descriptions, with values
from one batched getoption, since descriptions' own "current" field is
stale. Filters for everything, set in the config, and changed from the
default. A change is one line in hypr-theme's sections/keystone.lua,
required last, and is run through hyprctl eval first, which refuses an
unknown key or a wrongly shaped value without changing anything.

Both modules keep their own copy of the file text: FileView.text()
returns the old text right after setText(), and a second quick edit
built from it dropped the first. The AGENTS.md notes record that and
the hyprctl quirks found on the way.

Check: node desktop/modules/hyprland/test_hypr.js

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 56 insertions, 0 deletions

diff --git a/desktop/modules/hyprland/README.md b/desktop/modules/hyprland/README.md
new file mode 100644
index 0000000..278a3b4
--- /dev/null
+++ b/desktop/modules/hyprland/README.md
@@ -0,0 +1,56 @@
+# hyprland
+
+Two settings pages, under Hyprland in the settings window.
+
+## Keyboard shortcuts
+
+Every bind Hyprland has loaded, from `hyprctl binds -j`, joined to the
+`hl.bind` call in `~/.config/hypr` (`hyprland.lua` and `sections/*.lua`)
+that made it: by description, then by combo, then, for a bind built in a
+loop, by the longest literal head of its description. hyprctl reports every
+Lua action as an opaque `__lua` number, so the action shown is the source's.
+
+List shows the combo, the description and action, and the file:line. Source
+shows the files holding binds, line-numbered. Clashes lists combos bound
+more than once in the same submap.
+
+Clicking a row opens its combo for editing when the source writes it as a
+plain string, or one built from file-level string locals (`mainMod .. " +
+w"`). Save asks Hyprland first, by `hyprctl eval` of a do-nothing bind on the
+new combo, which fails on an unknown modifier or keysym. Then the first
+argument of that call is replaced with the combo as a string literal, and
+Hyprland's autoreload picks up the file. An edit is refused if the call is
+no longer where it was parsed. A bind built at run time says where to change
+it instead.
+
+## Options
+
+All of Hyprland's options from `hyprctl descriptions -j`, with values from
+one batched `getoption`, filtered by everything, set in the config, or
+changed from the default. Values differing from the default are in the
+accent, gradients show their colours.
+
+A change is one line in `sections/keystone.lua`, which `hyprland.lua`
+requires last, so it wins over the hand-written sections without editing
+them:
+
+    hl.config({ general = { border_size = 4 } }) -- keystone: general:border_size
+
+The line is run through `hyprctl eval` first, which refuses an unknown key or
+a value of the wrong shape and changes nothing; one that passes applies at
+once and is then written. Booleans and enums are picked from their choices,
+everything else is typed as a Lua expression, started from the current value
+(`{ top = 8, right = 8, bottom = 8, left = 8 }` for gaps, `{ colors = {
+"rgba(...)" }, angle = 45 }` for a gradient). Reset drops the line, and the
+reload brings back what the other sections, or the default, give it.
+
+Not handled: an option a hand-written section sets is shadowed, not edited
+there; and the two options `getoption` cannot read show as unreadable and
+cannot be edited.
+
+## Check
+
+    node desktop/modules/hyprland/test_hypr.js
+
+It also checks every live bind finds its source, when `~/.config/hypr` is
+there.