fix: prevent wallpaper clustering with 16-entry recency buffer (#1606)

## Problem

Custom sleep wallpapers feel repetitive — the same image appearing
multiple times in a short session. Only the single most-recently-shown
index was stored (`uint8_t lastSleepImage`), so on collections of 3–5
images, two-pick cycles were common. On larger collections, any image
could reappear within the next few picks.

## Solution

Add a 16-entry circular recency buffer to `CrossPointState` that
excludes recently shown wallpapers from selection.

**Recency buffer** (`recentSleepImages[16]`, `recentSleepPos`,
`recentSleepFill` — 34 bytes DRAM):
- Tracks the last 16 shown wallpaper indices
- On each pick, rerolls up to 20 times if the candidate was recently
shown
- Window auto-shrinks to `numFiles - 1` for small collections
(guarantees a non-repeat is always possible)
- `isRecentSleep()` clamps to `recentSleepFill` to avoid false positives
on unwritten buffer slots
- State persisted to `state.json` so the buffer survives sleep/wake
cycles

**Migration**:
- Binary (`state.bin`): old `lastSleepImage` field seeded into the new
buffer if valid
- JSON (`state.json`): legacy `lastSleepImage` key detected and seeded
into the buffer when upgrading from older firmware

## Index type fix

`randomFileIndex` upgraded from `uint8_t` to `uint16_t` — silently
truncated for collections larger than 255 wallpapers.

## Repeat probability: before vs after

Chance of seeing a recently-shown image on the next pick. After:
`(numFiles - 16) / numFiles` once collection exceeds the window; 0%
while ≤17.

| Collection | Before | After |
|---|---|---|
| 3 | 50% | 0% |
| 5 | 75% | 0% |
| 10 | 89% | 0% |
| 17 | 94% | 0% |
| 18 | 94% | 6% |
| 20 | 95% | 20% |
| 25 | 96% | 36% |
| 30 | 97% | 47% |
| 50 | 98% | 68% |
| 100 | 99% | 84% |

## Memory impact

| Addition | Size |
|---|---|
| `recentSleepImages[16]` | 32 bytes DRAM |
| `recentSleepPos` + `recentSleepFill` | 2 bytes DRAM |
| **Total** | **34 bytes DRAM** |

## Files changed

- `src/CrossPointState.h` — recency buffer fields + `isRecentSleep()` /
`pushRecentSleep()` declarations
- `src/CrossPointState.cpp` — `isRecentSleep()` / `pushRecentSleep()`
implementations + binary migration path
- `src/JsonSettingsIO.cpp` — JSON serialisation of buffer state + JSON
migration
- `src/activities/boot_sleep/SleepActivity.cpp` — retry loop with
recency check

Co-authored-by: Patryk Radtke <patryk@Patryks-MacBook-Pro.local>

src/CrossPointState.cpp

@@ -5,6 +5,8 @@
 #include <Logging.h>
 #include <Serialization.h>
 
+#include <algorithm>
+
 namespace {
 constexpr uint8_t STATE_FILE_VERSION = 4;
 constexpr char STATE_FILE_BIN[] = "/.crosspoint/state.bin";
@@ -14,6 +16,21 @@ constexpr char STATE_FILE_BAK[] = "/.crosspoint/state.bin.bak";
 
 CrossPointState CrossPointState::instance;
 
+bool CrossPointState::isRecentSleep(uint16_t idx, uint8_t checkCount) const {
+  const uint8_t effectiveCount = std::min(checkCount, recentSleepFill);
+  for (uint8_t i = 0; i < effectiveCount; i++) {
+    const uint8_t slot = (recentSleepPos + SLEEP_RECENT_COUNT - 1 - i) % SLEEP_RECENT_COUNT;
+    if (recentSleepImages[slot] == idx) return true;
+  }
+  return false;
+}
+
+void CrossPointState::pushRecentSleep(uint16_t idx) {
+  recentSleepImages[recentSleepPos] = idx;
+  recentSleepPos = (recentSleepPos + 1) % SLEEP_RECENT_COUNT;
+  if (recentSleepFill < SLEEP_RECENT_COUNT) recentSleepFill++;
+}
+
 bool CrossPointState::saveToFile() const {
   Storage.mkdir("/.crosspoint");
   return JsonSettingsIO::saveState(*this, STATE_FILE_JSON);
@@ -60,9 +77,11 @@ bool CrossPointState::loadFromBinaryFile() {
 
   serialization::readString(inputFile, openEpubPath);
   if (version >= 2) {
-    serialization::readPod(inputFile, lastSleepImage);
-  } else {
-    lastSleepImage = UINT8_MAX;
+    uint8_t legacyLastSleep = UINT8_MAX;
+    serialization::readPod(inputFile, legacyLastSleep);
+    if (legacyLastSleep != UINT8_MAX) {
+      pushRecentSleep(static_cast<uint16_t>(legacyLastSleep));
+    }
   }
 
   if (version >= 3) {

src/CrossPointState.h

@@ -1,6 +1,5 @@
 #pragma once
 #include <cstdint>
-#include <iosfwd>
 #include <string>
 
 class CrossPointState {
@@ -8,10 +7,20 @@ class CrossPointState {
   static CrossPointState instance;
 
  public:
+  static constexpr uint8_t SLEEP_RECENT_COUNT = 16;
+
   std::string openEpubPath;
-  uint8_t lastSleepImage = UINT8_MAX;  // UINT8_MAX = unset sentinel
+  uint16_t recentSleepImages[SLEEP_RECENT_COUNT] = {};  // circular buffer of recent wallpaper indices
+  uint8_t recentSleepPos = 0;                           // next write slot
+  uint8_t recentSleepFill = 0;                          // valid entries (0..SLEEP_RECENT_COUNT)
   uint8_t readerActivityLoadCount = 0;
   bool lastSleepFromReader = false;
+
+  // Returns true if idx was shown within the last checkCount picks.
+  // Walks backwards from the most recently written slot.
+  bool isRecentSleep(uint16_t idx, uint8_t checkCount) const;
+
+  void pushRecentSleep(uint16_t idx);
   ~CrossPointState() = default;
 
   // Get singleton instance

src/JsonSettingsIO.cpp

@@ -69,7 +69,10 @@ void applyLegacyStatusBarSettings(CrossPointSettings& settings) {
 bool JsonSettingsIO::saveState(const CrossPointState& s, const char* path) {
   JsonDocument doc;
   doc["openEpubPath"] = s.openEpubPath;
-  doc["lastSleepImage"] = s.lastSleepImage;
+  JsonArray recentArr = doc["recentSleepImages"].to<JsonArray>();
+  for (int i = 0; i < CrossPointState::SLEEP_RECENT_COUNT; i++) recentArr.add(s.recentSleepImages[i]);
+  doc["recentSleepPos"] = s.recentSleepPos;
+  doc["recentSleepFill"] = s.recentSleepFill;
   doc["readerActivityLoadCount"] = s.readerActivityLoadCount;
   doc["lastSleepFromReader"] = s.lastSleepFromReader;
 
@@ -87,8 +90,24 @@ bool JsonSettingsIO::loadState(CrossPointState& s, const char* json) {
   }
 
   s.openEpubPath = doc["openEpubPath"] | std::string("");
-  s.lastSleepImage = doc["lastSleepImage"] | (uint8_t)UINT8_MAX;
-  s.readerActivityLoadCount = doc["readerActivityLoadCount"] | (uint8_t)0;
+  memset(s.recentSleepImages, 0, sizeof(s.recentSleepImages));
+  JsonArrayConst recentArr = doc["recentSleepImages"];
+  const int actualCount = recentArr.isNull() ? 0
+                                             : std::min(static_cast<int>(recentArr.size()),
+                                                        static_cast<int>(CrossPointState::SLEEP_RECENT_COUNT));
+  for (int i = 0; i < actualCount; i++) s.recentSleepImages[i] = recentArr[i] | static_cast<uint16_t>(0);
+  s.recentSleepPos = doc["recentSleepPos"] | static_cast<uint8_t>(0);
+  if (s.recentSleepPos >= CrossPointState::SLEEP_RECENT_COUNT)
+    s.recentSleepPos = actualCount > 0 ? s.recentSleepPos % CrossPointState::SLEEP_RECENT_COUNT : 0;
+  s.recentSleepFill = doc["recentSleepFill"] | static_cast<uint8_t>(0);
+  s.recentSleepFill = static_cast<uint8_t>(std::min(static_cast<int>(s.recentSleepFill), actualCount));
+  // Migrate legacy single-image field from old state.json (pre-recency-buffer).
+  // Only seeds the buffer if the new buffer is empty (fresh migration, not a resave).
+  if (s.recentSleepFill == 0 && !doc["lastSleepImage"].isNull()) {
+    const uint8_t legacy = doc["lastSleepImage"] | static_cast<uint8_t>(UINT8_MAX);
+    if (legacy != UINT8_MAX) s.pushRecentSleep(static_cast<uint16_t>(legacy));
+  }
+  s.readerActivityLoadCount = doc["readerActivityLoadCount"] | static_cast<uint8_t>(0);
   s.lastSleepFromReader = doc["lastSleepFromReader"] | false;
   return true;
 }

src/activities/boot_sleep/SleepActivity.cpp

@@ -85,13 +85,16 @@ void SleepActivity::renderCustomSleepScreen() const {
     }
     const auto numFiles = files.size();
     if (numFiles > 0) {
-      // Generate a random number between 1 and numFiles
-      auto randomFileIndex = random(numFiles);
-      // If we picked the same image as last time, reroll
-      while (numFiles > 1 && APP_STATE.lastSleepImage != UINT8_MAX && randomFileIndex == APP_STATE.lastSleepImage) {
-        randomFileIndex = random(numFiles);
+      // Pick a random wallpaper, excluding recently shown ones.
+      // Window: up to SLEEP_RECENT_COUNT entries, capped at numFiles-1.
+      const uint16_t fileCount = static_cast<uint16_t>(std::min(numFiles, static_cast<size_t>(UINT16_MAX)));
+      const uint8_t window =
+          static_cast<uint8_t>(std::min(static_cast<size_t>(APP_STATE.recentSleepFill), numFiles - 1));
+      auto randomFileIndex = static_cast<uint16_t>(random(fileCount));
+      for (uint8_t attempt = 0; attempt < 20 && APP_STATE.isRecentSleep(randomFileIndex, window); attempt++) {
+        randomFileIndex = static_cast<uint16_t>(random(fileCount));
       }
-      APP_STATE.lastSleepImage = randomFileIndex;
+      APP_STATE.pushRecentSleep(randomFileIndex);
       APP_STATE.saveToFile();
       const auto filename = std::string(sleepDir) + "/" + files[randomFileIndex];
       FsFile file;