@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.18",
+  "version": "0.0.0-experimental.19",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,6 +132,15 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
   "dependencies": {
     "@vitejs/plugin-rsc": "^0.5.14",
     "magic-string": "^0.30.17",
@@ -141,12 +150,12 @@
   "devDependencies": {
     "@playwright/test": "^1.49.1",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
@@ -164,13 +173,5 @@
     "vite": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
   }
-}
+}

package/skills/hooks/SKILL.md

@@ -484,7 +484,7 @@ Or via `ctx.setLocationState()` on any response:
 
 ```tsx
 (ctx) => {
-  ctx.setLocationState([FlashMessage({ text: "Welcome back!" })]);
+  ctx.setLocationState(FlashMessage({ text: "Welcome back!" }));
   return <Dashboard />;
 };
 ```

package/skills/intercept/SKILL.md

@@ -8,6 +8,9 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Intercept
 
 ```typescript
@@ -68,6 +71,78 @@ intercept(
 )
 ```
 
+## Intercept Middleware
+
+Intercepts support their own middleware chain via the use callback. The full chain for an intercept request is:
+
+```
+global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept handler -> intercept loaders
+```
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  () => [
+    middleware(async (ctx, next) => {
+      // Runs only for this intercept, after global and route middleware
+      ctx.set("interceptSource", "modal");
+      await next();
+    }),
+    loader(ProductLoader),
+  ]
+)
+```
+
+The intercept handler can read context variables set by all upstream middleware layers (global, route, and intercept-specific).
+
+Handler/layout `ctx.set()` data follows the same rule as elsewhere:
+intercepts see data produced in the current render pass, but partial
+action revalidation only recomputes segments that actually revalidate.
+If an intercept depends on data established by an outer layout/handler,
+revalidate that outer segment too or reload/guard the data inside the
+intercept.
+
+### Revalidation Contracts for Intercept Dependencies
+
+Use named revalidation contracts on both the outer producer and the intercept
+consumer when they share `ctx.set()` data:
+
+```typescript
+export const revalidateProductShell = ({ actionId }) =>
+  actionId?.includes("src/actions/product.ts#") ?? false;
+
+layout(ProductLayout, () => [
+  revalidate(revalidateProductShell), // producer reruns
+  intercept("@modal", "product", <ProductModal />, () => [
+    revalidate(revalidateProductShell), // consumer reruns
+    loader(ProductLoader),
+  ]),
+]);
+```
+
+Compose multiple contracts if the intercept depends on multiple upstream
+domains.
+
+Helper handoff style keeps intercept trees terse:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateProduct = () => [
+  revalidate(revalidateProductShell),
+];
+
+layout(ProductLayout, () => [
+  revalidateProduct(),
+  intercept("@modal", "product", <ProductModal />, () => [
+    revalidateProduct(),
+    loader(ProductLoader),
+  ]),
+]);
+```
+
 ## Conditional Intercept with when()
 
 Only intercept based on navigation context:
@@ -166,6 +241,10 @@ Runtime behavior:
 Loaders inside the intercept always run fresh at request time, same as regular
 pre-rendered routes.
 
+During action-driven partial revalidation, this same partial rule applies:
+refreshing the intercept does not implicitly rebuild non-revalidated outer
+segments.
+
 ## Complete Example
 
 ```typescript

package/skills/layout/SKILL.md

@@ -8,6 +8,9 @@ argument-hint: [component]
 
 Layouts wrap child routes and persist during navigation within their scope.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Layout
 
 ```typescript
@@ -145,6 +148,13 @@ A layout as a child of `path()` wraps the route content and can read
 data set by the route handler via `ctx.get()`. The handler always
 executes before its children.
 
+This handler-first guarantee applies to a single full render pass
+(initial render, prerender, or full HTML re-render). During partial
+action revalidation, only the segments that revalidate are recomputed.
+If an orphan layout depends on data established by an outer handler or
+layout, that outer segment must also revalidate, or the orphan must
+guard/reload the data independently.
+
 ```typescript
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
@@ -175,8 +185,10 @@ urls(({ path, layout, parallel }) => [
 ])
 ```
 
-Orphan layouts cannot call `ctx.set()` -- only the route handler and
-middleware can write context variables.
+Orphan layouts can call `ctx.get()` to read data set by their parent
+handler. They can also call `ctx.set()`, though the primary pattern is
+for route handlers and middleware to write context variables and for
+orphan layouts to read them.
 
 ## Layout Revalidation
 
@@ -198,6 +210,54 @@ layout(<CartLayout />, () => [
 ])
 ```
 
+If child segments read data that was established by this layout or by a
+route handler above them, revalidate the outer segment too. Partial
+revalidation does not re-run non-revalidated ancestors just to rebuild
+their `ctx.set()` state.
+
+### Revalidation Contracts
+
+For shared upstream data, define named revalidation functions and reuse
+them on both producer and consumer segments:
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#addToCart") ?? false;
+```
+
+```typescript
+layout(<CartLayout />, () => [
+  revalidate(revalidateCartData), // producer
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(revalidateCartData), // consumer
+  ]),
+]);
+```
+
+If a segment depends on multiple upstream domains, compose multiple
+contracts (`revalidateAuthData`, `revalidateCartData`, and so on).
+
+You can also package them as importable handoff helpers:
+
+```typescript
+// revalidation-contracts.ts
+import { revalidate } from "@rangojs/router";
+
+export const revalidateAuthData = ({ actionId }) =>
+  actionId?.includes("src/actions/auth.ts#") ?? false;
+export const revalidateAuth = () => [revalidate(revalidateAuthData)];
+```
+
+```typescript
+layout(<ShellLayout />, () => [
+  revalidateAuth(),
+  path("/account", AccountPage, { name: "account" }, () => [
+    revalidateAuth(),
+  ]),
+]);
+```
+
 ## Complete Example
 
 ```typescript

package/skills/loader/SKILL.md

@@ -98,9 +98,12 @@ Loaders receive the same context as route handlers:
 export const ProductLoader = createLoader(async (ctx) => {
   "use server";
 
-  // URL params
+  // URL params (may include client-provided overrides for fetchable loaders)
   const { slug } = ctx.params;
 
+  // Server-trusted route params (from URL pattern matching, cannot be overridden)
+  const { slug: trustedSlug } = ctx.routeParams;
+
   // Query params
   const variant = ctx.url.searchParams.get("variant");
 
@@ -117,6 +120,33 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 ```
 
+### params vs routeParams
+
+- `ctx.params` — merged route params + explicit loader params. For fetchable
+  loaders called with `load(Loader, { params: { ... } })`, explicit params
+  override route-matched params.
+- `ctx.routeParams` — server-trusted route params from URL pattern matching.
+  Cannot be overridden by client-provided params.
+
+Use `ctx.routeParams` when you need trusted route identity for authorization
+or resource scoping:
+
+```typescript
+export const OrderLoader = createLoader(async (ctx) => {
+  "use server";
+
+  // Use routeParams for auth checks — client cannot spoof the URL-matched ID
+  const { orderId } = ctx.routeParams;
+  const user = ctx.get("user");
+
+  const order = await db.orders.get(orderId);
+  if (order.userId !== user.id)
+    throw new Response("Forbidden", { status: 403 });
+
+  return { order };
+});
+```
+
 ## Loader with Children
 
 Add caching or revalidation to specific loaders:
@@ -138,6 +168,44 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+### Revalidation Contracts for Loader Dependencies
+
+If a loader reads `ctx.get()` data produced by an outer handler/layout, share
+the same named revalidation contract across producer and consumer segments.
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateAccountScope = ({ actionId }) =>
+  actionId?.includes("src/actions/account.ts#") ?? false;
+
+layout(AccountLayout, () => [
+  revalidate(revalidateAccountScope), // producer reruns
+  path("/account/orders", OrdersPage, { name: "account.orders" }, () => [
+    loader(OrdersLoader, () => [
+      revalidate(revalidateAccountScope), // consumer reruns
+    ]),
+  ]),
+]);
+```
+
+For segments that depend on multiple upstream domains, compose multiple
+contracts on both sides.
+
+To keep loader route trees concise, export helper wrappers:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateAccount = () => [revalidate(revalidateAccountScope)];
+
+layout(AccountLayout, () => [
+  revalidateAccount(),
+  path("/account/orders", OrdersPage, { name: "account.orders" }, () => [
+    loader(OrdersLoader, () => [revalidateAccount()]),
+  ]),
+]);
+```
+
 ## Loaders: The Live Data Layer
 
 Loaders are the live data layer of the router. They resolve fresh on every
@@ -349,6 +417,31 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+### Fetchable Loader with Middleware
+
+Pass an options object instead of `true` to attach per-loader middleware.
+This middleware runs only on `_rsc_loader` fetch requests (client-side
+`load()` / `useFetchLoader()` calls), not during SSR `ctx.use()` execution:
+
+```typescript
+import { createLoader } from "@rangojs/router";
+import { authMiddleware } from "../middleware/auth";
+import { rateLimitMiddleware } from "../middleware/rate-limit";
+
+export const ProtectedLoader = createLoader(
+  async (ctx) => {
+    "use server";
+
+    const user = ctx.get("user");
+    return { orders: await db.orders.list(user.id) };
+  },
+  { middleware: [authMiddleware, rateLimitMiddleware] },
+);
+```
+
+The middleware uses the same `MiddlewareFn` signature as route/app middleware,
+so you can reuse existing middleware functions directly.
+
 Fetchable loaders support both GET and POST (PUT, PATCH, DELETE) from the client.
 The `load()` function auto-detects the body type:
 

package/skills/middleware/SKILL.md

@@ -8,6 +8,87 @@ argument-hint: [middleware-name]
 
 Middleware runs before/after route handlers using the onion model.
 
+## Execution Model
+
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
+There are two levels of middleware with different execution scopes:
+
+### Global middleware (`router.use()`)
+
+Registered on the router instance. Wraps the **entire request**, including server actions, rendering, and progressive enhancement (PE) re-renders.
+
+```typescript
+const router = createRouter<AppEnv>({})
+  .use(loggerMiddleware) // all routes
+  .use("/admin/*", authMiddleware) // pattern-scoped
+  .routes(urlpatterns);
+```
+
+### Route middleware (`middleware()` in `urls()`)
+
+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).
+
+```
+Request flow (with action):
+  global mw -> action executes -> route mw -> layout -> handler -> loaders
+
+Request flow (no action):
+  global mw -> route mw -> layout -> handler -> loaders
+
+Progressive enhancement (no-JS form POST):
+  global mw -> action executes -> route mw -> full page re-render
+```
+
+The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
+
+Revalidation is still partial. Route middleware wraps the render pass that
+does happen, but it does not force unrelated outer segments to recompute.
+If a child segment depends on data established by an outer handler/layout,
+revalidate that outer segment too, or have the child guard/reload the
+data itself.
+
+### Revalidation Contracts with Middleware-Backed Trees
+
+Middleware can establish request-level context (`ctx.set`) for segments that
+execute in the current render pass. It does not change partial revalidation
+boundaries between handler/layout/parallel segments.
+
+For shared segment data, use named revalidation contracts on both the producer
+and consumer segments, even when middleware is present in the chain.
+
+```typescript
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#") ?? false;
+
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidate(revalidateCartData), // producer reruns
+  parallel(
+    { "@cart": CartSummary },
+    () => [revalidate(revalidateCartData)], // consumer reruns
+  ),
+]);
+```
+
+You can package those contracts as importable helpers to avoid repeating
+`revalidate(...)` at each segment:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  middleware(cartRenderMiddleware),
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
+Route middleware is the right place for per-route concerns that affect rendering (setting context variables for handlers, adding response headers, reading cookies set by actions). It is NOT the right place for action guards -- use global middleware for that.
+
 ## Basic Middleware
 
 ```typescript

package/skills/parallel/SKILL.md

@@ -8,6 +8,9 @@ argument-hint: [@slot-name]
 
 Parallel routes render multiple components simultaneously in named slots.
 
+Canonical semantics reference:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
 ## Basic Parallel Routes
 
 ```typescript
@@ -56,8 +59,21 @@ parallel({
 
 ## Reading Handler Data
 
-When a parallel is inside a route that uses `ctx.set()`, it can read that
-data via `ctx.get()`. The route handler always executes before its children.
+Parallels can read `ctx.set()` values from their parent handler or layout
+via `ctx.get()`. The handler always executes before its parallels
+(handler-first).
+
+Visibility follows tree structure:
+
+- Layout-level parallels see layout data, but not path handler data
+  (the path is a separate entry).
+- Parallels inside a path (or its orphan layouts) see both layout and
+  path handler data.
+
+This applies to full render passes. During partial action revalidation,
+only revalidated segments are recomputed. If a parallel depends on data
+set by an outer handler or layout, revalidate that outer segment too, or
+have the parallel reload/guard the data itself.
 
 ```typescript
 path("/dashboard/:id", (ctx) => {
@@ -142,6 +158,45 @@ parallel(
 )
 ```
 
+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.
+
+### Revalidation Contracts for Parallel Dependencies
+
+Prefer named revalidation contracts shared by both the upstream producer and
+the parallel consumer:
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCartData = ({ actionId }) =>
+  actionId?.includes("src/actions/cart.ts#") ?? false;
+
+layout(CartLayout, () => [
+  revalidate(revalidateCartData), // producer reruns
+  parallel(
+    { "@cart": CartSummary },
+    () => [revalidate(revalidateCartData)], // consumer reruns
+  ),
+]);
+```
+
+If the slot consumes multiple upstream domains, compose the contracts on both
+segments.
+
+Handoff helper style also works:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCart = () => [revalidate(revalidateCartData)];
+
+layout(CartLayout, () => [
+  revalidateCart(),
+  parallel({ "@cart": CartSummary }, () => [revalidateCart()]),
+]);
+```
+
 ## Named Outlets
 
 Use `ParallelOutlet` to render slots in layouts: