@rangojs/router 0.0.0-experimental.f2337aef → 0.0.0-experimental.f2d1a2f1

package/src/urls/path-helper-types.ts

@@ -37,7 +37,10 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
-import type { PrerenderHandlerDefinition } from "../prerender.js";
+import type {
+  PrerenderHandlerDefinition,
+  PassthroughHandlerDefinition,
+} from "../prerender.js";
 import type { StaticHandlerDefinition } from "../static-handler.js";
 import type { InterceptWhenFn } from "../server/context";
 import type {
@@ -70,6 +73,7 @@ export type PathFn<TEnv> = <
         ctx: HandlerContext<TParams, TEnv, TSearch>,
       ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>)
     | PrerenderHandlerDefinition<TParams>
+    | PassthroughHandlerDefinition<TParams, TEnv>
     | StaticHandlerDefinition<TParams>,
   optionsOrUse?: PathOptions<TName, TSearch> | (() => UseItems<RouteUseItem>),
   use?: () => UseItems<RouteUseItem>,
@@ -229,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,
@@ -260,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
@@ -280,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/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,8 @@ import type {
   DefaultReverseRouteMap,
   DefaultVars,
 } from "../types/global-namespace.js";
+import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Reverse function for response handler contexts.
@@ -38,9 +40,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 +65,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 +79,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.
@@ -83,19 +94,10 @@ export type TextResponseHandler<
 export interface ResponseHandlerContext<
   TParams = Record<string, string>,
   TEnv = any,
-> {
-  request: Request;
+> extends RequestScope<TEnv> {
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  /** Platform bindings (DB, KV, secrets, etc.). */
-  env: TEnv;
-  /** Query parameters from the URL (system params like `_rsc*` are filtered). */
-  searchParams: URLSearchParams;
-  /** The full URL object (with system params filtered). */
-  url: URL;
-  /** The pathname portion of the request URL. */
-  pathname: string;
   reverse: ResponseReverseFunction;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {

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/debug.ts

@@ -0,0 +1,86 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger("rango:routes");
+ *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
+ *
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
+ */
+
+import debugFactory from "debug";
+
+// Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
+// console.logs in this plugin. Map it to `rango:*` so those call sites can
+// be migrated to the `debug` pipeline without breaking existing setups.
+// Uses debug.enable() rather than mutating process.env because the `debug`
+// package already snapshotted DEBUG when it was imported above.
+if (process.env.INTERNAL_RANGO_DEBUG) {
+  const existing = debugFactory.disable();
+  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+}
+
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+
+export function createRangoDebugger(namespace: string): Debugger | undefined {
+  const primary = debugFactory(namespace);
+  // Shadow namespace so `vite --debug rango:*` (which expands to
+  // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary as unknown as Debugger;
+  if (shadow.enabled) return shadow as unknown as Debugger;
+  return undefined;
+}
+
+/**
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
+ *
+ *     await timed(debug, "discover routers", () => discoverRouters(state));
+ */
+export async function timed<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  if (!debug) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export function timedSync<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T,
+): T {
+  if (!debug) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}

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;