2 files changed, 80 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;
+}
diff --git a/desktop/modules/appearance/test_shuffle.js b/desktop/modules/appearance/test_shuffle.js
new file mode 100644
index 0000000..6dcb528
--- /dev/null
+++ b/desktop/modules/appearance/test_shuffle.js
@@ -0,0 +1,45 @@
+// 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.
+
+// Run: node desktop/modules/appearance/test_shuffle.js
+// Shuffle.js is a QML library, so its .pragma line is stripped before node
+// evaluates it.
+
+const fs = require("fs");
+const assert = require("assert");
+
+const src = fs.readFileSync(__dirname + "/Shuffle.js", "utf8").replace(/^\.pragma library$/m, "");
+const S = new Function(src + "\nreturn { draw };")();
+
+// Every round shows each path once, and no path twice running, across the
+// refill included.
+const list = ["a", "b", "c", "d"];
+let bag = [], last = "";
+for (let r = 0; r < 200; r++) {
+    const round = [];
+    for (let i = 0; i < list.length; i++) {
+        const d = S.draw(list, bag, last);
+        assert.notStrictEqual(d.pick, last, `round ${r}: ${d.pick} twice running`);
+        round.push(d.pick);
+        bag = d.bag;
+        last = d.pick;
+    }
+    assert.deepStrictEqual(round.slice().sort(), list);
+}
+
+// A path removed from the list leaves the bag with it.
+assert.deepStrictEqual(S.draw(["a", "b"], ["c", "b"], "a"), { pick: "b", bag: [] });
+// One path is all there is, every time.
+assert.strictEqual(S.draw(["a"], [], "a").pick, "a");
+// Nothing listed, nothing picked.
+assert.deepStrictEqual(S.draw([], [], "a"), { pick: "", bag: [] });
+
+console.log("test_shuffle OK");