@rangojs/router 0.16.0 → 0.17.0

package/src/router/handler-context.ts

@@ -16,7 +16,7 @@ import {
 } from "../context-var.js";
 import {
   assertCachedHeaderWriteAllowed,
-  isInsideCacheScope,
+  assertNonCacheableReadAllowed,
 } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
@@ -29,6 +29,32 @@ import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 // once at module load instead of per createHandlerContext (per-request) call.
 const MUTATING_HEADERS_METHODS = new Set(["set", "append", "delete"]);
 
+/**
+ * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
+ * the handler ctx (createHandlerContext) and the middleware ctx
+ * (createMiddlewareContext).
+ */
+export function guardHeaderWrites(
+  headers: Headers,
+  assertWrite: (method: string | symbol) => void,
+): Headers {
+  return new Proxy(headers, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
+          return (...args: any[]) => {
+            assertWrite(prop);
+            return value.apply(target, args);
+          };
+        }
+        return value.bind(target);
+      }
+      return value;
+    },
+  });
+}
+
 /**
  * Strip internal _rsc* query params from a URL.
  * Returns a new URL with only user-facing params.
@@ -224,23 +250,10 @@ export function createHandlerContext<TEnv>(
   // assertCachedHeaderWriteAllowed, the unified #713 guard).
   // Uses lazy `ctx` reference (assigned below) — only the specific handler ctx
   // is stamped by cache-runtime, not the shared request context.
-  // MUTATING_HEADERS_METHODS is hoisted to module scope (constant, read-only).
   let ctx: InternalHandlerContext<any, TEnv>;
-  const guardedHeaders = new Proxy(stubResponse.headers, {
-    get(target, prop, receiver) {
-      const value = Reflect.get(target, prop, receiver);
-      if (typeof value === "function") {
-        if (MUTATING_HEADERS_METHODS.has(prop as string)) {
-          return (...args: any[]) => {
-            assertNotInsideCacheExec(ctx, "headers");
-            assertCachedHeaderWriteAllowed("ctx.headers", prop);
-            return value.apply(target, args);
-          };
-        }
-        return value.bind(target);
-      }
-      return value;
-    },
+  const guardedHeaders = guardHeaderWrites(stubResponse.headers, (prop) => {
+    assertNotInsideCacheExec(ctx, "headers");
+    assertCachedHeaderWriteAllowed("ctx.headers", prop);
   });
 
   ctx = {
@@ -263,14 +276,10 @@ export function createHandlerContext<TEnv>(
     executionContext: requestContext?.executionContext,
     _variables: variables,
     get: ((keyOrVar: any) => {
-      // Read-time guard: non-cacheable var inside cache() → throw.
-      // Works for both ContextVar tokens and string keys.
-      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
-        throw new Error(
-          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
-            `The variable was created with { cache: false } or set with { cache: false }, ` +
-            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
-        );
+      // Read-time guard: non-cacheable var inside "use cache" or cache() →
+      // throw. Works for both ContextVar tokens and string keys.
+      if (isNonCacheable(variables, keyOrVar)) {
+        assertNonCacheableReadAllowed(keyOrVar);
       }
       return contextGet(variables, keyOrVar);
     }) as HandlerContext<any, TEnv>["get"],

package/src/router/intercept-resolution.ts

@@ -26,8 +26,12 @@ import {
   warnOnStreamedResponse,
   buildLoaderErrorContext,
 } from "./segment-resolution.js";
+import { catchSegmentError } from "./segment-resolution/helpers.js";
+import { findInOrphans } from "./error-handling.js";
+import { resolveLoaderData } from "./segment-resolution/loader-cache.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { getRouterContext } from "./router-context.js";
 import {
   RangoContext,
   latchPprHeaderScopeForEntries,
@@ -101,15 +105,20 @@ export function collectInterceptTargetNames(
   fromEntry: EntryData | null,
 ): string[] {
   const names = new Set<string>();
+  // Tolerate partial entries (unit-test mocks omit the arrays); real
+  // registration always populates layout/intercept.
+  const add = (source: EntryData): undefined => {
+    for (const intercept of source.intercept ?? []) {
+      names.add(intercept.routeName);
+    }
+    return undefined;
+  };
   let current: EntryData | null = fromEntry;
+  let prev: EntryData | null = null;
   while (current) {
-    // Tolerate partial entries (unit-test mocks omit the arrays); real
-    // registration always populates layout/intercept.
-    for (const source of [current, ...(current.layout ?? [])]) {
-      for (const intercept of source.intercept ?? []) {
-        names.add(intercept.routeName);
-      }
-    }
+    add(current);
+    findInOrphans(current, add, prev);
+    prev = current;
     current = current.parent;
   }
   return [...names];
@@ -121,27 +130,62 @@ export function findInterceptForRoute(
   selectorContext: InterceptSelectorContext | null = null,
   isAction: boolean = false,
 ): { intercept: InterceptEntry; entry: EntryData } | null {
+  const match = (source: EntryData) => {
+    for (const intercept of source.intercept) {
+      if (
+        intercept.routeName === targetRouteKey &&
+        evaluateInterceptWhen(intercept, selectorContext, isAction)
+      ) {
+        return { intercept, entry: source };
+      }
+    }
+    return undefined;
+  };
   let current: EntryData | null = fromEntry;
+  let prev: EntryData | null = null;
 
   while (current) {
-    // current first, then its sibling layouts — same order as before.
-    for (const source of [current, ...current.layout]) {
-      for (const intercept of source.intercept) {
-        if (
-          intercept.routeName === targetRouteKey &&
-          evaluateInterceptWhen(intercept, selectorContext, isAction)
-        ) {
-          return { intercept, entry: source };
-        }
-      }
-    }
+    // current first, then its orphans (nested ones included) in render order.
+    const found = match(current) ?? findInOrphans(current, match, prev);
+    if (found) return found;
 
+    prev = current;
     current = current.parent;
   }
 
   return null;
 }
 
+/**
+ * An intercept handler's throw or notFound() renders the declaring entry's
+ * boundary as the slot component (catchSegmentError, as for route handlers on
+ * partial navigations: 500/404 status, onError "handler"). Responses and every
+ * error on the background re-render (skipMiddleware) rethrow, so a failed
+ * re-render aborts its cache write instead of storing the fallback.
+ */
+function renderInterceptHandlerError<TEnv>(
+  error: unknown,
+  parentEntry: EntryData,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  deps: SegmentResolutionDeps<TEnv>,
+  skipMiddleware: boolean | undefined,
+): ReactNode {
+  if (error instanceof Response || skipMiddleware) throw error;
+  return catchSegmentError(
+    error,
+    parentEntry,
+    params,
+    deps,
+    {
+      ...buildLoaderErrorContext(context),
+      isPartial: true,
+      telemetry: getRouterContext()?.telemetry,
+    },
+    context.pathname,
+  ).component;
+}
+
 /**
  * Resolve an intercept entry and emit segment with the slot name.
  */
@@ -210,8 +254,8 @@ export async function resolveInterceptEntry<TEnv>(
   const loaderIds: string[] = [];
 
   for (let i = 0; i < interceptEntry.loader.length; i++) {
-    const { loader, revalidate: loaderRevalidateFns } =
-      interceptEntry.loader[i];
+    const loaderEntry = interceptEntry.loader[i];
+    const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
     const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
 
     if (revalidationContext) {
@@ -273,7 +317,11 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        runInsideLoaderScope(() => context.use(loader)),
+        // The DSL binding's funnel, as for route loaders: a loader's own
+        // cache() applies here too.
+        runInsideLoaderScope(() =>
+          resolveLoaderData(loaderEntry, context, context.pathname),
+        ),
         parentEntry,
         segmentId,
         context.pathname,
@@ -284,10 +332,26 @@ export async function resolveInterceptEntry<TEnv>(
     );
   }
 
-  const handlerResult =
-    typeof interceptEntry.handler === "function"
-      ? handleHandlerResult(interceptEntry.handler(context))
-      : interceptEntry.handler;
+  let handlerResult: ReactNode;
+  try {
+    handlerResult =
+      typeof interceptEntry.handler === "function"
+        ? handleHandlerResult(interceptEntry.handler(context))
+        : interceptEntry.handler;
+  } catch (error) {
+    handlerResult = renderInterceptHandlerError(
+      error,
+      parentEntry,
+      params,
+      context,
+      deps,
+      options?.skipMiddleware,
+    );
+  }
+  // Consumed only after the layout and loader awaits below; a rejection in that
+  // window would be an unhandledRejection (process crash on Node's default
+  // mode). The later await / trackHandler still observes it.
+  if (handlerResult instanceof Promise) handlerResult.catch(() => {});
 
   let layoutElement: ReactNode | undefined;
   if (interceptEntry.layout) {
@@ -304,6 +368,14 @@ export async function resolveInterceptEntry<TEnv>(
 
   let component: ReactNode;
   let loaderDataPromise: Promise<any[]> | any[] | undefined;
+  // A streamed (loading()) handler resolves after the 200 has started, so its
+  // rejection stays with the client; track it like route handlers do
+  // (onError report, handle-store completion).
+  const trackStreamedHandler = (promise: Promise<unknown>): ReactNode =>
+    deps.trackHandler(promise, {
+      segmentId: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+      segmentType: "parallel",
+    }) as ReactNode;
 
   if (interceptEntry.loading && loaderPromises.length > 0) {
     if (handlerResult instanceof Promise) {
@@ -314,20 +386,30 @@ export async function resolveInterceptEntry<TEnv>(
     }
     component =
       handlerResult instanceof Promise
-        ? handlerResult
+        ? trackStreamedHandler(handlerResult)
         : (Promise.resolve(handlerResult) as ReactNode);
     loaderDataPromise = Promise.all(loaderPromises);
-  } else if (loaderPromises.length > 0) {
-    loaderDataPromise = await Promise.all(loaderPromises);
-    component =
-      handlerResult instanceof Promise ? await handlerResult : handlerResult;
+  } else if (interceptEntry.loading && handlerResult instanceof Promise) {
+    component = trackStreamedHandler(handlerResult);
   } else {
-    component =
-      interceptEntry.loading && handlerResult instanceof Promise
-        ? handlerResult
-        : handlerResult instanceof Promise
-          ? await handlerResult
-          : handlerResult;
+    if (loaderPromises.length > 0) {
+      loaderDataPromise = await Promise.all(loaderPromises);
+    }
+    component = handlerResult;
+    if (handlerResult instanceof Promise) {
+      try {
+        component = await handlerResult;
+      } catch (error) {
+        component = renderInterceptHandlerError(
+          error,
+          parentEntry,
+          params,
+          context,
+          deps,
+          options?.skipMiddleware,
+        );
+      }
+    }
   }
 
   const interceptSegment = {
@@ -401,8 +483,8 @@ export async function resolveInterceptLoadersOnly<TEnv>(
   } = revalidationContext;
 
   for (let i = 0; i < interceptEntry.loader.length; i++) {
-    const { loader, revalidate: loaderRevalidateFns } =
-      interceptEntry.loader[i];
+    const loaderEntry = interceptEntry.loader[i];
+    const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
     const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
 
     const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
@@ -451,7 +533,11 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        runInsideLoaderScope(() => context.use(loader)),
+        // The DSL binding's funnel, as for route loaders: a loader's own
+        // cache() applies here too.
+        runInsideLoaderScope(() =>
+          resolveLoaderData(loaderEntry, context, context.pathname),
+        ),
         parentEntry,
         segmentId,
         context.pathname,

package/src/router/loader-resolution.ts

@@ -7,7 +7,8 @@
 import type { ReactNode } from "react";
 import type { EntryData } from "../server/context";
 import { observePhase, PHASES } from "./instrument.js";
-import { contextGet } from "../context-var.js";
+import { contextGet, isNonCacheable } from "../context-var.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -43,6 +44,7 @@ import {
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
+  assertNonCacheableReadAllowed,
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
   isInsidePushCallbackScope,
@@ -394,6 +396,7 @@ function createLoaderExecutor<TEnv>(
   // Capture RequestContext eagerly for cookie access (ALS protection on Cloudflare)
   const reqCtxRef = _getRequestContext();
   const silentHandles = executorOptions?.silentHandles === true;
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
 
   // Dependency graph: loaderId -> set of loader IDs it directly depends on.
   const dependsOn = new Map<string, Set<string>>();
@@ -429,7 +432,12 @@ function createLoaderExecutor<TEnv>(
       deps.add(loader.$$id);
     }
 
-    // Return cached promise if already started
+    // Every loader execution funnels here (handler and loader-to-loader
+    // reads, uncached DSL bindings, cache misses): memoized per request, so a
+    // loader runs at most once however many reads, with no store cache. A
+    // loader's cache() read-through lives in loader-cache.ts
+    // (executeLoaderData), whose ctx.use override serves a later handler read
+    // the binding's result.
     if (loaderPromises.has(loader.$$id)) {
       return loaderPromises.get(loader.$$id)!;
     }
@@ -452,7 +460,7 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
-    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+    const variables = internal._variables;
 
     // Capture whether this loader is being started from a DSL loader scope
     // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
@@ -466,18 +474,26 @@ function createLoaderExecutor<TEnv>(
     // stale. Attributing to the owning route/layout segment gives handle
     // pushes the same granularity handler pushes have (segmentOrder-correct
     // for breadcrumb accumulation).
-    const owningSegmentId = (ctx as InternalHandlerContext<any, TEnv>)
-      ._currentSegmentId;
+    const owningSegmentId = internal._currentSegmentId;
 
     let renderedResolved = false;
     let renderedPromise: Promise<void> | null = null;
 
-    // Loader functions are always fresh (never cached), so they get an
-    // unguarded get that bypasses non-cacheable read guards. This applies
-    // to ALL loaders — DSL and handler-called — because the loader
-    // function itself always re-executes. Also handles nested deps
-    // (loaderA → use(loaderB)) since all share this unguarded get.
-    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+    // Request-scoped like the handler ctx it derives from (issue #940): the
+    // NOCACHE_SYMBOL brand below makes a "use cache" function taking it key by
+    // the route fields (_routeName, _responseType) and replay its handle
+    // pushes into the owning segment, claimed per loader like a handler ctx
+    // (_claimLoaderPushes, _runLoaderIsolated). Non-cacheable ctx.get reads
+    // run the shared guard; the body itself stays exempt (loader body scope).
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> &
+      Pick<
+        InternalHandlerContext<any, TEnv>,
+        | "_routeName"
+        | "_responseType"
+        | "_currentSegmentId"
+        | "_claimLoaderPushes"
+        | "_runLoaderIsolated"
+      > = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
@@ -517,6 +533,9 @@ function createLoaderExecutor<TEnv>(
             buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
           return collectHandleData(keyOrVar, snapshot, segmentOrder);
         }
+        if (isNonCacheable(variables, keyOrVar)) {
+          assertNonCacheableReadAllowed(keyOrVar);
+        }
         return contextGet(variables, keyOrVar);
       }) as typeof ctx.get,
       use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
@@ -552,6 +571,11 @@ function createLoaderExecutor<TEnv>(
       method: "GET",
       body: undefined,
       reverse: ctx.reverse as LoaderContext["reverse"],
+      _routeName: internal._routeName,
+      _responseType: internal._responseType,
+      _currentSegmentId: owningSegmentId,
+      _claimLoaderPushes: internal._claimLoaderPushes,
+      _runLoaderIsolated: internal._runLoaderIsolated,
       rendered: (): Promise<void> => {
         // Guard: only DSL loaders may use rendered()
         if (!isDslLoader) {
@@ -639,6 +663,7 @@ function createLoaderExecutor<TEnv>(
         return renderedPromise;
       },
     };
+    (loaderCtx as any)[NOCACHE_SYMBOL] = true;
 
     // Meter this loader once via observePhase (loader:<id> perf metric +
     // rango.loader span); loaderFn runs inside the span callback so its KV/D1/
@@ -736,6 +761,26 @@ export function setupLoaderAccess<TEnv>(
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
+  // Loader-cache HIT replay (loader-cache.ts replayLoaderHandles): a cached
+  // entry records its ctx.use dependencies' pushes too, and a dependency is
+  // memoized here and shared with live readers. A loader that already ran
+  // here keeps its live pushes; otherwise one replay delivers its recorded
+  // pushes, and a later run here replaces them (HandleStore.pushReplayed).
+  const claimed = new Set<string>();
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  internal._claimLoaderPushes = (loaderId) => {
+    if (loaderPromises.has(loaderId) || claimed.has(loaderId)) return false;
+    claimed.add(loaderId);
+    return true;
+  };
+  // A refresh's pushes are diverted, so its loader ctxs never claim
+  // (cache-runtime.ts refreshView).
+  internal._runLoaderIsolated = (loader) =>
+    createLoaderExecutor(
+      Object.create(ctx, { _claimLoaderPushes: { value: undefined } }),
+      new Map(),
+    )(loader, null);
+
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;

package/src/router/match-api.ts

@@ -7,7 +7,9 @@ import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
   createErrorSegment,
+  findInOrphans,
   findNearestErrorBoundary as findErrorBoundary,
+  withErrorBoundary,
 } from "./error-handling.js";
 import {
   createHandlerContext,
@@ -481,24 +483,21 @@ export async function matchError<TEnv>(
     segmentType,
   );
 
+  // Same search order as findNearestErrorBoundary, so the fallback above and
+  // the entry that positions it agree.
   let entryWithBoundary: EntryData | null = null;
   let current: EntryData | null = manifestEntry;
+  let prev: EntryData | null = null;
   while (current) {
     if (current.errorBoundary && current.errorBoundary.length > 0) {
       entryWithBoundary = current;
       break;
     }
 
-    if (current.layout && current.layout.length > 0) {
-      for (const orphan of current.layout) {
-        if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
-          entryWithBoundary = orphan;
-          break;
-        }
-      }
-      if (entryWithBoundary) break;
-    }
+    entryWithBoundary = findInOrphans(current, withErrorBoundary, prev) ?? null;
+    if (entryWithBoundary) break;
 
+    prev = current;
     current = current.parent;
   }
 
@@ -507,23 +506,19 @@ export async function matchError<TEnv>(
 
   if (entryWithBoundary) {
     boundaryEntry = entryWithBoundary;
+    // The chain entry holding the boundary, itself or in its orphan tree: the
+    // error segment takes the place of its child in the chain.
+    const boundaryOwner = current;
 
     outletEntry = manifestEntry;
     current = manifestEntry;
 
     while (current) {
-      if (current.parent === boundaryEntry) {
+      if (current.parent === boundaryOwner) {
         outletEntry = current;
         break;
       }
 
-      if (current.parent && current.parent.layout) {
-        if (current.parent.layout.includes(boundaryEntry)) {
-          outletEntry = current;
-          break;
-        }
-      }
-
       current = current.parent;
     }
   } else {