@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d68257e5

package/src/rsc/handler.ts

@@ -7,13 +7,11 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
-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,
@@ -31,32 +29,47 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
-import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { renderRscFlightStage, renderRscResponse } from "./render-pipeline.js";
+import { guardOutgoingRedirect } from "./redirect-guard.js";
+import {
+  resolveSoftRedirectUrl,
+  resolveExternalRedirect,
+  safeSameOriginLanding,
+} from "../redirect-origin.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
+import {
+  isWebSocketUpgradeResponse,
+  appendVaryAccept,
+} from "../response-utils.js";
 import {
   handleResponseRoute,
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
-import { generateNonce, nonce as nonceToken } from "./nonce.js";
+import { nonce as nonceToken, resolveProviderNonce } 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 {
+  invokeOnError,
+  resolveDefaultNotFound,
+} from "../router/error-handling.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,
-  getPrecomputedEntries,
   waitForManifestReady,
   getRouterManifest,
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
+import {
+  compileSearchParamsFilter,
+  type SearchParamsFilter,
+} from "../cache/search-params-filter.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
@@ -66,23 +79,32 @@ import {
   type ActionContinuation,
 } from "./server-action.js";
 import { handleLoaderFetch } from "./loader-fetch.js";
-import { checkRequestOrigin, type OriginCheckPhase } from "./origin-guard.js";
+import { applyStreamIdleTimeout } from "./stream-idle.js";
+import {
+  checkRequestOrigin,
+  ORIGIN_CHECK_PHASE_BY_MODE,
+} from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
 import {
   withTimeout,
+  isTimeoutEnabled,
   RouterTimeoutError,
   createDefaultTimeoutResponse,
   type TimeoutPhase,
+  type RenderTimeoutContext,
 } from "../router/timeout.js";
 import {
   createMetricsStore,
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import { safeEmit, resolveSink, getRequestId } from "../router/telemetry.js";
 import {
   startSSRSetup,
-  getSSRSetup,
+  createSsrHtmlStage,
   mayNeedSSR,
+  isRscRequest,
   SSR_SETUP_VAR,
 } from "./ssr-setup.js";
 import {
@@ -90,6 +112,7 @@ import {
   type RequestPlan,
   type ExecutableRequestPlan,
 } from "../router/request-classification.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 /**
  * Create an RSC request handler.
@@ -124,12 +147,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 {
@@ -204,7 +250,44 @@ export function createRSCHandler<
     actionId?: string,
   ): Promise<Response> {
     const timeoutError = new RouterTimeoutError(phase, durationMs);
+    const requestContext = _getRequestContext<TEnv>();
+    const cursor = requestContext?._renderForeground;
+    const render: RenderTimeoutContext | undefined =
+      phase === "render-start" && cursor
+        ? {
+            mode: cursor.mode,
+            phase: cursor.phase,
+            state: cursor.state,
+            completed: cursor.completed,
+            total: cursor.total,
+            ...(cursor.phaseStartedAt !== undefined && {
+              phaseDurationMs: performance.now() - cursor.phaseStartedAt,
+            }),
+          }
+        : undefined;
+    const trace =
+      phase === "render-start" ? requestContext?._activeRoutine : undefined;
+    const activeEntries = trace?.active() ?? [];
+    const activeStep = activeEntries.at(-1);
+    const activeAt = performance.now();
+    const routineSnapshot =
+      trace && activeStep
+        ? {
+            name: trace.name,
+            path: activeEntries.map((entry) => entry.name),
+            durationMs: activeAt - activeStep.startedAt,
+          }
+        : undefined;
+
+    if (INTERNAL_RANGO_DEBUG && trace && activeStep) {
+      console.log(
+        `[routine] TIMEOUT ${request.method} ${url.pathname} (${trace.name})\n${trace.formatActive(activeEntries, activeAt)}`,
+      );
+    }
 
+    // Each surface gets its OWN shallow render snapshot. A consumer that mutates
+    // its copy must not corrupt what the other two observe. The internal-debug
+    // routine snapshot is bounded metadata sent only to onError.
     callOnError(timeoutError, phase === "action" ? "action" : "handler", {
       request,
       url,
@@ -212,26 +295,28 @@ export function createRSCHandler<
       routeKey,
       actionId,
       handledByBoundary: false,
-      metadata: { timeout: true, phase, durationMs },
+      metadata: {
+        timeout: true,
+        phase,
+        durationMs,
+        ...(render && { render: { ...render } }),
+        ...(routineSnapshot && { routine: routineSnapshot }),
+      },
     });
 
-    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.telemetry) {
+      safeEmit(resolveSink(router.telemetry), {
+        type: "request.timeout",
+        timestamp: performance.now(),
+        requestId: getRequestId(request),
+        phase,
+        pathname: url.pathname,
+        routeKey,
+        actionId,
+        durationMs,
+        customHandler: !!router.onTimeout,
+        ...(render && { render: { ...render } }),
+      });
     }
 
     if (router.onTimeout) {
@@ -244,6 +329,7 @@ export function createRSCHandler<
           routeKey,
           actionId,
           durationMs,
+          ...(render && { render: { ...render } }),
         });
       } catch (e) {
         if (process.env.NODE_ENV !== "production") {
@@ -260,20 +346,66 @@ export function createRSCHandler<
    * Build a 200 Flight response that carries a redirect URL and optional state.
    * Used when a partial/action request results in a redirect -- fetch
    * auto-follows 3xx so we send the redirect as payload metadata instead.
+   *
+   * The redirect URL is resolved with {@link resolveSoftRedirectUrl} against
+   * the current request origin so an unsafe target never leaves as Flight
+   * metadata (client validators remain defense-in-depth).
    */
   function createRedirectFlightResponse(
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ): Response {
+    const reqCtx = _getRequestContext<TEnv>();
+    const requestOrigin =
+      reqCtx?.url.origin ?? new URL("http://localhost").origin;
+    // Resolve with the same policy as 3xx guardOutgoingRedirect. Keep
+    // external:true only when the external scheme check passed; a neutralized
+    // landing (javascript:/blocked) must not advertise external.
+    let resolvedUrl: string;
+    let resolvedExternal = false;
+    if (external) {
+      const ext = resolveExternalRedirect(redirectUrl, requestOrigin);
+      if (ext !== null) {
+        resolvedUrl = ext;
+        resolvedExternal = true;
+      } else {
+        resolvedUrl = safeSameOriginLanding(router.basename);
+      }
+    } else {
+      resolvedUrl = resolveSoftRedirectUrl(
+        redirectUrl,
+        requestOrigin,
+        router.basename,
+        false,
+      );
+    }
     const redirectPayload: RscPayload = {
       metadata: {
-        pathname: redirectUrl,
+        pathname: resolvedUrl,
         segments: [],
-        redirect: { url: redirectUrl },
+        redirect: {
+          url: resolvedUrl,
+          ...(resolvedExternal && { external: true }),
+        },
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload);
+    const rscStream = reqCtx
+      ? renderRscFlightStage({
+          ctx: { renderToReadableStream, callOnError },
+          request: reqCtx.request,
+          url: reqCtx.url,
+          env: reqCtx.env,
+          payload: redirectPayload,
+          tracking: {
+            mode: reqCtx.url.searchParams.has("_rsc_action")
+              ? "action-revalidation"
+              : "partial",
+            routeKey: reqCtx._routeName,
+          },
+        }).stream
+      : renderToReadableStream<RscPayload>(redirectPayload);
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -285,6 +417,7 @@ export function createRSCHandler<
   const handlerCtx: HandlerContext<TEnv> = {
     router,
     version,
+    devDiscoveryEpoch: router.__devDiscoveryEpoch,
     renderToReadableStream,
     decodeReply,
     createTemporaryReferenceSet,
@@ -323,12 +456,12 @@ export function createRSCHandler<
       }
     }
 
-    // Resolve nonce if provider is set
+    // Resolve nonce if provider is set. false/"" normalize to undefined —
+    // the per-request opt-out (resolveProviderNonce).
     const nonceStart = performance.now();
     let nonce: string | undefined;
     if (nonceProvider) {
-      const result = await nonceProvider(request, env);
-      nonce = result === true ? generateNonce() : result;
+      nonce = resolveProviderNonce(await nonceProvider(request, env));
     }
     const nonceDur = performance.now() - nonceStart;
 
@@ -355,6 +488,7 @@ export function createRSCHandler<
     // 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: SegmentCacheStore | undefined;
+    let searchParamsFilter: SearchParamsFilter | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
       const cacheConfig =
@@ -364,6 +498,9 @@ export function createRSCHandler<
 
       if (cacheConfig.enabled !== false) {
         cacheStore = cacheConfig.store;
+        searchParamsFilter = compileSearchParamsFilter(
+          cacheConfig.searchParams,
+        );
       }
     }
 
@@ -421,10 +558,25 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      searchParamsFilter,
+      explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
+      stateCookieName: router.resolvedStateCookieName,
+      version,
     });
+    // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):
+    // a `renderStartMs: 0` / negative opt-out disables the timeout, so the
+    // driver's cursor bookkeeping (which only the timeout reads) must be off too.
+    requestContext._renderDiagnosticsEnabled = isTimeoutEnabled(
+      router.timeouts.renderStartMs,
+    );
+    // Thread the true request entry timestamp onto the context so a metrics
+    // store created MID-request (ctx.debugPerformance() / getMetricsStore) anchors
+    // to the real start, not the opt-in moment — phases that began earlier then
+    // report non-negative offsets. Set unconditionally: debug may be enabled later.
+    requestContext._handlerStart = handlerStart;
     if (earlyMetricsStore) {
       requestContext._debugPerformance = true;
       requestContext._metricsStore = earlyMetricsStore;
@@ -433,7 +585,7 @@ export function createRSCHandler<
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (
       error: unknown,
-      category: string,
+      category: CacheErrorCategory,
     ) => {
       callOnError(error, "cache", {
         request,
@@ -465,82 +617,206 @@ export function createRSCHandler<
     // - Streaming
     // Store basename on request context (scoped per-request via existing ALS)
     requestContext._basename = router.basename;
+    requestContext._routerId = router.id;
+
+    // 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);
+        };
 
-    return runWithRequestContext(requestContext, async () => {
-      // 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; the response is finalized below, inside the response span.
+        const hasMiddleware = matchedMiddleware.length > 0;
+        const downstream = hasMiddleware
+          ? await executeMiddleware(
+              matchedMiddleware,
+              request,
+              env,
+              variables,
+              coreHandler,
+              createReverseFunction(getRequiredRouteMap()),
+            )
+          : await coreHandler();
+
+        // Final response construction + host handoff, wrapped in rango.response
+        // — the explicit stream-handoff marker. The callback is synchronous, so
+        // the span ends immediately before the handler returns the response to
+        // the host; it never reads or wraps response.body. A downstream throw
+        // skips it entirely (no response exists to hand off).
+        return observePhase(PHASES.response, (responseSpan) => {
+          let response: Response;
+          if (hasMiddleware) {
+            if (
+              url.searchParams.has("_rsc_partial") ||
+              url.searchParams.has("_rsc_action")
+            ) {
+              const intercepted = interceptRedirectForPartial(
+                downstream,
+                createRedirectFlightResponse,
+                { requestOrigin: url.origin, basename: router.basename },
+              );
+              response = intercepted ?? finalizeResponse(downstream);
+            } else {
+              response = finalizeResponse(downstream);
+            }
+          } else {
+            response = downstream;
+          }
 
-      // 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()),
-        );
+          // 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 its requestStart is now the threaded
+            // _handlerStart (== handlerStart), so both branches yield the true
+            // request entry; reading the store's own anchor keeps this correct even
+            // if a store ever lands without the threading (falls back to its start).
+            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);
+          }
 
-        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();
-      }
+          const fullTiming = timingParts.join(", ");
+          if (fullTiming && !isWebSocketUpgradeResponse(response)) {
+            try {
+              response.headers.set("Server-Timing", fullTiming);
+            } catch {
+              // Immutable headers (e.g. a passed-through platform Response) — drop
+              // the timing header, never the response. Instrumentation must not
+              // 500 a request.
+            }
+          }
 
-      // 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);
-      }
+          // 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).
+          const guarded = guardOutgoingRedirect(
+            response,
+            url.origin,
+            router.basename,
+          );
 
-      const fullTiming = timingParts.join(", ");
-      if (fullTiming && !isWebSocketUpgradeResponse(response)) {
-        response.headers.set("Server-Timing", fullTiming);
-      }
+          // Stream-idle watchdog (opt-in via timeouts.streamIdleMs): bounds
+          // end-to-end idle flow on the streamed body — see rsc/stream-idle.ts
+          // for the semantics. Applied at this finalization chokepoint so every
+          // streaming exit is covered; websocket upgrades must never be
+          // reconstructed and bodiless responses have nothing to bound. The
+          // trip fires POST-handoff (the request ALS may be gone), so it
+          // reports via the eagerly captured surfaces — callOnError +
+          // router.telemetry directly — mirroring handleStore.onError.
+          // onTimeout does NOT apply: the response already left the handler,
+          // so no replacement Response can be served mid-stream.
+          let finalResponse = guarded;
+          const streamIdleMs = router.timeouts.streamIdleMs;
+          // Websocket check FIRST: a workerd upgrade response must never have
+          // its body getter poked (same invariant as the body_kind attribute
+          // below).
+          if (
+            isTimeoutEnabled(streamIdleMs) &&
+            !isWebSocketUpgradeResponse(guarded) &&
+            guarded.body
+          ) {
+            const routeKey = requestContext._routeName;
+            finalResponse = applyStreamIdleTimeout(
+              guarded,
+              streamIdleMs!,
+              (tripInfo) => {
+                callOnError(tripInfo.error, "handler", {
+                  request,
+                  url,
+                  env,
+                  routeKey,
+                  handledByBoundary: false,
+                  metadata: {
+                    timeout: true,
+                    phase: "stream-idle",
+                    durationMs: tripInfo.totalMs,
+                  },
+                });
+                if (router.telemetry) {
+                  safeEmit(resolveSink(router.telemetry), {
+                    type: "request.timeout",
+                    timestamp: performance.now(),
+                    requestId: getRequestId(request),
+                    phase: "stream-idle",
+                    pathname: url.pathname,
+                    routeKey,
+                    durationMs: tripInfo.totalMs,
+                    customHandler: false,
+                  });
+                }
+              },
+            );
+          }
 
-      return response;
-    });
+          // Attributes describe the response actually handed to the host (after
+          // unsafe-redirect replacement), low-cardinality only. body_kind checks
+          // the websocket marker before the body getter so a workerd upgrade
+          // Response is never poked; `.body` is a getter access, not a read of
+          // the stream.
+          responseSpan.setAttribute(
+            "http.response.status_code",
+            finalResponse.status,
+          );
+          responseSpan.setAttribute(
+            "rango.response.mode",
+            requestContext._requestMode ?? "middleware-short-circuit",
+          );
+          responseSpan.setAttribute(
+            "rango.response.body_kind",
+            isWebSocketUpgradeResponse(finalResponse)
+              ? "websocket"
+              : finalResponse.body === null
+                ? "empty"
+                : "stream",
+          );
+          return finalResponse;
+        });
+      }),
+    );
   };
 
   // Core request handling logic (separated for middleware wrapping).
@@ -555,35 +831,6 @@ export function createRSCHandler<
   ): Promise<Response> {
     const handlerTiming: string[] = variables.__handlerTiming || [];
 
-    // 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,
-        ),
-        {
-          headers: { "Content-Type": "application/json" },
-        },
-      );
-    }
-
     // ---- 1. Classify ----
     // classifyRequest may throw RouteNotFoundError for unknown routes.
     // In that case, fall through to a full-render plan so the pipeline
@@ -597,10 +844,7 @@ export function createRSCHandler<
         routerId: router.id,
       });
     } catch (error) {
-      if (
-        error instanceof RouteNotFoundError ||
-        (error instanceof Error && error.name === "RouteNotFoundError")
-      ) {
+      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.
@@ -626,6 +870,12 @@ export function createRSCHandler<
     const classifyDur = performance.now() - classifyStart;
     handlerTiming.push(`handler-classify;dur=${classifyDur.toFixed(2)}`);
 
+    // Stash the classified mode for the rango.response span (rango.response.mode)
+    // — the outer handler tail cannot see the plan. Stays unset when middleware
+    // short-circuits before core execution runs (reported as
+    // "middleware-short-circuit").
+    getRequestContext()._requestMode = plan.mode;
+
     // ---- 2. Terminal plans (no execution needed) ----
     if (plan.mode === "redirect") {
       // Redirects are handled by the pipeline (match/matchPartial),
@@ -641,24 +891,18 @@ export function createRSCHandler<
       console.log(
         `[RSC] Version mismatch: client=${url.searchParams.get("_rsc_v")}, server=${version}. Forcing reload.`,
       );
-      return createResponseWithMergedHeaders(null, {
-        status: 200,
-        headers: {
-          "X-RSC-Reload": plan.reloadUrl,
-          "content-type": "text/x-component;charset=utf-8",
-        },
-      });
+      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);
     }
 
     // ---- 3. Origin guard (gate for action/loader/PE modes) ----
-    const originPhase: OriginCheckPhase | null =
-      plan.mode === "action"
-        ? "action"
-        : plan.mode === "loader"
-          ? "loader"
-          : plan.mode === "pe-render"
-            ? "pe-form"
-            : null;
+    const originPhase = ORIGIN_CHECK_PHASE_BY_MODE[plan.mode];
     if (originPhase) {
       const originResult = await checkRequestOrigin(
         request,
@@ -686,22 +930,17 @@ 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
+        if (router.telemetry) {
+          safeEmit(resolveSink(router.telemetry), {
+            type: "request.origin-rejected",
+            timestamp: performance.now(),
+            requestId: getRequestId(request),
+            method: request.method,
+            pathname: url.pathname,
+            phase: originPhase,
+            origin: request.headers.get("origin"),
+            host: request.headers.get("host"),
+          });
         }
 
         return originResult;
@@ -732,11 +971,11 @@ export function createRSCHandler<
     nonce: string | undefined,
   ): Promise<Response> {
     // Common setup
-    const handleStore = requireRequestContext()._handleStore;
+    const handleStore = getRequestContext()._handleStore;
 
     // Wire up error reporting for late streaming-handle failures
     handleStore.onError = (error: Error) => {
-      const reqCtx = requireRequestContext();
+      const reqCtx = getRequestContext();
       callOnError(error, "handler", {
         request,
         url,
@@ -744,22 +983,17 @@ 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)
+      if (router.telemetry) {
+        safeEmit(resolveSink(router.telemetry), {
+          type: "handler.error",
+          timestamp: performance.now(),
+          requestId: getRequestId(request),
+          error,
+          handledByBoundary: true,
+          pathname: url.pathname,
+          routeKey: reqCtx._routeName,
+          params: reqCtx.params as Record<string, string>,
+        });
       }
     };
 
@@ -768,7 +1002,7 @@ export function createRSCHandler<
     // instead of calling resolveRoute again.
     if (plan.mode !== "redirect") {
       setRequestContextParams(plan.route.params, plan.route.routeKey);
-      requireRequestContext()._classifiedRoute = plan.route;
+      getRequestContext()._classifiedRoute = plan.route;
     }
 
     const routeReverse = createReverseFunction(getRequiredRouteMap());
@@ -809,7 +1043,9 @@ export function createRSCHandler<
       }
       const response = responseOutcome.result;
       if (plan.negotiated && !isWebSocketUpgradeResponse(response)) {
-        response.headers.append("Vary", "Accept");
+        // handleResponseRoute (callHandlerWithVary) already appends Vary: Accept
+        // for negotiated responses; dedup so we don't emit Vary: Accept, Accept.
+        appendVaryAccept(response);
       }
       return response;
     }
@@ -817,16 +1053,41 @@ export function createRSCHandler<
     // 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.
-    if (plan.mode !== "loader" && mayNeedSSR(request, url)) {
-      variables[SSR_SETUP_VAR] = startSSRSetup(
+    //
+    // 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 adds the partial/__rsc
+    // flags; both share the same Accept rule (acceptsFlightExplicitly in
+    // ssr-setup.ts), so the Accept call cannot drift between them. Both must
+    // pass.
+    const willRenderHtml =
+      plan.mode === "pe-render" ||
+      (mayNeedSSR(request, url) &&
+        !isRscRequest(request, url, plan.mode === "partial-render"));
+    if (plan.mode !== "loader" && willRenderHtml) {
+      const ssrSetup = startSSRSetup(
         handlerCtx,
         request,
         env,
         url,
         router.debugPerformance
-          ? () => requireRequestContext()._metricsStore
+          ? () => getRequestContext()._metricsStore
           : undefined,
       );
+      variables[SSR_SETUP_VAR] = ssrSetup;
+
+      // A handler can short-circuit before HTML rendering consumes this promise
+      // (for example, by returning a redirect). Workerd cancels untracked dynamic
+      // imports at the request boundary; retaining that cancelled promise in the
+      // production SSR module memo makes every later document request hang.
+      // Extending the request lifetime lets the shared setup settle without
+      // delaying the short-circuit response.
+      getRequestContext().executionContext?.waitUntil(ssrSetup);
     }
 
     // ---- Loader fetch ----
@@ -865,14 +1126,20 @@ export function createRSCHandler<
     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,
-            plan.actionId,
-            handleStore,
+          observePhase(PHASES.action(plan.actionId), () =>
+            executeServerAction(
+              handlerCtx,
+              request,
+              env,
+              url,
+              plan.actionId,
+              handleStore,
+            ),
           ),
           router.timeouts.actionMs,
           "action",
@@ -925,47 +1192,17 @@ export function createRSCHandler<
       );
     }
 
-    // ---- Full render / Partial render (or PE that fell through) ----
-    if (plan.mode === "full-render" || plan.mode === "partial-render") {
-      const isPartial = plan.mode === "partial-render";
-      return executeRenderWithMiddleware(
-        plan.route.routeMiddleware,
-        plan.negotiated,
-        plan.route.routeKey,
-        routeReverse,
-        request,
-        env,
-        url,
-        variables,
-        nonce,
-        handleStore,
-        isPartial,
-      );
-    }
-
-    // PE that fell through (handleProgressiveEnhancement returned null)
-    // falls back to full render
-    if (plan.mode === "pe-render") {
-      return executeRenderWithMiddleware(
-        plan.route.routeMiddleware,
-        false,
-        plan.route.routeKey,
-        routeReverse,
-        request,
-        env,
-        url,
-        variables,
-        nonce,
-        handleStore,
-        false,
-      );
-    }
-
-    // Redirect plan that wasn't handled above (full-page redirect — let
-    // the pipeline handle it via match() which returns { redirect: url })
+    // 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,
-      false,
+      negotiated,
       plan.route.routeKey,
       routeReverse,
       request,
@@ -974,7 +1211,7 @@ export function createRSCHandler<
       variables,
       nonce,
       handleStore,
-      false,
+      isPartial,
     );
   }
 
@@ -991,7 +1228,7 @@ export function createRSCHandler<
     url: URL,
     variables: Record<string, any>,
     nonce: string | undefined,
-    handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+    handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
     isPartial: boolean,
     actionContinuation?: ActionContinuation,
   ): Promise<Response> {
@@ -1019,16 +1256,27 @@ export function createRSCHandler<
           );
         }
         if (negotiated && !isWebSocketUpgradeResponse(response)) {
-          response.headers.append("Vary", "Accept");
+          // 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 (isPartial && error.status === 200) {
+          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.`,
@@ -1042,10 +1290,11 @@ export function createRSCHandler<
             });
           }
 
-          if (isPartial) {
+          if (treatAsPartial) {
             const intercepted = interceptRedirectForPartial(
               error,
               createRedirectFlightResponse,
+              { requestOrigin: url.origin, basename: router.basename },
             );
             if (intercepted) return intercepted;
           }
@@ -1054,10 +1303,7 @@ export function createRSCHandler<
         }
 
         // Render 404 page for unmatched routes
-        const isRouteNotFound =
-          error instanceof RouteNotFoundError ||
-          (error instanceof Error && error.name === "RouteNotFoundError");
-        if (isRouteNotFound) {
+        if (isRouteNotFoundError(error)) {
           callOnError(error, "routing", {
             request,
             url,
@@ -1065,11 +1311,12 @@ export function createRSCHandler<
             handledByBoundary: true,
           });
 
-          const notFoundOption = router.notFound;
-          const notFoundComponent =
-            typeof notFoundOption === "function"
-              ? notFoundOption({ pathname: url.pathname })
-              : (notFoundOption ?? createElement("h1", null, "Not Found"));
+          // No boundary to consult: an unmatched route has no entry chain, so
+          // this always lands on the router option or the shared default.
+          const notFoundComponent = resolveDefaultNotFound(
+            router.notFound,
+            url.pathname,
+          );
 
           const notFoundSegment = {
             id: "notFound",
@@ -1088,51 +1335,81 @@ export function createRSCHandler<
               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(),
+              // Full (404) render: resolve deferred handle values server-side.
+              handles: resolvedHandleStream(handleStore),
               version,
+              prefetchCacheTTL: router.prefetchCacheTTL,
+              prefetchCacheSize: router.prefetchCacheSize,
+              prefetchConcurrency: router.prefetchConcurrency,
+              defaultPrefetch: router.defaultPrefetch,
+              stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
-              initialTheme: requireRequestContext().theme,
+              strictMode: router.strictMode,
+              initialTheme: getRequestContext().theme,
             },
           };
 
-          const rscStream = renderToReadableStream(payload, {
-            onError: (error: unknown) => {
-              callOnError(error, "rendering", { request, url, env });
-            },
-          });
-
-          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" },
-            });
-          }
-
-          const [ssrModule, streamMode] = await getSSRSetup(
-            handlerCtx,
+          const isNotFoundFlightResponse = isRscRequest(
             request,
-            env,
             url,
-            requireRequestContext()._metricsStore,
+            isPartial,
+          );
+          const notFoundStageTracking = {
+            mode: isPartial ? ("partial" as const) : ("full" as const),
+            routeKey,
+          };
+          return renderRscResponse(
+            {
+              ctx: handlerCtx,
+              request,
+              url,
+              env,
+              payload,
+              // The 404 path historically records no rsc-serialize metric (it
+              // used the standalone Flight constructor, whose gate was opt-in);
+              // opt out explicitly since renderRscResponse defaults the gate on.
+              recordSerializeMetric: false,
+              init: isNotFoundFlightResponse
+                ? {
+                    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 applies in place.
+                      "X-RSC-Router-Id": router.id,
+                    },
+                  }
+                : {
+                    status: 404,
+                    headers: {
+                      "content-type": "text/html;charset=utf-8",
+                    },
+                  },
+              tracking: notFoundStageTracking,
+            },
+            isNotFoundFlightResponse
+              ? undefined
+              : {
+                  html: createSsrHtmlStage({
+                    ctx: handlerCtx,
+                    request,
+                    env,
+                    url,
+                    metricsStore: getRequestContext()._metricsStore,
+                    render: { nonce },
+                  }),
+                },
           );
-          const htmlStream = await ssrModule.renderHTML(rscStream, {
-            nonce,
-            streamMode,
-          });
-
-          return createResponseWithMergedHeaders(htmlStream, {
-            status: 404,
-            headers: { "content-type": "text/html;charset=utf-8" },
-          });
         }
 
         // Report unhandled errors
@@ -1163,6 +1440,7 @@ export function createRSCHandler<
           const intercepted = interceptRedirectForPartial(
             mwResponse,
             createRedirectFlightResponse,
+            { requestOrigin: url.origin, basename: router.basename },
           );
           if (intercepted) return intercepted;
         }