Build FocusManagementService core with route transition focus
epic-screen-reader-support-core-services-task-003 — Implement the FocusManagementService as a singleton service that intercepts GoRouter route transitions and places VoiceOver/TalkBack focus on the first meaningful semantic node of the incoming screen. Handle both push and pop transitions, ensuring that on pop the focus returns to the element that triggered the navigation (e.g., the button that opened a detail screen).
Acceptance Criteria
Technical Requirements
Implementation Notes
Listen to GoRouter state changes via GoRouter.routerDelegate.addListener or a custom NavigatorObserver. On push, schedule focus placement with WidgetsBinding.instance.addPostFrameCallback to ensure the incoming screen is fully mounted. To find the 'first meaningful node', traverse the new route's BuildContext semantic tree looking for a node with SemanticsFlag.isHeader first, then fall back to the first node with SemanticsAction.tap or SemanticsFlag.isTextField. Implement the trigger registry as a simple stack (List
For StatefulShellRoute, maintain a per-branch Map
Testing Requirements
Unit tests: mock GoRouter delegate and verify registerNavigationTrigger() + push produces a focus placement call on the correct GlobalKey; verify pop restores focus to the registered trigger key; verify fallback to ancestor when trigger key is unmounted. Widget tests with flutter_test: pump a two-screen Navigator, call push, assert SemanticsNode.hasFocus on the destination heading. Integration tests: full activity registration flow — navigate from home to wizard, assert each screen's heading receives focus on arrival; pop from wizard, assert the originating button regains focus. Platform integration tests on iOS and Android via TestFlight builds.
Flutter's build pipeline and SemanticsService.announce() operate asynchronously. Announcements triggered too early (before the semantic tree settles) may be swallowed silently on both platforms, causing acceptance criteria around the 500ms window to fail intermittently in CI and on device, which would block pilot launch.
Mitigation & Contingency
Mitigation: Implement the LiveRegionAnnouncer with a post-frame callback delay and an internal timing guard. Write integration tests using WidgetTester.pump() sequences that verify announcement delivery across multiple frame boundaries. Validate on physical devices at each sprint boundary, not only in CI.
Contingency: If consistent announcement timing cannot be achieved within Flutter's semantic pipeline, switch to a platform channel approach that calls native UIAccessibility.post (iOS) and AccessibilityManager.announce (Android) directly, bypassing Flutter's intermediary.
Flutter does not natively emit a focus-gain event to Dart code when VoiceOver or TalkBack moves focus to a specific widget. If the intercept mechanism for the SensitiveFieldWarningDialog relies on an unsupported or undocumented hook in the semantics tree, it may miss focus events for some field types or in some navigation contexts, leaving sensitive data unprotected.
Mitigation & Contingency
Mitigation: Prototype the focus-intercept mechanism during the first sprint of this epic, before building the dialog UI. Evaluate Flutter's SemanticsBinding.instance callbacks and custom SemanticsActions as intercept points. Document the chosen mechanism with platform compatibility notes.
Contingency: If no reliable focus-intercept is available, implement an alternative where sensitive fields show a static 'Screen reader active — tap to reveal' overlay instead of an OS dialog, which is less seamless but achieves equivalent privacy protection without relying on an unreliable event hook.
The AccessibilityTestHarness depends on internal flutter_test semantic tree APIs that can change between Flutter minor versions. If the project upgrades Flutter during this epic, the harness may break silently, causing CI accessibility tests to pass while actually skipping assertions.
Mitigation & Contingency
Mitigation: Pin the Flutter SDK version in pubspec.yaml for the duration of this epic. Document which flutter_test APIs are used and their stability tier. Add a canary test that explicitly fails if the semantic tree API surface changes.
Contingency: If a forced Flutter upgrade breaks the harness, prioritise patching the harness as a blocking task before any other epic work continues, using the canary test failure as the trigger.