gps-speedo/.planning/phases/03-overlay-refactor/03-02-PLAN.md

---
phase: 03-overlay-refactor
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
  - lib/providers/overlay_provider.dart
  - lib/screens/overlay_screen.dart
  - lib/screens/speedometer_screen.dart
  - lib/main.dart
autonomous: true

must_haves:
  truths:
    - "Overlay receives continuous GPS updates without going stale (every tick forwarded)"
    - "Overlay dims speed display after 3 seconds of no data, shows '--' after 10 seconds"
    - "Recovery from staleness is immediate snap-back (no animation)"
    - "Overlay creation failures surface to user via auto-dismissing snackbar"
    - "Permission errors show snackbar with 'Settings' action button that opens app settings"
    - "OverlayProvider verifies overlay is actually active before setting isOverlayActive flag"
    - "Heartbeat timer only runs when overlay active AND app backgrounded"
    - "GPS continues for 30 seconds after overlay close when app is backgrounded"
    - "Theme and unit settings sync in real-time from main app to overlay"
  artifacts:
    - path: "lib/providers/overlay_provider.dart"
      provides: "OverlayService integration, error callback, verified overlay creation, GPS grace period"
      contains: "OverlayService"
    - path: "lib/screens/overlay_screen.dart"
      provides: "Staleness detection timer, two-stage dim/dash UI, timestamp-based freshness"
      contains: "STALENESS_DIM_THRESHOLD"
    - path: "lib/screens/speedometer_screen.dart"
      provides: "Error snackbar surfacing with permission Settings action"
      contains: "SnackBar"
    - path: "lib/main.dart"
      provides: "OverlayService injected into provider tree"
      contains: "OverlayService"
  key_links:
    - from: "lib/providers/overlay_provider.dart"
      to: "lib/services/overlay_service.dart"
      via: "Constructor injection, delegates show/close/share"
      pattern: "_overlayService"
    - from: "lib/providers/overlay_provider.dart"
      to: "lib/screens/speedometer_screen.dart"
      via: "onError callback for snackbar surfacing"
      pattern: "onError"
    - from: "lib/screens/overlay_screen.dart"
      to: "lib/models/overlay_message.dart"
      via: "Reads message.timestamp for staleness calculation"
      pattern: "timestamp"
    - from: "lib/screens/overlay_screen.dart"
      to: "lib/config/overlay_constants.dart"
      via: "Uses STALENESS_DIM_THRESHOLD and STALENESS_DASH_THRESHOLD"
      pattern: "STALENESS"
    - from: "lib/main.dart"
      to: "lib/services/overlay_service.dart"
      via: "Provider registration in MultiProvider"
      pattern: "OverlayService"
---

<objective>
Wire the overlay refactor: integrate OverlayService into OverlayProvider with error callbacks, add staleness detection to the overlay screen, and surface errors via snackbars in SpeedometerScreen.

Purpose: This is the integration plan that makes the overlay communication reliable. OverlayProvider delegates to OverlayService (retry + verification), overlay screen detects stale data visually (dim at 3s, dashes at 10s), and SpeedometerScreen shows errors to the user instead of swallowing them silently.

Output: Fully wired overlay refactor satisfying all OVRL-01 through OVRL-06 requirements with user-decided thresholds and behaviors.
</objective>

<execution_context>
@C:\Users\SKSup\.claude/get-shit-done/workflows/execute-plan.md
@C:\Users\SKSup\.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/03-overlay-refactor/03-CONTEXT.md
@.planning/phases/03-overlay-refactor/03-RESEARCH.md
@.planning/phases/03-overlay-refactor/03-01-SUMMARY.md
@lib/providers/overlay_provider.dart
@lib/screens/overlay_screen.dart
@lib/screens/speedometer_screen.dart
@lib/main.dart
@lib/services/overlay_service.dart
@lib/models/overlay_message.dart
@lib/config/overlay_constants.dart
@lib/config/timing_constants.dart
</context>

<tasks>

<task type="auto">
  <name>Task 1: Refactor OverlayProvider to use OverlayService with error callback and GPS grace period</name>
  <files>
    lib/providers/overlay_provider.dart
    lib/main.dart
  </files>
  <action>
**OverlayProvider refactor (lib/providers/overlay_provider.dart):**

1. **Add OverlayService dependency:**
   - Add `final OverlayService _overlayService;` field.
   - Update constructor: `OverlayProvider(this._overlayService);`
   - Import overlay_service.dart.

2. **Add error callback mechanism:**
   - Define enum at top of file (or in separate model if preferred):
     ```dart
     enum OverlayError { permission, creationFailed, communicationDegraded }
     ```
   - Add field: `void Function(OverlayError)? onError;`
   - This is set by SpeedometerScreen after provider is available (not constructor param — allows late binding since screen needs BuildContext for snackbar).

3. **Refactor showOverlay():**
   - BEFORE calling showOverlay, check permission via `_overlayService.checkPermission()`. If denied, call `onError?.call(OverlayError.permission)` and return early.
   - Replace direct FlutterOverlayWindow.showOverlay call with `_overlayService.showOverlay(width: ..., height: ...)`.
   - Check the return value (bool). If false, call `onError?.call(OverlayError.creationFailed)` and return early.
   - ONLY set `_isOverlayActive = true` AFTER showOverlay returns true (verified by OverlayService.isActive check inside).
   - Keep the initial data push (shareData via _overlayService.shareData instead of direct FlutterOverlayWindow.shareData).
   - Keep _startListeningToOverlayMessages() and _startOverlayStatusCheck() calls.

4. **Refactor closeOverlay():**
   - Replace direct FlutterOverlayWindow.closeOverlay with `_overlayService.closeOverlay()`.
   - Keep existing _handleOverlayClose() call.

5. **Refactor _pushDataToOverlay():**
   - Replace direct FlutterOverlayWindow.shareData with `_overlayService.shareData(message.toMap())`.
   - The OverlayMessage.updateDisplay factory already auto-stamps DateTime.now() (from Plan 01 Task 2).

6. **Refactor _startListeningToOverlayMessages():**
   - Replace `FlutterOverlayWindow.overlayListener` with `_overlayService.overlayListener`.

7. **Add GPS grace period to _handleOverlayClose():**
   - Add `Timer? _gracePeriodTimer;` field.
   - In _handleOverlayClose: After setting _isOverlayActive = false, start a 30-second grace period timer using `TimingConfig.GPS_GRACE_PERIOD`.
   - The grace period timer just logs when it expires: `Logger.info('GPS grace period expired', 'OverlayProvider')`.
   - Cancel grace period in dispose().
   - Note: Actual GPS subscription lifecycle management is Phase 4 scope. The timer is created here as infrastructure but does not yet control GPS subscription start/stop. This avoids scope creep.

8. **Cancel grace period when overlay reopens:**
   - In showOverlay(), cancel `_gracePeriodTimer` if running (user reopened overlay within grace period).

9. **Refactor _startOverlayStatusCheck():**
   - Replace `FlutterOverlayWindow.isActive()` with `_overlayService.isActive()`.

**main.dart update:**

10. Update MultiProvider in main.dart:
    - Add `Provider<OverlayService>(create: (_) => OverlayService()),` BEFORE the OverlayProvider.
    - Update OverlayProvider creation to pass OverlayService:
      ```dart
      ChangeNotifierProxyProvider2<GpsDataManager, SettingsProvider, OverlayProvider>(
        create: (context) => OverlayProvider(context.read<OverlayService>()),
        update: (_, gpsManager, settings, overlay) => overlay!
          ..updateDependencies(
            gpsManager: gpsManager,
            currentUnit: settings.currentUnit,
            currentThemeIndex: settings.currentThemeIndex,
          ),
      ),
      ```
    - Import overlay_service.dart.
  </action>
  <verify>
Run `flutter analyze` to confirm no errors. Verify OverlayProvider no longer directly imports or calls FlutterOverlayWindow (all calls go through _overlayService). Verify showOverlay checks permission, verifies creation success, and only sets _isOverlayActive after verification. Verify grace period timer is created and cancelled properly.
  </verify>
  <done>
OverlayProvider delegates all platform calls to OverlayService. Error callback mechanism exists for permission and creation failures. Overlay creation is verified before setting active flag. GPS grace period timer (30s) starts on overlay close. OverlayService is registered in MultiProvider and injected into OverlayProvider. No direct FlutterOverlayWindow usage remains in OverlayProvider.
  </done>
</task>

<task type="auto">
  <name>Task 2: Add staleness detection to overlay screen and error surfacing to SpeedometerScreen</name>
  <files>
    lib/screens/overlay_screen.dart
    lib/screens/speedometer_screen.dart
  </files>
  <action>
**Overlay screen staleness (lib/screens/overlay_screen.dart):**

1. **Add staleness monitoring:**
   - Import overlay_constants.dart (for STALENESS_DIM_THRESHOLD, STALENESS_DASH_THRESHOLD, STALENESS_DIM_OPACITY, STALENESS_CHECK_INTERVAL).
   - Add field: `DateTime _lastUpdateTime = DateTime.now();`
   - Add field: `Timer? _stalenessCheckTimer;`

2. **Start staleness check timer in initState():**
   - After existing _listenToMainAppMessages() call, add _startStalenessMonitoring().
   - _startStalenessMonitoring() creates a Timer.periodic with OverlayConfig.STALENESS_CHECK_INTERVAL (1 second).
   - Timer callback checks `if (!mounted) return;`, then:
     - Calculates age: `DateTime.now().difference(_lastUpdateTime)`
     - If age > STALENESS_DASH_THRESHOLD (10s) AND _speedText is not already '--': `setState(() => _speedText = '--');`
     - The dimming (3s threshold) is handled in build() via opacity, no setState needed for it.

3. **Update _listenToMainAppMessages() to track timestamp:**
   - When processing 'updateDisplay' messages, extract timestamp from message:
     ```dart
     _lastUpdateTime = message.timestamp;
     ```
   - This uses the timestamp from OverlayMessage (added in Plan 01 Task 2).
   - On receiving fresh data, _speedText gets the actual speed value — this is the "immediate snap-back" (no animation, just setState with new value).

4. **Update build() for staleness dimming:**
   - At the start of build(), calculate:
     ```dart
     final age = DateTime.now().difference(_lastUpdateTime);
     final isStale = age >= OverlayConfig.STALENESS_DIM_THRESHOLD;
     final staleOpacity = isStale ? OverlayConfig.STALENESS_DIM_OPACITY : 1.0;
     ```
   - Apply staleOpacity to the speed text color: change `color: currentTheme.speedText` to `color: currentTheme.speedText.withValues(alpha: staleOpacity)` for the speed Text widget.
   - Apply staleOpacity to the unit text color similarly.
   - Apply staleOpacity to the heading icon and heading text colors.
   - Do NOT use AnimatedOpacity — user decision is "immediate snap-back, no fade-in animation". Direct color alpha is correct.

5. **Cancel staleness timer in dispose():**
   - Add `_stalenessCheckTimer?.cancel();` before super.dispose().

**SpeedometerScreen error surfacing (lib/screens/speedometer_screen.dart):**

6. **Register error callback on OverlayProvider:**
   - Import permission_handler (for openAppSettings).
   - In initState() addPostFrameCallback, after _initializeGpsManager(), set up the error callback:
     ```dart
     context.read<OverlayProvider>().onError = _handleOverlayError;
     ```

7. **Implement _handleOverlayError(OverlayError error):**
   - Check `if (!mounted) return;`
   - Determine message and action based on error type:
     - `OverlayError.permission`: message = 'Overlay permission required', add SnackBarAction with label 'Settings' that calls `openAppSettings()` (from permission_handler).
     - `OverlayError.creationFailed`: message = 'Failed to create overlay window', no action button.
     - `OverlayError.communicationDegraded`: message = 'Overlay communication degraded', no action button.
   - Show snackbar:
     ```dart
     ScaffoldMessenger.of(context).showSnackBar(
       SnackBar(
         content: Text(message),
         action: action,
         duration: const Duration(seconds: 4),
       ),
     );
     ```

8. **Clean up error callback in dispose():**
   - Before super.dispose(), null out the callback:
     ```dart
     context.read<OverlayProvider>().onError = null;
     ```
   - Use a try-catch since the provider might already be disposed.
  </action>
  <verify>
Run `flutter analyze` to confirm no errors. Verify overlay_screen.dart has staleness timer that dims at 3s and shows dashes at 10s. Verify speedometer_screen.dart registers error callback and shows snackbar with Settings action for permission errors. Verify no AnimatedOpacity is used (immediate snap-back per user decision).
  </verify>
  <done>
Overlay screen has staleness detection: dims all display elements after 3s of no GPS data (0.5 opacity), shows "--" after 10s, snaps back immediately when fresh data arrives. SpeedometerScreen surfaces overlay errors via snackbar with "Settings" action button for permission issues. All staleness thresholds use constants from OverlayConfig. Error callback mechanism connects OverlayProvider (no BuildContext) to SpeedometerScreen (has BuildContext).
  </done>
</task>

</tasks>

<verification>
1. `flutter analyze` shows no new errors
2. OverlayProvider uses OverlayService for ALL platform calls (no direct FlutterOverlayWindow usage)
3. OverlayProvider checks permission before showing overlay
4. OverlayProvider verifies overlay creation via isActive() before setting flag
5. OverlayProvider has GPS grace period timer (30s)
6. Overlay screen has staleness timer checking every 1 second
7. Overlay screen dims at 3 seconds (opacity 0.5), shows "--" at 10 seconds
8. Overlay screen snap-back is immediate (no AnimatedOpacity)
9. SpeedometerScreen shows snackbar on overlay creation failure
10. SpeedometerScreen shows snackbar with "Settings" action on permission error
11. main.dart registers OverlayService in provider tree
12. OverlayMessage timestamps flow from main app to overlay screen
</verification>

<success_criteria>
- OVRL-01: Overlay receives continuous debounced data updates via GPS stream forwarding through OverlayService.shareData
- OVRL-02: Overlay errors surfaced to user via snackbar (permission errors include "Settings" action)
- OVRL-03: Overlay creation verified via isActive() before setting isOverlayActive flag
- OVRL-04: Messages include timestamp for staleness detection (millisecondsSinceEpoch)
- OVRL-05: Overlay displays dim at 3s, "--" at 10s when data is stale (user decision: 3s not 2s)
- OVRL-06: OverlayService encapsulates all FlutterOverlayWindow platform calls with retry logic
</success_criteria>

<output>
After completion, create `.planning/phases/03-overlay-refactor/03-02-SUMMARY.md`
</output>