@rangojs/router 0.16.0 → 0.18.0

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

@@ -45,7 +45,8 @@ import {
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { observeEvent, observeHandler } from "../instrument.js";
+import { observeEvent, observeSegmentHandler } from "../instrument.js";
+import { runInSegmentTagScope } from "../../cache/cache-tag.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
@@ -215,13 +216,14 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // onError/loader.error. isPartial flags the reporting phase accordingly.
   const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
 
-  // PPR lane decision, same rule as the fresh funnel (fresh.ts): an entry
-  // without renderable loading() puts its loaders on the BAKE lane. The key
-  // must thread through EVERY resolveLoaderData funnel — omitting it here made
-  // a capture-active context whole-container-mask every loader on this path
-  // (a never-settling promise for a loader that should have executed).
+  // PPR bake/seed key, same as fresh.ts (lane rule: see resolveLoaderData,
+  // loader-cache.ts). The key must thread through EVERY resolveLoaderData
+  // funnel — omitting it here made a capture-active context
+  // whole-container-mask every loader on this path (a never-settling promise
+  // for a loader that should have executed).
   // Outside capture the key only activates the _shellLoaderSeed overlay,
-  // which document-only serveShellHit seeds — inert for partial requests.
+  // which serveShellHit seeds for a document HIT and the PPR partial replay
+  // (matchPartialWithPprReplay) seeds once its doc record hits.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
 
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
@@ -240,9 +242,10 @@ export async function resolveLoadersWithRevalidation<TEnv>(
             loaderEntry,
             ctx,
             ctx.pathname,
-            bakeLane || loaderEntry.awaitBeforeFlush === true
-              ? segmentId
-              : null,
+            // `bake`, not awaitBeforeFlush: a navigation evaluation never
+            // carries awaitBeforeFlush, and an ssr: false loader must pin
+            // here exactly as on the document HIT.
+            bakeLane || loaderEntry.bake === true ? segmentId : null,
           ),
         ),
         entry,
@@ -476,7 +479,9 @@ async function resolveParallelSlotComponent<TEnv>(args: {
       handlerRan = true;
       if (hasLoadingFallback) {
         const result =
-          typeof handler === "function" ? handler(context) : handler;
+          typeof handler === "function"
+            ? runInSegmentTagScope(parallelId, handler, context)
+            : handler;
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, parallelId);
           const tracked = deps.trackHandler(result, {
@@ -497,7 +502,9 @@ async function resolveParallelSlotComponent<TEnv>(args: {
         }
       } else {
         component =
-          typeof handler === "function" ? await handler(context) : handler;
+          typeof handler === "function"
+            ? await runInSegmentTagScope(parallelId, handler, context)
+            : handler;
       }
     }
   }
@@ -842,14 +849,19 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
           : routeEntry.handler;
       if (!routeEntry.loading) {
         const result = handleHandlerResult(
-          await observeHandler(entry.id, handler, context),
+          await observeSegmentHandler(
+            entry.shortCode,
+            entry.id,
+            handler,
+            context,
+          ),
         );
         doneHandler();
         return result;
       }
       if (!actionContext) {
         const result = handleHandlerResult(
-          observeHandler(entry.id, handler, context),
+          observeSegmentHandler(entry.shortCode, entry.id, handler, context),
         );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, routeEntry.id);
@@ -875,7 +887,12 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         entryId: entry.id,
       });
       const actionResult = handleHandlerResult(
-        await observeHandler(entry.id, handler, context),
+        await observeSegmentHandler(
+          entry.shortCode,
+          entry.id,
+          handler,
+          context,
+        ),
       );
       doneHandler();
       return {
@@ -934,6 +951,8 @@ export async function resolveSegmentWithRevalidation<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
+  /** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+  chain?: readonly EntryData[],
 ): Promise<SegmentRevalidationResult> {
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
@@ -1066,6 +1085,7 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     matchedIds.push(...parallelResult.matchedIds);
 
     for (const orphan of entry.layout) {
+      if (chain?.includes(orphan)) continue;
       const orphanResult = await resolveOrphanLayoutWithRevalidation(
         orphan,
         params,
@@ -1274,6 +1294,27 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   segments.push(...parallelResult.segments);
   matchedIds.push(...parallelResult.matchedIds);
 
+  // Nested routeless entries; see resolveOrphanLayout (fresh.ts).
+  for (const nested of orphan.layout) {
+    const nestedResult = await resolveOrphanLayoutWithRevalidation(
+      nested,
+      params,
+      context,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      belongsToRoute,
+      deps,
+      actionContext,
+      stale,
+    );
+    segments.push(...nestedResult.segments);
+    matchedIds.push(...nestedResult.matchedIds);
+  }
+
   return { segments, matchedIds };
 }
 
@@ -1296,6 +1337,8 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   pathname: string,
   deps: SegmentResolutionDeps<TEnv>,
   stale?: boolean,
+  /** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+  chain: readonly EntryData[] = entries,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const allSegments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
@@ -1325,7 +1368,8 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
-    if (entry.type === "cache") {
+    // Same latch as resolveAllSegments (fresh.ts), route-level cache() included.
+    if (entry.cache) {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
       latchCachedHeaderScope("cache", routeKey);
@@ -1348,6 +1392,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
           deps,
           actionContext,
           stale,
+          chain,
         ),
       (seg) => ({ segments: [seg], matchedIds: [seg.id] }),
       deps,

package/src/router/segment-wrappers.ts

@@ -80,6 +80,8 @@ export interface SegmentWrappers<TEnv = any> {
     interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
+    chain?: readonly EntryData[],
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
   findInterceptForRoute: (
     targetRouteKey: string,
@@ -205,6 +207,7 @@ export function createSegmentWrappers<TEnv = any>(
     localRouteName: string,
     pathname: string,
     stale?: boolean,
+    chain?: readonly EntryData[],
   ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
     return _resolveAllSegmentsWithRevalidation(
       entries,
@@ -222,6 +225,7 @@ export function createSegmentWrappers<TEnv = any>(
       pathname,
       segmentDeps,
       stale,
+      chain,
     );
   }
 

package/src/rsc/full-payload.ts

@@ -13,6 +13,7 @@ import type { RscPayload } from "./types.js";
 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 { resolvedHandleStream } from "../handles/deferred-resolution.js";
 
@@ -71,7 +72,30 @@ export function buildFullPayload(
       // entry knows whether to wrap hydration in React.StrictMode. Partial
       // (navigation) payloads omit it by design; StrictMode is decided once.
       strictMode: ctx.router.strictMode,
-      initialTheme: reqCtx.theme,
+      initialTheme: payloadInitialTheme(reqCtx),
     },
   };
 }
+
+/**
+ * The theme a document payload carries as `metadata.initialTheme` (the
+ * 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.
+ */
+export function payloadInitialTheme(
+  reqCtx: Pick<
+    RequestContext<any>,
+    "_themeConfig" | "_shellCaptureRun" | "_readTheme"
+  >,
+): Theme | undefined {
+  const config = reqCtx._themeConfig;
+  if (!config) return undefined;
+  return reqCtx._shellCaptureRun ? config.defaultTheme : reqCtx._readTheme();
+}

package/src/rsc/handler.ts

@@ -31,6 +31,7 @@ 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,
@@ -85,6 +86,7 @@ import {
   ORIGIN_CHECK_PHASE_BY_MODE,
 } from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
+import { withoutShellMissMarker } from "./shell-serve.js";
 import {
   withTimeout,
   isTimeoutEnabled,
@@ -436,10 +438,16 @@ export function createRSCHandler<
   };
 
   return async function handler(
-    request: Request,
+    incomingRequest: Request,
     input: RouterRequestInput<TEnv> = {},
   ): Promise<Response> {
     const handlerStart = performance.now();
+    // A degraded PPR HIT's reload carries the forced-MISS marker: keep only
+    // the flag (set on the request context below) and drop the marker before
+    // anything reads the request, so middleware, handlers, loaders, cache
+    // keys and the SSR search seed see the URL the visitor asked for.
+    const unmarkedRequest = withoutShellMissMarker(incomingRequest);
+    const request = unmarkedRequest ?? incomingRequest;
     // Create the metrics store at handler start so handler:total has startTime=0
     // and all metrics are relative to the request entry point.
     const earlyMetricsStore = router.debugPerformance
@@ -566,6 +574,7 @@ export function createRSCHandler<
       stateCookieName: router.resolvedStateCookieName,
       version,
     });
+    if (unmarkedRequest) requestContext._shellForcedMiss = true;
     // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):
     // a `renderStartMs: 0` / negative opt-out disables the timeout, so the
     // driver's cursor bookkeeping (which only the timeout reads) must be off too.
@@ -662,6 +671,9 @@ export function createRSCHandler<
         // the host; it never reads or wraps response.body. A downstream throw
         // skips it entirely (no response exists to hand off).
         return observePhase(PHASES.response, (responseSpan) => {
+          // Header and cookie writes from here on (a streaming loader or
+          // render) no longer reach the response.
+          requestContext._responseSent = true;
           let response: Response;
           if (hasMiddleware) {
             if (
@@ -1355,7 +1367,7 @@ export function createRSCHandler<
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
               strictMode: router.strictMode,
-              initialTheme: getRequestContext().theme,
+              initialTheme: payloadInitialTheme(getRequestContext()),
             },
           };
 

package/src/rsc/progressive-enhancement.ts

@@ -15,6 +15,7 @@ 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 { payloadInitialTheme } from "./full-payload.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
@@ -444,7 +445,7 @@ function renderPeResponse<TEnv>(
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       strictMode: ctx.router.strictMode,
-      initialTheme: getRequestContext().theme,
+      initialTheme: payloadInitialTheme(getRequestContext()),
     },
   };
 
@@ -646,7 +647,7 @@ function renderPeErrorResponse<TEnv>(
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       strictMode: ctx.router.strictMode,
-      initialTheme: getRequestContext().theme,
+      initialTheme: payloadInitialTheme(getRequestContext()),
     },
   };
 

package/src/rsc/render-pipeline.ts

@@ -155,9 +155,12 @@ function createFlightStage<TEnv>(
   if (input.ctx.devDiscoveryEpoch !== undefined && input.payload.metadata) {
     input.payload.metadata.devDiscoveryEpoch = input.ctx.devDiscoveryEpoch;
   }
+  // Read once here: onError can fire outside the ALS frame.
+  const renderErrors = _getRequestContext()?._renderErrors;
   const stream = input.ctx.renderToReadableStream<RscPayload>(input.payload, {
     temporaryReferences: input.temporaryReferences,
     onError: (error: unknown) => {
+      renderErrors?.push(error);
       input.ctx.callOnError(error, "rendering", {
         request: input.request,
         url: input.url,

package/src/rsc/response-cache-serve.ts

@@ -105,7 +105,10 @@ export async function serveResponseRouteWithCache(
   // the host-namespacing and search-normalization rules cannot drift.
   let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
 
-  // Priority 1: route-level key() (full override). Priority 2: store-level
+  // Priority 1: route-level key() (full override): the key() results of every
+  // cache() enclosing the route, composed like the segment record key
+  // (CacheScope.resolveKeyFrom, #970), so a nested cache() never shares an
+  // entry across the enclosing partitions. Priority 2: store-level
   // keyGenerator (modifies the default key).
   //
   // A CONFIGURED key()/keyGenerator that THROWS must DEGRADE TO A MISS, not fall
@@ -114,13 +117,13 @@ export async function serveResponseRouteWithCache(
   // would cache PERSONALIZED output under it and serve it cross-user (cache
   // poisoning). Mirrors the segment-cache behavior (cache-scope.ts lookupRoute):
   // a throwing key degrades to a cache miss, never a collision onto the default
-  // slot. The no-key default path is left untouched (the broad key is correct
-  // when no key is configured).
+  // slot, and so does a key() with no ambient request context to run in
+  // (resolveKeyFrom rejects). The no-key default path is left untouched (the
+  // broad key is correct when no key is configured).
   let keyResolutionFailed = false;
-  if (cacheScope.config !== false && cacheScope.config.key) {
+  if (cacheScope.keyFns.length > 0) {
     try {
-      const customKey = await cacheScope.config.key(reqCtx);
-      cacheKey = `response:${customKey}`;
+      cacheKey = `response:${await cacheScope.resolveKeyFrom(cacheKey)}`;
     } catch (error) {
       keyResolutionFailed = true;
       reportCacheError(

package/src/rsc/response-route-handler.ts

@@ -8,7 +8,7 @@
 
 import { RouterError } from "../errors.js";
 import { getRequestContext } from "../server/request-context.js";
-import { contextGet } from "../context-var.js";
+import { contextGet, isNonCacheable } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
@@ -19,7 +19,10 @@ import {
   stripInternalParams,
 } from "../router/handler-context.js";
 import type { MiddlewareFn } from "../router/middleware.js";
-import type { EntryData } from "../server/context.js";
+import {
+  assertNonCacheableReadAllowed,
+  type EntryData,
+} from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
 import { createProblemDetails } from "./response-error.js";
 import {
@@ -85,7 +88,12 @@ export async function handleResponseRoute<TEnv>(
     originalUrl: reqCtx.originalUrl,
     pathname: url.pathname,
     reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
-    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+    get: ((keyOrVar: any) => {
+      if (isNonCacheable(variables, keyOrVar)) {
+        assertNonCacheableReadAllowed(keyOrVar);
+      }
+      return contextGet(variables, keyOrVar);
+    }) as any,
     header: (name: string, value: string) => reqCtx.header(name, value),
     waitUntil: reqCtx.waitUntil.bind(reqCtx),
     executionContext: reqCtx.executionContext,