@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

package/src/router/trie-matching.ts

@@ -15,10 +15,6 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
-  optionalParams?: string[];
-  /** Ancestry shortCodes for layout pruning */
-  ancestry: string[];
   /** Redirect target if trailing slash requires it */
   redirectTo?: string;
   /** Route has pre-rendered data available */
@@ -43,14 +39,12 @@ export function tryTrieMatch(
 ): TrieMatchResult | null {
   if (!trie) return null;
 
-  // Split pathname into segments, filtering empty strings from leading/trailing slashes
   const pathnameHasTrailingSlash =
     pathname.length > 1 && pathname.endsWith("/");
   const normalizedPath = pathnameHasTrailingSlash
     ? pathname.slice(0, -1)
     : pathname;
 
-  // Handle root path
   if (normalizedPath === "" || normalizedPath === "/") {
     if (trie.r) {
       return validateAndBuild(
@@ -61,13 +55,24 @@ export function tryTrieMatch(
         pathnameHasTrailingSlash,
       );
     }
+    // A root-level wildcard ("/*") matches "/" with an empty remainder, the
+    // same value the regex matcher produces for the bare prefix. Without this
+    // the trie misses, the regex fallback runs, and its no-config branch emits
+    // a corrupt slice-off redirect. The static terminal still wins above.
+    if (trie.w) {
+      return validateAndBuild(
+        trie.w,
+        [],
+        "",
+        pathname,
+        pathnameHasTrailingSlash,
+      );
+    }
     return null;
   }
 
-  // Remove leading slash and split
   const segments = normalizedPath.slice(1).split("/");
 
-  // Try exact match with normalized path (no trailing slash)
   const result = walkTrie(trie, segments, 0, []);
   if (result) {
     return validateAndBuild(
@@ -89,8 +94,58 @@ interface WalkResult {
 }
 
 /**
- * Walk the trie by segments with priority: static > param > wildcard.
- * Uses backtracking to try all possible matches.
+ * Check a leaf's constraints (leaf.cv) against already-resolved named params.
+ * Empty/undefined values are exempt (optional params that were not bound).
+ */
+function constraintsSatisfied(
+  leaf: TrieLeaf,
+  params: Record<string, string>,
+): boolean {
+  if (!leaf.cv) return true;
+  for (const paramName in leaf.cv) {
+    const allowed = leaf.cv[paramName]!;
+    const value = params[paramName];
+    if (value !== undefined && value !== "" && !allowed.includes(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Constraint check for a candidate terminal DURING the walk. Builds the named
+ * params from positional walk values (decoded the same way validateAndBuild
+ * does) and validates leaf.cv. Returning false lets walkTrie unwind to a
+ * lower-priority sibling instead of committing to a leaf that would only be
+ * rejected post-walk — that post-walk rejection is what forced the regex
+ * fallback (and its false "trie gap" R3 warning) for perfectly valid configs.
+ */
+function leafConstraintsPass(
+  leaf: TrieLeaf,
+  paramValues: string[],
+  wildcardValue: string | undefined,
+): boolean {
+  if (!leaf.cv) return true;
+  const params: Record<string, string> = {};
+  if (leaf.pa) {
+    for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
+    }
+  }
+  if (wildcardValue !== undefined && "pn" in leaf) {
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
+  }
+  return constraintsSatisfied(leaf, params);
+}
+
+/**
+ * Walk the trie by segments with priority: static > suffix-param > param >
+ * wildcard (Priority 1-4 below; matches the canonical M4 ordering in
+ * docs/internal/matching-and-lazy-discovery.md).
+ * Uses backtracking to try all possible matches. Per-leaf constraints are
+ * enforced at each candidate terminal so a constraint miss backtracks to a
+ * lower-priority sibling rather than aborting the whole match.
  */
 function walkTrie(
   node: TrieNode,
@@ -98,25 +153,34 @@ function walkTrie(
   index: number,
   paramValues: string[],
 ): WalkResult | null {
-  // All segments consumed: check for terminal
   if (index === segments.length) {
-    if (node.r) {
+    if (node.r && leafConstraintsPass(node.r, paramValues, undefined)) {
       return { leaf: node.r, paramValues: [...paramValues] };
     }
+    // A wildcard at this node matches the bare prefix with an empty remainder
+    // (e.g. "/files" against "/files/*"), mirroring the regex matcher's `*=""`.
+    // walkTrie otherwise only reaches node.w in the index<length branch below,
+    // so without this a request to the wildcard's own prefix misses the trie
+    // and the regex fallback emits a corrupt redirect. A static terminal
+    // (node.r) still wins.
+    if (node.w && leafConstraintsPass(node.w, paramValues, "")) {
+      return { leaf: node.w, paramValues: [...paramValues], wildcardValue: "" };
+    }
     return null;
   }
 
   const segment = segments[index];
   const staticChild = node.s?.[segment];
 
-  // Priority 1: Static match
   if (staticChild) {
     const result = walkTrie(staticChild, segments, index + 1, paramValues);
     if (result) return result;
   }
 
-  // Priority 2: Suffix-param match (e.g., :productId.html)
   if (node.xp) {
+    // node.xp keys are pre-sorted longest-suffix-first at build time
+    // (route-trie.ts sortSuffixParams), so the first match is the most specific
+    // suffix: `/app.min.js` matches `:file.min.js` before `:file.js`.
     for (const suffix in node.xp) {
       if (segment.endsWith(suffix) && segment.length > suffix.length) {
         const paramValue = segment.slice(0, -suffix.length);
@@ -133,7 +197,6 @@ function walkTrie(
     }
   }
 
-  // Priority 3: Param match
   if (node.p) {
     paramValues.push(segment);
     const result = walkTrie(node.p.c, segments, index + 1, paramValues);
@@ -141,14 +204,15 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 4: Wildcard match (consumes rest)
   if (node.w) {
     const rest = joinRemainingSegments(segments, index);
-    return {
-      leaf: node.w,
-      paramValues: [...paramValues],
-      wildcardValue: rest,
-    };
+    if (leafConstraintsPass(node.w, paramValues, rest)) {
+      return {
+        leaf: node.w,
+        paramValues: [...paramValues],
+        wildcardValue: rest,
+      };
+    }
   }
 
   return null;
@@ -174,10 +238,6 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues.
-  // Params are URL-decoded at this boundary so ctx.params holds the values
-  // apps expect (matching Express/React Router) and round-trip cleanly
-  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
@@ -185,34 +245,15 @@ function validateAndBuild(
     }
   }
 
-  // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
     params[(leaf as TrieLeaf & { pn: string }).pn] =
       safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints against decoded values so constraint lists can be
-  // written in decoded form (e.g. ["en-GB", "en US"]).
-  if (leaf.cv) {
-    for (const paramName in leaf.cv) {
-      const allowed = leaf.cv[paramName]!;
-      const value = params[paramName];
-      if (value !== undefined && value !== "" && !allowed.includes(value)) {
-        return null;
-      }
-    }
-  }
-
-  // Fill in empty strings for optional params that weren't matched
-  if (leaf.op) {
-    for (const name of leaf.op) {
-      if (!(name in params)) {
-        params[name] = "";
-      }
-    }
+  if (!constraintsSatisfied(leaf, params)) {
+    return null;
   }
 
-  // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;
   let redirectTo: string | undefined;
 
@@ -230,10 +271,8 @@ function validateAndBuild(
     routeKey: leaf.n,
     sp: leaf.sp,
     params,
-    ancestry: leaf.a,
   };
 
-  if (leaf.op) result.optionalParams = leaf.op;
   if (redirectTo) result.redirectTo = redirectTo;
   if (leaf.pr) result.pr = true;
   if (leaf.pt) result.pt = true;

package/src/router/types.ts

@@ -22,27 +22,11 @@ import type {
   ShouldRevalidateFn,
 } from "../types";
 
-/**
- * Result of resolving loaders with revalidation
- * Contains both segments to render and all matched segment IDs
- */
-export interface LoaderRevalidationResult {
-  segments: ResolvedSegment[];
-  matchedIds: string[];
-}
-
-/**
- * Result of resolving segments with revalidation
- * Contains both segments to render and all matched segment IDs
- */
 export interface SegmentRevalidationResult {
   segments: ResolvedSegment[];
   matchedIds: string[];
 }
 
-/**
- * Action context type for revalidation
- */
 export type ActionContext = {
   actionId?: string;
   actionUrl?: URL;
@@ -50,23 +34,6 @@ export type ActionContext = {
   formData?: FormData;
 };
 
-/**
- * Dependencies passed to segment resolution functions
- * These are created within createRouter and passed to extracted utilities
- */
-export interface RouterDependencies<TEnv> {
-  findNearestErrorBoundary: (
-    entry: EntryData | null,
-  ) => ReactNode | ErrorBoundaryHandler | null;
-  findNearestNotFoundBoundary: (
-    entry: EntryData | null,
-  ) => ReactNode | NotFoundBoundaryHandler | null;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted segment resolution functions.
- * These are the closure-bound helpers that cannot be imported directly.
- */
 export interface SegmentResolutionDeps<TEnv = any> {
   wrapLoaderPromise: <T>(
     promise: Promise<T>,
@@ -98,23 +65,16 @@ export interface SegmentResolutionDeps<TEnv = any> {
   ) => ReactNode | NotFoundBoundaryHandler | null;
   notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+  /**
+   * Router-level default for the per-segment `transition({ viewTransition })`
+   * flag, from createRouter({ viewTransition }). Resolved into each segment's
+   * transition config during resolution (only `false` is stamped) so the render
+   * gate reads the boundary decision off the segment on both server and client.
+   * Undefined is treated as "auto" (wrap).
+   */
+  viewTransitionDefault?: "auto" | false;
 }
 
-/**
- * Dependencies injected from createRouter closure into extracted intercept resolution functions.
- */
-export interface InterceptResolutionDeps<TEnv = any> {
-  wrapLoaderPromise: SegmentResolutionDeps<TEnv>["wrapLoaderPromise"];
-  evaluateInterceptWhen: (
-    intercept: InterceptEntry,
-    selectorContext: InterceptSelectorContext | null,
-    isAction: boolean,
-  ) => boolean;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted match API functions.
- */
 export interface MatchApiDeps<TEnv = any> {
   findMatch: (pathname: string, ms?: any) => any;
   getMetricsStore: () => any;
@@ -129,23 +89,13 @@ export interface MatchApiDeps<TEnv = any> {
   getRouteMap: () => Record<string, string>;
 }
 
-/**
- * Title descriptor types for template support
- */
 export type TitleDescriptor =
   | string
   | { template: string; default: string } // For layouts - template applied to child titles
-  | { absolute: string }; // Bypass parent template
+  | { absolute: string };
 
-/**
- * Unset descriptor to remove inherited meta
- * Key format matches getMetaKey output: "title", "name:description", "property:og:image"
- */
 export type UnsetDescriptor = { unset: string };
 
-/**
- * Base meta descriptor types (sync values)
- */
 export type MetaDescriptorBase =
   | { charSet: "utf-8" }
   | { title: TitleDescriptor }
@@ -157,10 +107,6 @@ export type MetaDescriptorBase =
   | UnsetDescriptor
   | { [name: string]: unknown };
 
-/**
- * Meta descriptor that can be sync or async.
- * Use Promise<MetaDescriptorBase> for streaming meta that resolves after initial render.
- */
 export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
 
 type LdJsonObject = { [Key in string]: LdJsonValue } & {

package/src/router/url-params.ts

@@ -25,11 +25,6 @@ export function safeDecodeURIComponent(raw: string): string {
   }
 }
 
-// encodeURIComponent over-encodes for path segments. After running it,
-// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
-// keeps human-readable characters that are legal in a path segment.
-// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
-// encoded.
 const PATH_SAFE_ESCAPES: Record<string, string> = {
   "%3A": ":",
   "%40": "@",

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";
@@ -21,10 +18,11 @@ 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 {
   type EntryData,
   getContext,
-  RSCRouterContext,
+  RangoContext,
   type MetricsStore,
 } from "./server/context";
 import { createHandleStore, type HandleStore } from "./server/handle-store.js";
@@ -56,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,
@@ -70,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";
@@ -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";
 
@@ -111,26 +108,27 @@ 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,
@@ -150,6 +148,7 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -158,23 +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.
-  const basename =
-    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
-      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
-      : undefined;
+  // 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).
@@ -209,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 =
@@ -255,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)
@@ -331,7 +351,6 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 
@@ -365,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;
   }
@@ -537,6 +558,7 @@ export function createRouter<TEnv = any>(
     findNearestNotFoundBoundary,
     notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies
@@ -664,6 +686,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -673,7 +696,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 +744,7 @@ export function createRouter<TEnv = any>(
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -833,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: "",
@@ -932,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,
 
@@ -999,6 +1029,13 @@ export function createRouter<TEnv = any>(
     // 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
@@ -1016,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,
@@ -1045,9 +1084,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"];
@@ -31,6 +31,7 @@ export interface HandlerContext<TEnv = unknown> {
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response;
 
   /**