Simplify scroll restoration with shared ScrollRef on CacheNode

The scroll system previously relied on accumulating segment paths during
navigation, then matching those paths in layout-router to decide which
segments should scroll. This was necessary when CacheNodes were created
lazily during render, since we couldn't mark scroll targets on the nodes
themselves. But now that we construct the entire CacheNode tree
immediately upon navigation, we can use a much simpler approach.

Each navigation creates a single shared mutable ref (ScrollRef) and
assigns it to every new leaf CacheNode. When any segment's scroll
handler fires, it sets the ref to false, preventing other segments from
scrolling. This replaces all the segment path accumulation and matching
logic with a straightforward per-node flag.

The motivation for this refactor was a bug where calling refresh() from
a server action would scroll the page to the top. The old path-based
system had a semantic gap between null (no segments to scroll) and an
empty array (scroll everything) — when a server action triggered a
refresh with no new segments, the null value fell through to a code path
that scrolled unconditionally. The new model avoids this entirely:
refresh creates no new CacheNodes, so no ScrollRef is assigned, and
nothing scrolls.

There is extensive existing test coverage for scroll restoration
behavior. This adds one additional test for the server action refresh
bug.

Author: acdlite

packages/next/src/client/app-dir/link.tsx

@@ -8,6 +8,7 @@ import { useMergedRef } from '../use-merged-ref'
 import { isAbsoluteUrl } from '../../shared/lib/utils'
 import { addBasePath } from '../add-base-path'
 import { warnOnce } from '../../shared/lib/utils/warn-once'
+import { ScrollBehavior } from '../components/router-reducer/router-reducer-types'
 import type { PENDING_LINK_STATUS } from '../components/links'
 import {
   IDLE_LINK_STATUS,
@@ -307,7 +308,7 @@ function linkClicked(
       dispatchNavigateAction(
         href,
         replace ? 'replace' : 'push',
-        scroll ?? true,
+        scroll === false ? ScrollBehavior.NoScroll : ScrollBehavior.Default,
         linkInstanceRef.current,
         transitionTypes
       )

packages/next/src/client/components/app-router-instance.ts

@@ -9,6 +9,7 @@ import {
   type NavigateAction,
   ACTION_HMR_REFRESH,
   PrefetchKind,
+  ScrollBehavior,
   type AppHistoryState,
 } from './router-reducer/router-reducer-types'
 import { reducer } from './router-reducer/router-reducer'
@@ -277,7 +278,7 @@ function getProfilingHookForOnNavigationStart() {
 export function dispatchNavigateAction(
   href: string,
   navigateType: NavigateAction['navigateType'],
-  shouldScroll: boolean,
+  scrollBehavior: ScrollBehavior,
   linkInstanceRef: LinkInstance | null,
   transitionTypes: string[] | undefined
 ): void {
@@ -307,7 +308,7 @@ export function dispatchNavigateAction(
     url,
     isExternalUrl: isExternalURL(url),
     locationSearch: location.search,
-    shouldScroll,
+    scrollBehavior,
     navigateType,
   })
 }
@@ -356,7 +357,10 @@ function gesturePush(href: string, options?: NavigateOptions): void {
 
     // Fork the router state for the duration of the gesture transition.
     const currentUrl = new URL(state.canonicalUrl, location.href)
-    const shouldScroll = options?.scroll ?? true
+    const scrollBehavior =
+      options?.scroll === false
+        ? ScrollBehavior.NoScroll
+        : ScrollBehavior.Default
     // This is a special freshness policy that prevents dynamic requests from
     // being spawned. During the gesture, we should only show the cached
     // prefetched UI, not dynamic data.
@@ -373,7 +377,7 @@ function gesturePush(href: string, options?: NavigateOptions): void {
       state.tree,
       state.nextUrl,
       freshnessPolicy,
-      shouldScroll,
+      scrollBehavior,
       'push'
     )
     dispatchGestureState(forkedGestureState)
@@ -442,7 +446,9 @@ export const publicAppRouterInstance: AppRouterInstance = {
       dispatchNavigateAction(
         href,
         'replace',
-        options?.scroll ?? true,
+        options?.scroll === false
+          ? ScrollBehavior.NoScroll
+          : ScrollBehavior.Default,
         null,
         options?.transitionTypes
       )
@@ -458,7 +464,9 @@ export const publicAppRouterInstance: AppRouterInstance = {
       dispatchNavigateAction(
         href,
         'push',
-        options?.scroll ?? true,
+        options?.scroll === false
+          ? ScrollBehavior.NoScroll
+          : ScrollBehavior.Default,
         null,
         options?.transitionTypes
       )