@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/router/prerender-match.ts

@@ -1,24 +1,27 @@
 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 { PartialPrerenderProps } from "../urls/pattern-types.js";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -31,7 +34,12 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  /** Owning router id; scopes bake-time root-scope/search-schema lookups the
+   *  same way reqCtx._routerId does at runtime (issue #762). */
+  routerId?: string;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   buildRouterContext: () => RouterContext<TEnv>;
   mergedRouteMap: Record<string, string>;
   resolveAllSegments: (
@@ -40,7 +48,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 +67,27 @@ 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;
+  /**
+   * The matched route entry's `ppr` path option, surfaced so the build
+   * collection can flag Prerender+ppr routes as build-time shell candidates
+   * (issue #699 producer B). Runtime-only today; the build otherwise never
+   * sees the option (it lives on EntryData, not the trie).
+   */
+  ppr?: boolean | PartialPrerenderProps;
 } | 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 +97,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(
@@ -126,7 +157,7 @@ export async function matchForPrerender<TEnv = any>(
             get env() {
               if (buildEnv !== undefined) return buildEnv;
               throw new Error(
-                "[rsc-router] ctx.env is not available during dev-mode getParams(). " +
+                "[rango] ctx.env is not available during dev-mode getParams(). " +
                   "Configure buildEnv in your rango() plugin options to enable build-time env access.",
               );
             },
@@ -140,19 +171,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 +182,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;
         }
@@ -193,6 +209,11 @@ export async function matchForPrerender<TEnv = any>(
       pathname,
       searchParams: new URLSearchParams(),
       _variables: variables,
+      build: true,
+      // Inert here: the prerender-collect / static-render pass has no live
+      // PPR-shell decision to gate; dynamic() reaches the shell axis only on a
+      // live request or a shell capture.
+      dynamic: () => {},
       get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
       set: ((keyOrVar: any, value: any) => {
         contextSet(variables, keyOrVar, value);
@@ -206,11 +227,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: [],
@@ -223,8 +247,13 @@ export async function matchForPrerender<TEnv = any>(
         deps.mergedRouteMap,
         matched.routeKey,
         matchedParams,
-        matched.routeKey ? isRouteRootScoped(matched.routeKey) : undefined,
+        matched.routeKey
+          ? isRouteRootScoped(matched.routeKey, deps.routerId)
+          : undefined,
       ),
+      // Scope the bake context's own lookups (createPrerenderContext reads it
+      // through the request ALS) per router as well.
+      _routerId: deps.routerId,
     };
 
     return runWithRequestContext(minimalRequestContext, async () => {
@@ -253,20 +282,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,26 +305,46 @@ 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;
 
+      // Surface the matched route entry's ppr option for the build collection
+      // (leaf-first: the deepest type:"route" entry in the ancestor chain is
+      // the matched page route; ancestors are layouts/includes).
+      let routePpr: boolean | PartialPrerenderProps | undefined;
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i]!;
+        if (e.type === "route") {
+          routePpr = e.ppr;
+          break;
+        }
+      }
+
       // 14. Resolve intercept segments for this route (if any ancestor defines
       //     an intercept targeting this route). At build time we skip when()
       //     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 +352,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 +370,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 +408,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 +428,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,
+          });
         }
       }
 
@@ -396,6 +453,7 @@ export async function matchForPrerender<TEnv = any>(
         params: matchedParams,
         interceptSegments,
         interceptHandles,
+        ppr: routePpr,
       };
     });
   });
@@ -414,7 +472,9 @@ export async function renderStaticSegment<TEnv = any>(
   routeName?: string,
   buildEnv?: TEnv,
   devMode?: boolean,
-): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null> {
+  routerId?: string,
+  rootScoped?: boolean,
+): Promise<{ encoded: string; handles: string } | null> {
   const syntheticUrl = new URL("http://prerender/");
   const syntheticRequest = new Request(syntheticUrl);
 
@@ -431,6 +491,8 @@ export async function renderStaticSegment<TEnv = any>(
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
     _variables: {},
+    build: true,
+    dynamic: () => {},
     get: () => undefined as any,
     set: () => {},
     params: {},
@@ -442,11 +504,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: [],
@@ -459,8 +524,15 @@ export async function renderStaticSegment<TEnv = any>(
       mergedRouteMap,
       routeName,
       {},
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      // Def-stamped value first: the collector passes the mount-time
+      // root-scope captured on the Static definition (stampStaticDefScope),
+      // which needs no registry lookup and survives name-prefix arguments.
+      rootScoped ??
+        (routeName ? isRouteRootScoped(routeName, routerId) : undefined),
     ),
+    // Scope the bake context's own lookups (createStaticContext reads it
+    // through the request ALS) per router as well.
+    _routerId: routerId,
   };
 
   return runWithRequestContext(minimalRequestContext, async () => {
@@ -479,23 +551,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>;
 }
 
 /**
@@ -67,9 +69,11 @@ export async function previewMatch<TEnv = any>(
             responseType: negotiation.responseType,
             handler: negotiation.handler,
             params: matched.params,
-            negotiated: true,
             manifestEntry: negotiation.manifestEntry,
             routeKey: matched.routeKey,
+            // omitted unless a variant negotiated, preserving the prior public
+            // shape (absent for plain response routes, not negotiated:false)
+            ...(negotiation.negotiated ? { negotiated: true } : {}),
           };
         }