rwsdk 1.0.0-beta.5 → 1.0.0-beta.51

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

@@ -1,11 +1,73 @@
 import "./setWebpackRequire";
 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;
-export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, }?: {
+/**
+ * Initializes the React client and hydrates the RSC payload.
+ *
+ * This function sets up client-side hydration for React Server Components,
+ * 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`. 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 onHydrated - 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
+ * import { initClient } from "rwsdk/client";
+ *
+ * initClient();
+ *
+ * @example
+ * // With client-side navigation
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * 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: {
+ *     onRecoverableError: (error) => {
+ *       console.warn("Recoverable error:", error);
+ *     },
+ *   },
+ * });
+ */
+export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, }?: {
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;
     handleResponse?: (response: Response) => boolean;
+    onHydrated?: () => void;
+    onActionResponse?: (actionResponse: ActionResponseData) => boolean | void;
 }) => Promise<void>;

package/dist/runtime/client/client.js

@@ -4,6 +4,7 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // context(justinvdm, 14 Aug 2025): `react-server-dom-webpack` uses this global
 // to load modules, so we need to define it here before importing
 // "react-server-dom-webpack."
+// prettier-ignore
 import "./setWebpackRequire";
 import React from "react";
 import { hydrateRoot } from "react-dom/client";
@@ -12,18 +13,57 @@ 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", method = "POST") => {
         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);
+            // If args are provided and method is GET, serialize them into the query string
+            if (args != null && method === "GET") {
+                url.searchParams.set("args", JSON.stringify(args));
+            }
+        }
+        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 {
+            const headers = new Headers();
+            // Add x-rsc-data-only header if we want to skip the React tree render on the server
+            if (source === "query") {
+                headers.set("x-rsc-data-only", "true");
+            }
+            if (method === "GET") {
+                fetchPromise = fetch(url, {
+                    method: "GET",
+                    headers,
+                    redirect: "manual",
+                });
+            }
+            else {
+                fetchPromise = fetch(url, {
+                    method: "POST",
+                    headers,
+                    redirect: "manual",
+                    body: args != null ? await encodeReply(args) : null,
+                });
+            }
         }
-        const 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;
@@ -35,27 +75,121 @@ export const fetchTransport = (transportContext) => {
             const streamData = createFromFetch(Promise.resolve(response), {
                 callServer: fetchCallServer,
             });
-            transportContext.setRscPayload(streamData);
+            if (source === "navigation" || source === "action") {
+                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, {
             callServer: fetchCallServer,
         });
-        transportContext.setRscPayload(streamData);
+        if (source === "navigation" || source === "action") {
+            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;
 };
-export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, } = {}) => {
+/**
+ * Initializes the React client and hydrates the RSC payload.
+ *
+ * This function sets up client-side hydration for React Server Components,
+ * 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`. 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 onHydrated - 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
+ * import { initClient } from "rwsdk/client";
+ *
+ * initClient();
+ *
+ * @example
+ * // With client-side navigation
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * 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: {
+ *     onRecoverableError: (error) => {
+ *       console.warn("Recoverable error:", error);
+ *     },
+ *   },
+ * });
+ */
+export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, } = {}) => {
     const transportContext = {
         setRscPayload: () => { },
         handleResponse,
+        onHydrated,
+        onActionResponse,
     };
     let transportCallServer = transport(transportContext);
-    const callServer = (id, args) => transportCallServer(id, args);
+    const callServer = (id, args, source, method) => {
+        return transportCallServer(id, args, source, method);
+    };
     const upgradeToRealtime = async ({ key } = {}) => {
         const { realtimeTransport } = await import("../lib/realtime/client");
         const createRealtimeTransport = realtimeTransport({ key });
@@ -68,7 +202,7 @@ export const initClient = async ({ transport = fetchTransport, hydrateRootOption
     };
     const rootEl = document.getElementById("hydrate-root");
     if (!rootEl) {
-        throw new Error('no element with id "hydrate-root"');
+        throw new Error('RedwoodSDK: No element with id "hydrate-root" found in the document. This element is required for hydration. Ensure your Document component contains a <div id="hydrate-root">{children}</div>.');
     }
     let rscPayload;
     // context(justinvdm, 18 Jun 2025): We inject the RSC payload
@@ -81,7 +215,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.onHydrated?.();
+        }, [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 {
@@ -12,6 +15,48 @@ export interface NavigateOptions {
     };
 }
 export declare function navigate(href: string, options?: NavigateOptions): Promise<void>;
+/**
+ * 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.
+ *
+ * @param opts.scrollToTop - Scroll to top after navigation (default: true)
+ * @param opts.scrollBehavior - How to scroll: 'instant', 'smooth', or 'auto' (default: 'instant')
+ * @param opts.onNavigate - Callback executed after history push but before RSC fetch
+ *
+ * @example
+ * // Basic usage
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse, onHydrated } = initClientNavigation();
+ * initClient({ handleResponse, onHydrated });
+ *
+ * @example
+ * // With custom scroll behavior
+ * const { handleResponse } = initClientNavigation({
+ *   scrollBehavior: "smooth",
+ *   scrollToTop: true,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // Preserve scroll position (e.g., for infinite scroll)
+ * const { handleResponse } = initClientNavigation({
+ *   scrollToTop: false,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With navigation callback
+ * const { handleResponse } = initClientNavigation({
+ *   onNavigate: () => {
+ *     console.log("Navigating to:", window.location.href);
+ *   },
+ * });
+ * initClient({ handleResponse });
+ */
 export declare function initClientNavigation(opts?: ClientNavigationOptions): {
     handleResponse: (response: Response) => boolean;
+    onHydrated: () => 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,7 +45,7 @@ export async function navigate(href, options = { history: "push" }) {
     else {
         window.history.replaceState({ path: href }, "", url);
     }
-    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") {
@@ -63,6 +64,47 @@ function saveScrollPosition(x, y) {
         scrollY: y,
     }, "", window.location.href);
 }
+/**
+ * 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.
+ *
+ * @param opts.scrollToTop - Scroll to top after navigation (default: true)
+ * @param opts.scrollBehavior - How to scroll: 'instant', 'smooth', or 'auto' (default: 'instant')
+ * @param opts.onNavigate - Callback executed after history push but before RSC fetch
+ *
+ * @example
+ * // Basic usage
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse, onHydrated } = initClientNavigation();
+ * initClient({ handleResponse, onHydrated });
+ *
+ * @example
+ * // With custom scroll behavior
+ * const { handleResponse } = initClientNavigation({
+ *   scrollBehavior: "smooth",
+ *   scrollToTop: true,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // Preserve scroll position (e.g., for infinite scroll)
+ * const { handleResponse } = initClientNavigation({
+ *   scrollToTop: false,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With navigation callback
+ * const { handleResponse } = initClientNavigation({
+ *   onNavigate: () => {
+ *     console.log("Navigating to:", window.location.href);
+ *   },
+ * });
+ * initClient({ handleResponse });
+ */
 export function initClientNavigation(opts = {}) {
     IS_CLIENT_NAVIGATION = true;
     history.scrollRestoration = "auto";
@@ -74,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 onHydrated() {
+        // 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.
+        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,
+        onHydrated,
     };
 }

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="x-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>;