@rangojs/router 0.10.0 → 0.11.0

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

@@ -32,7 +32,7 @@ index.rsc.ts` alias are all in [`./setup.md`](./setup.md). Read it before writin
 > [`./bindings.md`](./bindings.md).
 
 For the long-form prose guide (setup walkthrough + migration), see
-[`docs/testing.md`](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md)
+[`docs/testing.md`](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md)
 (the `docs/` directory is not shipped in the published package, so this is an
 absolute link).
 
@@ -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/bindings.md

@@ -100,4 +100,4 @@ describe("bindings seam", () => {
 
 - (cross-cutting)
 - Siblings: `./loader.md`, `./middleware.md`, `./server-actions.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"

package/skills/testing/cache-prerender.md

@@ -169,4 +169,4 @@ expect(await store.getShell(key)).not.toBeNull();
 
 - `/caching`, `/prerender`, `/use-cache`, `/ppr` — the DSL this tests
 - Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/client-components.md

@@ -128,4 +128,4 @@ it("resolves params + reverse + Outlet through the layout chain", async () => {
 
 - `/hooks` — the DSL this tests
 - Siblings: `./handles.md`, `./reverse-and-types.md`, `./render-handler.md`, `./e2e-parity.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Reverse and components" (and the "Catch: streaming `use(promise)` Suspense content" subsection)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Reverse and components" (and the "Catch: streaming `use(promise)` Suspense content" subsection)

package/skills/testing/e2e-parity.md

@@ -122,4 +122,4 @@ A `submit` intent does NOT replay against a snapshot of the server — it submit
 
 - `/hooks`, `/view-transitions` — the DSL this tests
 - Siblings: [`./cache-prerender.md`](./cache-prerender.md), [`./client-components.md`](./client-components.md)
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "E2E with dev/prod and PE parity" (and "Running a subset locally")
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "E2E with dev/prod and PE parity" (and "Running a subset locally")

package/skills/testing/flight.md

@@ -88,4 +88,4 @@ it("snapshots the normalized payload", async () => {
 
 - `/route` — the DSL this tests
 - Siblings: `./setup.md`, `./server-tree.md`, `./render-handler.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderToFlightString — real async Server Components"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "renderToFlightString — real async Server Components"

package/skills/testing/handles.md

@@ -150,4 +150,4 @@ it("renders the seeded trail (seed the INPUT pushes, the collect runs)", async (
 
 - `/handler-use`, `/breadcrumbs` — the DSL this tests
 - Siblings: `./loader.md`, `./client-components.md`, `./render-handler.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Testing a handle's collect/accumulator"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Testing a handle's collect/accumulator"

package/skills/testing/loader.md

@@ -127,4 +127,4 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 
 - `/loader` — the DSL this tests
 - Siblings: `./handles.md`, `./reverse-and-types.md`, `./bindings.md`, `./server-actions.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Loaders — the raw body or a registered createLoader"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Loaders — the raw body or a registered createLoader"

package/skills/testing/middleware.md

@@ -96,4 +96,4 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 
 - `/middleware` — the DSL this tests
 - Siblings: `./response-routes.md`, `./server-actions.md`, `./loader.md`, `./bindings.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Middleware"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Middleware"

package/skills/testing/render-handler.md

@@ -119,4 +119,4 @@ it("asserts the client-cache directives", async () => {
 
 - `/route` — the DSL this tests
 - Siblings: [`./server-tree.md`](./server-tree.md), [`./server-actions.md`](./server-actions.md), [`./setup.md`](./setup.md), [`./loader.md`](./loader.md)
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderHandler — run a real route handler and assert its RSC"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "renderHandler — run a real route handler and assert its RSC"

package/skills/testing/response-routes.md

@@ -92,4 +92,4 @@ describe("api routes via dispatch", () => {
 
 - `/response-routes`, `/mime-routes` — the DSL this tests
 - Siblings: `./middleware.md`, `./setup.md`, `./cache-prerender.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "dispatch — request to Response" (the `rangoTestConfig` preset stubs `@vitejs/plugin-rsc/rsc`, so no per-file `vi.mock` is needed)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "dispatch — request to Response" (the `rangoTestConfig` preset stubs `@vitejs/plugin-rsc/rsc`, so no per-file `vi.mock` is needed)

package/skills/testing/reverse-and-types.md

@@ -82,4 +82,4 @@ For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` file
 
 - `/typesafety`, `/links` — the DSL this tests
 - Siblings: `./client-components.md`, `./loader.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Type-level tests — make misuse fail to compile"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Type-level tests — make misuse fail to compile"

package/skills/testing/server-actions.md

@@ -104,4 +104,4 @@ it("asserts the client-cache directives an action issued", async () => {
 
 - `/server-actions` — the DSL this tests
 - Siblings: `./render-handler.md`, `./middleware.md`, `./loader.md`, `./bindings.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "runInRequestContext — the handler / server-action test primitive"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "runInRequestContext — the handler / server-action test primitive"

package/skills/testing/server-tree.md

@@ -125,4 +125,4 @@ it("asserts the server-rendered host content", async () => {
 
 - `/route` — the DSL this tests
 - Siblings: `./flight.md`, `./render-handler.md`, `./setup.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderServerTree — serialize then deserialize to an inspectable tree" (and the "findElements / textContent" subsection)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "renderServerTree — serialize then deserialize to an inspectable tree" (and the "findElements / textContent" subsection)

package/skills/testing/setup.md

@@ -120,4 +120,4 @@ Scripts:
 
 - (cross-cutting)
 - Siblings: `./flight.md`, `./server-tree.md`, `./render-handler.md`, `./response-routes.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")

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

@@ -207,8 +207,8 @@ interface CacheEnvelope {
  * leader (function threw, or the result was not serializable) propagates to
  * current waiters, which then retry fresh.
  *
- * A leader that NEVER settles must not hang followers (scar tissue, autobarn
- * pilot outage): a background shell capture's render became leader, awaited a
+ * A leader that NEVER settles must not hang followers (scar tissue, production
+ * pilot incident): a background shell capture's render became leader, awaited a
  * tarpitting upstream fetch, and workerd killed the capture's waitUntil context
  * — orphaning the leader promise as permanently pending, its map entry never
  * cleared. Every later document render calling the same cached function (an

package/src/cache/cf/cf-cache-constants.ts

@@ -86,7 +86,7 @@ export const MAX_REVALIDATION_INTERVAL = 30;
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
  *
- * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 25ms, raised from 10: Workers logs (production pilot) showed the
  * 10ms budget firing frequently on cold colos where the first Cache API touch
  * is slow but healthy — each false positive downgrades a warm L1 HIT to an
  * L2/render round trip that costs far more than the 15ms of extra patience.

package/src/cache/cf/cf-cache-store.ts

@@ -2383,7 +2383,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
    * and the entry silently never reaches L2 (observed in production for
    * "use cache" items whose serialized args — e.g. a CMS query object — blow
-   * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+   * the cap; production pilot). Keys are opaque storage identifiers, so
    * normalization is semantics-preserving as long as distinct logical keys
    * stay distinct: colliding requires an identical 400-byte prefix AND a
    * 128-bit SHA-256 collision. Deterministic, so every family's read, write,

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,