@rangojs/router 0.0.0-experimental.112 → 0.0.0-experimental.114

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/handle.ts

@@ -1,3 +1,5 @@
+import { missingInjectedIdError } from "./missing-id-error.js";
+
 /**
  * Handle definition for accumulating data across route segments.
  *
@@ -96,11 +98,7 @@ export function createHandle<TData, TAccumulated = TData[]>(
   const handleId = __injectedId ?? "";
 
   if (!handleId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rango] Handle is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)",
-    );
+    throw missingInjectedIdError("Handle", "createHandle");
   }
 
   const collectFn =

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.rsc.ts

@@ -21,6 +21,7 @@ import {
   registerFetchableLoader,
   getFetchableLoader,
 } from "./server/fetchable-loader-store.js";
+import { missingInjectedIdError } from "./missing-id-error.js";
 
 export { getFetchableLoader };
 
@@ -53,11 +54,7 @@ export function createLoader<T>(
   const loaderId = __injectedId || "";
 
   if (!loaderId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rango] Loader is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the loader is exported with: export const MyLoader = createLoader(...)",
-    );
+    throw missingInjectedIdError("Loader", "createLoader");
   }
 
   // If not fetchable, store fn in registry (for SSR ctx.use() resolution)

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.
@@ -18,6 +18,7 @@ import type {
   LoaderDefinition,
   LoaderFn,
 } from "./types.js";
+import { missingInjectedIdError } from "./missing-id-error.js";
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
@@ -38,10 +39,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,
@@ -50,11 +47,7 @@ export function createLoader<T>(
   const loaderId = __injectedId || "";
 
   if (!loaderId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rango] Loader is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the loader is exported with: export const MyLoader = createLoader(...)",
-    );
+    throw missingInjectedIdError("Loader", "createLoader");
   }
 
   return {

package/src/missing-id-error.ts

@@ -0,0 +1,68 @@
+// Builds the error thrown when a create*() call (createLoader / createHandle)
+// reaches runtime without an injected $$id. The exposeInternalIds Vite transform
+// injects $$id only for an EXPORTED const declaration, so a non-exported const,
+// an `export let/var`, or an inline create*() call gets none. Previously this
+// failed with a terse message and no source location; this helper adds the
+// offending call site (best-effort, from the stack) and actionable guidance.
+//
+// The "<Kind> is missing $$id" prefix is preserved so existing tests and any
+// log scrapers keep matching. Dev-only: the call sites guard on
+// process.env.NODE_ENV === "development", so production builds fold the branch
+// away and tree-shake this module out.
+
+// create*() implementation files to skip when locating the user's call site.
+const SELF_FILES = new Set([
+  "missing-id-error",
+  "loader",
+  "loader.rsc",
+  "handle",
+]);
+
+/**
+ * Best-effort "path:line:column" of the user's create*() call, parsed from the
+ * current stack. Skips @rangojs/router internals and node_modules. Returns
+ * undefined if nothing usable is found (stack parsing is inherently fragile).
+ */
+function findUserCallSite(): string | undefined {
+  try {
+    const stack = new Error().stack;
+    if (!stack) return undefined;
+    for (const frame of stack.split("\n").slice(1)) {
+      const m = frame.match(
+        /(?:\(|@|\s)(?:file:\/\/)?((?:\/|[A-Za-z]:[\\/])[^()\s]+?\.(?:ts|tsx|js|jsx|mts|cts)):(\d+):(\d+)\)?/,
+      );
+      if (!m) continue;
+      const path = m[1];
+      if (path.includes("node_modules") || path.includes("@rangojs/router")) {
+        continue;
+      }
+      const base = path
+        .split(/[\\/]/)
+        .pop()!
+        .replace(/\.(?:ts|tsx|js|jsx|mts|cts)$/, "");
+      if (SELF_FILES.has(base)) continue;
+      return `${path}:${m[2]}:${m[3]}`;
+    }
+  } catch {
+    // best-effort only
+  }
+  return undefined;
+}
+
+export function missingInjectedIdError(
+  kind: "Loader" | "Handle",
+  fnName: "createLoader" | "createHandle",
+): Error {
+  const site = findUserCallSite();
+  const at = site ? ` (created at ${site})` : "";
+  return new Error(
+    `[rango] ${kind} is missing $$id${at}.\n` +
+      `The @rangojs/router:expose-internal-ids Vite transform injects ${fnName}()'s ` +
+      `stable $$id from an EXPORTED const declaration only:\n` +
+      `  export const X = ${fnName}(...)\n` +
+      `  const X = ${fnName}(...); export { X }\n` +
+      `A non-exported const, an \`export let/var\`, or an inline ${fnName}(...) ` +
+      `call gets no $$id — export it as \`export const\`. (A matching ` +
+      `"Unsupported ${fnName} shape" warning names the exact file:line.)`,
+  );
+}

package/src/reverse.ts

@@ -231,47 +231,50 @@ export type LocalReverseParams<TPattern extends string> =
   };
 
 /**
- * Type-safe local reverse function with dot-prefixed names only.
+ * Type-safe local reverse function.
  *
  * Returned by `useReverse(routes)` on the client. The route map is the
  * exposure boundary (a generated `routes` from a `urls()` module) and the
- * scope is implicit from that import — there is no global namespace, so
- * names must be dot-prefixed to mirror `ctx.reverse(".name")`.
+ * scope is implicit from that import. Names may be written with or without a
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
+ * there is no separate global namespace here, so it carries no meaning.
  *
  * @example
  * ```typescript
  * const reverse = useReverse(blogRoutes);
- * reverse(".index");                         // ✓ no params
- * reverse(".post", { postId: "hello" });     // ✓ with params
- * reverse(".search", {}, { q: "hi" });       // ✓ with search schema
- * reverse(".typo");                          // ✗ compile error
+ * reverse("index");                          // ✓ no params (dot optional)
+ * reverse(".index");                         // ✓ identical to the above
+ * reverse("post", { postId: "hello" });      // ✓ with params
+ * reverse("search", {}, { q: "hi" });        // ✓ with search schema
+ * reverse("typo");                           // ✗ compile error
  * ```
  */
 export type LocalReverseFunction<TLocalRoutes> = {
   /**
-   * Dot-prefixed local route without params
+   * Route without params (leading dot optional)
    */
   <TName extends keyof TLocalRoutes & string>(
     name: IsEmptyObject<
       ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
     > extends true
-      ? `.${TName}`
+      ? TName | `.${TName}`
       : never,
   ): string;
 
   /**
-   * Dot-prefixed local route with params
+   * Route with params (leading dot optional)
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: `.${TName}`,
+    name: TName | `.${TName}`,
     params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
   ): string;
 
   /**
-   * Dot-prefixed local route with params and search
+   * Route with params and search (leading dot optional)
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: `.${TName}`,
+    name: TName | `.${TName}`,
     params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
     search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
   ): string;

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

@@ -866,8 +866,11 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
 };
 
 /**
- * Transition helper - attaches a ViewTransition config to the current entry
- * or wraps a group of routes in a transparent layout with ViewTransition
+ * Transition helper - opts the entry (or a wrapped group of routes) into
+ * transition-driven navigation by attaching a TransitionConfig. This drives the
+ * commit through startTransition (content hold on all React versions) and, on
+ * experimental React, places a `<ViewTransition>` boundary unless
+ * `viewTransition: false`. See skills/view-transitions for the matrix.
  */
 const transition = (
   configOrChildren?: TransitionConfig | (() => UseItems<AllUseItems>),

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

@@ -449,10 +449,30 @@ 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).
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * `transition()` does two independent things, and you choose how far to go:
+   * 1. startTransition (ALL React versions): the navigation commit is driven
+   *    through React's startTransition, so a same-route nav (same route,
+   *    different params, e.g. /product/1 -> /product/2) holds the previous
+   *    content while the new loader resolves instead of flashing the route's
+   *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
+   *    also the precondition for any view-transition animation.
+   * 2. <ViewTransition> (experimental React only): the segment content is also
+   *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
+   *    Layered on by default; pass { viewTransition: false } to keep #1 without
+   *    the router boundary (and place your own <ViewTransition> instead).
+   *
+   * A view transition cannot fire without a startTransition, so the meaningful
+   * choices are (see skills/view-transitions for the full matrix):
+   * - no transition()                         -> neither (remount + skeleton)
+   * - transition({ viewTransition: false })   -> startTransition only (hold)
+   * - transition({}) / transition({ enter… })  -> startTransition + ViewTransition
+   *
+   * Precedence: a bare transition({}) inherits createRouter({ viewTransition })
+   * (default "auto"); an explicit per-route `viewTransition` always wins. So
+   * transition({}) is startTransition + ViewTransition under the default and
+   * startTransition only when the router sets viewTransition: false.
    *
    * ```typescript
    * // Attach to a single route
@@ -466,13 +486,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   path("/about", AboutPage),
    * ])
    *
-   * // Direction-aware transitions
-   * transition({
-   *   enter: { "navigation": "slide-right", "navigation-back": "slide-left" },
-   *   exit: { "navigation": "slide-left", "navigation-back": "slide-right" },
-   * })
+   * // Hold content + drive view transitions, but place no router boundary:
+   * path("/product/:id", ProductPage, { name: "product" }, () => [
+   *   transition({ viewTransition: false }),
+   * ])
    * ```
-   * @param config - ViewTransition configuration (enter, exit, update, share, default, name)
+   * @param config - ViewTransition configuration (enter, exit, update, share,
+   *   default, name) plus `viewTransition: "auto" | false` to toggle the router
+   *   boundary (createRouter({ viewTransition }) sets the app-wide default)
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {

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();