@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/types/cache-types.ts

@@ -78,6 +78,14 @@ export interface CacheOptions<TEnv = unknown> {
    * - Loader-specific caching strategies
    * - Hot data in fast cache, cold data in larger/slower cache
    *
+   * Tag invalidation caveat: a per-boundary store becomes reachable by
+   * `updateTag()` / `revalidateTag()` once this boundary is resolved in the
+   * current process. If the store is *durable* (shared across processes) and the
+   * very first request to a fresh worker is an `updateTag`/`revalidateTag` for a
+   * tag held only in this store - before this boundary is matched - that
+   * invalidation can miss it. For data you invalidate by tag, prefer the
+   * app-level store (always reachable), or ensure the boundary is warmed.
+   *
    * @example
    * ```typescript
    * const kvStore = new CloudflareKVStore(env.CACHE_KV);
@@ -145,10 +153,11 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
-   * Note: Tags are passed through to the store but built-in stores
-   * (MemorySegmentCacheStore, CFCacheStore) do not yet index or
-   * invalidate by tag. Effective tag-based invalidation requires a
-   * custom store implementation with secondary indices.
+   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
+   * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
+   * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed
+   * invalidation requires a `kv` namespace (markers live in that same namespace).
    *
    * @example
    * ```typescript

package/src/types/error-types.ts

@@ -14,19 +14,19 @@
  * - "unknown": Fallback for unclassified errors (not currently invoked)
  */
 export type ErrorPhase =
-  | "routing" // During route matching
-  | "manifest" // During manifest loading (reserved, not currently invoked)
-  | "middleware" // During middleware execution (errors propagate to handler phase)
-  | "loader" // During loader execution
-  | "handler" // During route/layout handler execution
-  | "rendering" // During RSC/SSR rendering (SSR handler uses separate callback)
-  | "action" // During server action execution
-  | "revalidation" // During revalidation evaluation
-  | "cache" // During "use cache" background operations (stale revalidation, async cache writes)
-  | "prerender" // During build-time pre-rendering (Vite closeBundle)
-  | "static" // During build-time static handler rendering (Vite closeBundle)
-  | "origin" // During cross-origin request validation (CSRF protection)
-  | "unknown"; // Fallback for unclassified errors
+  | "routing"
+  | "manifest"
+  | "middleware"
+  | "loader"
+  | "handler"
+  | "rendering"
+  | "action"
+  | "revalidation"
+  | "cache"
+  | "prerender"
+  | "static"
+  | "origin"
+  | "unknown";
 
 /**
  * Comprehensive context passed to onError callback
@@ -59,103 +59,43 @@ export type ErrorPhase =
  * ```
  */
 export interface OnErrorContext<TEnv = any> {
-  /**
-   * The error that occurred
-   */
   error: Error;
-
-  /**
-   * Phase where the error occurred
-   */
   phase: ErrorPhase;
-
-  /**
-   * The original request
-   */
   request: Request;
-
-  /**
-   * Parsed URL from the request
-   */
   url: URL;
-
-  /**
-   * Request pathname
-   */
   pathname: string;
-
-  /**
-   * HTTP method
-   */
   method: string;
-
-  /**
-   * Matched route key (if available)
-   * e.g., "shop.products.detail"
-   */
+  /** Matched route key (if available) e.g., "shop.products.detail" */
   routeKey?: string;
-
-  /**
-   * Route params (if available)
-   * e.g., { slug: "headphones" }
-   */
+  /** Route params (if available) e.g., { slug: "headphones" } */
   params?: Record<string, string>;
-
-  /**
-   * Segment ID where error occurred (if available)
-   * e.g., "M1L0" for a layout, "M1R0" for a route
-   */
+  /** Segment ID where error occurred (if available) e.g., "M1L0" for a layout, "M1R0" for a route */
   segmentId?: string;
-
-  /**
-   * Segment type where error occurred (if available)
-   */
+  /** Segment type where error occurred (if available) */
   segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
-
-  /**
-   * Loader name (if error occurred in a loader)
-   */
+  /** Loader name (if error occurred in a loader) */
   loaderName?: string;
-
-  /**
-   * Middleware name/id (if error occurred in middleware)
-   */
+  /** Middleware name/id (if error occurred in middleware) */
   middlewareId?: string;
-
-  /**
-   * Action ID (if error occurred during server action)
-   * e.g., "src/actions.ts#addToCart"
-   */
+  /** Action ID (if error occurred during server action) e.g., "src/actions.ts#addToCart" */
   actionId?: string;
-
-  /**
-   * Environment/bindings (platform context)
-   */
+  /** Environment/bindings (platform context) */
   env?: TEnv;
-
-  /**
-   * Duration from request start to error (milliseconds)
-   */
+  /** Duration from request start to error (milliseconds) */
   duration?: number;
-
-  /**
-   * Whether this is a partial/navigation request
-   */
+  /** Whether this is a partial/navigation request */
   isPartial?: boolean;
-
-  /**
-   * Whether an error boundary caught the error
-   * If true, the error was handled and a fallback UI was rendered
-   */
+  /** Whether an error boundary caught the error */
   handledByBoundary?: boolean;
-
-  /**
-   * Stack trace (if available)
-   */
+  /** Stack trace (if available) */
   stack?: string;
 
   /**
-   * Additional metadata specific to the error phase
+   * Additional metadata specific to the error phase. For the `cache` phase,
+   * `metadata.category` is a `CacheErrorCategory` (exported from
+   * `@rangojs/router/cache`) identifying the failure kind, e.g. `cache-read`
+   * (transient outage, degraded to a miss) vs `cache-corrupt` (faulty entry
+   * self-healed) vs `cache-invalidate` (a failed background revalidateTag).
    */
   metadata?: Record<string, unknown>;
 }

package/src/types/global-namespace.ts

@@ -7,7 +7,7 @@
  * ```typescript
  * // In env.ts or env.d.ts
  * declare global {
- *   namespace RSCRouter {
+ *   namespace Rango {
  *     interface Env extends AppBindings {}
  *     interface Vars extends AppVariables {}
  *   }
@@ -18,39 +18,41 @@
  * ```
  */
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface Env {
-      // Empty by default - users augment with their bindings (e.g., { DB: D1Database })
-    }
+    interface Env {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface Vars {
-      // Empty by default - users augment with their variables (e.g., { user?: User })
-    }
+    interface Vars {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface RegisteredRoutes {
-      // Empty by default - users augment with their merged route maps for type-safe href()
-      // Values are string (pattern) for RSC routes, or { path: string; response: T } for response routes
-    }
+    interface RegisteredRoutes {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface GeneratedRouteMap {
-      // Empty by default - populated by generated named-routes.gen.ts
-      // Maps route names to URL pattern strings for Handler<"routeName"> support
-    }
+    interface GeneratedRouteMap {}
   }
 }
 
 /**
- * Get registered routes or fallback to generic Record<string, string>
- * When RSCRouter.RegisteredRoutes is augmented, provides autocomplete for route names
- * When not augmented, allows any string (no autocomplete)
+ * Route map for path-validation surfaces (`href`, `ValidPaths`, `PathResponse`).
+ *
+ * Resolution order:
+ * 1. `RegisteredRoutes` — manual `extends typeof router.routeMap`; richest map,
+ *    the only one carrying response-route payload metadata.
+ * 2. `GeneratedRouteMap` — auto-wired by `router.named-routes.gen.ts`; path +
+ *    search only. Lets `rango generate` alone enable `href()`/`ValidPaths` path
+ *    checking without a manual `RegisteredRoutes` declaration.
+ * 3. `Record<string, string>` — permissive fallback when nothing is registered.
+ *
+ * Referencing `GeneratedRouteMap` here is cycle-safe: it is declared in the
+ * standalone gen file with no imports, unlike `RegisteredRoutes extends typeof
+ * router.routeMap`.
  */
-export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
-  ? Record<string, string>
-  : RSCRouter.RegisteredRoutes;
+export type GetRegisteredRoutes = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
+    ? Record<string, string>
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Default route map for reverse() surfaces.
@@ -58,12 +60,11 @@ export type GetRegisteredRoutes = keyof RSCRouter.RegisteredRoutes extends never
  * cycles, but falls back to RegisteredRoutes for manual augmentation and then to
  * a permissive record when no route types are available.
  */
-export type DefaultReverseRouteMap =
-  keyof RSCRouter.GeneratedRouteMap extends never
-    ? keyof RSCRouter.RegisteredRoutes extends never
-      ? Record<string, string>
-      : RSCRouter.RegisteredRoutes
-    : RSCRouter.GeneratedRouteMap;
+export type DefaultReverseRouteMap = keyof Rango.GeneratedRouteMap extends never
+  ? keyof Rango.RegisteredRoutes extends never
+    ? Record<string, string>
+    : Rango.RegisteredRoutes
+  : Rango.GeneratedRouteMap;
 
 /**
  * Default route map for Handler type.
@@ -71,30 +72,42 @@ export type DefaultReverseRouteMap =
  * circular dependencies: router.tsx -> urls.tsx -> handler.tsx -> RegisteredRoutes -> router.tsx.
  * GeneratedRouteMap is declared in a standalone gen file with no imports.
  */
-export type DefaultHandlerRouteMap =
-  keyof RSCRouter.GeneratedRouteMap extends never
-    ? {}
-    : RSCRouter.GeneratedRouteMap;
+export type DefaultHandlerRouteMap = keyof Rango.GeneratedRouteMap extends never
+  ? {}
+  : Rango.GeneratedRouteMap;
 
 /**
- * Default environment type - uses global augmentation if available, any otherwise
+ * Default environment type - uses global augmentation if available.
+ *
+ * Falls back to `unknown` (not `any`) when `Rango.Env` is not augmented, so
+ * an app that forgets to register its bindings gets a compile error on
+ * `ctx.env.SOMETHING` instead of silently losing all env type-checking. Augment
+ * `Rango.Env` to type `ctx.env`.
  */
-export type DefaultEnv = keyof RSCRouter.Env extends never
-  ? any
-  : RSCRouter.Env;
+export type DefaultEnv = keyof Rango.Env extends never ? unknown : Rango.Env;
 
 /**
- * Default variables type - uses global augmentation if available, Record<string, any> otherwise
+ * Variables type backing the string-key `ctx.get` / `ctx.set` overloads.
+ *
+ * Uses `Rango.Vars` augmentation when present; otherwise falls back to
+ * `Record<string, any>` so an un-augmented app can use string-key vars with
+ * zero config -- at the cost of a typo'd key being silently `any`.
+ *
+ * This `any` fallback is deliberate (see #561) and is an intentional asymmetry
+ * with `DefaultEnv` above, which falls back to `unknown`: env bindings are
+ * platform-critical and should be registered, so a forgotten binding is made a
+ * compile error; vars are ad-hoc and middleware-set, so the zero-config path
+ * wins. Augment `Rango.Vars` for type-safe keys.
  */
-export type DefaultVars = keyof RSCRouter.Vars extends never
+export type DefaultVars = keyof Rango.Vars extends never
   ? Record<string, any>
-  : RSCRouter.Vars;
+  : Rango.Vars;
 
 /**
  * Default route name type for public `routeName` on contexts.
  * When GeneratedRouteMap is augmented, narrows to the known route names.
  * Otherwise falls back to `string` for untyped usage.
  */
-export type DefaultRouteName = keyof RSCRouter.GeneratedRouteMap extends never
+export type DefaultRouteName = keyof Rango.GeneratedRouteMap extends never
   ? string
-  : keyof RSCRouter.GeneratedRouteMap & string;
+  : keyof Rango.GeneratedRouteMap & string;

package/src/types/handler-context.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { Handle } from "../handle.js";
+import type { HandlePush } from "../defer.js";
 import type { ContextVar } from "../context-var.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { Theme } from "../theme/types.js";
@@ -20,6 +21,7 @@ import type {
 } from "./route-config.js";
 import type { LoaderDefinition } from "./loader-types.js";
 import type { UseItems, HandlerUseItem } from "../route-types.js";
+import type { RequestScope } from "./request-scope.js";
 
 // Re-export MiddlewareFn for internal/advanced use
 export type { MiddlewareFn } from "../router/middleware.js";
@@ -42,7 +44,7 @@ export type { MiddlewareFn } from "../router/middleware.js";
  */
 export type ScopedRouteMap<
   TPrefix extends string,
-  TMap = RSCRouter.GeneratedRouteMap,
+  TMap = Rango.GeneratedRouteMap,
 > = {
   [K in keyof TMap as K extends `${TPrefix}.${infer Rest}`
     ? Rest
@@ -106,14 +108,6 @@ type StrictLocalParamsWithExtras<TEntry> =
     ? Record<string, string>
     : ExtractParamsFromEntry<TEntry, {}> & Record<string, string>;
 
-// HandlerContext.reverse is the only reverse surface with runtime param autofill
-// from the current matched request. Middleware/loaders/request context do not
-// have the same local-route guarantees, so they keep plain ScopedReverseFunction.
-//
-// When a handler has an explicit local route map, enforce that local route
-// params declared by that map are present while still allowing extra mount
-// params to be passed through. Global names remain autofill-friendly because
-// parent include() params are often unknown at the module definition site.
 type StrictLocalAutofillGlobalReverseFunction<TLocalRoutes, TGlobalRoutes> =
   ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
     <TName extends keyof TGlobalRoutes & string>(
@@ -195,7 +189,7 @@ export type HandlerContext<
   TEnv = DefaultEnv,
   TSearch extends SearchSchema = {},
   TRouteMap = never,
-> = {
+> = RequestScope<TEnv> & {
   /**
    * Route parameters extracted from the URL pattern.
    * Type-safe when using Handler<"/path/:param"> or Handler<{ param: string }>.
@@ -215,44 +209,11 @@ export type HandlerContext<
    * changing build semantics (e.g., skip expensive operations in dev).
    */
   dev: boolean;
-  /**
-   * The original incoming Request object (transport URL intact).
-   * Use `ctx.url` / `ctx.searchParams` for application logic — those have
-   * internal `_rsc*` params stripped. `ctx.request` preserves the raw URL
-   * for cases where you need original headers, method, or body.
-   */
-  request: Request;
-  /**
-   * Query parameters from the URL (system params like `_rsc*` are filtered).
-   * Always a standard URLSearchParams instance.
-   */
-  searchParams: URLSearchParams;
   /**
    * Typed search parameters parsed from URL query string via the route's
    * search schema. Empty object when no schema is defined.
    */
   search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
-  /**
-   * The pathname portion of the request URL.
-   */
-  pathname: string;
-  /**
-   * The full URL object (with internal `_rsc*` params stripped).
-   * Use this for application logic — routing, link generation, display.
-   */
-  url: URL;
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params. Use `ctx.url` for application
-   * logic — this is only needed for advanced cases like debugging
-   * or custom cache keying.
-   */
-  originalUrl: URL;
-  /**
-   * Platform bindings (DB, KV, secrets, etc.).
-   * Access resources like `ctx.env.DB`, `ctx.env.KV`.
-   */
-  env: TEnv;
   /**
    * Type-safe getter for middleware variables.
    * Preferred way to read middleware-injected variables.
@@ -314,6 +275,8 @@ export type HandlerContext<
    * For handles: Returns a push function to add data for this segment.
    * Handle data accumulates across all matched route segments.
    * Push accepts: direct value, Promise, or async callback (executed immediately).
+   * Or call `.defer()` to reserve the slot now and resolve it later (e.g. from a
+   * deep async component), with a timeout safety net — see {@link HandlePush}.
    *
    * @example
    * ```typescript
@@ -347,6 +310,13 @@ export type HandlerContext<
    *   });
    *   return <ProductPage />;
    * });
+   *
+   * // Handle usage - deferred (reserve the slot now, resolve from a deep component)
+   * route("product", (ctx) => {
+   *   const resolve = ctx.use(Breadcrumbs).defer({ timeoutMs: 5000, else: null });
+   *   loadCrumb(ctx.params.id).then(resolve); // resolver is push-equal
+   *   return <ProductPage />;                 // auto-resolves to `else` on timeout
+   * });
    * ```
    */
   use: {
@@ -355,7 +325,7 @@ export type HandlerContext<
     ): Promise<T>;
     <TData, TAccumulated = TData[]>(
       handle: Handle<TData, TAccumulated>,
-    ): (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+    ): HandlePush<TData>;
   };
   /**
    * Current theme (from cookie or default).
@@ -462,6 +432,18 @@ export type InternalHandlerContext<
   _responseType?: string;
   /** Route name for cache key scoping (prevents cross-route collisions). */
   _routeName?: string;
+  /**
+   * @internal Loader-cache override table: loaderId -> memoized data promise.
+   * A single stable ctx.use interceptor consults this instead of chaining one
+   * wrapper per cached loader (avoids O(N) dispatch). See loader-cache.ts.
+   */
+  _loaderCacheOverrides?: Map<string, Promise<any>>;
+  /**
+   * @internal ctx.use captured before the loader-cache interceptor was installed.
+   * The cache-miss execute runs the loader through this, bypassing the override
+   * table (so a loader cannot await its own in-flight memoized promise).
+   */
+  _loaderCacheOriginalUse?: (item: any) => any;
 };
 
 /**
@@ -503,13 +485,16 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * **Return Types:**
  * - `boolean` - Hard decision: immediately returns this value (short-circuits)
  * - `{ defaultShouldRevalidate: boolean }` - Soft decision: updates suggestion for next revalidator
+ * - `void` / `null` / `undefined` - Defer to the current suggestion (no opinion); the
+ *   loop continues to the next revalidator without changing the running default
  *
  * **Execution Flow:**
  * 1. Start with built-in `defaultShouldRevalidate` (true if params changed)
  * 2. Execute global revalidators first, then route-specific
  * 3. Hard decision (boolean): stop immediately and use that value
  * 4. Soft decision (object): update suggestion and continue to next revalidator
- * 5. If all return soft decisions: use the final suggestion
+ * 5. Defer (`void` / `null` / `undefined`): leave suggestion unchanged and continue
+ * 6. If no hard decision was returned: use the final running suggestion
  *
  * @param args.currentParams - Previous route params (generic by default, can be narrowed)
  * @param args.currentUrl - Previous URL
@@ -519,9 +504,10 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.context - App context (db, user, etc.)
  * @param args.actionResult - Result from action (future support)
  * @param args.formData - Form data from action (future support)
- * @param args.formMethod - HTTP method from action (future support)
+ * @param args.method - HTTP method: "GET" for navigation, "POST" for server actions
  *
- * @returns Hard decision (boolean) or soft suggestion (object)
+ * @returns Hard decision (boolean), soft suggestion (object), or defer
+ *   (`void` / `null` / `undefined`) to keep the running suggestion as-is.
  *
  * @example
  * ```typescript
@@ -541,20 +527,46 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * })
  * ```
  */
+/**
+ * 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
+ * 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>;
+
 /**
  * Revalidation function called during client-side navigation to decide whether
  * a segment (layout, route, parallel slot, or loader) should be re-rendered.
  *
  * Return `true` to re-render, `false` to skip (keep client's current version),
- * or `{ defaultShouldRevalidate: boolean }` to override the default for
- * downstream segments.
+ * `{ defaultShouldRevalidate: boolean }` to update the running suggestion for
+ * downstream revalidators, or nothing (`void` / `null` / `undefined`) to defer
+ * to the current suggestion without changing it.
+ *
+ * Two idioms cover almost every case; they differ only in what an _unrelated_
+ * action does. Match actions by reference with `ctx.isAction()` (rename-safe)
+ * rather than `actionId?.includes("...")` (a renamed or moved action silently
+ * stops matching). Because `isAction` returns a raw boolean, combine it with
+ * `|| undefined` to defer or leave it bare to suppress.
  *
  * @example
  * ```ts
- * // Re-render only when a cart action happened or browser signals staleness
- * revalidate(({ actionId, stale }) =>
- *   actionId?.includes("cart") || stale || false
- * )
+ * import * as CartActions from "./actions/cart";
+ *
+ * // Idiom A — "mine, else defer": re-render on my actions, otherwise return
+ * // undefined so the segment's default decision still applies (and downstream
+ * // revalidators get a say).
+ * revalidate((ctx) => ctx.isAction(CartActions) || undefined)
+ *
+ * // Idiom B — "mine only": re-render on my actions and suppress everything
+ * // else (isAction returns a raw boolean, so an unrelated action yields false).
+ * revalidate((ctx) => ctx.isAction(CartActions))
  *
  * // Always re-render when params change (default behavior made explicit)
  * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)
@@ -580,8 +592,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
 
   // ── Segment metadata (which segment is being evaluated) ──────────────
 
-  /** The type of segment being revalidated. */
-  segmentType: "layout" | "route" | "parallel";
+  /**
+   * The type of segment being revalidated. `"loader"` is passed to revalidate
+   * functions attached to a `loader(Fn, () => [revalidate(...)])` registration.
+   */
+  segmentType: "layout" | "route" | "parallel" | "loader";
   /** Layout name (e.g., `"root"`, `"shop"`, `"auth"`). Only set for layout segments. */
   layoutName?: string;
   /** Slot name (e.g., `"@sidebar"`, `"@modal"`). Only set for parallel segments. */
@@ -597,21 +612,54 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * relative to the project root, followed by `#` and the exported function name.
    *
    * This is stable and can be used for path-based matching to revalidate
-   * when any action in a module or directory fires:
+   * when any action in a module or directory fires. Prefer `|| undefined`
+   * (defer to the segment default / downstream revalidators) over `?? false`
+   * (hard short-circuit that suppresses the default and ends the chain):
    *
    * @example
    * ```ts
    * // Match a specific action
-   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart")
+   * revalidate(({ actionId }) => actionId === "src/actions/cart.ts#addToCart" || undefined)
    *
    * // Match any action in the cart module
-   * revalidate(({ actionId }) => actionId?.includes("cart") ?? false)
+   * revalidate(({ actionId }) => actionId?.includes("cart") || undefined)
    *
    * // Match any action under src/apps/store/actions/
-   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") ?? false)
+   * revalidate(({ actionId }) => actionId?.startsWith("src/apps/store/actions/") || undefined)
    * ```
    */
   actionId?: string;
+  /**
+   * 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).
+   *
+   * 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
+   * you want to revalidate on every action regardless of which one fired.
+   *
+   * Prefer this over hand-written `actionId` substring matches: it resolves the
+   * action's stable `path#export` id from the imported reference, so a rename is
+   * a type error in one place instead of silent drift across consumers. It
+   * resolves the reference the same way the action boundary derives `actionId`
+   * (`$id ?? $$id`), so it matches in both dev and production.
+   *
+   * Returns a raw boolean, so for the common "revalidate on match, else defer"
+   * intent combine with `|| undefined`:
+   *
+   * @example
+   * ```ts
+   * import { addToCart, removeFromCart } from "./actions/cart";
+   * import * as CartActions from "./actions/cart";
+   *
+   * revalidate((ctx) => ctx.isAction() || undefined); // any action
+   * 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
+   * ```
+   */
+  isAction: (...actions: ActionRef[]) => boolean;
   /** 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. */
@@ -647,7 +695,7 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * action that may have mutated backend state.
    */
   stale?: boolean;
-}) => boolean | { defaultShouldRevalidate: boolean };
+}) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported
 
@@ -752,7 +800,7 @@ export type Revalidate<
  * Middleware function with typed params and environment
  *
  * @template TParams - Params object (defaults to generic)
- * @template TEnv - Environment type (defaults to global RSCRouter.Env)
+ * @template TEnv - Environment type (defaults to global Rango.Env)
  *
  * Note: Middleware cannot directly use route names for params typing because
  * middleware is defined during router setup, before RegisteredRoutes is populated.
@@ -760,7 +808,7 @@ export type Revalidate<
  *
  * @example
  * ```typescript
- * // Basic middleware (uses global RSCRouter.Env via module augmentation)
+ * // Basic middleware (uses global Rango.Env via module augmentation)
  * const middleware: Middleware = async (ctx, next) => {
  *   ctx.set("user", { id: "123" }); // Type-safe!
  *   await next();