@rangojs/router 0.0.0-experimental.760a71d9 → 0.0.0-experimental.77ed8945

package/src/route-definition/helper-factories.ts

@@ -11,122 +11,40 @@ import {
   when,
   errorBoundary,
   notFoundBoundary,
-  loaderFn,
-  loadingFn,
-  transitionFn,
-  routeFn,
+  route,
+  loader,
+  loading,
+  transition,
 } from "./dsl-helpers.js";
 import RootLayout from "../server/root-layout";
 import { invariant } from "../errors";
 
-/*
- * Create revalidate helper
- */
-const createRevalidateHelper = <TEnv>(): RouteHelpers<
-  any,
-  TEnv
->["revalidate"] => {
-  return revalidate as RouteHelpers<any, TEnv>["revalidate"];
-};
-
-/**
- * Create errorBoundary helper
- */
-const createErrorBoundaryHelper = <TEnv>(): RouteHelpers<
-  any,
-  TEnv
->["errorBoundary"] => {
-  return errorBoundary as RouteHelpers<any, TEnv>["errorBoundary"];
-};
-
-/**
- * Create notFoundBoundary helper
- */
-const createNotFoundBoundaryHelper = <TEnv>(): RouteHelpers<
-  any,
-  TEnv
->["notFoundBoundary"] => {
-  return notFoundBoundary as RouteHelpers<any, TEnv>["notFoundBoundary"];
-};
-
 /**
- * Create middleware helper
+ * Assemble the RouteHelpers object. The helpers are the DSL functions
+ * themselves; the single cast erases the phantom generics (and the extra
+ * `route` key) that the per-router RouteHelpers<T, TEnv> type carries but the
+ * runtime functions do not.
  */
-const createMiddlewareHelper = <TEnv>(): RouteHelpers<
-  any,
+function buildRouteHelpers<T extends RouteDefinition, TEnv>(): RouteHelpers<
+  T,
   TEnv
->["middleware"] => {
-  return middleware as RouteHelpers<any, TEnv>["middleware"];
-};
-
-/**
- * Create parallel helper
- */
-const createParallelHelper = <TEnv>(): RouteHelpers<any, TEnv>["parallel"] => {
-  return parallel as RouteHelpers<any, TEnv>["parallel"];
-};
-
-/**
- * Create intercept helper
- */
-const createInterceptHelper = <
-  const T extends RouteDefinition,
-  TEnv,
->(): RouteHelpers<T, TEnv>["intercept"] => {
-  return intercept as RouteHelpers<T, TEnv>["intercept"];
-};
-
-/**
- * Create loader helper
- */
-const createLoaderHelper = <TEnv>(): RouteHelpers<any, TEnv>["loader"] => {
-  return loaderFn as RouteHelpers<any, TEnv>["loader"];
-};
-
-/**
- * Create loading helper
- */
-const createLoadingHelper = (): RouteHelpers<any, any>["loading"] => {
-  return loadingFn;
-};
-
-/**
- * Create route helper
- */
-const createRouteHelper = <
-  const T extends RouteDefinition,
-  TEnv,
->(): RouteHelpers<T, TEnv>["route"] => {
-  return routeFn as unknown as RouteHelpers<T, TEnv>["route"];
-};
-
-/**
- * Create layout helper
- */
-const createLayoutHelper = <TEnv>(): RouteHelpers<any, TEnv>["layout"] => {
-  return layout as RouteHelpers<any, TEnv>["layout"];
-};
-
-/**
- * Create when helper for intercept conditions
- */
-const createWhenHelper = (): RouteHelpers<any, any>["when"] => {
-  return when;
-};
-
-/**
- * Create cache helper for cache configuration
- */
-const createCacheHelper = (): RouteHelpers<any, any>["cache"] => {
-  return cache;
-};
-
-/**
- * Create transition helper
- */
-const createTransitionHelper = (): RouteHelpers<any, any>["transition"] => {
-  return transitionFn as RouteHelpers<any, any>["transition"];
-};
+> {
+  return {
+    route,
+    layout,
+    parallel,
+    intercept,
+    middleware,
+    revalidate,
+    loader,
+    loading,
+    errorBoundary,
+    notFoundBoundary,
+    when,
+    cache,
+    transition,
+  } as unknown as RouteHelpers<T, TEnv>;
+}
 
 /**
  * Branded type for route handlers that carries the route type info.
@@ -152,21 +70,7 @@ export function map<const T extends RouteDefinition, TEnv = DefaultEnv>(
       "map() expects a builder function as its argument",
     );
     // Create helpers
-    const helpers: RouteHelpers<T, TEnv> = {
-      route: createRouteHelper<T, TEnv>(),
-      layout: createLayoutHelper<TEnv>(),
-      parallel: createParallelHelper<TEnv>(),
-      intercept: createInterceptHelper<T, TEnv>(),
-      middleware: createMiddlewareHelper<TEnv>(),
-      revalidate: createRevalidateHelper<TEnv>(),
-      loader: createLoaderHelper<TEnv>(),
-      loading: createLoadingHelper(),
-      errorBoundary: createErrorBoundaryHelper<TEnv>(),
-      notFoundBoundary: createNotFoundBoundaryHelper<TEnv>(),
-      when: createWhenHelper(),
-      cache: createCacheHelper(),
-      transition: createTransitionHelper(),
-    };
+    const helpers = buildRouteHelpers<T, TEnv>();
 
     return [layout(RootLayout, () => builder(helpers))].flat(3);
   };
@@ -182,19 +86,5 @@ export function createRouteHelpers<
   T extends RouteDefinition,
   TEnv,
 >(): RouteHelpers<T, TEnv> {
-  return {
-    route: createRouteHelper<T, TEnv>(),
-    layout: createLayoutHelper<TEnv>(),
-    parallel: createParallelHelper<TEnv>(),
-    intercept: createInterceptHelper<T, TEnv>(),
-    middleware: createMiddlewareHelper<TEnv>(),
-    revalidate: createRevalidateHelper<TEnv>(),
-    loader: createLoaderHelper<TEnv>(),
-    loading: createLoadingHelper(),
-    errorBoundary: createErrorBoundaryHelper<TEnv>(),
-    notFoundBoundary: createNotFoundBoundaryHelper<TEnv>(),
-    when: createWhenHelper(),
-    cache: createCacheHelper(),
-    transition: createTransitionHelper(),
-  };
+  return buildRouteHelpers<T, TEnv>();
 }

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

@@ -123,7 +123,7 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   "@main": async (ctx) => <MainContent data={ctx.use(DataLoader)} />,
    * })
    *
-   * // With loaders and loading states
+   * // With loaders and loading states (broadcast to every slot)
    * parallel({
    *   "@analytics": AnalyticsPanel,
    *   "@metrics": MetricsPanel,
@@ -131,12 +131,36 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   loader(DashboardLoader),
    *   loading(<DashboardSkeleton />),
    * ])
+   *
+   * // Per-slot scoped use via slot descriptor — for single-assignment items
+   * // like loading() that should not broadcast to siblings.
+   * parallel({
+   *   "@meta": MetaSlot,
+   *   "@sidebar": {
+   *     handler: SidebarSlot,
+   *     use: () => [loading(<SidebarSkeleton />)],
+   *   },
+   * })
    * ```
    * @param slots - Object with slot names (prefixed with @) mapped to handlers
+   *                or `{ handler, use? }` slot descriptors.
    * @param use - Optional callback for loaders, loading, revalidate, etc.
+   *              Items here apply to every slot in the call (broadcast).
+   *              For per-slot single-assignment items, use the slot descriptor's
+   *              own `use` callback — slot-local items run after the broadcast,
+   *              so they take precedence on `loading()` and other last-write-wins
+   *              fields.
    */
   parallel: <
-    TSlots extends Record<`@${string}`, Handler<any, any, TEnv> | ReactNode>,
+    TSlots extends Record<
+      `@${string}`,
+      | Handler<any, any, TEnv>
+      | ReactNode
+      | {
+          handler: Handler<any, any, TEnv> | ReactNode;
+          use?: () => UseItems<ParallelUseItem>;
+        }
+    >,
   >(
     slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
@@ -174,29 +198,49 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
     // Global: unprefixed, params inferred from global route map
-    <K extends keyof RSCRouter.GeneratedRouteMap & string>(
+    <K extends keyof Rango.GeneratedRouteMap & string>(
       slotName: `@${string}`,
       routeName: K,
-      handler: ReactNode | Handler<K, RSCRouter.GeneratedRouteMap, TEnv>,
+      handler: ReactNode | Handler<K, Rango.GeneratedRouteMap, TEnv>,
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
   };
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
+   *
+   * **Sibling mode** — attaches middleware to the parent entry:
    * ```typescript
-   * middleware(async (ctx, next) => {
-   *   const session = await getSession(ctx.request);
-   *   if (!session) return redirect("/login");
-   *   ctx.set("user", session.user);
-   *   next();
-   * })
+   * layout(<DashboardShell />, () => [
+   *   middleware(authMiddleware),
+   *   middleware([authMiddleware, loggingMiddleware]),
+   *   path("/", DashboardPage),
+   * ])
+   * ```
+   *
+   * **Wrapping mode** — scopes middleware to the children only:
+   * ```typescript
+   * middleware(authMiddleware, () => [
+   *   path("/dashboard", DashboardPage),
+   *   path("/settings", SettingsPage),
+   * ])
    *
-   * // Chain multiple middleware
-   * middleware(authMiddleware, loggingMiddleware, rateLimitMiddleware)
+   * middleware([authMiddleware, loggingMiddleware], () => [
+   *   path("/admin", AdminPage),
+   * ])
    * ```
-   * @param fns - One or more middleware functions to execute in order
    */
-  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
    * ```typescript
@@ -206,8 +250,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * )
    *
    * // Revalidate after specific actions (actionId format: "path/to/file.ts#exportName")
+   * // Use `|| undefined` (defer), not `?? false` (hard short-circuit), so the
+   * // chain and the segment default still apply when there is no match.
    * revalidate(({ actionId }) =>
-   *   actionId?.includes("Cart") ?? false
+   *   actionId?.includes("Cart") || undefined
    * )
    *
    * // Soft decision (suggest but allow override)
@@ -215,7 +261,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   ({ defaultShouldRevalidate: true })
    * )
    * ```
-   * @param fn - Function that returns boolean (hard) or { defaultShouldRevalidate } (soft)
+   * @param fn - Function returning either:
+   *   - `boolean` (hard decision — short-circuits the chain),
+   *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
+   *     for downstream revalidators),
+   *   - or nothing / `null` / `undefined` (defer — leaves the suggestion
+   *     unchanged and continues to the next revalidator).
    */
   revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
   /**
@@ -225,14 +276,15 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *
    * // With loader-specific revalidation (match by file or export name)
    * loader(CartLoader, () => [
-   *   revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+   *   revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
    * ])
    *
-   * // 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 +306,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
@@ -394,10 +449,30 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
     ): CacheItem;
   };
   /**
-   * Attach a ViewTransition boundary to the current segment or a group of routes
-   *
-   * Wraps segment content with React's `<ViewTransition>` component.
-   * Only takes effect when React experimental is used (no-op on stable React).
+   * Opt a route (or group of routes) into transition-driven navigation.
+   *
+   * `transition()` does two independent things, and you choose how far to go:
+   * 1. startTransition (ALL React versions): the navigation commit is driven
+   *    through React's startTransition, so a same-route nav (same route,
+   *    different params, e.g. /product/1 -> /product/2) holds the previous
+   *    content while the new loader resolves instead of flashing the route's
+   *    loading() skeleton (see segment-system.tsx inTransitionScope). This is
+   *    also the precondition for any view-transition animation.
+   * 2. <ViewTransition> (experimental React only): the segment content is also
+   *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.
+   *    Layered on by default; pass { viewTransition: false } to keep #1 without
+   *    the router boundary (and place your own <ViewTransition> instead).
+   *
+   * A view transition cannot fire without a startTransition, so the meaningful
+   * choices are (see skills/view-transitions for the full matrix):
+   * - no transition()                         -> neither (remount + skeleton)
+   * - transition({ viewTransition: false })   -> startTransition only (hold)
+   * - transition({}) / transition({ enter… })  -> startTransition + ViewTransition
+   *
+   * Precedence: a bare transition({}) inherits createRouter({ viewTransition })
+   * (default "auto"); an explicit per-route `viewTransition` always wins. So
+   * transition({}) is startTransition + ViewTransition under the default and
+   * startTransition only when the router sets viewTransition: false.
    *
    * ```typescript
    * // Attach to a single route
@@ -411,13 +486,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   path("/about", AboutPage),
    * ])
    *
-   * // Direction-aware transitions
-   * transition({
-   *   enter: { "navigation": "slide-right", "navigation-back": "slide-left" },
-   *   exit: { "navigation": "slide-left", "navigation-back": "slide-right" },
-   * })
+   * // Hold content + drive view transitions, but place no router boundary:
+   * path("/product/:id", ProductPage, { name: "product" }, () => [
+   *   transition({ viewTransition: false }),
+   * ])
    * ```
-   * @param config - ViewTransition configuration (enter, exit, update, share, default, name)
+   * @param config - ViewTransition configuration (enter, exit, update, share,
+   *   default, name) plus `viewTransition: "auto" | false` to toggle the router
+   *   boundary (createRouter({ viewTransition }) sets the app-wide default)
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {

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,155 @@
+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;
+  }
+  // Loader definitions from createLoader() — branded objects with optional .use
+  if (typeof handler === "object" && (handler as any).__brand === "loader") {
+    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",
+  ]),
+  // LoaderUseItem — only revalidate + cache can attach to a loader entry
+  loader: new Set(["revalidate", "cache"]),
+};
+
+/**
+ * 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-definition/use-item-types.ts

@@ -0,0 +1,32 @@
+import type { AllUseItems, WhenItem } from "../route-types.js";
+
+/**
+ * The set of valid use-item `type` discriminants — the single runtime source of
+ * truth for "is this a well-formed use item?" shape validation.
+ *
+ * Declared via a `Record<...>` so that adding a member to the union without
+ * updating this map is a compile error. `when` is included because when() items
+ * are valid inside intercept() even though WhenItem is not part of AllUseItems
+ * (it lives only in InterceptUseItem). This is shape validation only; per-mount-
+ * site rules remain the narrower hand-written tables in resolve-handler-use.ts.
+ */
+const USE_ITEM_TYPES: Record<AllUseItems["type"] | WhenItem["type"], true> = {
+  layout: true,
+  route: true,
+  middleware: true,
+  revalidate: true,
+  parallel: true,
+  intercept: true,
+  loader: true,
+  loading: true,
+  errorBoundary: true,
+  notFoundBoundary: true,
+  when: true,
+  cache: true,
+  transition: true,
+  include: true,
+};
+
+export const ALL_USE_ITEM_TYPES: ReadonlySet<string> = new Set(
+  Object.keys(USE_ITEM_TYPES),
+);