@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d7eeaa75

package/src/router/segment-resolution/helpers.ts

@@ -8,7 +8,7 @@
  * - Error boundary segment creation
  */
 
-import type { ReactNode } from "react";
+import { createElement, type ReactNode } from "react";
 import { DataNotFoundError } from "../../errors";
 import {
   createErrorInfo,
@@ -180,34 +180,39 @@ export function catchSegmentError<TEnv>(
 
   if (error instanceof DataNotFoundError) {
     const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+    // Fall back to router's notFound component, then a plain default
+    const notFoundOption = deps.notFoundComponent;
+    const defaultFallback =
+      typeof notFoundOption === "function"
+        ? notFoundOption({ pathname: pathname ?? "" })
+        : (notFoundOption ?? createElement("h1", null, "Not Found"));
+    const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
 
-    if (notFoundFallback) {
-      const notFoundInfo = createNotFoundInfo(
-        error,
-        entry.shortCode,
-        entry.type,
-        pathname,
-      );
+    const notFoundInfo = createNotFoundInfo(
+      error,
+      entry.shortCode,
+      entry.type,
+      pathname,
+    );
 
-      reportError(true, {
-        notFound: true,
-        message: notFoundInfo.message,
-      });
+    reportError(true, {
+      notFound: true,
+      message: notFoundInfo.message,
+    });
 
-      debugLog("segment", "notFound boundary handled error", {
-        segmentId: entry.shortCode,
-        message: notFoundInfo.message,
-      });
+    debugLog("segment", "notFound boundary handled error", {
+      segmentId: entry.shortCode,
+      message: notFoundInfo.message,
+    });
 
-      setResponseStatus(404);
+    setResponseStatus(404);
 
-      return createNotFoundSegment(
-        notFoundInfo,
-        notFoundFallback,
-        entry,
-        params,
-      );
-    }
+    return createNotFoundSegment(
+      notFoundInfo,
+      effectiveNotFoundFallback,
+      entry,
+      params,
+    );
   }
 
   const fallback = deps.findNearestErrorBoundary(entry);

package/src/router/segment-resolution/revalidation.ts

@@ -41,7 +41,11 @@ import {
 } from "./helpers.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
-import { track } from "../../server/context.js";
+import {
+  track,
+  RSCRouterContext,
+  runInsideLoaderScope,
+} from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
 // Telemetry helpers
@@ -232,7 +236,9 @@ export async function resolveLoadersWithRevalidation<TEnv>(
       params: ctx.params,
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
-        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+        runInsideLoaderScope(() =>
+          resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+        ),
         entry,
         segmentId,
         ctx.pathname,
@@ -269,28 +275,39 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     belongsToRoute: boolean,
     shortCodeOverride?: string,
   ): Promise<void> {
-    const { segments, matchedIds } = await resolveLoadersWithRevalidation(
-      entry,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      shortCodeOverride,
-      stale,
-    );
-    for (const seg of segments) {
-      if (!seenIds.has(seg.id)) {
-        seenIds.add(seg.id);
-        allLoaderSegments.push(seg);
+    // Skip if all loaders from this entry have already been resolved
+    // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
+    const loaderEntries = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      loaderEntries.length > 0 &&
+      loaderEntries.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const { segments, matchedIds } = await resolveLoadersWithRevalidation(
+        entry,
+        context,
+        belongsToRoute,
+        clientSegmentIds,
+        prevParams,
+        request,
+        prevUrl,
+        nextUrl,
+        routeKey,
+        deps,
+        actionContext,
+        shortCodeOverride,
+        stale,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          allLoaderSegments.push(seg);
+        }
       }
+      allMatchedIds.push(...matchedIds);
     }
-    allMatchedIds.push(...matchedIds);
 
     const seenParallelEntryIds = new Set<string>();
     for (const parallelEntry of getParallelEntries(entry.parallel)) {
@@ -302,6 +319,39 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     const childBelongsToRoute = belongsToRoute || entry.type === "route";
     for (const layoutEntry of entry.layout) {
       await collectEntryLoaders(layoutEntry, childBelongsToRoute);
+      // Inherit route loaders for orphan layouts with parallels.
+      // Resolve directly — do NOT re-enter collectEntryLoaders with the
+      // route entry, as that would re-iterate route.layout and loop.
+      if (
+        entry.type === "route" &&
+        entry.loader &&
+        entry.loader.length > 0 &&
+        Object.keys(layoutEntry.parallel).length > 0
+      ) {
+        const inherited = await resolveLoadersWithRevalidation(
+          entry,
+          context,
+          childBelongsToRoute,
+          clientSegmentIds,
+          prevParams,
+          request,
+          prevUrl,
+          nextUrl,
+          routeKey,
+          deps,
+          actionContext,
+          layoutEntry.shortCode,
+          stale,
+        );
+        for (const seg of inherited.segments) {
+          if (!seenIds.has(seg.id)) {
+            seenIds.add(seg.id);
+            seg._inherited = true;
+            allLoaderSegments.push(seg);
+          }
+        }
+        allMatchedIds.push(...inherited.matchedIds);
+      }
     }
   }
 
@@ -671,13 +721,20 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         return staticComponent;
       }
       const routeEntry = entry as Extract<EntryData, { type: "route" }>;
+      // For Passthrough routes at runtime, use the live handler instead of
+      // the build handler. At build time (context.build === true), always
+      // use the build handler from routeEntry.handler.
+      const handler =
+        !context.build && routeEntry.liveHandler
+          ? routeEntry.liveHandler
+          : routeEntry.handler;
       if (!routeEntry.loading) {
-        const result = handleHandlerResult(await routeEntry.handler(context));
+        const result = handleHandlerResult(await handler(context));
         doneHandler();
         return result;
       }
       if (!actionContext) {
-        const result = handleHandlerResult(routeEntry.handler(context));
+        const result = handleHandlerResult(handler(context));
         if (result instanceof Promise) {
           result.finally(doneHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
@@ -700,9 +757,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       debugLog("segment.action", "resolving action route with awaited value", {
         entryId: entry.id,
       });
-      const actionResult = handleHandlerResult(
-        await routeEntry.handler(context),
-      );
+      const actionResult = handleHandlerResult(await handler(context));
       doneHandler();
       return {
         content: Promise.resolve(actionResult),
@@ -711,10 +766,12 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     () => null,
   );
 
+  // Normalize void handlers (undefined) to null so the reconciler's
+  // component === null checks work consistently for both void and explicit null.
   const resolvedComponent =
     component && typeof component === "object" && "content" in component
-      ? (component as { content: ReactNode }).content
-      : component;
+      ? ((component as { content: ReactNode }).content ?? null)
+      : (component ?? null);
 
   const segment: ResolvedSegment = {
     id: entry.shortCode,
@@ -816,6 +873,7 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         deps,
         actionContext,
         stale,
+        entry,
       );
       segments.push(...orphanResult.segments);
       matchedIds.push(...orphanResult.matchedIds);
@@ -927,6 +985,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
+  /** Parent route entry — its loaders are inherited so parallel slots can access them. */
+  parentRouteEntry?: EntryData,
 ): Promise<SegmentRevalidationResult> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -954,6 +1014,37 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   segments.push(...loaderResult.segments);
   matchedIds.push(...loaderResult.matchedIds);
 
+  // Inherit parent route's loaders so parallel slots inside this layout
+  // can access them via useLoader(). See resolveOrphanLayout in fresh.ts.
+  if (
+    parentRouteEntry &&
+    parentRouteEntry.loader &&
+    parentRouteEntry.loader.length > 0 &&
+    Object.keys(orphan.parallel).length > 0
+  ) {
+    const inheritedResult = await resolveLoadersWithRevalidation(
+      parentRouteEntry,
+      context,
+      belongsToRoute,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      deps,
+      actionContext,
+      orphan.shortCode,
+      stale,
+    );
+    // Tag as inherited so buildMatchResult can deduplicate when safe
+    for (const s of inheritedResult.segments) {
+      s._inherited = true;
+    }
+    segments.push(...inheritedResult.segments);
+    matchedIds.push(...inheritedResult.matchedIds);
+  }
+
   // Handler-first: resolve orphan layout handler before its parallels
   // so ctx.set() values are visible to parallel children.
   matchedIds.push(orphan.shortCode);
@@ -1040,6 +1131,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     );
 
     if (!resolvedParallelEntries.has(parallelEntry.id)) {
+      // shortCodeOverride must match the parent layout, not the parallel entry.
       const loaderResult = await resolveLoadersWithRevalidation(
         parallelEntry,
         context,
@@ -1052,7 +1144,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         routeKey,
         deps,
         actionContext,
-        undefined,
+        orphan.shortCode,
         stale,
       );
       segments.push(...loaderResult.segments);
@@ -1235,6 +1327,10 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
+    if (entry.type === "cache") {
+      const store = RSCRouterContext.getStore();
+      if (store) store.insideCacheScope = true;
+    }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(
       nonParallelEntry,

package/src/router/types.ts

@@ -96,6 +96,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
   findNearestNotFoundBoundary: (
     entry: EntryData | null,
   ) => ReactNode | NotFoundBoundaryHandler | null;
+  notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
 }
 

package/src/router.ts

@@ -19,6 +19,8 @@ import {
 import MapRootLayout from "./server/root-layout.js";
 import type { AllUseItems } from "./route-types.js";
 import type { UrlPatterns } from "./urls.js";
+import type { UrlBuilder } from "./urls/pattern-types.js";
+import { urls } from "./urls.js";
 import {
   EntryData,
   InterceptSelectorContext,
@@ -133,6 +135,7 @@ export function createRouter<TEnv = any>(
   const {
     id: userProvidedId,
     $$id: injectedId,
+    basename: basenameOption,
     debugPerformance = false,
     document: documentOption,
     defaultErrorBoundary,
@@ -158,6 +161,13 @@ export function createRouter<TEnv = any>(
     originCheck: originCheckOption,
   } = options;
 
+  // Normalize basename: ensure leading slash, strip trailing slash.
+  // A bare "/" is equivalent to no basename.
+  const basename =
+    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
+      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
+      : undefined;
+
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
 
@@ -526,6 +536,7 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
   };
 
@@ -614,6 +625,8 @@ export function createRouter<TEnv = any>(
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _matchForPrerender(
       pathname,
@@ -621,6 +634,8 @@ export function createRouter<TEnv = any>(
       prerenderDeps,
       buildVars,
       isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -628,12 +643,16 @@ export function createRouter<TEnv = any>(
     handler: Function,
     handlerId: string,
     routeName?: string,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _renderStaticSegment<TEnv>(
       handler,
       handlerId,
       mergedRouteMap,
       routeName,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -658,8 +677,15 @@ export function createRouter<TEnv = any>(
   const router: RSCRouterInternal<TEnv, {}> = {
     __brand: RSC_ROUTER_BRAND,
     id: routerId,
+    basename,
+
+    routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
+      // Wrap builder functions in urls() automatically
+      const urlPatterns: UrlPatterns<TEnv> =
+        typeof patternsOrBuilder === "function"
+          ? (urls(patternsOrBuilder) as UrlPatterns<TEnv>)
+          : patternsOrBuilder;
 
-    routes(urlPatterns: UrlPatterns<TEnv>): any {
       // Store reference for runtime manifest generation
       storedUrlPatterns = urlPatterns;
       const currentMountIndex = mountIndex++;
@@ -707,6 +733,10 @@ export function createRouter<TEnv = any>(
           counters: {},
           mountIndex: currentMountIndex,
           cacheProfiles: resolvedCacheProfiles,
+          // basename sets the initial URL prefix so all path() patterns
+          // are registered with the prefix (e.g. "/admin" + "/users" = "/admin/users").
+          // No namePrefix — route names stay unprefixed.
+          ...(basename ? { urlPrefix: basename } : {}),
         },
         () => {
           handlerResult = urlPatterns.handler() as AllUseItems[];
@@ -726,7 +756,7 @@ export function createRouter<TEnv = any>(
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
           prerenderRouteKeys.add(name);
-          if (entry.prerenderDef?.options?.passthrough === true) {
+          if (entry.isPassthrough === true) {
             if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
             passthroughRouteKeys.add(name);
           }
@@ -855,8 +885,18 @@ export function createRouter<TEnv = any>(
       patternOrMiddleware: string | MiddlewareFn<TEnv>,
       middleware?: MiddlewareFn<TEnv>,
     ): any {
-      // Global middleware - no mount prefix
-      addMiddleware(patternOrMiddleware, middleware, null);
+      // Auto-prefix pattern with basename so router-level middleware
+      // patterns are router-relative (e.g. "/users/*" matches "/app/users/*").
+      if (basename && typeof patternOrMiddleware === "string") {
+        const pattern = patternOrMiddleware;
+        const prefixed =
+          pattern === "/*" || pattern === "*"
+            ? `${basename}/*`
+            : `${basename}${pattern}`;
+        addMiddleware(prefixed, middleware, null);
+      } else {
+        addMiddleware(patternOrMiddleware, middleware, null);
+      }
       return router;
     },
 
@@ -957,6 +997,9 @@ export function createRouter<TEnv = any>(
     // Expose source file for per-router type generation
     __sourceFile,
 
+    // Expose basename for runtime manifest generation
+    __basename: basename,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused
@@ -990,6 +1033,10 @@ export function createRouter<TEnv = any>(
       };
     })(),
 
+    // Low-level route matching for request classification
+    findMatch: (pathname: string, metricsStore?: any) =>
+      findMatch(pathname, metricsStore),
+
     // Debug utility for manifest inspection
     debugManifest: () => buildDebugManifest<TEnv>(routesEntries),
   };
@@ -998,7 +1045,9 @@ export function createRouter<TEnv = any>(
   RouterRegistry.set(routerId, router);
 
   // If urls option was provided, auto-register them
-  if (urlsOption) {
+  if (typeof urlsOption === "function") {
+    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+  } else if (urlsOption) {
     return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
   }