docs: wallpaper transitions

Also how to check a shader headless: the offscreen platform is the
software backend, where a ShaderEffect draws nothing, and an end frame
check passes for every shader while proving nothing.

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

1 files changed, 24 insertions, 14 deletions

diff --git a/desktop/modules/appearance/README.md b/desktop/modules/appearance/README.md
index 59868b4..ab61811 100644
--- a/desktop/modules/appearance/README.md
+++ b/desktop/modules/appearance/README.md
@@ -156,20 +156,30 @@ which screen is targeted. Their proportions come from the pane **width**, not
 its height. Scaling the stand off height gave the wide monitor a 20px stand
 that was invisible and would have given the vertical one an absurd long neck.
 
-### The burn
-
-Apply, and every engine change, burns the old picture away over the new
-one (`WallpaperSpread.qml`, `burn.frag`). swaybg has no transitions, and
-wallp kills one and starts another, so a surface on the bottom layer of each
-screen, above swaybg and below every window, holds the old picture over the
-swap. `Wallpapers.run()` emits `swapping`, then waits for each cover to call
-`covered()` (both its pictures decoded, then 50ms for a few frames) before
-it starts wallp, with a 1.5s fallback for a cover that never comes. Started
-any earlier, the new picture showed through for a moment before the burn.
-The images stay hidden until both are decoded for the same reason: the new
-one usually lands first. A set from a terminal gets no burn. After editing
-`burn.frag`, recompile with `qsb --qt6 -o burn.frag.qsb burn.frag` under a
-new name or restart the shell: a running shell keeps a shader by URL.
+### Transitions
+
+Apply, and every engine change, plays a transition over the swap, the old
+picture giving way to the new one (`WallpaperSpread.qml`, `WallShader.qml`,
+one `.frag` each: burn, ink, shatter, ripple, melt, blinds, crosswarp). The
+Transitions page picks one, or Random, which draws from the ticked ones and
+never repeats the last. Clicking a tile plays it between the two current
+wallpapers through the same shader. Both screens play the same one in a run.
+Each shader must draw the old picture exactly at `progress` 0 and the new one
+at 1, or the cover pops as it comes and goes. Pictures reach a shader through
+a layer, since an `Image` sampled directly gives the whole picture and not its
+crop.
+
+swaybg has no transitions, and wallp kills one and starts another, so a
+surface on the bottom layer of each screen, above swaybg and below every
+window, holds the old picture over the swap. `Wallpapers.run()` emits
+`swapping`, then waits for each cover to call `covered()` (both its pictures
+decoded, then 50ms for a few frames) before it starts wallp, with a 1.5s
+fallback for a cover that never comes. Started any earlier, the new picture
+showed through for a moment before the transition. The images stay hidden
+until both are decoded for the same reason: the new one usually lands first.
+A set from a terminal gets no transition. After editing a `.frag`, recompile
+with `qsb --qt6 -o <name>.frag.qsb <name>.frag` under a new name or restart
+the shell: a running shell keeps a shader by URL.
 
 ## Wallpaper engine