@rangojs/router 0.26.6 → 0.28.0

package/src/router/prerender-match.ts

@@ -17,18 +17,15 @@ import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { findInOrphans } from "./error-handling.js";
 import { interceptSlotId } from "./intercept-resolution.js";
+import { localRouteName } from "../route-name.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 { freshPassInput } from "./segment-resolution/resolution-pass.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,
-  ResolvedSegment,
-} from "../types";
+import type { InternalHandlerContext, ResolvedSegment } from "../types";
 import type {
   SerializedSegmentData,
   SegmentHandleData,
@@ -39,6 +36,21 @@ import type { OnDemandRouteConfig } from "../prerender/on-demand.js";
 import { isPrerenderPersonalizationError } from "../prerender/producer-guard.js";
 import { isDataNotFoundError } from "../errors.js";
 
+/**
+ * An intercept a navigation can select over the route that the build does
+ * not bake: its HIT misses (selectInterceptVariant) and it renders live,
+ * with the request instead of BuildContext.
+ * - `same-slot`: another intercept on its layout fills the same slot.
+ * - `handler-response` / `layout-response`: its handler or layout returned a
+ *   Response for this URL.
+ * - `local-name`: it targets the route's localRouteName, which the build
+ *   never bakes.
+ */
+export interface LiveIntercept {
+  slot: string;
+  reason: "same-slot" | "handler-response" | "layout-response" | "local-name";
+}
+
 export interface PrerenderMatchDeps<TEnv = any> {
   /** Owning router id; scopes bake-time root-scope/search-schema lookups the
    *  same way reqCtx._routerId does at runtime (issue #762). */
@@ -55,14 +67,7 @@ export interface PrerenderMatchDeps<TEnv = any> {
   ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   buildRouterContext: () => RouterContext<TEnv>;
   mergedRouteMap: Record<string, string>;
-  resolveAllSegments: (
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>,
-    options?: ResolveSegmentOptions,
-  ) => Promise<ResolvedSegment[]>;
+  resolveAllSegments: RouterContext<TEnv>["resolveAllSegments"];
 }
 
 /**
@@ -95,9 +100,13 @@ export async function matchForPrerender<TEnv = any>(
   routeName: string;
   params: Record<string, string>;
   interceptSegments?: SerializedSegmentData[];
-  /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact;
-   *  the sinks store it as-is (no longer merge raw records). */
+  /** RSC-encoded handle map for the intercept artifact: the intercept's
+   *  pushes and those of the main segments the intercepted route does not
+   *  own; the sinks store it as-is. */
   interceptHandles?: string;
+  /** The intercepts the intercept variant does not hold, for the build's
+   *  warning (warnLiveIntercepts). */
+  liveIntercepts?: LiveIntercept[];
   passthrough?: true;
   /** On-demand only: the render hit `notFound()` and nothing else failed. */
   notFound?: true;
@@ -340,16 +349,16 @@ export async function matchForPrerender<TEnv = any>(
         setupBuildUse(buildCtx);
 
         // 8. Resolve all segments with skipLoaders
-        const loaderPromises = new Map<string, Promise<any>>();
-        const allSegments = await deps.resolveAllSegments(
+        const { segments: allSegments } = await deps.resolveAllSegments(
+          freshPassInput(buildCtx, matched.routeKey, matchedParams, {
+            skipLoaders: true,
+            // A render failure (or `throw new Skip()`) must reach the
+            // build/dev caller, not be baked into a frozen error page
+            // (issue #587).
+            throwOnError: true,
+          }),
           entries,
-          matched.routeKey,
-          matchedParams,
-          buildCtx,
-          loaderPromises,
-          // 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 },
+          { pathname: buildCtx.pathname },
         );
 
         // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
@@ -375,7 +384,7 @@ export async function matchForPrerender<TEnv = any>(
         // the tree) as an error row and completes normally. Rethrown below like
         // a handler throw, so the caller's policy decides instead of baking the
         // error (#914). On-demand refresh: a deep async child calling
-        // cookies()/headers() throws here, not in resolveAllSegments; a
+        // cookies()/headers() throws here, not in segment resolution; a
         // personalization error is thrown in preference to any other so the
         // trigger maps it to skipped-personalized and keeps the old entry.
         const { serializeSegments } = await import("../cache/segment-codec.js");
@@ -453,18 +462,25 @@ export async function matchForPrerender<TEnv = any>(
           intercept: InterceptEntry;
           entry: EntryData;
         }[] = [];
-        // The entry, then its orphans (nested ones included): the same traversal
-        // findInterceptForRoute uses; the build keeps ALL matches (not just the
-        // innermost) and skips when().
+        const localNamed: InterceptEntry[] = [];
+        const localName = localRouteName(matched.routeKey);
+        // From the route's parent up, each entry then its orphans (nested ones
+        // included): the walk findInterceptForRoute makes at runtime, so an
+        // intercept in the route's own layouts, which it never selects, is not
+        // baked. The build keeps ALL matches (not just the innermost) and skips
+        // when(); a HIT serves the one the match selected
+        // (selectInterceptVariant, prerender/store.ts).
         const collect = (source: EntryData): undefined => {
           for (const ic of source.intercept) {
             if (ic.routeName === matched.routeKey) {
               foundIntercepts.push({ intercept: ic, entry: source });
+            } else if (ic.routeName === localName) {
+              localNamed.push(ic);
             }
           }
           return undefined;
         };
-        let current: EntryData | null = manifestEntry;
+        let current: EntryData | null = manifestEntry.parent;
         let prev: EntryData | null = null;
         while (current) {
           collect(current);
@@ -472,22 +488,50 @@ export async function matchForPrerender<TEnv = any>(
           prev = current;
           current = current.parent;
         }
+        // Two intercepts that fill one slot share its segment id, so a HIT
+        // could not tell which one the variant holds: neither is baked, and
+        // both render live.
+        const slotIds = foundIntercepts.map(({ intercept, entry }) =>
+          interceptSlotId(entry, intercept),
+        );
+        const bakedIntercepts = foundIntercepts.filter(
+          (_, i) =>
+            slotIds.indexOf(slotIds[i]!) === slotIds.lastIndexOf(slotIds[i]!),
+        );
+
+        const liveIntercepts: LiveIntercept[] = [];
+        const live = (
+          intercept: InterceptEntry,
+          reason: LiveIntercept["reason"],
+        ): void => {
+          liveIntercepts.push({ slot: intercept.slotName, reason });
+        };
+        for (const found of foundIntercepts) {
+          if (!bakedIntercepts.includes(found)) {
+            live(found.intercept, "same-slot");
+          }
+        }
+        // The match tries the local name only when no intercept for the full
+        // name applies, and one without when() always applies.
+        if (foundIntercepts.every(({ intercept }) => intercept.when?.length)) {
+          for (const intercept of localNamed) live(intercept, "local-name");
+        }
 
         // V1 writes only the main variant. Do not execute intercept producers
         // whose output would be discarded (and whose personalization/errors
         // must not block an otherwise valid main refresh).
-        if (!onDemand && foundIntercepts.length > 0) {
+        if (!onDemand && bakedIntercepts.length > 0) {
           const interceptResolvedSegments: typeof nonLoaderSegments = [];
 
-          for (const { intercept, entry: parentEntry } of foundIntercepts) {
+          for (const { intercept, entry: parentEntry } of bakedIntercepts) {
             // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
-            // resolveAllSegments pass left it on the route's segment id, so pin it
+            // segment 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).
+            // the same route each get their own id (mirrors the walker's
+            // parallel-slot pinning, revalidation.ts).
             const interceptSegmentId = interceptSlotId(parentEntry, intercept);
             (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
               interceptSegmentId;
@@ -500,7 +544,7 @@ export async function matchForPrerender<TEnv = any>(
             const handlerResolved =
               handlerRaw instanceof Promise ? await handlerRaw : handlerRaw;
             if (handlerResolved instanceof Response) {
-              // Handler returned a redirect/response -- skip this intercept
+              live(intercept, "handler-response");
               continue;
             }
             const component: ReactNode = handlerResolved;
@@ -510,7 +554,10 @@ export async function matchForPrerender<TEnv = any>(
             if (intercept.layout) {
               if (typeof intercept.layout === "function") {
                 const layoutResult = await intercept.layout(buildCtx);
-                if (layoutResult instanceof Response) continue;
+                if (layoutResult instanceof Response) {
+                  live(intercept, "layout-response");
+                  continue;
+                }
                 layoutElement = layoutResult;
               } else {
                 layoutElement = intercept.layout;
@@ -548,14 +595,22 @@ export async function matchForPrerender<TEnv = any>(
                   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).
+            // The handle map of exactly the segments the sinks store for the
+            // intercept artifact; they store this string as-is.
+            const { interceptVariantSegments } =
+              await import("../prerender/store.js");
+            const variantHandlesRecord: Record<string, SegmentHandleData> = {};
+            for (const { metadata } of interceptVariantSegments(
+              serializedSegments,
+              interceptSegments,
+            )) {
+              const data =
+                handlesRecord[metadata.id] ??
+                interceptHandlesRecord[metadata.id];
+              if (data) variantHandlesRecord[metadata.id] = data;
+            }
             interceptHandles = await encodeHandles(
-              {
-                ...handlesRecord,
-                ...interceptHandlesRecord,
-              },
+              variantHandlesRecord,
               onFlightError,
             );
           }
@@ -570,6 +625,7 @@ export async function matchForPrerender<TEnv = any>(
           params: matchedParams,
           interceptSegments,
           interceptHandles,
+          liveIntercepts,
           onDemandConfig,
           ppr: routePpr,
         };

package/src/router/preview-match.ts

@@ -1,6 +1,5 @@
 import { negotiateRoute } from "./content-negotiation.js";
 import { runWithRouterLogContext, withRouterLogScope } from "./logging.js";
-import type { EntryData } from "../server/context";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { MiddlewareFn } from "./middleware.js";
 import { resolveRoute } from "./route-snapshot.js";
@@ -12,8 +11,8 @@ export interface PreviewMatchDeps<TEnv = any> {
 }
 
 /**
- * Preview match - returns route middleware without segment resolution.
- * Also returns responseType and handler for response routes (non-RSC short-circuit).
+ * Preview match - returns the route, its params and route middleware without
+ * segment resolution (a content-negotiated variant's, when one wins).
  */
 export async function previewMatch<TEnv = any>(
   request: Request,
@@ -24,11 +23,7 @@ export async function previewMatch<TEnv = any>(
     handler: MiddlewareFn;
     params: Record<string, string>;
   }>;
-  responseType?: string;
-  handler?: Function;
   params?: Record<string, string>;
-  negotiated?: boolean;
-  manifestEntry?: EntryData;
   routeKey?: string;
 } | null> {
   return runWithRouterLogContext(
@@ -56,46 +51,16 @@ export async function previewMatch<TEnv = any>(
         }
 
         const snapshot = result.snapshot;
-        const { matched, manifestEntry, routeMiddleware, responseType } =
-          snapshot;
-
+        const { matched } = snapshot;
+        // A winning response variant brings its own route middleware.
         const negotiation = await negotiateRoute(request, pathname, snapshot);
-        if (negotiation) {
-          return {
-            routeMiddleware:
-              negotiation.routeMiddleware.length > 0
-                ? negotiation.routeMiddleware
-                : undefined,
-            responseType: negotiation.responseType,
-            handler: negotiation.handler,
-            params: matched.params,
-            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 } : {}),
-          };
-        }
-
-        // No negotiation or RSC won — return default route info
-        const hasVariants =
-          matched.negotiateVariants && matched.negotiateVariants.length > 0;
+        const routeMiddleware =
+          negotiation?.routeMiddleware ?? snapshot.routeMiddleware;
         return {
           routeMiddleware:
             routeMiddleware.length > 0 ? routeMiddleware : undefined,
           params: matched.params,
           routeKey: matched.routeKey,
-          ...(responseType
-            ? {
-                responseType,
-                handler:
-                  manifestEntry.type === "route"
-                    ? manifestEntry.handler
-                    : undefined,
-                manifestEntry,
-              }
-            : {}),
-          ...(hasVariants ? { negotiated: true } : {}),
         };
       }),
   );

package/src/router/request-classification.ts

@@ -22,6 +22,7 @@ import type { CollectedMiddleware } from "./middleware-types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import { negotiateRoute } from "./content-negotiation.js";
 import { stripInternalParams } from "./handler-context.js";
+import { WIRE } from "../wire-params.js";
 import { resolveRoute, type RouteSnapshot } from "./route-snapshot.js";
 
 interface RedirectPlan<TEnv = any> {
@@ -74,6 +75,11 @@ interface FullRenderPlan<TEnv = any> {
   mode: "full-render";
   route: RouteSnapshot<TEnv>;
   negotiated: boolean;
+  /**
+   * No route matched: the render path renders the 404 (match() re-throws
+   * RouteNotFoundError). Set by rsc/request-stages.ts classify.
+   */
+  unmatched?: true;
 }
 
 interface PartialRenderPlan<TEnv = any> {
@@ -151,9 +157,9 @@ export async function classifyRequest<TEnv = any>(
   const pathname = url.pathname;
   const isAction =
     requestHeaders(request).has("rsc-action") ||
-    url.searchParams.has("_rsc_action");
-  const isLoaderFetch = url.searchParams.has("_rsc_loader");
-  const isPartialReq = url.searchParams.has("_rsc_partial");
+    url.searchParams.has(WIRE.action);
+  const isLoaderFetch = url.searchParams.has(WIRE.loader);
+  const isPartialReq = url.searchParams.has(WIRE.partial);
   const contentType = requestHeaders(request).get("content-type") || "";
   const isFormSubmission =
     contentType.includes("multipart/form-data") ||
@@ -173,11 +179,11 @@ export async function classifyRequest<TEnv = any>(
   // Before the version check: each router has its own version, so a tab of
   // another app always carries one this router does not have. That request is
   // an app switch, not a stale client.
-  const clientRouterId = url.searchParams.get("_rsc_rid");
+  const clientRouterId = url.searchParams.get(WIRE.routerId);
   if (
     clientRouterId &&
     clientRouterId !== deps.routerId &&
-    url.searchParams.has("_rsc_partial")
+    url.searchParams.has(WIRE.partial)
   ) {
     return {
       mode: "app-switch",
@@ -185,7 +191,7 @@ export async function classifyRequest<TEnv = any>(
     };
   }
 
-  const clientVersion = url.searchParams.get("_rsc_v");
+  const clientVersion = url.searchParams.get(WIRE.version);
   if (
     deps.routerVersion &&
     clientVersion &&
@@ -254,7 +260,7 @@ export async function classifyRequest<TEnv = any>(
 
   const actionId =
     requestHeaders(request).get("rsc-action") ||
-    url.searchParams.get("_rsc_action");
+    url.searchParams.get(WIRE.action);
 
   const hasVariants =
     snapshot.matched.negotiateVariants &&

package/src/router/revalidation.ts

@@ -24,6 +24,22 @@ import { makeIsAction } from "./is-action.js";
 const REVALIDATE_ALWAYS: ShouldRevalidateFn<any, any> = () => true;
 const REVALIDATE_NEVER: ShouldRevalidateFn<any, any> = () => false;
 
+/** Trace reasons of the action defaults, per lane: an action, a stale request. */
+const ACTION_DEFAULT_REASONS = {
+  action: {
+    route: "action:route-segment",
+    loader: "action:loader-segment",
+    routeChild: "action:belongs-to-route",
+    parentChain: "action:parent-chain-skip",
+  },
+  stale: {
+    route: "stale:route-segment",
+    loader: "stale:loader-segment",
+    routeChild: "stale:belongs-to-route",
+    parentChain: "stale:parent-chain-skip",
+  },
+} as const;
+
 /**
  * The predicate `revalidate(true)` / `revalidate(false)` stands for: the
  * constant hard decision of `revalidate(() => true)` / `() => false`.
@@ -61,8 +77,13 @@ export interface EvaluateRevalidationOptions<TEnv> {
   context: HandlerContext<any, TEnv>;
   /** Action context if triggered by action */
   actionContext?: ActionContext;
-  /** If true, this is a stale cache revalidation request */
+  /** The browser's `_rsc_stale` signal: seeds the action defaults. */
   stale?: boolean;
+  /**
+   * The route-cache entry is past its TTL (SWR). Predicates see it as `stale`;
+   * it never seeds the action defaults.
+   */
+  cacheStale?: boolean;
   /** Trace source hint for the revalidation trace */
   traceSource?: RevalidationTraceEntry["source"];
   /**
@@ -100,6 +121,7 @@ export async function evaluateRevalidation<TEnv>(
     context,
     actionContext,
     stale,
+    cacheStale,
     traceSource,
     defaultOverride,
   } = options;
@@ -147,19 +169,23 @@ export async function evaluateRevalidation<TEnv>(
   if (defaultOverride) {
     defaultShouldRevalidate = defaultOverride.value;
     defaultReason = defaultOverride.reason;
-  } else if (request.method === "POST") {
+  } else if (request.method === "POST" || stale) {
+    // A stale request re-renders a page an action may have changed after the
+    // client cached it. Not an action: no actionContext, isAction() is false.
+    const reasons =
+      ACTION_DEFAULT_REASONS[request.method === "POST" ? "action" : "stale"];
     if (segment.type === "route") {
       defaultShouldRevalidate = true;
-      defaultReason = "action:route-segment";
+      defaultReason = reasons.route;
     } else if (segment.type === "loader") {
       defaultShouldRevalidate = true;
-      defaultReason = "action:loader-segment";
+      defaultReason = reasons.loader;
     } else if (segment.belongsToRoute) {
       defaultShouldRevalidate = true;
-      defaultReason = "action:belongs-to-route";
+      defaultReason = reasons.routeChild;
     } else {
       defaultShouldRevalidate = false;
-      defaultReason = "action:parent-chain-skip";
+      defaultReason = reasons.parentChain;
     }
   } else {
     if (segment.type === "route") {
@@ -251,7 +277,7 @@ export async function evaluateRevalidation<TEnv>(
         routeName: toRouteName,
         fromRouteName,
         toRouteName,
-        stale,
+        stale: cacheStale ? true : stale,
       });
     } catch (error) {
       // A thrown Response is control flow (e.g. `throw redirect(...)`), not a

package/src/router/route-snapshot.ts

@@ -20,6 +20,7 @@ import { loadManifest } from "./manifest.js";
 import { collectRouteMiddleware } from "./middleware.js";
 import type { CollectedMiddleware } from "./middleware-types.js";
 import { traverseBack } from "./pattern-matching.js";
+import { localRouteName } from "../route-name.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 /**
@@ -170,10 +171,6 @@ export async function resolveRoute<TEnv = any>(
     matched.responseType ||
     (manifestEntry.type === "route" ? manifestEntry.responseType : undefined);
 
-  const localRouteName = matched.routeKey.includes(".")
-    ? matched.routeKey.split(".").pop()!
-    : matched.routeKey;
-
   return {
     type: "match",
     snapshot: {
@@ -181,7 +178,7 @@ export async function resolveRoute<TEnv = any>(
       manifestEntry,
       entries,
       routeKey: matched.routeKey,
-      localRouteName,
+      localRouteName: localRouteName(matched.routeKey),
       params: matched.params,
       routeMiddleware,
       cacheScope,