@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -8,125 +8,41 @@ import {
   revalidate,
   parallel,
   intercept,
-  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,
+    cache,
+    transition,
+  } as unknown as RouteHelpers<T, TEnv>;
+}
 
 /**
  * Branded type for route handlers that carries the route type info.
@@ -152,21 +68,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 +84,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

@@ -29,12 +29,11 @@ import type {
   ParallelUseItem,
   InterceptUseItem,
   LoaderUseItem,
-  WhenItem,
   CacheItem,
   TransitionItem,
   UseItems,
 } from "../route-types.js";
-import type { InterceptWhenFn } from "../server/context";
+import type { StaticHandlerRef } from "../static-handler.js";
 
 // Re-export route item types for backward compatibility
 export type {
@@ -52,12 +51,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,
@@ -142,8 +141,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   },
    * })
    * ```
-   * @param slots - Object with slot names (prefixed with @) mapped to handlers
-   *                or `{ handler, use? }` slot descriptors.
+   * @param slots - Object with slot names (prefixed with @) mapped to handlers,
+   *                Static() definitions, or `{ handler, use? }` 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
@@ -151,18 +150,20 @@ 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
+      | StaticHandlerRef
       | {
-          handler: Handler<any, any, TEnv> | ReactNode;
+          handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
           use?: () => UseItems<ParallelUseItem>;
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
   ) => ParallelItem;
   /**
@@ -183,10 +184,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,13 +212,19 @@ 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
-    <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>,
+      config?:
+        | import("../server/context.js").InterceptConfig<TEnv>
+        | (() => UseItems<InterceptUseItem>),
       use?: () => UseItems<InterceptUseItem>,
     ): InterceptItem;
   };
@@ -250,8 +273,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)
@@ -259,7 +284,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;
   /**
@@ -269,7 +299,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()
@@ -340,40 +370,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
    *
@@ -434,18 +430,43 @@ 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.
+   *
+   * Conditional hold: pass `when: (ctx) => boolean` to gate the transition per
+   * request. It normally runs server-side after the route handler. On a `ppr`
+   * route it is automatically hoisted before route handlers and reevaluated on
+   * every replay, so it may read URL/params/action/env and middleware-set context
+   * but not handler-set context. Returning false drops this transition for the
+   * request. This is distinct from intercept()'s match-time `when` selector.
    *
    * ```typescript
    * // Attach to a single route
@@ -459,16 +480,25 @@ 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 }),
+   * ])
+   *
+   * // 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)
+   * @param config - ViewTransition configuration (enter, exit, update, share,
+   *   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
    * @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

@@ -0,0 +1,29 @@
+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. 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"], true> = {
+  layout: true,
+  route: true,
+  middleware: true,
+  revalidate: true,
+  parallel: true,
+  intercept: true,
+  loader: true,
+  loading: true,
+  errorBoundary: true,
+  notFoundBoundary: true,
+  cache: true,
+  transition: true,
+  include: true,
+};
+
+export const ALL_USE_ITEM_TYPES: ReadonlySet<string> = new Set(
+  Object.keys(USE_ITEM_TYPES),
+);