@rangojs/router 0.16.0 → 0.17.0

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,21 @@ 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.
+
+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

package/skills/i18n/SKILL.md

@@ -32,6 +32,12 @@ import { menuRoutes } from "./menu";
 export const urlpatterns = urls(({ include }) => [
   include("/:locale?", menuRoutes, { name: "menu" }),
 ]);
+
+// menu.tsx
+export const menuRoutes = urls(({ path }) => [
+  path("/", MenuIndex, { name: "index" }),
+  path("/c/:slug", MenuCategory, { name: "category" }),
+]);
 ```
 
 URLs that match:
@@ -59,7 +65,8 @@ URLs that match:
 Absent optionals are `undefined` (not `""`), so `??` coalesces correctly:
 
 ```typescript
-import { Handler } from "@rangojs/router";
+import type { Handler } from "@rangojs/router";
+import { resolveLocale } from "../lib/locale";
 
 export const MenuIndex: Handler<"menu.index"> = (ctx) => {
   // ctx.params.locale is `string | undefined`
@@ -87,9 +94,9 @@ 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";
+export const DEFAULT_LOCALE: Locale = "en";
 
-const isSupported = (v: string): v is Locale =>
+export const isSupported = (v: string): v is Locale =>
   (SUPPORTED_LOCALES as readonly string[]).includes(v);
 
 export function resolveLocale(ctx: {
@@ -104,24 +111,35 @@ export function resolveLocale(ctx: {
   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;
+    if (isSupported(code)) return code;
   }
   return DEFAULT_LOCALE;
 }
 ```
 
+`cookies()` and `headers()` read the current request, so the helper works in
+handlers, layouts, loaders, and middleware without passing the request in.
+
 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:
+that in global middleware (`router.use()`). Global middleware runs before
+route matching, and its `ctx.params` come from its own pattern — not from
+`include("/:locale?")` — so read the locale segment from the pathname:
 
 ```typescript
+// router.tsx
 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}`);
+import { DEFAULT_LOCALE, isSupported, resolveLocale } from "./lib/locale";
+
+router.use(async (ctx, next) => {
+  if (ctx.request.method !== "GET") return next(); // leave actions alone
+  const first = ctx.url.pathname.split("/")[1] ?? "";
+  if (!isSupported(first)) {
+    const resolved = resolveLocale({ params: {} }); // cookie → Accept-Language → default
+    if (resolved !== DEFAULT_LOCALE) {
+      const rest = ctx.url.pathname === "/" ? "" : ctx.url.pathname;
+      return redirect(`/${resolved}${rest}${ctx.url.search}`);
+    }
   }
   await next();
 });
@@ -138,9 +156,16 @@ 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"
+ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads" on an unprefixed request
 ```
 
+`ctx.reverse()` auto-fills missing params from the current request, so the
+last call returns `/en/c/breads` when the current URL is `/en/...`. That is
+what you want for in-locale links; to leave the locale, pass it explicitly
+(`{ locale: "fr" }`, or `undefined`/`""` for the bare default). Middleware and
+response routes are the exception: their `ctx.reverse` fills nothing from the
+request, so pass `locale` there explicitly.
+
 If the active locale is the app default and your URL strategy hides it
 (`"en"` → `/`, others → `/<locale>`), normalize before calling reverse:
 
@@ -177,28 +202,27 @@ export async function loadMessages(locale: Locale) {
 
 ### Server layout: hand off to the client provider
 
+A layout handler receives the handler context (not props) and renders its
+children with `<Outlet />`. It sees the matched route's params, including
+`locale` from the include below it:
+
 ```tsx
-// layouts/intl-layout.tsx (server component)
-import type { ReactNode } from "react";
+// layouts/intl-layout.tsx (server)
+import type { Handler } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
 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;
-}) {
+export const IntlLayout: Handler = async (ctx) => {
   const locale = resolveLocale(ctx);
   const messages = await loadMessages(locale);
   return (
     <IntlClientProvider locale={locale} messages={messages}>
-      {children}
+      <Outlet />
     </IntlClientProvider>
   );
-}
+};
 ```
 
 ### Client provider
@@ -252,20 +276,22 @@ export const urlpatterns = urls(({ layout, include }) => [
 ```
 
 `<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.
+under the layout. Server components and handlers can't use React context
+providers from the client; call `createIntl({ locale, messages })` (from
+`@formatjs/intl` or `react-intl`) directly with the same `messages` map for
+server-rendered 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. |
+| Pitfall                                                       | Fix                                                                                                                |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `ctx.params.locale === ""` returns `false`                    | Absent optionals are `undefined`, not `""`. Use `=== undefined` or `??`.                                           |
+| Unknown locale (e.g. `/de`) matches as `locale: "de"`         | Add a constraint: `:locale(en\|gb\|fr)?`. Unknown values now 404.                                                  |
+| Link meant for the default locale keeps `/en`                 | `ctx.reverse()` auto-fills the current `locale`. Pass `{ locale: undefined }` (or `""`) to drop it.                |
+| Reverse produces `//c/breads` for absent locale               | `reverse()` collapses `undefined`/`""` segments — should not happen. File a bug.                                   |
+| Locale switcher loses search params                           | Append `ctx.url.search` to the reversed URL, or pass `Object.fromEntries(ctx.searchParams)` as the third argument. |
+| Global middleware's `ctx.params.locale` is always `undefined` | Global middleware params come from its own pattern. Parse the first path segment (see "Locale Resolution").        |
+| Route middleware doesn't see actions                          | Route middleware doesn't wrap action execution. Use global `router.use()` for action-time locale logic.            |
 
 ## Cross-references