@rangojs/router 0.0.0-experimental.28 → 0.0.0-experimental.29

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.28",
+  version: "0.0.0-experimental.29",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.28",
+  "version": "0.0.0-experimental.29",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/router-setup/SKILL.md

@@ -108,6 +108,11 @@ interface RSCRouterOptions<TEnv> {
   // Connection warmup (default: true)
   warmup?: boolean;
 
+  // Prefetch cache TTL in seconds (default: 300)
+  // Controls in-memory cache duration and Cache-Control max-age for prefetch responses.
+  // Set to false to disable prefetch caching.
+  prefetchCacheTTL?: number | false;
+
   // CSP nonce provider (for router.fetch)
   nonce?: (
     request: Request,

package/src/browser/navigation-client.ts

@@ -17,6 +17,7 @@ import {
   emptyResponse,
   teeWithCompletion,
 } from "./response-adapter.js";
+import { buildPrefetchKey, consumePrefetch } from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -24,21 +25,12 @@ import {
  * The client handles building URLs with RSC parameters and
  * deserializing the response using the RSC runtime.
  *
+ * Checks the in-memory prefetch cache before making a network request.
+ * The cache key is source-dependent (includes the previous URL) so
+ * prefetch responses match the exact diff the server would produce.
+ *
  * @param deps - RSC browser dependencies (createFromFetch)
  * @returns NavigationClient instance
- *
- * @example
- * ```typescript
- * import { createFromFetch } from "@vitejs/plugin-rsc/browser";
- *
- * const client = createNavigationClient({ createFromFetch });
- *
- * const payload = await client.fetchPartial({
- *   targetUrl: "/shop/products",
- *   segmentIds: ["root", "shop"],
- *   previousUrl: "/",
- * });
- * ```
  */
 export function createNavigationClient(
   deps: Pick<RscBrowserDependencies, "createFromFetch">,
@@ -47,8 +39,9 @@ export function createNavigationClient(
     /**
      * Fetch a partial RSC payload for navigation
      *
-     * Sends current segment IDs to the server so it can determine
-     * which segments need to be re-rendered (diff).
+     * First checks the in-memory prefetch cache for a matching entry.
+     * If found, uses the cached response instantly. Otherwise sends
+     * current segment IDs to the server for diff-based rendering.
      *
      * @param options - Fetch options
      * @returns RSC payload with segments and metadata, plus stream completion promise
@@ -80,7 +73,8 @@ export function createNavigationClient(
         });
       }
 
-      // Build fetch URL with partial rendering params
+      // Build fetch URL with partial rendering params (used for both
+      // cache key lookup and actual fetch if cache misses)
       const fetchUrl = new URL(targetUrl, window.location.origin);
       fetchUrl.searchParams.set("_rsc_partial", "true");
       fetchUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
@@ -90,11 +84,17 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
-      if (tx) {
-        browserDebugLog(tx, "fetching", {
-          path: `${fetchUrl.pathname}${fetchUrl.search}`,
-        });
-      }
+
+      // Check in-memory prefetch cache before making a network request.
+      // The cache key includes the source URL (previousUrl) because the
+      // server's diff response depends on the source page context.
+      // Skip cache for stale revalidation (needs fresh data), HMR (needs
+      // fresh modules), and intercept contexts (source-dependent responses).
+      const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
+      const cachedResponse =
+        !staleRevalidation && !hmr && !interceptSourceUrl
+          ? consumePrefetch(cacheKey)
+          : null;
 
       // Track when the stream completes
       let resolveStreamComplete: () => void;
@@ -102,63 +102,88 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
-      // Create a response promise that tracks stream completion
-      const responsePromise = fetch(fetchUrl, {
-        headers: {
-          "X-RSC-Router-Client-Path": previousUrl,
-          "X-Rango-State": getRangoState(),
-          ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
-          ...(interceptSourceUrl && {
-            "X-RSC-Router-Intercept-Source": interceptSourceUrl,
-          }),
-          ...(hmr && { "X-RSC-HMR": "1" }),
-        },
-        signal,
-      }).then((response) => {
-        // Check for version mismatch - server wants us to reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          if (tx) {
-            browserDebugLog(tx, "version mismatch, reloading", {
-              reloadUrl: reload.url,
-            });
-          }
-          window.location.href = reload.url;
-          return new Promise<Response>(() => {});
-        }
+      let responsePromise: Promise<Response>;
 
-        // Server-side redirect without state: the server returned 204 with
-        // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
-        // to a URL rendering full HTML). Throw ServerRedirect so the
-        // navigation bridge catches it and re-navigates with _skipCache.
-        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-        if (redirect === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
+      if (cachedResponse) {
+        if (tx) {
+          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
         }
-        if (redirect) {
-          if (tx) {
-            browserDebugLog(tx, "server redirect", {
-              redirectUrl: redirect.url,
-            });
-          }
-          resolveStreamComplete();
-          throw new ServerRedirect(redirect.url, undefined);
+        // Cached response body is already fully buffered (arrayBuffer),
+        // so stream completion is immediate.
+        responsePromise = Promise.resolve(cachedResponse).then((response) => {
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete (from cache)");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      } else {
+        if (tx) {
+          browserDebugLog(tx, "fetching", {
+            path: `${fetchUrl.pathname}${fetchUrl.search}`,
+          });
         }
 
-        return teeWithCompletion(
-          response,
-          () => {
-            if (tx) browserDebugLog(tx, "stream complete");
-            resolveStreamComplete();
+        responsePromise = fetch(fetchUrl, {
+          headers: {
+            "X-RSC-Router-Client-Path": previousUrl,
+            "X-Rango-State": getRangoState(),
+            ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
+            ...(interceptSourceUrl && {
+              "X-RSC-Router-Intercept-Source": interceptSourceUrl,
+            }),
+            ...(hmr && { "X-RSC-HMR": "1" }),
           },
           signal,
-        );
-      });
+        }).then((response) => {
+          // Check for version mismatch - server wants us to reload
+          const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+          if (reload === "blocked") {
+            resolveStreamComplete();
+            return emptyResponse();
+          }
+          if (reload) {
+            if (tx) {
+              browserDebugLog(tx, "version mismatch, reloading", {
+                reloadUrl: reload.url,
+              });
+            }
+            window.location.href = reload.url;
+            return new Promise<Response>(() => {});
+          }
+
+          // Server-side redirect without state: the server returned 204 with
+          // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
+          // to a URL rendering full HTML). Throw ServerRedirect so the
+          // navigation bridge catches it and re-navigates with _skipCache.
+          const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+          if (redirect === "blocked") {
+            resolveStreamComplete();
+            return emptyResponse();
+          }
+          if (redirect) {
+            if (tx) {
+              browserDebugLog(tx, "server redirect", {
+                redirectUrl: redirect.url,
+              });
+            }
+            resolveStreamComplete();
+            throw new ServerRedirect(redirect.url, undefined);
+          }
+
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      }
 
       try {
         // Deserialize RSC payload

package/src/browser/prefetch/cache.ts

@@ -1,47 +1,127 @@
 /**
- * Prefetch Tracking
+ * Prefetch Cache
  *
- * Tracks in-flight and completed prefetches for deduplication.
- * The actual response caching is handled by the browser's HTTP cache
- * via Vary: X-Rango-State.
+ * In-memory cache storing prefetch Response objects for instant cache hits
+ * on subsequent navigation. Cache key is source-dependent (includes the
+ * current page URL) because the server's diff-based response depends on
+ * where the user navigates from.
+ *
+ * Replaces the previous browser HTTP cache approach which was unreliable
+ * due to response draining race conditions and browser inconsistencies.
  */
 
 import { cancelAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
 
+// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
+// the server-configured prefetchCacheTTL from router options.
+// 0 disables the in-memory cache entirely.
+let cacheTTL = 300_000;
+
+/**
+ * Initialize the prefetch cache with the configured TTL.
+ * Called once at app startup with the value from server metadata.
+ * A TTL of 0 disables the in-memory cache.
+ */
+export function initPrefetchCache(ttlMs: number): void {
+  cacheTTL = ttlMs;
+}
+const MAX_PREFETCH_CACHE_SIZE = 50;
+
+interface PrefetchCacheEntry {
+  response: Response;
+  timestamp: number;
+}
+
+const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
-const prefetched = new Set<string>();
 
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
-// started before a clear carry a stale generation and must not re-add their
-// key to the prefetched set (the browser HTTP cache entry is already invalid
-// due to Rango-State rotation).
+// started before a clear carry a stale generation and must not store their
+// response (the data may be stale due to a server action invalidation).
 let generation = 0;
 
 /**
- * Check if a prefetch is already in-flight or completed for the given key.
+ * Build a source-dependent cache key.
+ * Includes the source page href so the same target prefetched from
+ * different pages gets separate entries — the server response varies
+ * based on the source page context (diff-based rendering).
+ */
+export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
+  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+}
+
+/**
+ * Check if a prefetch is already cached, in-flight, or queued for the given key.
  */
 export function hasPrefetch(key: string): boolean {
-  return prefetched.has(key) || inflight.has(key);
+  if (inflight.has(key)) return true;
+  if (cacheTTL <= 0) return false;
+  const entry = cache.get(key);
+  if (!entry) return false;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return false;
+  }
+  return true;
 }
 
 /**
- * Capture the current generation. The returned value is passed to
- * markPrefetched so it can detect stale completions.
+ * Consume a cached prefetch response. Returns null if not found or expired.
+ * One-time consumption: the entry is deleted after retrieval.
+ * Returns null when caching is disabled (TTL <= 0).
  */
-export function currentGeneration(): number {
-  return generation;
+export function consumePrefetch(key: string): Response | null {
+  if (cacheTTL <= 0) return null;
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return null;
+  }
+  cache.delete(key);
+  return entry.response;
 }
 
 /**
- * Mark a key as successfully prefetched (response is in browser HTTP cache).
- * Skips if the generation has changed since the fetch started (cache was
- * invalidated mid-flight, so the response uses a stale X-Rango-State).
+ * Store a prefetch response in the in-memory cache.
+ * The response body must be fully buffered (e.g. via arrayBuffer()) before
+ * storing, so the cached Response is self-contained and network-independent.
+ *
+ * Skips storage if the generation has changed since the fetch started
+ * (a server action invalidated the cache mid-flight).
  */
-export function markPrefetched(key: string, fetchGeneration: number): void {
-  if (fetchGeneration === generation) {
-    prefetched.add(key);
+export function storePrefetch(
+  key: string,
+  response: Response,
+  fetchGeneration: number,
+): void {
+  if (cacheTTL <= 0) return;
+  if (fetchGeneration !== generation) return;
+
+  // Evict expired entries
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now - entry.timestamp > cacheTTL) {
+      cache.delete(k);
+    }
   }
+
+  // FIFO eviction if at capacity
+  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest) cache.delete(oldest);
+  }
+
+  cache.set(key, { response, timestamp: now });
+}
+
+/**
+ * Capture the current generation. The returned value is passed to
+ * storePrefetch so it can detect stale completions.
+ */
+export function currentGeneration(): number {
+  return generation;
 }
 
 export function markPrefetchInflight(key: string): void {
@@ -53,15 +133,14 @@ export function clearPrefetchInflight(key: string): void {
 }
 
 /**
- * Invalidate prefetch state. Called when server actions mutate data.
- * Updates the localStorage state key so next fetch has a different
- * X-Rango-State value, causing Vary mismatch in browser HTTP cache.
- * Also cancels any in-flight or queued speculative prefetches.
+ * Invalidate all prefetch state. Called when server actions mutate data.
+ * Clears the in-memory cache, cancels in-flight prefetches, and rotates
+ * the Rango state key so CDN-cached responses are also invalidated.
  */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
-  prefetched.clear();
+  cache.clear();
   cancelAllPrefetches();
   invalidateRangoState();
 }

package/src/browser/prefetch/fetch.ts

@@ -2,15 +2,17 @@
  * Prefetch Fetch
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
- * and useRouter().prefetch(). Sends low-priority fetch requests with
- * X-Rango-State and X-Rango-Prefetch headers so the browser HTTP cache
- * can serve the response on subsequent navigation.
+ * and useRouter().prefetch(). Sends the same headers and segment IDs as a
+ * real navigation so the server returns a proper diff. The Response is fully
+ * buffered and stored in an in-memory cache for instant consumption on
+ * subsequent navigation.
  */
 
 import {
+  buildPrefetchKey,
   hasPrefetch,
   markPrefetchInflight,
-  markPrefetched,
+  storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
 } from "./cache.js";
@@ -20,9 +22,9 @@ import { shouldPrefetch } from "./policy.js";
 
 /**
  * Build an RSC partial URL for prefetching.
- * Includes _rsc_v for version mismatch detection when available.
- * Returns null for malformed or cross-origin URLs to prevent
- * leaking router headers to external origins.
+ * Includes _rsc_segments so the server can diff against currently mounted
+ * segments, and _rsc_v for version mismatch detection.
+ * Returns null for malformed or cross-origin URLs.
  */
 function buildPrefetchUrl(
   url: string,
@@ -49,18 +51,9 @@ function buildPrefetchUrl(
 }
 
 /**
- * Build the dedup key for prefetch tracking.
- * Includes the source page pathname so the same target prefetched from
- * different pages gets separate entries — the server response varies on
- * X-RSC-Router-Client-Path (source page context).
- */
-function buildPrefetchKey(targetUrl: URL): string {
-  return window.location.href + "\0" + targetUrl.pathname + targetUrl.search;
-}
-
-/**
- * Core prefetch fetch logic. Returns a Promise and accepts an optional
- * AbortSignal for cancellation by the prefetch queue.
+ * Core prefetch fetch logic. Fetches the response, fully buffers the body,
+ * and stores it in the in-memory cache. Returns a Promise and accepts an
+ * optional AbortSignal for cancellation by the prefetch queue.
  */
 function executePrefetchFetch(
   key: string,
@@ -79,14 +72,19 @@ function executePrefetchFetch(
       "X-Rango-Prefetch": "1",
     },
   })
-    .then((response) => {
-      // Drain body to ensure full download for browser HTTP cache.
-      // pipeTo avoids decoding the stream into a JS string (unlike .text()).
-      if (response.ok && response.body) {
-        return response.body
-          .pipeTo(new WritableStream())
-          .then(() => markPrefetched(key, gen));
-      }
+    .then(async (response) => {
+      if (!response.ok) return;
+      // Fully buffer the response body so the cached Response is
+      // self-contained and doesn't depend on the network connection.
+      // This eliminates the race condition where the user clicks before
+      // the response body has been fully downloaded.
+      const buffer = await response.arrayBuffer();
+      const cachedResponse = new Response(buffer, {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
+      storePrefetch(key, cachedResponse, gen);
     })
     .catch(() => {
       // Silently ignore prefetch failures (including abort)
@@ -97,7 +95,7 @@ function executePrefetchFetch(
 }
 
 /**
- * Prefetch (direct): fetch with low priority and store in browser HTTP cache.
+ * Prefetch (direct): fetch with low priority and store in in-memory cache.
  * Used by hover strategy -- fires immediately without queueing.
  */
 export function prefetchDirect(
@@ -109,7 +107,7 @@ export function prefetchDirect(
 
   const targetUrl = buildPrefetchUrl(url, segmentIds, version);
   if (!targetUrl) return;
-  const key = buildPrefetchKey(targetUrl);
+  const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return;
   executePrefetchFetch(key, targetUrl.toString());
 }
@@ -127,7 +125,7 @@ export function prefetchQueued(
   if (!shouldPrefetch()) return "";
   const targetUrl = buildPrefetchUrl(url, segmentIds, version);
   if (!targetUrl) return "";
-  const key = buildPrefetchKey(targetUrl);
+  const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return key;
   const fetchUrlStr = targetUrl.toString();
   enqueuePrefetch(key, (signal) =>

package/src/browser/rsc-router.tsx

@@ -22,6 +22,7 @@ import type {
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
+import { initPrefetchCache } from "./prefetch/cache.js";
 import {
   isInterceptSegment,
   splitInterceptSegments,
@@ -201,10 +202,17 @@ export async function initBrowserApp(
   const rootLayout = initialPayload.metadata?.rootLayout;
   const version = initialPayload.metadata?.version;
 
-  // Initialize the localStorage state key for browser HTTP cache invalidation.
+  // Initialize the localStorage state key for cache invalidation.
   // Uses the build version so a new deploy automatically busts all cached prefetches.
   initRangoState(version ?? "0");
 
+  // Initialize the in-memory prefetch cache TTL from server config.
+  // A value of 0 disables the cache; undefined falls back to the module default.
+  const prefetchCacheTTL = initialPayload.metadata?.prefetchCacheTTL;
+  if (prefetchCacheTTL !== undefined) {
+    initPrefetchCache(prefetchCacheTTL);
+  }
+
   // Create a bound renderSegments that includes rootLayout
   const renderSegments = (
     segments: ResolvedSegment[],

package/src/browser/types.ts

@@ -55,6 +55,11 @@ export interface RscMetadata {
    * Used to detect version mismatches after HMR/deployment.
    */
   version?: string;
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * Sent on initial render so the browser can configure its cache duration.
+   */
+  prefetchCacheTTL?: number;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.

package/src/router/middleware-types.ts

@@ -12,6 +12,8 @@ import type {
   DefaultVars,
 } from "../types/global-namespace.js";
 import type { ScopedReverseFunction } from "../reverse.js";
+import type { Theme } from "../theme/types.js";
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 
 /**
  * Get variable function type
@@ -79,12 +81,25 @@ export interface MiddlewareContext<
    */
   readonly res: Response;
 
+  /**
+   * Shorthand for ctx.res.headers — response headers.
+   * Before `next()`, returns headers from the shared response stub.
+   * After `next()`, returns headers from the downstream response.
+   */
+  readonly headers: Headers;
+
   /** Get a context variable (shared with route handlers) */
   get: GetVariableFn;
 
   /** Set a context variable (shared with route handlers) */
   set: SetVariableFn;
 
+  /**
+   * Middleware-injected variables.
+   * Same shared dictionary as `ctx.get()`/`ctx.set()`.
+   */
+  var: DefaultVars;
+
   /**
    * Set a response header - can be called before or after `next()`
    *
@@ -113,6 +128,25 @@ export interface MiddlewareContext<
    */
   debugPerformance(): void;
 
+  /**
+   * Current theme (from cookie or default).
+   * Only available when theme is enabled in router config.
+   */
+  theme?: Theme;
+
+  /**
+   * Set the theme (only available when theme is enabled in router config).
+   * Sets a cookie with the new theme value.
+   */
+  setTheme?: (theme: Theme) => void;
+
+  /**
+   * Attach location state entries to this response.
+   * State is delivered to the client via history.pushState and accessible
+   * through the useLocationState() hook.
+   */
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+
   /**
    * Generate URLs from route names.
    * - `name` — global route, from the named-routes definition

package/src/router/middleware.ts

@@ -34,22 +34,6 @@ export type {
 } from "./middleware-types.js";
 export { parseCookies, serializeCookie } from "./middleware-cookies.js";
 
-// W5: Deduplicate by function reference so each distinct middleware warns once,
-// regardless of whether it is named or anonymous.
-let warnedRedirectMiddleware = new WeakSet<Function>();
-
-function warnCtxSetBeforeRedirect(handler: Function): void {
-  if (warnedRedirectMiddleware.has(handler)) return;
-  warnedRedirectMiddleware.add(handler);
-  const label = handler.name || "(anonymous)";
-  console.warn(
-    `[rango] Route middleware "${label}" called ctx.set() then returned a ` +
-      `redirect. Context variables are per-request and won't be available ` +
-      `on the redirect target. Use cookies to persist state across ` +
-      `redirects, or move ctx.set() to the target route's middleware.`,
-  );
-}
-
 const MIDDLEWARE_METRIC_DEPTH = 1;
 /** Ignore post-next() durations below this threshold (measurement noise). */
 const POST_METRIC_MIN_DURATION_MS = 0.01;
@@ -75,11 +59,6 @@ function getMiddlewareMetricLabel<TEnv>(
   return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
 }
 
-/** Reset W5 deduplication state (for tests only). */
-export function _resetW5Warnings(): void {
-  warnedRedirectMiddleware = new WeakSet();
-}
-
 /**
  * Parse a route pattern into regex and param names
  * Supports: *, /path, /path/*, /path/:param, /path/:param/*
@@ -221,6 +200,10 @@ export function createMiddlewareContext<TEnv>(
       );
     },
 
+    get headers(): Headers {
+      return this.res.headers;
+    },
+
     get: ((keyOrVar: any) =>
       contextGet(variables, keyOrVar)) as MiddlewareContext<TEnv>["get"],
 
@@ -228,6 +211,8 @@ export function createMiddlewareContext<TEnv>(
       contextSet(variables, keyOrVar, value);
     }) as MiddlewareContext<TEnv>["set"],
 
+    var: variables as MiddlewareContext<TEnv>["var"],
+
     header(name: string, value: string): void {
       // Before next(): delegate to shared RequestContext stub
       if (isPreNext()) {
@@ -246,6 +231,24 @@ export function createMiddlewareContext<TEnv>(
       responseHolder.response.headers.set(name, value);
     },
 
+    get theme(): MiddlewareContext<TEnv>["theme"] {
+      return _getRequestContext()?.theme;
+    },
+
+    get setTheme(): MiddlewareContext<TEnv>["setTheme"] {
+      return _getRequestContext()?.setTheme;
+    },
+
+    setLocationState(entries) {
+      const reqCtx = _getRequestContext();
+      if (!reqCtx) {
+        throw new Error(
+          "setLocationState() is not available outside a request context",
+        );
+      }
+      reqCtx.setLocationState(entries);
+    },
+
     reverse:
       reverse ??
       ((name: string) => {
@@ -425,16 +428,6 @@ export async function executeMiddleware<TEnv>(
       return nextPromise;
     };
 
-    // W5: track whether ctx.set() is called during this middleware
-    let ctxSetCalled = false;
-    if (process.env.NODE_ENV !== "production") {
-      const originalSet = ctx.set;
-      ctx.set = ((...args: any[]) => {
-        ctxSetCalled = true;
-        return (originalSet as Function).apply(ctx, args);
-      }) as typeof ctx.set;
-    }
-
     let result: Response | void;
     try {
       result = await entry.handler(ctx, wrappedNext);
@@ -464,16 +457,6 @@ export async function executeMiddleware<TEnv>(
     // RequestContext stub headers (from ctx.setCookie) into the
     // returned Response so they are not lost.
     if (result instanceof Response) {
-      // W5: warn if ctx.set() was called but middleware returned a redirect
-      if (
-        process.env.NODE_ENV !== "production" &&
-        ctxSetCalled &&
-        result.status >= 300 &&
-        result.status < 400
-      ) {
-        warnCtxSetBeforeRedirect(entry.handler);
-      }
-
       const mergedHeaders = new Headers(result.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
@@ -524,19 +507,6 @@ export async function executeMiddleware<TEnv>(
     // If middleware called next(), await it and return the response
     if (nextPromise) {
       await nextPromise;
-
-      // W5: warn if ctx.set() was called but the downstream response is a redirect.
-      // The ctx.set() values will be lost because the redirect navigates away.
-      if (
-        process.env.NODE_ENV !== "production" &&
-        ctxSetCalled &&
-        responseHolder.response &&
-        responseHolder.response.status >= 300 &&
-        responseHolder.response.status < 400
-      ) {
-        warnCtxSetBeforeRedirect(entry.handler);
-      }
-
       return responseHolder.response!;
     }
 

package/src/router/router-interfaces.ts

@@ -258,10 +258,17 @@ export interface RSCRouterInternal<
 
   /**
    * Cache-Control header value for prefetch responses.
-   * False means no browser caching of prefetch responses.
+   * False means no caching of prefetch responses.
+   * Derived from prefetchCacheTTL.
    */
   readonly prefetchCacheControl: string | false;
 
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * 0 means caching is disabled.
+   */
+  readonly prefetchCacheTTL: number;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods

package/src/router/router-options.ts

@@ -415,16 +415,21 @@ export interface RSCRouterOptions<TEnv = any> {
   version?: string;
 
   /**
-   * Cache-Control header value for prefetch responses.
-   * Only applied to non-intercept partial responses that include the
-   * `X-Rango-Prefetch` header (sent by the Link component's prefetch fetch).
-   * Navigation responses are never cached by the browser.
+   * TTL (in seconds) for the in-memory prefetch cache and the
+   * Cache-Control header on prefetch responses.
    *
-   * Set to `false` to disable browser caching of prefetch responses entirely.
+   * Controls how long prefetch responses are kept in the client-side
+   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
+   * on server responses for CDN/edge caching.
    *
-   * @default "private, max-age=300"
+   * The cache is automatically invalidated on server actions regardless
+   * of TTL, so this is primarily a staleness safety net.
+   *
+   * Set to `false` to disable prefetch caching entirely.
+   *
+   * @default 300 (5 minutes)
    */
-  prefetchCacheControl?: string | false;
+  prefetchCacheTTL?: number | false;
 
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.

package/src/router.ts

@@ -147,7 +147,7 @@ export function createRouter<TEnv = any>(
     $$sourceFile: injectedSourceFile,
     nonce,
     version,
-    prefetchCacheControl: prefetchCacheControlOption,
+    prefetchCacheTTL: prefetchCacheTTLOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -200,11 +200,17 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
-  // Resolve prefetch cache control (default: 'private, max-age=300')
-  const prefetchCacheControl =
-    prefetchCacheControlOption !== undefined
-      ? prefetchCacheControlOption
-      : "private, max-age=300";
+  // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
+  // Clamp to a non-negative integer for valid Cache-Control max-age.
+  const rawTTL =
+    prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
+  const prefetchCacheTTLSeconds =
+    rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
+  const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
+  const prefetchCacheControl: string | false =
+    prefetchCacheTTLSeconds === 0
+      ? false
+      : `private, max-age=${prefetchCacheTTLSeconds}`;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
@@ -879,8 +885,9 @@ export function createRouter<TEnv = any>(
     // Expose resolved cache profiles for per-request resolution
     cacheProfiles: resolvedCacheProfiles,
 
-    // Expose prefetch cache control for RSC handler
+    // Expose prefetch cache settings
     prefetchCacheControl,
+    prefetchCacheTTL,
 
     // Expose warmup enabled flag for handler and client
     warmupEnabled,

package/src/rsc/rsc-rendering.ts

@@ -62,6 +62,7 @@ export async function handleRscRendering<TEnv>(
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },

package/src/rsc/types.ts

@@ -32,6 +32,8 @@ export interface RscPayload {
     handles?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
+    /** TTL in milliseconds for the client-side in-memory prefetch cache */
+    prefetchCacheTTL?: number;
     /** Theme configuration for FOUC prevention */
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */