refactor(puzzle): isolate offline queue fill from the solve loop

Address review feedback on #3454. The previous approach tangled a background
fill into the solve/sync path, where the single-flight guard was inert (the
controller builds a fresh PuzzleService per call) and a within-pass stale
solve snapshot could clobber offline results.

- Revert the sync path to the original single-request logic, unchanged.
- Add PuzzleQueueFiller: a stable NotifierProvider that fills the offline
  queue to the configured count with sequential, single-flight, select-only
  requests. Re-reads storage each pass, dedups by id, never submits solves,
  and is safe offline.
- Trigger the fill as a one-time action on the offline-count setting change
  and on difficulty change, with a spinner on the settings tile while running.
- Raise the minimum offline queue to 100 (and the default to 100) per review.

Tests: PuzzleQueueFiller covered in isolation (fill-to-count over multiple
requests, deficit-only, no-op when full, server-exhausted stop, offline-safe,
select-only, single-flight). Screen test asserts the settings change triggers
the fill. Removed the obsolete background-fill service tests.

Author: HermesCoder

lib/src/model/puzzle/puzzle_controller.dart

@@ -15,6 +15,7 @@ import 'package:lichess_mobile/src/model/common/uci.dart';
 import 'package:lichess_mobile/src/model/puzzle/puzzle.dart';
 import 'package:lichess_mobile/src/model/puzzle/puzzle_difficulty.dart';
 import 'package:lichess_mobile/src/model/puzzle/puzzle_preferences.dart';
+import 'package:lichess_mobile/src/model/puzzle/puzzle_queue_filler.dart';
 import 'package:lichess_mobile/src/model/puzzle/puzzle_repository.dart';
 import 'package:lichess_mobile/src/model/puzzle/puzzle_service.dart';
 import 'package:lichess_mobile/src/model/puzzle/puzzle_session.dart';
@@ -205,6 +206,15 @@ class PuzzleController extends Notifier<PuzzleState> {
 
     state = state.copyWith(isChangingDifficulty: false);
 
+    // Difficulty invalidates the queue, so resetBatch only refetched one batch
+    // (capped at 50 by the server). Top the queue back up to the configured
+    // count in the background, matching the settings-change behaviour.
+    unawaited(
+      ref
+          .read(puzzleQueueFillerProvider.notifier)
+          .fill(userId: initialContext.userId, angle: initialContext.angle),
+    );
+
     return nextPuzzle;
   }
 

lib/src/model/puzzle/puzzle_preferences.dart

@@ -56,13 +56,13 @@ class PuzzlePreferences extends Notifier<PuzzlePrefs> with SessionPreferencesSto
 }
 
 /// Minimum number of puzzles kept in the offline queue.
-const kMinOfflinePuzzles = 50;
+const kMinOfflinePuzzles = 100;
 
 /// Maximum number of puzzles kept in the offline queue.
 const kMaxOfflinePuzzles = 500;
 
 /// Available choices for the size of the offline puzzle queue.
-const kOfflinePuzzlesChoices = [50, 100, 150, 200, 300, 500];
+const kOfflinePuzzlesChoices = [100, 150, 200, 300, 500];
 
 @Freezed(fromJson: true, toJson: true)
 sealed class PuzzlePrefs with _$PuzzlePrefs implements Serializable {
@@ -80,16 +80,16 @@ sealed class PuzzlePrefs with _$PuzzlePrefs implements Serializable {
     @Default(true) bool rated,
 
     /// Number of puzzles to keep downloaded in the offline queue.
-    /// Defaults to `50`.
-    @Default(50) int nbOfflinePuzzles,
+    /// Defaults to `100`.
+    @Default(100) int nbOfflinePuzzles,
   }) = _PuzzlePrefs;
 
   factory PuzzlePrefs.defaults({UserId? id}) => PuzzlePrefs(
     id: id,
     difficulty: PuzzleDifficulty.normal,
     autoNext: false,
     rated: true,
-    nbOfflinePuzzles: 50,
+    nbOfflinePuzzles: 100,
   );
 
   factory PuzzlePrefs.fromJson(Map<String, dynamic> json) => _$PuzzlePrefsFromJson(json);

lib/src/model/puzzle/puzzle_queue_filler.dart

@@ -0,0 +1,109 @@
+import 'dart:math' show max;
+
+import 'package:fast_immutable_collections/fast_immutable_collections.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:lichess_mobile/src/model/common/id.dart';
+import 'package:lichess_mobile/src/model/puzzle/puzzle_angle.dart';
+import 'package:lichess_mobile/src/model/puzzle/puzzle_batch_storage.dart';
+import 'package:lichess_mobile/src/model/puzzle/puzzle_preferences.dart';
+import 'package:lichess_mobile/src/model/puzzle/puzzle_repository.dart';
+import 'package:lichess_mobile/src/model/puzzle/puzzle_theme.dart';
+import 'package:lichess_mobile/src/network/http.dart';
+import 'package:logging/logging.dart';
+import 'package:meta/meta.dart';
+
+/// The server caps each batch request at 50 puzzles regardless of the requested
+/// `nb` (`nb.atMost(50)` in lila's `Puzzle` controller), so a queue larger than
+/// this is filled with several sequential requests, each asking for the current
+/// deficit and receiving at most 50.
+
+/// Whether a one-time offline-queue fill is currently running.
+///
+/// This is a top-level (stable) provider, not per-[PuzzleService] state, so the
+/// single-flight guard actually holds: the puzzle service factory builds a fresh
+/// service on every read, but this notifier is a single instance.
+final puzzleQueueFillerProvider = NotifierProvider<PuzzleQueueFiller, bool>(
+  PuzzleQueueFiller.new,
+  name: 'PuzzleQueueFillerProvider',
+);
+
+class PuzzleQueueFiller extends Notifier<bool> {
+  final Logger _log = Logger('PuzzleQueueFiller');
+
+  @override
+  bool build() => false;
+
+  /// Fills the offline queue for [angle] up to the configured
+  /// `nbOfflinePuzzles`, one server batch at a time.
+  ///
+  /// This is a one-time, select-only action triggered when the offline puzzle
+  /// count or the difficulty changes. It never submits solves, so it can't race
+  /// with the solve/sync path over the stored `solved` list. Re-reads storage
+  /// on every pass and merges by puzzle id so a solve made while the fill runs
+  /// is never clobbered. Guarded by [state] so overlapping calls can't
+  /// double-fetch. Never throws: network and storage failures stop the fill.
+  Future<void> fill({
+    required UserId? userId,
+    PuzzleAngle angle = const PuzzleTheme(PuzzleThemeKey.mix),
+    @visibleForTesting int? queueLengthOverride,
+  }) async {
+    if (state) return;
+    state = true;
+    try {
+      final queueLength =
+          queueLengthOverride ?? ref.read(puzzlePreferencesProvider).nbOfflinePuzzles;
+      final difficulty = ref.read(puzzlePreferencesProvider).difficulty;
+      final batchStorage = await ref.read(puzzleBatchStorageProvider.future);
+
+      // Tracks the stored queue length across passes. Stop when a pass fails to
+      // grow the queue (server exhausted or a silent no-op write), not when it
+      // shrinks: a solve made mid-fill lowers the count and legitimately widens
+      // the deficit, so that pass should still top up.
+      int lastLength = -1;
+      while (true) {
+        final current = await batchStorage.fetch(userId: userId, angle: angle);
+        final unsolved = current?.unsolved ?? IList(const []);
+
+        if (unsolved.length == lastLength) break;
+        lastLength = unsolved.length;
+
+        final deficit = max(0, queueLength - unsolved.length);
+        if (deficit <= 0) break;
+
+        final PuzzleBatchResponse response;
+        try {
+          response = await ref.withClient(
+            (client) => PuzzleRepository(
+              client,
+            ).selectBatch(nb: deficit, angle: angle, difficulty: difficulty),
+          );
+        } catch (e, st) {
+          // Offline or server error: stop the fill, keep what we have.
+          _log.warning('Offline puzzle queue fill failed', e, st);
+          break;
+        }
+
+        // Server has no more puzzles: stop rather than spin forever below an
+        // unreachable `queueLength`.
+        if (response.puzzles.isEmpty) break;
+
+        // Skip ids already stored so a re-read after a mid-fill solve can't
+        // reintroduce a duplicate.
+        final existingIds = unsolved.map((p) => p.puzzle.id).toISet();
+        final additions = response.puzzles.where((p) => !existingIds.contains(p.puzzle.id));
+        if (additions.isEmpty) break;
+
+        await batchStorage.save(
+          userId: userId,
+          angle: angle,
+          data: PuzzleBatch(
+            solved: current?.solved ?? IList(const []),
+            unsolved: IList([...unsolved, ...additions]),
+          ),
+        );
+      }
+    } finally {
+      state = false;
+    }
+  }
+}