back_stack

iOS swipe-back on TransitionPage

• The edge-swipe back gesture now works on pages with custom transitions. TransitionPage used to build a plain PageRoute, so on iOS the standard drag-from-the-left-edge gesture did nothing — a screen pushed with .fade or a shared-axis transition could only go back via a button. On iOS (defaultTargetPlatform), dragging from the leading edge now drives the page's own transitionsBuilder in reverse and pops past the halfway point or on a fling, exactly like CupertinoPageRoute — and the pop syncs the NavStack as usual. RTL layouts swipe from the right edge.
• New swipeBack parameter on every TransitionPage constructor to opt a page out (defaults to true; TransitionPage.none defaults to false). The gesture also stays off for fullscreenDialog pages, non-opaque pages, the root of the stack, and any screen whose PopScope/ConfirmPopScope blocks the pop — same rules as the framework's popGestureEnabled. (Like the AppBar back button, it goes through the Navigator, so the programmatic-pop veto stack.popGuard doesn't apply.)
• No behavior change on Android or desktop, and zero dependencies as always.

A correctness release for everything back-button-adjacent, driven by an adversarial audit of 0.4.0. Still zero dependencies.

System back now routes innermost-first, everywhere

• Tabs: OS back reaches the active tab's Navigator first. MultiNavStackRouterDelegate.popRoute() (and MultiNavDisplay's own PopScope) used to pop the active tab's stack model directly, skipping the tab's routes entirely — back would pop the page under an open dialog, or leave the app with a dialog still up, and a screen's PopScope/ConfirmPopScope inside a tab never saw the gesture. Back now goes through the active tab's navigator via maybePop (dialog → screen's PopScope → tab page → first-tab fallback → app close), tracked live via NavigationNotification so an open dialog is known even at a tab root. The delegate exposes its per-tab navigatorKeys, and MultiNavDisplay accepts navigatorKeys: for custom Router setups.
• NavDisplay(nested: true) routes back through its child navigator the same way, instead of popping the stack directly — dialogs, sheets and PopScopes inside a nested display now get first refusal.

AsyncRedirect: no flash of protected content, fail closed

• New gates: predicate — declare what's protected. Navigation matching gates is now held off screen while check runs: the stack stays where it is (as the docs always claimed), resolving drives your scrim, and the held navigation is applied — or bounced — when the check resolves. Everything not matching gates navigates instantly and is never checked, so pops and pushForResult results are unaffected. Without gates the old show-then-correct behavior remains (holding everything would swallow ordinary results); pass gates to get the hold.
• A throwing check now fails closed: the navigation is dropped, the user stays put, and the error is reported via FlutterError.reportError (it used to be silently allowed — an auth gate that failed open).
• A pushForResult into an undecided gated destination resolves null immediately; un-gated destinations are unaffected. Documented.

Browser back/forward restores the full typed stack

• Each history entry now carries a full-stack snapshot (RouteInformation.state), so a browser back/forward hop restores the entire typed stack — in-app depth the URL can't express included — instead of rebuilding from the URL's projection. Automatic in BackStackApp/BackStackTabsApp when links (or restoreWith) is set; custom Router setups opt in via the delegates' new stateCodec. A missing, corrupt, or URL-disagreeing snapshot falls back to the URL mapping, exactly like a deep link. The tabs snapshot covers every tab's stack plus the active tab.
• Breaking (type-level only): the delegates' Router configuration type changed from Uri to NavRouteInformation (uri + state), and NavStackRouteInformationParser now parses that type. Apps using BackStackApp/BackStackTabsApp are unaffected; direct setNewRoutePath(uri) callers wrap the uri: NavRouteInformation(uri). The imperative link API (handleLink/handleLinkAsync) still takes a plain Uri.

Fixes

• Tabs observers could never work — replaced with observersFor. A NavigatorObserver belongs to exactly one Navigator (the framework asserts it), but the tabs widgets attached the same list to every tab's navigator — any non-empty observers with 2+ tabs crashed in debug on the first frame. MultiNavDisplay/MultiNavStackRouterDelegate/ BackStackTabsApp now take observersFor: (tabIndex) => [...], called once per tab; observers remains for single-tab hosts and is rejected with a clear message otherwise.
• Core: a redirect no longer breaks pushForResult. _commit reconciled the redirect's result against the pre-change stack, so any attached redirect — even one that allowed the navigation unchanged — rebuilt the just-pushed entry with a fresh identity and its pushForResult awaiter resolved null. The redirect result now reconciles against the proposed entries, keeping the pushed entry's id (and awaiter) when it's allowed through.
• BackStackApp with no links/onLink: a runtime deep link now keeps the app where it is (as documented) instead of resetting navigation to its launch state.
• Memoized pages no longer freeze inherited reads. A screen built by builder/entries now rebuilds when a Theme / localization / media-query dependency changes — previously a live entry's screen was built exactly once and silently never updated.

Docs

• README: clarified that restoration restores the stack (destinations, in order, typed); state inside a screen follows Flutter's own restoration APIs.
• NavStackCodec: documented that browser back/forward rebuilds the stack from the URL via decode, like a deep link — in-app depth beyond the URL's projection isn't preserved across a history hop.

The "handled internally" release: the app shapes and URL plumbing every real app needs, each reduced to one parameter — plus a hardening pass over the core. Still zero dependencies.

One source of truth for URLs

• NavLinks — the URL table. One entry per linkable destination declares both directions at once ('/products/:id' ⇄ Product), with typed parameter reads (NavMatch), query parameters, *rest catch-alls, a per-destination parents: (the layer-vs-replace choice), and notFound. Deep links, the web address bar, browser back/forward, shareable links (linkFor) and state restoration all derive from the same table, so the two directions can never drift apart. It's a NavStackCodec, so it plugs in anywhere one goes — usually BackStackApp(links: …). It never owns the stack; back_stack still has no route graph.
• Round-trip drift validator. In debug builds the router verifies encode∘decode is idempotent per URL and reports a drifted codec the moment it's introduced — the classic hand-written onLink/toLink bug, caught at development time.

One-widget apps

• BackStackApp is now a true one-widget app: onLink is optional (BackStackApp(stack: …, entries: …) is a complete app), it accepts links: and entries: directly, and it forwards the previously missing MaterialApp knobs (onGenerateTitle, scaffoldMessengerKey, locale callbacks, high-contrast themes, shortcuts/actions, appBuilder). A shell: parameter wraps persistent chrome (side rail, overlays) around the navigating area, under MaterialApp. Config (onLink/toLink/builder) is read live, so hot reload and rebuilds take effect without losing navigation state.
• BackStackTabsApp — the tabbed app, bundled. Bottom navigation with a persistent back stack per tab used to take up to nine hand-wired objects; it's now one widget: pass tabs: + destinations: (built-in NavigationBar, selection and re-tap-to-pop-to-root wired) or shell: (your own chrome). Works with links: — the target tab is inferred from the decoded stack's root — plus onLinkAsync, initialLink/linkStream, lazy tabs, and automatic restoration of every tab's stack + the active tab.

Async everywhere

• Async link resolution — onLinkAsync on both apps (and asyncDecode on both router delegates): await a lookup before deciding what a link shows. Race-safe by design: a newer link supersedes an in-flight one, and errors fall through to the sync mapping.
• Async pop — NavStack.popGuardAsync + tryPop(): an "are you sure?" dialog or save-before-leave call for programmatic pops, race-safe (if the stack changes while the guard is deciding, nothing is popped).
• AsyncRedirect.attach(stack) wires redirect + refreshListenable in one call — forgetting the second half used to make gating silently hang. detach() undoes it; dispose() auto-detaches. Also hardened: disposing mid-check no longer crashes, and the decision cache is bounded (cacheSize) and keyed by real element-wise equality instead of a raw hash.

Full-stack restoration, automatic

• With links: set, the entire typed stack (and for tabs: every tab's stack + the active tab) survives process death — serialized through the same URL table, unregistered keys skipped, corrupt snapshots discarded. restoreWith: accepts a NavKeyCodec for destinations without URLs. A cold-start deep link still wins over the snapshot unless the snapshot is just the deeper history of the same location. (RestorableBackStack / RestorableMultiNavStack remain for Router-free setups.)

Per-destination presentation

• NavEntries.on<T>(page: …) — a destination can carry its own dialog, sheet, or transition, with decorators still applied: no global pageBuilder switch and no mixin on domain keys. Displays and delegates accept the registry directly (entries: as the alternative to builder:).

Typed navigation events, ergonomics & sugar (from the previous batch)

• NavStackObserver<K> — typed onScreen/onPush/onPop in your keys.
• NavPath — typed URL reading/building sugar for hand-written codecs.
• Ergonomic stack ops: pushAll, popToRoot, removeWhere.
• BackStackApp.initialLink — cold-start link, awaited and applied through the same mapping.
• pushOrMoveToTop now returns whether the stack changed — making it the double-tap-proof push (a second tap is a no-op, not a duplicate screen).
• replaceTop(key, result: …) completes the replaced screen's pushForResult awaiter with a value.
• pushForResult's result type is checked at the pop(result) call site in debug, instead of failing later as a cast error inside the await.

Fixes & hardening

• NavDisplay page memoization survives parent rebuilds with the documented entries.call tear-off (function equality instead of identity), and onRemoved still fires after a builder swap.
• popToRoot is one commit and respects popGuard on the current top; tab re-select uses the same semantics (one notification, protected forms stay).
• A deep link targeting an out-of-range tab now falls back instead of being silently dropped.
• Applying a platform route identical to the current location is a no-op (protects restored deep stacks from being collapsed to their URL projection).
• NavLinks/link decoding never throws — including trailing slashes and URLs whose percent-escapes aren't even valid UTF-8.
• Shell chrome gets its own Overlay (tooltips/menus in a bottom bar work).
• Shared-axis and fade-through transitions animate at the render-object level (no per-frame widget rebuilds).
• BackStack.of/MultiBackStack.of/parentOf throw real FlutterErrors in all build modes, with a "did you forget the type argument?" hint; maybeParentOf stops walking once found; custom pages that drop the supplied pageKey are caught by a debug assert (they would silently desync system back).
• The package archive no longer ships the 2 MB demo gif (3 MB → ~0.1 MB).

A feature drop aimed at everyday UX — all within the same few-concepts, zero-dependency model (nothing here changes how you own the stack).

• AsyncRedirect — loop-proof async auth gating. redirect stays synchronous (that's what makes it loop-proof), so async gates that need to await — a permission call, a session refresh, a "does this deep-linked doc exist" check — now have a first-class home. Assign gate.call to redirect and the gate to refreshListenable: navigating to a gated destination holds it while the check runs (gate.resolving drives a loading overlay), then either allows it or redirects. Decisions are cached per destination so a check runs once; call gate.invalidate() after login/logout. Built entirely on the existing sync primitives — the core is unchanged.
• Material motion transitions on TransitionPage. Adds sharedAxisHorizontal / sharedAxisVertical / sharedAxisScaled (X/Y/Z) and fadeThrough alongside the existing fade/slideUp/scale. Hand-rolled, dependency-free, and the shared-axis / fade-through motions animate the outgoing screen too. Pick the motion by the relationship between screens (peer step, into-a-hierarchy, unrelated switch).
• Migration guide from go_router (doc/MIGRATING_FROM_GO_ROUTER.md) — a mapping table plus before/after for routes, navigation calls, typed arguments, redirects (incl. async), shell/tab routes, deep links and error handling, with notes on migrating gradually.
• Examples: example/lib/guarded.dart (async gating with a loading overlay) and example/lib/motion.dart (per-destination Material motion).

• Async deep links from native. The platform's Router only surfaces the launch URL and standard app links it resolves itself. Links that arrive while the app runs — a custom scheme (myapp://…), a Firebase Dynamic Link, a warm app_links link — come from a native plugin as a Stream<Uri>. BackStackApp now takes an optional linkStream: hand it that stream and every emission runs through the same onLink, with the same never-throws fallback as a platform link. back_stack owns the subscription lifecycle and cancels it on dispose; you bring the Uris from whatever plugin you use — no new dependency.
• NavStackRouterDelegate.handleLink(uri) / MultiNavStackRouterDelegate.handleLink(uri) — the imperative sibling of setNewRoutePath, for driving your own router: apply a runtime link to the stack with the identical decode-or-fallback hardening. (setNewRoutePath now delegates to it, so platform and runtime links share one code path.)

A correctness + documentation pass. No API changes — every fix is behavior that matches what the docs already promised.

• Fix — NavListDetail no longer crashes when a lone detail is on top on a wide screen. Previously, if the only (or first) entry was itself a detail type, it was mounted in both panes under the same per-entry GlobalKey and threw a duplicate-key error. It now shows as the list pane with an empty detail pane. Regression-tested.
• Fix — NavEntryDecorator.onRemoved is now symmetric across the breakpoint in NavListDetail. onRemoved fires only for entries that were actually rendered (as a wide pane or a narrow page), so a wide-only middle entry that was never shown no longer gets a spurious onRemoved with no matching decorate.
• Fix — MultiNavStack.handleBack consumes back even when a popGuard vetoes the pop. With history in the active tab, back is now treated as handled (so the app stays open) instead of surfacing the vetoed pop's false to the host PopScope — which would have closed the app.
• Hardening — an empty stack is refused rather than crashing in release. A redirect/replaceAll that resolves to no destinations is caught by an assert in debug and, in release, declined (the current stack stays) instead of leaving the Navigator with an empty pages list.
• Examples: adds example/lib/tabs.dart (MultiNavStack bottom nav with per-tab history) and example/lib/results.dart (pushForResult — await a value from a pushed screen), filling the two biggest example gaps.
• Docs: README gains a table of contents and runnable snippets for results, per-tab nav, reusing an open screen (pushOrMoveToTop/moveToTop) and the live BackStackInspector; corrects the BackStack.of<AppKey> type argument, the exhaustiveness claim (now that the hero leads with NavEntries), and the example README's Pokédex description. pushForResult's Object?-cast caveat and the NavEntry.id / entries docs are clarified.

Convenience additions inspired by other routers — all built as plain list ops / pure functions / one widget, so the core model is unchanged (no codegen, no dependencies).

• NavStack.moveToTop(test) / pushOrMoveToTop(key) — reuse a screen that's already open instead of stacking a duplicate (singleTop/clearTop).
• combineRedirects([...]) — compose several redirect rules (auth, onboarding, flags) into one redirect, each a pure proposed → RedirectStep (ContinueRedirect / RedirectTo(stack, stop:)). Same once-per-change, loop-proof semantics as a single redirect.
• BackStackInspector<K> — a zero-dep in-app widget that lists the live stack (current entry marked), for debugging without any DevTools plumbing.

Not added, on purpose: a string query-parameter bag (typed key fields already carry a destination's arguments — a stringly-typed side channel would work against that) and a route-file code generator (back_stack stays codegen-free).

• BackStackApp<K> — deep links in one function. A single widget bundles the MaterialApp.router + NavStackRouterDelegate + parser wiring; you supply only onLink: (Uri) => [destinations]. Optional toLink projects the stack back onto the web address bar, onLinkFallback handles bad links, and restorationScopeId is set by default. Zero new dependencies — it drives Flutter's own Router.
• BackStack.parentOf<K>(context) (and maybeParentOf) — reach the stack one level up from a nested child when parent and child share the same key type, so a child screen can BackStack.parentOf<AppKey>(context).pop() the outer flow. (Distinct key subtypes + BackStack.of<ParentKey> remain the more type-safe default.)
• example/lib/multi_file/ now uses BackStackApp — the simplest example also demonstrates deep links (/product/7).

• Docs: the README hero snippet is corrected and no longer uses a switch — it leads with NavEntries (..on<Home>(...), builder: entries.call) over a non-sealed AppKey, so it compiles as shown and mirrors a multi-file app. (The previous snippet declared a sealed base with no const constructor and inferred NavStack<Home>, so it didn't compile.)
• Adds example/lib/multi_file/ — the simplest multi-file layout: app_key.dart
  • one file per feature (home_feature.dart, product_feature.dart) each with its own destination, screen and register* call, collected in main.dart. No switch, no central list.