@rangojs/router 0.0.0-experimental.29-prefetch-cache.29972e92 → 0.0.0-experimental.2a0dea97

package/src/browser/segment-reconciler.ts

@@ -6,6 +6,39 @@ import {
 } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
+import { debugLog } from "./logging.js";
+
+/**
+ * Carry forward renderSegments' internal memoization fields from the cached
+ * segment onto a merged/spread result. Without this, every reconcile that
+ * produces a fresh object ref drops the stable Promise wrappers that keep
+ * React's use() in "known fulfilled" state. The hasSameReferences guards
+ * inside renderSegments invalidate stale memoization when the underlying
+ * sources actually change, so copying is always safe. Server-provided values
+ * on `merged` (e.g., parallel intercept loaderDataPromise) win via the
+ * undefined check.
+ */
+const MEMO_FIELDS = [
+  "contentPromise",
+  "contentSource",
+  "layoutLoaderSources",
+  "parallelLoaderSources",
+  "loaderDataPromise",
+] as const;
+
+function preserveMemoization(
+  merged: ResolvedSegment,
+  cached: ResolvedSegment,
+): ResolvedSegment {
+  let result: ResolvedSegment | null = null;
+  for (const field of MEMO_FIELDS) {
+    if (merged[field] === undefined && cached[field] !== undefined) {
+      if (!result) result = { ...merged };
+      (result as any)[field] = cached[field];
+    }
+  }
+  return result ?? merged;
+}
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -85,15 +118,33 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const cachedSegments = new Map<string, ResolvedSegment>();
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
+  const diffSet = new Set(diff);
+  debugLog(
+    `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
+  );
+  debugLog(
+    `[reconcile] server segments: ${[...serverSegments.keys()].join(", ")}`,
+  );
+  debugLog(
+    `[reconcile] cached segments: ${[...cachedSegments.keys()].join(", ")}`,
+  );
+
   const segments = matched
     .map((segId: string) => {
       const fromServer = serverSegments.get(segId);
       const fromCache = cachedSegments.get(segId);
 
       if (fromServer) {
+        const inDiff = diffSet.has(segId);
         // Merge partial loader data when server returns fewer loaders than cached
         if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
-          return mergeSegmentLoaders(fromServer, fromCache);
+          debugLog(
+            `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
+          );
+          return preserveMemoization(
+            mergeSegmentLoaders(fromServer, fromCache),
+            fromCache,
+          );
         }
 
         // Preserve cached structural properties to maintain consistent React tree.
@@ -143,8 +194,14 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
           // above fails to preserve a value it should have.
           assertSegmentStructure(fromCache, merged, context);
 
-          return merged;
+          debugLog(
+            `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
+          );
+          return preserveMemoization(merged, fromCache);
         }
+        debugLog(
+          `[reconcile] ${segId}: SERVER only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
+        );
         return fromServer;
       }
 
@@ -158,15 +215,20 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         return fromCache;
       }
 
-      // For non-action actors: cached segments the server decided not to re-render.
-      // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - Clear truthy loading (active skeleton) to prevent suspense on cached content
-      if (actor !== "action") {
-        if (fromCache.loading !== undefined && fromCache.loading !== false) {
-          return { ...fromCache, loading: undefined };
-        }
-      }
+      debugLog(
+        `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
+      );
 
+      // Return the cached segment as-is, regardless of actor. We used to clear
+      // truthy `loading` here to prevent a stale Suspense fallback from
+      // committing against cached content, but that swapped the render tree
+      // from the LoaderBoundary branch to the plain OutletProvider branch
+      // inside renderSegments, causing React to unmount the entire chain
+      // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
+      // Suspender) every time the user opened an intercept or navigated back
+      // to a cached page. The flicker is now prevented by renderSegments'
+      // promise memoization keeping React's use() in "known fulfilled" state,
+      // so preserving `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/browser/server-action-bridge.ts

@@ -29,6 +29,7 @@ import {
 } from "./response-adapter.js";
 import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
+import { getAppVersion } from "./app-version.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -43,8 +44,6 @@ if (typeof Symbol.asyncDispose === "undefined") {
  */
 export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
-  version?: string;
   /** Callback to trigger SPA navigation (for action redirects) */
   onNavigate?: (
     url: string,
@@ -75,7 +74,6 @@ export function createServerActionBridge(
     deps,
     onUpdate,
     renderSegments,
-    version,
     onNavigate,
   } = config;
 
@@ -86,7 +84,7 @@ export function createServerActionBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: getAppVersion,
   });
 
   /**
@@ -165,9 +163,15 @@ export function createServerActionBridge(
         segmentState.currentSegmentIds.join(","),
       );
       // Add version param for version mismatch detection
+      const version = getAppVersion();
       if (version) {
         url.searchParams.set("_rsc_v", version);
       }
+      // Add router ID for app switch detection
+      const rid = store.getRouterId?.();
+      if (rid) {
+        url.searchParams.set("_rsc_rid", rid);
+      }
 
       // Encode arguments
       const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -206,7 +210,6 @@ export function createServerActionBridge(
           "rsc-action": id,
           "X-RSC-Router-Client-Path": segmentState.currentUrl,
           ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
-          // Send intercept source URL so server can maintain intercept context
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
           }),
@@ -309,7 +312,6 @@ export function createServerActionBridge(
         matchedCount: payload.metadata?.matched?.length ?? 0,
         diffCount: payload.metadata?.diff?.length ?? 0,
       });
-
       // Guard: if the action was aborted while streaming (e.g., user navigated
       // away or abortAllActions fired), bail out before any reconcile/render/cache
       // writes to avoid overwriting the current UI with stale action results.

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,6 +25,9 @@ export {
 } from "./route-types/include-resolution.js";
 export {
   extractUrlsVariableFromRouter,
+  extractUrlsFromRouter,
+  extractBasenameFromRouter,
+  type UrlsExtractionResult,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,
   detectUnresolvableIncludesForUrlsFile,

package/src/build/route-trie.ts

@@ -98,8 +98,14 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
@@ -107,14 +113,13 @@ function insertRoute(
   index: number,
   leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      paramNames.push(seg.value);
       if (seg.optional) {
         optionalParams.push(seg.value);
       }
@@ -124,21 +129,15 @@ function insertRoute(
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
     ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Recursively insert segments into the trie.
- * For optional params, we add a terminal at the current node (param absent)
- * AND continue inserting into the param child (param present).
- */
 /**
  * Extract ancestry map from a built trie by visiting all leaf nodes.
  * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
@@ -218,15 +217,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -235,12 +244,19 @@ function insertSegments(
   if (segment.type === "static") {
     if (!node.s) node.s = {};
     if (!node.s[segment.value]) node.s[segment.value] = {};
-    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } else if (segment.type === "param") {
     if (segment.optional) {
-      // Optional param: add terminal at current node (param absent)
-      mergeLeaf(node, leaf);
-      // AND continue with param child (param present)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
     if (segment.suffix) {
       // Suffix param: keyed by suffix string (e.g., ".html")
@@ -248,16 +264,26 @@ function insertSegments(
       if (!node.xp[segment.suffix]) {
         node.xp[segment.suffix] = { n: segment.value, c: {} };
       }
-      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     } 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, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*",
+    };
     const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
     const merged = mergeLeaves(existing, wildLeaf);
     node.w = merged as TrieLeaf & { pn: string };

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;