@rangojs/router 0.15.1 → 0.17.0

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

@@ -40,12 +40,16 @@ 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 +62,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 +84,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,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