Animate the radar timeline with a double-buffered overlay
Completes milestone 3: frames render over the map, play as a loop, and can be scrubbed, with the legend drawn from the manifest rather than a constant that could drift from what the worker actually rendered. The overlay alternates two MapLibre image sources. Updating one source in place flickers, because the layer briefly shows a half-written texture; adding every frame as its own layer avoids that but pins them all in GPU memory, and twenty 512x512 RGBA frames is about 80 MB. Two buffers cost the same whether the timeline holds six frames or sixty. Platform-channel work is serialised because `show` is called faster than the round trip completes during playback, and overlapping updates would swap visibility out of order and strobe. Prefetching loads a window around the playhead, nearest first and forward before backward, since playback moves forward and that frame is needed soonest. `FrameCache` is byte-budgeted rather than entry-counted because frame size tracks how much precipitation is on screen, and it evicts by distance from the playhead: plain LRU would keep frames the prefetcher touched a moment ago even after the playhead moved to the far end of the timeline. Also adds DpcRadarSource, which reads published frames from our CDN and never from the DPC API. Without it, the `dpc` adapter would have had to fall back to mock, putting demo frames on screen under the label of live data — exactly the confusion the adapter split exists to prevent. It now fails naming the missing setting instead. Running it on the emulator caught three things the tests had not: - The notifier wrote to `state` from inside `build()`, which Riverpod rejects as an uninitialised provider. That broke startup, not just tests. - Eight-month-old demo frames rendered as "Aggiornato 342535 minuti fa". The age formatter now steps up to hours and days. - Demo mode sat permanently behind a stale-data warning and so never showed the working state it exists to demonstrate. MockRadarSource now shifts the bundled timestamps onto the present, leaving images, order and spacing untouched, so the timeline behaves exactly as it would on live data. Corrects docs/stack-decisions.md, which described a disk cache that was not built: mock frames already live in the asset bundle, so a disk layer belongs with the network adapter where it would save a real request. Verified: analyze clean, 129 tests passing, and on the emulator the loop advances, wraps, and reports "Aggiornato ora". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,100 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:flutter_riverpod/flutter_riverpod.dart';
|
||||
|
||||
import '../../l10n/app_localizations.dart';
|
||||
import 'radar_timeline.dart';
|
||||
|
||||
/// Renders [age] at a scale a reader can take in at a glance.
|
||||
///
|
||||
/// Minutes alone stop being informative quickly: data three days old reads as
|
||||
/// "Aggiornato 4320 minuti fa", which is a number nobody converts in their
|
||||
/// head. The unit steps up so the magnitude is obvious even when the exact
|
||||
/// figure is not.
|
||||
String formatDataAge(AppLocalizations l10n, Duration age) {
|
||||
final clamped = age.isNegative ? Duration.zero : age;
|
||||
if (clamped.inHours < 1) return l10n.dataAgeMinutes(clamped.inMinutes);
|
||||
if (clamped.inDays < 1) return l10n.dataAgeHours(clamped.inHours);
|
||||
return l10n.dataAgeDays(clamped.inDays);
|
||||
}
|
||||
|
||||
/// States the age of the radar data, and says so loudly when it is stale.
|
||||
///
|
||||
/// Radar shown without its age is radar the reader will assume is current. That
|
||||
/// is the failure mode that matters for a weather app: someone deciding whether
|
||||
/// to leave the house based on a picture of the sky from an hour ago. So the
|
||||
/// age is always on screen, not only when something has gone wrong.
|
||||
class DataAgeBanner extends ConsumerWidget {
|
||||
const DataAgeBanner({super.key, this.now});
|
||||
|
||||
/// Injectable clock for tests.
|
||||
final DateTime? now;
|
||||
|
||||
/// Beyond this the data stops being "the current picture".
|
||||
///
|
||||
/// Frames arrive every five minutes, so a gap this size means several
|
||||
/// publishes were missed, not that one is slightly late.
|
||||
static const Duration staleAfter = Duration(minutes: 20);
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context, WidgetRef ref) {
|
||||
final l10n = AppLocalizations.of(context);
|
||||
final theme = Theme.of(context);
|
||||
final state = ref.watch(radarTimelineProvider);
|
||||
final manifest = state.manifest;
|
||||
|
||||
if (manifest == null || manifest.isEmpty) {
|
||||
// Nothing to date. Whether that is a failure or a first load is the
|
||||
// timeline bar's business, not this widget's.
|
||||
return const SizedBox.shrink();
|
||||
}
|
||||
|
||||
final age = manifest.ageAt(now ?? DateTime.now());
|
||||
final ageText = formatDataAge(l10n, age);
|
||||
final isStale = age >= staleAfter || state.error != null;
|
||||
|
||||
if (!isStale) {
|
||||
// Full width and left aligned, matching the stale variant below, so the
|
||||
// text does not jump across the screen when the state flips.
|
||||
return SizedBox(
|
||||
width: double.infinity,
|
||||
child: Padding(
|
||||
padding: const EdgeInsets.fromLTRB(16, 0, 16, 4),
|
||||
child: Text(
|
||||
ageText,
|
||||
style: theme.textTheme.bodySmall?.copyWith(
|
||||
color: theme.colorScheme.outline,
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
return Container(
|
||||
width: double.infinity,
|
||||
color: theme.colorScheme.errorContainer,
|
||||
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
|
||||
child: Row(
|
||||
children: [
|
||||
Icon(
|
||||
Icons.warning_amber_rounded,
|
||||
size: 18,
|
||||
color: theme.colorScheme.onErrorContainer,
|
||||
),
|
||||
const SizedBox(width: 8),
|
||||
Expanded(
|
||||
child: Text(
|
||||
// The age goes inside the warning rather than replacing it: "not
|
||||
// updated" alone leaves the reader guessing how far off it is.
|
||||
state.error != null
|
||||
? '${l10n.dataUnavailable} · $ageText'
|
||||
: l10n.radarStaleWithAge(ageText),
|
||||
style: theme.textTheme.bodySmall?.copyWith(
|
||||
color: theme.colorScheme.onErrorContainer,
|
||||
),
|
||||
),
|
||||
),
|
||||
],
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,318 @@
|
||||
import 'dart:async';
|
||||
import 'dart:typed_data';
|
||||
|
||||
import 'package:flutter_riverpod/flutter_riverpod.dart';
|
||||
|
||||
import '../../core/cache/frame_cache.dart';
|
||||
import '../../core/config/env.dart';
|
||||
import '../../core/region/region_config.dart';
|
||||
import '../../core/region/region_repository.dart';
|
||||
import '../../data/radar/arpa_radar_source.dart';
|
||||
import '../../data/radar/dpc_radar_source.dart';
|
||||
import '../../data/radar/mock_radar_source.dart';
|
||||
import '../../data/radar/radar_manifest.dart';
|
||||
import '../../data/radar/radar_source.dart';
|
||||
|
||||
/// What the radar timeline is showing right now.
|
||||
class RadarTimelineState {
|
||||
const RadarTimelineState({
|
||||
this.manifest,
|
||||
this.index = 0,
|
||||
this.isPlaying = false,
|
||||
this.isLoading = true,
|
||||
this.error,
|
||||
});
|
||||
|
||||
/// The last manifest that loaded successfully.
|
||||
///
|
||||
/// Kept across a failed refresh on purpose: showing yesterday's frames with
|
||||
/// their age stated beats showing an empty map.
|
||||
final RadarManifest? manifest;
|
||||
|
||||
/// Playhead position in [RadarManifest.frames].
|
||||
final int index;
|
||||
|
||||
final bool isPlaying;
|
||||
|
||||
/// A load is in flight. Not the same as having nothing to show.
|
||||
final bool isLoading;
|
||||
|
||||
/// Why the most recent load failed, or null if it succeeded.
|
||||
///
|
||||
/// Non-null together with a non-null [manifest] is the normal degraded state:
|
||||
/// stale data on screen, banner explaining it.
|
||||
final RadarUnavailableException? error;
|
||||
|
||||
bool get hasFrames => manifest?.frames.isNotEmpty ?? false;
|
||||
|
||||
int get frameCount => manifest?.frames.length ?? 0;
|
||||
|
||||
RadarFrame? get currentFrame {
|
||||
final frames = manifest?.frames;
|
||||
if (frames == null || frames.isEmpty) return null;
|
||||
return frames[index.clamp(0, frames.length - 1)];
|
||||
}
|
||||
|
||||
bool get isAtNewestFrame => frameCount == 0 || index >= frameCount - 1;
|
||||
|
||||
RadarTimelineState copyWith({
|
||||
RadarManifest? manifest,
|
||||
int? index,
|
||||
bool? isPlaying,
|
||||
bool? isLoading,
|
||||
RadarUnavailableException? error,
|
||||
bool clearError = false,
|
||||
}) => RadarTimelineState(
|
||||
manifest: manifest ?? this.manifest,
|
||||
index: index ?? this.index,
|
||||
isPlaying: isPlaying ?? this.isPlaying,
|
||||
isLoading: isLoading ?? this.isLoading,
|
||||
error: clearError ? null : (error ?? this.error),
|
||||
);
|
||||
}
|
||||
|
||||
/// Drives the radar timeline: loading, playback and prefetching.
|
||||
class RadarTimeline extends Notifier<RadarTimelineState> {
|
||||
/// How long each frame is held during playback.
|
||||
static const Duration framePeriod = Duration(milliseconds: 450);
|
||||
|
||||
/// Extra dwell on the newest frame, so a loop ends on the present instead of
|
||||
/// snapping straight back to the oldest frame.
|
||||
static const Duration lastFrameDwell = Duration(milliseconds: 1100);
|
||||
|
||||
/// How many frames either side of the playhead to keep loaded.
|
||||
///
|
||||
/// Wide enough that playback never waits on a fetch, narrow enough that a
|
||||
/// long timeline does not sit entirely in memory.
|
||||
static const int prefetchRadius = 4;
|
||||
|
||||
Timer? _playbackTimer;
|
||||
final FrameCache _cache = FrameCache();
|
||||
RadarSource? _source;
|
||||
|
||||
/// Guards against a prefetch that finishes after the playhead has moved on,
|
||||
/// or after the provider has been disposed.
|
||||
int _generation = 0;
|
||||
bool _disposed = false;
|
||||
|
||||
@override
|
||||
RadarTimelineState build() {
|
||||
ref.onDispose(() {
|
||||
_disposed = true;
|
||||
_playbackTimer?.cancel();
|
||||
_cache.clear();
|
||||
});
|
||||
|
||||
// Deferred to a microtask rather than started here: refresh() writes to
|
||||
// `state`, and while build() is still running the provider has no state to
|
||||
// write to yet — Riverpod throws "tried to read the state of an
|
||||
// uninitialized provider". The microtask runs as soon as build() returns.
|
||||
Future<void>.microtask(refresh).ignore();
|
||||
|
||||
return const RadarTimelineState();
|
||||
}
|
||||
|
||||
/// Visible for tests: the bytes currently held for the timeline.
|
||||
FrameCache get cache => _cache;
|
||||
|
||||
/// Loads the newest manifest and positions the playhead on the newest frame.
|
||||
Future<void> refresh() async {
|
||||
state = state.copyWith(isLoading: true);
|
||||
|
||||
try {
|
||||
final source = await _resolveSource();
|
||||
final manifest = await source.getLatestManifest();
|
||||
|
||||
if (_disposed) return;
|
||||
|
||||
_generation++;
|
||||
// Land on the newest frame: someone opening the app wants to know what
|
||||
// the sky is doing now, not two hours ago.
|
||||
final newestIndex = manifest.frames.isEmpty
|
||||
? 0
|
||||
: manifest.frames.length - 1;
|
||||
|
||||
state = RadarTimelineState(
|
||||
manifest: manifest,
|
||||
index: newestIndex,
|
||||
isPlaying: state.isPlaying,
|
||||
isLoading: false,
|
||||
);
|
||||
|
||||
await _prefetchAround(newestIndex);
|
||||
} on RadarUnavailableException catch (error) {
|
||||
if (_disposed) return;
|
||||
// Keep whatever manifest we already had. The banner reports the age.
|
||||
state = state.copyWith(isLoading: false, error: error);
|
||||
}
|
||||
}
|
||||
|
||||
void play() {
|
||||
if (!state.hasFrames || state.isPlaying) return;
|
||||
state = state.copyWith(isPlaying: true);
|
||||
_scheduleNextFrame();
|
||||
}
|
||||
|
||||
void pause() {
|
||||
_playbackTimer?.cancel();
|
||||
_playbackTimer = null;
|
||||
if (state.isPlaying) {
|
||||
state = state.copyWith(isPlaying: false);
|
||||
}
|
||||
}
|
||||
|
||||
void togglePlayPause() => state.isPlaying ? pause() : play();
|
||||
|
||||
/// Moves the playhead, pausing playback: a deliberate scrub should not fight
|
||||
/// the timer for control of the frame.
|
||||
void seek(int index) {
|
||||
if (!state.hasFrames) return;
|
||||
pause();
|
||||
_setIndex(index);
|
||||
}
|
||||
|
||||
void step(int delta) {
|
||||
if (!state.hasFrames) return;
|
||||
pause();
|
||||
_setIndex(state.index + delta);
|
||||
}
|
||||
|
||||
/// Called when the app leaves the foreground.
|
||||
///
|
||||
/// Playback keeps a timer running and decodes an image several times a
|
||||
/// second; continuing that behind another app would drain the battery for
|
||||
/// nothing, since there is no one watching.
|
||||
void onAppBackgrounded() => pause();
|
||||
|
||||
void _setIndex(int index) {
|
||||
final count = state.frameCount;
|
||||
if (count == 0) return;
|
||||
final clamped = index.clamp(0, count - 1);
|
||||
if (clamped == state.index) return;
|
||||
|
||||
_generation++;
|
||||
state = state.copyWith(index: clamped);
|
||||
unawaited(_prefetchAround(clamped));
|
||||
}
|
||||
|
||||
void _scheduleNextFrame() {
|
||||
_playbackTimer?.cancel();
|
||||
if (!state.isPlaying || !state.hasFrames) return;
|
||||
|
||||
final delay = state.isAtNewestFrame ? lastFrameDwell : framePeriod;
|
||||
_playbackTimer = Timer(delay, () {
|
||||
if (_disposed || !state.isPlaying) return;
|
||||
|
||||
final count = state.frameCount;
|
||||
final next = state.index >= count - 1 ? 0 : state.index + 1;
|
||||
_generation++;
|
||||
state = state.copyWith(index: next);
|
||||
unawaited(_prefetchAround(next));
|
||||
_scheduleNextFrame();
|
||||
});
|
||||
}
|
||||
|
||||
/// Returns the bytes for [frame], from cache when possible.
|
||||
Future<Uint8List> bytesFor(RadarFrame frame) async {
|
||||
final source = await _resolveSource();
|
||||
return _cache.load(frame.path, () => source.loadFrameBytes(frame));
|
||||
}
|
||||
|
||||
/// Loads the window around [index], nearest first.
|
||||
///
|
||||
/// Order matters: during playback the next frame is needed within
|
||||
/// milliseconds, while the far edge of the window can wait.
|
||||
Future<void> _prefetchAround(int index) async {
|
||||
final manifest = state.manifest;
|
||||
if (manifest == null || manifest.frames.isEmpty) return;
|
||||
|
||||
final generation = _generation;
|
||||
final frames = manifest.frames;
|
||||
|
||||
final window = <int>[index];
|
||||
for (var offset = 1; offset <= prefetchRadius; offset++) {
|
||||
// Ahead first: playback moves forward, so that is the frame that will be
|
||||
// needed soonest.
|
||||
if (index + offset < frames.length) window.add(index + offset);
|
||||
if (index - offset >= 0) window.add(index - offset);
|
||||
}
|
||||
|
||||
_cache.retainOnly(window.map((i) => frames[i].path).toSet());
|
||||
|
||||
for (final position in window) {
|
||||
if (_disposed || generation != _generation) return;
|
||||
final frame = frames[position];
|
||||
if (_cache.contains(frame.path)) continue;
|
||||
try {
|
||||
await bytesFor(frame);
|
||||
} on RadarUnavailableException {
|
||||
// One missing frame is not a timeline failure: the worker may be
|
||||
// mid-publish. The overlay holds the previous image instead.
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Future<RadarSource> _resolveSource() async {
|
||||
final existing = _source;
|
||||
if (existing != null) return existing;
|
||||
|
||||
final resolved = await ref.read(radarSourceProvider.future);
|
||||
_source = resolved;
|
||||
return resolved;
|
||||
}
|
||||
}
|
||||
|
||||
/// Chooses the radar adapter for [region].
|
||||
///
|
||||
/// A runtime override wins over the region default so a build can be pointed at
|
||||
/// live data without editing assets, but neither can select an adapter the
|
||||
/// region does not list — that would be a configuration typo silently changing
|
||||
/// where the data comes from.
|
||||
RadarSource createRadarSource(RegionConfig region) {
|
||||
var adapter = region.radar.defaultAdapter;
|
||||
|
||||
if (Env.radarSource.isNotEmpty) {
|
||||
final requested = RadarAdapter.parse(Env.radarSource);
|
||||
if (!region.radar.availableAdapters.contains(requested)) {
|
||||
throw StateError(
|
||||
'RADAR_SOURCE=${Env.radarSource} is not among the adapters '
|
||||
'${region.id} declares: '
|
||||
'${region.radar.availableAdapters.map((a) => a.name).join(', ')}',
|
||||
);
|
||||
}
|
||||
adapter = requested;
|
||||
}
|
||||
|
||||
return switch (adapter) {
|
||||
RadarAdapter.mock => MockRadarSource(),
|
||||
RadarAdapter.dpc => _createDpcSource(),
|
||||
RadarAdapter.arpa => const ArpaRadarSource(),
|
||||
};
|
||||
}
|
||||
|
||||
RadarSource _createDpcSource() {
|
||||
if (Env.radarManifestUrl.isEmpty) {
|
||||
// Falling back to mock here would put demo frames on screen under the
|
||||
// label of live data, which is exactly the confusion the adapter split
|
||||
// exists to prevent. Failing names the missing setting instead.
|
||||
throw StateError(
|
||||
'the dpc radar adapter needs RADAR_MANIFEST_URL; set it in env.json or '
|
||||
'select RADAR_SOURCE=mock',
|
||||
);
|
||||
}
|
||||
return DpcRadarSource(manifestUrl: Env.radarManifestUrl);
|
||||
}
|
||||
|
||||
/// The active radar adapter.
|
||||
///
|
||||
/// Separate from the timeline so tests can substitute a source without
|
||||
/// standing up assets or a network, and so the choice stays a single decision
|
||||
/// made in one place.
|
||||
final radarSourceProvider = FutureProvider<RadarSource>((ref) async {
|
||||
final region = await ref.watch(regionConfigProvider.future);
|
||||
return createRadarSource(region);
|
||||
});
|
||||
|
||||
final radarTimelineProvider =
|
||||
NotifierProvider<RadarTimeline, RadarTimelineState>(RadarTimeline.new);
|
||||
@@ -0,0 +1,75 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:flutter_riverpod/flutter_riverpod.dart';
|
||||
import 'package:intl/intl.dart';
|
||||
|
||||
import '../../l10n/app_localizations.dart';
|
||||
import 'radar_timeline.dart';
|
||||
|
||||
/// Play/pause control and scrubber for the radar loop.
|
||||
class TimelineBar extends ConsumerWidget {
|
||||
const TimelineBar({super.key});
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context, WidgetRef ref) {
|
||||
final l10n = AppLocalizations.of(context);
|
||||
final theme = Theme.of(context);
|
||||
final state = ref.watch(radarTimelineProvider);
|
||||
final timeline = ref.read(radarTimelineProvider.notifier);
|
||||
|
||||
if (!state.hasFrames) {
|
||||
return Padding(
|
||||
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
|
||||
child: Text(
|
||||
state.isLoading ? l10n.loading : l10n.radarNoData,
|
||||
style: theme.textTheme.bodySmall,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
final frame = state.currentFrame!;
|
||||
// Frame timestamps are UTC; the reader thinks in local time.
|
||||
final label = DateFormat.Hm().format(frame.timestamp.toLocal());
|
||||
final lastIndex = state.frameCount - 1;
|
||||
|
||||
return Padding(
|
||||
padding: const EdgeInsets.fromLTRB(4, 0, 12, 0),
|
||||
child: Row(
|
||||
children: [
|
||||
IconButton(
|
||||
onPressed: timeline.togglePlayPause,
|
||||
tooltip: state.isPlaying ? l10n.timelinePause : l10n.timelinePlay,
|
||||
icon: Icon(
|
||||
state.isPlaying
|
||||
? Icons.pause_circle_filled
|
||||
: Icons.play_circle_fill,
|
||||
size: 34,
|
||||
),
|
||||
color: theme.colorScheme.primary,
|
||||
),
|
||||
Expanded(
|
||||
child: Semantics(
|
||||
label: l10n.timelineScrubber,
|
||||
value: label,
|
||||
child: Slider(
|
||||
value: state.index.toDouble().clamp(0, lastIndex.toDouble()),
|
||||
max: lastIndex.toDouble(),
|
||||
// One division per frame, so dragging lands on a real frame
|
||||
// rather than interpolating to something that does not exist.
|
||||
divisions: lastIndex > 0 ? lastIndex : null,
|
||||
onChanged: (value) => timeline.seek(value.round()),
|
||||
),
|
||||
),
|
||||
),
|
||||
// Tabular figures so the label does not jitter as the digits change
|
||||
// during playback.
|
||||
Text(
|
||||
label,
|
||||
style: theme.textTheme.titleMedium?.copyWith(
|
||||
fontFeatures: const [FontFeature.tabularFigures()],
|
||||
),
|
||||
),
|
||||
],
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user