rwsdk 1.0.0-beta.41 → 1.0.0-beta.43

package/dist/lib/e2e/dev.mjs

@@ -2,6 +2,7 @@ import debug from "debug";
 import { setTimeout as sleep } from "node:timers/promises";
 import { $, $sh } from "../../lib/$.mjs";
 import { poll } from "./poll.mjs";
+import { IS_DEBUG_MODE } from "./constants.mjs";
 const DEV_SERVER_CHECK_TIMEOUT = process.env.RWSDK_DEV_SERVER_CHECK_TIMEOUT
     ? parseInt(process.env.RWSDK_DEV_SERVER_CHECK_TIMEOUT, 10)
     : 5 * 60 * 1000;
@@ -99,8 +100,10 @@ export async function runDevServer(packageManager = "pnpm", cwd) {
         // Listen for all output to get the URL
         const handleOutput = (data, source) => {
             const output = data.toString();
-            // Raw output for debugging
-            process.stdout.write(`[dev:${source}] ` + output);
+            // Raw output for debugging - only in debug mode
+            if (IS_DEBUG_MODE) {
+                process.stdout.write(`[dev:${source}] ` + output);
+            }
             allOutput += output; // Accumulate all output
             if (!url) {
                 // Multiple patterns to catch different package manager outputs
@@ -136,12 +139,16 @@ export async function runDevServer(packageManager = "pnpm", cwd) {
         };
         // Listen to all possible output streams
         log("Setting up stream listeners. Available streams: all=%s, stdout=%s, stderr=%s", !!devProcess.all, !!devProcess.stdout, !!devProcess.stderr);
-        devProcess.all?.on("data", (data) => handleOutput(data, "all"));
-        devProcess.stdout?.on("data", (data) => handleOutput(data, "stdout"));
-        devProcess.stderr?.on("data", (data) => handleOutput(data, "stderr"));
-        // Also try listening to the raw process output
+        if (devProcess.all) {
+            devProcess.all.on("data", (data) => handleOutput(data, "all"));
+        }
+        else {
+            devProcess.stdout?.on("data", (data) => handleOutput(data, "stdout"));
+            devProcess.stderr?.on("data", (data) => handleOutput(data, "stderr"));
+        }
+        // Also try listening to the raw process events
         if (devProcess.child) {
-            log("Setting up child process stream listeners");
+            log("Setting up child process events listeners");
             devProcess.child.on("spawn", () => {
                 log("Child process spawned successfully.");
             });
@@ -151,8 +158,6 @@ export async function runDevServer(packageManager = "pnpm", cwd) {
             devProcess.child.on("exit", (code, signal) => {
                 log("Child process exited with code %s and signal %s", code, signal);
             });
-            devProcess.child.stdout?.on("data", (data) => handleOutput(data, "child.stdout"));
-            devProcess.child.stderr?.on("data", (data) => handleOutput(data, "child.stderr"));
         }
         // Wait for URL with timeout
         const waitForUrl = async () => {
@@ -164,7 +169,6 @@ export async function runDevServer(packageManager = "pnpm", cwd) {
                 }
                 // Fallback: check accumulated output if stream listeners aren't working
                 if (!url && allOutput) {
-                    log("Checking accumulated output for URL patterns: %s", allOutput.replace(/\n/g, "\\n"));
                     const patterns = [
                         /Local:\s*(?:\u001b\[\d+m)?(https?:\/\/localhost:\d+)/i,
                         /[➜→]\s*Local:\s*(?:\u001b\[\d+m)?(https?:\/\/localhost:\d+)/i,

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

@@ -6,4 +6,5 @@ export * from "./poll.mjs";
 export * from "./release.mjs";
 export * from "./tarball.mjs";
 export * from "./testHarness.mjs";
+export { SKIP_DEPLOYMENT_TESTS, SKIP_DEV_SERVER_TESTS, } from "./testHarness.mjs";
 export * from "./types.mjs";

package/dist/lib/e2e/index.mjs

@@ -6,4 +6,5 @@ export * from "./poll.mjs";
 export * from "./release.mjs";
 export * from "./tarball.mjs";
 export * from "./testHarness.mjs";
+export { SKIP_DEPLOYMENT_TESTS, SKIP_DEV_SERVER_TESTS, } from "./testHarness.mjs";
 export * from "./types.mjs";

package/dist/lib/e2e/release.mjs

@@ -8,6 +8,7 @@ import { setTimeout } from "node:timers/promises";
 import { basename, dirname, join, resolve } from "path";
 import { $ } from "../../lib/$.mjs";
 import { extractLastJson, parseJson } from "../../lib/jsonUtils.mjs";
+import { IS_DEBUG_MODE } from "./constants.mjs";
 const log = debug("rwsdk:e2e:release");
 /**
  * Find wrangler cache by searching up the directory tree for node_modules/.cache/wrangler
@@ -68,8 +69,10 @@ export async function $expect(command, expectations, options = {
             const chunk = data.toString();
             stdout += chunk;
             buffer += chunk;
-            // Print to console
-            process.stdout.write(chunk);
+            // Print to console in debug mode
+            if (IS_DEBUG_MODE) {
+                process.stdout.write(chunk);
+            }
             // Only process expectations that haven't been fully matched yet
             // and in the order they were provided
             while (currentExpectationIndex < expectations.length) {
@@ -133,8 +136,10 @@ export async function $expect(command, expectations, options = {
             childProcess.stderr.on("data", (data) => {
                 const chunk = data.toString();
                 stderr += chunk;
-                // Also write stderr to console
-                process.stderr.write(chunk);
+                // Also write stderr to console in debug mode
+                if (IS_DEBUG_MODE) {
+                    process.stderr.write(chunk);
+                }
             });
         }
         // Handle process completion

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

@@ -15,6 +15,8 @@ interface DeploymentInstance {
     projectDir: string;
     cleanup: () => Promise<void>;
 }
+export declare const SKIP_DEV_SERVER_TESTS: boolean;
+export declare const SKIP_DEPLOYMENT_TESTS: boolean;
 export interface SetupPlaygroundEnvironmentOptions {
     /**
      * The directory of the playground project to set up.
@@ -86,6 +88,12 @@ type SDKRunner = (name: string, testLogic: (context: {
     page: Page;
     projectDir: string;
 }) => Promise<void>) => void;
+type SDKRunnerWithHelpers = SDKRunner & {
+    only: SDKRunner;
+    skip: typeof test.skip;
+    dev: SDKRunner;
+    deploy: SDKRunner;
+};
 declare function createTestRunner(testFn: (typeof test | typeof test.only)["concurrent"], envType: "dev" | "deploy"): (name: string, testLogic: (context: {
     devServer?: DevServerInstance;
     deployment?: DeploymentInstance;
@@ -94,10 +102,7 @@ declare function createTestRunner(testFn: (typeof test | typeof test.only)["conc
     url: string;
     projectDir: string;
 }) => Promise<void>) => void;
-export declare const testSDK: SDKRunner & {
-    only: SDKRunner;
-    skip: typeof test.skip;
-};
+export declare const testSDK: SDKRunnerWithHelpers;
 /**
  * High-level test wrapper for dev server tests.
  * Automatically skips if RWSDK_SKIP_DEV=1

package/dist/lib/e2e/testHarness.mjs

@@ -12,8 +12,8 @@ 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, };
 // Environment variable flags for skipping tests
-const SKIP_DEV_SERVER_TESTS = process.env.RWSDK_SKIP_DEV === "1";
-const SKIP_DEPLOYMENT_TESTS = process.env.RWSDK_SKIP_DEPLOY === "1";
+export const SKIP_DEV_SERVER_TESTS = process.env.RWSDK_SKIP_DEV === "1";
+export const SKIP_DEPLOYMENT_TESTS = process.env.RWSDK_SKIP_DEPLOY === "1";
 // Global test environment state
 let globalDevPlaygroundEnv = null;
 let globalDeployPlaygroundEnv = null;
@@ -461,9 +461,27 @@ function createSDKTestRunner() {
         };
     };
     const main = internalRunner(test);
+    // Helper method for dev-specific tests that respects SKIP_DEV_SERVER_TESTS
+    const dev = (name, testLogic) => {
+        if (SKIP_DEV_SERVER_TESTS) {
+            test.skip(`${name} (dev)`, () => { });
+            return;
+        }
+        return main(`${name} (dev)`, testLogic);
+    };
+    // Helper method for deploy-specific tests that respects SKIP_DEPLOYMENT_TESTS
+    const deploy = (name, testLogic) => {
+        if (SKIP_DEPLOYMENT_TESTS) {
+            test.skip(`${name} (deployment)`, () => { });
+            return;
+        }
+        return main(`${name} (deployment)`, testLogic);
+    };
     return Object.assign(main, {
         only: internalRunner(test.only),
         skip: test.skip,
+        dev,
+        deploy,
     });
 }
 export const testSDK = createSDKTestRunner();

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

@@ -3,7 +3,8 @@ export { default as React } from "react";
 export type { Dispatch, MutableRefObject, SetStateAction } from "react";
 export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
-import type { HydrationOptions, Transport } from "./types";
+export type { ActionResponseData } from "./types";
+import type { ActionResponseData, HydrationOptions, Transport } from "./types";
 export declare const fetchTransport: Transport;
 /**
  * Initializes the React client and hydrates the RSC payload.
@@ -12,8 +13,16 @@ export declare const fetchTransport: Transport;
  * making the page interactive. Call this from your client entry point.
  *
  * @param transport - Custom transport for server communication (defaults to fetchTransport)
- * @param hydrateRootOptions - Options passed to React's hydrateRoot
- * @param handleResponse - Custom response handler for navigation errors
+ * @param hydrateRootOptions - Options passed to React's `hydrateRoot`. Supports all React hydration options including:
+ *                             - `onUncaughtError`: Handler for uncaught errors (async errors, event handler errors).
+ *                               If not provided, defaults to logging errors to console.
+ *                             - `onCaughtError`: Handler for errors caught by error boundaries
+ *                             - `onRecoverableError`: Handler for recoverable errors
+ * @param handleResponse - Custom response handler for navigation errors (navigation GETs)
+ * @param onHydrationUpdate - Callback invoked after a new RSC payload has been committed on the client
+ * @param onActionResponse - Optional hook invoked when an action returns a Response;
+ *                           return true to signal that the response has been handled and
+ *                           default behaviour (e.g. redirects) should be skipped
  *
  * @example
  * // Basic usage
@@ -29,6 +38,23 @@ export declare const fetchTransport: Transport;
  * initClient({ handleResponse });
  *
  * @example
+ * // With error handling
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onUncaughtError: (error, errorInfo) => {
+ *       console.error("Uncaught error:", error);
+ *       // Send to monitoring service
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *     onCaughtError: (error, errorInfo) => {
+ *       console.error("Caught error:", error);
+ *       // Handle errors from error boundaries
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *   },
+ * });
+ *
+ * @example
  * // With custom React hydration options
  * initClient({
  *   hydrateRootOptions: {
@@ -38,8 +64,10 @@ export declare const fetchTransport: Transport;
  *   },
  * });
  */
-export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, }?: {
+export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, onHydrationUpdate, onActionResponse, }?: {
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;
     handleResponse?: (response: Response) => boolean;
+    onHydrationUpdate?: () => void;
+    onActionResponse?: (actionResponse: ActionResponseData) => boolean | void;
 }) => Promise<void>;

package/dist/runtime/client/client.js

@@ -13,18 +13,38 @@ import { rscStream } from "rsc-html-stream/client";
 export { default as React } from "react";
 export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
+import { getCachedNavigationResponse } from "./navigationCache.js";
+import { isActionResponse } from "./types";
 export const fetchTransport = (transportContext) => {
-    const fetchCallServer = async (id, args) => {
+    const fetchCallServer = async (id, args, source = "action") => {
         const url = new URL(window.location.href);
         url.searchParams.set("__rsc", "");
-        if (id != null) {
+        const isAction = id != null;
+        if (isAction) {
             url.searchParams.set("__rsc_action_id", id);
         }
-        const fetchPromise = fetch(url, {
-            method: "POST",
-            redirect: "manual",
-            body: args != null ? await encodeReply(args) : null,
-        });
+        let fetchPromise;
+        if (!isAction && source === "navigation") {
+            // Try to get cached response first
+            const cachedResponse = await getCachedNavigationResponse(url);
+            if (cachedResponse) {
+                fetchPromise = Promise.resolve(cachedResponse);
+            }
+            else {
+                // Fall back to network fetch on cache miss
+                fetchPromise = fetch(url, {
+                    method: "GET",
+                    redirect: "manual",
+                });
+            }
+        }
+        else {
+            fetchPromise = fetch(url, {
+                method: "POST",
+                redirect: "manual",
+                body: args != null ? await encodeReply(args) : null,
+            });
+        }
         // If there's a response handler, check the response first
         if (transportContext.handleResponse) {
             const response = await fetchPromise;
@@ -38,7 +58,21 @@ export const fetchTransport = (transportContext) => {
             });
             transportContext.setRscPayload(streamData);
             const result = await streamData;
-            return result.actionResult;
+            const rawActionResult = result.actionResult;
+            if (isActionResponse(rawActionResult)) {
+                const actionResponse = rawActionResult.__rw_action_response;
+                const handledByHook = transportContext.onActionResponse?.(actionResponse) === true;
+                if (!handledByHook) {
+                    const location = actionResponse.headers["location"];
+                    const isRedirect = actionResponse.status >= 300 && actionResponse.status < 400;
+                    if (location && isRedirect) {
+                        window.location.href = location;
+                        return undefined;
+                    }
+                }
+                return rawActionResult;
+            }
+            return rawActionResult;
         }
         // Original behavior when no handler is present
         const streamData = createFromFetch(fetchPromise, {
@@ -46,7 +80,21 @@ export const fetchTransport = (transportContext) => {
         });
         transportContext.setRscPayload(streamData);
         const result = await streamData;
-        return result.actionResult;
+        const rawActionResult = result.actionResult;
+        if (isActionResponse(rawActionResult)) {
+            const actionResponse = rawActionResult.__rw_action_response;
+            const handledByHook = transportContext.onActionResponse?.(actionResponse) === true;
+            if (!handledByHook) {
+                const location = actionResponse.headers["location"];
+                const isRedirect = actionResponse.status >= 300 && actionResponse.status < 400;
+                if (location && isRedirect) {
+                    window.location.href = location;
+                    return undefined;
+                }
+            }
+            return rawActionResult;
+        }
+        return rawActionResult;
     };
     return fetchCallServer;
 };
@@ -57,8 +105,16 @@ export const fetchTransport = (transportContext) => {
  * making the page interactive. Call this from your client entry point.
  *
  * @param transport - Custom transport for server communication (defaults to fetchTransport)
- * @param hydrateRootOptions - Options passed to React's hydrateRoot
- * @param handleResponse - Custom response handler for navigation errors
+ * @param hydrateRootOptions - Options passed to React's `hydrateRoot`. Supports all React hydration options including:
+ *                             - `onUncaughtError`: Handler for uncaught errors (async errors, event handler errors).
+ *                               If not provided, defaults to logging errors to console.
+ *                             - `onCaughtError`: Handler for errors caught by error boundaries
+ *                             - `onRecoverableError`: Handler for recoverable errors
+ * @param handleResponse - Custom response handler for navigation errors (navigation GETs)
+ * @param onHydrationUpdate - Callback invoked after a new RSC payload has been committed on the client
+ * @param onActionResponse - Optional hook invoked when an action returns a Response;
+ *                           return true to signal that the response has been handled and
+ *                           default behaviour (e.g. redirects) should be skipped
  *
  * @example
  * // Basic usage
@@ -74,6 +130,23 @@ export const fetchTransport = (transportContext) => {
  * initClient({ handleResponse });
  *
  * @example
+ * // With error handling
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onUncaughtError: (error, errorInfo) => {
+ *       console.error("Uncaught error:", error);
+ *       // Send to monitoring service
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *     onCaughtError: (error, errorInfo) => {
+ *       console.error("Caught error:", error);
+ *       // Handle errors from error boundaries
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *   },
+ * });
+ *
+ * @example
  * // With custom React hydration options
  * initClient({
  *   hydrateRootOptions: {
@@ -83,13 +156,17 @@ export const fetchTransport = (transportContext) => {
  *   },
  * });
  */
-export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, } = {}) => {
+export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, onHydrationUpdate, onActionResponse, } = {}) => {
     const transportContext = {
         setRscPayload: () => { },
         handleResponse,
+        onHydrationUpdate,
+        onActionResponse,
     };
     let transportCallServer = transport(transportContext);
-    const callServer = (id, args) => transportCallServer(id, args);
+    const callServer = (id, args, source) => {
+        return transportCallServer(id, args, source);
+    };
     const upgradeToRealtime = async ({ key } = {}) => {
         const { realtimeTransport } = await import("../lib/realtime/client");
         const createRealtimeTransport = realtimeTransport({ key });
@@ -115,7 +192,14 @@ export const initClient = async ({ transport = fetchTransport, hydrateRootOption
     function Content() {
         const [streamData, setStreamData] = React.useState(rscPayload);
         const [_isPending, startTransition] = React.useTransition();
-        transportContext.setRscPayload = (v) => startTransition(() => setStreamData(v));
+        transportContext.setRscPayload = (v) => startTransition(() => {
+            setStreamData(v);
+        });
+        React.useEffect(() => {
+            if (!streamData)
+                return;
+            transportContext.onHydrationUpdate?.();
+        }, [streamData]);
         return (_jsx(_Fragment, { children: streamData
                 ? React.use(streamData).node
                 : null }));

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

@@ -1,7 +1,10 @@
+import { type NavigationCache, type NavigationCacheStorage } from "./navigationCache.js";
+export type { NavigationCache, NavigationCacheStorage };
 export interface ClientNavigationOptions {
     onNavigate?: () => void;
     scrollToTop?: boolean;
     scrollBehavior?: "auto" | "smooth" | "instant";
+    cacheStorage?: NavigationCacheStorage;
 }
 export declare function validateClickEvent(event: MouseEvent, target: HTMLElement): boolean;
 export interface NavigateOptions {
@@ -26,8 +29,8 @@ export declare function navigate(href: string, options?: NavigateOptions): Promi
  * // Basic usage
  * import { initClient, initClientNavigation } from "rwsdk/client";
  *
- * const { handleResponse } = initClientNavigation();
- * initClient({ handleResponse });
+ * const { handleResponse, onHydrationUpdate } = initClientNavigation();
+ * initClient({ handleResponse, onHydrationUpdate });
  *
  * @example
  * // With custom scroll behavior
@@ -55,4 +58,5 @@ export declare function navigate(href: string, options?: NavigateOptions): Promi
  */
 export declare function initClientNavigation(opts?: ClientNavigationOptions): {
     handleResponse: (response: Response) => boolean;
+    onHydrationUpdate: () => void;
 };

package/dist/runtime/client/navigation.js

@@ -1,3 +1,4 @@
+import { onNavigationCommit, preloadFromLinkTags, } from "./navigationCache.js";
 export function validateClickEvent(event, target) {
     // should this only work for left click?
     if (event.button !== 0) {
@@ -44,8 +45,7 @@ export async function navigate(href, options = { history: "push" }) {
     else {
         window.history.replaceState({ path: href }, "", url);
     }
-    // @ts-expect-error
-    await globalThis.__rsc_callServer();
+    await globalThis.__rsc_callServer(null, null, "navigation");
     const scrollToTop = options.info?.scrollToTop ?? true;
     const scrollBehavior = options.info?.scrollBehavior ?? "instant";
     if (scrollToTop && history.scrollRestoration === "auto") {
@@ -78,8 +78,8 @@ function saveScrollPosition(x, y) {
  * // Basic usage
  * import { initClient, initClientNavigation } from "rwsdk/client";
  *
- * const { handleResponse } = initClientNavigation();
- * initClient({ handleResponse });
+ * const { handleResponse, onHydrationUpdate } = initClientNavigation();
+ * initClient({ handleResponse, onHydrationUpdate });
  *
  * @example
  * // With custom scroll behavior
@@ -116,22 +116,34 @@ export function initClientNavigation(opts = {}) {
         const el = event.target;
         const a = el.closest("a");
         const href = a?.getAttribute("href");
-        navigate(href);
+        await navigate(href);
     }, true);
     window.addEventListener("popstate", async function handlePopState() {
-        // @ts-expect-error
-        await globalThis.__rsc_callServer();
+        await globalThis.__rsc_callServer(null, null, "navigation");
     });
-    // Return a handleResponse function for use with initClient
+    function handleResponse(response) {
+        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.
+            window.location.href = window.location.href;
+            return false;
+        }
+        return true;
+    }
+    // Store cacheStorage globally for use in client.tsx
+    if (opts.cacheStorage && typeof globalThis !== "undefined") {
+        globalThis.__rsc_cacheStorage = opts.cacheStorage;
+    }
+    function onHydrationUpdate() {
+        // After each RSC hydration/update, increment generation and evict old caches,
+        // then warm the navigation cache based on any <link rel="prefetch"> tags
+        // rendered for the current location.
+        onNavigationCommit(undefined, opts.cacheStorage);
+        void preloadFromLinkTags(undefined, undefined, opts.cacheStorage);
+    }
+    // Return callbacks for use with initClient
     return {
-        handleResponse: function handleResponse(response) {
-            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.
-                window.location.href = window.location.href;
-                return false;
-            }
-            return true;
-        },
+        handleResponse,
+        onHydrationUpdate,
     };
 }

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

@@ -0,0 +1,68 @@
+export interface NavigationCacheEnvironment {
+    isSecureContext: boolean;
+    origin: string;
+    caches?: CacheStorage;
+    fetch: typeof fetch;
+}
+/**
+ * Interface for a single cache instance, mirroring the Cache API.
+ */
+export interface NavigationCache {
+    put(request: Request, response: Response): Promise<void>;
+    match(request: Request): Promise<Response | undefined>;
+}
+/**
+ * Interface for cache storage, mirroring the CacheStorage API.
+ */
+export interface NavigationCacheStorage {
+    open(cacheName: string): Promise<NavigationCache>;
+    delete(cacheName: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+}
+/**
+ * Creates a default NavigationCacheStorage implementation that wraps the browser's CacheStorage API.
+ * This maintains the current generation-based cache naming and eviction logic.
+ */
+export declare function createDefaultNavigationCacheStorage(env?: NavigationCacheEnvironment): NavigationCacheStorage | undefined;
+/**
+ * Preloads the RSC navigation response for a given URL into the Cache API.
+ *
+ * This issues a GET request with the `__rsc` query parameter set, and, on a
+ * successful response, stores it in a versioned Cache using `cache.put`.
+ *
+ * See MDN for Cache interface semantics:
+ * https://developer.mozilla.org/en-US/docs/Web/API/Cache
+ */
+export declare function preloadNavigationUrl(rawUrl: URL | string, env?: NavigationCacheEnvironment, cacheStorage?: NavigationCacheStorage): Promise<void>;
+/**
+ * Attempts to retrieve a cached navigation response for the given URL.
+ *
+ * Returns the cached Response if found, or undefined if not cached or if
+ * CacheStorage is unavailable.
+ */
+export declare function getCachedNavigationResponse(rawUrl: URL | string, env?: NavigationCacheEnvironment, cacheStorage?: NavigationCacheStorage): Promise<Response | undefined>;
+/**
+ * Cleans up old generation caches for the current tab.
+ *
+ * This should be called after navigation commits to evict cache entries from
+ * previous navigations. It runs asynchronously via requestIdleCallback or
+ * setTimeout to avoid blocking the critical path.
+ */
+export declare function evictOldGenerationCaches(env?: NavigationCacheEnvironment, cacheStorage?: NavigationCacheStorage): Promise<void>;
+/**
+ * Increments the generation counter and schedules cleanup of old caches.
+ *
+ * This should be called after navigation commits to mark the current generation
+ * as complete and prepare for the next navigation cycle.
+ */
+export declare function onNavigationCommit(env?: NavigationCacheEnvironment, cacheStorage?: NavigationCacheStorage): void;
+/**
+ * Scan the document for `<link rel="prefetch" href="...">` elements that point
+ * to same-origin paths and prefetch their RSC navigation responses into the
+ * Cache API.
+ *
+ * This is invoked after client navigations to warm the navigation cache in
+ * the background. We intentionally keep Cache usage write-only for now; reads
+ * still go through the normal fetch path.
+ */
+export declare function preloadFromLinkTags(doc?: Document, env?: NavigationCacheEnvironment, cacheStorage?: NavigationCacheStorage): Promise<void>;