V3-11: offline tile pre-download along a route corridor

Three pure modules: tile_math.dart (tilesForBounds/tilesAlongRoute, hard cap enforced by throwing), tile_cache.dart (FileTileCache with LRU eviction before any write that would exceed the cap), tile_downloader.dart (sequential, rate-limited, cooperatively cancellable, one bad tile doesn't abort the rest). CachedTileProvider wires the cache into flutter_map via a custom ImageProvider and now backs RideMap and RoutePlannerScreen's tile layers, so ordinary viewing write-throughs into the same capped cache.

RoutePlannerScreen gained a route-corridor download action (no rectangle-selection UI -- the ticket names the corridor as strictly better and V3-07 already exists to hang it off of), with a count/size confirmation before any request and a cancellable progress dialog. Fixed a real bug before shipping: a StatefulBuilder-based progress dialog would have started a new overlapping download subscription on every single progress tick; moved to a dedicated StatefulWidget that subscribes once in initState.

Marked partially done: aeroplane-mode verification on a real device is the ticket's own acceptance criterion and needs a phone this environment doesn't have.

test/route_planner_screen_test.dart

@@ -164,5 +164,42 @@ void main() {
 
       expect(find.textContaining('no longer exists'), findsOneWidget);
     });
+
+    screenTest('the offline-tiles download button is disabled with no pins '
+        '(V3-11)', (tester) async {
+      final id = await repo.createRoutePlan(1000);
+      await pumpMap(tester, host(RoutePlannerScreen(routeId: id)));
+
+      final button = tester.widget<IconButton>(
+        find.byKey(const Key('download-tiles')),
+      );
+      expect(button.onPressed, isNull);
+      expect(button.tooltip, contains('Add pins'));
+    });
+
+    screenTest('downloading shows a tile count and size estimate before any '
+        'request (V3-11)', (tester) async {
+      final id = await repo.createRoutePlan(1000);
+      await repo.addWaypoint(id, 51.0, -114.0);
+      await repo.addWaypoint(id, 51.01, -114.0);
+      await pumpMap(tester, host(RoutePlannerScreen(routeId: id)));
+
+      final button = tester.widget<IconButton>(
+        find.byKey(const Key('download-tiles')),
+      );
+      expect(button.onPressed, isNotNull);
+
+      await tester.tap(find.byKey(const Key('download-tiles')));
+      // Bounded, not pumpAndSettle: the confirmation dialog is safe to settle (no
+      // network involved yet), but this test stops before confirming, precisely to
+      // avoid needing a fake HTTP layer for what the pure downloadTiles/tile_cache/
+      // tile_math test suites already cover directly.
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 50));
+
+      expect(find.textContaining('Download'), findsWidgets);
+      expect(find.textContaining('tiles?'), findsOneWidget);
+      expect(find.textContaining('MB'), findsOneWidget);
+    });
   });
 }

test/tile_cache_test.dart

@@ -0,0 +1,92 @@
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:rippr/src/tiles/tile_cache.dart';
+import 'package:rippr/src/tiles/tile_math.dart';
+
+void main() {
+  late Directory tempDir;
+  late FileTileCache cache;
+
+  setUp(() async {
+    tempDir = await Directory.systemTemp.createTemp('rippr_tile_cache_test_');
+  });
+
+  tearDown(() async {
+    if (tempDir.existsSync()) tempDir.deleteSync(recursive: true);
+  });
+
+  Uint8List bytesOfSize(int n) => Uint8List.fromList(List.filled(n, 1));
+
+  test('a stored tile round-trips', () async {
+    cache = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+    const key = TileKey(12, 100, 200);
+
+    await cache.put(key, bytesOfSize(50));
+    final read = await cache.get(key);
+
+    expect(read, isNotNull);
+    expect(read!.length, 50);
+  });
+
+  test('a tile never written is a miss, not an error', () async {
+    cache = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+    expect(await cache.get(const TileKey(1, 1, 1)), isNull);
+  });
+
+  test('sizeBytes reflects everything stored', () async {
+    cache = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+    await cache.put(const TileKey(1, 0, 0), bytesOfSize(100));
+    await cache.put(const TileKey(1, 0, 1), bytesOfSize(200));
+
+    expect(await cache.sizeBytes(), 300);
+  });
+
+  test('eviction at the cap removes the least-recently-used tile first', () async {
+    // Room for two 100-byte tiles at a time.
+    cache = FileTileCache(directory: tempDir, maxBytes: 200);
+    const a = TileKey(1, 0, 0);
+    const b = TileKey(1, 0, 1);
+    const c = TileKey(1, 0, 2);
+
+    await cache.put(a, bytesOfSize(100));
+    await cache.put(b, bytesOfSize(100));
+    // Touch `a` so `b` becomes the least-recently-used.
+    await cache.get(a);
+    await cache.put(c, bytesOfSize(100));
+
+    expect(await cache.get(a), isNotNull, reason: 'recently touched, must survive');
+    expect(await cache.get(b), isNull, reason: 'least-recently-used, must be evicted');
+    expect(await cache.get(c), isNotNull, reason: 'just written, must survive');
+    expect(await cache.sizeBytes(), lessThanOrEqualTo(200));
+  });
+
+  test('the cache never exceeds its cap after many writes', () async {
+    cache = FileTileCache(directory: tempDir, maxBytes: 500);
+    for (var i = 0; i < 20; i++) {
+      await cache.put(TileKey(1, i, 0), bytesOfSize(100));
+    }
+    expect(await cache.sizeBytes(), lessThanOrEqualTo(500));
+  });
+
+  test('clear removes every tile and resets size to zero', () async {
+    cache = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+    await cache.put(const TileKey(1, 0, 0), bytesOfSize(100));
+    await cache.put(const TileKey(1, 0, 1), bytesOfSize(100));
+
+    await cache.clear();
+
+    expect(await cache.sizeBytes(), 0);
+    expect(await cache.get(const TileKey(1, 0, 0)), isNull);
+  });
+
+  test('a cache re-opened over the same directory sees what was stored', () async {
+    cache = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+    await cache.put(const TileKey(5, 10, 10), bytesOfSize(64));
+
+    final reopened = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+    expect(await reopened.get(const TileKey(5, 10, 10)), isNotNull);
+    expect(await reopened.sizeBytes(), 64);
+  });
+}

test/tile_downloader_test.dart

@@ -0,0 +1,106 @@
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:rippr/src/tiles/tile_cache.dart';
+import 'package:rippr/src/tiles/tile_downloader.dart';
+import 'package:rippr/src/tiles/tile_math.dart';
+
+void main() {
+  late Directory tempDir;
+  late FileTileCache cache;
+
+  setUp(() async {
+    tempDir = await Directory.systemTemp.createTemp('rippr_tile_downloader_test_');
+    cache = FileTileCache(directory: tempDir, maxBytes: 1024 * 1024);
+  });
+
+  tearDown(() async {
+    if (tempDir.existsSync()) tempDir.deleteSync(recursive: true);
+  });
+
+  List<TileKey> tiles(int n) => [for (var i = 0; i < n; i++) TileKey(1, i, 0)];
+
+  test('every tile is fetched exactly once and lands in the cache', () async {
+    final fetched = <TileKey>[];
+    final progress = await downloadTiles(
+      tiles: tiles(5),
+      cache: cache,
+      fetchTile: (key) async {
+        fetched.add(key);
+        return Uint8List.fromList([1, 2, 3]);
+      },
+      delay: Duration.zero,
+    ).toList();
+
+    expect(fetched, tiles(5), reason: 'sequential, in order, no duplicates');
+    expect(progress.last, isA<DownloadProgress>());
+    expect(progress.last.completed, 5);
+    expect(progress.last.isDone, isTrue);
+    for (final t in tiles(5)) {
+      expect(await cache.get(t), isNotNull);
+    }
+  });
+
+  test('one failing tile does not abort the rest', () async {
+    final progress = await downloadTiles(
+      tiles: tiles(4),
+      cache: cache,
+      fetchTile: (key) async {
+        if (key.x == 1) throw Exception('transient');
+        return Uint8List.fromList([1]);
+      },
+      delay: Duration.zero,
+    ).toList();
+
+    expect(progress.last.completed, 3);
+    expect(progress.last.failed, 1);
+    expect(progress.last.isDone, isTrue);
+    expect(await cache.get(const TileKey(1, 1, 0)), isNull);
+    expect(await cache.get(const TileKey(1, 0, 0)), isNotNull);
+    expect(await cache.get(const TileKey(1, 2, 0)), isNotNull);
+  });
+
+  test('cancelling mid-download keeps everything already fetched', () async {
+    final token = CancelToken();
+    final events = <DownloadProgress>[];
+
+    await for (final p in downloadTiles(
+      tiles: tiles(10),
+      cache: cache,
+      fetchTile: (key) async => Uint8List.fromList([1]),
+      cancelToken: token,
+      delay: Duration.zero,
+    )) {
+      events.add(p);
+      if (p.completed == 3) token.cancel();
+    }
+
+    final last = events.last;
+    expect(last.isDone, isFalse,
+        reason: 'stopped early -- fewer tiles than the total were fetched');
+    expect(last.completed, lessThan(10));
+
+    // Everything fetched before cancellation must still be in the cache -- a
+    // consistent partial cache, not rolled back to nothing.
+    for (var i = 0; i < last.completed; i++) {
+      expect(await cache.get(TileKey(1, i, 0)), isNotNull);
+    }
+  });
+
+  test('an empty tile list completes immediately with no fetch calls', () async {
+    var calls = 0;
+    final progress = await downloadTiles(
+      tiles: const [],
+      cache: cache,
+      fetchTile: (key) async {
+        calls++;
+        return Uint8List(0);
+      },
+    ).toList();
+
+    expect(calls, 0);
+    expect(progress.last.isDone, isTrue);
+    expect(progress.last.total, 0);
+  });
+}

test/tile_math_test.dart

@@ -0,0 +1,119 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:rippr/src/geo/geo.dart' show LatLon;
+import 'package:rippr/src/tiles/tile_math.dart';
+
+void main() {
+  group('tilesForBounds', () {
+    test('a single point covers exactly one tile per zoom level', () {
+      final tiles = tilesForBounds(
+        minLat: 51.0,
+        maxLat: 51.0,
+        minLon: -114.0,
+        maxLon: -114.0,
+        minZoom: 10,
+        maxZoom: 12,
+      );
+      // One tile at each of the three zoom levels.
+      expect(tiles.length, 3);
+      expect(tiles.map((t) => t.z).toSet(), {10, 11, 12});
+    });
+
+    test('the same box covers more tiles at a higher zoom', () {
+      final low = tilesForBounds(
+        minLat: 50.99,
+        maxLat: 51.01,
+        minLon: -114.01,
+        maxLon: -113.99,
+        minZoom: 10,
+        maxZoom: 10,
+      );
+      final high = tilesForBounds(
+        minLat: 50.99,
+        maxLat: 51.01,
+        minLon: -114.01,
+        maxLon: -113.99,
+        minZoom: 14,
+        maxZoom: 14,
+      );
+      expect(high.length, greaterThan(low.length));
+    });
+
+    test('throws rather than silently truncating past the cap', () {
+      expect(
+        () => tilesForBounds(
+          minLat: -80,
+          maxLat: 80,
+          minLon: -170,
+          maxLon: 170,
+          minZoom: 10,
+          maxZoom: 14,
+        ),
+        throwsA(isA<TooManyTilesException>()),
+      );
+    });
+
+    test('tiles are deduplicated across an overlapping request', () {
+      final tiles = tilesForBounds(
+        minLat: 51.0,
+        maxLat: 51.001,
+        minLon: -114.0,
+        maxLon: -113.999,
+        minZoom: 5,
+        maxZoom: 5,
+      );
+      // A Set literally cannot contain a duplicate; this documents the intent that
+      // adjacent/overlapping coverage collapses rather than being counted twice.
+      expect(tiles.toSet().length, tiles.length);
+    });
+  });
+
+  group('tilesAlongRoute', () {
+    test('costs far less than the bounding-box rectangle for a route that '
+        'zigzags across its own bounding box', () {
+      // A route that ping-pongs in latitude while advancing in longitude -- its
+      // bounding box is a full rectangle, but the corridor only has to cover the
+      // narrow path actually ridden through that rectangle.
+      final route = [
+        for (var i = 0; i <= 40; i++)
+          LatLon(51.0 + (i.isEven ? 0.0 : 0.3), -114.0 + i * 0.02),
+      ];
+
+      final corridor = tilesAlongRoute(
+        route,
+        minZoom: 12,
+        maxZoom: 12,
+        bufferMeters: 150,
+      );
+      final rectangle = tilesForBounds(
+        minLat: 51.0,
+        maxLat: 51.3,
+        minLon: -114.0,
+        maxLon: -113.2,
+        minZoom: 12,
+        maxZoom: 12,
+      );
+
+      expect(corridor.length, lessThan(rectangle.length),
+          reason: 'the whole point of a corridor is fewer tiles than the bounding box');
+    });
+
+    test('an empty route needs no tiles', () {
+      expect(tilesAlongRoute([], minZoom: 10, maxZoom: 12), isEmpty);
+    });
+
+    test('throws past the cap, same as tilesForBounds', () {
+      final route = [for (var i = 0; i < 500; i++) LatLon(i * 0.1 - 25, i * 0.1 - 25)];
+      expect(
+        () => tilesAlongRoute(route, minZoom: 12, maxZoom: 14, bufferMeters: 500),
+        throwsA(isA<TooManyTilesException>()),
+      );
+    });
+  });
+
+  group('estimatedSizeMb', () {
+    test('scales linearly with tile count', () {
+      expect(estimatedSizeMb(0), 0);
+      expect(estimatedSizeMb(1024, avgTileSizeKb: 1), closeTo(1.0, 1e-9));
+    });
+  });
+}