@rangojs/router 0.0.0-experimental.760a71d9 → 0.0.0-experimental.78

package/src/router/route-snapshot.ts

@@ -0,0 +1,245 @@
+/**
+ * Route Snapshot
+ *
+ * Pure data type representing the fully-resolved state of a single route match.
+ * Consolidates the duplicated findMatch + loadManifest + collectRouteMiddleware +
+ * cacheScope derivation that previously lived separately in preview-match.ts
+ * and match-api.ts.
+ *
+ * resolveRoute() is the factory: given a pathname and dependencies, it returns
+ * a RouteSnapshot (or redirect/null). Consumers (createMatchContextForFull,
+ * createMatchContextForPartial, previewMatch) read snapshot fields instead of
+ * re-deriving them.
+ */
+
+import type { CacheScope } from "../cache/cache-scope.js";
+import { createCacheScope } from "../cache/cache-scope.js";
+import type { EntryData, MetricsStore } from "../server/context.js";
+import { loadManifest } from "./manifest.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Immutable snapshot of a resolved route match.
+ *
+ * Contains everything derivable from (pathname, findMatch, loadManifest)
+ * without request context, navigation state, or intercept logic.
+ */
+export interface RouteSnapshot<TEnv = any> {
+  /** Raw match result from the trie/pattern matcher */
+  matched: RouteMatchResult<TEnv>;
+  /** Resolved manifest entry (with loaded handler, loader, etc.) */
+  manifestEntry: EntryData;
+  /** All entries in the route chain (from traverseBack) */
+  entries: EntryData[];
+  /** Canonical route key (e.g. "blog.detail") */
+  routeKey: string;
+  /** Last segment of a dotted route key (e.g. "detail" from "blog.detail") */
+  localRouteName: string;
+  /** Extracted route params */
+  params: Record<string, string>;
+  /** Collected route-level middleware from the entry tree */
+  routeMiddleware: CollectedMiddleware[];
+  /** Merged cache scope from the entry chain */
+  cacheScope: CacheScope | null;
+  /** Whether the matched route is a passthrough route */
+  isPassthrough: boolean;
+  /** Response type for non-RSC routes (e.g. "application/json") */
+  responseType?: string;
+}
+
+export type ResolveRouteResult<TEnv = any> =
+  | { type: "match"; snapshot: RouteSnapshot<TEnv> }
+  | { type: "redirect"; redirectTo: string }
+  | null;
+
+export interface ResolveRouteDeps<TEnv = any> {
+  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  metricsStore?: MetricsStore;
+  isSSR?: boolean;
+  /**
+   * When true, skip entries array and cacheScope chain construction.
+   * Used by previewMatch which only needs matched, manifestEntry,
+   * routeMiddleware, and responseType — avoids an extra traverseBack
+   * allocation and cacheScope composition on the hot classification path.
+   */
+  lite?: boolean;
+  /**
+   * When true, skip pushing the "route-matching" metric internally.
+   * Used by createMatchContextForPartial on the fresh path (no snapshot
+   * reuse) so it can measure current + prev + intercept-source findMatch
+   * calls under one combined "route-matching" metric. On the reuse path,
+   * the partial path emits "route-matching:nav" for the prev +
+   * intercept-source lookups only (current-route resolution was done
+   * during classification without metrics).
+   */
+  skipRouteMatchMetric?: boolean;
+}
+
+/**
+ * Resolve a pathname into a RouteSnapshot.
+ *
+ * This is the single source of truth for route derivation. It performs:
+ * 1. findMatch(pathname)
+ * 2. Redirect check
+ * 3. loadManifest
+ * 4. Passthrough detection
+ * 5. collectRouteMiddleware
+ * 6. Cache scope chain
+ * 7. responseType + localRouteName extraction
+ *
+ * Metrics timing is preserved identically to the previous inline code.
+ */
+export async function resolveRoute<TEnv = any>(
+  pathname: string,
+  deps: ResolveRouteDeps<TEnv>,
+): Promise<ResolveRouteResult<TEnv>> {
+  const {
+    metricsStore,
+    isSSR = false,
+    lite = false,
+    skipRouteMatchMetric = false,
+  } = deps;
+
+  const routeMatchStart =
+    metricsStore && !skipRouteMatchMetric ? performance.now() : 0;
+  const matched = deps.findMatch(pathname);
+  if (metricsStore && !skipRouteMatchMetric) {
+    metricsStore.metrics.push({
+      label: "route-matching",
+      duration: performance.now() - routeMatchStart,
+      startTime: routeMatchStart - metricsStore.requestStart,
+    });
+  }
+
+  if (!matched) {
+    return null;
+  }
+
+  if (matched.redirectTo) {
+    return { type: "redirect", redirectTo: matched.redirectTo };
+  }
+
+  const manifestStart = metricsStore ? performance.now() : 0;
+  const manifestEntry = await loadManifest(
+    matched.entry,
+    matched.routeKey,
+    pathname,
+    metricsStore,
+    isSSR,
+  );
+  if (metricsStore) {
+    metricsStore.metrics.push({
+      label: "manifest-loading",
+      duration: performance.now() - manifestStart,
+      startTime: manifestStart - metricsStore.requestStart,
+    });
+  }
+
+  const isPassthrough =
+    manifestEntry.type === "route" && manifestEntry.isPassthrough === true;
+
+  let entries: EntryData[];
+  let cacheScope: CacheScope | null = null;
+  if (lite) {
+    entries = [];
+  } else {
+    ({ entries, cacheScope } = buildEntriesAndCacheScope(manifestEntry));
+  }
+
+  const routeMiddleware = collectRouteMiddleware(
+    lite ? traverseBack(manifestEntry) : entries,
+    matched.params,
+  );
+
+  const responseType =
+    matched.responseType ||
+    (manifestEntry.type === "route" ? manifestEntry.responseType : undefined);
+
+  const localRouteName = matched.routeKey.includes(".")
+    ? matched.routeKey.split(".").pop()!
+    : matched.routeKey;
+
+  return {
+    type: "match",
+    snapshot: {
+      matched,
+      manifestEntry,
+      entries,
+      routeKey: matched.routeKey,
+      localRouteName,
+      params: matched.params,
+      routeMiddleware,
+      cacheScope,
+      isPassthrough,
+      responseType,
+    },
+  };
+}
+
+/**
+ * Fill in the entries and cacheScope fields on a lite snapshot.
+ *
+ * When classifyRequest produces a lite snapshot (entries=[], cacheScope=null),
+ * this function computes the missing fields from manifestEntry without
+ * re-running findMatch, loadManifest, or collectRouteMiddleware.
+ *
+ * If the snapshot already has entries, returns it as-is.
+ */
+export function ensureFullRouteSnapshot<TEnv = any>(
+  snapshot: RouteSnapshot<TEnv>,
+): RouteSnapshot<TEnv> {
+  if (snapshot.entries.length > 0) {
+    return snapshot;
+  }
+
+  const { entries, cacheScope } = buildEntriesAndCacheScope(
+    snapshot.manifestEntry,
+  );
+  return { ...snapshot, entries, cacheScope };
+}
+
+/**
+ * Materialize the entry chain and derive the merged cache scope.
+ * Shared by resolveRoute (non-lite) and ensureFullRouteSnapshot.
+ */
+function buildEntriesAndCacheScope(manifestEntry: EntryData): {
+  entries: EntryData[];
+  cacheScope: CacheScope | null;
+} {
+  const entries = [...traverseBack(manifestEntry)];
+  let cacheScope: CacheScope | null = null;
+  for (const entry of entries) {
+    if (entry.cache) {
+      cacheScope = createCacheScope(entry.cache, cacheScope);
+    }
+  }
+  return { entries, cacheScope };
+}
+
+/**
+ * Test helper: create a RouteSnapshot with sensible defaults and overrides.
+ */
+export function createRouteSnapshot<TEnv = any>(
+  overrides?: Partial<RouteSnapshot<TEnv>>,
+): RouteSnapshot<TEnv> {
+  return {
+    matched: {
+      entry: {} as any,
+      routeKey: "test",
+      params: {},
+      optionalParams: new Set(),
+    } as RouteMatchResult<TEnv>,
+    manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
+    entries: [],
+    routeKey: "test",
+    localRouteName: "test",
+    params: {},
+    routeMiddleware: [],
+    cacheScope: null,
+    isPassthrough: false,
+    ...overrides,
+  };
+}

package/src/router/router-context.ts

@@ -210,6 +210,7 @@ export interface RouterContext<TEnv = any> {
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
   // Generator-based simple resolution

package/src/router/router-interfaces.ts

@@ -2,6 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
@@ -68,12 +69,24 @@ export interface RSCRouter<
   readonly id: string;
 
   /**
-   * Register routes using URL patterns from urls()
+   * URL prefix applied to all routes. Undefined when no basename is configured.
+   */
+  readonly basename: string | undefined;
+
+  /**
+   * Register routes using URL patterns from urls() or a builder function
    *
    * @example
    * ```typescript
-   * createRouter({})
-   *   .routes(urlpatterns)
+   * // With urls()
+   * createRouter({}).routes(urlpatterns)
+   *
+   * // With builder function (urls() is implicit)
+   * createRouter({}).routes(({ path, layout }) => [
+   *   layout(RootLayout, () => [
+   *     path("/", HomePage),
+   *   ]),
+   * ])
    * ```
    */
   routes<T extends UrlPatterns<TEnv, any>>(
@@ -85,6 +98,7 @@ export interface RSCRouter<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -188,8 +202,11 @@ export interface RSCRouterInternal<
    */
   readonly id: string;
 
+  /** URL prefix applied to all routes. */
+  readonly basename: string | undefined;
+
   /**
-   * Register routes using URL patterns from urls()
+   * Register routes using URL patterns from urls() or a builder function
    */
   routes<T extends UrlPatterns<TEnv, any>>(
     patterns: T,
@@ -200,6 +217,7 @@ export interface RSCRouterInternal<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -338,6 +356,9 @@ export interface RSCRouterInternal<
    */
   readonly __sourceFile?: string;
 
+  /** @internal basename for runtime manifest generation */
+  readonly __basename?: string;
+
   match(
     request: Request,
     input?: RouterRequestInput<TEnv>,
@@ -353,6 +374,8 @@ export interface RSCRouterInternal<
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: any,
+    devMode?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
     handles: Record<string, SegmentHandleData>;
@@ -371,6 +394,8 @@ export interface RSCRouterInternal<
     handler: Function,
     handlerId: string,
     routeName?: string,
+    buildEnv?: any,
+    devMode?: boolean,
   ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null>;
 
   /**
@@ -424,6 +449,13 @@ export interface RSCRouterInternal<
     segmentType?: ErrorInfo["segmentType"],
   ): Promise<MatchResult | null>;
 
+  /**
+   * Low-level route matching function.
+   * Used by classifyRequest() for request classification without
+   * entering the full match pipeline.
+   */
+  findMatch(pathname: string, metricsStore?: any): any;
+
   /**
    * Debug utility to serialize the manifest for inspection
    * Returns a JSON-friendly representation of all routes and layouts

package/src/router/router-options.ts

@@ -8,6 +8,7 @@ import type {
 import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -95,6 +96,28 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   $$sourceFile?: string;
 
+  /**
+   * URL prefix applied to all routes registered with this router.
+   *
+   * Useful when the app is served under a sub-path (e.g. `/admin` or `/v2`).
+   * All `path()` patterns are automatically prefixed and `reverse()` returns
+   * full paths including the basename. Route names are NOT prefixed.
+   *
+   * @example
+   * ```typescript
+   * const router = createRouter({
+   *   basename: "/admin",
+   * }).routes(({ path }) => [
+   *   path("/", Dashboard, { name: "home" }),       // matches /admin
+   *   path("/users", Users, { name: "users" }),     // matches /admin/users
+   * ]);
+   *
+   * router.reverse("home");   // "/admin"
+   * router.reverse("users");  // "/admin/users"
+   * ```
+   */
+  basename?: string;
+
   /**
    * Enable performance metrics collection
    * When enabled, metrics are output to console and available via Server-Timing header
@@ -337,25 +360,28 @@ export interface RSCRouterOptions<TEnv = any> {
   /**
    * URL patterns to register with the router.
    *
-   * Alternative to calling `.routes()` method - allows passing patterns
-   * directly in the config for a more concise setup.
+   * Accepts either a `UrlPatterns` object from `urls()` or a builder function
+   * directly (urls() is called implicitly).
    *
    * @example
    * ```typescript
-   * import { urls } from "@rangojs/router/server";
-   *
-   * const urlpatterns = urls(({ path, layout }) => [
-   *   path("/", HomePage, { name: "home" }),
-   *   path("/about", AboutPage, { name: "about" }),
-   * ]);
-   *
-   * const router = createRouter<AppEnv>({
+   * // With urls()
+   * createRouter<AppEnv>({
    *   document: Document,
    *   urls: urlpatterns,
    * });
+   *
+   * // With builder function
+   * createRouter<AppEnv>({
+   *   document: Document,
+   *   urls: ({ path }) => [
+   *     path("/", HomePage, { name: "home" }),
+   *     path("/about", AboutPage, { name: "about" }),
+   *   ],
+   * });
    * ```
    */
-  urls?: UrlPatterns<TEnv, any>;
+  urls?: UrlPatterns<TEnv, any> | UrlBuilder<TEnv>;
 
   /**
    * Injected by the Vite transform at compile time.

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

@@ -30,7 +30,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";
 
 // ---------------------------------------------------------------------------
 // Streamed handler telemetry
@@ -100,9 +104,7 @@ export async function resolveLoaders<TEnv>(
 
   if (!loadingDisabled) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
-    // No per-loader timing here — settlement happens asynchronously during
-    // RSC/SSR stream consumption, after the perf timeline is logged.
-    return loaderEntries.map((loaderEntry, i) => {
+    const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
       const segmentId = `${shortCode}D${i}.${loader.$$id}`;
       return {
@@ -114,7 +116,9 @@ export async function resolveLoaders<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,
@@ -122,14 +126,17 @@ export async function resolveLoaders<TEnv>(
         belongsToRoute,
       };
     });
+
+    return segments;
   }
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  // We can measure actual execution time here since we await all loaders.
   const pendingLoaderData = loaderEntries.map((loaderEntry) => {
     const start = performance.now();
-    const promise = resolveLoaderData(loaderEntry, ctx, ctx.pathname);
+    const promise = runInsideLoaderScope(() =>
+      resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+    );
     return { promise, start, loaderId: loaderEntry.loader.$$id };
   });
   await Promise.all(pendingLoaderData.map((p) => p.promise));
@@ -277,9 +284,14 @@ export async function resolveSegment<TEnv>(
       entry.shortCode,
     );
     if (component === undefined) {
+      // 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 entry.handler.
+      const handler =
+        !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
-        const result = handleHandlerResult(entry.handler(context));
+        const result = handleHandlerResult(handler(context));
         if (result instanceof Promise) {
           result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
@@ -300,7 +312,7 @@ export async function resolveSegment<TEnv>(
           component = result;
         }
       } else {
-        component = handleHandlerResult(await entry.handler(context));
+        component = handleHandlerResult(await handler(context));
         doneRouteHandler();
       }
     }
@@ -315,6 +327,7 @@ export async function resolveSegment<TEnv>(
         deps,
         options,
         routeKey,
+        entry,
       );
       segments.push(...orphanSegments);
     }
@@ -370,6 +383,9 @@ export async function resolveOrphanLayout<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   options?: ResolveSegmentOptions,
   routeKey?: string,
+  /** Parent route entry — its loaders are inherited by the layout so
+   *  parallel slots inside this layout can access them via useLoader(). */
+  parentRouteEntry?: EntryData,
 ): Promise<ResolvedSegment[]> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -385,6 +401,30 @@ export async function resolveOrphanLayout<TEnv>(
       deps,
     );
     segments.push(...loaderSegments);
+
+    // Inherit parent route's loaders so parallel slots inside this layout
+    // can access them via useLoader(). Without this, the route's loaders
+    // are only in the route's OutletProvider (rendered as <Outlet /> content),
+    // which is a child — not a parent — of the layout's context.
+    if (
+      parentRouteEntry &&
+      parentRouteEntry.loader &&
+      parentRouteEntry.loader.length > 0 &&
+      Object.keys(orphan.parallel).length > 0
+    ) {
+      const inheritedLoaders = await resolveLoaders(
+        parentRouteEntry,
+        context,
+        belongsToRoute,
+        deps,
+        orphan.shortCode,
+      );
+      // Tag as inherited so buildMatchResult can deduplicate when safe
+      for (const s of inheritedLoaders) {
+        s._inherited = true;
+      }
+      segments.push(...inheritedLoaders);
+    }
   }
 
   // Handler-first: orphan layout handler executes before its parallels
@@ -580,6 +620,13 @@ export async function resolveAllSegments<TEnv>(
   } catch {}
 
   for (const entry of entries) {
+    // Set ALS flag when entering a cache() boundary so that ctx.get()
+    // can guard non-cacheable variable reads. Also guards response-level
+    // side effects (headers.set). Persists for all descendant entries.
+    if (entry.type === "cache") {
+      const store = RSCRouterContext.getStore();
+      if (store) store.insideCacheScope = true;
+    }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
       entry,
@@ -666,6 +713,30 @@ export async function resolveLoadersOnly<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 resolveLoaders(
+          entry,
+          context,
+          childBelongsToRoute,
+          deps,
+          layoutEntry.shortCode,
+        );
+        for (const seg of inherited) {
+          if (!seenIds.has(seg.id)) {
+            seenIds.add(seg.id);
+            seg._inherited = true;
+            loaderSegments.push(seg);
+          }
+        }
+      }
     }
   }
 

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);