@rangojs/router 0.24.3 → 0.25.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/context.ts

@@ -92,6 +92,12 @@ export type EntryPropCommon = {
   cache?: EntryCacheConfig;
   /** URL prefix from include() scope, used for MountContext on client */
   mountPath?: string;
+  /**
+   * Include scope the entry's handler and loaders resolve `ctx.reverse(".name")`
+   * in. Structural entries only (layout, cache, parallel, wrapping
+   * middleware); a route resolves from its own name. See ReverseScope.
+   */
+  reverseScope?: ReverseScope;
   /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
   clientGroup?: string;
 };
@@ -163,6 +169,13 @@ export type LoaderEntry = {
    * (router/segment-resolution/prefetch-deferral.ts).
    */
   prefetch?: false;
+  /**
+   * The declaring layout's / parallel's / cache()'s include scope, for the
+   * loader body's `ctx.reverse(".name")` (its DSL kickoff carries it,
+   * runInsideLoaderScope). Unset on a route's loaders: they resolve from the
+   * route's name.
+   */
+  reverseScope?: ReverseScope;
 };
 
 /**
@@ -233,7 +246,6 @@ export type InterceptEntry = {
   slotName: `@${string}`; // e.g., "@modal"
   routeName: string; // e.g., "card"
   handler: ReactNode | Handler<any, any, any>;
-  middleware: MiddlewareFn<any, any>[];
   loader: LoaderEntry[];
   loading?: ReactNode | false;
   transition?: TransitionConfig;
@@ -327,10 +339,22 @@ export type EntryData =
       EntryPropSegments &
       EntryPropRender);
 
+/**
+ * Where an include()'s handler runs in the route tree. Hidden include-scope
+ * names (`$prefix_*`) derive from it, never from counter state, so build
+ * discovery and runtime expansion name every include the same (#1104).
+ */
+export interface IncludeScopePosition {
+  /** Sibling indexes of the enclosing includes, "_"-joined ("" at a mount root). */
+  scopePath?: string;
+  /** The scopePath tail since the nearest include that added a name segment. */
+  hiddenScopePath?: string;
+}
+
 /**
  * Tracked include info for build-time manifest generation
  */
-export interface TrackedInclude {
+export interface TrackedInclude extends IncludeScopePosition {
   prefix: string;
   fullPrefix: string;
   namePrefix?: string;
@@ -352,7 +376,7 @@ export type CachedHeaderScope = {
 /**
  * Context stored in AsyncLocalStorage
  */
-interface HelperContext {
+interface HelperContext extends IncludeScopePosition {
   manifest: Map<string, EntryData>;
   namespace: string;
   parent: EntryData | null;
@@ -597,6 +621,8 @@ export const getContext = (): {
           trackedIncludes: store.trackedIncludes,
           cacheProfiles: store.cacheProfiles,
           includeScope: store.includeScope,
+          scopePath: store.scopePath,
+          hiddenScopePath: store.hiddenScopePath,
           // cachedHeaderScope (and insideCacheScope) deliberately NOT copied —
           // the header guard's middleware exemption depends on the latch dying
           // with the funnel scope (see assertCachedHeaderWriteAllowed).
@@ -641,6 +667,8 @@ export const getContext = (): {
           rootScoped: store?.rootScoped,
           trackedIncludes: store?.trackedIncludes,
           cacheProfiles: store?.cacheProfiles,
+          scopePath: store?.scopePath,
+          hiddenScopePath: store?.hiddenScopePath,
         },
         callback,
       );
@@ -763,6 +791,54 @@ export function getRootScoped(): boolean {
   return store?.rootScoped ?? true;
 }
 
+/**
+ * The include scope a segment's dot-local `ctx.reverse(".name")` resolves in.
+ *
+ * One handler ctx serves every segment of a request and is built from the
+ * matched route's name (match-api.ts), so a parent module's layout resolved
+ * `.settings` from the matched CHILD module's prefix first: on
+ * `/acme/web/issues` the account layout's `.settings` hit the project
+ * module's route. Structural entries (layout, cache, parallel, wrapping
+ * middleware) and the loaders they declare capture the scope where the DSL
+ * defined them. Their handler gets a ctx whose `reverse` carries it
+ * (withReverseScope, router/handler-context.ts), and their loaders' DSL
+ * kickoff carries it in the loader scope (runInsideLoaderScope) for the
+ * loader ctx the executor builds. Global names and mount-param autofill do
+ * not change.
+ */
+export interface ReverseScope {
+  /** Include name prefix ("account.project"); undefined outside named includes. */
+  readonly prefix: string | undefined;
+  /** getRootScoped() where the segment was defined: bare-name fallback allowed. */
+  readonly rootScoped: boolean;
+}
+
+/** The ReverseScope of the DSL position being evaluated. */
+export function getReverseScope(): ReverseScope {
+  return { prefix: getNamePrefix(), rootScoped: getRootScoped() };
+}
+
+/**
+ * A createReverseFunction result (router/handler-context.ts). The internal
+ * 4th argument resolves dot names in a segment's ReverseScope instead of the
+ * route's name.
+ */
+export type ScopableReverse = (
+  name: string,
+  hrefParams?: Record<string, string>,
+  search?: Record<string, unknown>,
+  segmentScope?: ReverseScope,
+) => string;
+
+/** `reverse` with dot names resolved in `scope`, if any. */
+export function scopeReverse(
+  reverse: ScopableReverse,
+  scope: ReverseScope | undefined,
+): ScopableReverse {
+  if (scope === undefined) return reverse;
+  return (name, hrefParams, search) => reverse(name, hrefParams, search, scope);
+}
+
 /**
  * Stamp build-time scope identity onto a Static() definition at mount time.
  * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
@@ -909,6 +985,8 @@ interface LoaderScope {
   active: true;
   /** $$id of the DSL loader this scope resolves (runInsideLoaderScope). */
   loaderId?: string;
+  /** The declaring entry's ReverseScope (LoaderEntry.reverseScope). */
+  reverseScope?: ReverseScope;
 }
 const loaderScopeALS: AsyncLocalStorage<LoaderScope> = ((globalThis as any)[
   LOADER_SCOPE_KEY
@@ -1472,8 +1550,21 @@ export function assertCachedHeaderWriteAllowed(
  * are bypassed because loaders are always fresh (never cached) and
  * their side effects (setCookie, header, etc.) are safe.
  */
-export function runInsideLoaderScope<T>(fn: () => T, loaderId?: string): T {
-  return loaderScopeALS.run({ active: true, loaderId }, fn);
+export function runInsideLoaderScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  reverseScope?: ReverseScope,
+): T {
+  return loaderScopeALS.run({ active: true, loaderId, reverseScope }, fn);
+}
+
+/**
+ * The ReverseScope of the DSL loader kickoff around this call: a loader the
+ * kickoff starts, and one its body starts with ctx.use(), resolve dot names
+ * in it. A handler's ctx.use(Loader) runs outside any kickoff: none.
+ */
+export function getLoaderReverseScope(): ReverseScope | undefined {
+  return loaderScopeALS.getStore()?.reverseScope;
 }
 
 /**

package/src/server/handle-store.ts

@@ -47,8 +47,9 @@ function createLateHandlePushError(
 ): Error {
   const error = new Error(
     `Handle "${handleName}" for segment "${segmentId}" was pushed after handle collection completed. ` +
-      `This usually means an async JSX subtree suspended and later tried to push a handle during streaming. ` +
-      `Push handles from the route/layout handler or during the initial synchronous JSX render instead.`,
+      `This usually means an async component pushed it after an await. ` +
+      `Push from the route or layout handler, or reserve the slot there with ` +
+      `ctx.use(Handle).defer() and resolve it from the component.`,
   );
   error.name = "LateHandlePushError";
   return error;