@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e9c0b2f2

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,7 +276,7 @@ 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),
    * ])
    *
    * // Consume in client components with useLoader()
@@ -390,18 +441,36 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
   cache: {
     (): CacheItem;
     (children: () => UseItems<AllUseItems>): CacheItem;
-    (profileName: string): CacheItem;
-    (profileName: string, use: () => UseItems<AllUseItems>): CacheItem;
     (
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use?: () => UseItems<AllUseItems>,
     ): 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
@@ -415,16 +484,19 @@ 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: {
+    (): TransitionItem;
+    (children: () => UseItems<AllUseItems>): TransitionItem;
     (config: TransitionConfig): TransitionItem;
     (
       config: TransitionConfig,

package/src/route-definition/redirect.ts

@@ -1,9 +1,9 @@
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import {
-  requireRequestContext,
   getRequestContext,
   _getRequestContext,
 } from "../server/request-context.js";
+import { markExternalRedirect } from "../redirect-origin.js";
 
 /**
  * Create a soft redirect Response for middleware short-circuit
@@ -39,6 +39,11 @@ import {
  *   status: 303,
  *   state: [Flash({ text: "Session expired" })],
  * });
+ *
+ * // Off-host redirect (opt out of the same-origin guard). Without
+ * // `external: true`, a cross-origin target is blocked and replaced with the
+ * // app root, matching the client's open-redirect protection.
+ * return redirect('https://accounts.example.com/oauth', { external: true });
  * ```
  */
 export function redirect(url: string, status?: number): Response;
@@ -47,13 +52,18 @@ export function redirect(
   options: {
     status?: number;
     state?: LocationStateEntry | LocationStateEntry[];
+    external?: boolean;
   },
 ): Response;
 export function redirect(
   url: string,
   statusOrOptions?:
     | number
-    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
+    | {
+        status?: number;
+        state?: LocationStateEntry | LocationStateEntry[];
+        external?: boolean;
+      },
 ): Response {
   const status =
     typeof statusOrOptions === "number"
@@ -61,9 +71,11 @@ export function redirect(
       : (statusOrOptions?.status ?? 302);
   const state =
     typeof statusOrOptions === "object" ? statusOrOptions?.state : undefined;
+  const external =
+    typeof statusOrOptions === "object" ? statusOrOptions?.external : undefined;
 
   if (state) {
-    const ctx = requireRequestContext();
+    const ctx = getRequestContext();
     ctx.setLocationState(state);
 
     if (process.env.NODE_ENV !== "production") {
@@ -85,17 +97,38 @@ export function redirect(
   }
 
   // Auto-prefix root-relative URLs with basename for app-local redirects.
+  // Treat the URL as already-prefixed when the basename is followed by a path
+  // separator, a query, a fragment, or end-of-string, so "/admin?tab=x" and
+  // "/admin#frag" are not double-prefixed into "/admin/admin?tab=x".
   const bn = _getRequestContext()?._basename;
   let resolvedUrl = url;
-  if (bn && url.startsWith("/") && !url.startsWith(bn + "/") && url !== bn) {
+  if (
+    bn &&
+    url.startsWith("/") &&
+    url !== bn &&
+    !url.startsWith(bn + "/") &&
+    !url.startsWith(bn + "?") &&
+    !url.startsWith(bn + "#")
+  ) {
     resolvedUrl = url === "/" ? bn : bn + url;
   }
 
-  return new Response(null, {
-    status,
-    headers: {
-      Location: resolvedUrl,
-      "X-RSC-Redirect": "soft",
-    },
-  });
+  const headers: Record<string, string> = {
+    Location: resolvedUrl,
+    "X-RSC-Redirect": "soft",
+  };
+
+  const response = new Response(null, { status, headers });
+
+  // Mark an explicit off-host redirect with an out-of-band brand so the
+  // same-origin guard (rsc/redirect-guard.ts) lets it through. The brand is a
+  // WeakSet membership on this Response object -- NOT a wire header -- so the
+  // opt-in cannot be forged by an attacker-controlled upstream response a
+  // proxy-style response route might copy. The internal redirect-rebuild paths
+  // transfer the brand; the guard reads and clears it (see markExternalRedirect).
+  if (external) {
+    markExternalRedirect(response);
+  }
+
+  return response;
 }

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

@@ -21,6 +21,10 @@ export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
   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;
@@ -99,6 +103,8 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
     "when",
     "transition",
   ]),
+  // LoaderUseItem — only revalidate + cache can attach to a loader entry
+  loader: new Set(["revalidate", "cache"]),
 };
 
 /**
@@ -133,6 +139,12 @@ export function mergeHandlerUse(
   mountSite: string,
 ): (() => any[]) | undefined {
   if (!handlerUse && !explicitUse) return undefined;
+  // Validation asymmetry (intentional, pre-1.0): only handler.use() items are
+  // checked against the mount-site allow-list (validateHandlerUseItems below).
+  // Explicit use() items pass through unvalidated on both the explicit-only
+  // branch here and the merged branch, so a structurally-valid-but-prohibited
+  // item (e.g. middleware() inside a parallel slot) is not rejected at this seam.
+  // Documented rather than enforced for now; revisit before 1.0 (#569).
   if (!handlerUse) return explicitUse;
   if (!explicitUse) {
     return () => {

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

package/src/route-map-builder.ts

@@ -8,15 +8,10 @@
  * See docs/manifests.md for the full data flow.
  */
 
-// Singleton route map instance - populated incrementally as routes are encountered
 let globalRouteMap: Record<string, string> = {};
 
-// Cached complete manifest - includes all routes (including lazy includes)
-// Set from runtime cache or build-time import
 let cachedManifest: Record<string, string> | null = null;
 
-// Pre-computed route entries from build-time prefix tree leaf nodes.
-// Used by evaluateLazyEntry() to skip running the handler for route matching.
 let cachedPrecomputedEntries: Array<{
   staticPrefix: string;
   routes: Record<string, string>;
@@ -43,7 +38,6 @@ export function registerRouteMap(map: Record<string, string>): void {
  * @internal
  */
 export function getGlobalRouteMap(): Record<string, string> {
-  // Cached manifest is complete (includes lazy routes), so prefer it
   if (cachedManifest) {
     return cachedManifest;
   }
@@ -231,10 +225,6 @@ export function waitForManifestReady(): Promise<void> | null {
   return manifestReadyPromise;
 }
 
-// ============================================================================
-// Route Scope Registry
-// ============================================================================
-
 // Tracks whether each route is at root scope (no named include boundary above).
 // Used by dot-local reverse resolution to decide whether bare-name fallback
 // is allowed after scoped lookups are exhausted.
@@ -259,14 +249,8 @@ export function isRouteRootScoped(routeName: string): boolean | undefined {
   return rootScopeRoutes.get(routeName);
 }
 
-// ============================================================================
-// Search Schema Registry
-// ============================================================================
-
 import type { SearchSchema } from "./search-params.js";
 
-// Global search schema map: route name -> search schema descriptor.
-// Populated by path() when a search option is provided.
 const globalSearchSchemas: Map<string, SearchSchema> = new Map();
 
 export function registerSearchSchema(