@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/rsc/handler.ts

@@ -8,33 +8,44 @@
  */
 
 import { createElement } from "react";
-import { RouteNotFoundError, RouterError } from "../errors.js";
+import { RouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
   requireRequestContext,
   createRequestContext,
-  getLocationState,
 } from "../server/request-context.js";
-import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc";
 
-import type { RscPayload, CreateRSCHandlerOptions } from "./types.js";
+import type {
+  RscPayload,
+  CreateRSCHandlerOptions,
+  LoadSSRModule,
+  SSRModule,
+} from "./types.js";
 import {
   createResponseWithMergedHeaders,
-  createSimpleRedirectResponse,
+  finalizeResponse,
+  interceptRedirectForPartial,
+  buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import {
+  handleResponseRoute,
+  type ResponseRouteMatch,
+} from "./response-route-handler.js";
 import { generateNonce, nonce as nonceToken } from "./nonce.js";
 import { VERSION } from "@rangojs/router:version";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import { invokeOnError } from "../router/error-handling.js";
-import { createReverseFunction } from "../router/handler-context.js";
-import { contextGet, contextSet } from "../context-var.js";
-import { NOCACHE_SYMBOL } from "../cache/taint.js";
-import { traverseBack } from "../router/pattern-matching.js";
-import { createCacheScope } from "../cache/cache-scope.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import { getRouterContext } from "../router/router-context.js";
+import { resolveSink, safeEmit } from "../router/telemetry.js";
+import { contextSet } from "../context-var.js";
 import {
   hasCachedManifest,
   getRouteTrie,
@@ -44,12 +55,33 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
-import { createResponseErrorPayload } from "./response-error.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
-import { handleServerAction } from "./server-action.js";
+import {
+  executeServerAction,
+  revalidateAfterAction,
+  type ActionContinuation,
+} from "./server-action.js";
 import { handleLoaderFetch } from "./loader-fetch.js";
+import { checkRequestOrigin, type OriginCheckPhase } from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
+import {
+  withTimeout,
+  RouterTimeoutError,
+  createDefaultTimeoutResponse,
+  type TimeoutPhase,
+} from "../router/timeout.js";
+import {
+  createMetricsStore,
+  appendMetric,
+  buildMetricsTiming,
+} from "../router/metrics.js";
+import {
+  startSSRSetup,
+  getSSRSetup,
+  mayNeedSSR,
+  SSR_SETUP_VAR,
+} from "./ssr-setup.js";
 
 /**
  * Create an RSC request handler.
@@ -84,13 +116,6 @@ import { handleRscRendering } from "./rsc-rendering.js";
  * });
  * ```
  */
-// Only cache successful responses. Non-200 statuses (errors, redirects) are
-// not cached — notFound() produces 500 in response routes, and explicit
-// non-200 Responses are rare enough that caching them would be surprising.
-function isCacheableStatus(status: number): boolean {
-  return status === 200;
-}
-
 export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
@@ -108,18 +133,28 @@ export function createRSCHandler<
     decodeFormState,
   } = deps;
 
-  // Use provided loadSSRModule or default to vite RSC module loader
-  const loadSSRModule =
+  // Use provided loadSSRModule or default to vite RSC module loader.
+  // In production the SSR module is stable across requests, so memoize
+  // the dynamic import to avoid repeated module resolution overhead.
+  // In dev mode Vite may hot-reload the module, so skip memoization.
+  const rawLoadSSRModule: LoadSSRModule =
     options.loadSSRModule ??
     (() => import.meta.viteRsc.loadModule("ssr", "index"));
-
-  // Track errors already reported to onError to prevent double-reporting
-  // when errors are caught by a phase-specific handler and re-thrown.
-  const reportedErrors = new WeakSet<object>();
+  let _ssrModulePromise: Promise<SSRModule> | undefined;
+  const loadSSRModule: LoadSSRModule =
+    process.env.NODE_ENV === "production"
+      ? () =>
+          (_ssrModulePromise ??= rawLoadSSRModule().catch((err) => {
+            _ssrModulePromise = undefined;
+            throw err;
+          }))
+      : rawLoadSSRModule;
 
   /**
-   * Wrapper for invokeOnError that binds the router's onError callback.
-   * Uses the shared utility from router/error-handling.ts for consistent behavior.
+   * Per-request error reporter that deduplicates via the ALS request context.
+   *
+   * Uses the same _reportedErrors WeakSet as the router layer so errors
+   * that propagate across layers are only reported once per request.
    */
   function callOnError(
     error: unknown,
@@ -127,6 +162,7 @@ export function createRSCHandler<
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
     if (error != null && typeof error === "object") {
+      const reportedErrors = requireRequestContext()._reportedErrors;
       if (reportedErrors.has(error)) return;
       reportedErrors.add(error);
     }
@@ -143,6 +179,72 @@ export function createRSCHandler<
     return routeMap;
   }
 
+  /**
+   * Handle a timeout by reporting the error, emitting telemetry,
+   * and returning either the custom onTimeout response or a default 504.
+   */
+  async function handleTimeoutResponse(
+    request: Request,
+    env: TEnv,
+    url: URL,
+    phase: TimeoutPhase,
+    durationMs: number,
+    routeKey?: string,
+    actionId?: string,
+  ): Promise<Response> {
+    const timeoutError = new RouterTimeoutError(phase, durationMs);
+
+    callOnError(timeoutError, phase === "action" ? "action" : "handler", {
+      request,
+      url,
+      env,
+      routeKey,
+      actionId,
+      handledByBoundary: false,
+      metadata: { timeout: true, phase, durationMs },
+    });
+
+    try {
+      const routerCtx = getRouterContext();
+      if (routerCtx?.telemetry) {
+        safeEmit(resolveSink(routerCtx.telemetry), {
+          type: "request.timeout" as const,
+          timestamp: performance.now(),
+          requestId: routerCtx.requestId,
+          phase,
+          pathname: url.pathname,
+          routeKey,
+          actionId,
+          durationMs,
+          customHandler: !!router.onTimeout,
+        });
+      }
+    } catch {
+      // Router context may not be available
+    }
+
+    if (router.onTimeout) {
+      try {
+        return await router.onTimeout({
+          phase,
+          request,
+          url,
+          env,
+          routeKey,
+          actionId,
+          durationMs,
+        });
+      } catch (e) {
+        if (process.env.NODE_ENV !== "production") {
+          console.error("[RSC] onTimeout callback error:", e);
+        }
+        return createDefaultTimeoutResponse(phase);
+      }
+    }
+
+    return createDefaultTimeoutResponse(phase);
+  }
+
   /**
    * Build a 200 Flight response that carries a redirect URL and optional state.
    * Used when a partial/action request results in a redirect -- fetch
@@ -167,7 +269,8 @@ export function createRSCHandler<
     });
   }
 
-  // Bundle shared dependencies for extracted handler functions
+  // Bundle shared dependencies for extracted handler functions.
+  // callOnError reads from ALS so it's inherently per-request scoped.
   const handlerCtx: HandlerContext<TEnv> = {
     router,
     version,
@@ -181,6 +284,11 @@ export function createRSCHandler<
     callOnError,
     getRequiredRouteMap,
     createRedirectFlightResponse,
+    resolveStreamMode: async (request, env, url) => {
+      const resolver = router.ssr?.resolveStreaming;
+      if (!resolver) return "stream";
+      return resolver({ request, env, url });
+    },
   };
 
   return async function handler(
@@ -188,6 +296,11 @@ export function createRSCHandler<
     input: RouterRequestInput<TEnv> = {},
   ): Promise<Response> {
     const handlerStart = performance.now();
+    // Create the metrics store at handler start so handler:total has startTime=0
+    // and all metrics are relative to the request entry point.
+    const earlyMetricsStore = router.debugPerformance
+      ? createMetricsStore(true, handlerStart)
+      : undefined;
 
     const { env = {} as TEnv, vars: initialVars, ctx: executionCtx } = input;
 
@@ -287,9 +400,6 @@ export function createRSCHandler<
     }
     const manifestCacheDur = performance.now() - manifestCacheStart;
 
-    // Note: Route map for useHref() is loaded lazily via getGlobalRouteMap()
-    // This allows it to include all routes from lazy includes after manifest loading
-
     // Create unified request context with all methods
     // Includes: stub response, handle store, loader memoization, use(), cookies, headers, cache store
     // params starts empty, populated after route matching via setRequestContextParams
@@ -300,9 +410,27 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
     });
+    if (earlyMetricsStore) {
+      requestContext._debugPerformance = true;
+      requestContext._metricsStore = earlyMetricsStore;
+    }
+    // Wire background error reporting so "use cache" and other subsystems
+    // can surface non-fatal errors through the router's onError callback.
+    requestContext._reportBackgroundError = (
+      error: unknown,
+      category: string,
+    ) => {
+      callOnError(error, "cache", {
+        request,
+        url,
+        metadata: { category },
+      });
+    };
+
     const ctxCreateDur = performance.now() - ctxCreateStart;
 
     // Accumulate handler-level timing for Server-Timing header
@@ -331,6 +459,7 @@ export function createRSCHandler<
       };
 
       // Execute middleware chain if any, otherwise call core handler directly
+      let response: Response;
       if (matchedMiddleware.length > 0) {
         const mwResponse = await executeMiddleware(
           matchedMiddleware,
@@ -341,30 +470,60 @@ export function createRSCHandler<
           createReverseFunction(getRequiredRouteMap()),
         );
 
-        // If global middleware returned a redirect during a partial (SPA)
-        // request, intercept it. fetch auto-follows 3xx, so we must signal
-        // the redirect via our own mechanism instead.
-        // - With state: Flight payload (200) so location state survives.
-        // - Without state: 204 + X-RSC-Redirect header (lightweight).
-        const isPartial = url.searchParams.has("_rsc_partial");
-        const redirectUrl = mwResponse.headers.get("Location");
-        const isRedirect =
-          mwResponse.status >= 300 && mwResponse.status < 400 && redirectUrl;
-        if (isPartial && isRedirect) {
-          const locationState = getLocationState();
-          if (locationState) {
-            return createRedirectFlightResponse(
-              redirectUrl,
-              resolveLocationStateEntries(locationState),
-            );
-          }
-          return createSimpleRedirectResponse(redirectUrl);
+        if (
+          url.searchParams.has("_rsc_partial") ||
+          url.searchParams.has("_rsc_action")
+        ) {
+          const intercepted = interceptRedirectForPartial(
+            mwResponse,
+            createRedirectFlightResponse,
+          );
+          response = intercepted ?? finalizeResponse(mwResponse);
+        } else {
+          response = finalizeResponse(mwResponse);
         }
+      } else {
+        response = await coreHandler();
+      }
 
-        return mwResponse;
+      // Finalize metrics after all middleware (including post-next work)
+      // has completed so :post spans are captured in the timeline.
+      // Handler timing parts are always emitted (even without debug metrics)
+      // so non-debug requests still get bootstrap Server-Timing entries.
+      const handlerTimingArr: string[] = variables.__handlerTiming || [];
+      // Preserve any existing Server-Timing set by response routes or middleware
+      const existingTiming = response.headers.get("Server-Timing");
+      const timingParts = existingTiming
+        ? [existingTiming, ...handlerTimingArr]
+        : [...handlerTimingArr];
+
+      const metricsStore = requestContext._metricsStore;
+      if (metricsStore) {
+        // When the store was created at handler start (earlyMetricsStore),
+        // handler:total covers the full request. When ctx.debugPerformance()
+        // created the store mid-request, use its requestStart to avoid a
+        // negative startTime offset.
+        const totalStart = earlyMetricsStore
+          ? handlerStart
+          : metricsStore.requestStart;
+        appendMetric(
+          metricsStore,
+          "handler:total",
+          totalStart,
+          performance.now() - totalStart,
+        );
+        const metricsTiming = buildMetricsTiming(
+          request.method,
+          url.pathname,
+          metricsStore,
+        );
+        if (metricsTiming) timingParts.push(metricsTiming);
       }
 
-      return coreHandler();
+      const fullTiming = timingParts.join(", ");
+      if (fullTiming) response.headers.set("Server-Timing", fullTiming);
+
+      return response;
     });
   };
 
@@ -376,7 +535,6 @@ export function createRSCHandler<
     variables: Record<string, any>,
     nonce: string | undefined,
   ): Promise<Response> {
-    // First, check for route-level middleware
     const previewStart = performance.now();
     const preview = await router.previewMatch(request, { env });
     const previewDur = performance.now() - previewStart;
@@ -384,286 +542,224 @@ export function createRSCHandler<
     handlerTiming.push(`handler-preview-match;dur=${previewDur.toFixed(2)}`);
     // Response route short-circuit: skip entire RSC pipeline
     if (preview?.responseType && preview.handler) {
-      const isPartial = url.searchParams.has("_rsc_partial");
-
-      // Partial requests (client-side navigation) to response routes
-      // get X-RSC-Reload to trigger hard navigation in the browser
-      if (isPartial) {
-        const cleanUrl = new URL(url);
-        cleanUrl.searchParams.delete("_rsc_partial");
-        cleanUrl.searchParams.delete("_rsc_segments");
-        cleanUrl.searchParams.delete("_rsc_v");
-        cleanUrl.searchParams.delete("_rsc_stale");
-        cleanUrl.searchParams.delete("_rsc_action");
-        cleanUrl.searchParams.delete("_rsc_prev");
-
-        return createResponseWithMergedHeaders(null, {
-          status: 200,
-          headers: {
-            "X-RSC-Reload": cleanUrl.toString(),
-            "content-type": "text/x-component;charset=utf-8",
-          },
-        });
+      const responseOutcome = await withTimeout(
+        handleResponseRoute(
+          handlerCtx,
+          preview as ResponseRouteMatch,
+          request,
+          env,
+          url,
+          variables,
+        ),
+        router.timeouts.renderStartMs,
+        "render-start",
+      );
+      if (responseOutcome.timedOut) {
+        return handleTimeoutResponse(
+          request,
+          env,
+          url,
+          "render-start",
+          responseOutcome.durationMs,
+          preview?.routeKey,
+        );
       }
+      return responseOutcome.result;
+    }
 
-      // Build lightweight context for response handler
-      const reqCtx = requireRequestContext();
-      const responseHandlerCtx = {
+    // Kick off SSR module loading + stream mode resolution in parallel with
+    // segment resolution. Placed after the response-route short-circuit so
+    // response/mime routes never pay for SSR work.
+    if (mayNeedSSR(request, url)) {
+      variables[SSR_SETUP_VAR] = startSSRSetup(
+        handlerCtx,
         request,
-        params: preview.params || {},
         env,
-        searchParams: url.searchParams,
         url,
-        pathname: url.pathname,
-        href: (name: string, hrefParams?: Record<string, string>) => {
-          if (name.startsWith("/")) {
-            if (!hrefParams) return name;
-            return name.replace(/:([^/]+)/g, (_, key) => {
-              const value = hrefParams[key];
-              if (value === undefined)
-                throw new Error(`Missing param "${key}" for path "${name}"`);
-              return encodeURIComponent(value);
+        router.debugPerformance
+          ? () => requireRequestContext()._metricsStore
+          : undefined,
+      );
+    }
+
+    const routeReverse = createReverseFunction(getRequiredRouteMap());
+
+    const isAction =
+      request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+    const isLoaderFetch = url.searchParams.has("_rsc_loader");
+    const actionId =
+      request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
+
+    // Origin guard: reject cross-origin actions, loader fetches, and
+    // PE form submissions before any execution. Regular page navigations
+    // (GET without _rsc_loader/_rsc_action) are not affected.
+    const originPhase: OriginCheckPhase | null = isAction
+      ? "action"
+      : isLoaderFetch
+        ? "loader"
+        : request.method === "POST"
+          ? "pe-form"
+          : null;
+    if (originPhase) {
+      const originResult = await checkRequestOrigin(
+        request,
+        url,
+        router.originCheck,
+        env,
+        router.id,
+        originPhase,
+      );
+      if (originResult) {
+        const originError = new Error(
+          `Origin check rejected: ${request.headers.get("origin") ?? "none"} vs ${request.headers.get("host") ?? "none"}`,
+        );
+        originError.name = "OriginCheckError";
+
+        callOnError(originError, "origin", {
+          request,
+          url,
+          env,
+          handledByBoundary: false,
+          metadata: {
+            phase: originPhase,
+            origin: request.headers.get("origin"),
+            host: request.headers.get("host"),
+          },
+        });
+
+        try {
+          const routerCtx = getRouterContext();
+          if (routerCtx?.telemetry) {
+            safeEmit(resolveSink(routerCtx.telemetry), {
+              type: "request.origin-rejected" as const,
+              timestamp: performance.now(),
+              requestId: routerCtx.requestId,
+              method: request.method,
+              pathname: url.pathname,
+              phase: originPhase,
+              origin: request.headers.get("origin"),
+              host: request.headers.get("host"),
             });
           }
-          return name;
-        },
-        get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
-        header: (name: string, value: string) => reqCtx.header(name, value),
-        setCookie: (name: string, value: string, options?: any) =>
-          reqCtx.setCookie(name, value, options),
-        _responseType: preview.responseType,
-      };
-      // Brand with taint symbol so "use cache" detects it as request-scoped
-      // and extracts route-identifying properties (params, pathname, _responseType)
-      (responseHandlerCtx as any)[NOCACHE_SYMBOL] = true;
-
-      // Call handler directly, wrapped by route middleware if present
-      const callHandler = async () => {
-        // JSON response routes: wrap in { data } / { error } envelope
-        if (preview.responseType === "json") {
-          const errorCtx = { request, url, env };
-          try {
-            const result = await (preview.handler as Function)(
-              responseHandlerCtx,
-            );
-            if (result instanceof Response) {
-              const mergedHeaders: Record<string, string> = {};
-              result.headers.forEach((value, key) => {
-                mergedHeaders[key] = value;
-              });
-              return createResponseWithMergedHeaders(result.body, {
-                status: result.status,
-                headers: mergedHeaders,
-              });
-            }
-            return createResponseWithMergedHeaders(
-              JSON.stringify({ data: result }),
-              {
-                status: 200,
-                headers: { "content-type": "application/json;charset=utf-8" },
-              },
-            );
-          } catch (error) {
-            callOnError(error, "handler", errorCtx);
-            const isDev = process.env.NODE_ENV !== "production";
-            const status = error instanceof RouterError ? error.status : 500;
-            return createResponseWithMergedHeaders(
-              JSON.stringify({
-                error: createResponseErrorPayload(error, isDev),
-              }),
-              {
-                status,
-                headers: { "content-type": "application/json;charset=utf-8" },
-              },
-            );
-          }
+        } catch {
+          // Router context may not be available
         }
 
-        // Non-JSON response routes: catch errors and return plain Response
-        const errorCtx = { request, url, env };
-        try {
-          const result = await (preview.handler as Function)(
-            responseHandlerCtx,
-          );
+        return originResult;
+      }
+    }
 
-          if (result instanceof Response) {
-            // Handler returned a Response directly -- pass through
-            const mergedHeaders: Record<string, string> = {};
-            result.headers.forEach((value, key) => {
-              mergedHeaders[key] = value;
-            });
-            return createResponseWithMergedHeaders(result.body, {
-              status: result.status,
-              headers: mergedHeaders,
-            });
-          }
+    // Get handle store from request context
+    const handleStore = requireRequestContext()._handleStore;
 
-          // Auto-wrap based on response type tag
-          switch (preview.responseType) {
-            case "text":
-              return createResponseWithMergedHeaders(String(result), {
-                status: 200,
-                headers: { "content-type": "text/plain;charset=utf-8" },
-              });
-            case "html":
-              return createResponseWithMergedHeaders(String(result), {
-                status: 200,
-                headers: { "content-type": "text/html;charset=utf-8" },
-              });
-            case "xml":
-              return createResponseWithMergedHeaders(String(result), {
-                status: 200,
-                headers: { "content-type": "application/xml;charset=utf-8" },
-              });
-            case "md":
-              return createResponseWithMergedHeaders(String(result), {
-                status: 200,
-                headers: { "content-type": "text/markdown;charset=utf-8" },
-              });
-            default:
-              // image, stream, any -- must return Response
-              throw new Error(
-                `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
-              );
-          }
-        } catch (error) {
-          callOnError(error, "handler", errorCtx);
-          const isDev = process.env.NODE_ENV !== "production";
-          const status = error instanceof RouterError ? error.status : 500;
-          const message =
-            error instanceof RouterError
-              ? error.message
-              : isDev && error instanceof Error
-                ? error.message
-                : "Internal Server Error";
-          return createResponseWithMergedHeaders(message, {
-            status,
-            headers: { "content-type": "text/plain;charset=utf-8" },
+    // Wire up error reporting for late streaming-handle failures
+    // (LateHandlePushError: handle pushed after stream completion).
+    // Without this, these errors are only caught by React's error boundary
+    // and never reach the router's onError callback or telemetry.
+    handleStore.onError = (error: Error) => {
+      const reqCtx = requireRequestContext();
+      callOnError(error, "handler", {
+        request,
+        url,
+        routeKey: reqCtx._routeName,
+        params: reqCtx.params as Record<string, string>,
+        handledByBoundary: true,
+      });
+      try {
+        const routerCtx = getRouterContext();
+        if (routerCtx?.telemetry) {
+          safeEmit(resolveSink(routerCtx.telemetry), {
+            type: "handler.error" as const,
+            timestamp: performance.now(),
+            requestId: routerCtx.requestId,
+            error,
+            handledByBoundary: true,
+            pathname: url.pathname,
+            routeKey: reqCtx._routeName,
+            params: reqCtx.params as Record<string, string>,
           });
         }
-      };
+      } catch {
+        // Router context may not be available (e.g. prerender path)
+      }
+    };
 
-      // Wrap callHandler to append Vary: Accept on content-negotiated responses
-      const callHandlerWithVary = async () => {
-        const response = await callHandler();
-        if (preview.negotiated) {
-          response.headers.append("Vary", "Accept");
-        }
-        return response;
-      };
+    // Set route params early so all execution paths can access ctx.params.
+    if (preview?.params) {
+      setRequestContextParams(preview.params, preview.routeKey);
+    }
 
-      // Wrap with response caching if cache() config is present
-      const executeHandler = async () => {
-        if (preview.routeMiddleware && preview.routeMiddleware.length > 0) {
-          const middlewareEntries = preview.routeMiddleware.map((mw) => ({
-            entry: {
-              pattern: null,
-              regex: null,
-              paramNames: [],
-              handler: mw.handler,
-              mountPrefix: null,
-            },
-            params: mw.params,
-          }));
-          return executeMiddleware(
-            middlewareEntries,
+    // Progressive enhancement runs before the normal action/render paths.
+    // Route middleware wraps the PE re-render so handlers see the same
+    // context variables regardless of JS/no-JS transport.
+    const progressiveResult = await handleProgressiveEnhancement(
+      handlerCtx,
+      request,
+      env,
+      url,
+      isAction,
+      handleStore,
+      nonce,
+      {
+        routeMiddleware: preview?.routeMiddleware,
+        variables,
+        routeReverse,
+      },
+    );
+    if (progressiveResult) {
+      return progressiveResult;
+    }
+
+    // --- Action execution: runs BEFORE route middleware ---
+    // Route middleware wraps rendering only. For actions, the action runs
+    // first in the global middleware context, then route middleware wraps
+    // the revalidation pass (identical to a normal render).
+    let actionContinuation: ActionContinuation | undefined;
+    if (isAction && actionId) {
+      try {
+        const actionOutcome = await withTimeout(
+          executeServerAction(
+            handlerCtx,
             request,
             env,
-            variables,
-            callHandlerWithVary,
-            createReverseFunction(getRequiredRouteMap()),
+            url,
+            actionId,
+            handleStore,
+          ),
+          router.timeouts.actionMs,
+          "action",
+        );
+        if (actionOutcome.timedOut) {
+          return handleTimeoutResponse(
+            request,
+            env,
+            url,
+            "action",
+            actionOutcome.durationMs,
+            preview?.routeKey,
+            actionId,
           );
         }
-        return callHandlerWithVary();
-      };
-
-      // Resolve cache config from entry tree (same pattern as match-api.ts)
-      if (preview.manifestEntry) {
-        const entries = [...traverseBack(preview.manifestEntry)];
-        let cacheScope: ReturnType<typeof createCacheScope> = null;
-        for (const entry of entries) {
-          if (entry.cache) {
-            cacheScope = createCacheScope(entry.cache, cacheScope);
-          }
-        }
-
-        if (cacheScope?.enabled) {
-          const store = cacheScope.getStore() ?? reqCtx._cacheStore;
-          if (store?.getResponse && store?.putResponse) {
-            // Build cache key with response:{type}: prefix to avoid collision
-            // with segment keys and differentiate between response types
-            let cacheKey = `response:${preview.responseType}:${url.pathname}`;
-            if (store.keyGenerator) {
-              try {
-                cacheKey = await store.keyGenerator(reqCtx, cacheKey);
-              } catch {
-                // Fall back to default key on keyGenerator failure
-              }
-            }
-
-            try {
-              const cached = await store.getResponse(cacheKey);
-
-              if (cached && isCacheableStatus(cached.response.status)) {
-                if (!cached.shouldRevalidate) {
-                  // Fresh hit
-                  return cached.response;
-                }
-
-                // Stale hit (SWR) - return cached, revalidate in background
-                reqCtx.waitUntil(async () => {
-                  try {
-                    const fresh = await executeHandler();
-                    if (isCacheableStatus(fresh.status)) {
-                      await store.putResponse!(
-                        cacheKey,
-                        fresh,
-                        cacheScope!.ttl,
-                        cacheScope!.swr,
-                      );
-                    }
-                  } catch (error) {
-                    console.error(
-                      `[ResponseCache] Revalidation failed:`,
-                      error,
-                    );
-                  }
-                });
-
-                return cached.response;
-              }
-            } catch (error) {
-              console.error(`[ResponseCache] Cache lookup failed:`, error);
-            }
-
-            // Cache miss - execute handler and cache the result
-            const response = await executeHandler();
-
-            if (isCacheableStatus(response.status)) {
-              reqCtx.waitUntil(async () => {
-                try {
-                  await store.putResponse!(
-                    cacheKey,
-                    response.clone(),
-                    cacheScope!.ttl,
-                    cacheScope!.swr,
-                  );
-                } catch (error) {
-                  console.error(`[ResponseCache] Cache write failed:`, error);
-                }
-              });
-            }
-
-            return response;
-          }
-        }
+        const result = actionOutcome.result;
+        // Response means redirect or error boundary — done.
+        if (result instanceof Response) return result;
+        actionContinuation = result;
+      } catch (error) {
+        callOnError(error, "action", {
+          request,
+          url,
+          env,
+          actionId,
+          handledByBoundary: false,
+        });
+        console.error(`[RSC] Action error:`, error);
+        throw error;
       }
-
-      return executeHandler();
     }
 
-    // Wrap RSC handler to append Vary: Accept on content-negotiated routes
-    const rscHandler = async () => {
+    // --- Rendering (action revalidation or navigation) ---
+    // Route middleware wraps this — same code path for both cases.
+    const renderHandler = async () => {
       const response = await coreRequestHandlerInner(
         request,
         env,
@@ -672,6 +768,8 @@ export function createRSCHandler<
         nonce,
         preview?.params,
         preview?.routeKey,
+        handleStore,
+        actionContinuation,
       );
       if (preview?.negotiated) {
         response.headers.append("Vary", "Accept");
@@ -679,57 +777,58 @@ export function createRSCHandler<
       return response;
     };
 
-    if (preview?.routeMiddleware && preview.routeMiddleware.length > 0) {
-      // Convert route middleware to app middleware format for execution
-      const middlewareEntries = preview.routeMiddleware.map((mw) => ({
-        entry: {
-          pattern: null,
-          regex: null,
-          paramNames: [],
-          handler: mw.handler,
-          mountPrefix: null,
-        },
-        params: mw.params,
-      }));
-
-      // Execute route middleware wrapping the actual request handling
-      const mwResponse = await executeMiddleware(
-        middlewareEntries,
-        request,
-        env,
-        variables,
-        rscHandler,
-        createReverseFunction(getRequiredRouteMap()),
-      );
+    // Wrap the render path (with or without route middleware) in a
+    // renderStartMs timeout so slow renders are caught before output.
+    const executeRender = async (): Promise<Response> => {
+      if (preview?.routeMiddleware && preview.routeMiddleware.length > 0) {
+        const mwResponse = await executeMiddleware(
+          buildRouteMiddlewareEntries<TEnv>(preview.routeMiddleware),
+          request,
+          env,
+          variables,
+          renderHandler,
+          routeReverse,
+        );
 
-      // If route middleware returned a redirect during a partial (SPA)
-      // request, intercept it. fetch auto-follows 3xx, so we must signal
-      // the redirect via our own mechanism instead.
-      // - With state: Flight payload (200) so location state survives.
-      // - Without state: 204 + X-RSC-Redirect header (lightweight).
-      const isPartial = url.searchParams.has("_rsc_partial");
-      const mwRedirectUrl = mwResponse.headers.get("Location");
-      const isMwRedirect =
-        mwResponse.status >= 300 && mwResponse.status < 400 && mwRedirectUrl;
-      if (isPartial && isMwRedirect) {
-        const locationState = getLocationState();
-        if (locationState) {
-          return createRedirectFlightResponse(
-            mwRedirectUrl,
-            resolveLocationStateEntries(locationState),
+        if (
+          url.searchParams.has("_rsc_partial") ||
+          url.searchParams.has("_rsc_action")
+        ) {
+          const intercepted = interceptRedirectForPartial(
+            mwResponse,
+            createRedirectFlightResponse,
           );
+          if (intercepted) return intercepted;
         }
-        return createSimpleRedirectResponse(mwRedirectUrl);
+
+        return finalizeResponse(mwResponse);
       }
 
-      return mwResponse;
-    }
+      // No route middleware, proceed directly
+      return renderHandler();
+    };
 
-    // No route middleware, proceed directly
-    return rscHandler();
+    const renderOutcome = await withTimeout(
+      executeRender(),
+      router.timeouts.renderStartMs,
+      "render-start",
+    );
+    if (renderOutcome.timedOut) {
+      return handleTimeoutResponse(
+        request,
+        env,
+        url,
+        "render-start",
+        renderOutcome.durationMs,
+        preview?.routeKey,
+      );
+    }
+    return renderOutcome.result;
   }
 
-  // Inner request handler (actual RSC logic, wrapped by route middleware if any)
+  // Inner request handler: rendering logic wrapped by route middleware.
+  // Handles action revalidation (when actionContinuation is present),
+  // loader fetches, and regular RSC rendering.
   async function coreRequestHandlerInner(
     request: Request,
     env: TEnv,
@@ -738,12 +837,12 @@ export function createRSCHandler<
     nonce: string | undefined,
     routeParams?: Record<string, string>,
     routeKey?: string,
+    handleStore?: ReturnType<typeof requireRequestContext>["_handleStore"],
+    actionContinuation?: ActionContinuation,
   ): Promise<Response> {
     const isPartial = url.searchParams.has("_rsc_partial");
     const isAction =
       request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
-    const actionId =
-      request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
 
     // Version mismatch detection - client may have stale code after HMR/deployment
     // If versions don't match, tell the client to reload
@@ -753,19 +852,10 @@ export function createRSCHandler<
         `[RSC] Version mismatch: client=${clientVersion}, server=${version}. Forcing reload.`,
       );
 
-      // Clean URL by removing RSC params
-      const cleanUrl = new URL(url);
-      cleanUrl.searchParams.delete("_rsc_partial");
-      cleanUrl.searchParams.delete("_rsc_segments");
-      cleanUrl.searchParams.delete("_rsc_v");
-      cleanUrl.searchParams.delete("_rsc_stale");
-      cleanUrl.searchParams.delete("_rsc_action");
-      cleanUrl.searchParams.delete("_rsc_prev");
-
       // For actions, reload current page (referer) if same origin.
       // For navigation, load the target URL.
       // Validate referer origin to prevent open redirect via crafted header.
-      let reloadUrl = cleanUrl.toString();
+      let reloadUrl = stripInternalParams(url).toString();
       if (isAction) {
         const referer = request.headers.get("referer");
         if (referer) {
@@ -818,57 +908,27 @@ export function createRSCHandler<
       );
     }
 
-    // Get handle store from request context (created at start of request)
-    const handleStore = requireRequestContext()._handleStore;
+    const store = handleStore ?? requireRequestContext()._handleStore;
 
     try {
-      // Set route params early so all execution paths (progressive enhancement,
-      // server actions, loader fetches) can access ctx.params via getRequestContext().
-      // Previously this was only done for JS actions, leaving PE actions with empty params.
+      // Route params were already set in coreRequestHandler, but set again
+      // for callers that enter coreRequestHandlerInner directly.
       if (routeParams) {
         setRequestContextParams(routeParams, routeKey);
       }
 
       // ============================================================================
-      // PROGRESSIVE ENHANCEMENT: No-JS Form Submissions
+      // ACTION REVALIDATION (action already executed, revalidate segments)
       // ============================================================================
-      const progressiveResult = await handleProgressiveEnhancement(
-        handlerCtx,
-        request,
-        env,
-        url,
-        isAction,
-        handleStore,
-        nonce,
-      );
-      if (progressiveResult) {
-        return progressiveResult;
-      }
-
-      // ============================================================================
-      // SERVER ACTION EXECUTION (JavaScript-enabled client)
-      // ============================================================================
-      if (isAction && actionId) {
-        try {
-          return await handleServerAction(
-            handlerCtx,
-            request,
-            env,
-            url,
-            actionId,
-            handleStore,
-          );
-        } catch (error) {
-          callOnError(error, "action", {
-            request,
-            url,
-            env,
-            actionId,
-            handledByBoundary: false,
-          });
-          console.error(`[RSC] Action error:`, error);
-          throw error;
-        }
+      if (actionContinuation) {
+        return await revalidateAfterAction(
+          handlerCtx,
+          request,
+          env,
+          url,
+          store,
+          actionContinuation,
+        );
       }
 
       // ============================================================================
@@ -896,7 +956,7 @@ export function createRSCHandler<
         env,
         url,
         isPartial,
-        handleStore,
+        store,
         nonce,
       );
     } catch (error) {
@@ -912,39 +972,21 @@ export function createRSCHandler<
             `[RSC] Route handler at ${url.pathname} returned a Response during client-side navigation. ` +
               `Falling back to hard navigation. Use data-external on the <Link> to avoid the extra round-trip.`,
           );
-          const cleanUrl = new URL(url);
-          cleanUrl.searchParams.delete("_rsc_partial");
-          cleanUrl.searchParams.delete("_rsc_segments");
-          cleanUrl.searchParams.delete("_rsc_v");
-          cleanUrl.searchParams.delete("_rsc_stale");
-          cleanUrl.searchParams.delete("_rsc_action");
-          cleanUrl.searchParams.delete("_rsc_prev");
           return createResponseWithMergedHeaders(null, {
             status: 200,
             headers: {
-              "X-RSC-Reload": cleanUrl.toString(),
+              "X-RSC-Reload": stripInternalParams(url).toString(),
               "content-type": "text/x-component;charset=utf-8",
             },
           });
         }
 
-        // For partial requests: intercept redirects. HTTP 3xx redirects are
-        // auto-followed by fetch, which would hit the target URL without
-        // _rsc_partial and render a full HTML page the client can't parse.
-        // - With state: Flight payload (200) so location state survives.
-        // - Without state: 204 + X-RSC-Redirect header (lightweight).
-        const redirectUrl = error.headers.get("Location");
-        const isRedirect =
-          error.status >= 300 && error.status < 400 && redirectUrl;
-        if (isPartial && isRedirect) {
-          const locationState = getLocationState();
-          if (locationState) {
-            return createRedirectFlightResponse(
-              redirectUrl,
-              resolveLocationStateEntries(locationState),
-            );
-          }
-          return createSimpleRedirectResponse(redirectUrl);
+        if (isPartial) {
+          const intercepted = interceptRedirectForPartial(
+            error,
+            createRedirectFlightResponse,
+          );
+          if (intercepted) return intercepted;
         }
 
         return error;
@@ -988,7 +1030,7 @@ export function createRSCHandler<
             diff: [],
             isPartial: false,
             rootLayout: router.rootLayout,
-            handles: handleStore.stream(),
+            handles: store.stream(),
             version,
             themeConfig: router.themeConfig,
             warmupEnabled: router.warmupEnabled,
@@ -1014,9 +1056,18 @@ export function createRSCHandler<
           });
         }
 
-        // Delegate to SSR for HTML response
-        const ssrModule = await loadSSRModule();
-        const htmlStream = await ssrModule.renderHTML(rscStream, { nonce });
+        // Delegate to SSR for HTML response (reuse early setup if available)
+        const [ssrModule, streamMode] = await getSSRSetup(
+          handlerCtx,
+          request,
+          env,
+          url,
+          requireRequestContext()._metricsStore,
+        );
+        const htmlStream = await ssrModule.renderHTML(rscStream, {
+          nonce,
+          streamMode,
+        });
 
         return createResponseWithMergedHeaders(htmlStream, {
           status: 404,