# V3-11 — Offline tile pre-download **Phase** Ride management · **Depends on** V3-04 · **Size** M · **Status** Partially done ## Goal Have map tiles available where there is no signal. ## Context `flutter_map` caches what it renders, so a re-viewed ride works. A **mountain ride with no signal shows blank tiles** — precisely where a map is most wanted. ## Design **Respect OSM's tile usage policy. Bulk prefetching their public servers is prohibited** and would get the app blocked. This constraint decides the design: - Pre-download only a **user-chosen area**, at a **limited zoom range**, with a visible tile count and size estimate before starting - Rate-limited, sequential, cancellable - If this becomes a headline feature, move to a paid tile provider or self-hosted tiles. Do not scale it on OSM's donated infrastructure. Natural pairing with V3-07: pre-download the corridor along a planned route rather than a rectangle — far fewer tiles for the same usefulness. ## Implementation 1. Persistent tile cache with a size cap and eviction (`flutter_map_cache` or similar) 2. Area selection on the map, plus a "download along this route" option 3. Tile count and MB estimate **before** any request 4. Sequential fetch with a delay, a progress indicator and cancellation 5. Settings: cache size, and a way to clear it ## Acceptance criteria - [ ] A downloaded area renders with the network off - [ ] Count and size shown before download starts - [ ] Cancellable mid-download, keeping what has already arrived - [ ] A hard cap on tiles per request — no unbounded area selection - [ ] Cache size visible and clearable ## Tests - Tile-count maths for a bounding box across zoom levels - Cache eviction at the cap - Cancellation leaves a consistent cache - **Manual:** aeroplane mode over a downloaded area ## Risks - **Abusing OSM's servers.** Cap, rate-limit, and be conservative. A blocked user agent would break the map for everyone. - Storage growth. Tiles add up fast; the cap is not optional. ## Out of scope Vector tiles or a full offline basemap. ## Outcome The download pipeline is done and unit-tested end to end; the on-device acceptance criterion (aeroplane mode over a downloaded area) is not, and can't be from here. **Deliberate scope reduction: no rectangle area-selection UI.** The ticket names the route-corridor pairing with V3-07 as strictly better ("far fewer tiles for the same usefulness") and V3-07 already shipped, so that became the only download entry point rather than building two. `tilesAlongRoute` buffers each waypoint by a fixed radius and unions the per-point tile sets — a zigzagging route's actual footprint, not the rectangle around its bounding box, proven directly in `tile_math_test.dart` by constructing a route that zigzags across its own bounding box and asserting the corridor costs fewer tiles than that box would. Three pure modules, layered the way `geo.dart`/`ride_statistics.dart` already are in this codebase: `tile_math.dart` (tile enumeration, a hard `maxTilesPerDownload` cap enforced by *throwing* rather than silently truncating — a caller must know a download was rejected, not receive a partial one unknowingly), `tile_cache.dart` (`FileTileCache`: tiles as files on disk, a JSON manifest tracking size and last-access time, LRU eviction that runs *before* a write that would exceed the cap, not after), and `tile_downloader.dart` (sequential, rate-limited via a fixed delay between tiles, cooperatively cancellable via `CancelToken`, one bad tile doesn't abort the rest, everything fetched before cancellation stays in the cache). `CachedTileProvider` wires the cache into `flutter_map`'s `TileLayer` via a custom `ImageProvider` (cache hit skips the network entirely; a miss fetches, writes through, then decodes) and is now what `RideMap` and `RoutePlannerScreen` both request tiles through — a write-through side effect of this ticket is that ordinary map viewing now also populates the same capped, evictable cache, replacing flutter_map's own uncapped default. `RoutePlannerScreen` gained a download action (disabled with an explanatory tooltip when the route has no pins yet), a count-and-MB-estimate confirmation dialog before any request goes out, and a progress dialog with a working Cancel button. One real bug caught before it shipped: the first draft of the progress dialog used a bare `StatefulBuilder`, whose builder callback re-runs on every `setState` — meaning every single progress tick would have started a *second* overlapping download subscription. Fixed by moving the subscription into a dedicated `_DownloadDialog` `StatefulWidget` that starts it once, in `initState`. Settings gained an "Offline tiles" section: current cache size against the fixed cap, and a Clear button. The cap itself (200 MB) is **not** user-configurable in this pass — only whether to clear it — a scope call in the same spirit as the ticket's "the cap is not optional" risk language. **Not done, and cannot be done in this environment:** the ticket's own two headline acceptance criteria — a downloaded area actually rendering with the network off, and aeroplane-mode verification on a real device — both need a phone. Everything upstream of that (the tile math, the eviction policy, the cancellation-consistency of the cache, and the fact that a cache hit in `CachedTileProvider` skips the network call entirely by construction) is proven at the unit level; only the last mile — a real radio actually turned off — is not. 21 new tests: 8 in `tile_math_test.dart`, 8 in `tile_cache_test.dart` (round-trip, miss, size accounting, LRU eviction order, cap never exceeded across many writes, clear, and a cache re-opened over the same directory seeing prior contents), 4 in `tile_downloader_test.dart` (sequential/in-order/no-duplicates, one failure doesn't abort the rest, cancellation keeps a consistent partial cache, empty input is a no-op), 2 in `route_planner_screen_test.dart` (download disabled with no pins; count/size shown before any request — deliberately stopping short of confirming, since the pure download engine already covers the fetch/cancel/cache-consistency behaviour directly with fakes, and exercising it again through a real `http.Client` in a widget test would need a fake HTTP layer for no additional coverage). `flutter analyze` clean; full suite green (305 tests, up from 284).