@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.21

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
  *
@@ -396,13 +388,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 +402,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 +524,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 +597,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

@@ -5,13 +5,17 @@ import { MetaTags } from "../handles/MetaTags.js";
 
 /**
  * Default document component that provides a basic HTML structure.
- * Used when no custom document is provided to createRSCRouter.
+ * Used when no custom document is provided to createRouter.
  * Includes MetaTags for automatic charset, viewport, and route meta support.
  *
  * 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

@@ -0,0 +1,243 @@
+/**
+ * Debug utilities for manifest inspection and comparison
+ */
+
+import type { EntryData } from "./server/context";
+
+/**
+ * Serialized entry for debug output
+ */
+export interface SerializedEntry {
+  id: string;
+  shortCode: string;
+  type: string;
+  parentShortCode: string | null;
+  pattern?: string;
+  hasLoader: boolean;
+  hasMiddleware: boolean;
+  hasErrorBoundary: boolean;
+  parallelCount: number;
+  interceptCount: number;
+}
+
+/**
+ * Serialized manifest structure
+ */
+export interface SerializedManifest {
+  routes: Record<string, SerializedEntry>;
+  layouts: Record<string, SerializedEntry>;
+  totalRoutes: number;
+  totalLayouts: number;
+}
+
+/**
+ * Serialize a manifest Map into a JSON-friendly structure
+ */
+export function serializeManifest(
+  manifest: Map<string, EntryData>,
+): SerializedManifest {
+  const routes: Record<string, SerializedEntry> = {};
+  const layouts: Record<string, SerializedEntry> = {};
+
+  // Collect all entries including parents
+  const allEntries = new Map<string, EntryData>();
+
+  for (const [key, entry] of manifest.entries()) {
+    allEntries.set(key, entry);
+
+    // Walk up parent chain to collect all layouts
+    let parent = entry.parent;
+    while (parent) {
+      if (!allEntries.has(parent.id)) {
+        allEntries.set(parent.id, parent);
+      }
+      parent = parent.parent;
+    }
+  }
+
+  for (const [key, entry] of allEntries.entries()) {
+    const serialized: SerializedEntry = {
+      id: entry.id,
+      shortCode: entry.shortCode,
+      type: entry.type,
+      parentShortCode: entry.parent?.shortCode ?? null,
+      hasLoader: entry.loader?.length > 0,
+      hasMiddleware: entry.middleware?.length > 0,
+      hasErrorBoundary: entry.errorBoundary?.length > 0,
+      parallelCount: entry.parallel?.length ?? 0,
+      interceptCount: entry.intercept?.length ?? 0,
+    };
+
+    if (entry.type === "route" && "pattern" in entry) {
+      serialized.pattern = entry.pattern;
+    }
+
+    if (entry.type === "route") {
+      routes[key] = serialized;
+    } else if (entry.type === "layout" || entry.type === "cache") {
+      layouts[key] = serialized;
+    }
+  }
+
+  return {
+    routes,
+    layouts,
+    totalRoutes: Object.keys(routes).length,
+    totalLayouts: Object.keys(layouts).length,
+  };
+}
+
+/**
+ * Compare two manifests and return differences
+ */
+export function compareManifests(
+  oldManifest: SerializedManifest,
+  newManifest: SerializedManifest,
+): {
+  addedRoutes: string[];
+  removedRoutes: string[];
+  changedRoutes: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }>;
+  addedLayouts: string[];
+  removedLayouts: string[];
+  changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }>;
+} {
+  const addedRoutes: string[] = [];
+  const removedRoutes: string[] = [];
+  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;
+  }> = [];
+
+  // Compare routes
+  const oldRouteKeys = new Set(Object.keys(oldManifest.routes));
+  const newRouteKeys = new Set(Object.keys(newManifest.routes));
+
+  for (const key of newRouteKeys) {
+    if (!oldRouteKeys.has(key)) {
+      addedRoutes.push(key);
+    }
+  }
+
+  for (const key of oldRouteKeys) {
+    if (!newRouteKeys.has(key)) {
+      removedRoutes.push(key);
+    } else {
+      // Compare fields
+      const oldEntry = oldManifest.routes[key];
+      const newEntry = newManifest.routes[key];
+      for (const field of Object.keys(oldEntry) as (keyof SerializedEntry)[]) {
+        if (oldEntry[field] !== newEntry[field]) {
+          changedRoutes.push({
+            key,
+            field,
+            old: oldEntry[field],
+            new: newEntry[field],
+          });
+        }
+      }
+    }
+  }
+
+  // Compare layouts
+  const oldLayoutKeys = new Set(Object.keys(oldManifest.layouts));
+  const newLayoutKeys = new Set(Object.keys(newManifest.layouts));
+
+  for (const key of newLayoutKeys) {
+    if (!oldLayoutKeys.has(key)) {
+      addedLayouts.push(key);
+    }
+  }
+
+  for (const key of oldLayoutKeys) {
+    if (!newLayoutKeys.has(key)) {
+      removedLayouts.push(key);
+    } else {
+      const oldEntry = oldManifest.layouts[key];
+      const newEntry = newManifest.layouts[key];
+      for (const field of Object.keys(oldEntry) as (keyof SerializedEntry)[]) {
+        if (oldEntry[field] !== newEntry[field]) {
+          changedLayouts.push({
+            key,
+            field,
+            old: oldEntry[field],
+            new: newEntry[field],
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    addedRoutes,
+    removedRoutes,
+    changedRoutes,
+    addedLayouts,
+    removedLayouts,
+    changedLayouts,
+  };
+}
+
+/**
+ * Format manifest diff as a human-readable string
+ */
+export function formatManifestDiff(
+  diff: ReturnType<typeof compareManifests>,
+): string {
+  const lines: string[] = [];
+
+  if (diff.addedRoutes.length > 0) {
+    lines.push("Added routes:");
+    diff.addedRoutes.forEach((r) => lines.push(`  + ${r}`));
+  }
+
+  if (diff.removedRoutes.length > 0) {
+    lines.push("Removed routes:");
+    diff.removedRoutes.forEach((r) => lines.push(`  - ${r}`));
+  }
+
+  if (diff.changedRoutes.length > 0) {
+    lines.push("Changed routes:");
+    diff.changedRoutes.forEach((c) =>
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
+    );
+  }
+
+  if (diff.addedLayouts.length > 0) {
+    lines.push("Added layouts:");
+    diff.addedLayouts.forEach((l) => lines.push(`  + ${l}`));
+  }
+
+  if (diff.removedLayouts.length > 0) {
+    lines.push("Removed layouts:");
+    diff.removedLayouts.forEach((l) => lines.push(`  - ${l}`));
+  }
+
+  if (diff.changedLayouts.length > 0) {
+    lines.push("Changed layouts:");
+    diff.changedLayouts.forEach((c) =>
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
+    );
+  }
+
+  return lines.length > 0 ? lines.join("\n") : "No differences found";
+}