@rangojs/router 0.24.3 → 0.25.0

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

@@ -43,6 +43,7 @@ import {
   deferUnit,
   fillSends,
   getPrefetchDeferral,
+  interceptFillSkips,
   registerDeferredLoader,
 } from "./prefetch-deferral.js";
 import {
@@ -58,6 +59,7 @@ import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { isLayoutLoaderCopy } from "../../client-urls/layout-loader-copies.js";
 import { getRouterContext } from "../router-context.js";
 import { observeEvent, observeSegmentHandler } from "../instrument.js";
+import { withReverseScope } from "../handler-context.js";
 import { runInSegmentTagScope } from "../../cache/cache-tag.js";
 import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import {
@@ -156,7 +158,7 @@ const deferredLoaderRuns = new WeakMap<ResolvedSegment, () => unknown>();
  * awaits; a streamed handler that reads the loader later is not seen, and
  * that loader runs again in the fill.
  */
-function deliverStartedLoaders<TEnv>(
+export function deliverStartedLoaders<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   segments: ResolvedSegment[],
 ): void {
@@ -180,14 +182,51 @@ function deliverStartedLoaders<TEnv>(
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve loaders with revalidation awareness (for partial rendering).
- * Returns both segments to render AND all matched segment IDs.
+ * Whose loaders a resolveOwnerLoaders call resolves: a route entry's (or the
+ * entry its loaders are inherited into), or an intercept's, whose loaders are
+ * loader segments of its slot (`${parent}.${slot}D${i}.${$$id}`).
  */
-export async function resolveLoadersWithRevalidation<TEnv>(
+export interface LoaderOwner {
+  readonly loaders: readonly LoaderEntry[];
+  /** The segments' namespace: the entry id, or `intercept:${routeName}`. */
+  readonly namespace: string;
+  /** The segment id the loader ids extend and the handle pushes file under. */
+  readonly segmentPrefix: string;
+  /** Where a loader error renders (wrapLoaderPromise). */
+  readonly boundary: EntryData;
+  /**
+   * resolveLoaderData's PPR bake/seed key for every loader (loader-cache.ts).
+   * False for an intercept: never a document.
+   */
+  readonly bakeLane: boolean;
+  readonly traceSource: "loader" | "intercept-loader";
+}
+
+/** A route entry as a LoaderOwner, under `shortCodeOverride` when inherited. */
+export function ownerOf(
   entry: EntryData,
+  shortCodeOverride?: string,
+): LoaderOwner {
+  return {
+    loaders: entry.loader ?? [],
+    namespace: entry.id,
+    segmentPrefix: shortCodeOverride ?? entry.shortCode,
+    boundary: entry,
+    bakeLane: !entryLoadingMasksLoaders(entry.loading),
+    traceSource: "loader",
+  };
+}
+
+/**
+ * The partial lane's one loader funnel: each loader is a segment, run when
+ * the client lacks it, asked its revalidate() when held, kept outright in a
+ * fill (fillSends), deferred in a prefetch that defers it (defersLoader).
+ */
+export async function resolveOwnerLoaders<TEnv>(
+  owner: LoaderOwner,
   ctx: HandlerContext<any, TEnv>,
   belongsToRoute: boolean,
-  clientSegmentIds: Set<string>,
+  clientSegmentIds: ReadonlySet<string>,
   prevParams: Record<string, string>,
   request: Request,
   prevUrl: URL,
@@ -195,13 +234,12 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   routeKey: string,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
-  shortCodeOverride?: string,
   stale?: boolean,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
-  const loaderEntries = entry.loader ?? [];
+  const loaderEntries = owner.loaders;
   if (loaderEntries.length === 0) return { segments: [], matchedIds: [] };
 
-  const shortCode = shortCodeOverride ?? entry.shortCode;
+  const shortCode = owner.segmentPrefix;
 
   // Pin `_currentSegmentId` to the OWNING entry before the kickoffs below —
   // createLoaderExecutor captures it synchronously for ctx.use(Handle) push
@@ -238,7 +276,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
                   segmentId,
                   segmentType: "loader",
                   belongsToRoute,
-                  source: "loader",
+                  source: owner.traceSource,
                   defaultShouldRevalidate: true,
                   finalShouldRevalidate: true,
                   reason: "new-segment",
@@ -249,7 +287,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
 
             const dummySegment: ResolvedSegment = {
               id: segmentId,
-              namespace: entry.id,
+              namespace: owner.namespace,
               type: "loader",
               index,
               component: null,
@@ -268,14 +306,14 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               prevUrl,
               nextUrl,
               revalidations: loaderRevalidateFns.map((fn, j) => ({
-                name: `loader-revalidate${j}`,
+                name: `${owner.traceSource}-revalidate${j}`,
                 fn,
               })),
               routeKey,
               context: ctx,
               actionContext,
               stale,
-              traceSource: "loader",
+              traceSource: owner.traceSource,
               held: clientSegmentIds,
             });
           },
@@ -300,7 +338,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // Outside capture the key only activates the _shellLoaderSeed overlay,
   // 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 bakeLane = owner.bakeLane;
 
   const kickoff = (
     loaderEntry: LoaderEntry,
@@ -319,6 +357,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
           bakeLane || loaderEntry.bake === true ? segmentId : null,
         ),
       loaderId,
+      loaderEntry.reverseScope,
     );
   const start = (
     loaderEntry: LoaderEntry,
@@ -327,7 +366,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   ) =>
     deps.wrapLoaderPromise(
       kickoff(loaderEntry, segmentId, loaderId),
-      entry,
+      owner.boundary,
       segmentId,
       ctx.pathname,
       errorContext,
@@ -338,7 +377,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
     ({ loaderEntry, loader, segmentId, index }) => {
       const base = {
         id: segmentId,
-        namespace: entry.id,
+        namespace: owner.namespace,
         type: "loader" as const,
         index,
         component: null,
@@ -411,8 +450,8 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
         seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
       );
     if (!allAlreadySeen) {
-      const { segments, matchedIds } = await resolveLoadersWithRevalidation(
-        entry,
+      const { segments, matchedIds } = await resolveOwnerLoaders(
+        ownerOf(entry, shortCodeOverride),
         context,
         belongsToRoute,
         clientSegmentIds,
@@ -423,7 +462,6 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
         routeKey,
         deps,
         actionContext,
-        shortCodeOverride,
         stale,
       );
       for (const seg of segments) {
@@ -454,8 +492,8 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
         entry.loader.length > 0 &&
         Object.keys(layoutEntry.parallel).length > 0
       ) {
-        const inherited = await resolveLoadersWithRevalidation(
-          entry,
+        const inherited = await resolveOwnerLoaders(
+          ownerOf(entry, layoutEntry.shortCode),
           context,
           childBelongsToRoute,
           clientSegmentIds,
@@ -466,7 +504,6 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
           routeKey,
           deps,
           actionContext,
-          layoutEntry.shortCode,
           stale,
         );
         for (const seg of inherited.segments) {
@@ -594,10 +631,11 @@ async function resolveParallelSlotComponent<TEnv>(args: {
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         parallelId;
       handlerRan = true;
+      const slotContext = withReverseScope(context, parallelEntry.reverseScope);
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function"
-            ? runInSegmentTagScope(parallelId, handler, context)
+            ? runInSegmentTagScope(parallelId, handler, slotContext)
             : handler;
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, parallelId);
@@ -616,7 +654,7 @@ async function resolveParallelSlotComponent<TEnv>(args: {
       } else {
         component =
           typeof handler === "function"
-            ? await runInSegmentTagScope(parallelId, handler, context)
+            ? await runInSegmentTagScope(parallelId, handler, slotContext)
             : handler;
       }
     }
@@ -697,8 +735,8 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     // emitted either before or after the slot segment per loaderOrder.
     const resolveSlotLoaders = async () => {
       if (resolvedParallelEntries.has(parallelEntry.id)) return;
-      const loaderResult = await resolveLoadersWithRevalidation(
-        parallelEntry,
+      const loaderResult = await resolveOwnerLoaders(
+        ownerOf(parallelEntry, entry.shortCode),
         context,
         belongsToRoute,
         clientSegmentIds,
@@ -709,7 +747,6 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         routeKey,
         deps,
         actionContext,
-        entry.shortCode,
         stale,
       );
       segments.push(...loaderResult.segments);
@@ -1095,8 +1132,8 @@ export async function resolveSegmentWithRevalidation<TEnv>(
 
   const belongsToRoute = entry.type === "route";
 
-  const loaderResult = await resolveLoadersWithRevalidation(
-    entry,
+  const loaderResult = await resolveOwnerLoaders(
+    ownerOf(entry),
     context,
     belongsToRoute,
     clientSegmentIds,
@@ -1107,7 +1144,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     routeKey,
     deps,
     actionContext,
-    undefined,
     stale,
   );
   segments.push(...loaderResult.segments);
@@ -1266,8 +1302,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
 
-  const loaderResult = await resolveLoadersWithRevalidation(
-    orphan,
+  const loaderResult = await resolveOwnerLoaders(
+    ownerOf(orphan),
     context,
     belongsToRoute,
     clientSegmentIds,
@@ -1278,7 +1314,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     routeKey,
     deps,
     actionContext,
-    undefined,
     stale,
   );
   segments.push(...loaderResult.segments);
@@ -1292,8 +1327,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     parentRouteEntry.loader.length > 0 &&
     Object.keys(orphan.parallel).length > 0
   ) {
-    const inheritedResult = await resolveLoadersWithRevalidation(
-      parentRouteEntry,
+    const inheritedResult = await resolveOwnerLoaders(
+      ownerOf(parentRouteEntry, orphan.shortCode),
       context,
       belongsToRoute,
       clientSegmentIds,
@@ -1304,7 +1339,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       routeKey,
       deps,
       actionContext,
-      orphan.shortCode,
       stale,
     );
     // Tag as inherited so buildMatchResult can deduplicate when safe
@@ -1491,6 +1525,11 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   latchPprHeaderScopeForEntries(entries, routeKey);
 
   const telemetry = getRouterContext()?.telemetry;
+  const fillMatch = {
+    handlerContext: context,
+    isIntercept: !!interceptResult,
+    clientSegmentSet,
+  };
 
   for (const entry of entries) {
     if (entry.type === "route" && interceptResult) {
@@ -1508,6 +1547,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
       }
       continue;
     }
+    if (interceptFillSkips(fillMatch, entry.shortCode)) continue;
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
     // Same latch as resolveAllSegments (fresh.ts), route-level cache() included.

package/src/router/segment-resolution.ts

@@ -14,7 +14,6 @@ export {
   resolveLoadersOnly,
 } from "./segment-resolution/fresh.js";
 export {
-  resolveLoadersWithRevalidation,
   resolveLoadersOnlyWithRevalidation,
   buildEntryRevalidateMap,
   resolveParallelSegmentsWithRevalidation,

package/src/router/segment-wrappers.ts

@@ -6,6 +6,7 @@ import type {
 } from "../types";
 import type { SegmentResolutionDeps } from "./types.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
+import type { RevalidationContext } from "./router-context.js";
 
 import {
   resolveAllSegments as _resolveAllSegments,
@@ -96,19 +97,15 @@ export interface SegmentWrappers<TEnv = any> {
     context: HandlerContext<any, TEnv>,
     belongsToRoute?: boolean,
     revalidationContext?: any,
-    options?: { skipMiddleware?: boolean },
+    options?: { background?: boolean },
   ) => Promise<ResolvedSegment[]>;
   resolveInterceptLoadersOnly: (
     interceptEntry: InterceptEntry,
     parentEntry: EntryData,
-    params: Record<string, string>,
     context: HandlerContext<any, TEnv>,
-    belongsToRoute?: boolean,
-    revalidationContext?: any,
-  ) => Promise<{
-    loaderDataPromise: Promise<any[]> | any[];
-    loaderIds: string[];
-  } | null>;
+    belongsToRoute: boolean,
+    revalidationContext: RevalidationContext,
+  ) => Promise<ResolvedSegment[]>;
 }
 
 /**
@@ -250,7 +247,7 @@ export function createSegmentWrappers<TEnv = any>(
     context: HandlerContext<any, TEnv>,
     belongsToRoute: boolean = true,
     revalidationContext?: any,
-    options?: { skipMiddleware?: boolean },
+    options?: { background?: boolean },
   ): ReturnType<typeof _resolveInterceptEntry> {
     return _resolveInterceptEntry(
       interceptEntry,
@@ -267,15 +264,13 @@ export function createSegmentWrappers<TEnv = any>(
   function resolveInterceptLoadersOnly(
     interceptEntry: InterceptEntry,
     parentEntry: EntryData,
-    params: Record<string, string>,
     context: HandlerContext<any, TEnv>,
-    belongsToRoute: boolean = true,
-    revalidationContext: any,
+    belongsToRoute: boolean,
+    revalidationContext: RevalidationContext,
   ): ReturnType<typeof _resolveInterceptLoadersOnly> {
     return _resolveInterceptLoadersOnly(
       interceptEntry,
       parentEntry,
-      params,
       context,
       belongsToRoute,
       segmentDeps,

package/src/router/substitute-pattern-params.ts

@@ -20,8 +20,9 @@ import { parsePattern } from "./parse-pattern.js";
  *                         omit when absent.
  *
  * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
- * helper), and `useReverse()` (client hook). The behavior must stay
- * identical across all three call sites.
+ * helper), `useReverse()` (client hook), and the include() mount fill of
+ * `useHref()` and relative `useRouter().push`. The behavior must stay
+ * identical across all of them.
  */
 export function substitutePatternParams(
   pattern: string,
@@ -73,3 +74,37 @@ export function substitutePatternParams(
   if (hasTrailingSlash && !result.endsWith("/")) result += "/";
   return result;
 }
+
+/**
+ * Join an include() mount with a mount-relative pattern. The mount is the
+ * include PATTERN (`/:locale?`), so the result is a pattern too.
+ *
+ * `pattern === "/"` is the index of the local module: under a non-root mount
+ * it collapses, so `/` under `/blog` becomes `/blog`, not `/blog/`. This
+ * matches `ctx.reverse(".index")` and, for a mount without a trailing slash,
+ * the route pattern the server registers (applyUrlPrefix in
+ * urls/path-helper.ts).
+ */
+export function joinMount(mount: string, pattern: string): string {
+  if (pattern === "/") {
+    if (mount === "" || mount === "/") return "/";
+    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  }
+  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
+  return normalizedMount + pattern;
+}
+
+/**
+ * Whether two matches of an include() mount pattern are in the same instance
+ * of the include: `/en/...` and `/de/...` under `/:locale` are not.
+ */
+export function sameMountInstance(
+  mount: string,
+  a: Readonly<Record<string, string>>,
+  b: Readonly<Record<string, string>>,
+): boolean {
+  return (
+    substitutePatternParams(mount, a, mount) ===
+    substitutePatternParams(mount, b, mount)
+  );
+}

package/src/router/tracing.ts

@@ -24,8 +24,8 @@
  * registry; do not call traceSpan directly from new code.
  *
  * Phase coverage (all via observePhase): rango.request (span-only; handler:total
- * metered directly), rango.middleware (span-only incl. intercept middleware;
- * pre/post metered directly), rango.action (action:<id>; server-action
+ * metered directly), rango.middleware (span-only; pre/post metered directly),
+ * rango.action (action:<id>; server-action
  * execution, JS + no-JS/PE), rango.loader (loader:<id>; single metering site at
  * useLoader, plus the fetchable path), rango.handler (span-only, one per segment
  * route/layout handler execution; the handler:<id> perf metric is owned by the

package/src/router.ts

@@ -276,14 +276,8 @@ export function createRouter<TEnv = any>(
   );
 
   // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes). Clamps to a
-  // non-negative integer and guards non-finite (NaN/Infinity) inputs so a
-  // malformed `Cache-Control: max-age=NaN` can never reach the wire.
-  const resolvedPrefetchCacheTTL = resolvePrefetchCacheTTL(
-    prefetchCacheTTLOption,
-  );
-  const prefetchCacheTTL = resolvedPrefetchCacheTTL.ms;
-  const prefetchCacheControl: string | false =
-    resolvedPrefetchCacheTTL.cacheControl;
+  // non-negative integer and guards non-finite (NaN/Infinity) inputs.
+  const prefetchCacheTTL = resolvePrefetchCacheTTL(prefetchCacheTTLOption).ms;
 
   // Resolve client-side prefetch limits (in-memory cache size and queue
   // concurrency). Both are positive-integer counts; sub-1/non-finite inputs
@@ -1153,7 +1147,6 @@ export function createRouter<TEnv = any>(
     cacheProfiles: resolvedCacheProfiles,
 
     // Expose prefetch cache settings
-    prefetchCacheControl,
     prefetchCacheTTL,
     prefetchCacheSize,
     prefetchConcurrency,

package/src/rsc/full-payload.ts

@@ -15,6 +15,7 @@ import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { Theme } from "../theme/types.js";
 import {
+  pathKey,
   rendersForSharedAudience,
   rewriteTrail,
   visitorUrl,
@@ -42,7 +43,7 @@ export function buildFullPayload(
 ): RscPayload {
   return {
     metadata: {
-      pathname: renderedLocation(reqCtx, url).pathname,
+      ...payloadLocation(reqCtx, url),
       routerId: ctx.router.id,
       basename: ctx.router.basename,
       segments: attachTransitionWhen(m.segments, reqCtx),
@@ -95,7 +96,8 @@ export function buildFullPayload(
  * bar) agree on `usePathname()` and `useSearchParams()`. A render other
  * visitors may be served shows `url`, the target, as a direct visit does: a
  * shell capture, and a render the document cache stores (its key is the
- * target). A render that shows the visitor's URL marks
+ * target), except a visitor-keyed shell capture, whose key covers the
+ * visitor's URL. Any other render that shows the visitor's URL marks
  * `_payloadVisitorLocation`, and the document cache does not store it.
  */
 export function renderedLocation(
@@ -104,6 +106,7 @@ export function renderedLocation(
         RequestContext<any>,
         | "_variables"
         | "_shellCaptureRun"
+        | "_shellCaptureForVisitor"
         | "_documentCacheRender"
         | "_payloadVisitorLocation"
         | "res"
@@ -111,13 +114,32 @@ export function renderedLocation(
     | undefined,
   url: URL,
 ): URL {
-  if (!reqCtx || !rewriteTrail(reqCtx) || rendersForSharedAudience(reqCtx)) {
-    return url;
+  if (!reqCtx || !rewriteTrail(reqCtx)) return url;
+  if (rendersForSharedAudience(reqCtx)) {
+    return reqCtx._shellCaptureForVisitor ? visitorUrl(reqCtx, url) : url;
   }
   reqCtx._payloadVisitorLocation = true;
   return visitorUrl(reqCtx, url);
 }
 
+/**
+ * A payload's `pathname` (renderedLocation) and, when middleware rewrote the
+ * request, `rewriteTarget`: the path and search the route rendered (the
+ * trail's last URL). The browser keeps it per history entry and sends it
+ * back as `_rsc_rt`, so the next request from the page diffs against the
+ * route that rendered it (navigation-snapshot.ts resolveNavigation, #1144).
+ */
+export function payloadLocation(
+  reqCtx: Parameters<typeof renderedLocation>[0],
+  url: URL,
+): { pathname: string; rewriteTarget?: string } {
+  const pathname = renderedLocation(reqCtx, url).pathname;
+  const trail = rewriteTrail(reqCtx);
+  return trail
+    ? { pathname, rewriteTarget: pathKey(new URL(trail[trail.length - 1]!)) }
+    : { pathname };
+}
+
 /**
  * The theme a document payload carries as `metadata.initialTheme` (the
  * ThemeProvider's first state), read with no identity guard: it is the