Model navigation as application state when URLs, deep links, restoration, or multiple navigators require it; use simpler imperative navigation for genuinely local flows.
Inspect first
Identify the current router, route ownership, authentication flow, tab/shell structure, supported platforms, URL requirements, and state restoration expectations. Preserve the existing routing package unless migration is requested.
Rules
- Keep route names, path parameters, and argument decoding typed or centrally validated.
- Make redirect logic deterministic and free of redirect loops.
- Preserve intended back behavior across Android system back, browser history, iOS gestures, nested navigators, and modals.
- Use nested navigation only for independent histories such as tab shells.
- Parse deep links into domain-safe state and define behavior for unknown or unauthorized destinations.
- Keep navigation side effects outside widget
build. - Do not place large domain objects directly in URLs or restoration state.
Verification
Test cold deep links, warm links, back/forward behavior, authentication redirects, invalid parameters, restoration where required, and each supported shell/tab history.
References
When tab shell patterns or independent back histories are in scope, follow the nested shell navigation reference. When handling deep links or state restoration, follow the deep link and restoration reference.