@rangojs/router 0.16.0 → 0.18.0

package/skills/view-transitions/SKILL.md

@@ -8,7 +8,7 @@ argument-hint: [layout|route|parallel|intercept]
 
 `transition()` opts a route (or group of routes) into transition-driven navigation. It does two things, and you choose how far to go:
 
-1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions. While the hold lasts, `useLoader` readers of the loaders being re-run report `isLoading: true` — render your stale indicator from it (see the hooks skill, `data.md`).
+1. **`startTransition` (the foundation).** The navigation commit is driven through React's `startTransition`. That holds the previous content across a same-route navigation (stale-while-revalidate — no loading-skeleton flash) and is the **precondition** for any view-transition animation. Works on **all** React versions. While the hold lasts, `useLoader` readers of the loaders being re-run report `isLoading: true` — keyed by loader family (`$$id`), not by segment; see the hooks skill, `data.md`.
 2. **`<ViewTransition>` (the animation, layered on top).** On React 19.3+ (or an experimental build), rango also wraps the segment content in React's `<ViewTransition>` so the swap cross-fades/morphs. This is the only part that needs 19.3+; pass `viewTransition: false` to keep #1 without it (and place your own `<ViewTransition>` where you want it).
 
 > The `<ViewTransition>` layer requires a React that exports `<ViewTransition>` / `addTransitionType`: stable 19.3+ or an experimental build. Rango feature-detects it; on React 19.2 that layer is a no-op — but the `startTransition` driving (content hold) still applies.
@@ -52,7 +52,7 @@ A simple cross-fade between pages that share a layout:
 import { urls } from "@rangojs/router";
 import { Outlet } from "@rangojs/router/client";
 
-function ShopShell({ children }: { children: React.ReactNode }) {
+function ShopShell() {
   return (
     <div className="shop">
       <NavBar />
@@ -74,23 +74,34 @@ export const urlpatterns = urls(({ layout, path, transition }) => [
 ]);
 ```
 
+The config values are React `<ViewTransition>` classes: React applies them as
+`view-transition-class`, so the CSS targets the view-transition
+pseudo-elements by class:
+
 ```css
-::view-transition-old(root) {
-  animation: fade-out 200ms ease both;
+::view-transition-old(.page-fade) {
+  animation: 200ms ease both fade-out;
+}
+::view-transition-new(.page-fade) {
+  animation: 200ms ease both fade-in;
 }
-::view-transition-new(root) {
-  animation: fade-in 200ms ease both;
+@keyframes fade-out {
+  to {
+    opacity: 0;
+  }
 }
-.page-fade {
-  /* class hooks per phase */
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
 }
 ```
 
-Navigating between `/`, `/about`, and `/contact` morphs the `<Outlet />` content with the `page-fade` class. The shell (NavBar, Footer) does not morph because the wrap sits inside the shell, not around it.
+Navigating between `/`, `/about`, and `/contact` cross-fades the `<Outlet />` content with the `page-fade` class. The shell (NavBar, Footer) does not animate because the wrap sits inside the shell, not around it.
 
 ## Direction-aware transitions
 
-`ViewTransitionClass` accepts an object form keyed by transition type. Rango tags forward navigations as `"navigation"` and back/forward popstate as `"navigation-back"`:
+`ViewTransitionClass` accepts an object form keyed by transition type. Rango tags forward navigations as `"navigation"` and back/forward navigations restored from the client cache as `"navigation-back"` (a back/forward that has to refetch from the server is tagged `"navigation"`):
 
 ```tsx
 layout(<ShopShell />, () => [
@@ -106,12 +117,19 @@ layout(<ShopShell />, () => [
 ```
 
 ```css
-.slide-left {
-  animation-name: slide-from-right;
+::view-transition-old(.slide-left) {
+  animation: 250ms ease both slide-out-to-left;
+}
+::view-transition-new(.slide-left) {
+  animation: 250ms ease both slide-in-from-right;
 }
-.slide-right {
-  animation-name: slide-from-left;
+::view-transition-old(.slide-right) {
+  animation: 250ms ease both slide-out-to-right;
 }
+::view-transition-new(.slide-right) {
+  animation: 250ms ease both slide-in-from-left;
+}
+/* @keyframes slide-out-to-left, slide-in-from-right, ... defined as usual */
 ```
 
 > Note: `"action"` is only tagged on partial-update action/refetch paths today; ordinary `server-action-bridge` commits (`useAction` / `useActionState` revalidations) are not currently tagged. Don't rely on an `action`-keyed class to fire on every form action.
@@ -147,8 +165,8 @@ function GalleryShell() {
       <main>
         <Outlet /> {/* page transition lands here */}
       </main>
-      <ParallelOutlet name="@modal" />{" "}
-      {/* modal mounts here — sibling of the VT */}
+      {/* modal mounts here, as a sibling of the VT */}
+      <ParallelOutlet name="@modal" />
     </>
   );
 }
@@ -222,12 +240,12 @@ interface TransitionConfig {
 
 ## Conditional transitions (`when`)
 
-`transition({ when })` gates the hold per request. The predicate runs server-side and outside any cache scope; return `false` to drop this segment's transition for the request (the navigation streams its `loading()` fallback instead of holding).
+`transition({ when })` gates the hold per request. The predicate runs server-side and outside any cache scope; return `false` to drop this segment's transition for the request. The hold is navigation-wide: the navigation streams its `loading()` fallback instead of holding only when no other matched segment still has a transition (the common case is a single `transition()` on the route).
 
 Timing follows the route's rendering contract:
 
 - On an ordinary route it runs after the route handler during fresh resolution, so `get()` can read handler- and middleware-set context. Cache/prerender hits replay the stored decision.
-- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers. This is what keeps the handler-free PPR fast path available without a second API.
+- On a `ppr` route it is automatically hoisted before route handlers and runs on every match, including runtime-cache, prerender, document-shell, and partial-navigation replay. It can read URL/params/action metadata, `env`, and middleware-set context, but not values set by route handlers, because a shell HIT never runs a handler.
 
 Its context mirrors the `revalidate()` predicate args — the same navigation/action metadata — plus `get`/`env` for request-context reads:
 
@@ -280,7 +298,10 @@ urls(({ path, transition }) => [
   ]),
 ]);
 
-// ProductPage renders the boundary itself, exactly where it's wanted:
+// ProductPage renders the boundary itself, exactly where it's wanted
+// (ViewTransition is exported by React 19.3+ and experimental builds):
+import { ViewTransition } from "react";
+
 function ProductPage() {
   return (
     <ViewTransition name="hero">
@@ -311,7 +332,7 @@ const router = createRouter<AppEnv>({ viewTransition: false });
 | `transition({ viewTransition: false })`  | `"auto"`                | no wrap (per-route wins) | **ST only** |
 | `transition({ viewTransition: false })`  | `false`                 | no wrap                  | ST only     |
 
-On stable React the "VT" column is always a no-op (there is no `<ViewTransition>`), so every row collapses to its `startTransition`-only behavior there.
+On React 19.2 (no `<ViewTransition>` export) the "VT" column is a no-op, so every row collapses to its `startTransition`-only behavior there.
 
 | Config                                               | Router boundary  | startTransition driving (no skeleton flash) | Your own `<ViewTransition name>`   |
 | ---------------------------------------------------- | ---------------- | ------------------------------------------- | ---------------------------------- |
@@ -320,7 +341,7 @@ On stable React the "VT" column is always a no-op (there is no `<ViewTransition>
 | `transition({ viewTransition: false })`              | none             | yes                                         | fires alone                        |
 | global `viewTransition: false`, route `transition()` | none             | yes                                         | fires alone                        |
 
-> On **stable** React there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
+> On React 19.2 there is no `<ViewTransition>` at all, so `viewTransition: false` is visually a no-op there — but the startTransition driving and content-hold still apply, identical to `transition({})`.
 
 ## Testing a transition() route
 

package/src/__augment-tests__/augmented.check.ts

@@ -6,7 +6,13 @@
  * turns these into tsc errors. Run via tsconfig.augment-check.json.
  */
 import "./augment.js";
-import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
+import type {
+  Handler,
+  MiddlewareContext,
+  ResponseHandlerContext,
+  RouteParams,
+  RouteSearchParams,
+} from "../index.js";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import { href } from "../href-client.js";
 import type { Money, TestBindings } from "./augment.js";
@@ -39,6 +45,25 @@ const varsHandler: Handler<"home"> = (ctx) => {
 };
 void varsHandler;
 
+// Response-route and middleware ctx.reverse resolve global names only (no
+// include() scope): generated names and params are validated, `.name` is not.
+function responseReverse(ctx: ResponseHandlerContext): void {
+  ctx.reverse("home");
+  ctx.reverse("blog.post", { slug: "hello" });
+  // @ts-expect-error - dot-local name; no include() scope to resolve it
+  ctx.reverse(".home");
+  // @ts-expect-error - unknown global name is rejected
+  ctx.reverse("nope");
+}
+void responseReverse;
+
+function middlewareReverse(ctx: MiddlewareContext): void {
+  ctx.reverse("blog.post", { slug: "hello" });
+  // @ts-expect-error - dot-local name; no include() scope to resolve it
+  ctx.reverse(".home");
+}
+void middlewareReverse;
+
 // routeName narrows to the generated route names.
 type _routeName = Expect<
   Equal<DefaultRouteName, "home" | "blog.post" | "search">

package/src/browser/cookie-name.ts

@@ -14,6 +14,29 @@
 /** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
 export const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
 
+/**
+ * The fresh-reads cookie: the state cookie PREFIX plus this suffix
+ * (`rango-state-fresh` by default). A response whose request ran
+ * updateTag()/revalidateTag() sets it (HttpOnly, SameSite=Lax, Path=/,
+ * Max-Age = the stores' longest memo staleness), and the same user's requests
+ * carrying it skip the stores' isolate memos (src/cache/isolate-tag-memo.ts).
+ * Keyed by prefix, not by router, so a mutation through one router also
+ * reaches the memos another router on the host reads (they often share a
+ * store); a router with its own `stateCookiePrefix` gets its own cookie.
+ */
+const FRESH_READS_COOKIE_SUFFIX = "-fresh";
+
+/**
+ * The fresh-reads cookie name for a router's resolved state cookie name
+ * (`{prefix}_{routerId}`; the prefix never contains `_`, see
+ * router/state-cookie-name.ts).
+ */
+export function freshReadsCookieName(stateCookieName: string): string {
+  const cut = stateCookieName.indexOf("_");
+  const prefix = cut < 0 ? stateCookieName : stateCookieName.slice(0, cut);
+  return `${prefix}${FRESH_READS_COOKIE_SUFFIX}`;
+}
+
 /** Internal response header carrying the keepClientCache() directive. */
 export const KEEP_CACHE_HEADER = "x-rango-keep-cache";
 

package/src/browser/history-state.ts

@@ -82,6 +82,29 @@ export function pushHistoryWithIdx(
   }
 }
 
+/**
+ * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
+ * which the browser bundle must not import): a degraded PPR shell HIT
+ * reloads the page with it, and the server renders a marked request like a
+ * cache miss.
+ */
+export const SHELL_MISS_MARKER: string = "_rsc_shell";
+
+/**
+ * Drop the forced-MISS marker from the address bar at boot, keeping the
+ * history entry's state (initBrowserApp calls it before any location read).
+ * Left in place, a refresh or a shared link would stay off the shell and the
+ * app's search params would carry it. The server strips the same marker from
+ * the request before rendering (shell-serve.ts withoutShellMissMarker), so
+ * the page was rendered for the clean URL and the hydrating client agrees.
+ */
+export function stripShellMissMarker(): void {
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has(SHELL_MISS_MARKER)) return;
+  url.searchParams.delete(SHELL_MISS_MARKER);
+  window.history.replaceState(window.history.state, "", url.href);
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/index.ts

@@ -3,10 +3,10 @@
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, Rango } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "@rangojs/router/browser";
 //
 // For React components (Link, useNavigation, etc.):
-//   import { Link, useNavigation, useAction, href } from "rsc-router/client";
+//   import { Link, useNavigation, useAction, href } from "@rangojs/router/client";
 //
 // ============================================================================
 

package/src/browser/navigation-bridge.ts

@@ -18,6 +18,7 @@ import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
+  handleTraversalStart,
   ensureHistoryKey,
 } from "./scroll-restoration.js";
 
@@ -496,6 +497,7 @@ export function createNavigationBridge(
     async handlePopstate(): Promise<void> {
       // Abort any pending navigation to prevent race conditions
       eventController.abortNavigation();
+      handleTraversalStart();
 
       const url = window.location.href;
 
@@ -698,7 +700,7 @@ export function createNavigationBridge(
           tx.handle.signal,
           tx.with({
             url,
-            replace: true,
+            traversal: true,
             scroll: false,
             intercept: isIntercept,
             interceptSourceUrl,
@@ -771,9 +773,6 @@ export function createNavigationBridge(
             "[Browser] Page restored from bfcache, resetting navigation state",
           );
           eventController.abortNavigation();
-          // pagehide flips scrollRestoration to "auto" for bfcache compat;
-          // restore "manual" so the router controls scroll on SPA navigations.
-          window.history.scrollRestoration = "manual";
         }
       };
 

package/src/browser/navigation-transaction.ts

@@ -11,7 +11,11 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  buildHistoryState,
+  mergeLocationState,
+  pushHistoryWithIdx,
+} from "./history-state.js";
 
 export { resolveNavigationState } from "./history-state.js";
 
@@ -49,6 +53,12 @@ interface CommitOptions {
   cacheOnly?: boolean;
   /** Server-set location state to merge into history.pushState */
   serverState?: Record<string, unknown>;
+  /**
+   * Back/forward: history is already at this entry. Its state (scroll key,
+   * location state, idx) stays as the browser restored it; serverState is
+   * merged in. The page left was saved by handleTraversalStart.
+   */
+  traversal?: boolean;
 }
 
 /**
@@ -131,6 +141,7 @@ export function createNavigationTransaction(
       interceptSourceUrl,
       cacheOnly,
       serverState,
+      traversal,
     } = opts;
 
     const parsedUrl = new URL(url, window.location.origin);
@@ -145,7 +156,7 @@ export function createNavigationTransaction(
       return { scroll: false };
     }
 
-    handleNavigationStart();
+    if (!traversal) handleNavigationStart();
 
     store.setSegmentIds(segmentIds);
     store.setCurrentUrl(url);
@@ -162,6 +173,15 @@ export function createNavigationTransaction(
       return { scroll: false };
     }
 
+    if (traversal) {
+      if (serverState && Object.keys(serverState).length > 0) {
+        mergeLocationState(serverState);
+      }
+      handle.complete(parsedUrl);
+      debugLog("[Browser] Traversal committed, historyKey:", historyKey);
+      return { scroll };
+    }
+
     const historyState = buildHistoryState(
       opts.state,
       { intercept, sourceUrl: interceptSourceUrl },

package/src/browser/partial-update.ts

@@ -43,7 +43,9 @@ function toScrollPayload(
   return { enabled: scroll !== false ? scroll : false };
 }
 
-function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
+export function shouldStartViewTransition(
+  segments: ResolvedSegment[],
+): boolean {
   let hasIntercept = false;
   let hasTransition = false;
   for (const s of segments) {
@@ -53,6 +55,29 @@ function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
   return !hasIntercept && hasTransition;
 }
 
+/**
+ * Transition commit. Every held commit announces the loader streams the
+ * committed tree is still receiving (loader-store.ts announcePendingStreams)
+ * so held useLoader readers pin isLoading:true until this transition lands;
+ * settled/cached segments make it a no-op. Urgent commits call onUpdate
+ * directly: nothing is held there, a reader of a pending stream suspends to
+ * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
+ */
+export function commitInTransition(
+  onUpdate: UpdateSubscriber,
+  segments: readonly ResolvedSegment[],
+  update: NavigationUpdate,
+  transitionTypes: readonly string[],
+): void {
+  startTransition(() => {
+    loaderStore.announcePendingStreams(segments);
+    if (addTransitionType) {
+      for (const type of transitionTypes) addTransitionType(type);
+    }
+    onUpdate(update);
+  });
+}
+
 /**
  * Configuration for creating a partial updater
  */
@@ -141,28 +166,6 @@ export function createPartialUpdater(
     return cached?.segments || [];
   }
 
-  /**
-   * Transition commit. Every held commit announces the loader streams the
-   * committed tree is still receiving (loader-store.ts announcePendingStreams)
-   * so held useLoader readers pin isLoading:true until this transition lands;
-   * settled/cached segments make it a no-op. Urgent commits call onUpdate
-   * directly: nothing is held there, a reader of a pending stream suspends to
-   * its fallback.
-   */
-  function commitInTransition(
-    segments: readonly ResolvedSegment[],
-    update: NavigationUpdate,
-    transitionTypes: readonly string[],
-  ): void {
-    startTransition(() => {
-      loaderStore.announcePendingStreams(segments);
-      if (addTransitionType) {
-        for (const type of transitionTypes) addTransitionType(type);
-      }
-      onUpdate(update);
-    });
-  }
-
   async function fetchPartialUpdate(
     targetUrl: string,
     segmentIds: string[] | undefined,
@@ -374,7 +377,9 @@ export function createPartialUpdater(
           };
 
           if (shouldStartViewTransition(existingSegments)) {
-            commitInTransition(existingSegments, cachedUpdate, ["navigation"]);
+            commitInTransition(onUpdate, existingSegments, cachedUpdate, [
+              "navigation",
+            ]);
           } else {
             onUpdate(cachedUpdate);
           }
@@ -614,12 +619,14 @@ export function createPartialUpdater(
       };
       if (mode.type === "action" || mode.type === "stale-revalidation") {
         commitInTransition(
+          onUpdate,
           reconciled.mainSegments,
           update,
           hasTransition ? ["action"] : [],
         );
       } else if (hasTransition) {
         commitInTransition(
+          onUpdate,
           reconciled.mainSegments,
           update,
           optimisticPresented
@@ -650,6 +657,7 @@ export function createPartialUpdater(
         // segment reconciles in place (clientGroup key), so a read that still
         // suspends must hold the presented content, not flash a fallback.
         commitInTransition(
+          onUpdate,
           reconciled.mainSegments,
           update,
           optimisticPresented ? [OPTIMISTIC_COMMIT_TRANSITION_TYPE] : [],
@@ -713,18 +721,20 @@ export function createPartialUpdater(
           return;
         }
         commitInTransition(
+          onUpdate,
           segments,
           fullUpdate,
           fullHasTransition ? ["action"] : [],
         );
       } else if (mode.type === "action") {
         commitInTransition(
+          onUpdate,
           segments,
           fullUpdate,
           fullHasTransition ? ["action"] : [],
         );
       } else if (fullHasTransition) {
-        commitInTransition(segments, fullUpdate, ["navigation"]);
+        commitInTransition(onUpdate, segments, fullUpdate, ["navigation"]);
       } else {
         onUpdate(fullUpdate);
       }

package/src/browser/react/ScrollRestoration.tsx

@@ -4,7 +4,7 @@ import { useEffect } from "react";
 import { initScrollRestoration } from "../scroll-restoration.js";
 
 /**
- * Props for ScrollRestoration component
+ * Props for `<Html.ScrollRestoration />`.
  */
 export interface ScrollRestorationProps {
   /**
@@ -25,10 +25,10 @@ export interface ScrollRestorationProps {
    * const byPathname = (location) => location.pathname;
    *
    * // Restore based on pathname (same URL = same scroll)
-   * <ScrollRestoration getKey={byPathname} />
+   * <Html.ScrollRestoration getKey={byPathname} />
    *
    * // Restore based on unique history entry (default)
-   * // <ScrollRestoration /> — omit getKey to use location.key
+   * // <Html.ScrollRestoration /> — omit getKey to use location.key
    * ```
    */
   getKey?: (location: {
@@ -40,7 +40,7 @@ export interface ScrollRestorationProps {
 }
 
 /**
- * ScrollRestoration component
+ * Public as `Html.ScrollRestoration` (`@rangojs/router/client`).
  *
  * Enables scroll position restoration across navigations:
  * - Saves scroll positions to sessionStorage
@@ -57,7 +57,7 @@ export interface ScrollRestorationProps {
  *   return (
  *     <html>
  *       <body>
- *         <ScrollRestoration />
+ *         <Html.ScrollRestoration />
  *         {children}
  *       </body>
  *     </html>
@@ -78,7 +78,7 @@ export function ScrollRestoration({ getKey }: ScrollRestorationProps) {
 /**
  * Hook to initialize scroll restoration
  *
- * Alternative to the ScrollRestoration component for more control.
+ * Alternative to `<Html.ScrollRestoration />` for more control.
  *
  * @example
  * ```tsx

package/src/browser/rsc-router.tsx

@@ -39,6 +39,7 @@ import {
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { stripShellMissMarker } from "./history-state.js";
 import { setActiveInterceptTargets } from "../client-urls/navigation.js";
 
 // Vite HMR types are provided by vite/client
@@ -169,6 +170,10 @@ export async function initBrowserApp(
   } = options;
 
   bootLog("initBrowserApp start");
+  // 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.
+  stripShellMissMarker();
   bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
@@ -655,7 +660,7 @@ export interface RangoProps {}
  *
  * @example
  * ```tsx
- * import { initBrowserApp, Rango } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "@rangojs/router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *

package/src/browser/scroll-restoration.ts

@@ -72,6 +72,13 @@ type GetScrollKeyFunction = (location: {
 
 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).
+ */
+let displayedKey: string | null = null;
+
 /**
  * Generate a unique key for the current history entry.
  * Uses history.state.key if available, otherwise generates and stores a new one.
@@ -138,7 +145,7 @@ export function initScrollRestoration(options?: {
   }
 
   // Ensure current history entry has a key
-  getHistoryStateKey();
+  trackDisplayedEntry();
 
   // Save scroll positions on pagehide (before leaving/refreshing)
   const handlePageHide = () => {
@@ -148,7 +155,14 @@ export function initScrollRestoration(options?: {
     window.history.scrollRestoration = "auto";
   };
 
+  // A bfcache restore keeps the "auto" set on pagehide; take scroll back.
+  // Only here: without <Html.ScrollRestoration> the browser owns scroll.
+  const handlePageShow = (event: PageTransitionEvent) => {
+    if (event.persisted) window.history.scrollRestoration = "manual";
+  };
+
   window.addEventListener("pagehide", handlePageHide);
+  window.addEventListener("pageshow", handlePageShow);
 
   if (IS_BROWSER_DEBUG) {
     debugLog(
@@ -160,10 +174,12 @@ export function initScrollRestoration(options?: {
   return () => {
     cancelScrollRestorationPolling();
     window.removeEventListener("pagehide", handlePageHide);
+    window.removeEventListener("pageshow", handlePageShow);
     window.history.scrollRestoration = "auto";
     initialized = false;
     savedScrollPositions = {};
     scrollKeyOrder = [];
+    displayedKey = null;
   };
 }
 
@@ -172,8 +188,10 @@ export function initScrollRestoration(options?: {
  * Maintains bounded size by evicting oldest entries when the limit is exceeded.
  */
 export function saveCurrentScrollPosition(): void {
-  const key = getScrollKey();
+  saveScrollPosition(getScrollKey(), window.scrollY);
+}
 
+function saveScrollPosition(key: string, y: number): void {
   // If this key already exists, remove it from its current position
   // in the order array so it can be re-appended at the end (most recent).
   const existingIndex = scrollKeyOrder.indexOf(key);
@@ -181,7 +199,7 @@ export function saveCurrentScrollPosition(): void {
     scrollKeyOrder.splice(existingIndex, 1);
   }
 
-  savedScrollPositions[key] = window.scrollY;
+  savedScrollPositions[key] = y;
   scrollKeyOrder.push(key);
 
   // Evict oldest entries if we exceed the limit
@@ -354,6 +372,23 @@ export function handleNavigationStart(): void {
   saveCurrentScrollPosition();
 }
 
+/**
+ * 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.
+ */
+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);
+  }
+}
+
 /**
  * Handle scroll after navigation completes.
  * @param options.restore - If true, restore saved position (for popstate)
@@ -376,10 +411,17 @@ export function handleNavigationEnd(options: {
   // But basic scroll-to-top and hash scrolling work without it — this
   // matters during cross-app navigation where ScrollRestoration unmounts
   // and remounts, creating a brief window where initialized is false.
-  if (restore && initialized) {
-    if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
+  if (restore) {
+    if (
+      initialized &&
+      restoreScrollPosition({ retryIfStreaming: true, isStreaming })
+    ) {
       return;
     }
+    // An "auto" entry (no <Html.ScrollRestoration>, or created before it mounted)
+    // is restored by the browser. A scrollTo here races that restore, and
+    // when it runs second the page lands at the top.
+    if (window.history.scrollRestoration === "auto") return;
     // Fall through to hash or top if no saved position
   }
 
@@ -410,5 +452,10 @@ export function handleNavigationEnd(options: {
  * Call this after changing history to ensure new entry has a key.
  */
 export function ensureHistoryKey(): void {
-  getHistoryStateKey();
+  trackDisplayedEntry();
+}
+
+/** Mints the current entry's key if missing and records it as displayed. */
+function trackDisplayedEntry(): void {
+  displayedKey = getScrollKey();
 }