@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define middleware for authentication, logging, and request processing in @rangojs/router
+description: Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.
 argument-hint: [middleware-name]
 ---
 
@@ -10,9 +10,6 @@ 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()`)
@@ -26,21 +23,32 @@ const router = createRouter<AppEnv>({})
   .routes(urlpatterns);
 ```
 
+When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
+
 ### 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).
 
+> **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
+  global mw -> action executes -> route mw -> render pass
 
 Request flow (no action):
-  global mw -> route mw -> layout -> handler -> loaders
+  global mw -> route mw -> render pass
 
 Progressive enhancement (no-JS form POST):
   global mw -> action executes -> route mw -> full page re-render
 ```
 
+The **render pass** resolves handler, layouts, parallels, and loaders together —
+it is not a handler-then-loaders sequence. Handler-first ordering is guaranteed
+only between a route handler and its child/orphan layouts and parallels (so
+`ctx.set` is visible); loaders run **concurrently** and stream their results, so
+their latency overlaps rendering rather than blocking it. See `/loader` →
+"Parallel and streaming".
+
 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
@@ -52,15 +60,21 @@ 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.
+execute in the current render pass. Because route middleware wraps **every**
+render pass — normal renders, post-action revalidation, PE re-renders — its
+variables are never stale: middleware is the safest `ctx.set` rung on the
+data-passing ladder (`/rango` → "Passing data down the tree"). But 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;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   middleware(cartRenderMiddleware),
@@ -135,17 +149,46 @@ export const urlpatterns = urls(({ path, layout, middleware }) => [
 ## Middleware with Multiple Handlers
 
 ```typescript
-// Spread multiple middleware from a single export
+// Group multiple middleware in an array
 export const shopMiddleware = [loggerMiddleware, mockAuthMiddleware];
 
-// In routes
+// In routes — pass the array directly
 layout(<ShopLayout />, () => [
-  middleware(...shopMiddleware),
+  middleware(shopMiddleware),
 
   path("/shop", ShopIndex, { name: "shop" }),
 ])
 ```
 
+## Wrapping Middleware (Scoped to Children)
+
+Use the wrapping form to scope middleware to a subset of routes without
+introducing a visible layout:
+
+```typescript
+urls(({ path, middleware }) => [
+  // authMw only applies to /admin and /admin/settings
+  middleware(authMw, () => [
+    path("/admin", AdminPage, { name: "admin" }),
+    path("/admin/settings", SettingsPage, { name: "settings" }),
+  ]),
+
+  // Public route — no authMw
+  path("/", HomePage, { name: "home" }),
+]);
+```
+
+Multiple middleware with wrapping:
+
+```typescript
+middleware([authMw, loggingMw], () => [
+  path("/admin", AdminPage, { name: "admin" }),
+]);
+```
+
+This creates a transparent layout (`<Outlet />`) that carries the middleware.
+The middleware does not affect sibling routes outside the callback.
+
 ## Middleware Context
 
 ```typescript
@@ -154,14 +197,18 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.request; // Request object
   ctx.url; // Parsed URL
   ctx.params; // Route parameters
+  ctx.build; // in middleware: true only during Prerender + ppr build-shell capture (plain Prerender does not run middleware)
 
   // Access platform bindings (plain bindings from createRouter<TEnv>())
   ctx.env.DB; // D1Database
   ctx.env.KV; // KVNamespace
 
-  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
+  // Opt the current request out of PPR shell lookup/capture.
+  ctx.dynamic();
+
   // Continue to next middleware/handler
   await next();
 
@@ -200,8 +247,37 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
 ```
 
 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.
+via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use Rango.Vars for app-wide middleware state.
+
+## Build-Time PPR Middleware
+
+Normal `Prerender` Flight payload collection does not run middleware: there is
+no request to wrap. The exception is `Prerender` + `ppr` build-shell capture.
+After the Flight payload exists, the shell producer replays global and route
+middleware for each generated URL before it captures HTML.
+
+In that build-shell pass:
+
+- `ctx.build === true`;
+- `ctx.waitUntil()` is inert;
+- `ctx.dynamic()` skips the baked shell for that URL;
+- context variables set by middleware are visible to the shell render.
+
+Use this to keep side effects predictable:
+
+```typescript
+export const commerceMiddleware: Middleware = async (ctx, next) => {
+  if (ctx.build) {
+    ctx.dynamic(); // leave this shell to runtime PPR
+    return next();
+  }
+
+  const session = await commerce.auth(ctx.request);
+  ctx.set("session", session);
+  return next();
+};
+```
 
 ## Redirect with State in Middleware