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

package/src/router/revalidation.ts

@@ -4,7 +4,7 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext } from "../types";
+import type { ResolvedSegment, HandlerContext, ActionRef } from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -14,21 +14,52 @@ import {
 import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import { paramsEqual } from "./params-util.js";
 
-function paramsEqual(
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean {
-  if (a === b) return true;
-
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) return false;
-
-  for (const key of keysA) {
-    if (a[key] !== b[key]) return false;
-  }
+/**
+ * Resolve a server-action reference's stable id, mirroring how the action
+ * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
+ * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
+ * production RSC build when present, otherwise React's `$$id`. Resolving both
+ * the incoming `actionId` and the reference with the same precedence makes
+ * `isAction()` form-agnostic across dev and production.
+ */
+function resolveActionRefId(ref: unknown): string | undefined {
+  if (ref == null) return undefined;
+  const r = ref as { $id?: unknown; $$id?: unknown };
+  if (typeof r.$id === "string") return r.$id;
+  if (typeof r.$$id === "string") return r.$$id;
+  return undefined;
+}
 
-  return true;
+/**
+ * Build the `isAction()` helper bound to the current action's id. Called with no
+ * arguments it answers "is this request an action at all?" (any action) — `true`
+ * during action handling, `false` on plain navigation. Called with one or more
+ * action references it narrows to those: a single imported action, several
+ * (variadic), or any export of a namespace import (`import * as Mod`). Returns
+ * `false` when there is no action (plain navigation) or nothing matches.
+ */
+function makeIsAction(
+  currentActionId: string | undefined,
+): (...actions: ActionRef[]) => boolean {
+  return (...actions: ActionRef[]): boolean => {
+    if (!currentActionId) return false;
+    // Bare isAction(): an action is in flight (currentActionId is set) and the
+    // caller did not narrow to a specific action, so this is "any action".
+    if (actions.length === 0) return true;
+    for (const action of actions) {
+      if (typeof action === "function") {
+        if (resolveActionRefId(action) === currentActionId) return true;
+      } else if (action && typeof action === "object") {
+        // Namespace import: match any export of the module.
+        for (const value of Object.values(action)) {
+          if (resolveActionRefId(value) === currentActionId) return true;
+        }
+      }
+    }
+    return false;
+  };
 }
 
 /**
@@ -95,8 +126,6 @@ export async function evaluateRevalidation<TEnv>(
   const paramsChanged = !paramsEqual(nextParams, prevParams);
   const searchChanged = prevUrl.search !== nextUrl.search;
 
-  // Trace helper: push a structured entry to the request-scoped trace buffer.
-  // Guarded by isTraceActive() so object construction is skipped in production.
   function pushTrace(
     defaultVal: boolean,
     finalVal: boolean,
@@ -115,43 +144,28 @@ export async function evaluateRevalidation<TEnv>(
     });
   }
 
-  // Calculate default revalidation based on segment type and request method
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
   if (defaultOverride) {
-    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
-    // Skip the type-derived heuristic — caller knows better in this context.
     defaultShouldRevalidate = defaultOverride.value;
     defaultReason = defaultOverride.reason;
   } else if (request.method === "POST") {
-    // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
-      // Route segment always revalidates on actions
       defaultShouldRevalidate = true;
       defaultReason = "action:route-segment";
     } else if (segment.type === "loader") {
-      // Loaders always revalidate on actions - they often contain action-sensitive data
-      // (e.g., cart count after add-to-cart action)
       defaultShouldRevalidate = true;
       defaultReason = "action:loader-segment";
     } else if (segment.belongsToRoute) {
-      // Segment belongs to route (orphan layouts/parallels) - revalidate
       defaultShouldRevalidate = true;
       defaultReason = "action:belongs-to-route";
     } else {
-      // Parent chain segment (shared layouts/parallels) - don't revalidate
       defaultShouldRevalidate = false;
       defaultReason = "action:parent-chain-skip";
     }
   } else {
-    // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
-    // Only the route segment revalidates by default - all others require explicit opt-in
-
     if (segment.type === "route") {
-      // Route segments revalidate when path params OR search params change.
-      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
-      // so the handler must re-execute to produce updated content.
       const routeChanged = paramsChanged || searchChanged;
       defaultShouldRevalidate = routeChanged;
       defaultReason = paramsChanged
@@ -167,8 +181,6 @@ export async function evaluateRevalidation<TEnv>(
         });
       }
     } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
-      // Children of the route path (loaders, orphan layouts/parallels)
-      // revalidate when path params or search params change
       defaultShouldRevalidate = true;
       defaultReason = paramsChanged
         ? "nav:route-child-params-changed"
@@ -180,9 +192,6 @@ export async function evaluateRevalidation<TEnv>(
         searchChanged,
       });
     } else {
-      // Parent layouts and parallels default to no revalidation
-      // Cannot assume these segments depend on params without explicit declaration
-      // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;
       defaultReason = "nav:non-route-skip";
       debugLog("revalidation", "non-route segment skipped by default", {
@@ -192,7 +201,6 @@ export async function evaluateRevalidation<TEnv>(
     }
   }
 
-  // No custom revalidations defined - return default behavior without prev segment
   if (revalidations.length === 0) {
     if (defaultShouldRevalidate) {
       debugLog("revalidation", "default revalidate=true", {
@@ -209,14 +217,10 @@ export async function evaluateRevalidation<TEnv>(
     return defaultShouldRevalidate;
   }
 
-  // Custom revalidations exist - may need full prev segment
-  // Lazy load prev segment only if getPrevSegment provided
   const prevSegment = getPrevSegment ? await getPrevSegment() : null;
 
-  // Execute revalidation functions with soft/hard decision pattern
   let currentSuggestion = defaultShouldRevalidate;
 
-  // Compute public route names (filtered: undefined for auto-generated routes)
   const toRouteName =
     routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
   const reqCtx = _getRequestContext();
@@ -240,23 +244,18 @@ export async function evaluateRevalidation<TEnv>(
       slotName: segment.slot,
       // Action context (only populated when triggered by server action)
       actionId: actionContext?.actionId,
+      isAction: makeIsAction(actionContext?.actionId),
       actionUrl: actionContext?.actionUrl,
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,
-      method: request.method, // GET for navigation, POST for actions
-      routeName: toRouteName, // Navigation target route name (filtered)
-      fromRouteName, // Navigation source route name (filtered)
-      toRouteName, // Navigation target route name (filtered)
-      // Stale cache context (only true for background revalidation after stale cache render)
+      method: request.method,
+      routeName: toRouteName,
+      fromRouteName,
+      toRouteName,
       stale,
     });
 
-    // Check return type:
-    // - boolean: hard decision, short-circuit immediately
-    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
-    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
     if (typeof result === "boolean") {
-      // Hard decision - short-circuit
       debugLog("revalidation", "hard decision", {
         segmentId: segment.id,
         revalidator: name,
@@ -269,7 +268,6 @@ export async function evaluateRevalidation<TEnv>(
       typeof result === "object" &&
       "defaultShouldRevalidate" in result
     ) {
-      // Soft decision - update suggestion and continue
       currentSuggestion = result.defaultShouldRevalidate;
       debugLog("revalidation", "soft decision", {
         segmentId: segment.id,
@@ -277,18 +275,14 @@ export async function evaluateRevalidation<TEnv>(
         revalidate: currentSuggestion,
       });
     } else if (result === null || result === undefined) {
-      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
-      // This means "I don't care, use whatever the default is"
       debugLog("revalidation", "deferred to current default", {
         segmentId: segment.id,
         revalidator: name,
         revalidate: currentSuggestion,
       });
-      // currentSuggestion stays the same, continue to next function
     }
   }
 
-  // All revalidators completed - use final suggestion
   debugLog("revalidation", "final decision", {
     segmentId: segment.id,
     revalidate: currentSuggestion,

package/src/router/route-snapshot.ts

@@ -230,7 +230,6 @@ export function createRouteSnapshot<TEnv = any>(
       entry: {} as any,
       routeKey: "test",
       params: {},
-      optionalParams: new Set(),
     } as RouteMatchResult<TEnv>,
     manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
     entries: [],

package/src/router/router-context.ts

@@ -54,10 +54,8 @@ export interface InterceptResult {
  * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
  */
 export interface RouterContext<TEnv = any> {
-  // Route matching
   findMatch: (pathname: string) => RouteMatchResult | null;
 
-  // Manifest loading
   loadManifest: (
     entry: any,
     routeKey: string,
@@ -66,10 +64,8 @@ export interface RouterContext<TEnv = any> {
     isSSR?: boolean,
   ) => Promise<EntryData>;
 
-  // Entry traversal
   traverseBack: (entry: EntryData) => Generator<EntryData>;
 
-  // Handler context creation
   createHandlerContext: (
     params: Record<string, string>,
     request: Request,
@@ -83,7 +79,6 @@ export interface RouterContext<TEnv = any> {
     isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
-  // Loader setup
   setupLoaderAccess: (
     ctx: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
@@ -94,7 +89,6 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => void;
 
-  // Context access
   getContext: () => {
     getOrCreateStore: (key: string) => any;
     runWithStore: <T>(
@@ -105,16 +99,13 @@ export interface RouterContext<TEnv = any> {
     ) => T;
   };
 
-  // Metrics
   getMetricsStore: () => MetricsStore | undefined;
 
-  // Cache
   createCacheScope: (
     cacheConfig: any,
     parent: CacheScope | null,
   ) => CacheScope | null;
 
-  // Intercept detection
   findInterceptForRoute: (
     routeKey: string,
     parentEntry: EntryData | null,
@@ -122,7 +113,6 @@ export interface RouterContext<TEnv = any> {
     isAction: boolean,
   ) => InterceptResult | null;
 
-  // Segment resolution (with revalidation)
   resolveAllSegmentsWithRevalidation: (
     entries: EntryData[],
     routeKey: string,
@@ -133,7 +123,6 @@ export interface RouterContext<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext: any | undefined,
     interceptResult: InterceptResult | null,
     localRouteName: string,
@@ -166,12 +155,10 @@ export interface RouterContext<TEnv = any> {
     revalidationContext?: RevalidationContext,
   ) => Promise<ResolvedSegment[]>;
 
-  // Collect with markers
   collectWithMarkers?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<{ items: T[]; matchedIds: string[] }>;
 
-  // Revalidation evaluation
   evaluateRevalidation: (params: {
     segment: ResolvedSegment;
     prevParams: Record<string, string>;
@@ -195,7 +182,6 @@ export interface RouterContext<TEnv = any> {
       | "intercept-loader";
   }) => Promise<boolean>;
 
-  // Request context
   getRequestContext: () =>
     | {
         waitUntil: (fn: () => Promise<void>) => void;
@@ -203,7 +189,6 @@ export interface RouterContext<TEnv = any> {
       }
     | undefined;
 
-  // Simple segment resolution (without revalidation - for full match)
   resolveAllSegments: (
     entries: EntryData[],
     routeKey: string,
@@ -213,7 +198,6 @@ export interface RouterContext<TEnv = any> {
     options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
-  // Generator-based simple resolution
   resolveAllSegmentsGenerator?: (
     entries: EntryData[],
     routeKey: string,
@@ -222,21 +206,17 @@ export interface RouterContext<TEnv = any> {
     loaderPromises: Map<string, Promise<any>>,
   ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
 
-  // Collect segments from generator
   collectSegmentsFromGenerator?: <T>(
     gen: AsyncGenerator<T | { __type: "id"; id: string }>,
   ) => Promise<T[]>;
 
-  // Handle store
   createHandleStore: () => any;
 
-  // Loaders-only resolution (for full match cache hit - no revalidation)
   resolveLoadersOnly?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
   ) => Promise<ResolvedSegment[]>;
 
-  // Loaders-only resolution (for cache hit scenarios)
   resolveLoadersOnlyWithRevalidation?: (
     entries: EntryData[],
     handlerContext: HandlerContext<any, TEnv>,
@@ -258,10 +238,8 @@ export interface RouterContext<TEnv = any> {
   // Telemetry sink (optional, no-op when undefined)
   telemetry?: TelemetrySink;
 
-  // Request ID for telemetry span correlation (set per-request in match handlers)
   requestId?: string;
 
-  // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,
     entry: EntryData,
@@ -284,7 +262,6 @@ export interface RouterContext<TEnv = any> {
   } | null>;
 }
 
-// AsyncLocalStorage instance for router context
 const routerContext = new AsyncLocalStorage<RouterContext<any>>();
 
 /**
@@ -308,10 +285,6 @@ export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
  *
  * All async code within fn() can call getRouterContext() to access router closures.
  * This works across async boundaries thanks to AsyncLocalStorage.
- *
- * @param deps Router dependencies to make available
- * @param fn Function to run with dependencies available
- * @returns Result of fn()
  */
 export function runWithRouterContext<T, TEnv = any>(
   deps: RouterContext<TEnv>,

package/src/router/router-interfaces.ts

@@ -2,18 +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 } from "../urls/pattern-types.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";
 
@@ -49,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>,
 > {
@@ -89,16 +87,16 @@ export interface RSCRouter<
    * ])
    * ```
    */
-  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>): RSCRouter<TEnv, TRoutes>;
+  routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -108,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
@@ -141,7 +144,7 @@ export interface RSCRouter<
    * type AppRoutes = typeof _router.routeMap;
    *
    * declare global {
-   *   namespace RSCRouter {
+   *   namespace Rango {
    *     interface RegisteredRoutes extends AppRoutes {}
    *   }
    * }
@@ -177,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>,
 > {
@@ -206,26 +209,36 @@ export interface RSCRouterInternal<
   readonly basename: string | undefined;
 
   /**
-   * Register routes using URL patterns from urls() or a builder function
-   */
-  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>): RSCRouter<TEnv, TRoutes>;
+  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
@@ -247,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)
@@ -287,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
@@ -359,6 +379,17 @@ export interface RSCRouterInternal<
   /** @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>,
@@ -378,11 +409,13 @@ export interface RSCRouterInternal<
     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>;
 
@@ -396,7 +429,7 @@ export interface RSCRouterInternal<
     routeName?: string,
     buildEnv?: any,
     devMode?: boolean,
-  ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null>;
+  ): Promise<{ encoded: string; handles: string } | null>;
 
   /**
    * Preview match - returns route middleware without segment resolution.
@@ -469,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>;
 }