@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2a0dea97

package/src/urls/path-helper.ts

@@ -12,10 +12,11 @@ import {
   getNamePrefix,
   getRootScoped,
 } from "../server/context";
-import { invariant } from "../errors";
+import { invariant, DataNotFoundError } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import {
   isPrerenderHandler,
+  isPassthroughHandler,
   type PrerenderHandlerDefinition,
 } from "../prerender.js";
 import {
@@ -34,6 +35,10 @@ import type {
   JsonResponsePathFn,
   TextResponsePathFn,
 } from "./path-helper-types.js";
+import {
+  resolveHandlerUse,
+  mergeHandlerUse,
+} from "../route-definition/resolve-handler-use.js";
 
 /**
  * Check if a value is a valid use item
@@ -142,6 +147,12 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       use = maybeUse;
     }
 
+    // Merge handler.use() defaults with explicit use()
+    // Response routes (path.json, path.text, etc.) only allow middleware + cache
+    const handlerUseFn = resolveHandlerUse(handler);
+    const mountSite = resolveResponseType(options) ? "response" : "path";
+    const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
+
     // Get prefixes from context (set by include())
     const urlPrefix = getUrlPrefix();
     const namePrefix = getNamePrefix();
@@ -176,14 +187,31 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
     }
 
     // Ensure handler is always a function (wrap ReactNode or extract from prerender/static def)
+    // For prerender stubs (production builds where handler code is evicted),
+    // handler.handler is undefined — provide a notFound fallback so requests
+    // for non-prerendered params get 404 instead of "handler is not a function".
     const wrappedHandler: Handler<any, any, TEnv> =
       typeof handler === "function"
         ? (handler as Handler<any, any, TEnv>)
-        : isPrerenderHandler(handler)
-          ? (handler.handler as Handler<any, any, TEnv>)
-          : isStaticHandler(handler)
-            ? (handler.handler as Handler<any, any, TEnv>)
-            : () => handler;
+        : isPassthroughHandler(handler)
+          ? typeof handler.prerenderDef.handler === "function"
+            ? (handler.prerenderDef.handler as Handler<any, any, TEnv>)
+            : () => {
+                throw new DataNotFoundError(
+                  "No prerender data found for this route",
+                );
+              }
+          : isPrerenderHandler(handler)
+            ? typeof handler.handler === "function"
+              ? (handler.handler as Handler<any, any, TEnv>)
+              : () => {
+                  throw new DataNotFoundError(
+                    "No prerender data found for this route",
+                  );
+                }
+            : isStaticHandler(handler)
+              ? (handler.handler as Handler<any, any, TEnv>)
+              : () => handler;
 
     const entry = {
       id: namespace,
@@ -199,16 +227,23 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       errorBoundary: [],
       notFoundBoundary: [],
       layout: [],
-      parallel: [],
+      parallel: {},
       intercept: [],
       loader: [],
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
-      ...(isPrerenderHandler(handler)
+      ...(isPassthroughHandler(handler)
         ? {
             isPrerender: true as const,
-            prerenderDef: handler as PrerenderHandlerDefinition,
+            prerenderDef: handler.prerenderDef as PrerenderHandlerDefinition,
+            isPassthrough: true as const,
+            liveHandler: handler.liveHandler as Handler<any, any, TEnv>,
           }
-        : {}),
+        : isPrerenderHandler(handler)
+          ? {
+              isPrerender: true as const,
+              prerenderDef: handler as PrerenderHandlerDefinition,
+            }
+          : {}),
       ...(isStaticHandler(handler)
         ? {
             isStaticPrerender: true as const,
@@ -264,9 +299,9 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       registerSearchSchema(routeName, options.search);
     }
 
-    // Run use callback if provided
-    if (use && typeof use === "function") {
-      const result = store.run(namespace, entry, use)?.flat(3);
+    // Run merged use callback (handler.use defaults + explicit use) if present
+    if (mergedUse) {
+      const result = store.run(namespace, entry, mergedUse)?.flat(3);
       invariant(
         Array.isArray(result) && result.every((item) => isValidUseItem(item)),
         `path() use() callback must return an array of use items [${namespace}]`,

package/src/urls/pattern-types.ts

@@ -7,6 +7,18 @@ import type {
 } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import { RESPONSE_TYPE } from "./response-types.js";
+import type { DefaultEnv } from "../types.js";
+import type { PathHelpers } from "./path-helper-types.js";
+
+/**
+ * Builder function accepted by urls() and as a shorthand for routes()/urls option.
+ * When passed directly to routes() or createRouter({ urls }), it is wrapped in urls() automatically.
+ */
+export type UrlBuilder<
+  TEnv = DefaultEnv,
+  TItems extends readonly (AllUseItems | readonly AllUseItems[])[] =
+    readonly AllUseItems[],
+> = (helpers: PathHelpers<TEnv>) => TItems;
 
 /**
  * Sentinel type for unnamed routes.

package/src/urls/response-types.ts

@@ -4,6 +4,7 @@ import type {
   DefaultReverseRouteMap,
   DefaultVars,
 } from "../types/global-namespace.js";
+import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
 
 /**
  * Reverse function for response handler contexts.
@@ -38,9 +39,12 @@ export const RESPONSE_TYPE: unique symbol = Symbol.for(
  * Handler that must return Response (not ReactNode).
  * Used by path.image(), path.stream(), path.any() (binary/streaming data).
  */
-export type ResponseHandler<TParams = Record<string, string>, TEnv = any> = (
+export type ResponseHandler<TParams = Record<string, string>, TEnv = any> = ((
   ctx: ResponseHandlerContext<TParams, TEnv>,
-) => Response | Promise<Response>;
+) => Response | Promise<Response>) & {
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<ResponseRouteUseItem>;
+};
 
 /**
  * JSON-serializable value type for auto-wrap support.
@@ -60,9 +64,12 @@ export type JsonValue =
 export type JsonResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = (
+> = ((
   ctx: ResponseHandlerContext<TParams, TEnv>,
-) => JsonValue | Response | Promise<JsonValue | Response>;
+) => JsonValue | Response | Promise<JsonValue | Response>) & {
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<ResponseRouteUseItem>;
+};
 
 /**
  * Handler for text-based response routes (text, html, xml).
@@ -71,9 +78,12 @@ export type JsonResponseHandler<
 export type TextResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = (
+> = ((
   ctx: ResponseHandlerContext<TParams, TEnv>,
-) => string | Response | Promise<string | Response>;
+) => string | Response | Promise<string | Response>) & {
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<ResponseRouteUseItem>;
+};
 
 /**
  * Lighter handler context for response routes.

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/bundle-postprocess.ts

@@ -31,25 +31,25 @@ export function postprocessBundle(state: DiscoveryState): void {
     state.rscEntryFileName ?? "index.js",
   );
 
-  // 1. Evict handler code from __prerender-handlers and __static-handlers chunks.
-  // handlerChunkInfo/staticHandlerChunkInfo are populated by generateBundle
+  // 1. Evict handler code from whichever chunks contain handler exports.
+  // handlerChunkInfoMap/staticHandlerChunkInfoMap are populated by generateBundle
   // after the production RSC build. In Vite 6 multi-environment builds, the
-  // RSC build runs twice (analysis + production). Chunk info is only available
-  // after the production pass, so we run eviction whenever it becomes available.
+  // RSC build runs twice (analysis + production). The maps are cleared at the
+  // start of each generateBundle pass so only production data is used here.
   const evictionTargets: Array<{
-    info: typeof state.handlerChunkInfo;
+    infos: Iterable<import("./state.js").ChunkInfo>;
     fnName: string;
     brand: string;
     label: string;
   }> = [
     {
-      info: state.handlerChunkInfo,
+      infos: state.handlerChunkInfoMap.values(),
       fnName: "Prerender",
       brand: "prerenderHandler",
       label: "handler code from RSC bundle",
     },
     {
-      info: state.staticHandlerChunkInfo,
+      infos: state.staticHandlerChunkInfoMap.values(),
       fnName: "Static",
       brand: "staticHandler",
       label: "static handler code",
@@ -57,35 +57,32 @@ export function postprocessBundle(state: DiscoveryState): void {
   ];
 
   for (const target of evictionTargets) {
-    if (!target.info) continue;
-    const chunkPath = resolve(
-      state.projectRoot,
-      "dist/rsc",
-      target.info.fileName,
-    );
-    try {
-      const code = readFileSync(chunkPath, "utf-8");
-      const result = evictHandlerCode(
-        code,
-        target.info.exports,
-        target.fnName,
-        target.brand,
-      );
-      if (result) {
-        writeFileSync(chunkPath, result.code);
-        const savedKB = (result.savedBytes / 1024).toFixed(1);
-        console.log(
-          `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${target.info.fileName}`,
+    for (const info of target.infos) {
+      const chunkPath = resolve(state.projectRoot, "dist/rsc", info.fileName);
+      try {
+        const code = readFileSync(chunkPath, "utf-8");
+        const result = evictHandlerCode(
+          code,
+          info.exports,
+          target.fnName,
+          target.brand,
+        );
+        if (result) {
+          writeFileSync(chunkPath, result.code);
+          const savedKB = (result.savedBytes / 1024).toFixed(1);
+          console.log(
+            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+          );
+        }
+      } catch (replaceErr: any) {
+        console.warn(
+          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
         );
       }
-    } catch (replaceErr: any) {
-      console.warn(
-        `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
-      );
     }
   }
-  state.handlerChunkInfo = null;
-  state.staticHandlerChunkInfo = null;
+  state.handlerChunkInfoMap.clear();
+  state.staticHandlerChunkInfoMap.clear();
 
   // 2. Write prerender data as separate importable asset modules
   // and inject a lazy manifest loader into the RSC entry.
@@ -138,7 +135,7 @@ export function postprocessBundle(state: DiscoveryState): void {
   // and inject a __STATIC_MANIFEST import into the RSC entry.
   if (hasStaticData && existsSync(rscEntryPath)) {
     const rscCode = readFileSync(rscEntryPath, "utf-8");
-    if (!rscCode.includes("__STATIC_MANIFEST")) {
+    if (!rscCode.includes("__static-manifest.js")) {
       try {
         const manifestEntries: string[] = [];
         let totalBytes = copyStagedBuildAssets(

package/src/vite/discovery/discover-routers.ts

@@ -135,7 +135,11 @@ export async function discoverRouters(
       continue;
     }
 
-    const manifest = generateManifestFull(router.urlpatterns, routerMountIndex);
+    const manifest = generateManifestFull(
+      router.urlpatterns,
+      routerMountIndex,
+      router.__basename ? { urlPrefix: router.__basename } : undefined,
+    );
     routerMountIndex++;
     allManifests.push({ id, manifest });
     const routeCount = Object.keys(manifest.routeManifest).length;

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

@@ -51,93 +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 || {};
     for (const routeName of manifest.prerenderRoutes) {
       const pattern = manifest.routeManifest[routeName];
-      if (!pattern) continue;
-      const def = defs[routeName];
-      const isPassthroughRoute = !!def?.options?.passthrough;
-      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 getParamsCtx = {
-              build: true as const,
-              set: ((keyOrVar: any, value: any) => {
-                contextSet(buildVars, keyOrVar, value);
-              }) as any,
-              reverse: getParamsReverse,
-            };
-            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));
+      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,
+                );
+                // 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;
@@ -175,6 +226,7 @@ export async function expandPrerenderRoutes(
               {},
               entry.buildVars,
               entry.isPassthroughRoute,
+              state.resolvedBuildEnv,
             );
             if (!result) continue;
 
@@ -326,6 +378,8 @@ export async function renderStaticHandlers(
             def.handler,
             def.$$id,
             (def as any).$$routePrefix,
+            state.resolvedBuildEnv,
+            !state.isBuildMode,
           );
           if (result) {
             const hasHandles = Object.keys(result.handles).length > 0;