@rangojs/router 0.24.4 → 0.26.0

package/src/segment-system.tsx

@@ -11,7 +11,7 @@ import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { isRenderableLoading } from "./types/boundaries.js";
 import { isPlaceholder } from "./types/segments.js";
-import { decodeLoaderResults } from "./decode-loader-results.js";
+import { decodeLoaderResults, isLoaderError } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
 import {
@@ -26,10 +26,8 @@ import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import { getBoundaryContent } from "./segment-boundary-content.js";
 import { asStream } from "./browser/defer.js";
-import {
-  buildLoaderPromise,
-  getMemoizedLoaderPromise,
-} from "./segment-loader-promise.js";
+import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
+import { loaderParentId } from "./browser/react/filter-segment-order.js";
 import {
   auditSegmentElement,
   finishTreeAudit,
@@ -106,6 +104,60 @@ export function restoreParallelLoaderMarkers(
   return nextSegments ?? segments;
 }
 
+/**
+ * An intercept's loaders arrive as loader segments of its slot
+ * (`${slot.id}D${i}.${$$id}`, router/intercept-resolution.ts). Folded back
+ * onto the slot before the tree walk, as one aggregate the slot's
+ * LoaderBoundary reads (client.tsx renderSlotContent): walked as loaders they
+ * would attach to the slot's parent, whose subtree (the page under the modal)
+ * would change shape and remount. Any other loader segment passes through; a
+ * list with nothing to fold is returned as it is, synchronously.
+ * The slot is a new object (rule 6, suspense-contract.md); its aggregate is
+ * memoized on the loaders' data (rule 1). Settled before the commit when
+ * nothing in it is deferred and the slot has no loading() or the lane settles
+ * loaders (forceAwait, action): a modal with no loading() commits whole, as
+ * when the server awaited its loaders.
+ */
+export function foldInterceptLoaders(
+  segments: ResolvedSegment[],
+  settleLoaders: boolean,
+): ResolvedSegment[] | Promise<ResolvedSegment[]> {
+  const loadersBySlot = new Map<string, ResolvedSegment[]>();
+  const rest: ResolvedSegment[] = [];
+  for (const segment of segments) {
+    // Only a slot's loader has a slot id, `${shortCode}.@${name}`, as parent.
+    const parentId =
+      segment.type === "loader" && segment.id.includes(".@")
+        ? loaderParentId(segment.id)
+        : "";
+    if (parentId.includes(".@")) pushToGroup(loadersBySlot, parentId, segment);
+    else rest.push(segment);
+  }
+  if (loadersBySlot.size === 0) return segments;
+  const fold = async (
+    slot: ResolvedSegment,
+    loaders: ResolvedSegment[],
+  ): Promise<ResolvedSegment> => {
+    const aggregate = getMemoizedLoaderPromise(loaders);
+    return {
+      ...slot,
+      loaderIds: loaders.map((l) => l.loaderId!),
+      loaderDataPromise: settlesLoaders(
+        loaders,
+        settleLoaders || !isRenderableLoading(slot.loading),
+      )
+        ? await aggregate
+        : aggregate,
+    };
+  };
+  return Promise.all(
+    rest.map((slot) => {
+      const loaders = loadersBySlot.get(slot.id);
+      return loaders ? fold(slot, loaders) : slot;
+    }),
+  );
+}
+
 /**
  * Options for renderSegments
  */
@@ -252,19 +304,21 @@ function wrapDefaultOutletContent(
  *
  * The settled results also go through decodeLoaderResults here: a settled
  * redirect()/notFound() (or an error with an errorBoundary() fallback) must
- * be resolved to its node while the tree is built, exactly as the
- * forceAwait/action lanes do, because the read-site throw has no boundary on
- * the document lane — flagged content renders without Suspense and a layout
- * reader sits above every boundary, so the throw is a Fizz shell error (500).
- * `settledFallback` is that node; the caller plants it and, for a redirect,
- * replaces the whole page (an ancestor reading the loader would still throw).
+ * be resolved to its node while the tree is built, because the read-site
+ * throw has no boundary on the document lane — flagged content renders
+ * without Suspense and a layout reader sits above every boundary, so the
+ * throw is a Fizz shell error (500). `settledFallback` is that node; the
+ * caller plants it and, for a redirect, replaces the whole page (an ancestor
+ * reading the loader would still throw).
  *
- * `settle` is the forceAwait/action lane of a loader set that holds a
- * deferred loader (`prefetch: false`, see hasDeferred): every other loader is
- * settled like a flagged one, so the commit stays whole for them, and the
- * deferred one keeps its hole for the read site to suspend on. A settled
- * error with no boundary is left to the read site there, where the aggregate
- * lane it replaces would have thrown it.
+ * `settle` is every client lane that commits whole (forceAwait: back/forward,
+ * a cached or fully-prefetched click, stale revalidation, leaving an
+ * intercept; and the action lane): every loader but a deferred one
+ * (`prefetch: false`, which keeps its hole for the read site to suspend on)
+ * is settled like a flagged one, so the commit shows no fallback. A loader
+ * error is left to its read site there, its errorBoundary() fallback riding
+ * the throw, as on a navigation: the nearest boundary to the read catches it
+ * (#1129, dc-t65). notFound()/redirect() keep their build-time node.
  */
 async function buildLoaderStreams(
   loaders: ResolvedSegment[],
@@ -283,34 +337,31 @@ async function buildLoaderStreams(
       const value = await l.loaderData;
       streams[l.loaderId!] = value;
       if (l.awaitBeforeFlush) (awaitedIds ??= []).push(l.loaderId!);
+      if (settle && isLoaderError(value)) continue;
       (settledIds ??= []).push(l.loaderId!);
       (settledValues ??= []).push(value);
     } else {
       streams[l.loaderId!] = l.loaderData;
     }
   }
-  let settledFallback: ReactNode | undefined;
-  if (settledIds) {
-    try {
-      settledFallback =
-        decodeLoaderResults(settledValues!, settledIds).errorFallback ??
-        undefined;
-    } catch (error) {
-      if (!settle) throw error;
-    }
-  }
+  // Only the document lane can throw here: a settle lane left its errors out.
+  const settledFallback = settledIds
+    ? (decodeLoaderResults(settledValues!, settledIds).errorFallback ??
+      undefined)
+    : undefined;
   return { streams, awaitedIds, settledFallback };
 }
 
 /**
- * A loader set that holds a deferred loader (`prefetch: false`): its
+ * Whether a loader set is settled before the commit: its lane asks for it
+ * and nothing in it is deferred. A deferred loader's (`prefetch: false`)
  * `loaderData` is a hole (browser/defer.ts) the browser resolves when the
  * fill request lands (browser/partial-update.ts fillHoles), so no lane may
  * await the set as a whole. The
  * tree build would wait for a request that is only sent once it returns.
  */
-function hasDeferred(loaders: ResolvedSegment[]): boolean {
-  return loaders.some(isPlaceholder);
+function settlesLoaders(loaders: ResolvedSegment[], lane: boolean): boolean {
+  return lane && !loaders.some(isPlaceholder);
 }
 
 function isLoaderRedirectNode(node: ReactNode): boolean {
@@ -378,10 +429,9 @@ export async function renderSegments(
     transitionGatedOff,
   } = options || {};
   // forceAwait and action lanes settle loader data before the commit, except
-  // a set that holds a deferred loader (hasDeferred).
+  // a deferred loader (settlesLoaders), and hand each settled entry to its
+  // read (buildLoaderStreams). Only the document lane decodes in the build.
   const settleLoaders = !!(forceAwait || isAction);
-  const settleAll = (loaders: ResolvedSegment[]): boolean =>
-    settleLoaders && !hasDeferred(loaders);
 
   const segDebug = INTERNAL_RANGO_DEBUG;
   const segDebugStart = segDebug ? performance.now() : 0;
@@ -395,10 +445,16 @@ export async function renderSegments(
   }
 
   const temporalLazyRefs: Promise<any>[] = [];
-  const normalizedSegments = restoreParallelLoaderMarkers(segments);
-  const normalizedInterceptSegments = interceptSegments
-    ? restoreParallelLoaderMarkers(interceptSegments)
-    : undefined;
+  // Back/forward restores an intercept entry unsplit (navigation-bridge.ts).
+  // Awaited only when there is something to fold: no extra microtask.
+  let folded = foldInterceptLoaders(segments, settleLoaders);
+  if (folded instanceof Promise) folded = await folded;
+  const normalizedSegments = restoreParallelLoaderMarkers(folded);
+  let normalizedInterceptSegments =
+    interceptSegments && foldInterceptLoaders(interceptSegments, settleLoaders);
+  if (normalizedInterceptSegments instanceof Promise) {
+    normalizedInterceptSegments = await normalizedInterceptSegments;
+  }
 
   /**
    * Registers promises from lazy/async components for awaiting.
@@ -423,7 +479,9 @@ export async function renderSegments(
     );
   }
   // Separate segments by type, passing intercept segments for explicit injection
-  const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
+  const tree = [
+    ...segmentTreeWalk(normalizedSegments, normalizedInterceptSegments),
+  ];
   // Dev only: the wrapper chain per segment, compared with the previous
   // tree's (suspense-audit.ts, I5).
   const treeAudit =
@@ -452,7 +510,8 @@ export async function renderSegments(
   );
   // Render content segments as siblings
   let content: ReactNode = null;
-  for (const node of tree) {
+  for (let i = 0; i < tree.length; i++) {
+    const node = tree[i]!;
     invariant(
       node.segment.type === "layout" ||
         node.segment.type === "route" ||
@@ -504,7 +563,7 @@ export async function renderSegments(
             .join(",")
         : "";
     // Route identity the per-route remount used to provide; group routes key
-    // by the group instead and pass it to the error boundary as its resetKey.
+    // by the group instead and pass it to the error boundary's reset.
     const idParamsKey = paramStr ? `${id}-${paramStr}` : id;
     const key = clientGroup ? `cg:${clientGroup}` : idParamsKey;
 
@@ -630,14 +689,19 @@ export async function renderSegments(
     // lane changes remount the subtree (docs/tree-structure.md).
     if (loaderEntries.length > 0 || clientGroup) {
       nodeContent = createElement(StreamedLoaderErrorBoundary, {
-        resetKey: idParamsKey,
+        // Leaf first: tree.slice(i) is this segment and its ancestors. A
+        // read walks up the chain, so this boundary can catch an ancestor
+        // loader's marker and resets when that loader's data changes too.
+        reset: [
+          idParamsKey,
+          ...tree.slice(i).flatMap((n) => n.loaders.map((l) => l.loaderData)),
+        ],
         children: nodeContent,
       });
     }
 
     if (!clientGroup && loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
-      let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
       // SPIKE (streaming useLoader): per-loader streams for the boundary's
       // readers. MUST come from the individual loader refs — splitting the
       // aggregate client-side is wrong (Promise.all resolves at the slowest
@@ -648,19 +712,7 @@ export async function renderSegments(
       // for content-suspending routes (segment-loader-promise.ts).
       let boundaryLoaderStreams: Record<string, unknown> | undefined;
       let boundaryAwaitedLoaderIds: string[] | undefined;
-      if (settleAll(loaderEntries)) {
-        const awaitStart = segDebug ? performance.now() : 0;
-        boundaryLoaderData =
-          loaderDataPromise instanceof Promise
-            ? await loaderDataPromise
-            : loaderDataPromise;
-        if (segDebug) {
-          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
-            loaderIds,
-            ms: Math.round(performance.now() - awaitStart),
-          });
-        }
-      } else if (loaderEntries.length > 0) {
+      if (loaderEntries.length > 0) {
         let settledFallback: ReactNode | undefined;
         ({
           streams: boundaryLoaderStreams,
@@ -668,7 +720,9 @@ export async function renderSegments(
           settledFallback,
         } = await buildLoaderStreams(loaderEntries, settleLoaders));
         if (settledFallback !== undefined) {
-          if (isLoaderRedirectNode(settledFallback)) {
+          // Only the document lane replaces the whole page; a client lane
+          // keeps its layouts and the redirect replaces this segment's content.
+          if (!settleLoaders && isLoaderRedirectNode(settledFallback)) {
             content = settledFallback;
             break;
           }
@@ -687,7 +741,7 @@ export async function renderSegments(
           : LoaderBoundary,
         {
           key: `loader-boundary-${key}`,
-          loaderDataPromise: boundaryLoaderData,
+          loaderDataPromise,
           loaderIds,
           loaderStreams: boundaryLoaderStreams,
           awaitedLoaderIds: boundaryAwaitedLoaderIds,
@@ -726,35 +780,13 @@ export async function renderSegments(
       // per-loader UNDECODED results (possibly pending promises) through
       // OutletProvider.loaderStreams — useLoader suspends at the read site to
       // the nearest CONSUMER Suspense boundary. forceAwait (popstate, stale
-      // revalidation, fully-prefetched) and action lanes keep the blocking
-      // await so those commits stay whole with no fallback flash.
-      let loaderData: Record<string, any> = {};
+      // revalidation, fully-prefetched) and the action lane await each loader
+      // in buildLoaderStreams so those commits stay whole with no fallback
+      // flash, and still hand each entry to its read.
       let errorFallback: ReactNode = null;
       let loaderStreams: Record<string, unknown> | undefined;
       let awaitedLoaderIds: string[] | undefined;
-      if (settleAll(layoutLoaders)) {
-        const layoutAwaitStart = segDebug ? performance.now() : 0;
-        const resolvedData = await buildLoaderPromise(layoutLoaders);
-        if (segDebug) {
-          segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
-            loaderIds: layoutLoaderIds,
-            ms: Math.round(performance.now() - layoutAwaitStart),
-          });
-        }
-        const decodeStart = segDebug ? performance.now() : 0;
-        ({ loaderData, errorFallback } = decodeLoaderResults(
-          resolvedData,
-          layoutLoaderIds,
-        ));
-        if (segDebug) {
-          const decodeMs = Math.round(performance.now() - decodeStart);
-          if (decodeMs > 0) {
-            segDebugLog(`segment ${id}: loader results decoded`, {
-              ms: decodeMs,
-            });
-          }
-        }
-      } else if (layoutLoaders.length > 0) {
+      if (layoutLoaders.length > 0) {
         let settledFallback: ReactNode | undefined;
         ({
           streams: loaderStreams,
@@ -762,7 +794,9 @@ export async function renderSegments(
           settledFallback,
         } = await buildLoaderStreams(layoutLoaders, settleLoaders));
         if (settledFallback !== undefined) {
-          if (isLoaderRedirectNode(settledFallback)) {
+          // Only the document lane replaces the whole page; a client lane
+          // keeps its layouts and the redirect replaces this segment's content.
+          if (!settleLoaders && isLoaderRedirectNode(settledFallback)) {
             content = settledFallback;
             break;
           }
@@ -813,10 +847,11 @@ export async function renderSegments(
           // Flagged (ssr:false) delivery still holds: when every owned
           // loader paid the pre-flush await, settle the aggregate so
           // LoaderResolver decodes the array without a Flight-chunk use().
-          const settleParallelAggregate =
-            (settleLoaders ||
-              ownedLoaders.every((l) => l.awaitBeforeFlush === true)) &&
-            !hasDeferred(ownedLoaders);
+          const settleParallelAggregate = settlesLoaders(
+            ownedLoaders,
+            settleLoaders ||
+              ownedLoaders.every((l) => l.awaitBeforeFlush === true),
+          );
           if (settleParallelAggregate) {
             const parallelAwaitStart = segDebug ? performance.now() : 0;
             p.loaderDataPromise =
@@ -855,8 +890,6 @@ export async function renderSegments(
           content: outletContent,
           segment: node.segment,
           parallel: node.parallel,
-          loaderData:
-            Object.keys(loaderData).length > 0 ? loaderData : undefined,
           loaderStreams,
           awaitedLoaderIds,
           pending: outletPending,
@@ -974,20 +1007,6 @@ export async function renderSegments(
  * @param segments - Main segments from the route tree
  * @param interceptSegments - Optional intercept segments to inject
  */
-// Loader segment ids have the grammar `${parentId}D${index}.${loaderId}`.
-// parentId is the parent shortCode (M/L/P/R/C + digits, never "D") for normal
-// loaders, or `${shortCode}.${slotName}` for intercept-slot loaders, where the
-// slot name is user-controlled (`@${string}`) and may contain an uppercase "D"
-// (e.g. "@Detail"). Strip from the first `D<index>.` separator so the slot name
-// is preserved; splitting on a bare "D" mis-cut "@Detail" to "@" and silently
-// dropped the loader's data. The first-`D<index>.` strip is only correct because
-// slot names cannot contain "." -- assertValidSlotName (route-definition/
-// dsl-helpers.ts) rejects a "." at definition time, so a name like "@D3.foo"
-// (which WOULD mis-cut here) can never reach this function.
-function loaderParentId(loaderSegmentId: string): string {
-  return loaderSegmentId.replace(/D\d+\..*$/, "");
-}
-
 // Append a value to the array stored under `key`, creating the array on first
 // use. Single Map lookup (vs the has/get!().push double-lookup idiom).
 function pushToGroup<K, V>(map: Map<K, V[]>, key: K, value: V): void {
@@ -1032,18 +1051,14 @@ function* segmentTreeWalk(
     }
   }
 
-  // INTERCEPT SEGMENTS: Explicitly inject into parent's parallel array
-  // Intercept segments are passed separately for explicit handling
+  // INTERCEPT SEGMENTS: Explicitly inject into parent's parallel array.
+  // Their loaders are on the slot already (foldInterceptLoaders).
   if (interceptSegments && interceptSegments.length > 0) {
     for (const intercept of interceptSegments) {
       if (intercept.type === "parallel" && intercept.slot) {
         // Extract parent ID from intercept ID (e.g., "M4L0L0L2.@modal" → "M4L0L0L2")
         const parentId = intercept.id.split(".")[0];
         pushToGroup(parallelsByParent, parentId, intercept);
-      } else if (intercept.type === "loader") {
-        // Intercept loaders - extract parent from loader ID (slot name preserved)
-        const parentId = loaderParentId(intercept.id);
-        pushToGroup(loadersByParent, parentId, intercept);
       }
     }
   }
@@ -1062,15 +1077,6 @@ function* segmentTreeWalk(
     const parallel = parallelsByParent.get(segment.id) || [];
     const loaders = loadersByParent.get(segment.id) || [];
 
-    // Also include loaders from parallel segments (e.g., intercept loaders)
-    // These have parent IDs like "M9L0L1.@modal" which match the parallel segment ID
-    for (const p of parallel) {
-      const parallelLoaders = loadersByParent.get(p.id);
-      if (parallelLoaders) {
-        loaders.push(...parallelLoaders);
-      }
-    }
-
     yield { segment, parallel, loaders };
   }
 }

package/src/server/build-version-table.ts

@@ -25,33 +25,24 @@ let table: RouterVersionsTable | undefined = ROUTER_VERSIONS;
 /**
  * The versions a router serves with, in order:
  *
- * 1. `override`, a consumer-set `version` (createRouter or createRSCHandler):
- *    that exact value for both.
- * 2. The router's entry in the build table, else the whole-build entry.
- * 3. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
+ * 1. The router's entry in the build table, else the whole-build entry.
+ * 2. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
  */
 export function resolveRouterVersions(
   routerId: string | undefined,
-  override?: string,
 ): RouterVersions {
-  return (
-    resolveVersionsFrom(table, routerId, override) ?? uniformVersions(VERSION)
-  );
+  return resolveVersionsFrom(table, routerId) ?? uniformVersions(VERSION);
 }
 
 /**
  * The version an on-demand prerender overlay key carries: the router's data
  * version, because the overlay stores segment data, as the segment cache does
  * (a client-only deploy keeps both). The write side (`router.prerender`,
- * router.ts) and the read side (rsc/handler.ts) both call this with
- * `createRouter({ version })`, the only override the trigger can see, so they
- * cannot disagree; a `createRSCHandler({ version })` does not move it.
+ * router.ts) and the read side (rsc/handler.ts) both call this, so they
+ * cannot disagree.
  */
-export function resolvePrerenderVersion(
-  routerId: string | undefined,
-  routerVersion: string | undefined,
-): string {
-  return resolveRouterVersions(routerId, routerVersion).data;
+export function resolvePrerenderVersion(routerId: string | undefined): string {
+  return resolveRouterVersions(routerId).data;
 }
 
 /** The table gives some router a pair of its own. */
@@ -104,16 +95,13 @@ export type KeyVersion = keyof RouterVersions | null;
 
 /**
  * The `v/{version}/` prefix of a persistent store key, or "" for an
- * unversioned one. A store-level `version` is used for every versioned kind;
- * otherwise the version is the serving router's, read per operation because
- * the cache factory builds the store before the request context exists.
+ * unversioned one. The version is the serving router's, read per operation
+ * because the cache factory builds the store before the request context
+ * exists.
  */
-export function versionKeyPrefix(
-  storeVersion: string | undefined,
-  kind: KeyVersion,
-): string {
+export function versionKeyPrefix(kind: KeyVersion): string {
   if (kind === null) return "";
-  const version = storeVersion ?? getCacheVersions()[kind];
+  const version = getCacheVersions()[kind];
   return version ? `v/${version}/` : "";
 }