@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.9c87b9aa

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) {
@@ -21,10 +102,10 @@ export const authMiddleware = createMiddleware(async (ctx, next) => {
   }
 
   const user = await verifyToken(token);
-  ctx.env.Variables.user = user;
+  ctx.set("user", user);
 
   await next();
-});
+};
 ```
 
 ## Using Middleware in Routes
@@ -68,42 +149,98 @@ 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
-  ctx.params;               // Route parameters
+  ctx.request; // Request object
+  ctx.url; // Parsed URL
+  ctx.params; // Route parameters
 
-  // Access environment
-  ctx.env.Bindings.DB;      // Cloudflare bindings
-  ctx.env.Variables;        // Mutable variables
+  // Access platform bindings (plain bindings from createRouter<TEnv>())
+  ctx.env.DB; // D1Database
+  ctx.env.KV; // KVNamespace
 
-  // Set variables for downstream handlers
-  ctx.env.Variables.user = { id: "123", name: "John" };
+  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  ctx.set("user", { id: "123", name: "John" });
 
   // Continue to next middleware/handler
   await next();
 
   // After handler (response intercepting)
   console.log("Handler completed");
+};
+```
+
+### Typed context variables in middleware
+
+Use `createVar<T>()` for type-safe data sharing between middleware and handlers:
+
+```typescript
+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: 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";
+
+const Dashboard: Handler<"dashboard"> = (ctx) => {
+  const user = ctx.get(CurrentUser);  // typed as AuthUser | undefined
+  return <DashboardPage user={user!} />;
+};
+```
+
+This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
+via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use RSCRouter.Vars for app-wide middleware state.
+
+## Redirect with State in Middleware
+
+```typescript
+import { redirect, createLocationState } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
 });
+
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
+  const token = ctx.request.headers.get("Authorization");
+  if (!token) {
+    return redirect("/login", {
+      state: [FlashMessage({ text: "Please log in to continue" })],
+    });
+  }
+  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`.
+
 ## Authentication Middleware
 
 ```typescript
-export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
-  const user = ctx.env.Variables.user;
+export const requireAuthMiddleware: Middleware = async (ctx, next) => {
+  const user = ctx.get("user");
 
   if (!user) {
     throw new Response("Unauthorized", { status: 401 });
   }
 
   await next();
-});
+};
 
-export const permissionsMiddleware = createMiddleware(async (ctx, next) => {
-  const user = ctx.env.Variables.user;
+export const permissionsMiddleware: Middleware = async (ctx, next) => {
+  const user = ctx.get("user");
   const requiredPermission = "admin";
 
   if (!user?.permissions?.includes(requiredPermission)) {
@@ -111,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}`);
@@ -126,54 +263,54 @@ 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}`;
 
-  const count = await ctx.env.Bindings.KV.get(key);
+  const count = await ctx.env.KV.get(key);
   const requests = count ? parseInt(count) : 0;
 
   if (requests > 100) {
     throw new Response("Too Many Requests", { status: 429 });
   }
 
-  await ctx.env.Bindings.KV.put(key, String(requests + 1), {
+  await ctx.env.KV.put(key, String(requests + 1), {
     expirationTtl: 60,
   });
 
   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.env.Variables.user = { id: "1", name: "Demo User" };
+  ctx.set("user", { id: "1", name: "Demo User" });
   await next();
-});
+};
 
-export const requireAuthMiddleware = createMiddleware(async (ctx, next) => {
-  if (!ctx.env.Variables.user) {
+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/mime-routes/SKILL.md

@@ -18,14 +18,18 @@ Declare the same URL pattern with both an RSC route and one or more response-typ
 Order within the `urls()` array does not matter — the trie merges them at build time.
 
 ```typescript
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, include }) => [
   // RSC page + JSON API on the same URL
   path("/products/:id", ProductPage, { name: "product" }),
-  path.json("/products/:id", (ctx) => {
-    return db.getProduct(ctx.params.id);
-  }, { name: "productJson" }),
+  path.json(
+    "/products/:id",
+    (ctx) => {
+      return db.getProduct(ctx.params.id);
+    },
+    { name: "productJson" },
+  ),
 ]);
 ```
 
@@ -45,14 +49,14 @@ There is no special short-circuit — RSC follows the same negotiation rules as
 
 The MIME mapping used for matching:
 
-| Tag | MIME type |
-|-----|-----------|
+| Tag                  | MIME type                                                    |
+| -------------------- | ------------------------------------------------------------ |
 | RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
-| `json` | `application/json` |
-| `text` | `text/plain` |
-| `xml` | `application/xml` |
-| `html` | `text/html` |
-| `md` | `text/markdown` |
+| `json`               | `application/json`                                           |
+| `text`               | `text/plain`                                                 |
+| `xml`                | `application/xml`                                            |
+| `html`               | `text/html`                                                  |
+| `md`                 | `text/markdown`                                              |
 
 RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
 The browser's RSC runtime decodes this transparently — clients requesting `text/html` get

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
@@ -54,6 +57,108 @@ parallel({
 })
 ```
 
+## Reading Handler Data
+
+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) => {
+  const user = await getUser(ctx.params.id);
+  ctx.set("user", user);
+  return <DashboardPage user={user} />;
+}, { name: "dashboard" }, () => [
+  layout(DashboardLayout, () => [
+    parallel({
+      "@sidebar": (ctx) => {
+        const user = ctx.get("user");
+        return <Sidebar role={user?.role} />;
+      },
+    }),
+  ]),
+])
+```
+
+## Setting Handles (Meta, Breadcrumbs)
+
+Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
+push handle data. The data is associated with the **parent** layout or route
+segment, not the parallel segment itself. This is because parallels execute
+after their parent handler and inherit its segment scope.
+
+This works well for document-level metadata — the handle data follows the
+parent's lifecycle (appears when the parent is mounted, removed when it
+unmounts).
+
+```typescript
+parallel({
+  "@meta": (ctx) => {
+    const meta = ctx.use(Meta);
+    meta({ title: "Product Detail" });
+    meta({ name: "description", content: "..." });
+    return null; // UI-less slot, only sets metadata
+  },
+  "@sidebar": (ctx) => <Sidebar />,
+})
+```
+
+Multiple parallels on the same parent can each push handle data — they all
+accumulate under the parent segment ID.
+
+### Pattern: `@meta` slot for per-route metadata overrides
+
+A dedicated `@meta` parallel slot lets routes define metadata separately from
+their handler logic. The layout sets defaults via a title template, and each
+route overrides via its own `@meta` slot. Since child segments push after
+parents and `collectMeta` uses last-wins deduplication, overrides work
+naturally.
+
+```typescript
+// Layout sets defaults
+layout((ctx) => {
+  ctx.use(Meta)({ title: { template: "%s | Store", default: "Store" } });
+  return <StoreLayout />;
+}, () => [
+  // Route with @meta override — decoupled from handler rendering
+  path("/:slug", ProductPage, { name: "product" }, () => [
+    parallel({
+      "@meta": async (ctx) => {
+        const product = await ctx.use(ProductLoader);
+        const meta = ctx.use(Meta);
+        meta({ title: product.name });
+        meta({ name: "description", content: product.description });
+        meta({
+          "script:ld+json": {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            name: product.name,
+            description: product.description,
+          },
+        });
+        return null; // UI-less slot
+      },
+    }),
+  ]),
+])
+```
+
+This keeps the route handler focused on rendering UI while metadata
+(title, description, Open Graph, JSON-LD) lives in a composable slot that
+can be added, removed, or swapped per route without touching the handler.
+
 ## Parallel Routes with Loaders
 
 Add loaders and loading states to parallel routes:
@@ -71,6 +176,65 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript
@@ -97,7 +261,7 @@ Render different content based on context:
 ```typescript
 parallel({
   "@sidebar": (ctx) => {
-    const user = ctx.env.Variables.user;
+    const user = ctx.get("user");
     return user ? <UserSidebar user={user} /> : <GuestSidebar />;
   },
 })
@@ -120,6 +284,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: