[go_router] Fix ShellRoute key collisions during imperative navigation

[Gorniv]

This supersedes #11143, which was closed as inactive. It incorporates the review feedback from that PR.

Problem

When push() navigates between sibling regular ShellRoute branches under the same parent, multiple shell pages and navigators can coexist in the widget tree.

This could produce duplicate page or widget keys because:

• _CustomNavigator was keyed using GlobalObjectKey(navigatorKey.hashCode), so distinct navigator keys with the same hash were treated as the same key.
• ShellRouteMatch.pageKey was derived only from route.hashCode.
• Re-entering a ShellRoute that was already present in the imperative stack reused its page and navigator identities.

The first implementation in #11143 created fresh page and navigator keys for every ShellRouteMatch. Review correctly pointed out that this made navigator identity unstable across route reparses and prevented the configured ShellRoute.navigatorKey from consistently identifying its navigator.

Fix

This version addresses that feedback by:

• preserving the configured navigator key during normal route matching and reparsing;
• making shell page keys identity-aware, so distinct routes remain distinct even when their hashCode values collide;
• keying only the nested _CustomNavigator wrapper by the navigator key object instead of its hashCode;
• assigning scoped page and navigator keys only when an imperative push would otherwise collide with another live regular ShellRoute match;
• deriving that scope from the persistent ImperativeRouteMatch.pageKey;
• leaving StatefulShellRoute, the root navigator wrapper, and normal configured-key navigation unchanged.

Tests

The regression test push to a sibling shell route under the same parent shell route forces both navigator-key and route-hash collisions.

It covers:

• pushing to a sibling shell route;
• re-entering the first shell route while its original instance is still in the stack;
• preserving navigator and page state across match-list reconstruction and refresh();
• detecting and scoping collisions in nested ShellRouteMatch trees;
• popping back through both shell routes;
• navigating with go() after the imperative stack is removed.

No screenshots are included because this is a routing/runtime fix.

• Fixes 'Multiple widgets used the same GlobalKey' on Hot Reload When Using ShellRoute with Global Key and Builder Parameter flutter#148712
• Fixes [go_router] Failed assertion: line 3817 pos 18: '!keyReservation.contains(key)': is not true. flutter#140586

Validation

• flutter test: 438 passed, 2 skipped
• flutter analyze: no issues
• flutter_plugin_tools validate --check-for-missing-changes --packages go_router: no issues

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

Footnotes

1. Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

[gemini-code-assist]

Code Review

This pull request resolves ShellRoute key collisions during imperative navigation by introducing custom page and navigator key classes (_ShellRoutePageKey and _ShellRouteNavigatorKey) and updating the match cloning logic to scope keys when collisions are detected. Feedback from the review suggests replacing GlobalObjectKey with ValueKey to prevent state loss during rebuilds, and implementing a recursive collision check to correctly handle nested ShellRouteMatches.

[gemini-code-assist]

Using GlobalObjectKey(navigatorKey) will cause the state of _CustomNavigator to be lost when the route match list is recreated (such as during state restoration or dynamic route updates).

This is because GlobalObjectKey overrides == to use identical(other.value, value). Even though _ShellRouteNavigatorKey overrides == and hashCode to support value equality, two different instances of _ShellRouteNavigatorKey will not be identical. As a result, GlobalObjectKey will treat them as different keys, destroying and recreating the _CustomNavigator state.

To fix this, we can use a ValueKey wrapping the navigatorKey. Since ValueKey uses value equality (==), it will correctly preserve the state across rebuilds even when the navigator key instance is recreated.

Suggested change

	key: GlobalObjectKey(navigatorKey),
	key: ValueKey<GlobalKey<NavigatorState>>(navigatorKey),

[Gorniv]

Thanks for flagging this. I added a regression check that serializes and decodes the full RouteMatchList, restores it, and verifies that both the scoped NavigatorState and the child state remain the same instances. This reconstructs the scoped shell keys from the persistent ImperativeRouteMatch.pageKey, and the test passes with GlobalObjectKey(navigatorKey).

I kept the global key intentionally: replacing it with ValueKey would change the wrapper from global to local key semantics, which is broader than necessary. The strengthened coverage is in 679ce61.

[gemini-code-assist]

The current collision check newMatches.whereType<ShellRouteMatch>().any(...) only inspects the top-level matches in newMatches. If there are nested ShellRouteMatches (e.g., a ShellRoute nested inside another ShellRoute), any key collisions within those nested matches will not be detected. This can lead to duplicate GlobalKey errors and runtime crashes.

We can resolve this by recursively checking for collisions throughout the entire match tree using a local recursive helper function.

    final bool needsScopedKeys;
    if (branch is ShellRouteMatch && branch.route is ShellRoute) {
      bool hasCollision(RouteMatchBase match) {
        if (match is ShellRouteMatch) {
          if (match.pageKey == branch.pageKey || match.navigatorKey == branch.navigatorKey) {
            return true;
          }
          return match.matches.any(hasCollision);
        }
        return false;
      }
      needsScopedKeys = newMatches.any(hasCollision);
    } else {
      needsScopedKeys = false;
    }

[Gorniv]

Thanks. Fixed in 679ce61.

Rather than comparing only the outer candidate key against the existing tree, the push logic now collects all existing ShellRouteMatch nodes and checks each regular shell node while cloning the new branch. This scopes only the nested shell whose page or navigator key actually collides, while preserving the configured keys of non-colliding outer shells.

I also added a focused regression test. It failed against the previous top-level-only check and passes with the recursive per-node check.