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

package/src/router/router-interfaces.ts

@@ -2,7 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
-import type { UrlBuilder } from "../urls/pattern-types.js";
+import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
@@ -13,7 +13,7 @@ import type {
 } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
-import type { RSCRouterOptions, RootLayoutProps } from "./router-options.js";
+import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
 import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 
@@ -49,16 +49,16 @@ type MergeRoutesWithResponses<
 };
 
 /**
- * Public RSC Router interface — the user-facing API surface.
+ * Public Rango router interface — the user-facing API surface.
  *
  * Users interact with this type when building and using routers.
- * Internal framework code uses RSCRouterInternal (via toInternal()) to access
+ * Internal framework code uses RangoInternal (via toInternal()) to access
  * matching, build-time, and configuration members that are not part of the
  * public contract.
  *
  * TRoutes accumulates all registered route types through the builder chain.
  */
-export interface RSCRouter<
+export interface Rango<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
 > {
@@ -89,16 +89,16 @@ export interface RSCRouter<
    * ])
    * ```
    */
-  routes<T extends UrlPatterns<TEnv, any>>(
-    patterns: T,
-  ): RSCRouter<
+  routes<T extends UrlPatterns<any, any, any>>(
+    patterns: T & EnvCompatible<T, TEnv>,
+  ): Rango<
     TEnv,
     TRoutes &
       (NonNullable<T["_routes"]> extends Record<string, unknown>
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
-  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
+  routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -114,7 +114,7 @@ export interface RSCRouter<
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
+  ): Rango<TEnv, TRoutes>;
 
   /**
    * Type-safe URL builder for registered routes
@@ -141,7 +141,7 @@ export interface RSCRouter<
    * type AppRoutes = typeof _router.routeMap;
    *
    * declare global {
-   *   namespace RSCRouter {
+   *   namespace Rango {
    *     interface RegisteredRoutes extends AppRoutes {}
    *   }
    * }
@@ -177,16 +177,16 @@ export interface RSCRouter<
 }
 
 /**
- * Internal RSC Router interface — the full framework-facing API.
+ * Internal Rango router interface — the full framework-facing API.
  *
  * This type includes all members used by the Vite plugin, RSC handler,
  * pre-rendering pipeline, and other framework internals. It is NOT exported
  * from the public package API.
  *
- * Use toInternal(router) to assert a public RSCRouter into this type
+ * Use toInternal(router) to assert a public Rango into this type
  * at the boundary where framework code receives a user-provided router.
  */
-export interface RSCRouterInternal<
+export interface RangoInternal<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
 > {
@@ -206,18 +206,24 @@ export interface RSCRouterInternal<
   readonly basename: string | undefined;
 
   /**
-   * Register routes using URL patterns from urls() or a builder function
-   */
-  routes<T extends UrlPatterns<TEnv, any>>(
-    patterns: T,
-  ): RSCRouter<
+   * Register routes using URL patterns from urls() or a builder function.
+   *
+   * Env compatibility is checked by EnvCompatible: an env-agnostic urls() block
+   * (its env is `unknown` — e.g. a shared module, or an app that does not augment
+   * `Rango.Env`) attaches to any router, while a urls<TEnv>() block carrying a
+   * concrete env is accepted only when this router's `TEnv` satisfies it. So a
+   * `urls<{ DB }>()` cannot be mounted on a `createRouter<{}>()`.
+   */
+  routes<T extends UrlPatterns<any, any, any>>(
+    patterns: T & EnvCompatible<T, TEnv>,
+  ): Rango<
     TEnv,
     TRoutes &
       (NonNullable<T["_routes"]> extends Record<string, unknown>
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
-  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
+  routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -225,7 +231,7 @@ export interface RSCRouterInternal<
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
+  ): Rango<TEnv, TRoutes>;
 
   /**
    * Type-safe URL builder for registered routes
@@ -247,17 +253,17 @@ export interface RSCRouterInternal<
    * Error callback for monitoring/alerting
    * Called when errors occur in loaders, actions, or routes
    */
-  readonly onError?: RSCRouterOptions<TEnv>["onError"];
+  readonly onError?: RangoOptions<TEnv>["onError"];
 
   /**
    * Cache configuration
    */
-  readonly cache?: RSCRouterOptions<TEnv>["cache"];
+  readonly cache?: RangoOptions<TEnv>["cache"];
 
   /**
    * Not found component to render when no route matches
    */
-  readonly notFound?: RSCRouterOptions<TEnv>["notFound"];
+  readonly notFound?: RangoOptions<TEnv>["notFound"];
 
   /**
    * Resolved theme configuration (null if theme not enabled)
@@ -469,16 +475,16 @@ export interface RSCRouterInternal<
 }
 
 /**
- * Assert a public RSCRouter into the internal type.
+ * Assert a public Rango into the internal type.
  *
  * Use this at the boundary where framework code receives a user-provided
  * router and needs access to internal members (match, config, build-time).
  * The cast is safe because createRouter() always produces an object that
- * satisfies RSCRouterInternal; the public type is just a narrower view.
+ * satisfies RangoInternal; the public type is just a narrower view.
  */
 export function toInternal<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
->(router: RSCRouter<TEnv, TRoutes>): RSCRouterInternal<TEnv, TRoutes> {
-  return router as RSCRouterInternal<TEnv, TRoutes>;
+>(router: Rango<TEnv, TRoutes>): RangoInternal<TEnv, TRoutes> {
+  return router as RangoInternal<TEnv, TRoutes>;
 }

package/src/router/router-options.ts

@@ -73,7 +73,7 @@ export interface RootLayoutProps {
 /**
  * Router configuration options
  */
-export interface RSCRouterOptions<TEnv = any> {
+export interface RangoOptions<TEnv = any> {
   /**
    * Unique identifier for this router instance.
    * Used to namespace static output files and route maps.

package/src/router/router-registry.ts

@@ -1,4 +1,4 @@
-import type { RSCRouterInternal } from "./router-interfaces.js";
+import type { RangoInternal } from "./router-interfaces.js";
 
 /**
  * Brand marker for identifying router instances at build time.
@@ -12,10 +12,7 @@ export const RSC_ROUTER_BRAND = "__rsc_router__" as const;
  * Used by the Vite plugin at build time to discover routers and extract
  * manifests, prefix trees, and pre-render candidates.
  */
-export const RouterRegistry: Map<
-  string,
-  RSCRouterInternal<any, any>
-> = new Map();
+export const RouterRegistry: Map<string, RangoInternal<any, any>> = new Map();
 
 export let routerAutoId = 0;
 

package/src/router/segment-resolution/fresh.ts

@@ -32,7 +32,7 @@ import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
   track,
-  RSCRouterContext,
+  RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
@@ -632,7 +632,7 @@ export async function resolveAllSegments<TEnv>(
     // can guard non-cacheable variable reads. Also guards response-level
     // side effects (headers.set). Persists for all descendant entries.
     if (entry.type === "cache") {
-      const store = RSCRouterContext.getStore();
+      const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
     }
     const doneEntry = track(`segment:${entry.id}`, 1);

package/src/router/segment-resolution/revalidation.ts

@@ -43,7 +43,7 @@ import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
   track,
-  RSCRouterContext,
+  RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
@@ -1356,7 +1356,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
     if (entry.type === "cache") {
-      const store = RSCRouterContext.getStore();
+      const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
     }
     const doneEntry = track(`segment:${entry.id}`, 1);

package/src/router.ts

@@ -24,7 +24,7 @@ import { urls } from "./urls.js";
 import {
   type EntryData,
   getContext,
-  RSCRouterContext,
+  RangoContext,
   type MetricsStore,
 } from "./server/context";
 import { createHandleStore, type HandleStore } from "./server/handle-store.js";
@@ -90,13 +90,10 @@ import {
   RouterRegistry,
   nextRouterAutoId,
 } from "./router/router-registry.js";
+import type { RangoOptions, RootLayoutProps } from "./router/router-options.js";
 import type {
-  RSCRouterOptions,
-  RootLayoutProps,
-} from "./router/router-options.js";
-import type {
-  RSCRouter,
-  RSCRouterInternal,
+  Rango,
+  RangoInternal,
   RouterRequestInput,
 } from "./router/router-interfaces.js";
 
@@ -115,22 +112,22 @@ import {
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
 export type {
-  RSCRouterOptions,
+  RangoOptions,
   RootLayoutProps,
   SSRStreamMode,
   SSROptions,
   ResolveStreamingContext,
 } from "./router/router-options.js";
 export type {
-  RSCRouter,
-  RSCRouterInternal,
+  Rango,
+  RangoInternal,
   RouterRequestInput,
 } from "./router/router-interfaces.js";
 export { toInternal } from "./router/router-interfaces.js";
 
 export function createRouter<TEnv = any>(
-  options: RSCRouterOptions<TEnv> = {},
-): RSCRouter<TEnv, {}> {
+  options: RangoOptions<TEnv> = {},
+): Rango<TEnv, {}> {
   const {
     id: userProvidedId,
     $$id: injectedId,
@@ -673,7 +670,7 @@ export function createRouter<TEnv = any>(
    * The type system tracks accumulated routes through the builder chain
    * Initial TRoutes is {} (empty) to avoid poisoning accumulated types with Record<string, string>
    */
-  const router: RSCRouterInternal<TEnv, {}> = {
+  const router: RangoInternal<TEnv, {}> = {
     __brand: RSC_ROUTER_BRAND,
     id: routerId,
     basename,
@@ -721,7 +718,7 @@ export function createRouter<TEnv = any>(
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -1045,9 +1042,9 @@ export function createRouter<TEnv = any>(
 
   // If urls option was provided, auto-register them
   if (typeof urlsOption === "function") {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   } else if (urlsOption) {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   }
 
   return router;

package/src/rsc/handler-context.ts

@@ -6,14 +6,14 @@
  * RSC rendering) so they can be standalone modules without closure coupling.
  */
 
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ErrorPhase } from "../types.js";
 import type { InvokeOnErrorContext } from "../router/error-handling.js";
 import type { RSCDependencies, LoadSSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 
 export interface HandlerContext<TEnv = unknown> {
-  router: RSCRouterInternal<TEnv, any>;
+  router: RangoInternal<TEnv, any>;
   version: string;
   renderToReadableStream: RSCDependencies["renderToReadableStream"];
   decodeReply: RSCDependencies["decodeReply"];

package/src/rsc/index.ts

@@ -1,5 +1,5 @@
 /**
- * RSC Router - RSC Entry Point
+ * Rango - RSC Entry Point
  *
  * This module provides RSC utilities for server-side rendering,
  * server actions, loader fetching, and progressive enhancement.

package/src/rsc/types.ts

@@ -7,7 +7,7 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
@@ -185,7 +185,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouterInternal<TEnv, TRoutes>;
+  router: RangoInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.

package/src/search-params.ts

@@ -81,11 +81,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
 // ============================================================================
 
 /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
-type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
-  ? keyof RSCRouter.GeneratedRouteMap extends never
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
     ? Record<string, string>
-    : RSCRouter.GeneratedRouteMap
-  : RSCRouter.RegisteredRoutes;
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Extract the resolved search params type for a named route.

package/src/server/context.ts

@@ -40,7 +40,7 @@ export interface MetricsStore {
   metrics: PerformanceMetric[];
 }
 // ============================================================================
-//  RSC Router Context
+//  Rango Context
 // ============================================================================
 
 /**
@@ -303,7 +303,7 @@ interface HelperContext {
 // hold references to the old instance — causing getStore() to return
 // undefined even inside a run() callback.
 const RSC_CONTEXT_KEY = Symbol.for("rangojs-router:rsc-context");
-export const RSCRouterContext: AsyncLocalStorage<HelperContext> = ((
+export const RangoContext: AsyncLocalStorage<HelperContext> = ((
   globalThis as any
 )[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage<HelperContext>());
 
@@ -330,12 +330,12 @@ export const getContext = (): {
     callback: (...args: any[]) => T,
   ) => T;
 } => {
-  const context = RSCRouterContext;
+  const context = RangoContext;
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
-      let store = RSCRouterContext.getStore();
+      let store = RangoContext.getStore();
       if (!store) {
         store = {
           manifest: new Map<string, EntryData>(),
@@ -355,7 +355,7 @@ export const getContext = (): {
       const store = context.getStore();
       if (!store) {
         throw new Error(
-          "RSC Router context store is not available. Make sure to run within RSC Router context.",
+          "Rango context store is not available. Make sure to run within Rango context.",
         );
       }
       return store;
@@ -372,7 +372,7 @@ export const getContext = (): {
       type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
+      invariant(store, "No context RangoContext available");
       store.counters[type] ??= 0;
       const index = store.counters[type];
       store.counters[type] = index + 1;
@@ -382,7 +382,7 @@ export const getContext = (): {
       type: "layout" | "parallel" | "route" | "loader" | "cache",
     ) => {
       const store = context.getStore();
-      invariant(store, "No context RSCRouterContext available");
+      invariant(store, "No context RangoContext available");
 
       const parent = store.parent;
       const prefix =
@@ -502,7 +502,7 @@ export function runWithPrefixes<T>(
   namePrefix: string | undefined,
   callback: () => T,
 ): T {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   if (!store) {
     throw new Error("runWithPrefixes must be called within router context");
   }
@@ -547,7 +547,7 @@ export function runWithPrefixes<T>(
         ? (store.rootScoped ?? false)
         : store.rootScoped;
 
-  return RSCRouterContext.run(
+  return RangoContext.run(
     {
       ...store,
       urlPrefix: combinedUrlPrefix,
@@ -562,7 +562,7 @@ export function runWithPrefixes<T>(
  * Get current URL prefix from context
  */
 export function getUrlPrefix(): string {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.urlPrefix || "";
 }
 
@@ -570,7 +570,7 @@ export function getUrlPrefix(): string {
  * Get current name prefix from context
  */
 export function getNamePrefix(): string | undefined {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.namePrefix;
 }
 
@@ -579,7 +579,7 @@ export function getNamePrefix(): string | undefined {
  * Returns true at root or inside { name: "" } includes, false inside named includes.
  */
 export function getRootScoped(): boolean {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
   return store?.rootScoped ?? true;
 }
 
@@ -676,7 +676,7 @@ export function getParallelSlotCount(
  * ```
  */
 export function track(label: string, depth?: number): () => void {
-  const store = RSCRouterContext.getStore();
+  const store = RangoContext.getStore();
 
   // No-op if context unavailable or metrics not enabled
   if (!store?.metrics?.enabled) {
@@ -699,8 +699,8 @@ export function track(label: string, depth?: number): () => void {
 
 /**
  * Separate ALS for tracking loader execution scope.
- * Uses a dedicated ALS (not RSCRouterContext) to avoid issues with
- * nested RSCRouterContext.run() calls in Vite's module runner.
+ * Uses a dedicated ALS (not RangoContext) to avoid issues with
+ * nested RangoContext.run() calls in Vite's module runner.
  */
 const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
 const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
@@ -713,7 +713,7 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
  * (never cached), so non-cacheable reads are safe.
  */
 export function isInsideCacheScope(): boolean {
-  if (RSCRouterContext.getStore()?.insideCacheScope !== true) return false;
+  if (RangoContext.getStore()?.insideCacheScope !== true) return false;
   // Loaders are always fresh — even inside a cache() boundary, the loader
   // function re-executes on every request. Skip the guard when running
   // inside a loader.

package/src/static-handler.ts

@@ -96,7 +96,7 @@ export function Static<TParams extends Record<string, any>>(
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
+      "[rango] Static: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }

package/src/types/global-namespace.ts

@@ -7,7 +7,7 @@
  * ```typescript
  * // In env.ts or env.d.ts
  * declare global {
- *   namespace RSCRouter {
+ *   namespace Rango {
  *     interface Env extends AppBindings {}
  *     interface Vars extends AppVariables {}
  *   }
@@ -18,7 +18,7 @@
  * ```
  */
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
     interface Env {
       // Empty by default - users augment with their bindings (e.g., { DB: D1Database })
@@ -44,13 +44,25 @@ declare global {
 }
 
 /**
- * Get registered routes or fallback to generic Record<string, string>
- * When RSCRouter.RegisteredRoutes is augmented, provides autocomplete for route names
- * When not augmented, allows any string (no autocomplete)
+ * Route map for path-validation surfaces (`href`, `ValidPaths`, `PathResponse`).
+ *
+ * Resolution order:
+ * 1. `RegisteredRoutes` — manual `extends typeof router.routeMap`; richest map,
+ *    the only one carrying response-route payload metadata.
+ * 2. `GeneratedRouteMap` — auto-wired by `router.named-routes.gen.ts`; path +
+ *    search only. Lets `rango generate` alone enable `href()`/`ValidPaths` path
+ *    checking without a manual `RegisteredRoutes` declaration.
+ * 3. `Record<string, string>` — permissive fallback when nothing is registered.
+ *
+ * Referencing `GeneratedRouteMap` here is cycle-safe: it is declared in the
+ * standalone gen file with no imports, unlike `RegisteredRoutes extends typeof
+ * router.routeMap`.
  */
-export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
-  ? Record<string, string>
-  : RSCRouter.RegisteredRoutes;
+export type GetRegisteredRoutes = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
+    ? Record<string, string>
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Default route map for reverse() surfaces.
@@ -58,12 +70,11 @@ export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
  * cycles, but falls back to RegisteredRoutes for manual augmentation and then to
  * a permissive record when no route types are available.
  */
-export type DefaultReverseRouteMap =
-  keyof RSCRouter.GeneratedRouteMap extends never
-    ? keyof RSCRouter.RegisteredRoutes extends never
-      ? Record<string, string>
-      : RSCRouter.RegisteredRoutes
-    : RSCRouter.GeneratedRouteMap;
+export type DefaultReverseRouteMap = keyof Rango.GeneratedRouteMap extends never
+  ? keyof Rango.RegisteredRoutes extends never
+    ? Record<string, string>
+    : Rango.RegisteredRoutes
+  : Rango.GeneratedRouteMap;
 
 /**
  * Default route map for Handler type.
@@ -71,30 +82,32 @@ export type DefaultReverseRouteMap =
  * circular dependencies: router.tsx -> urls.tsx -> handler.tsx -> RegisteredRoutes -> router.tsx.
  * GeneratedRouteMap is declared in a standalone gen file with no imports.
  */
-export type DefaultHandlerRouteMap =
-  keyof RSCRouter.GeneratedRouteMap extends never
-    ? {}
-    : RSCRouter.GeneratedRouteMap;
+export type DefaultHandlerRouteMap = keyof Rango.GeneratedRouteMap extends never
+  ? {}
+  : Rango.GeneratedRouteMap;
 
 /**
- * Default environment type - uses global augmentation if available, any otherwise
+ * Default environment type - uses global augmentation if available.
+ *
+ * Falls back to `unknown` (not `any`) when `Rango.Env` is not augmented, so
+ * an app that forgets to register its bindings gets a compile error on
+ * `ctx.env.SOMETHING` instead of silently losing all env type-checking. Augment
+ * `Rango.Env` to type `ctx.env`.
  */
-export type DefaultEnv = keyof RSCRouter.Env extends never
-  ? any
-  : RSCRouter.Env;
+export type DefaultEnv = keyof Rango.Env extends never ? unknown : Rango.Env;
 
 /**
  * Default variables type - uses global augmentation if available, Record<string, any> otherwise
  */
-export type DefaultVars = keyof RSCRouter.Vars extends never
+export type DefaultVars = keyof Rango.Vars extends never
   ? Record<string, any>
-  : RSCRouter.Vars;
+  : Rango.Vars;
 
 /**
  * Default route name type for public `routeName` on contexts.
  * When GeneratedRouteMap is augmented, narrows to the known route names.
  * Otherwise falls back to `string` for untyped usage.
  */
-export type DefaultRouteName = keyof RSCRouter.GeneratedRouteMap extends never
+export type DefaultRouteName = keyof Rango.GeneratedRouteMap extends never
   ? string
-  : keyof RSCRouter.GeneratedRouteMap & string;
+  : keyof Rango.GeneratedRouteMap & string;

package/src/types/handler-context.ts

@@ -43,7 +43,7 @@ export type { MiddlewareFn } from "../router/middleware.js";
  */
 export type ScopedRouteMap<
   TPrefix extends string,
-  TMap = RSCRouter.GeneratedRouteMap,
+  TMap = Rango.GeneratedRouteMap,
 > = {
   [K in keyof TMap as K extends `${TPrefix}.${infer Rest}`
     ? Rest
@@ -767,7 +767,7 @@ export type Revalidate<
  * Middleware function with typed params and environment
  *
  * @template TParams - Params object (defaults to generic)
- * @template TEnv - Environment type (defaults to global RSCRouter.Env)
+ * @template TEnv - Environment type (defaults to global Rango.Env)
  *
  * Note: Middleware cannot directly use route names for params typing because
  * middleware is defined during router setup, before RegisteredRoutes is populated.
@@ -775,7 +775,7 @@ export type Revalidate<
  *
  * @example
  * ```typescript
- * // Basic middleware (uses global RSCRouter.Env via module augmentation)
+ * // Basic middleware (uses global Rango.Env via module augmentation)
  * const middleware: Middleware = async (ctx, next) => {
  *   ctx.set("user", { id: "123" }); // Type-safe!
  *   await next();