rwsdk 1.2.9 → 1.2.11

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,47 +33,45 @@ 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 ?? ""}`;
+}
+function getUrlPathKey(url) {
+    return `${url.pathname ?? ""}${url.search ?? ""}` || getLocationPathKey();
+}
 export async function navigate(href, options = { history: "push" }) {
     if (!IS_CLIENT_NAVIGATION) {
         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);
     }
-    const scrollToTop = options.info?.scrollToTop ?? true;
-    const scrollBehavior = (options.info?.scrollBehavior ??
-        "instant");
+    currentPathKey = getUrlPathKey(url);
     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.
  *
@@ -116,23 +115,9 @@ 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)) {
             return;
@@ -144,28 +129,39 @@ export function initClientNavigation(opts = {}) {
         await navigate(href, { history: "push", onNavigate: opts.onNavigate });
     }, true);
     window.addEventListener("popstate", async function handlePopState() {
-        const state = window.history.state ?? {};
-        pendingScroll = {
-            x: typeof state.scrollX === "number" ? state.scrollX : 0,
-            y: typeof state.scrollY === "number" ? state.scrollY : 0,
-            behavior: "instant",
-        };
+        const nextPathKey = getLocationPathKey();
+        const isHashOnlyChange = nextPathKey === currentPathKey;
+        currentPathKey = nextPathKey;
+        if (isHashOnlyChange) {
+            return;
+        }
+        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");
@@ -190,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,25 +92,36 @@ 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;
             }),
         });
         vi.stubGlobal("window", {
-            location: { href: "http://localhost/" },
+            location: { href: "http://localhost/", pathname: "/", search: "" },
             addEventListener: vi.fn((event, handler) => {
                 if (event === "popstate")
                     capturedPopstateHandler = handler;
             }),
             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", {
@@ -148,12 +167,15 @@ describe("onNavigate callback (issue #1123 regression)", () => {
         const onNavigate = vi.fn();
         initClientNavigation({ onNavigate });
         expect(capturedPopstateHandler).not.toBeNull();
+        window.location.pathname = "/about";
         await capturedPopstateHandler();
         expect(onNavigate).toHaveBeenCalled();
     });
     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();
@@ -183,9 +205,59 @@ describe("onNavigate callback (issue #1123 regression)", () => {
     });
 });
 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();
@@ -213,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/");
+    });
 });

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

@@ -0,0 +1,25 @@
+export declare const HISTORY_STATE_SCROLL_KEY = "__rwsdk_scroll_key";
+export type ScrollPosition = {
+    x: number;
+    y: number;
+};
+export type PendingScroll = ScrollPosition & {
+    behavior: ScrollBehavior;
+};
+export interface NavigationHistoryState extends Record<string, unknown> {
+    path?: string;
+    scrollX?: number;
+    scrollY?: number;
+    [HISTORY_STATE_SCROLL_KEY]?: string;
+}
+export interface ScrollRestorationController {
+    initialize(): void;
+    recordCurrentPosition(x: number, y: number): void;
+    flushCurrentPositionToHistoryState(x?: number, y?: number): void;
+    pushEntry(href: string, url: URL, initialPosition: ScrollPosition): void;
+    replaceEntry(href: string, url: URL, initialPosition: ScrollPosition): void;
+    restorePopStateScroll(): void;
+    setPendingScroll(pendingScroll: PendingScroll): void;
+    applyPendingScroll(): void;
+}
+export declare function createScrollRestoration(): ScrollRestorationController;

package/dist/runtime/client/scrollRestoration.js

@@ -0,0 +1,157 @@
+export const HISTORY_STATE_SCROLL_KEY = "__rwsdk_scroll_key";
+export function createScrollRestoration() {
+    const historyEntryKeyPrefix = Math.random().toString(36).slice(2);
+    const scrollPositions = new Map();
+    let currentHistoryEntryKey = null;
+    let nextHistoryEntryKey = 0;
+    let pendingScroll = null;
+    function createHistoryEntryKey() {
+        nextHistoryEntryKey += 1;
+        return `${historyEntryKeyPrefix}:${nextHistoryEntryKey}`;
+    }
+    function readHistoryState() {
+        const state = window.history.state;
+        return state && typeof state === "object"
+            ? { ...state }
+            : {};
+    }
+    function getHistoryEntryKey(state) {
+        const key = state[HISTORY_STATE_SCROLL_KEY];
+        return typeof key === "string" ? key : null;
+    }
+    function getScrollPositionFromState(state) {
+        if (typeof state.scrollX === "number" ||
+            typeof state.scrollY === "number") {
+            return {
+                x: typeof state.scrollX === "number" ? state.scrollX : 0,
+                y: typeof state.scrollY === "number" ? state.scrollY : 0,
+            };
+        }
+        return null;
+    }
+    function ensureCurrentHistoryEntryKey(state = readHistoryState()) {
+        const existingKey = getHistoryEntryKey(state);
+        if (existingKey) {
+            currentHistoryEntryKey = existingKey;
+            return existingKey;
+        }
+        const historyEntryKey = createHistoryEntryKey();
+        currentHistoryEntryKey = historyEntryKey;
+        window.history.replaceState({ ...state, [HISTORY_STATE_SCROLL_KEY]: historyEntryKey }, "", window.location.href);
+        return historyEntryKey;
+    }
+    function getCurrentHistoryEntryKeyForReplace(state) {
+        const existingKey = getHistoryEntryKey(state) ?? currentHistoryEntryKey;
+        if (existingKey) {
+            currentHistoryEntryKey = existingKey;
+            return existingKey;
+        }
+        const historyEntryKey = createHistoryEntryKey();
+        currentHistoryEntryKey = historyEntryKey;
+        return historyEntryKey;
+    }
+    function getSavedScrollPosition(state) {
+        const historyEntryKey = getHistoryEntryKey(state) ?? currentHistoryEntryKey;
+        const savedPosition = historyEntryKey
+            ? scrollPositions.get(historyEntryKey)
+            : undefined;
+        return savedPosition ?? getScrollPositionFromState(state);
+    }
+    function writeHistoryState(state, historyEntryKey, position) {
+        window.history.replaceState({
+            ...state,
+            [HISTORY_STATE_SCROLL_KEY]: historyEntryKey,
+            scrollX: position.x,
+            scrollY: position.y,
+        }, "", window.location.href);
+    }
+    return {
+        initialize() {
+            // 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.
+            if ("scrollRestoration" in window.history) {
+                window.history.scrollRestoration = "manual";
+            }
+            // Boot can happen after a reload, or after an older runtime wrote only
+            // scrollX/scrollY. Seed the in-memory store from history.state so the
+            // first commit can restore the saved position without per-scroll writes.
+            const bootState = readHistoryState();
+            const bootHistoryEntryKey = ensureCurrentHistoryEntryKey(bootState);
+            const bootScrollPosition = getSavedScrollPosition(bootState);
+            if (bootScrollPosition) {
+                scrollPositions.set(bootHistoryEntryKey, bootScrollPosition);
+                pendingScroll = {
+                    x: bootScrollPosition.x,
+                    y: bootScrollPosition.y,
+                    behavior: "instant",
+                };
+            }
+        },
+        recordCurrentPosition(x, y) {
+            if (!currentHistoryEntryKey) {
+                return;
+            }
+            scrollPositions.set(currentHistoryEntryKey, { x, y });
+        },
+        flushCurrentPositionToHistoryState(x = window.scrollX, y = window.scrollY) {
+            const state = readHistoryState();
+            const historyEntryKey = ensureCurrentHistoryEntryKey(state);
+            const position = { x, y };
+            scrollPositions.set(historyEntryKey, position);
+            writeHistoryState(state, historyEntryKey, position);
+        },
+        pushEntry(href, url, initialPosition) {
+            this.flushCurrentPositionToHistoryState();
+            const historyEntryKey = createHistoryEntryKey();
+            currentHistoryEntryKey = historyEntryKey;
+            scrollPositions.set(historyEntryKey, initialPosition);
+            window.history.pushState({
+                path: href,
+                [HISTORY_STATE_SCROLL_KEY]: historyEntryKey,
+                scrollX: initialPosition.x,
+                scrollY: initialPosition.y,
+            }, "", url);
+        },
+        replaceEntry(href, url, initialPosition) {
+            const state = readHistoryState();
+            const historyEntryKey = getCurrentHistoryEntryKeyForReplace(state);
+            scrollPositions.set(historyEntryKey, initialPosition);
+            window.history.replaceState({
+                ...state,
+                path: href,
+                [HISTORY_STATE_SCROLL_KEY]: historyEntryKey,
+                scrollX: initialPosition.x,
+                scrollY: initialPosition.y,
+            }, "", url);
+        },
+        restorePopStateScroll() {
+            const state = readHistoryState();
+            const historyEntryKey = ensureCurrentHistoryEntryKey(state);
+            const savedScrollPosition = getSavedScrollPosition(state) ?? {
+                x: 0,
+                y: 0,
+            };
+            if (!scrollPositions.has(historyEntryKey)) {
+                scrollPositions.set(historyEntryKey, savedScrollPosition);
+            }
+            pendingScroll = {
+                x: savedScrollPosition.x,
+                y: savedScrollPosition.y,
+                behavior: "instant",
+            };
+        },
+        setPendingScroll(nextPendingScroll) {
+            pendingScroll = nextPendingScroll;
+            this.recordCurrentPosition(nextPendingScroll.x, nextPendingScroll.y);
+        },
+        applyPendingScroll() {
+            if (!pendingScroll)
+                return;
+            const { x, y, behavior } = pendingScroll;
+            pendingScroll = null;
+            window.scrollTo({ top: y, left: x, behavior });
+            this.recordCurrentPosition(x, y);
+        },
+    };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createScrollRestoration, HISTORY_STATE_SCROLL_KEY, } from "./scrollRestoration";
+describe("scrollRestoration", () => {
+    let historyState;
+    beforeEach(() => {
+        historyState = {};
+        vi.stubGlobal("window", {
+            location: { href: "http://localhost/" },
+            scrollX: 0,
+            scrollY: 0,
+            scrollTo: vi.fn(),
+            history: {
+                scrollRestoration: "auto",
+                get state() {
+                    return historyState;
+                },
+                pushState: vi.fn((state) => {
+                    historyState = state;
+                }),
+                replaceState: vi.fn((state) => {
+                    historyState = state;
+                }),
+            },
+        });
+    });
+    it("restores scroll from history state after a reload", () => {
+        historyState = {
+            [HISTORY_STATE_SCROLL_KEY]: "entry:1",
+            scrollX: 12,
+            scrollY: 345,
+        };
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        scrollRestoration.applyPendingScroll();
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 12,
+            top: 345,
+            behavior: "instant",
+        });
+    });
+    it("migrates legacy scrollX/scrollY history state on boot", () => {
+        historyState = { scrollX: 7, scrollY: 222 };
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        scrollRestoration.applyPendingScroll();
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 7,
+            scrollY: 222,
+        }), "", "http://localhost/");
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 7,
+            top: 222,
+            behavior: "instant",
+        });
+    });
+    it("restores back/forward positions from the in-memory key map", () => {
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        const firstEntryState = historyState;
+        window.scrollY = 500;
+        scrollRestoration.recordCurrentPosition(0, 500);
+        scrollRestoration.pushEntry("/next", new URL("/next", "http://localhost/"), { x: 0, y: 0 });
+        historyState = firstEntryState;
+        scrollRestoration.restorePopStateScroll();
+        scrollRestoration.applyPendingScroll();
+        expect(window.scrollTo).toHaveBeenCalledWith({
+            left: 0,
+            top: 500,
+            behavior: "instant",
+        });
+    });
+    it("does not write to history state while recording scroll", () => {
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        vi.mocked(window.history.replaceState).mockClear();
+        scrollRestoration.recordCurrentPosition(0, 100);
+        scrollRestoration.recordCurrentPosition(0, 200);
+        expect(window.history.replaceState).not.toHaveBeenCalled();
+    });
+    it("flushes the latest scroll position to history state on lifecycle boundaries", () => {
+        const scrollRestoration = createScrollRestoration();
+        scrollRestoration.initialize();
+        vi.mocked(window.history.replaceState).mockClear();
+        scrollRestoration.recordCurrentPosition(4, 400);
+        scrollRestoration.flushCurrentPositionToHistoryState(4, 400);
+        expect(window.history.replaceState).toHaveBeenCalledWith(expect.objectContaining({
+            [HISTORY_STATE_SCROLL_KEY]: expect.any(String),
+            scrollX: 4,
+            scrollY: 400,
+        }), "", "http://localhost/");
+    });
+});

package/dist/vite/miniflareHMRPlugin.mjs

@@ -7,7 +7,7 @@ import { normalizeModulePath } from "../lib/normalizeModulePath.mjs";
 import { hasDirective as sourceHasDirective } from "./hasDirective.mjs";
 import { invalidateModule } from "./invalidateModule.mjs";
 import { isJsFile } from "./isJsFile.mjs";
-import { VIRTUAL_SSR_PREFIX } from "./ssrBridgePlugin.mjs";
+import { VIRTUAL_SSR_PREFIX } from "./ssrVirtualModule.mjs";
 const log = debug("rwsdk:vite:hmr-plugin");
 let hasErrored = false;
 const hasDirective = async (filepath, directive) => {

package/dist/vite/ssrBridgePlugin.d.mts

@@ -1,5 +1,4 @@
 import type { Plugin } from "vite";
-export declare const VIRTUAL_SSR_PREFIX = "virtual:rwsdk:ssr:";
 export declare const ssrBridgePlugin: ({ clientFiles, serverFiles, }: {
     clientFiles: Set<string>;
     serverFiles: Set<string>;

package/dist/vite/ssrBridgePlugin.mjs

@@ -3,8 +3,8 @@ import MagicString from "magic-string";
 import { INTERMEDIATE_SSR_BRIDGE_PATH } from "../lib/constants.mjs";
 import { externalModulesSet } from "./constants.mjs";
 import { findSsrImportCallSites } from "./findSsrSpecifiers.mjs";
+import { isVirtualSsrModuleId, normalizeVirtualSsrModuleId, VIRTUAL_SSR_PREFIX, } from "./ssrVirtualModule.mjs";
 const log = debug("rwsdk:vite:ssr-bridge-plugin");
-export const VIRTUAL_SSR_PREFIX = "virtual:rwsdk:ssr:";
 export const ssrBridgePlugin = ({ clientFiles, serverFiles, }) => {
     let devServer;
     let isDev = false;
@@ -63,10 +63,11 @@ export const ssrBridgePlugin = ({ clientFiles, serverFiles, }) => {
                             process.env.VERBOSE &&
                                 log("Esbuild onResolve called for path=%s, args=%O", args.path, args);
                             if (args.path === "rwsdk/__ssr_bridge" ||
-                                args.path.startsWith(VIRTUAL_SSR_PREFIX)) {
-                                log("Marking as external: %s", args.path);
+                                isVirtualSsrModuleId(args.path)) {
+                                const path = normalizeVirtualSsrModuleId(args.path) ?? args.path;
+                                log("Marking as external: %s", path);
                                 return {
-                                    path: args.path,
+                                    path,
                                     external: true,
                                 };
                             }
@@ -98,14 +99,15 @@ export const ssrBridgePlugin = ({ clientFiles, serverFiles, }) => {
                 // context(justinvdm, 27 May 2025): In dev, we need to dynamically load
                 // SSR modules, so we return the virtual id so that the dynamic loading
                 // can happen in load()
-                if (id.startsWith(VIRTUAL_SSR_PREFIX)) {
-                    if (id.endsWith(".css")) {
-                        const newId = id + ".js";
+                const virtualSsrId = normalizeVirtualSsrModuleId(id);
+                if (virtualSsrId) {
+                    if (virtualSsrId.endsWith(".css")) {
+                        const newId = virtualSsrId + ".js";
                         log("Virtual CSS module, adding .js suffix. old: %s, new: %s", id, newId);
                         return newId;
                     }
-                    log("Returning virtual SSR id for dev: %s", id);
-                    return id;
+                    log("Returning virtual SSR id for dev: %s", virtualSsrId);
+                    return virtualSsrId;
                 }
                 // context(justinvdm, 28 May 2025): The SSR bridge module is a special case -
                 // it is the entry point for all SSR modules, so to trigger the
@@ -119,10 +121,11 @@ export const ssrBridgePlugin = ({ clientFiles, serverFiles, }) => {
             }
             else {
                 // In build mode, the behavior depends on the build pass
-                if (id.startsWith(VIRTUAL_SSR_PREFIX)) {
+                const virtualSsrId = normalizeVirtualSsrModuleId(id);
+                if (virtualSsrId) {
                     if (this.environment.name === "worker") {
                         log("Virtual SSR module case (build-worker pass): resolving to external");
-                        return { id, external: true };
+                        return { id: virtualSsrId, external: true };
                     }
                 }
                 if (id === "rwsdk/__ssr_bridge" && this.environment.name === "worker") {
@@ -141,9 +144,9 @@ export const ssrBridgePlugin = ({ clientFiles, serverFiles, }) => {
             }
         },
         async load(id) {
-            if (id.startsWith(VIRTUAL_SSR_PREFIX) &&
-                this.environment.name === "worker") {
-                const realId = id.slice(VIRTUAL_SSR_PREFIX.length);
+            const virtualSsrId = normalizeVirtualSsrModuleId(id);
+            if (virtualSsrId && this.environment.name === "worker") {
+                const realId = virtualSsrId.slice(VIRTUAL_SSR_PREFIX.length);
                 let idForFetch = realId.endsWith(".css.js")
                     ? realId.slice(0, -3)
                     : realId;

package/dist/vite/ssrVirtualModule.d.mts

@@ -0,0 +1,3 @@
+export declare const VIRTUAL_SSR_PREFIX = "virtual:rwsdk:ssr:";
+export declare function normalizeVirtualSsrModuleId(id: string): string | undefined;
+export declare function isVirtualSsrModuleId(id: string): boolean;

package/dist/vite/ssrVirtualModule.mjs

@@ -0,0 +1,11 @@
+const VITE_ID_PREFIX = "/@id/";
+export const VIRTUAL_SSR_PREFIX = "virtual:rwsdk:ssr:";
+export function normalizeVirtualSsrModuleId(id) {
+    const normalizedId = id.startsWith(VITE_ID_PREFIX)
+        ? id.slice(VITE_ID_PREFIX.length)
+        : id;
+    return normalizedId.startsWith(VIRTUAL_SSR_PREFIX) ? normalizedId : undefined;
+}
+export function isVirtualSsrModuleId(id) {
+    return normalizeVirtualSsrModuleId(id) !== undefined;
+}

package/dist/vite/transformJsxScriptTagsPlugin.hook.test.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/vite/transformJsxScriptTagsPlugin.hook.test.mjs

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { isVirtualSsrModuleId, normalizeVirtualSsrModuleId, VIRTUAL_SSR_PREFIX, } from "./ssrVirtualModule.mjs";
+import { transformJsxScriptTagsPlugin } from "./transformJsxScriptTagsPlugin.mjs";
+describe("isVirtualSsrModuleId", () => {
+    it.each([
+        [`${VIRTUAL_SSR_PREFIX}/src/Preview.tsx`, true],
+        [`${VIRTUAL_SSR_PREFIX}rwsdk/__ssr_bridge`, true],
+        [`/@id/${VIRTUAL_SSR_PREFIX}/src/Preview.tsx`, true],
+        [`/src/${VIRTUAL_SSR_PREFIX}Preview.tsx`, false],
+        ["/src/Preview.tsx", false],
+    ])("identifies %s as virtual SSR module id: %s", (id, expected) => {
+        expect(isVirtualSsrModuleId(id)).toBe(expected);
+    });
+    it("normalizes Vite /@id/ virtual SSR module URLs to bare module ids", () => {
+        expect(normalizeVirtualSsrModuleId(`/@id/${VIRTUAL_SSR_PREFIX}/src/Preview.tsx`)).toBe(`${VIRTUAL_SSR_PREFIX}/src/Preview.tsx`);
+    });
+});
+describe("transformJsxScriptTagsPlugin transform hook", () => {
+    function createPlugin() {
+        const clientEntryPoints = new Set();
+        const plugin = transformJsxScriptTagsPlugin({
+            clientEntryPoints,
+            projectRootDir: "/project/root/dir",
+        });
+        const configResolved = plugin.configResolved;
+        if (typeof configResolved === "function") {
+            configResolved.call({}, { command: "serve", base: "/" });
+        }
+        else {
+            configResolved?.handler.call({}, { command: "serve", base: "/" });
+        }
+        const transform = typeof plugin.transform === "function"
+            ? plugin.transform
+            : plugin.transform?.handler;
+        if (!transform) {
+            throw new Error("Expected transform hook to be defined");
+        }
+        return { clientEntryPoints, transform: transform };
+    }
+    it.each([
+        `${VIRTUAL_SSR_PREFIX}/src/Preview.tsx`,
+        `/@id/${VIRTUAL_SSR_PREFIX}/src/Preview.tsx`,
+    ])("skips virtual SSR bridge module ids in worker: %s", async (id) => {
+        // Regression for #1210: virtual SSR bridge modules have .tsx ids but are
+        // already transformed by the ssr environment, so the worker transform must
+        // not run script-tag discovery on them again.
+        const { clientEntryPoints, transform } = createPlugin();
+        const ssrBridgeCode = `
+      import { jsx } from "react/jsx-runtime";
+      const __vite_ssr_import_0__ = await __vite_ssr_import__("react/jsx-runtime", { importedNames: ["jsx"] });
+      export function Preview() {
+        return jsx("script", { async: true, src: "https://example.com/a.js" });
+      }
+    `;
+        const result = await transform.call({ environment: { name: "worker" } }, ssrBridgeCode, id);
+        expect(result).toBeNull();
+        expect(clientEntryPoints.size).toBe(0);
+    });
+    it("still transforms non-bridge worker .tsx modules", async () => {
+        const { transform } = createPlugin();
+        const code = `
+      import { jsx } from "react/jsx-runtime";
+      export function Preview() {
+        return jsx("script", { async: true, src: "https://example.com/a.js" });
+      }
+    `;
+        const result = await transform.call({ environment: { name: "worker" } }, code, "/src/Preview.tsx");
+        expect(result).toBeTruthy();
+        expect(typeof result === "object" && result !== null && "code" in result
+            ? result.code
+            : "").toContain("nonce: requestInfo.rw.nonce");
+    });
+});

package/dist/vite/transformJsxScriptTagsPlugin.mjs

@@ -2,6 +2,7 @@ import debug from "debug";
 import { Node, Project, SyntaxKind, } from "ts-morph";
 import { normalizeModulePath } from "../lib/normalizeModulePath.mjs";
 import { stripBase } from "../lib/stripBase.mjs";
+import { isVirtualSsrModuleId } from "./ssrVirtualModule.mjs";
 const log = debug("rwsdk:vite:transform-jsx-script-tags");
 function transformAssetPath(importPath, projectRootDir, base) {
     if (process.env.VITE_IS_DEV_SERVER === "1") {
@@ -336,6 +337,10 @@ export const transformJsxScriptTagsPlugin = ({ clientEntryPoints, projectRootDir
                 return null;
             }
             if (this.environment?.name === "worker" &&
+                // context(peterp, 29 May 2026): SSR bridge modules are already
+                // transformed by the `ssr` environment; rerunning script-tag discovery
+                // in the worker injects duplicate imports into virtual SSR modules.
+                !isVirtualSsrModuleId(id) &&
                 id.endsWith(".tsx") &&
                 hasJsxFunctions(code)) {
                 log("Transforming JSX script tags in %s", id);

package/dist/vite/transformServerFunctions.mjs

@@ -94,10 +94,8 @@ export const transformServerFunctions = (code, normalizedId, environment, server
         process.env.VERBOSE &&
             log(`Transforming for ${environment} environment: normalizedId=%s`, normalizedId);
         const exportInfo = findExportInfo(code, normalizedId);
-        const allExports = new Set([
-            ...exportInfo.localFunctions,
-            ...exportInfo.reExports.map((r) => r.localName),
-        ]);
+        const reExportNames = new Set(exportInfo.reExports.map((r) => r.localName));
+        const allExports = new Set(Array.from(exportInfo.localFunctions).filter((name) => !reExportNames.has(name)));
         // Check for default function exports that should also be named exports
         const defaultFunctionName = findDefaultFunctionName(code, normalizedId);
         if (defaultFunctionName) {
@@ -105,11 +103,26 @@ export const transformServerFunctions = (code, normalizedId, environment, server
         }
         // Generate completely new code for SSR
         const s = new MagicString("");
-        if (environment === "ssr") {
-            s.append('import { createServerReference } from "rwsdk/__ssr";\n\n');
+        const hasDefExport = hasDefaultExport(code, normalizedId);
+        if (allExports.size > 0 || hasDefExport) {
+            if (environment === "ssr") {
+                s.append('import { createServerReference } from "rwsdk/__ssr";\n\n');
+            }
+            else {
+                s.append('import { createServerReference } from "rwsdk/client";\n\n');
+            }
         }
-        else {
-            s.append('import { createServerReference } from "rwsdk/client";\n\n');
+        for (const reExport of exportInfo.reExports) {
+            const reExportStatement = reExport.originalName === "default"
+                ? `export { default as ${reExport.localName} } from ${JSON.stringify(reExport.moduleSpecifier)};\n`
+                : reExport.originalName === reExport.localName
+                    ? `export { ${reExport.originalName} } from ${JSON.stringify(reExport.moduleSpecifier)};\n`
+                    : `export { ${reExport.originalName} as ${reExport.localName} } from ${JSON.stringify(reExport.moduleSpecifier)};\n`;
+            s.append(reExportStatement);
+            log(`Preserved ${environment} re-export for function: %s (original: %s) from %s in normalizedId=%s`, reExport.localName, reExport.originalName, reExport.moduleSpecifier, normalizedId);
+        }
+        if (exportInfo.reExports.length > 0 && allExports.size > 0) {
+            s.append("\n");
         }
         const ext = path.extname(normalizedId).toLowerCase();
         const lang = ext === ".tsx" || ext === ".jsx" ? Lang.Tsx : SgLang.TypeScript;
@@ -151,7 +164,7 @@ export const transformServerFunctions = (code, normalizedId, environment, server
             }
         }
         // Check for default export in the actual module (not re-exports)
-        if (hasDefaultExport(code, normalizedId)) {
+        if (hasDefExport) {
             let method;
             let source = "action";
             const patterns = [

package/dist/vite/transformServerFunctions.test.mjs

@@ -169,6 +169,17 @@ export const getProject = serverQuery([
         SERVER_QUERY_ARRAY_POST_CODE,
     };
     describe("TRANSFORMS", () => {
+        it("preserves client re-exports so serverQuery metadata comes from the defining module", () => {
+            const barrelResult = transformServerFunctions(`
+"use server";
+
+export { getProject } from "./queries";
+`, "/actions.ts", "client", new Set());
+            expect(barrelResult?.code).toContain(`export { getProject } from "./queries";`);
+            expect(barrelResult?.code).not.toContain(`createServerReference("/actions.ts", "getProject")`);
+            const queryResult = transformServerFunctions(SERVER_QUERY_GET_CODE, "/queries.ts", "client", new Set());
+            expect(queryResult?.code).toContain(`createServerReference("/queries.ts", "getProject", "GET", "query")`);
+        });
         for (const [key, CODE] of Object.entries(TEST_CASES)) {
             describe(key, () => {
                 it(`CLIENT`, () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rwsdk",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "description": "Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime",
   "type": "module",
   "bin": {