@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/cache/segment-codec.ts

@@ -142,79 +142,76 @@ export const deserializeComponent: (encoded: string) => Promise<unknown> =
 export async function serializeSegments(
   segments: ResolvedSegment[],
 ): Promise<SerializedSegmentData[]> {
-  const serialized: SerializedSegmentData[] = [];
-
-  for (const segment of segments) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Await component if it's a Promise (intercepts with loading keep component as Promise)
-    const componentResolved =
-      segment.component instanceof Promise
-        ? await segment.component
-        : segment.component;
-
-    // Serialize the component to RSC stream
-    const stream = renderToReadableStream(componentResolved, {
-      temporaryReferences,
-    });
-
-    // Convert stream to string
-    const encoded = await streamToString(stream);
-
-    // RSC-serialize layout if present (ReactNode)
-    const encodedLayout = segment.layout
-      ? await rscSerialize(segment.layout)
-      : undefined;
-
-    // RSC-serialize loading if present (ReactNode) - preserves tree structure
-    // Use "null" string to distinguish explicit null from undefined
-    const encodedLoading =
-      segment.loading !== undefined
-        ? segment.loading === null
-          ? "null"
-          : await rscSerialize(segment.loading)
-        : undefined;
-
-    // Await and RSC-serialize loaderData if present
-    const loaderDataResolved =
-      segment.loaderData instanceof Promise
-        ? await segment.loaderData
-        : segment.loaderData;
-    const encodedLoaderData = await rscSerialize(loaderDataResolved);
-
-    // Await and RSC-serialize loaderDataPromise if present
-    const loaderDataPromiseResolved =
-      segment.loaderDataPromise instanceof Promise
-        ? await segment.loaderDataPromise
-        : segment.loaderDataPromise;
-    const encodedLoaderDataPromise = await rscSerialize(
-      loaderDataPromiseResolved,
-    );
-
-    serialized.push({
-      encoded,
-      encodedLayout,
-      encodedLoading,
-      encodedLoaderData,
-      encodedLoaderDataPromise,
-      metadata: {
-        id: segment.id,
-        type: segment.type,
-        namespace: segment.namespace,
-        index: segment.index,
-        params: segment.params,
-        slot: segment.slot,
-        belongsToRoute: segment.belongsToRoute,
-        layoutName: segment.layoutName,
-        parallelName: segment.parallelName,
-        loaderId: segment.loaderId,
-        loaderIds: segment.loaderIds,
-        transition: segment.transition,
-      },
-    });
-  }
+  return Promise.all(
+    segments.map(async (segment): Promise<SerializedSegmentData> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Await component if it's a Promise (intercepts with loading keep component as Promise)
+      const componentResolved =
+        segment.component instanceof Promise
+          ? await segment.component
+          : segment.component;
+
+      // Serialize the component to RSC stream
+      const stream = renderToReadableStream(componentResolved, {
+        temporaryReferences,
+      });
+
+      // RSC-serialize loading: "null" string distinguishes explicit null from undefined
+      const encodedLoading =
+        segment.loading !== undefined
+          ? segment.loading === null
+            ? "null"
+            : await rscSerialize(segment.loading)
+          : undefined;
+
+      // Await loaderData / loaderDataPromise if they're Promises
+      const loaderDataResolved =
+        segment.loaderData instanceof Promise
+          ? await segment.loaderData
+          : segment.loaderData;
+      const loaderDataPromiseResolved =
+        segment.loaderDataPromise instanceof Promise
+          ? await segment.loaderDataPromise
+          : segment.loaderDataPromise;
+
+      // Parallelize stream-to-string and RSC serialization of sub-fields
+      const [
+        encoded,
+        encodedLayout,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+      ] = await Promise.all([
+        streamToString(stream),
+        segment.layout ? rscSerialize(segment.layout) : undefined,
+        rscSerialize(loaderDataResolved),
+        rscSerialize(loaderDataPromiseResolved),
+      ]);
 
-  return serialized;
+      return {
+        encoded,
+        encodedLayout,
+        encodedLoading,
+        encodedLoaderData,
+        encodedLoaderDataPromise,
+        metadata: {
+          id: segment.id,
+          type: segment.type,
+          namespace: segment.namespace,
+          index: segment.index,
+          params: segment.params,
+          slot: segment.slot,
+          belongsToRoute: segment.belongsToRoute,
+          layoutName: segment.layoutName,
+          parallelName: segment.parallelName,
+          loaderId: segment.loaderId,
+          loaderIds: segment.loaderIds,
+          transition: segment.transition,
+          mountPath: segment.mountPath,
+        },
+      };
+    }),
+  );
 }
 
 /**
@@ -224,44 +221,36 @@ export async function serializeSegments(
 export async function deserializeSegments(
   data: SerializedSegmentData[],
 ): Promise<ResolvedSegment[]> {
-  const segments: ResolvedSegment[] = [];
-
-  for (const item of data) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Revive the component from cached string
-    const stream = stringToStream(item.encoded);
-    const component = await createFromReadableStream(stream, {
-      temporaryReferences,
-    });
-
-    // RSC-deserialize layout, loaderData, loaderDataPromise in parallel.
-    // Handle the "null" sentinel for loading before RSC deserialization.
-    // During serialization, loading: null is stored as the string "null" to
-    // distinguish it from undefined. This sentinel must be intercepted here
-    // rather than passed to rscDeserialize, which would try to decode it as
-    // an RSC Flight payload.
-    const loadingIsNullSentinel = item.encodedLoading === "null";
-
-    const [layout, loaderData, loaderDataPromise, loadingData] =
-      await Promise.all([
-        rscDeserialize(item.encodedLayout),
-        rscDeserialize(item.encodedLoaderData),
-        rscDeserialize(item.encodedLoaderDataPromise),
-        loadingIsNullSentinel
-          ? (null as any)
-          : rscDeserialize(item.encodedLoading),
-      ]);
-
-    segments.push({
-      ...item.metadata,
-      component,
-      layout,
-      loading: loadingData,
-      loaderData,
-      loaderDataPromise,
-    } as ResolvedSegment);
-  }
-
-  return segments;
+  return Promise.all(
+    data.map(async (item): Promise<ResolvedSegment> => {
+      const temporaryReferences = createTemporaryReferenceSet();
+
+      // Handle the "null" sentinel for loading before RSC deserialization.
+      // During serialization, loading: null is stored as the string "null" to
+      // distinguish it from undefined.
+      const loadingIsNullSentinel = item.encodedLoading === "null";
+
+      const [component, layout, loaderData, loaderDataPromise, loadingData] =
+        await Promise.all([
+          createFromReadableStream(stringToStream(item.encoded), {
+            temporaryReferences,
+          }),
+          rscDeserialize(item.encodedLayout),
+          rscDeserialize(item.encodedLoaderData),
+          rscDeserialize(item.encodedLoaderDataPromise),
+          loadingIsNullSentinel
+            ? (null as any)
+            : rscDeserialize(item.encodedLoading),
+        ]);
+
+      return {
+        ...item.metadata,
+        component,
+        layout,
+        loading: loadingData,
+        loaderData,
+        loaderDataPromise,
+      } as ResolvedSegment;
+    }),
+  );
 }

package/src/cache/taint.ts

@@ -25,11 +25,37 @@ export function isTainted(value: unknown): boolean {
  * cookies(), headers(), ctx.set(), ctx.header(), etc. check this flag and
  * throw if present — reads would cache per-request data under a shared key,
  * and side effects would be lost on cache hit.
+ *
+ * The value is a numeric reference count, not a boolean. Multiple concurrent
+ * cached functions sharing the same ctx/requestCtx each increment on entry
+ * and decrement on exit. Guards fire when count > 0.
  */
 export const INSIDE_CACHE_EXEC: unique symbol = Symbol.for(
   "rango:inside-cache-exec",
 ) as any;
 
+/**
+ * Increment the INSIDE_CACHE_EXEC ref count on an object.
+ */
+export function stampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  (obj as any)[INSIDE_CACHE_EXEC] = current + 1;
+}
+
+/**
+ * Decrement the INSIDE_CACHE_EXEC ref count on an object.
+ * Deletes the symbol when the count reaches zero so the `in` check
+ * used by guards no longer fires.
+ */
+export function unstampCacheExec(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_EXEC] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_EXEC];
+  } else {
+    (obj as any)[INSIDE_CACHE_EXEC] = current - 1;
+  }
+}
+
 /**
  * Throw if ctx is inside a "use cache" execution.
  * Call from side-effecting ctx methods (set, header, etc.) and cookie mutations.
@@ -55,6 +81,61 @@ export function assertNotInsideCacheExec(
   }
 }
 
+/**
+ * Symbol stamped on ctx when resolving handlers inside a cache() DSL boundary.
+ * Separate from INSIDE_CACHE_EXEC ("use cache") because cache() allows
+ * ctx.set() (children are also cached) but blocks response-level side effects
+ * (headers, cookies, status) which are lost on cache hit.
+ */
+export const INSIDE_CACHE_SCOPE: unique symbol = Symbol.for(
+  "rango:inside-cache-scope",
+) as any;
+
+/**
+ * Mark ctx as inside a cache() scope. Must be paired with unstampCacheScope.
+ */
+export function stampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  (obj as any)[INSIDE_CACHE_SCOPE] = current + 1;
+}
+
+/**
+ * Remove cache() scope mark.
+ */
+export function unstampCacheScope(obj: object): void {
+  const current = (obj as any)[INSIDE_CACHE_SCOPE] ?? 0;
+  if (current <= 1) {
+    delete (obj as any)[INSIDE_CACHE_SCOPE];
+  } else {
+    (obj as any)[INSIDE_CACHE_SCOPE] = current - 1;
+  }
+}
+
+/**
+ * Throw if ctx is inside a cache() DSL boundary.
+ * Call from response-level side effects (header, setCookie, setStatus, etc.)
+ * which are lost on cache hit because the handler body is skipped.
+ * ctx.set() is allowed inside cache() — children are also cached and can
+ * read the value.
+ */
+export function assertNotInsideCacheScope(
+  ctx: unknown,
+  methodName: string,
+): void {
+  if (
+    ctx !== null &&
+    ctx !== undefined &&
+    typeof ctx === "object" &&
+    (INSIDE_CACHE_SCOPE as symbol) in (ctx as Record<symbol, unknown>)
+  ) {
+    throw new Error(
+      `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+        `On cache hit the handler is skipped, so this side effect would be lost. ` +
+        `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+    );
+  }
+}
+
 /**
  * Brand symbol for functions wrapped by registerCachedFunction().
  * Used at runtime to detect when a "use cache" function is misused

package/src/client.rsc.tsx

@@ -17,7 +17,6 @@ export {
   OutletProvider,
   useOutlet,
   useLoader,
-  useLoaderData,
   ErrorBoundary,
   type ErrorBoundaryProps,
 } from "./client.js";
@@ -64,6 +63,8 @@ export { Meta } from "./handles/meta.js";
 // MetaTags is a "use client" component that can be imported from RSC
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+// Breadcrumbs handle works in RSC context
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 // Location state - createLocationState works in RSC (just creates definition)
 // useLocationState is NOT exported here as it uses client hooks

package/src/client.tsx

@@ -21,6 +21,7 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { OutletProvider } from "./outlet-provider.js";
+import { MountContextProvider } from "./browser/react/mount-context.js";
 
 /**
  * Outlet component - renders child content in layouts
@@ -87,6 +88,8 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
       content = segment.component ?? null;
     }
 
+    let result: ReactNode;
+
     // If segment has a layout, wrap appropriately
     if (segment.layout) {
       // Check if this segment has loaders that need streaming
@@ -106,25 +109,23 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
           </LoaderBoundary>
         );
 
-        return (
+        result = (
           <OutletProvider content={loaderAwareContent} segment={segment}>
             {segment.layout}
           </OutletProvider>
         );
+      } else {
+        // No loaders - wrap in OutletProvider so layout can use <Outlet />
+        result = (
+          <OutletProvider content={content} segment={segment}>
+            {segment.layout}
+          </OutletProvider>
+        );
       }
-
-      // No loaders - wrap in OutletProvider so layout can use <Outlet />
-      return (
-        <OutletProvider content={content} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    }
-
-    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-    // This is common for intercept routes that use useLoader without a custom layout
-    if (segment.loaderDataPromise && segment.loaderIds) {
-      return (
+    } else if (segment.loaderDataPromise && segment.loaderIds) {
+      // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
+      // This is common for intercept routes that use useLoader without a custom layout
+      result = (
         <LoaderBoundary
           loaderDataPromise={segment.loaderDataPromise}
           loaderIds={segment.loaderIds}
@@ -136,9 +137,20 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
           {content}
         </LoaderBoundary>
       );
+    } else {
+      result = content;
+    }
+
+    // Wrap with MountContextProvider for include() scoped parallel/intercept slots
+    if (segment.mountPath) {
+      return (
+        <MountContextProvider value={segment.mountPath}>
+          {result}
+        </MountContextProvider>
+      );
     }
 
-    return content;
+    return result;
   }
 
   // Default: render child content
@@ -202,6 +214,8 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
     content = segment.component ?? null;
   }
 
+  let result: ReactNode;
+
   // If segment has a layout, wrap appropriately
   if (segment.layout) {
     // Check if this segment has loaders that need streaming
@@ -220,25 +234,23 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
         </LoaderBoundary>
       );
 
-      return (
+      result = (
         <OutletProvider content={loaderAwareContent} segment={segment}>
           {segment.layout}
         </OutletProvider>
       );
+    } else {
+      // No loaders - wrap in OutletProvider so layout can use <Outlet />
+      result = (
+        <OutletProvider content={content} segment={segment}>
+          {segment.layout}
+        </OutletProvider>
+      );
     }
-
-    // No loaders - wrap in OutletProvider so layout can use <Outlet />
-    return (
-      <OutletProvider content={content} segment={segment}>
-        {segment.layout}
-      </OutletProvider>
-    );
-  }
-
-  // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-  // This is common for intercept routes that use useLoader without a custom layout
-  if (segment.loaderDataPromise && segment.loaderIds) {
-    return (
+  } else if (segment.loaderDataPromise && segment.loaderIds) {
+    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
+    // This is common for intercept routes that use useLoader without a custom layout
+    result = (
       <LoaderBoundary
         loaderDataPromise={segment.loaderDataPromise}
         loaderIds={segment.loaderIds}
@@ -250,9 +262,20 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
         {content}
       </LoaderBoundary>
     );
+  } else {
+    result = content;
   }
 
-  return content;
+  // Wrap with MountContextProvider for include() scoped parallel/intercept slots
+  if (segment.mountPath) {
+    return (
+      <MountContextProvider value={segment.mountPath}>
+        {result}
+      </MountContextProvider>
+    );
+  }
+
+  return result;
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -290,52 +313,6 @@ export {
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-/**
- * Hook to access all loader data in the current context
- *
- * Returns a record of all loader data available in the current outlet context
- * and all parent contexts. Useful for debugging or when you need access to
- * multiple loaders.
- *
- * @returns Record of loader name to data, or empty object if no loaders
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoaderData } from "rsc-router/client";
- *
- * export function DebugPanel() {
- *   const loaderData = useLoaderData();
- *   return <pre>{JSON.stringify(loaderData, null, 2)}</pre>;
- * }
- * ```
- */
-export function useLoaderData(): Record<string, any> {
-  const context = useContext(OutletContext);
-
-  // Collect all loader data from the context chain
-  // Child loaders override parent loaders with the same name
-  const result: Record<string, any> = {};
-  const stack: OutletContextValue[] = [];
-
-  // Build stack from current to root
-  let current: OutletContextValue | null | undefined = context;
-  while (current) {
-    stack.push(current);
-    current = current.parent;
-  }
-
-  // Apply from root to current (so children override parents)
-  for (let i = stack.length - 1; i >= 0; i--) {
-    const ctx = stack[i];
-    if (ctx.loaderData) {
-      Object.assign(result, ctx.loaderData);
-    }
-  }
-
-  return result;
-}
-
 /**
  * Client-safe createLoader factory
  *
@@ -567,6 +544,7 @@ export { useHandle } from "./browser/react/use-handle.js";
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 // Location state - type-safe navigation state
 export {

package/src/context-var.ts

@@ -12,6 +12,9 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
+ * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * export const User = createVar<UserData>({ cache: false });
+ *
  * // handler
  * ctx.set(Pagination, { current: 1, total: 4 });
  *
@@ -23,18 +26,36 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
+  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
 }
 
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Setting or getting this var inside a cache() boundary or "use cache"
+   * function will throw. Use for inherently request-specific data (user
+   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
 /**
  * Create a typed context variable token.
  *
  * The returned object is used with ctx.set(token, value) and ctx.get(token)
  * for compile-time-checked data flow between handlers, layouts, and middleware.
  */
-export function createVar<T>(): ContextVar<T> {
-  return { __brand: "context-var" as const, key: Symbol() };
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
 }
 
 /**
@@ -49,6 +70,36 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+) as any;
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
 /**
  * Read a variable from the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -64,6 +115,17 @@ export function contextGet(
 /** Keys that must never be used as string variable names */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
 /**
  * Write a variable to the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -72,6 +134,7 @@ export function contextSet(
   variables: any,
   keyOrVar: string | ContextVar<any>,
   value: any,
+  options?: ContextSetOptions,
 ): void {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -80,7 +143,14 @@ export function contextSet(
       );
     }
     variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
   } else {
     variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
   }
 }