@rangojs/router 0.0.0-experimental.111 → 0.0.0-experimental.113

package/src/cache/cache-scope.ts

@@ -187,6 +187,32 @@ export class CacheScope {
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
 
+  /**
+   * Evaluate the cache `condition` predicate. Returns false (skip the cache
+   * operation) when the predicate returns false or throws; returns true when
+   * there is no condition or no request context to evaluate it against.
+   */
+  private conditionAllows(op: "read" | "write"): boolean {
+    if (this.config === false || !this.config.condition) return true;
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return true;
+    try {
+      if (!this.config.condition(requestCtx)) {
+        debugCacheLog(
+          `[CacheScope] condition returned false, skipping cache ${op}`,
+        );
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error(
+        `[CacheScope] condition function threw, skipping cache ${op}:`,
+        error,
+      );
+      return false;
+    }
+  }
+
   /**
    * Lookup cached segments for a route (single cache entry per request).
    * Returns { segments, shouldRevalidate } or null if cache miss.
@@ -204,27 +230,7 @@ export class CacheScope {
     shouldRevalidate: boolean;
   } | null> {
     if (!this.enabled) return null;
-
-    // Evaluate condition — skip cache read when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const requestCtx = getRequestContext();
-      if (requestCtx) {
-        try {
-          if (!this.config.condition(requestCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache read`,
-            );
-            return null;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache read:`,
-            error,
-          );
-          return null;
-        }
-      }
-    }
+    if (!this.conditionAllows("read")) return null;
 
     const store = this.getStore();
     if (!store) return null;
@@ -284,27 +290,7 @@ export class CacheScope {
     isIntercept?: boolean,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
-
-    // Evaluate condition — skip cache write when condition returns false
-    if (this.config !== false && this.config.condition) {
-      const conditionCtx = getRequestContext();
-      if (conditionCtx) {
-        try {
-          if (!this.config.condition(conditionCtx)) {
-            debugCacheLog(
-              `[CacheScope] condition returned false, skipping cache write`,
-            );
-            return;
-          }
-        } catch (error) {
-          console.error(
-            `[CacheScope] condition function threw, skipping cache write:`,
-            error,
-          );
-          return;
-        }
-      }
-    }
+    if (!this.conditionAllows("write")) return;
 
     const store = this.getStore();
     if (!store) return;

package/src/cache/cf/cf-cache-store.ts

@@ -56,6 +56,15 @@ export const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
 /** Header storing cache status: HIT | REVALIDATING */
 export const CACHE_STATUS_HEADER = "x-edge-cache-status";
 
+/**
+ * Header stashing the route author's original Cache-Control on L1 document
+ * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * `max-age` so the CF Cache API retains the entry across the whole SWR window;
+ * getResponse restores this original value before serving so the client and any
+ * upstream CDN see the author's intended directive, not the internal edge TTL.
+ */
+const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
+
 /**
  * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
  * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
@@ -182,7 +191,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * Cache version string override. When this changes, all cached entries are
    * effectively invalidated (new keys won't match old entries).
    *
-   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+   * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
    * Only set this if you need a custom versioning strategy.
    */
   version?: string;
@@ -419,7 +428,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
 
       // L2: persist to KV
-      this.kvSetSegment(key, data, staleAt, totalTtl);
+      this.kvSetSegment(key, data, staleAt, totalTtl, swrWindow);
     } catch (error) {
       console.error("[CFCacheStore] set failed:", error);
     }
@@ -478,7 +487,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const isStale = staleAt > 0 && Date.now() > staleAt;
 
       return {
-        response,
+        response: this.toClientResponse(response),
         shouldRevalidate: isStale,
       };
     } catch (error) {
@@ -487,6 +496,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /**
+   * Strip internal edge headers and restore the author's Cache-Control before a
+   * cached document Response is served to a client. L1 entries carry the
+   * internal staleness/status headers and a rewritten Cache-Control; none of
+   * those should reach the browser or an upstream CDN.
+   */
+  private toClientResponse(response: Response): Response {
+    const headers = new Headers(response.headers);
+    const originalCacheControl = headers.get(CACHE_ORIG_CC_HEADER);
+    if (originalCacheControl !== null) {
+      headers.set("Cache-Control", originalCacheControl);
+    } else {
+      headers.delete("Cache-Control");
+    }
+    headers.delete(CACHE_ORIG_CC_HEADER);
+    headers.delete(CACHE_STALE_AT_HEADER);
+    headers.delete(CACHE_STATUS_HEADER);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
   /**
    * Store a Response with TTL and optional SWR window (for document-level caching).
    * When KV is configured, also persists to L2.
@@ -513,8 +546,14 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           : [null, null]
         : [response.body, null];
 
-      // Clone and add cache headers
+      // Clone and add cache headers. The author's Cache-Control is stashed and
+      // replaced with a long max-age so the CF Cache API holds the entry across
+      // the SWR window; getResponse restores the original before serving.
       const headers = new Headers(response.headers);
+      const originalCacheControl = response.headers.get("Cache-Control");
+      if (originalCacheControl !== null) {
+        headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
+      }
       headers.set("Cache-Control", `public, max-age=${totalTtl}`);
       headers.set(CACHE_STALE_AT_HEADER, String(staleAt));
 
@@ -764,13 +803,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     data: CachedEntryData,
     staleAt: number,
     totalTtl: number,
+    swrWindow: number,
   ): void {
     // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
     const kvKey = this.toKVKey(key);
-    const swrWindow = totalTtl * 1000 - (staleAt - Date.now());
-    const expiresAt = staleAt + swrWindow;
+    const expiresAt = staleAt + swrWindow * 1000;
 
     this.waitUntil(async () => {
       try {
@@ -937,6 +976,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         const request = this.keyToRequest(`doc:${key}`);
 
         const headers = new Headers(envelope.hd);
+        const originalCacheControl = headers.get("Cache-Control");
+        if (originalCacheControl !== null) {
+          headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
+        }
         headers.set("Cache-Control", `public, max-age=${remainingTtl}`);
         headers.set(CACHE_STALE_AT_HEADER, String(envelope.s));
 

package/src/decode-loader-results.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { isLoaderDataResult } from "./types.js";
+
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    if (result.fallback) {
+      errorFallback = result.fallback;
+    } else {
+      throw new Error(result.error.message);
+    }
+  }
+
+  return { loaderData, errorFallback };
+}

package/src/errors.ts

@@ -27,6 +27,17 @@ export class RouteNotFoundError extends Error {
   }
 }
 
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails.
+export function isRouteNotFoundError(
+  error: unknown,
+): error is RouteNotFoundError {
+  return (
+    error instanceof RouteNotFoundError ||
+    (error instanceof Error && error.name === "RouteNotFoundError")
+  );
+}
+
 /**
  * Thrown when data is not found (e.g., product with ID doesn't exist)
  * Use this in handlers/loaders to trigger the nearest notFoundBoundary

package/src/loader-store.ts

@@ -36,6 +36,13 @@
 
 export interface LoaderEntry<T = unknown> {
   readonly value: T | undefined;
+  /**
+   * Whether a load has committed a value to this bucket. Distinguishes a
+   * committed `null`/`undefined` result from "never loaded", so a loader that
+   * resolves to a falsy value is not mistaken for an empty bucket and is not
+   * overridden by the server-seeded context value.
+   */
+  readonly hasValue: boolean;
   readonly error: Error | null;
   readonly isLoading: boolean;
   /** Identifies the request that produced this snapshot. 0 means "no request". */
@@ -44,6 +51,7 @@ export interface LoaderEntry<T = unknown> {
 
 const EMPTY_SNAPSHOT: LoaderEntry = Object.freeze({
   value: undefined,
+  hasValue: false,
   error: null,
   isLoading: false,
   requestId: 0,
@@ -67,14 +75,15 @@ export interface SubscribeOptions {
    */
   ephemeral?: boolean;
   /**
-   * Cross-loader refresh group name. Tags this bucket so `refreshGroup(name)`
-   * can refresh it alongside buckets of other loaders. Group membership follows
-   * subscriber presence: a bucket leaves its group when its last subscriber
-   * unsubscribes.
+   * Cross-loader refresh group name(s). Tags this bucket so `refreshGroups(name)`
+   * can refresh it alongside buckets of other loaders. A bucket may be tagged
+   * with several group names at once (pass an array); it is then refreshed when
+   * ANY of its groups is refreshed. Group membership follows subscriber presence:
+   * a bucket leaves a group when that group's last subscriber unsubscribes.
    */
-  group?: string;
+  group?: string | string[];
   /**
-   * Plain-GET refresh thunk used by `refreshGroup`. Provided alongside `group`.
+   * Plain-GET refresh thunk used by `refreshGroups`. Provided alongside `group`.
    * Refreshes this bucket in place (no params/body) and rejects on failure.
    */
   refetch?: () => Promise<void>;
@@ -102,20 +111,31 @@ interface InternalEntry {
   /**
    * Cross-loader refresh groups this bucket belongs to, mapped to the number of
    * current subscribers that requested each group. A bucket can be in several
-   * groups at once (different subscribers may tag the same shared bucket with
-   * different group names); refcounting keeps membership independent of
-   * subscribe/unsubscribe order.
+   * groups at once (one read tagged with multiple names, or different subscribers
+   * tagging the same shared bucket with different names); refcounting keeps
+   * membership independent of subscribe/unsubscribe order.
    */
   groups: Map<string, number>;
-  /** Plain-GET refresh thunk for `refreshGroup`, set while in any group. */
+  /** Plain-GET refresh thunk for `refreshGroups`, set while in any group. */
   refetch: (() => Promise<void>) | undefined;
 }
 
+/**
+ * Normalize a group tag option (`undefined | string | string[]`) to a deduped
+ * list of names. Deduping keeps a single subscriber from being counted more than
+ * once in one group when the caller passes a repeated name.
+ */
+function normalizeGroups(group: string | string[] | undefined): string[] {
+  if (group === undefined) return [];
+  if (typeof group === "string") return [group];
+  return [...new Set(group)];
+}
+
 export class LoaderStore {
   private readonly entries = new Map<string, InternalEntry>();
   /** loader.$$id -> set of bucket keys, so clearFamily() can reach every bucket. */
   private readonly families = new Map<string, Set<string>>();
-  /** refresh group name -> set of bucket keys, for refreshGroup(). */
+  /** refresh group name -> set of bucket keys, for refreshGroups(). */
   private readonly groups = new Map<string, Set<string>>();
 
   private getOrCreate(bucketKey: string): InternalEntry {
@@ -163,8 +183,11 @@ export class LoaderStore {
     e.loaderId = loaderId;
     this.registerFamily(loaderId, bucketKey);
     if (options?.ephemeral !== true) e.sticky = true;
-    const group = options?.group;
-    if (group !== undefined) {
+    // Normalize the group tag(s) to a deduped list so one subscriber is counted
+    // once per distinct group, and subscribe/unsubscribe stay symmetric (the
+    // same list drives both addToGroup and releaseGroup).
+    const groups = normalizeGroups(options?.group);
+    for (const group of groups) {
       this.addToGroup(group, bucketKey, e, options?.refetch);
     }
     // A fresh subscriber means the bucket is wanted again: cancel any pending
@@ -174,11 +197,11 @@ export class LoaderStore {
     e.listeners.add(cb);
     return () => {
       e.listeners.delete(cb);
-      // Group membership is refcounted per subscriber so refreshGroup() never
+      // Group membership is refcounted per subscriber so refreshGroups() never
       // fetches for an unmounted reader, and a bucket shared by subscribers in
       // different groups stays in each group until ALL of that group's
       // subscribers have left (order-independent).
-      if (group !== undefined) this.releaseGroup(group, bucketKey, e);
+      for (const group of groups) this.releaseGroup(group, bucketKey, e);
       this.maybeScheduleRefcountClear(bucketKey, e);
     };
   }
@@ -232,17 +255,27 @@ export class LoaderStore {
   }
 
   /**
-   * Refresh every currently-mounted bucket in a cross-loader refresh group with
-   * a plain GET (no params/body). Buckets are deduped by key, so multiple reads
-   * of one bucket trigger a single fetch. Resolves when all refreshes settle;
-   * rejects with an `AggregateError` of the failures if any member fails — each
-   * failing member also records its error on its own snapshot.
+   * Refresh every currently-mounted bucket tagged with ANY of the given group
+   * names, with a plain GET (no params/body). Accepts a single name or an array
+   * of names. A bucket that belongs to more than one of the named groups is
+   * refreshed exactly once (members are unioned and deduped by bucket key), as
+   * are multiple reads of one bucket. Resolves when all refreshes settle; rejects
+   * with an `AggregateError` of the failures if any member fails — each failing
+   * member also records its error on its own snapshot.
    */
-  async refreshGroup(group: string): Promise<void> {
-    const members = this.groups.get(group);
-    if (!members || members.size === 0) return;
+  async refreshGroups(groups: string | string[]): Promise<void> {
+    const names = typeof groups === "string" ? [groups] : groups;
+    // Union the member buckets across every named group, deduped by key, so a
+    // bucket tagged into two of the requested groups is fetched a single time.
+    const buckets = new Set<string>();
+    for (const name of names) {
+      const members = this.groups.get(name);
+      if (!members) continue;
+      for (const bucketKey of members) buckets.add(bucketKey);
+    }
+    if (buckets.size === 0) return;
     const thunks: Array<() => Promise<void>> = [];
-    for (const bucketKey of members) {
+    for (const bucketKey of buckets) {
       const e = this.entries.get(bucketKey);
       if (!e || e.listeners.size === 0 || !e.refetch) continue;
       thunks.push(e.refetch);
@@ -253,9 +286,10 @@ export class LoaderStore {
       .filter((r): r is PromiseRejectedResult => r.status === "rejected")
       .map((r) => r.reason);
     if (reasons.length > 0) {
+      const label = names.map((n) => `"${n}"`).join(", ");
       throw new AggregateError(
         reasons,
-        `refreshGroup("${group}") had ${reasons.length} failure(s)`,
+        `refreshGroups(${label}) had ${reasons.length} failure(s)`,
       );
     }
   }
@@ -346,6 +380,7 @@ export class LoaderStore {
     if (e.snapshot.isLoading && e.snapshot.error === null) return;
     e.snapshot = Object.freeze({
       value: e.snapshot.value,
+      hasValue: e.snapshot.hasValue,
       error: null,
       isLoading: true,
       requestId,
@@ -363,6 +398,7 @@ export class LoaderStore {
     if (!e || requestId !== e.latestRequestId) return;
     e.snapshot = Object.freeze({
       value,
+      hasValue: true,
       error: null,
       isLoading: false,
       requestId,
@@ -381,6 +417,7 @@ export class LoaderStore {
     if (!e || requestId !== e.latestRequestId) return;
     e.snapshot = Object.freeze({
       value: e.snapshot.value,
+      hasValue: e.snapshot.hasValue,
       error,
       isLoading: false,
       requestId,

package/src/loader.ts

@@ -1,5 +1,5 @@
 /**
- * rsc-router/loader (client version)
+ * @rangojs/router/loader (client version)
  *
  * Client-only stub for createLoader. Returns a minimal loader definition
  * ({ __brand, $$id }) that can be passed to hooks like useLoader.
@@ -38,10 +38,6 @@ export function createLoader<T>(
 
 // Implementation - client stub that just returns the loader definition
 // The $$id parameter is injected by Vite plugin, not user-provided
-//
-// NOTE: For export-only loader files, the Vite plugin replaces the entire
-// file with object literals (bypassing this function). This function only
-// runs when loaders are in mixed files (not export-only).
 export function createLoader<T>(
   _fn: LoaderFn<T, Record<string, string | undefined>, any>,
   _fetchable?: true | FetchableLoaderOptions,

package/src/response-utils.ts

@@ -26,3 +26,12 @@ export function isWebSocketUpgradeResponse(response: Response): boolean {
     (response as unknown as { webSocket?: unknown }).webSocket != null
   );
 }
+
+// Location truthiness (not presence) so an empty `Location: ""` is not a redirect.
+export function isRedirectResponse(response: Response): boolean {
+  return (
+    response.status >= 300 &&
+    response.status < 400 &&
+    Boolean(response.headers.get("Location"))
+  );
+}

package/src/route-content-wrapper.tsx

@@ -4,7 +4,7 @@ import { Suspense, use, useId } from "react";
 import { invariant } from "./errors";
 import { OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
-import { isLoaderDataResult } from "./types.js";
+import { decodeLoaderResults } from "./decode-loader-results.js";
 
 /**
  * Stable async wrapper component for route content
@@ -26,10 +26,6 @@ export function RouteContentWrapper({
   fallback?: ReactNode;
   segmentId?: string;
 }): ReactNode {
-  if (!content) {
-    // Already resolved
-    return content as ReactNode;
-  }
   return (
     <Suspense
       fallback={fallback ?? null}
@@ -159,28 +155,10 @@ function LoaderResolver({
       ? use(loaderDataPromise)
       : loaderDataPromise;
 
-  // Build loaderData record from resolved values
-  const loaderData: Record<string, any> = {};
-  let loaderErrorFallback: ReactNode = null;
-
-  loaderIds.forEach((id, i) => {
-    const result = resolvedData[i];
-
-    if (isLoaderDataResult(result)) {
-      if (result.ok) {
-        loaderData[id] = result.data;
-      } else {
-        if (result.fallback) {
-          loaderErrorFallback = result.fallback;
-        } else {
-          throw new Error(result.error.message);
-        }
-      }
-    } else {
-      // Legacy format - direct data
-      loaderData[id] = result;
-    }
-  });
+  const { loaderData, errorFallback } = decodeLoaderResults(
+    resolvedData,
+    loaderIds,
+  );
 
   return (
     <OutletProvider
@@ -190,7 +168,7 @@ function LoaderResolver({
       parallel={parallel}
       loaderData={Object.keys(loaderData).length > 0 ? loaderData : undefined}
     >
-      {loaderErrorFallback ?? children}
+      {errorFallback ?? children}
     </OutletProvider>
   );
 }

package/src/route-definition/helpers-types.ts

@@ -449,10 +449,19 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
     ): CacheItem;
   };
   /**
-   * Attach a ViewTransition boundary to the current segment or a group of routes
-   *
-   * Wraps segment content with React's `<ViewTransition>` component.
-   * Only takes effect when React experimental is used (no-op on stable React).
+   * Attach a ViewTransition boundary to the current segment or a group of routes,
+   * and opt the route into same-route stale-while-revalidate navigation.
+   *
+   * Two effects, both opt-in via this helper:
+   * - Same-route navigation (same route, different params, e.g. /product/1 ->
+   *   /product/2) reconciles the route subtree instead of remounting it, so the
+   *   previous content is held while the new loader resolves rather than flashing
+   *   the route's loading() skeleton. This works on ALL React versions (it is
+   *   plain startTransition + Suspense; see segment-system.tsx inTransitionScope).
+   * - On React experimental, the segment content is additionally wrapped in
+   *   `<ViewTransition>`, so the held same-route swap animates (update/share
+   *   morph) and cross-route swaps animate exit/enter. The animation layer is a
+   *   no-op on stable React; the content-hold is not.
    *
    * ```typescript
    * // Attach to a single route

package/src/router/content-negotiation.ts

@@ -135,8 +135,8 @@ export interface NegotiationResult {
   manifestEntry: EntryData;
   /** Route middleware for the winning variant */
   routeMiddleware: CollectedMiddleware[];
-  /** Always true — negotiation occurred */
-  negotiated: true;
+  /** True when negotiation selected a variant; false for a plain response route. */
+  negotiated: boolean;
 }
 
 /**
@@ -155,6 +155,19 @@ export async function negotiateRoute(
 ): Promise<NegotiationResult | null> {
   const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
   if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    // No variants: a plain response route still yields a result (negotiated:false)
+    // so callers don't re-derive it; RSC routes (no responseType/handler) -> null.
+    const handler =
+      manifestEntry.type === "route" ? manifestEntry.handler : undefined;
+    if (responseType && handler) {
+      return {
+        responseType,
+        handler: handler as Function,
+        manifestEntry,
+        routeMiddleware,
+        negotiated: false,
+      };
+    }
     return null;
   }
 

package/src/router/intercept-resolution.ts

@@ -66,28 +66,14 @@ export function findInterceptForRoute(
   let current: EntryData | null = fromEntry;
 
   while (current) {
-    if (current.intercept && current.intercept.length > 0) {
-      for (const intercept of current.intercept) {
+    // 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: current };
-        }
-      }
-    }
-
-    if (current.layout && current.layout.length > 0) {
-      for (const siblingLayout of current.layout) {
-        if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-          for (const intercept of siblingLayout.intercept) {
-            if (
-              intercept.routeName === targetRouteKey &&
-              evaluateInterceptWhen(intercept, selectorContext, isAction)
-            ) {
-              return { intercept, entry: siblingLayout };
-            }
-          }
+          return { intercept, entry: source };
         }
       }
     }

package/src/router/loader-resolution.ts

@@ -24,7 +24,10 @@ import { isHandle, collectHandleData, type Handle } from "../handle.js";
 import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
-import { isInsideLoaderScope } from "../server/context.js";
+import {
+  isInsideLoaderScope,
+  runInsideLoaderBodyScope,
+} from "../server/context.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -353,8 +356,19 @@ function createLoaderExecutor<TEnv>(
     };
 
     const doneLoader = track(`loader:${loader.$$id}`, 2);
+    // Run the loader body inside loader scope so request-scoped reads
+    // (cookies()/headers() and non-cacheable ctx.get) are exempt from the
+    // cache-purity guards: loaders always run fresh, so their reads never leak
+    // into a cached segment. DSL loaders are already wrapped by fresh.ts; this
+    // also covers handler-invoked loaders (ctx.use(Loader) from a handler),
+    // which otherwise execute in the caller's cache scope and would wrongly
+    // throw. rendered() gating uses the captured isDslLoader (above), so this
+    // does not grant rendered() to handler-invoked loaders. Uses a body-only
+    // scope, so isInsideLoaderScope() / barrier / deadlock gating is unchanged.
     const promise = Promise.resolve(
-      loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+      runInsideLoaderBodyScope(() =>
+        loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+      ),
     ).finally(() => {
       pendingLoaders.delete(loader.$$id);
       doneLoader();