@rangojs/router 0.0.0-experimental.133 → 0.0.0-experimental.134

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,

package/src/route-types.ts

@@ -98,10 +98,6 @@ export type NotFoundBoundaryItem = {
   type: "notFoundBoundary";
   uses?: AllUseItems[];
 };
-export type WhenItem = {
-  name: string;
-  type: "when";
-};
 export type CacheItem = {
   name: string;
   type: "cache";
@@ -231,7 +227,6 @@ export type InterceptUseItem =
   | NotFoundBoundaryItem
   | LayoutItem
   | RouteItem
-  | WhenItem
   | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
 

package/src/router/match-api.ts

@@ -287,7 +287,11 @@ export async function createMatchContextForPartial<TEnv>(
     });
   }
 
-  setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
+  setRequestContextPrevRouteKey(
+    nav.effectiveFromMatch?.routeKey,
+    nav.effectiveFromUrl,
+    nav.effectiveFromMatch?.params ?? nav.prevParams,
+  );
 
   const interceptSelectorContext: InterceptSelectorContext = {
     from: nav.effectiveFromUrl,

package/src/router/segment-resolution/fresh.ts

@@ -202,6 +202,7 @@ export async function resolveSegment<TEnv>(
       transition: applyViewTransitionDefault(
         entry.transition,
         deps.viewTransitionDefault,
+        entry.shortCode,
       ),
       params,
       belongsToRoute: false,
@@ -345,6 +346,7 @@ export async function resolveSegment<TEnv>(
       transition: applyViewTransitionDefault(
         entry.transition,
         deps.viewTransitionDefault,
+        entry.shortCode,
       ),
       params,
       belongsToRoute: true,
@@ -432,6 +434,7 @@ export async function resolveOrphanLayout<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
+      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
@@ -565,6 +568,7 @@ export async function resolveParallelEntry<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
+        `${parentShortCode}.${slot}`,
       ),
       params,
       slot,

package/src/router/segment-resolution/revalidation.ts

@@ -660,6 +660,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
+        parallelId,
       ),
       params,
       slot,
@@ -861,6 +862,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       entry.transition,
       deps.viewTransitionDefault,
+      entry.shortCode,
     ),
     params,
     belongsToRoute,
@@ -1197,6 +1199,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
+      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });

package/src/router/segment-resolution/view-transition-default.ts

@@ -8,29 +8,49 @@
  */
 
 import type { EntryData } from "../../server/context";
+import { getRequestContext } from "../../server/request-context.js";
 
 /**
- * Resolve the effective `viewTransition` for a segment's transition config.
+ * Resolve a segment's transition config: stamp the `viewTransition` default and
+ * peel off a transition({ when }) predicate.
  *
- * The per-segment value (set via the transition() DSL) always wins. When it is
- * unset, the router-level createRouter({ viewTransition }) default is stamped
- * in so the render gate reads the boundary decision off the segment — server
- * and client, via the serialized segment — without the router option being
- * threaded to the client. Only `false` is ever stamped; an unset (or "auto")
- * value is left untouched because it already means "wrap" at the gate, which
- * also avoids needless object allocation and payload growth. Used by both the
- * fresh and revalidation resolution paths.
+ * `viewTransition`: the per-segment value (set via the transition() DSL) always
+ * wins. When it is unset, the router-level createRouter({ viewTransition })
+ * default is stamped in so the render gate reads the boundary decision off the
+ * segment — server and client, via the serialized segment — without the router
+ * option being threaded to the client. Only `false` is ever stamped; an unset
+ * (or "auto") value is left untouched because it already means "wrap" at the
+ * gate, which also avoids needless object allocation and payload growth.
+ *
+ * `when`: a server-only predicate. It is STRIPPED from the returned config (a
+ * function cannot cross Flight or the segment cache) and recorded on the request
+ * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
+ * outside any cache scope — and drop this segment's transition when it returns
+ * false. Used by both the fresh and revalidation resolution paths.
  */
 export function applyViewTransitionDefault(
   transition: EntryData["transition"],
   viewTransitionDefault: "auto" | false | undefined,
+  segmentId?: string,
 ): EntryData["transition"] {
   if (!transition) return transition;
-  if (
-    transition.viewTransition === undefined &&
-    viewTransitionDefault === false
-  ) {
-    return { ...transition, viewTransition: false };
+  let result = transition;
+  if (result.when) {
+    if (segmentId !== undefined) {
+      try {
+        const ctx = getRequestContext();
+        (ctx._transitionWhen ??= []).push({ id: segmentId, when: result.when });
+      } catch {
+        // No active request context (e.g. a unit test calling this util
+        // directly). Skip collection; the strip below still applies so the
+        // serialized config never carries the function.
+      }
+    }
+    const { when: _when, ...rest } = result;
+    result = rest;
+  }
+  if (result.viewTransition === undefined && viewTransitionDefault === false) {
+    return { ...result, viewTransition: false };
   }
-  return transition;
+  return result;
 }

package/src/rsc/progressive-enhancement.ts

@@ -14,6 +14,7 @@ import { getSSRSetup } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import { gateTransitions } from "./transition-gate.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -278,12 +279,26 @@ export async function handleProgressiveEnhancement<TEnv>(
       });
     }
 
+    // Expose the no-JS action to the transition({ when }) gate. currentUrl/Params
+    // are absent on this full-render path (no navigation snapshot); useActionState
+    // ids are block-scoped, so only a direct action id is available here.
+    // actionUrl is the page the action was submitted from (this request's url).
+    const peReqCtx = getRequestContext();
+    peReqCtx._gateActionId = directActionId ?? undefined;
+    peReqCtx._gateActionUrl = new URL(url);
+    peReqCtx._gateActionResult = actionResult;
+    peReqCtx._gateFormData = formData;
+
     const payload: RscPayload = {
       metadata: {
         pathname: url.pathname,
         routerId: ctx.router.id,
         basename: ctx.router.basename,
-        segments: match.segments,
+        segments: gateTransitions(
+          match.segments,
+          getRequestContext(),
+          ctx.router.onError,
+        ),
         matched: match.matched,
         diff: match.diff,
         resolvedIds: match.resolvedIds,
@@ -395,12 +410,26 @@ async function renderPeErrorBoundary<TEnv>(
 
   setRequestContextParams(errorResult.params, errorResult.routeName);
 
+  // Only the failing action id + URL are in scope here (no formData/actionResult
+  // thread into this helper). Expose the URL only when the action id is known:
+  // this helper also handles malformed form bodies before action detection, and
+  // those should not look like action-triggered renders to transition({ when }).
+  if (actionId != null) {
+    const peErrCtx = getRequestContext();
+    peErrCtx._gateActionId = actionId;
+    peErrCtx._gateActionUrl = new URL(url);
+  }
+
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: errorResult.segments,
+      segments: gateTransitions(
+        errorResult.segments,
+        getRequestContext(),
+        ctx.router.onError,
+      ),
       matched: errorResult.matched,
       diff: errorResult.diff,
       resolvedIds: errorResult.resolvedIds,

package/src/rsc/rsc-rendering.ts

@@ -21,6 +21,7 @@ import {
   attachLocationStateIfPresent,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
+import { gateTransitions } from "./transition-gate.js";
 
 export function handleRscRendering<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -70,7 +71,7 @@ async function handleRscRenderingInner<TEnv>(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: m.segments,
+      segments: gateTransitions(m.segments, reqCtx, ctx.router.onError),
       matched: m.matched,
       diff: m.diff,
       resolvedIds: m.resolvedIds,
@@ -126,7 +127,11 @@ async function handleRscRenderingInner<TEnv>(
           // intercepted server-side (X-RSC-Reload) and never delivers a
           // different-router payload to the client.
           routerId: ctx.router.id,
-          segments: result.segments,
+          segments: gateTransitions(
+            result.segments,
+            reqCtx,
+            ctx.router.onError,
+          ),
           matched: result.matched,
           diff: result.diff,
           resolvedIds: result.resolvedIds,

package/src/rsc/server-action.ts

@@ -21,6 +21,7 @@ import {
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import { gateTransitions } from "./transition-gate.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -363,6 +364,14 @@ async function revalidateAfterActionInner<TEnv>(
   const reqCtx = getRequestContext();
   const metricsStore = reqCtx._metricsStore;
 
+  // Expose the action that triggered this revalidation to the transition({ when })
+  // gate (covers both the error-boundary and success gate calls below). Mirrors
+  // the action fields a revalidate() predicate sees.
+  reqCtx._gateActionId = actionContext?.actionId;
+  reqCtx._gateActionUrl = actionContext?.actionUrl;
+  reqCtx._gateActionResult = actionContext?.actionResult;
+  reqCtx._gateFormData = actionContext?.formData;
+
   // Action threw and a boundary matched: render the (already-matched) error
   // boundary here so it runs inside the route-middleware wrapper, exactly like
   // the success branch below. setRequestContextParams + the payload mirror the
@@ -376,7 +385,11 @@ async function revalidateAfterActionInner<TEnv>(
         // routerId exposed for the frontend (current app identity); see
         // rsc-rendering.ts partial branch.
         routerId: ctx.router.id,
-        segments: errorBoundary.segments,
+        segments: gateTransitions(
+          errorBoundary.segments,
+          reqCtx,
+          ctx.router.onError,
+        ),
         isPartial: true,
         matched: errorBoundary.matched,
         diff: errorBoundary.diff,
@@ -460,7 +473,11 @@ async function revalidateAfterActionInner<TEnv>(
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
-      segments: matchResult.segments,
+      segments: gateTransitions(
+        matchResult.segments,
+        reqCtx,
+        ctx.router.onError,
+      ),
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,

package/src/rsc/transition-gate.ts

@@ -0,0 +1,89 @@
+import type { MatchResult } from "../types.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+import type { getRequestContext } from "../server/request-context.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * The predicates were collected during resolution (keyed by segment id) and
+ * stripped from the serialized config; here — after handlers ran and outside any
+ * cache scope — we evaluate each and drop the segment's transition when the
+ * predicate does not hold, so the navigation streams its loading fallback
+ * instead of holding the previous content. A predicate that throws is reported
+ * to the router's onError (phase "rendering") and then treated as "do not hold"
+ * (conservative), so a buggy predicate degrades to no transition rather than
+ * failing the response.
+ *
+ * Mutating the segments here is safe: the segment cache stores a serialized copy
+ * (segment-codec), written during match() BEFORE this gate runs, so dropping a
+ * transition never corrupts a cache entry. The flip side is that a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate) — combining transition({ when })
+ * with cache() on the same segment freezes the gate to its cached state, so
+ * avoid caching a route whose transition decision is request-dependent.
+ *
+ * Returns the same array (mutated) for inline use at the payload's `segments`
+ * field.
+ */
+export function gateTransitions(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+  onError?: OnErrorCallback,
+): MatchResult["segments"] {
+  const predicates = ctx._transitionWhen;
+  if (predicates && predicates.length) {
+    for (const { id, when } of predicates) {
+      let drop: boolean;
+      try {
+        // Assemble the ShouldRevalidateFn-shaped predicate context from the
+        // request context. Source fields (currentUrl/currentParams/fromRouteName)
+        // were stashed at match time from the navigation snapshot; action fields
+        // at the action-bearing gate call sites. nextUrl/nextParams/toRouteName/
+        // method/get/env come straight off ctx (setRequestContextParams ran
+        // before the gate). Source/action fields are undefined when absent —
+        // never fabricated (see TransitionWhenContext).
+        const whenCtx: TransitionWhenContext = {
+          currentUrl: ctx._gateCurrentUrl,
+          currentParams: ctx._gateCurrentParams,
+          fromRouteName:
+            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+          nextUrl: ctx.url,
+          nextParams: ctx.params,
+          toRouteName: ctx.routeName,
+          actionId: ctx._gateActionId,
+          actionUrl: ctx._gateActionUrl,
+          actionResult: ctx._gateActionResult,
+          formData: ctx._gateFormData,
+          method: ctx.request.method,
+          get: ctx.get,
+          env: ctx.env,
+        };
+        drop = when(whenCtx) === false;
+      } catch (error) {
+        // A throwing predicate must not fail the response: report it and treat
+        // the transition as gated off (do not hold). invokeOnError no-ops when
+        // onError is undefined.
+        drop = true;
+        invokeOnError(
+          onError,
+          error,
+          "rendering",
+          {
+            request: ctx.request,
+            url: ctx.url,
+            params: ctx.params,
+            segmentId: id,
+          },
+          "RSC",
+        );
+      }
+      if (drop) {
+        const seg = segments.find((s) => s.id === id);
+        if (seg) seg.transition = undefined;
+      }
+    }
+  }
+  return segments;
+}

package/src/segment-system.tsx

@@ -316,14 +316,32 @@ export async function renderSegments(
       resolvedComponent = await component;
     }
 
-    let nodeContent: ReactNode = isRenderableLoading(loading)
-      ? createElement(RouteContentWrapper, {
-          key: `suspense-loading-${id}`,
-          content: getMemoizedContentPromise(resolvedComponent),
-          fallback: loading,
-          segmentId: id,
-        })
-      : registerLazyRef(resolvedComponent);
+    let nodeContent: ReactNode = null;
+    if (isRenderableLoading(loading)) {
+      // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
+      // loading() route with the route content ALREADY resolved, so its
+      // RouteContentWrapper Suspender does not suspend for a microtask and flash
+      // the loading() fallback on a NORMAL (non-transition) commit. The router
+      // data is known-ready on these paths, so awaiting the content here is free.
+      // The wrapper tree is unchanged (RouteContentWrapper is still created with
+      // the same key/fallback) — only the `content` prop is a resolved node
+      // instead of a pending promise, which Suspender renders synchronously. This
+      // mirrors the forceAwait loaderData unwrap above; a CLIENT component that
+      // suspends on mount inside the content still reveals a fallback (it is not
+      // pre-resolved).
+      const contentPromise = getMemoizedContentPromise(resolvedComponent);
+      const loadingContent: Promise<ReactNode> | ReactNode = forceAwait
+        ? await contentPromise
+        : contentPromise;
+      nodeContent = createElement(RouteContentWrapper, {
+        key: `suspense-loading-${id}`,
+        content: loadingContent,
+        fallback: loading,
+        segmentId: id,
+      });
+    } else {
+      nodeContent = registerLazyRef(resolvedComponent);
+    }
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates

package/src/server/context.ts

@@ -150,6 +150,19 @@ export type InterceptWhenFn<TEnv = any> = (
   ctx: InterceptSelectorContext<TEnv>,
 ) => boolean;
 
+/**
+ * Config object passed to intercept() (its 4th argument). `when` gates whether
+ * the intercept activates on a soft navigation — a single match-time selector or
+ * an array of them (ALL must return true; omit to always activate). This is the
+ * intercept counterpart to transition({ when }); both express conditional
+ * behavior as a config field rather than a separate DSL helper.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface InterceptConfig<TEnv = any> {
+  when?: InterceptWhenFn<TEnv> | InterceptWhenFn<TEnv>[];
+}
+
 /**
  * Intercept entry stored in EntryData
  * Contains the slot name, route to intercept, and handler

package/src/server/request-context.ts

@@ -48,6 +48,7 @@ import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import type { TransitionWhenFn } from "../types/segments.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import {
@@ -161,6 +162,15 @@ export interface RequestContext<
   /** @internal Handle store for tracking handle data across segments */
   _handleStore: HandleStore;
 
+  /**
+   * @internal transition({ when }) predicates for segments matched this request,
+   * keyed by segment id. Collected during resolution (the function is stripped
+   * from the serialized segment config), then evaluated post-handler in
+   * rsc-rendering — outside any cache scope — to drop the transition of any
+   * segment whose predicate returns false.
+   */
+  _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
@@ -292,6 +302,20 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
+  /**
+   * @internal Navigation/action source data the transition({ when }) gate reads
+   * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
+   * come from the navigation snapshot (set at match time); action* are stashed
+   * at the action-bearing gate call sites. All undefined when there is no source
+   * (initial full load) or no action (plain navigation).
+   */
+  _gateCurrentUrl?: URL;
+  _gateCurrentParams?: Record<string, string>;
+  _gateActionId?: string;
+  _gateActionUrl?: URL;
+  _gateActionResult?: unknown;
+  _gateFormData?: FormData;
+
   /**
    * @internal Render barrier for experimental `rendered()` API.
    * Resolves when all non-loader segments have settled and handle data
@@ -413,6 +437,7 @@ export type PublicRequestContext<
   | "setCookie"
   | "deleteCookie"
   | "_handleStore"
+  | "_transitionWhen"
   | "_cacheStore"
   | "_explicitTaggedStores"
   | "_requestTags"
@@ -422,6 +447,12 @@ export type PublicRequestContext<
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
+  | "_gateCurrentUrl"
+  | "_gateCurrentParams"
+  | "_gateActionId"
+  | "_gateActionUrl"
+  | "_gateActionResult"
+  | "_gateFormData"
   | "_reportedErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
@@ -527,11 +558,17 @@ export function setRequestContextParams(
  */
 export function setRequestContextPrevRouteKey(
   prevRouteKey: string | undefined,
+  currentUrl?: URL,
+  currentParams?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
-  if (ctx && prevRouteKey !== undefined) {
-    ctx._prevRouteKey = prevRouteKey;
-  }
+  if (!ctx) return;
+  if (prevRouteKey !== undefined) ctx._prevRouteKey = prevRouteKey;
+  // Source URL/params for the transition({ when }) gate (effectiveFromUrl /
+  // effectiveFromMatch.params from the navigation snapshot). Same write point as
+  // _prevRouteKey, which doubles as fromRouteName.
+  if (currentUrl !== undefined) ctx._gateCurrentUrl = currentUrl;
+  if (currentParams !== undefined) ctx._gateCurrentParams = currentParams;
 }
 
 /**
@@ -842,6 +879,7 @@ export function createRequestContext<TEnv>(
     method: request.method,
 
     _handleStore: handleStore,
+    _transitionWhen: [],
     _cacheStore: cacheStore,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),

package/src/testing/index.ts

@@ -47,6 +47,12 @@ export type {
   TestLoaderContext,
 } from "./run-loader.js";
 
+export { runTransitionWhen } from "./run-transition-when.js";
+export type {
+  RunTransitionWhenOptions,
+  RunTransitionWhenResult,
+} from "./run-transition-when.js";
+
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";