Document navigation foundation contracts and integration guide
epic-navigation-and-gesture-accessibility-foundation-task-014 — Write developer documentation covering: the router contract (how to declare a new route with PopScope and RouteMetadata), the TabStateManager API (how UI components consume activeTabIndex and stack snapshots), the NavigationStateRepository lifecycle (when state is cleared, what triggers persistence), and the accessibility context change stream contract. Include code examples for each integration point so that teams building UI widgets on top of this foundation can do so without reading implementation internals.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Follow the existing documentation style in the project (check docs/ or README for conventions before writing). Structure the document with an overview diagram showing the four components and their relationships, then one section per contract. For the code examples, use minimal but realistic snippets — show just enough context that the reader knows where the code goes (e.g., inside build(), inside a provider definition). Explicitly document the negative cases: what happens if a component calls setActiveTab before hydration completes, what happens if RouteMetadata is missing, what happens if the accessibility stream subscription is never cancelled.
These are the questions that will surface during implementation and having the answers in the guide saves future debugging time.
Testing Requirements
Documentation does not require automated tests, but each code example should be verified to compile against the actual source (e.g., by including it in a doc_test/ directory or running dart analyze on the snippets). A peer review by one team member who was not involved in the epic implementation is the acceptance gate — they should confirm the guide is sufficient to implement a new route without asking clarifying questions.
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.