@rangojs/router 0.16.0 → 0.18.0

package/src/server/request-context.ts

@@ -17,6 +17,7 @@ import type { CookieOptions } from "../router/middleware.js";
 import {
   KEEP_CACHE_HEADER,
   getRawCookieValue,
+  freshReadsCookieName,
   mintStateValue,
   serializeStateCookie,
 } from "../browser/cookie-name.js";
@@ -61,9 +62,10 @@ import type { RoutineTrace } from "../rsc/routine-plan.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import {
   assertCachedHeaderWriteAllowed,
+  assertNonCacheableReadAllowed,
   clearPprHeaderScope,
-  isInsideCacheScope,
 } from "./context.js";
+import { assertThemeReadAllowed } from "./cookie-store.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -165,6 +167,40 @@ export interface RequestContext<
   _rotateStateCookie(): void;
   /** @internal Set the keepClientCache() directive header on the response. */
   _setKeepCacheDirective(): void;
+  /**
+   * @internal This request carries the fresh-reads cookie: it follows an
+   * updateTag()/revalidateTag() by the same user, so the stores read tag
+   * markers and shells from the store, not from an isolate memo.
+   */
+  _freshReads?: boolean;
+  /**
+   * @internal Set the fresh-reads cookie on this response for `maxAgeMs`
+   * (rounded up to whole seconds; the longest stays). Called by
+   * updateTag()/revalidateTag().
+   */
+  _setFreshReadsCookie(maxAgeMs: number): void;
+  /**
+   * @internal The context createRequestContext() returned. A context derived
+   * from it with Object.create (a PPR HIT tail, a shell capture, a background
+   * revalidation render) inherits it, so per-request invalidation state
+   * (tag-invalidation.ts, the stores' masks) is keyed by the request, not by
+   * whichever derived object called or read (#973).
+   */
+  _requestRoot?: RequestContext<any, any>;
+  /**
+   * @internal The tags this request invalidated with
+   * updateTag()/revalidateTag(), each with its position in the invalidation
+   * order (tag-invalidation.ts currentCacheSeq). Kept on _requestRoot. A
+   * "use cache" execution that started before one of its own tags was
+   * invalidated is neither joined nor written (cache-runtime.ts, #973).
+   */
+  _tagInvalidations?: Map<string, number>;
+  /**
+   * @internal The handler has handed the response to the host (rsc/handler.ts
+   * `rango.response`): header and cookie writes after this are lost, as from
+   * a streaming loader or render.
+   */
+  _responseSent?: boolean;
 
   /**
    * Access loader data or push handle data.
@@ -197,8 +233,13 @@ export interface RequestContext<
   /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
   method: string;
 
-  /** @internal Handle store for tracking handle data across segments */
-  _handleStore: HandleStore;
+  /**
+   * @internal Handle store for tracking handle data across segments.
+   * Readonly: a background render that needs its own store derives a context
+   * (rerenderAndCacheRoute, shell-capture.ts) instead of swapping this field,
+   * which the foreground still reads while it produces the page.
+   */
+  readonly _handleStore: HandleStore;
 
   /**
    * @internal transition({ when }) predicates for segments matched this request,
@@ -250,16 +291,58 @@ export interface RequestContext<
   /**
    * @internal Bake-lane loader containers collected DURING a shell capture:
    * segment-key -> the loader's (pre-wrap) result promise. Populated by
-   * resolveLoaderData for loaders on entries with no renderable loading() (the
-   * bake lane — they execute at capture instead of being masked; see
-   * docs/design/loader-container-bake.md). Drained by captureAndStoreShell
-   * after the shell quiesces: settled containers are promise-elided,
-   * Flight-serialized, and pinned into the snapshot's loader family; a
-   * REJECTED container refuses the capture (error UI must never bake into the
-   * shared shell). Own property of the capture's derived context only.
+   * resolveLoaderData for bake-lane loaders (lane rule: see its JSDoc in
+   * loader-cache.ts). Drained by captureAndStoreShell after the shell
+   * quiesces: settled containers are promise-elided, Flight-serialized, and
+   * pinned into the snapshot's loader family; a REJECTED container refuses
+   * the capture (error UI must never bake into the shared shell). Own
+   * property of the capture's derived context only.
    */
   _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
 
+  /**
+   * @internal Set on a capture's derived context when a loader pushed a
+   * value the record cannot keep (a deferred push, masked nested promises,
+   * or a push outside a loader body): the loader records then carry
+   * `runs: 1`, so a HIT still runs their bodies for those pushes.
+   */
+  _shellCaptureUnrecordedLoaderPush?: true;
+
+  /**
+   * @internal Record keys resolved for this request (CacheScope
+   * resolveKeyFrom): by the scope's `key()` (one result) or its store's
+   * keyGenerator (one per default key). A shell capture's derived context
+   * reads it through the prototype chain, so the capture reuses the
+   * partition its request resolved instead of running `key()` again.
+   */
+  _resolvedCacheKeys?: Map<unknown, Map<string, Promise<string>>>;
+
+  /**
+   * @internal The shell store key the PPR serve path resolved for this
+   * document request (rsc-rendering.ts shellServePlan), request partition
+   * included. Read by the testing helper serveShellRequest.
+   */
+  _shellKey?: string;
+
+  /**
+   * @internal The request carried the forced-MISS reload marker
+   * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
+   * request on entry and sets this; the shell gate renders the request like a
+   * cache miss.
+   */
+  _shellForcedMiss?: true;
+
+  /**
+   * @internal The freshness window of the route cache() records this
+   * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+   * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+   * its scope's swr. The narrowest record wins. A shell capture caps its
+   * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+   * shell is never fresher, or served longer, than the route cache() entry
+   * it replayed or wrote.
+   */
+  _routeRecordWindow?: RouteRecordWindow;
+
   /**
    * @internal Loader-family snapshot seed for a shell HIT's tail render:
    * segment-key -> the capture's elided container (already Flight-deserialized
@@ -267,8 +350,10 @@ export interface RequestContext<
    * overlays it onto the fresh run's container (recorded paths pinned,
    * hole-marker paths keep the fresh nested promises) so the payload's baked
    * bytes match the frozen prelude; a hole-free entry resolves pin-first
-   * without gating on the fresh run. Own property of the HIT tail's derived
-   * context only.
+   * and does not run the loader. Two owners: serveShellHit sets it on the
+   * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
+   * request context of a PPR partial replay once its doc record hits, and
+   * restores the previous value after the match.
    */
   _shellLoaderSeed?: Map<
     string,
@@ -276,16 +361,17 @@ export interface RequestContext<
   >;
 
   /**
-   * @internal Shell fast-path marker: makes the next eligible match treat the
-   * whole matched route as an implicit doc-level cache() boundary (see
+   * @internal The doc record marker: makes the next match treat the whole
+   * matched route as an implicit doc-level cache() boundary (see
    * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
    * (a) the capture's derived context — with a record-only store so the
    * capture's cacheRoute write lands in the snapshot, never the real store —
-   * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
-   * replay, where `store` is a request-local segment overlay. Handler-live holes
-   * and conditional transitions decline replay.
-   * Routes with their own cache() config are never overridden — their scope's
-   * store/key/ttl/swr/condition semantics stay authoritative. On the
+   * (b) a document HIT tail's seeded context (`docTail`), and (c) an eligible
+   * normal-route partial replay, where `store` is a request-local segment
+   * overlay.
+   * A document HIT tail replays the record even for a route with its own
+   * cache() config (the gate before the commit already evaluated that
+   * scope's opt-outs). Elsewhere the route's scope stays authoritative. On the
    * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
    * such a scope instead of being ignored: the seeded doc record supplies the match
    * only when the explicit tier misses (withCacheLookup). cache(false) and a
@@ -302,12 +388,17 @@ export interface RequestContext<
      * segment record even when the triggering request is partial.
      */
     keyPrefix?: "doc";
-    /** @internal Called only after the implicit cache hit decodes successfully. */
-    onHit?: () => void;
+    /**
+     * @internal Called only after the implicit cache hit decodes
+     * successfully; the lookup awaits it before returning the hit, so work
+     * it starts lands before the route's loaders resolve.
+     */
+    onHit?: () => void | Promise<void>;
     /**
      * @internal Called when the seeded document record fails server-side
      * deserialization. Partial replay uses it to replace the enclosing shell
-     * snapshot after serving the fresh fallback.
+     * snapshot after serving the fresh fallback. A document HIT tail does not
+     * set it: withCacheLookup throws ShellRecordUnavailableError instead.
      */
     onCorrupt?: () => void;
     /**
@@ -318,6 +409,21 @@ export interface RequestContext<
      * require the exact consumable record instead of "any segment record".
      */
     docKey?: string;
+    /**
+     * @internal Set on a document HIT tail (serveShellHit). The implicit doc
+     * scope replaces any route-derived cache() scope for the tail's match
+     * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
+     * ShellRecordUnavailableError instead of resolving segments
+     * (withCacheLookup): a HIT never runs a handler.
+     */
+    docTail?: true;
+    /**
+     * @internal The key a document HIT tail looks the doc record up by: the
+     * entry's own `docKey`. Recomputing it could name another key (a store
+     * keyGenerator folding request data, a build-time capture's synthetic
+     * host) and miss the record.
+     */
+    fixedDocKey?: string;
     /**
      * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
      * serve path. Its presence arms the explicit-scope composition in
@@ -361,43 +467,16 @@ export interface RequestContext<
   _shellFragmentPayload?: boolean;
 
   /**
-   * @internal Handler-layer liveness observed DURING a shell capture, from
-   * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
-   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
-   * (masked to a never-filling hole); (b) still-pending top-level handler
-   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
-   * executing during the capture (loader-resolution.ts — its consumption-lane
-   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
-   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
-   * property of the capture's derived context only.
-   */
-  _shellCaptureHandleLiveness?: {
-    holes: boolean;
-    pendingPushes: number;
-    handlerInvokedLoader: boolean;
-  };
-
-  /**
-   * @internal Handle values pushed from a DSL loader scope DURING a shell
-   * capture (identity set; populated by the capture push wrapper in
-   * shell-capture.ts). cacheRoute threads it into captureHandles so those
-   * values stay out of cache-write handle records — loaders re-run fresh on
-   * every HIT, so replaying their captured (masked) values would duplicate
-   * the fresh push and stall the Flight handle encode. Own property of the
-   * capture's derived context only; render-time handle consumers are
-   * unaffected (the exclusion applies only at the captureHandles call site).
-   */
-  _shellCaptureLoaderHandleValues?: WeakSet<object>;
-
-  /**
-   * @internal Set (to the offending fn name) by the cookies()/headers()
-   * capture guard when it throws DURING a capture render. Load-bearing for the
+   * @internal Set by the capture guard (server/context.ts
+   * tripShellCaptureGuard) when it throws DURING a capture render: the read
+   * ("cookies()", "headers()", "ctx.get()", "ctx.theme") and the fix the
+   * refusal warning gives for it. Load-bearing for the
    * bake lane: a guard throw inside an executing loader is swallowed by
    * wrapLoaderPromise into per-loader error UI, which would otherwise bake
    * silently into the shared shell — the capture checks this flag after the
    * render and refuses instead. Deterministic, so the capture does not retry.
    */
-  _shellCaptureGuardTripped?: string;
+  _shellCaptureGuardTripped?: { surface: string; fix: string };
 
   /**
    * @internal The loader $$id whose BODY was executing when the capture guard
@@ -428,6 +507,23 @@ export interface RequestContext<
    */
   _requestTags: Set<string>;
 
+  /**
+   * @internal This request can write a route cache() record: its match
+   * resolved a cache scope (match-api.ts). Arms the record tag owners
+   * (cache-tag.ts armRecordTagOwners); off, the segment scopes, loader links
+   * and owned tag sets are skipped entirely. A capture's or background
+   * re-render's derived context (Object.create) inherits it.
+   */
+  _recordTagOwners?: true;
+
+  /**
+   * @internal This request resolves a loader bound with its own cache()
+   * (match-api.ts, or the binding's funnel). Arms the per-execution loader
+   * tag sets (cache-tag.ts armLoaderTagSets); off, a loader execution
+   * allocates no set and a read links nothing. Derived contexts inherit it.
+   */
+  _recordLoaderTags?: true;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
@@ -475,6 +571,11 @@ export interface RequestContext<
    * Returns the theme value from the cookie, or the default theme if not set.
    * This is the user's preference ("light", "dark", or "system"), not the resolved value.
    *
+   * The visitor's cookie, so it is guarded like `cookies()`: reading it
+   * refuses a ppr shell capture and throws inside a `cache()` boundary or a
+   * `"use cache"` function (#971). A non-enumerable getter: a spread or
+   * `Object.assign` copy of the context does not carry it.
+   *
    * @example
    * ```typescript
    * route("settings", (ctx) => {
@@ -483,7 +584,7 @@ export interface RequestContext<
    * });
    * ```
    */
-  theme?: Theme;
+  readonly theme?: Theme;
 
   /**
    * Set the theme (only available when theme is enabled in router config)
@@ -507,6 +608,15 @@ export interface RequestContext<
   /** @internal Theme configuration (null if theme not enabled) */
   _themeConfig?: ResolvedThemeConfig | null;
 
+  /**
+   * @internal The theme cookie (or the default) read with no identity guard.
+   * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
+   * call it after assertThemeReadAllowed; the router's own payload read goes
+   * through payloadInitialTheme (rsc/full-payload.ts). Undefined without
+   * theme config.
+   */
+  _readTheme(): Theme | undefined;
+
   /**
    * Attach location state entries to the current response.
    *
@@ -650,6 +760,17 @@ export interface RequestContext<
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
+  /**
+   * @internal Errors this response's Flight or Fizz render reported through
+   * onError: a component that threw does not fail the stream, which completes
+   * with an error row or an errored Suspense boundary. Whole-response captures
+   * (document-cache.ts, captureAndStoreShell) store nothing while it is
+   * non-empty (issue #915). An array so a render under a derived context (the
+   * shell HIT tail) pushes into the request's own list through the prototype;
+   * deriveShellCaptureContext gives the capture its own.
+   */
+  _renderErrors?: unknown[];
+
   /**
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
@@ -723,6 +844,21 @@ export interface RequestContext<
   _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * request wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+  freshUntil: number;
+  staleUntil: number;
+  ttl: number;
+  swr: number;
+  written: boolean;
+}
+
 /**
  * Public view of RequestContext, without internal methods and fields.
  *
@@ -748,17 +884,23 @@ export type PublicRequestContext<
   | "_shellImplicitCache"
   | "_shellLoaderSeed"
   | "_shellCaptureLoaderRecords"
-  | "_shellCaptureHandleLiveness"
-  | "_shellCaptureLoaderHandleValues"
+  | "_shellCaptureUnrecordedLoaderPush"
+  | "_resolvedCacheKeys"
+  | "_shellKey"
+  | "_shellForcedMiss"
+  | "_routeRecordWindow"
   | "_shellFragmentPayload"
   | "_shellCaptureGuardTripped"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
+  | "_recordTagOwners"
+  | "_recordLoaderTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_pendingBackgroundTasks"
   | "_themeConfig"
+  | "_readTheme"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
@@ -770,6 +912,7 @@ export type PublicRequestContext<
   | "_gateFormData"
   | "_inActionRevalidation"
   | "_reportedErrors"
+  | "_renderErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
   | "_renderBarrierSegmentOrder"
@@ -792,6 +935,11 @@ export type PublicRequestContext<
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
+  | "_freshReads"
+  | "_setFreshReadsCookie"
+  | "_requestRoot"
+  | "_tagInvalidations"
+  | "_responseSent"
   | "_variables"
   | "_classifiedRoute"
   | "_requestMode"
@@ -988,6 +1136,10 @@ export function createRequestContext<TEnv>(
   } = options;
   const cookieHeader = request.headers.get("Cookie");
   let rangoStateRotated = false;
+  const freshCookie = stateCookieName
+    ? freshReadsCookieName(stateCookieName)
+    : undefined;
+  let freshCookieMaxAge = 0;
   let parsedCookies: Record<string, string> | null = null;
 
   let stubResponse = initialResponse
@@ -1140,12 +1292,8 @@ export function createRequestContext<TEnv>(
     },
     _dynamic: false,
     get: ((keyOrVar: any) => {
-      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.`,
-        );
+      if (isNonCacheable(variables, keyOrVar)) {
+        assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
       }
       return contextGet(variables, keyOrVar);
     }) as RequestContext<TEnv>["get"],
@@ -1255,6 +1403,48 @@ export function createRequestContext<TEnv>(
       rawStubHeaders.set(KEEP_CACHE_HEADER, "1");
     },
 
+    // The fresh-reads cookie (browser/cookie-name.ts): one Set-Cookie per
+    // response, the longest Max-Age any invalidation asked for. HttpOnly (the
+    // client never reads it), SameSite=Lax, Path=/. rawStubHeaders: an
+    // internal writer, allowed wherever updateTag()/revalidateTag() are. A
+    // shared cache never stores it (Set-Cookie is a per-client signal).
+    _setFreshReadsCookie(maxAgeMs: number): void {
+      if (!freshCookie) return;
+      const maxAge = Math.ceil(maxAgeMs / 1000);
+      // Already set for at least this long (an earlier invalidation in this
+      // request): nothing to add, sent or not.
+      if (maxAge <= freshCookieMaxAge) return;
+      if (ctx._responseSent) {
+        // A streaming loader or render: the headers already left. The
+        // invalidation itself still ran; only the mutating user's bypass of
+        // the stores' isolate memos is lost.
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(
+            `[rango] updateTag()/revalidateTag() ran after the response ` +
+              `headers were sent (from a streaming loader or render), so the ` +
+              `${freshCookie} cookie was not set: this user's next requests ` +
+              `can be served from a store's isolate memo for a few seconds. ` +
+              `Invalidate in a server action, a route handler, or middleware.`,
+          );
+        }
+        return;
+      }
+      const serialized = (age: number) =>
+        `${freshCookie}=1; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax` +
+        (url.protocol === "https:" ? "; Secure" : "");
+      if (freshCookieMaxAge > 0) {
+        const prior = serialized(freshCookieMaxAge);
+        const kept = rawStubHeaders
+          .getSetCookie()
+          .filter((cookie) => cookie !== prior);
+        rawStubHeaders.delete("Set-Cookie");
+        for (const cookie of kept) rawStubHeaders.append("Set-Cookie", cookie);
+      }
+      freshCookieMaxAge = maxAge;
+      rawStubHeaders.append("Set-Cookie", serialized(maxAge));
+      invalidateResponseCookieCache();
+    },
+
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
       assertResponseWriteAllowed("setStatus");
@@ -1276,6 +1466,9 @@ export function createRequestContext<TEnv>(
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
+    _freshReads:
+      freshCookie !== undefined &&
+      getRawCookieValue(cookieHeader, freshCookie) !== null,
 
     waitUntil(fn: () => Promise<void>): void {
       if (ctx.build) return;
@@ -1317,9 +1510,8 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    get theme() {
-      return themeConfig ? getTheme() : undefined;
-    },
+    // theme: a guarded, non-enumerable getter defined after this literal.
+    _readTheme: getTheme,
     setTheme: themeConfig
       ? (theme: Theme) => {
           assertNotInsideCacheExec(ctx, "setTheme");
@@ -1338,6 +1530,7 @@ export function createRequestContext<TEnv>(
     _locationState: undefined,
 
     _reportedErrors: new WeakSet<object>(),
+    _renderErrors: [],
     _metricsStore: undefined,
     _renderForeground: undefined,
     _activeRoutine: undefined,
@@ -1359,7 +1552,39 @@ export function createRequestContext<TEnv>(
     getContext: () => ctx,
   });
 
+  // getRequestContext().theme is the visitor's cookie, guarded like cookies()
+  // (#971); before it was a plain read that a ppr shell, a cache() entry or a
+  // "use cache" entry stored for every visitor. Non-enumerable like the
+  // handler ctx.theme (handler-context.ts THEME_DESCRIPTOR): serializing the
+  // context (React dev debug info) must not count as a read. The guard reads
+  // the ambient context, as cookies() does, and falls back to the receiver.
+  // _readTheme is the unguarded read: non-enumerable too, so a spread copy of
+  // the context (the fetchable-loader ctx, loader-fetch.ts) cannot carry it.
+  Object.defineProperties(ctx, {
+    theme: {
+      get(this: RequestContext<TEnv>): Theme | undefined {
+        if (!themeConfig) return undefined;
+        assertThemeReadAllowed(
+          _getRequestContext() ?? this,
+          "getRequestContext().theme",
+        );
+        return getTheme();
+      },
+      enumerable: false,
+      configurable: true,
+    },
+    _readTheme: { enumerable: false },
+  });
+
   (ctx as any)[NOCACHE_SYMBOL] = true;
+  // Non-enumerable: a self-reference would make the context circular for
+  // JSON.stringify, spreads and React's dev debug-info serialization of props.
+  Object.defineProperty(ctx, "_requestRoot", {
+    value: ctx,
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  });
   return ctx;
 }
 
@@ -1627,7 +1852,9 @@ export function createUseFunction<TEnv>(
       ? parseSearchParams(ctx.searchParams, searchSchema)
       : {};
 
-    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> & {
+      _routeName?: string;
+    } = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
@@ -1666,6 +1893,7 @@ export function createUseFunction<TEnv>(
           ? isRouteRootScoped(ctx._routeName, ctx._routerId)
           : undefined,
       ),
+      _routeName: ctx._routeName,
       rendered: () => {
         throw new Error(
           `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
@@ -1673,6 +1901,8 @@ export function createUseFunction<TEnv>(
         );
       },
     };
+    // "use cache" keys it by route, like the request ctx it reads (#940).
+    (loaderCtx as any)[NOCACHE_SYMBOL] = true;
 
     // Meter through the same unified phase API as the loader-resolution funnel
     // (observePhase), so a loader resolved via this base request-context ctx.use