Reference
Caveats
Known limits around breakpoints, overlays, pop semantics and the web.
Crossing a breakpoint keeps state
Page State is kept when the window crosses 600 or 840 (Navigator β viewport, branch β cover Navigator). Page subtrees carry a stable
GlobalKey and a transition delegate swaps them without an exit animation. It is dropped only when the page leaves the stack. Keep durable data in the URL, a signal, or a store anyway.
Pane overlays are clipped
Dialogs, menus, and sheets inside a column should use the root overlay: useRootNavigator: AdaptivePaneScope.maybeOf(context) != null. On compact, a tab-root sheet stays on the nearest navigator and covers the bottom bar only when the shell uses
AdaptiveShellChrome.
Context-free pop
Context-free pop / maybePop (including Escape and system back) only handle the top pane and root / shell popups that cover everything. A pane-local sheet / dialog in the
other pane is not closed by them: use maybePopFrom(context), or
Navigator.pop(context) from inside the popup. Stacked popups close outermost first (root β shell β pane).
When onExit runs
onExit runs for maybePop, system back, and browser back, after the top page's
PopScope. At the bottom of the stack, system back asks the route's onExit
before the app exits. pop / pushReplacementNamed
/ pushNamedAndRemoveUntil run immediately, like Navigator.
Web
Web keeps hash URLs. The platform's initial route wins over initialLocation
when it is not /.