@rangojs/router 0.0.0-experimental.cb54cbba → 0.0.0-experimental.debug-cache-2383ca26

package/src/router/segment-wrappers.ts

@@ -204,6 +204,7 @@ export function createSegmentWrappers<TEnv = any>(
     interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
     return _resolveAllSegmentsWithRevalidation(
       entries,
@@ -221,6 +222,7 @@ export function createSegmentWrappers<TEnv = any>(
       localRouteName,
       pathname,
       segmentDeps,
+      stale,
     );
   }
 

package/src/router.ts

@@ -560,6 +560,7 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
   function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -689,7 +690,7 @@ export function createRouter<TEnv = any>(
         errorBoundary: [],
         notFoundBoundary: [],
         layout: [],
-        parallel: [],
+        parallel: {},
         intercept: [],
         loader: [],
       };
@@ -751,6 +752,7 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -770,6 +772,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -813,6 +816,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,

package/src/segment-system.tsx

@@ -20,6 +20,61 @@ import { RootErrorBoundary } from "./root-error-boundary.js";
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
+function restoreParallelLoaderMarkers(
+  segments: ResolvedSegment[],
+): ResolvedSegment[] {
+  const parallelLoadingByNamespace = new Map<string, ReactNode>();
+  let nextSegments: ResolvedSegment[] | null = null;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+
+    if (segment.type === "parallel") {
+      if (
+        segment.namespace &&
+        segment.loading !== undefined &&
+        segment.loading !== null &&
+        segment.loading !== false
+      ) {
+        parallelLoadingByNamespace.set(segment.namespace, segment.loading);
+      }
+      continue;
+    }
+
+    if (segment.type !== "loader" || segment.parallelLoading !== undefined) {
+      continue;
+    }
+
+    const parallelLoading = segment.namespace
+      ? parallelLoadingByNamespace.get(segment.namespace)
+      : undefined;
+    if (parallelLoading === undefined) {
+      continue;
+    }
+
+    if (!nextSegments) {
+      nextSegments = segments.slice();
+    }
+    nextSegments[i] = { ...segment, parallelLoading };
+  }
+
+  return nextSegments ?? segments;
+}
+
+function hasSameReferences(a: unknown[] | undefined, b: unknown[]): boolean {
+  if (!a || a.length !== b.length) {
+    return false;
+  }
+
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 /**
  * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
  */
@@ -143,6 +198,10 @@ export async function renderSegments(
   } = options || {};
 
   const temporalLazyRefs: Promise<any>[] = [];
+  const normalizedSegments = restoreParallelLoaderMarkers(segments);
+  const normalizedInterceptSegments = interceptSegments
+    ? restoreParallelLoaderMarkers(interceptSegments)
+    : undefined;
 
   /**
    * Registers promises from lazy/async components for awaiting.
@@ -167,7 +226,7 @@ export async function renderSegments(
     );
   }
   // Separate segments by type, passing intercept segments for explicit injection
-  const tree = segmentTreeWalk(segments, interceptSegments);
+  const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
   // Render content segments as siblings
   let content: ReactNode = null;
   for (const node of tree) {
@@ -284,13 +343,90 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton - await loaders and render directly
-      const resolvedData = await loaderDataPromise;
+      // Has loaders but no loading skeleton.
+      // Split: parallel-owned loaders stream (their parallel has loading()),
+      // layout-owned loaders are awaited (they gate the layout content).
+      const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
+      const parallelOwnedLoaders = loaderEntries.filter(
+        (l) => !!l.parallelLoading,
+      );
+
+      // Await only layout-owned loaders
+      const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      const layoutLoaderDataPromise =
+        layoutLoaders.length > 0
+          ? Promise.all(
+              layoutLoaders.map((l) =>
+                l.loaderData instanceof Promise
+                  ? l.loaderData
+                  : Promise.resolve(l.loaderData),
+              ),
+            )
+          : Promise.resolve([]);
+      const resolvedData = await layoutLoaderDataPromise;
       const { loaderData, errorFallback } = resolveLoaderData(
         resolvedData,
-        loaderIds,
+        layoutLoaderIds,
       );
 
+      // Parallel-owned loaders: attach to their owning parallel segment
+      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
+      if (parallelOwnedLoaders.length > 0) {
+        const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
+
+        for (const loader of parallelOwnedLoaders) {
+          if (!loader.namespace) {
+            continue;
+          }
+          const existing = loadersByParallelNamespace.get(loader.namespace);
+          if (existing) {
+            existing.push(loader);
+          } else {
+            loadersByParallelNamespace.set(loader.namespace, [loader]);
+          }
+        }
+
+        for (const p of node.parallel) {
+          if (!p.loading || !p.namespace) {
+            continue;
+          }
+
+          const ownedLoaders = loadersByParallelNamespace.get(p.namespace);
+          if (!ownedLoaders || ownedLoaders.length === 0) {
+            continue;
+          }
+
+          const parallelLoaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const parallelLoaderSources = ownedLoaders.map((l) => l.loaderData);
+          p.loaderIds = parallelLoaderIds;
+
+          const shouldReuseParallelPromise =
+            p.loaderDataPromise !== undefined &&
+            hasSameReferences(p.parallelLoaderSources, parallelLoaderSources);
+
+          const parallelLoaderDataPromise = shouldReuseParallelPromise
+            ? p.loaderDataPromise
+            : forceAwait || isAction
+              ? await Promise.all(
+                  ownedLoaders.map((l) =>
+                    l.loaderData instanceof Promise
+                      ? l.loaderData
+                      : Promise.resolve(l.loaderData),
+                  ),
+                )
+              : Promise.all(
+                  ownedLoaders.map((l) =>
+                    l.loaderData instanceof Promise
+                      ? l.loaderData
+                      : Promise.resolve(l.loaderData),
+                  ),
+                );
+
+          p.loaderDataPromise = parallelLoaderDataPromise;
+          p.parallelLoaderSources = parallelLoaderSources;
+        }
+      }
+
       content = createElement(OutletProvider, {
         key,
         content: outletContent,

package/src/server/context.ts

@@ -157,10 +157,24 @@ export type InterceptEntry = {
   when: InterceptWhenFn[]; // Selector conditions - all must return true to intercept
 };
 
+export interface ParallelEntryData
+  extends EntryPropCommon, EntryPropDatas, EntryPropSegments {
+  type: "parallel";
+  handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
+  loading?: ReactNode | false;
+  transition?: TransitionConfig;
+  /** Set when any parallel slot is a Static definition */
+  isStaticPrerender?: true;
+  /** Per-slot static handler $$ids for build-time store lookup */
+  staticHandlerIds?: Record<string, string>;
+}
+
+export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
+
 export type EntryPropSegments = {
   loader: LoaderEntry[];
   layout: EntryData[];
-  parallel: EntryData[]; // type: "parallel" entries with their own loaders/revalidate/loading
+  parallel: ParallelEntries; // slot -> parallel entry (same entry may back multiple slots)
   intercept: InterceptEntry[]; // intercept definitions for soft navigation
 };
 
@@ -200,18 +214,7 @@ export type EntryData =
     } & EntryPropCommon &
       EntryPropDatas &
       EntryPropSegments)
-  | ({
-      type: "parallel";
-      handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
-      /** Set when any parallel slot is a Static definition */
-      isStaticPrerender?: true;
-      /** Per-slot static handler $$ids for build-time store lookup */
-      staticHandlerIds?: Record<string, string>;
-    } & EntryPropCommon &
-      EntryPropDatas &
-      EntryPropSegments)
+  | ParallelEntryData
   | ({
       type: "cache";
       /** Cache entries create cache boundaries and render like layouts (with Outlet) */
@@ -553,6 +556,80 @@ export function getRootScoped(): boolean {
 // Export HelperContext type for use in other modules
 export type { HelperContext };
 
+/**
+ * Return an isolated copy of a lazy include's captured parent entry.
+ *
+ * DSL helpers (loader(), middleware(), etc.) mutate ctx.parent in place.
+ * Multiple include() scopes capture the *same* syntheticMapRoot as their
+ * parent, so without isolation one include's loaders/middleware leak into
+ * every other route that shares that root.
+ *
+ * The clone is shallow: only the mutable arrays are copied so each
+ * include pushes to its own list. The rest of the entry (id, shortCode,
+ * parent pointer, handler) stays shared, which is correct and cheap.
+ */
+export function getIsolatedLazyParent(
+  captured: EntryData | null | undefined,
+): EntryData | null {
+  if (!captured) return null;
+  return {
+    ...captured,
+    loader: [...captured.loader],
+    middleware: [...captured.middleware],
+    revalidate: [...captured.revalidate],
+    errorBoundary: [...captured.errorBoundary],
+    notFoundBoundary: [...captured.notFoundBoundary],
+    layout: [...captured.layout],
+    parallel: { ...captured.parallel },
+    intercept: [...captured.intercept],
+  };
+}
+
+export function getParallelEntries(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): ParallelEntryData[] {
+  if (!parallels) return [];
+  if (Array.isArray(parallels)) {
+    return parallels.filter(
+      (entry): entry is ParallelEntryData => entry.type === "parallel",
+    );
+  }
+  return Object.values(parallels).filter(
+    (entry): entry is ParallelEntryData => !!entry,
+  );
+}
+
+export function getParallelSlotEntries(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): Array<{ slot: `@${string}`; entry: ParallelEntryData }> {
+  if (!parallels) return [];
+
+  if (Array.isArray(parallels)) {
+    return getParallelEntries(parallels).flatMap((entry) =>
+      (Object.keys(entry.handler) as `@${string}`[]).map((slot) => ({
+        slot,
+        entry,
+      })),
+    );
+  }
+
+  return Object.entries(parallels)
+    .filter(([, entry]) => !!entry)
+    .map(([slot, entry]) => ({
+      slot: slot as `@${string}`,
+      entry: entry!,
+    }));
+}
+
+export function getParallelSlotCount(
+  parallels: ParallelEntries | EntryData[] | undefined,
+): number {
+  if (!parallels) return 0;
+  return Array.isArray(parallels)
+    ? parallels.filter((entry) => entry?.type === "parallel").length
+    : Object.keys(parallels).length;
+}
+
 // ============================================================================
 //  Performance Metrics Helpers
 // ============================================================================

package/src/server/request-context.ts

@@ -30,7 +30,10 @@ import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
-import { createReverseFunction } from "../router/handler-context.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
 import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
 import { invariant } from "../errors.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
@@ -58,7 +61,7 @@ export interface RequestContext<
   originalUrl: URL;
   /** URL pathname */
   pathname: string;
-  /** URL search params (system params like _rsc* are NOT filtered here) */
+  /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
   searchParams: URLSearchParams;
   /** Variables set by middleware (same as ctx.var) */
   var: Record<string, any>;
@@ -555,14 +558,17 @@ export function createRequestContext<TEnv>(
     invalidateResponseCookieCache();
   };
 
+  // Strip internal _rsc* params so userland sees a clean URL.
+  const cleanUrl = stripInternalParams(url);
+
   // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
-    url,
+    url: cleanUrl,
     originalUrl: new URL(request.url),
     pathname: url.pathname,
-    searchParams: url.searchParams,
+    searchParams: cleanUrl.searchParams,
     var: variables,
     get: ((keyOrVar: any) =>
       contextGet(variables, keyOrVar)) as RequestContext<TEnv>["get"],

package/src/ssr/index.tsx

@@ -168,6 +168,7 @@ function createSsrEventController(opts: {
   const state: DerivedNavigationState = {
     state: "idle",
     isStreaming: false,
+    isNavigating: false,
     location,
     pendingUrl: null,
     inflightActions: [],

package/src/types/handler-context.ts

@@ -289,8 +289,12 @@ export type HandlerContext<
   /**
    * Access loader data or push handle data.
    *
+   * Available in route handlers, layout handlers, middleware, server actions,
+   * and server components rendered within the request context.
+   *
    * For loaders: Returns a promise that resolves to the loader data.
-   * Loaders are executed in parallel and memoized per request.
+   * Loaders are executed in parallel and memoized per request — calling
+   * `ctx.use(SameLoader)` multiple times returns the same promise.
    *
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
@@ -519,30 +523,112 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * })
  * ```
  */
+/**
+ * Revalidation function called during client-side navigation to decide whether
+ * a segment (layout, route, parallel slot, or loader) should be re-rendered.
+ *
+ * Return `true` to re-render, `false` to skip (keep client's current version),
+ * or `{ defaultShouldRevalidate: boolean }` to override the default for
+ * downstream segments.
+ *
+ * @example
+ * ```ts
+ * // Re-render only when a cart action happened or browser signals staleness
+ * revalidate(({ actionId, stale }) =>
+ *   actionId?.includes("cart") || stale || false
+ * )
+ *
+ * // Always re-render when params change (default behavior made explicit)
+ * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)
+ * ```
+ */
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
+  /** Route params from the page being navigated away from. */
   currentParams: TParams;
+  /** Full URL of the page being navigated away from. */
   currentUrl: URL;
+  /** Route params for the navigation target. */
   nextParams: TParams;
+  /** Full URL of the navigation target. */
   nextUrl: URL;
+  /**
+   * The router's default revalidation decision for this segment.
+   * `true` when params changed or the segment is new to the client.
+   * Return this when you want default behavior plus your own conditions.
+   */
   defaultShouldRevalidate: boolean;
+  /** Full handler context — access to `ctx.use()`, `ctx.env`, `ctx.params`, etc. */
   context: HandlerContext<TParams, TEnv>;
-  // Segment metadata (which segment is being evaluated):
+
+  // ── Segment metadata (which segment is being evaluated) ──────────────
+
+  /** The type of segment being revalidated. */
   segmentType: "layout" | "route" | "parallel";
-  layoutName?: string; // Layout name (e.g., "root", "shop", "auth") - only for layouts
-  slotName?: string; // Slot name (e.g., "@sidebar", "@modal") - only for parallels
-  // Action context (populated when revalidation triggered by server action):
-  actionId?: string; // Action identifier (e.g., "src/actions.ts#addToCart")
-  actionUrl?: URL; // URL where action was executed
-  actionResult?: any; // Return value from action execution
-  formData?: FormData; // FormData from action request
-  method?: string; // Request method: 'GET' for navigation, 'POST' for actions
-  routeName?: DefaultRouteName; // Route name of the navigation target (alias for toRouteName)
-  // Named-route identity for both ends of a navigation transition.
-  // Undefined for unnamed internal routes (those without a `name` option).
-  fromRouteName?: DefaultRouteName; // Route name being navigated away from
-  toRouteName?: DefaultRouteName; // Route name being navigated to
-  // Stale cache revalidation (SWR pattern):
-  stale?: boolean; // True if this is a stale cache revalidation request
+  /** Layout name (e.g., `"root"`, `"shop"`, `"auth"`). Only set for layout segments. */
+  layoutName?: string;
+  /** Slot name (e.g., `"@sidebar"`, `"@modal"`). Only set for parallel segments. */
+  slotName?: string;
+
+  // ── Action context (populated when revalidation is triggered by a server action) ──
+
+  /**
+   * Identifier of the server action that triggered revalidation.
+   * `undefined` during normal navigation (no action involved).
+   *
+   * Format: `"src/<path>#<exportName>"` — the file path is the source path
+   * relative to the project root, followed by `#` and the exported function name.
+   *
+   * This is stable and can be used for path-based matching to revalidate
+   * when any action in a module or directory fires:
+   *
+   * @example
+   * ```ts
+   * // Match a specific action
+   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart")
+   *
+   * // Match any action in the cart module
+   * revalidate(({ actionId }) => actionId?.includes("cart") ?? false)
+   *
+   * // Match any action under src/apps/store/actions/
+   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") ?? false)
+   * ```
+   */
+  actionId?: string;
+  /** URL where the action was executed (the page the user was on when they triggered the action). */
+  actionUrl?: URL;
+  /** Return value from the action execution. Can be used to conditionally revalidate based on the action's outcome. */
+  actionResult?: any;
+  /** FormData from the action request body. Only set for form-based actions (not inline `"use server"` actions). */
+  formData?: FormData;
+  /** HTTP method: `"GET"` for navigation, `"POST"` for server actions. */
+  method?: string;
+
+  // ── Route identity ───────────────────────────────────────────────────
+
+  /** Route name of the navigation target. Alias for `toRouteName`. */
+  routeName?: DefaultRouteName;
+  /**
+   * Route name being navigated away from.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  fromRouteName?: DefaultRouteName;
+  /**
+   * Route name being navigated to.
+   * `undefined` for unnamed internal routes (those without a `name` option).
+   */
+  toRouteName?: DefaultRouteName;
+
+  // ── Staleness signal ─────────────────────────────────────────────────
+
+  /**
+   * `true` when the browser signals that data may be stale — typically because
+   * a server action was executed in this or another tab (`_rsc_stale` header).
+   *
+   * This is NOT segment cache staleness (loaders are never segment-cached).
+   * Use this to decide whether loader data should be re-fetched after an
+   * action that may have mutated backend state.
+   */
+  stale?: boolean;
 }) => boolean | { defaultShouldRevalidate: boolean };
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported

package/src/types/route-entry.ts

@@ -55,6 +55,13 @@ export interface RouteEntry<TEnv = any> {
     | Promise<() => Array<AllUseItems>>;
   mountIndex: number;
 
+  /**
+   * Router ID that owns this entry. Used to namespace the manifest cache
+   * so multi-router setups (host routing) don't share cached EntryData
+   * across routers with overlapping mountIndex + routeKey combinations.
+   */
+  routerId?: string;
+
   /**
    * Route keys in this entry that have pre-render handlers.
    * Used by the non-trie match path to set the `pr` flag.

package/src/types/segments.ts

@@ -51,9 +51,11 @@ export interface ResolvedSegment {
   // Loader-specific fields
   loaderId?: string; // For loaders: the loader $$id identifier
   loaderData?: any; // For loaders: the resolved data from loader execution
+  parallelLoading?: ReactNode; // For parallel-owned loaders: the parallel's loading fallback
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
+  parallelLoaderSources?: any[]; // Internal: preserves stable aggregate promise across renders
   // Error-specific fields
   error?: ErrorInfo; // For error segments: the error information
   // NotFound-specific fields

package/src/urls/path-helper.ts

@@ -199,7 +199,7 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       errorBoundary: [],
       notFoundBoundary: [],
       layout: [],
-      parallel: [],
+      parallel: {},
       intercept: [],
       loader: [],
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),

package/src/vite/discovery/state.ts

@@ -13,8 +13,6 @@ export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 export interface PluginOptions {
   enableBuildPrerender?: boolean;
   staticRouteTypesGeneration?: boolean;
-  include?: string[];
-  exclude?: string[];
   // Mutable ref for deferred auto-discovery (node preset).
   // The auto-discover config() hook populates this before configResolved.
   routerPathRef?: { path?: string };