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>

lib/xpress/helpers/shift_end_alarm.dart

@@ -0,0 +1,144 @@
+import 'dart:io';
+import 'package:flutter/services.dart';
+import 'package:flutter/foundation.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:miler/xpress/background/backgroundservice.dart';
+
+/// Helper class to schedule/cancel shift end alarms
+/// Works even when app is killed (uses Android AlarmManager)
+class ShiftEndAlarm {
+  static const MethodChannel _channel = MethodChannel('doormile/shift_end');
+
+  /// Schedule an alarm for shift end time
+  /// This alarm will fire even if the app is killed
+  /// If shift end time has already passed today, it will trigger immediately
+  static Future<bool> scheduleAlarm({
+    required String endTime, // Format: "HH:mm:ss" or "HH:mm"
+    String startTime =
+        '', // Format: "HH:mm:ss" or "HH:mm" (for overnight shift detection)
+  }) async {
+    if (!Platform.isAndroid) {
+      debugPrint('[SHIFT_END_ALARM] Only supported on Android');
+      return false;
+    }
+
+    try {
+      debugPrint(
+        '[SHIFT_END_ALARM] 📅 scheduleAlarm called - endTime: "$endTime", startTime: "$startTime"',
+      );
+
+      // Check if shift end time has already passed today
+      final now = DateTime.now();
+      debugPrint('[SHIFT_END_ALARM] 📅 Current time: ${now.toString()}');
+
+      final endParts = endTime.split(':');
+      if (endParts.length >= 2) {
+        final int endHour = int.tryParse(endParts[0]) ?? 0;
+        final int endMinute = int.tryParse(endParts[1]) ?? 0;
+        final int endSecond = endParts.length > 2
+            ? (int.tryParse(endParts[2]) ?? 0)
+            : 0;
+
+        final DateTime endToday = DateTime(
+          now.year,
+          now.month,
+          now.day,
+          endHour,
+          endMinute,
+          endSecond,
+        );
+
+        debugPrint(
+          '[SHIFT_END_ALARM] 📅 Shift end time today: ${endToday.toString()}',
+        );
+        debugPrint(
+          '[SHIFT_END_ALARM] 📅 Time comparison: now.isAfter(endToday) = ${now.isAfter(endToday)}',
+        );
+
+        // If shift end time has passed, trigger immediately
+        if (now.isAfter(endToday) || now.isAtSameMomentAs(endToday)) {
+          debugPrint(
+            '[SHIFT_END_ALARM] ⚡ Shift end time ($endTime) has already passed - triggering break log immediately',
+          );
+          await handleShiftEnd();
+        } else {
+          debugPrint(
+            '[SHIFT_END_ALARM] ⏰ Shift end time ($endTime) has not passed yet - will schedule alarm',
+          );
+        }
+      } else {
+        debugPrint('[SHIFT_END_ALARM] ⚠️ Invalid endTime format: "$endTime"');
+      }
+
+      final result = await _channel.invokeMethod<bool>(
+        'scheduleShiftEndAlarm',
+        {'endTime': endTime, 'startTime': startTime},
+      );
+      final success = result ?? false;
+      if (success) {
+        debugPrint(
+          '[SHIFT_END_ALARM] ✅ Successfully scheduled alarm for shift end: $endTime',
+        );
+      } else {
+        debugPrint(
+          '[SHIFT_END_ALARM] ⚠️ Failed to schedule alarm for shift end: $endTime',
+        );
+      }
+      return success;
+    } on PlatformException catch (e) {
+      debugPrint('[SHIFT_END_ALARM] ❌ Error scheduling alarm: ${e.message}');
+      return false;
+    } catch (e) {
+      debugPrint('[SHIFT_END_ALARM] ❌ Unexpected error: $e');
+      return false;
+    }
+  }
+
+  /// Cancel the scheduled shift end alarm
+  static Future<bool> cancelAlarm() async {
+    if (!Platform.isAndroid) {
+      return false;
+    }
+
+    try {
+      final result = await _channel.invokeMethod<bool>('cancelShiftEndAlarm');
+      debugPrint('[SHIFT_END_ALARM] ✅ Cancelled shift end alarm');
+      return result ?? false;
+    } on PlatformException catch (e) {
+      debugPrint('[SHIFT_END_ALARM] ❌ Error cancelling alarm: ${e.message}');
+      return false;
+    } catch (e) {
+      debugPrint('[SHIFT_END_ALARM] ❌ Unexpected error: $e');
+      return false;
+    }
+  }
+
+  /// Handle shift end when alarm fires (called by BroadcastReceiver)
+  /// This will create the break log and set rider offline
+  static Future<void> handleShiftEnd() async {
+    try {
+      debugPrint(
+        '[SHIFT_END_ALARM] 🔔 Shift end alarm fired - creating break log...',
+      );
+
+      final prefs = await SharedPreferences.getInstance();
+
+      // Check if still on duty (might have been manually set offline)
+      final int onduty = prefs.getInt('onduty') ?? 0;
+      if (onduty != 1) {
+        debugPrint(
+          '[SHIFT_END_ALARM] Already offline, skipping break log creation',
+        );
+        return;
+      }
+
+      // Call the background service to create break log
+      // This will create break log and set offline
+      await BackgroundDeliveryLog.checkShiftEnd();
+
+      debugPrint('[SHIFT_END_ALARM] ✅ Break log created successfully');
+    } catch (e) {
+      debugPrint('[SHIFT_END_ALARM] ❌ Error handling shift end: $e');
+    }
+  }
+}