Session lifecycle, restoration, and dynamic modules

Most applications need only NavigationSession. Use NavigationRuntime when several windows share one Graph or when modules are installed while the app is running.

One Session per view

Each Session owns its own stacks, Navigator keys, Back behavior, current URI, and pending route results. Two windows may share definitions but must not share mutable navigation state.

final runtime = NavigationRuntime(graph: createBaseGraph());
final main = runtime.createSession(id: const NavigationSessionId('main'));
final inspector = runtime.createSession(
  id: const NavigationSessionId('inspector'),
);

Disposing the Runtime disposes its Sessions. If you create a Session directly, dispose that Session yourself.

What restoration keeps

Restorable entries are recreated through their URI codecs and stack plans. Session-only entries are skipped because their values exist only in the current process.

The public URI represents the nearest restorable Entry in the active branch. A session-only dialog above Product does not replace Product's public URL.

Update the Graph transactionally

final results = await runtime.updateGraph(
  (builder) {
    builder.installModule(createReportsModule());
    builder.mount(reportsMount);
  },
  activeEntries: const RejectActiveNavigationEntries(),
);

The update is applied to every Session as one transaction. Choose what happens if a removed route is active:

• RejectActiveNavigationEntries — keep the old Graph and report failure;
• RemoveActiveNavigationEntries — remove affected Entries;
• MigrateActiveNavigationEntries — provide an application migration.

Do not use dynamic updates for ordinary page navigation. They are for downloaded features, workspace plugins, or configuration that changes the available route set.

Separate Flutter engines or isolates cannot share live Dart objects. Bridge them through your own messages and implement NavigationSessionBridge at that boundary.