spec: wallpaper engine, wallpapers on a timer from hearted lists

Per-screen lists picked with the heart, one shuffled tick for both
screens, a light accent run for timer changes that leaves GRUB, the
homepage and SDDM alone, and a home wallpaper each screen returns to
when the engine is switched off, so the desktop matches those three
again.

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

1 files changed, 99 insertions, 0 deletions

diff --git a/docs/superpowers/specs/2026-10-29-wallpaper-engine-design.md b/docs/superpowers/specs/2026-10-29-wallpaper-engine-design.md
new file mode 100644
index 0000000..aac3b1c
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-29-wallpaper-engine-design.md
@@ -0,0 +1,99 @@
+# Wallpaper engine: wallpapers on a timer
+
+Date: 2026-10-29
+
+## Goal
+
+Change the wallpapers on a timer, from a list per screen picked with a heart
+in the wallpaper picker. Timer changes recolour the live desktop but leave the
+boot and login surfaces alone; the user's own picks keep doing everything.
+
+## Lists
+
+One plain-text file per screen, one absolute path per line:
+`~/.config/keystone/wallpapers/h.list` (DP-1) and `v.list` (DP-3). There are no
+portrait images in the gallery, so a screen's list is the user's choice, not
+derived from aspect ratio. A path whose file is missing stays in the list and
+is skipped by the timer.
+
+## Heart
+
+Back on every thumbnail in `WallpaperTab.qml`, with the glyphs it had before
+the companion was removed: outline `\u{F02D5}` on hover, filled `\u{F02D1}` in
+`Theme.red` when listed. It reads and toggles the list of the screen the picker
+targets (`Wallpapers.target`, H or V). A toggle writes the file at once. It sits
+after the pick `MouseArea`, so it takes its own click.
+
+## Engine section
+
+A section on the existing Wallpaper page, not a new page:
+
+- an on/off switch;
+- the interval, in minutes;
+- the two lists with their counts, each entry removable, a missing file dimmed;
+- a Next button that ticks now.
+
+On/off, the interval and the two home wallpapers (below) live in `Prefs`, so
+they survive a restart. A running engine is running again after a restart.
+
+## Tick
+
+A `Timer` in the `Wallpapers` singleton, repeating at the interval while the
+engine is on.
+
+- Each screen with a non-empty list takes the next path from a shuffle bag:
+  the list shuffled, drawn without repeats until empty, then reshuffled, with
+  the path just shown never first in the new round. The bag is not persisted;
+  a restart reshuffles.
+- Both screens go in one `wallp --set` call, through the same path as Apply,
+  so the burn transition plays. A screen with an empty list is left alone.
+- A tick while a `wallp` run is in progress is skipped.
+- A tick does not touch staged picks (`pendingH`, `pendingV`).
+- The call runs with `UDT_ROTATION=1` in its environment (light run, below).
+
+## Manual picks and the home wallpaper
+
+A manual Apply is always the full run, engine on or off.
+
+Each screen has a home wallpaper, kept in `Prefs`:
+
+- switching the engine on sets each home to what that screen shows;
+- a manual Apply while the engine is on sets the home of each screen it
+  applied, and restarts the timer, so the pick stays up a full interval;
+- switching the engine off sets each screen whose current wallpaper differs
+  from its home back to the home, in one full `wallp --set`. Both equal, or a
+  home whose file is gone, changes nothing.
+
+The shuffle continues where it was after a manual pick.
+
+## Light run: udt-accent
+
+In `unified-desktop-theme/bin/udt-accent`: with `UDT_ROTATION` set and
+non-empty, skip `write_grub`, `write_homepage` and `write_sddm`, and do not
+start the `udt-grub` and `udt-homepage` helpers. Everything else runs: the
+accent, Hyprland borders, hyprlock, QML palette, Sublime, colors.json,
+Firefox, conky, and the keyboard, LED strip, bulb and TV helpers. `wallp` needs
+no change: it runs `udt-accent` as a child, which inherits the variable.
+
+## Conky, separately
+
+Conky reloads `conky.conf` in place on an accent change, recreating its window,
+and the `dash-workspace` rule in hypr-theme's `sections/dashboard.lua` then
+sends the new window to `special:dash` without `silent`, which shows the
+special workspace. The rule becomes `workspace = WS .. " silent"`. To be
+confirmed by eye on the next accent change.
+
+## Checks
+
+- A runnable check for the shuffle bag, in a `.js` file beside it: no repeat
+  within a round, a refill after the last, and the last path never first in
+  the next round (a one-item list excepted).
+- A check in `udt-accent`'s selftest that the three writes and two helpers are
+  skipped with `UDT_ROTATION=1`, against temporary paths.
+- By eye: heart, engine section, a tick with the burn, switching off returning
+  home, conky staying hidden.
+
+## Out of scope
+
+Sequential order, per-screen intervals, persisting the shuffle, rotation from
+a terminal `wallp` without the desktop shell.