navigation-and-routing

Navigation and routing

This skill owns app navigation with go_router. There is exactly ONE GoRouter for the app, defined in lib/routing/, and every screen is reachable by a URL. Navigation is a data structure (routes + a pure redirect), not a pile of imperative Navigator.push calls.

Read the reference for the task at hand:

• references/go-router-config.md — the single router, context.go vs context.push, path params vs state.extra, typed route helpers, errorBuilder/404.
• references/guards-and-redirects.md — pure redirect functions, the Riverpod refreshListenable, auth + onboarding gates, avoiding redirect loops.
• references/shells-and-deep-links.md — StatefulShellRoute.indexedStack for bottom-nav/rail shells, CustomTransitionPage, PopScope, and notification-payload → location mapping.

Run scripts/check_routing.sh before a PR.

Non-negotiable rules

1. Exactly ONE GoRouter, built in lib/routing/, wired once via MaterialApp.router in app.dart. Multiple routers fragment history, deep links, and back-button behaviour. The router is created behind a provider so guards can watch app state.
2. Deep-linkable identity lives in PATH PARAMS, never in state.extra. extra is a live Dart object: it is null on a cold start from a deep link and after process death / restoration. A screen that needs an id to rebuild must read it from state.pathParameters so the URL alone fully reconstructs the screen.
3. state.extra is ONLY an optional non-identity optimisation (a pre-fetched object to avoid a reload flash). The screen must still work — refetch by id — when extra is null.
4. Use context.go to replace the stack (declarative destinations, tabs, post-login home); use context.push to stack a screen you expect to pop back from (a detail, a modal flow). Mixing them wrong breaks the back button. Know which one every call site needs.
5. Guards are PURE redirect functions. redirect returns a new location String? (or null to allow) from GoRouterState + a snapshot of app state. No I/O, no navigation calls, no side effects inside redirect — it runs on every navigation and can run repeatedly.
6. Reactive guards use a refreshListenable, not polling. Bridge the Riverpod auth/onboarding provider to a Listenable; the router re-evaluates redirect whenever it fires. See state-management-riverpod.
7. Redirects must be loop-free. Always allow the destination the guard sends you TO (e.g. never redirect /sign-in back to /sign-in). Guard against A→B→A by checking the current location before redirecting.
8. Tab/branch shells use StatefulShellRoute.indexedStack. It preserves each branch's navigation stack and state across tab switches; a plain ShellRoute with an IndexedStack you wire by hand does not survive router rebuilds as cleanly. Switch branches with navigationShell.goBranch(index).
9. Custom transitions go through CustomTransitionPage and respect reduced motion. When the platform requests reduced motion, collapse to a no-op/fade. Read the flag from MediaQuery, resolve motion via the design system — see accessibility-as-code and design-system-structure.
10. Intercept back / unsaved changes with PopScope, not WillPopScope (removed). Set canPop: false and handle in onPopInvokedWithResult(bool didPop, T? result); only navigate away after the user confirms.
11. Provide an errorBuilder and a real 404/error route. An unmatched deep link must land on a designed error screen, never a red error box.
12. Never hold a BuildContext across an await before navigating. Capture GoRouter.of(context) (or the router) before the await, or guard with context.mounted after. See async-safety.
13. A feature does not build its own router. scaffold-feature-module registers a feature's GoRoute INTO this router's route list; features never instantiate GoRouter.