@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

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

@@ -17,8 +17,10 @@ import {
   type EntryPropSegments,
   type HelperContext,
   type InterceptEntry,
+  type InterceptConfig,
 } from "../server/context";
 import { invariant } from "../errors";
+import { validateUserRouteName } from "../route-name.js";
 import { isCachedFunction } from "../cache/taint.js";
 import { RangoContext } from "../server/context";
 import { isStaticHandler } from "../static-handler.js";
@@ -35,7 +37,6 @@ import type {
   ErrorBoundaryItem,
   NotFoundBoundaryItem,
   LayoutItem,
-  WhenItem,
   CacheItem,
   TransitionItem,
   UseItems,
@@ -264,34 +265,6 @@ const notFoundBoundary: RouteHelpers<any, any>["notFoundBoundary"] = (
   return { name, type: "notFoundBoundary" } as NotFoundBoundaryItem;
 };
 
-/**
- * When helper - defines a condition for intercept activation
- *
- * Only valid inside intercept() use() callback. The when() function
- * is captured by the intercept and stored in its `when` array.
- * During soft navigation, all when() conditions must return true
- * for the intercept to activate.
- */
-const when: RouteHelpers<any, any>["when"] = (fn) => {
-  const { store, ctx } = requireDslContext(
-    "when() must be called inside intercept()",
-  );
-
-  // The when() function needs to be captured by the intercept's tempParent
-  // which should have a `when` array. If not present, we're not inside intercept()
-  const parent = ctx.parent as any;
-  if (!parent || !("when" in parent)) {
-    invariant(
-      false,
-      "when() can only be used inside intercept() use() callback",
-    );
-  }
-
-  const name = `$${store.getNextIndex("when")}`;
-  parent.when.push(fn);
-  return { name, type: "when" } as WhenItem;
-};
-
 /**
  * Cache helper - defines caching configuration for segments
  *
@@ -302,15 +275,15 @@ const when: RouteHelpers<any, any>["when"] = (fn) => {
  * Supports these call signatures:
  * - cache() - no args, uses app-level defaults (for loader caching)
  * - cache(() => [...]) - wraps children with app-level defaults
- * - cache('profileName') - uses a named cache profile
- * - cache('profileName', () => [...]) - named profile with children
  * - cache({ ttl: 60 }, () => [...]) - with explicit options
+ *
+ * Named cache profiles are applied via the `"use cache: <profile>"` directive,
+ * not a `cache("profileName")` form in the route tree.
  */
 const cache: RouteHelpers<any, any>["cache"] = (
   optionsOrChildren?:
     | PartialCacheOptions
     | false
-    | string
     | (() => UseItems<AllUseItems>),
   maybeChildren?: () => UseItems<AllUseItems>,
 ) => {
@@ -326,18 +299,6 @@ const cache: RouteHelpers<any, any>["cache"] = (
     // cache() - no args, use defaults
     options = {};
     children = undefined;
-  } else if (typeof optionsOrChildren === "string") {
-    // cache('profileName') or cache('profileName', () => [...])
-    // Resolve from context-scoped profiles (set per-router via HelperContext).
-    const ctxStore = RangoContext.getStore();
-    const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
-    invariant(
-      profile,
-      `cache("${optionsOrChildren}"): unknown cache profile. ` +
-        `Define it in createRouter({ cacheProfiles: { "${optionsOrChildren}": { ttl: ... } } }).`,
-    );
-    options = { ttl: profile.ttl, swr: profile.swr, tags: profile.tags };
-    children = maybeChildren;
   } else if (typeof optionsOrChildren === "function") {
     // cache(() => [...]) - use empty options (will use defaults)
     options = {};
@@ -393,10 +354,10 @@ const cache: RouteHelpers<any, any>["cache"] = (
     return { name: namespace, type: "cache" } as CacheItem;
   }
 
-  // Inside a loader() use() callback, only the direct form — cache()/cache(opts)/
-  // cache("profile") — writes cache config to the loader entry. The wrapper
-  // form creates a structural cache boundary with its own children scope, which
-  // has no effect on the loader and would silently no-op.
+  // Inside a loader() use() callback, only the direct form — cache()/cache(opts)
+  // — writes cache config to the loader entry. The wrapper form creates a
+  // structural cache boundary with its own children scope, which has no effect
+  // on the loader and would silently no-op.
   invariant(
     !(ctx.parent && (ctx.parent as any).type === "loader"),
     "cache() wrapper form is not valid inside loader() use(). Use cache({...}) without children to configure the loader's cache.",
@@ -536,6 +497,22 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
   } as MiddlewareItem;
 };
 
+// Slot names become part of segment ids: a parallel/intercept slot is encoded
+// as `${shortCode}.${slotName}`, and loader segments append `D${index}.${loaderId}`.
+// A "." in the slot name collides with that separator -- loaderParentId
+// (segment-system.tsx) strips from the FIRST `D<index>.`, so a name like
+// "@D3.foo" is mis-cut to "@" and the loader's data is silently dropped. Reject
+// the dot at definition time so the failure is loud, not a corrupted tree at
+// runtime. (A bare "D" without a trailing dot -- e.g. "@Detail" -- is fine.)
+function assertValidSlotName(slotName: string): void {
+  invariant(
+    !slotName.includes("."),
+    `Slot name "${slotName}" must not contain ".". The dot is a reserved ` +
+      `segment-id separator; a name like "@D3.foo" corrupts loader segment-id ` +
+      `parsing and silently drops the loader's data. Rename the slot.`,
+  );
+}
+
 const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   const { store, ctx } = requireDslContext(
     "parallel() must be called inside urls()",
@@ -551,6 +528,7 @@ const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {
   );
 
   const slotNames = Object.keys(slots as Record<string, any>) as `@${string}`[];
+  for (const slotName of slotNames) assertValidSlotName(slotName);
 
   const namespace = `${ctx.namespace}.$${store.getNextIndex("parallel")}`;
 
@@ -695,8 +673,19 @@ const intercept = (
   slotName: `@${string}`,
   routeName: string,
   handler: any,
+  configOrUse?: InterceptConfig | (() => any[]),
   use?: () => any[],
 ) => {
+  // arg4 discrimination: a function is the use() callback (no config); an object
+  // is the config carrying `when`. With config given, the use() callback is
+  // arg5. Keeps the no-config form intercept(slot, route, handler, () => [...])
+  // working unchanged.
+  const config: InterceptConfig | undefined =
+    typeof configOrUse === "function" || configOrUse == null
+      ? undefined
+      : configOrUse;
+  const useFn = typeof configOrUse === "function" ? configOrUse : use;
+
   const { store, ctx } = requireDslContext(
     "intercept() must be called inside urls()",
   );
@@ -710,6 +699,8 @@ const intercept = (
     "intercept() cannot be used inside parallel()",
   );
 
+  assertValidSlotName(slotName);
+
   const namespace = `${ctx.namespace}.$${store.getNextIndex("intercept")}.${slotName}`;
 
   // Dot-prefixed = local (add include prefix), unprefixed = global (use as-is)
@@ -732,9 +723,17 @@ const intercept = (
     when: [], // Selector conditions for conditional interception
   };
 
+  // Conditional interception: `when` from the config object — a single selector
+  // or an array (ALL must return true to activate). Replaces the former when()
+  // use-item captured inside the callback.
+  if (config?.when) {
+    const selectors = Array.isArray(config.when) ? config.when : [config.when];
+    entry.when.push(...selectors);
+  }
+
   // Merge handler.use defaults with explicit use
   const handlerUseFn = resolveHandlerUse(handler);
-  const mergedUse = mergeHandlerUse(handlerUseFn, use, "intercept");
+  const mergedUse = mergeHandlerUse(handlerUseFn, useFn, "intercept");
 
   // Run merged use callback to collect loaders, revalidate, middleware, etc.
   if (mergedUse) {
@@ -751,7 +750,6 @@ const intercept = (
       notFoundBoundary: entry.notFoundBoundary,
       loader: entry.loader,
       layout: capturedLayouts, // Capture layout() calls
-      when: entry.when, // Capture when() conditions
       get loading() {
         return entry.loading;
       },
@@ -890,7 +888,11 @@ const transition = (
     "transition() must be called inside urls()",
   );
 
-  const name = `$${store.getNextIndex("transition")}`;
+  // Allocate a single index for this transition() call (used in all paths),
+  // mirroring cache() — the child form uses it for the name, the wrapper form
+  // reuses it for the namespace, so no index is burned.
+  const transitionIndex = store.getNextIndex("transition");
+  const name = `$${transitionIndex}`;
 
   if (!children) {
     // Position 1: child of path() — attach to parent entry
@@ -903,7 +905,7 @@ const transition = (
   }
 
   // Position 2: wrapper — create a transparent layout with transition config
-  const namespace = `${ctx.namespace}.${store.getNextIndex("transition")}`;
+  const namespace = `${ctx.namespace}.${transitionIndex}`;
   const entry = {
     ...emptySegmentBase(),
     id: namespace,
@@ -933,6 +935,12 @@ const route: RouteHelpers<any, any>["route"] = (name, handler, use) => {
     "route() must be called inside urls()",
   );
 
+  // Reject names colliding with reserved internal prefixes ($path_, $prefix_),
+  // the same guard path() and include() enforce. Without it such a name
+  // type-checks on an untyped router, then silently vanishes from generated
+  // route-types and public reverse() (isAutoGeneratedRouteName filters it out).
+  validateUserRouteName(name);
+
   const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${name}`;
 
   const entry = {
@@ -1096,7 +1104,6 @@ export {
   revalidate,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
   route,

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

@@ -8,7 +8,6 @@ import {
   revalidate,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
   route,
@@ -40,7 +39,6 @@ function buildRouteHelpers<T extends RouteDefinition, TEnv>(): RouteHelpers<
     loading,
     errorBoundary,
     notFoundBoundary,
-    when,
     cache,
     transition,
   } as unknown as RouteHelpers<T, TEnv>;

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

@@ -29,12 +29,10 @@ import type {
   ParallelUseItem,
   InterceptUseItem,
   LoaderUseItem,
-  WhenItem,
   CacheItem,
   TransitionItem,
   UseItems,
 } from "../route-types.js";
-import type { InterceptWhenFn } from "../server/context";
 
 // Re-export route item types for backward compatibility
 export type {
@@ -52,12 +50,12 @@ export type {
   RouteUseItem,
   ParallelUseItem,
   InterceptUseItem,
-  WhenItem,
   CacheItem,
 } from "../route-types.js";
 
 // Re-export intercept selector types for use in handlers
 export type {
+  InterceptConfig,
   InterceptSelectorContext,
   InterceptSegmentsState,
   InterceptWhenFn,
@@ -151,8 +149,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *              so they take precedence on `loading()` and other last-write-wins
    *              fields.
    */
-  parallel: <
-    TSlots extends Record<
+  // Not generic over the slots record: an inferred type parameter makes the
+  // object literal an inference site, which suppresses contextual typing of
+  // arrow slot handlers (`(ctx) => ...` was implicit any).
+  parallel: (
+    slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
@@ -161,8 +162,6 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
           use?: () => UseItems<ParallelUseItem>;
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
   ) => ParallelItem;
   /**
@@ -183,10 +182,26 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   loader(CardModalLoader),
    *   revalidate(() => false),
    * ])
+   *
+   * // Conditional activation via the config object's `when` selector
+   * intercept("@modal", "card", <CardModal />, {
+   *   when: ({ from }) => from.pathname.startsWith("/board"),
+   * })
+   *
+   * // Config + other use-items: config is arg 4, use is arg 5
+   * intercept(
+   *   "@modal",
+   *   "card",
+   *   <CardModal />,
+   *   { when: ({ from }) => from.pathname.startsWith("/board") },
+   *   () => [loader(CardDetailLoader)],
+   * )
    * ```
    * @param slotName - Named slot (prefixed with @) where intercept renders
    * @param routeName - Route name to intercept
    * @param handler - Component or handler for intercepted render
+   * @param config - Optional InterceptConfig (e.g. `{ when }`), or the use
+   *   callback directly when there is no config
    * @param use - Optional callback for loaders, middleware, revalidate, etc.
    */
   intercept: {
@@ -195,6 +210,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
       slotName: `@${string}`,
       routeName: `.${K}`,
       handler: ReactNode | Handler<ExtractRouteParams<T, K>, {}, TEnv>,
+      config?:
+        | import("../server/context.js").InterceptConfig<TEnv>
+        | (() => UseItems<InterceptUseItem>),
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
     // Global: unprefixed, params inferred from global route map
@@ -202,6 +220,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
       slotName: `@${string}`,
       routeName: K,
       handler: ReactNode | Handler<K, Rango.GeneratedRouteMap, TEnv>,
+      config?:
+        | import("../server/context.js").InterceptConfig<TEnv>
+        | (() => UseItems<InterceptUseItem>),
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
   };
@@ -347,40 +368,6 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
   notFoundBoundary: (
     fallback: ReactNode | NotFoundBoundaryHandler,
   ) => NotFoundBoundaryItem;
-  /**
-   * Define a condition for when an intercept should activate
-   *
-   * Only valid inside intercept() use() callback. When multiple when() calls
-   * are present, ALL must return true for the intercept to activate.
-   * If no when() is defined, the intercept always activates on soft navigation.
-   *
-   * Context properties:
-   * - `from` - Source URL (where user is navigating from)
-   * - `to` - Destination URL (where user is navigating to)
-   * - `params` - Matched route params
-   * - `segments` - Client's current segments with `path` and `ids`
-   *
-   * ```typescript
-   * // Only intercept when coming from the board page
-   * intercept("@modal", "card", <CardModal />, () => [
-   *   when(({ from }) => from.pathname.startsWith("/board")),
-   *   loader(CardDetailLoader),
-   * ])
-   *
-   * // Use segments to check current route context
-   * intercept("@modal", "card", <CardModal />, () => [
-   *   when(({ segments }) => segments.path[0] === "kanban"),
-   * ])
-   *
-   * // Multiple conditions (AND logic)
-   * intercept("@modal", "card", <CardModal />, () => [
-   *   when(({ from }) => from.pathname.startsWith("/board")),
-   *   when(({ segments }) => segments.ids.includes("kanban-layout")),
-   * ])
-   * ```
-   * @param fn - Selector function receiving navigation context, returns boolean
-   */
-  when: (fn: InterceptWhenFn) => WhenItem;
   /**
    * Define cache configuration for segments
    *
@@ -441,10 +428,8 @@ 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;
   };
@@ -474,6 +459,13 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * transition({}) is startTransition + ViewTransition under the default and
    * startTransition only when the router sets viewTransition: false.
    *
+   * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
+   * request. It runs server-side AFTER the route handler (so it can read state
+   * the handler set via `ctx.get(...)`); returning false drops this transition
+   * for the request, so the navigation streams its loading() skeleton instead of
+   * holding. This is a post-handler predicate — distinct from intercept()'s
+   * match-time `when` config selector (`intercept(slot, route, Comp, { when })`).
+   *
    * ```typescript
    * // Attach to a single route
    * path("/about", AboutPage, { name: "about" }, () => [
@@ -490,13 +482,21 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    * path("/product/:id", ProductPage, { name: "product" }, () => [
    *   transition({ viewTransition: false }),
    * ])
+   *
+   * // Hold only when the handler decided to (post-handler predicate):
+   * path("/product/:id", ProductPage, { name: "product" }, () => [
+   *   transition({ when: (ctx) => ctx.get(KeepScroll) === true }),
+   * ])
    * ```
    * @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)
+   *   default, name), `viewTransition: "auto" | false` to toggle the router
+   *   boundary (createRouter({ viewTransition }) sets the app-wide default), and
+   *   `when: (ctx) => boolean` to gate the transition per request post-handler
    * @param children - Optional callback returning child routes to wrap
    */
   transition: {
+    (): TransitionItem;
+    (children: () => UseItems<AllUseItems>): TransitionItem;
     (config: TransitionConfig): TransitionItem;
     (
       config: TransitionConfig,

package/src/route-definition/index.ts

@@ -15,8 +15,8 @@ export type {
   RouteUseItem,
   ParallelUseItem,
   InterceptUseItem,
-  WhenItem,
   CacheItem,
+  InterceptConfig,
   InterceptSelectorContext,
   InterceptSegmentsState,
   InterceptWhenFn,
@@ -30,7 +30,6 @@ export {
   revalidate,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
   loader,

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

@@ -100,7 +100,6 @@ const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
     "notFoundBoundary",
     "layout",
     "route",
-    "when",
     "transition",
   ]),
   // LoaderUseItem — only revalidate + cache can attach to a loader entry
@@ -139,6 +138,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

@@ -1,16 +1,14 @@
-import type { AllUseItems, WhenItem } from "../route-types.js";
+import type { AllUseItems } 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-
+ * updating this map is a compile error. 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> = {
+const USE_ITEM_TYPES: Record<AllUseItems["type"], true> = {
   layout: true,
   route: true,
   middleware: true,
@@ -21,7 +19,6 @@ const USE_ITEM_TYPES: Record<AllUseItems["type"] | WhenItem["type"], true> = {
   loading: true,
   errorBoundary: true,
   notFoundBoundary: true,
-  when: true,
   cache: true,
   transition: true,
   include: true,