@rangojs/router 0.24.4 → 0.25.0

package/src/browser/react/use-handle.ts

@@ -1,18 +1,12 @@
 "use client";
 
-import {
-  useContext,
-  useState,
-  useEffect,
-  useRef,
-  useOptimistic,
-  startTransition,
-} from "react";
+import { useContext, useState, useEffect, useRef } from "react";
 import type { Handle } from "../../handle.js";
 import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
+import type { RouteStateSignal } from "../event-controller.js";
 
 /**
  * Hook to access collected handle data.
@@ -43,77 +37,75 @@ export function useHandle<T, A, S>(
 ): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
-  const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
-    if (!ctx) {
-      const collected = collectHandleData(
-        handle,
-        {},
-        [],
-      ) as Rango.FlightSerialize<A>;
-      return selector ? selector(collected) : collected;
-    }
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
 
-    // Until every boundary has hydrated the store returns the state the
-    // document's HTML was rendered with (EventController.lockHydration), so a
-    // reader hydrating late reads what SSR rendered (issue #1035).
-    const state = ctx.eventController.getHandleState();
+  // Until every boundary has hydrated the store returns the state the
+  // document's HTML was rendered with (EventController.lockHydration), so a
+  // reader hydrating late reads what SSR rendered (issue #1035).
+  const collect = (): Rango.FlightSerialize<A> | S => {
+    const state = ctx?.eventController.getHandleState();
     const collected = collectHandleData(
       handle,
-      state.data,
-      state.segmentOrder,
+      state?.data ?? {},
+      state?.segmentOrder ?? [],
     ) as Rango.FlightSerialize<A>;
-    return selector ? selector(collected) : collected;
-  });
-  const [optimisticValue, setOptimisticValue] = useOptimistic(value);
-
-  const prevValueRef = useRef(value);
-  prevValueRef.current = value;
+    return selectorRef.current ? selectorRef.current(collected) : collected;
+  };
 
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
+  const [value, setValue] = useCommitAnchoredState(collect);
 
   useEffect(() => {
     if (!ctx) return;
-
-    // Sync current state for the (possibly new) handle so that switching
-    // handles on an idle page doesn't leave stale data from the old handle.
-    const currentHandleState = ctx.eventController.getHandleState();
-    const currentCollected = collectHandleData(
-      handle,
-      currentHandleState.data,
-      currentHandleState.segmentOrder,
-    ) as Rango.FlightSerialize<A>;
-    const currentValue = selectorRef.current
-      ? selectorRef.current(currentCollected)
-      : currentCollected;
-    if (!shallowEqual(currentValue, prevValueRef.current)) {
-      prevValueRef.current = currentValue;
-      setValue(currentValue);
-    }
-
-    return ctx.eventController.subscribeToHandles(() => {
-      const state = ctx.eventController.getHandleState();
-      const isAction =
-        ctx.eventController.getState().inflightActions.length > 0;
-      const collected = collectHandleData(
-        handle,
-        state.data,
-        state.segmentOrder,
-      ) as Rango.FlightSerialize<A>;
-      const nextValue = selectorRef.current
-        ? selectorRef.current(collected)
-        : collected;
-
-      if (!shallowEqual(nextValue, prevValueRef.current)) {
-        prevValueRef.current = nextValue;
-        startTransition(() => {
-          // Skip optimistic update during actions to prevent Suspense fallback
-          if (!isAction) setOptimisticValue(nextValue);
-          setValue(nextValue);
-        });
-      }
-    });
+    const update = (signal?: RouteStateSignal): void =>
+      setValue(collect(), signal);
+    // A (possibly new) handle on an idle page reads the current state.
+    update();
+    return ctx.eventController.subscribeToHandles(update);
   }, [handle]);
 
-  return optimisticValue;
+  return value;
+}
+
+/**
+ * Route state the controller's handle notifications drive (useHandle,
+ * useSegments) commits with the page it belongs to. NavigationProvider
+ * flushes the controller inside every payload update, so a value known then
+ * is set in the page's lane. A page handed over urgently (signal "release")
+ * takes a value that arrives before it commits the same way: set at default
+ * priority, it renders in the page's lane, and the page's effects read it.
+ * A page in a transition (signal "anchor") does not: until it commits
+ * (releaseRouteState() from the provider's layout effect, signal "release"),
+ * a new value waits, and is applied in the commit's task, right after the
+ * page's own commit. In the page's lane, a value that suspends in a revealed
+ * <Suspense> (a crumb's content) would hold the page; in a lane of its own,
+ * it commits over the page being left and takes the page's transition types
+ * (#1165); and a transition entangled with the page misses its commit when it
+ * is set after React rendered the page, before its view transition's
+ * mutation, and starts a view transition of its own. A value shallow-equal to
+ * the last one sets nothing, so a reader renders only when its value moves.
+ */
+export function useCommitAnchoredState<T>(
+  init: () => T,
+): [T, (value: T, signal?: RouteStateSignal) => void] {
+  // An app that enables the React Compiler compiles the router too; its memo
+  // cache gains nothing here and cost 107 B gzip in the router chunk.
+  "use no memo";
+  const [value, setValue] = useState(init);
+  const ref = useRef<{ last: T; held?: boolean; waiting?: boolean }>({
+    last: value,
+  });
+  const [set] = useState(() => (next: T, signal?: RouteStateSignal): void => {
+    const r = ref.current;
+    if (signal) r.waiting = signal === "anchor";
+    if (!shallowEqual(next, r.last)) {
+      r.last = next;
+      r.held = true;
+    }
+    // The anchor's own change goes in the page's lane, with the page.
+    if (!r.held || (r.waiting && signal !== "anchor")) return;
+    r.held = false;
+    setValue(() => r.last);
+  });
+  return [value, set];
 }

package/src/browser/react/use-href.tsx

@@ -2,7 +2,9 @@
 
 import { useCallback } from "react";
 import { href, type ValidPaths } from "../../href-client.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
 import { useMount } from "./use-mount.js";
+import { useParams } from "./use-params.js";
 
 /**
  * Client-side hook for mount-aware URL resolution.
@@ -11,6 +13,12 @@ import { useMount } from "./use-mount.js";
  * include() mount prefix. Inside an include("/shop", ...) scope,
  * the returned function resolves local paths relative to /shop.
  *
+ * Under a parameterized mount (`include("/:accountId", ...)`) the mount's
+ * params are filled from the current route params, as `useReverse` does:
+ * `href("/issues")` at `/acme/board` returns `/acme/issues`. A mount param
+ * missing from the current match throws `Missing param` when the returned
+ * function is called.
+ *
  * For absolute paths (outside the current mount), use the bare
  * href() function directly instead.
  *
@@ -37,11 +45,22 @@ import { useMount } from "./use-mount.js";
  */
 export function useHref(): (path: `/${string}`) => string {
   const mount = useMount();
-  // Memoize on `mount` (stable within a route) so the returned function is
-  // referentially stable across re-renders — a consumer can safely pass it as a
-  // dependency or a prop to a memoized child without forcing re-renders.
+  // The filled mount (it starts with "/"), or the Missing param message. The
+  // selector also runs in the params subscription, so it must not throw, and
+  // a string lets useParams skip the re-render, and keeps the returned
+  // function stable, unless the mount's own values change.
+  const base = useParams((p) => {
+    try {
+      return substitutePatternParams(mount, p, mount);
+    } catch (e) {
+      return (e as Error).message;
+    }
+  });
   return useCallback(
-    (path: `/${string}`) => href(path as ValidPaths, mount),
-    [mount],
+    (path: `/${string}`) => {
+      if (!base.startsWith("/")) throw new Error(base);
+      return href(path as ValidPaths, base);
+    },
+    [base],
   );
 }

package/src/browser/react/use-link-status.ts

@@ -100,7 +100,7 @@ export function useLinkStatus(): LinkStatus {
   // to a non-idle (loading) state. Used to decide whether to emit a release
   // update when returning to idle, so the optimistic store doesn't stay pinned
   // to `true` if a parent transition (e.g. the <Link> click / view transition
-  // commit) is still pending. Mirrors useNavigation's optimisticPinnedRef.
+  // commit) is still pending.
   const optimisticPinnedRef = useRef(false);
 
   const [pending, setOptimisticPending] = useOptimistic(basePending);

package/src/browser/react/use-navigation.ts

@@ -4,7 +4,7 @@ import {
   useContext,
   useState,
   useEffect,
-  useOptimistic,
+  useLayoutEffect,
   startTransition,
   useRef,
 } from "react";
@@ -46,22 +46,19 @@ export function useNavigation<T>(
     throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
+  const [value, setValue] = useState<T | PublicNavigationState>(() => {
     const publicState = toPublicState(
       ctx.eventController.getHydrationSnapshot()?.state ??
         ctx.eventController.getState(),
     );
     return selector ? selector(publicState) : publicState;
   });
-  const prevState = useRef(baseValue);
-
-  // Tracks whether the most recent setOptimisticValue call pinned the value
-  // to a non-idle state. Used to decide whether to emit a release update when
-  // returning to idle, so the optimistic store doesn't stay pinned if a
-  // parent transition (e.g. <Link> click) is still pending.
-  const optimisticPinnedRef = useRef(false);
-
-  const [value, setOptimisticValue] = useOptimistic(baseValue);
+  const prevState = useRef(value);
+  // The value on screen: a set value that differs has not committed yet.
+  const committedRef = useRef(value);
+  useLayoutEffect(() => {
+    committedRef.current = value;
+  });
 
   // Store selector in a ref so the subscription callback always uses the
   // latest selector without re-subscribing on every render (inline functions
@@ -71,10 +68,28 @@ export function useNavigation<T>(
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Subscribe to event controller state changes (only runs on client)
+  // Subscribe to event controller state changes (only runs on client).
+  //
+  // The value commits in the lane of the notification that carries it, as
+  // the location hooks' values do: NavigationProvider flushes a navigation's
+  // notification into the transition that commits its tree, so idle commits
+  // with the destination's location (useSearchParams, usePathname,
+  // useParams). An optimistic update renders in the sync lane, ahead of that
+  // transition, and put idle on screen with the location being left (#1164).
   useEffect(() => {
+    let last: DerivedNavigationState | undefined;
     const update = () => {
       const currentState = ctx.eventController.getState();
+      // Neither the state nor the location moved (the stream starting or
+      // ending): while a value of this hook's is held, a transition, which
+      // React entangles with it, so it never commits ahead of the location.
+      // Otherwise urgent: a transition of its own would start a view
+      // transition, and could commit ahead of a held page and take its
+      // transition types.
+      const quiet =
+        currentState.state === last?.state &&
+        currentState.location === last.location;
+      last = currentState;
       const publicState = toPublicState(currentState);
       const nextSelected = selectorRef.current
         ? selectorRef.current(publicState)
@@ -82,35 +97,10 @@ export function useNavigation<T>(
 
       // Check if selected value has changed
       if (!shallowEqual(nextSelected, prevState.current)) {
+        const held = prevState.current !== committedRef.current;
         prevState.current = nextSelected;
-
-        // Check if any actions are in progress for optimistic updates
-        const hasInflightActions =
-          ctx.eventController.getInflightActions().size > 0;
-
-        const shouldPin = hasInflightActions || publicState.state !== "idle";
-
-        if (shouldPin) {
-          // Pin the optimistic store so the loading value shows immediately
-          // even if a parent transition (e.g. <Link> click) defers the
-          // urgent setBaseValue commit.
-          startTransition(() => {
-            setOptimisticValue(nextSelected);
-          });
-          optimisticPinnedRef.current = true;
-        } else if (optimisticPinnedRef.current) {
-          // Release a previously-pinned optimistic value. Without this,
-          // useOptimistic keeps returning the stale loading value while
-          // any parent transition is still pending, even after baseValue
-          // flipped to idle.
-          startTransition(() => {
-            setOptimisticValue(nextSelected);
-          });
-          optimisticPinnedRef.current = false;
-        }
-
-        // Always update base state so UI reflects current state
-        setBaseValue(nextSelected);
+        if (quiet && held) startTransition(() => setValue(nextSelected));
+        else setValue(nextSelected);
       }
     };
 

package/src/browser/react/use-router.ts

@@ -6,6 +6,8 @@ import { useMount } from "./use-mount.js";
 import { prefetchDirect } from "../prefetch/loader.js";
 import { getAppVersion } from "../app-version.js";
 import { prefixBasename } from "../../router/basename.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import { href, type ValidPaths } from "../../href-client.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**
@@ -22,7 +24,12 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  *
  * RELATIVE paths (no leading `/`, no scheme/query/hash) resolve against the
  * current include() mount: `router.push("cart")` inside `include("/shop")`
- * navigates to `/shop/cart`. Absolute paths stay APP-absolute — unlike
+ * navigates to `/shop/cart`. Under a parameterized mount
+ * (`include("/:accountId", ...)`) the mount's params are filled from the
+ * current route params: `router.push("issues")` at `/acme/board` navigates
+ * to `/acme/issues`, and a missing mount param rejects the push/replace
+ * promise with `Missing param` (a prefetch skips the target).
+ * Absolute paths stay APP-absolute — unlike
  * basename, the mount is scoped, and absolute pushes legitimately target
  * outside it, so they are never auto-prefixed.
  *
@@ -70,16 +77,32 @@ export function useRouter(): RouterInstance {
       ) {
         return withBasename(url);
       }
-      const base = mount === "/" ? "" : mount.replace(/\/$/, "");
-      return withBasename(`${base}/${relative}`);
+      // The mount is the include()'s URL pattern: fill its params from the
+      // committed params at call time (not render time, so this object stays
+      // stable across navigations), as useHref does.
+      return withBasename(
+        href(
+          `/${relative}` as ValidPaths,
+          substitutePatternParams(
+            mount,
+            ctx!.eventController.getParams(),
+            mount,
+          ),
+        ),
+      );
     }
 
+    // push/replace are async so a target that cannot resolve (a missing
+    // mount param) rejects the returned promise instead of throwing.
     return {
-      push(url: string, options?: RouterNavigateOptions): Promise<void> {
+      async push(url: string, options?: RouterNavigateOptions): Promise<void> {
         return ctx.navigate(resolveTarget(url), { ...options, replace: false });
       },
 
-      replace(url: string, options?: RouterNavigateOptions): Promise<void> {
+      async replace(
+        url: string,
+        options?: RouterNavigateOptions,
+      ): Promise<void> {
         return ctx.navigate(resolveTarget(url), { ...options, replace: true });
       },
 
@@ -90,8 +113,16 @@ export function useRouter(): RouterInstance {
       prefetch(url: string, options?: { key?: ":source" }): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
+          let target: string;
+          try {
+            target = resolveTarget(url);
+          } catch {
+            // A prefetch is a hint: a target that cannot resolve (missing
+            // mount param) is skipped; push/replace report the error.
+            return;
+          }
           prefetchDirect(
-            resolveTarget(url),
+            target,
             segmentState.currentSegmentIds,
             getAppVersion(),
             ctx.store?.getRouterId?.(),

package/src/browser/react/use-segments.ts

@@ -1,8 +1,9 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
+import { useContext, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { shallowEqual } from "./shallow-equal.js";
+import { useCommitAnchoredState } from "./use-handle.js";
+import type { RouteStateSignal } from "../event-controller.js";
 
 /**
  * Segments state returned by useSegments hook
@@ -71,7 +72,8 @@ export function useSegments<T>(
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  const [state, setState] = useState<T | SegmentsState>(() => {
+  // Commits with the page it describes (useCommitAnchoredState).
+  const [state, setState] = useCommitAnchoredState<T | SegmentsState>(() => {
     if (!ctx) {
       const fallbackLocation = new URL("/", "http://localhost");
       const fallbackState = buildSegmentsState(fallbackLocation, []);
@@ -88,8 +90,6 @@ export function useSegments<T>(
     return selector ? selector(segmentsState) : segmentsState;
   });
 
-  const prevState = useRef(state);
-
   useEffect(() => {
     if (!ctx) {
       return;
@@ -103,7 +103,7 @@ export function useSegments<T>(
       state: SegmentsState;
     } | null = null;
 
-    const updateState = () => {
+    const updateState = (signal?: RouteStateSignal) => {
       const location = ctx.eventController.getLocation() as URL;
       const { routeSegmentIds } = ctx.eventController.getHandleState();
       if (
@@ -118,17 +118,13 @@ export function useSegments<T>(
         };
       }
       const sel = selectorRef.current;
-      const nextSelected = sel ? sel(cache.state) : cache.state;
-      if (!shallowEqual(nextSelected, prevState.current)) {
-        prevState.current = nextSelected;
-        setState(nextSelected);
-      }
+      setState(sel ? sel(cache.state) : cache.state, signal);
     };
 
     // Catch up with a change between the seeding render and this effect.
     updateState();
 
-    const unsubscribeNav = ctx.eventController.subscribe(updateState);
+    const unsubscribeNav = ctx.eventController.subscribe(() => updateState());
     const unsubscribeHandles =
       ctx.eventController.subscribeToHandles(updateState);
 

package/src/browser/response-adapter.ts

@@ -1,4 +1,5 @@
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import { PREFETCH_FAILED_ROW } from "../prefetch-markers.js";
 
 type HeaderResult = { url: string } | "blocked" | null;
 
@@ -105,9 +106,11 @@ export function handleReloadHeader(
  * end-of-stream, calling onComplete when done.
  *
  * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
- * on a read error or an abort (the signal cancelled the reader). Callers that
- * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
- * treat a non-clean end as incomplete — a broken stream is not complete data.
+ * on a read error, an abort (the signal cancelled the reader), or a body that
+ * ends with PREFETCH_FAILED_ROW (a prefetch whose render reported an error,
+ * rsc/prefetch-render-error.ts). Callers that gate a "fully complete" fast
+ * path (e.g. prefetch's `entry.complete`) must treat a non-clean end as
+ * incomplete — a broken stream is not complete data.
  *
  * If the response has no body, onComplete fires synchronously with `true`
  * (an empty body is a clean, complete stream).
@@ -156,13 +159,16 @@ export function teeWithCompletion(
     // loop breaks here normally, NOT in the .catch — re-check the signal to
     // catch that case).
     let cleanEof = false;
+    // The last five bytes read, across chunk boundaries.
+    let tail = "";
     try {
       while (true) {
-        const { done } = await reader.read();
+        const { done, value } = await reader.read();
         if (done) {
-          cleanEof = true;
+          cleanEof = tail !== PREFETCH_FAILED_ROW;
           break;
         }
+        tail = (tail + String.fromCharCode(...value.slice(-5))).slice(-5);
       }
     } finally {
       if (onAbort) signal!.removeEventListener("abort", onAbort);

package/src/browser/rsc-router.tsx

@@ -37,6 +37,7 @@ import {
   setPrefetchConcurrency,
   setPrefetchDecoder,
 } from "./prefetch/loader.js";
+import { publishRangoMarker } from "./rango-marker.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -185,6 +186,7 @@ export async function initBrowserApp(
   } = options;
 
   bootLog("initBrowserApp start");
+  publishRangoMarker();
   // Before any location read (the history key, the navigation store, the
   // event controller): the server rendered the marked request for the clean
   // URL, so the client starts from the same one and hydration agrees.
@@ -248,7 +250,7 @@ export async function initBrowserApp(
 
   // The document's entry: the transition({ when }) source of the first
   // navigation, and of a later back/forward that leaves it.
-  store.rememberDisplayedEntry(initialPayload.metadata?.routeName);
+  store.rememberDisplayedEntry(initialPayload.metadata);
 
   // Register the active store on the module-level handle and wire the
   // jar-divergence observer before any getRangoState() read can detect a

package/src/browser/scroll-restoration.ts

@@ -75,7 +75,8 @@ let customGetKey: GetScrollKeyFunction | null = null;
 /**
  * Scroll key of the entry on screen. At popstate history.state already belongs
  * to the destination, so this is the only way to save the page being left
- * under its own key (see handleTraversalStart).
+ * under its own key (see handleTraversalStart). A traversal moves it when its
+ * restore commits (handleNavigationEnd), not at its event.
  */
 let displayedKey: string | null = null;
 
@@ -283,10 +284,12 @@ export function cancelScrollRestorationPolling(): void {
  *
  * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
  * @param options.isStreaming - Function to check if streaming is in progress
+ * @param options.committed - React has committed the restored tree (a layout effect)
  */
 export function restoreScrollPosition(options?: {
   retryIfStreaming?: boolean;
   isStreaming?: () => boolean;
+  committed?: boolean;
 }): boolean {
   // Clear any pending polling
   cancelScrollRestorationPolling();
@@ -298,6 +301,11 @@ export function restoreScrollPosition(options?: {
     return false;
   }
 
+  // Once React committed the restored tree, scroll now, so a view
+  // transition's new snapshot is taken at the restored position, while the
+  // page still streams too.
+  if (options?.committed) window.scrollTo(0, savedY);
+
   // If streaming, poll until streaming ends then scroll to saved position
   if (options?.retryIfStreaming && options?.isStreaming?.()) {
     const startTime = Date.now();
@@ -319,9 +327,8 @@ export function restoreScrollPosition(options?: {
     return true;
   }
 
-  // Not streaming — scroll after React commits and browser paints.
-  // startTransition defers the DOM commit, so scrolling synchronously
-  // would be overwritten when React replaces the content.
+  // Not streaming: scroll (again) on the next frame, for layout that settles
+  // after the commit and for a caller that ran before it.
   deferToNextPaint(() => {
     window.scrollTo(0, savedY);
     debugLog("[Scroll] Restored position:", savedY, "for key:", key);
@@ -374,18 +381,18 @@ export function handleNavigationStart(): void {
 
 /**
  * Handle scroll for a back/forward traversal, at popstate before anything
- * renders: save the page being left under ITS key (history has already moved,
- * so saveCurrentScrollPosition would use the destination's key) and track the
- * destination as the displayed entry.
+ * renders: save the page on screen under ITS key (history has already moved,
+ * so saveCurrentScrollPosition would use the destination's key). A second
+ * traversal before the first one's restore commits (a rapid double Back, a
+ * deferred animated restore) saves the page still on screen, never an entry
+ * it did not show.
  */
 export function handleTraversalStart(): void {
   if (!initialized) return;
-  const leftKey = displayedKey;
-  trackDisplayedEntry();
   // A key shared with the destination (a getKey that collapses entries, e.g.
   // by pathname) keeps the destination's saved position.
-  if (leftKey !== null && leftKey !== displayedKey) {
-    saveScrollPosition(leftKey, window.scrollY);
+  if (displayedKey !== null && displayedKey !== getScrollKey()) {
+    saveScrollPosition(displayedKey, window.scrollY);
   }
 }
 
@@ -394,13 +401,15 @@ export function handleTraversalStart(): void {
  * @param options.restore - If true, restore saved position (for popstate)
  * @param options.scroll - If false, don't scroll at all
  * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
+ * @param options.committed - Called after React committed the new tree
  */
 export function handleNavigationEnd(options: {
   restore?: boolean;
   scroll?: boolean;
   isStreaming?: () => boolean;
+  committed?: boolean;
 }): void {
-  const { restore = false, scroll = true, isStreaming } = options;
+  const { restore = false, scroll = true, isStreaming, committed } = options;
 
   // Don't scroll if explicitly disabled or not in a browser
   if (scroll === false || typeof window === "undefined") {
@@ -412,11 +421,17 @@ export function handleNavigationEnd(options: {
   // matters during cross-app navigation where ScrollRestoration unmounts
   // and remounts, creating a brief window where initialized is false.
   if (restore) {
-    if (
-      initialized &&
-      restoreScrollPosition({ retryIfStreaming: true, isStreaming })
-    ) {
-      return;
+    if (initialized) {
+      trackDisplayedEntry();
+      if (
+        restoreScrollPosition({
+          retryIfStreaming: true,
+          isStreaming,
+          committed,
+        })
+      ) {
+        return;
+      }
     }
     // An "auto" entry (no <Html.ScrollRestoration>, or created before it mounted)
     // is restored by the browser. A scrollTo here races that restore, and
@@ -438,9 +453,8 @@ export function handleNavigationEnd(options: {
   // against unmeasured layout, so sync scroll is correct here even
   // before the new tree's scrollHeight settles.
   //
-  // (The restore branch above keeps deferToNextPaint because savedY
-  // depends on the new tree's max scroll; sync scrollTo against an
-  // unmeasured DOM would clamp savedY to whatever the old/zero max was.)
+  // (The restore branch above also scrolls again on the next frame: savedY
+  // depends on the new tree's max scroll, which can grow after the commit.)
   if (scrollToHash()) {
     return;
   }