Wallpapers not working on ported machine: implementation guide, failure modes, verification

[nethum529]

Companion to #9 — read that first; the wallpaper system is a feature OF Ambxst, so nothing here works until #9's checks pass. Ground truth verified live on the source laptop 2026-08-09.

How wallpapers REALLY work here

• There is no wallpaper daemon. No swww, no hyprpaper, no mpvpaper process.
  Ambxst's quickshell draws the wallpaper itself as a QML background layer
  (modules/components/TintedWallpaper.qml and friends).
  If Ambxst isn't running, the desktop is black and no daemon will fix it.
• Files: ~/Pictures/Wallpapers/ — all 10 of the laptop's wallpapers are in
  the repo at parity/wallpapers/ (verified byte-identical to the laptop set);
  parity/install-parity.sh copies them (no clobber).
• State: ~/.cache/ambxst/wallpapers.json:
  wallPath (the folder), currentWall (active file), matugenScheme
  (scheme-tonal-spot), activeColorPreset, tintEnabled. As of PR Wallpaper first-launch parity: seed state + matugen package #11 the
  installer seeds this file when absent, defaulting to renwallpaper.jpg, so a
  fresh machine matches the laptop on first launch.
• Picker: Super+Comma → ambxst run wallpapers. Selecting a wallpaper
  rewrites wallpapers.json and re-themes the shell via matugen
  (in packages.txt as of PR Wallpaper first-launch parity: seed state + matugen package #11; it was missing before).
• Thumbnails cache under ~/.cache/ambxst/thumbnails/ regenerates itself; never seed or debug it.

Implementation

cd ~/linux-setup && git pull        # must include PR #11
./parity/install-parity.sh          # wallpapers + state seed (idempotent)
sudo pacman -S --needed matugen
# relog, or if Ambxst is already running: press Super+Comma and pick one

Failure modes, most likely first

1. Ambxst not running — root cause of a black desktop 100% of the time
   here. Fix Workspaces + Super+# + Super+Tab not working on ported machine: implementation guide, failure modes, verification #9 first; do NOT install swww/hyprpaper as a workaround (a second
   layer fights Ambxst's own and you get flicker/overdraw).
2. Old checkout — parity ran before PR Wallpaper first-launch parity: seed state + matugen package #11, so the state seed and matugen
   are missing: picker works but first boot is black/default until manual pick.
   git pull && ./parity/install-parity.sh again.
3. Stale state from a failed attempt — wallpapers.json exists but
   currentWall points at a path that doesn't exist (e.g. /home/nethum/...
   on a different username: the seeder writes $HOME correctly, but only if it
   ran). Check jq -r .currentWall ~/.cache/ambxst/wallpapers.json and confirm
   the file exists; delete wallpapers.json and re-run parity if wrong.
4. Wallpapers folder empty — parity step skipped or ran from a partial
   clone: ls ~/Pictures/Wallpapers | wc -l → 10.
5. matugen missing — picking a wallpaper works but colors don't re-theme
   and the shell may log matugen errors: command -v matugen.
6. Agent edits hyprland.conf to set a wallpaper — no hyprland wallpaper
   directive exists in this setup; revert any such edits.

Verify correctness

ls ~/Pictures/Wallpapers | wc -l                       # 10
jq -r .wallPath,.currentWall ~/.cache/ambxst/wallpapers.json
test -f "$(jq -r .currentWall ~/.cache/ambxst/wallpapers.json)" && echo wall-exists
pgrep -af 'qs -p'                                      # Ambxst running (see #9)
command -v matugen

Functional: desktop shows renwallpaper on a fresh machine; Super+Comma opens
the picker with 10 thumbnails; selecting another wallpaper changes the
background immediately AND shifts the bar/dock accent colors (matugen);
currentWall in wallpapers.json updates to the new path.