@rangojs/router 0.24.4 → 0.26.0

package/src/router/loader-resolution.ts

@@ -64,12 +64,15 @@ import {
 } from "./segment-resolution/prefetch-deferral.js";
 import {
   assertNonCacheableReadAllowed,
+  getLoaderReverseScope,
   isInsideLoaderScope,
+  scopeReverse,
   runInsideLoaderBodyScope,
   runInsideLoaderRun,
   isInsidePushCallbackScope,
   runInsidePushCallbackScope,
   type LoaderRunIdentity,
+  type ScopableReverse,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -179,6 +182,8 @@ export function wrapLoaderWithErrorHandling<T>(
   // The token is the loader's $$id (hash#export in prod, pathfrag#export in dev),
   // not a clean display name.
   const loaderName = segmentId.split(".").pop() || "unknown";
+  // Captured now: the rejection can settle outside the request's ALS frame.
+  const renderErrors = _getRequestContext()?._renderErrors;
 
   return Promise.resolve(promise)
     .then(
@@ -275,6 +280,11 @@ export function wrapLoaderWithErrorHandling<T>(
         };
       }
 
+      // The error renders in place inside a 200 as a value, which neither
+      // Flight nor Fizz reports: record it like their errors, so a writer
+      // that reads _renderErrors (the document cache) does not store it.
+      renderErrors?.push(error);
+
       // Find nearest error boundary
       const fallback = findNearestErrorBoundary(entry);
 
@@ -543,6 +553,11 @@ function createLoaderExecutor<TEnv>(
     // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
     // inside loader scope. This determines whether rendered() is allowed.
     const isDslLoader = isInsideLoaderScope();
+    // The body resolves ctx.reverse(".name") in its DSL declaration's module
+    // (a layout's / parallel's / cache()'s loader). A route's loader, and one
+    // a handler starts with ctx.use(), resolve from the route. One run per
+    // request: the first declaration to start it wins.
+    const reverseScope = getLoaderReverseScope();
 
     // Owning segment for ctx.handle() attribution, captured SYNCHRONOUSLY at
     // kickoff: segment resolution sets _currentSegmentId while resolving the
@@ -568,6 +583,7 @@ function createLoaderExecutor<TEnv>(
         InternalHandlerContext<any, TEnv>,
         | "_routeName"
         | "_responseType"
+        | "_reverseScope"
         | "_currentSegmentId"
         | "_claimLoaderPushes"
         | "_runLoaderIsolated"
@@ -648,9 +664,13 @@ function createLoaderExecutor<TEnv>(
       }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
-      reverse: ctx.reverse as LoaderContext["reverse"],
+      reverse: scopeReverse(
+        ctx.reverse as ScopableReverse,
+        reverseScope,
+      ) as LoaderContext["reverse"],
       _routeName: internal._routeName,
       _responseType: internal._responseType,
+      _reverseScope: reverseScope,
       _currentSegmentId: owningSegmentId,
       _claimLoaderPushes: internal._claimLoaderPushes,
       _runLoaderIsolated: internal._runLoaderIsolated,

package/src/router/manifest.ts

@@ -3,6 +3,7 @@ import { createRouteHelpers } from "../route-definition";
 import {
   getContext,
   runWithPrefixes,
+  getDocumentModeEntry,
   getIsolatedLazyParent,
   type EntryData,
   type MetricsStore,
@@ -11,10 +12,8 @@ import MapRootLayout from "../server/root-layout";
 import { joinPrefix } from "./pattern-matching.js";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
-import {
-  isIncludeProvider,
-  resolveIncludeModule,
-} from "../urls/include-provider.js";
+import { isIncludeProvider } from "../urls/include-provider.js";
+import { resolveEntryPatterns } from "./lazy-includes.js";
 import { VERSION } from "@rangojs/router:version";
 
 // Tags an error thrown while dynamically importing an async include's module
@@ -122,12 +121,18 @@ export async function loadManifest(
       mountIndex !== undefined ? `#router.M${mountIndex}` : "#router";
 
     // For lazy entries, use the captured parent from include() context
-    // This ensures routes are registered under the correct layout hierarchy
+    // This ensures routes are registered under the correct layout hierarchy.
+    // The captured chain comes from an evaluation without isSSR: a document
+    // request takes its document-mode copy (getDocumentModeEntry, #1179).
     const lazyContext =
       entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
+    const capturedParent =
+      (lazyContext?.parent as EntryData | null | undefined) ?? Store.parent;
     const parentForContext = lazyContext
       ? getIsolatedLazyParent(
-          (lazyContext.parent as EntryData | null) ?? Store.parent,
+          isSSR && capturedParent
+            ? getDocumentModeEntry(capturedParent)
+            : capturedParent,
         )
       : Store.parent;
 
@@ -167,6 +172,9 @@ export async function loadManifest(
     // undefined) so a prior lazy build's scope cannot leak into a later
     // non-lazy build on the same ALS-backed Store.
     Store.includeScope = lazyContext?.includeScope;
+    // Same rule for the include's tree position (hidden include names).
+    Store.scopePath = lazyContext?.scopePath;
+    Store.hiddenScopePath = lazyContext?.hiddenScopePath;
 
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
@@ -190,10 +198,7 @@ export async function loadManifest(
           // cache the resolved patterns on the entry so later renders reuse them.
           if (isIncludeProvider(entry.lazyPatterns)) {
             try {
-              entry.lazyPatterns = resolveIncludeModule(
-                await entry.lazyPatterns(),
-                entry.staticPrefix,
-              ) as unknown as UrlPatterns<any>;
+              await resolveEntryPatterns(entry);
             } catch (err) {
               // A failed dynamic import of a REAL, matched route's module is a
               // server error, not a missing route. Tag it so the outer catch

package/src/router/match-api.ts

@@ -54,10 +54,12 @@ import {
   type RouteSnapshot,
 } from "./route-snapshot.js";
 import { resolveNavigation } from "./navigation-snapshot.js";
+import { pathKey, visitorUrl } from "../server/rewrite-trail.js";
 import { withLayoutLoaderCopies } from "../client-urls/layout-loader-copies.js";
 import {
   partialDeferralMode,
   planPrefetchDeferral,
+  resolveInterceptDeferralScope,
   requestKind,
 } from "./segment-resolution/prefetch-deferral.js";
 
@@ -375,6 +377,12 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
+  // Two visitor URLs can share a rewrite target, and the render may read
+  // ctx.rewrittenFrom: a move of the visitor's URL counts as a change.
+  if (reqCtx && nav.prevVisitorUrl) {
+    reqCtx._visitorMoved =
+      pathKey(visitorUrl(reqCtx, cleanUrl)) !== pathKey(nav.prevVisitorUrl);
+  }
 
   const interceptSelectorContext: InterceptSelectorContext = {
     // The source's params come from matching its URL (the intercept source
@@ -484,7 +492,6 @@ export async function createMatchContextForPartial<TEnv>(
       prefetch: kind === "prefetch",
       method: request.method,
       isAction,
-      isIntercept,
       isShellCapture: reqCtx?._shellCaptureRun === true,
     }),
     matched,
@@ -492,6 +499,9 @@ export async function createMatchContextForPartial<TEnv>(
     // What the page holds, not the copy forced above: see
     // prefetch-deferral.ts.
     held,
+    interceptResult
+      ? resolveInterceptDeferralScope(interceptResult.intercept)
+      : undefined,
   );
   (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
     deferral;

package/src/router/match-middleware/background-revalidation.ts

@@ -230,10 +230,8 @@ export async function rerenderAndCacheRoute<TEnv>(
             handlerContext,
             true, // belongsToRoute
             undefined, // no revalidationContext: render fresh
-            // Skip intercept middleware: the foreground already ran it.
-            // Re-running it here would double its side effects, and a
-            // short-circuit Response would abort the write.
-            { skipMiddleware: true },
+            // A handler error rejects, so the failure is never cached.
+            { background: true },
           ),
         )),
       );

package/src/router/match-middleware/cache-lookup.ts

@@ -101,6 +101,7 @@ import { treeHasStreaming } from "./segment-resolution.js";
 import { loaderPins } from "../segment-resolution/loader-cache.js";
 import {
   fillSends,
+  interceptFillSkips,
   recordUse,
 } from "../segment-resolution/prefetch-deferral.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
@@ -127,6 +128,7 @@ import { ShellRecordUnavailableError } from "../../cache/shell-snapshot.js";
 import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
 import { paramsEqual } from "../params-util.js";
 import { requestHeaders } from "../../server/request-headers.js";
+import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
 // Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
@@ -207,6 +209,7 @@ async function* resolveFreshLoadersAndYield<TEnv>(
   resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment> {
   const loaderStart = performance.now();
+  entries = entries.filter((e) => !interceptFillSkips(ctx, e.shortCode));
 
   if (ctx.isFullMatch) {
     if (resolveLoadersOnly) {
@@ -347,14 +350,8 @@ async function* yieldFromStore<TEnv>(
     !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
   const resendRouteSegments = replaceable === true && ctx.isAction;
   for (const segment of segments) {
-    if (
-      !ctx.isFullMatch &&
-      ctx.clientSegmentSet.has(segment.id) &&
-      // A stored intercept segment is re-sent, as on the runtime cache path:
-      // its loaders run (handleCacheHitIntercept), and a kept (null) one would
-      // be left out of the response with its loaders' new data.
-      !segment.namespace?.startsWith("intercept:")
-    ) {
+    if (interceptFillSkips(ctx, segment)) continue;
+    if (!ctx.isFullMatch && ctx.clientSegmentSet.has(segment.id)) {
       // A fill keeps it (fillSends); otherwise it is sent again when the
       // params changed or an action re-sends the route's own segments.
       const sends =
@@ -912,10 +909,15 @@ export function withCacheLookup<TEnv>(
     const entryRevalidateMap = canCheckSegmentRevalidation
       ? buildEntryRevalidateMap(ctx.entries)
       : undefined;
+    const searchChanged =
+      ctx.prevUrl.search !== ctx.url.search ||
+      pipelineReqCtx?._visitorMoved === true;
+    const routeParamsChanged = !paramsEqual(ctx.matched.params, ctx.prevParams);
 
     yield* liveSegments;
 
     for (const segment of cacheResult.segments) {
+      if (interceptFillSkips(ctx, segment)) continue;
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -932,12 +934,8 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      if (segment.namespace?.startsWith("intercept:")) {
-        yield segment;
-        continue;
-      }
-
-      // A fill keeps a held segment outright (fillSends).
+      // A fill keeps a held segment outright (fillSends), an intercept's
+      // included.
       if (
         fillSends(ctx.handlerContext, segment.id, ctx.clientSegmentSet) ===
         false
@@ -946,14 +944,12 @@ export function withCacheLookup<TEnv>(
         yield segment;
         continue;
       }
+      if (isInterceptSegment(segment)) {
+        yield segment;
+        continue;
+      }
 
       const entryInfo = entryRevalidateMap?.get(segment.id);
-
-      const searchChanged = ctx.prevUrl.search !== ctx.url.search;
-      const routeParamsChanged = !paramsEqual(
-        ctx.matched.params,
-        ctx.prevParams,
-      );
       const shouldDefaultRevalidate =
         (searchChanged || routeParamsChanged) &&
         (segment.type === "route" ||

package/src/router/match-middleware/intercept-resolution.ts

@@ -29,7 +29,7 @@
  *         v
  *   +----------------------+    +----------------------------+
  *   | Fresh intercept?     |yes>| resolveInterceptEntry()    |
- *   | (!cacheHit or        |    | - middleware, loaders, UI  |
+ *   | (!cacheHit or        |    | - loaders, UI              |
  *   |  no intercept segs)  |    +----------------------------+
  *   +----------------------+              |
  *         | no                            v
@@ -59,7 +59,7 @@
  *
  * 1. Fresh intercept (no cache):
  *    - Full resolution of intercept entry
- *    - Resolves middleware, loaders, and component
+ *    - Resolves loaders and component
  *    - Yields all intercept segments
  *
  * 2. Cache hit with intercept:
@@ -106,6 +106,7 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog } from "../logging.js";
+import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 /**
  * Creates intercept resolution middleware
@@ -151,7 +152,7 @@ export function withInterceptResolution<TEnv>(
 
     if (skipInterceptResolution) {
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
-        await handleCacheHitIntercept(ctx, state, segments);
+        yield* await handleCacheHitIntercept(ctx, state, segments);
       }
       if (ms) {
         ms.metrics.push({
@@ -212,77 +213,57 @@ export function withInterceptResolution<TEnv>(
   };
 }
 
+/**
+ * A cache or prerender hit that carries the intercept's slot: the slot keeps
+ * its stored component and layout, and its loaders, never stored, resolve as
+ * loader segments of it. Returns those segments for the caller to yield.
+ */
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   segments: ResolvedSegment[],
-): Promise<void> {
-  if (!ctx.interceptResult) return;
+): Promise<ResolvedSegment[]> {
+  if (!ctx.interceptResult) return [];
 
   const { resolveInterceptLoadersOnly } = getRouterContext<TEnv>();
 
   const slotName = ctx.interceptResult.intercept.slotName;
 
-  const interceptSegments = segments.filter((s) =>
-    s.namespace?.startsWith("intercept:"),
-  );
-  state.interceptSegments = interceptSegments;
-
-  if (resolveInterceptLoadersOnly) {
-    const Store = ctx.Store;
-    const freshLoaderResult = await Store.run(() =>
-      resolveInterceptLoadersOnly(
-        ctx.interceptResult!.intercept,
-        ctx.interceptResult!.entry,
-        ctx.matched.params,
-        ctx.handlerContext,
-        true, // belongsToRoute
-        {
-          clientSegmentIds: ctx.clientSegmentSet,
-          prevParams: ctx.prevParams,
-          request: ctx.request,
-          prevUrl: ctx.prevUrl,
-          nextUrl: ctx.url,
-          routeKey: ctx.routeKey,
-          actionContext: ctx.actionContext,
-          stale: ctx.stale,
-        },
-      ),
-    );
+  const cachedSlot = segments.filter(isInterceptSegment);
+  // A record stored before 0.25.0 carries the loaders' aggregate on the slot;
+  // the loader segments below replace it. Build versions hash the router's
+  // code, so an upgrade does not read one; a custom store that ignores
+  // versions can.
+  for (const slot of cachedSlot) {
+    delete slot.loaderDataPromise;
+    delete slot.loaderIds;
+  }
 
-    if (freshLoaderResult) {
-      const interceptMainSegment = interceptSegments.find(
-        (s) => s.type === "parallel" && s.slot,
-      );
-      if (interceptMainSegment) {
-        interceptMainSegment.loaderDataPromise =
-          freshLoaderResult.loaderDataPromise;
-        interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
-        debugLog(
-          "matchPartial.intercept",
-          freshLoaderResult.loaderIds.length > 0
-            ? "cache hit with fresh intercept loaders"
-            : "cache hit, every intercept loader held",
+  const loaderSegments = resolveInterceptLoadersOnly
+    ? await ctx.Store.run(() =>
+        resolveInterceptLoadersOnly(
+          ctx.interceptResult!.intercept,
+          ctx.interceptResult!.entry,
+          ctx.handlerContext,
+          true, // belongsToRoute
           {
-            routeName: ctx.localRouteName,
-            slotName,
+            clientSegmentIds: ctx.clientSegmentSet,
+            prevParams: ctx.prevParams,
+            request: ctx.request,
+            prevUrl: ctx.prevUrl,
+            nextUrl: ctx.url,
+            routeKey: ctx.routeKey,
+            actionContext: ctx.actionContext,
+            stale: ctx.stale,
           },
-        );
-      }
-    } else {
-      debugLog(
-        "matchPartial.intercept",
-        "cache hit, intercept has no loaders",
-        {
-          routeName: ctx.localRouteName,
-          slotName,
-        },
-      );
-    }
-  }
-
+        ),
+      )
+    : [];
+  const interceptSegments = [...cachedSlot, ...loaderSegments];
+  state.interceptSegments = interceptSegments;
   state.slots[slotName] = {
     active: true,
     segments: interceptSegments,
   };
+  return loaderSegments;
 }

package/src/router/match-result.ts

@@ -109,10 +109,14 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import { isPlaceholder } from "../types/segments.js";
+import { loaderParentId } from "../browser/react/filter-segment-order.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
 import { appendMetric } from "./metrics.js";
-import { collectInterceptTargetNames } from "./intercept-resolution.js";
+import {
+  collectInterceptTargetNames,
+  interceptSegmentIds,
+} from "./intercept-resolution.js";
 
 export async function collectSegments(
   generator: AsyncGenerator<ResolvedSegment>,
@@ -192,6 +196,25 @@ function deduplicateLoaderSegments(
   return { segments: result, removedIds };
 }
 
+/**
+ * An intercept's `matched`: the client's ids without any of the slot's (its
+ * id and every loader segment on it, another intercept's into the same slot
+ * included), then the slot's (interceptSegmentIds). One order for the
+ * prefetch, its fill, an action and a revisit: a fill whose `matched` differs
+ * from its tree's is rendered as a new tree (browser/partial-update.ts
+ * fillHoles).
+ */
+function interceptMatched(
+  clientIds: readonly string[],
+  slotIds: readonly string[],
+): string[] {
+  // loaderParentId leaves a non-loader id as it is: the slot's own id goes too.
+  return [
+    ...clientIds.filter((id) => loaderParentId(id) !== slotIds[0]),
+    ...slotIds,
+  ];
+}
+
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
@@ -223,7 +246,13 @@ export function buildMatchResult<TEnv>(
   } else {
     allIds = ctx.interceptResult
       ? ctx.clientSegmentIds.length > 0
-        ? [...ctx.clientSegmentIds, ...state.interceptSegments.map((s) => s.id)]
+        ? interceptMatched(
+            ctx.clientSegmentIds,
+            interceptSegmentIds(
+              ctx.interceptResult.entry,
+              ctx.interceptResult.intercept,
+            ),
+          )
         : allSegments.map((s) => s.id)
       : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];