perf: defer chapter-boundary paint work after page turns

Move prune/warm off the animation-complete path, clear rapid-tap queue
when crossing chapters, and avoid stacking picture recording on the
same frame as chapter swaps.

Author: leetomlee123

lib/model/read_model.dart

@@ -63,11 +63,13 @@ class ReadModel with ChangeNotifier {
     showLoading: _showTextLoading,
     hideLoading: _hideTextLoading,
     prunePictures: _prunePictureCache,
-    warmPictures: () => _pictures.warmAroundCurrent(),
+    warmPictures: ({bool deferHeavy = false}) =>
+        _pictures.warmAroundCurrent(deferHeavy: deferHeavy),
     scheduleProgressSave: () => scheduleProgressSave(),
     notify: notifyListeners,
     markNeedsPaint: _markNeedsPaint,
     activeBookId: () => book?.id,
+    clearQueuedTurns: () => pagePainter?.pageManager?.clearQueuedTurns(),
   );
   GlobalKey? canvasKey;
   final ReaderPainter _painter = ReaderPainter();

lib/model/reader/page_picture_resolver.dart

@@ -66,10 +66,42 @@ class PagePictureResolver {
 
   /// Eagerly paint current page (if missing) then schedule prev/next on the
   /// next frame so the first gesture never cold-records mid-drag.
-  void warmAroundCurrent({bool includeNeighbors = true}) {
+  ///
+  /// When [deferHeavy] is true, recording is postponed to the next frame so
+  /// chapter-boundary commits (animation status callbacks) stay jank-free.
+  /// Cache hits are still free either way.
+  void warmAroundCurrent({
+    bool includeNeighbors = true,
+    bool deferHeavy = false,
+  }) {
     final b = bookOf();
     final current = curPageOf();
     if (b == null || current == null || current.pages.isEmpty) return;
+    final key = _key(b.id, b.chapterIndex, b.pageIndex.clamp(0, current.pageOffsets - 1));
+    final cached = cache.containsKey(key);
+    if (cached) {
+      if (includeNeighbors) scheduleNeighborWarm();
+      return;
+    }
+    if (deferHeavy) {
+      final gen = ++_warmGeneration;
+      final bookId = b.id;
+      final chapter = b.chapterIndex;
+      final page = b.pageIndex;
+      SchedulerBinding.instance.addPostFrameCallback((_) {
+        if (gen != _warmGeneration) return;
+        if (activeBookId() != bookId) return;
+        final now = bookOf();
+        if (now == null ||
+            now.chapterIndex != chapter ||
+            now.pageIndex != page) {
+          return;
+        }
+        paintCurrent();
+        if (includeNeighbors) preloadNeighbors();
+      });
+      return;
+    }
     paintCurrent();
     if (includeNeighbors) {
       scheduleNeighborWarm();

lib/model/reader/page_turn_committer.dart

@@ -3,6 +3,7 @@ import 'package:book/entity/chapter_toc_entry.dart';
 import 'package:book/entity/read_page.dart';
 import 'package:bot_toast/bot_toast.dart';
 import 'package:flutter/foundation.dart';
+import 'package:flutter/scheduler.dart';
 
 /// Commits a logical page/chapter advance after a swipe or tap turn.
 ///
@@ -27,6 +28,7 @@ class PageTurnCommitter {
     required this.notify,
     required this.markNeedsPaint,
     required this.activeBookId,
+    this.clearQueuedTurns,
   });
 
   final Book? Function() bookOf;
@@ -42,12 +44,18 @@ class PageTurnCommitter {
   final void Function() hideLoading;
   final void Function() prunePictures;
   /// Warm current + schedule prev/next after page/chapter advance.
-  final void Function() warmPictures;
+  ///
+  /// [deferHeavy] postpones picture recording when the page is a cache miss
+  /// so animation-complete handlers do not hitch the UI thread.
+  final void Function({bool deferHeavy}) warmPictures;
   final void Function() scheduleProgressSave;
   final void Function() notify;
   final void Function() markNeedsPaint;
   final String? Function() activeBookId;
 
+  /// Drop queued rapid-taps when crossing a chapter so we don't cascade loads.
+  final void Function()? clearQueuedTurns;
+
   void commit(Object? offsetDifference) {
     final b = bookOf();
     if (b == null) return;
@@ -106,12 +114,25 @@ class PageTurnCommitter {
       );
     }
     // New current may already be cached from neighbor warm; schedule next ±1.
-    warmPictures();
+    warmPictures(deferHeavy: false);
     markNeedsPaint();
     notify();
     scheduleProgressSave();
   }
 
+  /// Prune + warm after the current frame so animation-complete stays smooth.
+  void _deferChapterHousekeeping({required int chapterAfter}) {
+    final bookId = activeBookId();
+    SchedulerBinding.instance.addPostFrameCallback((_) {
+      if (activeBookId() != bookId) return;
+      final b = bookOf();
+      if (b == null || b.chapterIndex != chapterAfter) return;
+      prunePictures();
+      // Cache hit for page 0 is free; miss records next frame (already post-frame).
+      warmPictures(deferHeavy: false);
+    });
+  }
+
   void _turnToNextChapter(
     Book b,
     List<ChapterTocEntry> chapters,
@@ -126,19 +147,34 @@ class PageTurnCommitter {
       return;
     }
 
+    // Rapid taps must not chain-load multiple chapters while this one settles.
+    clearQueuedTurns?.call();
+
     b.chapterIndex += 1;
     setPrePage(curPageOf());
     final following = nextPageOf();
-    if (following == null || following.chapterName == '-1') {
+    final needsLoad =
+        following == null || following.chapterName == '-1' || following.pages.isEmpty;
+    if (needsLoad) {
       showLoading('正在加载下一章…');
-      loadChapter(b.chapterIndex).then((value) {
-        if (activeBookId() == b.id) {
-          setCurPage(value);
-          warmPictures();
-          markNeedsPaint();
-          notify();
+      final target = b.chapterIndex;
+      final bookId = b.id;
+      loadChapter(target).then((value) {
+        if (activeBookId() != bookId) {
+          hideLoading();
+          return;
         }
+        final cur = bookOf();
+        if (cur == null || cur.chapterIndex != target) {
+          hideLoading();
+          return;
+        }
+        setCurPage(value);
+        // Defer paint — pagination just finished; don't stack record on same turn.
+        markNeedsPaint();
+        notify();
         hideLoading();
+        _deferChapterHousekeeping(chapterAfter: target);
       });
     } else {
       setCurPage(following);
@@ -149,21 +185,29 @@ class PageTurnCommitter {
       debugPrint(
         '[ReadModel] commitPageTurn +chapter '
         '$beforeCur:$beforeIdx → ${b.chapterIndex}:${b.pageIndex} '
-        'dir=$dir pages=$curLen',
+        'dir=$dir pages=$curLen ready=${!needsLoad}',
       );
     }
-    prunePictures();
-    warmPictures();
+    // Swap first; prune/paint after this frame (avoids anim-callback jank).
+    markNeedsPaint();
+    notify();
     scheduleProgressSave();
+    if (!needsLoad) {
+      _deferChapterHousekeeping(chapterAfter: b.chapterIndex);
+    }
+    final nextTarget = b.chapterIndex + 1;
+    final bookId = b.id;
     Future.delayed(const Duration(milliseconds: 500), () {
-      if (activeBookId() == b.id) {
-        loadChapter(b.chapterIndex + 1).then((value) {
-          if (activeBookId() == b.id) {
-            setNextPage(value);
-            warmPictures();
-          }
-        });
-      }
+      if (activeBookId() != bookId) return;
+      final cur = bookOf();
+      if (cur == null || cur.chapterIndex != nextTarget - 1) return;
+      loadChapter(nextTarget).then((value) {
+        if (activeBookId() != bookId) return;
+        final now = bookOf();
+        if (now == null || now.chapterIndex != nextTarget - 1) return;
+        setNextPage(value);
+        warmPictures(deferHeavy: true);
+      });
     });
   }
 
@@ -178,11 +222,13 @@ class PageTurnCommitter {
       BotToast.showText(text: '第一页');
       return;
     }
+    clearQueuedTurns?.call();
     final previous = prePageOf();
-    if (previous == null) {
+    if (previous == null || previous.pages.isEmpty) {
       showLoading('正在加载上一章…');
+      final bookId = b.id;
       loadChapter(tempCur).then((value) {
-        if (activeBookId() != b.id) {
+        if (activeBookId() != bookId) {
           hideLoading();
           return;
         }
@@ -191,16 +237,17 @@ class PageTurnCommitter {
         b.chapterIndex = tempCur;
         b.pageIndex = (curPageOf()?.pageOffsets ?? 1) - 1;
         setPrePage(null);
-        warmPictures();
         markNeedsPaint();
         notify();
         hideLoading();
-        prunePictures();
         scheduleProgressSave();
+        _deferChapterHousekeeping(chapterAfter: tempCur);
         loadChapter(b.chapterIndex - 1).then((v) {
-          if (activeBookId() == b.id) {
+          if (activeBookId() == bookId) {
+            final now = bookOf();
+            if (now == null || now.chapterIndex != tempCur) return;
             setPrePage(v);
-            warmPictures();
+            warmPictures(deferHeavy: true);
           }
         });
       });
@@ -210,7 +257,6 @@ class PageTurnCommitter {
     setCurPage(previous);
     b.chapterIndex -= 1;
     b.pageIndex = (curPageOf()?.pageOffsets ?? 1) - 1;
-    notify();
     setPrePage(null);
     if (kDebugMode) {
       debugPrint(
@@ -219,18 +265,23 @@ class PageTurnCommitter {
         'dir=$dir',
       );
     }
-    prunePictures();
-    warmPictures();
+    markNeedsPaint();
+    notify();
     scheduleProgressSave();
+    _deferChapterHousekeeping(chapterAfter: b.chapterIndex);
+    final prevTarget = b.chapterIndex - 1;
+    final bookId = b.id;
     Future.delayed(const Duration(milliseconds: 500), () {
-      if (activeBookId() == b.id) {
-        loadChapter(b.chapterIndex - 1).then((value) {
-          if (activeBookId() == b.id) {
-            setPrePage(value);
-            warmPictures();
-          }
-        });
-      }
+      if (activeBookId() != bookId) return;
+      final cur = bookOf();
+      if (cur == null || cur.chapterIndex != prevTarget + 1) return;
+      loadChapter(prevTarget).then((value) {
+        if (activeBookId() != bookId) return;
+        final now = bookOf();
+        if (now == null || now.chapterIndex != prevTarget + 1) return;
+        setPrePage(value);
+        warmPictures(deferHeavy: true);
+      });
     });
   }
 }

lib/view/page_turn/reader_page_manager.dart

@@ -71,6 +71,13 @@ class ReaderPageManager {
     return left.isNegative ? Duration.zero : left;
   }
 
+  /// Drop any queued rapid-tap intents (e.g. on chapter boundary).
+  void clearQueuedTurns() {
+    if (_queuedDirs.isEmpty) return;
+    _log('clearQueuedTurns dropped=$_queuedDirs');
+    _queuedDirs.clear();
+  }
+
   bool get _needsController =>
       currentAnimationType == TYPE_ANIMATION_COVER_TURN ||
       currentAnimationType == TYPE_ANIMATION_SIMULATION_TURN;