@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.91

package/src/index.ts

@@ -1,18 +1,15 @@
 /**
- * rsc-router
+ * @rangojs/router
  *
- * Universal exports - types and utilities safe for both server and client
+ * Single user-facing entrypoint for all router APIs.
  *
- * For server-only exports (urls, createRouter, createLoader, etc.):
- *   import from "rsc-router/server"
+ * The "react-server" export condition selects index.rsc.ts (real implementations)
+ * vs this file (client stubs for server-only functions).
  *
- * For client-only exports (Outlet, useOutlet, etc.):
- *   import from "rsc-router/client"
+ * For client-only exports (Outlet, useOutlet, hooks, components):
+ *   import from "@rangojs/router/client"
  */
 
-// Universal rendering utilities (work on both server and client)
-export { renderSegments } from "./segment-system.js";
-
 // Error classes (can be used on both server and client)
 export {
   RouteNotFoundError,
@@ -22,22 +19,22 @@ export {
   HandlerError,
   BuildError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
+  Skip,
+  isSkip,
 } from "./errors.js";
 
 // Types (safe to import anywhere - no runtime code)
 export type {
   // Configuration types
   DocumentProps,
-  RouterEnv,
   DefaultEnv,
   RouteDefinition,
+  RouteConfig,
+  RouteDefinitionOptions,
+  TrailingSlashMode,
   // Handler types
-  Handler,            // Supports params object, path pattern, or route name
-  ScopedRouteMap,     // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
+  Handler, // Supports params object, path pattern, or route name
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -53,9 +50,6 @@ export type {
   LoaderContext,
   FetchableLoaderOptions,
   LoadOptions,
-  LoaderActionContext,
-  LoaderAction,
-  LoaderMiddlewareFn,
   // Error boundary types
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -65,12 +59,38 @@ export type {
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
 } from "./types.js";
 
+// Search params schema types
+export type {
+  SearchSchema,
+  SearchSchemaValue,
+  ResolveSearchSchema,
+  RouteSearchParams,
+  RouteParams,
+} from "./search-params.js";
+
 // Client-safe createLoader - only stores the $$id, function is not included
 // Use this when defining loaders that will be imported by client components
 export { createLoader } from "./loader.js";
 
+// Route definition types (safe to import anywhere)
+export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
+export type { TransitionConfig, ViewTransitionClass } from "./types.js";
+
+// Composition types for reusable callback factories
+export type {
+  RouteUseItem,
+  LayoutUseItem,
+  AllUseItems,
+  UseItems,
+  HandlerUseItem,
+} from "./route-types.js";
+
 // Response route types (usable in both server and client contexts)
 export type {
   ResponseHandler,
@@ -86,80 +106,215 @@ export type {
   ResponseEnvelope,
 } from "./urls.js";
 
+// Middleware context types
+export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
+
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
- * Import from "@rangojs/router/server" or use within RSC context instead.
  */
 export function urls(): never {
-  throw new Error(
-    'urls() is server-only. Import from "@rangojs/router/server" instead, or ensure you\'re using it in a server component.'
-  );
+  throw serverOnlyStubError("urls");
 }
 
 /**
  * Error-throwing stub for server-only `createRouter` function.
- * Import from "@rangojs/router/server" instead.
  */
 export function createRouter(): never {
-  throw new Error(
-    'createRouter() is server-only. Import from "@rangojs/router/server" instead.'
-  );
+  throw serverOnlyStubError("createRouter");
 }
 
 /**
  * Error-throwing stub for server-only `redirect` function.
- * Import from "@rangojs/router/server" or use within RSC context instead.
  */
 export function redirect(): never {
-  throw new Error(
-    'redirect() is server-only. Import from "@rangojs/router/server" instead.'
-  );
+  throw serverOnlyStubError("redirect");
 }
 
+// Handle API (universal - works on both server and client)
+export { createHandle, isHandle, type Handle } from "./handle.js";
+
+// Context variable API (typed ctx.set/ctx.get tokens)
+export { createVar, type ContextVar } from "./context-var.js";
+
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+export { nonce } from "./rsc/nonce.js";
+
 /**
- * Error-throwing stub for server-only `createHandle` function.
- * Import from "@rangojs/router/server" or use within RSC context instead.
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function createHandle(): never {
-  throw new Error(
-    'createHandle() is server-only. Import from "@rangojs/router/server" instead.'
-  );
+export function Prerender(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `createPrerenderHandler` function.
- * Import from "@rangojs/router/server" or use within RSC context instead.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function createPrerenderHandler(): never {
-  throw new Error(
-    'createPrerenderHandler() is server-only. Import from "@rangojs/router/server" instead.'
-  );
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
 }
 
-// Handle API (type-only exports safe for client)
-export { isHandle, type Handle } from "./handle.js";
+/**
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
+ */
+export function Static(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
+}
 
 /**
  * Error-throwing stub for server-only `getRequestContext` function.
- * Import from "@rangojs/router/server" or use within RSC context instead.
  */
 export function getRequestContext(): never {
-  throw new Error(
-    'getRequestContext() is server-only. Import from "@rangojs/router/server" instead.'
-  );
+  throw serverOnlyStubError("getRequestContext");
+}
+
+/**
+ * Error-throwing stub for server-only `cookies` function.
+ */
+export function cookies(): never {
+  throw serverOnlyStubError("cookies");
+}
+
+/**
+ * Error-throwing stub for server-only `headers` function.
+ */
+export function headers(): never {
+  throw serverOnlyStubError("headers");
+}
+
+/**
+ * Error-throwing stub for server-only `createReverse` function.
+ */
+export function createReverse(): never {
+  throw serverOnlyStubError("createReverse");
+}
+
+// Error-throwing stubs for server-only route helpers
+export function layout(): never {
+  throw serverOnlyStubError("layout");
+}
+export function cache(): never {
+  throw serverOnlyStubError("cache");
+}
+export function middleware(): never {
+  throw serverOnlyStubError("middleware");
+}
+export function revalidate(): never {
+  throw serverOnlyStubError("revalidate");
+}
+export function loader(): never {
+  throw serverOnlyStubError("loader");
+}
+export function loading(): never {
+  throw serverOnlyStubError("loading");
+}
+export function parallel(): never {
+  throw serverOnlyStubError("parallel");
+}
+export function intercept(): never {
+  throw serverOnlyStubError("intercept");
+}
+export function when(): never {
+  throw serverOnlyStubError("when");
+}
+export function errorBoundary(): never {
+  throw serverOnlyStubError("errorBoundary");
+}
+export function notFoundBoundary(): never {
+  throw serverOnlyStubError("notFoundBoundary");
+}
+export function transition(): never {
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)
-export type { RequestContext } from "./server/request-context.js";
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
+// Cookie store types (safe for client)
+export type {
+  CookieStore,
+  Cookie,
+  ReadonlyHeaders,
+} from "./server/cookie-store.js";
+
+// Built-in handles (universal — work on both server and client)
+export { Meta } from "./handles/meta.js";
+export { Breadcrumbs } from "./handles/breadcrumbs.js";
 
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
+// Breadcrumb types
+export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
+
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
-// ScopedReverseFunction is used with scopedReverse<typeof patterns>() for composable modules
-export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes } from "./reverse.js";
+export type {
+  ScopedReverseFunction,
+  ReverseFunction,
+  ExtractLocalRoutes,
+  ParamsFor,
+} from "./reverse.js";
 // scopedReverse() helper for handlers to get locally-typed reverse
 export { scopedReverse } from "./reverse.js";
 
+// Location state (universal - works on both server and client)
+export {
+  createLocationState,
+  type LocationStateDefinition,
+  type LocationStateEntry,
+  type LocationStateOptions,
+} from "./browser/react/location-state-shared.js";
+
 // Path-based response type lookup from RegisteredRoutes
 export type { PathResponse } from "./href-client.js";
+
+// Telemetry sink
+export { createConsoleSink } from "./router/telemetry.js";
+export { createOTelSink } from "./router/telemetry-otel.js";
+export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";

package/src/internal-debug.ts

@@ -0,0 +1,11 @@
+// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
+// Uses a Vite define (__RANGO_DEBUG__) for compile-time injection so it works
+// in all runtimes including Cloudflare Workers where process.env is unavailable.
+// Falls back to process.env for non-Vite contexts (tests, direct Node usage).
+export const INTERNAL_RANGO_DEBUG: boolean =
+  typeof __RANGO_DEBUG__ !== "undefined"
+    ? __RANGO_DEBUG__
+    : typeof process !== "undefined" &&
+      Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
+
+declare const __RANGO_DEBUG__: boolean;

package/src/loader.rsc.ts

@@ -5,9 +5,9 @@
  * Only used in react-server context via export conditions.
  *
  * For non-fetchable loaders: returns a loader definition with fn included
- * For fetchable loaders: stores fn in registry and returns a serializable loader with action
+ * For fetchable loaders: stores fn in registry and returns a serializable loader
  *
- * The $$id is injected by the Vite exposeLoaderId plugin as a hidden parameter.
+ * The $$id is injected by the Vite exposeInternalIds plugin as a hidden parameter.
  * Users don't need to pass any name - IDs are auto-generated from file path.
  */
 
@@ -17,90 +17,54 @@ import type {
   LoaderFn,
 } from "./types.js";
 import type { MiddlewareFn } from "./router/middleware.js";
-import { getRequestContext } from "./server/request-context.js";
+import {
+  registerFetchableLoader,
+  getFetchableLoader,
+} from "./server/fetchable-loader-store.js";
 
-// Internal registry for fetchable loaders (server-side only)
-// Maps loader $$id to its function and middleware
-//
-// WHY TWO REGISTRIES?
-// This registry (fetchableLoaderRegistry) is populated immediately when createLoader() runs.
-// The other registry in loader-registry.ts (loaderRegistry) is a cache used by the RSC handler
-// for GET-based fetching. The RSC handler calls getFetchableLoader() from here to populate
-// its cache. This separation allows:
-// 1. Server actions to look up loaders directly without going through lazy loading
-// 2. The RSC handler to use lazy loading for production builds
-// 3. Both to share the same source of truth (this registry)
-const fetchableLoaderRegistry = new Map<
-  string,
-  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
->();
-
-/**
- * Register a fetchable loader's function internally
- * Called during module initialization with the $$id
- */
-function registerFetchableLoader(
-  id: string,
-  fn: LoaderFn<any, any, any>,
-  middleware: MiddlewareFn[]
-): void {
-  fetchableLoaderRegistry.set(id, { fn, middleware });
-}
-
-/**
- * Get a fetchable loader's function from the internal registry by $$id
- *
- * This is used internally by:
- * - Server actions (loaderAction) to execute loader functions
- * - loader-registry.ts to populate the main registry for GET-based fetching
- *
- * Loaders are registered here when createLoader() is called with fetchable: true.
- * The $$id is injected by the Vite exposeLoaderId plugin.
- *
- * @param id - The loader's $$id (auto-generated from file path + export name)
- * @returns The loader function and middleware, or undefined if not found
- *
- * @internal This is primarily for internal use by the router infrastructure
- */
-export function getFetchableLoader(
-  id: string
-): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
-  return fetchableLoaderRegistry.get(id);
-}
+export { getFetchableLoader };
 
 // 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: Fetchable with `true` (no middleware)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true
+  fetchable: true,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 3: Fetchable with middleware options
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  options: FetchableLoaderOptions
+  options: FetchableLoaderOptions,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Implementation - the $$id parameter is injected by Vite plugin, not user-provided
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
   fetchable?: true | FetchableLoaderOptions,
-  // Hidden parameter injected by Vite exposeLoaderId plugin
-  __injectedId?: string
+  // Hidden parameter injected by Vite exposeInternalIds plugin
+  __injectedId?: string,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   // The $$id will be set on the returned object by Vite plugin
   // For fetchable loaders, __injectedId is also passed as a parameter
   const loaderId = __injectedId || "";
 
-  // If not fetchable, store fn in registry and return a plain object.
-  // Server-side code looks up fn via getFetchableLoader($$id).
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
+  // If not fetchable, store fn in registry (for SSR ctx.use() resolution)
+  // but mark fetchable=false so the _rsc_loader endpoint rejects it.
   if (fetchable === undefined) {
     if (fn && loaderId) {
-      registerFetchableLoader(loaderId, fn, []);
+      registerFetchableLoader(loaderId, fn, [], false);
     }
     return {
       __brand: "loader",
@@ -113,95 +77,13 @@ export function createLoader<T>(
     fetchable === true ? [] : fetchable?.middleware || [];
 
   // Register the function in the internal registry by $$id (server-side only)
-  // The server action will look it up by $$id when executed
+  // The loader fetch handler looks it up by $$id when load() is called from the client.
   if (fn && loaderId) {
-    registerFetchableLoader(loaderId, fn, middleware);
-  }
-
-  // Create server action for form-based fetching
-  // This action is serializable and can be passed to client components
-  // The loaderId is captured in closure (it's a primitive string)
-  //
-  // IMPORTANT: The signature must be (prevState, formData) for useActionState compatibility.
-  // When used with useActionState, React passes the previous state as the first argument.
-  // The prevState is ignored here since loaders are stateless data fetchers.
-  async function loaderAction(
-    _prevState: Awaited<T> | null,
-    formData: FormData
-  ): Promise<Awaited<T>> {
-    "use server";
-
-    // Look up the loader from registry by $$id
-    const registered = fetchableLoaderRegistry.get(loaderId);
-    if (!registered) {
-      throw new Error(`Loader "${loaderId}" not found in registry`);
-    }
-
-    // Get request context (env, request, url, variables) from the RSC handler
-    // This is set by runWithRequestContext in rsc/index.ts when executing actions
-    const requestCtx = getRequestContext();
-
-    // Convert FormData to params object
-    const params: Record<string, string> = {};
-    formData.forEach((value, key) => {
-      if (typeof value === "string") {
-        params[key] = value;
-      }
-    });
-
-    // Use real request/url from context, or fall back to synthetic for edge cases
-    const actionUrl = requestCtx?.url ?? new URL("http://localhost/");
-    const actionRequest = requestCtx?.request ?? new Request(actionUrl, { method: "POST" });
-    const env = requestCtx?.env ?? {};
-
-    // Merge variables from request context (app-level middleware) with loader-specific variables
-    // requestCtx.var is the shared variables object from the handler
-    const variables: Record<string, any> = { ...requestCtx?.var };
-
-    // Execute middleware for auth checks, headers, cookies
-    // Headers/cookies set on ctx.res will be merged into the final response
-    if (registered.middleware.length > 0 && requestCtx?.res) {
-      const { executeServerActionMiddleware } = await import(
-        "./router/middleware.js"
-      );
-      await executeServerActionMiddleware(
-        registered.middleware,
-        actionRequest,
-        env,
-        params,
-        variables,
-        requestCtx.res
-      );
-    }
-
-    // Build context using createHandlerContext for consistency with route handlers
-    // Variables are now accessed from request context via getRequestContext()
-    const { createHandlerContext } = await import("./router/handler-context.js");
-    const baseCtx = createHandlerContext(
-      params,
-      actionRequest,
-      actionUrl.searchParams,
-      actionUrl.pathname,
-      actionUrl,
-      env
-    );
-
-    // Extend with server action specific properties
-    const ctx: any = {
-      ...baseCtx,
-      method: "POST",
-      formData,
-    };
-
-    // Execute and return result
-    return registered.fn(ctx);
+    registerFetchableLoader(loaderId, fn, middleware, true);
   }
 
-  // Return a plain object with action for form-based fetching.
-  // loaderAction has "use server" so RSC Flight serializes it natively as a server action reference.
   return {
     __brand: "loader",
     $$id: loaderId,
-    action: loaderAction,
   };
 }

package/src/loader.ts

@@ -2,10 +2,15 @@
  * rsc-router/loader (client version)
  *
  * Client-only stub for createLoader. Returns a minimal loader definition
- * that can be passed to hooks like useLoader. The actual loader function
- * is not included - it only exists on the server.
+ * ({ __brand, $$id }) that can be passed to hooks like useLoader.
+ * The actual loader function is not included -- it only exists on the server.
  *
- * The $$id is injected by the Vite exposeLoaderId plugin.
+ * For export-only loader files, the Vite plugin replaces the entire file with
+ * object literals (bypassing this function). Those stubs only contain
+ * { __brand, $$id }.
+ * This function only runs when loaders are in mixed files (not export-only).
+ *
+ * The $$id is injected by the Vite exposeInternalIds plugin.
  */
 
 import type {
@@ -16,32 +21,44 @@ import type {
 
 // 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: Fetchable with `true` (no middleware)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true
+  fetchable: true,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // Overload 3: Fetchable with middleware options
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  options: FetchableLoaderOptions
+  options: FetchableLoaderOptions,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
 // 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,
-  __injectedId?: string
+  __injectedId?: string,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
-  // Client only needs the $$id for identification
-  // The actual loader function is only used on the server
+  const loaderId = __injectedId || "";
+
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
   return {
     __brand: "loader",
-    $$id: __injectedId || "",
+    $$id: loaderId,
   };
 }

package/src/network-error-thrower.tsx

@@ -16,6 +16,8 @@ interface NetworkErrorThrowerProps {
  * 1. Errors must be thrown during React's render phase to be caught by error boundaries
  * 2. The error occurs in async code (fetch), so we need to propagate it to React's render
  */
-export function NetworkErrorThrower({ error }: NetworkErrorThrowerProps): ReactNode {
+export function NetworkErrorThrower({
+  error,
+}: NetworkErrorThrowerProps): ReactNode {
   throw error;
 }

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {