@rangojs/router 0.15.1 → 0.17.0

package/src/route-types.ts

@@ -106,6 +106,8 @@ export type CacheItem = {
 export type TransitionItem = {
   name: string;
   type: "transition";
+  /** Wrapper form only: the children it wraps (see hasRoutesInItem). */
+  uses?: AllUseItems[];
 };
 
 /**
@@ -220,11 +222,8 @@ export type ParallelUseItem =
   | TransitionItem;
 export type InterceptUseItem =
   | MiddlewareItem
-  | RevalidateItem
   | LoaderItem
   | LoadingItem
-  | ErrorBoundaryItem
-  | NotFoundBoundaryItem
   | LayoutItem
   | RouteItem
   | TransitionItem;

package/src/router/debug-manifest.ts

@@ -5,8 +5,9 @@ import MapRootLayout from "../server/root-layout.js";
 import type { RouteEntry, TrailingSlashMode } from "../types";
 
 /**
- * Build a serialized manifest from all route entries for debug inspection.
- * Used by the `debugManifest()` method on the router instance.
+ * Build a serialized manifest from the eager route entries for debug
+ * inspection. Used by the `debugManifest()` method on the router instance.
+ * include() children are not expanded (lazy placeholders are skipped).
  */
 export async function buildDebugManifest<TEnv = any>(
   routesEntries: RouteEntry<TEnv>[],
@@ -14,6 +15,13 @@ export async function buildDebugManifest<TEnv = any>(
   const manifest = new Map<string, EntryData>();
 
   for (const entry of routesEntries) {
+    // Lazy include placeholders are not mounts: a top-level one carries the
+    // parent urls() handler (router.ts routes()), so re-running it re-registers
+    // the parent's routes into the shared manifest (path() duplicate-name
+    // invariant). A nested one (lazy-includes.ts runExpansion()) is only valid
+    // under its captured include context.
+    if (entry.lazy) continue;
+
     const Store = {
       manifest,
       namespace: `debug.M${entry.mountIndex}`,

package/src/router/error-handling.ts

@@ -105,31 +105,67 @@ export function invokeOnError<TEnv = any>(
   }
 }
 
+/**
+ * First non-undefined `pick(orphan)` over the routeless entries in
+ * `entry.layout` and, recursively, in theirs: depth-first in render order
+ * (resolveOrphanLayout in segment-resolution/fresh.ts). Since #922 a routeless
+ * entry nested in another renders (a layout() after a bare cache() marker, a
+ * layout() in a routeless wrapper); a one-level scan missed the boundaries and
+ * intercepts it declares (#926).
+ *
+ * `skip` is the entry an upward walk came from. Only a bare cache() marker is
+ * both in its layout's layout[] and in the chain, and its subtree was already
+ * scanned at its chain position.
+ */
+export function findInOrphans<T>(
+  entry: EntryData,
+  pick: (orphan: EntryData) => T | undefined,
+  skip?: EntryData | null,
+): T | undefined {
+  for (const orphan of entry.layout ?? []) {
+    if (orphan === skip) continue;
+    const found = pick(orphan) ?? findInOrphans(orphan, pick);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+/** `findInOrphans` pick: the orphan when it declares an errorBoundary(). */
+export const withErrorBoundary = (entry: EntryData): EntryData | undefined =>
+  entry.errorBoundary && entry.errorBoundary.length > 0 ? entry : undefined;
+
+const withNotFoundBoundary = (entry: EntryData): EntryData | undefined =>
+  entry.notFoundBoundary && entry.notFoundBoundary.length > 0
+    ? entry
+    : undefined;
+
 /**
  * Find the nearest error boundary by walking up the entry chain
  * Also checks sibling layouts (orphan layouts) for error boundaries
  * Returns the first fallback found, or the default error boundary if configured
+ *
+ * An orphan's parent is null, so from an orphan the walk continues at its
+ * orphanOwner (EntryData). Without that step, errors from an intercept declared
+ * in a routeless layout, or from that layout's loaders, stopped at the orphan
+ * and skipped every ancestor boundary (#898).
  */
 export function findNearestErrorBoundary(
   entry: EntryData | null,
   defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler,
 ): ReactNode | ErrorBoundaryHandler | null {
   let current: EntryData | null = entry;
+  let prev: EntryData | null = null;
 
   while (current) {
     if (current.errorBoundary && current.errorBoundary.length > 0) {
       return current.errorBoundary[current.errorBoundary.length - 1];
     }
 
-    if (current.layout && current.layout.length > 0) {
-      for (const orphan of current.layout) {
-        if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
-          return orphan.errorBoundary[orphan.errorBoundary.length - 1];
-        }
-      }
-    }
+    const orphan = findInOrphans(current, withErrorBoundary, prev);
+    if (orphan) return orphan.errorBoundary[orphan.errorBoundary.length - 1];
 
-    current = current.parent;
+    prev = current;
+    current = current.parent ?? current.orphanOwner ?? null;
   }
 
   // Return default error boundary if configured
@@ -145,6 +181,7 @@ export function findNearestNotFoundBoundary(
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler,
 ): ReactNode | NotFoundBoundaryHandler | null {
   let current: EntryData | null = entry;
+  let prev: EntryData | null = null;
 
   while (current) {
     if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
@@ -154,15 +191,14 @@ export function findNearestNotFoundBoundary(
     // Check orphan layouts mirroring findNearestErrorBoundary: notFoundBoundary
     // attaches identically (onto parent.notFoundBoundary), and an orphan layout
     // (parent=null) is reachable only via this scan. First sibling is "outer".
-    if (current.layout && current.layout.length > 0) {
-      for (const orphan of current.layout) {
-        if (orphan.notFoundBoundary && orphan.notFoundBoundary.length > 0) {
-          return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
-        }
-      }
+    const orphan = findInOrphans(current, withNotFoundBoundary, prev);
+    if (orphan) {
+      return orphan.notFoundBoundary[orphan.notFoundBoundary.length - 1];
     }
 
-    current = current.parent;
+    // Orphan: continue at its owner, as findNearestErrorBoundary does.
+    prev = current;
+    current = current.parent ?? current.orphanOwner ?? null;
   }
 
   // Return default notFound boundary if configured

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;