@rangojs/router 0.0.0-experimental.7 → 0.0.0-experimental.70

package/src/client.tsx

@@ -13,13 +13,14 @@ import {
   type ClientErrorBoundaryFallbackProps,
   type ErrorInfo,
   type LoaderDefinition,
-  type LoaderFn,
   type ResolvedSegment,
 } from "./types";
 import {
   RouteContentWrapper,
   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
@@ -86,6 +87,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
@@ -105,25 +108,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}
@@ -135,9 +136,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
@@ -201,6 +213,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
@@ -219,25 +233,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}
@@ -249,51 +261,28 @@ 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>
+    );
+  }
 
-/**
- * Provider for outlet content - used internally by renderSegments
- *
- * Stores a reference to parent context so useLoader can walk up the chain
- * to find loader data from parent layouts. If this segment defines a loading
- * component, Outlet will wrap content with Suspense using that as fallback.
- */
-export function OutletProvider({
-  content,
-  parallel,
-  segment,
-  loaderData,
-  children,
-}: {
-  content: ReactNode;
-  parallel?: ResolvedSegment[];
-  segment?: ResolvedSegment;
-  loaderData?: Record<string, any>;
-  children: ReactNode;
-}): ReactNode {
-  // Get parent context to enable walking up the chain for loader lookups
-  const parentContext = useContext(OutletContext);
-
-  const value = useMemo(
-    () => ({
-      content,
-      parallel,
-      segment,
-      loaderData,
-      parent: parentContext,
-      loading: segment?.loading,
-    }),
-    [content, parallel, segment, loaderData, parentContext]
-  );
-
-  return (
-    <OutletContext.Provider value={value}>{children}</OutletContext.Provider>
-  );
+  return result;
 }
 
+// OutletProvider is defined in outlet-provider.tsx to break a circular
+// dependency between client.tsx and route-content-wrapper.tsx.
+// Imported at the top of this file for local use in Outlet/ParallelOutlet,
+// and re-exported here for backwards compatibility.
+export { OutletProvider };
+
 /**
  * Hook to access outlet content programmatically
  *
@@ -323,103 +312,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
- *
- * Creates a loader definition that can be used with useLoader().
- * This is the client-side version that only stores the $$id - the function
- * is ignored since loaders only execute on the server.
- *
- * The $$id is injected by the exposeLoaderId Vite plugin. In most cases,
- * you should import the loader directly from the server file rather than
- * creating a reference manually.
- *
- * @param fn - Loader function (ignored on client, kept for API compatibility)
- * @param _fetchable - Optional fetchable flag (ignored on client)
- * @param __injectedId - $$id injected by Vite plugin
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoader } from "rsc-router/client";
- * import { CartLoader } from "../loaders/cart"; // Import from server file
- *
- * export function CartIcon() {
- *   const cart = useLoader(CartLoader);
- *   return <span>Cart ({cart?.items.length ?? 0})</span>;
- * }
- * ```
- */
-// Overload 1: With function only (not fetchable)
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Overload 2: With function and fetchable flag
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Implementation - function is ignored at runtime on client
-// The $$id is injected by Vite plugin as hidden third parameter
-export function createLoader(
-  _fn: LoaderFn<any, Record<string, string | undefined>, any>,
-  _fetchable?: true,
-  __injectedId?: string
-): LoaderDefinition<any, Record<string, string | undefined>> {
-  return {
-    __brand: "loader",
-    $$id: __injectedId || "",
-  };
-}
-
 /**
  * Props for the ErrorBoundary component
  */
@@ -534,11 +426,16 @@ export class ErrorBoundary extends Component<
 // ============================================================================
 
 // Navigation hooks
-export {
-  useNavigation,
-  type NavigationMethods,
-  type NavigationValue,
-} from "./browser/react/use-navigation.js";
+export { useNavigation } from "./browser/react/use-navigation.js";
+export { useRouter } from "./browser/react/use-router.js";
+export { usePathname } from "./browser/react/use-pathname.js";
+export { useSearchParams } from "./browser/react/use-search-params.js";
+export { useParams } from "./browser/react/use-params.js";
+export type {
+  RouterInstance,
+  RouterNavigateOptions,
+  ReadonlyURLSearchParams,
+} from "./browser/types.js";
 
 // Action state tracking hook
 export {
@@ -585,16 +482,15 @@ export {
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle API - for accumulating data across route segments
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Handle data hook
+// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
+export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
 // Built-in handles
 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 {
@@ -602,10 +498,40 @@ export {
   useLocationState,
   type LocationStateDefinition,
   type LocationStateEntry,
+  type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
 // Type-safe href for client-side path validation
-export { href, type ValidPaths, type PatternToPath } from "./href-client.js";
+export {
+  href,
+  type ValidPaths,
+  type PatternToPath,
+  type PathResponse,
+} from "./href-client.js";
+
+// Response envelope types for consuming JSON response routes
+export type { ResponseEnvelope, ResponseError } from "./urls.js";
+
+/**
+ * Type guard for checking if a response envelope contains an error.
+ *
+ * @example
+ * ```typescript
+ * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
+ * if (isResponseError(result)) {
+ *   console.log(result.error.message, result.error.code);
+ *   return;
+ * }
+ * result.data // fully typed as Product
+ * ```
+ */
+export function isResponseError<T>(
+  result: import("./urls.js").ResponseEnvelope<T>,
+): result is import("./urls.js").ResponseEnvelope<T> & {
+  error: import("./urls.js").ResponseError;
+} {
+  return result.error !== undefined;
+}
 
 // Mount context for include() scoped components
 export { useMount } from "./browser/react/use-mount.js";
@@ -614,8 +540,8 @@ export { MountContext } from "./browser/react/mount-context.js";
 // Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
-// Type-safe scoped href function for scopedHref<typeof patterns>()
-export type { ScopedHrefFunction } from "./href.js";
+// Type-safe scoped reverse function for scopedReverse<typeof patterns>()
+export type { ScopedReverseFunction } from "./reverse.js";
 
 // Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/component-utils.ts

@@ -33,7 +33,7 @@ const CLIENT_REFERENCE = Symbol.for("react.client.reference");
  * ```
  */
 export function isClientComponent(
-  component: ComponentType<unknown> | unknown
+  component: ComponentType<unknown> | unknown,
 ): boolean {
   if (typeof component !== "function") {
     return false;
@@ -52,13 +52,13 @@ export function isClientComponent(
  */
 export function assertClientComponent(
   component: ComponentType<unknown> | unknown,
-  name: string
+  name: string,
 ): asserts component is ComponentType<unknown> {
   if (typeof component !== "function") {
     throw new Error(
       `${name} must be a client component function with "use client" directive. ` +
         `Make sure to pass the component itself, not a JSX element: ` +
-        `${name}: My${capitalize(name)} (correct) vs ${name}: <My${capitalize(name)} /> (incorrect)`
+        `${name}: My${capitalize(name)} (correct) vs ${name}: <My${capitalize(name)} /> (incorrect)`,
     );
   }
 
@@ -66,7 +66,7 @@ export function assertClientComponent(
     throw new Error(
       `${name} must be a client component with "use client" directive at the top of the file. ` +
         `Server components cannot be used as the ${name} because their function reference ` +
-        `cannot be serialized in the RSC payload. Add "use client" to your ${name} file.`
+        `cannot be serialized in the RSC payload. Add "use client" to your ${name} file.`,
     );
   }
 }

package/src/components/DefaultDocument.tsx

@@ -11,7 +11,11 @@ import { MetaTags } from "../handles/MetaTags.js";
  * Uses suppressHydrationWarning on <html> because the theme script
  * may modify class/style attributes before React hydrates.
  */
-export function DefaultDocument({ children }: { children: ReactNode }): ReactElement {
+export function DefaultDocument({
+  children,
+}: {
+  children: ReactNode;
+}): ReactElement {
   return (
     <html lang="en" suppressHydrationWarning>
       <head>

package/src/context-var.ts

@@ -0,0 +1,156 @@
+/**
+ * Typed context variables for ctx.set() / ctx.get().
+ *
+ * createVar<T>() produces a typed token that handlers set and layouts/middleware
+ * read. The token carries a unique Symbol used as the property key on the
+ * per-request variables object — no build-time processing, no IDs.
+ *
+ * @example
+ * ```ts
+ * import { createVar } from "@rangojs/router";
+ *
+ * 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 });
+ *
+ * // layout
+ * const pg = ctx.get(Pagination); // PaginationData | undefined
+ * ```
+ */
+
+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>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
+}
+
+/**
+ * Type guard: is the value a ContextVar token?
+ */
+export function isContextVar(value: unknown): value is ContextVar<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "context-var"
+  );
+}
+
+/**
+ * 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).
+ */
+export function contextGet(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): any {
+  if (typeof keyOrVar === "string") return variables[keyOrVar];
+  return variables[keyOrVar.key];
+}
+
+/** 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).
+ */
+export function contextSet(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+  value: any,
+  options?: ContextSetOptions,
+): void {
+  if (typeof keyOrVar === "string") {
+    if (FORBIDDEN_KEYS.has(keyOrVar)) {
+      throw new Error(
+        `ctx.set(): "${keyOrVar}" is a reserved key and cannot be used as a variable name.`,
+      );
+    }
+    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);
+    }
+  }
+}

package/src/debug.ts

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -34,7 +34,7 @@ export interface SerializedManifest {
  * Serialize a manifest Map into a JSON-friendly structure
  */
 export function serializeManifest(
-  manifest: Map<string, EntryData>
+  manifest: Map<string, EntryData>,
 ): SerializedManifest {
   const routes: Record<string, SerializedEntry> = {};
   const layouts: Record<string, SerializedEntry> = {};
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 
@@ -92,7 +92,7 @@ export function serializeManifest(
  */
 export function compareManifests(
   oldManifest: SerializedManifest,
-  newManifest: SerializedManifest
+  newManifest: SerializedManifest,
 ): {
   addedRoutes: string[];
   removedRoutes: string[];
@@ -113,10 +113,20 @@ export function compareManifests(
 } {
   const addedRoutes: string[] = [];
   const removedRoutes: string[] = [];
-  const changedRoutes: Array<{ key: string; field: string; old: any; new: any }> = [];
+  const changedRoutes: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }> = [];
   const addedLayouts: string[] = [];
   const removedLayouts: string[] = [];
-  const changedLayouts: Array<{ key: string; field: string; old: any; new: any }> = [];
+  const changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }> = [];
 
   // Compare routes
   const oldRouteKeys = new Set(Object.keys(oldManifest.routes));
@@ -191,7 +201,7 @@ export function compareManifests(
  * Format manifest diff as a human-readable string
  */
 export function formatManifestDiff(
-  diff: ReturnType<typeof compareManifests>
+  diff: ReturnType<typeof compareManifests>,
 ): string {
   const lines: string[] = [];
 
@@ -208,7 +218,7 @@ export function formatManifestDiff(
   if (diff.changedRoutes.length > 0) {
     lines.push("Changed routes:");
     diff.changedRoutes.forEach((c) =>
-      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
     );
   }
 
@@ -225,7 +235,7 @@ export function formatManifestDiff(
   if (diff.changedLayouts.length > 0) {
     lines.push("Changed layouts:");
     diff.changedLayouts.forEach((c) =>
-      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
     );
   }