@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.a99e6916

package/src/browser/react/Link.tsx

@@ -5,6 +5,7 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useRef,
   type ForwardRefExoticComponent,
   type RefAttributes,
@@ -32,6 +33,7 @@ export type LinkState =
   | StateOrGetter<Record<string, unknown>>;
 
 import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import {
   observeForPrefetch,
   unobserveForPrefetch,
@@ -95,6 +97,26 @@ export interface LinkProps extends Omit<
    * @default "none"
    */
   prefetch?: PrefetchStrategy;
+  /**
+   * Custom prefetch cache key for source-agnostic cache reuse.
+   * When set, prefetch responses are cached independently of the current
+   * page URL, so navigating to the same target from different source pages
+   * reuses the cached prefetch.
+   *
+   * - String: static group name (e.g., `"pages"`)
+   * - Function: receives current URL (`window.location.href`), returns a
+   *   normalized source key
+   *
+   * @example
+   * ```tsx
+   * // Static group — all "pages" links share one cache entry per target
+   * <Link to="/page/3" prefetch="hover" prefetchKey="pages" />
+   *
+   * // Normalize — strip trailing page number from source URL
+   * <Link to="/page/3" prefetch="hover" prefetchKey={(from) => from.replace(/\/\d+$/, '')} />
+   * ```
+   */
+  prefetchKey?: string | ((from: string) => string);
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.
@@ -182,6 +204,7 @@ export const Link: ForwardRefExoticComponent<
     reloadDocument = false,
     revalidate,
     prefetch = "none",
+    prefetchKey,
     state,
     children,
     onClick,
@@ -192,6 +215,16 @@ export const Link: ForwardRefExoticComponent<
   const ctx = useContext(NavigationStoreContext);
   const isExternal = isExternalUrl(to);
 
+  // Auto-prefix with basename for app-local paths.
+  // Skip if external, already prefixed, or not a root-relative path.
+  const resolvedTo = useMemo(() => {
+    if (isExternal) return to;
+    const bn = ctx?.basename;
+    if (!bn || !to.startsWith("/") || to.startsWith(bn + "/") || to === bn)
+      return to;
+    return to === "/" ? bn : bn + to;
+  }, [to, isExternal, ctx?.basename]);
+
   // Resolve adaptive: viewport on touch devices, hover on pointer devices
   const resolvedStrategy =
     prefetch === "adaptive" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
@@ -273,9 +306,23 @@ export const Link: ForwardRefExoticComponent<
         resolvedState = currentState;
       }
 
-      ctx.navigate(to, { replace, scroll, state: resolvedState, revalidate });
+      ctx.navigate(resolvedTo, {
+        replace,
+        scroll,
+        state: resolvedState,
+        revalidate,
+      });
     },
-    [to, isExternal, reloadDocument, replace, scroll, revalidate, ctx, onClick],
+    [
+      resolvedTo,
+      isExternal,
+      reloadDocument,
+      replace,
+      scroll,
+      revalidate,
+      ctx,
+      onClick,
+    ],
   );
 
   const handleMouseEnter = useCallback(() => {
@@ -289,9 +336,15 @@ export const Link: ForwardRefExoticComponent<
       // prefetch — prefetchDirect bypasses the queue, and hasPrefetch
       // deduplicates if the viewport prefetch already completed.
       const segmentState = ctx.store.getSegmentState();
-      prefetchDirect(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchDirect(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+        prefetchKey,
+      );
     }
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
@@ -308,7 +361,13 @@ export const Link: ForwardRefExoticComponent<
     const triggerPrefetch = () => {
       if (cancelled) return;
       const segmentState = ctx.store.getSegmentState();
-      prefetchQueued(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchQueued(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+        prefetchKey,
+      );
     };
 
     // Schedule prefetch only when the app is idle (no navigation/streaming).
@@ -347,12 +406,12 @@ export const Link: ForwardRefExoticComponent<
         unobserveForPrefetch(observedElement);
       }
     };
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a
       ref={setRef}
-      href={to}
+      href={resolvedTo}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
       data-link-component
@@ -362,7 +421,7 @@ export const Link: ForwardRefExoticComponent<
       data-revalidate={revalidate === false ? "false" : undefined}
       {...props}
     >
-      <LinkContext.Provider value={to}>{children}</LinkContext.Provider>
+      <LinkContext.Provider value={resolvedTo}>{children}</LinkContext.Provider>
     </a>
   );
 });

package/src/browser/react/NavigationProvider.tsx

@@ -134,9 +134,14 @@ export interface NavigationProviderProps {
 
   /**
    * App version from server payload (stable, immutable).
-   * Forwarded to prefetch requests for version mismatch detection.
+   * Forwarded to context for cache key building.
    */
   version?: string;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   */
+  basename?: string;
 }
 
 /**
@@ -169,6 +174,7 @@ export function NavigationProvider({
   initialTheme,
   warmupEnabled,
   version,
+  basename,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -198,6 +204,7 @@ export function NavigationProvider({
       navigate,
       refresh,
       version,
+      basename,
     }),
     [],
   );

package/src/browser/react/context.ts

@@ -43,10 +43,15 @@ export interface NavigationStoreContextValue {
   refresh: () => Promise<void>;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Used in prefetch requests for version mismatch detection.
+   * App version from the initial server payload.
    */
   version: string | undefined;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used by Link and useRouter() to auto-prefix app-local paths.
+   */
+  basename: string | undefined;
 }
 
 /**

package/src/browser/react/use-handle.ts

@@ -9,64 +9,11 @@ import {
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
-import { getCollectFn } from "../../handle.js";
+import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 
-/**
- * Resolve the collect function for a handle.
- * Handle objects are plain { __brand, $$id } - collect is stored in the registry
- * (populated when createHandle runs on the client).
- */
-function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
-  // Look up collect from the registry (populated when the handle module is imported).
-  const registered = getCollectFn(handle.$$id);
-  if (registered) {
-    return registered as (segments: T[][]) => A;
-  }
-
-  // Fall back to default flat collect with a dev warning.
-  if (process.env.NODE_ENV !== "production") {
-    console.warn(
-      `[rsc-router] Handle "${handle.$$id}" was passed as a prop but its collect ` +
-        `function could not be resolved. Falling back to flat array. ` +
-        `Import the handle module in a client component to register its collect function.`,
-    );
-  }
-  return ((segments: unknown[][]) => segments.flat()) as unknown as (
-    segments: T[][],
-  ) => A;
-}
-
-/**
- * Collect handle data from segments and transform to final value.
- */
-function collectHandle<T, A>(
-  handle: Handle<T, A>,
-  data: HandleData,
-  segmentOrder: string[],
-): A {
-  const collect = resolveCollect(handle);
-  const segmentData = data[handle.$$id];
-
-  if (!segmentData) {
-    return collect([]);
-  }
-
-  // Build array of segment arrays in parent -> child order
-  const segmentArrays: T[][] = [];
-  for (const segmentId of segmentOrder) {
-    const entries = segmentData[segmentId];
-    if (entries && entries.length > 0) {
-      segmentArrays.push(entries as T[]);
-    }
-  }
-
-  // Call collect once with all segment data
-  return collect(segmentArrays);
-}
-
 /**
  * Hook to access collected handle data.
  *
@@ -99,13 +46,13 @@ export function useHandle<T, A, S>(
   // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<A | S>(() => {
     if (!ctx) {
-      const collected = collectHandle(handle, {}, []);
+      const collected = collectHandleData(handle, {}, []);
       return selector ? selector(collected) : collected;
     }
 
     // On client, use event controller state
     const state = ctx.eventController.getHandleState();
-    const collected = collectHandle(handle, state.data, state.segmentOrder);
+    const collected = collectHandleData(handle, state.data, state.segmentOrder);
     return selector ? selector(collected) : collected;
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -125,7 +72,7 @@ export function useHandle<T, A, S>(
     // Sync current state for the (possibly new) handle so that switching
     // handles on an idle page doesn't leave stale data from the old handle.
     const currentHandleState = ctx.eventController.getHandleState();
-    const currentCollected = collectHandle(
+    const currentCollected = collectHandleData(
       handle,
       currentHandleState.data,
       currentHandleState.segmentOrder,
@@ -142,7 +89,11 @@ export function useHandle<T, A, S>(
       const state = ctx.eventController.getHandleState();
       const isAction =
         ctx.eventController.getState().inflightActions.length > 0;
-      const collected = collectHandle(handle, state.data, state.segmentOrder);
+      const collected = collectHandleData(
+        handle,
+        state.data,
+        state.segmentOrder,
+      );
       const nextValue = selectorRef.current
         ? selectorRef.current(collected)
         : collected;

package/src/browser/react/use-router.ts

@@ -3,6 +3,7 @@
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { prefetchDirect } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**
@@ -29,14 +30,22 @@ export function useRouter(): RouterInstance {
   }
 
   // Stable reference: ctx is itself stable (NavigationProvider memoizes with [])
-  return useMemo<RouterInstance>(
-    () => ({
+  return useMemo<RouterInstance>(() => {
+    /** Prefix a root-relative path with basename if not already prefixed. */
+    function withBasename(url: string): string {
+      const bn = ctx!.basename;
+      if (!bn || !url.startsWith("/") || url.startsWith(bn + "/") || url === bn)
+        return url;
+      return url === "/" ? bn : bn + url;
+    }
+
+    return {
       push(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(url, { ...options, replace: false });
+        return ctx.navigate(withBasename(url), { ...options, replace: false });
       },
 
       replace(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(url, { ...options, replace: true });
+        return ctx.navigate(withBasename(url), { ...options, replace: true });
       },
 
       refresh(): Promise<void> {
@@ -46,7 +55,12 @@ export function useRouter(): RouterInstance {
       prefetch(url: string): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
-          prefetchDirect(url, segmentState.currentSegmentIds, ctx.version);
+          prefetchDirect(
+            withBasename(url),
+            segmentState.currentSegmentIds,
+            getAppVersion(),
+            ctx.store?.getRouterId?.(),
+          );
         }
       },
 
@@ -57,7 +71,6 @@ export function useRouter(): RouterInstance {
       forward(): void {
         window.history.forward();
       },
-    }),
-    [],
-  );
+    };
+  }, []);
 }

package/src/browser/rsc-router.tsx

@@ -23,6 +23,7 @@ import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
   splitInterceptSegments,
@@ -139,7 +140,6 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
-  // Load initial payload from SSR-injected __FLIGHT_DATA__
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
@@ -164,6 +164,12 @@ export async function initBrowserApp(
     ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
   });
 
+  // Seed router identity from the initial SSR payload so the first
+  // cross-app SPA navigation can detect the app switch.
+  if (initialPayload.metadata?.routerId) {
+    store.setRouterId?.(initialPayload.metadata.routerId);
+  }
+
   // Create event controller for reactive state management
   const eventController = createEventController({
     initialLocation: new URL(window.location.href),
@@ -205,6 +211,7 @@ export async function initBrowserApp(
   // Initialize the localStorage state key for cache invalidation.
   // Uses the build version so a new deploy automatically busts all cached prefetches.
   initRangoState(version ?? "0");
+  setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.
   // A value of 0 disables the cache; undefined falls back to the module default.
@@ -231,7 +238,6 @@ export async function initBrowserApp(
     deps,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
     onNavigate: (url, options) => {
       if (!navigateFn) {
         window.location.href = url;
@@ -249,7 +255,7 @@ export async function initBrowserApp(
     client,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
+    version: version,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -316,6 +322,7 @@ export async function initBrowserApp(
             segmentIds: [],
             previousUrl: store.getSegmentState().currentUrl,
             interceptSourceUrl: interceptSourceUrl || undefined,
+            routerId: store.getRouterId?.(),
             hmr: true,
             signal: abort.signal,
           });
@@ -329,6 +336,21 @@ export async function initBrowserApp(
             throw new Error("HMR refetch returned invalid payload");
           }
 
+          // Update version BEFORE rebuilding state so that
+          // clearHistoryCache() runs first, then the fresh segment
+          // cache entry we create below survives.
+          const newVersion = payload.metadata.version;
+          if (newVersion && newVersion !== version) {
+            console.log(
+              "[RSCRouter] HMR: version changed",
+              version,
+              "→",
+              newVersion,
+              "clearing caches",
+            );
+            navigationBridge.updateVersion(newVersion);
+          }
+
           if (payload.metadata?.isPartial) {
             const segments = payload.metadata.segments || [];
             const matched = payload.metadata.matched || [];
@@ -478,6 +500,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       initialTheme={initialTheme}
       warmupEnabled={warmupEnabled}
       version={version}
+      basename={initialPayload.metadata?.basename}
     />
   );
 }

package/src/browser/scroll-restoration.ts

@@ -356,19 +356,18 @@ export function handleNavigationEnd(options: {
   scroll?: boolean;
   isStreaming?: () => boolean;
 }): void {
-  if (!initialized) {
-    return;
-  }
-
   const { restore = false, scroll = true, isStreaming } = options;
 
-  // Don't scroll if explicitly disabled
-  if (scroll === false) {
+  // Don't scroll if explicitly disabled or not in a browser
+  if (scroll === false || typeof window === "undefined") {
     return;
   }
 
-  // For back/forward (restore), try to restore saved position
-  if (restore) {
+  // Save/restore requires initialization (sessionStorage, history state).
+  // But basic scroll-to-top and hash scrolling work without it — this
+  // matters during cross-app navigation where ScrollRestoration unmounts
+  // and remounts, creating a brief window where initialized is false.
+  if (restore && initialized) {
     if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
       return;
     }
@@ -378,6 +377,9 @@ export function handleNavigationEnd(options: {
   // Defer hash and scroll-to-top to after React paints the new content,
   // so the user doesn't see the current page jump before the new route appears.
   deferToNextPaint(() => {
+    // Re-check: the deferred callback may fire after environment teardown
+    if (typeof window === "undefined") return;
+
     // Try hash scrolling first
     if (scrollToHash()) {
       return;

package/src/browser/segment-reconciler.ts

@@ -6,6 +6,7 @@ import {
 } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
+import { debugLog } from "./logging.js";
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -85,14 +86,29 @@ 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)) {
+          debugLog(
+            `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
+          );
           return mergeSegmentLoaders(fromServer, fromCache);
         }
 
@@ -143,8 +159,14 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
           // above fails to preserve a value it should have.
           assertSegmentStructure(fromCache, merged, context);
 
+          debugLog(
+            `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
+          );
           return merged;
         }
+        debugLog(
+          `[reconcile] ${segId}: SERVER only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
+        );
         return fromServer;
       }
 
@@ -158,6 +180,10 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         return fromCache;
       }
 
+      debugLog(
+        `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
+      );
+
       // For non-action actors: cached segments the server decided not to re-render.
       // - Preserve loading=false (suppressed boundary) to maintain tree structure
       // - Preserve parallel segment loading so renderSegments can reconstruct

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

@@ -4,8 +4,6 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
-import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
-import { findSourceMapURL } from "../deps/browser.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -31,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") {
@@ -45,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,
@@ -77,7 +74,6 @@ export function createServerActionBridge(
     deps,
     onUpdate,
     renderSegments,
-    version,
     onNavigate,
   } = config;
 
@@ -88,7 +84,7 @@ export function createServerActionBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: getAppVersion,
   });
 
   /**
@@ -167,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 });
@@ -201,14 +203,6 @@ export function createServerActionBridge(
       const onHandleAbort = () => fetchAbort.abort();
       handle.signal.addEventListener("abort", onHandleAbort, { once: true });
 
-      // Dev-only: create debug channel for React Performance Tracks
-      const debugId = (import.meta as any).hot
-        ? crypto.randomUUID()
-        : undefined;
-      const debugChannel = debugId
-        ? createClientDebugChannel(debugId)
-        : undefined;
-
       // Send action request with stream tracking
       const responsePromise = fetch(url, {
         method: "POST",
@@ -216,11 +210,9 @@ 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,
           }),
-          ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
         },
         body: encodedBody,
         signal: fetchAbort.signal,
@@ -283,7 +275,6 @@ export function createServerActionBridge(
       try {
         payload = await deps.createFromFetch<RscPayload>(responsePromise, {
           temporaryReferences,
-          ...(debugChannel && { debugChannel, findSourceMapURL }),
         });
       } catch (error) {
         // Clean up streaming token on error (may be null if fetch failed before .then() ran)
@@ -321,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.