samplez/rippr-flutter-src/docs/ui-redesign/UI-02-offline-skeleton-map.md

# UI-02 — Offline / no-connection skeleton map

**Depends on** UI-01 · **Size** S · **Status** Done

## Goal
When the map has no tiles to show — no cached tiles for the current view and no network
to fetch fresh ones — show an animated skeleton in place of a broken or blank map, on
every tab, since UI-01 makes the map a permanent background presence rather than
something a rider opts into per-screen.

## Context
By explicit instruction: *"If we do not have connection for the map, we should just show
an animated skeleton map so it doesn't look weird."* Once UI-01 ships, the map is always
on screen somewhere — a blank grey rectangle or a grid of broken-image icons behind every
tab, all the time, on a phone with no signal, is a much worse look than it was when the
map only appeared on the one screen a rider explicitly opened.

This composes with existing infrastructure rather than duplicating it:
`CachedTileProvider` (V3-11) already tries the offline tile cache before the network, so
"no connection" in practice means *both* the cache and the network failed for the tiles
currently in view.

## Design
Detect at the `CachedTileProvider`/`TileLayer` level, not by asking the OS for
connectivity state directly — a connectivity API can report "online" while the actual
tile fetch still times out (captive portal, degraded connection), and the tile fetch's
own success/failure is the only thing that actually matters here.

- Track a rolling failure count for in-flight tile fetches (cache miss **and** network
  fetch failed) over a short window. Crossing a small threshold (e.g. 3 consecutive
  failures) flips the map into skeleton mode; a single successful fetch flips it back.
- Skeleton mode replaces the `TileLayer` with a static, non-fetching placeholder — never
  a widget that itself keeps trying and failing in a loop.
- Placeholder look: a shimmer/gradient-sweep animation over a neutral grid pattern
  (reuse the "technical grid overlay" treatment already present in the Stitch exports'
  `map-grid-overlay` CSS — 40px faint grid lines — as the static base under the shimmer),
  not a spinner. A map-shaped thing that is clearly still loading, not an error state.
- Recheck periodically (not on every frame) so the map recovers automatically the moment
  connectivity returns, without the rider having to do anything.

## Implementation
1. Wrap `CachedTileProvider` (or add a sibling) that reports fetch outcomes to a small
   `MapConnectivityState` — rolling window, threshold, debounced flip.
2. `SkeletonMapLayer` widget: the grid + shimmer, sized to fill the same space a
   `TileLayer` would.
3. `RideMap`/`PersistentMapBackground` (from UI-01) watches `MapConnectivityState` and
   swaps `TileLayer` for `SkeletonMapLayer` when in skeleton mode — markers/polylines
   (the rider's own path, planned route) keep rendering on top either way, since those
   come from local data, not tiles.
4. A cap on retry frequency while in skeleton mode — this must not turn into a tile-
   fetch retry loop that itself violates OSM's usage policy the way V3-11's design
   explicitly guards against.

## Acceptance criteria
- [ ] With no cached tiles and no network, the map area shows an animated skeleton, not
      blank space or broken-image icons
- [ ] Recovery is automatic: once tiles become fetchable again, the skeleton is replaced
      without user action
- [ ] The rider's live position/path and any planned route still render on top of the
      skeleton (only the base tiles are missing)
- [ ] Skeleton mode does not itself hammer the tile server with retries
- [ ] Behaves correctly across all four tabs (UI-01's shared background map), not just
      the Map tab

## Tests
- Unit: the failure-count/threshold/debounce logic that decides skeleton vs. live,
  exercised with fakes (no real network) — mirrors V3-11's `tile_downloader_test.dart`
  pattern of injecting fake fetch outcomes
- Widget: `SkeletonMapLayer` renders when connectivity state says offline; `TileLayer`
  renders when it says online
- Widget: markers/polylines still render in skeleton mode

## Risks
- Flapping between skeleton and live on a marginal connection would be worse than
  either state alone — the debounce window is what prevents this; tune it based on real
  behavior, not a guess (echoes V3-13's "measure, don't tune blind" discipline).
- Must not let skeleton-mode retries become the kind of bulk/rapid tile request V3-11's
  design explicitly exists to avoid.

## Out of scope
General offline-mode UX beyond the map itself (e.g. graying out map-dependent buttons).
Manual retry controls — automatic recovery is the whole point.

## Outcome

Built exactly to the ticket's Design section. `lib/src/tiles/map_connectivity.dart`'s
`MapConnectivityState` tracks consecutive tile-fetch failures (`skeletonFailureThreshold
= 3`), flips to skeleton mode on the threshold, and recovers instantly on a single
success — either an ordinary fetch succeeding (while still below threshold, resetting
the run) or, once already in skeleton mode, a periodic single-tile probe
(`skeletonProbeInterval = 15s`) succeeding. The probe is a deliberate design choice: once
skeleton mode starts, `RideMap`/the route planner fully unmount their `TileLayer` (no
ongoing requests at all, per the ticket's "never a widget that itself keeps trying and
failing in a loop"), so nothing generates ordinary fetch outcomes to recover from — the
probe exists specifically to test the water on the map's behalf, at a low, fixed
cadence, using one deterministic tile (the zoom-0 whole-world overview) rather than
whatever happened to be in view.

`CachedTileProvider` (`lib/src/tiles/cached_tile_provider.dart`) now takes an optional
`MapConnectivityState? connectivity` and reports outcomes around its network fetch only
— a cache hit is silently skipped since it says nothing about current connectivity
either way, matching the ticket's "cache miss *and* network fetch failed" definition of
a failure exactly. `mapConnectivityProvider` (`app/providers.dart`) is the one shared
instance every map watches, per the class's own reasoning: connectivity is a fact about
the network, not about which map widget happens to be on screen.

`SkeletonMapLayer` (`lib/src/ui/components/skeleton_map_layer.dart`) is the 40px faint
grid (reusing the Stitch exports' `.map-grid-overlay` treatment directly, `rgba(255,255,
255,0.03-0.05)` → `Color(0x0DFFFFFF)`) with a `LinearGradient` shimmer sweeping across it
on a 1800ms repeating cycle, painted via `ShaderMask`/`CustomPainter` rather than a
translated widget so it doesn't need to know its own pixel size. `RideMap` gained a
`skeletonMode` bool (a plain constructor param, not a `ConsumerWidget` watch — consistent
with how `tileProvider` is already handed down rather than looked up) that swaps
`TileLayer` for `SkeletonMapLayer` while leaving `PolylineLayer`/markers untouched, since
those come from local data. The route planner manages its own independent `FlutterMap`
and does the same swap itself, watching `mapConnectivityProvider` directly.

**Refactor along the way:** moved `tileUrlTemplate`/`tileSubdomains`/`tileMaxNativeZoom`/
`tileUserAgent` out of `ride_map.dart` into a new `lib/src/tiles/tile_config.dart`, and
had `ride_map.dart` re-export them for its existing importers. `app/providers.dart` (the
composition root) needed these constants for the connectivity probe's URL, and importing
a `ui/` file from the `app/` layer would have been a real layering violation the tiles
layer itself doesn't have a reason to accept — better to give the constants a home in
the layer they actually describe (tile fetching) than to route around the smell.

**Bug caught by the first real test run:** `mapConnectivityProvider`'s initial
implementation called `ref.onDispose(state.dispose)` in addition to
`ChangeNotifierProvider`'s own automatic disposal of the notifier it returns — a
double-dispose that threw "A MapConnectivityState was used after being disposed" and
failed five `route_planner_screen_test.dart` tests outright. Fixed by removing the
redundant manual dispose call.

**Tests:** `flutter analyze` clean. `flutter test` green at 328 tests (316 + 3 new
`ride_map_test.dart` skeleton-mode cases + 9 new `map_connectivity_test.dart` unit cases
covering threshold behavior, the reset-on-success case, notification-only-on-actual-
change, and the probe loop's recovery and its refusal to run at all while still live).

**Android emulator verification** (`Medium_Phone_API_35`) — a full end-to-end real-
network test, not just widget tests: cut the emulator's actual network
(`svc wifi disable` + `svc data disable`, confirmed via a failing `ping`), cleared the
offline tile cache via Settings, and navigated to an uncached view (the route planner's
default zoom-14 view, which the shell's already-cached Calgary-area background tiles
didn't cover). After the threshold of real failed fetches, the skeleton grid rendered
correctly — clearly a "still loading" placeholder, not blank space or broken-image
icons. Re-enabled the network and confirmed automatic recovery within one probe interval
with no user action, exactly per the acceptance criteria. The shared shell background
map (already displaying previously-cached tiles from memory) was unaffected throughout,
as expected since it never needed a fresh fetch during the test window.