@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/src/rsc/rsc-rendering.ts

@@ -7,7 +7,7 @@
  */
 
 import {
-  requireRequestContext,
+  getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
@@ -28,7 +28,7 @@ export function handleRscRendering<TEnv>(
   env: TEnv,
   url: URL,
   isPartial: boolean,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
 ): Promise<Response> {
   // Instrument the whole render phase once through the unified API: it records
@@ -55,10 +55,10 @@ async function handleRscRenderingInner<TEnv>(
   env: TEnv,
   url: URL,
   isPartial: boolean,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
 ): Promise<Response> {
-  const reqCtx = requireRequestContext();
+  const reqCtx = getRequestContext();
 
   let payload: RscPayload;
   let hasInterceptSlots = false;
@@ -82,6 +82,15 @@ async function handleRscRenderingInner<TEnv>(
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
+      // Carry warmupEnabled on the initial full-render payload so the client
+      // respects warmup:false from first load. The 404 and PE payloads already
+      // include it; without it here warmup could never be disabled on the
+      // normal full-load path (partial payloads omit it by design).
+      warmupEnabled: ctx.router.warmupEnabled,
+      // Carry strictMode on the initial full-render payload so the browser
+      // entry knows whether to wrap hydration in React.StrictMode. Partial
+      // (navigation) payloads omit it by design; StrictMode is decided once.
+      strictMode: ctx.router.strictMode,
       initialTheme: reqCtx.theme,
     },
   });

package/src/rsc/server-action.ts

@@ -16,7 +16,7 @@
  */
 
 import {
-  requireRequestContext,
+  getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
@@ -74,7 +74,7 @@ export async function executeServerAction<TEnv>(
   env: TEnv,
   url: URL,
   actionId: string,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
 ): Promise<Response | ActionContinuation> {
   const temporaryReferences = ctx.createTemporaryReferenceSet();
 
@@ -115,9 +115,55 @@ export async function executeServerAction<TEnv>(
     // Keep the original error as `cause` for server-side logging, but do not
     // interpolate it into the message: that string can surface to the client
     // and may leak decode internals.
-    throw new Error("Failed to decode action arguments", {
+    const decodeError = new Error("Failed to decode action arguments", {
       cause: error,
     });
+
+    // Produce a router-controlled response instead of re-throwing into the
+    // host (which would surface as an opaque 500). This mirrors the no-JS PE
+    // path, where a malformed form body renders the route error boundary or
+    // returns an explicit 400 (progressive-enhancement.ts). Attempt boundary
+    // rendering first; if a boundary matches, defer the render to the
+    // revalidation phase (errorBoundary continuation) so it runs inside route
+    // middleware, identical to the action-threw path below. Otherwise return a
+    // plain 400 — the JS and no-JS paths now converge on the same outcome.
+    let decodeBoundary: MatchResult | undefined;
+    try {
+      decodeBoundary =
+        (await ctx.router.matchError(request, { env }, decodeError, "route")) ??
+        undefined;
+    } catch {
+      // matchError itself failed — fall through to the plain 400 below.
+      decodeBoundary = undefined;
+    }
+
+    ctx.callOnError(decodeError, "action", {
+      request,
+      url,
+      env,
+      actionId,
+      handledByBoundary: !!decodeBoundary,
+    });
+
+    if (decodeBoundary) {
+      return {
+        returnValue: { ok: false, data: decodeError },
+        // 400: malformed action request, matching the PE explicit-400 status
+        // class (the action-threw path uses 500; a decode failure is a bad
+        // request, not an action runtime error).
+        actionStatus: 400,
+        temporaryReferences,
+        actionContext: {
+          actionId,
+          actionUrl: new URL(url),
+          actionResult: decodeError,
+          formData: actionFormData,
+        },
+        errorBoundary: decodeBoundary,
+      };
+    }
+
+    return createResponseWithMergedHeaders(null, { status: 400 });
   }
 
   // Execute the server action
@@ -279,7 +325,7 @@ export function revalidateAfterAction<TEnv>(
   request: Request,
   env: TEnv,
   url: URL,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   continuation: ActionContinuation,
 ): Promise<Response> {
   // Instrument the action-revalidation render through the unified phase API,
@@ -304,7 +350,7 @@ async function revalidateAfterActionInner<TEnv>(
   request: Request,
   env: TEnv,
   url: URL,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   continuation: ActionContinuation,
 ): Promise<Response> {
   const {
@@ -314,7 +360,7 @@ async function revalidateAfterActionInner<TEnv>(
     actionContext,
     errorBoundary,
   } = continuation;
-  const reqCtx = requireRequestContext();
+  const reqCtx = getRequestContext();
   const metricsStore = reqCtx._metricsStore;
 
   // Action threw and a boundary matched: render the (already-matched) error

package/src/rsc/types.ts

@@ -53,6 +53,13 @@ export interface RscPayload {
     basename?: string;
     /** Whether connection warmup is enabled */
     warmupEnabled?: boolean;
+    /**
+     * Whether the client should hydrate inside React.StrictMode. Carried on
+     * the initial full-render payload only; the browser entry reads it once at
+     * hydration. Absent on partial (navigation) payloads. Defaults to true on
+     * the client when omitted.
+     */
+    strictMode?: boolean;
     /**
      * Server-side redirect with optional state (for partial requests).
      * `external: true` (from redirect(url, { external: true })) tells the client

package/src/search-params.ts

@@ -9,6 +9,15 @@
 
 import { encodeKV } from "./encode-kv.js";
 
+/**
+ * Decimal-number grammar for `"number"` search params: optional sign, digits
+ * with optional fraction, optional exponent. Deliberately excludes hex (`0x`),
+ * `Infinity`, and empty/whitespace so `Number()`'s lenient coercions
+ * (`Number("")===0`, `Number("0x10")===16`, `Number("Infinity")===Infinity`)
+ * do not slip non-decimal values into typed search.
+ */
+const DECIMAL_NUMBER_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
 /** Supported scalar types for search params (append ? for optional). */
 export type SearchSchemaValue =
   | "string"
@@ -161,7 +170,11 @@ type ExtractParamsFromPattern<T extends string> =
  * Parse URLSearchParams into a typed object using the given schema.
  *
  * - `"string"` / `"string?"` - kept as-is
- * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
+ * - `"number"` / `"number?"` - parsed as a finite decimal number. Accepts an
+ *   optional sign, digits with optional fraction, and optional exponent
+ *   (e.g. `42`, `-3.5`, `1e3`). Empty/whitespace-only, non-decimal forms
+ *   (`0x10`), and non-finite (`Infinity`) are treated as missing (omitted),
+ *   NOT coerced to `0`/`16`/`Infinity`.
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
  *
  * Missing params (both required and optional) are omitted from the result
@@ -187,11 +200,17 @@ export function parseSearchParams<T extends SearchSchema>(
     if (baseType === "string") {
       result[key] = raw;
     } else if (baseType === "number") {
-      const num = Number(raw);
-      if (!Number.isNaN(num)) {
-        result[key] = num;
+      // Trim, then require a valid decimal numeral and a finite result.
+      // Empty/whitespace, hex (0x10), and Infinity are treated as missing
+      // (omitted) — not coerced to 0/16/Infinity by Number()'s lenient rules.
+      const trimmed = raw.trim();
+      if (trimmed !== "" && DECIMAL_NUMBER_RE.test(trimmed)) {
+        const num = Number(trimmed);
+        if (Number.isFinite(num)) {
+          result[key] = num;
+        }
       }
-      // NaN treated as missing (undefined)
+      // Anything else treated as missing (undefined)
     } else if (baseType === "boolean") {
       result[key] = raw === "true" || raw === "1";
     }

package/src/segment-loader-promise.ts

@@ -7,8 +7,9 @@ import type { ResolvedSegment } from "./types.js";
  * source array (typically a single entry, since distinct loader groups rarely
  * share a first source). Object first-refs live in a WeakMap (auto-GC);
  * primitive first-refs (strings/numbers/booleans/null) live in a Map so
- * loaders that resolve to primitive data are memoized too — bounded in
- * practice by the application's loader set.
+ * loaders that resolve to primitive data are memoized too. The per-key array
+ * is capped (MAX_ENTRIES_PER_KEY, oldest evicted) so a long session under a
+ * stable first-ref does not grow it without bound.
  *
  * Keying externally means reconciliation's fresh segment objects no longer
  * drop memoization — the cache survives as long as the underlying loader
@@ -32,6 +33,16 @@ interface LoaderCacheEntry {
   promise: Promise<any[]>;
 }
 
+// Cap the per-key entries array. A stable first-ref (e.g. a layout loader whose
+// loaderData object survives reconciliation across navigations) keeps its
+// WeakMap/Map key alive, while a per-route loader whose ref changes each
+// navigation appends a brand-new sources array under that same live key on
+// every navigation. Nothing was ever removed, so the array grew linearly with
+// navigation count, pinning each stale Promise + sources array from GC — a
+// steady client-side leak over a long session. Only the current render's combo
+// needs to stay warm; evict the oldest beyond the cap.
+const MAX_ENTRIES_PER_KEY = 8;
+
 const objectLoaderCache = IS_BROWSER
   ? new WeakMap<object, LoaderCacheEntry[]>()
   : null;
@@ -124,6 +135,10 @@ export function getMemoizedLoaderPromise(
   const promise = buildLoaderPromise(loaders);
   const newEntry: LoaderCacheEntry = { sources, promise };
   if (entries) {
+    // Bound the array: drop the oldest entry before appending when at the cap.
+    if (entries.length >= MAX_ENTRIES_PER_KEY) {
+      entries.shift();
+    }
     entries.push(newEntry);
   } else if (isObjectLike(first)) {
     objectLoaderCache.set(first, [newEntry]);

package/src/server/loader-registry.ts

@@ -53,16 +53,16 @@ export async function getLoaderLazy(
   if (lazyLoaderImports && lazyLoaderImports.size > 0) {
     const lazyImport = lazyLoaderImports.get(id);
     if (lazyImport) {
-      try {
-        await lazyImport();
+      // A failed import is a real server breakage (broken transitive import,
+      // syntax error, throw in module top-level code), not a "loader not
+      // registered" case. Rethrow so the caller can return a 500 and route
+      // the failure through onError, instead of collapsing it to a 404.
+      await lazyImport();
 
-        const registered = getFetchableLoader(id);
-        if (registered) {
-          loaderRegistry.set(id, registered);
-          return registered;
-        }
-      } catch (error) {
-        console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+      const registered = getFetchableLoader(id);
+      if (registered) {
+        loaderRegistry.set(id, registered);
+        return registered;
       }
     }
   }
@@ -72,16 +72,14 @@ export async function getLoaderLazy(
   if (hashIndex !== -1) {
     const filePath = id.slice(0, hashIndex);
 
-    try {
-      await import(/* @vite-ignore */ `/${filePath}`);
+    // Same as the lazy branch: a thrown import is a server error, not a
+    // not-found. Let it propagate to the caller for a 500 + onError.
+    await import(/* @vite-ignore */ `/${filePath}`);
 
-      const registered = getFetchableLoader(id);
-      if (registered) {
-        loaderRegistry.set(id, registered);
-        return registered;
-      }
-    } catch (error) {
-      console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+    const registered = getFetchableLoader(id);
+    if (registered) {
+      loaderRegistry.set(id, registered);
+      return registered;
     }
   }
 

package/src/server/request-context.ts

@@ -50,7 +50,11 @@ import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
-import { THEME_COOKIE } from "../theme/constants.js";
+import {
+  THEME_COOKIE,
+  isValidTheme,
+  warnInvalidTheme,
+} from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isInsideCacheScope } from "./context.js";
@@ -58,7 +62,12 @@ import {
   createReverseFunction,
   stripInternalParams,
 } from "../router/handler-context.js";
-import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
+import {
+  getGlobalRouteMap,
+  isRouteRootScoped,
+  getSearchSchema,
+} from "../route-map-builder.js";
+import { parseSearchParams } from "../search-params.js";
 import { invariant } from "../errors.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
@@ -536,16 +545,6 @@ export function getLocationState(): LocationStateEntry[] | undefined {
   return ctx?._locationState;
 }
 
-/**
- * Get the current request context, throwing if not available
- * @deprecated Use getRequestContext() directly — it now throws if outside context
- */
-export function requireRequestContext<
-  TEnv = DefaultEnv,
->(): RequestContext<TEnv> {
-  return getRequestContext<TEnv>();
-}
-
 export type { ExecutionContext };
 
 /**
@@ -676,10 +675,12 @@ export function createRequestContext<TEnv>(
   const setTheme = (theme: Theme): void => {
     if (!themeConfig) return;
 
-    if (theme !== "system" && !themeConfig.themes.includes(theme)) {
-      console.warn(
-        `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
-      );
+    // Shared guard (isValidTheme): reject any value not in the configured theme
+    // set, AND reject "system" when system detection is off — a cookie of
+    // theme=system with enableSystem:false would re-apply a bogus class="system"
+    // on the next SSR.
+    if (!isValidTheme(theme, themeConfig)) {
+      warnInvalidTheme(theme, themeConfig);
       return;
     }
 
@@ -848,7 +849,11 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        executionContext.waitUntil(fn());
+        // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
+        // non-async callback becomes a rejected promise handed to the host's
+        // waitUntil (logged as a background failure), instead of escaping into
+        // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
+        executionContext.waitUntil(Promise.resolve().then(fn));
       } else {
         fireAndForgetWaitUntil(fn);
       }
@@ -952,7 +957,17 @@ export function createRequestContext<TEnv>(
   return ctx;
 }
 
-const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
+// Capture the Max-Age value so it can be parsed numerically. A leading zero
+// (Max-Age=05) is a non-zero lifetime, not a deletion; only a value that parses
+// to <= 0 marks a cookie for deletion. Pattern-matching a leading "0" misread
+// zero-prefixed values like 05 / 010 as deletions.
+const MAX_AGE_RE = /;\s*Max-Age\s*=\s*(-?\d+)/i;
+
+function isCookieDeletion(header: string): boolean {
+  const m = MAX_AGE_RE.exec(header);
+  if (!m) return false;
+  return Number(m[1]) <= 0;
+}
 
 function parseResponseCookies(response: Response): Map<string, string | null> {
   const result = new Map<string, string | null>();
@@ -973,7 +988,7 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
       continue;
     }
 
-    const isDeleted = MAX_AGE_ZERO_RE.test(header);
+    const isDeleted = isCookieDeletion(header);
     result.set(name, isDeleted ? null : value);
   }
 
@@ -1064,12 +1079,24 @@ export function createUseFunction<TEnv>(
 
     const ctx = getContext();
 
+    // Build the typed ctx.search the same way the render path
+    // (createHandlerContext) and the fetchable-loader path (loader-fetch.ts) do:
+    // parse the route's search schema over the cleaned searchParams. The base
+    // RequestContext carries no `search` field, so reading `(ctx as any).search`
+    // here always yielded {} — dropping typed search for action/dispatch loaders.
+    const searchSchema = ctx._routeName
+      ? getSearchSchema(ctx._routeName)
+      : undefined;
+    const loaderSearch = searchSchema
+      ? parseSearchParams(ctx.searchParams, searchSchema)
+      : {};
+
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
-      search: (ctx as any).search ?? {},
+      search: loaderSearch,
       pathname: ctx.pathname,
       url: ctx.url,
       originalUrl: ctx.originalUrl,

package/src/testing/dispatch.ts

@@ -27,6 +27,11 @@
  *     status, matching handleResponseRoute (RFC 9457 problem+json body with
  *     application/problem+json for json routes, text/plain message otherwise)
  *   - content-negotiated route:                         Vary: Accept appended
+ *   - cached response route (cache({...})):             getResponse/putResponse
+ *     hit/SWR/tag write, resolved from the matched entry tree exactly as
+ *     handleResponseRoute does. The write is scheduled via ctx.waitUntil
+ *     (a microtask without an executionContext), so a HIT-asserting test must
+ *     flush microtasks between the seeding dispatch and the asserting one.
  * - Global middleware (router.use(...)) AND route-level middleware, with full
  *   next()/short-circuit/throw-Response/header+cookie-merge fidelity.
  * - Partial (client-navigation) requests to a RESPONSE route (?_rsc_partial):
@@ -41,6 +46,15 @@
  *   redirects: a cross-origin Location is rewritten to the basename root unless
  *   redirect(url, { external: true }) opted out, mirroring production's single
  *   handler chokepoint. Soft partial/action redirects are 204 and pass through.
+ * - createRouter({ onError }) for CACHE / background-error degradation. dispatch
+ *   wires the request context's _reportBackgroundError to the router's onError the
+ *   same way the production RSC handler does, so a cache-read/cache-write/
+ *   stale-revalidation failure on a cached response route (a throwing route
+ *   cache({ key })/cache({ tags }), or a custom store whose keyGenerator/
+ *   getResponse/putResponse throws) fires onError with phase "cache" and
+ *   metadata.category, while the request still degrades-to-miss exactly as before.
+ *   (A thrown response-route HANDLER error is the one onError path NOT covered —
+ *   see "DOES NOT support" below.)
  *
  * What dispatch DOES NOT support (and why):
  * - RSC component routes — rendering requires the Flight serializer + React
@@ -48,10 +62,11 @@
  *   This includes partial requests that resolve to a component route.
  * - Server actions (?_rsc_action) — RSC protocol concerns handled by
  *   router.fetch().
- * - ctx.onError() callbacks on a thrown response-route handler error: the
+ * - createRouter({ onError }) on a thrown response-route HANDLER error: the
  *   error is serialized into the same typed 500 / RouterError Response as
- *   production, but registered onError handlers are NOT invoked here. Cover
- *   onError side effects with an e2e test.
+ *   production, but onError is NOT invoked for that path here. Cover handler-error
+ *   onError side effects with an e2e test. (This is the unchanged boundary; cache
+ *   and other background errors DO route through onError — see below.)
  * - Location-state-carrying redirects on a partial/action request: production
  *   embeds a Flight payload (createRedirectFlightResponse) so the client can
  *   restore location state across the redirect. dispatch is RSC-free, so it
@@ -84,6 +99,12 @@ import {
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
+// cache-scope is loaded LAZILY inside the response-route cache path (below):
+// its module graph pulls @vitejs/plugin-rsc/rsc (via segment-codec), which the
+// non-Vite unit-test runner cannot resolve. A static import here would drag that
+// onto the whole testing barrel's eager graph and break every consumer suite
+// that imports `@rangojs/router/testing` without mocking plugin-rsc.
+import type { EntryData } from "../server/context.js";
 import { setRouterManifest } from "../route-map-builder.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { RouterError } from "../errors.js";
@@ -103,6 +124,8 @@ import {
   markExternalRedirect,
 } from "../redirect-origin.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
 import type { Rango } from "../router/router-interfaces.js";
 
 /**
@@ -116,6 +139,7 @@ interface DispatchableRouter<TEnv> {
   routerId?: string;
   routeMap: Record<string, unknown>;
   middleware: MiddlewareEntry<TEnv>[];
+  onError?: OnErrorCallback<TEnv>;
   findMatch(pathname: string): {
     redirectTo?: string;
     routeKey?: string;
@@ -134,6 +158,7 @@ interface DispatchableRouter<TEnv> {
     params?: Record<string, string>;
     routeKey?: string;
     negotiated?: boolean;
+    manifestEntry?: EntryData;
   } | null>;
   basename?: string;
   cache?:
@@ -381,6 +406,22 @@ export async function dispatch<TEnv = any>(
     cacheStore,
     cacheProfiles: router.cacheProfiles,
   });
+  // Wire background error reporting so cache degradation (reportCacheError ->
+  // _reportBackgroundError) reaches the router's onError, mirroring the production
+  // RSC handler (rsc/handler.ts). Without this, dispatch could not observe onError.
+  requestContext._reportBackgroundError = (error, category) => {
+    if (error != null && typeof error === "object") {
+      if (requestContext._reportedErrors.has(error)) return;
+      requestContext._reportedErrors.add(error);
+    }
+    invokeOnError(
+      router.onError,
+      error,
+      "cache",
+      { request: req, url, metadata: { category } },
+      "RSC",
+    );
+  };
   // Match production: the RSC handler stores the router's basename on the
   // request context (handler.ts), and redirect() prefixes root-relative URLs
   // with it. Mirror it so basename-redirect tests behave as they do in a real
@@ -417,7 +458,7 @@ export async function dispatch<TEnv = any>(
     // coreHandler below, mirroring production where handleResponseRoute is
     // nested inside coreHandler. Built lazily so a redirect/404 path never
     // touches it.
-    const callResponseRoute = (): Promise<Response> => {
+    const callResponseRoute = async (): Promise<Response> => {
       // Match production: a partial (client-navigation) request to a response
       // route is short-circuited to X-RSC-Reload (handleResponseRoute), BEFORE
       // route-level middleware runs. Route-level middleware is skipped on a
@@ -527,28 +568,70 @@ export async function dispatch<TEnv = any>(
       if (isPartial) {
         return partialFinalHandler();
       }
-      const routeMiddlewareEntries = (preview?.routeMiddleware ?? []).map(
-        (mw) => ({
-          entry: {
-            pattern: null,
-            regex: null,
-            paramNames: [],
-            handler: mw.handler,
-          } as MiddlewareEntry<TEnv>,
-          params: mw.params,
-        }),
-      );
-      if (routeMiddlewareEntries.length === 0) {
-        return callHandler();
+
+      // executeHandler = callHandler wrapped by route-level middleware, exactly
+      // the unit the production response cache wraps (response-route-handler.ts).
+      const executeHandler = (): Promise<Response> => {
+        const routeMiddlewareEntries = (preview?.routeMiddleware ?? []).map(
+          (mw) => ({
+            entry: {
+              pattern: null,
+              regex: null,
+              paramNames: [],
+              handler: mw.handler,
+            } as MiddlewareEntry<TEnv>,
+            params: mw.params,
+          }),
+        );
+        if (routeMiddlewareEntries.length === 0) {
+          return callHandler();
+        }
+        return executeMiddleware<TEnv>(
+          routeMiddlewareEntries,
+          req,
+          env,
+          variables,
+          callHandler,
+          reverse,
+        );
+      };
+
+      // Response-route cache path: resolved through the SAME shared serve leaf
+      // (rsc/response-cache-serve.ts) production uses, so a cached
+      // path.json/path.text route hits/SWRs/writes tags through dispatch exactly
+      // as in production — and the two can never drift. Resolved from the matched
+      // entry tree (preview.manifestEntry), which previewMatch surfaces for
+      // response routes.
+      const manifestEntry = preview?.manifestEntry;
+      if (manifestEntry) {
+        // Lazy so the testing barrel's eager graph stays plugin-rsc-free (see the
+        // import note above): the leaf takes createCacheScope/resolveCacheTags as
+        // INJECTED deps so it never imports plugin-rsc; we hand it the lazily
+        // imported pair here, only once a response route actually matched.
+        const cacheScopeMod = await import("../cache/cache-scope.js");
+        const { serveResponseRouteWithCache } =
+          await import("../rsc/response-cache-serve.js");
+        // requestContext is RequestContext<TEnv>; the leaf is typed against the
+        // default-env RequestContext (it reads only env-agnostic config).
+        // Assignable in the router's own tsc but not when a consumer pins a
+        // concrete Env — cast to the leaf's param type.
+        const cached = await serveResponseRouteWithCache({
+          reqCtx: requestContext as Parameters<
+            typeof serveResponseRouteWithCache
+          >[0]["reqCtx"],
+          manifestEntry,
+          responseType: responseType as string,
+          url,
+          executeHandler,
+          deps: {
+            createCacheScope: cacheScopeMod.createCacheScope,
+            resolveCacheTags: cacheScopeMod.resolveCacheTags,
+          },
+        });
+        if (cached !== undefined) return cached;
       }
-      return executeMiddleware<TEnv>(
-        routeMiddlewareEntries,
-        req,
-        env,
-        variables,
-        callHandler,
-        reverse,
-      );
+
+      return executeHandler().then(finalizeResponse);
     };
 
     // coreHandler is the single terminal the global middleware chain wraps,