@rangojs/router 0.0.0-experimental.dfa55db4 → 0.0.0-experimental.e16b7c00

package/src/server/cookie-store.ts

@@ -9,6 +9,7 @@
 
 import type { CookieOptions } from "../router/middleware-types.js";
 import { getRequestContext } from "./request-context.js";
+import { isInsideCacheScope } from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
 /**
@@ -84,10 +85,23 @@ export interface ReadonlyHeaders {
 type HeadersIterator<T> = IterableIterator<T>;
 
 /**
- * Throw if called inside a "use cache" function.
- * Reading request-scoped data (cookies, headers) inside a cached function
- * produces results that vary per request but the cache key does not include
- * those values, leading to one user's data being served to another.
+ * Throw if called inside a cache boundary — either a "use cache" function
+ * (`INSIDE_CACHE_EXEC` stamped on ctx by the cache runtime) or a `cache()`
+ * DSL boundary (`isInsideCacheScope()` — the render-store flag set while
+ * resolving a `type: "cache"` route entry).
+ *
+ * Reading request-scoped data (cookies, headers) inside a cached scope
+ * produces per-request values that are NOT reflected in the cache key, so
+ * they would be frozen into the shared cache entry and served to the wrong
+ * users. This is the same hazard for both scopes: a `cache()` boundary caches
+ * everything except loaders (it is the document-level "PPR shell"), so a read
+ * here is baked into the shell exactly like a `"use cache"` return value is
+ * baked into its cache entry.
+ *
+ * `isInsideCacheScope()` returns false inside loaders (loaders always run
+ * fresh on every request, even on a cache hit), so reading cookies()/headers()
+ * from a loader is allowed — loaders are the dynamic "holes" of a cached
+ * document.
  */
 function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
   if (
@@ -106,6 +120,16 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
         `  const data = await getCachedData(locale); // locale is now in the cache key`,
     );
   }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `${fnName}() cannot be called inside a cache() boundary. ` +
+        `A cache() scope caches everything except loaders, so request-scoped ` +
+        `data (cookies, headers) read here would be frozen into the shared ` +
+        `cached shell and served to other users. Read it inside a loader ` +
+        `instead — loaders always run fresh on every request, even on a cache hit:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
 }
 
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);

package/src/server/request-context.ts

@@ -11,6 +11,7 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
 import type { ScopedReverseFunction } from "../reverse.js";
@@ -37,6 +38,8 @@ import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
@@ -58,22 +61,7 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 export interface RequestContext<
   TEnv = DefaultEnv,
   TParams = Record<string, string>,
-> {
-  /** Platform bindings (Cloudflare env, etc.) */
-  env: TEnv;
-  /** Original HTTP request */
-  request: Request;
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-  /** URL pathname */
-  pathname: string;
-  /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
-  searchParams: URLSearchParams;
+> extends RequestScope<TEnv> {
   /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
   _variables: Record<string, any>;
   /** Get a variable set by middleware */
@@ -153,26 +141,31 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Handler-owned registry of explicit per-scope stores from
+   * cache({ store }). Created once per createRSCHandler() and threaded into
+   * every request context, so it accumulates every explicit store the handler
+   * resolves. updateTag()/revalidateTag() iterate this set plus _cacheStore to
+   * reach every store that may hold tagged entries. The app-level store is not
+   * added here (it is always reachable via _cacheStore).
+   */
+  _explicitTaggedStores?: Set<SegmentCacheStore>;
+
+  /**
+   * @internal Union of every cache tag resolved while producing this request's
+   * response (from cache({ tags }), runtime cacheTag(), and loader cache tags).
+   * Populated at the tag-resolution sites via recordRequestTags(). Read by the
+   * document cache middleware so a full-page entry is tagged with everything its
+   * content used and can therefore be invalidated by updateTag()/revalidateTag().
+   */
+  _requestTags: Set<string>;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
     import("../cache/profile-registry.js").CacheProfile
   >;
 
-  /**
-   * Schedule work to run after the response is sent.
-   * On Cloudflare Workers, uses ctx.waitUntil().
-   * On Node.js, runs as fire-and-forget.
-   *
-   * @example
-   * ```typescript
-   * ctx.waitUntil(async () => {
-   *   await cacheStore.set(key, data, ttl);
-   * });
-   * ```
-   */
-  waitUntil(fn: () => Promise<void>): void;
-
   /**
    * Register a callback to run when the response is created.
    * Callbacks are sync and receive the response. They can:
@@ -331,9 +324,13 @@ export interface RequestContext<
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
    * creation. Cache-runtime and other subsystems call this to surface
-   * errors without failing the response.
+   * errors without failing the response. `category` is surfaced to consumers as
+   * `metadata.category` on the onError context (phase `cache`).
    */
-  _reportBackgroundError?: (error: unknown, category: string) => void;
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
 
   /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
   _debugPerformance?: boolean;
@@ -368,6 +365,8 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_cacheStore"
+  | "_explicitTaggedStores"
+  | "_requestTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_themeConfig"
@@ -498,13 +497,7 @@ export function requireRequestContext<
   return getRequestContext<TEnv>();
 }
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+export type { ExecutionContext };
 
 /**
  * Options for creating a request context
@@ -518,6 +511,11 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Handler-owned registry of explicit per-scope stores for cross-store tag
+   * invalidation. Created once per handler, reused across requests.
+   */
+  explicitTaggedStores?: Set<SegmentCacheStore>;
   /** Optional cache profiles for "use cache" resolution (per-router) */
   cacheProfiles?: Record<
     string,
@@ -547,6 +545,7 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    explicitTaggedStores,
     cacheProfiles,
     executionContext,
     themeConfig,
@@ -764,20 +763,20 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _explicitTaggedStores: explicitTaggedStores,
+    _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        // Cloudflare Workers: use native waitUntil
         executionContext.waitUntil(fn());
       } else {
-        // Node.js / dev: fire-and-forget with error logging
-        fn().catch((err) =>
-          console.error("[waitUntil] Background task failed:", err),
-        );
+        fireAndForgetWaitUntil(fn);
       }
     },
 
+    executionContext,
+
     _onResponseCallbacks: [],
 
     onResponse(callback: (response: Response) => Response): void {
@@ -1043,7 +1042,10 @@ export function createUseFunction<TEnv>(
       search: (ctx as any).search ?? {},
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env as any,
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
       get: ctx.get as any,
       use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,

package/src/ssr/index.tsx

@@ -162,9 +162,13 @@ function createSsrEventController(opts: {
 }): EventController {
   const location = new URL(opts.pathname, "http://localhost");
   let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
   const handleState = {
     data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    ),
   };
   const state: DerivedNavigationState = {
     state: "idle",

package/src/static-handler.ts

@@ -96,7 +96,7 @@ export function Static<TParams extends Record<string, any>>(
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
+      "[rango] Static: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }

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 SWR; 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

@@ -155,7 +155,11 @@ export interface OnErrorContext<TEnv = any> {
   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,7 +18,7 @@
  * ```
  */
 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 })
@@ -44,13 +44,25 @@ declare global {
 }
 
 /**
- * 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 +70,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 +82,32 @@ 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
  */
-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

@@ -20,6 +20,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 +43,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
@@ -195,7 +196,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 +216,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.
@@ -503,13 +471,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
@@ -521,7 +492,8 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.formData - Form data from action (future support)
  * @param args.formMethod - HTTP method from action (future support)
  *
- * @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,19 +513,34 @@ 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.
  *
  * @example
  * ```ts
- * // Re-render only when a cart action happened or browser signals staleness
+ * // Re-render when a cart action happened or the browser signals staleness;
+ * // defer otherwise (|| undefined) so the segment default still applies
  * revalidate(({ actionId, stale }) =>
- *   actionId?.includes("cart") || stale || false
+ *   actionId?.includes("cart") || stale || undefined
  * )
  *
  * // Always re-render when params change (default behavior made explicit)
@@ -580,8 +567,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 +587,49 @@ 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).
+   *
+   * 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(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 +665,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 +770,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 +778,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();

package/src/types/index.ts

@@ -42,6 +42,7 @@ export type {
   GenericParams,
   RevalidateParams,
   ShouldRevalidateFn,
+  ActionRef,
   RouteKeys,
   ExtractRouteParams,
   HandlersForRouteMap,