zenrouter

Prerelease for early testers. APIs may still change before 3.0.0.

⚠️ Breaking Changes

• Coordinator capability mixins live in zenrouter_core 3.0.0-beta.1. Flutter Coordinator still composes the full set (LayoutCore + Navigatable + Mutatable + Recoverable + Flutter CoordinatorLayout). Apps that only extend Coordinator are unaffected.

• Coordinator.pushOrMoveToTop returns Future<void> (was incorrectly typed as void while being async). Call sites that ignored the return value keep working; prefer await when sequencing.

• PageCallback receives LocalKey instead of ValueKey<RouteTarget>. Custom page builders normally require no change unless they explicitly typed the callback parameter.

• pop() completes onResult and runs onDidPop immediately. Do not call completeOnResult again after pop / tryPop; the completer is already done. onDidPop is idempotent if Flutter's page callback also fires.

• Equatable.internalProps is removed. Equality and hashing use runtimeType + props only. Delete leftover overrides.

⚠️ Deprecated

• defineLayout / defineConverter on Coordinator / RouteModule. Bind layouts with bindLayout on the path (NavigationPath.createWith(...)..bindLayout(ShopLayout.new)). Register restorable converters in init() via defineRestorableConverter.

🚀 New Features

• pushReplacement on indexed/branched parents now activates the destination instead of no-oping after a possible pop of the current path.
• Stateful branch navigation via BranchedStackPath: fixed branch layout roots retain an independent child stack while branch selection and restoration reuse indexed-path semantics.
• Flutter route-manifest adapter: coordinators expose the core RouteManifest seam; generated coordinators bind matched IDs to concrete RouteTarget instances without putting Flutter types in the manifest.
• Typed handwritten manifests: coordinators may narrow the manifest ID to an enum or domain type and bind routes with Dart object patterns.
• Modular manifest composition: CoordinatorModular now exposes one root graph assembled from local and nested RouteModule manifests. Cross-module layout relationships and URI conflicts are validated after composition.
• Codegen-free Coordinator bindings: RouteModuleBinding connects a validated RouteBindingRegistry to routeManifest, URI parsing, Flutter Router resolution, and typed not-found handling. A coordinator implements RouteModule, so the same mixin covers standalone coordinators and child modules.
• Reverse routing as coordinator.location.home: generated and handwritten coordinators expose a location namespace (location.home, location.profile(...)) instead of reversed {route}Location() helpers.
• Compose-your-own coordinator (via zenrouter_core): mix only the capabilities you need. CoordinatorView.initialUri asserts in debug when the host lacks CoordinatorNavigatable.
• defineDeeplinkHandler: pluggable deep-link strategy handlers on CoordinatorRecoverable.
• recoverUri: parses a URI and recovers it on CoordinatorRecoverable (parseRouteFromUri → recover).
• Correct browser history intent: push → navigate, replace → neglect. Traversal reports none when the app URI already matches the engine, and neglect when a guard (or other failed apply) must restore the current entry. Unconditional none would push a new history entry on Flutter stable/master.
• Superseding Router resolution: newer route information cooperatively cancels unresolved older work. Commits remain serialized and atomic once started; cancelled Router futures complete normally.
• Atomic coordinator commits: nested layout/path mutations publish one final URI/history update with a monotonic NavigationCommit revision.
• Typed route resolution: Flutter Router consumes core match, redirect, not-found, and error outcomes; redirects replace the current history entry.
• Stable page-entry identity: equal semantic routes can coexist in a stack without duplicate Navigator page keys. Imperative NavigationStack diffs pages by identity; DeclarativeNavigationStack still diffs by ==.
• Reset cleanup: NavigationPath.reset discards route-owned resources. Inside a navigation transaction it notifies synchronously so multi-path replace publishes one commit; outside a transaction it still publishes in a microtask (safe during Flutter builds and in headless use).
• Atomic declarative diffs: inserting/replacing routes no longer exposes an intermediate empty stack or rebuilds retained pages.

📖 Documentation

• Architecture docs updated for the capability-mixin split.
• Migration guide covers 3.0 capability mixins, PageCallback, pop() results, and equality.

⚠️ Breaking Changes

• GuardRule contract renamed (via zenrouter_core 2.3.0). The 2.2.0 methods are removed:

  Removed	Replacement
  canPop(route)	canPopRule(route) / canPopRuleWith(coordinator, route)
  canPopListenable(route)	canPopListenableRule(route) / canPopListenableRuleWith(coordinator, route)
  guard(coordinator, route)	guardRule(route) / guardRuleWith(coordinator, route)

  Use route-only methods when no coordinator is needed; override *With for dialogs / app state. Each *With defaults to its non-With counterpart.

  // Before
  class UnsavedChangesRule extends GuardRule<AppRoute> {
    @override
    bool canPop(AppRoute route) => !route.hasUnsavedChanges;
  
    @override
    FutureOr<bool?> guard(Coordinator c, AppRoute route) async =>
        showDiscardDialog(c.navigator.context);
  }
  
  // After
  class UnsavedChangesRule extends GuardRule<AppRoute> {
    @override
    bool canPopRule(AppRoute route) => !route.hasUnsavedChanges;
  
    @override
    FutureOr<bool?> guardRuleWith(Coordinator c, AppRoute route) async =>
        showDiscardDialog(c.navigator.context);
  }
  

🚀 New Features

• RouteGuard.canPopWith / canPopListenableWith: Coordinator-aware PopScope hints; NavigationStack prefers these when a coordinator is present.
• RouteGuardRule.popGuard: Runs the guardRule chain without a coordinator.

📖 Documentation

• Recipe / example / mixins API updated for the dual guardRule / guardRuleWith API.

🚀 New Features

RouteGuardRule — composable pop guards

• New GuardRule / RouteGuardRule API (via zenrouter_core 2.1.0) for reusable leave-confirmation chains — first non-null bool wins (null = continue).
• RouteGuard.canPop / canPopListenable drive Flutter PopScope; programmatic pop still always consults popGuard / popGuardWith.
• Flutter bridges: toListenableMixin() / toFlutterListenable(); NavigationStack rebuilds PopScope via ListenableBuilder when a listenable is present.

⚠️ Breaking Changes

• CoordinatorCore.pop: Pops only the nearest eligible path (no longer multi-path in one call). Bumped zenrouter_core to 2.1.0.
• RouteRedirect.resolve: Throws StateError on redirect type mismatch.

📖 Documentation

• New Recipe: Composable Route Guard Rules
• Example: example/lib/main_guard_rules.dart
• API: Mixins — guard rules section

• Bump zenrouter_core version to 2.0.3

🚀 New Features

CoordinatorView — headless coordinator embed

• New CoordinatorView widget renders a coordinator via layoutBuilder without Flutter's Router—for super apps, parallel panels, plugin surfaces, and other host-owned shells.
• Optional initialUri seeds navigation once when coordinator.root.stack is empty (ignored after the embed has stack state or on remount with the same coordinator).
• Supports sync and async parseRouteFromUri for the initial bootstrap.

CoordinatorLayoutBuilder mixin

• Extracted layoutBuilder(BuildContext) into CoordinatorLayoutBuilder; CoordinatorLayout implements it so embed hosts can depend on layout rendering without RouterConfig.

⚠️ Breaking Changes

• layoutBuilder moved to CoordinatorLayout: Override layoutBuilder on your coordinator's CoordinatorLayout mixin (unchanged for typical extends Coordinator subclasses). It is no longer declared on the Coordinator class body.
• RouteLayoutBuilder signature: The first parameter is now CoordinatorCore instead of Coordinator. Update custom defineLayoutBuilder / kDefaultLayoutBuilderTable callbacks accordingly (cast to Coordinator when you need Flutter-specific APIs).
• RouteLayout.buildRoot: Now accepts CoordinatorLayout instead of Coordinator. Call sites that passed a bare CoordinatorCore must use a type that provides getLayoutBuilder / root.

📖 Documentation

• New Guide: CoordinatorView — embed patterns, initialUri semantics, pitfalls vs MaterialApp.router
• API: Coordinator API — CoordinatorView section and dual quick-start
• Roadmap: Embedded / multi-surface learning path in DOCUMENTATION_ROADMAP

• Fix: CoordinatorModular.getModule now correctly resolves the coordinator itself — runtimeType: this is registered in _allModules, enabling getModule<MyCoordinator>() to work at any level of the hierarchy. (Bumped zenrouter_core to 2.0.2)

• Fix: Fix CoordinatorModular edgecase cascading dispose and prevent duplicate definitions. (Bumped zenrouter_core to 2.0.1)

• Fix: Revert hasEmptyPath back to pathSegments.isEmpty in resolveInitialUri for correct path empty checks.
• Refactor: Remove redundant initialRouteInformation parameter from CoordinatorRouteInformationProvider since fallback defaults and resolution logic is robust now.

🎉 Major Release - Core Architecture & Layouts

🚀 New Features

• zenrouter_core Package: Extracted all platform-independent core routing types (RouteTarget, CoordinatorCore, StackPath, and route mixins) into a new dedicated package.
• Composable Redirects: You can use RouteRedirectRule as RouteRedirect to allow composable, testable redirect logic via multiple rules (e.g., StopRedirect, ContinueRedirect, RedirectTo).
• Route Identity updates: Introduced RouteUri abstract class (and RouteUnique) to centralize URI-based identity for coordinator-managed routes.

⚠️ Breaking Changes

• Layout Binding Refactoring: The global RouteLayout.defineLayout has been removed. You must now bind layouts to paths using the StackPath.bindLayout() cascade syntax (e.g., NavigationPath.createWith(...)..bindLayout(HomeLayout.new)), or use defineLayoutParent() / defineLayoutBuilder() inside the coordinator.
• Core Mixins Relocated: Core routing types have been consolidated under zenrouter_core. The main package still exports them, but any explicit deep imports to old paths must be updated.
• RouteLayout.definePath Deprecated: Deprecated RouteLayout.definePath in favor of coordinator.defineLayoutBuilder.

📖 Documentation

• Architecture Overview: Completely redesigned READMEs to highlight the layered architecture and paradigm decisions.
• API Reference: Rewrote coordinator, mixins, and navigation paths API references from source.

🐞 Fixes

• Fix: Regression error when using RouteRedirectRule inside IndexedStackPath (Thanks to @obenkucuk)

🚀 New Features

Coordinator as RouteModule — Nested Coordinators

• Coordinator now implements RouteModule<T>, enabling any coordinator to be nested inside a CoordinatorModular by overriding the coordinator getter.
• Unlocks route versioning (V1/V2 side by side), multi-team modular architectures, and deeply nested coordinator hierarchies.
• Auto-detected isRouteModule flag controls root path creation vs parent inheritance.
• See Guide & example/lib/main_coordinator_module.dart

⚠️ Breaking Changes

• Coordinator.parseRouteFromUri signature changed from FutureOr<T> to FutureOr<T?>. Child coordinators return null for unrecognized URIs; standalone coordinators are guarded by assertions.
• CoordinatorModular.parseRouteFromUri returns null instead of notFoundRoute when the coordinator is itself a nested module.

📖 Documentation

• New Guide: Coordinator as RouteModule
• New Recipe: Route Versioning

• BREAKING CHANGE: Remove coordinator from defineModules, use this getter instead.
• Feat: Enforce getModule method return exact type.

🎉 Major Release - Production Ready

🚀 New Features

CoordinatorModular - Modular Route Management

• Split route management across independent modules by domain/feature
• CoordinatorModular mixin + RouteModule base class
• Perfect for large apps with team collaboration
• See Guide & example/lib/main_modular.dart

class AppCoordinator extends Coordinator<AppRoute>
    with CoordinatorModular<AppRoute> {
  @override
  Set<RouteModule<AppRoute>> defineModules() => {
    AuthModule(this),
    ShopModule(this),
  };
}

RouteRedirectRule - Composable Redirect Logic

• Reusable, chainable redirect rules (auth → feature flags → logging)
• RedirectResult sealed class with Stop/Continue/RedirectTo variants
• Async support for API calls, database queries

class ProtectedRoute extends AppRoute
    with RouteRedirect, RouteRedirectRule {
  @override
  List<RedirectRule> get redirectRules => [
    AuthenticationRule(),
    PermissionRule(permission: 'admin'),
  ];
}

⚠️ Breaking Changes

Removed deprecated APIs:

• RouteLayout.buildPrimitivePath → Use RouteLayout.buildPath
• RouteLayout.layoutBuilderTable → Use RouteLayout.buildPath
• RouteLayout.navigationPath/indexedStackPath → Use NavigationPath.key/IndexedStackPath.key
• routerDelegateWithInitialRoute → Use RouteRedirect in IndexRoute

See Migration Guide for details.

📦 What's Included

• ✅ Stable API surface
• ✅ Full test coverage (48 new tests: 33 modular + 15 redirect rule)
• ✅ Comprehensive documentation with guides

---

• Fix: back gesture failed in android

• Fix: Blank screen when using Coordinator as routerConfig (due to unset routerInformationProvider).
• Feat: Added initialRoutePath property to Coordinator.
• Feat: Added NavigatorObserverListGetter typedef for passing external observers. (View Guide)

• Feat: Add pushReplacement method in StackMutatable.
• Feat: Coordinator now implements RouterConfig so you can use it with MaterialApp.router more easily.

  • MaterialApp.router(
      // New way
      routerConfig: coordinator,
      // Old way
      routerDelegate: coordinator.routerDelegate,
      routeInformationParser: coordinator.routeInformationParser,
    );
    

• Deprecate: routerDelegateWithInitialRoute is deprecated, you can simulate the same behavior by using RouteRedirect in IndexRoute.

0.4.17

• ZenRouter officially achieved 100% test coverage 🚀
• Docs: Added migration guides from other packages (go_router, auto_route, and Navigator 1.0/2.0)
• Docs: Added recipes for common use cases
• Docs: Added quick links section to make the docs easier to navigate

0.4.16

• Fix: Future already completed bug when pushing the same route with pushOrMoveToTop.

0.4.15

• Feat: Add onUpdate method to RouteTarget for handling in-place route updates when navigating to the same route with different state.
• Feat: Add bindLayout method to StackPath as a convenient alternative for layout registration. (See RouteLayout Guide)

0.4.14

• Breaking Change: Don't allow redirect to return null anymore since it doesn't do anything.
• Feat: Add mustCallSuper to paths getter (Thanks @mrgnhnt96)
• Feat: Add discard parameter to remove method for controlling discarding behavior.
• Fix: Memory leak when pushing RouteQueryParameters in IndexedStackPath.
• Fix: Memory leak when discard route in RouteRedirect.

0.4.13

• Fix: Ensure navigate method is compatible with RouteRedirect.

0.4.12

• Feat: Introduce new StackNavigatable mixin for StackPath to handle custom logic when receiving a navigate command. (Back/Forward button on the browser)
• Fix: navigate clear all history that occurred when pushing a custom layout.

0.4.11

• Feat: Expose stackPath in RouteTarget and expose protected method for developer create custom stackPath.
• Feat: Add onDiscard to handle discarding phase in RouteTarget.

0.4.10

• Chore: Fix analyzer warnings

0.4.9

• Chore: Standardize serialize and deserialize for supported RouteTarget type

0.4.8

• Feat: Introduce new state restoration with RouteRestoration mixin. Support state restoration by default if restorationScopeId is provided in MaterialApp.router and using Coordinator pattern.
• Fix: Resolve bug in recover method where RouteRedirect was ignored.

0.4.7

• Docs: Update README

0.4.6

• Docs: Update README and add screenshots

0.4.5

• Feat: Add RouteQueryParameters mixin for targeted query parameter updates using ValueNotifier.
• Fix: Ensure path is set for RouteTarget when initial IndexedStackPath.
• Fix: Ensure layout is resolve correct if they under deeper stack.
• Refactor: Refactor folder structure and test folder structure to be more organized.

0.4.4

• Feat: New ZenRoute Logo!
• Docs: Improve document and update outdate example

0.4.3

• Feat: Add CoordinatorNavigatorObserver mixin to provide a list of observers for the coordinator's navigator.
• Breaking Change: Complete redesign [RouteLayout] builder to be more flexible and powerful.
  • Deprecate static method RouteLayout.buildPrimitivePath and use buildPath function instead.
  • Add ability to define new [StackPath] using RouteLayout.definePath. You can create custom behavior path builder. (Eg: RecoverableHistoryStack like unrouter)

0.4.2

• Feat: Add transitionStrategy to Coordinator for default stack transition setup
• Fix: Ensure when [Navigator.pop] called sync new stack with [NavigationPath]

0.4.1

• Fix: Ensure [Coordinator.routeDelegate] initialize once
• Improvement: Add [IndexedStackPathBuilder] for improve performance for rendering [IndexedStackPath]

0.4.0

• Breaking Change: Deprecated default constructors for NavigationPath and IndexedStackPath. Use NavigationPath.create/createWith and IndexedStackPath.create/createWith instead.
• Breaking Change: Introduced internalProps to RouteTarget for better deep equality and hash code generation.
• Feat: Added popGuardWith to RouteGuard and redirectWith to RouteRedirect for coordinator-aware mixin logic.
• Feat: Added strict path-coordinator binding support via createWith factories.
• Docs: Added comprehensive Migration Guide.
• Feat: Added routerDelegateWithInitalRoute to Coordinator.
• Feat: Enhanced setInitialRoutePath to correctly handle initial routes vs deep links.

0.3.2

• Add navigate function: A smarter alternative to push that handles browser history restoration by popping to existing routes instead of duplicating them.

0.3.1

• Allow parseRouteFromUri to return Future for implementing deferred import/async route parsing

0.3.0

• Breaking change: Change return of Coordinator.push() from Future<dynamic> to Future<T?>
• Fix NavigationStack rerender page everytime path updated. Resolve #10.
• Feat: Add recover function

0.2.3

• Update activePathIndex to activeIndex in IndexedStackPath
• Update document for detailed, hand-written example of Coordinator pattern

0.2.2

• Expose pop result in Coordinator
• Fix memory leak: Complete route result futures when routes are removed via pushOrMoveToTop
• Fix memory leak: Complete intermediate route futures during RouteRedirect.resolve chain

0.2.1

• Standardize how to access primitive path layout builder
  • Define using definePrimitivePath
  • Build using buildPrimitivePath

0.2.0

• BREAKING: Rename activeHostPaths to activeLayoutPaths to reflect correct concept.

0.1.2

• Update homepage link

0.1.1

• Fix broken document link by update it to github link

0.1.1

• Fix broken document link

0.1.0

• Initial release of ZenRouter.
• Unified Navigator 1.0 and 2.0 support.
• Coordinator pattern for centralized navigation logic.
• Support for both Declarative and Imperative navigation paradigms.
• Route mixins: RouteGuard, RouteRedirect, RouteDeepLink.
• Optimized Myers diff algorithm for efficient stack updates.
• Type-safe routing with RouteUnique.