Destinations and Route Definitions

A NavigationDestination<R> is a typed request. R is the value that may return when its entry is popped.

final class ProductDestination extends NavigationDestination<bool> {
  const ProductDestination({required this.productId});
  final String productId;
}

A NavigationRouteDefinition<D, R> connects that request to three infrastructure concerns: stable route identity, page construction, and optional URI encoding.

NavigationRouteDefinition<ProductDestination, bool>(
  id: const NavigationRouteId('product'),
  pageBuilder: (context, destination, entry) => ProductPage(
    productId: destination.productId,
  ),
  uriCodec: CallbackNavigationUriCodec<ProductDestination>(
    pattern: '/products/:productId',
    encoder: (value) => Uri(path: '/products/${value.productId}'),
    decoder: (match) => ProductDestination(
      productId: match.path('productId'),
    ),
  ),
)

Application code constructs ProductDestination, never a parameter map. The codec is the only boundary where typed values become path, query, or fragment data. Stable NavigationRouteId, NavigationMountId, NavigationScopeId, and runtime NavigationEntryId are different identities; keeping them distinct prevents duplicate-key and ambiguous-stack behavior.