@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/client.tsx

@@ -20,6 +20,8 @@ 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
@@ -79,12 +81,15 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
               : Promise.resolve(segment.component)
           }
           fallback={segment.loading}
+          segmentId={segment.id}
         />
       );
     } else {
       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
@@ -104,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}
@@ -134,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
@@ -193,12 +207,15 @@ export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
             : Promise.resolve(segment.component)
         }
         fallback={segment.loading}
+        segmentId={segment.id}
       />
     );
   } else {
     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
@@ -217,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}
@@ -247,51 +262,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
  *
@@ -321,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
  *
@@ -396,13 +342,13 @@ export function useLoaderData(): Record<string, any> {
  */
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>
+  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
+  fetchable: true,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Implementation - function is ignored at runtime on client
@@ -410,7 +356,7 @@ export function createLoader<T>(
 export function createLoader(
   _fn: LoaderFn<any, Record<string, string | undefined>, any>,
   _fetchable?: true,
-  __injectedId?: string
+  __injectedId?: string,
 ): LoaderDefinition<any, Record<string, string | undefined>> {
   return {
     __brand: "loader",
@@ -532,11 +478,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 {
@@ -600,22 +551,50 @@ 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";
-
-// useHref hook for Django-style route name resolution
 export {
-  useHref,
-  HrefProvider,
-  HrefContext,
-  type HrefFn,
-  type HrefContextValue,
-} from "./browser/react/use-href.js";
-
-// Type-safe scoped href function for useHref<typeof patterns>()
-export type { ScopedHrefFunction } from "./href.js";
+  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";
+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 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,86 @@
+/**
+ * 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>();
+ *
+ * // 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;
+  /** Phantom field to carry the type parameter. Never set at runtime. */
+  readonly __type?: T;
+}
+
+/**
+ * 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() };
+}
+
+/**
+ * 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"
+  );
+}
+
+/**
+ * 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"]);
+
+/**
+ * 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,
+): 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;
+  } else {
+    variables[keyOrVar.key] = value;
+  }
+}

package/src/debug.ts

@@ -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> = {};
@@ -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}`),
     );
   }