Events, failures, and Entry lifecycle

Record requests and policy decisions

Implement NavigationEventSink and pass it to the Session or Runtime configuration. Events include requested, redirected, Guard-rejected, committed, and failed stages with one NavigationRequestId for correlation.

final class AnalyticsNavigationSink implements NavigationEventSink {
  @override
  void add(NavigationEvent event) {
    analytics.record(event.runtimeType.toString());
  }
}

Do not record typed denial as a crash. NavigationGuardRejected describes an expected application decision.

Centralize unexpected failures

Implement NavigationFailureSink once in application startup code, next to the place that creates NavigationSession or NavigationRuntime. Connect it to Ark Error Manager, Sentry, or your existing reporter. It receives the error, stack trace, request identity, and operation.

Own a resource for one Entry occurrence

Use NavigationLifecycleObserver when a controller, subscription, or cache belongs to one live Entry rather than a Route type. Key storage by NavigationEntryId, because the same Route may appear several times.

final resources = <NavigationEntryId, EntryResources>{};

Create resources when the Entry commits and dispose them on pop, replacement, removal, reset, reconciliation, or Graph migration.

Keep feature dependencies small

Pages and Presenters request transitions through NavigationPort. Only composition, diagnostics, restoration, and lifecycle adapters need Session or Controller objects.