Implement shared_preferences persistence layer
epic-navigation-and-gesture-accessibility-foundation-task-002 — Implement the NavigationStateRepository backed by shared_preferences. The repository must support read/write for tab index and per-tab sub-route stack snapshots. Expose typed async methods: saveTabIndex, loadTabIndex, saveStackSnapshot, loadStackSnapshot, clearAll. Handle cold start (no stored data), resume, logout, and role-switch by calling clearAll when appropriate lifecycle events are received.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use a constant prefix map or a static const List
Serialize snapshots with jsonEncode(snapshot.toJson()) and deserialize with NavigationStackSnapshot.fromJson(jsonDecode(stored)) wrapped in try/catch to handle corrupted data gracefully (return null on parse error).
Testing Requirements
Unit tests in task-003 cover all persistence methods using SharedPreferences.setMockInitialValues(). This task should include integration smoke tests that run against a real SharedPreferences instance on a test device (or via integration_test package) to verify actual disk persistence across app restart simulation. Specifically test: save tab index → restart simulation → load tab index returns the saved value. Cover all 5 tab indices.
Test clearAll() by saving data for all tabs then calling clearAll() and asserting every loadX() returns null.
StatefulShellRoute branch navigator state can interact unexpectedly with GoRouter's imperative navigation (go, push, replace), causing state snapshots to desync from actual route stacks. This could manifest as a user returning to a tab and seeing a different screen than expected, breaking the core motor-fatigue promise.
Mitigation & Contingency
Mitigation: Write integration tests that simulate cross-tab navigation with nested pushes before any UI layer is built. Pin go_router to a tested minor version and review the StatefulShellRoute changelog before upgrading.
Contingency: If branch navigator state consistently desyncs, fall back to a manual stack snapshot strategy using a custom NavigatorObserver that records and replays navigation events independently of StatefulShellRoute internals.
Persisted navigation stacks in shared_preferences can become stale or corrupt if route paths are renamed during development, causing app crashes or infinite redirect loops on cold start for users who have an old snapshot.
Mitigation & Contingency
Mitigation: Version the persisted schema with a format key. On app start, validate that all stored route paths exist in the current route config before restoring; silently discard invalid entries rather than crashing.
Contingency: Implement a safe-mode cold start that skips state restoration after a detected crash (via a dirty-launch flag written at startup and cleared on successful first frame), falling back to the default root tab.