onlyn00bs-badge

main.cpp (86698B)

---

 // ─────────────────────────────────────────────────────────────────────────
 //  DefCon friend-finder badge — firmware core
 //
 //  Modes, chosen at boot. The radio is never shared:
 //
 //    BOOT ─┬─ (no handle stored) OR (BOOT button held) ─► PROVISIONING (BLE)
 //          │        phone writes handle + clock → NVS → reboot
 //          └─ (handle stored) ───────────────────────────► DISCOVERY (ESP-NOW)
 //                   TX signed beacon ~1Hz; RX verify → peer table → display
 //                   peers leaving range → encounter log (LittleFS)
 //                   +1 point per minute while ≥1 crew is in range (→ NVS),
 //                   ×2 with crew around / ×3 in a group of 5+ (the group
 //                   multiplier — POINTS_X2/X3_PEERS), credited to every
 //                   in-gate companion (the points ledger)
 //                   hold BUTTON ≥REPORT_HOLD_MS → cycle view:
 //                        FINDER → REPORT → POINTS → FRIENDS → BATTERY → FINDER
 // ─────────────────────────────────────────────────────────────────────────
 
 #include <Arduino.h>
 #include <time.h>            // localtime_r / tzset — render the soft-clock epoch in DISPLAY_TZ
 #include <Preferences.h>
 #include <WiFi.h>
 #include <esp_now.h>
 #include <esp_wifi.h>
 #include <esp_mac.h>
 #include <esp_system.h>
 #include <esp_sleep.h>       // ext0 wake + deep sleep entry (OPTIONS → Power → Deep sleep)
 #include <NimBLEDevice.h>
 
 #include "config.h"
 #include "beacon.h"
 #include "clock.h"
 #include "encounters.h"
 #include "peers.h"
 #include "points.h"
 #include "points_history.h"
 #include "battery.h"
 #include "display.h"
 #include "pet.h"
 #include "test_log.h"
 
 enum Mode { MODE_PROVISION, MODE_DISCOVER };
 static Mode mode;
 
 // In discovery mode the BUTTON cycles through these views (REPORT is a static
 // snapshot; HOME, FINDER and POINTS are live and redraw on every display tick).
 // HOME is the at-a-glance default/initial view; it leads the ring.
 enum View { VIEW_HOME = 0, VIEW_FINDER, VIEW_REPORT, VIEW_POINTS, VIEW_FRIENDS, VIEW_BATTERY,
             VIEW_OPTIONS, VIEW_COUNT };
 static View g_view = VIEW_HOME;
 // FINDER right column: false = peer pet face, true = dBm. Set via User Settings →
 // "Finder View" (persisted to NVS, key "finder"); the FINDER header no longer labels it.
 static bool g_finder_rssi = false;
 // FINDER paging: the list shows FINDER_PAGE_ROWS closest peers per screen; a single tap
 // pages down (wrapping). g_finder_pages caches the last render's page total so the tap
 // handler can wrap without re-locking the peer table.
 static int g_finder_page  = 0;
 static int g_finder_pages = 1;
 static int finder_pages(int n) {              // total finder pages for n peers (≥1)
   int p = (n + FINDER_PAGE_ROWS - 1) / FINDER_PAGE_ROWS;
   return p < 1 ? 1 : p;
 }
 
 // OPTIONS is a nested menu: the ROOT list (Back · User Settings · Badge Settings), the
 // two settings sub-menus, their sub-sub-menus (Display / Developer Options / Power under
 // Badge, Reminders under User), or a child value-picker (pet, reached from User; splash,
 // from Display). Every screen stays <= 5 rows, which is the renderer's row array and
 // y0/dy layout ladder budget. BADGE sits exactly ON that cap — "Power" replaced "Reboot"
 // there rather than adding a row, which is why the reboot action moved down a level.
 enum OptScreen { OPT_MENU = 0, OPT_USER, OPT_BADGE, OPT_DISPLAY, OPT_DEVOPTS,
                  OPT_PET, OPT_SPLASH, OPT_WHOAMI, OPT_REMIND, OPT_RESET, OPT_POWER };
 static OptScreen g_opt_screen = OPT_MENU;
 static int       g_opt_cursor = 0;        // current menu row; 0=Back leads so it's the
                                           //   DEFAULT row (double-tap in, double-tap back
                                           //   out). Reset to 0 entering a sub-menu; restored
                                           //   to the sub-menu's row when backing out to ROOT.
 // POINTS graph window, cycled by a single tap on the POINTS view.
 enum PointsWin { PWIN_5DAY = 0, PWIN_24H, PWIN_1H, PWIN_COUNT };
 static PointsWin g_points_window = PWIN_5DAY;
 
 // Settings + companion state (NVS-backed: keys "splash", "pet", "bright").
 static uint8_t  g_splash_style    = BOOT_SPLASH_STYLE;  // active boot splash (0..BOOT_SPLASH_COUNT-1)
 static uint8_t  g_bright          = SCREEN_BRIGHT_DEFAULT;  // screen brightness (0=LOW..2=HIGH)
 static int      g_pet_idx         = 0;                  // active pet (0..PET_BUILTIN_N-1)
 static PetState g_pet_react       = PET_IDLE;           // transient reaction (PET_IDLE = none)
 static uint32_t g_pet_react_until = 0;
 static uint32_t g_pet_popup_until = 0;                  // cooldown gate for reaction pop-ups
 static Pet      g_custom_pet      = {};                 // uploaded custom pet (slot PET_BUILTIN_N)
 static bool     g_custom_valid    = false;              // is a custom pet stored in NVS?
 static const Pet* current_pet();                        // fwd decl (send_beacon needs it)
 
 // Reminders (User Settings → Reminders; NVS keys "rmglob"/"rmshow"). "Global" is the
 // master switch for all reminders; "Shower" gates the shower reminder specifically.
 // Both default ON — toggling a switch OFF disables it. The alert is a NON-BLOCKING
 // toast (g_toast_active): shown by the loop, dismissed by any button press or after
 // REMINDER_TOAST_MS, so the badge keeps beaconing/scoring while it's up.
 static bool     g_remind_global   = true;
 static bool     g_remind_shower   = true;
 static bool     g_toast_active    = false;              // a reminder toast is on screen
 static uint32_t g_toast_until     = 0;                  // auto-dismiss deadline (millis)
 
 // Broadcast switch, surfaced as Badge Settings → STEALTH. Note the polarity: this holds
 // the RADIO state, and stealth is its inverse (stealth ON = g_radio_on false). The name
 // stays radio-side because that's what the code actually gates; the inversion happens once,
 // where OptView is built. NVS key "radio", default ON (= not stealthed).
 // Off gates send_beacon() and nothing else: the badge stops broadcasting — nobody can see
 // it — but the ESP-NOW stack stays up, so RX, the peer table, FINDER and scoring all keep
 // working. See the Radio/discovery block in config.h for why it's TX-only, not a teardown.
 static bool     g_radio_on        = true;
 
 static Preferences prefs;
 static SoftClock   g_clock;
 static char        g_handle[HANDLE_MAX_LEN + 1] = {0};
 static uint32_t    g_counter = 0;
 
 // Points: +1 per full minute spent with ≥1 crew badge in range. We tally the
 // proximity time in seconds (g_prox_seconds, persisted to NVS) and carry the
 // sub-second remainder between ticks (g_prox_accum_ms). points = seconds / 60.
 // Each earned second is also credited to EVERY in-gate friend in g_ledger,
 // which backs the "Best Friends" view: a friend's seconds = how many of your
 // social minutes they shared (so each ≤ the tally, but they overlap and don't
 // sum to it — being near three friends at once is one shared minute, not three).
 static uint32_t      g_prox_seconds  = 0;
 static uint32_t      g_prox_accum_ms = 0;
 static PointsLedger  g_ledger;
 static PointsHistory g_points_history;   // rolling score samples for the POINTS graph (hourly, 5-day)
 static PointsRecent  g_points_recent;    // fine 1-min ring for the 1-hour POINTS view (in-RAM)
 
 // Peer table is touched by both the ESP-NOW RX callback and loop() → guard it.
 static PeerTable peers;
 static portMUX_TYPE peerMux = portMUX_INITIALIZER_UNLOCKED;
 
 // ─── Test mode (OPTIONS → Test): LittleFS CSV logs + boot MAC / serial dump ──
 static bool     g_test_mode = false;
 static uint32_t g_boot_id   = 0;        // ++ each time test mode goes active; tags every log line
 static TestLog  g_batt_log("/test_batt.csv", "boot,elapsed_ms,vbat_mv,soc_pct");
 static TestLog  g_pts_log ("/test_pts.csv",  "boot,elapsed_ms,points,prox_s,peers,mult");
 
 static const uint8_t BCAST[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
 
 // Session set of badge MACs we've already greeted, so the "new crew!" pet
 // reaction fires exactly once per device — not on every TTL re-entry, the way
 // the old snapshot-diff did. MAC (not handle) is the identity: it's the stable
 // hardware address and is available on both Arduino cores (handles can change or
 // collide). RAM-only by design — a reboot re-greets your crew. Bounded ring:
 // past CONTACT_SEEN_MAX distinct devices the oldest is evicted, so a long-gone
 // badge may re-greet once (fine for a cosmetic pop-up). Single-writer (the recv
 // callback is serialized on the WiFi task), so the set itself needs no lock; the
 // main loop only reads/clears the volatile flag.
 static constexpr int CONTACT_SEEN_MAX = 256;
 static uint8_t       g_seen_macs[CONTACT_SEEN_MAX][6];
 static int           g_seen_n    = 0;            // entries in use (0..MAX)
 static int           g_seen_head = 0;            // ring evict point once full
 static volatile bool g_new_contact = false;      // a never-seen MAC just arrived
 static char g_contact_handle[HANDLE_MAX_LEN + 1] = {0};  // its handle, for the contact toast
 
 // First-sighting test for a source MAC: returns true (and records it) only the
 // first time this MAC is seen this session. Called from the recv callback only.
 static bool note_contact_mac(const uint8_t* mac) {
   if (!mac) return false;
   for (int i = 0; i < g_seen_n; i++)
     if (memcmp(g_seen_macs[i], mac, 6) == 0) return false;   // already greeted
   if (g_seen_n < CONTACT_SEEN_MAX) {
     memcpy(g_seen_macs[g_seen_n++], mac, 6);
   } else {
     memcpy(g_seen_macs[g_seen_head], mac, 6);                // evict oldest
     g_seen_head = (g_seen_head + 1) % CONTACT_SEEN_MAX;
   }
   return true;
 }
 
 // ─── shared helpers ────────────────────────────────────────────────────────
 
 // Clamp untrusted input to printable ASCII, max HANDLE_MAX_LEN bytes.
 static uint8_t sanitize_handle(const uint8_t* in, size_t n, char* out) {
   uint8_t k = 0;
   for (size_t i = 0; i < n && k < HANDLE_MAX_LEN; i++) {
     uint8_t c = in[i];
     // drop control/non-ASCII AND comma: a comma would break the CSV metrics export
     // (best_friends.csv, and the encounters TSV the web comma-izes on receipt).
     if (c >= 0x20 && c <= 0x7E && c != ',') out[k++] = (char)c;
   }
   out[k] = '\0';
   return k;
 }
 
 // ─── PROVISIONING MODE (BLE GATT) ───────────────────────────────────────────
 
 static volatile bool g_saved = false;
 
 // Pairing code: a fresh 3-char code is shown on the badge each provisioning session;
 // the web app must write it (PROV_CODE_CHAR_UUID) before any handle/time/pet write is
 // honored — a physical-presence gate against drive-by BLE provisioning. NOT crypto (BLE
 // writes are cleartext); it just requires line-of-sight to the badge screen.
 static char          g_prov_code[4] = {0};
 static volatile bool g_prov_authed  = false;
 static char          g_prov_name[32] = {0};   // advertised name; kept for setup-screen redraws
 
 // Pairing-code attempt limiting (see PROV_CODE_MAX_TRIES). The tally is per-BOOT, not
 // per-connection: onDisconnect must NOT reset it, or reconnecting resets the limit and
 // the limit means nothing — free reconnects were the actual finding.
 static volatile uint8_t  g_prov_fails        = 0;
 static volatile bool     g_prov_locked       = false;  // latched; only a reboot clears it
 static volatile bool     g_prov_lock_pending = false;  // loop(): rotate, redraw, drop the peer
 static volatile uint16_t g_prov_conn         = 0;      // conn handle of the last code writer
 
 // Metrics export (BLE, provisioning mode): the reserved metrics char streams a framed CSV/TSV
 // dump to the web app once the pairing code is accepted. The client subscribes → onSubscribe
 // flags a request; the actual streaming runs in loop() (never in a BLE callback), then the
 // badge reboots to discovery. g_metrics_ch = the char (for notify); g_metrics_conn = the peer
 // (for the MTU query that sizes the chunks).
 static NimBLECharacteristic* g_metrics_ch       = nullptr;
 static volatile uint16_t     g_metrics_conn     = 0;
 static volatile bool         g_metrics_req      = false;   // subscribed → stream once authed
 static bool                  g_metrics_done      = false;  // stream sent → reboot to discovery
 static uint32_t              g_metrics_reboot_at = 0;
 
 // Unambiguous uppercase alphabet (no 0/O/1/I/L) — easy to read off-screen + retype.
 static void gen_prov_code(char out[4]) {
   static const char A[] = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";   // 30 glyphs
   for (int i = 0; i < 3; i++) out[i] = A[esp_random() % (sizeof(A) - 1)];
   out[3] = '\0';
 }
 
 class HandleWriteCB : public NimBLECharacteristicCallbacks {
   void onWrite(NimBLECharacteristic* c, NimBLEConnInfo&) override {
     if (!g_prov_authed) { Serial.println("[PROV] handle write ignored — pairing code not accepted"); return; }
     NimBLEAttValue v = c->getValue();
     char clean[HANDLE_MAX_LEN + 1];
     uint8_t len = sanitize_handle(v.data(), v.length(), clean);
     if (len == 0) return;                       // ignore empty/garbage writes
     prefs.putString("handle", clean);
     Serial.printf("[PROV] stored handle: \"%s\"\n", clean);
     g_saved = true;                             // loop() will reboot us
   }
 };
 
 // Optional: phone writes the current epoch (u32 little-endian) to seed the
 // soft-clock, so the report can show real wall-clock times.
 class TimeWriteCB : public NimBLECharacteristicCallbacks {
   void onWrite(NimBLECharacteristic* c, NimBLEConnInfo&) override {
     if (!g_prov_authed) { Serial.println("[PROV] time write ignored — pairing code not accepted"); return; }
     NimBLEAttValue v = c->getValue();
     if (v.length() < 4) return;
     const uint8_t* d = v.data();
     uint32_t epoch = (uint32_t)d[0] | ((uint32_t)d[1] << 8) |
                      ((uint32_t)d[2] << 16) | ((uint32_t)d[3] << 24);
     g_clock.set(epoch);
     Serial.printf("[PROV] clock synced: %u\n", (unsigned)epoch);
     // If a handle is already stored, this is a re-sync (not first-time setup),
     // so reboot back into home for the corrected clock to take effect. During
     // first-time provisioning the handle isn't stored yet, so this no-ops and we
     // wait for the handle write to trigger the reboot.
     if (prefs.getString("handle", "").length() > 0) g_saved = true;
   }
 };
 
 // Optional: phone uploads a custom pet — a blob of up to 6 newline-separated
 // fields (name, then the 5 state-faces idle/contact/milestone/lonely/lowbatt).
 // Each field is clamped to printable ASCII + its max length, stored to NVS, and
 // auto-selected. If a handle is already stored, reboots into home (re-provision).
 class PetWriteCB : public NimBLECharacteristicCallbacks {
   void onWrite(NimBLECharacteristic* c, NimBLEConnInfo&) override {
     if (!g_prov_authed) { Serial.println("[PROV] pet write ignored — pairing code not accepted"); return; }
     NimBLEAttValue v = c->getValue();
     const char* data = (const char*)v.data();
     size_t len = v.length();
     Pet p;
     memset(&p, 0, sizeof(p));
     int field = 0;
     size_t start = 0;
     for (size_t i = 0; i <= len && field < 1 + PET_STATE_COUNT; i++) {
       if (i == len || data[i] == '\n') {
         uint8_t maxlen = (field == 0) ? PET_NAME_MAX - 1 : PET_FACE_MAX - 1;
         char clean[PET_FACE_MAX];
         uint8_t k = 0;
         for (size_t j = start; j < i && k < maxlen; j++) {
           uint8_t ch = (uint8_t)data[j];
           if (ch >= 0x20 && ch <= 0x7E) clean[k++] = (char)ch;   // printable ASCII only
         }
         clean[k] = '\0';
         if (field == 0) strncpy(p.name, clean, PET_NAME_MAX - 1);
         else            strncpy(p.face[field - 1], clean, PET_FACE_MAX - 1);
         field++;
         start = i + 1;
       }
     }
     if (p.name[0] == '\0') return;                       // need at least a name
     g_custom_pet = p;
     g_custom_valid = true;
     prefs.putBytes("petcust", &g_custom_pet, sizeof(g_custom_pet));
     prefs.putUChar("petc_ok", 1);
     g_pet_idx = PET_BUILTIN_N;                           // auto-select the new custom pet
     prefs.putUInt("pet", g_pet_idx);
     Serial.printf("[PROV] custom pet stored: \"%s\"\n", p.name);
     if (prefs.getString("handle", "").length() > 0) g_saved = true;
   }
 };
 
 // The gate: the web app writes the 3-char code shown on the badge here; only an exact
 // (case-insensitive) match flips g_prov_authed, unlocking the handle/time/pet writes.
 class CodeWriteCB : public NimBLECharacteristicCallbacks {
   void onWrite(NimBLECharacteristic* c, NimBLEConnInfo& info) override {
     // Checked first: once latched, nothing gets compared at all, so a locked badge is
     // also a badge that no longer leaks whether a guess was close.
     if (g_prov_locked) {
       g_prov_authed = false;
       Serial.println("[PROV] code write rejected — gate locked until reboot");
       return;
     }
 
     NimBLEAttValue v = c->getValue();
     char in[4] = {0};
     for (uint8_t i = 0; i < v.length() && i < 3; i++) {
       char ch = (char)v.data()[i];
       in[i] = (ch >= 'a' && ch <= 'z') ? (char)(ch - 32) : ch;   // uppercase
     }
     g_prov_authed = (strcmp(in, g_prov_code) == 0);
     if (g_prov_authed) {
       g_prov_fails = 0;                       // a good code clears the tally
       Serial.printf("[PROV] pairing code \"%s\" -> ACCEPTED\n", in);
       return;
     }
 
     if (g_prov_fails < 255) g_prov_fails++;
     Serial.printf("[PROV] pairing code \"%s\" -> REJECTED (%u/%u)\n",
                   in, (unsigned)g_prov_fails, (unsigned)PROV_CODE_MAX_TRIES);
     if (g_prov_fails >= PROV_CODE_MAX_TRIES) {
       g_prov_locked       = true;             // latch immediately — before loop() gets a turn
       g_prov_conn         = info.getConnHandle();
       g_prov_lock_pending = true;             // loop() rotates the code, redraws, and disconnects
     }
   }
 };
 
 // Metrics stream: the web app subscribes to notifications (after entering the pairing code)
 // to pull the framed dump. We only flag the request here; loop() does the streaming, gated on
 // g_prov_authed, so this BLE-stack callback stays fast (no long work in the callback).
 class MetricsReadCB : public NimBLECharacteristicCallbacks {
   void onSubscribe(NimBLECharacteristic*, NimBLEConnInfo& info, uint16_t subValue) override {
     if (subValue == 0) return;                  // client unsubscribed
     g_metrics_conn = info.getConnHandle();      // for the MTU query
     g_metrics_req  = true;                       // loop() streams once the code is accepted
     Serial.println("[METRICS] client subscribed — will stream after the pairing code");
   }
 };
 
 class ServerCB : public NimBLEServerCallbacks {
   void onDisconnect(NimBLEServer*, NimBLEConnInfo&, int) override {
     g_prov_authed = false;                      // each new connection must re-send the code
     g_metrics_req = false;                       // cancel any pending (unauthed) stream request
     // NOTE: g_prov_fails is deliberately NOT reset here. Advertising restarts below, so a
     // reconnect is free — if the tally reset with it, the attempt limit would be worthless.
     NimBLEDevice::startAdvertising();           // allow repeated attempts
   }
 };
 
 static void start_provisioning() {
   // Per-badge advertised name: base + the FULL 6-byte eFuse MAC (e.g.
   // "badge-setup-14335C591858"), so badges in pairing mode are uniquely identifiable in
   // the browser device picker AND map 1:1 to the bench roster (which dedups by full MAC).
   // 24 chars fits the 31B BLE scan-response budget; the OLED setup screen renders it in a
   // 5px font so the whole name fits one line.
   uint8_t mac[6];
   esp_read_mac(mac, ESP_MAC_WIFI_STA);
   // File-static, not a local: prov_escape_tick() redraws this screen when an aborted
   // hold-to-exit has to put the setup screen back.
   snprintf(g_prov_name, sizeof(g_prov_name), "%s-%02X%02X%02X%02X%02X%02X",
            PROV_DEVICE_NAME, mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
   const char* prov_name = g_prov_name;
 
   gen_prov_code(g_prov_code);                  // fresh pairing code per session
   g_prov_authed = false;
   display_provisioning(prov_name, g_prov_code);
 
   NimBLEDevice::init(prov_name);
   NimBLEServer* server = NimBLEDevice::createServer();
   server->setCallbacks(new ServerCB());
 
   NimBLEService* svc = server->createService(PROV_SERVICE_UUID);
 
   NimBLECharacteristic* hch =
       svc->createCharacteristic(PROV_CHAR_UUID, NIMBLE_PROPERTY::WRITE);
   hch->setCallbacks(new HandleWriteCB());
 
   NimBLECharacteristic* tch =
       svc->createCharacteristic(PROV_TIME_CHAR_UUID, NIMBLE_PROPERTY::WRITE);
   tch->setCallbacks(new TimeWriteCB());
 
   NimBLECharacteristic* pch =
       svc->createCharacteristic(PROV_PET_CHAR_UUID, NIMBLE_PROPERTY::WRITE);
   pch->setCallbacks(new PetWriteCB());
 
   NimBLECharacteristic* cch =                  // pairing-code gate (write before the others)
       svc->createCharacteristic(PROV_CODE_CHAR_UUID, NIMBLE_PROPERTY::WRITE);
   cch->setCallbacks(new CodeWriteCB());
 
   // Metrics characteristic (READ|NOTIFY): streams a framed CSV/TSV dump — encounters.log +
   // points history, plus the Test-Mode CSVs when Debug is on — to the provisioning web app,
   // gated by the pairing code. Chunked to the negotiated MTU; the page reassembles the notify
   // chunks until the "==== EOF ====" sentinel. Streaming happens in loop() (see stream_metrics).
   NimBLECharacteristic* mch =
       svc->createCharacteristic(PROV_METRICS_CHAR_UUID,
                                 NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::NOTIFY);
   mch->setCallbacks(new MetricsReadCB());
   mch->setValue("subscribe (notify) after the pairing code to pull metrics");
   g_metrics_ch = mch;
 
   svc->start();
 
   // The 128-bit service UUID (18B) + flags (3B) fill 21B of the 31B legacy adv packet,
   // so the name can't also live there. Build BOTH packets EXPLICITLY rather than rely on
   // auto-routing: the previous `setName()` shortened a 24-char name down to "badge-setup"
   // (31B − the 18B UUID = a 13B slot → an 11-char *Shortened Local Name*). Here the scan
   // response carries the full name ALONE (its own 31B), so the complete name survives.
   NimBLEAdvertising* adv = NimBLEDevice::getAdvertising();
 
   NimBLEAdvertisementData advData;                                   // PRIMARY: flags + service filter
   advData.setFlags(BLE_HS_ADV_F_DISC_GEN | BLE_HS_ADV_F_BREDR_UNSUP);
   advData.addServiceUUID(PROV_SERVICE_UUID);
   adv->setAdvertisementData(advData);
 
   NimBLEAdvertisementData scanData;                                  // SCAN RESPONSE: full name, alone
   scanData.setName(prov_name);
   adv->setScanResponseData(scanData);
 
   adv->enableScanResponse(true);
   adv->start();
 }
 
 // ─── DISCOVERY MODE (ESP-NOW) ───────────────────────────────────────────────
 
 // The ESP-NOW receive callback signature changed between Arduino-ESP32 cores:
 //   core 3.x (IDF 5.x): (const esp_now_recv_info_t*, ...) — exposes RSSI
 //   core 2.x (IDF 4.x): (const uint8_t* mac,         ...) — no RSSI
 // Support both: compiles on the stock toolchain today, and gains proximity
 // sorting for free on core 3.x (pioarduino platform — see platformio.ini).
 #if ESP_ARDUINO_VERSION_MAJOR >= 3
 static void on_espnow_recv(const esp_now_recv_info_t* info,
                            const uint8_t* data, int len) {
   int8_t rssi = (info && info->rx_ctrl) ? info->rx_ctrl->rssi : 0;
   const uint8_t* src = info ? info->src_addr : nullptr;
 #else
 static void on_espnow_recv(const uint8_t* mac,
                            const uint8_t* data, int len) {
   int8_t rssi = 0;   // RSSI not exposed by the core 2.x ESP-NOW callback
   const uint8_t* src = mac;
 #endif
   // Verify (HMAC) OUTSIDE the lock — never run crypto in a critical section.
   if (!beacon_verify((const Beacon*)data, (size_t)len)) return;
   const Beacon* b = (const Beacon*)data;
   uint32_t epoch = g_clock.now();
 
   portENTER_CRITICAL(&peerMux);
   peers.upsert(b->handle, b->handle_len, rssi, b->counter, millis(), epoch,
                b->pet, b->pet_face);
   portEXIT_CRITICAL(&peerMux);
 
   // MAC dedup is independent of the peer table, so keep it out of the lock: fire
   // the contact flag once, the first time this device's MAC is heard.
   if (note_contact_mac(src)) {                   // first time this MAC is heard
     uint8_t hl = b->handle_len <= HANDLE_MAX_LEN ? b->handle_len : HANDLE_MAX_LEN;
     memcpy(g_contact_handle, b->handle, hl);
     g_contact_handle[hl] = '\0';                 // name the peer in the contact toast
     g_new_contact = true;
   }
 }
 
 static void send_beacon() {
   Beacon b;
   memset(&b, 0, sizeof(b));                      // zero-pad handle for the MAC
   b.magic   = BEACON_MAGIC;
   b.version = BEACON_VERSION;
   b.counter = ++g_counter;
   size_t hl = strlen(g_handle);
   if (hl > HANDLE_MAX_LEN) hl = HANDLE_MAX_LEN;
   b.handle_len = (uint8_t)hl;
   memcpy(b.handle, g_handle, hl);
   b.pet = (uint8_t)g_pet_idx;                          // our selected pet …
   strncpy(b.pet_face, current_pet()->face[PET_IDLE], PET_FACE_MAX);  // … + its idle face (zero-padded)
   beacon_sign(&b);
   esp_now_send(BCAST, (const uint8_t*)&b, sizeof(b));
 }
 
 static void start_discovery() {
   enc_begin();   // mount LittleFS for the encounter log
 
   // Persisted counter jumps forward each boot so old captured beacons (with
   // lower counters) can't be replayed as "fresher" after a power cycle.
   g_counter = prefs.getUInt("ctr", 0) + 1000;
   prefs.putUInt("ctr", g_counter);
 
   // Resume the points tally + per-friend ledger — a power cycle mid-con must
   // not zero your score or your best-friends ranking.
   g_prox_seconds = prefs.getUInt("prox", 0);
   g_ledger.load(prefs);
   g_points_history.load(prefs);   // restore the graph; arms a reboot break
 
   WiFi.mode(WIFI_STA);
   WiFi.disconnect();
   esp_wifi_set_channel(ESPNOW_CHANNEL, WIFI_SECOND_CHAN_NONE);
   // NB: the ESP32's DEFAULT max TX (~19.5 dBm) is already its effective ceiling here. Calling
   // esp_wifi_set_max_tx_power(80 or 84) paradoxically *lowered* it to 17.5 dBm on this chip
   // (rc=ESP_OK, but the read-back regressed — an ESP-IDF quirk), so we deliberately DON'T set
   // it; we just read + log. The real range lever is antenna keepout, not these tenths of a dB.
   int8_t txp = 0; esp_wifi_get_max_tx_power(&txp);
   Serial.printf("[DISC] TX power: %.2f dBm\n", txp * 0.25f);
 
   if (esp_now_init() != ESP_OK) {
     display_boot("ESP-NOW init FAILED");
     return;
   }
   esp_now_register_recv_cb(on_espnow_recv);
 
   esp_now_peer_info_t p = {};
   memcpy(p.peer_addr, BCAST, 6);
   p.channel = ESPNOW_CHANNEL;
   p.ifidx   = WIFI_IF_STA;
   p.encrypt = false;
   esp_now_add_peer(&p);
 
   Serial.printf("[DISC] %s as \"%s\" on ch %d\n",
                 g_radio_on ? "beaconing" : "listening only (STEALTH on)",
                 g_handle, ESPNOW_CHANNEL);
 }
 
 // Finalize in-range encounters, aggregate the log, and render the report.
 static void enter_report() {
   // static scratch: this path nests loop()→enter_report→enc_append→vfprintf, and ev[32] (~1.1KB)
   // + Report r (~1.9KB) on the stack tripped the loopTask stack canary (a reboot on FINDER→REPORT).
   // Single-task, non-reentrant, refilled every call (ev by flush, r by enc_report's memset), so
   // static is safe and moves ~3KB off the stack.
   static Encounter ev[MAX_PEERS];
   int en = 0;
   portENTER_CRITICAL(&peerMux);
   peers.flush(ev, en, MAX_PEERS);
   portEXIT_CRITICAL(&peerMux);
   for (int i = 0; i < en; i++) enc_append(ev[i]);   // file IO outside the lock
 
   static Report r;
   enc_report(&r, g_clock.synced());
   display_report(g_handle, r);
 }
 
 // True when ≥1 crew is in range AND the closest clears the RSSI gate. The peer
 // snapshot is sorted closest-first, so snap[0] carries the strongest signal.
 //
 // STEALTH also stops scoring. Points are meant to measure time spent WITH crew, and
 // while stealthed the exchange is one-way: they can't see us, so they aren't being
 // credited for us either. Earning off badges that can't earn off you back is a leech.
 // Gating it here rather than at the accrual site is deliberate — the POINTS view reads
 // the same predicate, so the tally and the on-screen "earning/paused" state can't drift.
 static bool points_earning(const Peer* snap, int n) {
   return g_radio_on && n > 0 && snap[0].rssi >= POINTS_MIN_RSSI;
 }
 
 // Group multiplier from the in-range crew count (the peer table — anyone on the
 // FINDER list counts, gated or not; the RSSI gate still decides WHETHER you
 // earn). A 1-on-1 earns at base ×1; ×2 needs POINTS_X2_PEERS+ crew in range, ×3
 // needs POINTS_X3_PEERS+. Each earned second is scaled by this before tally + ledger.
 static uint8_t points_multiplier(int n) {
   if (n >= POINTS_X3_PEERS) return 3;
   if (n >= POINTS_X2_PEERS) return 2;
   return 1;
 }
 
 // Render the points scoreboard for the current tally + in-range crew count.
 static void render_points() {
   Peer snap[MAX_PEERS];
   int n;
   portENTER_CRITICAL(&peerMux);
   n = peers.snapshot(snap, MAX_PEERS);
   portEXIT_CRITICAL(&peerMux);
   static PointSample hist[POINTS_HISTORY_LEN];   // static: keep ~960B off the loop-task
   int hn;                                         //   stack (POINTS-only; render runs single-threaded)
   uint32_t span;
   const char* label;
   if (g_points_window == PWIN_1H) {
     hn = g_points_recent.snapshot(hist, POINTS_HISTORY_LEN);   // fine 1-min ring
     span = POINTS_GRAPH_1H_SPAN_S; label = "1h";
   } else if (g_points_window == PWIN_24H) {
     hn = g_points_history.snapshot(hist, POINTS_HISTORY_LEN);
     span = POINTS_GRAPH_24H_SPAN_S; label = "24h";
   } else {
     hn = g_points_history.snapshot(hist, POINTS_HISTORY_LEN);
     span = POINTS_GRAPH_SPAN_S; label = "5d";
   }
   display_points(g_handle, g_prox_seconds / 60, g_prox_seconds, n,
                  points_earning(snap, n), hist, hn, span, label,
                  g_points_window != PWIN_5DAY, points_multiplier(n), !g_radio_on);
 }
 
 // Render the best-friends scoreboard from the points ledger (top contributors).
 static void render_friends() {
   PointFriend top[MAX_POINT_FRIENDS];
   int n = g_ledger.top(top, MAX_POINT_FRIENDS);
   display_friends(g_handle, top, n, g_prox_seconds / 60);
 }
 
 // ─── disk usage cache ────────────────────────────────────────────────────────
 // LittleFS.usedBytes() walks the filesystem, so it is NOT safe to call from a live
 // redraw (the BATTERY/STORAGE view repaints every VIEW_REFRESH). The disk guard already
 // polls once a minute (DISK_CHECK_MS); both it and the STORAGE view read this cache
 // instead of re-walking. disk_refresh() re-reads on demand — entering the STORAGE view
 // forces one, since the guard's first poll is a whole DISK_CHECK_MS after boot.
 static size_t g_disk_total = 0, g_disk_used = 0;
 
 static void disk_refresh() {
   g_disk_total = LittleFS.totalBytes();
   g_disk_used  = LittleFS.usedBytes();
 }
 
 // The disk-guard trip: >=90% full. Shared so the STORAGE view's "FULL!" badge lights on
 // exactly the condition that trims the log, rather than a second threshold that could drift.
 static bool disk_is_full() {
   return g_disk_total && g_disk_used * DISK_FULL_DEN >= g_disk_total * DISK_FULL_NUM;
 }
 
 // % USED, matching the STORAGE view's polarity — for the HOME header gauge.
 static uint8_t disk_pct() {
   return g_disk_total ? (uint8_t)((uint64_t)g_disk_used * 100 / g_disk_total) : 0;
 }
 
 // BATTERY view sub-toggle: a single tap flips to the STORAGE readout and back, the same
 // way POINTS cycles its window. Reset on fresh entry so cycling views always lands on the
 // battery face — storage is a peek, not a place to park.
 static bool g_batt_storage = false;
 
 // Render the battery fuel gauge from the latest smoothed ADC reading — or, when toggled,
 // the storage readout from the cached LittleFS figures.
 static void render_battery() {
   if (g_batt_storage) display_storage(g_handle, g_disk_used, g_disk_total, disk_is_full());
   else                display_battery(g_handle, battery_mv(), battery_pct(), battery_is_low());
 }
 
 // ─── pet (companion) ─────────────────────────────────────────────────────────
 
 // The active pet: a built-in, or the uploaded custom pet in slot PET_BUILTIN_N.
 static const Pet* current_pet() {
   if (g_pet_idx == PET_BUILTIN_N && g_custom_valid) return &g_custom_pet;
   return pet_get(g_pet_idx);
 }
 // How many pets are selectable (built-ins + the custom slot iff uploaded).
 static int pet_total() { return PET_BUILTIN_N + (g_custom_valid ? 1 : 0); }
 
 // Resolve the face to show: an active reaction wins, else the ambient state
 // (low-batt > lonely > idle).
 static const char* pet_face_now(const Pet* p, uint32_t now, int nearby, bool lowbatt) {
   if (g_pet_react != PET_IDLE && now < g_pet_react_until) return p->face[g_pet_react];
   if (lowbatt)     return p->face[PET_LOWBATT];
   if (nearby == 0) return p->face[PET_LONELY];
   return p->face[PET_IDLE];
 }
 
 static void render_pet();   // fwd decl (pet_react may redraw it)
 
 // Fire a transient reaction (contact/milestone). On the PET view it redraws the
 // face; off it, the reaction pops up briefly over the current view, rate-limited
 // by PET_POPUP_COOLDOWN_MS so a crowded room doesn't spam it.
 static void pet_react(PetState s, uint32_t now, const char* line1 = nullptr,
                       const char* line2 = nullptr, uint16_t hold = 0, bool force = false) {
   g_pet_react = s;
   g_pet_react_until = now + PET_REACT_MS;
   if (g_view == VIEW_OPTIONS && g_opt_screen == OPT_PET) { render_pet(); return; }
   // A reminder toast owns the screen — hold reaction pop-ups (the face still updates) so a
   // blocking pet_popup can't clobber it; the toast auto-clears in ≤ REMINDER_TOAST_MS.
   if (!g_toast_active && (force || now >= g_pet_popup_until)) {   // force = important enough to skip the cooldown
     g_pet_popup_until = now + PET_POPUP_COOLDOWN_MS;
     const Pet* p = current_pet();
     // line1 = the reason (caller wins, else a generic), line2 = the detail (optional)
     const char* l1 = line1 ? line1 : (s == PET_MILESTONE ? "milestone" : "new crew");
     uint16_t h = hold ? hold : (s == PET_MILESTONE ? PET_MILESTONE_POPUP_MS : PET_POPUP_MS);
     display_pet_popup(p->face[s], l1, line2, h);
   }
 }
 
 // Render the PET view: the active pet's current face + a quick stat line.
 static void render_pet() {
   Peer snap[MAX_PEERS];
   int n;
   portENTER_CRITICAL(&peerMux);
   n = peers.snapshot(snap, MAX_PEERS);
   portEXIT_CRITICAL(&peerMux);
   const Pet* p = current_pet();
   display_pet(p->name, pet_face_now(p, millis(), n, battery_is_low()));   // n still feeds the lonely/idle face
 }
 
 // Render the settings MENU (boot-splash picker).
 static void render_menu() {
   display_menu(g_splash_style);
 }
 
 static const char* splash_name(uint8_t s) {
   static const char* n[BOOT_SPLASH_COUNT] = { "radar", "terminal", "glitch", "matrix" };
   return n[s % BOOT_SPLASH_COUNT];
 }
 
 static const char* bright_name(uint8_t b) {
   static const char* n[SCREEN_BRIGHT_LEVELS] = { "LOW", "MED", "HIGH" };
   return n[b % SCREEN_BRIGHT_LEVELS];
 }
 
 // Snapshot the peer table and draw the current FINDER page (closest first, in the
 // selected pet/dBm column mode). Recomputes the page total and clamps the page in
 // case peers have left. Used by the ring, the page tap, and the live redraw.
 static void render_finder() {
   Peer snap[MAX_PEERS];
   int n;
   portENTER_CRITICAL(&peerMux);
   n = peers.snapshot(snap, MAX_PEERS);
   portEXIT_CRITICAL(&peerMux);
   g_finder_pages = finder_pages(n);
   if (g_finder_page >= g_finder_pages) g_finder_page = g_finder_pages - 1;   // peers left → clamp
   display_peers(g_handle, snap, n, g_finder_rssi, points_multiplier(n), g_finder_page);
 }
 
 // Render the HOME view — the at-a-glance default: handle, pet, total points,
 // battery, and wall-clock time. The clock is formatted HERE (epoch→HH:MM, or
 // "--:--" when unsynced/stale) so both display backends stay clock-agnostic.
 static void render_home() {
   Peer snap[MAX_PEERS];
   int n;
   portENTER_CRITICAL(&peerMux);
   n = peers.snapshot(snap, MAX_PEERS);                  // for the resolved pet face (lonely/idle)
   portEXIT_CRITICAL(&peerMux);
   const Pet* p = current_pet();
   char clk[6];
   if (g_clock.synced()) {
     time_t t = (time_t)g_clock.now();                  // seeded epoch is UTC (phone sends Date.now()/1000)
     struct tm lt;
     localtime_r(&t, &lt);                              // → DISPLAY_TZ (Pacific, DST-aware) via tzset() at boot
     snprintf(clk, sizeof(clk), "%02u:%02u", (unsigned)lt.tm_hour, (unsigned)lt.tm_min);
   } else {
     strncpy(clk, "--:--", sizeof(clk));                // never synced, or stale → don't show a wrong time
   }
   display_home(g_handle, pet_face_now(p, millis(), n, battery_is_low()),
                g_prox_seconds / 60, battery_pct(), battery_is_low(), disk_pct(), clk,
                g_radio_on);
 }
 
 // Wipe every trace of this badge's owner and restart into a fresh-board state. Exists so a
 // badge can be handed on WITHOUT a USB cable — the flashing SOP's `esptool erase_flash` is
 // still the authority when a board is on the bench, but that is no help
 // to someone passing a badge to a friend at the con.
 //
 // Three separate stores have to go, and missing any one leaves the badge identifiably the
 // previous owner's:
 //   "badge" NVS  — handle, avatar, points/ledger/history, splash, brightness, stealth, …
 //   "clock" NVS  — a SEPARATE namespace, so prefs.clear() above does not reach it
 //   LittleFS     — /encounters.log (the social graph) + the Test-Mode CSVs. format() rather
 //                  than enc_clear(), which only removes the log and would strand the CSVs.
 // Never returns: the caller's world (g_handle, the peer table, the ledger) is now
 // inconsistent with NVS, so the only safe next step is a cold boot.
 static void factory_reset() {
   display_boot("erasing...");            // format() can take a moment; don't look hung
   prefs.clear();
   g_clock.factory_clear();
   LittleFS.format();
   delay(150);                            // let the NVS + FS commits land before the reset
   esp_restart();
 }
 
 // OPTIONS → Power → "Deep sleep". The closest thing to an OFF switch this hardware has:
 // the SoC's RTC domain stays alive to watch one pin, everything else stops. Never returns —
 // waking is a full application restart (ESP_RST_DEEPSLEEP), not a resume, so setup() runs
 // again from the top and the badge comes up on HOME.
 //
 // NOT actually off. The regulator, the charge IC and the onboard VBAT divider on GPIO34 all
 // sit on the battery side of anything software controls, so a slept badge still drains.
 // Board-level sleep current is unmeasured and decides whether this
 // is an "off" or a long nap.
 //
 // Wake is the button and ONLY the button: this board has no VBUS-detect tap,
 // so plugging in USB will not wake it (it does still charge). esptool drives EN/BOOT over
 // RTS/DTR, which resets the SoC regardless — a slept unit is still flashable.
 static void enter_deep_sleep() {
   display_pet_popup(current_pet()->face[PET_IDLE], "Sleeping...", "Press to wake", 2000);
   g_points_history.save(prefs);          // sleep may last days; don't strand the last sample
   display_sleep();                       // panel off — without this the sleep saves ~nothing
 
   // Don't sleep into a held button. ext0 wakes on the pin going LOW and the button is
   // INPUT_PULLUP/active-low, so entering deep sleep while it is still down re-wakes us
   // instantly and the badge looks like it ignored the command. Same guard the provisioning
   // escape hatch uses before its restart.
   while (digitalRead(BUTTON_PIN) == LOW) delay(10);
   delay(50);                             // let the contact settle before arming the wake
 
   esp_sleep_enable_ext0_wakeup((gpio_num_t)BUTTON_PIN, 0);   // 0 = wake on LOW (press)
   esp_deep_sleep_start();
 }
 
 // Jump to the HOME view (long-press from anywhere, or the OPTIONS "Back" row).
 static void go_home() {
   g_view = VIEW_HOME;
   render_home();
 }
 
 // Render whichever OPTIONS screen is active: parent list or a child picker.
 // Formatted eFuse MAC "14:33:5C:xx:xx:xx" (same base MAC as the provisioning name).
 static void format_mac(char out[18]) {
   uint8_t mac[6];
   esp_read_mac(mac, ESP_MAC_WIFI_STA);
   snprintf(out, 18, "%02X:%02X:%02X:%02X:%02X:%02X",
            mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
 }
 
 static void render_options() {
   if (g_opt_screen == OPT_PET)    { render_pet();  return; }   // pet face + live reactions
   if (g_opt_screen == OPT_SPLASH) { render_menu(); return; }   // splash picker
   if (g_opt_screen == OPT_RESET)  { display_reset_confirm(g_opt_cursor); return; }
   if (g_opt_screen == OPT_WHOAMI) {                            // read-only identity screen
     char ms[18]; format_mac(ms);
     display_whoami(g_handle, ms);
     return;
   }
   int m = (g_opt_screen == OPT_USER)    ? OPTM_USER
         : (g_opt_screen == OPT_BADGE)   ? OPTM_BADGE
         : (g_opt_screen == OPT_DISPLAY) ? OPTM_DISPLAY
         : (g_opt_screen == OPT_DEVOPTS) ? OPTM_DEVOPTS
         : (g_opt_screen == OPT_POWER)   ? OPTM_POWER
         : (g_opt_screen == OPT_REMIND)  ? OPTM_REMIND : OPTM_ROOT;
   OptView v = { current_pet()->name, splash_name(g_splash_style), bright_name(g_bright),
                 g_test_mode ? "ON" : "OFF", g_finder_rssi ? "dBm" : "avatar",
                 g_remind_global ? "ON" : "OFF", g_remind_shower ? "ON" : "OFF",
                 g_radio_on ? "OFF" : "ON" };   // stealth is the INVERSE of the radio state
   display_options_menu(m, g_opt_cursor, v);
 }
 
 // Redraw whichever view is active — used to restore the screen after a reminder toast
 // clears (the toast overlays the live view; dismissing it repaints what was underneath).
 static void redraw_current_view() {
   switch (g_view) {
     case VIEW_HOME:    render_home();    break;
     case VIEW_FINDER:  render_finder();  break;
     case VIEW_REPORT:  enter_report();   break;   // re-snapshot the static report
     case VIEW_POINTS:  render_points();  break;
     case VIEW_FRIENDS: render_friends(); break;
     case VIEW_BATTERY: render_battery(); break;
     case VIEW_OPTIONS: render_options(); break;
     default:           render_home();    break;
   }
 }
 
 // Fire a NON-BLOCKING reminder toast: draw it now and arm an auto-dismiss deadline. The
 // loop holds the frame (view redraws are suppressed while g_toast_active) until a button
 // press or REMINDER_TOAST_MS clears it — unlike display_pet_popup it never blocks the loop,
 // so beaconing/scoring keep running under the toast.
 static void show_toast(const char* face, const char* l1, const char* l2) {
   g_toast_active = true;
   g_toast_until  = millis() + REMINDER_TOAST_MS;
   display_toast(face, l1, l2);
 }
 
 // Unified one-button gesture detector. With a single button we disambiguate by
 // tap count and hold:
 //   single tap → sub-view action (fires after DOUBLETAP_GAP_MS rules out a 2nd tap)
 //   double tap → next view (fires immediately on the second tap)
 //   long press → fires once at REPORT_HOLD_MS while held (jump home to FINDER)
 // A "tap" is a press released within TAP_MAX_MS. (Holding BOOT at power-on forces
 // provisioning — a separate boot-time check in setup().) Call every loop.
 enum Gesture { GEST_NONE = 0, GEST_SINGLE, GEST_DOUBLE, GEST_LONG };
 
 static Gesture button_gesture() {
   static uint32_t press_ms = 0;
   static uint32_t first_tap_ms = 0;
   static bool was_down = false;
   static bool pending = false;          // a first tap is awaiting a possible second
   static bool long_fired = false;       // long-press already emitted for this hold
   uint32_t now = millis();
   bool down = (digitalRead(BUTTON_PIN) == LOW);
   Gesture g = GEST_NONE;
 
   if (down && !was_down) {               // press edge
     press_ms = now;
     long_fired = false;
   } else if (down && was_down) {         // still held → emit long-press once at threshold
     if (!long_fired && now - press_ms >= REPORT_HOLD_MS) {
       long_fired = true;
       pending = false;                   // a long hold cancels any pending tap
       g = GEST_LONG;
     }
   } else if (!down && was_down) {        // release edge
     if (!long_fired && now - press_ms <= TAP_MAX_MS) {   // a short tap
       if (pending && now - first_tap_ms <= DOUBLETAP_GAP_MS) {
         pending = false;
         g = GEST_DOUBLE;                 // second tap within the window → double
       } else {
         pending = true;                  // first tap; wait the window out
         first_tap_ms = now;
       }
     } else {
       pending = false;                   // a hold/long, not a tap
     }
   }
   was_down = down;
   // A lone first tap, no second within the window → single (only once released).
   if (g == GEST_NONE && pending && !down && now - first_tap_ms > DOUBLETAP_GAP_MS) {
     pending = false;
     g = GEST_SINGLE;
   }
   return g;
 }
 
 // Whatever the setup screen should currently be. Once the pairing gate has latched,
 // redrawing the normal setup screen would show a freshly rotated code that cannot work —
 // baiting the owner into retyping forever. Show the lockout instead.
 static void prov_redraw() {
   if (g_prov_locked) display_boot("locked, power-cycle");
   else               display_provisioning(g_prov_name, g_prov_code);
 }
 
 // ─── provisioning escape hatch ──────────────────────────────────────────────
 // Setup mode never times out and doesn't beacon, so a badge that lands there by accident
 // is inert with no way out on the device itself. The firmware even nudges people toward
 // re-provisioning to fix a stale clock — and the crowd most likely to follow that nudge
 // into a dead end is the iOS-only one, who cannot run the Web Bluetooth app to provision
 // their way back out. Holding BUTTON for PROV_ESCAPE_HOLD_MS reboots to the home view.
 //
 // Two things this MUST get right or it silently does nothing at all:
 //
 //   1. THE BUTTON IS STILL DOWN WHEN WE REBOOT. setup() reads BUTTON_PIN to decide
 //      whether to force provisioning, so restarting mid-hold walks straight back into
 //      setup mode. We wait for the release first.
 //
 //   2. A BADGE WITH NO STORED HANDLE RE-ENTERS SETUP REGARDLESS of the button —
 //      have_handle is false, so setup() has nowhere else to send it. Escaping therefore
 //      has to leave a usable handle behind, so we seed a MAC-derived default. That is
 //      the difference between "escaped" and "escaped into the same room".
 //
 // Called only from the MODE_PROVISION branch of loop(), where the button is otherwise
 // unused, so there's no gesture to conflict with.
 static void prov_escape_tick() {
   static uint32_t press_ms = 0;
   static bool     was_down = false;
   static bool     armed    = false;     // see below — requires one release before it listens
   static int      shown    = -1;        // countdown value currently drawn (-1 = setup screen)
 
   uint32_t now  = millis();
   bool     down = (digitalRead(BUTTON_PIN) == LOW);
 
   // Trap 3: the usual way INTO setup mode is holding BOOT through power-on, so the
   // button is often still down on our first ticks. Without this, entering setup mode
   // and simply not letting go would bounce you straight back out — the feature
   // sabotaging the very gesture that reaches it. Require a fresh press.
   if (!armed) {
     if (down) return;
     armed = true;
   }
 
   if (down && !was_down) press_ms = now;              // press edge
   was_down = down;
 
   if (!down) {                                        // released early → restore the screen
     if (shown >= 0) { prov_redraw(); shown = -1; }
     return;
   }
 
   uint32_t held = now - press_ms;
   if (held < PROV_ESCAPE_FEEDBACK_MS) return;         // ignore incidental presses
 
   if (held < PROV_ESCAPE_HOLD_MS) {                   // counting down, once per second
     int left = (int)((PROV_ESCAPE_HOLD_MS - held + 999) / 1000);
     if (left != shown) {
       char line[24];
       snprintf(line, sizeof(line), "exit setup in %d", left);
       display_boot(line);
       shown = left;
     }
     return;
   }
 
   // Held the full duration → leave setup mode.
   if (prefs.getString("handle", "").length() == 0) {  // trap 2: never-provisioned badge
     uint8_t mac[6];
     esp_read_mac(mac, ESP_MAC_WIFI_STA);
     char dflt[HANDLE_MAX_LEN + 1];
     snprintf(dflt, sizeof(dflt), "n00b-%02X%02X", mac[4], mac[5]);
     prefs.putString("handle", dflt);                  // renameable later from the web app
     char line[24];
     snprintf(line, sizeof(line), "named %s", dflt);
     display_boot(line);
     delay(1200);                                       // long enough to read it
   }
 
   display_boot("exiting setup");
   while (digitalRead(BUTTON_PIN) == LOW) delay(10);   // trap 1: don't reboot into a held button
   delay(50);                                          // debounce the release
   ESP.restart();
 }
 
 // ─── lifecycle ──────────────────────────────────────────────────────────────
 
 // Active boot-splash style: the user's NVS pick (set in the MENU view), defaulting to the
 // compiled-in BOOT_SPLASH_STYLE. Wrapped on BOOT_SPLASH_COUNT so a stored index from an
 // older build (or a wider one) can never index past the name table.
 static int pick_splash_style() {
   return (int)(prefs.getUInt("splash", BOOT_SPLASH_STYLE) % BOOT_SPLASH_COUNT);
 }
 
 // Serial POST / boot diagnostics — printed after the splash, before the welcome.
 static void print_boot_diag(const char* modestr, const char* handle) {
   uint8_t mac[6] = {0};
   esp_read_mac(mac, ESP_MAC_WIFI_STA);
   const char* rst;
   switch (esp_reset_reason()) {
     case ESP_RST_POWERON:   rst = "POWERON";   break;
     case ESP_RST_SW:        rst = "SW";        break;
     case ESP_RST_PANIC:     rst = "PANIC";     break;
     case ESP_RST_INT_WDT:
     case ESP_RST_TASK_WDT:
     case ESP_RST_WDT:       rst = "WDT";       break;
     case ESP_RST_BROWNOUT:  rst = "BROWNOUT";  break;
     case ESP_RST_DEEPSLEEP: rst = "DEEPSLEEP"; break;
     default:                rst = "OTHER";     break;
   }
   Serial.println("  ── boot ───────────────────────────────");
   Serial.printf( "  build : %s\n", FW_BUILD_STR);
   Serial.printf( "  chip  : %s · %d core @ %d MHz\n",
                  ESP.getChipModel(), ESP.getChipCores(), (int)ESP.getCpuFreqMHz());
   Serial.printf( "  flash : %u MB   heap: %u KB free\n",
                  (unsigned)(ESP.getFlashChipSize() >> 20),
                  (unsigned)(ESP.getFreeHeap() >> 10));
   Serial.printf( "  mac   : %02X:%02X:%02X:%02X:%02X:%02X\n",
                  mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
   Serial.printf( "  reset : %s\n", rst);
   Serial.printf( "  mode  : %s   handle \"%s\"   ch %d\n",
                  modestr, handle, ESPNOW_CHANNEL);
   Serial.printf( "  stealth: %s\n", g_radio_on ? "OFF (broadcasting)"
                                                : "ON (not broadcasting — RX still live)");
   Serial.println("  ────────────────────────────────────────");
   delay((uint32_t)BOOT_DIAG_HOLD_MS * BOOT_TIMING_SCALE);   // hold so the readout is readable
 }
 
 void setup() {
   Serial.begin(115200);
   delay(200);
   display_init();
 
   prefs.begin("badge", false);                 // up top: settings (splash/pet) + handle live here
 
   // Brightness first: display_init() ran before NVS was open (it has to — it owns the
   // bus), so the saved level can only be applied here. Do it before the splash so the
   // very first frame the user sees is at their pick, not a flash of the panel default.
   g_bright = (uint8_t)(prefs.getUChar("bright", SCREEN_BRIGHT_DEFAULT) % SCREEN_BRIGHT_LEVELS);
   display_set_brightness(g_bright);
 
   g_splash_style = (uint8_t)pick_splash_style();
   // restore a custom pet (slot PET_BUILTIN_N) if one was uploaded
   if (prefs.getUChar("petc_ok", 0) == 1 &&
       prefs.getBytes("petcust", &g_custom_pet, sizeof(g_custom_pet)) == sizeof(g_custom_pet))
     g_custom_valid = true;
   g_pet_idx = (int)(prefs.getUInt("pet", 0) % pet_total());
   g_finder_rssi = (prefs.getUChar("finder", 0) == 1);   // FINDER column: 0=pet face, 1=dBm (User Settings)
   g_remind_global = (prefs.getUChar("rmglob", 1) == 1); // reminders default ON (toggle to disable)
   g_remind_shower = (prefs.getUChar("rmshow", 1) == 1);
   g_radio_on = (prefs.getUChar("radio", 1) == 1);       // broadcast defaults ON (Badge Settings → Radio)
   g_test_mode = (prefs.getUChar("testmode", 0) == 1);   // OPTIONS → Test (persisted)
   if (g_test_mode) {
     g_boot_id = prefs.getUInt("bootid", 0) + 1;
     prefs.putUInt("bootid", g_boot_id);
     // The user's pet announces test mode BEFORE the boot splash.
     display_pet_popup(current_pet()->face[PET_MILESTONE], "Debug Mode On", nullptr, TEST_MODE_POPUP_MS);
   }
   display_boot_splash(g_splash_style);         // animated splash (OLED) / ASCII banner (serial)
   display_boot_logos();                        // logo card — FOLLOWS the chosen splash, every boot
   display_disclaimer();                        // heat/LiPo safety card, held then continues boot
 
   g_clock.begin();
   setenv("TZ", DISPLAY_TZ, 1);   // wall-clock shown in Pacific (DST-aware); epoch stays UTC
   tzset();
   // A brownout reset means we were dark for an unknown span, so the resumed-from-NVS
   // wall-clock is skewed → flag it stale (report shows relative + a re-sync nudge).
   //
   // A deep-sleep wake is the SAME failure with a different cause, and it is the more likely
   // one now that OPTIONS → Power → Deep sleep exists: the soft clock free-runs off millis(),
   // which resets to 0 on wake, so a badge slept overnight resumes from its last 60 s NVS
   // checkpoint hours behind. Without this the report would show a confidently-WRONG
   // wall-clock with no warning — exactly the bug the stale flag was added to kill.
   {
     esp_reset_reason_t rr = esp_reset_reason();
     if (rr == ESP_RST_BROWNOUT || rr == ESP_RST_DEEPSLEEP) g_clock.mark_stale();
   }
   battery_init();
 
   pinMode(BUTTON_PIN, INPUT_PULLUP);
   delay(50);
   // Enter provisioning if BOOT is held, OR if OPTIONS → Provisioning Mode requested it
   // (one-shot NVS flag) so the hosted BLE page can re-seed handle/clock/pet without a
   // button-held reboot.
   bool force_provision = (digitalRead(BUTTON_PIN) == LOW) ||
                          (prefs.getUChar("provreq", 0) == 1);
   prefs.putUChar("provreq", 0);                  // consume the one-shot
 
   String stored = prefs.getString("handle", "");
   bool have_handle = stored.length() > 0 && !force_provision;
   if (have_handle) {
     strncpy(g_handle, stored.c_str(), HANDLE_MAX_LEN);
     g_handle[HANDLE_MAX_LEN] = '\0';
   }
 
   // Serial POST / boot diagnostics, after the splash and before the welcome.
   print_boot_diag(have_handle ? "DISCOVERY" : "PROVISION",
                   have_handle ? g_handle : "(unset)");
 
   if (g_test_mode) {                            // TEST MODE: show the MAC + dump prior logs
     uint8_t mac[6] = {0};
     esp_read_mac(mac, ESP_MAC_WIFI_STA);        // the STA MAC = the peer-table identity
     char macs[18];
     snprintf(macs, sizeof(macs), "%02X:%02X:%02X:%02X:%02X:%02X",
              mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
     display_boot(macs);                         // on the OLED — read/photograph it, no USB needed
     Serial.printf("[TEST] MAC %s  -- dumping logs --\n", macs);
     LittleFS.begin(true);                       // ensure mounted before reading the CSVs
     g_batt_log.dump(Serial);
     g_pts_log.dump(Serial);
     delay(TEST_MAC_HOLD_MS);                     // hold the MAC screen long enough to capture
   }
 
   if (!have_handle) {
     mode = MODE_PROVISION;
     start_provisioning();
   } else {
     // Welcome as a pet TOAST (the old welcome screen in toast form) — the pet greets you by
     // handle. "Welcome," over "<handle>!" across the toast's two lines (as the old screen was)
     // so the full handle keeps its own line width; one combined line would cap the handle ~8
     // chars. PET_CONTACT = the greeting "new crew in range" face.
     char hl[HANDLE_MAX_LEN + 2];
     snprintf(hl, sizeof(hl), "%.*s!", 17, g_handle);   // handle + '!', clamped to the toast line
     display_pet_popup(current_pet()->face[PET_CONTACT], "Welcome,", hl, 1200 * BOOT_TIMING_SCALE);
     mode = MODE_DISCOVER;
     start_discovery();
     disk_refresh();       // seed the cache — start_discovery() has just mounted LittleFS, and the
                           //   guard's first poll is DISK_CHECK_MS away, but HOME shows the disk
                           //   gauge immediately and would otherwise read 0% for the first minute.
   }
 }
 
 // ─── test-mode loggers (gated by g_test_mode at the call sites) ──────────────
 
 // Battery: adaptive cadence — coarse on the plateau, fast once the cell drops
 // below the knee (the cliff is where VBAT_EMPTY + the real curve live).
 static void test_batt_log_tick(uint32_t now) {
   static uint32_t last = 0;
   uint16_t mv = battery_mv();
   uint32_t iv = (mv && mv < TEST_LOG_CLIFF_MV) ? TEST_LOG_FAST_MS : TEST_LOG_INTERVAL_MS;
   if (last != 0 && (now - last) < iv) return;
   last = now;
   char line[48];
   snprintf(line, sizeof(line), "%lu,%lu,%u,%u",
            (unsigned long)g_boot_id, (unsigned long)now, mv, battery_pct());
   g_batt_log.append(line);
 }
 
 // Points: 1-min snapshots of the live scoring counters (the graph rings don't
 // expose these as CSV — handy for validating the group-multiplier logic).
 static void test_pts_log_tick(uint32_t now, int peers_now, uint8_t mult) {
   static uint32_t last = 0;
   if (last != 0 && (now - last) < TEST_PTLOG_INTERVAL_MS) return;
   last = now;
   char line[64];
   snprintf(line, sizeof(line), "%lu,%lu,%lu,%lu,%d,%u",
            (unsigned long)g_boot_id, (unsigned long)now,
            (unsigned long)(g_prox_seconds / 60), (unsigned long)g_prox_seconds,
            peers_now, (unsigned)mult);
   g_pts_log.append(line);
 }
 
 // ─── metrics export (BLE stream, provisioning mode) ──────────────────────────
 // Send `data` (len bytes) as ≤`chunk` notify pieces, paced so the BLE tx buffer can drain.
 // Returns false if the peer vanished mid-send (caller aborts the stream).
 static bool metrics_notify(const uint8_t* data, size_t len, size_t chunk) {
   size_t off = 0;
   while (off < len) {
     if (!g_metrics_ch || NimBLEDevice::getServer()->getConnectedCount() == 0) return false;
     size_t n = (len - off < chunk) ? (len - off) : chunk;
     // notify(data,len) sends THIS slice directly (no setValue/notify race) and returns false when
     // the tx buffer is full — retry with backoff so a chunk is NEVER silently dropped. Dropped
     // chunks fuse CSV lines into garbage on the far end (the bug that made vbat_mv read in the
     // millions). Abort if the peer vanishes.
     int tries = 0;
     while (!g_metrics_ch->notify(data + off, n)) {
       if (++tries > METRICS_NOTIFY_RETRIES ||
           NimBLEDevice::getServer()->getConnectedCount() == 0) return false;
       delay(METRICS_PACE_MS);                    // let the controller drain, then retry the same slice
     }
     off += n;
     delay(METRICS_PACE_MS);                      // steady pacing between chunks (also feeds the WDT)
   }
   return true;
 }
 static bool metrics_notify_str(const char* s, size_t chunk) {
   return metrics_notify((const uint8_t*)s, strlen(s), chunk);
 }
 
 // Stream one LittleFS file, framed like TestLog::dump (==== path ==== … ==== end ====).
 static bool metrics_stream_file(const char* path, size_t chunk) {
   char hdr[64];
   snprintf(hdr, sizeof(hdr), "==== %s ====\n", path);
   if (!metrics_notify_str(hdr, chunk)) return false;
   File f = LittleFS.open(path, FILE_READ);
   if (f) {
     uint8_t buf[METRICS_CHUNK_MAX];
     while (f.available()) {
       size_t n = f.read(buf, chunk);
       if (n && !metrics_notify(buf, n, chunk)) { f.close(); return false; }
     }
     f.close();
   } else if (!metrics_notify_str("(none)\n", chunk)) {
     return false;
   }
   return metrics_notify_str("==== end ====\n", chunk);
 }
 
 // Stream the points-history ring as CSV (formatted from the NVS-backed RAM buffer).
 static bool metrics_stream_points(size_t chunk) {
   if (!metrics_notify_str("==== /points_history.csv ====\n", chunk)) return false;
   if (!metrics_notify_str("epoch,points,seg_start\n", chunk)) return false;
   static PointSample ps[POINTS_HISTORY_LEN];     // static: keep it off the stack
   int n = g_points_history.snapshot(ps, POINTS_HISTORY_LEN);
   char line[32];
   for (int i = 0; i < n; i++) {
     int m = snprintf(line, sizeof(line), "%lu,%u,%u\n",
                      (unsigned long)ps[i].epoch, (unsigned)ps[i].points, (unsigned)ps[i].seg_start);
     if (!metrics_notify((const uint8_t*)line, (size_t)m, chunk)) return false;
   }
   return metrics_notify_str("==== end ====\n", chunk);
 }
 
 // Stream the best-friends ledger (per-friend credited proximity seconds, ranked). Handle LAST —
 // sanitized handles may contain a comma, so keep the numeric column unsplittable by it.
 static bool metrics_stream_friends(size_t chunk) {
   if (!metrics_notify_str("==== /best_friends.csv ====\n", chunk)) return false;
   if (!metrics_notify_str("seconds,handle\n", chunk)) return false;
   static PointFriend bf[MAX_POINT_FRIENDS];
   int n = g_ledger.top(bf, MAX_POINT_FRIENDS);
   char line[HANDLE_MAX_LEN + 16];
   for (int i = 0; i < n; i++) {
     int m = snprintf(line, sizeof(line), "%lu,%s\n", (unsigned long)bf[i].seconds, bf[i].handle);
     if (!metrics_notify((const uint8_t*)line, (size_t)m, chunk)) return false;
   }
   return metrics_notify_str("==== end ====\n", chunk);
 }
 
 // The whole export: encounters.log always, points history always, the Test-Mode CSVs only
 // when Debug is on. Chunk size = the negotiated MTU (−3 ATT overhead), capped. Ends with the
 // "==== EOF ====" sentinel the page reassembles up to. Runs in loop() — never a BLE callback.
 static void stream_metrics() {
   // The export runs in PROVISIONING mode, which never calls start_discovery() — so LittleFS may
   // be unmounted and the NVS points-history ring unloaded (0 samples). Prepare both here or
   // points_history streams empty even when the OLED shows a populated graph, and the log files
   // read as "(none)" on a non-Test badge. Idempotent — start_discovery already did this in
   // discovery mode (re-begin just warns "Already Mounted").
   LittleFS.begin(true);
   g_points_history.load(prefs);
   g_ledger.load(prefs);          // best-friends ledger — also only loaded in start_discovery()
   uint16_t mtu   = NimBLEDevice::getServer()->getPeerMTU(g_metrics_conn);
   size_t   chunk = (mtu > 23) ? (size_t)(mtu - 3) : 20;
   if (chunk > METRICS_CHUNK_MAX) chunk = METRICS_CHUNK_MAX;
   Serial.printf("[METRICS] streaming (mtu=%u chunk=%u debug=%d)\n",
                 (unsigned)mtu, (unsigned)chunk, (int)g_test_mode);
   if (!metrics_stream_file(ENC_LOG_PATH, chunk)) { Serial.println("[METRICS] aborted (peer gone)"); return; }
   if (!metrics_stream_points(chunk))             { Serial.println("[METRICS] aborted (peer gone)"); return; }
   if (!metrics_stream_friends(chunk))            { Serial.println("[METRICS] aborted (peer gone)"); return; }
   if (g_test_mode) {
     if (!metrics_stream_file("/test_batt.csv", chunk)) return;
     if (!metrics_stream_file("/test_pts.csv", chunk))  return;
   }
   metrics_notify_str("==== EOF ====\n", chunk);
   Serial.println("[METRICS] stream complete");
 }
 
 void loop() {
   if (mode == MODE_PROVISION) {
     if (g_saved) {
       display_boot("saved — rebooting to home");
       delay(800);
       ESP.restart();
     }
     // Pairing gate latched (PROV_CODE_MAX_TRIES bad codes). The callback only sets the
     // flag; the screen redraw and the disconnect happen here so the BLE stack callback
     // stays fast — same rule the metrics stream follows.
     if (g_prov_lock_pending) {
       g_prov_lock_pending = false;
       gen_prov_code(g_prov_code);            // burn the code that was being ground down
       prov_redraw();                          // → the lockout screen
       NimBLEServer* srv = NimBLEDevice::getServer();
       if (srv) srv->disconnect(g_prov_conn);  // drop the peer; reconnecting won't help
       Serial.printf("[PROV] gate LOCKED after %u bad codes — power-cycle to retry\n",
                     (unsigned)PROV_CODE_MAX_TRIES);
     }
 
     prov_escape_tick();      // hold-to-exit: the only on-device way out of setup mode
     // Metrics export: once the client has subscribed AND entered the pairing code, stream the
     // framed dump here (not in the BLE callback), then reboot to discovery a moment later so
     // the badge returns to normal use without a manual power-cycle.
     if (g_metrics_req && g_prov_authed && !g_metrics_done) {
       g_metrics_req = false;
       stream_metrics();
       g_metrics_done = true;
       g_metrics_reboot_at = millis() + METRICS_REBOOT_MS;
     }
     if (g_metrics_done && (int32_t)(millis() - g_metrics_reboot_at) >= 0) {
       display_boot("export done — rebooting");
       delay(300);
       ESP.restart();
     }
     delay(50);
     return;
   }
 
   // MODE_DISCOVER
   static uint32_t last_beacon = 0, last_display = 0;
   uint32_t now = millis();
   g_clock.tick();
   battery_sample(now);                       // throttled + smoothed internally
   if (g_test_mode) test_batt_log_tick(now);  // test mode: log VBAT on the adaptive cadence
 
   // Low-battery toast: fire when VBAT first crosses the LOW threshold, then re-warn
   // every PET_LOWBATT_REMIND_MS while still low — persistent, since it matters. Forced
   // past the reaction cooldown so an unrelated toast can't swallow the warning.
   static bool     prev_low = false;
   static uint32_t last_lowbatt_warn = 0;
   bool low_now = battery_is_low();
   if (low_now && (!prev_low || now - last_lowbatt_warn >= PET_LOWBATT_REMIND_MS)) {
     last_lowbatt_warn = now;
     char d[16];
     snprintf(d, sizeof(d), "%u%% - charge", (unsigned)battery_pct());
     pet_react(PET_LOWBATT, now, "low battery", d, PET_LOWBATT_POPUP_MS, true);
   }
   prev_low = low_now;
 
   // Shower reminder — an 8h UPTIME interval (the board has no RTC, so we nudge on elapsed
   // uptime, not wall-clock 8am/5pm). "Global" gates all reminders, "Shower" gates this one
   // (User Settings → Reminders, both default ON). Seeded to `now` so it never fires at boot,
   // and skipped while a toast is already up. show_toast is non-blocking (loop keeps running).
   static uint32_t last_shower_reminder = 0;
   if (last_shower_reminder == 0) last_shower_reminder = now;
   if (g_remind_global && g_remind_shower && !g_toast_active &&
       now - last_shower_reminder >= REMINDER_SHOWER_MS) {
     last_shower_reminder = now;
     show_toast(current_pet()->face[PET_MILESTONE], "shower time", "freshen up!");
   }
 
   // Disk guard — now a BACKSTOP, not the primary bound. enc_append caps the log at
   // ENC_LOG_MAX_BYTES, so this should never fire on encounter growth alone; if it does, the
   // pressure is coming from somewhere else (the Test-Mode CSVs) and trimming the log is a
   // best-effort response. It used to be the only bound, and it could not work: at ≥90% used
   // there is ~90 KB free but `keep` below asks for ~80% of the partition, so the copy ran out
   // of space and — walking forward from the cut — kept the OLDEST slice, destroying the newest
   // history. enc_trim_oldest now clamps `keep` to real free space and refuses to replace the
   // live log on a short write, so an over-large request degrades to "less history, still the
   // most recent" instead of silent inversion.
   // NVS (settings/points/handle) is a separate partition — safe.
   static uint32_t last_disk_check = 0, last_disk_warn = 0;
   if (now - last_disk_check >= DISK_CHECK_MS) {
     last_disk_check = now;
     disk_refresh();                                                      // also feeds the STORAGE view
     size_t total = g_disk_total, used = g_disk_used;
     if (disk_is_full()) {                                                // ≥90% full
       size_t logsz  = enc_size();
       size_t nonlog = (used > logsz) ? used - logsz : 0;                 // test CSVs + FS overhead
       size_t target = (size_t)((uint64_t)total * DISK_TARGET_NUM / DISK_TARGET_DEN);
       size_t keep   = (target > nonlog) ? target - nonlog : total / 20;  // newest log bytes to keep (≥5% floor)
       size_t freed  = enc_trim_oldest(keep);
       disk_refresh();                                                    // the trim freed space — re-cache
       Serial.printf("[DISK] %u/%u used (>=90%%) - dropped %u B of oldest encounters\n",
                     (unsigned)used, (unsigned)total, (unsigned)freed);
       if (!g_toast_active && (last_disk_warn == 0 || now - last_disk_warn >= DISK_WARN_REMIND_MS)) {
         last_disk_warn = now;
         show_toast(current_pet()->face[PET_LOWBATT], "log almost full", "export soon");
       }
     }
   }
 
   // One button (called every loop to keep its edge state current):
   //   double tap → next view
   //   single tap → change this view's sub-setting (POINTS window · PET swap · MENU splash)
   Gesture gest = button_gesture();
   // A reminder toast overlays the live view: dismiss it on ANY button press (press consumed,
   // not routed) or when its deadline passes; either way repaint the view underneath. While
   // it's up, the view redraws further down are suppressed so it holds the frame.
   if (g_toast_active && (gest != GEST_NONE || (int32_t)(now - g_toast_until) >= 0)) {
     g_toast_active = false;
     gest = GEST_NONE;                                // swallow the dismissing press
     redraw_current_view();
   }
   if (gest == GEST_LONG) {
     go_home();                                       // long-press → home from anywhere
   } else if (g_view == VIEW_OPTIONS) {
     // Nested OPTIONS menu — single tap = move/cycle, double tap = enter/back.
     if (g_opt_screen == OPT_MENU) {                  // ROOT: Back · User Settings · Badge Settings
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 3;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if      (g_opt_cursor == 0) go_home();        // "Back" — the default row
         else if (g_opt_cursor == 1) { g_opt_screen = OPT_USER;  g_opt_cursor = 0; render_options(); }
         else                        { g_opt_screen = OPT_BADGE; g_opt_cursor = 0; render_options(); }
       }
     } else if (g_opt_screen == OPT_USER) {           // Back · Pet · Finder View · Reminders
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 4;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if      (g_opt_cursor == 0) { g_opt_screen = OPT_MENU; g_opt_cursor = 1; render_options(); }  // Back → ROOT (on "User Settings")
         else if (g_opt_cursor == 1) { g_opt_screen = OPT_PET; render_options(); }
         else if (g_opt_cursor == 2) { g_finder_rssi = !g_finder_rssi;            // "Finder View" — inline toggle pet ↔ dBm
                                       prefs.putUChar("finder", g_finder_rssi ? 1 : 0); render_options(); }
         else { g_opt_screen = OPT_REMIND; g_opt_cursor = 0; render_options(); }  // "Reminders" — submenu
       }
     } else if (g_opt_screen == OPT_BADGE) {          // Back · Display · Stealth · Developer Options · Power
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 5;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if      (g_opt_cursor == 0) { g_opt_screen = OPT_MENU;    g_opt_cursor = 2; render_options(); }  // Back → ROOT (on "Badge Settings")
         else if (g_opt_cursor == 1) { g_opt_screen = OPT_DISPLAY; g_opt_cursor = 0; render_options(); }  // "Display" — submenu
         else if (g_opt_cursor == 2) {                // "Stealth" — inline toggle: stop/resume broadcasting
           g_radio_on = !g_radio_on;                  //   TX-only gate; RX and the peer table are untouched
           prefs.putUChar("radio", g_radio_on ? 1 : 0);
           render_options();
         }
         else if (g_opt_cursor == 3) { g_opt_screen = OPT_DEVOPTS; g_opt_cursor = 0; render_options(); }  // "Developer Options" — submenu
         else { g_opt_screen = OPT_POWER; g_opt_cursor = 0; render_options(); }                           // "Power" — submenu (was Reboot)
       }
     } else if (g_opt_screen == OPT_POWER) {          // Back · Reboot · Deep sleep
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 3;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if      (g_opt_cursor == 0) { g_opt_screen = OPT_BADGE; g_opt_cursor = 4; render_options(); }  // Back → Badge (on "Power")
         else if (g_opt_cursor == 1) {                // "Reboot" — plain restart (moved here from Badge)
           display_pet_popup(current_pet()->face[PET_IDLE], "Rebooting...", nullptr, 700);
           esp_restart();
         }
         else enter_deep_sleep();                     // "Deep sleep" — never returns; button wakes
       }
     } else if (g_opt_screen == OPT_DISPLAY) {        // Back · Splash · Brightness
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 3;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if      (g_opt_cursor == 0) { g_opt_screen = OPT_BADGE; g_opt_cursor = 1; render_options(); }  // Back → Badge (on "Display")
         else if (g_opt_cursor == 1) { g_opt_screen = OPT_SPLASH; render_options(); }                   // "Splash" — picker
         else {                                       // "Brightness" — inline cycle LOW → MED → HIGH
           g_bright = (g_bright + 1) % SCREEN_BRIGHT_LEVELS;
           prefs.putUChar("bright", g_bright);
           display_set_brightness(g_bright);          // takes effect on this very redraw
           render_options();
         }
       }
     } else if (g_opt_screen == OPT_DEVOPTS) {        // Back · Whoami · Debug · Provisioning · Factory Reset
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 5;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if (g_opt_cursor == 0) { g_opt_screen = OPT_BADGE; g_opt_cursor = 3; render_options(); }      // Back → Badge (on "Developer Options")
         else if (g_opt_cursor == 1) { g_opt_screen = OPT_WHOAMI; render_options(); }                  // "Whoami" — identity screen
         else if (g_opt_cursor == 2) {                // "Debug" — toggle diagnostics
           g_test_mode = !g_test_mode;
           prefs.putUChar("testmode", g_test_mode ? 1 : 0);
           if (g_test_mode) {                         // enabling → fresh capture + new boot id
             g_boot_id = prefs.getUInt("bootid", 0) + 1;
             prefs.putUInt("bootid", g_boot_id);
             g_batt_log.reset();
             g_pts_log.reset();
           }
           render_options();
         } else if (g_opt_cursor == 3) {              // "Provisioning Mode" — reboot into BLE setup
           prefs.putUChar("provreq", 1);              // one-shot: setup() enters provisioning
           display_pet_popup(current_pet()->face[PET_CONTACT], "Provisioning mode", nullptr, 1200);
           esp_restart();                             // BLE comes up → hosted page sets handle/clock/pet
         } else {                                     // "Factory Reset" — confirm first, never inline
           g_opt_screen = OPT_RESET; g_opt_cursor = 0;   // land on Cancel
           render_options();
         }
       }
     } else if (g_opt_screen == OPT_RESET) {           // Cancel · ERASE (destructive; confirm gate)
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 2;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if (g_opt_cursor == 0) { g_opt_screen = OPT_DEVOPTS; g_opt_cursor = 4; render_options(); }  // Cancel
         else                   { factory_reset(); }   // does not return — restarts
       }
     } else if (g_opt_screen == OPT_WHOAMI) {          // read-only identity screen
       if (gest == GEST_DOUBLE) { g_opt_screen = OPT_DEVOPTS; g_opt_cursor = 1; render_options(); }  // back → Developer Options (on Whoami)
     } else if (g_opt_screen == OPT_PET) {
       if (gest == GEST_SINGLE) {
         g_pet_idx = (g_pet_idx + 1) % pet_total();
         prefs.putUInt("pet", g_pet_idx);
         render_pet();
       } else if (gest == GEST_DOUBLE) { g_opt_screen = OPT_USER; g_opt_cursor = 1; render_options(); }   // back → User Settings (on "Pet")
     } else if (g_opt_screen == OPT_REMIND) {          // Back · Global · Shower (toggles; default ON)
       if (gest == GEST_SINGLE) {
         g_opt_cursor = (g_opt_cursor + 1) % 3;
         render_options();
       } else if (gest == GEST_DOUBLE) {
         if      (g_opt_cursor == 0) { g_opt_screen = OPT_USER; g_opt_cursor = 3; render_options(); }  // Back → User (on "Reminders")
         else if (g_opt_cursor == 1) { g_remind_global = !g_remind_global;         // master switch
                                       prefs.putUChar("rmglob", g_remind_global ? 1 : 0); render_options(); }
         else                        { g_remind_shower = !g_remind_shower;          // shower reminder
                                       prefs.putUChar("rmshow", g_remind_shower ? 1 : 0); render_options(); }
       }
     } else {  // OPT_SPLASH
       if (gest == GEST_SINGLE) {
         g_splash_style = (g_splash_style + 1) % BOOT_SPLASH_COUNT;
         prefs.putUInt("splash", g_splash_style);
         render_menu();
       } else if (gest == GEST_DOUBLE) { g_opt_screen = OPT_DISPLAY; g_opt_cursor = 1; render_options(); }   // back → Display (on "Splash")
     }
   } else if (gest == GEST_DOUBLE) {
     g_view = (View)((g_view + 1) % VIEW_COUNT);
     switch (g_view) {
       case VIEW_HOME:    render_home();    break;  // also redraws live below
       case VIEW_FINDER:  g_finder_page = 0; render_finder(); break;  // fresh entry → page 1; live below
       case VIEW_REPORT:  enter_report();   break;  // static snapshot, drawn once
       case VIEW_POINTS:  render_points();  break;  // also redraws live below
       case VIEW_FRIENDS: render_friends(); break;  // also redraws live below
       case VIEW_BATTERY: g_batt_storage = false; render_battery(); break;  // fresh entry → battery face; live below
       case VIEW_OPTIONS: g_opt_screen = OPT_MENU; g_opt_cursor = 0; render_options(); break;
       default:           display_boot("resuming"); break;
     }
   } else if (gest == GEST_SINGLE) {
     if (g_view == VIEW_POINTS) {                    // POINTS: cycle the graph window
       g_points_window = (PointsWin)((g_points_window + 1) % PWIN_COUNT);
       render_points();
     } else if (g_view == VIEW_FINDER) {             // FINDER: page down the badge list (wraps)
       g_finder_page = (g_finder_page + 1) % g_finder_pages;
       render_finder();
     } else if (g_view == VIEW_BATTERY) {            // BATTERY: flip to the storage readout
       g_batt_storage = !g_batt_storage;
       if (g_batt_storage) disk_refresh();           // fresh on arrival — the guard only polls every 60 s
       render_battery();
     }
   }
 
   // Broadcast. Gated by the Stealth switch: while stealthed we simply never transmit, so
   // badge is invisible to everyone else while still hearing them. g_counter therefore
   // stops advancing too, which is fine — it only has to be monotonic, and receivers
   // compare it per-sender, so it just resumes where it left off when the radio comes back.
   if (g_radio_on && now - last_beacon >= BEACON_INTERVAL_MS) {
     last_beacon = now;
     send_beacon();
   }
 
   // Low-battery glyph blink: the home view needs a faster redraw than the 3 s
   // view refresh to animate it. Cheap (re-renders home only), and only while low.
   static uint32_t last_lowblink = 0;
   if (!g_toast_active && g_view == VIEW_HOME && battery_is_low() && now - last_lowblink >= BATT_LOW_BLINK_MS / 2) {
     last_lowblink = now;
     render_home();
   }
 
   // Expire + log departures, accrue points, and redraw the live view (FINDER
   // or POINTS). REPORT is a static snapshot, so we leave its screen untouched.
   if (now - last_display >= DISPLAY_REFRESH_MS) {
     last_display = now;
     static Encounter ev[MAX_PEERS];              // static: this block also nests into enc_append→
     int en = 0;                                  //   vfprintf on departures; keep ev (~1.1KB) off the
     Peer snap[MAX_PEERS];                         //   loopTask stack (same canary risk as enter_report)
     int n;
     portENTER_CRITICAL(&peerMux);
     peers.expire(now, ev, en, MAX_PEERS);
     n = peers.snapshot(snap, MAX_PEERS);
     portEXIT_CRITICAL(&peerMux);
     for (int i = 0; i < en; i++) enc_append(ev[i]);   // file IO outside the lock
 
     // Points: add the elapsed tick to the proximity tally whenever crew are
     // both in range AND close enough to clear the RSSI gate. Seeded to `now` on
     // the first pass so we never count boot time. Whole seconds earned this tick
     // are scaled by the group multiplier (×2 crew around / ×3 group of 5+) and
     // credited to EVERY in-gate companion for the best-friends view — the same
     // scaled amount, so friend minutes stay ≤ the total and the views agree.
     bool earning = points_earning(snap, n);
     uint8_t mult = points_multiplier(n);
     static uint32_t last_points_ms = 0;
     if (last_points_ms == 0) last_points_ms = now;
     uint32_t dt = now - last_points_ms;
     last_points_ms = now;
     if (earning) {
       g_prox_accum_ms += dt;
       uint32_t whole = g_prox_accum_ms / 1000;
       g_prox_accum_ms %= 1000;
       if (whole) {
         g_prox_seconds += whole * mult;           // each wall second counts ×mult
         // Credit the minute to EVERY in-gate friend (snapshot is sorted
         // closest-first, so stop at the first one below the gate).
         for (int i = 0; i < n && snap[i].rssi >= POINTS_MIN_RSSI; i++)
           g_ledger.credit(snap[i].handle, whole * mult);
       }
     }
 
     // Group-bonus activation pop-up: when the multiplier level RISES (crew
     // gathered), celebrate it like an achievement — the milestone face with an
     // "xN bonus!" label. Falling levels change the header chip silently. The
     // pet_react cooldown + the 15s peer TTL keep a flapping 5th badge from
     // spamming the screen.
     static uint8_t prev_mult = 1;
     if (mult > prev_mult) {
       char mb[16];
       snprintf(mb, sizeof(mb), "x%u score", (unsigned)mult);
       pet_react(PET_MILESTONE, now, "group bonus", mb);
     }
     prev_mult = mult;
 
     // Checkpoint the tally to NVS at most once per interval, and only when it
     // actually moved (no needless flash writes while you're off alone).
     static uint32_t last_persist_ms  = 0;
     static uint32_t last_persisted_s = 0xFFFFFFFF;
     if (now - last_persist_ms >= POINTS_PERSIST_MS && g_prox_seconds != last_persisted_s) {
       last_persist_ms  = now;
       last_persisted_s = g_prox_seconds;
       prefs.putUInt("prox", g_prox_seconds);
       g_ledger.save(prefs);                 // same cadence/guard as the tally
     }
 
     // Sample the cumulative score (with wall-clock epoch) for the POINTS graph,
     // self-throttled to the hourly cadence. Persist only when a new sample lands
     // (≈hourly) so the graph survives reboots without churning flash.
     if (g_points_history.sample((uint16_t)(g_prox_seconds / 60), g_clock.now(), now))
       g_points_history.save(prefs);
     g_points_recent.sample((uint16_t)(g_prox_seconds / 60), g_clock.now(), now);  // 1h ring (in-RAM)
     if (g_test_mode) test_pts_log_tick(now, n, mult);   // test mode: snapshot the live counters
 
     // Pet reactions: a never-before-seen device MAC → CONTACT (fires once per
     // device per session, flagged by the recv callback); crossing a
     // PET_MILESTONE_STEP points boundary → MILESTONE. Off the PET view, pet_react
     // pops the reaction up over the current view (cooldown-limited). Clear the
     // flag before reacting so a contact arriving mid-reaction isn't lost.
     if (g_new_contact) { g_new_contact = false; pet_react(PET_CONTACT, now, "new crew", g_contact_handle); }
     static uint32_t prev_milestone_pts = 0;
     uint32_t pts_now = g_prox_seconds / 60;
     if (pts_now > 0 && pts_now / PET_MILESTONE_STEP > prev_milestone_pts / PET_MILESTONE_STEP) {
       char ms[16];                                    // the milestone value = the detail line
       snprintf(ms, sizeof(ms), "%u pts",
                (unsigned)((pts_now / PET_MILESTONE_STEP) * PET_MILESTONE_STEP));
       pet_react(PET_MILESTONE, now, "milestone", ms);
     }
     prev_milestone_pts = pts_now;
 
     if      (g_toast_active)         { /* a reminder toast owns the screen — hold its frame */ }
     else if (g_view == VIEW_HOME)    render_home();      // live clock/points/battery
     else if (g_view == VIEW_FINDER) {                   // live: keep the page clamped as peers move
       g_finder_pages = finder_pages(n);
       if (g_finder_page >= g_finder_pages) g_finder_page = g_finder_pages - 1;
       display_peers(g_handle, snap, n, g_finder_rssi, mult, g_finder_page);
     }
     else if (g_view == VIEW_POINTS)  render_points();   // passes the history graph
     else if (g_view == VIEW_FRIENDS) render_friends();
     else if (g_view == VIEW_BATTERY) render_battery();
     else if (g_view == VIEW_OPTIONS && g_opt_screen == OPT_PET) render_pet();  // live pet reactions
   }
 
   delay(10);
 }