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

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
03-overlay-refactor	01	execute	1		lib/services/overlay_service.dart lib/models/overlay_message.dart lib/config/overlay_constants.dart lib/config/timing_constants.dart pubspec.yaml	true	truths artifacts key_links OverlayService class encapsulates all FlutterOverlayWindow platform calls OverlayMessage includes timestamp field serialized as millisecondsSinceEpoch Staleness thresholds (3s dim, 10s dashes) and grace period (30s) defined as named constants retry package added to dependencies for exponential backoff path provides min_lines lib/services/overlay_service.dart Platform channel wrapper with retry logic for show/close/shareData/isActive/overlayListener 60 path provides contains lib/models/overlay_message.dart Timestamp field in OverlayMessage model with toMap/fromMap serialization timestamp path provides contains lib/config/overlay_constants.dart STALENESS_DIM_THRESHOLD, STALENESS_DASH_THRESHOLD, STALENESS_DIM_OPACITY constants STALENESS path provides contains lib/config/timing_constants.dart GPS_GRACE_PERIOD constant (30 seconds) GPS_GRACE_PERIOD path provides contains pubspec.yaml retry package dependency retry from to via pattern lib/services/overlay_service.dart flutter_overlay_window import and method delegation FlutterOverlayWindow from to via pattern lib/services/overlay_service.dart retry RetryOptions for showOverlay and closeOverlay RetryOptions from to via pattern lib/models/overlay_message.dart overlay_service.dart consumers timestamp field in toMap/fromMap millisecondsSinceEpoch

Create the foundation building blocks for overlay refactor: OverlayService wrapper, timestamp-enhanced OverlayMessage, and staleness/grace period constants.

Purpose: Isolate all flutter_overlay_window platform calls behind a service with retry logic and error handling, add timestamp tracking to overlay messages for staleness detection, and define the constants that Plan 02 will use for staleness UI and GPS grace period.

Output: Three new/modified files providing the service layer, enhanced model, and constants that Plan 02 will integrate into OverlayProvider, overlay screen, and SpeedometerScreen.

<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>

@.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 @lib/services/overlay_service.dart @lib/models/overlay_message.dart @lib/config/overlay_constants.dart @lib/config/timing_constants.dart @lib/services/logger.dart @pubspec.yaml Task 1: Create OverlayService and add retry dependency lib/services/overlay_service.dart lib/config/overlay_constants.dart lib/config/timing_constants.dart pubspec.yaml 1. Add `retry: ^3.1.2` to pubspec.yaml under dependencies (after shared_preferences). Run `flutter pub get` to install.

2. Create lib/services/overlay_service.dart — a service class that wraps all FlutterOverlayWindow platform calls:

   • Constructor: No parameters needed. Create a static RetryOptions with maxAttempts: 3 and delayFactor: Duration(milliseconds: 200).

   • showOverlay({required int width, required int height}) → Future:

     • Uses retry to call FlutterOverlayWindow.showOverlay with enableDrag: true, overlayTitle: "Speedometer", overlayContent: 'Speedo overlay active', flag: OverlayFlag.defaultFlag, visibility: NotificationVisibility.visibilityPublic, positionGravity: PositionGravity.none, plus width/height params.
     • After showOverlay completes, calls FlutterOverlayWindow.isActive() to verify overlay actually opened.
     • Returns true if verified active, false if not.
     • On exception after retries exhausted, logs via Logger.error and returns false.
     • retryIf should catch Exception (broad, since platform exceptions vary).

   • closeOverlay() → Future:

     • Uses retry to call FlutterOverlayWindow.closeOverlay().
     • Returns true on success, false on failure after retries.
     • Logs errors via Logger.error.

   • shareData(Map<String, dynamic> data) → Future:

     • Calls FlutterOverlayWindow.shareData(data).
     • Catches exceptions and logs via Logger.warn (NOT error — data loss is expected and handled by staleness).
     • Does NOT retry — fire-and-forget by design (user decision: forward every tick, staleness handles drops).

   • isActive() → Future:

     • Delegates to FlutterOverlayWindow.isActive() with try-catch.
     • Returns false on error.

   • get overlayListener → Stream:

     • Returns FlutterOverlayWindow.overlayListener (direct delegation).

   • checkPermission() → Future:

     • Uses Permission.systemAlertWindow.isGranted from permission_handler.
     • Returns the boolean result.

   Import: flutter_overlay_window, retry, permission_handler, logger.dart. Use Logger with caller tag 'OverlayService' for all log calls.

3. Add staleness constants to lib/config/overlay_constants.dart:

   • static const Duration STALENESS_DIM_THRESHOLD = Duration(seconds: 3); — time after which overlay dims speed display (user decision: 3 seconds, NOT 2)
   • static const Duration STALENESS_DASH_THRESHOLD = Duration(seconds: 10); — time after which overlay shows "--" dashes
   • static const double STALENESS_DIM_OPACITY = 0.5; — opacity value for dimmed stale state
   • static const Duration STALENESS_CHECK_INTERVAL = Duration(seconds: 1); — how often overlay checks for staleness

4. Add GPS grace period constant to lib/config/timing_constants.dart:

   • static const Duration GPS_GRACE_PERIOD = Duration(seconds: 30); — GPS continues 30s after overlay close when backgrounded (user decision) Run flutter pub get to confirm retry dependency resolves. Run flutter analyze to confirm no analysis errors in new/modified files. Verify overlay_service.dart imports compile correctly. OverlayService exists with showOverlay, closeOverlay, shareData, isActive, overlayListener, and checkPermission methods. retry package installed. Staleness constants (3s/10s/0.5 opacity/1s check) and GPS_GRACE_PERIOD (30s) defined in their respective config files. No analysis errors.

Task 2: Add timestamp field to OverlayMessage model lib/models/overlay_message.dart Extend the existing OverlayMessage class to include a timestamp field:

1. Add final DateTime timestamp; field to the class.

2. Update the primary constructor to include required this.timestamp as a required parameter. Remove const from the constructor since DateTime.now() is not a compile-time constant.

3. Update OverlayMessage.updateDisplay factory:

   • Add timestamp: DateTime.now() in the returned OverlayMessage.
   • No changes to parameters (timestamp is auto-generated, not passed in).

4. Update OverlayMessage.longPressClose factory:

   • Remove const from the returned value.
   • Add timestamp: DateTime.now().

5. Update OverlayMessage.overlayClosed factory:

   • Remove const from the returned value.
   • Add timestamp: DateTime.now().

6. Update toMap():

   • Add map['timestamp'] = timestamp.millisecondsSinceEpoch; (always include — timestamp is never null).

7. Update fromMap():

   • Parse timestamp: timestamp: DateTime.fromMillisecondsSinceEpoch(map['timestamp'] as int? ?? DateTime.now().millisecondsSinceEpoch).
   • Fallback to DateTime.now() if timestamp missing (backward compatibility with any in-flight messages during upgrade).

8. Update copyWith():

   • Add DateTime? timestamp parameter.
   • Add timestamp: timestamp ?? this.timestamp in the returned OverlayMessage.

Do NOT change any existing field names, types, or factory parameter signatures. The timestamp is purely additive. Run flutter analyze to confirm no analysis errors. Verify OverlayMessage can be constructed with all three factories. Verify toMap() includes 'timestamp' key. Verify fromMap() parses timestamp correctly and handles missing timestamp gracefully. OverlayMessage has timestamp field, auto-populated by all factory constructors via DateTime.now(), serialized as int via millisecondsSinceEpoch in toMap(), parsed with fallback in fromMap(), and included in copyWith(). No breaking changes to existing API.

1. `flutter pub get` succeeds with retry dependency added 2. `flutter analyze` shows no new errors or warnings (existing SCREAMING_SNAKE info-level warnings are expected) 3. lib/services/overlay_service.dart exists and contains OverlayService class 4. lib/models/overlay_message.dart contains `timestamp` field 5. lib/config/overlay_constants.dart contains STALENESS_DIM_THRESHOLD, STALENESS_DASH_THRESHOLD, STALENESS_DIM_OPACITY, STALENESS_CHECK_INTERVAL 6. lib/config/timing_constants.dart contains GPS_GRACE_PERIOD 7. pubspec.yaml contains retry dependency

<success_criteria>

• OverlayService wraps all FlutterOverlayWindow calls with retry for show/close and error handling for all methods
• OverlayMessage timestamp field serializes/deserializes correctly
• All staleness and grace period constants defined with user-decision values (3s dim, 10s dashes, 30s grace)
• No compilation errors, no breaking changes to existing API </success_criteria>

After completion, create `.planning/phases/03-overlay-refactor/03-01-SUMMARY.md`