@reckona/mreact-router 0.0.202 → 0.0.204

package/src/render.ts

@@ -16,12 +16,13 @@ import {
   installQueryAsyncStorage,
   runWithQueryClient,
   type DehydratedQueryClient,
+  type DehydrateOptions,
   type QueryClient,
 } from "@reckona/mreact-query";
 import {
   createStringSink,
   type HtmlSink,
-  renderAsyncBoundary,
+  renderOutOfOrderBoundary,
   renderOutOfOrderReorderScript,
   renderReactNodeToString,
   renderToReadableStream,
@@ -35,9 +36,9 @@ import {
 } from "./client-route-inference.js";
 import {
   hydrationMarkerParts,
+  routeMarkerParts,
   routeIdForPath,
   withHydrationMarkers,
-  withRouteMarkers,
 } from "./navigation-runtime.js";
 import { assetPath } from "./assets.js";
 import { escapeHtmlAttribute } from "@reckona/mreact-shared/html-escape";
@@ -66,11 +67,9 @@ import {
   type TrackedHeaderRequest,
   withTrackedRequest,
 } from "./request-header-tracking.js";
-import {
-  configuredHstsHeader,
-  hasInvalidConfiguredHsts,
-} from "./security-headers.js";
+import { configuredHstsHeader, hasInvalidConfiguredHsts } from "./security-headers.js";
 import { resolveRouterCacheLimit } from "./cache-config.js";
+import { protectNonceBearingResponse } from "./prerender-entry.js";
 import {
   importAppRouterBuiltFileModule,
   importAppRouterFileModule,
@@ -129,13 +128,15 @@ import {
   type RouteMiddlewareControl,
 } from "./middleware.js";
 import {
-  applyFileConventionMetadata,
+  applyFileConventionMetadataTemplate,
+  fileConventionMetadataTemplate,
   injectHeadMetadata,
   mergeRouteMetadata,
   responseHeadersForMetadata,
   serializeRobots,
   serializeSitemap,
   validateRouteMetadata,
+  type FileConventionMetadataTemplate,
 } from "./metadata.js";
 import {
   createSlotRenderContext,
@@ -202,6 +203,7 @@ export interface RenderAppRequestOptions {
   clientStylesByFile?: ReadonlyMap<string, readonly string[]>;
   clientStyles?: ReadonlyMap<string, readonly string[]>;
   define?: UserConfig["define"] | undefined;
+  dehydrateOptions?: DehydrateOptions | undefined;
   env?: unknown;
   importPolicy?: AppRouterImportPolicy | undefined;
   instrumentation?: RouterInstrumentation | undefined;
@@ -217,6 +219,7 @@ export interface RenderAppRequestOptions {
   routeMatcher?: RouteMatcher | undefined;
   routes?: readonly AppRoute[] | undefined;
   serverModules?: ReadonlyMap<string, BuiltServerModuleArtifact> | undefined;
+  serverRenderArtifactLoader?: AppRouterServerRenderArtifactLoader | undefined;
   serverModuleCacheVersion?: string | undefined;
   devServerModuleCacheVersion?: string | undefined;
   // True when serving through a dev server: request-time server transforms
@@ -233,6 +236,14 @@ export interface RenderAppRequestOptions {
 }
 
 export interface RenderAppRequestRuntimeOptions extends RenderAppRequestOptions {
+  /**
+   * Wraps a server-only page with build-time variant capture comments.
+   *
+   * This is an in-process render signal. It must not be derived from request
+   * headers because network clients are not allowed to change response shape
+   * outside the route-cache key.
+   */
+  prerenderVariantCapture?: boolean | undefined;
   /**
    * Receives whether the render depended on the incoming request headers.
    *
@@ -243,8 +254,12 @@ export interface RenderAppRequestRuntimeOptions extends RenderAppRequestOptions
    * dependent. Call it only after draining the response body, because a
    * streamed render can read headers while its deferred parts resolve.
    */
-  renderSignals?: { headerDependent: () => boolean } | undefined;
-  serverRenderArtifactLoader?: AppRouterServerRenderArtifactLoader | undefined;
+  renderSignals?:
+    | {
+        headerDependent: () => boolean;
+        strictTransportSecurity: () => string | undefined;
+      }
+    | undefined;
 }
 
 export interface AppRouterRenderPreload {
@@ -565,7 +580,12 @@ const middlewareModuleCache = new Map<string, Promise<MiddlewareModule>>();
 const middlewareModuleCacheCounters = createRouterRuntimeCacheCounters();
 const serverRouteModuleCache = new Map<string, Promise<Record<string, unknown>>>();
 const serverRouteModuleCacheCounters = createRouterRuntimeCacheCounters();
-const composedRouteMetadataCache = new Map<string, Promise<RouteMetadata | undefined>>();
+interface ComposedRouteMetadataCacheEntry {
+  metadata: RouteMetadata | undefined;
+  template: FileConventionMetadataTemplate;
+}
+
+const composedRouteMetadataCache = new Map<string, Promise<ComposedRouteMetadataCacheEntry>>();
 const composedRouteMetadataCacheCounters = createRouterRuntimeCacheCounters();
 const maxServerTransformCacheEntries = resolveRouterCacheLimit("SERVER_TRANSFORM", 512);
 const maxServerSourceFileCacheEntries = resolveRouterCacheLimit("SERVER_SOURCE_FILE", 512);
@@ -688,7 +708,9 @@ export async function renderAppRequest(options: RenderAppRequestOptions): Promis
   };
   invokeRouterInstrumentation(options.instrumentation?.onRequestStart, requestEvent);
   const response = await renderAppRequestInternal({ ...options, requestUrl: url });
-  const finalResponse = await applyAppRouterResponseHook(response, options);
+  const finalResponse = protectNonceBearingResponse(
+    await applyAppRouterResponseHook(response, options),
+  );
   invokeRouterInstrumentation(options.instrumentation?.onRequestEnd, {
     ...requestEvent,
     status: finalResponse.status,
@@ -717,43 +739,24 @@ function finishRenderTimingPhase(
   timing.phases[phaseName] = logDurationMs(startedAt);
 }
 
-async function readSettledPromiseAtNextTask<T>(
-  promise: Promise<T>,
-): Promise<{ settled: true; value: T } | { settled: false }> {
-  return await Promise.race([
-    promise.then((value) => ({ settled: true as const, value })),
-    new Promise<{ settled: false }>((resolve) => {
-      setTimeout(() => resolve({ settled: false }), 0);
-    }),
-  ]);
-}
+type ObservedPromiseSettlement<T> =
+  | { status: "pending" }
+  | { status: "fulfilled"; value: T }
+  | { error: unknown; status: "rejected" };
 
-function createDeferredSignal(): {
-  promise: Promise<void>;
-  resolve(): void;
-} {
-  let resolve: (() => void) | undefined;
-  const promise = new Promise<void>((innerResolve) => {
-    resolve = innerResolve;
-  });
+function observePromiseSettlement<T>(promise: Promise<T>): () => ObservedPromiseSettlement<T> {
+  let settlement: ObservedPromiseSettlement<T> = { status: "pending" };
 
-  return {
-    promise,
-    resolve() {
-      resolve?.();
+  void promise.then(
+    (value) => {
+      settlement = { status: "fulfilled", value };
     },
-  };
-}
-
-async function waitForLoaderReadyOrSettled(
-  dataPromise: Promise<unknown>,
-  loaderReady: Promise<void> | undefined,
-): Promise<void> {
-  if (loaderReady === undefined) {
-    return;
-  }
+    (error: unknown) => {
+      settlement = { error, status: "rejected" };
+    },
+  );
 
-  await Promise.race([loaderReady, dataPromise.then(() => undefined, () => undefined)]);
+  return () => settlement;
 }
 
 function addRenderTimingPhaseDuration(
@@ -768,14 +771,6 @@ function addRenderTimingPhaseDuration(
   timing.phases[phaseName] = (timing.phases[phaseName] ?? 0) + logDurationMs(startedAt);
 }
 
-function routeLoaderMayReturnControlResponse(code: string): boolean {
-  return (
-    /\b(?:redirect|redirectExternal|rewrite|notFound|throwNotFound)\s*\(/.test(code) ||
-    /\bnew\s+Response\s*\(/.test(code) ||
-    /\bResponse\.(?:redirect|json)\s*\(/.test(code)
-  );
-}
-
 async function waitForRenderPreload(
   options: Pick<RenderAppRequestOptions, "preload">,
   timing: RenderTiming | undefined,
@@ -1000,211 +995,526 @@ async function renderAppRequestInternal(
   let trackedRequest: TrackedHeaderRequest | undefined;
   let sourceUsesRequestInput = true;
   let invalidConfiguredHsts = false;
-  return (await withRouteCacheContext(options.routeCache, async () => {
-  try {
-    if (matched.route.kind === "asset") {
-      return await dispatchConventionAssetRoute({
-        file: matched.route.file,
-        request: options.request,
-      });
-    }
-
-    if (matched.route.kind === "metadata") {
-      return await dispatchMetadataRoute({
-        appDir: options.appDir,
-        file: matched.route.file,
-        importPolicy: options.importPolicy,
-        params: matched.params,
-        request: options.request,
-        route: matched.route,
-        serverModules: options.serverModules,
-        serverModuleCacheVersion: options.serverModuleCacheVersion,
-        serverSourceFiles: options.serverSourceFiles,
-        vitePlugins: options.vitePlugins,
-      });
-    }
-
-    if (matched.route.kind === "server") {
-      return await dispatchServerRoute({
-        appDir: options.appDir,
-        env: options.env,
-        file: matched.route.file,
-        importPolicy: options.importPolicy,
-        params: matched.params,
-        request: options.request,
-        route: matched.route,
-        serverModules: options.serverModules,
-        serverModuleCacheVersion: options.serverModuleCacheVersion,
-        serverSourceFiles: options.serverSourceFiles,
-        vitePlugins: options.vitePlugins,
-      });
-    }
-
-    // Issue 080: page routes render HTML for GET / HEAD only. Other
-    // methods (PUT, PATCH, DELETE, PROPFIND, ...) get 405 with an
-    // Allow header so the response shape complies with RFC 9110 §9
-    // and so caching intermediaries do not cross-cache method results.
-    const methodResponse = pageRouteMethodResponse(options.request.method);
-    if (methodResponse !== undefined) {
-      return methodResponse;
-    }
-
-    const clientScript = options.clientScripts?.get(matched.route.path);
-    const clientStyleSheets = options.clientStyles?.get(matched.route.path);
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const originalCode = await readServerSourceFile(
-      matched.route.file,
-      options.serverModuleCacheVersion,
-      options.serverSourceFiles,
-    );
-    finishRenderTimingPhase(timing, phaseStartedAt, "readSourceMs");
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const originalAnalysis = await analyzeRouteSource({
-      appDir: options.appDir,
-      artifact: options.serverModules?.get(matched.route.file)?.analysis,
-      code: originalCode,
-      filename: matched.route.file,
-      routePath: matched.route.path,
-      clientRouteInferenceCache,
-      serverModuleCacheVersion: options.serverModuleCacheVersion,
-      serverSourceFiles: options.serverSourceFiles,
-      define: options.define,
-      timing,
-      vitePlugins: options.vitePlugins,
-    });
-    sourceUsesRequestInput = originalAnalysis.usesRequestInput;
-    finishRenderTimingPhase(timing, phaseStartedAt, "sourceAnalysisMs");
-    const cachePolicy = originalAnalysis.cachePolicy;
-    const navigationScript = options.navigationScripts?.get(matched.route.path);
-    const cacheKey = routeCacheKey(options.appDir, matched.route.path, url);
-    const mayUseRouteCache =
-      !sourceUsesRequestInput &&
-      (cachePolicy === undefined
-        ? originalAnalysis.usesRuntimeCacheControl
-        : cachePolicy.revalidateSeconds !== 0);
-    const reloadRouteCache = isNavigationRouteCacheReloadRequest(options.request);
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const cachedResponse =
-      !mayUseRouteCache || reloadRouteCache
-        ? undefined
-        : await cachedRouteResponse({
-            cache: options.routeCache,
-            key: cacheKey,
+  let renderedStrictTransportSecurity: string | undefined;
+  return (
+    await withRouteCacheContext(options.routeCache, async () => {
+      try {
+        if (matched.route.kind === "asset") {
+          return await dispatchConventionAssetRoute({
+            file: matched.route.file,
             request: options.request,
           });
-    finishRenderTimingPhase(timing, phaseStartedAt, "routeCacheMs");
+        }
 
-    if (cachedResponse !== undefined) {
-      return cachedResponse;
-    }
+        if (matched.route.kind === "metadata") {
+          return await dispatchMetadataRoute({
+            appDir: options.appDir,
+            file: matched.route.file,
+            importPolicy: options.importPolicy,
+            params: matched.params,
+            request: options.request,
+            route: matched.route,
+            serverModules: options.serverModules,
+            serverModuleCacheVersion: options.serverModuleCacheVersion,
+            serverSourceFiles: options.serverSourceFiles,
+            vitePlugins: options.vitePlugins,
+          });
+        }
 
-    // Only a route whose result may be stored pays for header-read tracking;
-    // cache hits returned above never construct it. Application code reads
-    // headers through this request so that a render depending on one is never
-    // stored under a key that ignores it. Callers that store by path alone ask
-    // for tracking through `renderSignals` even when the route itself declares
-    // no cache policy.
-    trackedRequest =
-      mayUseRouteCache || options.renderSignals !== undefined
-        ? trackRequestHeaderReads(options.request)
-        : undefined;
-    const appRequest = trackedRequest?.request ?? options.request;
-
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const preparedActions = await prepareRouteServerActions({
-      appDir: options.appDir,
-      code: originalCode,
-      formActionReferences: options.serverActionReferencesByFile?.get(matched.route.file),
-      placeholders: true,
-      pageFile: matched.route.file,
-      request: options.request,
-    });
-    for (const diagnostic of preparedActions.diagnostics ?? []) {
-      console.warn(`${diagnostic.code}: ${diagnostic.message}`);
-    }
-    finishRenderTimingPhase(timing, phaseStartedAt, "serverActionsMs");
-    const code = preparedActions.code;
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const routeAnalysis =
-      code === originalCode
-        ? originalAnalysis
-        : await analyzeRouteSource({
+        if (matched.route.kind === "server") {
+          return await dispatchServerRoute({
             appDir: options.appDir,
-            buildRenderCode: preparedActions.htmlReplacements !== undefined,
-            code,
-            filename: matched.route.file,
-            routePath: matched.route.path,
-            clientRouteInferenceCache,
-            serverModuleCacheVersion: undefined,
+            env: options.env,
+            file: matched.route.file,
+            importPolicy: options.importPolicy,
+            params: matched.params,
+            request: options.request,
+            route: matched.route,
+            serverModules: options.serverModules,
+            serverModuleCacheVersion: options.serverModuleCacheVersion,
             serverSourceFiles: options.serverSourceFiles,
-            define: options.define,
             vitePlugins: options.vitePlugins,
           });
-    finishRenderTimingPhase(timing, phaseStartedAt, "routeCodeAnalysisMs");
-    const routeCode = routeAnalysis.routeCode;
-    const streamRoute = routeAnalysis.streamRoute;
-    const clientInference = routeAnalysis.clientInference;
-    const clientRoute = clientInference.client;
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const loaderReady = routeAnalysis.hasLoader ? createDeferredSignal() : undefined;
-    const dataPromise = routeAnalysis.hasLoader
-      ? loadRouteDataWithInstrumentation({
+        }
+
+        // Issue 080: page routes render HTML for GET / HEAD only. Other
+        // methods (PUT, PATCH, DELETE, PROPFIND, ...) get 405 with an
+        // Allow header so the response shape complies with RFC 9110 §9
+        // and so caching intermediaries do not cross-cache method results.
+        const methodResponse = pageRouteMethodResponse(options.request.method);
+        if (methodResponse !== undefined) {
+          return methodResponse;
+        }
+
+        const clientScript = options.clientScripts?.get(matched.route.path);
+        const clientStyleSheets = options.clientStyles?.get(matched.route.path);
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+        const originalCode = await readServerSourceFile(
+          matched.route.file,
+          options.serverModuleCacheVersion,
+          options.serverSourceFiles,
+        );
+        finishRenderTimingPhase(timing, phaseStartedAt, "readSourceMs");
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+        const originalAnalysis = await analyzeRouteSource({
           appDir: options.appDir,
+          artifact: options.serverModules?.get(matched.route.file)?.analysis,
           code: originalCode,
-          context: withTrackedRequest({
-            env: options.env,
-            params: matched.params,
-            queryClient,
-          }, appRequest, trackedRequest),
           filename: matched.route.file,
-          importPolicy: options.importPolicy,
-          instrumentation: options.instrumentation,
-          devServerModuleCacheVersion: options.devServerModuleCacheVersion,
-          request: options.request,
-          routeId: routeIdForPath(matched.route.path),
           routePath: matched.route.path,
-          serverModules: options.serverModules,
+          clientRouteInferenceCache,
           serverModuleCacheVersion: options.serverModuleCacheVersion,
+          serverSourceFiles: options.serverSourceFiles,
           define: options.define,
-          vitePlugins: options.vitePlugins,
           timing,
-          onLoaderReady: loaderReady?.resolve,
-        })
-      : undefined;
-    finishRenderTimingPhase(timing, phaseStartedAt, "loaderStartMs");
-    recoveryRoute = {
-      clientRoute,
-      props: {
-        params: matched.params,
-        request: { url: options.request.url },
-      },
-      routePath: matched.route.path,
-      script: clientScript,
-    };
-    if (streamRoute) {
-      phaseStartedAt = renderTimingPhaseStartedAt(timing);
-      const loadingFile = await nearestExistingBoundaryFileForPage({
-        appDir: options.appDir,
-        filename: "loading.mreact.tsx",
-        pageFile: matched.route.file,
-        serverSourceFiles: options.serverSourceFiles,
-      });
-      finishRenderTimingPhase(timing, phaseStartedAt, "loadingBoundaryLookupMs");
-      const streamShellResponseHeaders = {
-        "content-type": "text/html; charset=utf-8",
-        "x-mreact-stream": "1",
-      };
-
-      phaseStartedAt = renderTimingPhaseStartedAt(timing);
-      const mayRenderOutOfOrder = await mayRenderOutOfOrderBoundaryDeep({
-        code: routeCode,
-        filename: matched.route.file,
-        serverModuleCacheVersion: options.serverModuleCacheVersion,
-        serverSourceFiles: options.serverSourceFiles,
-      });
-      finishRenderTimingPhase(timing, phaseStartedAt, "outOfOrderAnalysisMs");
+          vitePlugins: options.vitePlugins,
+        });
+        sourceUsesRequestInput = originalAnalysis.usesRequestInput;
+        finishRenderTimingPhase(timing, phaseStartedAt, "sourceAnalysisMs");
+        const cachePolicy = originalAnalysis.cachePolicy;
+        const navigationScript = options.navigationScripts?.get(matched.route.path);
+        const navigationRequest = isNavigationRequest(options.request);
+        const cacheKey = routeCacheKey(
+          options.appDir,
+          matched.route.path,
+          url,
+          navigationRequest ? "navigation" : "document",
+        );
+        const mayUseRouteCache =
+          !sourceUsesRequestInput &&
+          (cachePolicy === undefined
+            ? originalAnalysis.usesRuntimeCacheControl
+            : cachePolicy.revalidateSeconds !== 0);
+        const reloadRouteCache = isNavigationRouteCacheReloadRequest(options.request);
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+        const cachedResponse =
+          !mayUseRouteCache || reloadRouteCache
+            ? undefined
+            : await cachedRouteResponse({
+                cache: options.routeCache,
+                key: cacheKey,
+                request: options.request,
+              });
+        finishRenderTimingPhase(timing, phaseStartedAt, "routeCacheMs");
+
+        if (cachedResponse !== undefined) {
+          return cachedResponse;
+        }
+
+        // Only a route whose result may be stored pays for header-read tracking;
+        // cache hits returned above never construct it. Application code reads
+        // headers through this request so that a render depending on one is never
+        // stored under a key that ignores it. Callers that store by path alone ask
+        // for tracking through `renderSignals` even when the route itself declares
+        // no cache policy.
+        trackedRequest =
+          mayUseRouteCache || options.renderSignals !== undefined
+            ? trackRequestHeaderReads(options.request)
+            : undefined;
+        const appRequest = trackedRequest?.request ?? options.request;
+
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+        const preparedActions = await prepareRouteServerActions({
+          appDir: options.appDir,
+          code: originalCode,
+          formActionReferences: options.serverActionReferencesByFile?.get(matched.route.file),
+          placeholders: true,
+          pageFile: matched.route.file,
+          request: options.request,
+        });
+        for (const diagnostic of preparedActions.diagnostics ?? []) {
+          console.warn(`${diagnostic.code}: ${diagnostic.message}`);
+        }
+        finishRenderTimingPhase(timing, phaseStartedAt, "serverActionsMs");
+        const code = preparedActions.code;
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+        const routeAnalysis =
+          code === originalCode
+            ? originalAnalysis
+            : await analyzeRouteSource({
+                appDir: options.appDir,
+                buildRenderCode: preparedActions.htmlReplacements !== undefined,
+                code,
+                filename: matched.route.file,
+                routePath: matched.route.path,
+                clientRouteInferenceCache,
+                serverModuleCacheVersion: undefined,
+                serverSourceFiles: options.serverSourceFiles,
+                define: options.define,
+                vitePlugins: options.vitePlugins,
+              });
+        finishRenderTimingPhase(timing, phaseStartedAt, "routeCodeAnalysisMs");
+        const routeCode = routeAnalysis.routeCode;
+        const streamRoute = routeAnalysis.streamRoute;
+        const clientInference = routeAnalysis.clientInference;
+        const clientRoute = clientInference.client;
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+        const dataPromise = routeAnalysis.hasLoader
+          ? loadRouteDataWithInstrumentation({
+              appDir: options.appDir,
+              code: originalCode,
+              context: withTrackedRequest(
+                {
+                  env: options.env,
+                  params: matched.params,
+                  queryClient,
+                },
+                appRequest,
+                trackedRequest,
+              ),
+              filename: matched.route.file,
+              importPolicy: options.importPolicy,
+              instrumentation: options.instrumentation,
+              devServerModuleCacheVersion: options.devServerModuleCacheVersion,
+              request: options.request,
+              routeId: routeIdForPath(matched.route.path),
+              routePath: matched.route.path,
+              serverModules: options.serverModules,
+              serverModuleCacheVersion: options.serverModuleCacheVersion,
+              define: options.define,
+              vitePlugins: options.vitePlugins,
+              timing,
+            })
+          : undefined;
+        // Route analysis and loading-boundary discovery can continue before the loader is awaited.
+        // Observe an early rejection immediately so strict unhandled-rejection runtimes do not
+        // terminate before the request-level control/error handler receives the same promise.
+        void dataPromise?.catch(() => {});
+        finishRenderTimingPhase(timing, phaseStartedAt, "loaderStartMs");
+        recoveryRoute = {
+          clientRoute,
+          props: {
+            params: matched.params,
+            request: { url: url.pathname },
+          },
+          routePath: matched.route.path,
+          script: clientScript,
+        };
+        if (streamRoute) {
+          phaseStartedAt = renderTimingPhaseStartedAt(timing);
+          const loadingFile = await nearestExistingBoundaryFileForPage({
+            appDir: options.appDir,
+            filename: "loading.mreact.tsx",
+            pageFile: matched.route.file,
+            serverSourceFiles: options.serverSourceFiles,
+          });
+          finishRenderTimingPhase(timing, phaseStartedAt, "loadingBoundaryLookupMs");
+          const streamShellResponseHeaders = {
+            "content-type": "text/html; charset=utf-8",
+            "x-mreact-stream": "1",
+          };
+
+          phaseStartedAt = renderTimingPhaseStartedAt(timing);
+          const mayRenderOutOfOrder = await mayRenderOutOfOrderBoundaryDeep({
+            code: routeCode,
+            filename: matched.route.file,
+            serverModuleCacheVersion: options.serverModuleCacheVersion,
+            serverSourceFiles: options.serverSourceFiles,
+          });
+          finishRenderTimingPhase(timing, phaseStartedAt, "outOfOrderAnalysisMs");
+
+          if (loadingFile === undefined && !mayRenderOutOfOrder) {
+            phaseStartedAt = renderTimingPhaseStartedAt(timing);
+            let data: unknown;
+            try {
+              data = dataPromise === undefined ? undefined : await dataPromise;
+            } finally {
+              finishRenderTimingPhase(timing, phaseStartedAt, "loaderWaitMs");
+            }
+            if (data instanceof Response) {
+              emitRenderTiming(options, timing, data.status);
+              return data;
+            }
+            await waitForRenderPreload(options, timing);
+            await loadServerRenderArtifacts(options, matched.route.file, timing);
+            phaseStartedAt = renderTimingPhaseStartedAt(timing);
+            const stringOutput = transformServerModule({
+              code: routeCode,
+              clientBoundaryImports: clientInference.clientBoundaryImports,
+              clientBoundaryFallbackImports: clientInference.clientBoundaryFallbackImports,
+              filename: matched.route.file,
+              serverModules: options.serverModules,
+              serverOutput: "string",
+            });
+            finishRenderTimingPhase(timing, phaseStartedAt, "stringTransformMs");
+            const stringFatalDiagnostics = fatalServerDiagnostics(stringOutput.diagnostics);
+
+            if (stringFatalDiagnostics.length > 0) {
+              return new Response(
+                formatServerDiagnostics(matched.route.file, stringFatalDiagnostics),
+                {
+                  status: 500,
+                  headers: { "content-type": "text/plain; charset=utf-8" },
+                },
+              );
+            }
+
+            const renderedPage = await runWithQueryClient(queryClient, () =>
+              runServerModuleWithSlots(
+                stringOutput.code,
+                withTrackedRequest(
+                  {
+                    data,
+                    params: matched.params,
+                    queryClient,
+                  },
+                  appRequest,
+                  trackedRequest,
+                ),
+                matched.route.file,
+                options.serverModules,
+                options.serverModuleCacheVersion,
+                options.define,
+                options.vitePlugins,
+                undefined,
+                options.importPolicy,
+                options.devServerModuleCacheVersion,
+              ),
+            );
+            const pageHtml = renderedPage.html;
+            const pageHtmlForLayout = clientRoute
+              ? withHydrationMarkers({
+                  assetBaseUrl: options.assetBaseUrl,
+                  clientReferenceManifest: stringOutput.metadata.clientReferenceManifest,
+                  html: pageHtml,
+                  routePath: matched.route.path,
+                  script: clientScript,
+                  props: {
+                    params: matched.params,
+                    request: { url: url.pathname },
+                    data,
+                  },
+                })
+              : withServerOnlyRouteMarkers(
+                  pageHtml,
+                  matched.route.path,
+                  options.request,
+                  options.prerenderVariantCapture === true,
+                );
+            let html = await runWithQueryClient(queryClient, () =>
+              applyLayouts({
+                appDir: options.appDir,
+                pageFile: matched.route.file,
+                html: pageHtmlForLayout,
+                props: withTrackedRequest(
+                  {
+                    data,
+                    params: matched.params,
+                    queryClient,
+                  },
+                  appRequest,
+                  trackedRequest,
+                ),
+                slots: renderedPage.slots,
+                serverModules: options.serverModules,
+                serverModuleCacheVersion: options.serverModuleCacheVersion,
+                serverSourceFiles: options.serverSourceFiles,
+                clientRouteInferenceCache,
+                timing,
+                vitePlugins: options.vitePlugins,
+                importPolicy: options.importPolicy,
+              }),
+            );
+            const metadata = await loadComposedRouteMetadata({
+              appDir: options.appDir,
+              code: originalCode,
+              context: withTrackedRequest(
+                {
+                  data,
+                  params: matched.params,
+                },
+                appRequest,
+                trackedRequest,
+              ),
+              filename: matched.route.file,
+              importPolicy: options.importPolicy,
+              routes,
+              serverModules: options.serverModules,
+              serverModuleCacheVersion: options.serverModuleCacheVersion,
+              devServerModuleCacheVersion: options.devServerModuleCacheVersion,
+              serverSourceFiles: options.serverSourceFiles,
+              define: options.define,
+              vitePlugins: options.vitePlugins,
+            });
+            html = injectHeadMetadata(html, metadata);
+            warnIfCspNonceWouldBlockInlineTags({
+              html,
+              logger: options.logger,
+              metadata,
+              request: options.request,
+              serverModuleCacheVersion: options.serverModuleCacheVersion,
+            });
+            html = injectAuthSessionClaims(
+              html,
+              originalAnalysis.authIncludesClaims ? currentAuthClaims() : undefined,
+            );
+            html = injectQueryState(html, dehydrate(queryClient, options.dehydrateOptions));
+            const response = withOptionalActionCookie(
+              htmlResponse(
+                applyActionHtmlReplacements(
+                  `<!DOCTYPE html>${clientNavigationHeadTags({
+                    assetBaseUrl: options.assetBaseUrl,
+                    currentStyleSheets: clientStyleSheets,
+                    currentScript: clientRoute ? clientScript : undefined,
+                    currentNavigationScript: navigationScript,
+                    routeScripts: options.clientScripts,
+                  })}${html}`,
+                  preparedActions.htmlReplacements,
+                ),
+                {
+                  headers: responseHeadersForMetadata(metadata, options.request, {
+                    "x-mreact-stream": "1",
+                  }),
+                },
+              ),
+              preparedActions.csrfToken,
+              preparedActions.csrfTokenIsNew === true,
+            );
+            appendNavigationVary(response.headers);
+            emitRenderTiming(options, timing, response.status);
+            return response;
+          }
+
+          let streamData: unknown;
+          phaseStartedAt = renderTimingPhaseStartedAt(timing);
+          try {
+            streamData = dataPromise === undefined ? undefined : await dataPromise;
+          } finally {
+            finishRenderTimingPhase(timing, phaseStartedAt, "loaderWaitMs");
+          }
+          if (streamData instanceof Response) {
+            emitRenderTiming(options, timing, streamData.status);
+            return streamData;
+          }
+          const streamDataPromise = Promise.resolve(streamData);
+
+          const streamDataSettlement =
+            loadingFile === undefined ? undefined : observePromiseSettlement(streamDataPromise);
+
+          await waitForRenderPreload(options, timing);
+          await loadServerRenderArtifacts(options, matched.route.file, timing);
+          phaseStartedAt = renderTimingPhaseStartedAt(timing);
+          const output = transformServerModule({
+            code: routeCode,
+            clientBoundaryImports: clientInference.clientBoundaryImports,
+            clientBoundaryFallbackImports: clientInference.clientBoundaryFallbackImports,
+            filename: matched.route.file,
+            serverModules: options.serverModules,
+            serverOutput: "stream",
+            serverAwaitHydration: clientRoute,
+          });
+          finishRenderTimingPhase(timing, phaseStartedAt, "streamTransformMs");
+          const fatalDiagnostics = fatalServerDiagnostics(output.diagnostics);
+
+          if (fatalDiagnostics.length > 0) {
+            return new Response(formatServerDiagnostics(matched.route.file, fatalDiagnostics), {
+              status: 500,
+              headers: { "content-type": "text/plain; charset=utf-8" },
+            });
+          }
+
+          if (loadingFile !== undefined && streamDataSettlement !== undefined) {
+            phaseStartedAt = renderTimingPhaseStartedAt(timing);
+            const errorFile = await nearestExistingBoundaryFileForPage({
+              appDir: options.appDir,
+              filename: "error.mreact.tsx",
+              pageFile: matched.route.file,
+              serverSourceFiles: options.serverSourceFiles,
+            });
+            const streamResult = await runServerStreamModuleWithLoading(output.code, {
+              appDir: options.appDir,
+              assetBaseUrl: options.assetBaseUrl,
+              clientRoute,
+              data: streamDataPromise,
+              dataSettlement: streamDataSettlement,
+              define: options.define,
+              errorFile,
+              loadingFile,
+              markerRequest: options.request,
+              onRenderError: options.onRenderError,
+              prerenderVariantCapture: options.prerenderVariantCapture,
+              pageFile: matched.route.file,
+              params: matched.params,
+              queryClient,
+              request: appRequest,
+              requestUrl: url.pathname,
+              trackedRequest,
+              routePath: matched.route.path,
+              routeScripts: options.clientScripts,
+              serverModules: options.serverModules,
+              serverModuleCacheVersion: options.serverModuleCacheVersion,
+              serverSourceFiles: options.serverSourceFiles,
+              vitePlugins: options.vitePlugins,
+              clientRouteInferenceCache,
+              importPolicy: options.importPolicy,
+              script: clientScript,
+              clientReferenceManifest: output.metadata.clientReferenceManifest,
+            });
+            finishRenderTimingPhase(timing, phaseStartedAt, "streamConstructionMs");
+
+            if (streamResult instanceof Response) {
+              emitRenderTiming(options, timing, streamResult.status);
+              return streamResult;
+            }
+
+            const response = withOptionalActionCookie(
+              new Response(streamResult, {
+                headers: streamShellResponseHeaders,
+              }),
+              preparedActions.csrfToken,
+              preparedActions.csrfTokenIsNew === true,
+            );
+            appendNavigationVary(response.headers);
+            emitRenderTiming(options, timing, response.status);
+            return response;
+          }
+
+          const data = streamData;
+          const props = withTrackedRequest(
+            {
+              data,
+              params: matched.params,
+              queryClient,
+            },
+            appRequest,
+            trackedRequest,
+          );
+          phaseStartedAt = renderTimingPhaseStartedAt(timing);
+          const stream = runServerStreamModule(output.code, {
+            appDir: options.appDir,
+            assetBaseUrl: options.assetBaseUrl,
+            pageFile: matched.route.file,
+            markerRequest: options.request,
+            prerenderVariantCapture: options.prerenderVariantCapture,
+            props,
+            requestUrl: url.pathname,
+            routePath: matched.route.path,
+            routeScripts: options.clientScripts,
+            serverModules: options.serverModules,
+            serverModuleCacheVersion: options.serverModuleCacheVersion,
+            serverSourceFiles: options.serverSourceFiles,
+            define: options.define,
+            vitePlugins: options.vitePlugins,
+            clientRouteInferenceCache,
+            importPolicy: options.importPolicy,
+            clientRoute,
+            script: clientScript,
+            clientReferenceManifest: output.metadata.clientReferenceManifest,
+          });
+          finishRenderTimingPhase(timing, phaseStartedAt, "streamConstructionMs");
+
+          const response = withOptionalActionCookie(
+            new Response(stream, {
+              headers: streamShellResponseHeaders,
+            }),
+            preparedActions.csrfToken,
+            preparedActions.csrfTokenIsNew === true,
+          );
+          appendNavigationVary(response.headers);
+          emitRenderTiming(options, timing, response.status);
+          return response;
+        }
 
-      if (loadingFile === undefined && !mayRenderOutOfOrder) {
         phaseStartedAt = renderTimingPhaseStartedAt(timing);
         let data: unknown;
         try {
@@ -1216,10 +1526,16 @@ async function renderAppRequestInternal(
           emitRenderTiming(options, timing, data.status);
           return data;
         }
+        sourceUsesRequestInput ||= await routeShellsMayUseRequestInput({
+          appDir: options.appDir,
+          pageFile: matched.route.file,
+          serverModuleCacheVersion: options.serverModuleCacheVersion,
+          serverSourceFiles: options.serverSourceFiles,
+        });
         await waitForRenderPreload(options, timing);
         await loadServerRenderArtifacts(options, matched.route.file, timing);
         phaseStartedAt = renderTimingPhaseStartedAt(timing);
-        const stringOutput = transformServerModule({
+        const output = transformServerModule({
           code: routeCode,
           clientBoundaryImports: clientInference.clientBoundaryImports,
           clientBoundaryFallbackImports: clientInference.clientBoundaryFallbackImports,
@@ -1228,63 +1544,79 @@ async function renderAppRequestInternal(
           serverOutput: "string",
         });
         finishRenderTimingPhase(timing, phaseStartedAt, "stringTransformMs");
-        const stringFatalDiagnostics = fatalServerDiagnostics(stringOutput.diagnostics);
+        const fatalDiagnostics = fatalServerDiagnostics(output.diagnostics);
 
-        if (stringFatalDiagnostics.length > 0) {
-          return new Response(formatServerDiagnostics(matched.route.file, stringFatalDiagnostics), {
+        if (fatalDiagnostics.length > 0) {
+          return new Response(formatServerDiagnostics(matched.route.file, fatalDiagnostics), {
             status: 500,
             headers: { "content-type": "text/plain; charset=utf-8" },
           });
         }
 
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
         const renderedPage = await runWithQueryClient(queryClient, () =>
           runServerModuleWithSlots(
-            stringOutput.code,
-            withTrackedRequest({
-              data,
-              params: matched.params,
-              queryClient,
-            }, appRequest, trackedRequest),
+            output.code,
+            withTrackedRequest(
+              {
+                data,
+                params: matched.params,
+                queryClient,
+              },
+              appRequest,
+              trackedRequest,
+            ),
             matched.route.file,
             options.serverModules,
             options.serverModuleCacheVersion,
             options.define,
             options.vitePlugins,
-            undefined,
+            timing,
             options.importPolicy,
             options.devServerModuleCacheVersion,
           ),
         );
+        finishRenderTimingPhase(timing, phaseStartedAt, "pageRenderMs");
         const pageHtml = renderedPage.html;
+        // Wrap the page (not the full document) with the hydration marker so
+        // the marker sits inside <body>, not around <html>. Wrapping <html>
+        // forces the browser HTML parser to strip the wrappers and promote
+        // <head> / <body> children up to the marker, which flattens the
+        // layout into the marker and breaks the hydration target lookup.
         const pageHtmlForLayout = clientRoute
           ? withHydrationMarkers({
               assetBaseUrl: options.assetBaseUrl,
-              clientReferenceManifest: stringOutput.metadata.clientReferenceManifest,
+              clientReferenceManifest: output.metadata.clientReferenceManifest,
               html: pageHtml,
               routePath: matched.route.path,
               script: clientScript,
               props: {
                 params: matched.params,
-                request: { url: options.request.url },
+                request: { url: url.pathname },
                 data,
               },
             })
-          : isNavigationRequest(options.request)
-            ? withRouteMarkers({
-                html: pageHtml,
-                routePath: matched.route.path,
-              })
-            : pageHtml;
+          : withServerOnlyRouteMarkers(
+              pageHtml,
+              matched.route.path,
+              options.request,
+              options.prerenderVariantCapture === true,
+            );
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
         let html = await runWithQueryClient(queryClient, () =>
           applyLayouts({
             appDir: options.appDir,
             pageFile: matched.route.file,
             html: pageHtmlForLayout,
-            props: withTrackedRequest({
-              data,
-              params: matched.params,
-              queryClient,
-            }, appRequest, trackedRequest),
+            props: withTrackedRequest(
+              {
+                data,
+                params: matched.params,
+                queryClient,
+              },
+              appRequest,
+              trackedRequest,
+            ),
             slots: renderedPage.slots,
             serverModules: options.serverModules,
             serverModuleCacheVersion: options.serverModuleCacheVersion,
@@ -1292,16 +1624,21 @@ async function renderAppRequestInternal(
             clientRouteInferenceCache,
             timing,
             vitePlugins: options.vitePlugins,
-            importPolicy: options.importPolicy,
           }),
         );
+        finishRenderTimingPhase(timing, phaseStartedAt, "layoutRenderMs");
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
         const metadata = await loadComposedRouteMetadata({
           appDir: options.appDir,
           code: originalCode,
-          context: withTrackedRequest({
-            data,
-            params: matched.params,
-          }, appRequest, trackedRequest),
+          context: withTrackedRequest(
+            {
+              data,
+              params: matched.params,
+            },
+            appRequest,
+            trackedRequest,
+          ),
           filename: matched.route.file,
           importPolicy: options.importPolicy,
           routes,
@@ -1312,6 +1649,8 @@ async function renderAppRequestInternal(
           define: options.define,
           vitePlugins: options.vitePlugins,
         });
+        finishRenderTimingPhase(timing, phaseStartedAt, "metadataMs");
+        phaseStartedAt = renderTimingPhaseStartedAt(timing);
         html = injectHeadMetadata(html, metadata);
         warnIfCspNonceWouldBlockInlineTags({
           html,
@@ -1324,7 +1663,8 @@ async function renderAppRequestInternal(
           html,
           originalAnalysis.authIncludesClaims ? currentAuthClaims() : undefined,
         );
-        html = injectQueryState(html, dehydrate(queryClient));
+        html = injectQueryState(html, dehydrate(queryClient, options.dehydrateOptions));
+
         const response = withOptionalActionCookie(
           htmlResponse(
             applyActionHtmlReplacements(
@@ -1338,408 +1678,122 @@ async function renderAppRequestInternal(
               preparedActions.htmlReplacements,
             ),
             {
-              headers: responseHeadersForMetadata(metadata, options.request, {
-                "x-mreact-stream": "1",
-              }),
+              headers: responseHeadersForMetadata(metadata, options.request),
             },
           ),
           preparedActions.csrfToken,
           preparedActions.csrfTokenIsNew === true,
         );
-        emitRenderTiming(options, timing, response.status);
-        return response;
-      }
-
-      let streamData: unknown;
-      let streamDataPromise = dataPromise ?? Promise.resolve(undefined);
-      phaseStartedAt = renderTimingPhaseStartedAt(timing);
-      if (loadingFile === undefined || routeLoaderMayReturnControlResponse(originalCode)) {
-        try {
-          streamData = dataPromise === undefined ? undefined : await dataPromise;
-        } finally {
-          finishRenderTimingPhase(timing, phaseStartedAt, "loaderWaitMs");
-        }
-        if (streamData instanceof Response) {
-          emitRenderTiming(options, timing, streamData.status);
-          return streamData;
-        }
-        streamDataPromise = Promise.resolve(streamData);
-      } else {
-        try {
-          const settledData = await readSettledPromiseAtNextTask(streamDataPromise);
-          if (settledData.settled) {
-            if (settledData.value instanceof Response) {
-              emitRenderTiming(options, timing, settledData.value.status);
-              return settledData.value;
-            }
-            streamDataPromise = Promise.resolve(settledData.value);
-          } else {
-            await waitForLoaderReadyOrSettled(streamDataPromise, loaderReady?.promise);
-          }
-        } finally {
-          finishRenderTimingPhase(timing, phaseStartedAt, "loaderWaitMs");
+        appendNavigationVary(response.headers);
+
+        const effectiveCachePolicy = cachePolicy ?? activeRouteCacheContext()?.cachePolicy;
+        const configuredHsts = configuredHstsHeader(metadata?.security);
+        renderedStrictTransportSecurity = configuredHsts;
+        invalidConfiguredHsts = hasInvalidConfiguredHsts(metadata?.security);
+
+        const finalResponse = preparedActions.hasFormActions
+          ? withRouteCacheHeader(response, effectiveCachePolicy)
+          : await cacheRouteResponse({
+              key: cacheKey,
+              cache: options.routeCache,
+              // A policy can still arrive from a runtime cacheControl() call made
+              // outside the page source, which is what `mayUseRouteCache` scans.
+              // Without a tracker there is no evidence the render ignored request
+              // headers, so the entry is treated as header dependent.
+              headerDependent:
+                sourceUsesRequestInput ||
+                invalidConfiguredHsts ||
+                (trackedRequest?.requestDependent() ?? true),
+              ...(configuredHsts === undefined ? {} : { strictTransportSecurity: configuredHsts }),
+              path: matched.route.path,
+              policy: effectiveCachePolicy,
+              request: options.request,
+              response,
+            });
+        finishRenderTimingPhase(timing, phaseStartedAt, "responseBuildMs");
+        emitRenderTiming(options, timing, finalResponse.status);
+        return finalResponse;
+      } catch (error) {
+        if (isRedirectError(error)) {
+          const response = new Response(null, {
+            headers: { location: error.location },
+            status: error.status,
+          });
+          emitRenderTiming(options, timing, response.status);
+          return response;
         }
-      }
 
-      await waitForRenderPreload(options, timing);
-      await loadServerRenderArtifacts(options, matched.route.file, timing);
-      phaseStartedAt = renderTimingPhaseStartedAt(timing);
-      const output = transformServerModule({
-        code: routeCode,
-        clientBoundaryImports: clientInference.clientBoundaryImports,
-        clientBoundaryFallbackImports: clientInference.clientBoundaryFallbackImports,
-        filename: matched.route.file,
-        serverModules: options.serverModules,
-        serverOutput: "stream",
-        serverAwaitHydration: clientRoute,
-      });
-      finishRenderTimingPhase(timing, phaseStartedAt, "streamTransformMs");
-      const fatalDiagnostics = fatalServerDiagnostics(output.diagnostics);
+        if (isNotFoundError(error)) {
+          const notFoundFile = await nearestBoundaryFileForPage({
+            appDir: options.appDir,
+            filename: "not-found.mreact.tsx",
+            pageFile: matched.route.file,
+          });
 
-      if (fatalDiagnostics.length > 0) {
-        return new Response(formatServerDiagnostics(matched.route.file, fatalDiagnostics), {
-          status: 500,
-          headers: { "content-type": "text/plain; charset=utf-8" },
+          const response = await renderSpecialRoute({
+            appDir: options.appDir,
+            assetBaseUrl: options.assetBaseUrl,
+            currentStyleSheets: options.clientStylesByFile?.get(notFoundFile),
+            error: undefined,
+            request: options.request,
+            routePath: matched.route.path,
+            routeFile: notFoundFile,
+            routeScripts: options.clientScripts,
+            serverModules: options.serverModules,
+            serverModuleCacheVersion: options.serverModuleCacheVersion,
+            serverSourceFiles: options.serverSourceFiles,
+            vitePlugins: options.vitePlugins,
+            navigation: recoveryRoute,
+            status: 404,
+            textFallback: "Not Found",
+          });
+          emitRenderTiming(options, timing, response.status);
+          return response;
+        }
+
+        const errorFile = await nearestBoundaryFileForPage({
+          appDir: options.appDir,
+          filename: "error.mreact.tsx",
+          pageFile: matched.route.file,
         });
-      }
+        options.onRenderError?.(error);
 
-      if (loadingFile !== undefined) {
-        phaseStartedAt = renderTimingPhaseStartedAt(timing);
-        const stream = await runServerStreamModuleWithLoading(output.code, {
+        const response = await renderSpecialRoute({
           appDir: options.appDir,
           assetBaseUrl: options.assetBaseUrl,
-          clientRoute,
-          data: streamDataPromise,
-          define: options.define,
-          loadingFile,
-          pageFile: matched.route.file,
-          params: matched.params,
-          queryClient,
-          request: appRequest,
-          trackedRequest,
+          currentStyleSheets: options.clientStylesByFile?.get(errorFile),
+          error,
+          request: options.request,
           routePath: matched.route.path,
+          routeFile: errorFile,
           routeScripts: options.clientScripts,
           serverModules: options.serverModules,
           serverModuleCacheVersion: options.serverModuleCacheVersion,
           serverSourceFiles: options.serverSourceFiles,
           vitePlugins: options.vitePlugins,
-          clientRouteInferenceCache,
-          importPolicy: options.importPolicy,
-          script: clientScript,
-          clientReferenceManifest: output.metadata.clientReferenceManifest,
+          navigation: recoveryRoute,
+          status: 500,
+          textFallback: "Internal Server Error",
         });
-        finishRenderTimingPhase(timing, phaseStartedAt, "streamConstructionMs");
-
-        const response = withOptionalActionCookie(
-          new Response(stream, {
-            headers: streamShellResponseHeaders,
-          }),
-          preparedActions.csrfToken,
-          preparedActions.csrfTokenIsNew === true,
-        );
         emitRenderTiming(options, timing, response.status);
         return response;
-      }
-
-      const data = streamData;
-      const props = withTrackedRequest({
-        data,
-        params: matched.params,
-        queryClient,
-      }, appRequest, trackedRequest);
-      phaseStartedAt = renderTimingPhaseStartedAt(timing);
-      const stream = runServerStreamModule(output.code, {
-        appDir: options.appDir,
-        assetBaseUrl: options.assetBaseUrl,
-        pageFile: matched.route.file,
-        props,
-        routePath: matched.route.path,
-        routeScripts: options.clientScripts,
-        serverModules: options.serverModules,
-        serverModuleCacheVersion: options.serverModuleCacheVersion,
-        serverSourceFiles: options.serverSourceFiles,
-        define: options.define,
-        vitePlugins: options.vitePlugins,
-        clientRouteInferenceCache,
-        importPolicy: options.importPolicy,
-        clientRoute,
-        script: clientScript,
-        clientReferenceManifest: output.metadata.clientReferenceManifest,
-      });
-      finishRenderTimingPhase(timing, phaseStartedAt, "streamConstructionMs");
-
-      const response = withOptionalActionCookie(
-        new Response(stream, {
-          headers: streamShellResponseHeaders,
-        }),
-        preparedActions.csrfToken,
-        preparedActions.csrfTokenIsNew === true,
-      );
-      emitRenderTiming(options, timing, response.status);
-      return response;
-    }
-
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    let data: unknown;
-    try {
-      data = dataPromise === undefined ? undefined : await dataPromise;
-    } finally {
-      finishRenderTimingPhase(timing, phaseStartedAt, "loaderWaitMs");
-    }
-    if (data instanceof Response) {
-      emitRenderTiming(options, timing, data.status);
-      return data;
-    }
-    sourceUsesRequestInput ||= await routeShellsMayUseRequestInput({
-      appDir: options.appDir,
-      pageFile: matched.route.file,
-      serverModuleCacheVersion: options.serverModuleCacheVersion,
-      serverSourceFiles: options.serverSourceFiles,
-    });
-    await waitForRenderPreload(options, timing);
-    await loadServerRenderArtifacts(options, matched.route.file, timing);
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const output = transformServerModule({
-      code: routeCode,
-      clientBoundaryImports: clientInference.clientBoundaryImports,
-      clientBoundaryFallbackImports: clientInference.clientBoundaryFallbackImports,
-      filename: matched.route.file,
-      serverModules: options.serverModules,
-      serverOutput: "string",
-    });
-    finishRenderTimingPhase(timing, phaseStartedAt, "stringTransformMs");
-    const fatalDiagnostics = fatalServerDiagnostics(output.diagnostics);
-
-    if (fatalDiagnostics.length > 0) {
-      return new Response(formatServerDiagnostics(matched.route.file, fatalDiagnostics), {
-        status: 500,
-        headers: { "content-type": "text/plain; charset=utf-8" },
-      });
-    }
-
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const renderedPage = await runWithQueryClient(queryClient, () =>
-      runServerModuleWithSlots(
-        output.code,
-        withTrackedRequest({
-          data,
-          params: matched.params,
-          queryClient,
-        }, appRequest, trackedRequest),
-        matched.route.file,
-        options.serverModules,
-        options.serverModuleCacheVersion,
-        options.define,
-        options.vitePlugins,
-        timing,
-        options.importPolicy,
-        options.devServerModuleCacheVersion,
-      ),
-    );
-    finishRenderTimingPhase(timing, phaseStartedAt, "pageRenderMs");
-    const pageHtml = renderedPage.html;
-    // Wrap the page (not the full document) with the hydration marker so
-    // the marker sits inside <body>, not around <html>. Wrapping <html>
-    // forces the browser HTML parser to strip the wrappers and promote
-    // <head> / <body> children up to the marker, which flattens the
-    // layout into the marker and breaks the hydration target lookup.
-    const pageHtmlForLayout = clientRoute
-      ? withHydrationMarkers({
-          assetBaseUrl: options.assetBaseUrl,
-          clientReferenceManifest: output.metadata.clientReferenceManifest,
-          html: pageHtml,
-          routePath: matched.route.path,
-          script: clientScript,
-          props: {
-            params: matched.params,
-            request: { url: options.request.url },
-            data,
-          },
-        })
-      : isNavigationRequest(options.request)
-        ? withRouteMarkers({
-            html: pageHtml,
-            routePath: matched.route.path,
-          })
-        : pageHtml;
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    let html = await runWithQueryClient(queryClient, () =>
-      applyLayouts({
-        appDir: options.appDir,
-        pageFile: matched.route.file,
-        html: pageHtmlForLayout,
-        props: withTrackedRequest({
-          data,
-          params: matched.params,
-          queryClient,
-        }, appRequest, trackedRequest),
-        slots: renderedPage.slots,
-        serverModules: options.serverModules,
-        serverModuleCacheVersion: options.serverModuleCacheVersion,
-        serverSourceFiles: options.serverSourceFiles,
-        clientRouteInferenceCache,
-        timing,
-        vitePlugins: options.vitePlugins,
-      }),
-    );
-    finishRenderTimingPhase(timing, phaseStartedAt, "layoutRenderMs");
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    const metadata = await loadComposedRouteMetadata({
-      appDir: options.appDir,
-      code: originalCode,
-      context: withTrackedRequest({
-        data,
-        params: matched.params,
-      }, appRequest, trackedRequest),
-      filename: matched.route.file,
-      importPolicy: options.importPolicy,
-      routes,
-      serverModules: options.serverModules,
-      serverModuleCacheVersion: options.serverModuleCacheVersion,
-      devServerModuleCacheVersion: options.devServerModuleCacheVersion,
-      serverSourceFiles: options.serverSourceFiles,
-      define: options.define,
-      vitePlugins: options.vitePlugins,
-    });
-    finishRenderTimingPhase(timing, phaseStartedAt, "metadataMs");
-    phaseStartedAt = renderTimingPhaseStartedAt(timing);
-    html = injectHeadMetadata(html, metadata);
-    warnIfCspNonceWouldBlockInlineTags({
-      html,
-      logger: options.logger,
-      metadata,
-      request: options.request,
-      serverModuleCacheVersion: options.serverModuleCacheVersion,
-    });
-    html = injectAuthSessionClaims(
-      html,
-      originalAnalysis.authIncludesClaims ? currentAuthClaims() : undefined,
-    );
-    html = injectQueryState(html, dehydrate(queryClient));
-
-    const response = withOptionalActionCookie(
-      htmlResponse(
-        applyActionHtmlReplacements(
-          `<!DOCTYPE html>${clientNavigationHeadTags({
-            assetBaseUrl: options.assetBaseUrl,
-            currentStyleSheets: clientStyleSheets,
-            currentScript: clientRoute ? clientScript : undefined,
-            currentNavigationScript: navigationScript,
-            routeScripts: options.clientScripts,
-          })}${html}`,
-          preparedActions.htmlReplacements,
-        ),
-        {
-          headers: responseHeadersForMetadata(metadata, options.request),
-        },
-      ),
-      preparedActions.csrfToken,
-      preparedActions.csrfTokenIsNew === true,
-    );
-
-    const effectiveCachePolicy = cachePolicy ?? activeRouteCacheContext()?.cachePolicy;
-    const configuredHsts = configuredHstsHeader(metadata?.security);
-    invalidConfiguredHsts = hasInvalidConfiguredHsts(metadata?.security);
-
-    const finalResponse = preparedActions.hasFormActions
-      ? withRouteCacheHeader(response, effectiveCachePolicy)
-      : await cacheRouteResponse({
-          key: cacheKey,
-          cache: options.routeCache,
-          // A policy can still arrive from a runtime cacheControl() call made
-          // outside the page source, which is what `mayUseRouteCache` scans.
-          // Without a tracker there is no evidence the render ignored request
-          // headers, so the entry is treated as header dependent.
-          headerDependent:
+      } finally {
+        // Reported from every return path, including the streaming ones, so that a
+        // caller storing by path alone never mistakes an unreported render for a
+        // shareable one. The value stays lazy because a streamed render can still
+        // read request headers while its deferred parts resolve; callers read it
+        // after draining the body.
+        if (options.renderSignals !== undefined) {
+          const tracked = trackedRequest;
+          options.renderSignals.headerDependent = () =>
             sourceUsesRequestInput ||
             invalidConfiguredHsts ||
-            (trackedRequest?.requestDependent() ?? true),
-          ...(configuredHsts === undefined ? {} : { strictTransportSecurity: configuredHsts }),
-          path: matched.route.path,
-          policy: effectiveCachePolicy,
-          request: options.request,
-          response,
-        });
-    finishRenderTimingPhase(timing, phaseStartedAt, "responseBuildMs");
-    emitRenderTiming(options, timing, finalResponse.status);
-    return finalResponse;
-  } catch (error) {
-    if (isRedirectError(error)) {
-      const response = new Response(null, {
-        headers: { location: error.location },
-        status: error.status,
-      });
-      emitRenderTiming(options, timing, response.status);
-      return response;
-    }
-
-    if (isNotFoundError(error)) {
-      const notFoundFile = await nearestBoundaryFileForPage({
-        appDir: options.appDir,
-        filename: "not-found.mreact.tsx",
-        pageFile: matched.route.file,
-      });
-
-      const response = await renderSpecialRoute({
-        appDir: options.appDir,
-        assetBaseUrl: options.assetBaseUrl,
-        currentStyleSheets: options.clientStylesByFile?.get(notFoundFile),
-        error: undefined,
-        request: options.request,
-        routePath: matched.route.path,
-        routeFile: notFoundFile,
-        routeScripts: options.clientScripts,
-        serverModules: options.serverModules,
-        serverModuleCacheVersion: options.serverModuleCacheVersion,
-        serverSourceFiles: options.serverSourceFiles,
-        vitePlugins: options.vitePlugins,
-        navigation: recoveryRoute,
-        status: 404,
-        textFallback: "Not Found",
-      });
-      emitRenderTiming(options, timing, response.status);
-      return response;
-    }
-
-    const errorFile = await nearestBoundaryFileForPage({
-      appDir: options.appDir,
-      filename: "error.mreact.tsx",
-      pageFile: matched.route.file,
-    });
-    options.onRenderError?.(error);
-
-    const response = await renderSpecialRoute({
-      appDir: options.appDir,
-      assetBaseUrl: options.assetBaseUrl,
-      currentStyleSheets: options.clientStylesByFile?.get(errorFile),
-      error,
-      request: options.request,
-      routePath: matched.route.path,
-      routeFile: errorFile,
-      routeScripts: options.clientScripts,
-      serverModules: options.serverModules,
-      serverModuleCacheVersion: options.serverModuleCacheVersion,
-      serverSourceFiles: options.serverSourceFiles,
-      vitePlugins: options.vitePlugins,
-      navigation: recoveryRoute,
-      status: 500,
-      textFallback: "Internal Server Error",
-    });
-    emitRenderTiming(options, timing, response.status);
-    return response;
-  } finally {
-    // Reported from every return path, including the streaming ones, so that a
-    // caller storing by path alone never mistakes an unreported render for a
-    // shareable one. The value stays lazy because a streamed render can still
-    // read request headers while its deferred parts resolve; callers read it
-    // after draining the body.
-    if (options.renderSignals !== undefined) {
-      const tracked = trackedRequest;
-      options.renderSignals.headerDependent = () =>
-        sourceUsesRequestInput || invalidConfiguredHsts || (tracked?.requestDependent() ?? true);
-    }
-  }
-  })).value;
+            (tracked?.requestDependent() ?? true);
+          options.renderSignals.strictTransportSecurity = () => renderedStrictTransportSecurity;
+        }
+      }
+    })
+  ).value;
 }
 
 async function applyAppRouterResponseHook(
@@ -1966,6 +2020,48 @@ function isNavigationRequest(request: Request): boolean {
   return request.headers.get("x-mreact-navigation") === "1";
 }
 
+function withServerOnlyRouteMarkers(
+  html: string,
+  routePath: string,
+  request: Request,
+  prerenderVariantCapture: boolean,
+): string {
+  const marker = serverOnlyRouteMarkerParts(routePath, request, prerenderVariantCapture);
+  return marker === undefined ? html : `${marker.prefix}${html}${marker.suffix}`;
+}
+
+function serverOnlyRouteMarkerParts(
+  routePath: string,
+  request: Request,
+  prerenderVariantCapture: boolean,
+): { prefix: string; suffix: string } | undefined {
+  if (prerenderVariantCapture) {
+    return prerenderVariantMarkerParts(routePath);
+  }
+  return isNavigationRequest(request) ? routeMarkerParts(routePath) : undefined;
+}
+
+export function prerenderVariantMarkerParts(routePath: string): {
+  prefix: string;
+  suffix: string;
+} {
+  const routeId = routeIdForPath(routePath);
+  return {
+    prefix: `<!--mreact-route-variant-start:${routeId}-->`,
+    suffix: `<!--mreact-route-variant-end:${routeId}-->`,
+  };
+}
+
+function appendNavigationVary(headers: Headers): void {
+  const vary = headers.get("vary");
+  if (
+    vary?.split(",").some((value) => value.trim().toLowerCase() === "x-mreact-navigation") === true
+  ) {
+    return;
+  }
+  headers.append("vary", "x-mreact-navigation");
+}
+
 function isNavigationRouteCacheReloadRequest(request: Request): boolean {
   return (
     isNavigationRequest(request) && request.headers.get("x-mreact-navigation-cache") === "reload"
@@ -2148,15 +2244,7 @@ async function renderSpecialRoute(options: {
   }
 
   const props = {
-    data: undefined,
-    debug: errorDebugContext(options.error, options.routePath),
-    error: normalizeErrorForProps(options.error),
-    params: {},
-    queryClient: createQueryClient(),
-    request: options.request,
-    requestId: requestIdForErrorContext(options.request),
-    routeId: routeIdForPath(options.routePath ?? new URL(options.request.url).pathname),
-    traceId: traceContextFromRequest(options.request)?.traceId,
+    ...errorBoundaryProps(options.error, options.request, options.routePath),
   };
   const pageHtml = await renderServerFileToHtml(
     options.routeFile,
@@ -2205,6 +2293,20 @@ async function renderSpecialRoute(options: {
   );
 }
 
+function errorBoundaryProps(error: unknown, request: Request, routePath: string | undefined) {
+  return {
+    data: undefined,
+    debug: errorDebugContext(error, routePath),
+    error: normalizeErrorForProps(error),
+    params: {},
+    queryClient: createQueryClient(),
+    request,
+    requestId: requestIdForErrorContext(request),
+    routeId: routeIdForPath(routePath ?? new URL(request.url).pathname),
+    traceId: traceContextFromRequest(request)?.traceId,
+  };
+}
+
 async function renderServerFileToHtml(
   file: string,
   props: ServerComponentProps,
@@ -3399,8 +3501,11 @@ function runServerStreamModule(
     appDir: string;
     assetBaseUrl?: string | undefined;
     clientRouteInferenceCache: ClientRouteInferenceCache;
+    markerRequest: Request;
+    prerenderVariantCapture?: boolean | undefined;
     pageFile: string;
     props: ServerComponentProps;
+    requestUrl: string;
     routePath: string;
     routeScripts?: ReadonlyMap<string, string> | undefined;
     clientRoute: boolean;
@@ -3445,11 +3550,15 @@ function runServerStreamModule(
           script: options.script,
           props: {
             params: options.props.params,
-            request: { url: options.props.request.url },
+            request: { url: options.requestUrl },
             data: options.props.data,
           },
         })
-      : undefined;
+      : serverOnlyRouteMarkerParts(
+          options.routePath,
+          options.markerRequest,
+          options.prerenderVariantCapture === true,
+        );
 
     sink.append("<!DOCTYPE html>");
     sink.append(
@@ -3665,12 +3774,18 @@ async function runServerStreamModuleWithLoading(
     clientRoute: boolean;
     clientReferenceManifest?: readonly ClientReferenceMetadata[] | undefined;
     data: Promise<unknown>;
+    dataSettlement: () => ObservedPromiseSettlement<unknown>;
     define?: UserConfig["define"] | undefined;
+    errorFile?: string | undefined;
     loadingFile: string;
+    markerRequest: Request;
+    onRenderError?: ((error: unknown) => void) | undefined;
+    prerenderVariantCapture?: boolean | undefined;
     pageFile: string;
     params: RouteParams;
     queryClient: QueryClient;
     request: Request;
+    requestUrl: string;
     trackedRequest?: TrackedHeaderRequest | undefined;
     routePath: string;
     routeScripts?: ReadonlyMap<string, string> | undefined;
@@ -3681,12 +3796,16 @@ async function runServerStreamModuleWithLoading(
     vitePlugins?: readonly PluginOption[] | undefined;
     importPolicy?: AppRouterImportPolicy | undefined;
   },
-): Promise<ReadableStream<Uint8Array>> {
-  const loadingProps = withTrackedRequest({
-    data: undefined,
-    params: options.params,
-    queryClient: options.queryClient,
-  }, options.request, options.trackedRequest);
+): Promise<ReadableStream<Uint8Array> | Response> {
+  const loadingProps = withTrackedRequest(
+    {
+      data: undefined,
+      params: options.params,
+      queryClient: options.queryClient,
+    },
+    options.request,
+    options.trackedRequest,
+  );
   const layoutShells = await layoutShellsForPage(
     options.appDir,
     options.pageFile,
@@ -3717,10 +3836,24 @@ async function runServerStreamModuleWithLoading(
         script: options.script,
         props: {
           params: options.params,
-          request: { url: options.request.url },
+          request: { url: options.requestUrl },
         },
       })
-    : undefined;
+    : serverOnlyRouteMarkerParts(
+        options.routePath,
+        options.markerRequest,
+        options.prerenderVariantCapture === true,
+      );
+
+  const dataSettlement = options.dataSettlement();
+
+  if (dataSettlement.status === "rejected") {
+    throw dataSettlement.error;
+  }
+
+  if (dataSettlement.status === "fulfilled" && dataSettlement.value instanceof Response) {
+    return dataSettlement.value;
+  }
 
   return renderToReadableStream((sink) => {
     sink.append("<!DOCTYPE html>");
@@ -3738,7 +3871,7 @@ async function runServerStreamModuleWithLoading(
 
     sink.append(marker?.prefix ?? "");
 
-    renderVisibleOutOfOrderBoundary(
+    renderOutOfOrderBoundary(
       sink,
       "mreact-route",
       options.data,
@@ -3746,11 +3879,15 @@ async function runServerStreamModuleWithLoading(
         await appendServerStreamModule(
           code,
           boundarySink,
-          withTrackedRequest({
-            data,
-            params: options.params,
-            queryClient: options.queryClient,
-          }, options.request, options.trackedRequest),
+          withTrackedRequest(
+            {
+              data,
+              params: options.params,
+              queryClient: options.queryClient,
+            },
+            options.request,
+            options.trackedRequest,
+          ),
           options.pageFile,
           options.serverModules,
           options.serverModuleCacheVersion,
@@ -3760,6 +3897,34 @@ async function runServerStreamModuleWithLoading(
         );
       },
       {
+        async catch(boundarySink, error) {
+          try {
+            options.onRenderError?.(error);
+          } catch {
+            // Error reporting is best-effort and must not truncate a response that already flushed.
+          }
+
+          if (options.errorFile === undefined) {
+            boundarySink.append("Internal Server Error");
+            return;
+          }
+
+          try {
+            boundarySink.append(
+              await renderServerFileToHtml(
+                options.errorFile,
+                errorBoundaryProps(error, options.request, options.routePath),
+                options.serverModules,
+                options.serverModuleCacheVersion,
+                options.serverSourceFiles,
+                options.define,
+                options.vitePlugins,
+              ),
+            );
+          } catch {
+            boundarySink.append("Internal Server Error");
+          }
+        },
         placeholder(boundarySink) {
           boundarySink.append(loadingHtml);
         },
@@ -3777,70 +3942,6 @@ async function runServerStreamModuleWithLoading(
   });
 }
 
-function renderVisibleOutOfOrderBoundary<T>(
-  sink: HtmlSink,
-  id: string,
-  value: T,
-  render: (sink: HtmlSink, value: Awaited<T>) => void | PromiseLike<void>,
-  options: {
-    catch?: (sink: HtmlSink, error: unknown) => void | PromiseLike<void>;
-    placeholder?: (sink: HtmlSink) => void | PromiseLike<void>;
-    placeholderTag?: string;
-  } = {},
-): void {
-  const placeholderSink = createStringSink();
-  void options.placeholder?.(placeholderSink);
-  const placeholderTag = normalizeVisibleOutOfOrderPlaceholderTag(options.placeholderTag);
-  sink.append(
-    `<${placeholderTag} data-mreact-oob-placeholder="${escapeHtmlAttribute(id)}">${placeholderSink.toString()}</${placeholderTag}>`,
-  );
-
-  const task = renderVisibleOutOfOrderFragment(sink, id, value, render, options);
-
-  if (sink.defer === undefined) {
-    void task;
-    return;
-  }
-
-  sink.defer(task);
-}
-
-function normalizeVisibleOutOfOrderPlaceholderTag(tag: unknown): string {
-  if (typeof tag !== "string") {
-    return "span";
-  }
-
-  const normalized = tag.trim().toLowerCase();
-  return /^[a-z][a-z0-9-]*$/.test(normalized) ? normalized : "span";
-}
-
-async function renderVisibleOutOfOrderFragment<T>(
-  sink: HtmlSink,
-  id: string,
-  value: T,
-  render: (sink: HtmlSink, value: Awaited<T>) => void | PromiseLike<void>,
-  options: {
-    catch?: (sink: HtmlSink, error: unknown) => void | PromiseLike<void>;
-  },
-): Promise<void> {
-  const fragmentSink = createStringSink();
-
-  await renderAsyncBoundary(
-    fragmentSink,
-    value,
-    render,
-    options.catch === undefined ? {} : { catch: options.catch },
-  );
-  await fragmentSink.drain();
-
-  sink.append(renderVisibleOutOfOrderFragmentHtml(id, fragmentSink.toString()));
-}
-
-function renderVisibleOutOfOrderFragmentHtml(id: string, html: string): string {
-  const escapedId = escapeHtmlAttribute(id);
-  return `<template data-mreact-oob-fragment="${escapedId}">${html}</template><mreact-oob-complete hidden data-mreact-oob-complete="${escapedId}"></mreact-oob-complete>`;
-}
-
 async function appendServerStreamModule(
   code: string,
   sink: HtmlSink,
@@ -5053,7 +5154,12 @@ async function loadComposedRouteMetadata(options: {
       composedRouteMetadataCacheCounters,
     );
     if (cached !== undefined) {
-      return cached;
+      const entry = await cached;
+      return applyFileConventionMetadataTemplate(
+        entry.metadata,
+        entry.template,
+        options.context.params,
+      );
     }
   }
 
@@ -5063,13 +5169,17 @@ async function loadComposedRouteMetadata(options: {
       setBoundedCacheEntry(
         composedRouteMetadataCache,
         cacheKey,
-        Promise.resolve(loaded.metadata),
+        Promise.resolve({ metadata: loaded.metadata, template: loaded.template }),
         maxComposedRouteMetadataCacheEntries,
         composedRouteMetadataCacheCounters,
       );
     }
 
-    return loaded.metadata;
+    return applyFileConventionMetadataTemplate(
+      loaded.metadata,
+      loaded.template,
+      options.context.params,
+    );
   } catch (error) {
     if (cacheKey !== undefined) {
       composedRouteMetadataCache.delete(cacheKey);
@@ -5111,7 +5221,11 @@ async function loadComposedRouteMetadataUncached(options: {
   serverModuleCacheVersion?: string | undefined;
   serverSourceFiles?: ReadonlyMap<string, string> | undefined;
   vitePlugins?: readonly PluginOption[] | undefined;
-}): Promise<{ dynamic: boolean; metadata: RouteMetadata | undefined }> {
+}): Promise<{
+  dynamic: boolean;
+  metadata: RouteMetadata | undefined;
+  template: FileConventionMetadataTemplate;
+}> {
   const layoutFiles = await shellFilesForPage(
     options.appDir,
     options.filename,
@@ -5174,12 +5288,8 @@ async function loadComposedRouteMetadataUncached(options: {
 
   return {
     dynamic,
-    metadata: applyFileConventionMetadata(
-      mergeRouteMetadata(metadata),
-      options.routes,
-      options.filename,
-      options.context.params,
-    ),
+    metadata: mergeRouteMetadata(metadata),
+    template: fileConventionMetadataTemplate(options.routes, options.filename),
   };
 }