@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1c0bdfad

package/src/router/url-params.ts

@@ -0,0 +1,44 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}

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,
@@ -63,15 +63,17 @@ import {
 import { loadManifest } from "./router/manifest.js";
 import { createMetricsStore } from "./router/metrics.js";
 import {
-  parsePattern,
+  compileMiddlewarePattern,
   type MiddlewareEntry,
   type MiddlewareFn,
 } from "./router/middleware.js";
 import {
   extractStaticPrefix,
+  joinPrefix,
   traverseBack,
 } from "./router/pattern-matching.js";
 import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
+import { resolveTracing } from "./router/tracing.js";
 import { evaluateRevalidation } from "./router/revalidation.js";
 import {
   type RouterContext,
@@ -89,13 +91,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 +109,32 @@ import {
   matchForPrerender as _matchForPrerender,
   renderStaticSegment as _renderStaticSegment,
 } from "./router/prerender-match.js";
+import { resolveStateCookieName } from "./router/state-cookie-name.js";
+import { resolvePrefetchCacheTTL } from "./router/prefetch-cache-ttl.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,
@@ -147,25 +149,47 @@ export function createRouter<TEnv = any>(
     $$sourceFile: injectedSourceFile,
     nonce,
     version,
-    prefetchCacheControl: prefetchCacheControlOption,
+    prefetchCacheTTL: prefetchCacheTTLOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
+    tracing: tracingOption,
     ssr: ssrOption,
     timeout: timeoutShorthand,
     timeouts: timeoutsOption,
     onTimeout,
     originCheck: originCheckOption,
+    viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
+    strictMode: strictModeOption = true,
   } = 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 span tracing (undefined when not configured; every traceSpan() call
+  // is then a direct pass-through with zero behavior change).
+  const resolvedTracing = resolveTracing(tracingOption);
+
+  // 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,15 +224,32 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
-  // Resolve prefetch cache control (default: 'private, max-age=300')
-  const prefetchCacheControl =
-    prefetchCacheControlOption !== undefined
-      ? prefetchCacheControlOption
-      : "private, max-age=300";
+  // 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). Clamps to a
+  // non-negative integer and guards non-finite (NaN/Infinity) inputs so a
+  // malformed `Cache-Control: max-age=NaN` can never reach the wire.
+  const resolvedPrefetchCacheTTL = resolvePrefetchCacheTTL(
+    prefetchCacheTTLOption,
+  );
+  const prefetchCacheTTL = resolvedPrefetchCacheTTL.ms;
+  const prefetchCacheControl: string | false =
+    resolvedPrefetchCacheTTL.cacheControl;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
 
+  // Resolve StrictMode flag (default: true). Shipped to the client in payload
+  // metadata; the browser entry reads it once to decide whether to wrap the
+  // hydrated tree in React.StrictMode.
+  const strictMode = strictModeOption !== false;
+
   // Resolve theme config (null if theme not enabled)
   const resolvedThemeConfig = themeOption
     ? resolveThemeConfig(themeOption)
@@ -240,9 +281,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)
@@ -306,7 +352,7 @@ export function createRouter<TEnv = any>(
     let regex: RegExp | null = null;
     let paramNames: string[] = [];
     if (fullPattern) {
-      const parsed = parsePattern(fullPattern);
+      const parsed = compileMiddlewarePattern(fullPattern);
       regex = parsed.regex;
       paramNames = parsed.paramNames;
     }
@@ -316,7 +362,6 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 
@@ -350,15 +395,27 @@ 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;
   }
 
-  // Wrapper to pass debugPerformance to external createMetricsStore
-  const getMetricsStore = () => createMetricsStore(debugPerformance);
+  // Wrapper to pass debugPerformance to external createMetricsStore.
+  // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  const getMetricsStore = () => {
+    const reqCtx = _getRequestContext();
+    const enabled = debugPerformance || !!reqCtx?._debugPerformance;
+    if (!enabled) return undefined;
+    if (!reqCtx) {
+      return createMetricsStore(true);
+    }
+    reqCtx._metricsStore ??= createMetricsStore(true);
+    return reqCtx._metricsStore;
+  };
 
   // Wrapper to pass defaults to error/notFound boundary finders
   const findNearestErrorBoundary = (entry: EntryData | null) =>
@@ -510,7 +567,9 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies
@@ -544,6 +603,7 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
   function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -597,6 +657,8 @@ export function createRouter<TEnv = any>(
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _matchForPrerender(
       pathname,
@@ -604,6 +666,8 @@ export function createRouter<TEnv = any>(
       prerenderDeps,
       buildVars,
       isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -611,12 +675,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,
     );
   }
 
@@ -629,6 +697,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -638,11 +707,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++;
@@ -673,13 +749,13 @@ export function createRouter<TEnv = any>(
         errorBoundary: [],
         notFoundBoundary: [],
         layout: [],
-        parallel: [],
+        parallel: {},
         intercept: [],
         loader: [],
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -690,6 +766,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[];
@@ -709,7 +789,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);
           }
@@ -735,6 +815,7 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -754,6 +835,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -785,10 +867,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: "",
@@ -797,6 +882,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,
@@ -835,8 +921,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;
     },
 
@@ -869,12 +965,26 @@ export function createRouter<TEnv = any>(
     // Expose resolved cache profiles for per-request resolution
     cacheProfiles: resolvedCacheProfiles,
 
-    // Expose prefetch cache control for RSC handler
+    // Expose prefetch cache settings
     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,
 
+    // Expose StrictMode flag for the initial-render payload metadata
+    strictMode,
+
+    // Expose router-wide performance debugging for request-level metrics setup
+    debugPerformance,
+
+    // Expose resolved span tracing for the handler (Cloudflare custom spans)
+    tracing: resolvedTracing,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 
@@ -933,6 +1043,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
@@ -950,8 +1070,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,
@@ -966,6 +1088,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),
   };
@@ -974,8 +1100,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;
 
   /**