@rangojs/router 0.16.0 → 0.18.0

package/skills/hooks/SKILL.md

@@ -6,8 +6,14 @@ argument-hint: [hook-name]
 
 # Client-Side React Hooks
 
+The client-side API for reading router state in client components: navigation
+state and actions, URL and params, loader data, handles, action status,
+location state, outlets, and client-cache invalidation.
+
 Import the hooks and components in this skill from `@rangojs/router/client`.
-The root `@rangojs/router` entrypoint is for server/RSC APIs and shared types.
+The root `@rangojs/router` entrypoint is for server/RSC APIs and shared types;
+the exceptions used here are `invalidateClientCache()` (root only) and
+`createLocationState()` (exported from both).
 
 ## Not this skill if…
 
@@ -16,6 +22,8 @@ The root `@rangojs/router` entrypoint is for server/RSC APIs and shared types.
   resolved.
 - You want to control when a loader re-runs after an action — that is
   `revalidate()` in the server DSL: see `/loader`.
+- You want an action to leave the client cache alone — that is
+  `keepClientCache()` inside the action: see `/server-actions`.
 
 Each hook's full API and recipe lives in a companion file linked below. Read
 the one for your case.
@@ -65,22 +73,22 @@ the one for your case.
 
 ## Hook Summary
 
-| Hook                      | Purpose                                                        | Returns                                                            |
-| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string>`) or selected value |
-| `usePathname()`           | Current pathname                                               | `string`                                                           |
-| `useSearchParams()`       | URL search params (read + write)                               | `[ReadonlyURLSearchParams, SetSearchParams]` (RR-style tuple)      |
-| `useHref()`               | Mount-aware href                                               | `(path) => string`                                                 |
-| `useMount()`              | Current include() mount path                                   | `string`                                                           |
-| `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                               |
-| `useNavigation()`         | Reactive navigation state                                      | state, location, isStreaming                                       |
-| `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                    |
-| `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                         |
-| `useLinkStatus()`         | Link pending state                                             | { pending }                                                        |
-| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error, load, refetch                              |
-| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading, error, refetch                              |
-| `useRefreshLoaders()`     | Refresh cross-loader group(s)                                  | `() => (groups: string \| string[]) => Promise<void>`              |
-| `useHandle()`             | Accumulated handle data                                        | T (handle type)                                                    |
-| `useAction()`             | Server action state                                            | state, error, result                                               |
-| `useLocationState()`      | History state (persists or flash)                              | T \| undefined                                                     |
-| `invalidateClientCache()` | Force client caches to miss (function, not a hook; root entry) | `void`                                                             |
+| Hook                      | Purpose                                                        | Returns                                                                         |
+| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string \| undefined>`) or selected value |
+| `usePathname()`           | Current pathname                                               | `string`                                                                        |
+| `useSearchParams()`       | URL search params (read + write)                               | `[ReadonlyURLSearchParams, SetSearchParams]` (RR-style tuple)                   |
+| `useHref()`               | Mount-aware href                                               | `(path) => string`                                                              |
+| `useMount()`              | Current include() mount path                                   | `string`                                                                        |
+| `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                                            |
+| `useNavigation()`         | Reactive navigation state                                      | state, location, pendingUrl, isStreaming                                        |
+| `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                                 |
+| `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                                      |
+| `useLinkStatus()`         | Link pending state                                             | { pending }                                                                     |
+| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error, load, refetch                                           |
+| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading, error, refetch                                           |
+| `useRefreshLoaders()`     | Refresh cross-loader group(s)                                  | `() => (groups: string \| string[]) => Promise<void>`                           |
+| `useHandle()`             | Accumulated handle data                                        | T (handle type)                                                                 |
+| `useAction()`             | Server action state                                            | state, actionId, payload, error, result                                         |
+| `useLocationState()`      | History state (persists or flash)                              | T \| undefined                                                                  |
+| `invalidateClientCache()` | Force client caches to miss (function, not a hook; root entry) | `void`                                                                          |

package/skills/hooks/data.md

@@ -36,9 +36,15 @@ same-route nav, a same-structure search/filter nav), the reader that is still
 showing the OLD data reports `isLoading: true` from
 the moment the new tree is committed until the new data lands — render your
 stale indicator from it. The flag never flashes back to `false` on the old
-data: it flips in the same commit that swaps `data`. Only loaders the
-navigation actually re-runs are flagged: a layout loader the server does not
-re-execute keeps its data and stays `isLoading: false`. It never applies to a
+data: it flips in the same commit that swaps `data`. The pin is per loader
+family (`loader.$$id`), not per segment: a navigation that re-runs
+`CartLoader` flags every `useLoader(CartLoader)`, including a persisting
+layout reader whose own copy is not replaced. That is "this loader is in
+flight," not "this segment's copy is being replaced." A _different_ layout
+loader the server does not re-execute stays `isLoading: false`. A child can
+already read a layout registration via the context walk; a second
+`loader(Same)` on the child is a second run of the same family, not a
+separate loading flag. It never applies to a
 navigation that remounts the route (that reader is gone; the skeleton shows),
 to a fully-prefetched nav (its data is already settled when it commits, so
 nothing is pending to flag), or to an ephemeral `useFetchLoader` read outside
@@ -51,8 +57,19 @@ function ProductPrice() {
 }
 ```
 
+Unit-test the indicator with `renderRoute` (`/testing`, client-components.md
+"Held navigation"): a `transition` spec plus a pending seed in
+`router.navigate(url, { loaders })`.
+
 **Precondition**: Loader must be registered on route via `loader()` helper.
 
+**`load()` / `refetch` need a fetchable loader.** `load()`, `refetch`, and
+`useRefreshLoaders()` call the loader through the `_rsc_loader` endpoint, which
+only serves loaders created with `createLoader(fn, true)` or
+`createLoader(fn, { middleware })`. A plain `createLoader(fn)` answers 403 there;
+it re-runs only as part of a render (navigation, `router.refresh()`, or the
+revalidation after a server action). See `/loader` → "Fetchable Loaders".
+
 Loaders can also be passed as props from server to client components:
 
 ```tsx
@@ -108,6 +125,7 @@ reading the same loader id. Layout, page, and parallel-slot reads
 all converge on the new value:
 
 ```tsx
+// CartLoader = createLoader(fn, true), registered with loader(CartLoader).
 // Layout button calls load() — the page read below sees the update too.
 function Layout() {
   const { data, load } = useLoader(CartLoader);
@@ -262,9 +280,11 @@ server, JSON bodies are available via `ctx.body` and FormData bodies via `ctx.fo
 
 ```tsx
 "use client";
+import { useRef } from "react";
 import { useFetchLoader } from "@rangojs/router/client";
 import { FileUploadLoader } from "../loaders/upload";
 
+// Needs JavaScript: the form action is a client function, not a server action.
 function FileUploader() {
   const { data, load, isLoading } = useFetchLoader(FileUploadLoader);
   const formRef = useRef<HTMLFormElement>(null);

package/skills/hooks/handle-and-actions.md

@@ -34,18 +34,24 @@ Writers: handlers AND loader bodies — `ctx.use(Handle)` returns the push
 function in each (middleware has no handle APIs). Loader pushes follow a delivery race (settle before
 the handler barrier → in the SSR'd document; later → applied client-side), and
 `loader(Def, { ssr: false })` makes them deterministic in the
-document. See `/loader` → "Writing Handles from Loaders". `useHandle`
+document. On a `ppr` shell HIT, a loader without `ssr: false` never ran during
+the capture, so its pushes always apply client-side; with `ssr: false` they
+bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.
 
 Handles can be passed as props from server to client components:
 
 ```tsx
-// Server component
-path("/dashboard", (ctx) => {
-  const push = ctx.use(Breadcrumbs);
-  push({ label: "Dashboard", href: "/dashboard" });
-  return <DashboardNav handle={Breadcrumbs} />;
-});
+// Server component (route handler)
+path(
+  "/dashboard",
+  (ctx) => {
+    const push = ctx.use(Breadcrumbs);
+    push({ label: "Dashboard", href: "/dashboard" });
+    return <DashboardNav handle={Breadcrumbs} />;
+  },
+  { name: "dashboard" },
+);
 ```
 
 ```tsx
@@ -58,7 +64,9 @@ function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
   return (
     <nav>
       {crumbs.map((c) => (
-        <a href={c.href}>{c.label}</a>
+        <a key={c.href} href={c.href}>
+          {c.label}
+        </a>
       ))}
     </nav>
   );
@@ -78,33 +86,42 @@ tracking actions called outside a `<form action={...}>` flow.
 
 ### useAction()
 
-Track state of server action invocations:
+Track the lifecycle of a server action, wherever on the page it was invoked.
+If the same action fires several times, the hook reports the latest call.
 
 ```tsx
 "use client";
 import { useAction } from "@rangojs/router/client";
-import { addToCart } from "../actions/cart";
+import { addToCart } from "../actions/cart"; // addToCart(productId: string)
 
 function AddToCartButton({ productId }: { productId: string }) {
   const { state, error, result } = useAction(addToCart);
 
   // state: 'idle' | 'loading' | 'streaming'
   // actionId: string | null
-  // payload: unknown | null (input data)
-  // error: Error | null
+  // payload: unknown[] | FormData | null (the call's arguments)
+  // error: unknown | null (whatever the action threw)
   // result: unknown | null (return value)
 
   return (
-    <form action={addToCart}>
-      <input type="hidden" name="productId" value={productId} />
+    // .bind keeps the form progressively enhanced; useAction still matches it
+    <form action={addToCart.bind(null, productId)}>
       <button disabled={state === "loading"}>
         {state === "loading" ? "Adding..." : "Add to Cart"}
       </button>
-      {error && <p className="error">{error.message}</p>}
+      {error instanceof Error && <p className="error">{error.message}</p>}
     </form>
   );
 }
 
-// Match by string suffix (convenient but may be ambiguous)
-const isLoading = useAction("addToCart", (s) => s.state === "loading");
+// With a selector (re-renders only when the selected value changes)
+const isLoading = useAction(addToCart, (s) => s.state === "loading");
+
+// Match by export name (suffix match on "#addToCart"; ambiguous if two
+// "use server" files export the same name)
+const isAdding = useAction("addToCart", (s) => s.state === "loading");
 ```
+
+Pass an action imported directly into the client component, or its export
+name as a string. An action received as a prop from a server component has
+lost the metadata `useAction` needs and throws; use the string form there.

package/skills/hooks/navigation.md

@@ -13,7 +13,7 @@ function NavIndicator() {
 
   // State properties
   nav.state; // 'idle' | 'loading'
-  nav.isStreaming; // boolean
+  nav.isStreaming; // boolean — RSC data is still streaming
   nav.location; // Current URL
   nav.pendingUrl; // Target URL during navigation (or null)
 
@@ -29,7 +29,9 @@ function IsLoading() {
 
 ### useRouter()
 
-Access stable router actions (never causes re-renders):
+Access stable router actions. The returned object never changes identity, so
+components using it do not re-render on navigation. Call its methods from
+event handlers or effects:
 
 ```tsx
 "use client";
@@ -38,15 +40,41 @@ import { useRouter } from "@rangojs/router/client";
 function NavigationControls() {
   const router = useRouter();
 
-  router.push("/products"); // Navigate (adds history entry)
-  router.replace("/login"); // Navigate (replaces history entry)
-  router.refresh(); // Re-fetch current route data
-  router.prefetch("/dashboard"); // Prefetch for faster navigation
-  router.back(); // Go back in history
-  router.forward(); // Go forward in history
+  return (
+    <>
+      <button onClick={() => router.push("/products")}>Products</button>
+      <button onClick={() => router.replace("/login", { scroll: false })}>
+        Log in
+      </button>
+      <button onClick={() => router.refresh()}>Reload data</button>
+      <button onMouseEnter={() => router.prefetch("/dashboard")}>
+        Dashboard
+      </button>
+      <button onClick={() => router.back()}>Back</button>
+      <button onClick={() => router.forward()}>Forward</button>
+    </>
+  );
 }
 ```
 
+| Method                   | Behaviour                                                                                                       |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `push(url, options?)`    | Navigate and add a history entry. Returns a promise.                                                            |
+| `replace(url, options?)` | Navigate and replace the current history entry. Returns a promise.                                              |
+| `refresh()`              | Re-fetch the current route's server data, keeping client state. Returns a promise.                              |
+| `prefetch(url, opts?)`   | Prefetch a target. `{ key: ":source" }` scopes the entry to the source page (parity with `<Link prefetchKey>`). |
+| `back()`                 | `history.back()`; on the first entry of the session it replaces to the app root instead of leaving the app.     |
+| `forward()`              | `history.forward()`.                                                                                            |
+
+`push` / `replace` options: `scroll` (`false` keeps the current scroll
+position), `revalidate` (default `true`, see below), and `state` (location
+state, see [`./state.md`](./state.md)).
+
+Target resolution: a path starting with `/` is app-absolute and gets the
+router `basename` prefixed. A relative path (`"cart"`, `"./cart"`) resolves
+against the current `include()` mount, so `router.push("cart")` inside
+`include("/shop", ...)` navigates to `/shop/cart`.
+
 #### Skipping revalidation
 
 Pass `revalidate: false` to skip the RSC server fetch for same-pathname navigations (search param or hash changes). The URL updates and all hooks re-render, but server components stay as-is.
@@ -79,7 +107,7 @@ function Breadcrumbs() {
   const { path, segmentIds, location } = useSegments();
 
   // path: ["shop", "products", "123"] (split on "/", no leading slash on any element)
-  // segmentIds: ["L0", "L0L1", "L0L1R0"] (opaque internal short-codes, not route names)
+  // segmentIds: ["L0", "L0L1", "L0L1R0"] (layouts and routes only; opaque internal short-codes, not route names)
   // location: URL object
 
   return <nav>{path.join(" > ")}</nav>;
@@ -91,7 +119,8 @@ const isShopRoute = useSegments((s) => s.path[0] === "shop");
 
 ### useLinkStatus()
 
-Track pending state inside a Link component:
+Track pending state inside a Link component. `pending` is `true` while a
+navigation to this link's `to` is in flight:
 
 ```tsx
 "use client";

package/skills/hooks/outlets.md

@@ -2,24 +2,32 @@
 
 ### Outlet / ParallelOutlet
 
-Render child content in layouts:
+Render child content in layouts. `<Outlet />` renders the matched child
+segment; `<ParallelOutlet name="@slot" />` renders a named `parallel()` slot.
+Both apply the segment's `loading()` fallback as a Suspense boundary:
 
 ```tsx
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
 
-function DashboardLayout({ children }: { children?: React.ReactNode }) {
+function DashboardLayout() {
   return (
     <div className="dashboard">
       <aside>
         <ParallelOutlet name="@sidebar" />
       </aside>
-      <main>{children ?? <Outlet />}</main>
+      <main>
+        <Outlet />
+      </main>
       <ParallelOutlet name="@notifications" />
     </div>
   );
 }
 ```
 
+`<Outlet name="@sidebar" />` is equivalent to `<ParallelOutlet name="@sidebar" />`;
+`ParallelOutlet` requires the name and reads clearer at the call site. See
+`/layout` and `/parallel` for the server side.
+
 ### useOutlet()
 
 Access outlet content and its client-route presentation state programmatically:
@@ -48,9 +56,8 @@ function ConditionalLayout() {
 }
 ```
 
-Migration from the old bare-node return is `const { content, pending } =
-useOutlet()`, then render `content` where you previously rendered the hook result.
-`<Outlet />` itself is unchanged.
+Migrating from the older API where `useOutlet()` returned the node directly:
+destructure `content` and render it where you rendered the hook result.
 
 `pending` is narrow. After hydration, a `clientUrls()` layout receives `true`
 while a browser-local match to a different client route beneath it is presenting

package/skills/hooks/state.md

@@ -74,6 +74,16 @@ Plain state can also be evaluated just in time (also requires a client component
 </Link>
 ```
 
+Read plain (untyped) state by calling the hook with a type argument and no
+definition:
+
+```tsx
+const state = useLocationState<{ from?: string }>(); // { from?: string } | undefined
+```
+
+The same `state` option exists on `router.push()` / `router.replace()` (see
+[`./navigation.md`](./navigation.md)).
+
 ### Flash State (read-once)
 
 Create a location state with `{ flash: true }` for read-once state that
@@ -106,22 +116,22 @@ function FlashBanner() {
 ```
 
 Flash behavior is determined by the definition (`{ flash: true }`), not by which
-hook reads it. `useLocationState` reads the value synchronously during render,
-then clears it from `history.state` via `replaceState` in a `useEffect`.
-Multiple components reading the same flash definition all see the value.
-Pressing back/forward will not re-show the flash since it was cleared.
+hook reads it. `useLocationState` reads the value during render (on the
+hydration render it returns `undefined` and reads in a post-mount effect, so
+SSR and hydration agree), then clears it from `history.state` via
+`replaceState` in a `useEffect`. Multiple components reading the same flash
+definition all see the value. Pressing back/forward will not re-show the flash
+since it was cleared.
 
-Set flash state from the server via `redirect()` with state:
+Set flash state from the server via `redirect()` with state (from a handler,
+middleware, or server action). Import the definition from the shared module so
+the client reader uses the same one:
 
 ```tsx
 // In a route handler
-import { redirect, createLocationState } from "@rangojs/router";
-
-export const FlashMessage = createLocationState<{ text: string }>({
-  flash: true,
-});
+import { redirect } from "@rangojs/router";
+import { FlashMessage } from "../location-states";
 
-// Handler
 (ctx) => {
   return redirect("/dashboard", {
     state: [FlashMessage({ text: "Item saved!" })],
@@ -129,7 +139,7 @@ export const FlashMessage = createLocationState<{ text: string }>({
 };
 ```
 
-Or via `ctx.setLocationState()` on any response:
+Or via `ctx.setLocationState()` on any response (handlers and middleware):
 
 ```tsx
 (ctx) => {
@@ -194,9 +204,23 @@ ProductState.delete();
 Force the client's caches to miss after a mutation the router can't see (a REST
 call, a WebSocket push, a login). It is a plain function, not a hook, so it works
 from module-level callbacks too. Imported from the root entry `@rangojs/router`,
-it is selected by export conditions: in a client component it marks the caches
-stale immediately; from a handler/server component it writes a rotated
-`Set-Cookie` for the responding client.
+it is selected by export conditions:
+
+- **Client** (client component or module): marks the history cache stale,
+  flushes the prefetch cache, rotates the router state, and notifies other tabs
+  — the same thing a completed server action does. During SSR of a client
+  component it is a no-op (dev warning).
+- **Server** (handler, server component, middleware, loader, or action): writes
+  a rotated state `Set-Cookie` for the responding client, which marks its
+  caches stale when it next reads them. Idempotent within a request; throws
+  inside a `cache()` / `"use cache"` boundary; a no-op with a dev warning
+  outside a request. On a `ppr` route a shell HIT runs no handler, so a call
+  from handler code writes the cookie only on the renders that run it (a
+  MISS); call it from middleware, which runs on every request, HITs included.
+
+Server actions already invalidate automatically; to suppress that for a no-op
+action, call `keepClientCache()` inside it (see `/server-actions` → "Client
+Cache After an Action").
 
 ```tsx
 "use client";

package/skills/hooks/urls.md

@@ -29,7 +29,7 @@ function ProductId() {
 }
 ```
 
-Returns merged params from all matched route segments as a `Readonly<T>` map. Updates on navigation commit (not during pending navigation).
+Returns merged params from all matched route segments as a `Readonly<T>` map (default `Record<string, string | undefined>` — absent optional params are omitted, so guard them). Updates on navigation commit, not during a pending navigation — except inside an optimistically rendered `clientUrls()` destination, where it reports that destination's params (see `/client-urls`).
 
 ### usePathname()
 
@@ -119,19 +119,21 @@ import { useHref, href, Link } from "@rangojs/router/client";
 
 // Inside include("/shop", shopPatterns)
 function ShopNav() {
-  const href = useHref();
+  const localHref = useHref();
 
   return (
     <>
       {/* Local paths - auto-prefixed with /shop */}
-      <Link to={href("/cart")}>Cart</Link>
-      <Link to={href("/product/widget")}>Widget</Link>
+      <Link to={localHref("/cart")}>Cart</Link>
+      <Link to={localHref("/product/widget")}>Widget</Link>
+      {/* Absolute path - not prefixed */}
+      <Link to={href("/about")}>About</Link>
     </>
   );
 }
 ```
 
-Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths.
+Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths. The function `useHref()` returns is referentially stable within a mount, so it is safe as a hook dependency or memoized prop.
 
 ### useMount()
 

package/skills/host-router/SKILL.md

@@ -8,6 +8,12 @@ argument-hint:
 
 Route requests to different apps based on domain, subdomain, or path prefix patterns. Supports middleware, lazy loading, cookie-based host override for dev, and a fallback handler.
 
+Use it when one deployment serves several independently built Rango apps (or
+plain request handlers) and the hostname or a path prefix decides which one
+handles the request. Each sub-app is an ordinary `createRouter()` app; the host
+router only picks which one runs. For a single app mounted under a sub-path,
+use `basename` instead (`/router-setup`).
+
 ## Import
 
 ```typescript
@@ -64,6 +70,10 @@ import { router } from "./router.js";
 export default (request: Request, input: any) => router.fetch(request, input);
 ```
 
+Each sub-app has its own generated route map and `Rango.Env`; typecheck each
+in its own TypeScript program (or give route names per-app prefixes) so the
+global augmentations don't collide — see `/typesafety` (multi-project setup).
+
 Selecting the host entry — a host app has several `createRouter()` sub-apps, so single-router auto-discovery can't pick one. Either let rango auto-detect the lone `createHostRouter()` file, or point at it explicitly:
 
 ```typescript
@@ -71,7 +81,7 @@ Selecting the host entry — a host app has several `createRouter()` sub-apps, s
 rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
 ```
 
-On Vercel this is a single function running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model); `{ env, ctx }` (`process.env` + `{ waitUntil }`) is threaded unchanged to each matched sub-app's handler and `cache(env, ctx)` factory. See the `vercel` skill.
+On Vercel this is a single function running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model); `{ env, ctx }` (`process.env` + `{ waitUntil }`) is threaded unchanged to each matched sub-app's handler and `cache(env, ctx)` factory. See `/vercel`.
 
 Unmatched hosts on node/vercel: because rango owns the generated entry (you have no worker `try/catch`), it catches `NoRouteMatchError` and returns **404** by default — so you do **not** need a catch-all host route. If you want different behavior (a branded 404, a redirect, a default app), register a catch-all mount as the **last** route, e.g. `host(["**"]).lazy(() => import("./apps/site/handler.js"))` — it matches any host, so the built-in 404 only fires when nothing matched at all. (Note `fallback()` is for cookie-override errors, not general unmatched hosts.)
 
@@ -120,6 +130,18 @@ Why two methods instead of one overloaded `.map()`:
 
 Patterns are tested in registration order. First match wins.
 
+Matching details:
+
+- **Apex means exactly two labels.** There is no Public Suffix List:
+  `example.co.uk` has three labels, so `.`/`*` do not match it and `*.` does.
+  `localhost` has one label, so it matches neither `.` nor `*.`; use an exact
+  `localhost` pattern (or `**`) for local dev.
+- **Hosts are case-insensitive; paths are not.** A path prefix matches the
+  exact path or anything below it (`example.com/api` matches `"/api"` and
+  `"/api/x"`, not `"/apix"`). A trailing `/` on the pattern is ignored.
+- A pattern that is empty, not a string, or contains whitespace throws
+  `InvalidPatternError` at registration.
+
 ## `defineHosts` for Type Safety
 
 ```typescript
@@ -142,6 +164,8 @@ Returns a frozen object — keys are autocompleted by TypeScript.
 Global middleware runs for every matched route. Per-route middleware runs only for that host pattern.
 
 ```typescript
+import { createHostRouter, type Middleware } from "@rangojs/router/host";
+
 const router = createHostRouter();
 
 // Global — runs for all routes
@@ -150,7 +174,14 @@ router.use(async (request, input, next) => {
   return next();
 });
 
-// Per-route
+// Per-route: return a Response without calling next() to short-circuit
+const requireAuth: Middleware = async (request, input, next) => {
+  if (!request.headers.get("authorization")) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+  return next();
+};
+
 router
   .host(["admin.*"])
   .use(requireAuth)
@@ -159,23 +190,37 @@ router
 
 Middleware signature: `(request: Request, input: RouterRequestInput, next: () => Promise<Response>) => Promise<Response>`
 
+Global middleware runs first, then the matched route's middleware, then the
+handler. `input` is typed `RouterRequestInput<any>` on purpose: one host router
+fans out to sub-apps with different env shapes, so `input.env`/`input.vars` are
+`any` here and each sub-app types its own env via `createRouter<TEnv>()`.
+
 Calling `next()` more than once throws.
 
 ## Fallback Handler
 
-Handles cookie-override errors when `hostOverride` is configured (e.g., override from a disallowed host, invalid cookie hostname). The fallback does **not** catch unmatched hosts — those throw `NoRouteMatchError`. Catch that at the worker level if you need a 404.
+Handles cookie-override errors when `hostOverride` is configured (e.g., override from a disallowed host, invalid cookie hostname, a throwing `validate`). The fallback does **not** catch unmatched hosts — those throw `NoRouteMatchError`. Catch that at the worker level if you need a 404.
 
 ```typescript
 const router = createHostRouter({
   hostOverride: { cookieName: "x-dev-host", allowedHosts: ["localhost"] },
 });
 
-// Called when cookie override fails (not for general unmatched hosts)
-router.fallback().map((request) => {
-  return new Response("Invalid host override", { status: 400 });
+// Called when cookie override fails (not for general unmatched hosts).
+// Global middleware and the fallback's own middleware still run.
+router.fallback().map((request, input) => {
+  // The override error is passed on the input (not part of RouterRequestInput's type)
+  const { error } = input as { error?: Error };
+  return new Response(`Invalid host override: ${error?.message}`, {
+    status: 400,
+  });
 });
 ```
 
+Without a registered fallback, a failed override returns a `400` JSON
+response (`{ error, message }`) that also clears the override cookie
+(`Set-Cookie: <cookieName>=; Max-Age=0`).
+
 For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch. Use the `isNoRouteMatchError()` guard rather than a bare `instanceof`: a workspace with a duplicated `@rangojs/router` copy can throw the error with a different class identity, and `instanceof` would then turn the 404 into an opaque 500.
 
 ```typescript
@@ -215,10 +260,14 @@ const router = createHostRouter({
 When a request arrives:
 
 1. If no cookie → use actual hostname
-2. If cookie present and host is in `allowedHosts` → use cookie value as hostname
-3. If cookie present but host not allowed → throw `HostOverrideNotAllowedError`
+2. If cookie present and the actual host matches an `allowedHosts` pattern → use the cookie value as the hostname (after `validate`, when given)
+3. If cookie present but the host is not allowed → `HostOverrideNotAllowedError`, handled by the fallback (see above)
 
-Without a custom `validate`, the cookie value is validated as a hostname via `new URL()`.
+Without a custom `validate`, the cookie value must parse as a bare hostname via
+`new URL()` (no port or path) and is lowercased; otherwise
+`InvalidHostnameError`. A custom `validate` returns the effective hostname; if
+it throws, the error is wrapped in `HostValidationError`. The effective
+hostname is then matched against the host patterns as usual.
 
 ## Debug Mode
 
@@ -251,12 +300,15 @@ matchesHost(
   new Request("https://foo.workers.dev/admin"),
 ); // true
 
-// Create requests for integration tests
+// Create requests for integration tests (method defaults to GET, path to "/")
 const request = createTestRequest({
   host: "admin.example.com",
   path: "/dashboard",
+  method: "POST",
+  headers: { authorization: "Bearer test" },
   cookies: { "x-dev-host": "api.example.com" },
 });
+const response = await router.match(request);
 
 // Test which route would match (without executing)
 router.test("admin.example.com"); // { pattern, handler, kind } | null
@@ -309,8 +361,8 @@ document navigation**, not a soft in-tree swap. When the server sees a partial
 Why a reload rather than a soft swap: a soft swap can't faithfully re-establish
 the target app's **document-level** state. Stylesheets shared across apps are
 dropped by React 19's by-`href` resource dedup; and theme, warmup, and
-prefetch-TTL are document-lifetime (captured once at load — see
-`browser/app-shell.ts`), so the target app's config would never take effect. A
+prefetch-TTL are document-lifetime (captured once at document load), so the
+target app's config would never take effect. A
 full document load re-establishes the target app's entire document — CSS, theme,
 meta, everything — by construction. So you do **not** need to coordinate
 stylesheet `href`s, `precedence`, theme config, etc. across independently-authored