@rangojs/router 0.18.0 → 0.19.1

package/src/router/segment-resolution/revalidation.ts

@@ -708,7 +708,6 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
-        parallelId,
       ),
       params,
       slot,
@@ -920,7 +919,6 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       entry.transition,
       deps.viewTransitionDefault,
-      entry.shortCode,
     ),
     params,
     belongsToRoute,
@@ -1261,7 +1259,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
-      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });

package/src/router/segment-resolution/view-transition-default.ts

@@ -8,7 +8,6 @@
  */
 
 import type { EntryData } from "../../server/context";
-import { getRequestContext } from "../../server/request-context.js";
 
 /**
  * Resolve a segment's transition config: stamp the `viewTransition` default and
@@ -22,34 +21,20 @@ import { getRequestContext } from "../../server/request-context.js";
  * (or "auto") value is left untouched because it already means "wrap" at the
  * gate, which also avoids needless object allocation and payload growth.
  *
- * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache). PPR routes evaluate it
- * from the manifest before the pipeline; other routes record it here for the
- * existing post-handler gate. Used by both fresh and revalidation resolution.
+ * `when`: a client reference the server never calls. It is STRIPPED here so no
+ * segment record (segment cache, prerender artifact, shell snapshot) carries
+ * it: those stores JSON-serialize the config and would silently drop it on
+ * some stores and keep it on others. rsc/attach-transition-when.ts attaches it
+ * from the route definition right before Flight instead. Used by both fresh
+ * and revalidation resolution.
  */
 export function applyViewTransitionDefault(
   transition: EntryData["transition"],
   viewTransitionDefault: "auto" | false | undefined,
-  segmentId?: string,
 ): EntryData["transition"] {
   if (!transition) return transition;
   let result = transition;
   if (result.when) {
-    if (segmentId !== undefined) {
-      try {
-        const ctx = getRequestContext();
-        if (!ctx._pprTransitionDecisions?.has(segmentId)) {
-          (ctx._transitionWhen ??= []).push({
-            id: segmentId,
-            when: result.when,
-          });
-        }
-      } catch {
-        // No active request context (e.g. a unit test calling this util
-        // directly). Skip collection; the strip below still applies so the
-        // serialized config never carries the function.
-      }
-    }
     const { when: _when, ...rest } = result;
     result = rest;
   }

package/src/router/telemetry.ts

@@ -14,6 +14,8 @@
  *   - revalidation.decision          (revalidation evaluation)
  */
 
+import { requestHeaders } from "../server/request-headers.js";
+
 interface BaseEvent {
   /** Monotonic timestamp from performance.now() */
   timestamp: number;
@@ -294,10 +296,11 @@ export function getRequestId(request: Request): string {
   const existing = requestIds.get(request);
   if (existing) return existing;
 
+  const headers = requestHeaders(request);
   const candidate =
-    request.headers.get("x-rsc-router-request-id") ??
-    request.headers.get("x-request-id") ??
-    request.headers.get("cf-ray");
+    headers.get("x-rsc-router-request-id") ??
+    headers.get("x-request-id") ??
+    headers.get("cf-ray");
 
   let id: string;
   if (candidate) {

package/src/router/transition-when.ts

@@ -1,76 +1,58 @@
 import { getParallelSlotEntries, type EntryData } from "../server/context.js";
 import type { RequestContext } from "../server/request-context.js";
-import type { TransitionWhenContext } from "../types/segments.js";
+import type { TransitionWhenSite } from "../transition-when-ref.js";
+import type { TransitionWhenFn } from "../types/segments.js";
 
-export type TransitionWhenErrorReporter = (
-  error: unknown,
-  segmentId: string,
-) => void;
-
-export function createTransitionWhenContext<TEnv>(
-  ctx: RequestContext<TEnv>,
-  target?: {
-    params: Record<string, string>;
-    routeName?: string;
-  },
-): TransitionWhenContext<Record<string, string>, TEnv> {
-  return {
-    currentUrl: ctx._gateCurrentUrl,
-    currentParams: ctx._gateCurrentParams,
-    fromRouteName: ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
-    nextUrl: ctx.url,
-    nextParams: target?.params ?? ctx.params,
-    toRouteName: (target?.routeName ??
-      ctx.routeName) as TransitionWhenContext["toRouteName"],
-    actionId: ctx._gateActionId,
-    actionUrl: ctx._gateActionUrl,
-    actionResult: ctx._gateActionResult,
-    formData: ctx._gateFormData,
-    method: ctx.request.method,
-    get: ctx.get,
-    env: ctx.env,
-  };
+/** A matched entry's transition({ when }) and where it was declared. */
+export interface TransitionWhenRecord {
+  readonly when: TransitionWhenFn;
+  readonly site: TransitionWhenSite;
 }
 
-/** Evaluate server-only transition gates before handlers on a PPR route. */
-export function evaluatePprTransitionWhen<TEnv>(
-  entries: EntryData[],
+/**
+ * Record the transition({ when }) references of a matched entry chain, keyed
+ * by the segment id each entry resolves to. The server never calls them:
+ * rsc/attach-transition-when.ts attaches them to the payload's segments right
+ * before Flight, and the browser decides (browser/transition-when.ts).
+ *
+ * Recorded from the static route definition on EVERY match (fresh, cache hit,
+ * prerender, PPR replay) because stored segments never carry them:
+ * applyViewTransitionDefault strips `when` at resolution, since segment stores
+ * JSON-serialize the transition config (dropping a function on some stores,
+ * keeping it by reference on others). Segment ids follow resolution: an
+ * entry's shortCode, and `${owner.shortCode}.${slot}` for a rendered parallel
+ * slot.
+ */
+export function recordTransitionWhenRefs<TEnv>(
+  entries: readonly EntryData[] | undefined,
   ctx: RequestContext<TEnv>,
-  target: {
-    params: Record<string, string>;
-    routeName?: string;
-  },
-  reportError: TransitionWhenErrorReporter,
+  route: { routeName?: string; pattern?: string } = {},
 ): void {
-  const decisions = new Map<string, boolean>();
-  const whenContext = createTransitionWhenContext(ctx, target);
+  const refs = new Map<string, TransitionWhenRecord>();
   const visited = new Set<EntryData>();
 
-  const evaluate = (entry: EntryData, segmentId: string): void => {
+  const record = (entry: EntryData, segmentId: string): void => {
     const when = entry.transition?.when;
-    if (!when) return;
-    try {
-      decisions.set(segmentId, when(whenContext) !== false);
-    } catch (error) {
-      decisions.set(segmentId, false);
-      reportError(error, segmentId);
-    }
+    if (when === undefined) return;
+    refs.set(segmentId, {
+      when,
+      site: { ...route, entryType: entry.type },
+    });
   };
 
   const visitEntryAndOrphanLayouts = (entry: EntryData): void => {
     if (visited.has(entry)) return;
     visited.add(entry);
-    evaluate(entry, entry.shortCode);
+    record(entry, entry.shortCode);
 
     for (const orphan of entry.layout) visitEntryAndOrphanLayouts(orphan);
-    // Rendered parallel slots are leaves identified by their owning segment.
     for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
       entry.parallel,
     )) {
-      evaluate(parallelEntry, `${entry.shortCode}.${slot}`);
+      record(parallelEntry, `${entry.shortCode}.${slot}`);
     }
   };
 
-  for (const entry of entries) visitEntryAndOrphanLayouts(entry);
-  ctx._pprTransitionDecisions = decisions.size > 0 ? decisions : undefined;
+  for (const entry of entries ?? []) visitEntryAndOrphanLayouts(entry);
+  ctx._transitionWhenRefs = refs.size > 0 ? refs : undefined;
 }

package/src/router.ts

@@ -1,3 +1,4 @@
+import { requestHeaders } from "./server/request-headers.js";
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
@@ -1161,7 +1162,7 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
-        const requestedDiscoveryEpoch = request.headers.get(
+        const requestedDiscoveryEpoch = requestHeaders(request).get(
           DEV_DISCOVERY_PROBE_HEADER,
         );
         if (

package/src/rsc/attach-transition-when.ts

@@ -0,0 +1,47 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.js";
+import {
+  createTransitionWhenError,
+  isTransitionWhenValidationEnabled,
+  transitionWhenProblem,
+} from "../transition-when-ref.js";
+
+/**
+ * Attach transition({ when }) references to a payload's segments, right before
+ * Flight. Returns a copy for every segment it changes: the input segments may
+ * be the records a cache, prerender, or shell snapshot holds.
+ *
+ * Only a segment that carries `transition` gets its predicate. The config
+ * itself never varies per request, so the segment key and the <ViewTransition>
+ * wrapper depend only on the route definition (#995); the browser decides for
+ * every committed segment, kept ones included (#989).
+ *
+ * Render-time backstop for an invalid `when` that route discovery did not see
+ * (a route evaluated lazily at runtime): it throws the discovery error. A
+ * plain function reaching Flight would otherwise fail with React's generic
+ * "Functions cannot be passed directly to Client Components", or be dropped.
+ */
+export function attachTransitionWhen(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+): MatchResult["segments"] {
+  const refs = ctx?._transitionWhenRefs;
+  if (!refs) return segments;
+  const strict = isTransitionWhenValidationEnabled();
+  let out = segments;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    const record = segment.transition ? refs.get(segment.id) : undefined;
+    if (!record || segment.transition!.when === record.when) continue;
+    const problem = transitionWhenProblem(record.when, strict);
+    if (problem) {
+      throw createTransitionWhenError(record.when, problem, record.site);
+    }
+    if (out === segments) out = [...segments];
+    out[i] = {
+      ...segment,
+      transition: { ...segment.transition, when: record.when },
+    };
+  }
+  return out;
+}

package/src/rsc/full-payload.ts

@@ -14,7 +14,9 @@ import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { Theme } from "../theme/types.js";
-import { gateTransitions } from "./transition-gate.js";
+import { documentCacheStoresRender } from "../cache/document-cache.js";
+import { attachTransitionWhen } from "./attach-transition-when.js";
+import { publicRouteName } from "../route-name.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 
 /**
@@ -39,11 +41,12 @@ export function buildFullPayload(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: gateTransitions(m.segments, reqCtx, ctx.router.onError),
+      segments: attachTransitionWhen(m.segments, reqCtx),
       matched: m.matched,
       diff: m.diff,
       resolvedIds: m.resolvedIds,
       params: m.params,
+      routeName: publicRouteName(m.routeName),
       isPartial: false,
       interceptTargets: m.interceptTargets,
       rootLayout: ctx.router.rootLayout,
@@ -82,20 +85,37 @@ export function buildFullPayload(
  * ThemeProvider's first state), read with no identity guard: it is the
  * router's own read, not handler code (#971).
  *
- * A shell capture carries the no-cookie default, not the capturing visitor's
- * theme. The shell and its ShellCacheEntry.initialTheme serve every visitor,
- * and ThemeProvider re-syncs only from an explicitly stored theme, so a
- * visitor with none kept the capturer's `useTheme().theme` for the page's
- * lifetime. A visitor with a stored theme gets it pre-paint (theme script)
- * and in the provider after mount.
+ * A render other visitors may be served carries the no-cookie default, not
+ * the rendering visitor's theme: a shell capture, and a render the document
+ * cache runs whose response opted in before next() (documentCacheStoresRender,
+ * #978). The shell, its ShellCacheEntry.initialTheme and the stored document
+ * serve every visitor, and ThemeProvider re-syncs only from an explicitly
+ * stored theme, so a visitor with none kept the first visitor's
+ * `useTheme().theme` for the page's lifetime. A visitor with a stored theme
+ * gets it pre-paint (theme script) and in the provider after mount.
+ *
+ * Any other render carries the visitor's theme (the unmatched-route 404 reads
+ * it without this function, rsc/handler.ts); when that differs from the
+ * default it marks `_payloadVisitorTheme`, and the document cache does not
+ * store the response.
  */
 export function payloadInitialTheme(
   reqCtx: Pick<
     RequestContext<any>,
-    "_themeConfig" | "_shellCaptureRun" | "_readTheme"
+    | "_themeConfig"
+    | "_shellCaptureRun"
+    | "_readTheme"
+    | "_documentCacheRender"
+    | "_payloadVisitorTheme"
+    | "res"
   >,
 ): Theme | undefined {
   const config = reqCtx._themeConfig;
   if (!config) return undefined;
-  return reqCtx._shellCaptureRun ? config.defaultTheme : reqCtx._readTheme();
+  if (reqCtx._shellCaptureRun || documentCacheStoresRender(reqCtx)) {
+    return config.defaultTheme;
+  }
+  const theme = reqCtx._readTheme();
+  if (theme !== config.defaultTheme) reqCtx._payloadVisitorTheme = true;
+  return theme;
 }

package/src/rsc/handler.ts

@@ -7,6 +7,7 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
@@ -31,7 +32,6 @@ import {
 } from "./helpers.js";
 import { renderRscFlightStage, renderRscResponse } from "./render-pipeline.js";
 import { guardOutgoingRedirect } from "./redirect-guard.js";
-import { payloadInitialTheme } from "./full-payload.js";
 import {
   resolveSoftRedirectUrl,
   resolveExternalRedirect,
@@ -925,8 +925,10 @@ export function createRSCHandler<
         originPhase,
       );
       if (originResult) {
+        const origin = requestHeaders(request).get("origin");
+        const host = requestHeaders(request).get("host");
         const originError = new Error(
-          `Origin check rejected: ${request.headers.get("origin") ?? "none"} vs ${request.headers.get("host") ?? "none"}`,
+          `Origin check rejected: ${origin ?? "none"} vs ${host ?? "none"}`,
         );
         originError.name = "OriginCheckError";
 
@@ -935,11 +937,7 @@ export function createRSCHandler<
           url,
           env,
           handledByBoundary: false,
-          metadata: {
-            phase: originPhase,
-            origin: request.headers.get("origin"),
-            host: request.headers.get("host"),
-          },
+          metadata: { phase: originPhase, origin, host },
         });
 
         if (router.telemetry) {
@@ -950,8 +948,8 @@ export function createRSCHandler<
             method: request.method,
             pathname: url.pathname,
             phase: originPhase,
-            origin: request.headers.get("origin"),
-            host: request.headers.get("host"),
+            origin,
+            host,
           });
         }
 
@@ -1367,7 +1365,11 @@ export function createRSCHandler<
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
               strictMode: router.strictMode,
-              initialTheme: payloadInitialTheme(getRequestContext()),
+              // The visitor's theme, not payloadInitialTheme (full-payload.ts):
+              // that picks the default when middleware opted the URL into the
+              // document cache before next(), but a 404 is never stored or
+              // captured (#978).
+              initialTheme: getRequestContext()._readTheme(),
             },
           };
 

package/src/rsc/loader-fetch.ts

@@ -11,6 +11,7 @@
  * has already extracted params from it.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
 import { isDataNotFoundError } from "../errors.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
@@ -144,7 +145,7 @@ export async function handleLoaderFetch<TEnv>(
 
   if (isBodyMethod) {
     try {
-      const contentType = request.headers.get("content-type") || "";
+      const contentType = requestHeaders(request).get("content-type") || "";
       if (contentType.includes("multipart/form-data")) {
         // FormData body — sent by load() when body is a FormData instance.
         // Preserves File objects and binary data.

package/src/rsc/manifest-init.ts

@@ -14,6 +14,7 @@ import {
   setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
 import { mergeFullManifests } from "../build/merge-full-manifests.js";
+import { isTransitionWhenValidationEnabled } from "../transition-when-ref.js";
 
 /**
  * Build a fresh route trie from the router's URL-pattern mounts and store it in
@@ -49,6 +50,9 @@ export async function buildRouterTrieFromUrlpatterns(
       await generateManifestFull(mount.patterns, mount.mountIndex, {
         routerId: router.id,
         ...(router.basename ? { urlPrefix: router.basename } : {}),
+        // Under the Vite plugin the realm validates like discovery does, so
+        // a Cloudflare dev rebuild fails on an invalid when too.
+        validateTransitionWhen: isTransitionWhenValidationEnabled(),
       }),
     );
   }

package/src/rsc/origin-guard.ts

@@ -9,6 +9,7 @@
  * navigations, bookmarks, and non-browser clients don't send Origin.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import type { RequestPlan } from "../router/request-classification.js";
 
 /**
@@ -69,10 +70,11 @@ export type OriginCheckConfig<TEnv = any> =
  * Returns true to allow, false to reject.
  */
 export function defaultOriginCheck(request: Request, url: URL): boolean {
-  let requestOrigin = request.headers.get("origin");
+  const headers = requestHeaders(request);
+  let requestOrigin = headers.get("origin");
 
   if (!requestOrigin) {
-    const referer = request.headers.get("referer");
+    const referer = headers.get("referer");
     if (referer) {
       try {
         requestOrigin = new URL(referer).origin;
@@ -92,7 +94,7 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
   // :authority), so a missing Host here is anomalous. Fail closed rather than
   // fall back to url.host (derived from the request line) when the trusted Host
   // cannot be established.
-  const expectedHost = request.headers.get("host");
+  const expectedHost = headers.get("host");
   if (!expectedHost) return false;
 
   const expectedOrigin = `${url.protocol}//${expectedHost}`;
@@ -102,11 +104,12 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
 
 function createForbiddenResponse(request: Request): Response {
   const isDev = process.env.NODE_ENV !== "production";
+  const headers = requestHeaders(request);
   const body = isDev
     ? "Forbidden: Origin mismatch. The request origin does not match the server host. " +
       `Set originCheck: false in createRouter() to disable this check. ` +
-      `(Origin: ${request.headers.get("origin") ?? "none"}, ` +
-      `Host: ${request.headers.get("host") ?? "none"})`
+      `(Origin: ${headers.get("origin") ?? "none"}, ` +
+      `Host: ${headers.get("host") ?? "none"})`
     : "Forbidden";
 
   return new Response(body, {

package/src/rsc/progressive-enhancement.ts

@@ -6,6 +6,7 @@
  * reference. We detect these and return HTML instead of RSC stream.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import {
   getRequestContext,
   setRequestContextParams,
@@ -14,7 +15,7 @@ import { createSsrHtmlStage } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
-import { gateTransitions } from "./transition-gate.js";
+import { attachTransitionWhen } from "./attach-transition-when.js";
 import { payloadInitialTheme } from "./full-payload.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
@@ -64,7 +65,7 @@ export async function handleProgressiveEnhancement<TEnv>(
   nonce: string | undefined,
   routeMwInfo?: PeRouteMiddlewareInfo,
 ): Promise<Response | null> {
-  const contentType = request.headers.get("content-type") || "";
+  const contentType = requestHeaders(request).get("content-type") || "";
   const isFormSubmission =
     contentType.includes("multipart/form-data") ||
     contentType.includes("application/x-www-form-urlencoded");
@@ -312,7 +313,7 @@ async function handleProgressiveEnhancementInner<TEnv>(
     // custom headers) so loaders that read request headers/cookies behave
     // identically under PE and the JS action path. Drop body-framing headers
     // from the bodyless GET and force the HTML accept.
-    const headers = new Headers(request.headers);
+    const headers = new Headers(requestHeaders(request));
     headers.delete("content-type");
     headers.delete("content-length");
     headers.delete("content-encoding");
@@ -326,15 +327,9 @@ async function handleProgressiveEnhancementInner<TEnv>(
     // JS/PE parity: this is an action's revalidation render, so mark it BEFORE
     // matching — a stale `foregroundOnAction` cache entry must re-execute in the
     // foreground during the re-render, exactly as the JS path's
-    // revalidateAfterAction does. PPR transition({ when }) runs during match,
-    // while foregroundOnAction reads _inActionRevalidation there too, so all
-    // action metadata must be available before matching.
+    // revalidateAfterAction does.
     const peReqCtx = getRequestContext();
     peReqCtx._inActionRevalidation = true;
-    peReqCtx._gateActionId = directActionId ?? undefined;
-    peReqCtx._gateActionUrl = new URL(url);
-    peReqCtx._gateActionResult = actionResult;
-    peReqCtx._gateFormData = formData;
 
     return runRoutine(
       peRenderPlan({
@@ -427,11 +422,7 @@ function renderPeResponse<TEnv>(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: gateTransitions(
-        match.segments,
-        getRequestContext(),
-        ctx.router.onError,
-      ),
+      segments: attachTransitionWhen(match.segments, getRequestContext()),
       matched: match.matched,
       diff: match.diff,
       resolvedIds: match.resolvedIds,
@@ -603,16 +594,6 @@ async function matchPeErrorBoundary<TEnv>(
 
   setRequestContextParams(errorResult.params, errorResult.routeName);
 
-  // Only the failing action id + URL are in scope here (no formData/actionResult
-  // thread into this helper). Expose the URL only when the action id is known:
-  // this helper also handles malformed form bodies before action detection, and
-  // those should not look like action-triggered renders to transition({ when }).
-  if (actionId != null) {
-    const peErrCtx = getRequestContext();
-    peErrCtx._gateActionId = actionId;
-    peErrCtx._gateActionUrl = new URL(url);
-  }
-
   return errorResult;
 }
 
@@ -628,11 +609,7 @@ function renderPeErrorResponse<TEnv>(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: gateTransitions(
-        errorResult.segments,
-        getRequestContext(),
-        ctx.router.onError,
-      ),
+      segments: attachTransitionWhen(errorResult.segments, getRequestContext()),
       matched: errorResult.matched,
       diff: errorResult.diff,
       resolvedIds: errorResult.resolvedIds,