@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1c0bdfad

package/src/rsc/handler.ts

@@ -8,23 +8,33 @@
  */
 
 import { createElement } from "react";
-import { RouteNotFoundError } from "../errors.js";
+import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
-  requireRequestContext,
+  getRequestContext,
+  _getRequestContext,
   createRequestContext,
 } from "../server/request-context.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,
   finalizeResponse,
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { guardOutgoingRedirect } from "./redirect-guard.js";
+import {
+  isWebSocketUpgradeResponse,
+  appendVaryAccept,
+} from "../response-utils.js";
 import {
   handleResponseRoute,
   type ResponseRouteMatch,
@@ -38,8 +48,6 @@ 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,
@@ -50,6 +58,8 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
+import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
 import {
@@ -58,7 +68,10 @@ import {
   type ActionContinuation,
 } from "./server-action.js";
 import { handleLoaderFetch } from "./loader-fetch.js";
-import { checkRequestOrigin, type OriginCheckPhase } from "./origin-guard.js";
+import {
+  checkRequestOrigin,
+  ORIGIN_CHECK_PHASE_BY_MODE,
+} from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
 import {
   withTimeout,
@@ -66,6 +79,24 @@ import {
   createDefaultTimeoutResponse,
   type TimeoutPhase,
 } from "../router/timeout.js";
+import {
+  createMetricsStore,
+  appendMetric,
+  buildMetricsTiming,
+} from "../router/metrics.js";
+import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
+import {
+  startSSRSetup,
+  getSSRSetup,
+  mayNeedSSR,
+  isRscRequest,
+  SSR_SETUP_VAR,
+} from "./ssr-setup.js";
+import {
+  classifyRequest,
+  type RequestPlan,
+  type ExecutableRequestPlan,
+} from "../router/request-classification.js";
 
 /**
  * Create an RSC request handler.
@@ -100,12 +131,35 @@ import {
  * });
  * ```
  */
+
+/**
+ * Response that tells the client to do a full document navigation. Shared by
+ * the terminal reload plans (version-mismatch and app-switch): an empty 200
+ * carrying X-RSC-Reload, which the client turns into window.location.href.
+ */
+function createReloadResponse(reloadUrl: string) {
+  return createResponseWithMergedHeaders(null, {
+    status: 200,
+    headers: {
+      "X-RSC-Reload": reloadUrl,
+      "content-type": "text/x-component;charset=utf-8",
+    },
+  });
+}
+
 export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, version = VERSION, nonce: nonceProvider } = options;
 
+  // Handler-owned registry of explicit per-scope stores from cache({ store }).
+  // Lives in the closure so it is scoped per handler (multi-router deployments
+  // get separate registries) and accumulates every explicit store this handler
+  // resolves across requests. updateTag()/revalidateTag() iterate it to reach
+  // stores not covered by the app-level ctx._cacheStore.
+  const explicitTaggedStores = new Set<SegmentCacheStore>();
+
   // Use provided deps or default to @vitejs/plugin-rsc/rsc exports
   const deps = options.deps ?? rscDeps;
   const {
@@ -117,10 +171,22 @@ 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"));
+  let _ssrModulePromise: Promise<SSRModule> | undefined;
+  const loadSSRModule: LoadSSRModule =
+    process.env.NODE_ENV === "production"
+      ? () =>
+          (_ssrModulePromise ??= rawLoadSSRModule().catch((err) => {
+            _ssrModulePromise = undefined;
+            throw err;
+          }))
+      : rawLoadSSRModule;
 
   /**
    * Per-request error reporter that deduplicates via the ALS request context.
@@ -133,10 +199,13 @@ export function createRSCHandler<
     phase: ErrorPhase,
     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);
+    // Guard: abort signal handlers fire asynchronously outside the ALS
+    // request scope, so the context may be gone. Skip dedup in that
+    // case — the error is from a cancelled stream, not a real failure.
+    const reqCtx = _getRequestContext();
+    if (error != null && typeof error === "object" && reqCtx) {
+      if (reqCtx._reportedErrors.has(error)) return;
+      reqCtx._reportedErrors.add(error);
     }
     invokeOnError(router.onError, error, phase, context, "RSC");
   }
@@ -176,24 +245,16 @@ export function createRSCHandler<
       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
-    }
+    observeEvent({
+      type: "request.timeout",
+      timestamp: performance.now(),
+      phase,
+      pathname: url.pathname,
+      routeKey,
+      actionId,
+      durationMs,
+      customHandler: !!router.onTimeout,
+    });
 
     if (router.onTimeout) {
       try {
@@ -225,16 +286,27 @@ export function createRSCHandler<
   function createRedirectFlightResponse(
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ): Response {
     const redirectPayload: RscPayload = {
       metadata: {
         pathname: redirectUrl,
         segments: [],
-        redirect: { url: redirectUrl },
+        redirect: { url: redirectUrl, ...(external && { external: true }) },
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload);
+    const rscStream = renderToReadableStream<RscPayload>(redirectPayload, {
+      onError: (error: unknown) => {
+        const reqCtx = _getRequestContext<TEnv>();
+        if (!reqCtx) return;
+        callOnError(error, "rendering", {
+          request: reqCtx.request,
+          url: reqCtx.url,
+          env: reqCtx.env,
+        });
+      },
+    });
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -268,6 +340,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;
 
@@ -310,7 +387,7 @@ export function createRSCHandler<
     // Resolve cache store configuration
     // Priority: options.cache (handler override) > router.cache (router default)
     // Store is enabled only if: config provided, enabled, and no ?__no_cache query param
-    let cacheStore = undefined;
+    let cacheStore: SegmentCacheStore | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
       const cacheConfig =
@@ -377,15 +454,22 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
+      stateCookieName: router.resolvedStateCookieName,
+      version,
     });
+    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,
+      category: CacheErrorCategory,
     ) => {
       callOnError(error, "cache", {
         request,
@@ -415,42 +499,112 @@ export function createRSCHandler<
     // - Server components during rendering
     // - Error boundaries
     // - Streaming
-    return runWithRequestContext(requestContext, async () => {
-      // Core handler logic (wrapped by middleware)
-      const coreHandler = async (): Promise<Response> => {
-        return coreRequestHandler(request, env, url, variables, nonce);
-      };
+    // Store basename on request context (scoped per-request via existing ALS)
+    requestContext._basename = router.basename;
+
+    // Resolved span tracing for this request (read at each traced phase).
+    requestContext._tracing = router.tracing;
+
+    // The "rango.request" span is opened inside the request context so the
+    // Cloudflare runner can read executionContext.tracing, and so every nested
+    // phase span (and the platform's automatic KV/D1/fetch spans) nests under
+    // it. Construction-bound: the span ends when the Response is built, never
+    // wrapping the streamed body. metric:false — handler:total is metered
+    // directly below (a grand total incl. the pre-context bootstrap timings).
+    // When tracing is off this is a direct pass-through.
+    return runWithRequestContext(requestContext, () =>
+      observePhase(PHASES.request, async (span) => {
+        span.setAttribute("http.method", request.method);
+        // The matched route template is not known until match() runs later, so
+        // emit the concrete path as url.path (low-level), NOT http.route — the
+        // latter is reserved for the low-cardinality template (OTel convention).
+        span.setAttribute("url.path", url.pathname);
+
+        // Core handler logic (wrapped by middleware)
+        const coreHandler = async (): Promise<Response> => {
+          return coreRequestHandler(request, env, url, variables, nonce);
+        };
 
-      // Execute middleware chain if any, otherwise call core handler directly
-      if (matchedMiddleware.length > 0) {
-        const mwResponse = await executeMiddleware(
-          matchedMiddleware,
-          request,
-          env,
-          variables,
-          coreHandler,
-          createReverseFunction(getRequiredRouteMap()),
-        );
+        // Execute middleware chain if any, otherwise call core handler directly
+        let response: Response;
+        if (matchedMiddleware.length > 0) {
+          const mwResponse = await executeMiddleware(
+            matchedMiddleware,
+            request,
+            env,
+            variables,
+            coreHandler,
+            createReverseFunction(getRequiredRouteMap()),
+          );
 
-        if (
-          url.searchParams.has("_rsc_partial") ||
-          url.searchParams.has("_rsc_action")
-        ) {
-          const intercepted = interceptRedirectForPartial(
-            mwResponse,
-            createRedirectFlightResponse,
+          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();
+        }
+
+        // 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,
           );
-          if (intercepted) return intercepted;
+          const metricsTiming = buildMetricsTiming(
+            request.method,
+            url.pathname,
+            metricsStore,
+          );
+          if (metricsTiming) timingParts.push(metricsTiming);
         }
 
-        return finalizeResponse(mwResponse);
-      }
+        const fullTiming = timingParts.join(", ");
+        if (fullTiming && !isWebSocketUpgradeResponse(response)) {
+          response.headers.set("Server-Timing", fullTiming);
+        }
 
-      return coreHandler();
-    });
+        // Single open-redirect chokepoint: every response (PE, full-page,
+        // middleware short-circuit, response-route) funnels through here, so
+        // guarding browser-followed (3xx) redirects once covers them all and any
+        // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
+        // through untouched (validated client-side instead).
+        return guardOutgoingRedirect(response, url.origin, router.basename);
+      }),
+    );
   };
 
-  // Core request handling logic (separated for middleware wrapping)
+  // Core request handling logic (separated for middleware wrapping).
+  // Uses the classify → execute model: classifyRequest produces a RequestPlan,
+  // then execution dispatches on the plan mode.
   async function coreRequestHandler(
     request: Request,
     env: TEnv,
@@ -458,56 +612,103 @@ export function createRSCHandler<
     variables: Record<string, any>,
     nonce: string | undefined,
   ): Promise<Response> {
-    const previewStart = performance.now();
-    const preview = await router.previewMatch(request, { env });
-    const previewDur = performance.now() - previewStart;
     const handlerTiming: string[] = variables.__handlerTiming || [];
-    handlerTiming.push(`handler-preview-match;dur=${previewDur.toFixed(2)}`);
-    // Response route short-circuit: skip entire RSC pipeline
-    if (preview?.responseType && preview.handler) {
-      const responseOutcome = await withTimeout(
-        handleResponseRoute(
-          handlerCtx,
-          preview as ResponseRouteMatch,
-          request,
-          env,
-          url,
-          variables,
+
+    // Debug manifest endpoint: handled before classification since it
+    // doesn't need a route match and needs trie access from the closure.
+    const isDev = process.env.NODE_ENV !== "production";
+    if (
+      url.searchParams.has("__debug_manifest") &&
+      (isDev || router.allowDebugManifest)
+    ) {
+      const trie = getRouterTrie(router.id) ?? getRouteTrie();
+      const routeManifest = getRequiredRouteMap();
+      const { extractAncestryFromTrie } =
+        await import("../build/route-trie.js");
+      return new Response(
+        JSON.stringify(
+          {
+            routerId: router.id,
+            routeManifest,
+            routeAncestry: trie ? extractAncestryFromTrie(trie) : {},
+            routeTrie: trie,
+            precomputedEntries: getPrecomputedEntries(),
+          },
+          null,
+          2,
         ),
-        router.timeouts.renderStartMs,
-        "render-start",
+        {
+          headers: { "Content-Type": "application/json" },
+        },
       );
-      if (responseOutcome.timedOut) {
-        return handleTimeoutResponse(
-          request,
-          env,
-          url,
-          "render-start",
-          responseOutcome.durationMs,
-          preview?.routeKey,
-        );
+    }
+
+    // ---- 1. Classify ----
+    // classifyRequest may throw RouteNotFoundError for unknown routes.
+    // In that case, fall through to a full-render plan so the pipeline
+    // can render the 404 page via the existing error handling path.
+    const classifyStart = performance.now();
+    let plan: RequestPlan<TEnv>;
+    try {
+      plan = await classifyRequest<TEnv>(request, url, {
+        findMatch: router.findMatch,
+        routerVersion: version,
+        routerId: router.id,
+      });
+    } catch (error) {
+      if (isRouteNotFoundError(error)) {
+        // Let the render path handle 404 — match()/matchPartial() will
+        // re-throw RouteNotFoundError and the catch block in
+        // executeRenderWithMiddleware renders the not-found page.
+        plan = {
+          mode: "full-render",
+          route: {
+            matched: null as any,
+            manifestEntry: null as any,
+            entries: [],
+            routeKey: "",
+            localRouteName: "",
+            params: {},
+            routeMiddleware: [],
+            cacheScope: null,
+            isPassthrough: false,
+          },
+          negotiated: false,
+        };
+      } else {
+        throw error;
+      }
+    }
+    const classifyDur = performance.now() - classifyStart;
+    handlerTiming.push(`handler-classify;dur=${classifyDur.toFixed(2)}`);
+
+    // ---- 2. Terminal plans (no execution needed) ----
+    if (plan.mode === "redirect") {
+      // Redirects are handled by the pipeline (match/matchPartial),
+      // but for partial requests we short-circuit with a Flight redirect.
+      if (url.searchParams.has("_rsc_partial")) {
+        return createRedirectFlightResponse(plan.redirectUrl);
       }
-      return responseOutcome.result;
+      // Full requests: let the pipeline handle the redirect via match()
+      // which returns { redirect: url }. Fall through to full-render.
     }
 
-    const routeReverse = createReverseFunction(getRequiredRouteMap());
+    if (plan.mode === "version-mismatch") {
+      console.log(
+        `[RSC] Version mismatch: client=${url.searchParams.get("_rsc_v")}, server=${version}. Forcing reload.`,
+      );
+      return createReloadResponse(plan.reloadUrl);
+    }
+
+    if (plan.mode === "app-switch") {
+      // Cross-app SPA navigation crossed a host-router app boundary. Force a
+      // real document navigation so the target app's document is re-established
+      // (stylesheets, theme, warmup, prefetch-TTL). See request-classification.
+      return createReloadResponse(plan.reloadUrl);
+    }
 
-    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;
+    // ---- 3. Origin guard (gate for action/loader/PE modes) ----
+    const originPhase = ORIGIN_CHECK_PHASE_BY_MODE[plan.mode];
     if (originPhase) {
       const originResult = await checkRequestOrigin(
         request,
@@ -535,37 +736,49 @@ export function createRSCHandler<
           },
         });
 
-        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"),
-            });
-          }
-        } catch {
-          // Router context may not be available
-        }
+        observeEvent({
+          type: "request.origin-rejected",
+          timestamp: performance.now(),
+          method: request.method,
+          pathname: url.pathname,
+          phase: originPhase,
+          origin: request.headers.get("origin"),
+          host: request.headers.get("host"),
+        });
 
         return originResult;
       }
     }
 
-    // Get handle store from request context
-    const handleStore = requireRequestContext()._handleStore;
+    // ---- 4. Execute ----
+    return executeRequest(
+      plan as ExecutableRequestPlan<TEnv>,
+      request,
+      env,
+      url,
+      variables,
+      nonce,
+    );
+  }
+
+  // Execute a classified request plan. Dispatches to the appropriate handler
+  // based on plan.mode. Lives in the createRSCHandler closure for access to
+  // handlerCtx, router, callOnError, etc.
+  // Only receives executable plans (version-mismatch is handled above).
+  async function executeRequest(
+    plan: ExecutableRequestPlan<TEnv>,
+    request: Request,
+    env: TEnv,
+    url: URL,
+    variables: Record<string, any>,
+    nonce: string | undefined,
+  ): Promise<Response> {
+    // Common setup
+    const handleStore = getRequestContext()._handleStore;
 
     // 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();
+      const reqCtx = getRequestContext();
       callOnError(error, "handler", {
         request,
         url,
@@ -573,66 +786,149 @@ export function createRSCHandler<
         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)
-      }
+      observeEvent({
+        type: "handler.error",
+        timestamp: performance.now(),
+        error,
+        handledByBoundary: true,
+        pathname: url.pathname,
+        routeKey: reqCtx._routeName,
+        params: reqCtx.params as Record<string, string>,
+      });
     };
 
     // Set route params early so all execution paths can access ctx.params.
-    if (preview?.params) {
-      setRequestContextParams(preview.params, preview.routeKey);
+    // Also store the classified snapshot so match/matchPartial can reuse it
+    // instead of calling resolveRoute again.
+    if (plan.mode !== "redirect") {
+      setRequestContextParams(plan.route.params, plan.route.routeKey);
+      getRequestContext()._classifiedRoute = plan.route;
     }
 
-    // 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,
+    const routeReverse = createReverseFunction(getRequiredRouteMap());
+
+    // ---- Response route: skip entire RSC pipeline ----
+    if (plan.mode === "response") {
+      // Build ResponseRouteMatch from plan fields. handleResponseRoute
+      // expects a flat object with params at the top level.
+      const responseMatch: ResponseRouteMatch = {
+        responseType: plan.responseType,
+        handler: plan.handler,
+        params: plan.route.params,
+        negotiated: plan.negotiated,
+        manifestEntry: plan.manifestEntry,
+        routeMiddleware: plan.routeMiddleware,
+      };
+      const responseOutcome = await withTimeout(
+        handleResponseRoute(
+          handlerCtx,
+          responseMatch,
+          request,
+          env,
+          url,
+          variables,
+        ),
+        router.timeouts.renderStartMs,
+        "render-start",
+      );
+      if (responseOutcome.timedOut) {
+        return handleTimeoutResponse(
+          request,
+          env,
+          url,
+          "render-start",
+          responseOutcome.durationMs,
+          plan.route.routeKey,
+        );
+      }
+      const response = responseOutcome.result;
+      if (plan.negotiated && !isWebSocketUpgradeResponse(response)) {
+        // handleResponseRoute (callHandlerWithVary) already appends Vary: Accept
+        // for negotiated responses; dedup so we don't emit Vary: Accept, Accept.
+        appendVaryAccept(response);
+      }
+      return response;
+    }
+
+    // SSR setup: kick off in parallel for modes that need HTML rendering.
+    // Placed after response-route short-circuit so response/mime routes
+    // never pay for SSR work.
+    //
+    // Only kick off when the request will actually render HTML, so the
+    // eager loadSSRModule() + user resolveStreaming() are not started (and
+    // never consumed) for a request that returns an RSC stream — that wasted
+    // work also leaves an orphaned Promise.all that can reject (D7). PE form
+    // submissions always render HTML (handleProgressiveEnhancement renders via
+    // getSSRSetup regardless of Accept). For full/partial-render and action,
+    // the render-time HTML decision is exactly !isRscRequest — mayNeedSSR is
+    // the coarse transport pre-filter, isRscRequest is the precise Accept call
+    // (it, unlike mayNeedSSR, treats a MISSING Accept as RSC). Both must pass.
+    const willRenderHtml =
+      plan.mode === "pe-render" ||
+      (mayNeedSSR(request, url) &&
+        !isRscRequest(request, url, plan.mode === "partial-render"));
+    if (plan.mode !== "loader" && willRenderHtml) {
+      variables[SSR_SETUP_VAR] = startSSRSetup(
+        handlerCtx,
+        request,
+        env,
+        url,
+        router.debugPerformance
+          ? () => getRequestContext()._metricsStore
+          : undefined,
+      );
+    }
+
+    // ---- Loader fetch ----
+    if (plan.mode === "loader") {
+      return handleLoaderFetch(
+        handlerCtx,
+        request,
+        env,
+        url,
         variables,
-        routeReverse,
-      },
-    );
-    if (progressiveResult) {
-      return progressiveResult;
+        plan.route.params,
+      );
+    }
+
+    // ---- Progressive enhancement ----
+    if (plan.mode === "pe-render") {
+      const peResult = await handleProgressiveEnhancement(
+        handlerCtx,
+        request,
+        env,
+        url,
+        false, // isAction = false for PE
+        handleStore,
+        nonce,
+        {
+          routeMiddleware: plan.route.routeMiddleware,
+          variables,
+          routeReverse,
+        },
+      );
+      if (peResult) return peResult;
+      // PE handler returned null (not a PE form) — fall through to render
     }
 
-    // --- 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) {
+    // ---- Action: execute action, then revalidate wrapped in route middleware ----
+    if (plan.mode === "action") {
+      let actionContinuation: ActionContinuation | undefined;
       try {
+        // Instrument the action execution as its own phase (action:<actionId> +
+        // rango.action), so a POST shows the mutation time AND which action ran,
+        // not just the downstream revalidation render. The action's own
+        // loaders/fetches nest under rango.action.
         const actionOutcome = await withTimeout(
-          executeServerAction(
-            handlerCtx,
-            request,
-            env,
-            url,
-            actionId,
-            handleStore,
+          observePhase(PHASES.action(plan.actionId), () =>
+            executeServerAction(
+              handlerCtx,
+              request,
+              env,
+              url,
+              plan.actionId,
+              handleStore,
+            ),
           ),
           router.timeouts.actionMs,
           "action",
@@ -644,8 +940,8 @@ export function createRSCHandler<
             url,
             "action",
             actionOutcome.durationMs,
-            preview?.routeKey,
-            actionId,
+            plan.route.routeKey,
+            plan.actionId,
           );
         }
         const result = actionOutcome.result;
@@ -657,40 +953,248 @@ export function createRSCHandler<
           request,
           url,
           env,
-          actionId,
+          actionId: plan.actionId,
           handledByBoundary: false,
         });
         console.error(`[RSC] Action error:`, error);
         throw error;
       }
-    }
 
-    // --- Rendering (action revalidation or navigation) ---
-    // Route middleware wraps this — same code path for both cases.
-    const renderHandler = async () => {
-      const response = await coreRequestHandlerInner(
+      // Revalidation render wrapped in route middleware.
+      // Actions from client-side navigation include _rsc_partial — preserve
+      // the partial flag so the revalidation returns a Flight stream, not HTML.
+      // App-switch is already excluded by classifyRequest (would be full-render).
+      const isPartialAction = url.searchParams.has("_rsc_partial");
+      return executeRenderWithMiddleware(
+        plan.route.routeMiddleware,
+        plan.negotiated,
+        plan.route.routeKey,
+        routeReverse,
         request,
         env,
         url,
         variables,
         nonce,
-        preview?.params,
-        preview?.routeKey,
         handleStore,
+        isPartialAction,
         actionContinuation,
       );
-      if (preview?.negotiated) {
-        response.headers.append("Vary", "Accept");
+    }
+
+    // Full render, partial render, fallen-through PE, and full-page redirect all
+    // render through the same middleware-wrapped path. Only full/partial-render
+    // carry negotiation + the partial flag; pe/redirect render plainly.
+    const isPartial = plan.mode === "partial-render";
+    const negotiated =
+      plan.mode === "full-render" || plan.mode === "partial-render"
+        ? plan.negotiated
+        : false;
+    return executeRenderWithMiddleware(
+      plan.route.routeMiddleware,
+      negotiated,
+      plan.route.routeKey,
+      routeReverse,
+      request,
+      env,
+      url,
+      variables,
+      nonce,
+      handleStore,
+      isPartial,
+    );
+  }
+
+  // Shared render execution: wraps handleRscRendering (or revalidateAfterAction)
+  // in route middleware and timeout handling. Consolidates the pattern used by
+  // action-revalidate, full-render, and partial-render modes.
+  async function executeRenderWithMiddleware(
+    routeMiddleware: import("../router/middleware-types.js").CollectedMiddleware[],
+    negotiated: boolean,
+    routeKey: string,
+    routeReverse: ReturnType<typeof createReverseFunction>,
+    request: Request,
+    env: TEnv,
+    url: URL,
+    variables: Record<string, any>,
+    nonce: string | undefined,
+    handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
+    isPartial: boolean,
+    actionContinuation?: ActionContinuation,
+  ): Promise<Response> {
+    const renderHandler = async (): Promise<Response> => {
+      try {
+        let response: Response;
+        if (actionContinuation) {
+          response = await revalidateAfterAction(
+            handlerCtx,
+            request,
+            env,
+            url,
+            handleStore,
+            actionContinuation,
+          );
+        } else {
+          response = await handleRscRendering(
+            handlerCtx,
+            request,
+            env,
+            url,
+            isPartial,
+            handleStore,
+            nonce,
+          );
+        }
+        if (negotiated && !isWebSocketUpgradeResponse(response)) {
+          // handleRscRendering bakes `accept` into the RSC response's Vary list;
+          // dedup so the negotiated append does not list accept twice.
+          appendVaryAccept(response);
+        }
+        return response;
+      } catch (error) {
+        // Check if middleware/handler returned Response
+        if (error instanceof Response) {
+          // An action revalidation render is delivered to the client over the
+          // same Flight-parsing path as a partial navigation, so a Response
+          // thrown during it must be converted exactly like a partial one
+          // (raw 200 -> hard-nav hint, 3xx -> Flight redirect). Without this,
+          // the no-middleware path returns the raw Response (the with-middleware
+          // path is already covered by the isPartial || actionContinuation
+          // guard below).
+          const treatAsPartial = isPartial || actionContinuation != null;
+
+          // During partial (client-side navigation), a 200 Response from a handler
+          // means the route serves raw content (JSON, text, etc.), not JSX.
+          // Signal the browser to hard-navigate so it renders the raw response.
+          if (treatAsPartial && error.status === 200) {
+            console.warn(
+              `[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.`,
+            );
+            return createResponseWithMergedHeaders(null, {
+              status: 200,
+              headers: {
+                "X-RSC-Reload": stripInternalParams(url).toString(),
+                "content-type": "text/x-component;charset=utf-8",
+              },
+            });
+          }
+
+          if (treatAsPartial) {
+            const intercepted = interceptRedirectForPartial(
+              error,
+              createRedirectFlightResponse,
+            );
+            if (intercepted) return intercepted;
+          }
+
+          return error;
+        }
+
+        // Render 404 page for unmatched routes
+        if (isRouteNotFoundError(error)) {
+          callOnError(error, "routing", {
+            request,
+            url,
+            env,
+            handledByBoundary: true,
+          });
+
+          const notFoundOption = router.notFound;
+          const notFoundComponent =
+            typeof notFoundOption === "function"
+              ? notFoundOption({ pathname: url.pathname })
+              : (notFoundOption ?? createElement("h1", null, "Not Found"));
+
+          const notFoundSegment = {
+            id: "notFound",
+            namespace: "notFound",
+            type: "route" as const,
+            index: 0,
+            component: notFoundComponent,
+            params: {},
+          };
+
+          const payload: RscPayload = {
+            metadata: {
+              pathname: url.pathname,
+              routerId: router.id,
+              basename: router.basename,
+              segments: [notFoundSegment],
+              matched: [],
+              diff: [],
+              // Shape parity with buildFullPayload (rsc-rendering.ts): the 404
+              // payload carries params/resolvedIds/prefetchCacheTTL the same way a
+              // matched full render does. resolvedIds mirrors the rendered segment
+              // list (the single notFound segment) like the error-boundary path
+              // (match-api.ts) does for its boundary segment.
+              resolvedIds: [notFoundSegment.id],
+              params: {},
+              isPartial: false,
+              rootLayout: router.rootLayout,
+              handles: handleStore.stream(),
+              version,
+              prefetchCacheTTL: router.prefetchCacheTTL,
+              stateCookieName: router.resolvedStateCookieName,
+              themeConfig: router.themeConfig,
+              warmupEnabled: router.warmupEnabled,
+              strictMode: router.strictMode,
+              initialTheme: getRequestContext().theme,
+            },
+          };
+
+          const rscStream = renderToReadableStream(payload, {
+            onError: (error: unknown) => {
+              callOnError(error, "rendering", { request, url, env });
+            },
+          });
+
+          if (isRscRequest(request, url, isPartial)) {
+            return createResponseWithMergedHeaders(rscStream, {
+              status: 404,
+              headers: {
+                "content-type": "text/x-component;charset=utf-8",
+                // Router identity for the client's pre-decode integrity check; a
+                // same-app 404 matches and applies in place. See response-adapter.
+                "X-RSC-Router-Id": router.id,
+              },
+            });
+          }
+
+          const [ssrModule, streamMode] = await getSSRSetup(
+            handlerCtx,
+            request,
+            env,
+            url,
+            getRequestContext()._metricsStore,
+          );
+          const htmlStream = await ssrModule.renderHTML(rscStream, {
+            nonce,
+            streamMode,
+          });
+
+          return createResponseWithMergedHeaders(htmlStream, {
+            status: 404,
+            headers: { "content-type": "text/html;charset=utf-8" },
+          });
+        }
+
+        // Report unhandled errors
+        callOnError(error, "routing", {
+          request,
+          url,
+          env,
+          handledByBoundary: false,
+        });
+        console.error(`[RSC] Error:`, error);
+        throw error;
       }
-      return response;
     };
 
-    // Wrap the render path (with or without route middleware) in a
-    // renderStartMs timeout so slow renders are caught before output.
+    // Wrap the render path in a renderStartMs timeout
     const executeRender = async (): Promise<Response> => {
-      if (preview?.routeMiddleware && preview.routeMiddleware.length > 0) {
+      if (routeMiddleware.length > 0) {
         const mwResponse = await executeMiddleware(
-          buildRouteMiddlewareEntries<TEnv>(preview.routeMiddleware),
+          buildRouteMiddlewareEntries<TEnv>(routeMiddleware),
           request,
           env,
           variables,
@@ -698,10 +1202,7 @@ export function createRSCHandler<
           routeReverse,
         );
 
-        if (
-          url.searchParams.has("_rsc_partial") ||
-          url.searchParams.has("_rsc_action")
-        ) {
+        if (isPartial || actionContinuation) {
           const intercepted = interceptRedirectForPartial(
             mwResponse,
             createRedirectFlightResponse,
@@ -712,7 +1213,6 @@ export function createRSCHandler<
         return finalizeResponse(mwResponse);
       }
 
-      // No route middleware, proceed directly
       return renderHandler();
     };
 
@@ -728,267 +1228,9 @@ export function createRSCHandler<
         url,
         "render-start",
         renderOutcome.durationMs,
-        preview?.routeKey,
+        routeKey,
       );
     }
     return renderOutcome.result;
   }
-
-  // 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,
-    url: URL,
-    variables: Record<string, any>,
-    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");
-
-    // Version mismatch detection - client may have stale code after HMR/deployment
-    // If versions don't match, tell the client to reload
-    const clientVersion = url.searchParams.get("_rsc_v");
-    if (version && clientVersion && clientVersion !== version) {
-      console.log(
-        `[RSC] Version mismatch: client=${clientVersion}, server=${version}. Forcing reload.`,
-      );
-
-      // 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 = stripInternalParams(url).toString();
-      if (isAction) {
-        const referer = request.headers.get("referer");
-        if (referer) {
-          try {
-            const refererUrl = new URL(referer);
-            if (refererUrl.origin === url.origin) {
-              reloadUrl = referer;
-            }
-          } catch {
-            // Malformed referer, fall back to cleanUrl
-          }
-        }
-      }
-
-      // Return special response that tells client to reload
-      return createResponseWithMergedHeaders(null, {
-        status: 200,
-        headers: {
-          "X-RSC-Reload": reloadUrl,
-          "content-type": "text/x-component;charset=utf-8",
-        },
-      });
-    }
-    // Debug manifest endpoint: ?__debug_manifest on any route.
-    // Always available in dev, requires allowDebugManifest option in production.
-    const isDev = process.env.NODE_ENV !== "production";
-    if (
-      url.searchParams.has("__debug_manifest") &&
-      (isDev || router.allowDebugManifest)
-    ) {
-      const trie = getRouterTrie(router.id) ?? getRouteTrie();
-      const routeManifest = getRequiredRouteMap();
-      const { extractAncestryFromTrie } =
-        await import("../build/route-trie.js");
-      return new Response(
-        JSON.stringify(
-          {
-            routerId: router.id,
-            routeManifest,
-            routeAncestry: trie ? extractAncestryFromTrie(trie) : {},
-            routeTrie: trie,
-            precomputedEntries: getPrecomputedEntries(),
-          },
-          null,
-          2,
-        ),
-        {
-          headers: { "Content-Type": "application/json" },
-        },
-      );
-    }
-
-    const store = handleStore ?? requireRequestContext()._handleStore;
-
-    try {
-      // Route params were already set in coreRequestHandler, but set again
-      // for callers that enter coreRequestHandlerInner directly.
-      if (routeParams) {
-        setRequestContextParams(routeParams, routeKey);
-      }
-
-      // ============================================================================
-      // ACTION REVALIDATION (action already executed, revalidate segments)
-      // ============================================================================
-      if (actionContinuation) {
-        return await revalidateAfterAction(
-          handlerCtx,
-          request,
-          env,
-          url,
-          store,
-          actionContinuation,
-        );
-      }
-
-      // ============================================================================
-      // LOADER FETCH EXECUTION (data fetching with RSC serialization)
-      // ============================================================================
-      const isLoaderRequest = url.searchParams.has("_rsc_loader");
-      if (isLoaderRequest) {
-        return handleLoaderFetch(
-          handlerCtx,
-          request,
-          env,
-          url,
-          variables,
-          routeParams,
-        );
-      }
-
-      // ============================================================================
-      // REGULAR RSC RENDERING (Navigation)
-      // ============================================================================
-      // Note: Must use "return await" for try/catch to catch async rejections
-      return await handleRscRendering(
-        handlerCtx,
-        request,
-        env,
-        url,
-        isPartial,
-        store,
-        nonce,
-      );
-    } catch (error) {
-      // Check if middleware/handler returned Response
-      if (error instanceof Response) {
-        // During partial (client-side navigation), a 200 Response from a handler
-        // means the route serves raw content (JSON, text, etc.), not JSX.
-        // Signal the browser to hard-navigate so it renders the raw response.
-        // Only for 200 — redirects (3xx) work already because the browser follows
-        // them automatically to a URL that serves Flight data.
-        if (isPartial && error.status === 200) {
-          console.warn(
-            `[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.`,
-          );
-          return createResponseWithMergedHeaders(null, {
-            status: 200,
-            headers: {
-              "X-RSC-Reload": stripInternalParams(url).toString(),
-              "content-type": "text/x-component;charset=utf-8",
-            },
-          });
-        }
-
-        if (isPartial) {
-          const intercepted = interceptRedirectForPartial(
-            error,
-            createRedirectFlightResponse,
-          );
-          if (intercepted) return intercepted;
-        }
-
-        return error;
-      }
-
-      // Render 404 page for unmatched routes
-      // Check both instanceof and error.name for cross-bundle compatibility
-      const isRouteNotFound =
-        error instanceof RouteNotFoundError ||
-        (error instanceof Error && error.name === "RouteNotFoundError");
-      if (isRouteNotFound) {
-        callOnError(error, "routing", {
-          request,
-          url,
-          env,
-          handledByBoundary: true, // Handled by notFound component
-        });
-
-        // Get notFound component from router options or use default
-        const notFoundOption = router.notFound;
-        const notFoundComponent =
-          typeof notFoundOption === "function"
-            ? notFoundOption({ pathname: url.pathname })
-            : (notFoundOption ?? createElement("h1", null, "Not Found"));
-
-        // Create a simple segment for the 404 page
-        const notFoundSegment = {
-          id: "notFound",
-          namespace: "notFound",
-          type: "route" as const,
-          index: 0,
-          component: notFoundComponent,
-          params: {},
-        };
-
-        const payload: RscPayload = {
-          metadata: {
-            pathname: url.pathname,
-            segments: [notFoundSegment],
-            matched: [],
-            diff: [],
-            isPartial: false,
-            rootLayout: router.rootLayout,
-            handles: store.stream(),
-            version,
-            themeConfig: router.themeConfig,
-            warmupEnabled: router.warmupEnabled,
-            initialTheme: requireRequestContext().theme,
-            // No routeName for not-found routes
-          },
-        };
-
-        const rscStream = renderToReadableStream(payload);
-
-        // Determine if this is an RSC request or HTML request.
-        // Partial requests are always RSC (see main isRscRequest comment).
-        const isRscRequest =
-          isPartial ||
-          (!request.headers.get("accept")?.includes("text/html") &&
-            !url.searchParams.has("__html")) ||
-          url.searchParams.has("__rsc");
-
-        if (isRscRequest) {
-          return createResponseWithMergedHeaders(rscStream, {
-            status: 404,
-            headers: { "content-type": "text/x-component;charset=utf-8" },
-          });
-        }
-
-        // Delegate to SSR for HTML response
-        const [ssrModule, streamMode] = await Promise.all([
-          loadSSRModule(),
-          handlerCtx.resolveStreamMode(request, env, url),
-        ]);
-        const htmlStream = await ssrModule.renderHTML(rscStream, {
-          nonce,
-          streamMode,
-        });
-
-        return createResponseWithMergedHeaders(htmlStream, {
-          status: 404,
-          headers: { "content-type": "text/html;charset=utf-8" },
-        });
-      }
-
-      // Report unhandled errors
-      callOnError(error, "routing", {
-        request,
-        url,
-        env,
-        handledByBoundary: false,
-      });
-      console.error(`[RSC] Error:`, error);
-      throw error;
-    }
-  }
 }