@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.3232cd17

package/src/router/router-interfaces.ts

@@ -2,17 +2,16 @@ 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, 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";
 import type { ExecutionContext } from "../server/request-context.js";
-import type {
-  SerializedSegmentData,
-  SegmentHandleData,
-} from "../cache/types.js";
+import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
+import type { ExtractParams } from "../types/route-config.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";
 
@@ -48,16 +47,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>,
 > {
@@ -68,23 +67,36 @@ export interface RSCRouter<
   readonly id: string;
 
   /**
-   * Register routes using URL patterns from urls()
+   * URL prefix applied to all routes. Undefined when no basename is configured.
+   */
+  readonly basename: string | undefined;
+
+  /**
+   * Register routes using URL patterns from urls() or a builder function
    *
    * @example
    * ```typescript
-   * createRouter({})
-   *   .routes(urlpatterns)
+   * // With urls()
+   * createRouter({}).routes(urlpatterns)
+   *
+   * // With builder function (urls() is implicit)
+   * createRouter({}).routes(({ path, layout }) => [
+   *   layout(RootLayout, () => [
+   *     path("/", HomePage),
+   *   ]),
+   * ])
    * ```
    */
-  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>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -94,13 +106,18 @@ export interface RSCRouter<
    * createRouter({ document: RootLayout })
    *   .use(loggerMiddleware)           // All routes
    *   .use("/api/*", rateLimiter)      // Pattern match
+   *   .use("/users/:id", (ctx) => {})  // ctx.params.id is typed
    *   .routes(urlpatterns)
    * ```
    */
+  use<Pattern extends string>(
+    pattern: Pattern,
+    middleware: MiddlewareFn<TEnv, ExtractParams<Pattern>>,
+  ): Rango<TEnv, TRoutes>;
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
+  ): Rango<TEnv, TRoutes>;
 
   /**
    * Type-safe URL builder for registered routes
@@ -127,7 +144,7 @@ export interface RSCRouter<
    * type AppRoutes = typeof _router.routeMap;
    *
    * declare global {
-   *   namespace RSCRouter {
+   *   namespace Rango {
    *     interface RegisteredRoutes extends AppRoutes {}
    *   }
    * }
@@ -163,16 +180,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>,
 > {
@@ -188,26 +205,40 @@ export interface RSCRouterInternal<
    */
   readonly id: string;
 
+  /** URL prefix applied to all routes. */
+  readonly basename: string | undefined;
+
   /**
-   * Register routes using URL patterns from urls()
-   */
-  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>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
    */
+  use<Pattern extends string>(
+    pattern: Pattern,
+    middleware: MiddlewareFn<TEnv, ExtractParams<Pattern>>,
+  ): Rango<TEnv, TRoutes>;
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
+  ): Rango<TEnv, TRoutes>;
 
   /**
    * Type-safe URL builder for registered routes
@@ -229,17 +260,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)
@@ -269,6 +300,13 @@ export interface RSCRouterInternal<
    */
   readonly prefetchCacheTTL: number;
 
+  /**
+   * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
+   * router init and shipped to the client in payload metadata. The server-side
+   * cookie writer reads it from here; the client reads it from metadata.
+   */
+  readonly resolvedStateCookieName: string;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods
@@ -338,6 +376,20 @@ export interface RSCRouterInternal<
    */
   readonly __sourceFile?: string;
 
+  /** @internal basename for runtime manifest generation */
+  readonly __basename?: string;
+
+  /**
+   * @internal Router-level error/notFound fallbacks (`createRouter` options),
+   * exposed for the build-time clientChunks discovery so a `"use client"`
+   * default boundary is routed into the dedicated `app-fallback` chunk. Unlike
+   * the route-tree `errorBoundary()`/`notFoundBoundary()` helpers these never
+   * land in `EntryData`, so they are read directly off the router instance.
+   */
+  readonly __defaultErrorBoundary?: RangoOptions<TEnv>["defaultErrorBoundary"];
+  readonly __defaultNotFoundBoundary?: RangoOptions<TEnv>["defaultNotFoundBoundary"];
+  readonly __notFound?: RangoOptions<TEnv>["notFound"];
+
   match(
     request: Request,
     input?: RouterRequestInput<TEnv>,
@@ -353,13 +405,17 @@ export interface RSCRouterInternal<
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: any,
+    devMode?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
-    handles: Record<string, SegmentHandleData>;
+    /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. */
+    handles: string;
     routeName: string;
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
-    interceptHandles?: Record<string, SegmentHandleData>;
+    /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact. */
+    interceptHandles?: string;
     passthrough?: true;
   } | null>;
 
@@ -371,7 +427,9 @@ export interface RSCRouterInternal<
     handler: Function,
     handlerId: string,
     routeName?: string,
-  ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null>;
+    buildEnv?: any,
+    devMode?: boolean,
+  ): Promise<{ encoded: string; handles: string } | null>;
 
   /**
    * Preview match - returns route middleware without segment resolution.
@@ -424,6 +482,13 @@ export interface RSCRouterInternal<
     segmentType?: ErrorInfo["segmentType"],
   ): Promise<MatchResult | null>;
 
+  /**
+   * Low-level route matching function.
+   * Used by classifyRequest() for request classification without
+   * entering the full match pipeline.
+   */
+  findMatch(pathname: string, metricsStore?: any): any;
+
   /**
    * Debug utility to serialize the manifest for inspection
    * Returns a JSON-friendly representation of all routes and layouts
@@ -437,16 +502,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

@@ -8,6 +8,7 @@ import type {
 import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -72,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.
@@ -95,6 +96,28 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   $$sourceFile?: string;
 
+  /**
+   * URL prefix applied to all routes registered with this router.
+   *
+   * Useful when the app is served under a sub-path (e.g. `/admin` or `/v2`).
+   * All `path()` patterns are automatically prefixed and `reverse()` returns
+   * full paths including the basename. Route names are NOT prefixed.
+   *
+   * @example
+   * ```typescript
+   * const router = createRouter({
+   *   basename: "/admin",
+   * }).routes(({ path }) => [
+   *   path("/", Dashboard, { name: "home" }),       // matches /admin
+   *   path("/users", Users, { name: "users" }),     // matches /admin/users
+   * ]);
+   *
+   * router.reverse("home");   // "/admin"
+   * router.reverse("users");  // "/admin/users"
+   * ```
+   */
+  basename?: string;
+
   /**
    * Enable performance metrics collection
    * When enabled, metrics are output to console and available via Server-Timing header
@@ -109,6 +132,21 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   allowDebugManifest?: boolean;
 
+  /**
+   * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
+   * the cache status of the matched route, for use by testing primitives such
+   * as `assertCacheStatus`.
+   *
+   * Defaults to `false`. When neither this option nor the
+   * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
+   * router output is byte-identical to the default.
+   *
+   * The header encodes per-segment (v1: coarse route-level) status keyed by the
+   * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
+   * production — it exposes internal cache decisions.
+   */
+  debugCacheSignal?: boolean;
+
   /**
    * Document component that wraps the entire application.
    *
@@ -335,27 +373,54 @@ export interface RSCRouterOptions<TEnv = any> {
   theme?: import("../theme/types.js").ThemeConfig | true;
 
   /**
-   * URL patterns to register with the router.
+   * Default for whether the router wraps `transition()` segments in its own
+   * React `<ViewTransition>` boundary (experimental React only).
+   *
+   * - "auto" (default): every route/layout that opts in via `transition()`
+   *   gets a router-owned cross-fade.
+   * - false: the router never places its own boundary. Routes that use
+   *   `transition()` still drive navigation through startTransition (so loaders
+   *   hold instead of flashing a skeleton) and still let consumer-placed
+   *   `<ViewTransition>` elements animate — the router just contributes no
+   *   cross-fade of its own. This is the "router triggers, you place the
+   *   transitions" model.
    *
-   * Alternative to calling `.routes()` method - allows passing patterns
-   * directly in the config for a more concise setup.
+   * A per-segment `transition({ viewTransition })` overrides this default.
    *
    * @example
    * ```typescript
-   * import { urls } from "@rangojs/router/server";
+   * // App-wide: drive + hold, but never auto-wrap. Place <ViewTransition>
+   * // yourself in components where you want a morph.
+   * const router = createRouter<AppEnv>({ viewTransition: false });
+   * ```
+   */
+  viewTransition?: "auto" | false;
+
+  /**
+   * URL patterns to register with the router.
    *
-   * const urlpatterns = urls(({ path, layout }) => [
-   *   path("/", HomePage, { name: "home" }),
-   *   path("/about", AboutPage, { name: "about" }),
-   * ]);
+   * Accepts either a `UrlPatterns` object from `urls()` or a builder function
+   * directly (urls() is called implicitly).
    *
-   * const router = createRouter<AppEnv>({
+   * @example
+   * ```typescript
+   * // With urls()
+   * createRouter<AppEnv>({
    *   document: Document,
    *   urls: urlpatterns,
    * });
+   *
+   * // With builder function
+   * createRouter<AppEnv>({
+   *   document: Document,
+   *   urls: ({ path }) => [
+   *     path("/", HomePage, { name: "home" }),
+   *     path("/about", AboutPage, { name: "about" }),
+   *   ],
+   * });
    * ```
    */
-  urls?: UrlPatterns<TEnv, any>;
+  urls?: UrlPatterns<TEnv, any> | UrlBuilder<TEnv>;
 
   /**
    * Injected by the Vite transform at compile time.
@@ -431,6 +496,21 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   prefetchCacheTTL?: number | false;
 
+  /**
+   * Prefix for the rango state cookie name. The resolved name is
+   * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe
+   * characters (`[A-Za-z0-9-]`) and an empty result falls back to the default.
+   *
+   * The rango state cookie keys the client's prefetch / HTTP caches. Overriding
+   * the prefix lets you align it with cookie-naming policies or consent-manager
+   * classification lists, or avoid colliding with an existing `rango-state`
+   * cookie. It is not a full-name override: the `_{routerId}` suffix is what
+   * keeps sibling apps on one origin from clobbering each other's state.
+   *
+   * @default "rango-state"
+   */
+  stateCookiePrefix?: string;
+
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.
    *

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;