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

package/src/segment-system.tsx

@@ -10,6 +10,7 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 import { getMemoizedContentPromise } from "./segment-content-promise.js";
 import {
   buildLoaderPromise,
@@ -316,14 +317,47 @@ 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 {
+      // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. A segment in the no-loading()
+      // branch whose component decodes as a Promise/lazy gets registered into
+      // temporalLazyRefs and awaited before commit (see below) — which on builds
+      // where the segment component arrives deferred defeats client-nav streaming.
+      if (INTERNAL_RANGO_DEBUG && typeof window === "object") {
+        const c = resolvedComponent as unknown;
+        console.log("[VT-DIAG] renderSegments no-loading-branch segment", {
+          id,
+          type: node.segment.type,
+          componentIsPromise: c instanceof Promise,
+          componentIsLazy:
+            c != null && typeof c === "object" && "_payload" in c,
+          componentTypeof: typeof c,
+        });
+      }
+      nodeContent = registerLazyRef(resolvedComponent);
+    }
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
@@ -462,7 +496,24 @@ export async function renderSegments(
     children: content,
   });
   if (typeof window === "object") {
+    // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. If this await dominates the
+    // navigation time, a deferred/lazy segment component is being fully resolved
+    // before commit, which defeats client-nav streaming. The await itself is
+    // functional (it preloads lazy chunk refs); only the timing log is gated.
+    const vtDebug = INTERNAL_RANGO_DEBUG && temporalLazyRefs.length > 0;
+    const vtDebugStart = vtDebug ? performance.now() : 0;
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments awaiting temporalLazyRefs", {
+        count: temporalLazyRefs.length,
+      });
+    }
     await Promise.allSettled(temporalLazyRefs);
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments temporalLazyRefs settled", {
+        count: temporalLazyRefs.length,
+        ms: Math.round(performance.now() - vtDebugStart),
+      });
+    }
   }
 
   let result: ReactNode = errorBoundaryWrapped;

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/loader-registry.ts

@@ -67,7 +67,19 @@ export async function getLoaderLazy(
     }
   }
 
-  // Dev fallback: parse ID (format: "src/path/to/file.ts#ExportName") and import
+  // The remaining dev fallback (parse the id as "src/path/file.ts#ExportName"
+  // and import it by path) only makes sense in dev, where ids ARE file paths
+  // and the dev loader manifest is intentionally empty. In production ids are
+  // hashed ("<hash>#ExportName") and every resolvable loader is reached above
+  // via the in-memory registry or the lazy import manifest. The hash is not a
+  // path, so a production fall-through would run import("/<hash>") and throw a
+  // misleading "No such module <hash>" 500 instead of reporting the loader as
+  // unregistered. Return undefined in production so a genuinely unknown loader
+  // is a clean 404 "not found in registry" from handleLoaderFetch.
+  if (process.env.NODE_ENV === "production") {
+    return undefined;
+  }
+
   const hashIndex = id.indexOf("#");
   if (hashIndex !== -1) {
     const filePath = id.slice(0, hashIndex);

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,30 @@ 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 True while the post-action revalidation render is running (set by
+   * revalidateAfterAction). The "use cache" runtime reads this to prefer
+   * freshness over a fast stale response during an action: a stale entry
+   * re-executes in the foreground (so the action response reflects the refreshed
+   * value) with only the store write deferred, instead of serving stale and
+   * revalidating in the background. A plain navigation (flag unset) keeps SWR.
+   */
+  _inActionRevalidation?: boolean;
+
   /**
    * @internal Render barrier for experimental `rendered()` API.
    * Resolves when all non-loader segments have settled and handle data
@@ -413,6 +447,7 @@ export type PublicRequestContext<
   | "setCookie"
   | "deleteCookie"
   | "_handleStore"
+  | "_transitionWhen"
   | "_cacheStore"
   | "_explicitTaggedStores"
   | "_requestTags"
@@ -422,6 +457,13 @@ export type PublicRequestContext<
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
+  | "_gateCurrentUrl"
+  | "_gateCurrentParams"
+  | "_gateActionId"
+  | "_gateActionUrl"
+  | "_gateActionResult"
+  | "_gateFormData"
+  | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
@@ -527,11 +569,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 +890,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";
 

package/src/testing/render-handler.ts

@@ -116,6 +116,15 @@ export interface RenderHandlerOptions<TEnv = any> {
    * `"use cache: profileName"` resolution once a `cacheStore` is wired.
    */
   cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Render as if inside a server action's revalidation render (production sets
+   * this in revalidateAfterAction). A stale `"use cache"` entry whose profile
+   * opts into `foregroundOnAction` then re-executes in the FOREGROUND (fresh
+   * result in this render) instead of being served stale + revalidated in the
+   * background. Without it, a stale entry keeps SWR. Pair with `cacheStore` +
+   * `cacheProfiles` to exercise the `foregroundOnAction` opt-in.
+   */
+  inActionRevalidation?: boolean;
   /**
    * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
    * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert,
@@ -238,6 +247,11 @@ export async function renderHandler<TEnv = any>(
       opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
   });
 
+  // Simulate an action revalidation render (production sets this in
+  // revalidateAfterAction) so a `foregroundOnAction` cache profile foregrounds a
+  // stale entry. See the foregroundOnAction option doc.
+  if (opts.inActionRevalidation) reqCtx._inActionRevalidation = true;
+
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
   const handlePushes = new Map<Handle<any, any>, unknown[]>();
 

package/src/testing/run-transition-when.ts

@@ -0,0 +1,164 @@
+/**
+ * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ *
+ * Runs the SAME two server functions the router uses — applyViewTransitionDefault
+ * (strips the `when` function from the serialized config and records the
+ * predicate on the request context) and gateTransitions (assembles the
+ * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * predicate sees exactly the navigation/action metadata it would at runtime
+ * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
+ * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
+ * whether the transition would apply this request. The result also exposes the
+ * assembled `whenContext` so tests can assert the exact fields without reaching
+ * into private request-context state.
+ *
+ * This is the public way to exercise a transition gate: the full
+ * match -> render pipeline that wires these together only runs under real RSC
+ * rendering (which the Flight primitives do not drive), so without this primitive
+ * a consumer could not test their predicate through @rangojs/router/testing.
+ *
+ * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
+ */
+
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { applyViewTransitionDefault } from "../router/segment-resolution/view-transition-default.js";
+import { gateTransitions } from "../rsc/transition-gate.js";
+import { createTestRequestContext, type VarsInit } from "./internal/context.js";
+import type {
+  ResolvedSegment,
+  TransitionConfig,
+  TransitionWhenContext,
+} from "../types/segments.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+const toURL = (v: string | URL, base: URL): URL =>
+  typeof v === "string" ? new URL(v, base.origin) : v;
+
+/**
+ * Options for runTransitionWhen. All navigation/action fields are optional and
+ * default to "absent", matching what the gate sees for an initial full load with
+ * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
+ * navigation source being unavailable, and omit the `action*` fields to model a
+ * plain (non-action) navigation.
+ */
+export interface RunTransitionWhenOptions<TEnv = any> {
+  /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
+  request?: Request | string;
+  /** Route params for the target (`nextParams`). */
+  params?: Record<string, string>;
+  /** Target route name (`toRouteName`). */
+  toRouteName?: string;
+  /** Environment bindings surfaced as `env` (and `ctx.env`). */
+  env?: TEnv;
+  /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+  vars?: VarsInit;
+  /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
+  currentUrl?: string | URL;
+  /** Source route params (`currentParams`). */
+  currentParams?: Record<string, string>;
+  /** Source route name (`fromRouteName`). */
+  fromRouteName?: string;
+  /** Id of the action that triggered a revalidation (`actionId`). */
+  actionId?: string;
+  /** Url the action was submitted from (`actionUrl`). */
+  actionUrl?: string | URL;
+  /** The action's return value (`actionResult`). */
+  actionResult?: unknown;
+  /** FormData from a form action (`formData`). */
+  formData?: FormData;
+  /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
+  onError?: OnErrorCallback;
+}
+
+/**
+ * Result of runTransitionWhen.
+ */
+export interface RunTransitionWhenResult<TEnv = any> {
+  /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
+  kept: boolean;
+  /** Convenience inverse of `kept`. */
+  dropped: boolean;
+  /**
+   * The production-assembled predicate context. Undefined when the config has
+   * no `when` predicate.
+   */
+  whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
+  /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
+  ctx: RequestContext<TEnv>;
+}
+
+export function runTransitionWhen<TEnv = any>(
+  config: TransitionConfig,
+  opts: RunTransitionWhenOptions<TEnv> = {},
+): RunTransitionWhenResult<TEnv> {
+  const { ctx } = createTestRequestContext<TEnv>({
+    env: opts.env,
+    request: opts.request,
+    vars: opts.vars,
+    params: opts.params,
+  });
+  const reqCtx = ctx as unknown as RequestContext<TEnv>;
+
+  // Target route name (the public field the gate reads for `toRouteName`).
+  if (opts.toRouteName !== undefined)
+    reqCtx.routeName = opts.toRouteName as RequestContext<TEnv>["routeName"];
+  // Source (match-time) data the gate reads for currentUrl/currentParams/fromRouteName.
+  if (opts.currentUrl !== undefined)
+    reqCtx._gateCurrentUrl = toURL(opts.currentUrl, reqCtx.url);
+  if (opts.currentParams !== undefined)
+    reqCtx._gateCurrentParams = opts.currentParams;
+  if (opts.fromRouteName !== undefined)
+    reqCtx._prevRouteKey = opts.fromRouteName;
+  // Action data the gate reads at the action-bearing call sites.
+  if (opts.actionId !== undefined) reqCtx._gateActionId = opts.actionId;
+  if (opts.actionUrl !== undefined)
+    reqCtx._gateActionUrl = toURL(opts.actionUrl, reqCtx.url);
+  if (opts.actionResult !== undefined)
+    reqCtx._gateActionResult = opts.actionResult;
+  if (opts.formData !== undefined) reqCtx._gateFormData = opts.formData;
+
+  let whenContext:
+    | TransitionWhenContext<Record<string, string>, TEnv>
+    | undefined;
+  const when = config.when;
+  const configForGate: TransitionConfig = when
+    ? {
+        ...config,
+        when: (c) => {
+          whenContext = c as TransitionWhenContext<
+            Record<string, string>,
+            TEnv
+          >;
+          return when(c);
+        },
+      }
+    : config;
+
+  return runWithRequestContext(reqCtx, () => {
+    // The real resolution-time collection + post-handler gate, so the predicate
+    // sees the production-assembled TransitionWhenContext.
+    const serialized = applyViewTransitionDefault(
+      configForGate,
+      undefined,
+      "tx-when-seg",
+    );
+    const segment = {
+      id: "tx-when-seg",
+      namespace: "r",
+      type: "route",
+      index: 0,
+      component: null,
+      transition: serialized,
+    } as ResolvedSegment;
+    gateTransitions(
+      [segment],
+      reqCtx as Parameters<typeof gateTransitions>[1],
+      opts.onError,
+    );
+    const kept = segment.transition !== undefined;
+    return { kept, dropped: !kept, whenContext, ctx: reqCtx };
+  });
+}

package/src/types/handler-context.ts

@@ -504,7 +504,7 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.context - App context (db, user, etc.)
  * @param args.actionResult - Result from action (future support)
  * @param args.formData - Form data from action (future support)
- * @param args.formMethod - HTTP method from action (future support)
+ * @param args.method - HTTP method: "GET" for navigation, "POST" for server actions
  *
  * @returns Hard decision (boolean), soft suggestion (object), or defer
  *   (`void` / `null` / `undefined`) to keep the running suggestion as-is.

package/src/types/index.ts

@@ -48,6 +48,8 @@ export type {
 export type {
   ViewTransitionClass,
   TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
   ResolvedSegment,
   SegmentMetadata,
   SlotState,

package/src/types/segments.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
+import type { RevalidateParams, HandlerContext } from "./handler-context.js";
 
 /**
  * CSS class(es) for a ViewTransition phase.
@@ -8,6 +9,96 @@ import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
  */
 export type ViewTransitionClass = Record<string, string> | string;
 
+/**
+ * The context a transition({ when }) predicate receives.
+ *
+ * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
+ * gets — the same navigation/action metadata — so the two read the same shape,
+ * plus `get`/`env` for post-handler reads. There is no full `HandlerContext`
+ * here: the gate runs at the RSC-payload layer with the request context, not a
+ * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
+ * absent by design. `get` is the way to read what the handler/middleware set
+ * via `ctx.set(...)` this request.
+ *
+ * Field availability (all source fields are optional — never fabricated):
+ * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
+ *   populated on soft navigations and action-success revalidations. They are
+ *   undefined on an initial full document load and on action-error / no-JS error
+ *   paths that skip the navigation snapshot — there is no prior page to name.
+ * - `nextUrl` / `nextParams` / `get` / `env` / `method` are always present;
+ *   `toRouteName` is present only when the target route is named (undefined for
+ *   unnamed/auto-generated routes, like `fromRouteName`).
+ * - `actionId` / `actionUrl` / `actionResult` / `formData` are populated only
+ *   when a server action triggered the render; `method` is "POST" then, "GET"
+ *   otherwise. On no-JS (progressive-enhancement) action paths `actionId` may be
+ *   undefined when React cannot surface the action's stable id: the success
+ *   re-render still sets `actionUrl`/`formData` for a recognized action, but the
+ *   error-boundary re-render exposes `actionUrl` only when `actionId` resolved.
+ *   Malformed form bodies that fail before action detection expose no action
+ *   fields. Treat `actionId` as "the action, if known", not as "was this an
+ *   action".
+ *
+ * PREFETCH / CACHE CAVEAT (read this before gating on the source): the gate runs
+ * server-side during resolution. A PREFETCHED navigation renders at prefetch
+ * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
+ * prefetch fired from, NOT necessarily the page the user actually navigates from
+ * — the decision is baked into the stored Flight payload and replayed verbatim.
+ * A `cache()`/prerender hit replays the stored transition with the predicate NOT
+ * re-run at all. So a source-sensitive predicate can be frozen to prefetch-time
+ * or store-time state. This is accepted (~99% of navigations match), but if your
+ * gate must reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`) and do not `cache()` that segment.
+ */
+export type TransitionWhenContext<
+  TParams = Record<string, string>,
+  TEnv = unknown,
+> = Partial<
+  Pick<
+    RevalidateParams<TParams, TEnv>,
+    "currentUrl" | "currentParams" | "fromRouteName"
+  >
+> &
+  Pick<
+    RevalidateParams<TParams, TEnv>,
+    | "nextUrl"
+    | "nextParams"
+    | "toRouteName"
+    | "actionId"
+    | "actionUrl"
+    | "actionResult"
+    | "formData"
+    | "method"
+  > &
+  Pick<HandlerContext<any, TEnv>, "get" | "env">;
+
+/**
+ * Predicate that gates whether a transition() applies for the current request.
+ *
+ * Evaluated server-side AFTER the route's handler runs (so `get(...)` can read
+ * handler/middleware-set state) and outside any cache scope. Return false to
+ * drop this segment's transition for the request; return true to apply it. The
+ * context ({@link TransitionWhenContext}) carries the same navigation/action
+ * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
+ * error is reported to the router's onError (phase "rendering") and the
+ * transition is dropped (the navigation does not hold).
+ *
+ * Distinct from intercept()'s `when` config selector, which runs at MATCH time
+ * over `{ from, to, params, segments, … }`; a transition `when` runs
+ * post-handler over the resolved payload.
+ *
+ * Scope: dropping a transition removes only THIS segment's contribution to the
+ * navigation's hold. The startTransition hold is navigation-wide — it engages if
+ * any matched segment still has a transition — so `when: false` makes the
+ * navigation stream its loading fallback only when no other matched segment
+ * keeps a transition (the common case: a single transition on the route).
+ *
+ * Evaluated on every fresh (cache-miss) resolution; it is NOT re-run when a
+ * segment is replayed from the runtime cache or a build-time prerender, and a
+ * prefetched navigation freezes it to prefetch-time state — see the caveat on
+ * {@link TransitionWhenContext}.
+ */
+export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
+
 /**
  * Configuration for React's <ViewTransition> component.
  *
@@ -36,6 +127,15 @@ export interface TransitionConfig {
    * When unset, inherits the createRouter({ viewTransition }) default.
    */
   viewTransition?: "auto" | false;
+  /**
+   * Optional server-side predicate that gates this transition per request. When
+   * present and it returns false (evaluated post-handler), the router drops this
+   * segment's transition for the request, so the navigation streams its loading
+   * fallback instead of holding. The predicate is server-only and never
+   * serialized to the client; only its resolved effect (transition kept or
+   * dropped) crosses. See {@link TransitionWhenFn}.
+   */
+  when?: TransitionWhenFn;
 }
 
 /**

package/src/urls/path-helper-types.ts

@@ -28,7 +28,6 @@ import type {
   ParallelUseItem,
   InterceptUseItem,
   LoaderUseItem,
-  WhenItem,
   TypedCacheItem,
   TransitionItem,
   TypedTransitionItem,
@@ -42,7 +41,6 @@ import type {
   PassthroughHandlerDefinition,
 } from "../prerender.js";
 import type { StaticHandlerDefinition } from "../static-handler.js";
-import type { InterceptWhenFn } from "../server/context";
 import type {
   ResponseHandler,
   ResponseHandlerContext,
@@ -275,12 +273,18 @@ export type PathHelpers<TEnv> = {
         slotName: `@${string}`,
         routeName: string,
         handler: ReactNode | Handler<any, any, TEnv>,
+        config?:
+          | import("../server/context.js").InterceptConfig<TEnv>
+          | (() => InterceptUseItem[]),
         use?: () => InterceptUseItem[],
       ) => InterceptItem
     : (
         slotName: `@${string}`,
         routeName: (keyof Rango.GeneratedRouteMap & string) | `.${string}`,
         handler: ReactNode | Handler<any, any, TEnv>,
+        config?:
+          | import("../server/context.js").InterceptConfig<TEnv>
+          | (() => InterceptUseItem[]),
         use?: () => InterceptUseItem[],
       ) => InterceptItem;
 
@@ -335,11 +339,6 @@ export type PathHelpers<TEnv> = {
     fallback: ReactNode | NotFoundBoundaryHandler,
   ) => NotFoundBoundaryItem;
 
-  /**
-   * Define a condition for when an intercept should activate
-   */
-  when: (fn: InterceptWhenFn) => WhenItem;
-
   /**
    * Define cache configuration for segments
    */
@@ -365,6 +364,10 @@ export type PathHelpers<TEnv> = {
    * `{ viewTransition: false }` to keep #1 without the router boundary. A view
    * transition cannot fire without a startTransition. See
    * skills/view-transitions for the startTransition x ViewTransition matrix.
+   *
+   * Pass `when: (ctx) => boolean` to gate the transition per request: it runs
+   * server-side after the route handler (can read `ctx.get(...)`), and returning
+   * false drops the transition so the navigation streams its loading() skeleton.
    */
   transition: {
     (): TransitionItem;

package/src/urls/urls-function.ts

@@ -58,7 +58,6 @@ export function urls<
       loading: baseHelpers.loading,
       errorBoundary: baseHelpers.errorBoundary,
       notFoundBoundary: baseHelpers.notFoundBoundary,
-      when: baseHelpers.when,
       cache: baseHelpers.cache as PathHelpers<TEnv>["cache"],
       transition: baseHelpers.transition as PathHelpers<TEnv>["transition"],
     };