react-bun-ssr 0.3.2 → 0.4.1

package/framework/runtime/request-executor.ts

@@ -0,0 +1,1705 @@
+import path from "node:path";
+import { createElement, type ReactElement, type ReactNode } from "react";
+import { createBunRouteAdapter, type BunRouteAdapter } from "./bun-route-adapter";
+import {
+  isDeferredLoaderResult,
+  prepareDeferredPayload,
+  type DeferredSettleEntry,
+} from "./deferred";
+import { isRedirectResult, json } from "./helpers";
+import { statPath } from "./io";
+import { runMiddlewareChain } from "./middleware";
+import {
+  extractRouteMiddleware,
+  loadApiRouteModule,
+  loadGlobalMiddleware,
+  loadNestedMiddleware,
+  loadRouteModule,
+  loadRouteModules,
+  type RouteModuleLoadOptions,
+} from "./module-loader";
+import {
+  collectHeadMarkup,
+  collectHeadElements,
+  createManagedHeadMarkup,
+  renderDocumentStream as defaultRenderDocumentStream,
+} from "./render";
+import {
+  sanitizeRouteErrorResponse,
+  toRouteErrorHttpResponse,
+  toRouteErrorResponse,
+} from "./route-errors";
+import { sortRoutesBySpecificity } from "./route-order";
+import { applyResponseContext, createResponseContext } from "./response-context";
+import {
+  createCatchAppTree,
+  createErrorAppTree,
+  createNotFoundAppTree,
+  createPageAppTree,
+} from "./tree";
+import type {
+  ActionContext,
+  ActionResponseEnvelope,
+  ApiRouteModule,
+  BuildRouteAsset,
+  ClientRouteSnapshot,
+  ClientRouterSnapshot,
+  HydrationDocumentAssets,
+  LoaderContext,
+  Middleware,
+  PageRouteDefinition,
+  RenderPayload,
+  RequestContext,
+  ResolvedConfig,
+  RouteCatchContext,
+  RouteErrorContext,
+  RouteErrorPhase,
+  RouteErrorResponse,
+  RouteManifest,
+  RouteModule,
+  RouteModuleBundle,
+  ServerRuntimeOptions,
+  TransitionChunk,
+  TransitionDeferredChunk,
+  TransitionDocumentChunk,
+  TransitionInitialChunk,
+  TransitionRedirectChunk,
+} from "./types";
+import {
+  ensureWithin,
+  isMutatingMethod,
+  normalizeSlashes,
+  parseCookieHeader,
+  sanitizeErrorMessage,
+  stableHash,
+} from "./utils";
+
+export interface RequestExecutor {
+  fetch(request: Request): Promise<Response>;
+}
+
+export interface RequestExecutorDeps {
+  getRouteAdapter(activeConfig: ResolvedConfig): Promise<BunRouteAdapter>;
+  loadRouteBundle(options: {
+    rootFilePath: string;
+    layoutFiles: string[];
+    routeFilePath: string;
+    routeServerFilePath?: string;
+    cacheBustKey?: string;
+    serverBytecode?: boolean;
+    devSourceImports?: boolean;
+    nodeEnv?: "development" | "production";
+  }): Promise<RouteModuleBundle>;
+  loadApiModule(filePath: string, options: RouteModuleLoadOptions): Promise<ApiRouteModule>;
+  loadGlobalMiddleware(
+    filePath: string,
+    options: RouteModuleLoadOptions | string,
+  ): Promise<Middleware[]>;
+  loadNestedMiddleware(
+    filePaths: string[],
+    options: RouteModuleLoadOptions | string,
+  ): Promise<Middleware[]>;
+  renderDocumentStream(options: {
+    appTree: ReactElement;
+    payload: RenderPayload;
+    assets: HydrationDocumentAssets;
+    headElements: ReactNode[];
+    routerSnapshot: ClientRouterSnapshot;
+    deferredSettleEntries?: DeferredSettleEntry[];
+  }): Promise<ReadableStream<Uint8Array>>;
+}
+
+type ResponseKind =
+  | "static"
+  | "html"
+  | "api"
+  | "internal-dev"
+  | "internal-transition"
+  | "internal-action";
+
+const HASHED_CLIENT_CHUNK_RE = /^\/client\/.+-[A-Za-z0-9]{6,}\.(?:js|css)$/;
+const STATIC_IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+const STATIC_DEFAULT_CACHE = "public, max-age=3600";
+
+function toRedirectResponse(location: string, status = 302): Response {
+  return Response.redirect(location, status);
+}
+
+function isResponse(value: unknown): value is Response {
+  return value instanceof Response;
+}
+
+function resolveThrownRedirect(error: unknown): Response | null {
+  if (!(error instanceof Response)) {
+    return null;
+  }
+
+  const location = error.headers.get("location");
+  if (location && isRedirectStatus(error.status)) {
+    return Response.redirect(location, error.status);
+  }
+
+  return null;
+}
+
+function getLifecycleModules(modules: RouteModuleBundle): RouteModule[] {
+  return [
+    modules.route,
+    ...[...modules.layouts].reverse(),
+    modules.root,
+  ];
+}
+
+function toRouteErrorContextBase(options: {
+  requestContext: RequestContext;
+  routeId: string;
+  phase: RouteErrorPhase;
+  dev: boolean;
+}): Omit<RouteErrorContext, "error"> {
+  return {
+    request: options.requestContext.request,
+    url: options.requestContext.url,
+    params: options.requestContext.params,
+    routeId: options.routeId,
+    phase: options.phase,
+    dev: options.dev,
+  };
+}
+
+async function notifyErrorHooks(options: {
+  modules: RouteModuleBundle;
+  context: RouteErrorContext;
+}): Promise<void> {
+  const targets = getLifecycleModules(options.modules);
+  for (const moduleValue of targets) {
+    if (typeof moduleValue.onError !== "function") {
+      continue;
+    }
+
+    try {
+      await moduleValue.onError(options.context);
+    } catch (hookError) {
+      // eslint-disable-next-line no-console
+      console.warn("[rbssr] route onError hook failed", Bun.inspect(hookError));
+    }
+  }
+}
+
+async function notifyCatchHooks(options: {
+  modules: RouteModuleBundle;
+  context: RouteCatchContext;
+}): Promise<void> {
+  const targets = getLifecycleModules(options.modules);
+  for (const moduleValue of targets) {
+    if (typeof moduleValue.onCatch !== "function") {
+      continue;
+    }
+
+    try {
+      await moduleValue.onCatch(options.context);
+    } catch (hookError) {
+      // eslint-disable-next-line no-console
+      console.warn("[rbssr] route onCatch hook failed", Bun.inspect(hookError));
+    }
+  }
+}
+
+function toUncaughtErrorPayload(
+  error: unknown,
+  production: boolean,
+): { message: string } {
+  return {
+    message: sanitizeErrorMessage(error, production),
+  };
+}
+
+function toCaughtErrorPayload(
+  routeErrorResponse: RouteErrorResponse,
+  production: boolean,
+): RouteErrorResponse {
+  return sanitizeRouteErrorResponse(routeErrorResponse, production);
+}
+
+function toHtmlStreamResponse(stream: ReadableStream<Uint8Array>, status: number): Response {
+  return new Response(stream, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+    },
+  });
+}
+
+function applyFrameworkDefaultHeaders(options: {
+  headers: Headers;
+  dev: boolean;
+  kind: ResponseKind;
+  pathname: string;
+}): void {
+  const { headers, dev, kind, pathname } = options;
+
+  if (kind === "internal-dev" || kind === "internal-transition" || kind === "internal-action") {
+    if (!headers.has("cache-control")) {
+      headers.set("cache-control", "no-store");
+    }
+    return;
+  }
+
+  if (dev) {
+    if (kind === "static") {
+      headers.set("cache-control", "no-store");
+      headers.set("pragma", "no-cache");
+      headers.set("expires", "0");
+    }
+    return;
+  }
+
+  if (kind === "static" && !headers.has("cache-control")) {
+    headers.set(
+      "cache-control",
+      HASHED_CLIENT_CHUNK_RE.test(pathname) ? STATIC_IMMUTABLE_CACHE : STATIC_DEFAULT_CACHE,
+    );
+  }
+}
+
+function applyConfiguredHeaders(options: {
+  headers: Headers;
+  pathname: string;
+  config: ResolvedConfig;
+}): void {
+  const { headers, pathname, config } = options;
+  for (const rule of config.headerRules) {
+    if (!rule.matcher.test(pathname)) {
+      continue;
+    }
+
+    for (const [name, value] of Object.entries(rule.headers)) {
+      if (value === null) {
+        headers.delete(name);
+        continue;
+      }
+
+      headers.set(name, value);
+    }
+  }
+}
+
+function finalizeResponseHeaders(options: {
+  response: Response;
+  request: Request;
+  pathname: string;
+  kind: ResponseKind;
+  dev: boolean;
+  config: ResolvedConfig;
+}): Response {
+  const headers = new Headers(options.response.headers);
+
+  applyFrameworkDefaultHeaders({
+    headers,
+    dev: options.dev,
+    kind: options.kind,
+    pathname: options.pathname,
+  });
+
+  applyConfiguredHeaders({
+    headers,
+    pathname: options.pathname,
+    config: options.config,
+  });
+
+  return new Response(options.request.method.toUpperCase() === "HEAD" ? null : options.response.body, {
+    status: options.response.status,
+    statusText: options.response.statusText,
+    headers,
+  });
+}
+
+async function tryServeStatic(baseDir: string, pathname: string): Promise<Response | null> {
+  if (!pathname || pathname === "/") {
+    return null;
+  }
+
+  const decodedPath = decodeURIComponent(pathname);
+  const relativePath = decodedPath.replace(/^\/+/, "");
+
+  if (!relativePath) {
+    return null;
+  }
+
+  const resolved = ensureWithin(baseDir, relativePath);
+  if (!resolved) {
+    return null;
+  }
+
+  const stat = await statPath(resolved);
+  if (!stat?.isFile()) {
+    return null;
+  }
+
+  return new Response(Bun.file(resolved));
+}
+
+function getMethodHandler(moduleValue: Record<string, unknown>, method: string): unknown {
+  const upper = method.toUpperCase();
+  if (upper === "HEAD" && typeof moduleValue.HEAD !== "function" && typeof moduleValue.GET === "function") {
+    return moduleValue.GET;
+  }
+  return moduleValue[upper];
+}
+
+function getAllowedMethods(moduleValue: Record<string, unknown>): string[] {
+  return ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].filter(method => {
+    return typeof moduleValue[method] === "function";
+  });
+}
+
+async function parseActionBody(request: Request): Promise<Pick<ActionContext, "formData" | "json">> {
+  const contentType = request.headers.get("content-type") ?? "";
+
+  if (contentType.includes("application/json")) {
+    try {
+      return { json: await request.json() };
+    } catch {
+      return {};
+    }
+  }
+
+  if (
+    contentType.includes("multipart/form-data")
+    || contentType.includes("application/x-www-form-urlencoded")
+  ) {
+    try {
+      return { formData: await request.formData() };
+    } catch {
+      return {};
+    }
+  }
+
+  return {};
+}
+
+function createRequestContext(options: {
+  request: Request;
+  url: URL;
+  params: RequestContext["params"];
+}): RequestContext {
+  const cookies = parseCookieHeader(options.request.headers.get("cookie"));
+  return {
+    request: options.request,
+    url: options.url,
+    params: options.params,
+    cookies,
+    locals: {},
+    response: createResponseContext(cookies),
+  };
+}
+
+async function loadRootOnlyModule(
+  rootModulePath: string,
+  options: RouteModuleLoadOptions,
+): Promise<RouteModule> {
+  return loadRouteModule(rootModulePath, options);
+}
+
+function resolveAllRouteAssets(options: {
+  dev: boolean;
+  runtimeOptions: ServerRuntimeOptions;
+}): Record<string, BuildRouteAsset> {
+  if (options.dev) {
+    return options.runtimeOptions.getDevAssets?.() ?? options.runtimeOptions.devAssets ?? {};
+  }
+
+  return options.runtimeOptions.buildManifest?.routes ?? {};
+}
+
+export function toClientRouteSnapshots(routes: PageRouteDefinition[]): ClientRouteSnapshot[] {
+  return sortRoutesBySpecificity([...routes]).map(route => ({
+    id: route.id,
+    routePath: route.routePath,
+    segments: route.segments,
+    score: route.score,
+  }));
+}
+
+function createRouterSnapshot(options: {
+  manifest: RouteManifest;
+  routeAssets: Record<string, BuildRouteAsset>;
+  devVersion?: number;
+}): ClientRouterSnapshot {
+  return {
+    pages: toClientRouteSnapshots(options.manifest.pages),
+    assets: options.routeAssets,
+    devVersion: options.devVersion,
+  };
+}
+
+function resolveFallbackHtmlAssets(options: {
+  routeAssets: Record<string, BuildRouteAsset>;
+  devVersion?: number;
+}): HydrationDocumentAssets {
+  const css = Array.from(
+    new Set(
+      Object.values(options.routeAssets).flatMap(asset => asset.css),
+    ),
+  );
+
+  return {
+    script: undefined,
+    css,
+    devVersion: options.devVersion,
+  };
+}
+
+function toTransitionStreamResponse(
+  stream: ReadableStream<Uint8Array>,
+  baseHeaders?: HeadersInit,
+): Response {
+  const headers = new Headers(baseHeaders);
+  headers.set("content-type", "application/x-ndjson; charset=utf-8");
+  if (!headers.has("cache-control")) {
+    headers.set("cache-control", "no-store");
+  }
+
+  return new Response(stream, {
+    headers,
+  });
+}
+
+function toTransitionChunkLine(chunk: TransitionChunk): Uint8Array {
+  return new TextEncoder().encode(`${JSON.stringify(chunk)}\n`);
+}
+
+function isRedirectStatus(status: number): boolean {
+  return status >= 300 && status < 400;
+}
+
+function toRedirectChunk(location: string, status: number): TransitionRedirectChunk {
+  return {
+    type: "redirect",
+    location,
+    status,
+  };
+}
+
+function toDocumentChunk(location: string, status: number): TransitionDocumentChunk {
+  return {
+    type: "document",
+    location,
+    status,
+  };
+}
+
+function createTransitionStream(options: {
+  initialChunk?: TransitionInitialChunk;
+  controlChunk?: TransitionRedirectChunk | TransitionDocumentChunk;
+  deferredSettleEntries?: DeferredSettleEntry[];
+  sanitizeDeferredError: (message: string) => string;
+}): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        if (options.controlChunk) {
+          controller.enqueue(toTransitionChunkLine(options.controlChunk));
+          controller.close();
+          return;
+        }
+
+        if (options.initialChunk) {
+          controller.enqueue(toTransitionChunkLine(options.initialChunk));
+        }
+
+        const settleEntries = options.deferredSettleEntries ?? [];
+        if (settleEntries.length === 0) {
+          controller.close();
+          return;
+        }
+
+        await Promise.all(
+          settleEntries.map(async entry => {
+            const settled = await entry.settled;
+            const chunk: TransitionDeferredChunk = settled.ok
+              ? {
+                  type: "deferred",
+                  id: entry.id,
+                  ok: true,
+                  value: settled.value,
+                }
+              : {
+                  type: "deferred",
+                  id: entry.id,
+                  ok: false,
+                  error: options.sanitizeDeferredError(settled.error),
+                };
+            controller.enqueue(toTransitionChunkLine(chunk));
+          }),
+        );
+
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+  });
+}
+
+function toActionEnvelopeResponse(
+  envelope: ActionResponseEnvelope,
+  options: {
+    status?: number;
+    headers?: HeadersInit;
+  } = {},
+): Response {
+  const headers = new Headers(options.headers);
+  headers.set("content-type", "application/json; charset=utf-8");
+
+  return new Response(JSON.stringify(envelope), {
+    status: options.status ?? envelope.status,
+    headers,
+  });
+}
+
+async function readActionResponsePayload(response: Response): Promise<unknown> {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+
+  try {
+    return await response.text();
+  } catch {
+    return null;
+  }
+}
+
+function resolveResponseRedirect(response: Response): { location: string; status: number } | null {
+  const location = response.headers.get("location");
+  if (!location || !isRedirectStatus(response.status)) {
+    return null;
+  }
+
+  return {
+    location,
+    status: response.status,
+  };
+}
+
+function isActionResponseEnvelopePayload(value: unknown): value is ActionResponseEnvelope {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as {
+    type?: unknown;
+    status?: unknown;
+  };
+  return typeof candidate.type === "string" && typeof candidate.status === "number";
+}
+
+function createDefaultGetRouteAdapter(options: {
+  baseConfig: ResolvedConfig;
+  runtimeOptions: ServerRuntimeOptions;
+  dev: boolean;
+}): RequestExecutorDeps["getRouteAdapter"] {
+  const { baseConfig, runtimeOptions, dev } = options;
+  const adapterCache = new Map<string, BunRouteAdapter>();
+  const pendingAdapterCache = new Map<string, Promise<BunRouteAdapter>>();
+
+  const getAdapterKey = (activeConfig: ResolvedConfig): string => {
+    const routeVersion = dev
+      ? runtimeOptions.routeManifestVersion?.() ?? runtimeOptions.reloadVersion?.() ?? 0
+      : 0;
+    return `${normalizeSlashes(activeConfig.routesDir)}|${dev ? "dev" : "prod"}|${routeVersion}`;
+  };
+
+  const trimAdapterCache = (): void => {
+    if (!dev || adapterCache.size <= 3) {
+      return;
+    }
+
+    const keys = [...adapterCache.keys()];
+    while (keys.length > 3) {
+      const oldestKey = keys.shift();
+      if (!oldestKey) {
+        break;
+      }
+      adapterCache.delete(oldestKey);
+      pendingAdapterCache.delete(oldestKey);
+    }
+  };
+
+  return async (activeConfig: ResolvedConfig): Promise<BunRouteAdapter> => {
+    const cacheKey = getAdapterKey(activeConfig);
+    const cached = adapterCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const pending = pendingAdapterCache.get(cacheKey);
+    if (pending) {
+      return pending;
+    }
+
+    const routesHash = stableHash(normalizeSlashes(activeConfig.routesDir));
+    const projectionRootDir = dev
+      ? path.resolve(baseConfig.cwd, ".rbssr/generated/router-projection", `dev-${routesHash}`)
+      : path.resolve(baseConfig.cwd, ".rbssr/generated/router-projection", "prod", routesHash);
+
+    const buildAdapterPromise = createBunRouteAdapter({
+      routesDir: activeConfig.routesDir,
+      generatedMarkdownRootDir: path.resolve(baseConfig.cwd, ".rbssr/generated/markdown-routes"),
+      projectionRootDir,
+    });
+
+    pendingAdapterCache.set(cacheKey, buildAdapterPromise);
+
+    try {
+      const adapter = await buildAdapterPromise;
+      adapterCache.set(cacheKey, adapter);
+      trimAdapterCache();
+      return adapter;
+    } finally {
+      pendingAdapterCache.delete(cacheKey);
+    }
+  };
+}
+
+function createDefaultRequestExecutorDeps(options: {
+  baseConfig: ResolvedConfig;
+  runtimeOptions: ServerRuntimeOptions;
+  dev: boolean;
+}): RequestExecutorDeps {
+  return {
+    getRouteAdapter: createDefaultGetRouteAdapter(options),
+    loadRouteBundle: loadRouteModules,
+    loadApiModule: loadApiRouteModule,
+    loadGlobalMiddleware,
+    loadNestedMiddleware,
+    renderDocumentStream: defaultRenderDocumentStream,
+  };
+}
+
+export function createRequestExecutor(options: {
+  config: ResolvedConfig;
+  runtimeOptions: ServerRuntimeOptions;
+  deps?: Partial<RequestExecutorDeps>;
+}): RequestExecutor {
+  const resolvedConfig = options.config;
+  const runtimeOptions = options.runtimeOptions;
+  const dev = runtimeOptions.dev ?? resolvedConfig.mode !== "production";
+  const deps: RequestExecutorDeps = {
+    ...createDefaultRequestExecutorDeps({
+      baseConfig: resolvedConfig,
+      runtimeOptions,
+      dev,
+    }),
+    ...options.deps,
+  };
+
+  const fetchHandler = async (request: Request): Promise<Response> => {
+    const runtimePaths = runtimeOptions.resolvePaths?.() ?? {};
+    const activeConfig: ResolvedConfig = {
+      ...resolvedConfig,
+      ...runtimePaths,
+    };
+    const devClientDir = path.resolve(resolvedConfig.cwd, ".rbssr/dev/client");
+
+    const url = new URL(request.url);
+    const finalize = (
+      response: Response,
+      kind: ResponseKind,
+      requestContext?: RequestContext,
+    ): Response => {
+      const finalResponse = requestContext
+        ? applyResponseContext(response, requestContext.response)
+        : response;
+      return finalizeResponseHeaders({
+        response: finalResponse,
+        request,
+        pathname: url.pathname,
+        kind,
+        dev,
+        config: activeConfig,
+      });
+    };
+
+    if (dev && url.pathname === "/__rbssr/version") {
+      const version = runtimeOptions.reloadVersion?.() ?? 0;
+      return finalize(new Response(String(version), {
+        headers: {
+          "content-type": "text/plain; charset=utf-8",
+          "cache-control": "no-store",
+        },
+      }), "internal-dev");
+    }
+
+    if (dev && url.pathname.startsWith("/__rbssr/client/")) {
+      const relative = url.pathname.replace(/^\/__rbssr\/client\//, "");
+      const response = await tryServeStatic(devClientDir, relative);
+      if (response) {
+        return finalize(response, "static");
+      }
+    }
+
+    if (!dev && url.pathname.startsWith("/client/")) {
+      const relative = url.pathname.replace(/^\/client\//, "");
+      const response = await tryServeStatic(path.join(activeConfig.distDir, "client"), relative);
+      if (response) {
+        return finalize(response, "static");
+      }
+    }
+
+    if (!dev) {
+      const builtPublicResponse = await tryServeStatic(path.join(activeConfig.distDir, "client"), url.pathname);
+      if (builtPublicResponse) {
+        return finalize(builtPublicResponse, "static");
+      }
+    }
+
+    const publicResponse = await tryServeStatic(activeConfig.publicDir, url.pathname);
+    if (publicResponse) {
+      return finalize(publicResponse, "static");
+    }
+
+    await runtimeOptions.onBeforeRequest?.();
+
+    const routeAdapter = await deps.getRouteAdapter(activeConfig);
+    const devCacheBustKey = dev ? String(runtimeOptions.reloadVersion?.() ?? 0) : undefined;
+    const nodeEnv: "development" | "production" = dev ? "development" : "production";
+    const routeModuleLoadOptions: RouteModuleLoadOptions = {
+      cacheBustKey: devCacheBustKey,
+      serverBytecode: activeConfig.serverBytecode,
+      devSourceImports: false,
+      nodeEnv,
+    };
+    const requestModuleLoadOptions: RouteModuleLoadOptions = {
+      cacheBustKey: devCacheBustKey,
+      serverBytecode: activeConfig.serverBytecode,
+      devSourceImports: dev,
+      nodeEnv,
+    };
+    const routeAssetsById = resolveAllRouteAssets({
+      dev,
+      runtimeOptions,
+    });
+    const routerSnapshot = createRouterSnapshot({
+      manifest: routeAdapter.manifest,
+      routeAssets: routeAssetsById,
+      devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+    });
+    const fallbackHtmlAssets = resolveFallbackHtmlAssets({
+      routeAssets: routeAssetsById,
+      devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+    });
+
+    if (request.method.toUpperCase() === "POST" && url.pathname === "/__rbssr/action") {
+      const toParam = url.searchParams.get("to");
+      if (!toParam) {
+        return finalize(
+          toActionEnvelopeResponse({
+            type: "error",
+            status: 400,
+            message: "Missing required `to` query parameter.",
+          }, { status: 400 }),
+          "internal-action",
+        );
+      }
+
+      let targetUrl: URL;
+      try {
+        targetUrl = new URL(toParam, url);
+      } catch {
+        return finalize(
+          toActionEnvelopeResponse({
+            type: "error",
+            status: 400,
+            message: "Invalid `to` URL.",
+          }, { status: 400 }),
+          "internal-action",
+        );
+      }
+
+      if (targetUrl.origin !== url.origin) {
+        return finalize(
+          toActionEnvelopeResponse({
+            type: "error",
+            status: 400,
+            message: "Cross-origin action targets are not allowed.",
+          }, { status: 400 }),
+          "internal-action",
+        );
+      }
+
+      const actionPageMatch = routeAdapter.matchPage(targetUrl.pathname);
+      if (!actionPageMatch) {
+        return finalize(
+          toActionEnvelopeResponse({
+            type: "error",
+            status: 404,
+            message: "No page route matched the action target.",
+          }, { status: 404 }),
+          "internal-action",
+        );
+      }
+
+      const [routeModules, globalMiddleware, nestedMiddleware, actionBody] = await Promise.all([
+        deps.loadRouteBundle({
+          rootFilePath: activeConfig.rootModule,
+          layoutFiles: actionPageMatch.route.layoutFiles,
+          routeFilePath: actionPageMatch.route.filePath,
+          routeServerFilePath: actionPageMatch.route.serverFilePath,
+          ...routeModuleLoadOptions,
+        }),
+        deps.loadGlobalMiddleware(activeConfig.middlewareFile, requestModuleLoadOptions),
+        deps.loadNestedMiddleware(actionPageMatch.route.middlewareFiles, requestModuleLoadOptions),
+        parseActionBody(request.clone()),
+      ]);
+
+      const moduleMiddleware = extractRouteMiddleware(routeModules.route);
+      const actionRequest = new Request(targetUrl.toString(), {
+        method: request.method,
+        headers: request.headers,
+      });
+      const requestContext = createRequestContext({
+        request: actionRequest,
+        url: targetUrl,
+        params: actionPageMatch.params,
+      });
+      const contextBase = toRouteErrorContextBase({
+        requestContext,
+        routeId: actionPageMatch.route.id,
+        phase: "action",
+        dev,
+      });
+
+      try {
+        const middlewareResponse = await runMiddlewareChain(
+          [...globalMiddleware, ...nestedMiddleware, ...moduleMiddleware],
+          requestContext,
+          async () => {
+            if (!routeModules.route.action) {
+              return toActionEnvelopeResponse({
+                type: "error",
+                status: 405,
+                message:
+                  "Method Not Allowed: route has no server action export. "
+                  + "Define a server action (for example in a *.server.tsx companion) "
+                  + "and call it from useActionState(action, initialState) with createRouteAction().",
+              }, { status: 405 });
+            }
+
+            const actionCtx: ActionContext = {
+              ...requestContext,
+              ...actionBody,
+            };
+            const actionResult = await routeModules.route.action(actionCtx);
+
+            if (isDeferredLoaderResult(actionResult)) {
+              return toActionEnvelopeResponse({
+                type: "error",
+                status: 500,
+                message: "defer() is only supported in route loaders.",
+              }, { status: 500 });
+            }
+
+            if (isRedirectResult(actionResult)) {
+              return toActionEnvelopeResponse({
+                type: "redirect",
+                status: actionResult.status ?? 302,
+                location: actionResult.location,
+              }, { status: 200 });
+            }
+
+            if (isResponse(actionResult)) {
+              const responseRedirect = resolveResponseRedirect(actionResult);
+              if (responseRedirect) {
+                return toActionEnvelopeResponse({
+                  type: "redirect",
+                  status: responseRedirect.status,
+                  location: responseRedirect.location,
+                }, {
+                  headers: actionResult.headers,
+                  status: 200,
+                });
+              }
+
+              const data = await readActionResponsePayload(actionResult.clone());
+              return toActionEnvelopeResponse({
+                type: "data",
+                status: actionResult.status,
+                data,
+              }, {
+                headers: actionResult.headers,
+                status: 200,
+              });
+            }
+
+            return toActionEnvelopeResponse({
+              type: "data",
+              status: 200,
+              data: actionResult,
+            }, { status: 200 });
+          },
+        );
+        const middlewareRedirect = resolveResponseRedirect(middlewareResponse);
+        if (middlewareRedirect) {
+          return finalize(
+            toActionEnvelopeResponse({
+              type: "redirect",
+              status: middlewareRedirect.status,
+              location: middlewareRedirect.location,
+            }, {
+              headers: middlewareResponse.headers,
+              status: 200,
+            }),
+            "internal-action",
+            requestContext,
+          );
+        }
+
+        const parsedPayload = await readActionResponsePayload(middlewareResponse.clone());
+        if (isActionResponseEnvelopePayload(parsedPayload)) {
+          return finalize(middlewareResponse, "internal-action", requestContext);
+        }
+
+        if (middlewareResponse.status >= 400) {
+          const message = typeof parsedPayload === "string"
+            ? parsedPayload
+            : sanitizeErrorMessage(parsedPayload, !dev);
+          return finalize(
+            toActionEnvelopeResponse({
+              type: "error",
+              status: middlewareResponse.status,
+              message,
+            }, {
+              headers: middlewareResponse.headers,
+              status: 200,
+            }),
+            "internal-action",
+            requestContext,
+          );
+        }
+
+        return finalize(
+          toActionEnvelopeResponse({
+            type: "data",
+            status: middlewareResponse.status,
+            data: parsedPayload,
+          }, {
+            headers: middlewareResponse.headers,
+            status: 200,
+          }),
+          "internal-action",
+          requestContext,
+        );
+      } catch (error) {
+        const redirectResponse = resolveThrownRedirect(error);
+        if (redirectResponse) {
+          const location = redirectResponse.headers.get("location");
+          if (location) {
+            return finalize(
+              toActionEnvelopeResponse({
+                type: "redirect",
+                status: redirectResponse.status,
+                location,
+              }, {
+                headers: redirectResponse.headers,
+                status: 200,
+              }),
+              "internal-action",
+              requestContext,
+            );
+          }
+        }
+
+        const caught = toRouteErrorResponse(error);
+        if (caught) {
+          await notifyCatchHooks({
+            modules: routeModules,
+            context: {
+              ...contextBase,
+              error: caught,
+            },
+          });
+
+          return finalize(
+            toActionEnvelopeResponse({
+              type: "catch",
+              status: caught.status,
+              error: toCaughtErrorPayload(caught, !dev),
+            }, { status: 200 }),
+            "internal-action",
+            requestContext,
+          );
+        }
+
+        await notifyErrorHooks({
+          modules: routeModules,
+          context: {
+            ...contextBase,
+            error,
+          },
+        });
+
+        return finalize(
+          toActionEnvelopeResponse({
+            type: "error",
+            status: 500,
+            message: sanitizeErrorMessage(error, !dev),
+          }, { status: 200 }),
+          "internal-action",
+          requestContext,
+        );
+      }
+    }
+
+    if (request.method.toUpperCase() === "GET" && url.pathname === "/__rbssr/transition") {
+      const toParam = url.searchParams.get("to");
+      if (!toParam) {
+        return finalize(
+          new Response("Missing required `to` query parameter.", { status: 400 }),
+          "internal-transition",
+        );
+      }
+
+      let targetUrl: URL;
+      try {
+        targetUrl = new URL(toParam, url);
+      } catch {
+        return finalize(new Response("Invalid `to` URL.", { status: 400 }), "internal-transition");
+      }
+
+      if (targetUrl.origin !== url.origin) {
+        return finalize(
+          new Response("Cross-origin transitions are not allowed.", { status: 400 }),
+          "internal-transition",
+        );
+      }
+
+      const transitionPageMatch = routeAdapter.matchPage(targetUrl.pathname);
+      if (!transitionPageMatch) {
+        const rootModule = await loadRootOnlyModule(activeConfig.rootModule, {
+          ...routeModuleLoadOptions,
+        });
+        const fallbackRoute: RouteModule = {
+          default: () => null,
+          NotFound: rootModule.NotFound,
+        };
+        const payload = {
+          routeId: "__not_found__",
+          loaderData: null,
+          params: {},
+          url: targetUrl.toString(),
+        };
+        const modules = {
+          root: rootModule,
+          layouts: [],
+          route: fallbackRoute,
+        };
+        const initialChunk: TransitionInitialChunk = {
+          type: "initial",
+          kind: "not_found",
+          status: 404,
+          payload,
+          head: createManagedHeadMarkup({
+            headMarkup: collectHeadMarkup(modules, payload),
+            assets: fallbackHtmlAssets,
+          }),
+          redirected: false,
+        };
+        const stream = createTransitionStream({
+          initialChunk,
+          sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+        });
+        return finalize(toTransitionStreamResponse(stream), "internal-transition");
+      }
+
+      const [routeModules, globalMiddleware, nestedMiddleware] = await Promise.all([
+        deps.loadRouteBundle({
+          rootFilePath: activeConfig.rootModule,
+          layoutFiles: transitionPageMatch.route.layoutFiles,
+          routeFilePath: transitionPageMatch.route.filePath,
+          routeServerFilePath: transitionPageMatch.route.serverFilePath,
+          ...routeModuleLoadOptions,
+        }),
+        deps.loadGlobalMiddleware(activeConfig.middlewareFile, requestModuleLoadOptions),
+        deps.loadNestedMiddleware(transitionPageMatch.route.middlewareFiles, requestModuleLoadOptions),
+      ]);
+      const moduleMiddleware = extractRouteMiddleware(routeModules.route);
+      const routeAssets = routeAssetsById[transitionPageMatch.route.id] ?? null;
+      const transitionRequest = new Request(targetUrl.toString(), {
+        method: "GET",
+        headers: request.headers,
+      });
+
+      const requestContext = createRequestContext({
+        request: transitionRequest,
+        url: targetUrl,
+        params: transitionPageMatch.params,
+      });
+
+      let transitionInitialChunk: TransitionInitialChunk | undefined;
+      let deferredSettleEntries: DeferredSettleEntry[] = [];
+      let transitionPhase: RouteErrorPhase = "middleware";
+
+      let middlewareResponse: Response;
+      try {
+        middlewareResponse = await runMiddlewareChain(
+          [...globalMiddleware, ...nestedMiddleware, ...moduleMiddleware],
+          requestContext,
+          async () => {
+            let loaderDataForRender: unknown = null;
+            let loaderDataForPayload: unknown = null;
+
+            if (routeModules.route.loader) {
+              transitionPhase = "loader";
+              const loaderCtx: LoaderContext = requestContext;
+              const loaderResult = await routeModules.route.loader(loaderCtx);
+
+              if (isResponse(loaderResult)) {
+                return loaderResult;
+              }
+
+              if (isRedirectResult(loaderResult)) {
+                return toRedirectResponse(loaderResult.location, loaderResult.status);
+              }
+
+              if (isDeferredLoaderResult(loaderResult)) {
+                const prepared = prepareDeferredPayload(transitionPageMatch.route.id, loaderResult);
+                loaderDataForRender = prepared.dataForRender;
+                loaderDataForPayload = prepared.dataForPayload;
+                deferredSettleEntries = prepared.settleEntries;
+              } else {
+                loaderDataForRender = loaderResult;
+                loaderDataForPayload = loaderResult;
+              }
+            }
+
+            const renderPayload = {
+              routeId: transitionPageMatch.route.id,
+              loaderData: loaderDataForRender,
+              params: transitionPageMatch.params,
+              url: targetUrl.toString(),
+            };
+            const payload = {
+              ...renderPayload,
+              loaderData: loaderDataForPayload,
+            };
+            transitionInitialChunk = {
+              type: "initial",
+              kind: "page",
+              status: 200,
+              payload,
+              head: createManagedHeadMarkup({
+                headMarkup: collectHeadMarkup(routeModules, renderPayload),
+                assets: {
+                  script: routeAssets?.script,
+                  css: routeAssets?.css ?? [],
+                  devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+                },
+              }),
+              redirected: false,
+            };
+
+            return new Response(null, { status: 204 });
+          },
+        );
+      } catch (error) {
+        const redirectResponse = resolveThrownRedirect(error);
+        if (redirectResponse) {
+          const location = redirectResponse.headers.get("location");
+          if (location) {
+            const stream = createTransitionStream({
+              controlChunk: toRedirectChunk(location, redirectResponse.status),
+              sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+            });
+            return finalize(
+              toTransitionStreamResponse(stream, redirectResponse.headers),
+              "internal-transition",
+              requestContext,
+            );
+          }
+        }
+
+        const contextBase = toRouteErrorContextBase({
+          requestContext,
+          routeId: transitionPageMatch.route.id,
+          phase: transitionPhase,
+          dev,
+        });
+        const caught = toRouteErrorResponse(error);
+        if (caught) {
+          const payload = {
+            routeId: transitionPageMatch.route.id,
+            loaderData: null,
+            params: transitionPageMatch.params,
+            url: targetUrl.toString(),
+            error: toCaughtErrorPayload(caught, !dev),
+          };
+          await notifyCatchHooks({
+            modules: routeModules,
+            context: {
+              ...contextBase,
+              error: caught,
+            },
+          });
+          const initialChunk: TransitionInitialChunk = {
+            type: "initial",
+            kind: "catch",
+            status: caught.status,
+            payload,
+            head: createManagedHeadMarkup({
+              headMarkup: collectHeadMarkup(routeModules, payload),
+              assets: {
+                script: routeAssets?.script,
+                css: routeAssets?.css ?? [],
+                devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+              },
+            }),
+            redirected: false,
+          };
+          const stream = createTransitionStream({
+            initialChunk,
+            sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+          });
+          return finalize(toTransitionStreamResponse(stream), "internal-transition", requestContext);
+        }
+
+        await notifyErrorHooks({
+          modules: routeModules,
+          context: {
+            ...contextBase,
+            error,
+          },
+        });
+        const renderPayload = {
+          routeId: transitionPageMatch.route.id,
+          loaderData: null,
+          params: transitionPageMatch.params,
+          url: targetUrl.toString(),
+          error: toUncaughtErrorPayload(error, !dev),
+        };
+        const initialChunk: TransitionInitialChunk = {
+          type: "initial",
+          kind: "error",
+          status: 500,
+          payload: renderPayload,
+          head: createManagedHeadMarkup({
+            headMarkup: collectHeadMarkup(routeModules, renderPayload),
+            assets: {
+              script: routeAssets?.script,
+              css: routeAssets?.css ?? [],
+              devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+            },
+          }),
+          redirected: false,
+        };
+        const stream = createTransitionStream({
+          initialChunk,
+          sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+        });
+        return finalize(toTransitionStreamResponse(stream), "internal-transition", requestContext);
+      }
+
+      const redirectLocation = middlewareResponse.headers.get("location");
+      if (redirectLocation && isRedirectStatus(middlewareResponse.status)) {
+        const stream = createTransitionStream({
+          controlChunk: toRedirectChunk(redirectLocation, middlewareResponse.status),
+          sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+        });
+        return finalize(
+          toTransitionStreamResponse(stream, middlewareResponse.headers),
+          "internal-transition",
+          requestContext,
+        );
+      }
+
+      if (!transitionInitialChunk) {
+        const stream = createTransitionStream({
+          controlChunk: toDocumentChunk(targetUrl.toString(), middlewareResponse.status),
+          sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+        });
+        return finalize(
+          toTransitionStreamResponse(stream, middlewareResponse.headers),
+          "internal-transition",
+          requestContext,
+        );
+      }
+
+      const stream = createTransitionStream({
+        initialChunk: transitionInitialChunk,
+        deferredSettleEntries,
+        sanitizeDeferredError: message => sanitizeErrorMessage(message, !dev),
+      });
+      return finalize(toTransitionStreamResponse(stream, middlewareResponse.headers), "internal-transition", requestContext);
+    }
+
+    const apiMatch = routeAdapter.matchApi(url.pathname);
+    if (apiMatch) {
+      const apiModule = await deps.loadApiModule(apiMatch.route.filePath, requestModuleLoadOptions);
+      const methodHandler = getMethodHandler(apiModule as Record<string, unknown>, request.method);
+
+      if (typeof methodHandler !== "function") {
+        const allow = getAllowedMethods(apiModule as Record<string, unknown>);
+        return finalize(new Response("Method Not Allowed", {
+          status: 405,
+          headers: {
+            allow: allow.join(", "),
+          },
+        }), "api");
+      }
+
+      const requestContext = createRequestContext({
+        request,
+        url,
+        params: apiMatch.params,
+      });
+
+      const [globalMiddleware, routeMiddleware] = await Promise.all([
+        deps.loadGlobalMiddleware(activeConfig.middlewareFile, requestModuleLoadOptions),
+        deps.loadNestedMiddleware(apiMatch.route.middlewareFiles, requestModuleLoadOptions),
+      ]);
+      const allMiddleware = [...globalMiddleware, ...routeMiddleware];
+      let apiPhase: RouteErrorPhase = "middleware";
+
+      let response: Response;
+      try {
+        response = await runMiddlewareChain(allMiddleware, requestContext, async () => {
+          apiPhase = "api";
+          const result = await (methodHandler as (ctx: RequestContext) => unknown)(requestContext);
+
+          if (isResponse(result)) {
+            return result;
+          }
+
+          if (isRedirectResult(result)) {
+            return toRedirectResponse(result.location, result.status);
+          }
+
+          return json(result);
+        });
+      } catch (error) {
+        const redirectResponse = resolveThrownRedirect(error);
+        if (redirectResponse) {
+          return finalize(redirectResponse, "api", requestContext);
+        }
+
+        const caught = toRouteErrorResponse(error);
+        if (caught) {
+          return finalize(toRouteErrorHttpResponse(toCaughtErrorPayload(caught, !dev)), "api", requestContext);
+        }
+
+        const apiErrorHook = (apiModule as Record<string, unknown>).onError;
+        if (typeof apiErrorHook === "function") {
+          try {
+            await (apiErrorHook as (ctx: RouteErrorContext) => void | Promise<void>)({
+              error,
+              request: requestContext.request,
+              url: requestContext.url,
+              params: requestContext.params,
+              routeId: apiMatch.route.id,
+              phase: apiPhase,
+              dev,
+            });
+          } catch (hookError) {
+            // eslint-disable-next-line no-console
+            console.warn("[rbssr] api onError hook failed", Bun.inspect(hookError));
+          }
+        }
+
+        return finalize(json(
+          {
+            error: sanitizeErrorMessage(error, !dev),
+          },
+          { status: 500 },
+        ), "api", requestContext);
+      }
+      return finalize(response, "api", requestContext);
+    }
+
+    const pageMatch = routeAdapter.matchPage(url.pathname);
+
+    if (!pageMatch) {
+      const rootModule = await loadRootOnlyModule(activeConfig.rootModule, {
+        ...routeModuleLoadOptions,
+      });
+      const fallbackRoute: RouteModule = {
+        default: () => null,
+        NotFound: rootModule.NotFound,
+      };
+
+      const payload = {
+        routeId: "__not_found__",
+        loaderData: null,
+        params: {},
+        url: url.toString(),
+      };
+
+      const modules = {
+        root: rootModule,
+        layouts: [],
+        route: fallbackRoute,
+      };
+
+      const appTree = createNotFoundAppTree(modules, payload) ?? createElement(
+        "main",
+        null,
+        createElement("h1", null, "404"),
+        createElement("p", null, "Page not found."),
+      );
+      const stream = await deps.renderDocumentStream({
+        appTree,
+        payload,
+        assets: fallbackHtmlAssets,
+        headElements: collectHeadElements(modules, payload),
+        routerSnapshot,
+      });
+
+      return finalize(toHtmlStreamResponse(stream, 404), "html");
+    }
+
+    if (isMutatingMethod(request.method)) {
+      return finalize(
+        new Response(
+          "Page route mutations are not supported via document requests. "
+            + "Use useActionState(action, initialState) with createRouteAction() "
+            + "(or useRouteAction for backwards compatibility).",
+          {
+            status: 405,
+            headers: {
+              allow: "GET, HEAD",
+            },
+          },
+        ),
+        "html",
+      );
+    }
+
+    const [routeModules, globalMiddleware, nestedMiddleware] = await Promise.all([
+      deps.loadRouteBundle({
+        rootFilePath: activeConfig.rootModule,
+        layoutFiles: pageMatch.route.layoutFiles,
+        routeFilePath: pageMatch.route.filePath,
+        routeServerFilePath: pageMatch.route.serverFilePath,
+        ...routeModuleLoadOptions,
+      }),
+      deps.loadGlobalMiddleware(activeConfig.middlewareFile, requestModuleLoadOptions),
+      deps.loadNestedMiddleware(pageMatch.route.middlewareFiles, requestModuleLoadOptions),
+    ]);
+    const moduleMiddleware = extractRouteMiddleware(routeModules.route);
+
+    const requestContext = createRequestContext({
+      request,
+      url,
+      params: pageMatch.params,
+    });
+
+    const routeAssets = routeAssetsById[pageMatch.route.id] ?? null;
+    let pagePhase: RouteErrorPhase = "middleware";
+
+    const renderFailureDocument = async (
+      failure: unknown,
+      phase: RouteErrorPhase,
+    ): Promise<Response> => {
+      const contextBase = toRouteErrorContextBase({
+        requestContext,
+        routeId: pageMatch.route.id,
+        phase,
+        dev,
+      });
+      const caught = toRouteErrorResponse(failure);
+      if (caught) {
+        const serializedCatch = toCaughtErrorPayload(caught, !dev);
+        await notifyCatchHooks({
+          modules: routeModules,
+          context: {
+            ...contextBase,
+            error: caught,
+          },
+        });
+
+        const basePayload = {
+          routeId: pageMatch.route.id,
+          loaderData: null,
+          params: pageMatch.params,
+          url: url.toString(),
+        };
+        const catchPayload = {
+          ...basePayload,
+          error: serializedCatch,
+        };
+
+        if (serializedCatch.status === 404) {
+          const notFoundTree = createNotFoundAppTree(routeModules, catchPayload);
+          if (notFoundTree) {
+            const stream = await deps.renderDocumentStream({
+              appTree: notFoundTree,
+              payload: catchPayload,
+              assets: {
+                script: routeAssets?.script,
+                css: routeAssets?.css ?? [],
+                devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+              },
+              headElements: collectHeadElements(routeModules, catchPayload),
+              routerSnapshot,
+            });
+            return toHtmlStreamResponse(stream, 404);
+          }
+        }
+
+        const catchTree = createCatchAppTree(routeModules, catchPayload, serializedCatch);
+        if (catchTree) {
+          const stream = await deps.renderDocumentStream({
+            appTree: catchTree,
+            payload: catchPayload,
+            assets: {
+              script: routeAssets?.script,
+              css: routeAssets?.css ?? [],
+              devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+            },
+            headElements: collectHeadElements(routeModules, catchPayload),
+            routerSnapshot,
+          });
+          return toHtmlStreamResponse(stream, serializedCatch.status);
+        }
+
+        return toRouteErrorHttpResponse(serializedCatch);
+      }
+
+      await notifyErrorHooks({
+        modules: routeModules,
+        context: {
+          ...contextBase,
+          error: failure,
+        },
+      });
+
+      const renderPayload = {
+        routeId: pageMatch.route.id,
+        loaderData: null,
+        params: pageMatch.params,
+        url: url.toString(),
+      };
+      const errorPayload = {
+        ...renderPayload,
+        error: toUncaughtErrorPayload(failure, !dev),
+      };
+      const boundaryTree = createErrorAppTree(routeModules, errorPayload, failure);
+      if (boundaryTree) {
+        const stream = await deps.renderDocumentStream({
+          appTree: boundaryTree,
+          payload: errorPayload,
+          assets: {
+            script: routeAssets?.script,
+            css: routeAssets?.css ?? [],
+            devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+          },
+          headElements: collectHeadElements(routeModules, errorPayload),
+          routerSnapshot,
+        });
+        return toHtmlStreamResponse(stream, 500);
+      }
+
+      return new Response(sanitizeErrorMessage(failure, !dev), { status: 500 });
+    };
+
+    let response: Response;
+    try {
+      response = await runMiddlewareChain(
+        [...globalMiddleware, ...nestedMiddleware, ...moduleMiddleware],
+        requestContext,
+        async () => {
+          let loaderDataForRender: unknown = null;
+          let loaderDataForPayload: unknown = null;
+          let deferredSettleEntries: DeferredSettleEntry[] = [];
+
+          const resolveLoaderData = async (): Promise<Response | null> => {
+            if (!routeModules.route.loader) {
+              return null;
+            }
+
+            pagePhase = "loader";
+            const loaderCtx: LoaderContext = requestContext;
+            const loaderResult = await routeModules.route.loader(loaderCtx);
+
+            if (isResponse(loaderResult)) {
+              return loaderResult;
+            }
+
+            if (isRedirectResult(loaderResult)) {
+              return toRedirectResponse(loaderResult.location, loaderResult.status);
+            }
+
+            if (isDeferredLoaderResult(loaderResult)) {
+              const prepared = prepareDeferredPayload(pageMatch.route.id, loaderResult);
+              loaderDataForRender = prepared.dataForRender;
+              loaderDataForPayload = prepared.dataForPayload;
+              deferredSettleEntries = prepared.settleEntries;
+            } else {
+              loaderDataForRender = loaderResult;
+              loaderDataForPayload = loaderResult;
+            }
+
+            return null;
+          };
+
+          const loaderResponse = await resolveLoaderData();
+          if (loaderResponse) {
+            return loaderResponse;
+          }
+
+          const renderPayload = {
+            routeId: pageMatch.route.id,
+            loaderData: loaderDataForRender,
+            params: pageMatch.params,
+            url: url.toString(),
+          };
+
+          const clientPayload = {
+            ...renderPayload,
+            loaderData: loaderDataForPayload,
+          };
+
+          let appTree: ReturnType<typeof createPageAppTree>;
+          try {
+            pagePhase = "render";
+            appTree = createPageAppTree(routeModules, renderPayload);
+          } catch (error) {
+            return renderFailureDocument(error, pagePhase);
+          }
+
+          const stream = await deps.renderDocumentStream({
+            appTree,
+            payload: clientPayload,
+            assets: {
+              script: routeAssets?.script,
+              css: routeAssets?.css ?? [],
+              devVersion: dev ? runtimeOptions.reloadVersion?.() ?? 0 : undefined,
+            },
+            headElements: collectHeadElements(routeModules, renderPayload),
+            routerSnapshot,
+            deferredSettleEntries,
+          });
+
+          return toHtmlStreamResponse(stream, 200);
+        },
+      );
+    } catch (error) {
+      const redirectResponse = resolveThrownRedirect(error);
+      if (redirectResponse) {
+        return finalize(redirectResponse, "html", requestContext);
+      }
+
+      const fallbackResponse = await renderFailureDocument(error, pagePhase);
+      return finalize(fallbackResponse, "html", requestContext);
+    }
+
+    return finalize(response, "html", requestContext);
+  };
+
+  return {
+    fetch: fetchHandler,
+  };
+}