Miler rider app: surface system, visible design language, backend lifecycle

Design system
- MilerSurface ladder (canvas → working → raised → floating) with MilerPanel
  as layer 1; canvas moved to #DEE3EA so white separates at 1.290:1.
- Visible vocabulary applied across Home, Deliveries, Activity, Account and
  the sheets: hero heads (tabular numeral + small caption, clamped at 1.3x),
  canvas wells for anything that opens, small filled tags for shelf labels,
  demoted placeholders. Recorded in DESIGN_SYSTEM.md §6.
- One icon family: 222 Material glyphs migrated to Lucide; none left outside
  lib/xpress.
- Colour semantics corrected: amber only for what is genuinely owed, brand red
  reserved for the live stop, disabled primaries go neutral rather than pale.

Data and lifecycle
- lib/data/lifecycle.dart reads mutations for what they prove; route_order.dart
  makes admin sequence the single ordering authority; service_day.dart, and
  stop_area.dart rewritten against live Coimbatore addresses (digit-token
  stripping, city stoplist, street suffixes, stammer collapse).
- countLabel states the load once, in bags.

Testing
- 1440 tests passing; golden shot harnesses for Home, Deliveries, Activity,
  sheets and verify, with test/failures/ now gitignored (diff debris).
- New pins: home_gutter_test, stop_area_test, plus updated structural bounds.

Note: this commit also carries pre-existing working-tree deletions that were
present before this work (API_SPEC.md, README.md, demo test fixtures).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test/load_state_view_test.dart

@@ -0,0 +1,140 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_screenutil/flutter_screenutil.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:miler/data/load_state.dart';
+import 'package:miler/views/helpers/widgets/load_state_view.dart';
+
+/// ─────────────────────────────────────────────────────────────────────────
+/// FOUR SCREENS, ONE ANSWER PER STATE
+///
+/// Every screen decided independently what a failure looked like — usually by
+/// rendering its empty state, which tells a rider to wait for work that is
+/// actually a dead request. These pin the mapping, and in particular the two
+/// cases that were previously indistinguishable.
+/// ─────────────────────────────────────────────────────────────────────────
+void main() {
+  Future<void> pump(
+    WidgetTester tester,
+    LoadState<List<String>> state, {
+    Future<void> Function()? onRetry,
+  }) async {
+    await tester.pumpWidget(
+      ScreenUtilInit(
+        designSize: const Size(390, 844),
+        builder: (_, _) => MaterialApp(
+          home: Scaffold(
+            body: SingleChildScrollView(
+              child: LoadStateView<List<String>>(
+                state: state,
+                onRetry: onRetry,
+                empty: const Text('NOTHING TODAY'),
+                builder: (v, refreshing) =>
+                    Text('${v.join(",")} refreshing=$refreshing'),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+    await tester.pump();
+  }
+
+  testWidgets('data renders, and says whether a refresh is behind it', (
+    tester,
+  ) async {
+    await pump(tester, const LoadData(['a', 'b'], refreshing: true));
+    expect(find.text('a,b refreshing=true'), findsOneWidget);
+  });
+
+  testWidgets('an empty day is the screen\'s own empty state', (tester) async {
+    await pump(tester, const LoadEmpty<List<String>>());
+    expect(find.text('NOTHING TODAY'), findsOneWidget);
+  });
+
+  // ── The distinction the old code could not make ──
+  testWidgets('a failure is never the empty state', (tester) async {
+    await pump(
+      tester,
+      const LoadFailure<List<String>>(
+        LoadFailureKind.server,
+        message: 'hub is down',
+      ),
+      onRetry: () async {},
+    );
+
+    expect(
+      find.text('NOTHING TODAY'),
+      findsNothing,
+      reason: 'telling a rider to wait for work is wrong when the request died',
+    );
+    // The server's own sentence, not one this app invented.
+    expect(find.text('hub is down'), findsOneWidget);
+    expect(find.text('Try again'), findsOneWidget);
+  });
+
+  testWidgets('offline says so and offers a retry', (tester) async {
+    await pump(
+      tester,
+      const LoadFailure<List<String>>(LoadFailureKind.offline),
+      onRetry: () async {},
+    );
+    expect(find.text('No connection'), findsOneWidget);
+    expect(find.text('Try again'), findsOneWidget);
+  });
+
+  testWidgets('an expired session offers no retry', (tester) async {
+    await pump(
+      tester,
+      const LoadFailure<List<String>>(LoadFailureKind.unauthorized),
+      onRetry: () async {},
+    );
+    expect(find.text('Signed out'), findsOneWidget);
+    expect(
+      find.text('Try again'),
+      findsNothing,
+      reason: 'retrying cannot succeed without signing in again',
+    );
+  });
+
+  testWidgets('rate limiting does not invite another tap', (tester) async {
+    await pump(
+      tester,
+      const LoadFailure<List<String>>(LoadFailureKind.rateLimited),
+      onRetry: () async {},
+    );
+    expect(find.text('Too many requests'), findsOneWidget);
+  });
+
+  // ── Unavailable is neither an error nor an empty day ──
+  testWidgets('a line with no endpoint gets its own state and no retry', (
+    tester,
+  ) async {
+    await pump(
+      tester,
+      const LoadUnavailable<List<String>>('Milk Man work is not served yet.'),
+      onRetry: () async {},
+    );
+
+    expect(find.text('Not available yet'), findsOneWidget);
+    expect(find.text('Milk Man work is not served yet.'), findsOneWidget);
+    expect(find.text('NOTHING TODAY'), findsNothing);
+    expect(
+      find.text('Try again'),
+      findsNothing,
+      reason: 'nothing the rider does changes a missing backend capability',
+    );
+  });
+
+  testWidgets('the retry actually runs', (tester) async {
+    var tries = 0;
+    await pump(
+      tester,
+      const LoadFailure<List<String>>(LoadFailureKind.offline),
+      onRetry: () async => tries++,
+    );
+    await tester.tap(find.text('Try again'));
+    await tester.pump();
+    expect(tries, 1);
+  });
+}