rwsdk 1.3.3 → 1.4.0

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

@@ -3,9 +3,12 @@ export { default as React } from "react";
 export type { Dispatch, MutableRefObject, SetStateAction } from "react";
 export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
-export type { ActionResponseData } from "./types";
+export { NavigationPending, useNavigationPending, } from "./navigationPending.js";
+export type { NavigationPendingOptions, NavigationPendingProps, NavigationPendingWatch, NavigationPendingWhenArgs, NavigationSearchParamsWatch, } from "./navigationPending.js";
+export type { NavigationSnapshot, PendingNavigationSnapshot, } from "./navigationState.js";
+export type { ActionResponseData, RscPayloadMeta } from "./types";
 import { type RecoveryOptions } from "./recovery.js";
-import type { ActionResponseData, HydrationOptions, Transport } from "./types";
+import type { ActionResponseData, HydrationOptions, RscPayloadMeta, Transport } from "./types";
 export declare const fetchTransport: Transport;
 /**
  * Initializes the React client and hydrates the RSC payload.
@@ -65,6 +68,6 @@ export declare const initClient: ({ transport, hydrateRootOptions, handleRespons
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;
     handleResponse?: (response: Response) => boolean;
-    onHydrated?: () => void;
+    onHydrated?: (meta?: RscPayloadMeta) => void;
     onActionResponse?: (actionResponse: ActionResponseData) => boolean | void;
 } & RecoveryOptions) => Promise<void>;

package/dist/runtime/client/client.js

@@ -1,4 +1,4 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 // note(justinvdm, 14 Aug 2025): Rendering related imports and logic go here.
 // See client.tsx for the actual client entrypoint.
 // context(justinvdm, 14 Aug 2025): `react-server-dom-webpack` uses this global
@@ -13,12 +13,16 @@ import { rscStream } from "rsc-html-stream/client";
 export { default as React } from "react";
 export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
+export { NavigationPending, useNavigationPending, } from "./navigationPending.js";
 import { getCachedNavigationResponse } from "./navigationCache.js";
+import { NavigationPayloadProvider } from "./navigationPending.js";
+import { abortPendingNavigation, isPendingNavigationCommit, isSameNavigationDocumentUrl, } from "./navigationState.js";
 import { configureRecovery } from "./recovery.js";
 import { isActionResponse } from "./types";
 export const fetchTransport = (transportContext) => {
     const fetchCallServer = async (id, args, source = "action", method = "POST") => {
-        const url = new URL(window.location.href);
+        const pageUrl = new URL(window.location.href);
+        const url = new URL(pageUrl.href);
         url.searchParams.set("__rsc", "");
         const isAction = id != null;
         if (isAction) {
@@ -65,6 +69,16 @@ export const fetchTransport = (transportContext) => {
                 });
             }
         }
+        const discardStaleNavigationResponse = () => {
+            if (source !== "navigation" ||
+                isSameNavigationDocumentUrl(pageUrl, window.location.href)) {
+                return false;
+            }
+            if (isPendingNavigationCommit(pageUrl)) {
+                abortPendingNavigation();
+            }
+            return true;
+        };
         const processActionResponse = (rawActionResult) => {
             if (isActionResponse(rawActionResult)) {
                 const actionResponse = rawActionResult.__rw_action_response;
@@ -87,6 +101,9 @@ export const fetchTransport = (transportContext) => {
         // If there's a response handler, check the response first
         if (transportContext.handleResponse) {
             const response = await fetchPromise;
+            if (discardStaleNavigationResponse()) {
+                return undefined;
+            }
             const shouldContinue = transportContext.handleResponse(response);
             if (!shouldContinue) {
                 return undefined;
@@ -96,13 +113,22 @@ export const fetchTransport = (transportContext) => {
                 callServer: fetchCallServer,
             });
             if (source === "navigation" || source === "action") {
-                transportContext.setRscPayload(streamData);
+                if (discardStaleNavigationResponse()) {
+                    return undefined;
+                }
+                transportContext.setRscPayload(streamData, {
+                    source,
+                    href: pageUrl.href,
+                });
             }
             const result = await streamData;
             return processActionResponse(result.actionResult);
         }
         // Original behavior when no handler is present
         const response = await fetchPromise;
+        if (discardStaleNavigationResponse()) {
+            return undefined;
+        }
         const location = response.headers.get("Location");
         if (response.status >= 300 && response.status < 400 && location) {
             window.location.href = location;
@@ -112,7 +138,13 @@ export const fetchTransport = (transportContext) => {
             callServer: fetchCallServer,
         });
         if (source === "navigation" || source === "action") {
-            transportContext.setRscPayload(streamData);
+            if (discardStaleNavigationResponse()) {
+                return undefined;
+            }
+            transportContext.setRscPayload(streamData, {
+                source,
+                href: pageUrl.href,
+            });
         }
         const result = await streamData;
         return processActionResponse(result.actionResult);
@@ -210,18 +242,23 @@ export const initClient = async ({ transport = fetchTransport, hydrateRootOption
         });
     }
     function Content() {
-        const [streamData, setStreamData] = React.useState(rscPayload);
+        const [streamState, setStreamState] = React.useState(rscPayload
+            ? {
+                data: rscPayload,
+                meta: { source: "initial", href: window.location.href },
+            }
+            : null);
         const [_isPending, startTransition] = React.useTransition();
-        transportContext.setRscPayload = (v) => startTransition(() => {
-            setStreamData(v);
+        transportContext.setRscPayload = (v, meta) => startTransition(() => {
+            setStreamState({ data: v, meta });
         });
         React.useEffect(() => {
-            if (!streamData)
+            if (!streamState)
                 return;
-            transportContext.onHydrated?.();
-        }, [streamData]);
-        return (_jsx(_Fragment, { children: streamData
-                ? React.use(streamData).node
+            transportContext.onHydrated?.(streamState.meta);
+        }, [streamState]);
+        return (_jsx(NavigationPayloadProvider, { meta: streamState?.meta, children: streamState
+                ? React.use(streamState.data).node
                 : null }));
     }
     hydrateRoot(rootEl, _jsx(Content, {}), {

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

@@ -1,4 +1,5 @@
 import { type NavigationCache, type NavigationCacheStorage } from "./navigationCache.js";
+import type { RscPayloadMeta } from "./types.js";
 export type { NavigationCache, NavigationCacheStorage };
 export interface ClientNavigationOptions {
     onNavigate?: () => Promise<void> | void;
@@ -20,7 +21,7 @@ export declare function navigate(href: string, options?: NavigateOptions): Promi
  * Initializes client-side navigation for Single Page App (SPA) behavior.
  *
  * Intercepts clicks on internal links and fetches page content without full-page reloads.
- * Returns a handleResponse function to pass to initClient.
+ * Returns handleResponse and onHydrated functions to pass to initClient.
  *
  * @param opts.scrollToTop - Scroll to top after navigation (default: true)
  * @param opts.scrollBehavior - How to scroll: 'instant', 'smooth', or 'auto' (default: 'instant')
@@ -35,29 +36,29 @@ export declare function navigate(href: string, options?: NavigateOptions): Promi
  *
  * @example
  * // With custom scroll behavior
- * const { handleResponse } = initClientNavigation({
+ * const { handleResponse, onHydrated } = initClientNavigation({
  *   scrollBehavior: "smooth",
  *   scrollToTop: true,
  * });
- * initClient({ handleResponse });
+ * initClient({ handleResponse, onHydrated });
  *
  * @example
  * // Preserve scroll position (e.g., for infinite scroll)
- * const { handleResponse } = initClientNavigation({
+ * const { handleResponse, onHydrated } = initClientNavigation({
  *   scrollToTop: false,
  * });
- * initClient({ handleResponse });
+ * initClient({ handleResponse, onHydrated });
  *
  * @example
  * // With navigation callback
- * const { handleResponse } = initClientNavigation({
+ * const { handleResponse, onHydrated } = initClientNavigation({
  *   onNavigate: () => {
  *     console.log("Navigating to:", window.location.href);
  *   },
  * });
- * initClient({ handleResponse });
+ * initClient({ handleResponse, onHydrated });
  */
 export declare function initClientNavigation(opts?: ClientNavigationOptions): {
     handleResponse: (response: Response) => boolean;
-    onHydrated: () => void;
+    onHydrated: (meta?: RscPayloadMeta) => void;
 };

package/dist/runtime/client/navigation.js

@@ -1,4 +1,5 @@
 import { onNavigationCommit, preloadFromLinkTags, } from "./navigationCache.js";
+import { abortPendingNavigation, beginPendingNavigation, commitPendingNavigation, isPendingNavigationCommit, } from "./navigationState.js";
 import { createScrollRestoration, } from "./scrollRestoration.js";
 export function validateClickEvent(event, target) {
     // should this only work for left click?
@@ -69,14 +70,21 @@ export async function navigate(href, options = { history: "push" }) {
     else {
         scrollRestoration?.recordCurrentPosition(window.scrollX, window.scrollY);
     }
-    await options.onNavigate?.();
-    await globalThis.__rsc_callServer(null, null, "navigation");
+    const pendingNavigation = beginPendingNavigation(url);
+    try {
+        await options.onNavigate?.();
+        await globalThis.__rsc_callServer(null, null, "navigation");
+    }
+    catch (error) {
+        abortPendingNavigation(pendingNavigation.id);
+        throw error;
+    }
 }
 /**
  * Initializes client-side navigation for Single Page App (SPA) behavior.
  *
  * Intercepts clicks on internal links and fetches page content without full-page reloads.
- * Returns a handleResponse function to pass to initClient.
+ * Returns handleResponse and onHydrated functions to pass to initClient.
  *
  * @param opts.scrollToTop - Scroll to top after navigation (default: true)
  * @param opts.scrollBehavior - How to scroll: 'instant', 'smooth', or 'auto' (default: 'instant')
@@ -91,27 +99,27 @@ export async function navigate(href, options = { history: "push" }) {
  *
  * @example
  * // With custom scroll behavior
- * const { handleResponse } = initClientNavigation({
+ * const { handleResponse, onHydrated } = initClientNavigation({
  *   scrollBehavior: "smooth",
  *   scrollToTop: true,
  * });
- * initClient({ handleResponse });
+ * initClient({ handleResponse, onHydrated });
  *
  * @example
  * // Preserve scroll position (e.g., for infinite scroll)
- * const { handleResponse } = initClientNavigation({
+ * const { handleResponse, onHydrated } = initClientNavigation({
  *   scrollToTop: false,
  * });
- * initClient({ handleResponse });
+ * initClient({ handleResponse, onHydrated });
  *
  * @example
  * // With navigation callback
- * const { handleResponse } = initClientNavigation({
+ * const { handleResponse, onHydrated } = initClientNavigation({
  *   onNavigate: () => {
  *     console.log("Navigating to:", window.location.href);
  *   },
  * });
- * initClient({ handleResponse });
+ * initClient({ handleResponse, onHydrated });
  */
 export function initClientNavigation(opts = {}) {
     IS_CLIENT_NAVIGATION = true;
@@ -136,8 +144,15 @@ export function initClientNavigation(opts = {}) {
             return;
         }
         scrollRestoration?.restorePopStateScroll();
-        await opts.onNavigate?.();
-        await globalThis.__rsc_callServer(null, null, "navigation");
+        const pendingNavigation = beginPendingNavigation(window.location.href);
+        try {
+            await opts.onNavigate?.();
+            await globalThis.__rsc_callServer(null, null, "navigation");
+        }
+        catch (error) {
+            abortPendingNavigation(pendingNavigation.id);
+            throw error;
+        }
     });
     // 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
@@ -166,6 +181,7 @@ export function initClientNavigation(opts = {}) {
         if (response.status >= 300 && response.status < 400) {
             const location = response.headers.get("Location");
             if (location) {
+                abortPendingNavigation();
                 window.location.href = location;
                 return false;
             }
@@ -173,6 +189,7 @@ export function initClientNavigation(opts = {}) {
         if (!response.ok) {
             // Redirect to the current page (window.location) to show the error
             // This means the page that produced the error is called twice.
+            abortPendingNavigation();
             window.location.href = window.location.href;
             return false;
         }
@@ -182,11 +199,21 @@ export function initClientNavigation(opts = {}) {
     if (opts.cacheStorage && typeof globalThis !== "undefined") {
         globalThis.__rsc_cacheStorage = opts.cacheStorage;
     }
-    function onHydrated() {
-        // 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.
-        scrollRestoration?.applyPendingScroll();
+    function onHydrated(meta) {
+        // Apply any pending scroll intent once the relevant DOM has committed. For
+        // navigation payloads, ignore stale/superseded commits whose href no longer
+        // matches the pending navigation target.
+        const shouldCommitPendingNavigation = !meta || meta.source === "navigation";
+        const isMatchingNavigationCommit = shouldCommitPendingNavigation && isPendingNavigationCommit(meta?.href);
+        if (!meta || meta.source === "initial" || isMatchingNavigationCommit) {
+            scrollRestoration?.applyPendingScroll();
+        }
+        // Resolve NavigationPending boundaries only for navigation payloads. If a
+        // custom transport does not provide metadata, fall back to the historical
+        // onHydrated behavior and treat the commit as the pending navigation.
+        if (isMatchingNavigationCommit) {
+            commitPendingNavigation(meta?.href);
+        }
         // 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,6 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { initClientNavigation, validateClickEvent } from "./navigation";
+import { getNavigationSnapshot, resetNavigationStateForTests, } from "./navigationState";
 import { HISTORY_STATE_SCROLL_KEY } from "./scrollRestoration";
+beforeEach(() => {
+    resetNavigationStateForTests();
+});
 // Mocking browser globals
 vi.stubGlobal("window", {
     location: { href: "http://localhost/" },
@@ -130,11 +134,6 @@ describe("onNavigate callback (issue #1123 regression)", () => {
             replaceState: vi.fn(),
             state: {},
         });
-        vi.stubGlobal("URL", class {
-            constructor(path, base) {
-                this.href = base.replace(/\/$/, "") + path;
-            }
-        });
         // Assign directly to globalThis without replacing it (avoids breaking Vitest internals)
         globalThis.__rsc_callServer = vi.fn().mockResolvedValue(undefined);
     });
@@ -301,6 +300,23 @@ describe("initClientNavigation", () => {
         expect(globalThis.__rsc_callServer).not.toHaveBeenCalled();
         expect(window.scrollTo).not.toHaveBeenCalled();
     });
+    it("keeps navigation pending until the matching navigation payload hydrates", async () => {
+        globalThis.__rsc_callServer = vi.fn().mockResolvedValue(undefined);
+        const { onHydrated } = initClientNavigation();
+        expect(capturedPopstateHandler).not.toBeNull();
+        window.location.href =
+            "http://localhost/about";
+        window.location.pathname = "/about";
+        await capturedPopstateHandler();
+        const pending = getNavigationSnapshot().pending;
+        expect(pending?.pendingUrl.href).toBe("http://localhost/about");
+        onHydrated({ source: "action", href: pending.pendingUrl.href });
+        expect(getNavigationSnapshot().pending?.id).toBe(pending.id);
+        onHydrated({ source: "navigation", href: "http://localhost/other" });
+        expect(getNavigationSnapshot().pending?.id).toBe(pending.id);
+        onHydrated({ source: "navigation", href: pending.pendingUrl.href });
+        expect(getNavigationSnapshot().pending).toBeNull();
+    });
     it("does not write to history state on scroll", () => {
         initClientNavigation();
         expect(capturedScrollHandler).not.toBeNull();

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

@@ -0,0 +1,47 @@
+import React from "react";
+import { type NavigationSnapshot } from "./navigationState.js";
+import type { RscPayloadMeta } from "./types.js";
+export type NavigationSearchParamsWatch = boolean | readonly string[];
+export interface NavigationPendingWatch {
+    /** Watch pathname changes. Defaults to true when using a watch config. */
+    pathname?: boolean;
+    /** Watch all search params, no search params, or a specific list of params. */
+    searchParams?: NavigationSearchParamsWatch;
+    /** Watch hash changes. Defaults to false when using a watch config. */
+    hash?: boolean;
+}
+export interface NavigationPendingWhenArgs {
+    currentUrl: URL;
+    pendingUrl: URL;
+}
+export interface NavigationPendingOptions {
+    /** Shorthand for watching only these search params. */
+    searchParams?: readonly string[];
+    /** Explicit URL parts to watch. */
+    watch?: NavigationPendingWatch;
+    /** Advanced predicate for deciding whether the pending navigation is relevant. */
+    when?: (args: NavigationPendingWhenArgs) => boolean;
+}
+export interface NavigationPendingProps extends NavigationPendingOptions {
+    children?: React.ReactNode;
+}
+export declare function NavigationPayloadProvider({ children, meta, }: {
+    children?: React.ReactNode;
+    meta?: RscPayloadMeta;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function shouldSuspendForPendingNavigation(snapshot: NavigationSnapshot, options?: NavigationPendingOptions): boolean;
+/**
+ * Suspends while a matching client-side RSC navigation is pending.
+ *
+ * Use this hook inside a React <Suspense> boundary. When the pending navigation
+ * commits to the visible React tree, the thrown promise resolves and React
+ * retries the render with the newly committed tree.
+ */
+export declare function useNavigationPending(options?: NavigationPendingOptions): NavigationSnapshot;
+/**
+ * Suspense-aware boundary for client-side RSC navigations.
+ *
+ * Wrap server-backed UI with this component inside your own <Suspense> fallback
+ * to avoid showing stale props while a relevant navigation is in flight.
+ */
+export declare function NavigationPending({ children, searchParams, watch, when, }: NavigationPendingProps): import("react/jsx-runtime").JSX.Element;

package/dist/runtime/client/navigationPending.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { useContext, useSyncExternalStore } from "react";
+import { getNavigationSnapshot, isSameNavigationDocumentUrl, subscribeNavigationState, } from "./navigationState.js";
+const NO_NAVIGATION_PAYLOAD_META = Symbol("NO_NAVIGATION_PAYLOAD_META");
+const NavigationPayloadMetaContext = React.createContext(NO_NAVIGATION_PAYLOAD_META);
+export function NavigationPayloadProvider({ children, meta, }) {
+    return (_jsx(NavigationPayloadMetaContext.Provider, { value: meta, children: children }));
+}
+function cloneUrl(url) {
+    return new URL(url.href);
+}
+function arraysEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function searchParamChanged(currentUrl, pendingUrl, name) {
+    return !arraysEqual(currentUrl.searchParams.getAll(name), pendingUrl.searchParams.getAll(name));
+}
+function searchParamsChanged(currentUrl, pendingUrl, watch) {
+    if (watch === false) {
+        return false;
+    }
+    if (watch === true) {
+        return currentUrl.search !== pendingUrl.search;
+    }
+    return watch.some((name) => searchParamChanged(currentUrl, pendingUrl, name));
+}
+function watchedUrlChanged(currentUrl, pendingUrl, watch) {
+    const watchPathname = watch.pathname ?? true;
+    const watchSearchParams = watch.searchParams ?? true;
+    const watchHash = watch.hash ?? false;
+    if (watchPathname && currentUrl.pathname !== pendingUrl.pathname) {
+        return true;
+    }
+    if (searchParamsChanged(currentUrl, pendingUrl, watchSearchParams)) {
+        return true;
+    }
+    if (watchHash && currentUrl.hash !== pendingUrl.hash) {
+        return true;
+    }
+    return false;
+}
+function isRenderingMatchingNavigationPayload(snapshot, meta) {
+    const pending = snapshot.pending;
+    if (!pending) {
+        return false;
+    }
+    if (meta === NO_NAVIGATION_PAYLOAD_META) {
+        return false;
+    }
+    if (meta === undefined) {
+        return true;
+    }
+    if (meta.source !== "navigation") {
+        return false;
+    }
+    if (!meta.href) {
+        return true;
+    }
+    try {
+        return isSameNavigationDocumentUrl(new URL(meta.href, pending.currentUrl), pending.pendingUrl);
+    }
+    catch {
+        return false;
+    }
+}
+export function shouldSuspendForPendingNavigation(snapshot, options = {}) {
+    const pending = snapshot.pending;
+    if (!pending) {
+        return false;
+    }
+    const currentUrl = pending.currentUrl;
+    const pendingUrl = pending.pendingUrl;
+    if (options.when) {
+        return options.when({
+            currentUrl: cloneUrl(currentUrl),
+            pendingUrl: cloneUrl(pendingUrl),
+        });
+    }
+    if (options.watch) {
+        return watchedUrlChanged(currentUrl, pendingUrl, options.watch);
+    }
+    if (options.searchParams) {
+        return searchParamsChanged(currentUrl, pendingUrl, options.searchParams);
+    }
+    return true;
+}
+/**
+ * Suspends while a matching client-side RSC navigation is pending.
+ *
+ * Use this hook inside a React <Suspense> boundary. When the pending navigation
+ * commits to the visible React tree, the thrown promise resolves and React
+ * retries the render with the newly committed tree.
+ */
+export function useNavigationPending(options = {}) {
+    const snapshot = useSyncExternalStore(subscribeNavigationState, getNavigationSnapshot, getNavigationSnapshot);
+    const payloadMeta = useContext(NavigationPayloadMetaContext);
+    if (shouldSuspendForPendingNavigation(snapshot, options) &&
+        !isRenderingMatchingNavigationPayload(snapshot, payloadMeta)) {
+        throw snapshot.pending.promise;
+    }
+    return snapshot;
+}
+/**
+ * Suspense-aware boundary for client-side RSC navigations.
+ *
+ * Wrap server-backed UI with this component inside your own <Suspense> fallback
+ * to avoid showing stale props while a relevant navigation is in flight.
+ */
+export function NavigationPending({ children, searchParams, watch, when, }) {
+    useNavigationPending({ searchParams, watch, when });
+    return _jsx(_Fragment, { children: children });
+}

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

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

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

@@ -0,0 +1,122 @@
+import React, { Suspense } from "react";
+import { renderToString } from "react-dom/server";
+import { beforeEach, describe, expect, it } from "vitest";
+import { NavigationPayloadProvider, NavigationPending, shouldSuspendForPendingNavigation, } from "./navigationPending";
+import { abortPendingNavigation, beginPendingNavigation, commitPendingNavigation, getNavigationSnapshot, isSameNavigationDocumentUrl, resetNavigationStateForTests, } from "./navigationState";
+function renderPendingBoundary(meta) {
+    return renderToString(React.createElement(NavigationPayloadProvider, { meta }, React.createElement(Suspense, { fallback: React.createElement("span", null, "loading") }, React.createElement(NavigationPending, null, React.createElement("span", null, "ready")))));
+}
+async function expectPromiseResolved(promise) {
+    let resolved = false;
+    promise.then(() => {
+        resolved = true;
+    });
+    await Promise.resolve();
+    expect(resolved).toBe(true);
+}
+describe("navigation pending state", () => {
+    beforeEach(() => {
+        resetNavigationStateForTests("http://localhost/results?search=old&page=1");
+    });
+    it("tracks a pending navigation until the matching navigation commit", async () => {
+        const pending = beginPendingNavigation("http://localhost/results?search=new&page=1");
+        expect(getNavigationSnapshot().pending?.id).toBe(pending.id);
+        expect(getNavigationSnapshot().pending?.currentUrl.href).toBe("http://localhost/results?search=old&page=1");
+        expect(getNavigationSnapshot().pending?.pendingUrl.href).toBe("http://localhost/results?search=new&page=1");
+        expect(commitPendingNavigation("http://localhost/results?search=old&page=1")).toBe(false);
+        expect(getNavigationSnapshot().pending?.id).toBe(pending.id);
+        expect(commitPendingNavigation("http://localhost/results?search=new&page=1")).toBe(true);
+        expect(getNavigationSnapshot().pending).toBeNull();
+        expect(getNavigationSnapshot().currentUrl.href).toBe("http://localhost/results?search=new&page=1");
+        await expectPromiseResolved(pending.promise);
+    });
+    it("resolves a superseded navigation promise while keeping the newest navigation pending", async () => {
+        const first = beginPendingNavigation("/results?search=first&page=1");
+        const second = beginPendingNavigation("/results?search=second&page=1");
+        expect(getNavigationSnapshot().pending?.id).toBe(second.id);
+        await expectPromiseResolved(first.promise);
+        expect(getNavigationSnapshot().pending?.id).toBe(second.id);
+    });
+    it("treats hash-only differences as the same navigation document", async () => {
+        const pending = beginPendingNavigation("/results?search=new&page=1");
+        expect(isSameNavigationDocumentUrl("http://localhost/results?search=new&page=1", "http://localhost/results?search=new&page=1#details")).toBe(true);
+        expect(isSameNavigationDocumentUrl("http://localhost/results?search=new&page=1", "http://localhost/results?search=new&page=2#details")).toBe(false);
+        expect(commitPendingNavigation("/results?search=new&page=1#details")).toBe(true);
+        expect(getNavigationSnapshot().pending).toBeNull();
+        await expectPromiseResolved(pending.promise);
+    });
+    it("can abort only the matching pending navigation", async () => {
+        const pending = beginPendingNavigation("/results?search=new&page=1");
+        expect(abortPendingNavigation(pending.id + 1)).toBe(false);
+        expect(getNavigationSnapshot().pending?.id).toBe(pending.id);
+        expect(abortPendingNavigation(pending.id)).toBe(true);
+        expect(getNavigationSnapshot().pending).toBeNull();
+        await expectPromiseResolved(pending.promise);
+    });
+});
+describe("shouldSuspendForPendingNavigation", () => {
+    beforeEach(() => {
+        resetNavigationStateForTests("http://localhost/results?search=old&page=1");
+    });
+    it("suspends for any pending navigation by default", () => {
+        beginPendingNavigation("/results?search=new&page=1");
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot())).toBe(true);
+    });
+    it("can watch a shorthand list of search params", () => {
+        beginPendingNavigation("/results?search=new&page=1&sort=asc");
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            searchParams: ["search"],
+        })).toBe(true);
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            searchParams: ["page"],
+        })).toBe(false);
+    });
+    it("does not let the searchParams shorthand suspend for pathname-only changes", () => {
+        beginPendingNavigation("/other?search=old&page=1");
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            searchParams: ["search", "page"],
+        })).toBe(false);
+    });
+    it("supports explicit watch configuration", () => {
+        beginPendingNavigation("/other?search=old&page=2#details");
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            watch: { pathname: false, searchParams: ["page"], hash: false },
+        })).toBe(true);
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            watch: { pathname: false, searchParams: ["search"], hash: false },
+        })).toBe(false);
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            watch: { pathname: false, searchParams: false, hash: true },
+        })).toBe(true);
+    });
+    it("supports a custom predicate", () => {
+        beginPendingNavigation("/results?tab=details&page=1");
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            when: ({ currentUrl, pendingUrl }) => currentUrl.searchParams.get("tab") !==
+                pendingUrl.searchParams.get("tab"),
+        })).toBe(true);
+        expect(shouldSuspendForPendingNavigation(getNavigationSnapshot(), {
+            when: ({ currentUrl, pendingUrl }) => currentUrl.searchParams.get("page") !==
+                pendingUrl.searchParams.get("page"),
+        })).toBe(false);
+    });
+    it("keeps current payloads suspended but lets the matching navigation payload render", () => {
+        beginPendingNavigation("/results?search=new&page=1");
+        expect(renderPendingBoundary({
+            source: "initial",
+            href: "http://localhost/results?search=old&page=1",
+        })).toContain("loading");
+        expect(renderPendingBoundary({
+            source: "navigation",
+            href: "http://localhost/results?search=other&page=1",
+        })).toContain("loading");
+        expect(renderPendingBoundary({
+            source: "navigation",
+            href: "http://localhost/results?search=new&page=1",
+        })).toContain("ready");
+        expect(renderPendingBoundary({
+            source: "navigation",
+            href: "http://localhost/results?search=new&page=1#details",
+        })).toContain("ready");
+    });
+});

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

@@ -0,0 +1,28 @@
+export interface NavigationSnapshot {
+    /** URL represented by the React tree that has committed to the screen. */
+    currentUrl: URL;
+    /** The latest client navigation that has updated history but not committed. */
+    pending: PendingNavigationSnapshot | null;
+}
+export interface PendingNavigationSnapshot {
+    id: number;
+    /** URL represented by the currently visible React tree when navigation began. */
+    currentUrl: URL;
+    /** URL that the pending RSC navigation is rendering. */
+    pendingUrl: URL;
+    /** Resolves when this pending navigation commits, is superseded, or is aborted. */
+    promise: Promise<void>;
+}
+interface PendingNavigationInternal extends PendingNavigationSnapshot {
+    resolve: () => void;
+}
+type NavigationListener = () => void;
+export declare function isSameNavigationDocumentUrl(left: string | URL, right: string | URL): boolean;
+export declare function subscribeNavigationState(listener: NavigationListener): () => void;
+export declare function getNavigationSnapshot(): NavigationSnapshot;
+export declare function beginPendingNavigation(url: string | URL): PendingNavigationInternal;
+export declare function isPendingNavigationCommit(href?: string | URL): boolean;
+export declare function commitPendingNavigation(href?: string | URL): boolean;
+export declare function abortPendingNavigation(id?: number): boolean;
+export declare function resetNavigationStateForTests(href?: string): void;
+export {};

package/dist/runtime/client/navigationState.js

@@ -0,0 +1,124 @@
+const listeners = new Set();
+let nextNavigationId = 0;
+let currentUrl = readWindowUrl();
+let pendingNavigation = null;
+let snapshot = createSnapshot();
+function readWindowUrl() {
+    if (typeof window !== "undefined" && window.location?.href) {
+        return new URL(window.location.href);
+    }
+    return new URL("http://localhost/");
+}
+function cloneUrl(url) {
+    return new URL(url.href);
+}
+function createSnapshot() {
+    return {
+        currentUrl: cloneUrl(currentUrl),
+        pending: pendingNavigation
+            ? {
+                id: pendingNavigation.id,
+                currentUrl: cloneUrl(pendingNavigation.currentUrl),
+                pendingUrl: cloneUrl(pendingNavigation.pendingUrl),
+                promise: pendingNavigation.promise,
+            }
+            : null,
+    };
+}
+function updateSnapshot() {
+    snapshot = createSnapshot();
+}
+function notifyListeners() {
+    for (const listener of listeners) {
+        listener();
+    }
+}
+function toUrl(url) {
+    if (url instanceof URL) {
+        return cloneUrl(url);
+    }
+    return new URL(url, readWindowUrl());
+}
+function toNavigationDocumentHref(url) {
+    const nextUrl = toUrl(url);
+    nextUrl.hash = "";
+    return nextUrl.href;
+}
+export function isSameNavigationDocumentUrl(left, right) {
+    return toNavigationDocumentHref(left) === toNavigationDocumentHref(right);
+}
+function createDeferred() {
+    let resolve;
+    const promise = new Promise((resolvePromise) => {
+        resolve = resolvePromise;
+    });
+    return { promise, resolve };
+}
+export function subscribeNavigationState(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function getNavigationSnapshot() {
+    return snapshot;
+}
+export function beginPendingNavigation(url) {
+    const supersededNavigation = pendingNavigation;
+    const targetUrl = toUrl(url);
+    const { promise, resolve } = createDeferred();
+    pendingNavigation = {
+        id: ++nextNavigationId,
+        currentUrl: cloneUrl(currentUrl),
+        pendingUrl: targetUrl,
+        promise,
+        resolve,
+    };
+    updateSnapshot();
+    notifyListeners();
+    supersededNavigation?.resolve();
+    return pendingNavigation;
+}
+export function isPendingNavigationCommit(href) {
+    if (!pendingNavigation) {
+        return false;
+    }
+    if (href === undefined) {
+        return true;
+    }
+    return isSameNavigationDocumentUrl(href, pendingNavigation.pendingUrl);
+}
+export function commitPendingNavigation(href) {
+    if (!isPendingNavigationCommit(href)) {
+        return false;
+    }
+    const committedNavigation = pendingNavigation;
+    pendingNavigation = null;
+    currentUrl = cloneUrl(committedNavigation.pendingUrl);
+    updateSnapshot();
+    notifyListeners();
+    committedNavigation.resolve();
+    return true;
+}
+export function abortPendingNavigation(id) {
+    if (!pendingNavigation) {
+        return false;
+    }
+    if (id !== undefined && pendingNavigation.id !== id) {
+        return false;
+    }
+    const abortedNavigation = pendingNavigation;
+    pendingNavigation = null;
+    updateSnapshot();
+    notifyListeners();
+    abortedNavigation.resolve();
+    return true;
+}
+export function resetNavigationStateForTests(href = "http://localhost/") {
+    pendingNavigation?.resolve();
+    pendingNavigation = null;
+    nextNavigationId = 0;
+    currentUrl = new URL(href);
+    updateSnapshot();
+    notifyListeners();
+}

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

@@ -4,6 +4,11 @@ export type RscActionResponse<Result> = {
     node: React.ReactNode;
     actionResult: Result;
 };
+export type RscPayloadMeta = {
+    source: "initial" | "action" | "navigation" | "query";
+    /** Browser URL represented by this RSC payload, without the internal __rsc marker. */
+    href?: string;
+};
 export type ActionResponseData = {
     status: number;
     headers: {
@@ -15,14 +20,14 @@ export type ActionResponseMeta = {
 };
 export declare function isActionResponse(value: unknown): value is ActionResponseMeta;
 export type TransportContext = {
-    setRscPayload: <Result>(v: Promise<RscActionResponse<Result>>) => void;
+    setRscPayload: <Result>(v: Promise<RscActionResponse<Result>>, meta?: RscPayloadMeta) => void;
     handleResponse?: (response: Response) => boolean;
     /**
      * Optional callback invoked after a new RSC payload has been committed on the client.
      * This is useful for features like client-side navigation that want to run logic
      * after hydration/updates, e.g. warming navigation caches.
      */
-    onHydrated?: () => void;
+    onHydrated?: (meta?: RscPayloadMeta) => void;
     /**
      * Optional callback invoked when an action returns a Response.
      * Return true to signal that the response has been handled and

package/dist/runtime/lib/realtime/client.js

@@ -46,7 +46,10 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
             setTimeout(setupWebSocket, 5000);
         });
         listenForUpdates(ws, (response) => {
-            processResponse(response);
+            processResponse(response, {
+                source: "action",
+                href: window.location.href,
+            });
         });
     };
     const ensureWs = () => {
@@ -58,7 +61,7 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
         }
         return ws;
     };
-    const realtimeCallServer = async (id, args, _source, _method) => {
+    const realtimeCallServer = async (id, args, source = "action", _method) => {
         try {
             const socket = ensureWs();
             const { encodeReply } = await import("react-server-dom-webpack/client.browser");
@@ -78,17 +81,24 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
             });
             const promisedResponse = respondToRequest(requestId, socket);
             socket.send(message);
-            return await processResponse(await promisedResponse);
+            return await processResponse(await promisedResponse, {
+                source,
+                href: window.location.href,
+            });
         }
         catch (e) {
             console.error("[Realtime] Error calling server", e);
             return undefined;
         }
     };
-    const processResponse = async (response) => {
+    const processResponse = async (response, meta) => {
         try {
             let streamForRsc;
             let shouldContinue = true;
+            const isStaleNavigationResponse = () => meta?.source === "navigation" && meta.href !== window.location.href;
+            if (isStaleNavigationResponse()) {
+                return undefined;
+            }
             if (transportContext.handleResponse) {
                 const [stream1, stream2] = response.body.tee();
                 const clonedResponse = new Response(stream1, response);
@@ -104,7 +114,10 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
             const rscPayload = createFromReadableStream(streamForRsc, {
                 callServer: realtimeCallServer,
             });
-            transportContext.setRscPayload(rscPayload);
+            if (isStaleNavigationResponse()) {
+                return undefined;
+            }
+            transportContext.setRscPayload(rscPayload, meta);
             const rawActionResult = (await rscPayload).actionResult;
             if (isActionResponse(rawActionResult)) {
                 const actionResponse = rawActionResult.__rw_action_response;

package/package.json

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