fix(app-router): restore shallow history tree snapshots

packages/vinext/src/client/navigation-runtime.ts

@@ -77,6 +77,14 @@ export type NavigationRuntimeFunctions = {
   notifyLinkNavigationStart?: () => void;
   pingVisibleLinks?: () => void;
   preparePrefetchResponse?: (response: Response) => Promise<unknown>;
+  claimCurrentHistoryTreeSnapshot?: (
+    historyUpdateMode: NavigationRuntimeHistoryUpdateMode,
+    previousHistoryState: unknown,
+  ) => void;
+  commitAppOwnedHistoryStateWrite?: (
+    historyUpdateMode: NavigationRuntimeHistoryUpdateMode,
+    previousHistoryState: unknown,
+  ) => void;
 };
 
 export type NavigationRuntimeBootstrap = {
@@ -132,7 +140,9 @@ function isNavigationRuntimeFunctions(value: unknown): value is NavigationRuntim
     isOptionalRuntimeFunction(Reflect.get(value, "getPrefetchRouterState")) &&
     isOptionalRuntimeFunction(Reflect.get(value, "notifyLinkNavigationStart")) &&
     isOptionalRuntimeFunction(Reflect.get(value, "pingVisibleLinks")) &&
-    isOptionalRuntimeFunction(Reflect.get(value, "preparePrefetchResponse"))
+    isOptionalRuntimeFunction(Reflect.get(value, "preparePrefetchResponse")) &&
+    isOptionalRuntimeFunction(Reflect.get(value, "claimCurrentHistoryTreeSnapshot")) &&
+    isOptionalRuntimeFunction(Reflect.get(value, "commitAppOwnedHistoryStateWrite"))
   );
 }
 

packages/vinext/src/server/app-browser-entry.ts

@@ -119,6 +119,7 @@ import {
   createInitialBfcacheIdMap,
   isCacheRestorableAppPayloadMetadata,
   isCompleteAppPayloadMetadata,
+  isExternalHistoryState,
   readHistoryStatePreviousNextUrl,
   resolveInterceptionContextFromPreviousNextUrl,
   type AppNavigationPayloadOrigin,
@@ -140,6 +141,7 @@ import {
 import {
   createPopstateRestoreHandler,
   restoreSynchronousPopstateScrollPosition,
+  shouldCommitPopstateUrlWithoutNavigation,
 } from "./app-browser-popstate.js";
 import {
   DevRecoveryBoundary,
@@ -374,14 +376,17 @@ function restoreHistoryStateSnapshot(
   historyState: unknown,
   navId: number,
   onApprovedBeforeCommit?: () => void,
+  restoreCopiedExternalHistoryEntry = false,
 ): boolean {
   let restored = false;
   flushSync(() => {
     restored = historyController.restoreHistorySnapshot({
       historyState,
+      preferExternalSnapshot: restoreCopiedExternalHistoryEntry,
       stageClientParams,
       approveVisibleRestore: ({ state, beforeCommit }) =>
         browserNavigationController.restoreHistorySnapshotVisibleState({
+          restoreCopiedExternalHistoryEntry,
           beforeCommit: () => {
             onApprovedBeforeCommit?.();
             beforeCommit();
@@ -2458,6 +2463,10 @@ function bootstrapHydration(
     navigate: navigateRsc,
     preparePrefetchResponse: (response) =>
       decodeAppElementsPromise(createFromFetch<AppWireElements>(Promise.resolve(response))),
+    claimCurrentHistoryTreeSnapshot: (historyUpdateMode, previousHistoryState) =>
+      historyController.claimCurrentHistoryTreeSnapshot(historyUpdateMode, previousHistoryState),
+    commitAppOwnedHistoryStateWrite: (historyUpdateMode, previousHistoryState) =>
+      historyController.commitAppOwnedHistoryStateWrite(historyUpdateMode, previousHistoryState),
   });
 
   // Note: This popstate handler runs for App Router (RSC navigation available).
@@ -2492,18 +2501,31 @@ function bootstrapHydration(
     // Notify the transition start so observers still see the URL change, then
     // restore scroll directly and skip the RSC dispatch.
     const href = window.location.href;
-    if (isSameAppRoutePopstateTarget(href)) {
+    const isExternalHistoryEntry = isExternalHistoryState(event.state);
+    if (
+      shouldCommitPopstateUrlWithoutNavigation({
+        historyState: event.state,
+        isCurrentExternalHistoryTree: historyController.isCurrentExternalHistoryTree(event.state),
+        isSameAppRouteTarget: isSameAppRoutePopstateTarget(href),
+      })
+    ) {
       notifyAppRouterTransitionStart(href, "traverse");
       historyController.commitTraversalIndexFromHistoryState(event.state);
+      commitClientNavigationState();
       restorePopstateScrollPosition(event.state);
       return;
     }
     const snapshotNavigationId = browserNavigationController.beginNavigation();
     if (
-      restoreHistoryStateSnapshot(event.state, snapshotNavigationId, () => {
-        abortSupersededNavigation();
-        notifyAppRouterTransitionStart(href, "traverse");
-      })
+      restoreHistoryStateSnapshot(
+        event.state,
+        snapshotNavigationId,
+        () => {
+          abortSupersededNavigation();
+          notifyAppRouterTransitionStart(href, "traverse");
+        },
+        isExternalHistoryEntry,
+      )
     ) {
       window.__VINEXT_RSC_PENDING__ = null;
       restoreSynchronousPopstateScrollPosition(