@rangojs/router 0.0.0-experimental.106 → 0.0.0-experimental.108

package/src/__augment-tests__/augmented.check.ts

@@ -0,0 +1,64 @@
+/**
+ * Compile-only assertions for the AUGMENTED Rango namespace.
+ *
+ * Pins the type-safety contract a consumer gets after augmenting Env, Vars, and
+ * GeneratedRouteMap. A regression in the fallback chains (global-namespace.ts)
+ * turns these into tsc errors. Run via tsconfig.augment-check.json.
+ */
+import "./augment.js";
+import type { Handler, RouteParams, RouteSearchParams } from "../index.js";
+import type { DefaultRouteName } from "../types/global-namespace.js";
+import { href } from "../href-client.js";
+import type { TestBindings } from "./augment.js";
+
+type Expect<T extends true> = T;
+type Equal<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+
+// Env: ctx.env resolves to the augmented bindings, not `unknown`/`any`.
+const envHandler: Handler<"home"> = (ctx) => {
+  type _envIsBindings = Expect<Equal<typeof ctx.env, TestBindings>>;
+  ctx.env.DB.query("select 1");
+  // @ts-expect-error - unknown binding is rejected once Env is augmented
+  ctx.env.MISSING();
+  return null;
+};
+void envHandler;
+
+// Vars: ctx.get is keyed by the augmented Vars.
+const varsHandler: Handler<"home"> = (ctx) => {
+  const user = ctx.get("user");
+  type _userTyped = Expect<
+    Equal<typeof user, { id: string; role: "admin" | "user" } | undefined>
+  >;
+  // @ts-expect-error - unknown var key is rejected once Vars is augmented
+  ctx.get("nope");
+  return null;
+};
+void varsHandler;
+
+// routeName narrows to the generated route names.
+type _routeName = Expect<
+  Equal<DefaultRouteName, "home" | "blog.post" | "search">
+>;
+
+// RouteParams / RouteSearchParams resolve from the generated map with no
+// explicit route map argument.
+type _params = Expect<Equal<RouteParams<"blog.post">, { slug: string }>>;
+type _search = Expect<
+  Equal<RouteSearchParams<"search">, { q: string | undefined; page?: number }>
+>;
+
+// href / ValidPaths read GeneratedRouteMap even without a manual RegisteredRoutes
+// augmentation — this is the core of the "rango generate alone enables typed
+// href()" guarantee. The paths below come from the generated map in augment.ts.
+href("/");
+href("/blog/anything");
+href("/search");
+// @ts-expect-error - path is not in the generated route map
+href("/not-a-route");
+
+// Reference the top-level assertion aliases so they are unambiguously evaluated.
+export type _Assertions = [_routeName, _params, _search];

package/src/browser/index.ts

@@ -1,9 +1,9 @@
 // ============================================================================
-// Browser Module - Browser entry point for RSC Router
+// Browser Module - Browser entry point for Rango
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "rsc-router/browser";
 //
 // For React components (Link, useNavigation, etc.):
 //   import { Link, useNavigation, useAction, href } from "rsc-router/client";
@@ -13,6 +13,6 @@
 // Browser app initialization
 export {
   initBrowserApp,
-  RSCRouter,
+  Rango,
   type InitBrowserAppOptions,
 } from "./rsc-router.js";

package/src/browser/react/location-state-shared.ts

@@ -125,7 +125,7 @@ export function createLocationState<TState>(
   function getKey(): string {
     if (!_key && process.env.NODE_ENV === "development") {
       throw new Error(
-        "[rsc-router] createLocationState key not set. " +
+        "[rango] createLocationState key not set. " +
           "Make sure the exposeInternalIds Vite plugin is enabled and " +
           "the state is exported with: export const MyState = createLocationState(...)",
       );
@@ -176,7 +176,7 @@ export function createLocationState<TState>(
     value: (value: TState): void => {
       if (typeof window === "undefined") {
         throw new Error(
-          "[rsc-router] LocationState.write() is client-only. " +
+          "[rango] LocationState.write() is client-only. " +
             "It mutates window.history.state and cannot run on the server.",
         );
       }
@@ -195,7 +195,7 @@ export function createLocationState<TState>(
     value: (): void => {
       if (typeof window === "undefined") {
         throw new Error(
-          "[rsc-router] LocationState.delete() is client-only. " +
+          "[rango] LocationState.delete() is client-only. " +
             "It mutates window.history.state and cannot run on the server.",
         );
       }

package/src/browser/rsc-router.tsx

@@ -128,7 +128,7 @@ export interface BrowserAppContext {
 let browserAppContext: BrowserAppContext | null = null;
 
 /**
- * Initialize the browser app. Must be called before rendering RSCRouter.
+ * Initialize the browser app. Must be called before rendering Rango.
  *
  * This function:
  * - Loads the initial RSC payload from the stream
@@ -325,11 +325,11 @@ export async function initBrowserApp(
         // full lifecycle (fetching + streaming, before commit) without
         // blocking on server actions.
         if (eventController.getState().isNavigating) {
-          console.log("[RSCRouter] HMR: Skipping — navigation in progress");
+          console.log("[Rango] HMR: Skipping — navigation in progress");
           return;
         }
 
-        console.log("[RSCRouter] HMR: Server update, refetching RSC");
+        console.log("[Rango] HMR: Server update, refetching RSC");
 
         const abort = new AbortController();
         hmrAbort = abort;
@@ -367,7 +367,7 @@ export async function initBrowserApp(
           const newVersion = payload.metadata.version;
           if (newVersion && newVersion !== version) {
             console.log(
-              "[RSCRouter] HMR: version changed",
+              "[Rango] HMR: version changed",
               version,
               "→",
               newVersion,
@@ -415,10 +415,10 @@ export async function initBrowserApp(
 
           await streamComplete;
           handle.complete(new URL(window.location.href));
-          console.log("[RSCRouter] HMR: RSC stream complete");
+          console.log("[Rango] HMR: RSC stream complete");
         } catch (err) {
           if (abort.signal.aborted) return;
-          console.warn("[RSCRouter] HMR: Refetch failed, reloading page", err);
+          console.warn("[Rango] HMR: Refetch failed, reloading page", err);
           window.location.reload();
           return;
         } finally {
@@ -430,7 +430,7 @@ export async function initBrowserApp(
     });
   }
 
-  // Store context for RSCRouter component
+  // Store context for Rango component
   const context: BrowserAppContext = {
     store,
     eventController,
@@ -454,7 +454,7 @@ export async function initBrowserApp(
 export function getBrowserAppContext(): BrowserAppContext {
   if (!browserAppContext) {
     throw new Error(
-      "RSCRouter: initBrowserApp() must be called before rendering RSCRouter",
+      "Rango: initBrowserApp() must be called before rendering Rango",
     );
   }
   return browserAppContext;
@@ -468,18 +468,18 @@ export function resetBrowserAppContext(): void {
 }
 
 /**
- * Props for the RSCRouter component
+ * Props for the Rango component
  */
-export interface RSCRouterProps {}
+export interface RangoProps {}
 
 /**
- * RSCRouter component - renders the RSC router with all internal wiring.
+ * Rango component - renders the RSC router with all internal wiring.
  *
  * Must be called after initBrowserApp() has completed.
  *
  * @example
  * ```tsx
- * import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "rsc-router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *
@@ -489,14 +489,14 @@ export interface RSCRouterProps {}
  *   hydrateRoot(
  *     document,
  *     <React.StrictMode>
- *       <RSCRouter />
+ *       <Rango />
  *     </React.StrictMode>
  *   );
  * }
  * main();
  * ```
  */
-export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
+export function Rango(_props: RangoProps): React.ReactElement {
   const {
     store,
     eventController,

package/src/browser/segment-structure-assert.ts

@@ -48,7 +48,7 @@ export function assertSegmentStructure(
 
   if (cachedCategory !== incomingCategory) {
     console.warn(
-      `[RSC Router] Tree structure mismatch detected in ${context} ` +
+      `[Rango] Tree structure mismatch detected in ${context} ` +
         `for segment "${cached.id}": loading category changed from ` +
         `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
         `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
@@ -64,7 +64,7 @@ export function assertSegmentStructure(
   const incomingHasMount = !!incoming.mountPath;
   if (cachedHasMount !== incomingHasMount) {
     console.warn(
-      `[RSC Router] MountContextProvider mismatch detected in ${context} ` +
+      `[Rango] MountContextProvider mismatch detected in ${context} ` +
         `for segment "${cached.id}": mountPath changed from ` +
         `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
         `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +

package/src/build/generate-manifest.ts

@@ -11,7 +11,7 @@
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems } from "../route-types.js";
 import { extractStaticPrefix } from "../router/pattern-matching.js";
-import { RSCRouterContext, runWithPrefixes } from "../server/context.js";
+import { RangoContext, runWithPrefixes } from "../server/context.js";
 import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
@@ -93,7 +93,7 @@ function buildPrefixTreeNode(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,
@@ -296,7 +296,7 @@ export function generateManifestFull<TEnv>(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,

package/src/build/route-types/codegen.ts

@@ -23,7 +23,7 @@ export function generatePerModuleTypesSource(
   const valid = routes.filter(({ name }) => {
     if (!name || /["'\\`\n\r]/.test(name)) {
       console.warn(
-        `[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`,
+        `[rango] Skipping route with invalid name: ${JSON.stringify(name)}`,
       );
       return false;
     }
@@ -42,7 +42,7 @@ export function generatePerModuleTypesSource(
   for (const { name, pattern, params, search } of valid) {
     if (deduped.has(name)) {
       console.warn(
-        `[rsc-router] Duplicate route name "${name}" — keeping first definition`,
+        `[rango] Duplicate route name "${name}" — keeping first definition`,
       );
       continue;
     }
@@ -59,7 +59,7 @@ export function generatePerModuleTypesSource(
 }
 
 /**
- * Generates a .ts file that augments RSCRouter.GeneratedRouteMap
+ * Generates a .ts file that augments Rango.GeneratedRouteMap
  * with route name -> pattern mappings. This enables Handler<"routeName">
  * without circular references since the file has no imports from the app.
  */
@@ -94,7 +94,7 @@ ${objectBody}
 } as const;
 
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
   }
 }

package/src/build/route-types/include-resolution.ts

@@ -376,7 +376,7 @@ export function buildCombinedRouteMapWithSearch(
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
   if (visited.has(key)) {
-    console.warn(`[rsc-router] Circular include detected, skipping: ${key}`);
+    console.warn(`[rango] Circular include detected, skipping: ${key}`);
     return { routes: {}, searchSchemas: {} };
   }
   visited.add(key);

package/src/build/route-types/per-module-writer.ts

@@ -106,7 +106,7 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       if (varNames.length > 0 && !existsSync(genPath)) {
         writeFileSync(genPath, generatePerModuleTypesSource([]));
         console.log(
-          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+          `[rango] Generated route types (placeholder) -> ${genPath}`,
         );
       }
       return;
@@ -118,11 +118,11 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       : null;
     if (existing !== genSource) {
       writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+      console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
+      `[rango] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
     );
   }
 }

package/src/build/route-types/router-processing.ts

@@ -61,7 +61,7 @@ function findRouterFilesRecursive(
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return;
   }
@@ -142,7 +142,7 @@ export function findNestedRouterConflict(
 
 export function formatNestedRouterConflictError(
   conflict: { ancestor: string; nested: string },
-  prefix = "[rsc-router]",
+  prefix = "[rango]",
 ): string {
   return (
     `${prefix} Nested router roots are not supported.\n` +
@@ -536,7 +536,7 @@ export function writeCombinedRouteTypes(
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -611,7 +611,7 @@ export function writeCombinedRouteTypes(
       }
       writeFileSync(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
       );
     }
   }

package/src/build/route-types/scan-filter.ts

@@ -54,7 +54,7 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return results;
   }

package/src/errors.ts

@@ -1,5 +1,5 @@
 /**
- * Custom error classes for RSC Router
+ * Custom error classes for Rango
  *
  * All errors include:
  * - Descriptive names for easy identification

package/src/handle.ts

@@ -97,7 +97,7 @@ export function createHandle<TData, TAccumulated = TData[]>(
 
   if (!handleId && process.env.NODE_ENV === "development") {
     throw new Error(
-      "[rsc-router] Handle is missing $$id. " +
+      "[rango] Handle is missing $$id. " +
         "Make sure the exposeInternalIds Vite plugin is enabled and " +
         "the handle is exported with: export const MyHandle = createHandle(...)",
     );
@@ -151,7 +151,7 @@ export function collectHandleData<TData, TAccumulated>(
   const collectFn = getCollectFn(handle.$$id);
   if (!collectFn && process.env.NODE_ENV !== "production") {
     console.warn(
-      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+      `[rango] Handle "${handle.$$id}" has no registered collect function. ` +
         `Falling back to flat array. Ensure the handle module is imported so ` +
         `createHandle() runs and registers the collect function.`,
     );

package/src/href-client.ts

@@ -140,7 +140,7 @@ type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
 /**
  * Union of all valid paths from registered routes
  *
- * Generated from RSCRouter.RegisteredRoutes via module augmentation.
+ * Generated from Rango.RegisteredRoutes via module augmentation.
  * Allows optional query strings and hash fragments.
  */
 export type ValidPaths<TRoutes = GetRegisteredRoutes> =

package/src/index.rsc.ts

@@ -68,7 +68,7 @@ export type {
 
 // Router options type (server-only, so import directly)
 export type {
-  RSCRouterOptions,
+  RangoOptions,
   SSRStreamMode,
   SSROptions,
   ResolveStreamingContext,
@@ -152,7 +152,7 @@ export {
 // Core router (server-side)
 export {
   createRouter,
-  type RSCRouter,
+  type Rango,
   type RootLayoutProps,
   type RouterRequestInput,
 } from "./router.js";

package/src/loader.rsc.ts

@@ -54,7 +54,7 @@ export function createLoader<T>(
 
   if (!loaderId && process.env.NODE_ENV === "development") {
     throw new Error(
-      "[rsc-router] Loader is missing $$id. " +
+      "[rango] Loader is missing $$id. " +
         "Make sure the exposeInternalIds Vite plugin is enabled and " +
         "the loader is exported with: export const MyLoader = createLoader(...)",
     );

package/src/loader.ts

@@ -51,7 +51,7 @@ export function createLoader<T>(
 
   if (!loaderId && process.env.NODE_ENV === "development") {
     throw new Error(
-      "[rsc-router] Loader is missing $$id. " +
+      "[rango] Loader is missing $$id. " +
         "Make sure the exposeInternalIds Vite plugin is enabled and " +
         "the loader is exported with: export const MyLoader = createLoader(...)",
     );

package/src/prerender.ts

@@ -69,9 +69,9 @@ type BuildReverseFunction = [DefaultReverseRouteMap] extends [
  * Default route map for Prerender named route resolution.
  * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
  */
-type DefaultPrerenderRouteMap = keyof RSCRouter.GeneratedRouteMap extends never
+type DefaultPrerenderRouteMap = keyof Rango.GeneratedRouteMap extends never
   ? {}
-  : RSCRouter.GeneratedRouteMap;
+  : Rango.GeneratedRouteMap;
 
 /** Extract params from a route map entry (string pattern or { path } object). */
 type ExtractParamsFromEntry<TEntry> = TEntry extends string
@@ -378,7 +378,7 @@ export function Prerender<TParams extends Record<string, any>>(
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Prerender: missing $$id. " +
+      "[rango] Prerender: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
@@ -499,7 +499,7 @@ export function Passthrough<
 ): PassthroughHandlerDefinition<TParams, TEnv> {
   if (!isPrerenderHandler(prerenderDef)) {
     throw new Error(
-      "[rsc-router] Passthrough: first argument must be a Prerender() definition.",
+      "[rango] Passthrough: first argument must be a Prerender() definition.",
     );
   }
   return {

package/src/route-definition/dsl-helpers.ts

@@ -16,7 +16,7 @@ import {
 } from "../server/context";
 import { invariant } from "../errors";
 import { isCachedFunction } from "../cache/taint.js";
-import { RSCRouterContext } from "../server/context";
+import { RangoContext } from "../server/context";
 import { isStaticHandler } from "../static-handler.js";
 import RootLayout from "../server/root-layout";
 import type {
@@ -232,7 +232,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
   } else if (typeof optionsOrChildren === "string") {
     // cache('profileName') or cache('profileName', () => [...])
     // Resolve from context-scoped profiles (set per-router via HelperContext).
-    const ctxStore = RSCRouterContext.getStore();
+    const ctxStore = RangoContext.getStore();
     const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
     invariant(
       profile,

package/src/route-definition/helpers-types.ts

@@ -198,10 +198,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
     // Global: unprefixed, params inferred from global route map
-    <K extends keyof RSCRouter.GeneratedRouteMap & string>(
+    <K extends keyof Rango.GeneratedRouteMap & string>(
       slotName: `@${string}`,
       routeName: K,
-      handler: ReactNode | Handler<K, RSCRouter.GeneratedRouteMap, TEnv>,
+      handler: ReactNode | Handler<K, Rango.GeneratedRouteMap, TEnv>,
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
   };

package/src/router/error-handling.ts

@@ -1,7 +1,7 @@
 /**
  * Router Error Handling Utilities
  *
- * Error boundary and not-found boundary handling for RSC Router.
+ * Error boundary and not-found boundary handling for Rango.
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
 

package/src/router/lazy-includes.ts

@@ -2,7 +2,7 @@ import { registerRouteMap } from "../route-map-builder.js";
 import { extractStaticPrefix } from "./pattern-matching.js";
 import {
   type EntryData,
-  RSCRouterContext,
+  RangoContext,
   runWithPrefixes,
   getIsolatedLazyParent,
 } from "../server/context";
@@ -131,7 +131,7 @@ export function evaluateLazyEntry<TEnv = any>(
     }
   }
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns,

package/src/router/metrics.ts

@@ -1,7 +1,7 @@
 /**
  * Router Metrics Utilities
  *
- * Performance metrics collection and reporting for RSC Router.
+ * Performance metrics collection and reporting for Rango.
  */
 
 import type { MetricsStore, PerformanceMetric } from "../server/context";

package/src/router/middleware-types.ts

@@ -140,7 +140,7 @@ export interface MiddlewareContext<
  * @template TEnv - Environment type - defaults to any for internal flexibility
  * @template TParams - URL params type (typed for route middleware)
  *
- * When using middleware with global augmentation (RSCRouter.Env), explicitly
+ * When using middleware with global augmentation (Rango.Env), explicitly
  * annotate your middleware functions, or the types will be inferred from context:
  *
  * @example

package/src/router/prerender-match.ts

@@ -126,7 +126,7 @@ export async function matchForPrerender<TEnv = any>(
             get env() {
               if (buildEnv !== undefined) return buildEnv;
               throw new Error(
-                "[rsc-router] ctx.env is not available during dev-mode getParams(). " +
+                "[rango] ctx.env is not available during dev-mode getParams(). " +
                   "Configure buildEnv in your rango() plugin options to enable build-time env access.",
               );
             },