rwsdk 1.3.0-canary.7 → 1.3.1

package/dist/lib/e2e/release.d.mts

@@ -39,9 +39,10 @@ export declare function runRelease(cwd: string, projectDir: string, resourceUniq
 /**
  * Run a local production preview server (build + preview) and return the URL.
  */
-export declare function runPreviewServer(packageManager?: string, cwd?: string): Promise<{
+export declare function runPreviewServer(packageManager?: string, cwd?: string, preferredPort?: number): Promise<{
     url: string;
     stopPreview: () => Promise<void>;
+    port: number;
 }>;
 /**
  * Check if a resource name includes a specific resource unique key

package/dist/lib/e2e/release.mjs

@@ -3,6 +3,7 @@ import { execaCommand } from "execa";
 import { existsSync, readFileSync } from "fs";
 import { pathExists } from "fs-extra";
 import * as fs from "fs/promises";
+import { createConnection } from "node:net";
 import { parse as parseJsonc } from "jsonc-parser";
 import { setTimeout } from "node:timers/promises";
 import { basename, dirname, join, relative, resolve } from "path";
@@ -11,6 +12,42 @@ import { checkServerUp } from "./browser.mjs";
 import { extractLastJson, parseJson } from "../../lib/jsonUtils.mjs";
 import { IS_DEBUG_MODE, PREVIEW_SERVER_TIMEOUT } from "./constants.mjs";
 const log = debug("rwsdk:e2e:release");
+function isPortFree(port, host = "localhost") {
+    return new Promise((resolve) => {
+        const socket = createConnection(port, host);
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(value);
+        };
+        socket.once("connect", () => finish(false));
+        socket.once("error", (err) => {
+            finish(err.code === "ECONNREFUSED");
+        });
+        socket.setTimeout(300, () => finish(true));
+    });
+}
+async function findFreePort(startingAt = 4173) {
+    for (let port = startingAt; port < startingAt + 100; port++) {
+        if (await isPortFree(port)) {
+            return port;
+        }
+    }
+    throw new Error(`Could not find a free port between ${startingAt} and ${startingAt + 99}`);
+}
+async function waitForPortFree(port, timeoutMs = 10000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await isPortFree(port)) {
+            return;
+        }
+        await setTimeout(200);
+    }
+    throw new Error(`Port ${port} did not become free within ${timeoutMs}ms`);
+}
 /**
  * Find wrangler cache by searching up the directory tree for node_modules/.cache/wrangler
  */
@@ -404,7 +441,7 @@ export async function runRelease(cwd, projectDir, resourceUniqueKey) {
 /**
  * Run a local production preview server (build + preview) and return the URL.
  */
-export async function runPreviewServer(packageManager = "pnpm", cwd) {
+export async function runPreviewServer(packageManager = "pnpm", cwd, preferredPort) {
     console.log("🚀 Building for production preview...");
     const pm = packageManager === "yarn-classic" ? "yarn" : packageManager;
     await $(pm, ["run", "build"], {
@@ -413,6 +450,29 @@ export async function runPreviewServer(packageManager = "pnpm", cwd) {
         env: { ...process.env, NODE_ENV: "production" },
     });
     console.log("✅ Build complete. Starting preview server...");
+    // Pick a port. If the caller asked for a specific port (e.g. a redeploy
+    // wants to reuse the previous port), try that first and wait briefly for
+    // the old process to release it. If it is still occupied, fall back to a
+    // free port rather than failing — deterministic port assignment can collide
+    // between different playground test files.
+    let port;
+    if (preferredPort != null) {
+        if (await isPortFree(preferredPort)) {
+            port = preferredPort;
+        }
+        else {
+            try {
+                await waitForPortFree(preferredPort, 3000);
+                port = preferredPort;
+            }
+            catch {
+                port = await findFreePort(preferredPort + 1);
+            }
+        }
+    }
+    else {
+        port = await findFreePort(4173);
+    }
     let previewProcess = null;
     let isErrorExpected = false;
     const stopPreview = async () => {
@@ -430,7 +490,7 @@ export async function runPreviewServer(packageManager = "pnpm", cwd) {
         await previewProcess.catch(() => { });
         console.log("Preview server stopped");
     };
-    previewProcess = $(pm, ["run", "preview", "--", "--port", "4173", "--strictPort"], {
+    previewProcess = $(pm, ["run", "preview", "--port", String(port), "--strictPort"], {
         all: true,
         detached: process.platform !== "win32",
         cleanup: true,
@@ -439,6 +499,11 @@ export async function runPreviewServer(packageManager = "pnpm", cwd) {
         env: { ...process.env, NODE_ENV: "production" },
         stdio: "pipe",
     });
+    previewProcess.all?.on("data", (data) => {
+        if (IS_DEBUG_MODE) {
+            process.stdout.write(data.toString());
+        }
+    });
     previewProcess.catch((error) => {
         if (!isErrorExpected) {
             log("Preview server process exited unexpectedly: %O", error);
@@ -471,10 +536,10 @@ export async function runPreviewServer(packageManager = "pnpm", cwd) {
     // context(justinvdm, 2026-05-13): Give the CI preview path the same
     // readiness budget as the dev server so local agent-ci runs can absorb build
     // and startup latency without falling back to Cloudflare.
-    const reachableDebugUrl = await checkServerUp("http://localhost:4173", "/__debug", Math.max(1, Math.ceil(PREVIEW_SERVER_TIMEOUT / 2000)), false);
-    const serverUrl = new URL(reachableDebugUrl).origin;
+    const serverUrl = `http://localhost:${port}`;
+    await checkServerUp(serverUrl, "/__debug", Math.max(1, Math.ceil(PREVIEW_SERVER_TIMEOUT / 2000)), false);
     console.log(`✅ Preview server started at ${serverUrl}`);
-    return { url: serverUrl, stopPreview };
+    return { url: serverUrl, stopPreview, port };
 }
 /**
  * Check if a resource name includes a specific resource unique key

package/dist/lib/e2e/testHarness.d.mts

@@ -14,6 +14,7 @@ interface DeploymentInstance {
     resourceUniqueKey: string;
     projectDir: string;
     cleanup: () => Promise<void>;
+    redeploy: () => Promise<void>;
 }
 export declare const SKIP_DEV_SERVER_TESTS: boolean;
 export declare const SKIP_DEPLOYMENT_TESTS: boolean;

package/dist/lib/e2e/testHarness.mjs

@@ -11,6 +11,17 @@ import { deleteD1Database, deleteWorker, isRelatedToTest, runPreviewServer, runR
 import { setupTarballEnvironment } from "./tarball.mjs";
 import { ensureTmpDir } from "./utils.mjs";
 export { DEPLOYMENT_CHECK_TIMEOUT, DEPLOYMENT_MIN_TRIES, DEPLOYMENT_TIMEOUT, DEV_SERVER_MIN_TRIES, DEV_SERVER_TIMEOUT, HYDRATION_TIMEOUT, INSTALL_DEPENDENCIES_RETRIES, PUPPETEER_TIMEOUT, SETUP_PLAYGROUND_ENV_TIMEOUT, SETUP_WAIT_TIMEOUT, TEST_MAX_RETRIES, TEST_MAX_RETRIES_PER_CODE, };
+function getProjectBasePort(projectDir) {
+    // Spread concurrent playground previews across a wide port range so
+    // different playgrounds are unlikely to collide. Each playground still
+    // reuses the same port for redeploys within a single test file.
+    const name = basename(projectDir);
+    let hash = 0;
+    for (let i = 0; i < name.length; i++) {
+        hash = (hash * 31 + name.charCodeAt(i)) >>> 0;
+    }
+    return 4173 + (hash % 1000);
+}
 // Environment variable flags for skipping tests
 export const SKIP_DEV_SERVER_TESTS = process.env.RWSDK_SKIP_DEV === "1";
 export const SKIP_DEPLOYMENT_TESTS = process.env.RWSDK_SKIP_DEPLOY === "1";
@@ -212,7 +223,41 @@ export function createDeployment() {
         throw new Error("Deploy playground environment not initialized. Enable `deploy: true` in setupPlaygroundEnvironment.");
     }
     const { projectDir } = globalDeployPlaygroundEnv;
+    const packageManager = process.env.PACKAGE_MANAGER || "pnpm";
     let instance = null;
+    let previewStop = null;
+    let previewPort = null;
+    const makeRedeploy = () => async () => {
+        if (!instance) {
+            throw new Error("Deployment not started");
+        }
+        if (IS_PULL_REQUEST) {
+            if (!previewStop || previewPort == null) {
+                throw new Error("No preview server to redeploy");
+            }
+            await previewStop();
+            const newPreview = await runPreviewServer(packageManager, projectDir, previewPort);
+            previewStop = newPreview.stopPreview;
+            previewPort = newPreview.port;
+            instance.url = newPreview.url;
+            return;
+        }
+        const deployResult = await runRelease(projectDir, projectDir, instance.resourceUniqueKey);
+        await poll(async () => {
+            try {
+                const response = await fetch(deployResult.url);
+                const body = await response.text();
+                return body.includes("__RWSDK_CONTEXT");
+            }
+            catch (e) {
+                return false;
+            }
+        }, {
+            timeout: DEPLOYMENT_CHECK_TIMEOUT,
+        });
+        instance.url = deployResult.url;
+        instance.workerName = deployResult.workerName;
+    };
     return {
         projectDir,
         start: async () => {
@@ -231,8 +276,10 @@ export function createDeployment() {
                 : Math.random().toString(36).substring(2, 15);
             if (IS_PULL_REQUEST) {
                 console.log("PR mode detected — using local preview instead of deploy");
-                const previewResult = await runPreviewServer(process.env.PACKAGE_MANAGER ||
-                    "pnpm", projectDir);
+                const basePort = getProjectBasePort(projectDir);
+                const previewResult = await runPreviewServer(packageManager, projectDir, basePort);
+                previewStop = previewResult.stopPreview;
+                previewPort = previewResult.port;
                 instance = {
                     url: previewResult.url,
                     workerName: `preview-${resourceUniqueKey}`,
@@ -244,6 +291,7 @@ export function createDeployment() {
                         });
                         return Promise.resolve();
                     },
+                    redeploy: makeRedeploy(),
                 };
                 deploymentInstances.push(instance);
                 return instance;
@@ -284,6 +332,7 @@ export function createDeployment() {
                     resourceUniqueKey,
                     projectDir: projectDir,
                     cleanup,
+                    redeploy: makeRedeploy(),
                 };
             }, {
                 timeout: DEPLOYMENT_TIMEOUT,

package/dist/runtime/client/client.d.ts

@@ -4,6 +4,7 @@ export type { Dispatch, MutableRefObject, SetStateAction } from "react";
 export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
 export type { ActionResponseData } from "./types";
+import { type RecoveryOptions } from "./recovery.js";
 import type { ActionResponseData, HydrationOptions, Transport } from "./types";
 export declare const fetchTransport: Transport;
 /**
@@ -60,10 +61,10 @@ export declare const fetchTransport: Transport;
  *   },
  * });
  */
-export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, }?: {
+export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, onModuleNotFound, }?: {
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;
     handleResponse?: (response: Response) => boolean;
     onHydrated?: () => void;
     onActionResponse?: (actionResponse: ActionResponseData) => boolean | void;
-}) => Promise<void>;
+} & RecoveryOptions) => Promise<void>;

package/dist/runtime/client/client.js

@@ -14,6 +14,7 @@ export { default as React } from "react";
 export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
 import { getCachedNavigationResponse } from "./navigationCache.js";
+import { configureRecovery } from "./recovery.js";
 import { isActionResponse } from "./types";
 export const fetchTransport = (transportContext) => {
     const fetchCallServer = async (id, args, source = "action", method = "POST") => {
@@ -172,7 +173,10 @@ export const fetchTransport = (transportContext) => {
  *   },
  * });
  */
-export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, } = {}) => {
+export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, onModuleNotFound, } = {}) => {
+    if (onModuleNotFound) {
+        configureRecovery({ onModuleNotFound });
+    }
     const transportContext = {
         setRscPayload: () => { },
         handleResponse,

package/dist/runtime/client/navigation.js

@@ -1,4 +1,5 @@
 import { onNavigationCommit, preloadFromLinkTags, } from "./navigationCache.js";
+import { createScrollRestoration, } from "./scrollRestoration.js";
 export function validateClickEvent(event, target) {
     // should this only work for left click?
     if (event.button !== 0) {
@@ -32,10 +33,7 @@ export function validateClickEvent(event, target) {
     return true;
 }
 let IS_CLIENT_NAVIGATION = false;
-// Scroll intent recorded at navigation time and applied post-commit in
-// onHydrated, so the new scroll position aligns with the new DOM rather
-// than flashing on top of the old one.
-let pendingScroll = null;
+let scrollRestoration = null;
 let currentPathKey = null;
 function getLocationPathKey() {
     return `${window.location.pathname ?? ""}${window.location.search ?? ""}`;
@@ -48,39 +46,32 @@ export async function navigate(href, options = { history: "push" }) {
         window.location.href = href;
         return;
     }
-    saveScrollPosition(window.scrollX, window.scrollY);
     const url = new URL(href, window.location.href);
+    const scrollToTop = options.info?.scrollToTop ?? true;
+    const scrollBehavior = (options.info?.scrollBehavior ??
+        "instant");
+    const nextScrollPosition = scrollToTop
+        ? { x: 0, y: 0 }
+        : { x: window.scrollX, y: window.scrollY };
     if (options.history === "push") {
-        window.history.pushState({ path: href }, "", url);
+        scrollRestoration?.pushEntry(href, url, nextScrollPosition);
     }
     else {
-        window.history.replaceState({ path: href }, "", url);
+        scrollRestoration?.replaceEntry(href, url, nextScrollPosition);
     }
     currentPathKey = getUrlPathKey(url);
-    const scrollToTop = options.info?.scrollToTop ?? true;
-    const scrollBehavior = (options.info?.scrollBehavior ??
-        "instant");
     if (scrollToTop) {
-        pendingScroll = { x: 0, y: 0, behavior: scrollBehavior };
+        scrollRestoration?.setPendingScroll({
+            ...nextScrollPosition,
+            behavior: scrollBehavior,
+        });
+    }
+    else {
+        scrollRestoration?.recordCurrentPosition(window.scrollX, window.scrollY);
     }
     await options.onNavigate?.();
     await globalThis.__rsc_callServer(null, null, "navigation");
 }
-function saveScrollPosition(x, y) {
-    window.history.replaceState({
-        ...window.history.state,
-        scrollX: x,
-        scrollY: y,
-    }, "", window.location.href);
-}
-function applyPendingScroll() {
-    if (!pendingScroll)
-        return;
-    const { x, y, behavior } = pendingScroll;
-    pendingScroll = null;
-    window.scrollTo({ top: y, left: x, behavior });
-    saveScrollPosition(x, y);
-}
 /**
  * Initializes client-side navigation for Single Page App (SPA) behavior.
  *
@@ -124,23 +115,8 @@ function applyPendingScroll() {
  */
 export function initClientNavigation(opts = {}) {
     IS_CLIENT_NAVIGATION = true;
-    // Take manual control of scroll restoration. With "auto", the browser
-    // restores scroll immediately on popstate — before the RSC payload has
-    // committed — which causes the old DOM to flash at the new scroll offset.
-    history.scrollRestoration = "manual";
-    // If we're booting onto an entry that already has a saved scroll (e.g.
-    // a reload after scrolling, or a back-forward cache restore), queue that
-    // position so the first commit lands us where the user left off.
-    const bootState = window.history.state;
-    if (bootState &&
-        (typeof bootState.scrollX === "number" ||
-            typeof bootState.scrollY === "number")) {
-        pendingScroll = {
-            x: bootState.scrollX ?? 0,
-            y: bootState.scrollY ?? 0,
-            behavior: "instant",
-        };
-    }
+    scrollRestoration = createScrollRestoration();
+    scrollRestoration.initialize();
     currentPathKey = getLocationPathKey();
     document.addEventListener("click", async function handleClickEvent(event) {
         if (!validateClickEvent(event, event.target)) {
@@ -159,28 +135,33 @@ export function initClientNavigation(opts = {}) {
         if (isHashOnlyChange) {
             return;
         }
-        const state = window.history.state ?? {};
-        pendingScroll = {
-            x: typeof state.scrollX === "number" ? state.scrollX : 0,
-            y: typeof state.scrollY === "number" ? state.scrollY : 0,
-            behavior: "instant",
-        };
+        scrollRestoration?.restorePopStateScroll();
         await opts.onNavigate?.();
         await globalThis.__rsc_callServer(null, null, "navigation");
     });
-    // Persist the user's scroll position on the current history entry so
-    // that back/forward navigation can restore it accurately once the new
-    // RSC payload commits. Coalesced via rAF to avoid thrashing replaceState.
-    let scrollSaveScheduled = false;
+    // Track the user's scroll position in memory so back/forward navigation can
+    // restore it after the RSC payload commits. Avoid writing on every scroll via
+    // history.replaceState because browsers throttle frequent history updates.
     window.addEventListener("scroll", () => {
-        if (scrollSaveScheduled)
-            return;
-        scrollSaveScheduled = true;
-        requestAnimationFrame(() => {
-            scrollSaveScheduled = false;
-            saveScrollPosition(window.scrollX, window.scrollY);
-        });
+        scrollRestoration?.recordCurrentPosition(window.scrollX, window.scrollY);
     }, { passive: true });
+    let didFlushForHiddenPage = false;
+    function flushForPageLifecycle() {
+        if (didFlushForHiddenPage) {
+            return;
+        }
+        didFlushForHiddenPage = true;
+        scrollRestoration?.flushCurrentPositionToHistoryState();
+    }
+    window.addEventListener("pagehide", flushForPageLifecycle);
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") {
+            flushForPageLifecycle();
+        }
+        else {
+            didFlushForHiddenPage = false;
+        }
+    });
     function handleResponse(response) {
         if (response.status >= 300 && response.status < 400) {
             const location = response.headers.get("Location");
@@ -205,7 +186,7 @@ export function initClientNavigation(opts = {}) {
         // Apply any pending scroll intent now that React has committed the new
         // DOM — this is what prevents the scroll flash on both link-click and
         // popstate navigations.
-        applyPendingScroll();
+        scrollRestoration?.applyPendingScroll();
         // After each RSC hydration/update, increment generation and evict old caches,
         // then warm the navigation cache based on any <link rel="x-prefetch"> tags
         // rendered for the current location.

package/dist/runtime/client/navigation.test.js

@@ -1,10 +1,18 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
-import { validateClickEvent, initClientNavigation } from "./navigation";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { initClientNavigation, validateClickEvent } from "./navigation";
+import { HISTORY_STATE_SCROLL_KEY } from "./scrollRestoration";
 // Mocking browser globals
 vi.stubGlobal("window", {
     location: { href: "http://localhost/" },
     addEventListener: vi.fn(),
-    history: { scrollRestoration: "auto" },
+    history: {
+        scrollRestoration: "auto",
+        pushState: vi.fn(),
+        replaceState: vi.fn(),
+        state: {},
+    },
+    scrollX: 0,
+    scrollY: 0,
 });
 vi.stubGlobal("document", {
     addEventListener: vi.fn(),
@@ -84,8 +92,11 @@ describe("onNavigate callback (issue #1123 regression)", () => {
         capturedClickHandler = null;
         capturedPopstateHandler = null;
         vi.clearAllMocks();
+        let historyState = {};
         // Capture registered event listeners so we can invoke them manually
         vi.stubGlobal("document", {
+            visibilityState: "visible",
+            querySelectorAll: vi.fn().mockReturnValue([]),
             addEventListener: vi.fn((event, handler) => {
                 if (event === "click")
                     capturedClickHandler = handler;
@@ -99,10 +110,18 @@ describe("onNavigate callback (issue #1123 regression)", () => {
             }),
             history: {
                 scrollRestoration: "auto",
-                pushState: vi.fn(),
-                replaceState: vi.fn(),
-                state: {},
+                get state() {
+                    return historyState;
+                },
+                pushState: vi.fn((state) => {
+                    historyState = state;
+                }),
+                replaceState: vi.fn((state) => {
+                    historyState = state;
+                }),
             },
+            scrollX: 0,
+            scrollY: 0,
             scrollTo: vi.fn(),
         });
         vi.stubGlobal("history", {
@@ -154,7 +173,9 @@ describe("onNavigate callback (issue #1123 regression)", () => {
     });
     it("onNavigate fires after pushState but before RSC fetch", async () => {
         const callOrder = [];
-        const onNavigate = vi.fn(() => { callOrder.push("onNavigate"); });
+        const onNavigate = vi.fn(() => {
+            callOrder.push("onNavigate");
+        });
         globalThis.__rsc_callServer = vi.fn(() => {
             callOrder.push("rscCallServer");
             return Promise.resolve();
@@ -182,21 +203,61 @@ describe("onNavigate callback (issue #1123 regression)", () => {
         expect(callOrder).toEqual(["onNavigate", "rscCallServer"]);
         expect(window.history.pushState).toHaveBeenCalled();
     });
-    it("ignores hash-only popstate events so anchor links keep their native scroll", async () => {
-        const onNavigate = vi.fn();
-        globalThis.__rsc_callServer = vi.fn().mockResolvedValue(undefined);
-        initClientNavigation({ onNavigate });
-        expect(capturedPopstateHandler).not.toBeNull();
-        window.location.hash = "#heading";
-        await capturedPopstateHandler();
-        expect(onNavigate).not.toHaveBeenCalled();
-        expect(globalThis.__rsc_callServer).not.toHaveBeenCalled();
-    });
 });
 describe("initClientNavigation", () => {
+    let historyState;
+    let capturedScrollHandler = null;
+    let capturedPagehideHandler = null;
+    let capturedVisibilityChangeHandler = null;
+    let capturedPopstateHandler = null;
     beforeEach(() => {
-        window.location.href = "http://localhost/";
+        historyState = {};
+        capturedScrollHandler = null;
+        capturedPagehideHandler = null;
+        capturedVisibilityChangeHandler = null;
+        capturedPopstateHandler = null;
         vi.clearAllMocks();
+        const mockHistory = {
+            scrollRestoration: "auto",
+            get state() {
+                return historyState;
+            },
+            pushState: vi.fn((state) => {
+                historyState = state;
+            }),
+            replaceState: vi.fn((state) => {
+                historyState = state;
+            }),
+        };
+        vi.stubGlobal("document", {
+            visibilityState: "visible",
+            querySelectorAll: vi.fn().mockReturnValue([]),
+            addEventListener: vi.fn((event, handler) => {
+                if (event === "visibilitychange") {
+                    capturedVisibilityChangeHandler = handler;
+                }
+            }),
+        });
+        vi.stubGlobal("window", {
+            location: { href: "http://localhost/", pathname: "/", search: "" },
+            addEventListener: vi.fn((event, handler) => {
+                if (event === "scroll") {
+                    capturedScrollHandler = handler;
+                }
+                if (event === "pagehide") {
+                    capturedPagehideHandler = handler;
+                }
+                if (event === "popstate") {
+                    capturedPopstateHandler = handler;
+                }
+            }),
+            history: mockHistory,
+            fetch: vi.fn(),
+            scrollX: 0,
+            scrollY: 0,
+            scrollTo: vi.fn(),
+        });
+        vi.stubGlobal("history", mockHistory);
     });
     it("handleResponse should follow redirects", () => {
         const { handleResponse } = initClientNavigation();
@@ -224,4 +285,91 @@ describe("initClientNavigation", () => {
         initClientNavigation();
         expect(history.scrollRestoration).toBe("manual");
     });
+    it("ignores hash-only popstate events so anchor links keep their native scroll", async () => {
+        const onNavigate = vi.fn();
+        globalThis.__rsc_callServer = vi.fn().mockResolvedValue(undefined);
+        const { onHydrated } = initClientNavigation({ onNavigate });
+        expect(capturedPopstateHandler).not.toBeNull();
+        window.location.hash =
+            "#heading";
+        window.location.href =
+            "http://localhost/#heading";
+        window.scrollY = 500;
+        await capturedPopstateHandler();
+        onHydrated();
+        expect(onNavigate).not.toHaveBeenCalled();
+        expect(globalThis.__rsc_callServer).not.toHaveBeenCalled();
+        expect(window.scrollTo).not.toHaveBeenCalled();
+    });
+    it("does not write to history state on scroll", () => {
+        initClientNavigation();
+        expect(capturedScrollHandler).not.toBeNull();
+        vi.mocked(window.history.replaceState).mockClear();
+        window.scrollY = 100;
+        capturedScrollHandler();
+        window.scrollY = 200;
+        capturedScrollHandler();
+        expect(window.history.replaceState).not.toHaveBeenCalled();
+    });
+    it("restores scroll from persisted history state after reload", () => {
+        historyState = {
+            [HISTORY_STATE_SCROLL_KEY]: "entry:1",
+            scrollX: 9,
+            scrollY: 321,
+        };
+        const { onHydrated } = initClientNavigation();
+        onHydrated();
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 9,
+            top: 321,
+            behavior: "instant",
+        });
+    });
+    it("migrates legacy scrollX/scrollY state on boot", () => {
+        historyState = { scrollX: 11, scrollY: 432 };
+        const { onHydrated } = initClientNavigation();
+        onHydrated();
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 11,
+            scrollY: 432,
+        }), "", "http://localhost/");
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 11,
+            top: 432,
+            behavior: "instant",
+        });
+    });
+    it("flushes the latest scroll position on pagehide for reload restoration", () => {
+        initClientNavigation();
+        expect(capturedScrollHandler).not.toBeNull();
+        expect(capturedPagehideHandler).not.toBeNull();
+        vi.mocked(window.history.replaceState).mockClear();
+        window.scrollX = 3;
+        window.scrollY = 250;
+        capturedScrollHandler();
+        capturedPagehideHandler();
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 3,
+            scrollY: 250,
+        }), "", "http://localhost/");
+    });
+    it("flushes the latest scroll position when the page is hidden", () => {
+        initClientNavigation();
+        expect(capturedVisibilityChangeHandler).not.toBeNull();
+        vi.mocked(window.history.replaceState).mockClear();
+        window.scrollX = 5;
+        window.scrollY = 275;
+        Object.defineProperty(document, "visibilityState", {
+            value: "hidden",
+            configurable: true,
+        });
+        capturedVisibilityChangeHandler();
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 5,
+            scrollY: 275,
+        }), "", "http://localhost/");
+    });
 });