wallpaper: a shuffle bag for the engine's order

Each round shows every hearted wallpaper once, in random order, so no
picture is skipped or doubled within a round. A reshuffle never opens
with the picture on screen, so the same wallpaper cannot appear twice
in a row across the round boundary.

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

1 files changed, 35 insertions, 0 deletions

diff --git a/desktop/modules/appearance/Shuffle.js b/desktop/modules/appearance/Shuffle.js
new file mode 100644
index 0000000..7e5cf16
--- /dev/null
+++ b/desktop/modules/appearance/Shuffle.js
@@ -0,0 +1,35 @@
+.pragma library
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+// The wallpaper engine's order, tested by test_shuffle.js under node: a
+// shuffle bag. Each round shows every path once in random order, and a new
+// round never opens with the path on screen, so a reshuffle cannot show the
+// same picture twice running.
+
+// The next path and what is left of the round. `list` is what may be shown
+// now, so a heart removed since the last draw drops out of the bag; `last` is
+// the path on screen. pick is "" for an empty list.
+function draw(list, bag, last) {
+    let left = bag.filter(p => list.indexOf(p) >= 0);
+    if (left.length === 0) left = shuffled(list, last);
+    return { pick: left.length ? left[0] : "", bag: left.slice(1) };
+}
+
+function shuffled(list, last) {
+    const a = list.slice();
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const t = a[i]; a[i] = a[j]; a[j] = t;
+    }
+    if (a.length > 1 && a[0] === last) { const t = a[0]; a[0] = a[1]; a[1] = t; }
+    return a;
+}