fix(reader): never lose reading time — deep-sleep commit + incremental save + drop 10s floor

Ports the applicable subset of dawsonfi/aalu's (MIT) reading-stats
correctness fixes into our architecture. Three bugs in the stock
session-tracking path:

  1. Deep-sleep didn't commit the reader's session. enterDeepSleep
     called activityManager.goToSleep() which deferred the replace
     (and therefore the reader's onExit) until the next loop tick —
     but the hardware deep-sleep entry ran immediately after, so the
     transition never fired. Every minute spent reading since the
     last onExit was lost on each power-off.

  2. A brown-out, hard hang, or sudden battery cut also lost the
     whole session. stats.bin was only written at onExit, never
     during reading.

  3. Sessions under 10 seconds discarded reading time entirely
     (floor-gated at 10s for totalReadingSeconds). Users who do many
     short reads accumulated nothing.

Fixes:

  - New Activity::onBeforeDeepSleep() virtual + ActivityManager::
    notifyBeforeDeepSleep() that fans out to current + stacked. Wired
    into main.cpp::enterDeepSleep BEFORE the hardware sleep call so
    the reader commits its session before powering off.

  - EpubReaderActivity::commitReadingSession() — idempotent helper
    that banks elapsed time from the current segment (segment anchor
    resets after commit so successive commits don't double-count).
    Replaces the inline onExit() calculation and is shared with
    onBeforeDeepSleep + the incremental-save tick.

  - 60s incremental save in EpubReaderActivity::loop() — every minute
    of reading, commitReadingSession flushes to stats.bin. Worst-case
    loss on hard crash drops from "entire session" to "<=1 minute".

  - Drop the 10s floor on totalReadingSeconds. All elapsed seconds
    add to lifetime totals; sessionCount still uses the 60s floor
    (only bumped once per open, even across multiple commits).

  - Live in-reader stats popup now adds `millis() - sessionSegmentStartMs`
    on top of saved stats instead of `millis() - sessionStartMs`.
    With incremental saves, the previously-banked time is already in
    stats — using sessionStartMs would double-count.

aalu's fixes #2 (don't walk progressPercent backwards) and #4
(beginSession doesn't overwrite progress) don't apply: our
architecture stores progress in a separate progress.bin file rather
than a progressPercent field in stats, and onEnter doesn't write
progress. Fix #5 (100%/99% off-by-one) doesn't appear to apply
either — our Epub::calculateProgress already does byte-weighted
cumulative-size math and reaches 1.0 at last-page/last-spine.

Author: imshentastic

src/activities/Activity.h

@@ -30,6 +30,13 @@ class Activity {
   virtual ~Activity() = default;
   virtual void onEnter();
   virtual void onExit();
+  // FlexBLE: called by main.cpp::enterDeepSleep BEFORE the hardware
+  // sleep enters. Activities can use this to commit in-flight state
+  // (reading sessions, draft inputs, etc.) that would otherwise be
+  // lost — the normal onExit() path doesn't fire when going to deep
+  // sleep, because the activity isn't being torn down; the chip is
+  // just being powered off. Default no-op.
+  virtual void onBeforeDeepSleep() {}
   virtual void loop() {}
 
   virtual void render(RenderLock&&) {}

src/activities/ActivityManager.cpp

@@ -275,6 +275,16 @@ ScreenshotInfo ActivityManager::getScreenshotInfo() const {
   return {};
 }
 
+void ActivityManager::notifyBeforeDeepSleep() {
+  // Forward to the current activity AND anything stacked underneath.
+  // The reader might not be the top of the stack (e.g. an action menu
+  // is open on top of it) but still wants its session committed.
+  if (currentActivity) currentActivity->onBeforeDeepSleep();
+  for (auto& stacked : stackActivities) {
+    if (stacked) stacked->onBeforeDeepSleep();
+  }
+}
+
 void ActivityManager::requestUpdate(bool immediate) {
   if (immediate) {
     if (renderTaskHandle) {

src/activities/ActivityManager.h

@@ -112,6 +112,10 @@ class ActivityManager {
   bool canSnapshotForSleepOverlay() const;
   bool skipLoopDelay() const;
   ScreenshotInfo getScreenshotInfo() const;
+  // FlexBLE: called from main.cpp::enterDeepSleep so the current
+  // activity can flush in-flight state (e.g. reader session time)
+  // before the chip powers off. See Activity::onBeforeDeepSleep().
+  void notifyBeforeDeepSleep();
 
   // If immediate is true, the update will be triggered immediately.
   // Otherwise, it will be deferred until the end of the current loop iteration.

src/activities/reader/EpubReaderActivity.cpp

@@ -242,6 +242,10 @@ void EpubReaderActivity::onEnter() {
   // Session count and reading time are committed on exit once thresholds are met.
   stats = BookReadingStats::load(epub->getCachePath());
   sessionStartMs = millis();
+  sessionSegmentStartMs = sessionStartMs;
+  totalSessionMsThisOpen = 0UL;
+  sessionCountedThisOpen = false;
+  lastIncrementalSaveMs = sessionStartMs;
 
   globalStats = GlobalReadingStats::load();
 
@@ -279,21 +283,10 @@ void EpubReaderActivity::onExit() {
   APP_STATE.readerActivityLoadCount = 0;
   APP_STATE.saveToFile();
 
-  // Commit session stats based on how long the session lasted.
-  // Sessions under 1 minute don't count toward session count or reading time.
-  // Sessions under 10 seconds don't add to reading time.
-  const unsigned long elapsedMs = millis() - sessionStartMs;
-  if (elapsedMs >= 60000UL) {
-    stats.sessionCount++;
-    globalStats.totalSessions++;
-  }
-  if (elapsedMs >= 10000UL) {
-    const uint32_t elapsedSecs = static_cast<uint32_t>(elapsedMs / 1000UL);
-    stats.totalReadingSeconds += elapsedSecs;
-    globalStats.totalReadingSeconds += elapsedSecs;
-  }
-  stats.save(epub->getCachePath());
-  globalStats.save();
+  // Commit any remaining session time. Idempotent — if a deep-sleep
+  // commit or incremental save already banked the current segment,
+  // commitReadingSession returns without double-counting.
+  commitReadingSession();
 
   BOOKMARKS.unload();
   section.reset();
@@ -336,13 +329,66 @@ void EpubReaderActivity::onExit() {
   }
 }
 
+void EpubReaderActivity::commitReadingSession() {
+  if (!epub) return;
+  // Bank elapsed time from the current segment. sessionSegmentStartMs
+  // is reset every time we commit so successive commits (incremental
+  // save, deep-sleep, onExit) don't double-add the same milliseconds.
+  const unsigned long now = millis();
+  const unsigned long segmentMs = now - sessionSegmentStartMs;
+  if (segmentMs == 0UL) return;
+  sessionSegmentStartMs = now;
+  totalSessionMsThisOpen += segmentMs;
+
+  // Session count: incremented at most once per open (when cumulative
+  // time crosses the 60s threshold). A book briefly tapped open
+  // doesn't bump the count; a long read commits exactly one +1 even
+  // if it spans multiple deep-sleep commits.
+  if (!sessionCountedThisOpen && totalSessionMsThisOpen >= 60000UL) {
+    stats.sessionCount++;
+    globalStats.totalSessions++;
+    sessionCountedThisOpen = true;
+  }
+
+  // Reading time: no longer floor-gated. Every banked ms adds to the
+  // lifetime totals (was previously gated at 10 s, which silently
+  // discarded short reads — particularly bad for users who do
+  // many <10s sessions, e.g. mid-session deep-sleep cycles).
+  const uint32_t elapsedSecs = static_cast<uint32_t>(segmentMs / 1000UL);
+  if (elapsedSecs > 0) {
+    stats.totalReadingSeconds += elapsedSecs;
+    globalStats.totalReadingSeconds += elapsedSecs;
+  }
+
+  stats.save(epub->getCachePath());
+  globalStats.save();
+}
+
+void EpubReaderActivity::onBeforeDeepSleep() {
+  // Same commit path as onExit, but the activity STAYS alive (just
+  // gets put to sleep alongside the chip). When the device wakes,
+  // session-resume continues from the saved progress.bin position
+  // and a fresh session segment begins.
+  commitReadingSession();
+}
+
 void EpubReaderActivity::loop() {
   if (!epub) {
     // Should never happen
     finish();
     return;
   }
 
+  // Incremental session save. Without this, a brown-out / hard crash
+  // mid-reading loses ALL accumulated time since onEnter (or the last
+  // commit). With it, worst-case loss is kIncrementalSaveMs. The cost
+  // is small: one SD write per minute of reading.
+  constexpr unsigned long kIncrementalSaveMs = 60000UL;  // 1 min
+  if (millis() - lastIncrementalSaveMs >= kIncrementalSaveMs) {
+    commitReadingSession();
+    lastIncrementalSaveMs = millis();
+  }
+
   if (completionPromptQueued) {
     completionPromptQueued = false;
     completionPromptShown = true;
@@ -842,9 +888,13 @@ void EpubReaderActivity::onReaderMenuConfirm(EpubReaderMenuActivity::MenuAction
       break;
     }
     case EpubReaderMenuActivity::MenuAction::READING_STATS: {
-      // Include elapsed time from the current session in the display stats.
+      // Include elapsed time from the CURRENT (uncommitted) session
+      // segment on top of what's been banked into stats. Previously
+      // banked segments are already in `stats.totalReadingSeconds`
+      // because commitReadingSession persists them incrementally —
+      // adding `millis() - sessionStartMs` would double-count.
       BookReadingStats displayStats = stats;
-      displayStats.totalReadingSeconds += static_cast<uint32_t>((millis() - sessionStartMs) / 1000UL);
+      displayStats.totalReadingSeconds += static_cast<uint32_t>((millis() - sessionSegmentStartMs) / 1000UL);
       startActivityForResult(
           std::make_unique<BookStatsActivity>(renderer, mappedInput, epub->getPath(), epub->getTitle(),
                                               epub->getThumbBmpPath(), displayStats, globalStats),

src/activities/reader/EpubReaderActivity.h

@@ -32,6 +32,20 @@ class EpubReaderActivity final : public Activity {
   BookReadingStats stats;
   GlobalReadingStats globalStats;
   unsigned long sessionStartMs = 0UL;
+  // Wall-clock anchor for the current "session segment" — reset by
+  // commitReadingSession every time it banks elapsed time so we don't
+  // double-count across deep-sleep / shutdown commits.
+  unsigned long sessionSegmentStartMs = 0UL;
+  // Cumulative session ms already banked into stats this opening. Used
+  // only to gate sessionCount (the +1 happens once per session ≥ 60s,
+  // even if multiple commits add up to >60s).
+  unsigned long totalSessionMsThisOpen = 0UL;
+  bool sessionCountedThisOpen = false;
+  // Wall-clock anchor for the periodic incremental save. Reading
+  // sessions that crash before onExit (e.g. brown-out, hard hang) used
+  // to lose ALL elapsed time. Now we flush every kIncrementalSaveMs
+  // milliseconds during loop() so worst-case loss is bounded.
+  unsigned long lastIncrementalSaveMs = 0UL;
   // Signals that the next render should reposition within the newly loaded section
   // based on a cross-book percentage jump.
   bool pendingPercentJump = false;
@@ -89,6 +103,12 @@ class EpubReaderActivity final : public Activity {
   SavedPosition savedPositions[MAX_FOOTNOTE_DEPTH] = {};
   int footnoteDepth = 0;
 
+  // Banks elapsed time from `sessionSegmentStartMs` into stats.bin +
+  // GlobalReadingStats and resets the anchor so subsequent calls don't
+  // double-count. Idempotent: a 0-ms segment is a no-op. Called from
+  // onExit, onBeforeDeepSleep, and the incremental save tick.
+  void commitReadingSession();
+
   void renderContents(std::unique_ptr<Page> page, int orientedMarginTop, int orientedMarginRight,
                       int orientedMarginBottom, int orientedMarginLeft);
   void renderStatusBar() const;
@@ -124,6 +144,11 @@ class EpubReaderActivity final : public Activity {
       : Activity("EpubReader", renderer, mappedInput), epub(std::move(epub)) {}
   void onEnter() override;
   void onExit() override;
+  // Banks the current reading session into stats before the device
+  // powers off. Without this, time read since the last commit was
+  // lost — onExit only fires on explicit activity transitions, and
+  // hardware deep-sleep skips that path. Idempotent with onExit.
+  void onBeforeDeepSleep() override;
   void loop() override;
   void render(RenderLock&& lock) override;
   bool preventAutoSleep() override { return automaticPageTurnActive; }

src/main.cpp

@@ -526,6 +526,14 @@ void enterDeepSleep() {
   APP_STATE.lastSleepFromReader = activityManager.isReaderActivity();
   APP_STATE.saveToFile();
 
+  // FlexBLE: give the current activity a chance to flush in-flight
+  // state (most importantly: the reader's accumulated session time)
+  // before the chip powers off. Without this hook, every minute spent
+  // reading since the last natural activity-exit was lost on each
+  // deep-sleep cycle. Ported in spirit from dawsonfi/aalu's
+  // ReadingStatsManager::endSession deep-sleep wiring.
+  activityManager.notifyBeforeDeepSleep();
+
   // Disable BLE before deep sleep so the NimBLE host shuts down cleanly and
   // the radio is released before the chip powers off. Idempotent if BLE was
   // already off (reader exit path) — defensive against the auto-sleep timer