@rangojs/router 0.0.0-experimental.116 → 0.0.0-experimental.118

package/src/router/loader-resolution.ts

@@ -27,6 +27,8 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
+  isInsidePushCallbackScope,
+  runInsidePushCallbackScope,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -290,6 +292,12 @@ function createLoaderExecutor<TEnv>(
             );
           }
           const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
+          // The complete snapshot is cached at barrier resolution for
+          // non-streaming trees, and by rendered() after handleStore.settled for
+          // streaming trees (where the eager snapshot would have been incomplete
+          // because loading() handlers were still in flight). Either way it is
+          // present by the time a loader reads a handle; the fresh build is only
+          // a defensive fallback.
           const snapshot =
             reqCtx._renderBarrierHandleSnapshot ??
             buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
@@ -311,15 +319,7 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
-        // Guard: reject streaming trees
         const reqCtx = reqCtxRef ?? _getRequestContext();
-        if (reqCtx?._treeHasStreaming) {
-          throw new Error(
-            `ctx.rendered() is not supported when the matched route tree uses loading(). ` +
-              `Streaming handlers may not have settled when rendered() resolves. ` +
-              `Remove loading() from the route tree or restructure to avoid rendered().`,
-          );
-        }
 
         if (renderedPromise) return renderedPromise;
 
@@ -330,7 +330,10 @@ function createLoaderExecutor<TEnv>(
         }
 
         // Bidirectional deadlock check: if a handler already started
-        // awaiting this loader, calling rendered() would deadlock.
+        // awaiting this loader, calling rendered() would deadlock. This is the
+        // real cycle guard (it holds for both streaming and non-streaming): the
+        // handler blocks segment resolution, which blocks the barrier, which
+        // blocks this loader.
         if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
           throw new Error(
             `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
@@ -348,7 +351,29 @@ function createLoaderExecutor<TEnv>(
         }
         reqCtx._renderBarrierWaiters.add(currentLoaderId);
 
-        renderedPromise = reqCtx._renderBarrier.then(() => {
+        // Streaming trees (loading()): the barrier resolves once the segment
+        // tree is resolved, but loading() handlers stream behind Suspense and
+        // their handle pushes are still in flight then. Their async execution
+        // IS tracked in the handle store (trackHandler -> store.track), so after
+        // the barrier we seal (no further handlers register once the tree is
+        // resolved) and wait for settled — every tracked handler, streaming
+        // included, has finished pushing. The loader's own segment streams in
+        // after, so this does not block the shell; the deadlock guard above
+        // keeps a handler from depending on this loader.
+        const streaming = reqCtx._treeHasStreaming === true;
+        renderedPromise = reqCtx._renderBarrier.then(async () => {
+          if (streaming) {
+            reqCtx._handleStore.seal();
+            await reqCtx._handleStore.settled;
+            // The eager snapshot was intentionally left unbuilt for streaming
+            // (it would have been incomplete). Build the complete one once, now
+            // that the store has settled, so every ctx.use(handle) reads the
+            // cached snapshot instead of rebuilding it per call.
+            reqCtx._renderBarrierHandleSnapshot ??= buildHandleSnapshot(
+              reqCtx._handleStore,
+              reqCtx._renderBarrierSegmentOrder ?? [],
+            );
+          }
           renderedResolved = true;
         });
         return renderedPromise;
@@ -404,12 +429,6 @@ export function setupLoaderAccess<TEnv>(
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
-  // Track whether we're inside a handle push callback. Loaders started
-  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
-  // block segment resolution, so they must not be registered as handler
-  // dependencies for deadlock detection.
-  let insideHandlePush = false;
-
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -430,15 +449,17 @@ export function setupLoaderAccess<TEnv>(
         if (!store) return;
 
         if (typeof dataOrFn === "function") {
-          // Mark scope so ctx.use(loader) calls inside the callback
-          // are not registered as handler-to-loader deps.
-          insideHandlePush = true;
-          try {
-            const result = (dataOrFn as () => Promise<unknown>)();
-            store.push(handle.$$id, segmentId, result);
-          } finally {
-            insideHandlePush = false;
-          }
+          // Run the callback inside the push-callback scope so ctx.use(loader)
+          // calls it makes — including after its own awaits, for an async
+          // callback — are not registered as handler-to-loader deps and do not
+          // trip the deadlock guard. A pushed promise value is not tracked by
+          // handleStore.settled and does not block segment resolution, so it
+          // cannot form a rendered() deadlock. The ALS scope (not a plain
+          // boolean) is what survives the callback's awaits.
+          const result = runInsidePushCallbackScope(() =>
+            (dataOrFn as () => Promise<unknown>)(),
+          );
+          store.push(handle.$$id, segmentId, result);
           return;
         }
 
@@ -450,9 +471,12 @@ export function setupLoaderAccess<TEnv>(
     // Skip when inside a DSL loader scope (resolveLoaderData also calls
     // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
     // inside a handle push callback (push callbacks don't block segment
-    // resolution so they can't cause rendered() deadlocks).
+    // resolution so they can't cause rendered() deadlocks). The push-callback
+    // check is an ALS scope so it also exempts an ASYNC callback's continuation
+    // after its first await — relevant on streaming trees, where the guard
+    // state now stays live until handleStore.settled.
     const loader = item as LoaderDefinition<any, any>;
-    if (!isInsideLoaderScope() && !insideHandlePush) {
+    if (!isInsideLoaderScope() && !isInsidePushCallbackScope()) {
       const reqCtx = reqCtxRef ?? _getRequestContext();
       if (reqCtx) {
         // Direction 1: handler awaits loader that already called rendered()
@@ -466,13 +490,18 @@ export function setupLoaderAccess<TEnv>(
               `Move the data dependency to a loader-to-loader pattern instead.`,
           );
         }
-        // Direction 2: track dep so rendered() can detect the deadlock
-        // if the loader calls it later. Skip when the barrier has already
-        // resolved — no deadlock is possible (rendered() resolves immediately).
-        // _renderBarrierSegmentOrder is undefined before resolution, string[]
-        // after. This also prevents false positives from handle push callbacks
-        // that resume after their first await (post-barrier-resolution).
-        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+        // Direction 2: track dep so rendered() can detect the deadlock if the
+        // loader calls it later. Skip once the guard window is CLOSED — for a
+        // non-streaming tree that is when the barrier resolves (rendered()
+        // resolves immediately), and for a streaming tree it is when
+        // handleStore.settled completes (rendered() keeps waiting until then, so
+        // a loading() handler resuming after the barrier can still form a
+        // cycle). Using the explicit guard-closed flag rather than
+        // _renderBarrierSegmentOrder keeps tracking live across the streaming
+        // settle wait. (Handle push callbacks are already excluded above via
+        // isInsidePushCallbackScope(), so they cannot produce false positives
+        // here.)
+        if (!reqCtx._renderBarrierGuardClosed) {
           if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
           reqCtx._handlerLoaderDeps.add(loader.$$id);
         }

package/src/router/manifest.ts

@@ -32,7 +32,7 @@ import { VERSION } from "@rangojs/router:version";
 // own pruned manifest, so alternating sibling requests would thrash (re-run the
 // handler every time). Running the include handler once per isolate instead of once
 // per route is possible but needs an unpruned manifest cache with prune-on-read — see
-// LP1 in docs/internal/matching-stability-review.md. VERSION comes from the
+// LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();

package/src/router/match-middleware/cache-lookup.ts

@@ -114,6 +114,9 @@ let _deserializeSegments:
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
+let _decodeHandles:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandles
+  | undefined;
 let _hashParams:
   | typeof import("../../prerender/param-hash.js").hashParams
   | undefined;
@@ -148,6 +151,7 @@ async function ensurePrerenderDeps() {
     ]);
     _deserializeSegments = codec.deserializeSegments;
     _restoreHandles = snapshot.restoreHandles;
+    _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
     _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
@@ -174,6 +178,7 @@ async function* yieldFromStore<TEnv>(
   if (
     !_deserializeSegments ||
     !_restoreHandles ||
+    !_decodeHandles ||
     !_hashParams ||
     !_lazyGetRequestContext
   ) {
@@ -182,11 +187,15 @@ async function* yieldFromStore<TEnv>(
 
   const segments = await _deserializeSegments(entry.segments);
 
-  // Replay handle data (same as runtime cache hit path).
-  // Prefer the eagerly-captured handleStoreRef to avoid ALS disruption in workerd.
+  // Replay handle data (same as runtime cache hit path). entry.handles is a
+  // Flight-encoded string ("" when none) — decode before restore so
+  // Promise/ReactNode handle values are revived, not the corrupted JSON form.
   const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
-  if (handleStore) {
-    _restoreHandles(entry.handles, handleStore);
+  if (handleStore && entry.handles) {
+    const handlesRecord = await _decodeHandles(entry.handles);
+    if (handlesRecord) {
+      _restoreHandles(handlesRecord, handleStore);
+    }
   }
 
   state.cacheHit = true;

package/src/router/prerender-match.ts

@@ -59,11 +59,16 @@ export async function matchForPrerender<TEnv = any>(
   devMode?: boolean,
 ): Promise<{
   segments: SerializedSegmentData[];
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. Encoded in
+   *  the producer (where the Flight codec resolves) so the node-side build/dev
+   *  sinks can persist it without touching the codec. */
+  handles: string;
   routeName: string;
   params: Record<string, string>;
   interceptSegments?: SerializedSegmentData[];
-  interceptHandles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact;
+   *  the sinks store it as-is (no longer merge raw records). */
+  interceptHandles?: string;
   passthrough?: true;
 } | null> {
   // 1. Find the matching route entry
@@ -142,7 +147,7 @@ export async function matchForPrerender<TEnv = any>(
           if (!isKnown) {
             return {
               segments: [],
-              handles: {},
+              handles: "",
               routeName: matched.routeKey,
               params: matchedParams,
               passthrough: true as const,
@@ -162,7 +167,7 @@ export async function matchForPrerender<TEnv = any>(
           if (err?.name === "Skip") {
             return {
               segments: [],
-              handles: {},
+              handles: "",
               routeName: matched.routeKey,
               params: matchedParams,
               passthrough: true as const,
@@ -261,7 +266,7 @@ export async function matchForPrerender<TEnv = any>(
         if (isPrerenderPassthrough(seg.component)) {
           return {
             segments: [],
-            handles: {},
+            handles: "",
             routeName: matched.routeKey,
             params: matchedParams,
             passthrough: true as const,
@@ -278,16 +283,22 @@ export async function matchForPrerender<TEnv = any>(
 
       // 12. Serialize segments using the cache serializer
       const { serializeSegments } = await import("../cache/segment-codec.js");
+      const { encodeHandles } = await import("../cache/handle-snapshot.js");
       const serializedSegments = await serializeSegments(nonLoaderSegments);
 
-      // 13. Collect handle data per segment (skip segments with no handle data)
-      const handles: Record<string, SegmentHandleData> = {};
+      // 13. Collect handle data per segment (skip segments with no handle data).
+      // Encoded through the Flight codec (not stored raw) so Promise/ReactNode
+      // handle values survive the JSON-serialized build artifact / dev wire —
+      // the same fix the runtime cache uses. Encode happens here, in the RSC
+      // environment where the codec resolves; the node-side sinks only persist.
+      const handlesRecord: Record<string, SegmentHandleData> = {};
       for (const seg of nonLoaderSegments) {
         const segHandles = handleStore.getDataForSegment(seg.id);
         if (Object.keys(segHandles).length > 0) {
-          handles[seg.id] = segHandles;
+          handlesRecord[seg.id] = segHandles;
         }
       }
+      const handles = await encodeHandles(handlesRecord);
 
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
@@ -297,7 +308,7 @@ export async function matchForPrerender<TEnv = any>(
       //     evaluation -- we pre-render all intercepts unconditionally and let
       //     runtime matching decide which to serve.
       let interceptSegments: SerializedSegmentData[] | undefined;
-      let interceptHandles: Record<string, SegmentHandleData> | undefined;
+      let interceptHandles: string | undefined;
 
       const foundIntercepts: {
         intercept: InterceptEntry;
@@ -379,13 +390,20 @@ export async function matchForPrerender<TEnv = any>(
           interceptSegments = await serializeSegments(
             interceptResolvedSegments,
           );
-          interceptHandles = {};
+          const interceptHandlesRecord: Record<string, SegmentHandleData> = {};
           for (const seg of interceptResolvedSegments) {
             const segHandles = handleStore.getDataForSegment(seg.id);
             if (Object.keys(segHandles).length > 0) {
-              interceptHandles[seg.id] = segHandles;
+              interceptHandlesRecord[seg.id] = segHandles;
             }
           }
+          // The intercept artifact serves main + intercept segments together, so
+          // encode the MERGED handle map here (the sinks no longer merge raw
+          // records — they store this pre-encoded string as-is).
+          interceptHandles = await encodeHandles({
+            ...handlesRecord,
+            ...interceptHandlesRecord,
+          });
         }
       }
 
@@ -414,7 +432,7 @@ export async function renderStaticSegment<TEnv = any>(
   routeName?: string,
   buildEnv?: TEnv,
   devMode?: boolean,
-): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null> {
+): Promise<{ encoded: string; handles: string } | null> {
   const syntheticUrl = new URL("http://prerender/");
   const syntheticRequest = new Request(syntheticUrl);
 
@@ -492,10 +510,17 @@ export async function renderStaticSegment<TEnv = any>(
     };
 
     const { serializeSegments } = await import("../cache/segment-codec.js");
+    const { encodeHandleValue } = await import("../cache/handle-snapshot.js");
     const [serialized] = await serializeSegments([segment]);
 
-    // Collect handle data pushed during rendering
-    const handles = handleStore.getDataForSegment(handlerId);
+    // Collect handle data pushed during rendering and Flight-encode it (so
+    // Promise/ReactNode handle values survive the JSON build artifact). "" when
+    // nothing was pushed.
+    const segHandles = handleStore.getDataForSegment(handlerId);
+    const handles =
+      Object.keys(segHandles).length > 0
+        ? await encodeHandleValue(segHandles)
+        : "";
 
     return { encoded: serialized.encoded, handles };
   });

package/src/router/request-classification.ts

@@ -40,6 +40,12 @@ interface VersionMismatchPlan<TEnv = any> {
   reloadUrl: string;
 }
 
+interface AppSwitchReloadPlan {
+  mode: "app-switch";
+  /** Clean target URL (internal _rsc_* params stripped) to navigate to. */
+  reloadUrl: string;
+}
+
 interface ResponseRoutePlan<TEnv = any> {
   mode: "response";
   route: RouteSnapshot<TEnv>;
@@ -86,6 +92,7 @@ interface PartialRenderPlan<TEnv = any> {
 export type RequestPlan<TEnv = any> =
   | RedirectPlan<TEnv>
   | VersionMismatchPlan<TEnv>
+  | AppSwitchReloadPlan
   | ResponseRoutePlan<TEnv>
   | LoaderFetchPlan<TEnv>
   | PeRenderPlan<TEnv>
@@ -94,12 +101,13 @@ export type RequestPlan<TEnv = any> =
   | PartialRenderPlan<TEnv>;
 
 /**
- * Plans that have passed the terminal-check gate (version-mismatch handled)
- * and are ready for execution. Always have a `route` field.
+ * Plans that have passed the terminal-check gate (version-mismatch and
+ * app-switch reloads handled) and are ready for execution. Always have a
+ * `route` field.
  */
 export type ExecutableRequestPlan<TEnv = any> = Exclude<
   RequestPlan<TEnv>,
-  VersionMismatchPlan<TEnv>
+  VersionMismatchPlan<TEnv> | AppSwitchReloadPlan
 >;
 
 /**
@@ -179,6 +187,30 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
+  // App switch — also runs BEFORE route resolution (like version-mismatch
+  // above), and for the same reason: a cross-app SPA navigation must reload
+  // even when the target route does NOT exist in the target app. If we resolved
+  // first, a missing route would throw RouteNotFoundError and the 404 would
+  // render in-place under the SOURCE app's document — violating the invariant
+  // that crossing a host-router app boundary is always a full document load.
+  // A mismatched routerId (_rsc_rid) means the navigation crossed an app
+  // boundary; force a real document navigation. A soft swap can't faithfully
+  // re-establish the target app's document (stylesheets shared across apps are
+  // dropped by React 19's by-href dedup; theme/warmup/prefetch-TTL are
+  // document-lifetime — see browser/app-shell.ts). Only SPA (`_rsc_partial`)
+  // requests need this; a direct full load already IS the document navigation.
+  const clientRouterId = url.searchParams.get("_rsc_rid");
+  if (
+    clientRouterId &&
+    clientRouterId !== deps.routerId &&
+    url.searchParams.has("_rsc_partial")
+  ) {
+    return {
+      mode: "app-switch",
+      reloadUrl: stripInternalParams(url).toString(),
+    };
+  }
+
   // No metricsStore — classification is a lightweight gating step.
   // Route-matching and manifest-loading metrics belong in the match path
   // (createMatchContextForFull/Partial) which runs the authoritative resolution.
@@ -252,12 +284,7 @@ export async function classifyRequest<TEnv = any>(
     return { mode: "pe-render", route: snapshot };
   }
 
-  // App switch: client's routerId doesn't match this router
-  const clientRouterId = url.searchParams.get("_rsc_rid");
-  const isAppSwitch = !!(clientRouterId && clientRouterId !== deps.routerId);
-  const isPartial = url.searchParams.has("_rsc_partial") && !isAppSwitch;
-
-  if (isPartial) {
+  if (url.searchParams.has("_rsc_partial")) {
     return { mode: "partial-render", route: snapshot, negotiated };
   }
 

package/src/router/router-interfaces.ts

@@ -7,10 +7,7 @@ import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
-import type {
-  SerializedSegmentData,
-  SegmentHandleData,
-} from "../cache/types.js";
+import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RangoOptions, RootLayoutProps } from "./router-options.js";
@@ -395,11 +392,13 @@ export interface RangoInternal<
     devMode?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
-    handles: Record<string, SegmentHandleData>;
+    /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. */
+    handles: string;
     routeName: string;
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
-    interceptHandles?: Record<string, SegmentHandleData>;
+    /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact. */
+    interceptHandles?: string;
     passthrough?: true;
   } | null>;
 
@@ -413,7 +412,7 @@ export interface RangoInternal<
     routeName?: string,
     buildEnv?: any,
     devMode?: boolean,
-  ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null>;
+  ): Promise<{ encoded: string; handles: string } | null>;
 
   /**
    * Preview match - returns route middleware without segment resolution.

package/src/router/segment-resolution/static-store.ts

@@ -8,6 +8,7 @@
 import type { ReactNode } from "react";
 import { _getRequestContext } from "../../server/request-context.js";
 import type { StaticStore } from "../../prerender/store.js";
+import type { SegmentHandleData } from "../../cache/types.js";
 
 // Lazy-initialized static store for production Static handler interception.
 // Remains undefined until first check; null means checked but no manifest.
@@ -19,6 +20,9 @@ let _staticStore: StaticStore | null | undefined =
     ? undefined
     : null;
 let _deserializeComponent: ((encoded: string) => Promise<unknown>) | undefined;
+let _decodeHandleValue:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandleValue
+  | undefined;
 
 async function ensureStaticDeps(): Promise<void> {
   if (_staticStore === undefined) {
@@ -29,6 +33,9 @@ async function ensureStaticDeps(): Promise<void> {
     const { deserializeComponent } =
       await import("../../cache/segment-codec.js");
     _deserializeComponent = deserializeComponent;
+    const { decodeHandleValue } =
+      await import("../../cache/handle-snapshot.js");
+    _decodeHandleValue = decodeHandleValue;
   }
 }
 
@@ -53,13 +60,20 @@ export async function tryStaticLookup(
   const entry = await _staticStore.get(handlerId);
   if (!entry) return undefined;
 
-  // Replay handle data captured during build-time rendering.
-  // The data was keyed by handlerId at build time; replay under segmentId
-  // so it matches the segment order used by useHandle on the client.
-  if (entry.handles && Object.keys(entry.handles).length > 0) {
+  // Replay handle data captured during build-time rendering. entry.handles is a
+  // Flight-encoded string ("" when none) — decode before replay so
+  // Promise/ReactNode handle values are revived. The data was keyed by handlerId
+  // at build time; replay under segmentId so it matches the segment order used
+  // by useHandle on the client.
+  if (entry.handles && _decodeHandleValue) {
     const handleStore = _getRequestContext()?._handleStore;
     if (handleStore) {
-      handleStore.replaySegmentData(segmentId, entry.handles);
+      const segHandles = await _decodeHandleValue<SegmentHandleData>(
+        entry.handles,
+      );
+      if (segHandles) {
+        handleStore.replaySegmentData(segmentId, segHandles);
+      }
     }
   }
 

package/src/rsc/handler.ts

@@ -128,6 +128,22 @@ import {
  * });
  * ```
  */
+
+/**
+ * Response that tells the client to do a full document navigation. Shared by
+ * the terminal reload plans (version-mismatch and app-switch): an empty 200
+ * carrying X-RSC-Reload, which the client turns into window.location.href.
+ */
+function createReloadResponse(reloadUrl: string) {
+  return createResponseWithMergedHeaders(null, {
+    status: 200,
+    headers: {
+      "X-RSC-Reload": reloadUrl,
+      "content-type": "text/x-component;charset=utf-8",
+    },
+  });
+}
+
 export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
@@ -642,13 +658,14 @@ export function createRSCHandler<
       console.log(
         `[RSC] Version mismatch: client=${url.searchParams.get("_rsc_v")}, server=${version}. Forcing reload.`,
       );
-      return createResponseWithMergedHeaders(null, {
-        status: 200,
-        headers: {
-          "X-RSC-Reload": plan.reloadUrl,
-          "content-type": "text/x-component;charset=utf-8",
-        },
-      });
+      return createReloadResponse(plan.reloadUrl);
+    }
+
+    if (plan.mode === "app-switch") {
+      // Cross-app SPA navigation crossed a host-router app boundary. Force a
+      // real document navigation so the target app's document is re-established
+      // (stylesheets, theme, warmup, prefetch-TTL). See request-classification.
+      return createReloadResponse(plan.reloadUrl);
     }
 
     // ---- 3. Origin guard (gate for action/loader/PE modes) ----
@@ -1068,7 +1085,12 @@ export function createRSCHandler<
           if (isRscRequest(request, url, isPartial)) {
             return createResponseWithMergedHeaders(rscStream, {
               status: 404,
-              headers: { "content-type": "text/x-component;charset=utf-8" },
+              headers: {
+                "content-type": "text/x-component;charset=utf-8",
+                // Router identity for the client's pre-decode integrity check; a
+                // same-app 404 matches and applies in place. See response-adapter.
+                "X-RSC-Router-Id": router.id,
+              },
             });
           }
 

package/src/rsc/origin-guard.ts

@@ -30,6 +30,8 @@ export const ORIGIN_CHECK_PHASE_BY_MODE: Record<
   response: null,
   redirect: null,
   "version-mismatch": null,
+  // Terminal: handled before the origin guard (emits X-RSC-Reload, no execution).
+  "app-switch": null,
 };
 
 /**

package/src/rsc/response-route-handler.ts

@@ -131,7 +131,26 @@ export async function handleResponseRoute<TEnv>(
 
       // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
       if (preview.responseType === "json") {
-        return createResponseWithMergedHeaders(JSON.stringify(result), {
+        // Runtime guard: the json() return type rejects nested Promises at
+        // compile time, but an `as`-cast or untyped (JS) handler can still slip
+        // one through. JSON.stringify would silently emit {} for it (the
+        // forgotten-await footgun — the RSC pipeline awaits nested promises, this
+        // path does not). Throw a clear error instead of shipping empty data.
+        const body = JSON.stringify(result, (_key, value) => {
+          if (
+            value != null &&
+            typeof (value as { then?: unknown }).then === "function"
+          ) {
+            throw new RouterError(
+              "RESPONSE_NOT_SERIALIZABLE",
+              "A json() response route returned a Promise (likely a forgotten " +
+                "await). Await async values before returning so they serialize, " +
+                "instead of emitting an empty {}.",
+            );
+          }
+          return value;
+        });
+        return createResponseWithMergedHeaders(body, {
           status: 200,
           headers: { "content-type": "application/json;charset=utf-8" },
         });

package/src/rsc/rsc-rendering.ts

@@ -83,6 +83,11 @@ export async function handleRscRendering<TEnv>(
       payload = {
         metadata: {
           pathname: url.pathname,
+          // routerId is serialized on every payload (including within-session
+          // ones) so the frontend can read the current app/router identity. It
+          // always equals the current app's id: a cross-app navigation is
+          // intercepted server-side (X-RSC-Reload) and never delivers a
+          // different-router payload to the client.
           routerId: ctx.router.id,
           segments: result.segments,
           matched: result.matched,
@@ -180,6 +185,11 @@ export async function handleRscRendering<TEnv>(
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+      // Router identity, so the client can verify pre-decode (before importing
+      // chunks) that this content payload belongs to its app and refuse a
+      // foreign one (cache/proxy/bug). Control-only reload/redirect responses
+      // are deliberately NOT stamped. See browser/response-adapter.ts.
+      "X-RSC-Router-Id": ctx.router.id,
     };
     // Tell the client's prefetch cache to scope this response to its source
     // URL (instead of the default source-agnostic wildcard). Intercept