akanjs 3.0.0-beta.9 → 3.0.1

package/server/rscWorker.tsx

@@ -9,6 +9,7 @@ import type {
 } from "akanjs/client";
 import { type AkanI18nConfig, DEFAULT_AKAN_I18N, getBasePathFromPathname, Logger } from "akanjs/common";
 import {
+  type AkanTheme,
   getRequestDynamicUsage,
   getRequestFrameState,
   getRequestPolicy,
@@ -16,6 +17,7 @@ import {
   pushRequestFallback,
   requestStorage,
   setRequestFrameState,
+  setRequestTheme,
   untrackedCookies,
   untrackedRequest,
   updateRequestPolicy,
@@ -30,19 +32,13 @@ import {
   type LruTtlCacheOptions,
   parsePositiveInt,
   type RouteCacheEntry,
-  type RouteCacheInvalidation,
   type RouteCacheRenderState,
   resolvePublicRouteCacheEntryDecision,
   resolveRouteCacheStoreTtl,
   shouldStoreRouteCache,
 } from "./cachePolicy";
+import { createAkanLocaleAlternateHeadSnapshot, mergeAkanHeadSnapshots, renderAkanHeadSnapshot } from "./head";
 import { LogForwarder } from "./logging/logForwarder";
-import {
-  createAkanLocaleAlternateHeadSnapshot,
-  mergeAkanHeadSnapshots,
-  renderAkanHeadSnapshot,
-  shouldRenderLocaleAlternates,
-} from "./metadata";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { RouteElementComposer } from "./routeElementComposer";
 import {
@@ -51,6 +47,7 @@ import {
   encodeAkanHeadSnapshot,
   encodeAkanRouterState,
   encodeAkanRscPatchSegmentPath,
+  isAkanRscPartialCommitEnabled,
   readAkanRouterStateRequest,
   resolveAkanRscPartialDecision,
   resolveAkanRscPatchDecision,
@@ -58,22 +55,21 @@ import {
 import { type PagesContext, RouteTreeBuilder } from "./routeTreeBuilder";
 import { encodeAkanRedirectDigest } from "./rscHttp";
 import { RscPagePrompts } from "./rscPagePrompts";
-import { isAkanRscPartialCommitEnabled } from "./rscPartialCommit";
-import { resolveAkanRscHeadSafePatchDecision } from "./rscPatchSafety";
 import {
   type CachedRscResult,
   createCachedRscPatchMetadata,
   createRscWorkerCachedPatchReplayDecision,
   invalidateCachedRscResults,
   isCachedRscPatchMetadataCompatible,
+  replayCachedRscResult,
+  resolveAkanRscHeadSafePatchDecision,
   resolveRscWorkerPatchCacheEntry,
   shouldCollectRscWorkerRenderChunks,
   shouldStoreRscWorkerPatchResult,
   shouldUseRscWorkerFullResultCache,
 } from "./rscWorkerCache";
-import { replayCachedRscResult } from "./rscWorkerReplay";
 import type { RscTraceMetadata } from "./ssrTypes";
-import { createSystemPageDocument, getSystemPageHomeHref } from "./systemPageDocument";
+import { createSystemPageDocument, getPathnameLocale, getSystemPageHomeHref } from "./systemPageDocument";
 
 interface InitMsg {
   type: "init";
@@ -101,8 +97,8 @@ interface ReloadMsg {
   clientManifest: ClientManifest;
   cssAssets?: Record<string, { cssUrl: string; cssRelPath: string }>;
   buildId: number;
-  /** Optional new bundle path — when the builder rebundled user code. */
   pagesBundlePath?: string;
+  reloadId?: number;
 }
 interface UpdateCssAssetsMsg {
   type: "updateCssAssets";
@@ -229,7 +225,7 @@ export class RscRenderer {
     pagesBundleBuildId: 0,
   };
   readonly #routeStats = new Map<string, RouteRenderStats>();
-
+  
   #resultCache = new LruTtlCache<CachedRscResult>(
     parsePositiveInt(process.env.AKAN_RSC_RESULT_CACHE_MAX_ENTRIES) ?? 100,
     RscRenderer.#resultCacheOptions(),
@@ -259,7 +255,7 @@ export class RscRenderer {
     if (Logger.isNdjson) Logger.consoleOutput = false;
     this.#logForwarder = new LogForwarder((message) => this.#send(message));
     process.on("message", (msg: InMsg) => this.#handleMessage(msg));
-
+    
     process.on("disconnect", () => {
       this.#logger.warn("parent IPC channel closed; exiting rsc worker");
       process.exit(0);
@@ -269,7 +265,8 @@ export class RscRenderer {
 
   start(): void {
     this.#logger.verbose("sending hello to host");
-    this.#startMetricsReporting();
+    if (!this.#metricsTimer)
+      this.#metricsTimer = ProcessMetricsCollector.startReporting(() => this.#sendMetricsReport());
     this.#send({ type: "hello" });
   }
 
@@ -297,7 +294,8 @@ export class RscRenderer {
         return;
       case "invalidate-cache":
         this.#logger.verbose(`received invalidate-cache reason=${msg.reason ?? "(none)"}`);
-        this.#invalidateResultCache(msg);
+        invalidateCachedRscResults(this.#resultCache, msg);
+        invalidateCachedRscResults(this.#patchResultCache, msg);
         return;
       case "log-level":
         this.#logForwarder.setMinSev(msg.minSev);
@@ -311,7 +309,6 @@ export class RscRenderer {
     }
   }
 
-  /** A request whose answer is one JSON value: it rides a single reply rather than the render stream. */
   async #answer(requestId: string, type: string, fn: () => Promise<unknown>): Promise<void> {
     try {
       this.#send({ type, requestId, result: await fn() });
@@ -328,11 +325,6 @@ export class RscRenderer {
     });
   }
 
-  #invalidateResultCache(invalidation: RouteCacheInvalidation): void {
-    invalidateCachedRscResults(this.#resultCache, invalidation);
-    invalidateCachedRscResults(this.#patchResultCache, invalidation);
-  }
-
   async #handleInit(msg: InitMsg): Promise<void> {
     const startedAt = Date.now();
     try {
@@ -392,15 +384,24 @@ export class RscRenderer {
       this.#resultCache.clear();
       this.#patchResultCache.clear();
       this.#logger.verbose(`reload complete buildId=${msg.buildId} in ${Date.now() - startedAt}ms`);
-      this.#send({ type: "reloaded", buildId: msg.buildId });
+      this.#send({
+        type: "reloaded",
+        buildId: msg.buildId,
+        reloadId: msg.reloadId,
+        pagesBundlePath: nextPagesBundlePath,
+      });
     } catch (error) {
       this.#logger.error(
         `reload failed buildId=${msg.buildId}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
       );
+      
+      if (seq !== this.#reloadSeq) return;
       this.#send({
         type: "error",
         requestId: "__reload__",
         buildId: msg.buildId,
+        reloadId: msg.reloadId,
+        running: { pagesBundlePath: this.#pagesBundlePath, buildId: this.#pagesBundleBuildId },
         message: error instanceof Error ? error.message : String(error),
       });
     }
@@ -482,10 +483,8 @@ export class RscRenderer {
               })
             : { status: "full" as const, reason: partialDecision.reason, commonPrefixLength: 0 };
         const safePatchDecision = match
-          ? await this.#resolveHeadSafePatchDecision(
-              match.pathRoute,
-              patchDecision,
-              await this.#resolveRouteHeadSnapshot(urlObj, match, searchParams),
+          ? await this.#resolveHeadSafePatchDecision(match.pathRoute, patchDecision, () =>
+              this.#resolveRouteHeadSnapshot(urlObj, match, searchParams),
             )
           : patchDecision;
         const patchCacheEntry = resolveRscWorkerPatchCacheEntry({
@@ -521,7 +520,7 @@ export class RscRenderer {
           ...(cacheDecision.reason ? { cacheReason: cacheDecision.reason } : {}),
         });
         const traceBase = createTraceBase(safePatchDecision, patchCacheEntry?.key ?? cacheEntry?.key);
-        const cachedPatch = patchCacheEntry ? this.#getCachedPatchResult(patchCacheEntry.key) : null;
+        const cachedPatch = patchCacheEntry ? this.#getCached(this.#patchResultCache, patchCacheEntry.key) : null;
         if (
           cachedPatch?.patch &&
           patchCacheEntry &&
@@ -540,63 +539,31 @@ export class RscRenderer {
             patchCacheEntry.key,
             cachedPatch.patch.targetRouterState,
           );
-          this.#stats.lastRenderDurationMs = Date.now() - startedAt;
-          this.#stats.lastRenderLoadedModuleDelta = 0;
-          this.#stats.lastRenderLoadedModules = [];
-          this.#stats.lastFlightBytes = cachedPatch.bytes;
-          this.#stats.lastFlightChunks = cachedPatch.chunksCount;
-          this.#stats.totalFlightBytes += cachedPatch.bytes;
-          this.#stats.totalFlightChunks += cachedPatch.chunksCount;
-          this.#recordRouteStats(routeId, cachedPatch.bytes, this.#stats.lastRenderDurationMs);
-          await replayCachedRscResult({
-            requestId,
-            chunks: cachedPatch.chunks,
-            theme: cachedPatch.theme,
-            cacheState: cachedPatch.cacheState,
-            trace: {
-              ...cachedTraceBase,
-              cache: "hit",
-              partial: "patch",
-              partialReason: "cache-hit-patch-replay",
-            },
-            send: (message) => this.#send(message),
-            isCancelled: () => this.#cancelledRenderRequests.has(requestId),
+          await this.#replayCached(requestId, routeId, startedAt, cachedPatch, {
+            ...cachedTraceBase,
+            cache: "hit",
+            partial: "patch",
+            partialReason: "cache-hit-patch-replay",
           });
           return;
         }
         const cached =
           shouldUseRscWorkerFullResultCache({ cacheEntry, patchCacheEntry }) && cacheEntry
-            ? this.#getCachedResult(cacheEntry.key)
+            ? this.#getCached(this.#resultCache, cacheEntry.key)
             : null;
         if (cached) {
-          this.#stats.lastRenderDurationMs = Date.now() - startedAt;
-          this.#stats.lastRenderLoadedModuleDelta = 0;
-          this.#stats.lastRenderLoadedModules = [];
-          this.#stats.lastFlightBytes = cached.bytes;
-          this.#stats.lastFlightChunks = cached.chunksCount;
-          this.#stats.totalFlightBytes += cached.bytes;
-          this.#stats.totalFlightChunks += cached.chunksCount;
-          this.#recordRouteStats(routeId, cached.bytes, this.#stats.lastRenderDurationMs);
-          await replayCachedRscResult({
-            requestId,
-            chunks: cached.chunks,
-            theme: cached.theme,
-            cacheState: cached.cacheState,
-            trace: {
-              ...traceBase,
-              cache: "hit",
-              partial: "full",
-              partialReason: "cache-hit-full-replay",
-              partialCommonPrefixLength: 0,
-              patchStartIndex: undefined,
-              patchSegmentPath: undefined,
-              patchStartSegment: undefined,
-              patchHeadSafe: undefined,
-              patchHeadSnapshot: undefined,
-              ssrBlocking: cached.ssrBlocking,
-            },
-            send: (message) => this.#send(message),
-            isCancelled: () => this.#cancelledRenderRequests.has(requestId),
+          await this.#replayCached(requestId, routeId, startedAt, cached, {
+            ...traceBase,
+            cache: "hit",
+            partial: "full",
+            partialReason: "cache-hit-full-replay",
+            partialCommonPrefixLength: 0,
+            patchStartIndex: undefined,
+            patchSegmentPath: undefined,
+            patchStartSegment: undefined,
+            patchHeadSafe: undefined,
+            patchHeadSnapshot: undefined,
+            ssrBlocking: cached.ssrBlocking,
           });
           return;
         }
@@ -645,6 +612,17 @@ export class RscRenderer {
               lateRedirect: control?.type === "redirect" && lateControlSent,
             });
             const storeTtl = cacheEntry ? resolveRouteCacheStoreTtl(cacheEntry.ttl, cacheState) : null;
+            const stored = (): CachedRscResult => ({
+              chunks,
+              bytes,
+              chunksCount,
+              pathname: urlObj.pathname,
+              routeId,
+              tags: cacheState.tags,
+              theme: getRequestTheme(),
+              ssrBlocking,
+              cacheState,
+            });
             if (
               shouldStoreRscWorkerPatchResult({
                 cacheEntry,
@@ -657,41 +635,10 @@ export class RscRenderer {
               effectivePatchDecision.patch &&
               storeTtl !== null
             ) {
-              this.#setCachedPatchResult(
-                patchCacheEntry.key,
-                {
-                  chunks,
-                  bytes,
-                  chunksCount,
-                  pathname: urlObj.pathname,
-                  routeId,
-                  tags: cacheState.tags,
-                  theme: getRequestTheme(),
-                  ssrBlocking,
-                  cacheState,
-                  patch: createCachedRscPatchMetadata({
-                    targetRouterState,
-                    patch: effectivePatchDecision.patch,
-                  }),
-                },
-                storeTtl,
-              );
+              const patch = createCachedRscPatchMetadata({ targetRouterState, patch: effectivePatchDecision.patch });
+              this.#store("patch", this.#patchResultCache, patchCacheEntry.key, { ...stored(), patch }, storeTtl);
             } else if (cacheEntry && storeTtl !== null && effectivePatchDecision.status !== "patch") {
-              this.#setCachedResult(
-                cacheEntry.key,
-                {
-                  chunks,
-                  bytes,
-                  chunksCount,
-                  pathname: urlObj.pathname,
-                  routeId,
-                  tags: cacheState.tags,
-                  theme: getRequestTheme(),
-                  ssrBlocking,
-                  cacheState,
-                },
-                storeTtl,
-              );
+              this.#store("full", this.#resultCache, cacheEntry.key, stored(), storeTtl);
             }
             return cacheState;
           },
@@ -710,10 +657,7 @@ export class RscRenderer {
               msg.clientManifest ?? this.#clientManifest,
               { requestId, status: 404, trace },
             );
-            if (systemResult.cancelled) return;
-            if (!systemResult.control) {
-              return;
-            }
+            if (systemResult.cancelled || !systemResult.control) return;
           }
           if (
             match &&
@@ -747,18 +691,14 @@ export class RscRenderer {
           this.#sendRenderControl(requestId, control);
           return;
         }
-        this.#stats.lastFlightBytes = result.bytes;
-        this.#stats.lastFlightChunks = result.chunksCount;
-        this.#stats.totalFlightBytes += result.bytes;
-        this.#stats.totalFlightChunks += result.chunksCount;
+        this.#recordFlight(result);
         this.#stats.lastRenderDurationMs = Date.now() - startedAt;
         const afterLoadedKeys = RouteTreeBuilder.getCacheStats().loadedModuleKeys;
         this.#stats.lastRenderLoadedModules = afterLoadedKeys.filter((key) => !beforeLoadedKeys.includes(key));
         this.#stats.lastRenderLoadedModuleDelta = this.#stats.lastRenderLoadedModules.length;
         this.#recordRouteStats(routeId, result.bytes, this.#stats.lastRenderDurationMs);
-        const responseTheme = getRequestTheme();
         this.#logger.verbose(
-          `render[${requestId}] done chunks=${result.chunksCount} bytes=${result.bytes} theme=${responseTheme ?? "(none)"} in ${
+          `render[${requestId}] done chunks=${result.chunksCount} bytes=${result.bytes} theme=${getRequestTheme() ?? "(none)"} in ${
             Date.now() - startedAt
           }ms`,
         );
@@ -776,27 +716,25 @@ export class RscRenderer {
         });
         return;
       }
+      const { url: fallbackUrl, match: fallbackMatch } = activeRoute;
+      const trySendFallback = async (kind: "not-found" | "error") =>
+        !!fallbackUrl &&
+        !!fallbackMatch &&
+        (await this.#trySendFallbackRender({
+          requestId,
+          kind,
+          route: fallbackMatch.pathRoute,
+          params: fallbackMatch.params,
+          searchParams: RouteTreeBuilder.parseSearchParams(fallbackUrl.search),
+          pathname: fallbackUrl.pathname,
+          url: fallbackUrl,
+          error: kind === "error" ? error : undefined,
+          clientManifest: msg.clientManifest ?? this.#clientManifest,
+        }));
       if (isAkanNotFoundError(error)) {
         this.#stats.lastRenderKind = "not-found";
         this.#logger.verbose(`render[${requestId}] not-found`);
-        const fallbackUrl = activeRoute.url;
-        const fallbackMatch = activeRoute.match;
-        if (
-          fallbackUrl &&
-          fallbackMatch &&
-          (await this.#trySendFallbackRender({
-            requestId,
-            kind: "not-found",
-            route: fallbackMatch.pathRoute,
-            params: fallbackMatch.params,
-            searchParams: RouteTreeBuilder.parseSearchParams(fallbackUrl.search),
-            pathname: fallbackUrl.pathname,
-            url: fallbackUrl,
-            clientManifest: msg.clientManifest ?? this.#clientManifest,
-          }))
-        ) {
-          return;
-        }
+        if (await trySendFallback("not-found")) return;
         if (
           fallbackUrl &&
           (await this.#trySendSystemNotFoundRender({
@@ -813,25 +751,7 @@ export class RscRenderer {
       this.#logger.error(
         `render[${requestId}] failed url=${url}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
       );
-      const fallbackUrl = activeRoute.url;
-      const fallbackMatch = activeRoute.match;
-      if (
-        fallbackUrl &&
-        fallbackMatch &&
-        (await this.#trySendFallbackRender({
-          requestId,
-          kind: "error",
-          route: fallbackMatch.pathRoute,
-          params: fallbackMatch.params,
-          searchParams: RouteTreeBuilder.parseSearchParams(fallbackUrl.search),
-          pathname: fallbackUrl.pathname,
-          url: fallbackUrl,
-          error,
-          clientManifest: msg.clientManifest ?? this.#clientManifest,
-        }))
-      ) {
-        return;
-      }
+      if (await trySendFallback("error")) return;
       this.#send({
         type: "error",
         requestId,
@@ -844,15 +764,6 @@ export class RscRenderer {
     }
   }
 
-  #startMetricsReporting() {
-    if (this.#metricsTimer) return;
-    const report = () => {
-      void this.#sendMetricsReport();
-    };
-    report();
-    this.#metricsTimer = setInterval(report, ProcessMetricsCollector.parseMemoryLogIntervalMs());
-  }
-
   async #sendMetricsReport() {
     const routeStats = RouteTreeBuilder.getCacheStats();
     const metrics = await ProcessMetricsCollector.collect({
@@ -878,7 +789,6 @@ export class RscRenderer {
       rscLoadedRouteModuleKeys: routeStats.loadedModuleKeys,
       rscTopRoutesByRenderCount: this.#topRoutes((route) => route.count),
       rscTopRoutesByFlightBytes: this.#topRoutes((route) => route.flightBytes),
-
       rscResultCacheEntries: this.#resultCache.size,
       rscResultCacheBytes: this.#resultCache.byteSize,
       rscPatchResultCacheEntries: this.#patchResultCache.size,
@@ -890,12 +800,6 @@ export class RscRenderer {
     this.#send({ type: "metrics", metrics });
   }
 
-  /**
-   * An error raised after the first Flight chunk has left the worker can no longer become a status code or a
-   * system error page — `sendLateRedirect` is the only control the host can still act on, so the render
-   * control is dropped. Logging here is the only record that the request failed at all; without it a page
-   * whose boundary died mid-stream is indistinguishable from one that rendered.
-   */
   #reportRenderError(error: unknown, pathname?: string): void {
     const description = error instanceof Error ? (error.stack ?? error.message) : String(error);
     const scope = pathname ? ` path=${pathname}` : "";
@@ -906,7 +810,6 @@ export class RscRenderer {
     this.#logger.error(`[rsc] render failed${scope}: ${description}`);
   }
 
-  /** A client that navigated away, or a stream the host cancelled: expected, and not the replica's problem. */
   static #isExpectedRequestAbort(error: unknown): boolean {
     if (!(error instanceof Error)) return false;
     return (
@@ -924,30 +827,18 @@ export class RscRenderer {
       collectChunks?: boolean;
       status?: number;
       trace?: RscTraceMetadata;
-      onComplete?: (result: {
-        chunks: Uint8Array[];
-        bytes: number;
-        chunksCount: number;
-        control: RenderControl | null;
-        lateControlSent: boolean;
-      }) => Promise<RouteCacheRenderState> | RouteCacheRenderState;
+      onComplete?: (
+        result: Omit<FlightRenderResult, "cancelled">,
+      ) => Promise<RouteCacheRenderState> | RouteCacheRenderState;
     } = {},
   ): Promise<FlightRenderResult> {
     const controlRef: { current: RenderControl | null } = { current: null };
     const stream = await renderToReadableStream(element, clientManifest, {
       onError: (error) => {
         if (isAkanRedirectError(error)) {
-          controlRef.current = {
-            type: "redirect",
-            location: error.location,
-            method: error.method,
-            status: error.status,
-          };
-          return encodeAkanRedirectDigest({
-            location: error.location,
-            method: error.method,
-            status: error.status,
-          });
+          const { location, method, status } = error;
+          controlRef.current = { type: "redirect", location, method, status };
+          return encodeAkanRedirectDigest({ location, method, status });
         }
         if (isAkanNotFoundError(error)) {
           controlRef.current = { type: "not-found" };
@@ -966,6 +857,7 @@ export class RscRenderer {
     let sentChunk = false;
     let lateControlSent = false;
     const chunks: Uint8Array[] = [];
+    let reportedTheme: AkanTheme | undefined;
     const sendMeta = () => {
       if (!options.requestId || sentMeta) return;
       sentMeta = true;
@@ -973,17 +865,25 @@ export class RscRenderer {
         const trace = getCurrentTrace();
         if (trace) trace.status = options.status;
       }
+      reportedTheme = getRequestTheme();
       this.#send({
         type: "meta",
         requestId: options.requestId,
-        theme: getRequestTheme(),
+        theme: reportedTheme,
         status: options.status,
         trace: options.trace,
       });
     };
+
+    const sendLateTheme = () => {
+      const theme = getRequestTheme();
+      if (!options.requestId || !sentMeta || theme === reportedTheme) return;
+      reportedTheme = theme;
+      this.#send({ type: "theme", requestId: options.requestId, theme });
+    };
     const sendLateRedirect = () => {
       if (!options.requestId || lateControlSent || controlRef.current?.type !== "redirect") return;
-
+      
       lateControlSent = true;
       this.#send({
         type: "late-redirect",
@@ -1012,6 +912,7 @@ export class RscRenderer {
         if (options.collectChunks) chunks.push(chunk);
         if (options.requestId) {
           sendMeta();
+          sendLateTheme();
           this.#send({ type: "chunk", requestId: options.requestId, data: chunk });
           sentChunk = true;
         }
@@ -1081,22 +982,11 @@ export class RscRenderer {
         searchParams,
         pathname,
         url,
-        error: kind === "error" ? RscRenderer.#errorForFallback(error) : undefined,
+        error: kind === "error" && process.env.NODE_ENV !== "production" ? error : undefined,
         digest: kind === "error" ? "AKAN_RENDER_ERROR" : undefined,
       });
       if (!element) return false;
-      const result = await this.#renderFlightElement(element, clientManifest, {
-        requestId,
-        status: kind === "not-found" ? 404 : 500,
-        trace,
-      });
-      if (result.cancelled) return true;
-      if (result.control) return false;
-      this.#stats.lastFlightBytes = result.bytes;
-      this.#stats.lastFlightChunks = result.chunksCount;
-      this.#stats.totalFlightBytes += result.bytes;
-      this.#stats.totalFlightChunks += result.chunksCount;
-      return true;
+      return await this.#trySendFlight(requestId, element, clientManifest, kind === "not-found" ? 404 : 500, trace);
     } catch (fallbackError) {
       this.#logger.error(
         `render[${requestId}] custom ${kind} fallback failed: ${
@@ -1119,18 +1009,7 @@ export class RscRenderer {
     trace?: RscTraceMetadata;
   }): Promise<boolean> {
     try {
-      const result = await this.#renderFlightElement(this.#renderSystemNotFound(url), clientManifest, {
-        requestId,
-        status: 404,
-        trace,
-      });
-      if (result.cancelled) return true;
-      if (result.control) return false;
-      this.#stats.lastFlightBytes = result.bytes;
-      this.#stats.lastFlightChunks = result.chunksCount;
-      this.#stats.totalFlightBytes += result.bytes;
-      this.#stats.totalFlightChunks += result.chunksCount;
-      return true;
+      return await this.#trySendFlight(requestId, this.#renderSystemNotFound(url), clientManifest, 404, trace);
     } catch (error) {
       this.#logger.error(
         `render[${requestId}] system not-found fallback failed: ${
@@ -1141,6 +1020,50 @@ export class RscRenderer {
     }
   }
 
+  async #trySendFlight(
+    requestId: string,
+    element: ReactNode,
+    clientManifest: ClientManifest,
+    status: number,
+    trace?: RscTraceMetadata,
+  ): Promise<boolean> {
+    const result = await this.#renderFlightElement(element, clientManifest, { requestId, status, trace });
+    if (result.cancelled) return true;
+    if (result.control) return false;
+    this.#recordFlight(result);
+    return true;
+  }
+
+  async #replayCached(
+    requestId: string,
+    routeId: string,
+    startedAt: number,
+    cached: CachedRscResult,
+    trace: RscTraceMetadata,
+  ): Promise<void> {
+    this.#stats.lastRenderDurationMs = Date.now() - startedAt;
+    this.#stats.lastRenderLoadedModuleDelta = 0;
+    this.#stats.lastRenderLoadedModules = [];
+    this.#recordFlight(cached);
+    this.#recordRouteStats(routeId, cached.bytes, this.#stats.lastRenderDurationMs);
+    await replayCachedRscResult({
+      requestId,
+      chunks: cached.chunks,
+      theme: cached.theme,
+      cacheState: cached.cacheState,
+      trace,
+      send: (message) => this.#send(message),
+      isCancelled: () => this.#cancelledRenderRequests.has(requestId),
+    });
+  }
+
+  #recordFlight({ bytes, chunksCount }: { bytes: number; chunksCount: number }): void {
+    this.#stats.lastFlightBytes = bytes;
+    this.#stats.lastFlightChunks = chunksCount;
+    this.#stats.totalFlightBytes += bytes;
+    this.#stats.totalFlightChunks += chunksCount;
+  }
+
   #sendRenderControl(requestId: string, control: RenderControl): void {
     if (control.type === "redirect") {
       this.#logger.verbose(`render[${requestId}] redirect ${control.location}`);
@@ -1166,7 +1089,7 @@ export class RscRenderer {
   async #resolveHeadSafePatchDecision(
     pathRoute: PathRoute,
     patchDecision: AkanRscPatchDecision,
-    headSnapshot: ResolvedHead["headSnapshot"],
+    resolveHeadSnapshot: () => Promise<ResolvedHead["headSnapshot"]>,
   ): Promise<AkanRscPatchDecision> {
     if (patchDecision.status !== "patch" || !patchDecision.patch) {
       return patchDecision;
@@ -1174,11 +1097,12 @@ export class RscRenderer {
     if (!isAkanRscPartialCommitEnabled()) {
       return { status: "full", reason: "guard-disabled", commonPrefixLength: patchDecision.commonPrefixLength };
     }
+    const pageConfig = await pathRoute.renderPage.getPageConfig?.();
     return resolveAkanRscHeadSafePatchDecision({
       partialCommitEnabled: true,
       patchDecision,
-      pageConfig: await pathRoute.renderPage.getPageConfig?.(),
-      headSnapshot,
+      pageConfig,
+      headSnapshot: pageConfig?.rscPatchHeadSafe === true ? await resolveHeadSnapshot() : undefined,
     });
   }
 
@@ -1229,37 +1153,15 @@ export class RscRenderer {
     };
   }
 
-  #getCachedResult(cacheKey: string): CachedRscResult | null {
-    const cached = this.#resultCache.get(cacheKey);
-    if (!cached) {
-      this.#resultCacheMisses += 1;
-      return null;
-    }
-    this.#resultCacheHits += 1;
+  #getCached(cache: LruTtlCache<CachedRscResult>, cacheKey: string): CachedRscResult | null {
+    const cached = cache.get(cacheKey);
+    if (cached) this.#resultCacheHits += 1;
+    else this.#resultCacheMisses += 1;
     return cached;
   }
 
-  #getCachedPatchResult(cacheKey: string): CachedRscResult | null {
-    const cached = this.#patchResultCache.get(cacheKey);
-    if (!cached) {
-      this.#resultCacheMisses += 1;
-      return null;
-    }
-    this.#resultCacheHits += 1;
-    return cached;
-  }
-
-  #setCachedResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
-    this.#logRejectedStore("full", result, this.#resultCache.set(cacheKey, result, ttl));
-  }
-
-  #setCachedPatchResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
-    this.#logRejectedStore("patch", result, this.#patchResultCache.set(cacheKey, result, ttl));
-  }
-
-  /** A silently dropped store looks identical to a cache miss; say which route is too big to cache. */
-  #logRejectedStore(kind: string, result: CachedRscResult, stored: boolean): void {
-    if (stored) return;
+  #store(kind: string, cache: LruTtlCache<CachedRscResult>, cacheKey: string, result: CachedRscResult, ttl: number) {
+    if (cache.set(cacheKey, result, ttl)) return;
     this.#logger.verbose(
       `${kind} result cache store skipped pathname=${result.pathname} bytes=${result.bytes} reason=body-too-large`,
     );
@@ -1311,17 +1213,15 @@ export class RscRenderer {
     if (!body) return null;
     const routeHead =
       "resolveHead" in route
-        ? await RouteElementComposer.resolveHeadWithMetadata({
+        ? await RouteElementComposer.resolveHeadWithSnapshot({
             pathRoute: route,
             params,
             searchParams,
           })
-        : { node: undefined, hasExplicitLanguageAlternates: false };
-    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead, {
-      hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
-    });
+        : { node: undefined };
+    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead);
     return (
-      <html lang={params.lang ?? RscRenderer.#getLocale(pathname, this.#i18n)} suppressHydrationWarning>
+      <html lang={params.lang ?? getPathnameLocale(pathname, this.#i18n)} suppressHydrationWarning>
         <head key="head">
           <meta key="charset" charSet="utf-8" />
           <meta key="viewport" name="viewport" content="width=device-width, initial-scale=1" />
@@ -1329,10 +1229,7 @@ export class RscRenderer {
           {routeHeadSnapshot
             ? renderAkanHeadSnapshot(routeHeadSnapshot)
             : (routeHead.node ?? this.#renderDefaultHead())}
-          {!routeHeadSnapshot &&
-          shouldRenderLocaleAlternates({ hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates })
-            ? this.#renderLocaleAlternates(url)
-            : null}
+          {routeHeadSnapshot ? null : this.#renderLocaleAlternates(url)}
           {this.#renderStylesheet(pathname)}
         </head>
         <body key="body">{body}</body>
@@ -1353,15 +1250,16 @@ export class RscRenderer {
       basePath: this.#getBasePath(url),
     });
     setRequestFrameState(pathRoute.pageState);
-    const routeHead = await RouteElementComposer.resolveHeadWithMetadata({
+    
+    const rootThemes = await Promise.all(pathRoute.renderRootLayouts.map((render) => render.getLayoutTheme?.()));
+    const rootTheme = rootThemes.find((theme) => theme !== undefined);
+    if (rootTheme) setRequestTheme(rootTheme);
+    const routeHead = await RouteElementComposer.resolveHeadWithSnapshot({
       pathRoute,
       params: match.params,
       searchParams,
     });
-    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead, {
-      isSpecialRoute: pathRoute.isSpecialRoute,
-      hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
-    });
+    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead);
     const body = RouteElementComposer.compose({
       pathRoute,
       params: match.params,
@@ -1377,13 +1275,7 @@ export class RscRenderer {
           {routeHeadSnapshot
             ? renderAkanHeadSnapshot(routeHeadSnapshot)
             : (routeHead.node ?? this.#renderDefaultHead())}
-          {!routeHeadSnapshot &&
-          shouldRenderLocaleAlternates({
-            isSpecialRoute: pathRoute.isSpecialRoute,
-            hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
-          })
-            ? this.#renderLocaleAlternates(url)
-            : null}
+          {routeHeadSnapshot ? null : this.#renderLocaleAlternates(url)}
           {this.#renderStylesheet(url.pathname)}
         </head>
         <body key="body">{body}</body>
@@ -1405,7 +1297,6 @@ export class RscRenderer {
       basePath: this.#getBasePath(url),
     });
     setRequestFrameState(pathRoute.pageState);
-
     await RouteElementComposer.resolveSuffixLoadings(pathRoute, patchStartIndex);
     return RouteElementComposer.composeSuffix({
       pathRoute,
@@ -1442,7 +1333,7 @@ export class RscRenderer {
     return createSystemPageDocument({
       kind: "not-found",
       pathname: url.pathname,
-      lang: RscRenderer.#getLocale(url.pathname, this.#i18n),
+      lang: getPathnameLocale(url.pathname, this.#i18n),
       homeHref: getSystemPageHomeHref({
         pathname: url.pathname,
         i18n: this.#i18n,
@@ -1470,33 +1361,22 @@ export class RscRenderer {
     match: { pathRoute: PathRoute; params: Record<string, string> },
     searchParams: Record<string, string | string[]>,
   ): Promise<ResolvedHead["headSnapshot"]> {
-    const routeHead = await RouteElementComposer.resolveHeadWithMetadata({
+    const routeHead = await RouteElementComposer.resolveHeadWithSnapshot({
       pathRoute: match.pathRoute,
       params: match.params,
       searchParams,
     });
-    return this.#createRouteHeadSnapshot(url, routeHead, {
-      isSpecialRoute: match.pathRoute.isSpecialRoute,
-      hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
-    });
+    return this.#createRouteHeadSnapshot(url, routeHead);
   }
 
-  #createRouteHeadSnapshot(
-    url: URL,
-    routeHead: ResolvedHead,
-    options: { isSpecialRoute?: boolean; hasExplicitLanguageAlternates?: boolean },
-  ): ResolvedHead["headSnapshot"] {
+  #createRouteHeadSnapshot(url: URL, routeHead: ResolvedHead): ResolvedHead["headSnapshot"] {
     if (!routeHead.headSnapshot) return undefined;
     return mergeAkanHeadSnapshots(
       routeHead.headSnapshot,
-      shouldRenderLocaleAlternates(options) ? this.#createLocaleAlternateHeadSnapshot(url) : undefined,
+      createAkanLocaleAlternateHeadSnapshot(this.#getLocaleAlternateLanguages(url)),
     );
   }
 
-  #createLocaleAlternateHeadSnapshot(url: URL): ResolvedHead["headSnapshot"] {
-    return createAkanLocaleAlternateHeadSnapshot(this.#getLocaleAlternateLanguages(url));
-  }
-
   #getLocaleAlternateLanguages(url: URL): Record<string, string> {
     const languages: Record<string, string> = {};
     const publicUrl = RscRenderer.#getPublicRequestUrl(url);
@@ -1534,22 +1414,12 @@ export class RscRenderer {
     return this.#cssAssets[basePath ?? ""]?.cssUrl ?? null;
   }
 
-  static #getLocale(pathname: string, i18n: AkanI18nConfig): string {
-    const [segment] = pathname.split("/").filter(Boolean);
-    return segment && i18n.locales.includes(segment) ? segment : i18n.defaultLocale;
-  }
-
-  static #errorForFallback(error: unknown): unknown {
-    if (process.env.NODE_ENV !== "production") return error;
-    return undefined;
-  }
-
   static #getPublicRequestUrl(url: URL): URL {
     const publicUrl = new URL(url);
     const req = untrackedRequest();
     const headers = req?.headers;
-    const host = headers?.get("x-forwarded-host") ?? headers?.get("host");
-    const proto = headers?.get("x-forwarded-proto");
+    const host = headers?.get("x-forwarded-host")?.split(",")[0]?.trim() ?? headers?.get("host");
+    const proto = headers?.get("x-forwarded-proto")?.split(",")[0]?.trim();
     if (host) publicUrl.host = host;
     if (host && !host.includes(":")) publicUrl.port = "";
     if (proto) publicUrl.protocol = proto.endsWith(":") ? proto : `${proto}:`;