Add a displays widget for monitor layout and per-monitor wallpapers

docs/commands.md

@@ -43,6 +43,7 @@ of the `blob` listing.
 | `blob-bg-cache` | Cache background switcher thumbnails for the current theme | - |
 | `blob-bg-current` | Show current background | - |
 | `blob-bg-install` | Open the current theme's user background folder | - |
+| `blob-bg-monitor` | Assign a wallpaper to one monitor, leaving the others alone | <--list\|--clear-all\|<output> <image>\|<output> --clear> |
 | `blob-bg-next` | Cycle to the next background for the current theme | - |
 | `blob-bg-set` | Set the current background image | <path-to-image> |
 | `blob-bg-switcher` | Open the Blob background switcher | - |
@@ -138,6 +139,7 @@ of the `blob` listing.
 
 | Command | Does | Arguments |
 | --- | --- | --- |
+| `blob-display-arrange` | Apply a monitor layout at runtime without touching monitors.lua | <list\|apply <keyword>...\|reset> |
 | `blob-display-size` | Scale text everywhere — blob shell, GTK apps, and terminals | [size\|reset] |
 | `blob-display-state` | Print monitor panel state for the shell | - |
 
@@ -620,4 +622,4 @@ of the `blob` listing.
 
 ## Totals
 
-291 commands.
+293 commands.

docs/keybinds.md

@@ -14,6 +14,7 @@ Personal overrides in `hypr/bindings.lua` win over the defaults, and
 | `SUPER + ALT + W` | Wallpaper picker |
 | `SUPER + CTRL + M` | System monitor |
 | `SUPER + CTRL + Q` | Quick settings |
+| `SUPER + SHIFT + CTRL + D` | Displays |
 | `SUPER + SPACE` | Apps menu |
 
 ## Applications

docs/packages.md

@@ -64,6 +64,35 @@ Two are worth knowing about:
 
 `quickshell` never came from the Omarchy repository - it is in official `extra`.
 
+## Installing packages
+
+`install.sh` installs what is missing before it writes any config:
+
+```
+packages/blob.packages       117 packages from core, extra, multilib
+packages/blob-aur.packages    11 packages with no official equivalent
+```
+
+Only missing packages are touched, through `pacman -S --needed` and
+`yay -S --needed`. `./install.sh --check` lists what it would install without
+installing anything, and `--skip-packages` does the directories and config only.
+
+An entry may be written `wanted|already-fine`, which asks for the first name but
+accepts either as satisfying the requirement. That is how
+`hyprland-preview-share-picker-git` avoids conflicting with the non-git build
+that the Omarchy repository still ships.
+
+Three of the AUR entries are load-bearing for this fork and were not in
+Omarchy's own package list, because they were installed by hand on this machine:
+
+| Package | Needed by |
+| --- | --- |
+| `python-pywal` | `blob-wallpaper-set`, palette extraction |
+| `awww` | the wallpaper daemon `blob-wallpaper-set` and `blob-theme-menu` drive |
+| `playerctl` | the quick settings media row |
+
+`playerctl` is in official `extra`, so it sits in the repo list.
+
 ## Updating
 
 ```

docs/widgets.md

@@ -52,3 +52,51 @@ binding to the shell's own audio, brightness and media services. Polling only
 runs while a panel is open, so the cost is bounded, but wiring these to the
 services is the obvious next refinement and would remove the last per-tick
 process spawns.
+
+## Displays
+
+`blob.displays` arranges monitors and assigns wallpapers per monitor. Opened
+with `Super + Shift + Ctrl + D` or the Blob menu's Displays row.
+
+### Monitors tab
+
+A scaled picture of the desktop, one draggable rectangle per monitor. Dropping
+one applies the new position immediately. Edges snap to a neighbour's edge
+within 60 logical pixels, so monitors end up touching exactly.
+
+Per-monitor controls: mode, scale, enable or disable, and mirror.
+
+**Scale options are filtered, not free.** Hyprland steps fractional scaling in
+1/120 and rejects a scale that does not land on a whole number of physical
+pixels on both axes. `DisplayModel.scaleIsValid` applies that rule, so only
+usable scales are offered. On a 1920x1080 panel that means 1.0 and 1.2 are
+adjacent with nothing between them, which is the constraint `hypr/monitors.lua`
+documents by hand.
+
+**Nothing is written to `monitors.lua`.** Every change goes through
+`hyprctl keyword monitor` and lasts until the config reloads or the session
+ends. "Reset to monitors.lua" runs `hyprctl reload` and makes the checked-in
+config authoritative again. To keep a layout, edit `monitors.lua` yourself -
+`blob display arrange list` prints the current layout in the exact keyword form,
+ready to copy.
+
+### Wallpapers tab
+
+A thumbnail grid of `~/wallpapers`. Clicking one assigns it to the selected
+monitor through `blob-bg-monitor`, which symlinks it under
+`~/.local/state/blob/backgrounds/<output>`.
+
+`blob.background` already drew one window per screen but pointed them all at the
+same image. It now resolves per screen: a monitor with an assignment shows it,
+and a monitor without one shows the global wallpaper from `blob-bg-set`. The
+crossfade machinery stays on the global path only, so an assigned monitor swaps
+without the reveal animation rather than risking that code.
+
+| Command | Does |
+| --- | --- |
+| `blob bg monitor <output> <image>` | assign a wallpaper to one monitor |
+| `blob bg monitor <output> --clear` | fall back to the global wallpaper |
+| `blob bg monitor --list` | show assignments |
+| `blob display arrange list` | print the layout as monitor keywords |
+| `blob display arrange apply <kw>` | apply a keyword now |
+| `blob display arrange reset` | reload, restoring monitors.lua |