feat: copy the vertical wallpaper to a phone

With PHONE_V set, every change of the vertical wallpaper is copied to
that path, a fixed name inside a folder Syncthing shares with a phone,
where a Termux loop applies it (script in the README). A copy, not a
symlink, because Syncthing does not follow links. It is built in
~/.cache/wallp and moved into place, so Syncthing never sees a partial
file.

PHONE_SIZE (WxH) crops it to the phone screen, centred, with magick, as
swaybg's fill does: Android otherwise scales a landscape image to the
screen height and shows its left edge. A stamp of source and size skips
an image already copied, so a --restore at login does not make the phone
reapply it. Unset PHONE_V does nothing.

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

1 files changed, 29 insertions, 0 deletions

diff --git a/README.md b/README.md
index 394ba29..a715cca 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,7 @@ with one flag-driven program.
 | `swaybg`      | yes                 | paints the wallpaper on each output  |
 | `udt-accent`  | optional            | refreshes the desktop accent colour  |
 | `qarma`       | only for GUI `--set`| screen-choice menu + file picker     |
+| `magick`      | only for `PHONE_SIZE`| crops the phone copy (ImageMagick)  |
 | `bats`        | dev only            | running the test suite               |
 
 `wallp` checks for the required binaries at startup and exits with a clear
@@ -132,6 +133,7 @@ State is owned entirely by `wallp`:
 | `~/.cache/wallp/H.pid`        | PID of the horizontal `swaybg`                  |
 | `~/.cache/wallp/V.pid`        | PID of the vertical `swaybg`                    |
 | `~/.cache/udt/wpaper`         | symlink to the current horizontal image         |
+| `PHONE_V` (optional)          | copy of the current vertical image, for a phone |
 
 Setting a screen: validate the file, kill **only** that screen's old `swaybg`,
 launch a new one (`swaybg -o <output> -i <file> -m fill`), record the new PID,
@@ -144,6 +146,33 @@ configured default; apply it; then refresh the accent the same way.
 The `wpaper` symlink is the hand-off point to the rest of the theme: other
 tools (rofi, `udt-accent`) read it rather than `wallp`'s own state.
 
+## Phone wallpaper
+
+Set `PHONE_V` in the config and every change of the vertical wallpaper is
+copied to that path, a fixed name inside a folder Syncthing shares with a
+phone. Unset, nothing happens. With `PHONE_SIZE=1440x3120` (the phone's
+screen in pixels) it is cropped to that size, centred, using ImageMagick's
+`magick`. Without it Android scales a landscape image to the screen height and
+shows its left edge. A wallpaper already copied is not rewritten.
+
+On an Android phone with Termux and Termux:API (both from F-Droid), a loop
+applies the file whenever it changes. Start it from Termux:Boot and exempt
+Termux from battery optimisation:
+
+```sh
+#!/data/data/com.termux/files/usr/bin/sh
+# Polls rather than using inotify, which is unreliable on shared storage.
+f=~/storage/shared/Documents/phone-wallpaper.png
+last=
+while sleep 60; do
+  m=$(stat -c %Y "$f" 2>/dev/null) || continue
+  [ "$m" = "$last" ] || { termux-wallpaper -f "$f"; termux-wallpaper -l -f "$f"; last=$m; }
+done
+```
+
+Drop the `-l` call to leave the lock screen alone. The launcher draws the
+system wallpaper, so it follows without setup of its own.
+
 ## Integration with sway / Hyprland
 
 Bind the interactive setter to a key and run a restore at startup. For Hyprland: