@rangojs/router 0.0.0-experimental.25 → 0.0.0-experimental.25dbaac3

package/skills/links/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
-argument-hint: [href|useHref|useMount|scopedReverse]
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, and scopedReverse
+argument-hint: [ctx.reverse|href|useHref|useMount|scopedReverse]
 ---
 
 # Links & URL Generation
 
 @rangojs/router provides different href APIs for server and client contexts.
 
+**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills mount params, and resolves local (`.name`) and absolute (`name.sub`) names.
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context, neither of which are available in the browser. Client components receive URLs as props, loader data, or server-action return values — they never call `reverse` directly.
+
 ## Server: ctx.reverse()
 
-Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+Available in route handlers via HandlerContext. Resolves named routes using the full route map. This is the default way to generate URLs on the server.
 
 ```typescript
 import { urls, scopedReverse } from "@rangojs/router";
@@ -103,7 +107,7 @@ path("/search", (ctx) => {
 
 ### scopedReverse() - type-safe ctx.reverse
 
-Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+Wraps `ctx.reverse` with local route type information for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast. The same dot-prefix rule applies: local names use `.name`, global names use `name.sub`.
 
 ```typescript
 import { scopedReverse } from "@rangojs/router";
@@ -111,18 +115,85 @@ import { scopedReverse } from "@rangojs/router";
 path("/product/:slug", (ctx) => {
   const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
 
-  reverse("cart");                        // Type-safe local name
-  reverse("product", { slug: "widget" }); // Type-safe with params
-  reverse("blog.post");                   // Absolute names (dot notation) always allowed
-  reverse("/about");                      // Path-based always allowed
+  reverse(".cart");                        // Local name (dot-prefixed) — resolves in include scope
+  reverse(".product", { slug: "widget" }); // Local name with params
+  reverse("blog.post", { slug: "hi" });    // Global name (dotted) — full route map
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+`reverse()` does not accept raw path strings (`"/about"`). For static paths in client components, use `href("/about")`; on the server, look up the route by name.
+
+## Client components: receive URLs as props
+
+`reverse()` is not available inside `"use client"` modules — there is no handler context and no route manifest in the browser bundle. Generate the URL on the server and hand it to the client component.
+
+Three patterns, in order of preference:
+
+1. Pass as a prop from a server component:
+
+```tsx
+// server
+function BlogPostPage(ctx: HandlerContext) {
+  return <ShareButton url={ctx.reverse(".post", { slug: ctx.params.slug })} />;
+}
+```
+
+```tsx
+"use client";
+
+export function ShareButton({ url }: { url: string }) {
+  return (
+    <button onClick={() => navigator.clipboard.writeText(url)}>Share</button>
+  );
+}
+```
+
+2. Return from a loader (attached to the route via the DSL):
+
+```tsx
+// server — loaders/nav.ts
+export const NavLoader = createLoader((ctx) => ({
+  home: ctx.reverse("home"),
+  blog: ctx.reverse("blog.index"),
+}));
+
+// server — urls.tsx: attach the loader so useLoader has data in context
+const urlpatterns = urls(({ path, loader }) => [
+  path("/", HomePage, { name: "home" }, () => [loader(NavLoader)]),
+]);
+```
+
+```tsx
+"use client";
+
+function Nav() {
+  const { data } = useLoader(NavLoader);
+  return <Link to={data.home}>Home</Link>;
+}
+```
+
+`useLoader()` requires the loader to be attached to an active route. If you need on-demand fetching instead, use `useFetchLoader()`.
+
+3. Return from a server action:
+
+```tsx
+"use server";
+
+export async function getProductUrl(slug: string) {
+  const ctx = getRequestContext();
+  return ctx.reverse("product", { slug });
+}
+```
+
+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()
 
-Plain function for absolute path-based URLs. No hook needed - works anywhere.
+Plain function for absolute path-based URLs. No hook needed - works anywhere in client components. `href()` validates paths at compile time, but does **not** resolve named routes — for named routes, use one of the patterns above.
 
 ```typescript
 "use client";
@@ -139,7 +210,9 @@ function GlobalNav() {
 }
 ```
 
-`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
 ## Client: useHref()
 
@@ -185,13 +258,16 @@ function MountInfo() {
 
 ## When to use what
 
-| Context          | API                             | Resolves                        | Use for                             |
-| ---------------- | ------------------------------- | ------------------------------- | ----------------------------------- |
-| Server handler   | `ctx.reverse("name")`           | Named routes (local + absolute) | Server-side URL generation          |
-| Server handler   | `scopedReverse<T>(ctx.reverse)` | Same, with type safety          | Type-safe server URLs               |
-| Client component | `href("/path")`                 | Absolute paths                  | Global navigation                   |
-| Client component | `useHref()`                     | Mount-prefixed paths            | Local navigation inside `include()` |
-| Client component | `useMount()`                    | Raw mount path                  | Custom mount-aware logic            |
+| Context          | API                                                | Resolves                        | Use for                                                          |
+| ---------------- | -------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
+| Server handler   | `ctx.reverse("name")`                              | Named routes (local + absolute) | **Default** server-side URL generation                           |
+| Server handler   | `scopedReverse<T>(ctx.reverse)`                    | Same, with type safety          | Type-safe server URLs                                            |
+| Client component | (URL passed as prop / loader data / action return) | Named routes                    | Any URL derived from a named route — generate on server, pass in |
+| Client component | `href("/path")`                                    | Absolute paths (static strings) | Static navigation where no named-route lookup is needed          |
+| Client component | `useHref()`                                        | Mount-prefixed paths            | Local navigation inside `include()`                              |
+| Client component | `useMount()`                                       | Raw mount path                  | Custom mount-aware logic                                         |
+
+> `reverse()` is server-only. Client components never import or call it — they receive the already-resolved string.
 
 ## Complete example: mounted module
 

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
 
@@ -65,19 +68,10 @@ export const urlpatterns = urls(({ path, loader }) => [
 
 ## Consuming Loader Data
 
-### In Server Components
-
-```typescript
-import { useLoader } from "@rangojs/router/client";
-import { ProductLoader } from "./loaders/product";
-
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  return <h1>{product.name}</h1>;
-}
-```
-
-### In Client Components
+Register loaders with `loader()` in the DSL and consume them in client
+components with `useLoader()`. This is the recommended pattern — it keeps
+data fetching on the server and consumption on the client, with a clean
+separation that works correctly with `cache()`.
 
 ```typescript
 "use client";
@@ -90,9 +84,87 @@ function ProductDetails() {
 }
 ```
 
+```typescript
+// Route definition — loader() registration required
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader),
+]);
+```
+
+DSL loaders are the **live data layer** — they resolve fresh on every
+request, even when the route is inside a `cache()` boundary. The router
+excludes them from the segment cache at storage time and re-resolves them
+on retrieval. This means `cache()` gives you cached UI + fresh data by
+default.
+
+### Cache safety
+
+DSL loaders can safely read `createVar({ cache: false })` variables
+because they are always resolved fresh. The read guard is bypassed for
+loader functions — they never produce stale data.
+
+### ctx.use(Loader) — escape hatch
+
+For cases where you need loader data in the server handler itself (e.g.,
+to set ctx variables or make routing decisions), use `ctx.use(Loader)`:
+
+```typescript
+path("/product/:slug", async (ctx) => {
+  const { product } = await ctx.use(ProductLoader);
+  ctx.set(Product, product); // make available to children
+  return <ProductPage />;
+}, { name: "product" }, () => [
+  loader(ProductLoader), // still register for client consumption
+])
+```
+
+When you register with `loader()` in the DSL, `ctx.use()` returns the
+same memoized result — loaders never run twice per request.
+
+**Limitations of ctx.use(Loader):**
+
+- The handler output depends on the loader data. If the route is inside
+  `cache()`, the handler is cached with the loader result baked in —
+  defeating the live data guarantee.
+- Non-cacheable variable reads (`createVar({ cache: false })`) inside the
+  handler still throw, even if the data came from a loader.
+- Prefer DSL `loader()` + client `useLoader()` for data that depends on
+  non-cacheable context variables.
+
+**Never use `useLoader()` in server components** — it is a client-only API.
+
+### Summary
+
+| Pattern                | API                 | Cache-safe | Recommended |
+| ---------------------- | ------------------- | ---------- | ----------- |
+| DSL + client component | `useLoader(Loader)` | Yes        | Yes         |
+| Handler escape hatch   | `ctx.use(Loader)`   | No         | When needed |
+
 ## Loader Context
 
-Loaders receive the same context as route handlers:
+Loaders receive the same context shape as route handlers.
+
+### Full field surface
+
+| Field          | Type                           | Notes                                                                                               |
+| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                 |
+| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                        |
+| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                 |
+| `url`          | `URL`                          | Parsed request URL.                                                                                 |
+| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                     |
+| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                |
+| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                   |
+| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                 |
+| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                     |
+| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
+| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data.      |
+| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.               |
+| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                      |
+| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                     |
+| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).              |
+
+### Example
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
@@ -116,10 +188,21 @@ export const ProductLoader = createLoader(async (ctx) => {
   // Variables set by middleware (from RSCRouter.Vars augmentation)
   const user = ctx.get("user");
 
-  return { product: await fetchProduct(slug) };
+  // Type-checked URLs for payloads. `.name` resolves within the current
+  // include() scope; a bare `name` resolves globally. See /route and
+  // /typesafety for scope rules and route-name autocomplete.
+  const detailUrl = ctx.reverse(".detail", { slug });
+
+  return {
+    product: await fetchProduct(slug),
+    links: { self: detailUrl },
+  };
 });
 ```
 
+See `/route` for the full handler-context contract (shared with loaders) and
+`/typesafety` for route-name typing that powers `ctx.reverse` autocomplete.
+
 ### params vs routeParams
 
 - `ctx.params` — merged route params + explicit loader params. For fetchable
@@ -168,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
@@ -507,7 +621,7 @@ export const ProductLoader = createLoader(async (ctx) => {
     .first();
 
   if (!product) {
-    throw new Response("Product not found", { status: 404 });
+    notFound("Product not found");
   }
 
   return { product };
@@ -523,10 +637,9 @@ export const CartLoader = createLoader(async (ctx) => {
   return { cart };
 });
 
-// urls.tsx
+// urls.tsx — register loaders in the DSL
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
-    // Shared cart loader for all shop routes
     loader(CartLoader, () => [
       revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
     ]),
@@ -538,18 +651,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
   ]),
 ]);
 
-// pages/product.tsx
+// components/ProductDetails.tsx — consume in client component
+"use client";
 import { useLoader } from "@rangojs/router/client";
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  const { cart } = await useLoader(CartLoader);
+function ProductDetails() {
+  const { data: { product } } = useLoader(ProductLoader);
+  const { data: { cart } } = useLoader(CartLoader);
 
   return (
     <div>
       <h1>{product.name}</h1>
-      <AddToCartButton productId={product.id} inCart={cart?.items.includes(product.id)} />
+      <AddToCartButton
+        productId={product.id}
+        inCart={cart?.items.includes(product.id)}
+      />
     </div>
   );
 }

package/skills/middleware/SKILL.md

@@ -26,10 +26,14 @@ 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
@@ -135,17 +139,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