@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/skills/loader/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loader
 description: Define data loaders for fetching data in routes with createLoader
-argument-hint: [name]
+argument-hint: [loader]
 ---
 
 # Data Loaders with loader()
@@ -13,7 +13,9 @@ Loaders fetch data on the server and stream it to the client.
 ```typescript
 import { createLoader } from "@rangojs/router";
 
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+
   const product = await ctx.env.DB.prepare(
     "SELECT * FROM products WHERE slug = ?",
   )
@@ -30,19 +32,19 @@ All of the following are equivalent and fully supported by the Vite transform:
 
 ```typescript
 // Direct export (most common)
-export const ProductLoader = createLoader("product", handler);
+export const ProductLoader = createLoader(handler);
 
 // Separate declaration + named export
-const ProductLoader = createLoader("product", handler);
+const ProductLoader = createLoader(handler);
 export { ProductLoader };
 
 // Aliased export
-const InternalLoader = createLoader("product", handler);
+const InternalLoader = createLoader(handler);
 export { InternalLoader as ProductLoader };
 
 // Aliased import
 import { createLoader as cl } from "@rangojs/router";
-export const ProductLoader = cl("product", handler);
+export const ProductLoader = cl(handler);
 ```
 
 The `export const` form and the `const + export { }` form both work for
@@ -66,7 +68,7 @@ export const urlpatterns = urls(({ path, loader }) => [
 ### In Server Components
 
 ```typescript
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader } from "./loaders/product";
 
 async function ProductPage() {
@@ -79,12 +81,12 @@ async function ProductPage() {
 
 ```typescript
 "use client";
-import { useLoaderData } from "@rangojs/router/client";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader } from "./loaders/product";
 
 function ProductDetails() {
-  const { product } = useLoaderData(ProductLoader);
-  return <div>{product.description}</div>;
+  const { data } = useLoader(ProductLoader);
+  return <div>{data.product.description}</div>;
 }
 ```
 
@@ -93,10 +95,15 @@ function ProductDetails() {
 Loaders receive the same context as route handlers:
 
 ```typescript
-export const ProductLoader = createLoader("product", async (ctx) => {
-  // URL params
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+
+  // 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");
 
@@ -113,6 +120,33 @@ export const ProductLoader = createLoader("product", 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:
@@ -134,6 +168,157 @@ 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
+request, even when the route's UI segments are served from cache. This is a
+core design principle — route-level `cache()` caches rendered components but
+never caches loader data. Loaders are excluded at storage time and re-resolved
+on retrieval.
+
+This means `cache()` gives you cached UI + fresh data by default. Pre-rendering
+follows the same rule: at build time, loaders are skipped entirely (there is no
+real request context), and at runtime the worker resolves them fresh against
+the live database.
+
+### Opting a Loader into Caching
+
+To cache a specific loader's data, attach a `cache()` child:
+
+```typescript
+loader(ProductLoader, () => [cache({ ttl: 300 })]),
+```
+
+The loader's data is cached independently from the route's segment cache,
+using the same `SegmentCacheStore` (app-level or per-loader override).
+
+Values are serialized through RSC Flight, so loaders can return ReactNode,
+Promises, null, and any RSC-serializable type — all round-trip correctly
+through the cache.
+
+### Cache Key
+
+The default cache key is `loader:{loaderId}:{pathname}:{sortedParams}`.
+This can be customized at two levels:
+
+```typescript
+// Full override — key function replaces the default entirely
+loader(ProductLoader, () => [
+  cache({
+    ttl: 300,
+    key: (ctx) => `product:${ctx.params.slug}:${cookies().get("locale")?.value ?? "en"}`,
+  }),
+]),
+
+// Store-level keyGenerator — modifies the default key (e.g., adds a region prefix)
+// Set in the store configuration, applies to all entries in that store
+```
+
+Resolution priority (same as route-level `cache()`):
+
+1. `key(ctx)` from cache options — full override
+2. `store.keyGenerator(ctx, defaultKey)` — store-level modification
+3. Default key — `loader:{id}:{pathname}:{params}`
+
+If a custom key function throws, it falls back to the default key silently
+(logged to console.error).
+
+### Tags for Invalidation
+
+```typescript
+// Static tags
+loader(ProductLoader, () => [
+  cache({ ttl: 300, tags: ["products", "catalog"] }),
+]),
+
+// Dynamic tags
+loader(ProductLoader, () => [
+  cache({
+    ttl: 300,
+    tags: (ctx) => [`product:${ctx.params.slug}`, "products"],
+  }),
+]),
+```
+
+### Stale-While-Revalidate
+
+```typescript
+loader(ProductLoader, () => [
+  cache({ ttl: 60, swr: 300 }),
+]),
+```
+
+During the SWR window (60-360s), stale data is returned immediately while
+fresh data is fetched in the background via `waitUntil`. After the SWR window
+expires (360s+), the entry is treated as a cache miss.
+
+### Conditional Caching
+
+Skip the cache at runtime based on request properties:
+
+```typescript
+loader(ProductLoader, () => [
+  cache({
+    ttl: 300,
+    condition: (ctx) => !ctx.request.headers.has("authorization"),
+  }),
+]),
+```
+
+When `condition` returns false, the loader runs fresh and the cache is bypassed
+entirely (no read, no write).
+
+### Per-Loader Store Override
+
+```typescript
+const hotStore = new MemorySegmentCacheStore({ defaults: { ttl: 10 } });
+
+loader(PricingLoader, () => [
+  cache({ store: hotStore }),
+]),
+```
+
+Without an explicit store, the loader uses the app-level store from the
+handler config (`cache.store`).
+
 ## Multiple Loaders
 
 Routes can have multiple loaders that run in parallel:
@@ -232,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:
 
@@ -288,7 +498,9 @@ Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
 // loaders/shop.ts
 import { createLoader } from "@rangojs/router";
 
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+
   const product = await ctx.env.DB
     .prepare("SELECT * FROM products WHERE slug = ?")
     .bind(ctx.params.slug)
@@ -301,7 +513,9 @@ export const ProductLoader = createLoader("product", async (ctx) => {
   return { product };
 });
 
-export const CartLoader = createLoader("cart", async (ctx) => {
+export const CartLoader = createLoader(async (ctx) => {
+  "use server";
+
   const user = ctx.get("user");
   if (!user) return { cart: null };
 
@@ -325,7 +539,7 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
 ]);
 
 // pages/product.tsx
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
 async function ProductPage() {

package/skills/middleware/SKILL.md

@@ -8,12 +8,93 @@ 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
-import { createMiddleware } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
-export const authMiddleware = createMiddleware(async (ctx, next) => {
+export const authMiddleware: Middleware = async (ctx, next) => {
   const token = ctx.request.headers.get("Authorization");
 
   if (!token) {
@@ -24,7 +105,7 @@ export const authMiddleware = createMiddleware(async (ctx, next) => {
   ctx.set("user", user);
 
   await next();
-});
+};
 ```
 
 ## Using Middleware in Routes
@@ -68,7 +149,7 @@ layout(<ShopLayout />, () => [
 ## Middleware Context
 
 ```typescript
-export const myMiddleware = createMiddleware(async (ctx, next) => {
+export const myMiddleware: Middleware = async (ctx, next) => {
   // Access request
   ctx.request; // Request object
   ctx.url; // Parsed URL
@@ -86,7 +167,7 @@ export const myMiddleware = createMiddleware(async (ctx, next) => {
 
   // After handler (response intercepting)
   console.log("Handler completed");
-});
+};
 ```
 
 ### Typed context variables in middleware
@@ -94,19 +175,20 @@ export const myMiddleware = createMiddleware(async (ctx, next) => {
 Use `createVar<T>()` for type-safe data sharing between middleware and handlers:
 
 ```typescript
-import { createMiddleware, createVar } from "@rangojs/router";
+import { createVar } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
 interface AuthUser { id: string; email: string; role: string }
 export const CurrentUser = createVar<AuthUser>();
 
-export const authMiddleware = createMiddleware(async (ctx, next) => {
+export const authMiddleware: Middleware = async (ctx, next) => {
   const token = ctx.request.headers.get("Authorization");
   if (!token) throw new Response("Unauthorized", { status: 401 });
 
   const user = await verifyToken(token);
   ctx.set(CurrentUser, user);  // type-checked
   await next();
-});
+};
 
 // In a handler -- typed read
 import { CurrentUser } from "./middleware";
@@ -124,17 +206,14 @@ data; use RSCRouter.Vars for app-wide middleware state.
 ## Redirect with State in Middleware
 
 ```typescript
-import {
-  createMiddleware,
-  redirect,
-  createLocationState,
-} from "@rangojs/router";
+import { redirect, createLocationState } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
 export const FlashMessage = createLocationState<{ text: string }>({
   flash: true,
 });
 
-export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
   const token = ctx.request.headers.get("Authorization");
   if (!token) {
     return redirect("/login", {
@@ -142,7 +221,7 @@ export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
     });
   }
   await next();
-});
+};
 ```
 
 Read the flash on the target page with `useLocationState(FlashMessage)`. The `{ flash: true }` option makes it auto-clear after first render. See `/hooks`.
@@ -150,7 +229,7 @@ Read the flash on the target page with `useLocationState(FlashMessage)`. The `{
 ## Authentication Middleware
 
 ```typescript
-export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
   const user = ctx.get("user");
 
   if (!user) {
@@ -158,9 +237,9 @@ export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
   }
 
   await next();
-});
+};
 
-export const permissionsMiddleware = createMiddleware(async (ctx, next) => {
+export const permissionsMiddleware: Middleware = async (ctx, next) => {
   const user = ctx.get("user");
   const requiredPermission = "admin";
 
@@ -169,13 +248,13 @@ export const permissionsMiddleware = createMiddleware(async (ctx, next) => {
   }
 
   await next();
-});
+};
 ```
 
 ## Logger Middleware
 
 ```typescript
-export const loggerMiddleware = createMiddleware(async (ctx, next) => {
+export const loggerMiddleware: Middleware = async (ctx, next) => {
   const start = Date.now();
 
   console.log(`[${ctx.request.method}] ${ctx.url.pathname}`);
@@ -184,13 +263,13 @@ export const loggerMiddleware = createMiddleware(async (ctx, next) => {
 
   const duration = Date.now() - start;
   console.log(`[${ctx.request.method}] ${ctx.url.pathname} - ${duration}ms`);
-});
+};
 ```
 
 ## Rate Limiting Middleware
 
 ```typescript
-export const rateLimitMiddleware = createMiddleware(async (ctx, next) => {
+export const rateLimitMiddleware: Middleware = async (ctx, next) => {
   const ip = ctx.request.headers.get("CF-Connecting-IP") ?? "unknown";
   const key = `rate-limit:${ip}`;
 
@@ -206,32 +285,32 @@ export const rateLimitMiddleware = createMiddleware(async (ctx, next) => {
   });
 
   await next();
-});
+};
 ```
 
 ## Complete Example
 
 ```typescript
 // middleware/index.ts
-import { createMiddleware } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
-export const loggerMiddleware = createMiddleware(async (ctx, next) => {
+export const loggerMiddleware: Middleware = async (ctx, next) => {
   console.log(`[${ctx.request.method}] ${ctx.url.pathname}`);
   await next();
-});
+};
 
-export const mockAuthMiddleware = createMiddleware(async (ctx, next) => {
+export const mockAuthMiddleware: Middleware = async (ctx, next) => {
   // Mock user for development
   ctx.set("user", { id: "1", name: "Demo User" });
   await next();
-});
+};
 
-export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
   if (!ctx.get("user")) {
     throw new Response("Unauthorized", { status: 401 });
   }
   await next();
-});
+};
 
 // urls.tsx
 import { urls } from "@rangojs/router";

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: