@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.ac99d918

package/src/router.ts

@@ -1,9 +1,6 @@
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
-import {
-  setCacheProfiles,
-  resolveCacheProfiles,
-} from "./cache/profile-registry.js";
+import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
@@ -19,11 +16,13 @@ import {
 import MapRootLayout from "./server/root-layout.js";
 import type { AllUseItems } from "./route-types.js";
 import type { UrlPatterns } from "./urls.js";
+import type { UrlBuilder } from "./urls/pattern-types.js";
+import { urls } from "./urls.js";
+import { buildPrecomputedByPrefix } from "./build/prefix-tree-utils.js";
 import {
-  EntryData,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
-  RSCRouterContext,
+  RangoContext,
   type MetricsStore,
 } from "./server/context";
 import { createHandleStore, type HandleStore } from "./server/handle-store.js";
@@ -55,6 +54,7 @@ import { buildDebugManifest } from "./router/debug-manifest.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
 import { createHandlerContext } from "./router/handler-context.js";
+import { normalizeBasename } from "./router/basename.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
@@ -69,6 +69,7 @@ import {
 } from "./router/middleware.js";
 import {
   extractStaticPrefix,
+  joinPrefix,
   traverseBack,
 } from "./router/pattern-matching.js";
 import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
@@ -89,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";
 
@@ -110,29 +108,31 @@ import {
   matchForPrerender as _matchForPrerender,
   renderStaticSegment as _renderStaticSegment,
 } from "./router/prerender-match.js";
+import { resolveStateCookieName } from "./router/state-cookie-name.js";
 
 // 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,
+    basename: basenameOption,
     debugPerformance = false,
     document: documentOption,
     defaultErrorBoundary,
@@ -148,6 +148,7 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -156,16 +157,31 @@ export function createRouter<TEnv = any>(
     timeouts: timeoutsOption,
     onTimeout,
     originCheck: originCheckOption,
+    viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
   } = options;
 
+  // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
+  // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
+  // no X-Rango-Cache header is emitted and output is byte-identical.
+  const cacheSignalEnabled =
+    debugCacheSignalOption ||
+    (typeof process !== "undefined" &&
+      (process as { env?: Record<string, string | undefined> }).env
+        ?.RANGO_TEST_SIGNALS === "1");
+
+  // Normalize basename: ensure leading slash, strip trailing slash.
+  // A bare "/" is equivalent to no basename. Shared with the testing
+  // primitives via normalizeBasename so they can never drift.
+  const basename = normalizeBasename(basenameOption);
+
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
 
-  // Resolve cache profiles: merge user config with guaranteed default profile.
-  // This resolved map is both stored on the router (for per-request context)
-  // and written to the global registry (for DSL-time cache("profileName")).
+  // Resolve cache profiles: merge user config with the guaranteed default
+  // profile. This resolved map is threaded onto each request context; the
+  // "use cache: <profile>" runtime path reads it request-scoped.
   const resolvedCacheProfiles = resolveCacheProfiles(cacheProfilesOption);
-  setCacheProfiles(resolvedCacheProfiles);
 
   // Source file: prefer Vite-injected path (zero cost), fall back to
   // stack trace parsing for non-Vite environments (e.g. tests).
@@ -200,6 +216,14 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
+  // Resolve the rango state cookie name once, here, so the two cookie writers
+  // (the client document.cookie writer and the server Set-Cookie writer)
+  // consume one pre-composed name and cannot drift.
+  const resolvedStateCookieName = resolveStateCookieName(
+    stateCookiePrefixOption,
+    routerId,
+  );
+
   // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
   // Clamp to a non-negative integer for valid Cache-Control max-age.
   const rawTTL =
@@ -246,9 +270,14 @@ export function createRouter<TEnv = any>(
     invokeOnError(onError, error, phase, context, "Router");
   }
 
-  // Validate document is a client component
+  // Validate document is a client component. Under a test runner the "use
+  // client" transform has not run, so a real exported document has no marker;
+  // allowServerInTest lets the router construct in a bare unit test (for
+  // dispatch / assertGeneratedRoutesMatch) while a real build still throws.
   if (documentOption !== undefined) {
-    assertClientComponent(documentOption, "document");
+    assertClientComponent(documentOption, "document", {
+      allowServerInTest: true,
+    });
   }
 
   // Use default document if none provided (keeps internal name as rootLayout)
@@ -322,7 +351,6 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 
@@ -356,9 +384,11 @@ export function createRouter<TEnv = any>(
       getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
     if (current !== precomputedSource) {
       precomputedSource = current;
-      precomputedByPrefix = current
-        ? new Map(current.map((e) => [e.staticPrefix, e.routes]))
-        : null;
+      // buildPrecomputedByPrefix drops any staticPrefix owned by more than one
+      // leaf include instead of collapsing it last-wins (which would mis-assign
+      // one include's routes to another's entry and 500 a valid sibling route).
+      // Such shared-prefix includes resolve via the handler path instead.
+      precomputedByPrefix = current ? buildPrecomputedByPrefix(current) : null;
     }
     return precomputedByPrefix;
   }
@@ -528,6 +558,7 @@ export function createRouter<TEnv = any>(
     findNearestNotFoundBoundary,
     notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies
@@ -615,6 +646,8 @@ export function createRouter<TEnv = any>(
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _matchForPrerender(
       pathname,
@@ -622,6 +655,8 @@ export function createRouter<TEnv = any>(
       prerenderDeps,
       buildVars,
       isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -629,12 +664,16 @@ export function createRouter<TEnv = any>(
     handler: Function,
     handlerId: string,
     routeName?: string,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _renderStaticSegment<TEnv>(
       handler,
       handlerId,
       mergedRouteMap,
       routeName,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -647,6 +686,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -656,11 +696,18 @@ 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,
+
+    routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
+      // Wrap builder functions in urls() automatically
+      const urlPatterns: UrlPatterns<TEnv> =
+        typeof patternsOrBuilder === "function"
+          ? (urls(patternsOrBuilder) as UrlPatterns<TEnv>)
+          : patternsOrBuilder;
 
-    routes(urlPatterns: UrlPatterns<TEnv>): any {
       // Store reference for runtime manifest generation
       storedUrlPatterns = urlPatterns;
       const currentMountIndex = mountIndex++;
@@ -697,7 +744,7 @@ export function createRouter<TEnv = any>(
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -708,6 +755,10 @@ export function createRouter<TEnv = any>(
           counters: {},
           mountIndex: currentMountIndex,
           cacheProfiles: resolvedCacheProfiles,
+          // basename sets the initial URL prefix so all path() patterns
+          // are registered with the prefix (e.g. "/admin" + "/users" = "/admin/users").
+          // No namePrefix — route names stay unprefixed.
+          ...(basename ? { urlPrefix: basename } : {}),
         },
         () => {
           handlerResult = urlPatterns.handler() as AllUseItems[];
@@ -727,7 +778,7 @@ export function createRouter<TEnv = any>(
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
           prerenderRouteKeys.add(name);
-          if (entry.prerenderDef?.options?.passthrough === true) {
+          if (entry.isPassthrough === true) {
             if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
             passthroughRouteKeys.add(name);
           }
@@ -805,10 +856,13 @@ export function createRouter<TEnv = any>(
 
       // Create placeholder RouteEntry for each lazy include
       for (const lazyInclude of lazyIncludes) {
-        // Compute the full URL prefix (combining parent prefix if any)
-        const fullPrefix = lazyInclude.context.urlPrefix
-          ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-          : lazyInclude.prefix;
+        // Compute the full URL prefix (combining parent prefix if any). Use the
+        // slash-collapsing join so a trailing-slash parent prefix does not
+        // produce a double-slash staticPrefix the trie's sp can never match.
+        const fullPrefix = joinPrefix(
+          lazyInclude.context.urlPrefix,
+          lazyInclude.prefix,
+        );
 
         const lazyEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
           prefix: "",
@@ -856,8 +910,18 @@ export function createRouter<TEnv = any>(
       patternOrMiddleware: string | MiddlewareFn<TEnv>,
       middleware?: MiddlewareFn<TEnv>,
     ): any {
-      // Global middleware - no mount prefix
-      addMiddleware(patternOrMiddleware, middleware, null);
+      // Auto-prefix pattern with basename so router-level middleware
+      // patterns are router-relative (e.g. "/users/*" matches "/app/users/*").
+      if (basename && typeof patternOrMiddleware === "string") {
+        const pattern = patternOrMiddleware;
+        const prefixed =
+          pattern === "/*" || pattern === "*"
+            ? `${basename}/*`
+            : `${basename}${pattern}`;
+        addMiddleware(prefixed, middleware, null);
+      } else {
+        addMiddleware(patternOrMiddleware, middleware, null);
+      }
       return router;
     },
 
@@ -894,6 +958,10 @@ export function createRouter<TEnv = any>(
     prefetchCacheControl,
     prefetchCacheTTL,
 
+    // Expose the resolved rango state cookie name for the server-side writer
+    // (invalidateClientCache) and for shipping to the client in metadata.
+    resolvedStateCookieName,
+
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
@@ -958,6 +1026,16 @@ export function createRouter<TEnv = any>(
     // Expose source file for per-router type generation
     __sourceFile,
 
+    // Expose basename for runtime manifest generation
+    __basename: basename,
+
+    // Expose router-level boundary defaults for build-time clientChunks
+    // discovery (so a "use client" default boundary lands in app-fallback).
+    // These are createRouter options, never pushed onto EntryData.
+    __defaultErrorBoundary: defaultErrorBoundary,
+    __defaultNotFoundBoundary: defaultNotFoundBoundary,
+    __notFound: notFound,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused
@@ -975,8 +1053,10 @@ export function createRouter<TEnv = any>(
         if (!handler) {
           // Lazy import deferred to first request to avoid dev mode issues
           const { createRSCHandler } = await import("./rsc/handler.js");
-          // Cast: handler.ts still accepts (request, env) — will be updated
-          // separately to accept RouterRequestInput.
+          // Cast: createRSCHandler receives `router as any`, which erases TEnv
+          // and infers its handler as RouterRequestInput<unknown>. Re-narrow the
+          // returned handler to RouterRequestInput<TEnv> so the call below stays
+          // typed. (The handler already accepts (request, RouterRequestInput).)
           handler = createRSCHandler({
             router: router as any,
             cache,
@@ -991,6 +1071,10 @@ export function createRouter<TEnv = any>(
       };
     })(),
 
+    // Low-level route matching for request classification
+    findMatch: (pathname: string, metricsStore?: any) =>
+      findMatch(pathname, metricsStore),
+
     // Debug utility for manifest inspection
     debugManifest: () => buildDebugManifest<TEnv>(routesEntries),
   };
@@ -999,8 +1083,10 @@ export function createRouter<TEnv = any>(
   RouterRegistry.set(routerId, router);
 
   // If urls option was provided, auto-register them
-  if (urlsOption) {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+  if (typeof urlsOption === "function") {
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
+  } else if (urlsOption) {
+    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"];
@@ -31,6 +31,7 @@ export interface HandlerContext<TEnv = unknown> {
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response;
 
   /**