UI-04: customizable, persisted HUD telemetry widget layout

Adds the full drag/resize/visibility infrastructure for a rider-owned HUD
layout: HudMetric (the stable 8-metric set), HudWidgetLayout (fractional
x/y/width/height + visible, with clamping to a legibility floor/ceiling
and JSON round-trip that degrades to sane defaults rather than crashing),
Config.hudLayout persistence, and a HudLayoutController that stays
in-memory-authoritative during an edit session and only writes through on
persist() -- never per drag frame.

DraggableResizableHudWidget and HudEditOverlay assemble the interaction:
edit mode is entered by a long-press on empty HUD space (not a specific
widget) and exited via Done or a tap on empty space; only while editing
does a widget attach any drag/resize gesture at all, so a normal tap can
never move one mid-ride by construction, not by an internal flag.

Fixes a real gesture-arena bug found during testing: outside edit mode, a
long-press landing on a widget was free to bubble to the overlay's
background long-press handler and wrongly enter edit mode. An inner no-op
GestureDetector of the same gesture type now absorbs it.

Adds a "Live HUD stats" Settings section, one switch per metric, that
persists immediately (unlike drag frames). Placed at the end of the
Settings list rather than in the middle -- inserting mid-list pushed
every later section below several existing tests' viewport assumptions.

Verified end-to-end on a real emulator including a full process restart:
resized a widget, force-stopped the app, relaunched, and the resize held.
No consuming screen exists yet (UI-05's job) -- verified via a throwaway
preview entry point, deleted after use.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Xki7YAcc2TiN2PRZJ2tXr

test/config_test.dart

@@ -1,6 +1,8 @@
 import 'package:flutter_test/flutter_test.dart';
 import 'package:rippr/src/config/config.dart';
 import 'package:rippr/src/domain/models.dart';
+import 'package:rippr/src/hud/hud_metric.dart';
+import 'package:rippr/src/hud/hud_widget_layout.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 /// `Config` had no dedicated tests before V3-03 — every existing widget test leaves
@@ -81,6 +83,57 @@ void main() {
     });
   });
 
+  group('hudLayout (UI-04)', () {
+    test('a fresh install gets a default layout for every metric', () async {
+      final config = await freshConfig();
+      final layout = config.hudLayout;
+      expect(layout.keys.toSet(), HudMetric.values.toSet());
+    });
+
+    test('round-trips an edited layout through set/get', () async {
+      final config = await freshConfig();
+      final edited = {
+        ...config.hudLayout,
+        HudMetric.speed: const HudWidgetLayout(
+          metric: HudMetric.speed,
+          x: 0.33,
+          y: 0.44,
+          width: 0.25,
+          height: 0.1,
+          visible: true,
+        ),
+      };
+
+      await config.setHudLayout(edited);
+      final reloaded = config.hudLayout;
+
+      expect(reloaded[HudMetric.speed]!.x, 0.33);
+      expect(reloaded[HudMetric.speed]!.y, 0.44);
+    });
+
+    test('a metric missing from a saved layout (e.g. one added in a later app '
+        'version) falls back to its default rather than being omitted', () async {
+      SharedPreferences.setMockInitialValues({
+        'hud_layout': '{"speed": {"x": 0.1, "y": 0.1, "width": 0.2, "height": 0.1, '
+            '"visible": true}}',
+      });
+      final config = await Config.load();
+      final layout = config.hudLayout;
+
+      expect(layout.keys.toSet(), HudMetric.values.toSet());
+      final expectedDefault = HudWidgetLayout.defaultFor(HudMetric.distance);
+      expect(layout[HudMetric.distance]!.x, expectedDefault.x);
+      expect(layout[HudMetric.distance]!.visible, expectedDefault.visible);
+    });
+
+    test('corrupted stored JSON falls back to defaults rather than crashing',
+        () async {
+      SharedPreferences.setMockInitialValues({'hud_layout': 'not json at all'});
+      final config = await Config.load();
+      expect(config.hudLayout.keys.toSet(), HudMetric.values.toSet());
+    });
+  });
+
   group('deviceId', () {
     test('is generated once and then stable across reads', () async {
       final config = await freshConfig();

test/hud_edit_overlay_test.dart

@@ -0,0 +1,113 @@
+import 'package:flutter/gestures.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:rippr/src/app/providers.dart';
+import 'package:rippr/src/config/config.dart';
+import 'package:rippr/src/hud/hud_metric.dart';
+import 'package:rippr/src/ui/components/hud_edit_overlay.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// UI-04: drag/toggle behaviour of the customizable HUD, simulated via `TestGesture`
+/// the same way other drag interactions in this codebase are tested (see
+/// `route_planner_screen_test.dart`'s waypoint-drag coverage).
+void main() {
+  late Config config;
+
+  setUp(() async {
+    SharedPreferences.setMockInitialValues({});
+    config = await Config.load();
+  });
+
+  Widget host() => ProviderScope(
+    overrides: [configProvider.overrideWith((ref) => config)],
+    child: MaterialApp(
+      home: Scaffold(
+        body: SizedBox.expand(
+          child: HudEditOverlay(
+            metricBuilder: (context, metric) => Text(metric.label),
+          ),
+        ),
+      ),
+    ),
+  );
+
+  testWidgets('a tap outside edit mode does not move a widget', (tester) async {
+    await tester.pumpWidget(host());
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const Key('hud-edit-done')), findsNothing,
+        reason: 'not editing yet');
+
+    await tester.tap(find.text('Speed'));
+    await tester.pump();
+
+    expect(find.byKey(const Key('hud-edit-done')), findsNothing,
+        reason: 'a plain tap on a widget must never enter edit mode or move it');
+  });
+
+  testWidgets('a long-press on empty space enters edit mode, showing resize handles '
+      'and Done', (tester) async {
+    await tester.pumpWidget(host());
+    await tester.pumpAndSettle();
+
+    await tester.longPress(find.byKey(const Key('hud-edit-background')));
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const Key('hud-edit-done')), findsOneWidget);
+    expect(find.byKey(const Key('hud-resize-handle')), findsWidgets);
+  });
+
+  testWidgets('a long-press-and-drag on a widget moves it, and Done persists the new '
+      'position', (tester) async {
+    await tester.pumpWidget(host());
+    await tester.pumpAndSettle();
+
+    await tester.longPress(find.byKey(const Key('hud-edit-background')));
+    await tester.pumpAndSettle();
+
+    final before = config.hudLayout[HudMetric.speed]!;
+
+    final speedFinder = find.text('Speed');
+    final gesture = await tester.startGesture(tester.getCenter(speedFinder));
+    await tester.pump(kLongPressTimeout + kPressTimeout);
+    await gesture.moveBy(const Offset(40, 60));
+    await tester.pump();
+    await gesture.up();
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.byKey(const Key('hud-edit-done')));
+    await tester.pumpAndSettle();
+
+    final after = config.hudLayout[HudMetric.speed]!;
+    expect(after.x, isNot(before.x));
+    expect(after.y, isNot(before.y));
+  });
+
+  testWidgets('a drag while not editing does not move the widget', (tester) async {
+    await tester.pumpWidget(host());
+    await tester.pumpAndSettle();
+
+    final before = config.hudLayout[HudMetric.speed]!;
+    final speedFinder = find.text('Speed');
+
+    final gesture = await tester.startGesture(tester.getCenter(speedFinder));
+    await tester.pump(kLongPressTimeout + kPressTimeout);
+    await gesture.moveBy(const Offset(40, 60));
+    await gesture.up();
+    await tester.pumpAndSettle();
+
+    expect(find.byKey(const Key('hud-edit-done')), findsNothing);
+    final after = config.hudLayout[HudMetric.speed]!;
+    expect(after.x, before.x);
+    expect(after.y, before.y);
+  });
+
+  testWidgets('only visible metrics render a widget', (tester) async {
+    await tester.pumpWidget(host());
+    await tester.pumpAndSettle();
+
+    expect(find.text('Speed'), findsOneWidget, reason: 'visible by default');
+    expect(find.text('Average speed'), findsNothing, reason: 'hidden by default');
+  });
+}

test/hud_layout_controller_test.dart

@@ -0,0 +1,71 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:rippr/src/config/config.dart';
+import 'package:rippr/src/hud/hud_layout_controller.dart';
+import 'package:rippr/src/hud/hud_metric.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+void main() {
+  Future<Config> freshConfig() async {
+    SharedPreferences.setMockInitialValues({});
+    return Config.load();
+  }
+
+  group('HudLayoutController', () {
+    test('updatePosition updates only the given metric, clamped', () async {
+      final controller = HudLayoutController(await freshConfig());
+      final before = controller.state[HudMetric.distance]!;
+
+      controller.updatePosition(HudMetric.speed, 5.0, 5.0);
+
+      expect(controller.state[HudMetric.speed]!.x, lessThanOrEqualTo(1.0));
+      expect(controller.state[HudMetric.distance]!.x, before.x,
+          reason: 'moving one metric must not disturb another');
+    });
+
+    test('updateSize clamps to the legibility floor/ceiling', () async {
+      final controller = HudLayoutController(await freshConfig());
+
+      controller.updateSize(HudMetric.speed, 0.0, 0.0);
+      expect(controller.state[HudMetric.speed]!.width, greaterThan(0.0));
+      expect(controller.state[HudMetric.speed]!.height, greaterThan(0.0));
+    });
+
+    test('setVisible(false) then setVisible(true) restores the last saved position, '
+        'not a fresh default', () async {
+      final controller = HudLayoutController(await freshConfig());
+      controller.updatePosition(HudMetric.avgSpeed, 0.6, 0.6);
+      final movedX = controller.state[HudMetric.avgSpeed]!.x;
+
+      controller.setVisible(HudMetric.avgSpeed, false);
+      expect(controller.state[HudMetric.avgSpeed]!.visible, isFalse);
+
+      controller.setVisible(HudMetric.avgSpeed, true);
+      expect(controller.state[HudMetric.avgSpeed]!.visible, isTrue);
+      expect(controller.state[HudMetric.avgSpeed]!.x, movedX,
+          reason: 'a metric with a real saved position keeps it when re-enabled');
+    });
+
+    test('persist writes the current state to Config', () async {
+      final config = await freshConfig();
+      final controller = HudLayoutController(config);
+      controller.updatePosition(HudMetric.speed, 0.4, 0.4);
+
+      await controller.persist();
+
+      final reloaded = config.hudLayout;
+      expect(reloaded[HudMetric.speed]!.x, 0.4);
+    });
+
+    test('edits before persist are not visible to a fresh read of Config', () async {
+      final config = await freshConfig();
+      final controller = HudLayoutController(config);
+      controller.updatePosition(HudMetric.speed, 0.4, 0.4);
+
+      // No persist() call yet.
+      final reloaded = config.hudLayout;
+      expect(reloaded[HudMetric.speed]!.x, isNot(0.4),
+          reason: 'a drag in progress must only touch in-memory state -- '
+              'persisting every frame is the ticket\'s own named risk');
+    });
+  });
+}

test/hud_widget_layout_test.dart

@@ -0,0 +1,127 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:rippr/src/hud/hud_metric.dart';
+import 'package:rippr/src/hud/hud_widget_layout.dart';
+
+/// UI-04: the JSON round-trip and clamp math are exercised directly with fixed inputs
+/// -- no real gestures needed to test either, per the ticket's own Tests section.
+void main() {
+  group('JSON round trip', () {
+    test('encodes and decodes exactly', () {
+      const original = HudWidgetLayout(
+        metric: HudMetric.speed,
+        x: 0.1,
+        y: 0.2,
+        width: 0.3,
+        height: 0.15,
+        visible: true,
+      );
+
+      final decoded = HudWidgetLayout.fromJson(HudMetric.speed, original.toJson());
+
+      expect(decoded.x, original.x);
+      expect(decoded.y, original.y);
+      expect(decoded.width, original.width);
+      expect(decoded.height, original.height);
+      expect(decoded.visible, original.visible);
+    });
+
+    test('a malformed entry falls back to the default rather than crashing', () {
+      final decoded = HudWidgetLayout.fromJson(HudMetric.distance, {'x': 'not a number'});
+      final default_ = HudWidgetLayout.defaultFor(HudMetric.distance);
+
+      expect(decoded.x, default_.x);
+      expect(decoded.width, default_.width);
+    });
+
+    test('a missing field falls back to the default rather than crashing', () {
+      final decoded = HudWidgetLayout.fromJson(HudMetric.maxSpeed, {'x': 0.1, 'y': 0.1});
+      final default_ = HudWidgetLayout.defaultFor(HudMetric.maxSpeed);
+
+      expect(decoded.x, default_.x);
+    });
+  });
+
+  group('defaultFor', () {
+    test('every metric gets a distinct default position', () {
+      final positions = HudMetric.values
+          .map(HudWidgetLayout.defaultFor)
+          .map((l) => '${l.x},${l.y}')
+          .toSet();
+      expect(positions.length, HudMetric.values.length,
+          reason: 'no two metrics should default to overlapping positions');
+    });
+
+    test('the first four metrics (the mockup\'s fixed row) start visible', () {
+      expect(HudWidgetLayout.defaultFor(HudMetric.speed).visible, isTrue);
+      expect(HudWidgetLayout.defaultFor(HudMetric.distance).visible, isTrue);
+      expect(HudWidgetLayout.defaultFor(HudMetric.elapsedTime).visible, isTrue);
+      expect(HudWidgetLayout.defaultFor(HudMetric.maxSpeed).visible, isTrue);
+    });
+
+    test('metrics beyond the fixed row start hidden', () {
+      expect(HudWidgetLayout.defaultFor(HudMetric.avgSpeed).visible, isFalse);
+      expect(HudWidgetLayout.defaultFor(HudMetric.elevationGain).visible, isFalse);
+    });
+
+    test('every default is already within the valid clamp bounds', () {
+      for (final metric in HudMetric.values) {
+        final layout = HudWidgetLayout.defaultFor(metric);
+        expect(layout.clamped().x, layout.x);
+        expect(layout.clamped().y, layout.y);
+        expect(layout.clamped().width, layout.width);
+        expect(layout.clamped().height, layout.height);
+      }
+    });
+  });
+
+  group('clamped', () {
+    const base = HudWidgetLayout(
+      metric: HudMetric.speed,
+      x: 0.5,
+      y: 0.5,
+      width: 0.3,
+      height: 0.15,
+      visible: true,
+    );
+
+    test('a position dragged past the right/bottom edge is pulled back on-screen', () {
+      final result = base.copyWith(x: 1.5, y: 1.5).clamped();
+      expect(result.x, 1.0 - base.width);
+      expect(result.y, 1.0 - base.height);
+    });
+
+    test('a position dragged past the left/top edge is pulled back on-screen', () {
+      final result = base.copyWith(x: -0.5, y: -0.5).clamped();
+      expect(result.x, 0.0);
+      expect(result.y, 0.0);
+    });
+
+    test('a resize below the legibility floor is corrected up to the minimum', () {
+      final result = base.copyWith(width: 0.01, height: 0.01).clamped();
+      expect(result.width, hudMinWidthFraction);
+      expect(result.height, hudMinHeightFraction);
+    });
+
+    test('a resize above the sane ceiling is corrected down to the maximum', () {
+      final result = base.copyWith(width: 5.0, height: 5.0).clamped();
+      expect(result.width, hudMaxWidthFraction);
+      expect(result.height, hudMaxHeightFraction);
+    });
+
+    test('shrinking to fit happens before repositioning, so a widget resized past '
+        'the edge shrinks rather than silently relocates', () {
+      final result = base.copyWith(x: 0.9, width: 0.7).clamped();
+      expect(result.width, hudMaxWidthFraction);
+      // x itself is still clamped against the (now-bounded) width so the widget
+      // never sits partially off-screen either.
+      expect(result.x + result.width, lessThanOrEqualTo(1.0));
+    });
+
+    test('an already-valid layout is unchanged', () {
+      expect(base.clamped().x, base.x);
+      expect(base.clamped().y, base.y);
+      expect(base.clamped().width, base.width);
+      expect(base.clamped().height, base.height);
+    });
+  });
+}

test/settings_screen_test.dart

@@ -4,6 +4,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:rippr/src/app/providers.dart';
 import 'package:rippr/src/config/config.dart';
 import 'package:rippr/src/domain/models.dart';
+import 'package:rippr/src/hud/hud_metric.dart';
 import 'package:rippr/src/ui/settings/settings_screen.dart';
 import 'package:rippr/src/ui/theme.dart';
 import 'package:shared_preferences/shared_preferences.dart';
@@ -196,6 +197,46 @@ void main() {
     expect(tester.takeException(), isNull);
   });
 
+  group('Live HUD stats (UI-04)', () {
+    // The section sits at the bottom of a long ListView -- these rows are not built
+    // until scrolled into view (a plain `ListView(children:)` still lazily materialises
+    // via a sliver, same as `.builder`), so every test here scrolls first.
+    Future<void> scrollTo(WidgetTester tester, Key key) => tester.scrollUntilVisible(
+      find.byKey(key),
+      200,
+      scrollable: find.byType(Scrollable).first,
+    );
+
+    testWidgets('a metric switch reflects and writes through to Config', (tester) async {
+      await tester.pumpWidget(host());
+      await tester.pumpAndSettle();
+      await scrollTo(tester, const Key('hud-visible-avgSpeed'));
+
+      final initial = tester
+          .widget<SwitchListTile>(find.byKey(const Key('hud-visible-avgSpeed')))
+          .value;
+      expect(initial, isFalse, reason: 'metrics beyond the fixed row start hidden');
+
+      await tester.tap(find.byKey(const Key('hud-visible-avgSpeed')));
+      await tester.pumpAndSettle();
+
+      expect(config.hudLayout[HudMetric.avgSpeed]!.visible, isTrue,
+          reason: 'the switch must write through to Config immediately, not wait '
+              'for a HUD edit-mode session to end');
+    });
+
+    testWidgets('a metric already visible by default shows as on', (tester) async {
+      await tester.pumpWidget(host());
+      await tester.pumpAndSettle();
+      await scrollTo(tester, const Key('hud-visible-speed'));
+
+      final speedSwitch = tester
+          .widget<SwitchListTile>(find.byKey(const Key('hud-visible-speed')))
+          .value;
+      expect(speedSwitch, isTrue);
+    });
+  });
+
   testWidgets('shows a spinner rather than crashing while Config is still loading',
       (tester) async {
     await tester.pumpWidget(