@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/router/timeout.ts

@@ -0,0 +1,148 @@
+/**
+ * Router Timeout
+ *
+ * Types, resolution logic, and helpers for request-level timeouts.
+ * Timeouts wrap action execution and render-start phases with
+ * a Promise.race mechanism, returning 504 on expiry.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RouterTimeouts {
+  /** Timeout for server action execution (ms). */
+  actionMs?: number;
+  /** Timeout for initial render/response production (ms). */
+  renderStartMs?: number;
+  /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+  streamIdleMs?: number;
+}
+
+export type TimeoutPhase = "action" | "render-start" | "stream-idle";
+
+export interface TimeoutContext<TEnv = any> {
+  phase: TimeoutPhase;
+  request: Request;
+  url: URL;
+  env: TEnv;
+  routeKey?: string;
+  actionId?: string;
+  durationMs: number;
+}
+
+export type OnTimeoutCallback<TEnv = any> = (
+  ctx: TimeoutContext<TEnv>,
+) => Response | Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// Internal resolved form
+// ---------------------------------------------------------------------------
+
+export interface ResolvedTimeouts {
+  actionMs: number | undefined;
+  renderStartMs: number | undefined;
+  streamIdleMs: number | undefined;
+}
+
+/**
+ * Merge the `timeout` shorthand with the structured `timeouts` object.
+ *
+ * - `timeout` applies to `actionMs` and `renderStartMs` (NOT `streamIdleMs`).
+ * - Explicit `timeouts.*` values override the shorthand.
+ * - Returns `undefined` for any phase that has no configured value.
+ */
+export function resolveTimeouts(
+  timeout?: number,
+  timeouts?: RouterTimeouts,
+): ResolvedTimeouts {
+  return {
+    actionMs: timeouts?.actionMs ?? timeout ?? undefined,
+    renderStartMs: timeouts?.renderStartMs ?? timeout ?? undefined,
+    streamIdleMs: timeouts?.streamIdleMs ?? undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+export class RouterTimeoutError extends Error {
+  override name = "RouterTimeoutError" as const;
+  phase: TimeoutPhase;
+  durationMs: number;
+
+  constructor(phase: TimeoutPhase, durationMs: number) {
+    super(
+      `Request timed out during ${phase} after ${Math.round(durationMs)}ms`,
+    );
+    this.phase = phase;
+    this.durationMs = durationMs;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Race helper
+// ---------------------------------------------------------------------------
+
+type TimeoutResult<T> =
+  | { result: T; timedOut: false }
+  | { timedOut: true; durationMs: number };
+
+/**
+ * Race an operation against a deadline.
+ *
+ * Returns a discriminated union so callers handle the timeout case
+ * without try/catch. Non-timeout errors from the operation re-throw.
+ *
+ * When `timeoutMs` is `undefined` or `<= 0`, the operation runs
+ * without any deadline (pass-through).
+ */
+export async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number | undefined,
+  phase: TimeoutPhase,
+): Promise<TimeoutResult<T>> {
+  if (timeoutMs == null || timeoutMs <= 0) {
+    return { result: await operation, timedOut: false };
+  }
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout>;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new RouterTimeoutError(phase, performance.now() - start));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([operation, timeoutPromise]);
+    clearTimeout(timer!);
+    return { result, timedOut: false };
+  } catch (error) {
+    clearTimeout(timer!);
+    if (error instanceof RouterTimeoutError) {
+      return { timedOut: true, durationMs: error.durationMs };
+    }
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default response
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the default 504 response for a timed-out request.
+ * Includes `X-Rango-Timeout-Phase` header for observability.
+ */
+export function createDefaultTimeoutResponse(phase: TimeoutPhase): Response {
+  return new Response("Request timed out", {
+    status: 504,
+    headers: {
+      "Content-Type": "text/plain;charset=utf-8",
+      "X-Rango-Timeout-Phase": phase,
+    },
+  });
+}

package/src/router/trie-matching.ts

@@ -114,7 +114,25 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 2: Param match
+  // Priority 2: Suffix-param match (e.g., :productId.html)
+  if (node.xp) {
+    for (const suffix in node.xp) {
+      if (segment.endsWith(suffix) && segment.length > suffix.length) {
+        const paramValue = segment.slice(0, -suffix.length);
+        paramValues.push(paramValue);
+        const result = walkTrie(
+          node.xp[suffix].c,
+          segments,
+          index + 1,
+          paramValues,
+        );
+        paramValues.pop();
+        if (result) return result;
+      }
+    }
+  }
+
+  // Priority 3: Param match
   if (node.p) {
     paramValues.push(segment);
     const result = walkTrie(node.p.c, segments, index + 1, paramValues);
@@ -122,7 +140,7 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 3: Wildcard match (consumes rest)
+  // Priority 4: Wildcard match (consumes rest)
   if (node.w) {
     const rest = joinRemainingSegments(segments, index);
     return {

package/src/router/types.ts

@@ -83,13 +83,20 @@ export interface SegmentResolutionDeps<TEnv = any> {
       requestStartTime?: number;
     },
   ) => Promise<LoaderDataResult<T>>;
-  trackHandler: <T>(promise: Promise<T>) => Promise<T>;
+  trackHandler: <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ) => Promise<T>;
   findNearestErrorBoundary: (
     entry: EntryData | null,
   ) => ReactNode | ErrorBoundaryHandler | null;
   findNearestNotFoundBoundary: (
     entry: EntryData | null,
   ) => ReactNode | NotFoundBoundaryHandler | null;
+  notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
 }
 

package/src/router.ts

@@ -1,6 +1,9 @@
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
-import { setCacheProfiles } from "./cache/profile-registry.js";
+import {
+  setCacheProfiles,
+  resolveCacheProfiles,
+} from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
@@ -16,6 +19,8 @@ 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 {
   EntryData,
   InterceptSelectorContext,
@@ -68,12 +73,14 @@ import {
   extractStaticPrefix,
   traverseBack,
 } from "./router/pattern-matching.js";
+import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
 import { evaluateRevalidation } from "./router/revalidation.js";
 import {
   type RouterContext,
   runWithRouterContext,
 } from "./router/router-context.js";
 import { resolveThemeConfig } from "./theme/constants.js";
+import { resolveTimeouts } from "./router/timeout.js";
 
 // Extracted content negotiation utilities
 import { flattenNamedRoutes } from "./router/content-negotiation.js";
@@ -111,6 +118,9 @@ export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
 export type {
   RSCRouterOptions,
   RootLayoutProps,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
 } from "./router/router-options.js";
 export type {
   RSCRouter,
@@ -125,6 +135,7 @@ export function createRouter<TEnv = any>(
   const {
     id: userProvidedId,
     $$id: injectedId,
+    basename: basenameOption,
     debugPerformance = false,
     document: documentOption,
     defaultErrorBoundary,
@@ -139,15 +150,32 @@ export function createRouter<TEnv = any>(
     $$sourceFile: injectedSourceFile,
     nonce,
     version,
-    prefetchCacheControl: prefetchCacheControlOption,
+    prefetchCacheTTL: prefetchCacheTTLOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
+    telemetry: telemetrySink,
+    ssr: ssrOption,
+    timeout: timeoutShorthand,
+    timeouts: timeoutsOption,
+    onTimeout,
+    originCheck: originCheckOption,
   } = options;
 
-  // Set cache profiles for "use cache" directive
-  if (cacheProfilesOption) {
-    setCacheProfiles(cacheProfilesOption);
-  }
+  // Normalize basename: ensure leading slash, strip trailing slash.
+  // A bare "/" is equivalent to no basename.
+  const basename =
+    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
+      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
+      : undefined;
+
+  // 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")).
+  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).
@@ -182,11 +210,17 @@ 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 prefetch cache TTL (default: 300 seconds / 5 minutes)
+  // Clamp to a non-negative integer for valid Cache-Control max-age.
+  const rawTTL =
+    prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
+  const prefetchCacheTTLSeconds =
+    rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
+  const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
+  const prefetchCacheControl: string | false =
+    prefetchCacheTTLSeconds === 0
+      ? false
+      : `private, max-age=${prefetchCacheTTLSeconds}`;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
@@ -196,15 +230,29 @@ export function createRouter<TEnv = any>(
     ? resolveThemeConfig(themeOption)
     : null;
 
+  // Resolve timeout config (merge shorthand + structured)
+  const resolvedTimeouts = resolveTimeouts(timeoutShorthand, timeoutsOption);
+
   /**
    * Wrapper for invokeOnError that binds the router's onError callback.
    * Uses the shared utility from router/error-handling.ts for consistent behavior.
+   *
+   * Deduplicates via per-request WeakSet stored on the ALS request context.
+   * A closure-level WeakSet would silently swallow errors if the same object
+   * instance is thrown across separate requests (e.g. a singleton error).
    */
   function callOnError(
     error: unknown,
     phase: ErrorPhase,
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
+    if (error != null && typeof error === "object") {
+      const reportedErrors = _getRequestContext()?._reportedErrors;
+      if (reportedErrors) {
+        if (reportedErrors.has(error)) return;
+        reportedErrors.add(error);
+      }
+    }
     invokeOnError(onError, error, phase, context, "Router");
   }
 
@@ -325,8 +373,18 @@ export function createRouter<TEnv = any>(
     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) =>
@@ -340,14 +398,43 @@ export function createRouter<TEnv = any>(
     return _getRequestContext()?._handleStore;
   };
 
-  // Track a pending handler promise (non-blocking)
-  const trackHandler = <T>(promise: Promise<T>): Promise<T> => {
+  // Track a pending handler promise (non-blocking).
+  // Attaches a side-effect .catch() to report streaming handler errors to onError
+  // without altering the rejection chain (React's streaming error boundary still handles it).
+  const trackHandler = <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ): Promise<T> => {
     const store = getHandleStore();
-    return store ? store.track(promise) : promise;
+    const tracked = store ? store.track(promise) : promise;
+
+    // Report streaming handler errors to onError as a side-effect.
+    // The rejection still propagates to the RSC stream for client error boundaries.
+    // Captures request context eagerly (closure) so the catch handler has full context.
+    const reqCtx = _getRequestContext();
+    if (reqCtx && onError) {
+      tracked.catch((error) => {
+        callOnError(error, "handler", {
+          request: reqCtx.request,
+          url: reqCtx.url,
+          routeKey: reqCtx._routeName,
+          params: reqCtx.params as Record<string, string>,
+          env: reqCtx.env as TEnv,
+          segmentId: errorContext?.segmentId,
+          segmentType: errorContext?.segmentType as any,
+          handledByBoundary: true,
+        });
+      });
+    }
+
+    return tracked;
   };
 
   // Wrapper for wrapLoaderWithErrorHandling that uses router's error boundary finder
-  // Includes onError callback for loader error notification
+  // Includes onError callback for loader error notification and telemetry emission.
   function wrapLoaderPromise<T>(
     promise: Promise<T>,
     entry: EntryData,
@@ -363,7 +450,25 @@ export function createRouter<TEnv = any>(
       requestStartTime?: number;
     },
   ): Promise<LoaderDataResult<T>> {
-    return wrapLoaderWithErrorHandling(
+    const loaderStart = telemetrySink ? performance.now() : 0;
+    const loaderRequestId = telemetrySink
+      ? errorContext?.request
+        ? getRequestId(errorContext.request)
+        : undefined
+      : undefined;
+    if (telemetrySink) {
+      const loaderName = segmentId.split(".").pop() || "unknown";
+      safeEmit(telemetry, {
+        type: "loader.start",
+        timestamp: loaderStart,
+        requestId: loaderRequestId,
+        segmentId,
+        loaderName,
+        pathname,
+      });
+    }
+
+    const result = wrapLoaderWithErrorHandling(
       promise,
       entry,
       segmentId,
@@ -386,9 +491,42 @@ export function createRouter<TEnv = any>(
               handledByBoundary: ctx.handledByBoundary,
               requestStartTime: errorContext.requestStartTime,
             });
+            if (telemetrySink) {
+              const errorObj =
+                error instanceof Error ? error : new Error(String(error));
+              safeEmit(telemetry, {
+                type: "loader.error",
+                timestamp: performance.now(),
+                requestId: loaderRequestId,
+                segmentId: ctx.segmentId,
+                loaderName: ctx.loaderName,
+                pathname,
+                error: errorObj,
+                handledByBoundary: ctx.handledByBoundary,
+              });
+            }
           }
         : undefined,
     );
+
+    // Emit loader.end after the promise settles (fire-and-forget)
+    if (telemetrySink) {
+      const loaderName = segmentId.split(".").pop() || "unknown";
+      result.then((r) => {
+        safeEmit(telemetry, {
+          type: "loader.end",
+          timestamp: performance.now(),
+          requestId: loaderRequestId,
+          segmentId,
+          loaderName,
+          pathname,
+          durationMs: performance.now() - loaderStart,
+          ok: r.ok,
+        });
+      });
+    }
+
+    return result;
   }
 
   // Dependencies object for extracted segment resolution functions.
@@ -398,6 +536,7 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
   };
 
@@ -432,6 +571,7 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
   function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -468,6 +608,7 @@ export function createRouter<TEnv = any>(
       resolveLoadersOnlyWithRevalidation,
       resolveInterceptLoadersOnly,
       resolveLoadersOnly,
+      telemetry: telemetrySink,
     };
   }
 
@@ -483,8 +624,15 @@ export function createRouter<TEnv = any>(
     pathname: string,
     params: Record<string, string>,
     buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
   ) {
-    return _matchForPrerender(pathname, params, prerenderDeps, buildVars);
+    return _matchForPrerender(
+      pathname,
+      params,
+      prerenderDeps,
+      buildVars,
+      isPassthroughRoute,
+    );
   }
 
   async function renderStaticSegment(
@@ -508,6 +656,7 @@ export function createRouter<TEnv = any>(
     defaultErrorBoundary,
     findMatch,
     findInterceptForRoute,
+    telemetry: telemetrySink,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -520,8 +669,15 @@ export function createRouter<TEnv = any>(
   const router: RSCRouterInternal<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++;
@@ -552,7 +708,7 @@ export function createRouter<TEnv = any>(
         errorBoundary: [],
         notFoundBoundary: [],
         layout: [],
-        parallel: [],
+        parallel: {},
         intercept: [],
         loader: [],
       };
@@ -568,6 +724,11 @@ export function createRouter<TEnv = any>(
           parent: syntheticMapRoot,
           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[];
@@ -582,10 +743,15 @@ export function createRouter<TEnv = any>(
 
       // Collect route keys that have prerender handlers (for non-trie match path)
       let prerenderRouteKeys: Set<string> | undefined;
+      let passthroughRouteKeys: Set<string> | undefined;
       for (const [name, entry] of manifest.entries()) {
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
           prerenderRouteKeys.add(name);
+          if (entry.prerenderDef?.options?.passthrough === true) {
+            if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
+            passthroughRouteKeys.add(name);
+          }
         }
       }
 
@@ -608,7 +774,10 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
+            cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
+            ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
           });
         }
       } else {
@@ -625,7 +794,10 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
+          cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
+          ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
         });
       }
 
@@ -666,6 +838,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,
@@ -704,8 +877,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;
     },
 
@@ -735,15 +918,32 @@ export function createRouter<TEnv = any>(
     // Expose resolved theme configuration for NavigationProvider and MetaTags
     themeConfig: resolvedThemeConfig,
 
-    // Expose prefetch cache control for RSC handler
+    // Expose resolved cache profiles for per-request resolution
+    cacheProfiles: resolvedCacheProfiles,
+
+    // Expose prefetch cache settings
     prefetchCacheControl,
+    prefetchCacheTTL,
 
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
+    // Expose router-wide performance debugging for request-level metrics setup
+    debugPerformance,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 
+    // Expose origin check configuration for handler (default: enabled)
+    originCheck: originCheckOption ?? true,
+
+    // Expose SSR configuration for handler
+    ssr: ssrOption,
+
+    // Expose resolved timeouts for RSC handler
+    timeouts: resolvedTimeouts,
+    onTimeout,
+
     // Expose global middleware for RSC handler
     middleware: globalMiddleware,
 
@@ -789,6 +989,9 @@ export function createRouter<TEnv = any>(
     // Expose source file for per-router type generation
     __sourceFile,
 
+    // Expose basename for runtime manifest generation
+    __basename: basename,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused
@@ -830,7 +1033,9 @@ export function createRouter<TEnv = any>(
   RouterRegistry.set(routerId, router);
 
   // If urls option was provided, auto-register them
-  if (urlsOption) {
+  if (typeof urlsOption === "function") {
+    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+  } else if (urlsOption) {
     return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
   }