@rangojs/router 0.10.1 → 0.12.0

package/dist/vite/index.js

@@ -1401,6 +1401,14 @@ function isUseServerModule(filePath) {
     return false;
   }
 }
+var ACTION_BIND_HELPER_NAME = "__rangoActionBind";
+var ACTION_BIND_HELPER_SOURCE = `var ${ACTION_BIND_HELPER_NAME} = function () {
+  var bound = Function.prototype.bind.apply(this, arguments);
+  if (typeof this.$id === "string") bound.$id = this.$id;
+  if (typeof this.$$id === "string") bound.$$id = this.$$id;
+  bound.bind = ${ACTION_BIND_HELPER_NAME};
+  return bound;
+};`;
 function applyServerReferenceWrapping(code, s, hashToFileMap) {
   if (!code.includes("createServerReference(")) {
     return false;
@@ -1425,9 +1433,13 @@ function applyServerReferenceWrapping(code, s, hashToFileMap) {
         }
       }
     }
-    const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; return fn; })(${fnCall}(${idArg}${rest}))`;
+    const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; if (!Object.prototype.hasOwnProperty.call(fn, "bind")) fn.bind = ${ACTION_BIND_HELPER_NAME}; return fn; })(${fnCall}(${idArg}${rest}))`;
     s.overwrite(start, end, replacement);
   }
+  if (hasChanges) {
+    s.prepend(`${ACTION_BIND_HELPER_SOURCE}
+`);
+  }
   return hasChanges;
 }
 function transformServerReferences(code, sourceId, hashToFileMap) {
@@ -3036,6 +3048,7 @@ function useCacheTransform() {
         } catch {
           return;
         }
+        stripNullDirectiveFields(ast);
         const filePath = normalizePath(path5.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
         if (hasDirective(ast.body, "use cache")) {
@@ -3046,7 +3059,8 @@ function useCacheTransform() {
             id,
             isBuild,
             isLayoutOrTemplate,
-            transformWrapExport
+            transformWrapExport,
+            hasDirective
           );
         }
         const functionResult = transformFunctionLevelUseCache(
@@ -3065,7 +3079,7 @@ function useCacheTransform() {
     }
   };
 }
-function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport) {
+function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective) {
   const unconfirmedExports = [];
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value, name) => {
@@ -3075,6 +3089,11 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
     rejectNonAsyncFunction: false,
     filter: (name, meta) => {
       if (name === "default" && isLayoutOrTemplate) return false;
+      if (name.startsWith("$$hoist_")) return false;
+      if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+        return false;
+      }
       if (meta.isFunction !== true) {
         unconfirmedExports.push(name);
         return false;
@@ -3146,6 +3165,36 @@ function transformFunctionLevelUseCache(code, ast, filePath, sourceId, isBuild,
     return;
   }
 }
+function stripNullDirectiveFields(node) {
+  if (!node || typeof node !== "object") return;
+  const rec = node;
+  if (rec.type === "ExpressionStatement" && typeof rec.directive !== "string") {
+    delete rec.directive;
+  }
+  for (const value of Object.values(rec)) {
+    if (Array.isArray(value)) {
+      for (const item of value) stripNullDirectiveFields(item);
+    } else if (value && typeof value === "object" && "type" in value) {
+      stripNullDirectiveFields(value);
+    }
+  }
+}
+function isHoistedServerReferenceRebind(valueNode) {
+  if (!valueNode || valueNode.type !== "CallExpression") return false;
+  const first = valueNode.arguments[0];
+  return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
+}
+function functionHasUseServerDirective(valueNode, hasDirective) {
+  if (!valueNode || !("body" in valueNode)) return false;
+  const { body } = valueNode;
+  if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
+    return false;
+  }
+  return hasDirective(
+    body.body,
+    "use server"
+  );
+}
 function findFileLevelDirective(ast) {
   for (const node of ast.body ?? []) {
     if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string" && node.expression.value.startsWith("use cache")) {
@@ -3489,7 +3538,7 @@ function emitProgressiveChunkSize(value) {
 }
 function getVirtualEntrySSR(headScripts = "preinit", progressiveChunkSize) {
   const preinit = headScripts !== "preload";
-  const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference," : "createFromReadableStream,";
+  const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference,\n  getClientEntryUrl," : "createFromReadableStream,";
   const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
   const install = preinit ? `
 // Upgrade client-reference modulepreload hints to executing module scripts in
@@ -3497,6 +3546,8 @@ function getVirtualEntrySSR(headScripts = "preinit", progressiveChunkSize) {
 // See src/ssr/preinit-client-references.ts for the full rationale.
 installClientReferencePreinit(setOnClientReference);
 ` : "";
+  const bootstrapDep = preinit ? "getClientEntryUrl," : `loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),`;
   const hs = JSON.stringify(headScripts);
   const pcs = progressiveChunkSize !== void 0 ? `
   progressiveChunkSize: ${emitProgressiveChunkSize(progressiveChunkSize)},` : "";
@@ -3518,8 +3569,7 @@ export const renderHTML = createSSRHandler({
   renderToReadableStream,
   injectRSCPayload,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 
 export const captureShellHTML = createShellCaptureHandler({
@@ -3529,8 +3579,7 @@ export const captureShellHTML = createShellCaptureHandler({
   prerender,
   resume,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 
 export const resumeShellHTML = createShellResumeHandler({
@@ -3540,8 +3589,7 @@ export const resumeShellHTML = createShellResumeHandler({
   prerender,
   resume,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 `.trim();
 }
@@ -3698,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.10.1",
+  version: "0.12.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3786,6 +3834,11 @@ var package_default = {
       "react-server": "./src/deps/rsc.ts",
       default: "./src/deps/rsc.ts"
     },
+    "./internal/deps/rsc-client": {
+      types: "./dist/types/deps/rsc-client.d.ts",
+      "react-server": "./src/deps/rsc-client.ts",
+      default: "./src/deps/rsc-client.ts"
+    },
     "./internal/deps/html-stream-client": {
       types: "./dist/types/deps/html-stream-client.d.ts",
       default: "./src/deps/html-stream-client.ts"
@@ -3891,7 +3944,7 @@ var package_default = {
   },
   dependencies: {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.4",
@@ -3924,7 +3977,7 @@ var package_default = {
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     react: ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     vite: "^8.0.16",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -88,6 +88,11 @@
       "react-server": "./src/deps/rsc.ts",
       "default": "./src/deps/rsc.ts"
     },
+    "./internal/deps/rsc-client": {
+      "types": "./dist/types/deps/rsc-client.d.ts",
+      "react-server": "./src/deps/rsc-client.ts",
+      "default": "./src/deps/rsc-client.ts"
+    },
     "./internal/deps/html-stream-client": {
       "types": "./dist/types/deps/html-stream-client.d.ts",
       "default": "./src/deps/html-stream-client.ts"
@@ -179,7 +184,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -212,7 +217,7 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     "react": ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",

package/skills/client-urls/SKILL.md

@@ -91,7 +91,7 @@ export default clientUrls(({ path, layout, loader, revalidate }) => [
             nextParams,
             defaultShouldRevalidate,
           }) => {
-            if (isAction) return false;
+            if (isAction()) return false;
             return currentParams.slug !== nextParams.slug
               ? defaultShouldRevalidate
               : false;
@@ -184,14 +184,36 @@ only its _decision_ crosses the wire with the navigation request. Requests that
 carry no decisions (no-JS, progressive enhancement, prefetch, document loads)
 follow the locked server defaults.
 
+`isAction` is the same callable matcher as the server predicate, not a
+boolean. Action identity is `actionId`, whose FORM differs per environment:
+file-path `$id` (`path#export`) in the RSC env, hashed `$$id` in the
+browser — which is why the matcher (resolving an imported reference's
+`$id ?? $$id`) is the supported surface and a file-path substring on
+`actionId` is not:
+
+```ts
+import { addToCart, removeFromCart } from "./actions/cart";
+import * as CartActions from "./actions/cart";
+
+revalidate(({ isAction }) => isAction()); // any action
+revalidate(({ isAction }) => isAction(addToCart)); // one action
+revalidate(({ isAction }) => isAction(addToCart, removeFromCart)); // several
+revalidate(({ isAction }) => isAction(CartActions)); // import * as
+revalidate(({ isAction }) => isAction({ addToCart, removeFromCart })); // object
+```
+
+Bare `isAction()` is "is this an action at all?". `actionId` stays as the
+string escape hatch. Return `isAction(refs) || undefined` to defer to the
+locked default on a non-match (same idiom as the server).
+
 Two scars worth copying:
 
 - A blunt `() => false` keeps serving the OLD product on product→product
   navigations (same route, new param). Make predicates param-sensitive:
   return `defaultShouldRevalidate` when the identifying param changed.
-- One action, per-loader outcomes: a cart badge loader revalidates on actions
-  (`isAction ? defaultShouldRevalidate : false`) while product/related loaders
-  hold — three freshness outcomes in a single commit, decided per loader.
+- One action, per-loader outcomes: a cart badge loader revalidates on cart
+  actions (`isAction(CartActions)`) while product/related loaders hold —
+  three freshness outcomes in a single commit, decided per loader.
 
 ## Loaders are full citizens: signals and handles
 

package/skills/loader/SKILL.md

@@ -359,6 +359,7 @@ loader(CartLoader, () => [
 ]);
 revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
 revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+revalidate((ctx) => ctx.isAction({ addToCart, removeFromCart }) || undefined); // object form
 ```
 
 `isAction()` is a method on the revalidate predicate's **context argument** —

package/skills/testing/SKILL.md

@@ -89,6 +89,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
 | a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
 | a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`; pass `{ ppr: true }` for pre-handler timing)    | `@rangojs/router/testing`        |
+| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | `runClientRevalidate` (production `makeIsAction` + locked defaults)                           | `@rangojs/router/testing`        |
 | a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                           | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
 | a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |

package/skills/testing/setup.md

@@ -14,11 +14,11 @@ Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolv
 
 ### Functions
 
-| Function                    | Returns                                   | Use                                                                                                                                                                                                         |
-| --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                         |
-| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
-| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                  |
+| Function                    | Returns                                   | Use                                                                                                                                                                                                                                        |
+| --------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                                                        |
+| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                                                 |
 
 ### Returns — `RangoTestConfig` (from `rangoTestConfig`)
 
@@ -112,7 +112,7 @@ Scripts:
 - The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`). `renderToFlightString` / `renderServerTree` now self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
 - `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
-- The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
+- The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
 - The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
 - Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`.
 

package/skills/typesafety/route-types.md

@@ -204,6 +204,7 @@ import * as CartActions from "./actions/cart";
 revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
 revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
 revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+revalidate((ctx) => ctx.isAction({ addToCart, removeFromCart }) || undefined); // object form
 ```
 
 `ctx.isAction()` (only available on the revalidate predicate's context) returns a

package/src/browser/partial-update.ts

@@ -101,7 +101,7 @@ export type UpdateMode =
     }
   | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
-  | { type: "action"; interceptSourceUrl?: string };
+  | { type: "action"; interceptSourceUrl?: string; actionId?: string };
 
 /**
  * Type for the fetchPartialUpdate function
@@ -200,7 +200,16 @@ export function createPartialUpdater(
       clientRevalidation = collectClientRevalidationDecisions({
         currentUrl: new URL(previousUrl, window.location.origin),
         nextUrl: new URL(url, window.location.origin),
-        isAction: false,
+        // This partial fetch is a GET the server evaluates WITHOUT
+        // actionContext (navigation defaults) even when it is an
+        // action-triggered refetch — so the decision baseline is never the
+        // action default here. Predicates still see isAction()/actionId
+        // truthfully for matching.
+        actionRequest: false,
+        isAction: mode.type === "action",
+        ...(mode.type === "action" && mode.actionId !== undefined
+          ? { actionId: mode.actionId }
+          : {}),
         stale: mode.type === "stale-revalidation",
       });
     } catch {

package/src/browser/server-action-bridge.ts

@@ -145,6 +145,7 @@ export function createServerActionBridge(
   async function refetchRoute(opts?: {
     segments?: string[];
     interceptSourceUrl?: string | null;
+    actionId?: string;
   }): Promise<void> {
     const src = opts?.interceptSourceUrl ?? null;
     const navTx = createNavigationTransaction(
@@ -167,6 +168,7 @@ export function createServerActionBridge(
         {
           type: "action" as const,
           ...(src ? { interceptSourceUrl: src } : {}),
+          ...(opts?.actionId !== undefined ? { actionId: opts.actionId } : {}),
         },
       );
     } finally {
@@ -309,6 +311,9 @@ export function createServerActionBridge(
         clientRevalidation = collectClientRevalidationDecisions({
           currentUrl: actionPageUrl,
           nextUrl: actionPageUrl,
+          // Decisions ride the action POST itself — the server evaluates it
+          // with actionContext, so the locked default is the action default.
+          actionRequest: true,
           isAction: true,
           actionId: id,
           stale: false,
@@ -707,7 +712,7 @@ export function createServerActionBridge(
             // Invalidation is deferred to finalizeAction(); here we only trigger
             // the revalidation refetch of the new route (suppressed on keep).
             if (!scenario.onInterceptRoute && !keepCache) {
-              refetchRoute().catch((error) => {
+              refetchRoute({ actionId: id }).catch((error) => {
                 if (isBackgroundSuppressible(error)) return;
                 console.error(
                   "[Browser] Background revalidation failed:",
@@ -724,6 +729,7 @@ export function createServerActionBridge(
           if (!keepCache) {
             await refetchRoute({
               interceptSourceUrl: store.getInterceptSourceUrl(),
+              actionId: id,
             });
           }
           break;
@@ -737,7 +743,7 @@ export function createServerActionBridge(
           // resolving last must discharge a directive-free sibling's repair.
           // See the keep row in docs/design/rango-state-cookie.md (the all-keep
           // edge, and the benign re-mark-stale-after-refetch end-state delta).
-          await refetchRoute({ interceptSourceUrl });
+          await refetchRoute({ interceptSourceUrl, actionId: id });
           break;
         }
 
@@ -759,6 +765,7 @@ export function createServerActionBridge(
           await refetchRoute({
             segments: segmentsToSend,
             interceptSourceUrl,
+            actionId: id,
           });
           break;
         }

package/src/cache/cache-runtime.ts

@@ -19,7 +19,7 @@
 import {
   encodeReply,
   createClientTemporaryReferenceSet,
-} from "@vitejs/plugin-rsc/rsc";
+} from "../deps/rsc-client.js";
 import {
   getRequestContext,
   runWithRequestContext,

package/src/cache/segment-codec.ts

@@ -15,8 +15,8 @@ import { segmentFragment } from "../segment-fragments.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
-} from "@vitejs/plugin-rsc/rsc";
-import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
+} from "../deps/rsc.js";
+import { createFromReadableStream } from "../deps/rsc-client.js";
 
 // Preserve embedded server references on a cache/prerender HIT so they
 // re-serialize to the client instead of resolving to a raw function React

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;
+}