@rangojs/router 0.0.0-experimental.b000c598 → 0.0.0-experimental.b30bbf02

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.b000c598",
+  "version": "0.0.0-experimental.b30bbf02",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -142,7 +142,9 @@
     "test:unit:watch": "vitest"
   },
   "dependencies": {
+    "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.23",
+    "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.3",
     "rsc-html-stream": "^0.0.7"

package/skills/hooks/SKILL.md

@@ -323,6 +323,11 @@ RSC serialization strips the `collect` function via `toJSON()`. On the client,
 
 ## Action Hooks
 
+For the full server-action guide (defining actions, `useActionState`,
+`useOptimistic`, validation, revalidation, error handling, file uploads),
+see `/server-actions`. `useAction()` below is a Rango-specific hook for
+tracking actions called outside a `<form action={...}>` flow.
+
 ### useAction()
 
 Track state of server action invocations:

package/skills/links/SKILL.md

@@ -187,6 +187,8 @@ export async function getProductUrl(slug: string) {
 }
 ```
 
+See `/server-actions` for the full action surface (`getRequestContext()` is the same context middleware and handlers use).
+
 For static path strings (not named routes), client components can use `href()` — see below.
 
 ## Client: href()

package/skills/loader/SKILL.md

@@ -6,7 +6,10 @@ argument-hint: [loader]
 
 # Data Loaders with loader()
 
-Loaders fetch data on the server and stream it to the client.
+Loaders fetch data on the server and stream it to the client. For mutations
+(writes triggered by forms or buttons), use server actions instead — see
+`/server-actions`. Loaders re-resolve after an action runs, so the typical
+flow is _action mutates → loader re-reads → UI updates_.
 
 ## Creating a Loader
 
@@ -248,6 +251,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/middleware/SKILL.md

@@ -32,6 +32,8 @@ When the router has a `basename`, pattern-scoped `.use()` patterns are automatic
 
 Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
 
+> **Implication for auth:** route middleware cannot guard server actions. Use `router.use("/admin/*", requireAuth)` (global, scoped) for action protection, or check inside the action body. See `/server-actions` for action-side auth patterns.
+
 ```
 Request flow (with action):
   global mw -> action executes -> route mw -> layout -> handler -> loaders

package/skills/migrate-nextjs/SKILL.md

@@ -225,7 +225,7 @@ Loaders are Rango's live data layer. Use them when you need:
 
 - **Client-side data refresh** — `useLoader()` in client components for reactive data
 - **Per-loader caching** — opt in with `loader(MyLoader, () => [cache({ ttl: 60 })])`; loaders stay live by default
-- **Revalidation control** — `revalidate()` targets specific loaders after actions
+- **Revalidation control** — `revalidate()` targets specific segments and loaders after actions
 - **Loading skeletons** — `loading()` shows a Suspense fallback while loaders resolve
 
 ```typescript
@@ -463,6 +463,8 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
+Next.js's `revalidatePath()` / `revalidateTag()` have no direct equivalent — Rango partially re-renders matched route segments (path/layout/parallel/intercept) and re-resolves their loaders, and you scope re-runs by attaching a `revalidate(({ actionId }) => ...)` rule to any segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads) and `/loader` for revalidation rule semantics.
+
 ## 8. Metadata / Head
 
 Rango uses the `Meta` handle + `<MetaTags />` client component:

package/skills/migrate-react-router/SKILL.md

@@ -483,6 +483,10 @@ Since Rango uses RSC server actions, all React action patterns work:
 `useActionState`, `useOptimistic`, `useTransition`, `startTransition`,
 and plain `<form action={serverAction}>`. No framework-specific hook needed.
 
+For the full guide — defining actions, validation with Zod, error handling,
+revalidation rules, file uploads, and progressive enhancement — see
+`/server-actions`.
+
 ### clientLoader / clientAction (framework mode)
 
 RR7 framework mode's `clientLoader` and `clientAction` run in the browser.

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/skills/rango/SKILL.md

@@ -16,6 +16,7 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/route`                | Define routes with `urls()` and `path()`                                   |
 | `/layout`               | Layouts that wrap child routes                                             |
 | `/loader`               | Data loaders with `createLoader()`                                         |
+| `/server-actions`       | Mutations with `"use server"`, useActionState, validation, revalidation    |
 | `/middleware`           | Request processing and authentication                                      |
 | `/intercept`            | Modal/slide-over patterns for soft navigation                              |
 | `/parallel`             | Multi-column layouts and sidebars                                          |