@rangojs/router 0.10.0 → 0.11.0

package/AGENTS.md

@@ -10,4 +10,4 @@ Start with the mental model at `node_modules/@rangojs/router/skills/rango/SKILL.
 
 ## Contributing
 
-This package is developed in the monorepo at https://github.com/ivogt/vite-rsc. If you are contributing there rather than consuming the published package, read the root `AGENTS.md` in that repo for the pre-push gate and e2e rules — they apply to the monorepo, not to consumer apps.
+This package is developed in the monorepo at https://github.com/rangojs/rango. If you are contributing there rather than consuming the published package, read the root `AGENTS.md` in that repo for the pre-push gate and e2e rules — they apply to the monorepo, not to consumer apps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ivo Todorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,13 +4,14 @@ A code-first, type-safe React Server Components router. Django-inspired:
 routes are expressed in one visible tree, URLs are built from names, and
 everything past the core is opt-in.
 
-> **Experimental:** This package is under active development. APIs may change
-> between releases. Install with `@experimental` tag.
+> **Pre-1.0:** Rango follows semver 0.x — breaking changes land in minor
+> releases and are noted in the changelog. npm `latest` is the current 0.x
+> release; the `experimental` tag tracks `main` between tagged releases.
 
 This page is a tour: it builds one small shop and meets the entire core API
 along the way — about six primitives. Everything else is opt-in and linked at
 the end. For the design rationale behind these APIs, read
-[Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
+[Why Rango](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
 argues why it's right.
 
 ## Start a new app
@@ -24,7 +25,8 @@ pnpm create rango my-app
 
 Select a deployment target with `--template basic`, `--template cloudflare`, or
 `--template vercel`. The templates include streaming RSC, typed routes, Server
-Actions, Tailwind CSS, and production deployment configuration. For a plain
+Actions, Tailwind CSS, and production deployment configuration; the scaffolder
+installs the latest `@rangojs/router` release. For a plain
 JavaScript Node app, add `--template basic --js`. With npm, run
 `npm create rango@latest my-app`. The scaffolder currently requires Node.js 24
 or newer.
@@ -34,7 +36,7 @@ or newer.
 If you are adding Rango to an existing Vite RSC project:
 
 ```bash
-npm install @rangojs/router@experimental react @vitejs/plugin-rsc
+npm install @rangojs/router@latest react @vitejs/plugin-rsc
 ```
 
 ```ts
@@ -170,7 +172,7 @@ per group — while matching stays an `O(path length)` prefix trie, identical
 in dev and production. None of this is assumed: the trie is benchmarked
 in-repo against multi-thousand-route manifests, and the lazy guarantees are
 pinned by run-count tests (see
-[matching & lazy discovery](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/internal/matching-and-lazy-discovery.md)).
+[matching & lazy discovery](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/internal/matching-and-lazy-discovery.md)).
 Grow the tree without watching the boot time.
 
 That's a working site. Everything below adds to this app.
@@ -466,19 +468,19 @@ npx rango generate src/             # recursive scan
 
 ### Examples
 
-- [`e2e/mini`](https://github.com/ivogt/vite-rsc/tree/main/packages/rangojs-router/e2e/mini) — single-file demo app
-- [`cloudflare-basic`](https://github.com/ivogt/vite-rsc/tree/main/tests/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
-- [`cloudflare-multi-router`](https://github.com/ivogt/vite-rsc/tree/main/examples/cloudflare-multi-router) — multi-app host routing
-- [`vercel-basic`](https://github.com/ivogt/vite-rsc/tree/main/examples/vercel-basic) — Vercel deployment with `preset: "vercel"`, `VercelCacheStore`, and OTel tracing
-- [`vercel-multi-router`](https://github.com/ivogt/vite-rsc/tree/main/examples/vercel-multi-router) — multi-app host routing on Vercel (single function, routed by Host header)
+- [`e2e/mini`](https://github.com/rangojs/rango/tree/main/packages/rangojs-router/e2e/mini) — single-file demo app
+- [`cloudflare-basic`](https://github.com/rangojs/rango/tree/main/tests/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
+- [`cloudflare-multi-router`](https://github.com/rangojs/rango/tree/main/examples/cloudflare-multi-router) — multi-app host routing
+- [`vercel-basic`](https://github.com/rangojs/rango/tree/main/examples/vercel-basic) — Vercel deployment with `preset: "vercel"`, `VercelCacheStore`, and OTel tracing
+- [`vercel-multi-router`](https://github.com/rangojs/rango/tree/main/examples/vercel-multi-router) — multi-app host routing on Vercel (single function, routed by Host header)
 
 ### Going deeper
 
-- [Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md) — the design rationale, claim by claim
+- [Why Rango](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/why-rango.md) — the design rationale, claim by claim
 - [Framework comparison](./skills/comparison/references/framework-comparison.md) — Rango vs Next.js App Router, TanStack Start, and Waku, capability by capability
-- [Docs index](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/README.md) — architecture, caching, prerender, testing
-- [Execution model](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/internal/execution-model.md) — the runtime contract
+- [Docs index](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/README.md) — architecture, caching, prerender, testing
+- [Execution model](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/internal/execution-model.md) — the runtime contract
 
 ## License
 
-MIT
+[MIT](./LICENSE)

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/cache/cf/cf-cache-constants.d.ts

@@ -66,7 +66,7 @@ export declare 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/dist/types/cache/cf/cf-cache-store.d.ts

@@ -322,7 +322,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * 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/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/rsc/shell-capture-constants.d.ts

@@ -29,7 +29,7 @@ export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
  * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
  * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
  * captureShellHTML, AFTER the capture's router.match(); a handler wedged on a
- * never-settling upstream await (autobarn pilot: a 30s+ tarpitting fetch)
+ * never-settling upstream await (production pilot: a 30s+ tarpitting fetch)
  * wedges the task with no deadline in force. The task's settle path releases
  * the per-key stampede guard and the serialized capture-queue slot, so an
  * unbounded task strands BOTH for the isolate's lifetime.

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.0",
+  version: "0.11.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3707,15 +3719,15 @@ var package_default = {
     "rsc",
     "vite"
   ],
-  homepage: "https://github.com/ivogt/vite-rsc#readme",
+  homepage: "https://github.com/rangojs/rango#readme",
   bugs: {
-    url: "https://github.com/ivogt/vite-rsc/issues"
+    url: "https://github.com/rangojs/rango/issues"
   },
   license: "MIT",
   author: "Ivo Todorov",
   repository: {
     type: "git",
-    url: "git+https://github.com/ivogt/vite-rsc.git",
+    url: "git+https://github.com/rangojs/rango.git",
     directory: "packages/rangojs-router"
   },
   bin: {
@@ -3730,7 +3742,8 @@ var package_default = {
     "dist",
     "skills",
     "AGENTS.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   type: "module",
   exports: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -9,15 +9,15 @@
     "rsc",
     "vite"
   ],
-  "homepage": "https://github.com/ivogt/vite-rsc#readme",
+  "homepage": "https://github.com/rangojs/rango#readme",
   "bugs": {
-    "url": "https://github.com/ivogt/vite-rsc/issues"
+    "url": "https://github.com/rangojs/rango/issues"
   },
   "license": "MIT",
   "author": "Ivo Todorov",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ivogt/vite-rsc.git",
+    "url": "git+https://github.com/rangojs/rango.git",
     "directory": "packages/rangojs-router"
   },
   "bin": {
@@ -32,7 +32,8 @@
     "dist",
     "skills",
     "AGENTS.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "type": "module",
   "exports": {

package/skills/bundle-analysis/SKILL.md

@@ -150,7 +150,7 @@ The treemap shows nested boxes; box area = uncompressed size. Hover for gzip/bro
 
 ## Reporting Rango regressions
 
-If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/ivogt/vite-rsc/issues) and include:
+If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/rangojs/rango/issues) and include:
 
 - The output of `client.html` / `rsc.html` (screenshots or the JSON `data = {...}` block from the HTML).
 - The `@rangojs/router` version (`pnpm why @rangojs/router`).