@rangojs/router 0.0.0-experimental.fa8a383a → 0.0.0-experimental.fb6e2f40

package/src/route-definition/dsl-helpers.ts

@@ -37,6 +37,7 @@ import type {
   UseItems,
 } from "../route-types.js";
 import type { RouteHelpers } from "./helpers-types.js";
+import { resolveHandlerUse, mergeHandlerUse } from "./resolve-handler-use.js";
 
 /**
  * Check if an item contains routes (directly or inside nested structures like cache).
@@ -447,15 +448,6 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
       : {}),
   } satisfies EntryData;
 
-  // Run use callback if provided to collect loaders, revalidate, loading
-  if (use && typeof use === "function") {
-    const result = store.run(namespace, entry, use)?.flat(3);
-    invariant(
-      Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-      `parallel() use() callback must return an array of use items [${namespace}]`,
-    );
-  }
-
   for (const slotName of slotNames) {
     const slotEntry = {
       ...entry,
@@ -478,6 +470,22 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
             staticHandlerIds: undefined,
           }),
     } satisfies EntryData;
+
+    // Per-slot: handler.use defaults first, then explicit use second.
+    // This matches the "defaults first, overrides second" rule used by
+    // path(), layout(), and intercept(). Each slot's handler.use is
+    // scoped to its own entry (no cross-slot bleed).
+    const slotHandler = (slots as Record<string, any>)[slotName];
+    const slotHandlerUse = resolveHandlerUse(slotHandler);
+    const slotMergedUse = mergeHandlerUse(slotHandlerUse, use, "parallel");
+    if (slotMergedUse) {
+      const result = store.run(namespace, slotEntry, slotMergedUse)?.flat(3);
+      invariant(
+        Array.isArray(result) && result.every((item) => isValidUseItem(item)),
+        `parallel() use() callback must return an array of use items [${namespace}]`,
+      );
+    }
+
     ctx.parent.parallel[slotName] = slotEntry;
   }
   return { name: namespace, type: "parallel" } as ParallelItem;
@@ -527,8 +535,12 @@ const intercept = (
     when: [], // Selector conditions for conditional interception
   };
 
-  // Run use callback if provided to collect loaders, revalidate, middleware, etc.
-  if (use && typeof use === "function") {
+  // Merge handler.use defaults with explicit use
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "intercept");
+
+  // Run merged use callback to collect loaders, revalidate, middleware, etc.
+  if (mergedUse) {
     // Create a temporary parent context for the use() callback
     // so that middleware, loader, revalidate attach to the intercept entry
     const originalParent = ctx.parent;
@@ -555,7 +567,7 @@ const intercept = (
     };
     ctx.parent = tempParent as EntryData;
 
-    const result = use()?.flat(3);
+    const result = mergedUse()?.flat(3);
 
     // Restore original parent
     ctx.parent = originalParent;
@@ -652,11 +664,15 @@ const loadingFn: RouteHelpers<any, any>["loading"] = (component, options) => {
     invariant(false, "No parent entry available for loading()");
   }
 
+  // Unwrap function form: loading(() => <Skeleton />) → loading(<Skeleton />)
+  const resolved =
+    typeof component === "function" ? (component as () => any)() : component;
+
   // If ssr: false and we're in SSR, set loading to false
   if (options?.ssr === false && ctx.isSSR) {
     parent.loading = false;
   } else {
-    parent.loading = component;
+    parent.loading = resolved;
   }
 
   const name = `$${store.getNextIndex("loading")}`;
@@ -752,7 +768,7 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
     shortCode: store.getShortCode("route"),
     type: "route",
     parent: ctx.parent,
-    handler,
+    handler: handler as unknown as Handler<any, any, any>,
     loading: undefined, // Allow loading() to attach loading state
     middleware: [],
     revalidate: [],
@@ -771,9 +787,12 @@ const routeFn: RouteHelpers<any, any>["route"] = (name, handler, use) => {
   );
   /* Register route entry */
   ctx.manifest.set(name, entry);
+  /* Merge handler.use defaults with explicit use */
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "route");
   /* Run use and attach handlers */
-  if (use && typeof use === "function") {
-    const result = store.run(namespace, entry, use)?.flat(3);
+  if (mergedUse) {
+    const result = store.run(namespace, entry, mergedUse)?.flat(3);
     invariant(
       Array.isArray(result) && result.every((item) => isValidUseItem(item)),
       `route() use() callback must return an array of use items [${namespace}]`,
@@ -834,10 +853,14 @@ const layout: RouteHelpers<any, any>["layout"] = (handler, use) => {
     (handler as any).$$routePrefix = ctx.namePrefix;
   }
 
-  // Run use callback if provided
+  // Merge handler.use defaults with explicit use
+  const handlerUseFn = resolveHandlerUse(handler);
+  const mergedUse = mergeHandlerUse(handlerUseFn, use, "layout");
+
+  // Run merged use callback if present
   let result: AllUseItems[] | undefined;
-  if (use && typeof use === "function") {
-    result = store.run(namespace, entry, use)?.flat(3);
+  if (mergedUse) {
+    result = store.run(namespace, entry, mergedUse)?.flat(3);
 
     invariant(
       Array.isArray(result) && result.every((item) => isValidUseItem(item)),

package/src/route-definition/helpers-types.ts

@@ -228,11 +228,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
    * ])
    *
-   * // Access loader data in handlers via ctx.use()
-   * route("products.detail", async (ctx) => {
-   *   const product = await ctx.use(ProductLoader);
-   *   return <ProductPage product={product} />;
-   * })
+   * // Consume in client components with useLoader()
+   * // (preferred — cache-safe, always fresh)
+   * function ProductDetails() {
+   *   const { data } = useLoader(ProductLoader);
+   *   return <div>{data.name}</div>;
+   * }
    * ```
    * @param loaderDef - Loader created with createLoader()
    * @param use - Optional callback for loader-specific revalidation rules
@@ -254,7 +255,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * @param options - Configuration options
    * @param options.ssr - If false, skip showing loading on document requests (SSR)
    */
-  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 and children
    * ```typescript

package/src/route-definition/index.ts

@@ -45,6 +45,9 @@ export {
   type RouteHandlers,
 } from "./helper-factories.js";
 
+// Handler use resolver
+export { resolveHandlerUse } from "./resolve-handler-use.js";
+
 // Redirect
 export { redirect } from "./redirect.js";
 

package/src/route-definition/redirect.ts

@@ -2,6 +2,7 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
 import {
   requireRequestContext,
   getRequestContext,
+  _getRequestContext,
 } from "../server/request-context.js";
 
 /**
@@ -83,10 +84,17 @@ export function redirect(
     }
   }
 
+  // Auto-prefix root-relative URLs with basename for app-local redirects.
+  const bn = _getRequestContext()?._basename;
+  let resolvedUrl = url;
+  if (bn && url.startsWith("/") && !url.startsWith(bn + "/") && url !== bn) {
+    resolvedUrl = url === "/" ? bn : bn + url;
+  }
+
   return new Response(null, {
     status,
     headers: {
-      Location: url,
+      Location: resolvedUrl,
       "X-RSC-Redirect": "soft",
     },
   });

package/src/route-definition/resolve-handler-use.ts

@@ -0,0 +1,149 @@
+import type { AllUseItems } from "../route-types.js";
+import { isPrerenderHandler, isPassthroughHandler } from "../prerender.js";
+import { isStaticHandler } from "../static-handler.js";
+
+/**
+ * Extract the .use callback from any handler shape.
+ *
+ * Checks definition brands first (objects with __brand), then plain functions.
+ * ReactNode handlers return undefined (no .use possible).
+ */
+export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
+  if (handler == null) return undefined;
+
+  // Check branded definitions first — they're objects but also have typeof "object"
+  if (isPassthroughHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isPrerenderHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isStaticHandler(handler)) {
+    return (handler as any).use;
+  }
+  // Plain handler function
+  if (typeof handler === "function") {
+    return (handler as any).use;
+  }
+  // ReactNode or other — no .use
+  return undefined;
+}
+
+/**
+ * Allowed item types per mount site.
+ * Mirrors the RouteUseItem / ParallelUseItem / InterceptUseItem / LayoutUseItem unions
+ * from route-types.ts for runtime validation.
+ */
+const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
+  path: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // Response routes (path.json, path.text, etc.) — mirrors ResponseRouteUseItem
+  response: new Set(["middleware", "cache"]),
+  route: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // layout allows AllUseItems — no validation needed, but included for completeness
+  layout: new Set([
+    "layout",
+    "route",
+    "middleware",
+    "revalidate",
+    "parallel",
+    "intercept",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+    "include",
+  ]),
+  parallel: new Set([
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "transition",
+  ]),
+  intercept: new Set([
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "layout",
+    "route",
+    "when",
+    "transition",
+  ]),
+};
+
+/**
+ * Validate that items from handler.use() are valid for the given mount site.
+ * Throws a descriptive error if any item is not allowed.
+ */
+export function validateHandlerUseItems(
+  items: AllUseItems[],
+  mountSite: string,
+): void {
+  const allowed = MOUNT_SITE_ALLOWED_TYPES[mountSite];
+  if (!allowed) return;
+  for (const item of items) {
+    if (item == null) continue;
+    if (!allowed.has((item as any).type)) {
+      throw new Error(
+        `handler.use() returned ${(item as any).type}() which is not valid inside ${mountSite}(). ` +
+          `Allowed types: ${[...allowed].join(", ")}.`,
+      );
+    }
+  }
+}
+
+/**
+ * Create a merged use callback from handler.use and explicit use.
+ * handler.use items come first (defaults), explicit items second (overrides).
+ * Returns undefined if both are absent.
+ */
+export function mergeHandlerUse(
+  handlerUse: (() => any[]) | undefined,
+  explicitUse: (() => any[]) | undefined,
+  mountSite: string,
+): (() => any[]) | undefined {
+  if (!handlerUse && !explicitUse) return undefined;
+  if (!handlerUse) return explicitUse;
+  if (!explicitUse) {
+    return () => {
+      const items = handlerUse().flat(3);
+      validateHandlerUseItems(items, mountSite);
+      return items;
+    };
+  }
+  return () => {
+    const hItems = handlerUse().flat(3);
+    validateHandlerUseItems(hItems, mountSite);
+    return [...hItems, ...explicitUse()];
+  };
+}

package/src/route-types.ts

@@ -257,3 +257,14 @@ export type LoaderUseItem = RevalidateItem | CacheItem;
  * runtime via .flat(3).
  */
 export type UseItems<T> = (T | readonly T[])[];
+
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem =
+  | RouteUseItem
+  | LayoutUseItem
+  | ParallelUseItem
+  | InterceptUseItem;

package/src/router/content-negotiation.ts

@@ -2,10 +2,18 @@
  * Content Negotiation Utilities
  *
  * Pure functions for HTTP Accept header parsing and response type matching.
- * Used by createRouter's previewMatch for content negotiation between
+ * Used by previewMatch and classifyRequest for content negotiation between
  * RSC routes and response routes (JSON, text, image, stream, etc.).
  */
 
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import { loadManifest } from "./manifest.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouteSnapshot } from "./route-snapshot.js";
+
 // Response type -> MIME type used for Accept header matching
 export const RESPONSE_TYPE_MIME: Record<string, string> = {
   json: "application/json",
@@ -114,3 +122,94 @@ export function pickNegotiateVariant(
   // No match -- use first candidate as default
   return candidates[0]!;
 }
+
+/**
+ * Result of content negotiation for a route with negotiate variants.
+ */
+export interface NegotiationResult {
+  /** The winning response type */
+  responseType: string;
+  /** Handler function for the winning variant */
+  handler: Function;
+  /** Manifest entry for the winning variant (may differ from primary) */
+  manifestEntry: EntryData;
+  /** Route middleware for the winning variant */
+  routeMiddleware: CollectedMiddleware[];
+  /** Always true — negotiation occurred */
+  negotiated: true;
+}
+
+/**
+ * Perform content negotiation for a route with negotiate variants.
+ *
+ * Returns a NegotiationResult when a response route wins negotiation.
+ * Returns null when RSC wins or no negotiation is needed.
+ *
+ * Shared by previewMatch and classifyRequest to avoid duplicating
+ * the candidate-building and variant-loading logic.
+ */
+export async function negotiateRoute(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot,
+): Promise<NegotiationResult | null> {
+  const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
+  if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    return null;
+  }
+
+  const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
+
+  // Build candidate list preserving definition order.
+  const variants = matched.negotiateVariants;
+  let candidates: Array<{ routeKey: string; responseType: string }>;
+  if (responseType) {
+    candidates = [...variants, { routeKey: matched.routeKey, responseType }];
+  } else {
+    const rscCandidate = {
+      routeKey: matched.routeKey,
+      responseType: RSC_RESPONSE_TYPE,
+    };
+    candidates = matched.rscFirst
+      ? [rscCandidate, ...variants]
+      : [...variants, rscCandidate];
+  }
+
+  const variant = pickNegotiateVariant(acceptEntries, candidates);
+
+  // RSC won negotiation
+  if (variant.responseType === RSC_RESPONSE_TYPE) {
+    return null;
+  }
+
+  // Primary response-type won — use existing manifest entry and middleware
+  if (responseType && variant.routeKey === matched.routeKey) {
+    return {
+      responseType,
+      handler: manifestEntry.handler as Function,
+      manifestEntry,
+      routeMiddleware,
+      negotiated: true,
+    };
+  }
+
+  // Different variant won — load its manifest entry
+  const negotiateEntry = await loadManifest(
+    matched.entry,
+    variant.routeKey,
+    pathname,
+    undefined,
+    false,
+  );
+  const variantMiddleware = collectRouteMiddleware(
+    traverseBack(negotiateEntry),
+    matched.params,
+  );
+  return {
+    responseType: variant.responseType,
+    handler: negotiateEntry.handler as Function,
+    manifestEntry: negotiateEntry,
+    routeMiddleware: variantMiddleware,
+    negotiated: true,
+  };
+}