@rangojs/router 0.0.0-experimental.60 → 0.0.0-experimental.60c5dbde

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,24 @@ import {
 import { getRangoState } from "../rango-state.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
+import { debugLog } from "../logging.js";
+
+/**
+ * Check if a URL resolves to the current page (same pathname + search).
+ * Used to prevent same-page prefetching with prefetchKey, which would
+ * produce a trivial diff that corrupts the wildcard cache.
+ */
+function isSamePage(url: string): boolean {
+  try {
+    const target = new URL(url, window.location.origin);
+    return (
+      target.pathname + target.search ===
+      window.location.pathname + window.location.search
+    );
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Build an RSC partial URL for prefetching.
@@ -113,13 +131,32 @@ export function prefetchDirect(
   segmentIds: string[],
   version?: string,
   routerId?: string,
+  prefetchKey?: string | ((from: string) => string),
 ): void {
   if (!shouldPrefetch()) return;
 
   const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
-  const key = buildPrefetchKey(window.location.href, targetUrl);
-  if (hasPrefetch(key)) return;
+  // Skip same-page prefetch with prefetchKey — a same-page diff is trivial
+  // and would corrupt the wildcard cache entry for cross-page navigation.
+  if (prefetchKey != null && isSamePage(url)) {
+    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());
 }
 
@@ -133,17 +170,36 @@ export function prefetchQueued(
   segmentIds: string[],
   version?: string,
   routerId?: string,
+  prefetchKey?: string | ((from: string) => string),
 ): string {
   if (!shouldPrefetch()) return "";
   const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
-  const key = buildPrefetchKey(window.location.href, targetUrl);
-  if (hasPrefetch(key)) return key;
+  // Skip same-page prefetch with prefetchKey — a same-page diff is trivial
+  // and would corrupt the wildcard cache entry for cross-page navigation.
+  if (prefetchKey != null && isSamePage(url)) {
+    return "";
+  }
+  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
     // have started or completed this key while the item sat in the queue.
     if (hasPrefetch(key)) return Promise.resolve();
+    // By execution time, the user may have navigated to the target page.
+    // A same-page prefetch produces a trivial diff that would overwrite
+    // the useful cross-page entry in the wildcard cache.
+    if (prefetchKey != null && isSamePage(url)) {
+      return Promise.resolve();
+    }
     return executePrefetchFetch(key, fetchUrlStr, signal).then(() => {});
   });
   return key;

package/src/browser/react/Link.tsx

@@ -97,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.
@@ -184,6 +204,7 @@ export const Link: ForwardRefExoticComponent<
     reloadDocument = false,
     revalidate,
     prefetch = "none",
+    prefetchKey,
     state,
     children,
     onClick,
@@ -320,9 +341,10 @@ export const Link: ForwardRefExoticComponent<
         segmentState.currentSegmentIds,
         getAppVersion(),
         ctx.store.getRouterId?.(),
+        prefetchKey,
       );
     }
-  }, [resolvedStrategy, resolvedTo, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
@@ -344,6 +366,7 @@ export const Link: ForwardRefExoticComponent<
         segmentState.currentSegmentIds,
         getAppVersion(),
         ctx.store.getRouterId?.(),
+        prefetchKey,
       );
     };
 
@@ -383,7 +406,7 @@ export const Link: ForwardRefExoticComponent<
         unobserveForPrefetch(observedElement);
       }
     };
-  }, [resolvedStrategy, resolvedTo, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a

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/segment-reconciler.ts

@@ -6,6 +6,45 @@ 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 (in-diff server segments, loading-strip spread,
+ * mergeSegmentLoaders) 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.
+ *
+ * Only overwrites fields that aren't already set on `merged` — preserves
+ * server-provided loaderDataPromise (parallel intercept segments) while still
+ * restoring the layout/route memoization that only renderSegments sets.
+ */
+function preserveMemoization(
+  merged: ResolvedSegment,
+  cached: ResolvedSegment,
+): ResolvedSegment {
+  if (
+    cached.contentPromise === undefined &&
+    cached.contentSource === undefined &&
+    cached.layoutLoaderSources === undefined &&
+    cached.parallelLoaderSources === undefined &&
+    cached.loaderDataPromise === undefined
+  ) {
+    return merged;
+  }
+  return {
+    ...merged,
+    contentPromise: merged.contentPromise ?? cached.contentPromise,
+    contentSource: merged.contentSource ?? cached.contentSource,
+    layoutLoaderSources:
+      merged.layoutLoaderSources ?? cached.layoutLoaderSources,
+    parallelLoaderSources:
+      merged.parallelLoaderSources ?? cached.parallelLoaderSources,
+    loaderDataPromise: merged.loaderDataPromise ?? cached.loaderDataPromise,
+  };
+}
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -85,15 +124,36 @@ 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"})`,
+          );
+          // mergeSegmentLoaders spreads fromCache, so most memoization survives
+          // naturally; preserveMemoization fills any gaps and is a no-op when
+          // everything is already carried over.
+          return preserveMemoization(
+            mergeSegmentLoaders(fromServer, fromCache),
+            fromCache,
+          );
         }
 
         // Preserve cached structural properties to maintain consistent React tree.
@@ -143,8 +203,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,6 +224,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/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);
         }
       }
@@ -350,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/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/scan-filter.ts

@@ -61,7 +61,14 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (
+        entry.name === "node_modules" ||
+        entry.name.startsWith(".") ||
+        entry.name === "dist" ||
+        entry.name === "build" ||
+        entry.name === "coverage"
+      )
+        continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if (
       (entry.name.endsWith(".ts") ||