@rangojs/router 0.10.1 → 0.11.0

package/dist/types/browser/partial-update.d.ts

@@ -52,6 +52,7 @@ export type UpdateMode = {
 } | {
     type: "action";
     interceptSourceUrl?: string;
+    actionId?: string;
 };
 /**
  * Type for the fetchPartialUpdate function

package/dist/types/client-urls/navigation.d.ts

@@ -31,6 +31,17 @@ export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSi
 export declare 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;

package/dist/types/client-urls/revalidate-chain.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 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 declare function lockedClientDefault(options: {
+    actionRequest: boolean;
+    currentParams: Record<string, string>;
+    nextParams: Record<string, string>;
+    currentUrl: URL;
+    nextUrl: URL;
+}): boolean;
+export declare function runClientRevalidateChain(fns: readonly ClientRevalidateFn[], baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate">, lockedDefault: boolean, label: string): boolean;

package/dist/types/client-urls/types.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactNode } from "react";
-import type { LoaderDefinition, LoaderOptions, TransitionConfig } from "../types.js";
+import type { IsActionFn, LoaderDefinition, LoaderOptions, TransitionConfig } from "../types.js";
 import type { TrieMatchResult } from "../router/trie-matching.js";
 import type { PathOptions } from "../urls/pattern-types.js";
 import type { SearchSchema } from "../search-params.js";
@@ -23,7 +23,8 @@ export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: Co
  * 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). */
@@ -35,20 +36,45 @@ 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>;
     /** Client-run per-loader revalidation predicates; empty = locked defaults. */
@@ -114,10 +140,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/dist/types/client.d.ts

@@ -190,3 +190,5 @@ export { useHref } from "./browser/react/use-href.js";
 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/dist/types/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./errors.js";
 export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, // Supports params object, path pattern, or route name
-HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, LoaderOptions, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, } from "./types.js";
+HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, IsActionFn, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, LoaderOptions, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, } from "./types.js";
 export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams, } from "./search-params.js";
 export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./cache/search-params-filter.js";
 export { createLoader } from "./loader.js";

package/dist/types/index.rsc.d.ts

@@ -9,7 +9,7 @@
  * in RSC context, while the regular index.ts is used in client components.
  */
 export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./index.js";
-export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
+export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, IsActionFn, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
 export type { RangoOptions, SSRStreamMode, SSROptions, ResolveStreamingContext, } from "./router.js";
 export type { OriginCheckConfig, OriginCheckContext, OriginCheckPhase, } from "./rsc/origin-guard.js";
 export type { ShellCaptureDebug, ShellCaptureDebugEvent, } from "./rsc/shell-capture.js";

package/dist/types/router/is-action.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { IsActionFn } from "../types.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.
+ */
+export declare function resolveActionRefId(ref: unknown): string | undefined;
+/**
+ * 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 declare function makeIsAction(currentActionId: string | undefined, inAction?: boolean): IsActionFn;

package/dist/types/testing/index.d.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)
@@ -39,6 +39,8 @@ export { runLoader, runLoaderResult } from "./run-loader.js";
 export type { RunLoaderOptions, RunLoaderResult, UseResolver, TestLoaderContext, } from "./run-loader.js";
 export { runTransitionWhen } from "./run-transition-when.js";
 export type { RunTransitionWhenOptions, 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";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";

package/dist/types/testing/run-client-revalidate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { ClientRevalidateFn } from "../client-urls/types.js";
+/**
+ * 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 declare function runClientRevalidate(fn: ClientRevalidateFn | readonly ClientRevalidateFn[], opts?: RunClientRevalidateOptions): boolean;

package/dist/types/testing/to-url.d.ts

@@ -0,0 +1,2 @@
+/** Shared string|URL coercion for the testing primitives. */
+export declare function toURL(value: string | URL | undefined, fallback: URL): URL;

package/dist/types/types/handler-context.d.ts

@@ -418,13 +418,17 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<S
 /**
  * A reference to a server action, used by `isAction()` in a revalidate predicate.
  *
- * Either a directly imported action (`import { addToCart }`) or a namespace
- * import of an action module (`import * as CartActions`). Matching resolves the
+ * Either a directly imported action (`import { addToCart }`), a namespace
+ * import of an action module (`import * as CartActions`), an object
+ * literal of actions (`{ addToCart, removeFromCart }`), or a grouped
+ * namespace (`{ Cart: CartActions, Order: OrderActions }`). Matching resolves the
  * action's build-injected id (`path#export`) — the same identity the router uses
  * for `actionId` — so a renamed or moved action breaks at compile time instead
  * of silently failing to match.
  */
 export type ActionRef = ((...args: never[]) => unknown) | Record<string, unknown>;
+/** The `isAction()` matcher passed to server and client `revalidate()` predicates. */
+export type IsActionFn = (...actions: ActionRef[]) => boolean;
 /**
  * Revalidation function called during client-side navigation to decide whether
  * a segment (layout, route, parallel slot, or loader) should be re-rendered.
@@ -511,8 +515,10 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
     /**
      * Typed, rename-safe action matching. Returns `true` when the action that
      * triggered this revalidation is one of the given references — or, for a
-     * namespace import (`import * as CartActions`), any export of that module —
-     * and `false` otherwise (including plain navigation with no action).
+     * namespace import (`import * as CartActions`), object literal
+     * (`{ addToCart, removeFromCart }`), or grouped namespaces
+     * (`{ Cart: CartActions }`), any of those exports — and `false`
+     * otherwise (including plain navigation with no action).
      *
      * Called with NO arguments it answers "is this request an action at all?":
      * `true` for any action, `false` on plain navigation. Use the bare form when
@@ -536,9 +542,10 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
      * revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
      * revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
      * revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any in the module
+     * revalidate((ctx) => ctx.isAction({ addToCart, removeFromCart }) || undefined); // object form
      * ```
      */
-    isAction: (...actions: ActionRef[]) => boolean;
+    isAction: IsActionFn;
     /** URL where the action was executed (the page the user was on when they triggered the action). */
     actionUrl?: URL;
     /** Return value from the action execution. Can be used to conditionally revalidate based on the action's outcome. */

package/dist/types/types/index.d.ts

@@ -3,7 +3,7 @@ import "./global-namespace.js";
 export type { DocumentProps, ExtractParams, TrailingSlashMode, RouteConfig, RouteDefinitionOptions, RouteDefinition, ResolvedRouteMap, } from "./route-config.js";
 export type { ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, LoaderDataResult, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, } from "./boundaries.js";
 export { isLoaderDataResult } from "./boundaries.js";
-export type { MiddlewareFn, ScopedRouteMap, Handler, HandlerContext, InternalHandlerContext, GenericParams, RevalidateParams, ShouldRevalidateFn, ActionRef, RouteKeys, ExtractRouteParams, HandlersForRouteMap, Revalidate, Middleware, } from "./handler-context.js";
+export type { MiddlewareFn, ScopedRouteMap, Handler, HandlerContext, InternalHandlerContext, GenericParams, RevalidateParams, ShouldRevalidateFn, ActionRef, IsActionFn, RouteKeys, ExtractRouteParams, HandlersForRouteMap, Revalidate, Middleware, } from "./handler-context.js";
 export type { ViewTransitionClass, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ResolvedSegment, SegmentMetadata, SlotState, RootLayoutProps, MatchResult, } from "./segments.js";
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
 export type { LoaderContext, LoaderFn, FetchableLoaderOptions, LoaderOptions, LoadOptions, LoaderDefinition, } from "./loader-types.js";

package/dist/types/vite/plugins/expose-action-id.d.ts

@@ -1,4 +1,18 @@
 import type { Plugin } from "vite";
+/**
+ * Per-reference own `bind` injected next to `$$id`. React's client.browser
+ * build carries no server-reference metadata across `.bind()` (the
+ * edge/node/server builds install an own `bind` on each reference that
+ * does), so `isAction(boundStub)` would silently miss in the browser only.
+ * Installing the same per-reference own `bind` here — scoped to the stubs
+ * this plugin already wraps, guarded to never override an existing own
+ * `bind` — closes that without mutating the global Function.prototype
+ * (which would re-wrap once per Vite environment/HMR pass and break
+ * native-function detection for co-loaded code). The helper re-installs
+ * itself on the bound result so chained binds keep the metadata too.
+ */
+export declare const ACTION_BIND_HELPER_NAME: string;
+export declare const ACTION_BIND_HELPER_SOURCE: string;
 /**
  * Vite plugin that exposes action IDs on server reference functions.
  *

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) {
@@ -3698,7 +3710,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.10.1",
+  version: "0.11.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

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