@rangojs/router 0.10.1 → 0.11.0

package/src/client-urls/navigation.ts

@@ -1,8 +1,13 @@
 "use client";
 
 import { startTransition } from "react";
+import { makeIsAction } from "../router/is-action.js";
+import {
+  lockedClientDefault,
+  runClientRevalidateChain,
+} from "./revalidate-chain.js";
 import { encodeClientRevalidationDecisions } from "./revalidation-protocol.js";
-import type { ClientRevalidateArgs, ClientUrlPatterns } from "./types.js";
+import type { ClientUrlPatterns } from "./types.js";
 
 export interface ClientUrlNavigationIntent {
   readonly routeId: string;
@@ -156,6 +161,17 @@ export function beginClientUrlNavigation(
 export function collectClientRevalidationDecisions(options: {
   currentUrl: URL;
   nextUrl: URL;
+  /**
+   * True only when the decisions ride the action POST itself — the one
+   * request the server evaluates with actionContext (locked default true).
+   * Action-triggered refetch GETs (partial-update terminals) pass false:
+   * the server gives those navigation defaults, and the delta gate below
+   * must diff against the default the SERVER will use, or a force decision
+   * on the refetch would be silently swallowed as "equals default".
+   */
+  actionRequest: boolean;
+  /** Action TRUTH for the predicates' isAction() matcher; may be true on
+   * refetch GETs where actionRequest is false. */
   isAction: boolean;
   actionId?: string;
   stale: boolean;
@@ -163,7 +179,8 @@ export function collectClientRevalidationDecisions(options: {
   const group = activeGroup;
   if (!group) return null;
 
-  const { currentUrl, nextUrl, isAction, actionId, stale } = options;
+  const { currentUrl, nextUrl, actionRequest, isAction, actionId, stale } =
+    options;
   const currentLocal = stripMountPrefix(currentUrl.pathname, group.mount);
   if (currentLocal === null) return null;
   const currentMatch = group.definition.match(currentLocal);
@@ -178,52 +195,33 @@ export function collectClientRevalidationDecisions(options: {
     nextLocal === null ? null : group.definition.match(nextLocal);
   const nextParams = nextMatch?.params ?? {};
 
-  // Locked default, mirrored client-side: actions re-run route-owned loaders;
-  // navigations re-run them when params or search changed.
-  const paramsEqual = (
-    a: Record<string, string>,
-    b: Record<string, string>,
-  ): boolean => {
-    const aKeys = Object.keys(a);
-    return (
-      aKeys.length === Object.keys(b).length &&
-      aKeys.every((key) => a[key] === b[key])
-    );
+  const defaultShouldRevalidate = lockedClientDefault({
+    actionRequest,
+    currentParams: currentMatch.params,
+    nextParams,
+    currentUrl,
+    nextUrl,
+  });
+
+  const baseArgs = {
+    currentUrl,
+    nextUrl,
+    currentParams: currentMatch.params,
+    nextParams,
+    stale,
+    isAction: makeIsAction(actionId, isAction),
+    ...(actionId !== undefined ? { actionId } : {}),
   };
-  const defaultShouldRevalidate = isAction
-    ? true
-    : !paramsEqual(currentMatch.params, nextParams) ||
-      currentUrl.search !== nextUrl.search;
-
   const skip: string[] = [];
   const force: string[] = [];
   for (const { loader, revalidate } of record.loaders) {
     if (revalidate.length === 0) continue;
-    const args: ClientRevalidateArgs = {
-      currentUrl,
-      nextUrl,
-      currentParams: currentMatch.params,
-      nextParams,
+    const decision = runClientRevalidateChain(
+      revalidate,
+      baseArgs,
       defaultShouldRevalidate,
-      stale,
-      isAction,
-      ...(actionId !== undefined ? { actionId } : {}),
-    };
-    // Same iteration contract as the server: every predicate runs, the last
-    // boolean verdict wins. A throwing predicate fails open to the default
-    // (mirrors evaluateRevalidation's fail-open).
-    let decision = defaultShouldRevalidate;
-    for (const fn of revalidate) {
-      try {
-        const verdict = fn(args);
-        if (typeof verdict === "boolean") decision = verdict;
-      } catch (error) {
-        console.error(
-          `[@rangojs/router] clientUrls revalidate() threw for loader "${loader.$$id}"; using default decision:`,
-          error,
-        );
-      }
-    }
+      `loader "${loader.$$id}"`,
+    );
     if (decision === defaultShouldRevalidate) continue;
     (decision ? force : skip).push(loader.$$id);
   }

package/src/client-urls/revalidate-chain.ts

@@ -0,0 +1,83 @@
+/**
+ * The clientUrls revalidate() chain evaluator, shared by the browser
+ * collector (navigation.ts) and the public testing primitive
+ * (testing/run-client-revalidate.ts) so the two can never drift.
+ *
+ * Semantics mirror the server's evaluateRevalidation
+ * (src/router/revalidation.ts): a boolean verdict is a hard decision and
+ * short-circuits the rest of the chain; a `{ defaultShouldRevalidate }`
+ * object updates the running suggestion, which later predicates receive as
+ * their `defaultShouldRevalidate`; null/undefined defers; a throwing
+ * predicate fails open to the current suggestion (logged). One deliberate
+ * divergence: the object form is accepted only with a boolean value — the
+ * server is laxer, but never re-compares the value, while this decision
+ * feeds a strict-equality delta gate and the wire encoding
+ * (navigation.ts), where a truthy non-boolean would invert intent.
+ */
+
+import { paramsEqual } from "../router/params-util.js";
+import type { ClientRevalidateArgs, ClientRevalidateFn } from "./types.js";
+
+/**
+ * The locked default the server will apply to the request these decisions
+ * ride on. `actionRequest` is about the REQUEST, not the user gesture: only
+ * the action POST itself is evaluated server-side with actionContext
+ * (default `true`); the follow-up refetch GETs an action can trigger carry
+ * no actionContext and get navigation defaults — even though their
+ * predicates still see `isAction()` as true.
+ */
+export function lockedClientDefault(options: {
+  actionRequest: boolean;
+  currentParams: Record<string, string>;
+  nextParams: Record<string, string>;
+  currentUrl: URL;
+  nextUrl: URL;
+}): boolean {
+  if (options.actionRequest) return true;
+  return (
+    !paramsEqual(options.currentParams, options.nextParams) ||
+    options.currentUrl.search !== options.nextUrl.search
+  );
+}
+
+export function runClientRevalidateChain(
+  fns: readonly ClientRevalidateFn[],
+  baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate">,
+  lockedDefault: boolean,
+  label: string,
+): boolean {
+  let suggestion = lockedDefault;
+  for (const fn of fns) {
+    let verdict: ReturnType<ClientRevalidateFn>;
+    try {
+      verdict = fn({ ...baseArgs, defaultShouldRevalidate: suggestion });
+    } catch (error) {
+      console.error(
+        `[@rangojs/router] clientUrls revalidate() threw for ${label}; using default decision:`,
+        error,
+      );
+      continue;
+    }
+    if (
+      process.env.NODE_ENV !== "production" &&
+      verdict != null &&
+      typeof (verdict as { then?: unknown }).then === "function"
+    ) {
+      console.warn(
+        `[rango] clientUrls revalidate() for ${label} returned a Promise; ` +
+          `predicates must be synchronous (return a boolean, ` +
+          `{ defaultShouldRevalidate }, or null/undefined). The async result ` +
+          `was IGNORED and the default (${suggestion}) was kept.`,
+      );
+    }
+    if (typeof verdict === "boolean") return verdict;
+    if (
+      verdict &&
+      typeof verdict === "object" &&
+      typeof verdict.defaultShouldRevalidate === "boolean"
+    ) {
+      suggestion = verdict.defaultShouldRevalidate;
+    }
+  }
+  return suggestion;
+}

package/src/client-urls/types.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactNode } from "react";
 import type {
+  IsActionFn,
   LoaderDefinition,
   LoaderOptions,
   TransitionConfig,
@@ -54,7 +55,8 @@ export type ClientLayoutFn = <const TItems extends ClientUrlItems>(
  * subset of the server ShouldRevalidateFn args — the predicate RUNS IN THE
  * BROWSER (it is declared in a "use client" module and never crosses the
  * projection boundary); only its decision is sent to the server. There is no
- * `context` — no server handler context exists where this executes.
+ * `context` — no server handler context exists where this executes. `isAction`
+ * is the same callable matcher as on the server, not a boolean.
  */
 export interface ClientRevalidateArgs {
   /** Full URL of the page being navigated away from (current location). */
@@ -66,21 +68,46 @@ export interface ClientRevalidateArgs {
   /** Route params for the navigation target (definition-local match). */
   readonly nextParams: Record<string, string>;
   /**
-   * The locked default decision for this loader, computed client-side with
-   * the same rules the server would apply: `true` on actions and when
-   * params/search changed, `false` otherwise. Return it for default behavior
-   * plus your own conditions.
+   * The current default decision for this loader, computed client-side with
+   * the same rules the server applies to the request the decisions ride on:
+   * `true` when they ride the action POST itself, otherwise `true` when
+   * params/search changed. (An action-triggered refetch GET gets navigation
+   * defaults — matching the server — even though `isAction()` is true.)
+   * Earlier predicates' `{ defaultShouldRevalidate }` verdicts thread into
+   * this value, exactly like the server chain. Return it for default
+   * behavior plus your own conditions.
    */
   readonly defaultShouldRevalidate: boolean;
   /** True when this is a stale history-entry background revalidation. */
   readonly stale: boolean;
-  /** True when revalidation is triggered by a server action. */
-  readonly isAction: boolean;
-  /** The triggering server action's id, when isAction. */
+  /**
+   * Same {@link IsActionFn} the server `revalidate()` predicate receives.
+   * In the browser the match is against the action stub's hashed `$$id`
+   * (the id the action request carries) — not the RSC file-path `$id`.
+   */
+  readonly isAction: IsActionFn;
+  /**
+   * The triggering server action's id, when this is an action. In the
+   * browser this is the hashed `hash#export` form (`$$id`), not the RSC
+   * file-path `src/...#export`. Prefer `isAction(ref)` — a substring of
+   * `path#export` will not match here in production.
+   */
   readonly actionId?: string;
 }
 
-export type ClientRevalidateFn = (args: ClientRevalidateArgs) => boolean;
+/**
+ * Client-run per-loader predicate, with the same chain semantics as the
+ * server's `revalidate()` (src/router/revalidation.ts): a boolean is a HARD
+ * decision that short-circuits the rest of the chain; a
+ * `{ defaultShouldRevalidate }` object updates the running suggestion, which
+ * later predicates receive as their `defaultShouldRevalidate`; `void` /
+ * `null` / `undefined` defers to the current suggestion — so
+ * `isAction(CartActions) || undefined` defers to the locked default.
+ * Predicates must be synchronous; the object form requires a boolean value.
+ */
+export type ClientRevalidateFn = (
+  args: ClientRevalidateArgs,
+) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 export interface ClientUrlLoaderRecord {
   readonly loader: LoaderDefinition<any, any>;
@@ -158,10 +185,11 @@ export interface ClientUrlHelpers {
   readonly loading: (component: ReactNode) => ClientUrlItem;
   /**
    * Per-loader revalidation predicate, valid inside a loader() use callback
-   * only. Runs IN THE BROWSER with client-computable args; return true to
-   * re-run the loader, false to keep held data. Absent predicates (and
-   * requests that carry no decisions: no-JS, PE, prefetch, document loads)
-   * follow the locked server defaults.
+   * only. Runs IN THE BROWSER with client-computable args (including the
+   * callable `isAction(...refs)` matcher); return true to re-run the loader,
+   * false to keep held data. Absent predicates (and requests that carry no
+   * decisions: no-JS, PE, prefetch, document loads) follow the locked server
+   * defaults.
    */
   readonly revalidate: (fn: ClientRevalidateFn) => ClientUrlItem;
   /**

package/src/client.tsx

@@ -470,3 +470,8 @@ export { useReverse } from "./browser/react/use-reverse.js";
 export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
 export type { LoaderDefinition } from "./types.js";
+export type { ActionRef, IsActionFn } from "./types.js";
+export type {
+  ClientRevalidateArgs,
+  ClientRevalidateFn,
+} from "./client-urls/types.js";

package/src/index.rsc.ts

@@ -45,6 +45,7 @@ export type {
   RevalidateParams,
   Revalidate,
   ActionRef,
+  IsActionFn,
   RouteKeys,
   // Loader types
   LoaderDefinition,

package/src/index.ts

@@ -45,6 +45,7 @@ export type {
   RevalidateParams,
   Revalidate,
   ActionRef,
+  IsActionFn,
   RouteKeys,
   // Loader types
   LoaderDefinition,

package/src/router/is-action.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared `isAction()` matcher for revalidate predicates (server + clientUrls).
+ *
+ * Action identity is `actionId`. The helper resolves an imported reference the
+ * same way the action boundary derives that id (`$id ?? $$id`), so a
+ * rename-safe `isAction(fn)` / `isAction(namespace)` match works in both the
+ * RSC environment (file-path `$id`) and the browser (hashed `$$id`).
+ */
+
+import type { ActionRef, IsActionFn } from "../types.js";
+
+// Bind preservation is per-reference, in expose-action-id.ts. Do not patch
+// Function.prototype.bind here (rsc+ssr share a realm; global wrap stacks).
+
+/**
+ * Resolve a server-action reference's stable id, mirroring how the action
+ * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
+ * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
+ * production RSC build when present, otherwise React's `$$id`. Resolving both
+ * the incoming `actionId` and the reference with the same precedence makes
+ * `isAction()` form-agnostic across dev and production.
+ */
+export function resolveActionRefId(ref: unknown): string | undefined {
+  if (ref == null) return undefined;
+  const r = ref as { $id?: unknown; $$id?: unknown };
+  if (typeof r.$id === "string") return r.$id;
+  if (typeof r.$$id === "string") return r.$$id;
+  return undefined;
+}
+
+/**
+ * Depth cap for the object walk. The supported shapes need at most two
+ * object levels — a namespace (values are functions) and a grouped-namespace
+ * literal (`{ Cart: CartActions }`, values are namespaces). The cap keeps an
+ * accidentally passed arbitrary object (a ctx, a data blob — it type-checks
+ * as Record<string, unknown>) from triggering a full deep traversal on every
+ * predicate call.
+ */
+const MAX_ACTION_REF_DEPTH = 3;
+
+function matchesActionRef(
+  ref: unknown,
+  currentActionId: string,
+  seen: Set<object>,
+  depth: number,
+): boolean {
+  if (ref == null) return false;
+  if (typeof ref === "function") {
+    return resolveActionRefId(ref) === currentActionId;
+  }
+  if (typeof ref !== "object") return false;
+  if (depth >= MAX_ACTION_REF_DEPTH) return false;
+  if (seen.has(ref)) return false;
+  seen.add(ref);
+  // Namespace, object literal, or grouped namespaces
+  // (`{ Cart: CartActions, Order: OrderActions }`): walk every value.
+  // Object.values invokes getters; a throwing getter must not abort the
+  // predicate into the fail-open path, so treat it as "no match here".
+  let values: unknown[];
+  try {
+    values = Object.values(ref);
+  } catch {
+    return false;
+  }
+  for (const value of values) {
+    if (matchesActionRef(value, currentActionId, seen, depth + 1)) return true;
+  }
+  return false;
+}
+
+/**
+ * Build the `isAction()` helper bound to the current action. Called with no
+ * arguments it answers "is this request an action at all?" — `true` during
+ * action handling (including action-triggered refetches that carry no id
+ * yet), `false` on plain navigation. Called with one or more action
+ * references it narrows to those: a single imported action, several
+ * (variadic), a namespace import (`import * as Mod`), an object literal of
+ * actions (`{ addToCart, removeFromCart }`), or a grouped namespace object.
+ * Returns `false` when there is no action or nothing matches.
+ *
+ * `inAction` is the request kind. It defaults to "an id is present" so
+ * existing server call sites stay a single argument. The client passes the
+ * explicit flag so a refetch terminal with `isAction: true` still answers
+ * bare `isAction()` even if `actionId` was not threaded.
+ */
+export function makeIsAction(
+  currentActionId: string | undefined,
+  inAction: boolean = currentActionId !== undefined,
+): IsActionFn {
+  return (...actions: ActionRef[]): boolean => {
+    if (!inAction) return false;
+    if (actions.length === 0) return true;
+    if (!currentActionId) return false;
+    const seen = new Set<object>();
+    for (const action of actions) {
+      if (matchesActionRef(action, currentActionId, seen, 0)) return true;
+    }
+    return false;
+  };
+}

package/src/router/revalidation.ts

@@ -4,7 +4,7 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext, ActionRef } from "../types";
+import type { ResolvedSegment, HandlerContext } from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -15,52 +15,7 @@ import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { paramsEqual } from "./params-util.js";
-
-/**
- * Resolve a server-action reference's stable id, mirroring how the action
- * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
- * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
- * production RSC build when present, otherwise React's `$$id`. Resolving both
- * the incoming `actionId` and the reference with the same precedence makes
- * `isAction()` form-agnostic across dev and production.
- */
-function resolveActionRefId(ref: unknown): string | undefined {
-  if (ref == null) return undefined;
-  const r = ref as { $id?: unknown; $$id?: unknown };
-  if (typeof r.$id === "string") return r.$id;
-  if (typeof r.$$id === "string") return r.$$id;
-  return undefined;
-}
-
-/**
- * Build the `isAction()` helper bound to the current action's id. Called with no
- * arguments it answers "is this request an action at all?" (any action) — `true`
- * during action handling, `false` on plain navigation. Called with one or more
- * action references it narrows to those: a single imported action, several
- * (variadic), or any export of a namespace import (`import * as Mod`). Returns
- * `false` when there is no action (plain navigation) or nothing matches.
- */
-function makeIsAction(
-  currentActionId: string | undefined,
-): (...actions: ActionRef[]) => boolean {
-  return (...actions: ActionRef[]): boolean => {
-    if (!currentActionId) return false;
-    // Bare isAction(): an action is in flight (currentActionId is set) and the
-    // caller did not narrow to a specific action, so this is "any action".
-    if (actions.length === 0) return true;
-    for (const action of actions) {
-      if (typeof action === "function") {
-        if (resolveActionRefId(action) === currentActionId) return true;
-      } else if (action && typeof action === "object") {
-        // Namespace import: match any export of the module.
-        for (const value of Object.values(action)) {
-          if (resolveActionRefId(value) === currentActionId) return true;
-        }
-      }
-    }
-    return false;
-  };
-}
+import { makeIsAction } from "./is-action.js";
 
 /**
  * Options for revalidation evaluation
@@ -249,6 +204,8 @@ export async function evaluateRevalidation<TEnv>(
       ? prevRouteKey
       : undefined;
 
+  const isActionFn = makeIsAction(actionContext?.actionId);
+
   for (const { name, fn } of revalidations) {
     let result: any;
     try {
@@ -265,7 +222,7 @@ export async function evaluateRevalidation<TEnv>(
         slotName: segment.slot,
         // Action context (only populated when triggered by server action)
         actionId: actionContext?.actionId,
-        isAction: makeIsAction(actionContext?.actionId),
+        isAction: isActionFn,
         actionUrl: actionContext?.actionUrl,
         actionResult: actionContext?.actionResult,
         formData: actionContext?.formData,

package/src/rsc/server-action.ts

@@ -20,6 +20,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import { resolveActionRefId } from "../router/is-action.js";
 import type { TraceSpan } from "../router/tracing.js";
 import { gateTransitions } from "./transition-gate.js";
 import type { RscPayload } from "./types.js";
@@ -302,10 +303,7 @@ export async function executeServerAction<TEnv>(
   }
 
   // Build continuation for the revalidation phase
-  const actionMeta = loadedAction as
-    | { $id?: string; $$id?: string }
-    | undefined;
-  const resolvedActionId = actionMeta?.$id ?? actionMeta?.$$id ?? actionId;
+  const resolvedActionId = resolveActionRefId(loadedAction) ?? actionId;
 
   return {
     returnValue,

package/src/testing/index.ts

@@ -26,7 +26,7 @@
  *   condition and would throw if pulled into this barrel.
  *
  * Layers:
- * - Unit:        runMiddleware, runLoader
+ * - Unit:        runMiddleware, runLoader, runClientRevalidate
  * - Integration: dispatch (request -> Response)
  * - Cross-cut:   assertCacheStatus, assertShellStatus, assertGeneratedRoutesMatch
  * - Component:   see @rangojs/router/testing/dom (renderRoute)
@@ -53,6 +53,9 @@ export type {
   RunTransitionWhenResult,
 } from "./run-transition-when.js";
 
+export { runClientRevalidate } from "./run-client-revalidate.js";
+export type { RunClientRevalidateOptions } from "./run-client-revalidate.js";
+
 export { dispatch } from "./dispatch.js";
 export type { DispatchOptions } from "./dispatch.js";
 

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

@@ -0,0 +1,108 @@
+/**
+ * runClientRevalidate — unit-test clientUrls() revalidate() predicates.
+ *
+ * Builds the same {@link ClientRevalidateArgs} the browser collector passes
+ * and evaluates the predicate(s) through the SAME chain evaluator production
+ * uses (client-urls/revalidate-chain.ts) — locked default, boolean
+ * short-circuit, soft-verdict threading, and fail-open are the production
+ * code paths, not a re-implementation. Pass an array to test a chain.
+ *
+ * Synchronous: client revalidate functions must be sync.
+ */
+
+import { makeIsAction, resolveActionRefId } from "../router/is-action.js";
+import {
+  lockedClientDefault,
+  runClientRevalidateChain,
+} from "../client-urls/revalidate-chain.js";
+import { toURL } from "./to-url.js";
+import type {
+  ClientRevalidateArgs,
+  ClientRevalidateFn,
+} from "../client-urls/types.js";
+
+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`).
+ */
+export interface RunClientRevalidateOptions {
+  currentUrl?: string | URL;
+  nextUrl?: string | URL;
+  currentParams?: Record<string, string>;
+  nextParams?: Record<string, string>;
+  stale?: boolean;
+  /**
+   * The triggering action: a single imported reference (id resolved via
+   * `$id ?? $$id`; throws if the function carries neither) or a raw actionId
+   * string. A namespace/object is rejected — it cannot identify the ONE
+   * action that triggered the request. Omit for a plain navigation.
+   */
+  action?: ((...args: never[]) => unknown) | string;
+  /**
+   * Model an action-triggered refetch GET: predicates see `isAction()` as
+   * true, but the locked default stays the navigation default, matching how
+   * the server evaluates that request (no actionContext). Defaults to
+   * treating a provided `action` as the action POST itself.
+   */
+  actionRequest?: boolean;
+}
+
+/**
+ * Run one clientUrls `revalidate()` predicate — or a chain, in declaration
+ * order — against production-built args. Returns the final boolean decision
+ * (locked default if every predicate defers or throws).
+ */
+export function runClientRevalidate(
+  fn: ClientRevalidateFn | readonly ClientRevalidateFn[],
+  opts: RunClientRevalidateOptions = {},
+): boolean {
+  const currentUrl = toURL(opts.currentUrl, new URL(DEFAULT_URL));
+  const nextUrl = toURL(opts.nextUrl, currentUrl);
+  const currentParams = opts.currentParams ?? {};
+  const nextParams = opts.nextParams ?? currentParams;
+  const inAction = opts.action !== undefined;
+  const actionId = resolveActionId(opts.action);
+  const defaultShouldRevalidate = lockedClientDefault({
+    actionRequest: opts.actionRequest ?? inAction,
+    currentParams,
+    nextParams,
+    currentUrl,
+    nextUrl,
+  });
+
+  const baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate"> = {
+    currentUrl,
+    nextUrl,
+    currentParams,
+    nextParams,
+    stale: opts.stale ?? false,
+    isAction: makeIsAction(actionId, inAction),
+    ...(actionId !== undefined ? { actionId } : {}),
+  };
+
+  return runClientRevalidateChain(
+    Array.isArray(fn) ? fn : [fn],
+    baseArgs,
+    defaultShouldRevalidate,
+    "runClientRevalidate predicate",
+  );
+}

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

@@ -35,9 +35,7 @@ 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";
-
-const toURL = (v: string | URL, base: URL): URL =>
-  typeof v === "string" ? new URL(v, base.origin) : v;
+import { toURL } from "./to-url.js";
 
 /**
  * Options for runTransitionWhen. All navigation/action fields are optional and

package/src/testing/to-url.ts

@@ -0,0 +1,5 @@
+/** Shared string|URL coercion for the testing primitives. */
+export function toURL(value: string | URL | undefined, fallback: URL): URL {
+  if (value === undefined) return fallback;
+  return typeof value === "string" ? new URL(value, fallback.origin) : value;
+}