@rangojs/router 0.0.0-experimental.c73f3e16 → 0.0.0-experimental.c7e2ee4c

package/skills/i18n/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: i18n
+description: Locale-aware routing with `include("/:locale?", ...)`, locale resolution chains, and react-intl integration
+argument-hint: "[topic]"
+---
+
+# Internationalization (i18n) and Locale Routing
+
+Rango doesn't ship an i18n module. The router gives you the URL primitives
+(optional include prefixes, constraints, typed reverse) and you compose
+them with whatever message library you use — `react-intl`, `lingui`,
+`@formatjs/intl`, or hand-rolled.
+
+This skill covers:
+
+- Mounting routes under an optional locale prefix (`/`, `/en`, `/gb`)
+- Constraining the prefix to a known locale set
+- Resolving the active locale (URL → cookie → `Accept-Language` → default)
+- Generating localized URLs via `reverse()` round-trip
+- Wiring `react-intl` into an RSC route tree
+
+## URL Shape: Optional Locale Prefix
+
+Mount your localized routes under an optional include prefix so the
+default locale lives at the bare URL and other locales get a prefix:
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+import { menuRoutes } from "./menu";
+
+export const urlpatterns = urls(({ include }) => [
+  include("/:locale?", menuRoutes, { name: "menu" }),
+]);
+```
+
+URLs that match:
+
+| URL            | Matched route   | `ctx.params.locale` |
+| -------------- | --------------- | ------------------- |
+| `/`            | `menu.index`    | `undefined`         |
+| `/en`          | `menu.index`    | `"en"`              |
+| `/c/breads`    | `menu.category` | `undefined`         |
+| `/en/c/breads` | `menu.category` | `"en"`              |
+
+> **Constrain to known locales** when you want unknown locales to fall
+> through to other routes (or 404) instead of being treated as a slug:
+>
+> ```typescript
+> include("/:locale(en|gb|fr)?", menuRoutes, { name: "menu" });
+> ```
+>
+> `/de` now 404s (constraint rejects `de`), and `/c/breads` continues to
+> match `menu.category` with `locale: undefined`. Without the constraint,
+> `/de` would match `menu.index` with `locale: "de"`.
+
+## Reading the Locale in Handlers
+
+Absent optionals are `undefined` (not `""`), so `??` coalesces correctly:
+
+```typescript
+import { Handler } from "@rangojs/router";
+
+export const MenuIndex: Handler<"menu.index"> = (ctx) => {
+  // ctx.params.locale is `string | undefined`
+  const locale = resolveLocale(ctx);
+  return <Welcome locale={locale} />;
+};
+```
+
+The `resolveLocale` helper below implements a typical fallback chain.
+
+## Locale Resolution
+
+URL is the strongest signal but you usually want a fallback chain:
+
+1. **URL prefix** — if the user navigates to `/gb/...`, honor it
+2. **Cookie** — sticky preference set by a previous language switcher
+3. **`Accept-Language`** — browser hint
+4. **Default** — your app default
+
+Put it in a small helper that every locale-aware handler calls:
+
+```typescript
+// lib/locale.ts
+import { cookies, headers } from "@rangojs/router";
+
+export const SUPPORTED_LOCALES = ["en", "gb", "fr"] as const;
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+const DEFAULT_LOCALE: Locale = "en";
+
+const isSupported = (v: string): v is Locale =>
+  (SUPPORTED_LOCALES as readonly string[]).includes(v);
+
+export function resolveLocale(ctx: {
+  params: Record<string, string | undefined>;
+}): Locale {
+  const fromUrl = ctx.params.locale;
+  if (fromUrl && isSupported(fromUrl)) return fromUrl;
+
+  const fromCookie = cookies().get("locale")?.value;
+  if (fromCookie && isSupported(fromCookie)) return fromCookie;
+
+  const accept = headers().get("accept-language") ?? "";
+  for (const tag of accept.split(",")) {
+    const code = tag.split(";")[0].trim().split("-")[0];
+    if (isSupported(code)) return code as Locale;
+  }
+  return DEFAULT_LOCALE;
+}
+```
+
+If you want to redirect to the canonical URL when the resolved locale
+doesn't match the URL (e.g., user has `gb` cookie but visits `/`), do
+that in a global middleware so it covers actions too:
+
+```typescript
+import { redirect } from "@rangojs/router";
+
+router.use("/*", async (ctx, next) => {
+  const fromUrl = ctx.params.locale;
+  const resolved = resolveLocale(ctx);
+  if (resolved !== DEFAULT_LOCALE && !fromUrl) {
+    return redirect(`/${resolved}${ctx.url.pathname}`);
+  }
+  await next();
+});
+```
+
+## Generating Localized URLs
+
+`reverse()` treats `undefined` and `""` for an optional param as "absent"
+and collapses the segment cleanly. The round-trip is symmetric with the
+matcher:
+
+```typescript
+ctx.reverse("menu.index", { locale: "" }); // → "/"
+ctx.reverse("menu.index", { locale: undefined }); // → "/"
+ctx.reverse("menu.index", { locale: "en" }); // → "/en"
+ctx.reverse("menu.category", { locale: "en", slug: "breads" }); // → "/en/c/breads"
+ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads"
+```
+
+If the active locale is the app default and your URL strategy hides it
+(`"en"` → `/`, others → `/<locale>`), normalize before calling reverse:
+
+```typescript
+const normalized = locale === DEFAULT_LOCALE ? undefined : locale;
+const href = ctx.reverse("menu.category", { locale: normalized, slug });
+```
+
+## react-intl Integration
+
+`react-intl` needs a `<IntlProvider>` wrapping the tree, with `locale`
+and `messages` props. The cleanest split: load messages on the server
+(handler or layout), pass them through to a client provider component.
+
+### Messages loader
+
+Load message bundles per locale. Keep them server-side so they stream
+through the RSC payload and don't bloat the client bundle:
+
+```typescript
+// lib/messages.ts
+import type { Locale } from "./locale";
+
+const loaders: Record<Locale, () => Promise<Record<string, string>>> = {
+  en: () => import("../messages/en.json").then((m) => m.default),
+  gb: () => import("../messages/gb.json").then((m) => m.default),
+  fr: () => import("../messages/fr.json").then((m) => m.default),
+};
+
+export async function loadMessages(locale: Locale) {
+  return loaders[locale]();
+}
+```
+
+### Server layout: hand off to the client provider
+
+```tsx
+// layouts/intl-layout.tsx (server component)
+import type { ReactNode } from "react";
+import { resolveLocale } from "../lib/locale";
+import { loadMessages } from "../lib/messages";
+import { IntlClientProvider } from "../components/intl-client-provider";
+
+export async function IntlLayout({
+  ctx,
+  children,
+}: {
+  ctx: any;
+  children: ReactNode;
+}) {
+  const locale = resolveLocale(ctx);
+  const messages = await loadMessages(locale);
+  return (
+    <IntlClientProvider locale={locale} messages={messages}>
+      {children}
+    </IntlClientProvider>
+  );
+}
+```
+
+### Client provider
+
+```tsx
+// components/intl-client-provider.tsx
+"use client";
+
+import { IntlProvider } from "react-intl";
+import type { ReactNode } from "react";
+
+export function IntlClientProvider({
+  locale,
+  messages,
+  children,
+}: {
+  locale: string;
+  messages: Record<string, string>;
+  children: ReactNode;
+}) {
+  return (
+    <IntlProvider
+      locale={locale}
+      defaultLocale="en"
+      messages={messages}
+      onError={(err) => {
+        if (err.code === "MISSING_TRANSLATION") return; // common, log only
+        console.error(err);
+      }}
+    >
+      {children}
+    </IntlProvider>
+  );
+}
+```
+
+### Mounting
+
+Wrap your localized routes with the layout:
+
+```typescript
+import { urls } from "@rangojs/router";
+import { IntlLayout } from "./layouts/intl-layout";
+import { menuRoutes } from "./menu";
+
+export const urlpatterns = urls(({ layout, include }) => [
+  layout(IntlLayout, () => [
+    include("/:locale?", menuRoutes, { name: "menu" }),
+  ]),
+]);
+```
+
+`<FormattedMessage>`, `useIntl()`, etc. work in any client component
+under the layout. Server components can use `formatjs`'s `createIntl()`
+directly with the same `messages` map for static text.
+
+## Common Pitfalls
+
+| Pitfall                                                       | Fix                                                                                    |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `ctx.params.locale === ""` returns `false`                    | Absent optionals are `undefined`, not `""`. Use `=== undefined` or `??`.               |
+| `ctx.params.locale ?? "en"` returns `""`                      | Pre-fix behavior. After the include-prefix fix this works correctly.                   |
+| Bare `/` 404s when mounted via `include("/:locale?", routes)` | Requires the all-optional pattern fix in `compilePattern` (shipped).                   |
+| Unknown locale (e.g. `/de`) matches as `locale: "de"`         | Add a constraint: `:locale(en\|gb\|fr)?`. Unknown values now 404.                      |
+| Reverse produces `//c/breads` for absent locale               | `reverse()` collapses `undefined`/`""` segments — should not happen. File a bug.       |
+| Locale switcher loses search params                           | Read `ctx.url.search` and pass to `reverse(..., undefined, parsedSearch)`.             |
+| Action middleware can't read `ctx.params.locale`              | Route middleware doesn't wrap action execution. Use global `router.use()` for actions. |
+
+## Cross-references
+
+- `/route` — optional URL param syntax and runtime contract
+- `/typesafety` — `RouteParams<"name">` typing for optionals
+- `/middleware` — global vs route middleware scope (matters for actions)
+- `/server-actions` — actions and the global-vs-route middleware boundary
+- `/links` — `ctx.reverse()` and locale-aware URL generation

package/skills/intercept/SKILL.md

@@ -311,3 +311,23 @@ export const shopPatterns = urls(({
   ]),
 ]);
 ```
+
+## Handler-attached `.use`
+
+Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+
+```typescript
+const QuickViewModal: Handler = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <QuickView product={product} />;
+};
+QuickViewModal.use = () => [
+  loader(ProductLoader),
+  loading(<QuickViewSkeleton />),
+  layout(<ModalChrome />),
+];
+
+intercept("@modal", "product", QuickViewModal);
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and the per-mount-site allowed-types table.

package/skills/layout/SKILL.md

@@ -308,3 +308,25 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   ]),
 ]);
 ```
+
+## Handler-attached `.use`
+
+Layout handlers can carry their own middleware, default parallels, and includes via `.use` so a layout becomes a self-contained unit reusable across mount sites.
+
+```typescript
+const AdminLayout: Handler = (ctx) => {
+  const user = ctx.get(CurrentUser);
+  return <Admin user={user} />;
+};
+AdminLayout.use = () => [
+  middleware(requireAdmin),
+  parallel({ "@adminNotifs": AdminNotifsSlot }),
+];
+
+// Mount site declares structure only; defaults travel with the layout.
+layout(AdminLayout, () => [
+  path("/admin", AdminIndex, { name: "admin.index" }),
+]);
+```
+
+Allowed item types in a layout's `.use` mirror the layout `use()` callback (the broadest set). Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and per-mount-site allowed types.

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";
@@ -187,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
 
@@ -139,7 +142,29 @@ same memoized result — loaders never run twice per request.
 
 ## 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) => {
@@ -163,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
@@ -215,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

package/skills/middleware/SKILL.md

@@ -32,6 +32,8 @@ When the router has a `basename`, pattern-scoped `.use()` patterns are automatic
 
 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
@@ -137,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