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

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

package/src/rsc/server-action.ts

@@ -184,6 +184,8 @@ export async function executeServerAction<TEnv>(
       const payload: RscPayload = {
         metadata: {
           pathname: url.pathname,
+          // routerId exposed for the frontend (current app identity); see
+          // rsc-rendering.ts partial branch.
           routerId: ctx.router.id,
           segments: errorResult.segments,
           isPartial: true,
@@ -211,7 +213,12 @@ export async function executeServerAction<TEnv>(
 
       return createResponseWithMergedHeaders(rscStream, {
         status: actionStatus,
-        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 (the
+          // action apply path has no post-decode guard). See response-adapter.
+          "X-RSC-Router-Id": ctx.router.id,
+        },
       });
     }
   }
@@ -296,6 +303,8 @@ export async function revalidateAfterAction<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      // routerId exposed for the frontend (current app identity); see
+      // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
       segments: matchResult.segments,
       isPartial: true,
@@ -331,6 +340,11 @@ export async function revalidateAfterAction<TEnv>(
 
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,
-    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 (the action
+      // apply path has no post-decode guard). See response-adapter.
+      "X-RSC-Router-Id": ctx.router.id,
+    },
   });
 }

package/src/urls/path-helper-types.ts

@@ -114,6 +114,12 @@ export type ResponsePathFn<TEnv> = <
  * Path function for JSON response routes (path.json()).
  * Handler can return plain JSON-serializable values or Response.
  * TData is inferred from the handler's return type (excluding Response/Promise wrappers).
+ *
+ * Note: a nested Promise in the return (a forgotten await) is caught at runtime
+ * by response-route-handler.ts (it throws instead of silently emitting `{}`). A
+ * compile-time JsonValue constraint was evaluated and rejected — it breaks
+ * interface-typed returns (interfaces lack the index signature JsonValue
+ * requires) and preserves literal types in the inferred response shape.
  */
 export type JsonResponsePathFn<TEnv> = <
   const TPattern extends string,

package/src/vite/discovery/prerender-collection.ts

@@ -282,10 +282,9 @@ export async function expandPrerenderRoutes(
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...(result.interceptHandles || {}),
-                },
+                // interceptHandles is the pre-encoded MERGED (main + intercept)
+                // handle string (the producer merged before encoding).
+                handles: result.interceptHandles ?? "",
               });
               manifestEntries[interceptKey] = stageBuildAssetModule(
                 state.projectRoot,
@@ -420,7 +419,8 @@ export async function renderStaticHandlers(
             !state.isBuildMode,
           );
           if (result) {
-            const hasHandles = Object.keys(result.handles).length > 0;
+            // result.handles is the pre-encoded handle string ("" when none).
+            const hasHandles = result.handles !== "";
             const exportValue = hasHandles
               ? JSON.stringify(result)
               : JSON.stringify(result.encoded);

package/src/vite/router-discovery.ts

@@ -893,10 +893,9 @@ export function createRouterDiscoveryPlugin(
             if (wantIntercept && result.interceptSegments?.length) {
               payload = {
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...(result.interceptHandles || {}),
-                },
+                // Pre-encoded MERGED handle string from the producer (handles are
+                // Flight-encoded so Promise/ReactNode values survive the wire).
+                handles: result.interceptHandles ?? "",
               };
             } else {
               payload = { segments: result.segments, handles: result.handles };