@rangojs/router 0.0.0-experimental.91 → 0.0.0-experimental.92

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.91",
+  version: "0.0.0-experimental.92",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.91",
+  "version": "0.0.0-experimental.92",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/loader/SKILL.md

@@ -248,6 +248,37 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+### `revalidate()` return shapes
+
+A `revalidate(fn)` callback can return one of four shapes. The chain
+processes revalidators in order; each call's return controls how the
+chain continues:
+
+```typescript
+// 1) Hard decision — short-circuits the chain, used as the final answer.
+revalidate(() => true);
+revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
+
+// 2) Soft decision — updates the running suggestion for downstream
+//    revalidators on the same segment, chain continues.
+revalidate(({ defaultShouldRevalidate }) => ({
+  defaultShouldRevalidate: !defaultShouldRevalidate,
+}));
+
+// 3) Defer (no opinion) — leaves the running suggestion unchanged and
+//    continues to the next revalidator. Implicit return / null /
+//    undefined are all equivalent and consumer-friendly.
+revalidate(({ actionId }) => {
+  if (actionId?.includes("Cart")) return true; // hard for this branch only
+  // implicit return — let downstream revalidators or the segment default decide
+});
+revalidate(() => undefined); // explicit defer
+revalidate(() => null); // explicit defer
+```
+
+If every revalidator on a segment defers, the segment-type default
+(e.g. params-changed for routes, `false` for parallels) is used.
+
 ### Revalidation Contracts for Loader Dependencies
 
 If a loader reads `ctx.get()` data produced by an outer handler/layout, share

package/skills/parallel/SKILL.md

@@ -347,6 +347,13 @@ Revalidating only the parallel does not re-run outer handlers/layouts.
 If the slot reads `ctx.get()` data established above it, opt the outer
 segment into revalidation as well.
 
+A `revalidate()` callback may return a hard `boolean`, a soft
+`{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /
+`undefined`) to defer to the next revalidator. See
+[loader/SKILL.md#revalidate-return-shapes](../loader/SKILL.md#revalidate-return-shapes)
+for the full contract — it's the same across `loader()`, `path()`,
+`layout()`, `parallel()`, and `intercept()`.
+
 ### Revalidation Contracts for Parallel Dependencies
 
 Prefer named revalidation contracts shared by both the upstream producer and

package/src/route-definition/helpers-types.ts

@@ -259,7 +259,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   ({ defaultShouldRevalidate: true })
    * )
    * ```
-   * @param fn - Function that returns boolean (hard) or { defaultShouldRevalidate } (soft)
+   * @param fn - Function returning either:
+   *   - `boolean` (hard decision — short-circuits the chain),
+   *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
+   *     for downstream revalidators),
+   *   - or nothing / `null` / `undefined` (defer — leaves the suggestion
+   *     unchanged and continues to the next revalidator).
    */
   revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
   /**

package/src/types/handler-context.ts

@@ -471,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
@@ -489,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
@@ -514,8 +518,9 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * 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
@@ -615,7 +620,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