@rangojs/router 0.0.0-experimental.ae6e7825 → 0.0.0-experimental.bf2846be

package/src/browser/navigation-client.ts

@@ -12,8 +12,6 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
-import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
-import { findSourceMapURL } from "../deps/browser.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -63,6 +61,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -90,6 +89,9 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
+      if (routerId) {
+        fetchUrl.searchParams.set("_rsc_rid", routerId);
+      }
 
       // Check completed in-memory prefetch cache before making a network request.
       // The cache key includes the source URL (previousUrl) because the
@@ -99,35 +101,88 @@ export function createNavigationClient(
       //
       const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
       const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
-      const inflightResponsePromise = canUsePrefetch
-        ? consumeInflightPrefetch(cacheKey)
-        : null;
+      // Wildcard key matches prefetch entries stored with a custom prefetchKey
+      // (Link's prefetchKey prop stores under "*" instead of the source URL).
+      const wildcardKey = "*\0" + fetchUrl.pathname + fetchUrl.search;
+
+      let cachedResponse: Response | null = null;
+      let hitKey: string | null = null;
+      if (canUsePrefetch) {
+        cachedResponse = consumePrefetch(cacheKey);
+        if (cachedResponse) {
+          hitKey = cacheKey;
+        } else {
+          cachedResponse = consumePrefetch(wildcardKey);
+          if (cachedResponse) hitKey = wildcardKey;
+        }
+      }
+
+      let inflightResponsePromise: Promise<Response | null> | null = null;
+      if (canUsePrefetch && !cachedResponse) {
+        inflightResponsePromise = consumeInflightPrefetch(cacheKey);
+        if (inflightResponsePromise) {
+          hitKey = cacheKey;
+        } else {
+          inflightResponsePromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightResponsePromise) hitKey = wildcardKey;
+        }
+      }
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
         resolveStreamComplete = resolve;
       });
 
-      // Dev-only: debug channel is created lazily only for fresh fetches.
-      // Cached/inflight responses don't have a server-side channel, so passing
-      // debugChannel to createFromFetch would hang waiting for data that never comes.
-      let debugChannel: {
-        readable: ReadableStream<Uint8Array>;
-        writable: WritableStream<Uint8Array>;
-      } | null = null;
+      /**
+       * Validate RSC control headers on any response (fresh, cached, or
+       * in-flight). Handles version-mismatch reloads and server redirects.
+       * Returns the response unchanged when no control header is present.
+       */
+      const validateRscHeaders = (
+        response: Response,
+        source: string,
+      ): Response | Promise<Response> => {
+        // Version mismatch — server wants a full page reload
+        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+        if (reload === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
+        }
+        if (reload) {
+          if (tx) {
+            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+              reloadUrl: reload.url,
+            });
+          }
+          window.location.href = reload.url;
+          // Block further processing — page is reloading
+          return new Promise<Response>(() => {});
+        }
 
-      /** Start a fresh navigation fetch (no cache / inflight hit). */
-      const doFreshFetch = (): Promise<Response> => {
-        // Dev-only: create debug channel for React Performance Tracks
-        const debugId = (import.meta as any).hot
-          ? crypto.randomUUID()
-          : undefined;
-        if (debugId) {
-          debugChannel = createClientDebugChannel(debugId);
-          console.log("[perf-tracks] client: fresh fetch, debugId =", debugId);
+        // Server-side redirect without state: the server returned 204 with
+        // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
+        // to a URL rendering full HTML). Throw ServerRedirect so the
+        // navigation bridge catches it and re-navigates with _skipCache.
+        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+        if (redirect === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
         }
+        if (redirect) {
+          if (tx) {
+            browserDebugLog(tx, `server redirect (${source})`, {
+              redirectUrl: redirect.url,
+            });
+          }
+          resolveStreamComplete();
+          throw new ServerRedirect(redirect.url, undefined);
+        }
+
+        return response;
+      };
 
+      /** Start a fresh navigation fetch (no cache / inflight hit). */
+      const doFreshFetch = (): Promise<Response> => {
         if (tx) {
           browserDebugLog(tx, "fetching", {
             path: `${fetchUrl.pathname}${fetchUrl.search}`,
@@ -143,47 +198,14 @@ export function createNavigationClient(
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,
             }),
             ...(hmr && { "X-RSC-HMR": "1" }),
-            ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
           },
           signal,
         }).then((response) => {
-          // Check for version mismatch - server wants us to reload
-          const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-          if (reload === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (reload) {
-            if (tx) {
-              browserDebugLog(tx, "version mismatch, reloading", {
-                reloadUrl: reload.url,
-              });
-            }
-            window.location.href = reload.url;
-            return new Promise<Response>(() => {});
-          }
-
-          // Server-side redirect without state: the server returned 204 with
-          // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
-          // to a URL rendering full HTML). Throw ServerRedirect so the
-          // navigation bridge catches it and re-navigates with _skipCache.
-          const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-          if (redirect === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (redirect) {
-            if (tx) {
-              browserDebugLog(tx, "server redirect", {
-                redirectUrl: redirect.url,
-              });
-            }
-            resolveStreamComplete();
-            throw new ServerRedirect(redirect.url, undefined);
-          }
+          const validated = validateRscHeaders(response, "fetch");
+          if (validated instanceof Promise) return validated;
 
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) browserDebugLog(tx, "stream complete");
               resolveStreamComplete();
@@ -197,13 +219,17 @@ export function createNavigationClient(
 
       if (cachedResponse) {
         if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+          browserDebugLog(tx, "prefetch cache hit", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
-        // Cached response body is already fully buffered (arrayBuffer),
-        // so stream completion is immediate.
         responsePromise = Promise.resolve(cachedResponse).then((response) => {
+          const validated = validateRscHeaders(response, "prefetch cache");
+          if (validated instanceof Promise) return validated;
+
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) browserDebugLog(tx, "stream complete (from cache)");
               resolveStreamComplete();
@@ -213,7 +239,10 @@ export function createNavigationClient(
         });
       } else if (inflightResponsePromise) {
         if (tx) {
-          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+          browserDebugLog(tx, "reusing inflight prefetch", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
         responsePromise = inflightResponsePromise.then(async (response) => {
           if (!response) {
@@ -223,8 +252,11 @@ export function createNavigationClient(
             return doFreshFetch();
           }
 
+          const validated = validateRscHeaders(response, "inflight prefetch");
+          if (validated instanceof Promise) return validated;
+
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) {
                 browserDebugLog(tx, "stream complete (from inflight prefetch)");
@@ -239,11 +271,8 @@ export function createNavigationClient(
       }
 
       try {
-        // Deserialize RSC payload
-        const payload = await deps.createFromFetch<RscPayload>(
-          responsePromise,
-          debugChannel ? { debugChannel, findSourceMapURL } : undefined,
-        );
+        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,

package/src/browser/navigation-store.ts

@@ -28,9 +28,15 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
 // Maximum number of history entries to cache (URLs visited)
 const HISTORY_CACHE_SIZE = 20;
 
-// Cache entry: [url-key, segments, stale, handleData?]
+// Cache entry: [url-key, segments, stale, handleData?, routerId?]
 // stale=true means the data may be outdated and should be revalidated on access
-type HistoryCacheEntry = [string, ResolvedSegment[], boolean, HandleData?];
+type HistoryCacheEntry = [
+  string,
+  ResolvedSegment[],
+  boolean,
+  HandleData?,
+  string?,
+];
 
 /**
  * Shallow clone handleData to avoid reference sharing between cache entries.
@@ -258,6 +264,11 @@ export function createNavigationStore(
   // Used to maintain intercept context during action revalidation
   let interceptSourceUrl: string | null = null;
 
+  // Router identity - tracks which router is currently active.
+  // When this changes on a partial response, the client forces a full
+  // tree replacement instead of reconciling with stale segments.
+  let currentRouterId: string | undefined;
+
   // Action state tracking (for useAction hook)
   // Maps action function ID to its tracked state
   const actionStates = new Map<string, TrackedActionState>();
@@ -571,10 +582,17 @@ export function createNavigationStore(
           segments,
           false,
           clonedHandleData,
+          currentRouterId,
         ];
       } else {
         // Add new entry at the end (not stale)
-        historyCache.push([historyKey, segments, false, clonedHandleData]);
+        historyCache.push([
+          historyKey,
+          segments,
+          false,
+          clonedHandleData,
+          currentRouterId,
+        ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
           historyCache.shift();
@@ -586,14 +604,22 @@ export function createNavigationStore(
      * Get cached segments for a history entry
      * Returns { segments, stale, handleData } or undefined if not cached
      */
-    getCachedSegments(
-      historyKey: string,
-    ):
-      | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+    getCachedSegments(historyKey: string):
+      | {
+          segments: ResolvedSegment[];
+          stale: boolean;
+          handleData?: HandleData;
+          routerId?: string;
+        }
       | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
       if (!entry) return undefined;
-      return { segments: entry[1], stale: entry[2], handleData: entry[3] };
+      return {
+        segments: entry[1],
+        stale: entry[2],
+        handleData: entry[3],
+        routerId: entry[4],
+      };
     },
 
     /**
@@ -621,6 +647,7 @@ export function createNavigationStore(
           entry[1],
           entry[2],
           clonedHandleData,
+          entry[4], // preserve routerId
         ];
       }
     },
@@ -687,6 +714,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================

package/src/browser/partial-update.ts

@@ -39,8 +39,8 @@ export interface PartialUpdateConfig {
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
-  /** RSC version received from server (from initial payload metadata) */
-  version?: string;
+  /** RSC version getter — returns the current version (may change after HMR) */
+  getVersion?: () => string | undefined;
 }
 
 /**
@@ -104,7 +104,13 @@ export type PartialUpdater = (
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
-  const { store, client, onUpdate, renderSegments, version } = config;
+  const {
+    store,
+    client,
+    onUpdate,
+    renderSegments,
+    getVersion = () => undefined,
+  } = config;
 
   /**
    * Get current page's cached segments as an array
@@ -182,6 +188,11 @@ export function createPartialUpdater(
       targetCache && targetCache.length > 0
         ? targetCache
         : getCurrentCachedSegments();
+    const cachedSegsSource =
+      targetCache && targetCache.length > 0 ? "history-cache" : "current-page";
+    debugLog(
+      `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+    );
 
     // Fetch partial payload (no abort signal - RSC doesn't support it well)
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
@@ -193,7 +204,8 @@ export function createPartialUpdater(
       // (action redirect sends empty segments for a fresh render).
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
-      version,
+      version: getVersion(),
+      routerId: store.getRouterId?.(),
     });
     // Mark navigation as streaming (response received, now parsing RSC).
     // Called after fetchPartial so pendingUrl stays set during the network wait,
@@ -206,6 +218,21 @@ export function createPartialUpdater(
       streamingToken.end();
     });
 
+    // Detect app switch: if routerId changed, the navigation crossed into
+    // a different router (e.g., via host router path mount). Downgrade
+    // partial to full so the entire tree is replaced without reconciliation
+    // against stale segments from the previous app.
+    if (payload.metadata?.routerId) {
+      const prevRouterId = store.getRouterId?.();
+      if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
+        debugLog(
+          `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
+        );
+        payload.metadata.isPartial = false;
+      }
+      store.setRouterId?.(payload.metadata.routerId);
+    }
+
     // Handle server-side redirect with state
     if (payload.metadata?.redirect) {
       if (signal?.aborted) {
@@ -259,7 +286,7 @@ export function createPartialUpdater(
             existingSegments,
           );
 
-          // Fix: tx.commit() cached the source page's handleData because
+          // tx.commit() cached the source page's handleData because
           // eventController hasn't been updated yet. Overwrite with the
           // correct cached handleData to prevent cache corruption on
           // subsequent navigations to this same URL.

package/src/browser/prefetch/cache.ts

@@ -61,13 +61,23 @@ const inflightPromises = new Map<string, Promise<Response | null>>();
 let generation = 0;
 
 /**
- * Build a source-dependent cache key.
- * Includes the source page href so the same target prefetched from
- * different pages gets separate entries — the server response varies
- * based on the source page context (diff-based rendering).
+ * Build a cache key for prefetched responses.
+ *
+ * By default the key includes the source page href so the same target
+ * prefetched from different pages gets separate entries (the server's
+ * diff response depends on the source page context).
+ *
+ * When `prefetchKey` is provided, the source portion is replaced with
+ * a `*` sentinel so all custom-keyed entries share one cache slot per
+ * target — enabling source-agnostic cache reuse.
  */
-export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
-  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+export function buildPrefetchKey(
+  sourceHref: string,
+  targetUrl: URL,
+  prefetchKey?: string | ((from: string) => string),
+): string {
+  const source = prefetchKey != null ? "*" : sourceHref;
+  return source + "\0" + targetUrl.pathname + targetUrl.search;
 }
 
 /**

package/src/browser/prefetch/fetch.ts

@@ -23,6 +23,7 @@ import {
 import { getRangoState } from "../rango-state.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
+import { debugLog } from "../logging.js";
 
 /**
  * Build an RSC partial URL for prefetching.
@@ -34,6 +35,7 @@ function buildPrefetchUrl(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): URL | null {
   let targetUrl: URL;
   try {
@@ -51,6 +53,9 @@ function buildPrefetchUrl(
   if (version) {
     targetUrl.searchParams.set("_rsc_v", version);
   }
+  if (routerId) {
+    targetUrl.searchParams.set("_rsc_rid", routerId);
+  }
   return targetUrl;
 }
 
@@ -108,13 +113,28 @@ export function prefetchDirect(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
+  prefetchKey?: string | ((from: string) => string),
 ): void {
   if (!shouldPrefetch()) return;
 
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
-  const key = buildPrefetchKey(window.location.href, targetUrl);
-  if (hasPrefetch(key)) return;
+  const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
+  if (hasPrefetch(key)) {
+    debugLog("[prefetch] direct dedup (key already exists)", {
+      url,
+      key,
+      prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+    });
+    return;
+  }
+  debugLog("[prefetch] direct fetch", {
+    url,
+    key,
+    source: window.location.href,
+    prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+  });
   executePrefetchFetch(key, targetUrl.toString());
 }
 
@@ -127,12 +147,21 @@ export function prefetchQueued(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
+  prefetchKey?: string | ((from: string) => string),
 ): string {
   if (!shouldPrefetch()) return "";
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
-  const key = buildPrefetchKey(window.location.href, targetUrl);
-  if (hasPrefetch(key)) return key;
+  const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
+  if (hasPrefetch(key)) {
+    debugLog("[prefetch] queued dedup (key already exists)", {
+      url,
+      key,
+      prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+    });
+    return key;
+  }
   const fetchUrlStr = targetUrl.toString();
   enqueuePrefetch(key, (signal) => {
     // Re-check at execution time: a hover-triggered prefetchDirect may

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>
   );
 });