@rangojs/router 0.18.0 → 0.19.0

package/src/testing/location-state-key.ts

@@ -0,0 +1,45 @@
+import {
+  peekLocationStateKey,
+  type LocationStateDefinition,
+} from "../browser/react/location-state-shared.js";
+
+// Typed history.state slots must carry this prefix: buildHistoryState spreads
+// only `__rsc_ls_*` keys onto history.state (history-state.ts).
+const KEY_PREFIX = "__rsc_ls_";
+
+let syntheticKeyCounter = 0;
+
+/**
+ * Assign a location-state key to a `createLocationState()` definition in a unit
+ * test that runs without the rango Vite plugin (which injects the key in dev
+ * and build). Outside production, a definition without a key throws on first
+ * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
+ *
+ * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
+ *   (a name that already starts with `__rsc_ls_` is used as-is).
+ * - Without a name, a key already set (by the plugin or an earlier call) is
+ *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
+ *   which then stays on it.
+ *
+ * Returns the definition.
+ *
+ * @example
+ * ```ts
+ * import { withLocationStateKey } from "@rangojs/router/testing";
+ * import { GridState } from "../src/location-states";
+ *
+ * withLocationStateKey(GridState);
+ * ```
+ */
+export function withLocationStateKey<
+  TDefinition extends LocationStateDefinition<any, any>,
+>(definition: TDefinition, name?: string): TDefinition {
+  if (name !== undefined) {
+    definition.__rsc_ls_key = name.startsWith(KEY_PREFIX)
+      ? name
+      : KEY_PREFIX + name;
+  } else if (!peekLocationStateKey(definition)) {
+    definition.__rsc_ls_key = `${KEY_PREFIX}test_${syntheticKeyCounter++}`;
+  }
+  return definition;
+}

package/src/testing/render-handler.ts

@@ -338,7 +338,7 @@ export async function renderHandler<TEnv = any>(
     }
   });
 
-  const cookies = { ...reqCtx.cookies() };
+  const cookies = reqCtx._readCookies();
   const responseSource = didThrow
     ? thrown
     : out instanceof Response

package/src/testing/render-route.tsx

@@ -30,6 +30,11 @@
  *     model is the held-navigation useLoader().isLoading: a `transition` spec
  *     plus a pending Promise seeded via navigate(url, { loaders }) commits
  *     through production's commitInTransition (browser/partial-update.ts).
+ *   - A spec's transition({ when }) decides every commit with production's
+ *     browser decision: navigate() and useRouter().push model kind "push",
+ *     useRouter().replace kind "replace", refresh() kind "revalidate".
+ *     Back/forward, action and optimistic clientUrls() swap decisions are
+ *     e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -42,6 +47,7 @@
  * (the segment chain is wrapped in a MountContext exactly as in production).
  */
 
+import { decideTransitionGatedOff } from "../browser/transition-when.js";
 import { useEffect, type ReactNode, type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
 import { renderSegments } from "../segment-system.js";
@@ -56,6 +62,7 @@ import {
   shouldStartViewTransition,
 } from "../browser/partial-update.js";
 import type {
+  NavigateOptionsInternal,
   NavigationStore,
   NavigationBridge,
   UpdateSubscriber,
@@ -68,8 +75,19 @@ import {
   buildParamsFromMatch,
 } from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
-import type { LoaderDefinition, TransitionConfig } from "../types.js";
+import type {
+  LoaderDefinition,
+  TransitionConfig,
+  TransitionWhenKind,
+} from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import {
+  buildHistoryState,
+  hasLocationState,
+  pushHistoryWithIdx,
+  resolveNavigationState,
+} from "../browser/history-state.js";
+import { withLocationStateKey } from "./location-state-key.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
@@ -93,18 +111,15 @@ export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
 const syntheticIds = new WeakMap<object, string>();
 let syntheticIdCounter = 0;
 
-function ensureSyntheticId(
-  handle: object,
-  field: "$$id" | "__rsc_ls_key",
-): string {
-  const existing = (handle as Record<string, string>)[field];
+function ensureSyntheticId(loader: object): string {
+  const existing = (loader as { $$id?: string }).$$id;
   if (existing) return existing;
-  let id = syntheticIds.get(handle);
+  let id = syntheticIds.get(loader);
   if (!id) {
     id = `__rango_test_id_${syntheticIdCounter++}`;
-    syntheticIds.set(handle, id);
+    syntheticIds.set(loader, id);
   }
-  (handle as Record<string, string>)[field] = id;
+  (loader as { $$id?: string }).$$id = id;
   return id;
 }
 
@@ -337,11 +352,20 @@ export interface TestRouterHandle {
    * // reader: isLoading true, old data
    * await act(async () => resolve({ name: "Product 2" }));
    * // reader: isLoading false, new data
+   *
+   * `options.transition: false` is the per-navigation opt-out
+   * (`router.push(url, { transition: false })`, `<Link transition={false}>`):
+   * the commit is urgent and no transition({ when }) predicate is called.
    */
   navigate(
     url: string,
-    options?: Pick<RenderRouteOptions, "loaders">,
+    options?: Pick<RenderRouteOptions, "loaders"> & { transition?: boolean },
   ): Promise<void>;
+  /**
+   * Re-render the current location, as router.refresh() does: a spec's
+   * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
+   */
+  refresh(): Promise<void>;
   /** The current committed pathname. */
   pathname(): string;
   /** The current committed params. */
@@ -508,7 +532,7 @@ export async function renderRoute(
   ): Record<string, unknown> => {
     const out = { ...base };
     for (const [loader, data] of loaders ?? []) {
-      out[ensureSyntheticId(loader as object, "$$id")] = data;
+      out[ensureSyntheticId(loader)] = data;
     }
     return out;
   };
@@ -517,7 +541,7 @@ export async function renderRoute(
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
-      stateObj[ensureSyntheticId(def as object, "__rsc_ls_key")] = value;
+      stateObj[withLocationStateKey(def).__rsc_ls_key] = value;
     }
     window.history.replaceState(stateObj, "");
   }
@@ -597,8 +621,30 @@ export async function renderRoute(
   let warnedNavLifecycle = false;
   const navigate = async (
     target: string,
-    navOptions?: Pick<RenderRouteOptions, "loaders">,
+    navOptions?: Pick<RenderRouteOptions, "loaders"> & {
+      history?: Pick<
+        NavigateOptionsInternal,
+        "state" | "replace" | "transition"
+      >;
+      kind?: TransitionWhenKind;
+      transition?: boolean;
+    },
   ): Promise<void> => {
+    // A useRouter().push/replace or <Link> navigation (`history`) writes its
+    // entry the way production does (navigation-bridge.ts navigate ->
+    // navigation-transaction.ts commit): the dev state check, typed entries
+    // spread onto history.state, the idx stamp, and the __rsc_locationstate
+    // event when the old or new entry carries location state. The URL stays
+    // put: renderRoute tracks location on the event controller, not
+    // window.location. router.navigate() and refresh() leave history alone.
+    const history = navOptions?.history;
+    const historyState = history
+      ? buildHistoryState(
+          history.state !== undefined
+            ? resolveNavigationState(history.state)
+            : undefined,
+        )
+      : undefined;
     // No server fetch, so the navigation lifecycle never starts: the state
     // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting
     // a pending/loading/submitting state here proves nothing. Warn once (per
@@ -623,30 +669,76 @@ export async function renderRoute(
       mount,
     );
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
+    // Production's browser-run transition({ when }) decision
+    // (browser/partial-update.ts): the committed location is the source.
+    const kind: TransitionWhenKind =
+      navOptions?.kind ?? (history?.replace ? "replace" : "push");
+    // `transition: false` gates off without calling a predicate
+    // (navigation-bridge.ts navigate).
+    const transitionOptOut =
+      (navOptions?.transition ?? history?.transition) === false;
+    const gatedOff =
+      transitionOptOut ||
+      decideTransitionGatedOff(segments, () => ({
+        kind,
+        from: {
+          url: eventController.getLocation().href,
+          params: eventController.getParams(),
+          routeName: leaf.name,
+          state: window.history.state,
+        },
+        to: {
+          url: nextUrl,
+          params: match.params,
+          routeName: leaf.name,
+          state: historyState ?? null,
+        },
+      }));
     const root = await renderSegments(segments, {
       outletPending: options.outletPending,
+      transitionGatedOff: gatedOff,
     });
     eventController.setLocation(nextUrl);
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
     store.setSegmentIds(segments.map((s) => s.id));
+    let notifyLocationState = false;
+    if (history) {
+      notifyLocationState =
+        hasLocationState(window.history.state) ||
+        hasLocationState(historyState);
+      pushHistoryWithIdx(
+        historyState ?? null,
+        window.location.href,
+        history.replace ?? false,
+      );
+    }
     const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
       // Production's transition() lane (browser/partial-update.ts). Its
       // same-structure / fully-prefetched / optimistic hold lanes are not
       // modeled: without transition() the commit stays urgent.
-      if (shouldStartViewTransition(segments)) {
+      if (shouldStartViewTransition(segments, gatedOff)) {
         commitInTransition(emit, segments, { root, metadata }, ["navigation"]);
       } else {
         emit({ root, metadata });
       }
+      if (notifyLocationState) {
+        window.dispatchEvent(new Event("__rsc_locationstate"));
+      }
     });
   };
 
+  const refresh = (): Promise<void> => {
+    const current = new URL(eventController.getLocation().href);
+    return navigate(current.pathname + current.search, { kind: "revalidate" });
+  };
+
   let prefetchRoot: HTMLElement | undefined;
   const bridge: NavigationBridge = {
-    navigate: (target) => navigate(target),
-    refresh: () => navigate(url.pathname + url.search),
+    navigate: (target, navigateOptions) =>
+      navigate(target, { history: navigateOptions ?? {} }),
+    refresh: () => refresh(),
     handlePopstate: async () => {},
     registerLinkInterception: () => () => {},
     registerDelegatedPrefetch: () =>
@@ -704,6 +796,7 @@ export async function renderRoute(
 
   const router: TestRouterHandle = {
     navigate,
+    refresh,
     pathname: () => new URL(eventController.getLocation().href).pathname,
     params: () => eventController.getParams(),
     store,

package/src/testing/run-client-revalidate.ts

@@ -10,7 +10,8 @@
  * Synchronous: client revalidate functions must be sync.
  */
 
-import { makeIsAction, resolveActionRefId } from "../router/is-action.js";
+import { makeIsAction } from "../router/is-action.js";
+import { resolveTestActionId } from "./internal/action-id.js";
 import {
   lockedClientDefault,
   runClientRevalidateChain,
@@ -23,23 +24,6 @@ import type {
 
 const DEFAULT_URL = "http://localhost/";
 
-function resolveActionId(
-  action: ((...args: never[]) => unknown) | string | undefined,
-): string | undefined {
-  if (action === undefined) return undefined;
-  if (typeof action === "string") return action;
-  const id = resolveActionRefId(action);
-  if (id === undefined) {
-    throw new Error(
-      "runClientRevalidate: `action` must be a single imported server action " +
-        "(carrying its build-injected id) or an actionId string. The passed " +
-        "function has no $id/$$id — outside a built app, pass the id string " +
-        'your predicate should match (e.g. "src/actions/cart.ts#addToCart").',
-    );
-  }
-  return id;
-}
-
 /**
  * Options for {@link runClientRevalidate}. Defaults model a same-URL
  * navigation with no action (locked default `false`).
@@ -80,7 +64,7 @@ export function runClientRevalidate(
   const currentParams = opts.currentParams ?? {};
   const nextParams = opts.nextParams ?? currentParams;
   const inAction = opts.action !== undefined;
-  const actionId = resolveActionId(opts.action);
+  const actionId = resolveTestActionId(opts.action, "runClientRevalidate");
   const defaultShouldRevalidate = lockedClientDefault({
     actionRequest: opts.actionRequest ?? inAction,
     currentParams,

package/src/testing/run-loader.ts

@@ -51,6 +51,7 @@ import type { CacheProfile } from "../cache/profile-registry.js";
 import type { PartialCacheOptions } from "../types/cache-types.js";
 import type { HandlerContext } from "../types/handler-context.js";
 import { resolveLoaderData } from "../router/segment-resolution/loader-cache.js";
+import { armLoaderTagSets } from "../cache/cache-tag.js";
 import {
   createTestRequestContext,
   buildRunSnapshot,
@@ -385,7 +386,9 @@ function cacheLoaderId(loader: RunnableLoader<unknown>): string {
 /**
  * Call the loader: directly, or through its `cache()` binding (the funnel a
  * route's DSL loaders take, loader-cache.ts resolveLoaderData), whose MISS
- * reads the binding through the handler ctx's use().
+ * reads the binding through the handler ctx's use(). A binding arms the
+ * per-execution loader tag sets first, as a match that resolves one does
+ * (match-api.ts, bindsLoaderCache).
  */
 function invokeLoader<T>(
   loader: RunnableLoader<T>,
@@ -395,6 +398,7 @@ function invokeLoader<T>(
 ): Promise<T> {
   const run = () => Promise.resolve(loaderFn(loaderCtx));
   if (!opts.cache) return run();
+  armLoaderTagSets();
   const handlerCtx = {
     params: loaderCtx.params,
     use: run,

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

@@ -1,195 +1,132 @@
 /**
- * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ * runTransitionWhen — unit-test a transition({ when }) browser predicate.
  *
- * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
- * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
- * function), and gateTransitions. 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.
+ * Builds the context and evaluates the predicate through the SAME browser
+ * functions the router uses at navigation time (browser/transition-when.ts):
+ * a throw counts as false and is logged. `from`/`to` take a URL string or a
+ * partial RouteLocation; a `state` given as location-state entries
+ * (`[Def(value)]`, what Link/push take) is stored the way a push stores it,
+ * so `Def.read(ctx.to)` reads it back. Accepts the predicate or a whole
+ * TransitionConfig.
  *
- * 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.
+ * Synchronous: a transition predicate returns a boolean and 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";
+  createTransitionWhenContext,
+  evaluateTransitionWhen,
+  type RouteLocationInput,
+} from "../browser/transition-when.js";
+import {
+  buildHistoryState,
+  resolveNavigationState,
+} from "../browser/history-state.js";
+import { isLocationStateEntry } from "../browser/react/location-state-shared.js";
+import { resolveTestActionId } from "./internal/action-id.js";
 import type {
-  ResolvedSegment,
+  RouteLocation,
   TransitionConfig,
   TransitionWhenContext,
+  TransitionWhenFn,
+  TransitionWhenKind,
 } from "../types/segments.js";
-import type { OnErrorCallback } from "../types/error-types.js";
-import type { EntryData } from "../server/context.js";
-import { evaluatePprTransitionWhen } from "../router/transition-when.js";
-import { invokeOnError } from "../router/error-handling.js";
-import { toURL } from "./to-url.js";
 
-/**
- * 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 readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
-  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`). */
+type ImportedAction = (...args: never[]) => unknown;
+
+/** A navigation side: a URL, or a partial RouteLocation. */
+export type RunTransitionWhenLocation =
+  | string
+  | URL
+  | (Partial<Omit<RouteLocation, "url">> & { url?: string | URL });
+
+/** The action fields of a `kind: "action"` context. */
+export interface RunTransitionWhenAction {
+  /** The triggering action: an imported server action or its actionId. */
+  ref?: ImportedAction | string;
   formData?: FormData;
-  /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
-  onError?: OnErrorCallback;
-  /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
-  ppr?: boolean;
+  /** The action's return value on success. */
+  result?: unknown;
+  /** What a failed action threw (the error lane). */
+  error?: unknown;
 }
 
-/**
- * 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;
+export interface RunTransitionWhenOptions {
+  /** Defaults to `"action"` when `action` is given, `"push"` otherwise. */
+  kind?: TransitionWhenKind;
+  /** The committed location being left. Defaults to `http://localhost/`. */
+  from?: RunTransitionWhenLocation;
+  /** The destination. Defaults to `from`; always `from` for "action" and "revalidate". */
+  to?: RunTransitionWhenLocation;
   /**
-   * The production-assembled predicate context. Undefined when the config has
-   * no `when` predicate.
+   * The triggering action (like runClientRevalidate's): an imported server
+   * action (id via `$id ?? $$id`), an actionId string, or
+   * `{ ref, formData, result, error }`.
    */
-  whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
-  /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
-  ctx: RequestContext<TEnv>;
+  action?: ImportedAction | string | RunTransitionWhenAction;
 }
 
-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>;
+export interface RunTransitionWhenResult {
+  /** True when the navigation holds (the predicate did not return false or throw, or there is none). */
+  applied: boolean;
+  /** Inverse of `applied`. */
+  gatedOff: boolean;
+  /** The context the predicate received. */
+  context: TransitionWhenContext;
+}
 
-  // 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;
+const DEFAULT_URL = "http://localhost/";
 
-  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;
+function toStoredState(state: unknown): unknown {
+  if (
+    Array.isArray(state) &&
+    state.length > 0 &&
+    isLocationStateEntry(state[0])
+  ) {
+    return buildHistoryState(resolveNavigationState(state));
+  }
+  return state;
+}
+
+function toLocation(
+  value: RunTransitionWhenLocation | undefined,
+  fallback: string | URL,
+): RouteLocationInput {
+  if (value === undefined) return { url: fallback };
+  if (typeof value === "string" || value instanceof URL) return { url: value };
+  return {
+    url: value.url ?? fallback,
+    params: value.params,
+    routeName: value.routeName,
+    state: toStoredState(value.state),
+  };
+}
 
-  return runWithRequestContext(reqCtx, () => {
-    if (opts.ppr) {
-      const entry = {
-        type: "route",
-        id: "tx-when-entry",
-        shortCode: "tx-when-seg",
-        parent: null,
-        transition: configForGate,
-        layout: [],
-        parallel: {},
-      } as unknown as EntryData;
-      evaluatePprTransitionWhen(
-        [entry],
-        reqCtx,
-        { params: reqCtx.params, routeName: opts.toRouteName },
-        (error, segmentId) =>
-          invokeOnError(
-            opts.onError,
-            error,
-            "rendering",
-            {
-              request: reqCtx.request,
-              url: reqCtx.url,
-              params: reqCtx.params,
-              segmentId,
-            },
-            "RSC",
-          ),
-      );
-    }
-    // Ordinary predicates are collected here and evaluated by the gate. PPR
-    // predicates keep the decision already evaluated before this step.
-    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;
-    const [gatedSegment] = gateTransitions(
-      [segment],
-      reqCtx as Parameters<typeof gateTransitions>[1],
-      opts.onError,
-    );
-    const kept = gatedSegment.transition !== undefined;
-    return { kept, dropped: !kept, whenContext, ctx: reqCtx };
+export function runTransitionWhen(
+  whenOrConfig: TransitionWhenFn | TransitionConfig,
+  opts: RunTransitionWhenOptions = {},
+): RunTransitionWhenResult {
+  const actionOption =
+    typeof opts.action === "function" || typeof opts.action === "string"
+      ? { ref: opts.action }
+      : opts.action;
+  const from = toLocation(opts.from, DEFAULT_URL);
+  const context = createTransitionWhenContext({
+    kind: opts.kind ?? (actionOption ? "action" : "push"),
+    from,
+    to: opts.to === undefined ? undefined : toLocation(opts.to, from.url),
+    ...(actionOption
+      ? {
+          action: {
+            id: resolveTestActionId(actionOption.ref, "runTransitionWhen"),
+            formData: actionOption.formData,
+            result: actionOption.result,
+            error: actionOption.error,
+          },
+        }
+      : {}),
   });
+  const when =
+    typeof whenOrConfig === "function" ? whenOrConfig : whenOrConfig.when;
+  const applied = when ? evaluateTransitionWhen(when, context) : true;
+  return { applied, gatedOff: !applied, context };
 }