README: the software-cursor workaround for garbled cursors on NVIDIA with Hyprland (13.1, #9)

AGENTS.md

@@ -176,6 +176,7 @@ Deliberate name breaks: `MetalBrushCoverage` → `BrushCoverage`, `MetalLayerEff
 - Tool icons: SF Symbols have no Linux twin, and icon themes differ by distro, so `src/UI/ToolIcons` draws each tool's icon as paths in an 18-point square, in one colour that the caller takes from the palette (the Omarchy theme retints them for free). Swift's two hand-drawn icons keep their geometry there (`GradientToolIcon`'s Floyd–Steinberg fade, `CloneStampToolIcon`'s four parts); Swift keeps them in `GradientControls` and `BrushControls`, and the twin keeps them with the rail's other icons. The eyedropper's glyph lives in `Rendering/EyedropperIcon`, since the canvas's cursor draws it too. Icons that follow tool state (the ellipse marquee, the polygonal lasso, the Magic tool's object mode, the eraser) take a `ToolIconKind`. `tests/fixtures/ToolIcons.png` is the reference sheet: `ToolIconTests` redraws it, allows a font a few pixels and a stroke none, and writes the fresh sheet beside the test binary; after a wanted change, look at it and commit it.
 - Omarchy theme: `src/UI/OmarchyTheme` reads `~/.local/state/omarchy/current/theme/colors.toml` (Omarchy 4.x: flat `key = "value"` lines, `mode` dark or light, the twenty-two stock themes' keys required, `orange` optional and `yellow` its stand-in) into `OmarchyColors`, applies them as the application palette (Window and Text from `background` and `foreground`, Base from `darker_background`, Button from `lighter_background`, Highlight and Link from `accent` with the background as highlighted text, PlaceholderText from `dark_foreground`, BrightText from `orange` or `yellow`, Mid from `muted`, the disabled roles from `muted`) and sets the Fusion style, which follows a palette on every desktop where a platform style does not; no stylesheet is needed. Keys and values read in double or single quotes. A missing key, or a recognised key whose value is bare or half-quoted or no `#rrggbb`, refuses the file with the key's name; a file that exists but cannot be opened, or sits behind a folder that cannot be searched (`stat` fails other than `ENOENT`), is refused too; either way the app keeps the palette it has and logs a warning, where an absent file means the built-in dark, Swift's grays, installed before the first load. `omarchy-theme-set` removes `current/theme`, moves `next-theme` in and writes `theme.name`, so the watcher holds `current/`, `current/theme` and the file, adds them back after each load (a removed path leaves a `QFileSystemWatcher`) and renews the file's watch every load (it follows the inode, which an atomic replacement swaps), watches the nearest ancestor the watcher accepts while `current/` is missing or barred, letting it go once the directory is watched, and loads once 100 ms after the last event. A read that stops short (an error, or fewer bytes than the file holds) is refused like a malformed file. Each load logs the theme's name and mode on `omaphoto.app`. `main` makes the theme before the window. Widgets take colours from the palette, never from literals; the canvas keeps Swift's document grays. The UI font stays Qt's default: `omarchy font current` is not followed.
 - No updater. Distro packages own updates.
+- Custom cursors (`QCursor` pixmaps) come out garbled on the hardware cursor path with NVIDIA and Hyprland at a fractional scale; theme cursors render correctly (issue #9, hyprwm/Hyprland#16413). README gives the software-cursor setting; the app keeps its cursors and does not guess at drivers (the user's decision, 13.1).
 - Distribution (11.4b): releases live on GitHub under fixed asset names (`omaphoto-noble_amd64.deb`, `omaphoto-resolute_amd64.deb`, `omaphoto-fc43.x86_64.rpm`, `omaphoto-fc44.x86_64.rpm`, `omaphoto-x86_64.pkg.tar.zst`; 1.0.0 had one DEB, `omaphoto_amd64.deb`, and 1.0.0 to 1.2.3 one RPM, `omaphoto.x86_64.rpm`) with `SHA256SUMS`, so `releases/latest/download/<name>` always reaches the newest. `scripts/install/arch.sh` reads `/etc/os-release` (`ID` or `ID_LIKE`; Omarchy says `ID_LIKE=arch`), `fedora.sh` its `ID` or `ID_LIKE` and `VERSION_ID`, taking the RPM of release 43 or 44 and refusing any other, since each names its release's LibRaw (`libraw_r.so.23` on 43, `.25` on 44; found in 12.16, when 1.2.3's single RPM from Fedora 43 would not install on 44), and `ubuntu.sh` its `UBUNTU_CODENAME`, which Ubuntu's derivatives set to their base: each DEB names its release's Qt libraries (24.04's carry a `t64` suffix that 26.04's drop, and Debian 13 has neither), so the release carries one DEB per LTS, built on it (`Dockerfile.dev` takes the base as `BASE`), and the script takes the one whose codename matches, `noble` or `resolute`, refusing any other. Each refuses another system or another machine than x86_64, verify the package against the sums and install it with apt, dnf or pacman under sudo, so the package manager resolves dependencies; apt reads the file as its own user, so the download folder is opened to it. Fedora's script names RPM Fusion's `libheif-freeworld` when it is missing, since Fedora's libheif decodes no HEVC, and adds no repository itself. `nixos.sh` installs the flake at the newest release's tag, which GitHub's `releases/latest` redirect names, into the user's profile (`nix profile install`, the name every Nix still takes), so no user builds unreleased work from `main`. The README runs each script after downloading it, so the package manager's questions read the terminal and fish runs it too. `release.yml` builds each package with the command the distro checks use, the DEBs on the dev image over each base, the RPMs on Fedora 43 and 44 (`scripts/distro/fedora/Dockerfile` takes the release as `RELEASE`, 43 by default), the Arch package through `makepkg` as a user; the version is CMake's `project` version, the PKGBUILD's and the flake's, kept equal by hand, and the workflow's first job refuses a tag that names another.
 - Remove Background runs an open-licensed model on ONNX Runtime.
 - A `.comp` project is a directory on Linux; its layout matches the macOS package.

README.md

@@ -63,6 +63,24 @@ Or add `github:ZacharyZhang-NY/OmaPhoto/<tag>`, a release tag, as a flake input
 
 The packages themselves sit on the [releases page](https://github.com/ZacharyZhang-NY/OmaPhoto/releases).
 
+### Garbled cursors on NVIDIA with Hyprland
+
+On NVIDIA with Hyprland at a fractional scale, the cursors OmaPhoto draws itself, such as those of the selection tools, the wand, the eyedropper, zoom and moving layers, can show garbled or cut off. Theme cursors render correctly. The fault lies in the hardware cursor path (reported upstream as [Hyprland #16413](https://github.com/hyprwm/Hyprland/issues/16413)). Software cursors avoid it.
+
+Current Hyprland and Omarchy read `~/.config/hypr/hyprland.lua`; Omarchy users can put the line in `~/.config/hypr/looknfeel.lua`:
+
+```lua
+hl.config({ cursor = { no_hardware_cursors = 1 } })
+```
+
+An older setup that reads `~/.config/hypr/hyprland.conf` takes:
+
+```
+cursor {
+    no_hardware_cursors = 1
+}
+```
+
 ## Build from source
 
 The build runs in Docker, so the host needs only Docker:

TASKS.md

@@ -412,7 +412,8 @@ Reviews for this section run on codex `gpt-6.1-sol` at `max` (agent `codex-sol`,
 
 - [x] 13.0 Survey v1.3.3..v1.4.5 (94 commits) and split them into the items below; the two window-teardown crashes found in 11.5 are fixed on `main` (e94fd73) and ship with 1.4.5.
 - 13.0 codex review (gpt-6.1-sol, max): round 1 FAIL (the Metal commits' shared CPU contracts unnamed, ordinary paint at the layer's resolution missing from 13.11, Camera Raw's graph gestures missing from 13.18); round 2 FAIL (more contracts from its inventory, the empty layer's document resolution); round 3 PASS.
-- [ ] 13.1 Issue #9: custom cursors garbled on NVIDIA + Hyprland at a fractional scale (the driver's hardware cursor plane, hyprwm/Hyprland#16413). README's Install section names the workaround, `cursor { no_hardware_cursors = true }`; the issue gets the answer. No app-side fallback (the user's decision).
+- [x] 13.1 Issue #9: custom cursors garbled on NVIDIA + Hyprland at a fractional scale (the driver's hardware cursor plane, hyprwm/Hyprland#16413). README's Install section names the workaround, `cursor { no_hardware_cursors = true }`; the issue gets the answer. No app-side fallback (the user's decision).
+- 13.1 review (codex-sol): round 1 FAIL (the config path: Hyprland 0.56 and Omarchy load `hyprland.lua`, the `.conf` block is the older form; an unproven reason for theme cursors; the cursor list not marked as examples); round 2 PASS. The reply posted on the issue.
 - [ ] 13.2 Version 1.3.4, part one: a font change applies to the selected letters, a mixed selection takes the face the menu shows, the menu says (Multiple) (`0eaeb98`, `1ffc8f4`, `916d1ab`, `bc29006`'s test), with the manifest and both format documents.
 - [ ] 13.3 Part two: Dither's ASCII as readable text (`2309a85`, the kernel and the sheet); Select › Color Range (`c3e360a`: `ColorRangeSelection`, `WandPixels.c`, the sheet, the canvas's sampling).
 - [ ] 13.4 Version 1.3.5, part one: Export JPEG and Canvas Size take the app's colour picker (`c580a38`); Export JPEG's zoomable preview and tidier layout (`ac6f309`); `908bed9` and `158cd53` judged (Swift concurrency and warnings).