Tasks completed: 2/2
- Task 1: Integrated OverlayService into OverlayProvider with error callbacks and GPS grace period
- Task 2: Added staleness detection to overlay screen and error surfacing to SpeedometerScreen
SUMMARY: .planning/phases/03-overlay-refactor/03-02-SUMMARY.md
Overlay screen staleness:
- Add _lastUpdateTime field to track GPS data freshness
- Add _stalenessCheckTimer for periodic staleness monitoring (1s interval)
- Update _lastUpdateTime from message.timestamp in _listenToMainAppMessages
- Start staleness monitoring in initState, cancel in dispose
- Calculate staleness opacity in build() (0.5 alpha after 3s)
- Apply staleness dimming to speed text, unit text, heading icon, and heading text
- Show "--" for speed after 10s of no data (setState in timer callback)
- Immediate snap-back when fresh data arrives (no AnimatedOpacity)
SpeedometerScreen error surfacing:
- Import permission_handler for openAppSettings
- Register error callback on OverlayProvider in initState postFrameCallback
- Implement _handleOverlayError to show snackbars for overlay errors
- Permission error: snackbar with "Settings" action button that opens app settings
- Creation failure: snackbar with error message (no action button)
- Communication degraded: snackbar with error message (no action button)
- Clean up error callback in dispose (try-catch for disposed provider)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add OverlayError enum (permission, creationFailed, communicationDegraded)
- Add OverlayService dependency via constructor injection
- Add onError callback field for error surfacing (set by SpeedometerScreen)
- Refactor showOverlay to check permission before showing overlay
- Refactor showOverlay to verify overlay creation via isActive check
- Only set _isOverlayActive after verification succeeds
- Replace all FlutterOverlayWindow calls with OverlayService methods
- Add GPS grace period timer (30s) in _handleOverlayClose
- Cancel grace period if overlay reopens within 30s
- Register OverlayService in MultiProvider before OverlayProvider
- Inject OverlayService into OverlayProvider constructor
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Tasks completed: 2/2
- Task 1: Create OverlayService and add retry dependency
- Task 2: Add timestamp field to OverlayMessage model
SUMMARY: .planning/phases/03-overlay-refactor/03-01-SUMMARY.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add timestamp field with auto-population via DateTime.now()
- Update all factory constructors to include timestamp
- Serialize timestamp as millisecondsSinceEpoch in toMap()
- Deserialize with fallback to DateTime.now() in fromMap()
- Add timestamp parameter to copyWith() method
- Remove const modifiers to allow DateTime.now() runtime values
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase 3: Overlay Refactor
- 2 plan(s) in 2 wave(s)
- Sequential execution (Plan 02 depends on Plan 01)
- Ready for execution
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove all shared state variables (unit, theme, GPS data, overlay status)
- Keep only local widget state (_errorMessage, _isInBackground, timer)
- Replace GPS initialization with context.read<GpsDataManager>().initialize()
- Replace overlay show/close/toggle with OverlayProvider methods
- Replace theme/unit cycling with SettingsProvider.cycleTheme/Unit()
- Remove isOverlayMode parameter (not used, overlay runs in separate isolate)
- Wrap build with Selector<SettingsProvider, ColorTheme> for scaffold background
- Use Selector<GpsDataManager, double> for speed display (rebuilds only on speed change)
- Use Selector<SettingsProvider, String> for unit label (rebuilds only on unit change)
- Use Selector<GpsDataManager, (heading, displayHeading)> for compass (rebuilds only on heading change)
- Use context.read<> for event handlers (non-rebuilding access)
- Simplify dispose() - only cancel background heartbeat timer and disable wakelock
- Background heartbeat uses OverlayProvider.pushCurrentData() instead of inline logic
- setState remains ONLY for _errorMessage (purely local error UI state)
- Remove unused imports (speed_unit.dart, processed_gps_data.dart)
- Portrait and landscape layouts both use Provider pattern
Tasks completed: 3/3
- Task 1: Add provider dependencies and refactor GpsDataManager to ChangeNotifier
- Task 2: Create SettingsProvider for theme and unit state
- Task 3: Create OverlayProvider for overlay lifecycle and messaging
SUMMARY: .planning/phases/02-provider-migration/02-01-SUMMARY.md
- Created lib/providers/overlay_provider.dart
- Extends ChangeNotifier for reactive overlay state management
- Centralizes ALL overlay operations: show, close, toggle, status monitoring, messaging
- updateDependencies() called by ProxyProvider when GPS or Settings change
- Subscribes to GpsDataManager.dataStream on first update (persist subscription)
- Skips overlay sends when inactive (if-check, not unsubscribe)
- _isDisposed guards on all async-accessible methods
- showOverlay() sends initial data with overlay size info
- _pushDataToOverlay() sends GPS data with current theme/unit
- _startListeningToOverlayMessages() handles overlay→main IPC
- _startOverlayStatusCheck() polls overlay status at 1s interval
- _handleOverlayClose() manages cleanup and optional bring-to-front
- pushCurrentData() public method for background heartbeat usage
- dispose() cancels 4 subscriptions/timers, calls super.dispose() last
- Created lib/providers/settings_provider.dart
- Extends ChangeNotifier for reactive state management
- Constructor accepts pre-initialized SharedPreferences instance
- Loads theme index and speed unit synchronously from SharedPreferences
- cycleTheme() and cycleUnit() methods with haptic feedback
- Persists settings to SharedPreferences on every change
- Both cycle methods call notifyListeners() for reactive UI updates
- No notifyListeners() in constructor (runs before first build)
- Added provider ^6.1.2 and shared_preferences ^2.3.4 to pubspec.yaml
- Removed singleton pattern from GpsDataManager (deleted _instance and instance getter)
- Changed GpsDataManager._internal() to public GpsDataManager() constructor
- Extended ChangeNotifier to enable reactive state updates
- Added _isDisposed guard field to prevent disposed notifications
- Updated _updateData() to call notifyListeners() after stream emission
- Added _isDisposed guards to _onGpsError() and _handleStaleDataTimeout()
- Updated dispose() to set _isDisposed, call super.dispose() last, removed _isInitialized reset
Phase 1 fully executed and verified (9/9 must-haves).
Ready to resume with Phase 2 (Provider Migration).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Create 01-01-SUMMARY.md: Comprehensive execution summary with 12.8 min duration
- Update STATE.md: Progress 50% (1/2 plans complete), velocity metrics, decisions table
- Document 5 key decisions made during execution
- Record zero deviations, one minor bug (missing import)
- Phase 1 ready to proceed with plan 01-02
- Update gps_data_manager.dart: import ProcessedGpsData from models/, use GpsConfig constants, replace all print() with Logger calls
- Update gps_service.dart: use GpsConfig.VALID_HEADING_MIN/MAX for heading validation
- Update main.dart: import from config/, models/, replace all customDebugPrint() and print() with Logger, use TimingConfig/OverlayConfig constants, convert overlay IPC to OverlayMessage typed class
- Delete customDebugPrint() function definition
- Delete lib/speed_units.dart and lib/color_themes.dart (moved to config/)
- Zero analyzer errors, zero bare print() calls remaining
- Move SpeedUnit enum to config/speed_unit.dart
- Move ColorTheme/ColorThemes classes to config/color_themes.dart
- Extract ProcessedGpsData model from gps_data_manager to models/
- Create OverlayMessage typed class for overlay IPC (replaces raw Maps)
- Create ThemeModel with palette rotation and state management
Phase 01: Foundation
- 2 plan(s) in 2 wave(s)
- 2 autonomous, 0 checkpoint-only
- Ready for execution
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phase 01: Foundation
- Standard stack identified
- Architecture patterns documented
- Pitfalls catalogued
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
GPS Timeout Improvements:
- Add separate GPS timeouts: 20s for initial fix, 2s for ongoing updates
- Resolve indoor GPS timeout issues that caused stream termination
- Prevent GPS stream from stopping immediately due to aggressive timeouts
- Enhanced GPS manager initialization with initial position fetch
Documentation Updates:
- Update TODO.md with v2.3.0-dev architecture completion status
- Update CLAUDE.md with GPS manager architecture details
- Document clean data flow and separate timeout strategy
- Update branch strategy to reflect current development state
Technical Notes:
- GPS manager now handles initial cold start with long timeout
- Ongoing updates use shorter timeout for responsive behavior
- Architecture ready for intelligent caching logic implementation
- All overlay functionality preserved while improving GPS reliability
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add GpsDataManager singleton service for centralized GPS data processing
- Refactor main app to use processed GPS data streams instead of raw position data
- Add haptic feedback to all main UI tap interactions (theme, unit, navigation)
- Implement faster GPS update frequency (500ms timeLimit in LocationSettings)
- Clean up verbose debug logging while preserving essential error logs
- Remove unused debug variables and imports
- Preserve existing background survival mechanisms and overlay lifecycle
- Add temporary GPS simulation while resolving geolocator engine conflicts
Architecture improvements:
- Clean data flow: GPS Hardware → GpsDataManager → Main App → Overlay
- Single source of truth for processed GPS data in manager
- Separation of concerns: GPS logic isolated from UI components
- Foundation ready for intelligent caching logic implementation
Technical notes:
- GPS engine conflict detected, temporarily using simulation data
- All functionality tested and working with test data
- Real GPS integration pending engine conflict resolution
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Mikkeli Matlock