docs: the monitors settings page

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

1 files changed, 36 insertions, 0 deletions

diff --git a/desktop/modules/monitors/README.md b/desktop/modules/monitors/README.md
new file mode 100644
index 0000000..3716110
--- /dev/null
+++ b/desktop/modules/monitors/README.md
@@ -0,0 +1,36 @@
+# monitors
+
+Settings > Hyprland > Monitors: the connected monitors, from `hyprctl
+monitors -j`.
+
+The layout draws each monitor at its logical size (rotated a quarter turn
+swaps width and height, scale divides both). Drag one to move it; on release
+it snaps to the other monitor's edges when within 64 logical pixels, and its
+position becomes exact; a click without movement does not snap. Each card sets the mode, from the monitor's own list
+with duplicates dropped, the scale, rotation and flip, VRR, and the position,
+exact or one of Hyprland's `auto-*` values.
+
+Apply runs each monitor's `hl.monitor({ ... })` through `hyprctl eval`, one
+call per monitor because eval wraps its argument in a `return`. A refused
+line (exit 7) changes nothing and shows its error; a reload follows, since an
+earlier monitor may have gone through. Accepted, the change is live and a bar
+asks to keep it. Keep writes `~/.config/hypr/sections/monitors.lua`, which
+this page owns and rewrites whole. Revert, leaving the page, or 15 seconds
+with no answer runs `hyprctl reload`, which reapplies the untouched file. A
+setting that blanks a screen never reaches the file. The cards and the layout
+are locked while the bar waits, since Keep writes the draft as it stands.
+
+hyprctl only reports where a monitor ended up, so a monitor set to an `auto-*`
+position in the file reads back as exact. VRR is assumed to read the same
+way, as the active state rather than the configured one, so a `vrr = 2`
+(fullscreen only) would read off and be dropped by Keep; not checked, as the
+config sets no VRR.
+
+Not handled: disabling an output, mirroring, bit depth and colour management,
+outputs that are not connected (an unplugged monitor drops out of the file on
+Keep), renaming outputs. The island and the window switcher are tied to DP-1
+by name.
+
+## Check
+
+    node desktop/modules/monitors/test_mon.js