Mikkeli Matlock
8bc1e392a5
- Created SUMMARY.md documenting lifecycle-aware GPS engine implementation - Updated STATE.md to Phase 4 Plan 1 of 2 complete (70% progress) - Added 6 key decisions to STATE.md decisions table - Updated performance metrics: 7 plans, 4.9 min average for Phase 4 - Updated session continuity and blockers sections - Documented self-check results: all files and commits verified Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
150 lines
8.1 KiB
Markdown
150 lines
8.1 KiB
Markdown
# Project State
|
|
|
|
## Project Reference
|
|
|
|
See: .planning/PROJECT.md (updated 2026-02-09)
|
|
|
|
**Core value:** Reliable, lag-free GPS speed display that coexists politely with other Android apps
|
|
**Current focus:** Phase 4 - GPS Optimization
|
|
|
|
## Current Position
|
|
|
|
Phase: 4 of 4 (GPS Power Optimization)
|
|
Plan: 1 of 2 complete
|
|
Status: In progress
|
|
Last activity: 2026-02-12 — Completed 04-01-PLAN.md
|
|
|
|
Progress: [███████░░░] 70% (Phase 4: 1/2 plans complete)
|
|
|
|
## Performance Metrics
|
|
|
|
**Velocity:**
|
|
- Total plans completed: 7
|
|
- Average duration: 6.0 minutes
|
|
- Total execution time: 0.71 hours
|
|
|
|
**By Phase:**
|
|
|
|
| Phase | Plans | Total | Avg/Plan |
|
|
|-------|-------|-------|----------|
|
|
| 1. Foundation | 2 | 19.6 min | 9.8 min |
|
|
| 2. Provider Migration | 2 | 11.5 min | 5.75 min |
|
|
| 3. Overlay Refactor | 2 | 8.25 min | 4.1 min |
|
|
| 4. GPS Optimization | 1 | 4.9 min | 4.9 min |
|
|
|
|
**Recent Trend:**
|
|
- Last 5 plans: 02-02 (3.8 min), 03-01 (4.0 min), 03-02 (4.25 min), 04-01 (4.9 min)
|
|
- Trend: Consistent sub-5-minute plans continuing in Phase 4
|
|
|
|
*Updated after each plan completion*
|
|
|
|
## Accumulated Context
|
|
|
|
### Decisions
|
|
|
|
Decisions are logged in PROJECT.md Key Decisions table.
|
|
Recent decisions affecting current work:
|
|
|
|
| Phase | Plan | Decision | Status |
|
|
| ----- | ----- | ---------------------------------------------------- | -------------- |
|
|
| 01 | 01 | SCREAMING_SNAKE naming for behavioral constants | Implemented |
|
|
| 01 | 01 | Logger replaces print()/customDebugPrint() globally | Implemented |
|
|
| 01 | 01 | OverlayMessage typed class for IPC | Implemented |
|
|
| 01 | 01 | ThemeModel delegates to ColorThemes | Implemented |
|
|
| 01 | 01 | Layer-first directory structure | Implemented |
|
|
| 01 | 02 | SpeedometerScreen extracted to dedicated file | Implemented |
|
|
| 01 | 02 | OverlaySpeedometer extracted to dedicated file | Implemented |
|
|
| 01 | 02 | main.dart as pure entry point (now 65 lines) | Implemented |
|
|
| 02 | 01 | GpsDataManager singleton removed, ChangeNotifier added | Implemented |
|
|
| 02 | 01 | SettingsProvider combines theme + units | Implemented |
|
|
| 02 | 01 | OverlayProvider continuous GPS stream subscription | Implemented |
|
|
| 02 | 01 | SharedPreferences pre-initialized in async main() | Implemented |
|
|
| 02 | 02 | Speed Selector uses context.read<SettingsProvider>() | Implemented |
|
|
| 02 | 02 | Background heartbeat stays in screen (not provider) | Implemented |
|
|
| 02 | 02 | _isInBackground direct assignment (no setState) | Implemented |
|
|
| 03 | 01 | OverlayService wraps all FlutterOverlayWindow calls | Implemented |
|
|
| 03 | 01 | showOverlay verifies with isActive() post-call | Implemented |
|
|
| 03 | 01 | shareData fire-and-forget (no retry, warn logging) | Implemented |
|
|
| 03 | 01 | Staleness thresholds: 3s dim, 10s dash | 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 | 01 | Speed-adaptive GPS precision (8/12 km/h hysteresis) | Implemented |
|
|
| 04 | 01 | Precision switching gated until 5s after first fix | Implemented |
|
|
| 04 | 01 | Background grace period re-checks overlay at expiry | Implemented |
|
|
| 04 | 01 | Wake lock contextual: GPS + (overlay OR foreground) | Implemented |
|
|
| 04 | 01 | GPS stop preserves last data for staleness display | Implemented |
|
|
| 04 | 01 | BACKGROUND_GRACE_PERIOD (7s) replaces GPS_GRACE_PERIOD| Implemented |
|
|
|
|
### Pending Todos
|
|
|
|
**Phase 1 Complete - Verification Needed:**
|
|
- [ ] Run full functionality test on physical Android device (non-blocking checkpoint from 01-02)
|
|
- [ ] Verify speed display, theme/unit cycling, overlay launch/close, landscape mode
|
|
- [ ] Confirm Logger output format in debug console
|
|
|
|
**Phase 2 Complete - Manual Testing Needed:**
|
|
- [x] 02-01 complete — Provider infrastructure created (7.7 min)
|
|
- [x] 02-02 complete — MultiProvider wiring and screen migration (3.8 min)
|
|
- [x] All shared state moved to Provider pattern
|
|
- [x] Zero setState calls for shared state (only _errorMessage local state)
|
|
- [ ] Manual testing: Settings persistence, theme/unit cycling, overlay toggle, background heartbeat
|
|
- [ ] Manual testing: Verify no "setState after dispose" or "ChangeNotifier after dispose" errors
|
|
|
|
**Phase 3 Complete:**
|
|
- [x] 03-01 complete — Overlay foundation infrastructure (4.0 min)
|
|
- [x] 03-02 complete — Overlay integration with staleness detection (4.25 min)
|
|
- [x] OverlayProvider delegates all platform calls to OverlayService
|
|
- [x] Permission checks before overlay creation, verified creation via isActive()
|
|
- [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
|
|
|
|
**Phase 1 (Complete):**
|
|
- RESOLVED: All structural requirements (ORG-01 through ORG-08) satisfied
|
|
- LOW: SCREAMING_SNAKE analyzer warnings (21 intentional info-level warnings) — Consider `analysis_options.yaml` exclusion if noise becomes issue
|
|
- LOW: Logger severity level guidelines should be documented for contributors
|
|
- INFO: Phase 1 functionality testing deferred to user-initiated session (non-blocking checkpoint)
|
|
|
|
**Phase 2 (Complete):**
|
|
- RESOLVED: Provider infrastructure complete — 3 ChangeNotifier classes created
|
|
- RESOLVED: MultiProvider wiring complete with pre-initialized SharedPreferences
|
|
- RESOLVED: SpeedometerScreen migrated to Provider pattern (799 lines → 493 lines, -38%)
|
|
- RESOLVED: Zero setState calls for shared state (theme, unit, GPS data, overlay status)
|
|
- INFO: Manual testing needed to verify settings persistence and provider lifecycle
|
|
|
|
**Phase 3 (Overlay Refactor) — Complete:**
|
|
- RESOLVED: OverlayService foundation complete with retry logic
|
|
- RESOLVED: OverlayProvider integration complete with permission checks and verified creation
|
|
- 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)
|
|
- INFO: Manual testing needed to verify overlay reliability improvements on physical device
|
|
- INFO: All OVRL-01 through OVRL-06 requirements satisfied
|
|
|
|
**Phase 4 (GPS Optimization) - In Progress:**
|
|
- RESOLVED: Core GPS engine complete with lifecycle awareness and precision switching
|
|
- RESOLVED: ProcessedGpsData timestamp field added for staleness detection
|
|
- RESOLVED: Background grace period (7s) with race condition protection
|
|
- RESOLVED: Conditional wake lock (GPS active + visible)
|
|
- INFO: Plan 04-01 complete (4.9 min) — ready for Plan 04-02 (UI Integration)
|
|
- PENDING: SpeedometerScreen needs gpsDataManager.setOverlayProvider() call
|
|
- PENDING: Background heartbeat (5s) may need adjustment vs 7s grace period
|
|
- FIELD TESTING: Speed thresholds (8/12 km/h) need validation on physical device
|
|
- FIELD TESTING: Android OEM behavior varies (Samsung, Xiaomi duty-cycling differences)
|
|
|
|
## Session Continuity
|
|
|
|
Last session: 2026-02-12 (Plan 04-01 execution complete)
|
|
Stopped at: Completed 04-01-PLAN.md — Phase 4 in progress (1/2 plans)
|
|
Resume file: None
|
|
Next action: Execute Plan 04-02 (UI Integration)
|