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

package/src/browser/types.ts

@@ -32,6 +32,9 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
 export interface RscMetadata {
   pathname: string;
   segments: ResolvedSegment[];
+  /** Router instance ID. When this changes between navigations, the client
+   *  forces a full tree replacement (app switch via host router). */
+  routerId?: string;
   isPartial?: boolean;
   isError?: boolean;
   matched?: string[];
@@ -55,6 +58,11 @@ export interface RscMetadata {
    * Used to detect version mismatches after HMR/deployment.
    */
   version?: string;
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * Sent on initial render so the browser can configure its cache duration.
+   */
+  prefetchCacheTTL?: number;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.
@@ -65,6 +73,8 @@ export interface RscMetadata {
    * Included when theme is enabled in router config.
    */
   initialTheme?: Theme;
+  /** URL prefix for all routes (from createRouter({ basename })). */
+  basename?: string;
   /** Whether connection warmup is enabled */
   warmupEnabled?: boolean;
   /** Server-side redirect with optional state (for partial requests) */
@@ -210,6 +220,15 @@ export interface SegmentState {
 export interface NavigationUpdate {
   root: ReactNode | Promise<ReactNode>;
   metadata: RscMetadata;
+  /** Scroll behavior to apply after React commits this update */
+  scroll?: {
+    /** For back/forward: restore saved position */
+    restore?: boolean;
+    /** Set to false to disable scrolling entirely */
+    enabled?: boolean;
+    /** Function to check if streaming is in progress */
+    isStreaming?: () => boolean;
+  };
 }
 
 /**
@@ -227,6 +246,25 @@ export type HistoryState =
 export interface NavigateOptions {
   replace?: boolean;
   scroll?: boolean;
+  /**
+   * Whether to revalidate server data on navigation.
+   * Set to `false` to skip the RSC server fetch and only update the URL.
+   *
+   * Only takes effect when the pathname stays the same (search param / hash changes).
+   * If the pathname changes, this option is ignored and a full navigation occurs.
+   *
+   * All location-aware hooks (`useSearchParams`, `useNavigation`, etc.) still update.
+   * Server components do not re-render.
+   *
+   * @default true
+   *
+   * @example
+   * ```tsx
+   * router.push("/products?color=blue", { revalidate: false });
+   * router.replace("/products?page=3", { revalidate: false });
+   * ```
+   */
+  revalidate?: boolean;
   /**
    * State to pass to history.pushState/replaceState
    * Accessible via useLocationState() hook.
@@ -308,7 +346,13 @@ export type ReadonlyURLSearchParams = Omit<
 export interface RscBrowserDependencies {
   createFromFetch: <T>(
     response: Promise<Response>,
-    options?: { temporaryReferences?: any },
+    options?: {
+      temporaryReferences?: any;
+      findSourceMapURL?: (
+        filename: string,
+        environmentName: string,
+      ) => string | null;
+    },
   ) => Promise<T>;
   createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
   encodeReply: (
@@ -370,10 +414,13 @@ export interface NavigationStore {
     segments: ResolvedSegment[],
     handleData?: HandleData,
   ): void;
-  getCachedSegments(
-    historyKey: string,
-  ):
-    | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+  getCachedSegments(historyKey: string):
+    | {
+        segments: ResolvedSegment[];
+        stale: boolean;
+        handleData?: HandleData;
+        routerId?: string;
+      }
     | undefined;
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
@@ -389,6 +436,10 @@ export interface NavigationStore {
   getInterceptSourceUrl(): string | null;
   setInterceptSourceUrl(url: string | null): void;
 
+  // Router identity tracking (for cross-app navigation detection)
+  getRouterId?(): string | undefined;
+  setRouterId?(id: string): void;
+
   // UI update notifications
   onUpdate(callback: UpdateSubscriber): () => void;
   emitUpdate(update: NavigationUpdate): void;
@@ -419,6 +470,8 @@ export interface FetchPartialOptions {
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;
+  /** Current router ID — server detects app switch and returns full response */
+  routerId?: string;
   /** If true, this is an HMR refetch - server should invalidate manifest cache */
   hmr?: boolean;
 }
@@ -487,6 +540,8 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
+  updateVersion(newVersion: string): void;
 }
 
 /**

package/src/build/generate-manifest.ts

@@ -45,7 +45,7 @@ export interface GeneratedManifest {
   routeTrailingSlash?: Record<string, string>;
   /** Route names using Prerender (for dev-mode Node.js delegation) */
   prerenderRoutes?: string[];
-  /** Route names with passthrough: true (handler kept in bundle for live fallback) */
+  /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
   passthroughRoutes?: string[];
   /** Route name → response type for non-RSC routes */
   responseTypeRoutes?: Record<string, string>;
@@ -150,10 +150,7 @@ function buildPrefixTreeNode(
         if (prerenderDefs && entry.prerenderDef) {
           prerenderDefs[name] = entry.prerenderDef;
         }
-        if (
-          passthroughRoutes &&
-          entry.prerenderDef?.options?.passthrough === true
-        ) {
+        if (passthroughRoutes && entry.isPassthrough === true) {
           passthroughRoutes.push(name);
         }
       }
@@ -285,6 +282,7 @@ export function generateManifest<TEnv>(
 export function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
+  options?: { urlPrefix?: string },
 ): FullManifest {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
@@ -310,6 +308,8 @@ export function generateManifestFull<TEnv>(
       counters: {},
       mountIndex,
       trackedIncludes, // Enable include tracking
+      // basename sets the initial URL prefix for all path() registrations
+      ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
     },
     () => {
       const helpers = createRouteHelpers();
@@ -347,7 +347,7 @@ export function generateManifestFull<TEnv>(
       if (entry.prerenderDef) {
         prerenderDefs[name] = entry.prerenderDef;
       }
-      if (entry.prerenderDef?.options?.passthrough === true) {
+      if (entry.isPassthrough === true) {
         passthroughRoutes.push(name);
       }
     }

package/src/build/generate-route-types.ts

@@ -25,9 +25,14 @@ export {
 } from "./route-types/include-resolution.js";
 export {
   extractUrlsVariableFromRouter,
+  extractUrlsFromRouter,
+  extractBasenameFromRouter,
+  type UrlsExtractionResult,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,
   detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
   findRouterFiles,
   writeCombinedRouteTypes,
 } from "./route-types/router-processing.js";

package/src/build/route-trie.ts

@@ -47,6 +47,8 @@ export interface TrieNode {
   s?: Record<string, TrieNode>;
   /** Param child: { n: paramName, c: child node } */
   p?: { n: string; c: TrieNode };
+  /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
+  xp?: Record<string, { n: string; c: TrieNode }>;
   /** Wildcard terminal: leaf + paramName */
   w?: TrieLeaf & { pn: string };
 }
@@ -158,6 +160,11 @@ export function extractAncestryFromTrie(
         visit(child);
       }
     }
+    if (node.xp) {
+      for (const child of Object.values(node.xp)) {
+        visit(child.c);
+      }
+    }
     if (node.p) {
       visit(node.p.c);
     }
@@ -235,10 +242,19 @@ function insertSegments(
       mergeLeaf(node, leaf);
       // AND continue with param child (param present)
     }
-    if (!node.p) {
-      node.p = { n: segment.value, c: {} };
+    if (segment.suffix) {
+      // Suffix param: keyed by suffix string (e.g., ".html")
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leaf);
     }
-    insertSegments(node.p.c, segments, index + 1, leaf);
   } else if (segment.type === "wildcard") {
     // Wildcard consumes all remaining segments
     const wildLeaf = { ...leaf, pn: "*" };

package/src/build/route-types/include-resolution.ts

@@ -357,12 +357,17 @@ function buildRouteMapFromBlock(
 /**
  * Build route map and search schemas together.
  * Internal helper used by the include resolution path.
+ *
+ * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
+ *   builder function). When provided, variableName is ignored and the block
+ *   is parsed directly for path()/include() calls.
  */
 export function buildCombinedRouteMapWithSearch(
   filePath: string,
   variableName?: string,
   visited?: Set<string>,
   diagnosticsOut?: UnresolvableInclude[],
+  inlineBlock?: string,
 ): {
   routes: Record<string, string>;
   searchSchemas: Record<string, Record<string, string>>;
@@ -384,7 +389,9 @@ export function buildCombinedRouteMapWithSearch(
   }
 
   let block: string;
-  if (variableName) {
+  if (inlineBlock) {
+    block = inlineBlock;
+  } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(source, variableName);
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;