fix: stop truncated pagination from skipping chapter pages

Neighbor preloads no longer cancel in-flight layout; incomplete
progressive results are fully re-paginated and not cached. Page-turn
commit clamps indices so a one-page leftover cannot jump chapters.

Author: leetomlee123

lib/model/reader/chapter_content_loader.dart

@@ -149,9 +149,15 @@ class ChapterContentLoader {
             'native=${BookPager.isAvailable}',
       );
     } else {
+      var layoutComplete = false;
       try {
-        final outcome = await _paginator.paginateProgressive(r);
+        // Neighbor preloads must not cancel each other / the open chapter.
+        final outcome = await _paginator.paginateProgressive(
+          r,
+          cancelPrevious: false,
+        );
         r.pages = outcome.pages;
+        layoutComplete = outcome.complete;
         debugPrint(
           '[PagerEngine] progressive engine=${outcome.engine} '
           'pages=${r.pages.length} complete=${outcome.complete} '
@@ -162,25 +168,41 @@ class ChapterContentLoader {
           'progressive engine=${outcome.engine} pages=${r.pages.length} '
               'complete=${outcome.complete} reason=${outcome.fallbackReason ?? "-"}',
         );
+        // Incomplete progressive results (cancelled mid-chapter) must not be
+        // treated as final layout — one-page leftovers make "next" jump chapters.
+        if (!outcome.complete) {
+          AppLog.w(
+            'Pager',
+            'progressive incomplete idx=$idx pages=${r.pages.length} '
+                '→ full re-paginate',
+          );
+          r.pages = await _paginator.paginate(r);
+          layoutComplete = r.pages.isNotEmpty;
+        }
       } catch (e, st) {
         AppLog.e('Read', 'paginateProgressive failed idx=$idx',
             error: e, stackTrace: st);
         r.pages = const [];
+        layoutComplete = false;
       }
 
       if (r.pages.isEmpty) {
         try {
           r.pages = await _paginator.paginate(r);
+          layoutComplete = r.pages.isNotEmpty;
         } catch (e, st) {
           AppLog.e('Read', 'parseContentAsync retry failed idx=$idx',
               error: e, stackTrace: st);
         }
         if (r.pages.isEmpty) {
           r.pages = fallbackPages(r.chapterContent);
+          layoutComplete = r.pages.isNotEmpty;
         }
       }
 
-      if (r.pages.isNotEmpty &&
+      // Only persist complete layouts — never cache a truncated first page.
+      if (layoutComplete &&
+          r.pages.isNotEmpty &&
           contentSource != 'fail' &&
           contentSource != 'network-error-text' &&
           !r.chapterContent.startsWith('章节内容加载失败')) {

lib/model/reader/page_picture_resolver.dart

@@ -118,18 +118,25 @@ class PagePictureResolver {
     final current = curPageOf();
     if (b == null || current == null) return null;
     final i = b.pageIndex - 1;
-    final key = _key(b.id, b.chapterIndex, i);
-    if (cache.containsKey(key)) return cache[key];
+    final inChapter = i >= 0;
 
-    final sw = kDebugMode ? (Stopwatch()..start()) : null;
-    final ui.Picture pic;
-    if (i < 0) {
-      final previous = prePageOf();
+    final String key;
+    final previous = inChapter ? null : prePageOf();
+    if (inChapter) {
+      key = _key(b.id, b.chapterIndex, i);
+    } else {
       if (previous == null || previous.pages.isEmpty) {
         _log('miss previous (no pre chapter)');
         return null;
       }
-      pic = drawContent(previous, previous.pageOffsets - 1);
+      key = _key(b.id, b.chapterIndex - 1, previous.pageOffsets - 1);
+    }
+    if (cache.containsKey(key)) return cache[key];
+
+    final sw = kDebugMode ? (Stopwatch()..start()) : null;
+    final ui.Picture pic;
+    if (!inChapter) {
+      pic = drawContent(previous!, previous.pageOffsets - 1);
     } else {
       pic = drawContent(current, i);
     }
@@ -171,12 +178,21 @@ class PagePictureResolver {
     final current = curPageOf();
     if (b == null || current == null) return null;
     final i = b.pageIndex + 1;
-    final key = _key(b.id, b.chapterIndex, i);
+    final inChapter = i >= 0 && i < current.pageOffsets;
+
+    // Cross-chapter next must use the next chapter's key — never store chapter
+    // N+1 page 0 under `book|N|pageOffsets` (pollutes cache / confuses warm).
+    final String key;
+    if (inChapter) {
+      key = _key(b.id, b.chapterIndex, i);
+    } else {
+      key = _key(b.id, b.chapterIndex + 1, 0);
+    }
     if (cache.containsKey(key)) return cache[key];
 
     final sw = kDebugMode ? (Stopwatch()..start()) : null;
     final ui.Picture pic;
-    if (i >= current.pageOffsets) {
+    if (!inChapter) {
       final following = nextPageOf();
       if (following == null) {
         final target = b.chapterIndex + 1;

lib/model/reader/page_turn_committer.dart

@@ -54,24 +54,49 @@ class PageTurnCommitter {
     final dir = (offsetDifference is num)
         ? offsetDifference.toDouble()
         : double.tryParse(offsetDifference?.toString() ?? '') ?? 0;
+    if (dir == 0) return;
     final beforeCur = b.chapterIndex;
     final beforeIdx = b.pageIndex;
     final idx = b.pageIndex;
     final chapters = chaptersOf();
     final curLen = curPageOf()?.pageOffsets ?? 0;
 
-    if (idx == curLen - 1 && dir > 0) {
-      _turnToNextChapter(b, chapters, beforeCur, beforeIdx, dir, curLen);
+    // No laid-out pages yet — never treat as "last page → next chapter".
+    if (curLen <= 0) {
+      if (kDebugMode) {
+        debugPrint(
+          '[ReadModel] commitPageTurn ignored (no pages) '
+          '$beforeCur:$beforeIdx dir=$dir',
+        );
+      }
       return;
     }
-    if (idx == 0 && dir < 0) {
-      _turnToPreviousChapter(b, beforeCur, beforeIdx, dir);
-      return;
+
+    // Clamp a stale index before deciding chapter vs in-chapter turn.
+    final safeIdx = idx < 0 ? 0 : (idx >= curLen ? curLen - 1 : idx);
+    if (safeIdx != idx) {
+      b.pageIndex = safeIdx;
+      if (kDebugMode) {
+        debugPrint(
+          '[ReadModel] commitPageTurn clamp index $idx → $safeIdx '
+          '(pages=$curLen)',
+        );
+      }
     }
+
     if (dir > 0) {
-      b.pageIndex += 1;
+      // Only leave the chapter from its real last page.
+      if (safeIdx >= curLen - 1) {
+        _turnToNextChapter(b, chapters, beforeCur, safeIdx, dir, curLen);
+        return;
+      }
+      b.pageIndex = safeIdx + 1;
     } else {
-      b.pageIndex -= 1;
+      if (safeIdx <= 0) {
+        _turnToPreviousChapter(b, beforeCur, safeIdx, dir);
+        return;
+      }
+      b.pageIndex = safeIdx - 1;
     }
     if (kDebugMode) {
       debugPrint(

lib/model/reader/text_paginator.dart

@@ -75,9 +75,17 @@ class TextPaginator {
     bool shouldJustifyHeight = false,
     void Function(List<TextPage> pages, bool complete)? onProgress,
     bool firstPageFirst = true,
+    /// When true (default for explicit user actions like font change), cancel
+    /// any in-flight progressive job. Neighbor preloads pass false so they
+    /// do not abort the chapter currently being laid out.
+    bool cancelPrevious = true,
   }) async {
-    cancelActive();
+    if (cancelPrevious) {
+      cancelActive();
+    }
     final jobId = _nextJobId++;
+    // Track latest job for cancelActive(); concurrent neighbor jobs keep their
+    // own jobId and only stop if explicitly cancelled or superseded.
     _activeJobId = jobId;
 
     final p = layoutParams(shouldJustifyHeight: shouldJustifyHeight);