@rangojs/router 0.0.0-experimental.88a3b2f7 → 0.0.0-experimental.8bd1b239

package/src/segment-system.tsx

@@ -2,11 +2,7 @@ import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import type {
-  ResolvedSegment,
-  LoaderDataResult,
-  RootLayoutProps,
-} from "./types.js";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { isLoaderDataResult } from "./types.js";
 import { invariant } from "./errors.js";
 import {
@@ -14,6 +10,8 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
@@ -61,20 +59,6 @@ function restoreParallelLoaderMarkers(
   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
  */
@@ -278,10 +262,7 @@ export async function renderSegments(
       loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
-            content:
-              resolvedComponent instanceof Promise
-                ? resolvedComponent
-                : Promise.resolve(resolvedComponent),
+            content: getMemoizedContentPromise(resolvedComponent),
             fallback: loading,
             segmentId: id,
           })
@@ -305,16 +286,7 @@ export async function renderSegments(
 
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise =
-      loaderEntries.length > 0
-        ? Promise.all(
-            loaderEntries.map((loader) =>
-              loader.loaderData instanceof Promise
-                ? loader.loaderData
-                : Promise.resolve(loader.loaderData),
-            ),
-          )
-        : Promise.resolve([]);
+    const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
 
     // Use LoaderBoundary when loading is defined to maintain consistent tree structure
     // This ensures cached segments (which may not have loader segments) have the same
@@ -396,34 +368,12 @@ export async function renderSegments(
             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;
+          p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const aggregated = getMemoizedLoaderPromise(ownedLoaders);
+          p.loaderDataPromise =
+            (forceAwait || isAction) && aggregated instanceof Promise
+              ? await aggregated
+              : aggregated;
         }
       }
 

package/src/server/handle-store.ts

@@ -13,6 +13,25 @@
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
+/**
+ * Build a HandleData snapshot from a HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
+ */
+export function buildHandleSnapshot(
+  handleStore: HandleStore,
+  segmentOrder: string[],
+): HandleData {
+  const data: HandleData = {};
+  for (const segmentId of segmentOrder) {
+    const segData = handleStore.getDataForSegment(segmentId);
+    for (const handleName in segData) {
+      if (!data[handleName]) data[handleName] = {};
+      data[handleName][segmentId] = segData[handleName];
+    }
+  }
+  return data;
+}
+
 function createLateHandlePushError(
   handleName: string,
   segmentId: string,

package/src/server/request-context.ts

@@ -26,7 +26,12 @@ import {
   contextSet,
   isNonCacheable,
 } from "../context-var.js";
-import { createHandleStore, type HandleStore } from "./handle-store.js";
+import {
+  createHandleStore,
+  buildHandleSnapshot,
+  type HandleStore,
+  type HandleData,
+} from "./handle-store.js";
 import { isHandle } from "../handle.js";
 import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
@@ -306,6 +311,19 @@ export interface RequestContext<
    */
   _renderBarrierWaiters?: Set<string>;
 
+  /**
+   * @internal Loader IDs that handlers have started awaiting via ctx.use().
+   * Used for bidirectional deadlock detection: if a loader later calls
+   * rendered() and a handler already awaits it, we can detect the deadlock.
+   */
+  _handlerLoaderDeps?: Set<string>;
+
+  /**
+   * @internal Cached HandleData snapshot built at barrier resolution time.
+   * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
+   */
+  _renderBarrierHandleSnapshot?: HandleData;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -362,6 +380,8 @@ export type PublicRequestContext<
   | "_renderBarrierSegmentOrder"
   | "_treeHasStreaming"
   | "_renderBarrierWaiters"
+  | "_handlerLoaderDeps"
+  | "_renderBarrierHandleSnapshot"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
@@ -798,29 +818,49 @@ export function createRequestContext<TEnv>(
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Create deferred render barrier. Phase 1: non-streaming only, so all handlers
-  // complete synchronously during resolveAllSegments. The barrier is a simple
-  // deferred promise resolved after segment resolution (or after handle replay
-  // on cache/prerender paths). No HandleStore sealing here — that stays in the
-  // existing lifecycle (rsc-rendering.ts, cache-scope.ts, etc.).
+  // Lazy render barrier: only allocate the Promise when a loader actually
+  // calls rendered(). Requests that don't use rendered() pay zero cost.
   let barrierResolved = false;
-  let resolveBarrier: () => void;
-  ctx._renderBarrier = new Promise<void>((resolve) => {
-    resolveBarrier = resolve;
-  });
+  let resolveBarrier: (() => void) | undefined;
+  ctx._renderBarrier = null as any; // lazy — created on first access
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
     if (barrierResolved) return;
     barrierResolved = true;
-    ctx._renderBarrierSegmentOrder = segments
+    const segOrder = segments
       .filter((s) => s.type !== "loader")
       .map((s) => s.id);
-    // Clear deadlock detection set — once the barrier resolves, the loaders
-    // waiting on it will settle and the deadlock window is closed.
+    ctx._renderBarrierSegmentOrder = segOrder;
+    // Build and cache handle snapshot so loader ctx.use(handle) calls
+    // don't rebuild it on every invocation.
+    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+      handleStore,
+      segOrder,
+    );
     ctx._renderBarrierWaiters = undefined;
-    resolveBarrier();
+    ctx._handlerLoaderDeps = undefined;
+    if (resolveBarrier) resolveBarrier();
   };
+  Object.defineProperty(ctx, "_renderBarrier", {
+    get() {
+      // Barrier already resolved (cache/prerender hit) or first lazy access.
+      // Either way, replace the getter with a concrete value to avoid
+      // repeated Promise.resolve() allocations on subsequent reads.
+      const p = barrierResolved
+        ? Promise.resolve()
+        : new Promise<void>((resolve) => {
+            resolveBarrier = resolve;
+          });
+      Object.defineProperty(ctx, "_renderBarrier", {
+        value: p,
+        writable: false,
+        configurable: false,
+      });
+      return p;
+    },
+    configurable: true,
+  });
 
   // Now create use() with access to ctx
   ctx.use = createUseFunction({

package/src/types/segments.ts

@@ -50,12 +50,12 @@ export interface ResolvedSegment {
   parallelName?: string; // For parallels: the parallel group name (used to match with revalidations)
   // Loader-specific fields
   loaderId?: string; // For loaders: the loader $$id identifier
+  _inherited?: boolean; // For inherited loaders: dedup marker for buildMatchResult
   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-types.ts

@@ -233,12 +233,27 @@ export type PathHelpers<TEnv> = {
   include: IncludeFn<TEnv>;
 
   /**
-   * Define parallel routes that render simultaneously in named slots
+   * Define parallel routes that render simultaneously in named slots.
+   *
+   * A slot value can be a Handler / ReactNode / StaticHandlerDefinition
+   * (legacy form, broadcast use applies to every slot) or a slot descriptor
+   * `{ handler, use? }` whose `use` is scoped to that slot only. Per-slot
+   * merge order is `handler.use` → shared `use` → slot-local `use`, with
+   * narrowest scope winning for last-write-wins items like `loading()`.
    */
   parallel: <
     TSlots extends Record<
       `@${string}`,
-      Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | StaticHandlerDefinition
+      | {
+          handler:
+            | Handler<any, any, TEnv>
+            | ReactNode
+            | StaticHandlerDefinition;
+          use?: () => ParallelUseItem[];
+        }
     >,
   >(
     slots: TSlots,
@@ -264,9 +279,20 @@ export type PathHelpers<TEnv> = {
       ) => InterceptItem;
 
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
 
   /**
    * Control when a segment should revalidate during navigation
@@ -284,7 +310,10 @@ export type PathHelpers<TEnv> = {
   /**
    * Attach a loading component to the current route/layout
    */
-  loading: (component: ReactNode, options?: { ssr?: boolean }) => LoadingItem;
+  loading: (
+    component: ReactNode | (() => ReactNode),
+    options?: { ssr?: boolean },
+  ) => LoadingItem;
 
   /**
    * Attach an error boundary to catch errors in this segment

package/src/use-loader.tsx

@@ -1,9 +1,71 @@
 "use client";
 
-import { useCallback, useContext, useEffect, useRef, useState } from "react";
+import {
+  isValidElement,
+  startTransition,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
+/**
+ * Extract a specific loader's data from a content ReactNode.
+ *
+ * When a route registers loaders via loader(), the resolved data lives in
+ * the route's OutletProvider (rendered as <Outlet /> content). Parallel
+ * slots are siblings of <Outlet />, so they can't find it by walking
+ * the parent context chain. This helper traverses wrapper elements
+ * (MountContextProvider, ViewTransition, etc.) to reach the OutletProvider
+ * and extract the loader data directly.
+ */
+const NOT_FOUND = Symbol("not-found");
+
+function extractContentLoaderData(
+  node: ReactNode,
+  loaderId: string,
+): unknown | typeof NOT_FOUND {
+  if (!isValidElement(node)) return NOT_FOUND;
+  const props = node.props as Record<string, any> | undefined;
+  if (!props) return NOT_FOUND;
+
+  // Direct OutletProvider with loaderData
+  if (props.loaderData && loaderId in props.loaderData) {
+    return props.loaderData[loaderId];
+  }
+
+  // LoaderBoundary: loaderIds + loaderDataPromise (already resolved array).
+  // When the segment has loading(), loaderData is resolved inside
+  // LoaderBoundary via use(). If the promise was pre-awaited (forceAwait
+  // or isAction), the prop is a raw array we can index into.
+  if (
+    props.loaderIds &&
+    Array.isArray(props.loaderIds) &&
+    props.loaderDataPromise &&
+    !(props.loaderDataPromise instanceof Promise)
+  ) {
+    const idx = (props.loaderIds as string[]).indexOf(loaderId);
+    if (idx !== -1) {
+      const data = (props.loaderDataPromise as any[])[idx];
+      // loaderDataPromise entries may be { ok, data } result objects
+      if (data && typeof data === "object" && "ok" in data) {
+        return data.ok ? data.data : NOT_FOUND;
+      }
+      return data;
+    }
+  }
+
+  // Traverse into wrapper elements (MountContextProvider, ViewTransition,
+  // Suspense wrappers, etc.)
+  if (props.children) return extractContentLoaderData(props.children, loaderId);
+  return NOT_FOUND;
+}
+
 /**
  * Payload returned by loader RSC requests
  */
@@ -71,19 +133,27 @@ function useLoaderInternal<T>(
   const context = useContext(OutletContext);
 
   // Get data from context (SSR/navigation)
-  const getContextData = useCallback((): T | undefined => {
+  const contextData = useMemo((): T | undefined => {
     let current: OutletContextValue | null | undefined = context;
     while (current) {
       if (current.loaderData && loader.$$id in current.loaderData) {
         return current.loaderData[loader.$$id] as T;
       }
+      // Check content element — the route's OutletProvider is rendered as
+      // <Outlet /> content (a child), so its loaderData isn't in the parent
+      // chain. Parallel slots need to reach into it to find route-level loaders.
+      const contentData = extractContentLoaderData(
+        current.content,
+        loader.$$id,
+      );
+      if (contentData !== NOT_FOUND) {
+        return contentData as T;
+      }
       current = current.parent;
     }
     return undefined;
   }, [context, loader.$$id]);
 
-  const contextData = getContextData();
-
   // Local state for fetched data (from load() calls)
   const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
   const [isLoading, setIsLoading] = useState(false);
@@ -215,7 +285,9 @@ function useLoaderInternal<T>(
 
         const result = payload.loaderResult;
         if (requestId === requestIdRef.current) {
-          setFetchedData(result);
+          startTransition(() => {
+            setFetchedData(result);
+          });
         }
         return result;
       } catch (e) {

package/src/vite/discovery/prerender-collection.ts

@@ -51,103 +51,144 @@ export async function expandPrerenderRoutes(
     return substituteRouteParams(pattern, params);
   };
 
+  let resolvedRoutes = 0;
+  let totalDynamic = 0;
+
+  // Count dynamic routes upfront for progress reporting
   for (const { manifest } of allManifests) {
     if (!manifest.prerenderRoutes) continue;
-    const defs = manifest._prerenderDefs || {};
-    const passthroughSet = new Set(manifest.passthroughRoutes || []);
     for (const routeName of manifest.prerenderRoutes) {
       const pattern = manifest.routeManifest[routeName];
-      if (!pattern) continue;
-      const def = defs[routeName];
-      const isPassthroughRoute = passthroughSet.has(routeName);
-      const hasDynamic = pattern.includes(":") || pattern.includes("*");
-      if (!hasDynamic) {
-        // Static route: use pattern directly (strip trailing slash for URL)
-        entries.push({
-          urlPath: pattern.replace(/\/$/, "") || "/",
-          routeName,
-          concurrency: 1,
-          isPassthroughRoute,
-        });
-      } else {
-        // Dynamic route: call getParams() to enumerate param combinations
-        if (def?.getParams) {
-          try {
-            const buildVars: Record<string, any> = {};
-            const buildEnv = state.resolvedBuildEnv;
-            const getParamsCtx = {
-              build: true as const,
-              dev: !state.isBuildMode,
-              set: ((keyOrVar: any, value: any) => {
-                contextSet(buildVars, keyOrVar, value);
-              }) as any,
-              reverse: getParamsReverse,
-              get env() {
-                if (buildEnv !== undefined) return buildEnv;
-                throw new Error(
-                  "[rsc-router] ctx.env is not available during build-time getParams(). " +
-                    "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+      if (pattern && (pattern.includes(":") || pattern.includes("*"))) {
+        totalDynamic++;
+      }
+    }
+  }
+
+  // Periodic progress log so long getParams() calls don't look stalled
+  const paramsStart = performance.now();
+  const progressInterval =
+    totalDynamic > 0
+      ? setInterval(() => {
+          const elapsed = ((performance.now() - paramsStart) / 1000).toFixed(1);
+          console.log(
+            `[rsc-router] Resolving prerender params... ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
+          );
+        }, 5000)
+      : undefined;
+
+  try {
+    for (const { manifest } of allManifests) {
+      if (!manifest.prerenderRoutes) continue;
+      const defs = manifest._prerenderDefs || {};
+      const passthroughSet = new Set(manifest.passthroughRoutes || []);
+      for (const routeName of manifest.prerenderRoutes) {
+        const pattern = manifest.routeManifest[routeName];
+        if (!pattern) continue;
+        const def = defs[routeName];
+        const isPassthroughRoute = passthroughSet.has(routeName);
+        const hasDynamic = pattern.includes(":") || pattern.includes("*");
+        if (!hasDynamic) {
+          // Static route: use pattern directly (strip trailing slash for URL)
+          entries.push({
+            urlPath: pattern.replace(/\/$/, "") || "/",
+            routeName,
+            concurrency: 1,
+            isPassthroughRoute,
+          });
+        } else {
+          // Dynamic route: call getParams() to enumerate param combinations
+          if (def?.getParams) {
+            try {
+              const buildVars: Record<string, any> = {};
+              const buildEnv = state.resolvedBuildEnv;
+              const getParamsCtx = {
+                build: true as const,
+                dev: !state.isBuildMode,
+                set: ((keyOrVar: any, value: any) => {
+                  contextSet(buildVars, keyOrVar, value);
+                }) as any,
+                reverse: getParamsReverse,
+                get env() {
+                  if (buildEnv !== undefined) return buildEnv;
+                  throw new Error(
+                    "[rsc-router] ctx.env is not available during build-time getParams(). " +
+                      "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+                  );
+                },
+              };
+              const paramsList = await def.getParams(getParamsCtx);
+              const concurrency = def.options?.concurrency ?? 1;
+              const hasBuildVars =
+                Object.keys(buildVars).length > 0 ||
+                Object.getOwnPropertySymbols(buildVars).length > 0;
+              for (const params of paramsList) {
+                let url = substituteRouteParams(
+                  pattern,
+                  params as Record<string, string>,
+                  encodePathParam,
                 );
-              },
-            };
-            const paramsList = await def.getParams(getParamsCtx);
-            const concurrency = def.options?.concurrency ?? 1;
-            const hasBuildVars =
-              Object.keys(buildVars).length > 0 ||
-              Object.getOwnPropertySymbols(buildVars).length > 0;
-            for (const params of paramsList) {
-              let url = substituteRouteParams(
-                pattern,
-                params as Record<string, string>,
-                encodePathParam,
-              );
-              // Anonymous wildcard fallback: use conventional keys if provided
-              if (url.includes("*")) {
-                const wildcardValue =
-                  (params as Record<string, string>)["*"] ??
-                  (params as Record<string, string>).splat;
-                if (wildcardValue !== undefined) {
-                  url = url.replace(/\*[^/]*$/, encodePathParam(wildcardValue));
+                // Anonymous wildcard fallback: use conventional keys if provided
+                if (url.includes("*")) {
+                  const wildcardValue =
+                    (params as Record<string, string>)["*"] ??
+                    (params as Record<string, string>).splat;
+                  if (wildcardValue !== undefined) {
+                    url = url.replace(
+                      /\*[^/]*$/,
+                      encodePathParam(wildcardValue),
+                    );
+                  }
                 }
+                entries.push({
+                  urlPath: url.replace(/\/$/, "") || "/",
+                  routeName,
+                  concurrency,
+                  ...(hasBuildVars ? { buildVars } : {}),
+                  isPassthroughRoute,
+                });
               }
-              entries.push({
-                urlPath: url.replace(/\/$/, "") || "/",
-                routeName,
-                concurrency,
-                ...(hasBuildVars ? { buildVars } : {}),
-                isPassthroughRoute,
-              });
-            }
-          } catch (err: any) {
-            // Skip in getParams() skips the entire route
-            if (err.name === "Skip") {
-              console.log(
-                `[rsc-router]   SKIP route "${routeName}" - ${err.message}`,
-              );
-              notifyOnError(
-                registry,
-                err,
-                "prerender",
-                routeName,
-                undefined,
-                true,
+              resolvedRoutes++;
+            } catch (err: any) {
+              resolvedRoutes++;
+              // Skip in getParams() skips the entire route
+              if (err.name === "Skip") {
+                console.log(
+                  `[rsc-router]   SKIP route "${routeName}" - ${err.message}`,
+                );
+                notifyOnError(
+                  registry,
+                  err,
+                  "prerender",
+                  routeName,
+                  undefined,
+                  true,
+                );
+                continue;
+              }
+              // Regular error: fail the build
+              console.error(
+                `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`,
               );
-              continue;
+              notifyOnError(registry, err, "prerender", routeName);
+              throw err;
             }
-            // Regular error: fail the build
-            console.error(
-              `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`,
+          } else {
+            console.warn(
+              `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`,
             );
-            notifyOnError(registry, err, "prerender", routeName);
-            throw err;
           }
-        } else {
-          console.warn(
-            `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`,
-          );
         }
       }
     }
+  } finally {
+    if (progressInterval) {
+      clearInterval(progressInterval);
+      const elapsed = ((performance.now() - paramsStart) / 1000).toFixed(1);
+      console.log(
+        `[rsc-router] Resolved prerender params: ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
+      );
+    }
   }
 
   if (entries.length === 0) return;