docs(03-02): complete overlay integration plan
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
This commit is contained in:
Mikkeli Matlock
+35
-24
@@ -5,23 +5,23 @@
|
|||||||
See: .planning/PROJECT.md (updated 2026-02-09)
|
See: .planning/PROJECT.md (updated 2026-02-09)
|
||||||
|
|
||||||
**Core value:** Reliable, lag-free GPS speed display that coexists politely with other Android apps
|
**Core value:** Reliable, lag-free GPS speed display that coexists politely with other Android apps
|
||||||
**Current focus:** Phase 3 - Overlay Refactor (IN PROGRESS)
|
**Current focus:** Phase 4 - GPS Optimization
|
||||||
|
|
||||||
## Current Position
|
## Current Position
|
||||||
|
|
||||||
Phase: 3 of 4 (Overlay Refactor)
|
Phase: 3 of 4 (Overlay Refactor)
|
||||||
Plan: 1 of 2 complete
|
Plan: 2 of 2 complete
|
||||||
Status: In progress
|
Status: Phase complete
|
||||||
Last activity: 2026-02-11 — Completed 03-01-PLAN.md
|
Last activity: 2026-02-11 — Completed 03-02-PLAN.md
|
||||||
|
|
||||||
Progress: [████░░░░░░] 55% (Phase 3: 1/2 plans)
|
Progress: [██████░░░░] 60% (Phase 3: 2/2 plans complete)
|
||||||
|
|
||||||
## Performance Metrics
|
## Performance Metrics
|
||||||
|
|
||||||
**Velocity:**
|
**Velocity:**
|
||||||
- Total plans completed: 5
|
- Total plans completed: 6
|
||||||
- Average duration: 6.9 minutes
|
- Average duration: 6.3 minutes
|
||||||
- Total execution time: 0.58 hours
|
- Total execution time: 0.63 hours
|
||||||
|
|
||||||
**By Phase:**
|
**By Phase:**
|
||||||
|
|
||||||
@@ -29,11 +29,11 @@ Progress: [████░░░░░░] 55% (Phase 3: 1/2 plans)
|
|||||||
|-------|-------|-------|----------|
|
|-------|-------|-------|----------|
|
||||||
| 1. Foundation | 2 | 19.6 min | 9.8 min |
|
| 1. Foundation | 2 | 19.6 min | 9.8 min |
|
||||||
| 2. Provider Migration | 2 | 11.5 min | 5.75 min |
|
| 2. Provider Migration | 2 | 11.5 min | 5.75 min |
|
||||||
| 3. Overlay Refactor | 1 | 4.0 min | 4.0 min |
|
| 3. Overlay Refactor | 2 | 8.25 min | 4.1 min |
|
||||||
|
|
||||||
**Recent Trend:**
|
**Recent Trend:**
|
||||||
- Last 5 plans: 01-02 (6.8 min), 02-01 (7.7 min), 02-02 (3.8 min), 03-01 (4.0 min)
|
- Last 5 plans: 02-01 (7.7 min), 02-02 (3.8 min), 03-01 (4.0 min), 03-02 (4.25 min)
|
||||||
- Trend: Continuing acceleration (4.0 min on latest plan)
|
- Trend: Consistent sub-5-minute plans in Phase 3
|
||||||
|
|
||||||
*Updated after each plan completion*
|
*Updated after each plan completion*
|
||||||
|
|
||||||
@@ -66,6 +66,10 @@ Recent decisions affecting current work:
|
|||||||
| 03 | 01 | shareData fire-and-forget (no retry, warn logging) | Implemented |
|
| 03 | 01 | shareData fire-and-forget (no retry, warn logging) | Implemented |
|
||||||
| 03 | 01 | Staleness thresholds: 3s dim, 10s dash | Implemented |
|
| 03 | 01 | Staleness thresholds: 3s dim, 10s dash | Implemented |
|
||||||
| 03 | 01 | Timestamp auto-populated in OverlayMessage factories | Implemented |
|
| 03 | 01 | Timestamp auto-populated in OverlayMessage factories | Implemented |
|
||||||
|
| 03 | 02 | OverlayProvider delegates ALL calls to OverlayService | Implemented |
|
||||||
|
| 03 | 02 | Error callback pattern for provider-to-screen comm | Implemented |
|
||||||
|
| 03 | 02 | Staleness opacity via withValues(alpha:) no animation | Implemented |
|
||||||
|
| 03 | 02 | GPS grace period timer created (Phase 4 lifecycle) | Implemented |
|
||||||
| 04 | TBD | Speed-adaptive GPS precision (~10 km/h threshold) | Pending |
|
| 04 | TBD | Speed-adaptive GPS precision (~10 km/h threshold) | Pending |
|
||||||
| 04 | TBD | Background GPS only when overlay visible | Pending |
|
| 04 | TBD | Background GPS only when overlay visible | Pending |
|
||||||
|
|
||||||
@@ -84,12 +88,17 @@ Recent decisions affecting current work:
|
|||||||
- [ ] Manual testing: Settings persistence, theme/unit cycling, overlay toggle, background heartbeat
|
- [ ] Manual testing: Settings persistence, theme/unit cycling, overlay toggle, background heartbeat
|
||||||
- [ ] Manual testing: Verify no "setState after dispose" or "ChangeNotifier after dispose" errors
|
- [ ] Manual testing: Verify no "setState after dispose" or "ChangeNotifier after dispose" errors
|
||||||
|
|
||||||
**Phase 3 In Progress:**
|
**Phase 3 Complete:**
|
||||||
- [x] 03-01 complete — Overlay foundation infrastructure (4.0 min)
|
- [x] 03-01 complete — Overlay foundation infrastructure (4.0 min)
|
||||||
- [x] OverlayService wrapper with retry logic created
|
- [x] 03-02 complete — Overlay integration with staleness detection (4.25 min)
|
||||||
- [x] OverlayMessage enhanced with timestamp tracking
|
- [x] OverlayProvider delegates all platform calls to OverlayService
|
||||||
- [x] Staleness constants and GPS grace period defined
|
- [x] Permission checks before overlay creation, verified creation via isActive()
|
||||||
- [ ] 03-02 next — Integrate OverlayService and staleness detection
|
- [x] Staleness detection: dim at 3s, dashes at 10s, immediate snap-back
|
||||||
|
- [x] Error surfacing via snackbar with Settings action for permission errors
|
||||||
|
- [x] GPS grace period timer (30s) infrastructure for Phase 4
|
||||||
|
- [ ] Manual testing: Verify overlay reliability improvements on physical device
|
||||||
|
- [ ] Manual testing: Test permission error snackbar and Settings action button
|
||||||
|
- [ ] Manual testing: Verify staleness dimming and dash display timing
|
||||||
|
|
||||||
### Blockers/Concerns
|
### Blockers/Concerns
|
||||||
|
|
||||||
@@ -106,13 +115,15 @@ Recent decisions affecting current work:
|
|||||||
- RESOLVED: Zero setState calls for shared state (theme, unit, GPS data, overlay status)
|
- RESOLVED: Zero setState calls for shared state (theme, unit, GPS data, overlay status)
|
||||||
- INFO: Manual testing needed to verify settings persistence and provider lifecycle
|
- INFO: Manual testing needed to verify settings persistence and provider lifecycle
|
||||||
|
|
||||||
**Phase 3 (Overlay Refactor) — In Progress:**
|
**Phase 3 (Overlay Refactor) — Complete:**
|
||||||
- RESOLVED: OverlayService foundation complete with retry logic
|
- RESOLVED: OverlayService foundation complete with retry logic
|
||||||
- RESOLVED: Timestamp tracking in OverlayMessage for staleness detection
|
- RESOLVED: OverlayProvider integration complete with permission checks and verified creation
|
||||||
- RESOLVED: Staleness constants defined (3s dim, 10s dash, 30s GPS grace)
|
- RESOLVED: Staleness detection complete (3s dim, 10s dash, immediate snap-back)
|
||||||
|
- RESOLVED: Error surfacing complete (snackbar with Settings action for permission errors)
|
||||||
|
- RESOLVED: GPS grace period timer infrastructure created for Phase 4
|
||||||
- MEDIUM RISK: flutter_overlay_window 0.5.0 has known communication issues (mitigated by retry + verification)
|
- MEDIUM RISK: flutter_overlay_window 0.5.0 has known communication issues (mitigated by retry + verification)
|
||||||
- INFO: Plan 03-02 will integrate OverlayService and implement staleness UI feedback
|
- INFO: Manual testing needed to verify overlay reliability improvements on physical device
|
||||||
- INFO: Manual testing needed after 03-02 to verify overlay reliability improvements
|
- INFO: All OVRL-01 through OVRL-06 requirements satisfied
|
||||||
|
|
||||||
**Phase 4 (GPS Optimization):**
|
**Phase 4 (GPS Optimization):**
|
||||||
- Speed thresholds (8/12 km/h) need field testing validation
|
- Speed thresholds (8/12 km/h) need field testing validation
|
||||||
@@ -120,7 +131,7 @@ Recent decisions affecting current work:
|
|||||||
|
|
||||||
## Session Continuity
|
## Session Continuity
|
||||||
|
|
||||||
Last session: 2026-02-11 (Plan 03-01 execution complete)
|
Last session: 2026-02-11 (Plan 03-02 execution complete)
|
||||||
Stopped at: Completed 03-01-PLAN.md — Phase 3 Plan 1 complete
|
Stopped at: Completed 03-02-PLAN.md — Phase 3 complete
|
||||||
Resume file: None
|
Resume file: None
|
||||||
Next action: Execute 03-02-PLAN.md (Overlay integration)
|
Next action: Begin Phase 4 (GPS Optimization) planning
|
||||||
|
|||||||
@@ -0,0 +1,139 @@
|
|||||||
|
---
|
||||||
|
phase: 03-overlay-refactor
|
||||||
|
plan: 02
|
||||||
|
subsystem: overlay
|
||||||
|
tags: [flutter, overlay, staleness, error-handling, provider, permission-handler, flutter-overlay-window]
|
||||||
|
|
||||||
|
# Dependency graph
|
||||||
|
requires:
|
||||||
|
- phase: 03-01
|
||||||
|
provides: OverlayService wrapper with retry logic, OverlayMessage timestamp tracking, staleness constants
|
||||||
|
provides:
|
||||||
|
- OverlayProvider delegates all platform calls to OverlayService with permission checks and verified creation
|
||||||
|
- Error callback mechanism connects OverlayProvider to SpeedometerScreen for snackbar surfacing
|
||||||
|
- Overlay screen detects stale GPS data (dim at 3s, dashes at 10s) with immediate snap-back on fresh data
|
||||||
|
- Permission errors surface to user with "Settings" action button that opens app settings
|
||||||
|
- GPS grace period timer (30s) starts on overlay close (infrastructure for Phase 4)
|
||||||
|
affects: [04-gps-optimization]
|
||||||
|
|
||||||
|
# Tech tracking
|
||||||
|
tech-stack:
|
||||||
|
added: [permission_handler]
|
||||||
|
patterns:
|
||||||
|
- Error callback pattern for provider-to-screen communication without BuildContext
|
||||||
|
- Staleness detection via timestamp comparison in build()
|
||||||
|
- Immediate snap-back on fresh data (no animation)
|
||||||
|
|
||||||
|
key-files:
|
||||||
|
created: []
|
||||||
|
modified:
|
||||||
|
- lib/providers/overlay_provider.dart
|
||||||
|
- lib/screens/overlay_screen.dart
|
||||||
|
- lib/screens/speedometer_screen.dart
|
||||||
|
- lib/main.dart
|
||||||
|
|
||||||
|
key-decisions:
|
||||||
|
- "OverlayProvider delegates ALL FlutterOverlayWindow calls to OverlayService (no direct usage)"
|
||||||
|
- "Error callback set by SpeedometerScreen after provider available (late binding for BuildContext)"
|
||||||
|
- "Staleness opacity applied via withValues(alpha:) to color (no AnimatedOpacity per user decision)"
|
||||||
|
- "GPS grace period timer created but does not yet control GPS lifecycle (Phase 4 scope)"
|
||||||
|
|
||||||
|
patterns-established:
|
||||||
|
- "OverlayError enum for typed error surfacing (permission, creationFailed, communicationDegraded)"
|
||||||
|
- "onError callback field on OverlayProvider set by SpeedometerScreen in postFrameCallback"
|
||||||
|
- "Staleness check timer runs every 1 second, dims at 3s, shows dashes at 10s"
|
||||||
|
- "Permission errors show snackbar with Settings action button via openAppSettings()"
|
||||||
|
|
||||||
|
# Metrics
|
||||||
|
duration: 4.25min
|
||||||
|
completed: 2026-02-11
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 03 Plan 02: Overlay Integration Summary
|
||||||
|
|
||||||
|
**OverlayService integration with permission checks, verified creation, staleness detection (3s dim/10s dash), and error surfacing via snackbars with Settings action**
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
- **Duration:** 4.25 min
|
||||||
|
- **Started:** 2026-02-11T10:20:25Z
|
||||||
|
- **Completed:** 2026-02-11T10:24:40Z
|
||||||
|
- **Tasks:** 2
|
||||||
|
- **Files modified:** 4
|
||||||
|
|
||||||
|
## Accomplishments
|
||||||
|
|
||||||
|
- OverlayProvider delegates all platform calls to OverlayService with permission checks before showing overlay
|
||||||
|
- Overlay creation verified via isActive() check before setting _isOverlayActive flag
|
||||||
|
- Overlay screen detects stale GPS data with two-stage visual feedback (dim at 3s, dashes at 10s)
|
||||||
|
- Permission errors surface to user via snackbar with "Settings" action button that opens app settings
|
||||||
|
- GPS grace period timer (30s) infrastructure created for Phase 4
|
||||||
|
|
||||||
|
## Task Commits
|
||||||
|
|
||||||
|
Each task was committed atomically:
|
||||||
|
|
||||||
|
1. **Task 1: Refactor OverlayProvider to use OverlayService with error callback and GPS grace period** - `66bdd35` (feat)
|
||||||
|
2. **Task 2: Add staleness detection to overlay screen and error surfacing to SpeedometerScreen** - `cc11a3d` (feat)
|
||||||
|
|
||||||
|
## Files Created/Modified
|
||||||
|
|
||||||
|
- `lib/providers/overlay_provider.dart` - Added OverlayService dependency, error callback mechanism, permission checks, verified creation, GPS grace period timer
|
||||||
|
- `lib/screens/overlay_screen.dart` - Added staleness monitoring timer, timestamp tracking, opacity-based dimming, dash display after 10s
|
||||||
|
- `lib/screens/speedometer_screen.dart` - Added error callback registration, _handleOverlayError method, snackbar surfacing with Settings action
|
||||||
|
- `lib/main.dart` - Registered OverlayService in MultiProvider, injected into OverlayProvider constructor
|
||||||
|
|
||||||
|
## Decisions Made
|
||||||
|
|
||||||
|
**OverlayProvider refactor:**
|
||||||
|
- All FlutterOverlayWindow calls replaced with OverlayService methods (showOverlay, closeOverlay, shareData, isActive, overlayListener)
|
||||||
|
- Permission check via _overlayService.checkPermission() before showing overlay
|
||||||
|
- Overlay creation success verified via _overlayService.showOverlay() return value (bool)
|
||||||
|
- _isOverlayActive only set after successful verification (prevents false positive active state)
|
||||||
|
- Error callback mechanism uses nullable function field set by SpeedometerScreen after provider available (late binding for BuildContext)
|
||||||
|
- GPS grace period timer (30s) starts on overlay close, cancelled on reopen or dispose (infrastructure only, Phase 4 will control GPS lifecycle)
|
||||||
|
|
||||||
|
**Overlay screen staleness detection:**
|
||||||
|
- _lastUpdateTime field tracks timestamp from OverlayMessage.timestamp
|
||||||
|
- Staleness check timer runs every 1 second (OverlayConfig.STALENESS_CHECK_INTERVAL)
|
||||||
|
- Timer callback shows "--" for speed after 10 seconds (OverlayConfig.STALENESS_DASH_THRESHOLD)
|
||||||
|
- Build() calculates staleness opacity (0.5 after 3s via OverlayConfig.STALENESS_DIM_THRESHOLD)
|
||||||
|
- Staleness opacity applied via color.withValues(alpha:) to speed text, unit text, heading icon, heading text
|
||||||
|
- No AnimatedOpacity used per user decision (immediate snap-back, no fade-in animation)
|
||||||
|
|
||||||
|
**SpeedometerScreen error surfacing:**
|
||||||
|
- Error callback registered in initState() postFrameCallback (after context available)
|
||||||
|
- _handleOverlayError shows snackbar with message and optional action button
|
||||||
|
- Permission error: snackbar with "Settings" action button that calls openAppSettings()
|
||||||
|
- Creation failure: snackbar with error message (no action button)
|
||||||
|
- Communication degraded: snackbar with error message (no action button)
|
||||||
|
- Error callback nulled in dispose() with try-catch (provider might already be disposed)
|
||||||
|
|
||||||
|
## Deviations from Plan
|
||||||
|
|
||||||
|
None - plan executed exactly as written.
|
||||||
|
|
||||||
|
## Issues Encountered
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
## Next Phase Readiness
|
||||||
|
|
||||||
|
**Phase 3 complete. Ready for Phase 4 (GPS Optimization):**
|
||||||
|
- Overlay communication is reliable with retry logic and verified creation
|
||||||
|
- Staleness detection provides visual feedback when GPS data is stale
|
||||||
|
- Error surfacing gives users actionable guidance (permission Settings button)
|
||||||
|
- GPS grace period timer infrastructure exists for Phase 4 GPS lifecycle management
|
||||||
|
- All OVRL-01 through OVRL-06 requirements satisfied
|
||||||
|
|
||||||
|
**Phase 4 blockers:**
|
||||||
|
- None
|
||||||
|
|
||||||
|
**Phase 4 dependencies satisfied:**
|
||||||
|
- GPS grace period timer exists (Phase 4 will control GPS subscription start/stop)
|
||||||
|
- Overlay active state is reliable (verified creation, status check monitoring)
|
||||||
|
- Background heartbeat only runs when overlay active AND app backgrounded (ready for GPS optimization)
|
||||||
|
|
||||||
|
---
|
||||||
|
*Phase: 03-overlay-refactor*
|
||||||
|
*Completed: 2026-02-11*
|
||||||
Reference in New Issue
Block a user