@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/router/prerender-match.ts

@@ -1,22 +1,24 @@
 import { type ReactNode } from "react";
 import { createHandleStore } from "../server/handle-store.js";
+import { resolveSegmentHandleValues } from "../handles/deferred-resolution.js";
 import { getRequestContext } from "../server/request-context.js";
 import {
   runWithRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
-import { contextGet, contextSet } from "../context-var.js";
+import { contextGet, contextSet, hasContextVars } from "../context-var.js";
 import {
   createPrerenderContext,
   createStaticContext,
   createReverseFunction,
 } from "./handler-context.js";
-import { isPrerenderPassthrough } from "../prerender.js";
+import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { loadManifest } from "./manifest.js";
 import { traverseBack } from "./pattern-matching.js";
 import type { RouterContext } from "./router-context.js";
+import type { ResolveSegmentOptions } from "./segment-resolution.js";
 import { runWithRouterContext } from "./router-context.js";
 import type { EntryData, InterceptEntry } from "../server/context";
 import type {
@@ -31,7 +33,9 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   buildRouterContext: () => RouterContext<TEnv>;
   mergedRouteMap: Record<string, string>;
   resolveAllSegments: (
@@ -40,7 +44,7 @@ export interface PrerenderMatchDeps<TEnv = any> {
     params: Record<string, string>,
     context: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
-    options?: { skipLoaders?: boolean },
+    options?: ResolveSegmentOptions,
   ) => Promise<ResolvedSegment[]>;
 }
 
@@ -59,15 +63,20 @@ 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
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (!matched) return null;
 
   // Use params from trie match if available, fall back to provided params
@@ -77,6 +86,17 @@ export async function matchForPrerender<TEnv = any>(
   // Build RouterContext for loadManifest/traverseBack
   const routerCtx = deps.buildRouterContext();
 
+  // Passthrough sentinel result: an unknown-param Passthrough route falls
+  // through to the live handler at runtime, so no artifact is baked. A fresh
+  // object is returned per call (no site mutates or identity-compares it).
+  const passthroughResult = () => ({
+    segments: [],
+    handles: "",
+    routeName: matched.routeKey,
+    params: matchedParams,
+    passthrough: true as const,
+  });
+
   return runWithRouterContext(routerCtx, async () => {
     // 2. Load the manifest entry tree
     const manifestEntry = await loadManifest(
@@ -140,19 +160,10 @@ export async function matchForPrerender<TEnv = any>(
             );
           });
           if (!isKnown) {
-            return {
-              segments: [],
-              handles: {},
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           // Preserve vars set by getParams() for the render context
-          if (
-            Object.keys(probeBuildVars).length > 0 ||
-            Object.getOwnPropertySymbols(probeBuildVars).length > 0
-          ) {
+          if (hasContextVars(probeBuildVars)) {
             devProbeBuildVars = probeBuildVars;
           }
         } catch (err: any) {
@@ -160,13 +171,7 @@ export async function matchForPrerender<TEnv = any>(
           // Skip errors are intentional — treat as passthrough.
           // All other errors propagate so dev surfaces them.
           if (err?.name === "Skip") {
-            return {
-              segments: [],
-              handles: {},
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           throw err;
         }
@@ -206,11 +211,14 @@ export async function matchForPrerender<TEnv = any>(
       header: () => {},
       setStatus: () => {},
       _setStatus: () => {},
+      _rotateStateCookie: () => {},
+      _setKeepCacheDirective: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
       method: "GET",
       _handleStore: handleStore,
+      _requestTags: new Set<string>(),
       waitUntil: () => {},
       onResponse: () => {},
       _onResponseCallbacks: [],
@@ -253,20 +261,18 @@ export async function matchForPrerender<TEnv = any>(
         matchedParams,
         buildCtx,
         loaderPromises,
-        { skipLoaders: true },
+        // throwOnError: a render failure (or `throw new Skip()`) must reach the
+        // build/dev caller, not be baked into a frozen error page (issue #587).
+        { skipLoaders: true, throwOnError: true },
       );
 
-      // 9. Detect passthrough sentinel: handler returned ctx.passthrough()
-      for (const seg of allSegments) {
-        if (isPrerenderPassthrough(seg.component)) {
-          return {
-            segments: [],
-            handles: {},
-            routeName: matched.routeKey,
-            params: matchedParams,
-            passthrough: true as const,
-          };
-        }
+      // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
+      // When the route declares loading(), the handler result is deferred so the
+      // component is a thenable resolving to the sentinel — detectPrerenderPassthrough
+      // resolves thenables before testing (a sync check would miss it and bake a
+      // corrupt artifact).
+      if (await detectPrerenderPassthrough(allSegments)) {
+        return passthroughResult();
       }
 
       // 10. Filter out any loader segments (belt-and-suspenders)
@@ -278,16 +284,24 @@ 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;
+          // Resolve deferred values before encoding so the baked artifact holds
+          // resolved data (prerender = build-time cache).
+          handlesRecord[seg.id] = await resolveSegmentHandleValues(segHandles);
         }
       }
+      const handles = await encodeHandles(handlesRecord);
 
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
@@ -297,7 +311,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;
@@ -305,24 +319,14 @@ export async function matchForPrerender<TEnv = any>(
       }[] = [];
       let current: EntryData | null = manifestEntry;
       while (current) {
-        if (current.intercept && current.intercept.length > 0) {
-          for (const ic of current.intercept) {
+        // Flatten the entry and its sibling layouts into one source list, the
+        // same traversal findInterceptForRoute uses; the build keeps ALL matches
+        // (not just the innermost) and skips when(). intercept/layout are
+        // non-optional arrays, so empty ones are a no-op here.
+        for (const source of [current, ...current.layout]) {
+          for (const ic of source.intercept) {
             if (ic.routeName === matched.routeKey) {
-              foundIntercepts.push({ intercept: ic, entry: current });
-            }
-          }
-        }
-        if (current.layout && current.layout.length > 0) {
-          for (const siblingLayout of current.layout) {
-            if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-              for (const ic of siblingLayout.intercept) {
-                if (ic.routeName === matched.routeKey) {
-                  foundIntercepts.push({
-                    intercept: ic,
-                    entry: siblingLayout,
-                  });
-                }
-              }
+              foundIntercepts.push({ intercept: ic, entry: source });
             }
           }
         }
@@ -333,6 +337,18 @@ export async function matchForPrerender<TEnv = any>(
         const interceptResolvedSegments: typeof nonLoaderSegments = [];
 
         for (const { intercept, entry: parentEntry } of foundIntercepts) {
+          // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
+          // resolveAllSegments pass left it on the route's segment id, so pin it
+          // to THIS intercept's slot id before resolving the handler/layout --
+          // otherwise the intercept's ctx.use() handle pushes land in the wrong
+          // bucket and getDataForSegment(seg.id) below drops them from the baked
+          // artifact. Re-pinned per iteration so multiple intercepts targeting
+          // the same route each get their own id (mirrors fresh.ts parallel-slot
+          // pinning).
+          const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+          (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+            interceptSegmentId;
+
           // Resolve handler
           const handlerRaw =
             typeof intercept.handler === "function"
@@ -359,7 +375,7 @@ export async function matchForPrerender<TEnv = any>(
           }
 
           interceptResolvedSegments.push({
-            id: `${parentEntry.shortCode}.${intercept.slotName}`,
+            id: interceptSegmentId,
             namespace: `intercept:${intercept.routeName}`,
             type: "parallel" as const,
             index: 0,
@@ -379,13 +395,21 @@ 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] =
+                await resolveSegmentHandleValues(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 +438,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);
 
@@ -442,11 +466,14 @@ export async function renderStaticSegment<TEnv = any>(
     header: () => {},
     setStatus: () => {},
     _setStatus: () => {},
+    _rotateStateCookie: () => {},
+    _setKeepCacheDirective: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,
     method: "GET",
     _handleStore: handleStore,
+    _requestTags: new Set<string>(),
     waitUntil: () => {},
     onResponse: () => {},
     _onResponseCallbacks: [],
@@ -479,23 +506,41 @@ export async function renderStaticSegment<TEnv = any>(
     setupBuildUse(buildCtx);
 
     const raw = await handler(buildCtx);
-    const component = raw?.type ? raw : raw;
+
+    // Static handlers must return a ReactNode. A returned Response (e.g. an
+    // accidental redirect()) would otherwise be serialized as a corrupt build
+    // artifact; fail loudly instead. The fresh/revalidation paths route handler
+    // results through handleHandlerResult, which throws Responses; the static
+    // build path bypasses that, so guard here.
+    if (raw instanceof Response) {
+      throw new TypeError(
+        `Static handler "${routeName}" returned a Response. Static handlers must return a ReactNode; ` +
+          `Responses (redirects, file responses) are not supported during static pre-rendering.`,
+      );
+    }
 
     const segment: ResolvedSegment = {
       id: handlerId,
       namespace: handlerId,
       type: "layout",
       index: 0,
-      component,
+      component: raw,
       params: {},
       belongsToRoute: false,
     };
 
     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(await resolveSegmentHandleValues(segHandles))
+        : "";
 
     return { encoded: serialized.encoded, handles };
   });

package/src/router/preview-match.ts

@@ -6,7 +6,9 @@ import type { MiddlewareFn } from "./middleware.js";
 import { resolveRoute } from "./route-snapshot.js";
 
 export interface PreviewMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
 }
 
 /**

package/src/router/request-classification.ts

@@ -23,10 +23,6 @@ import { negotiateRoute } from "./content-negotiation.js";
 import { stripInternalParams } from "./handler-context.js";
 import { resolveRoute, type RouteSnapshot } from "./route-snapshot.js";
 
-// ---------------------------------------------------------------------------
-// RequestPlan — discriminated union
-// ---------------------------------------------------------------------------
-
 interface RedirectPlan<TEnv = any> {
   mode: "redirect";
   route: RouteSnapshot<TEnv>;
@@ -40,6 +36,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 +88,7 @@ interface PartialRenderPlan<TEnv = any> {
 export type RequestPlan<TEnv = any> =
   | RedirectPlan<TEnv>
   | VersionMismatchPlan<TEnv>
+  | AppSwitchReloadPlan
   | ResponseRoutePlan<TEnv>
   | LoaderFetchPlan<TEnv>
   | PeRenderPlan<TEnv>
@@ -94,12 +97,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
 >;
 
 /**
@@ -116,12 +120,10 @@ export type {
   PartialRenderPlan,
 };
 
-// ---------------------------------------------------------------------------
-// classifyRequest — the single authoritative classification step
-// ---------------------------------------------------------------------------
-
 export interface ClassifyRequestDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   routerVersion: string;
   routerId: string;
 }
@@ -148,16 +150,30 @@ export async function classifyRequest<TEnv = any>(
   const pathname = url.pathname;
   const isAction =
     request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+  const isLoaderFetch = url.searchParams.has("_rsc_loader");
+  const isPartialReq = url.searchParams.has("_rsc_partial");
+  const contentType = request.headers.get("content-type") || "";
+  const isFormSubmission =
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded");
+  const isPeRender = request.method === "POST" && !isAction && isFormSubmission;
+
+  // A plain document request (full-render mode) is the only mode that renders
+  // through match() with isSSR:true; every other mode (action, loader, PE,
+  // partial) renders — if at all — through the non-SSR matchPartial() path.
+  // Resolve the manifest under the flag the eventual render will use so
+  // createMatchContextForFull can reuse this snapshot instead of re-resolving.
+  // Response routes ignore isSSR entirely (they short-circuit before match),
+  // so the flag is moot for them. Mode detection below reuses these booleans.
+  const willFullRender =
+    !isAction && !isLoaderFetch && !isPartialReq && !isPeRender;
 
-  // Version mismatch — runs BEFORE route resolution so stale clients
-  // requesting removed routes get a reload, not a 404.
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
     deps.routerVersion &&
     clientVersion &&
     clientVersion !== deps.routerVersion
   ) {
-    // Strip internal _rsc_* params so the browser reloads to a clean URL
     let reloadUrl = stripInternalParams(url).toString();
     if (isAction) {
       const referer = request.headers.get("referer");
@@ -167,9 +183,7 @@ export async function classifyRequest<TEnv = any>(
           if (refererUrl.origin === url.origin) {
             reloadUrl = referer;
           }
-        } catch {
-          // Malformed referer, fall back to stripped url
-        }
+        } catch {}
       }
     }
 
@@ -179,12 +193,22 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  // 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.
+  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(),
+    };
+  }
+
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,
+    isSSR: willFullRender,
   });
 
   if (!result) {
@@ -193,7 +217,6 @@ export async function classifyRequest<TEnv = any>(
     });
   }
 
-  // Redirect
   if (result.type === "redirect") {
     const snapshot: RouteSnapshot<TEnv> = {
       matched: result as any,
@@ -215,7 +238,6 @@ export async function classifyRequest<TEnv = any>(
 
   const snapshot = result.snapshot;
 
-  // Response route — non-RSC short-circuit (JSON, streaming, etc.)
   const responseResult = await classifyResponseRoute(
     request,
     pathname,
@@ -225,10 +247,8 @@ export async function classifyRequest<TEnv = any>(
     return responseResult;
   }
 
-  // Mode detection from request signals
   const actionId =
     request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
-  const isLoaderFetch = url.searchParams.has("_rsc_loader");
 
   const hasVariants =
     snapshot.matched.negotiateVariants &&
@@ -243,31 +263,17 @@ export async function classifyRequest<TEnv = any>(
     return { mode: "loader", route: snapshot };
   }
 
-  // PE detection: POST with form content-type, but not a server action
-  const contentType = request.headers.get("content-type") || "";
-  const isFormSubmission =
-    contentType.includes("multipart/form-data") ||
-    contentType.includes("application/x-www-form-urlencoded");
-  if (request.method === "POST" && !isAction && isFormSubmission) {
+  if (isPeRender) {
     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 (isPartialReq) {
     return { mode: "partial-render", route: snapshot, negotiated };
   }
 
   return { mode: "full-render", route: snapshot, negotiated };
 }
 
-// ---------------------------------------------------------------------------
-// Content negotiation for response routes
-// ---------------------------------------------------------------------------
-
 /**
  * Check if the route is a response route and perform content negotiation
  * if negotiate variants exist. Returns a ResponseRoutePlan if the route
@@ -278,7 +284,6 @@ async function classifyResponseRoute<TEnv>(
   pathname: string,
   snapshot: RouteSnapshot<TEnv>,
 ): Promise<ResponseRoutePlan<TEnv> | null> {
-  // negotiateRoute returns the response plan (variant or plain) or null for RSC.
   const negotiation = await negotiateRoute(request, pathname, snapshot);
   return negotiation
     ? { mode: "response", route: snapshot, ...negotiation }