Tap-to-navigate delegation to scenario-deep-link-router
epic-scenario-push-engagement-ui-task-007 — Implement tap handling on the in-app-notification-banner that delegates navigation to scenario-deep-link-router (578). Pass the notification's scenario type and contextual payload so the router resolves the correct destination screen (e.g., activity wizard). Dismiss the banner immediately on tap.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Add an optional onTap callback to the banner widget constructor (onTap: VoidCallback?) — the widget itself does not know about the router; the OverlayController or the Riverpod consumer that creates the OverlayEntry supplies the onTap closure that calls ref.read(scenarioDeepLinkRouterProvider).navigate(...). This keeps the widget decoupled from routing. To prevent double-navigation, use a bool _navigating flag in the OverlayController and set it to true before calling navigate. Always dismiss (remove the OverlayEntry) before calling the router so the banner is gone regardless of whether navigation succeeds.
Ensure the navigator context used in the router call is the root navigator context stored at app startup, not the overlay entry's BuildContext, which may be unmounted by the time the async navigation resolves.
Testing Requirements
Write widget tests: tap the banner body and assert the mock router was called with the correct scenario_type and payload; assert the banner is no longer in the widget tree after the tap. Tap the dismiss button and assert the router was NOT called. Simulate a double-tap and assert router.navigate was called exactly once. Test the fallback: configure the mock router to throw an UnknownRouteException and assert the banner is still dismissed.
Write a unit test for the tap guard (boolean flag) in the handler function to confirm double-call protection. Manual test on device: verify the activity wizard opens when tapping a notification banner with scenario_type = 'activity_prompt'.
The in-app notification banner depends on a Supabase Realtime subscription to detect new notification records. If the subscription reconnects slowly after an app resume from background, or if Realtime delivery is delayed under high load, the banner may not appear within the 2-second acceptance criterion.
Mitigation & Contingency
Mitigation: Implement an explicit subscription reconnect handler on app foreground events using Flutter's AppLifecycleState.resumed hook, and add a polling fallback that queries for unread notifications once per app foreground event as a safety net against missed Realtime events.
Contingency: If Realtime proves unreliable in production, promote the polling fallback to the primary mechanism with a 30-second interval, accepting slight latency in exchange for reliability.
Cold-start deep linking (app not running when push notification is tapped) requires deferred navigation after the Flutter engine and Supabase session are fully initialised. If the deep link is consumed before authentication completes, the router may navigate to a protected route without a valid session, causing an error or redirect loop.
Mitigation & Contingency
Mitigation: Implement a deferred navigation queue in scenario-deep-link-router that holds the parsed deep-link target until the auth session restoration lifecycle event fires, following the existing deep-link-handler pattern used in the BankID and Vipps authentication flows.
Contingency: If deferred navigation is not achievable within the epic's scope, fall back to navigating the user to the notification centre (which is always accessible post-login) where the relevant notification record is visible and tappable.