@rangojs/router 0.16.0 → 0.17.0

package/skills/document-cache/SKILL.md

@@ -6,13 +6,21 @@ argument-hint: [setup]
 
 # Store-backed Document Cache
 
-Caches complete HTTP responses (HTML/RSC) in the app-level cache store based on
-`Cache-Control`. Routes opt in by setting `s-maxage`.
+Caches complete HTTP responses (HTML documents and RSC payloads) in the
+app-level cache store. Routes opt in by sending a `Cache-Control` header with
+`s-maxage`; `stale-while-revalidate` adds a stale window. On a hit, nothing
+below the middleware runs — no route middleware, handlers, or loaders.
+
+Use it for pages whose **whole** response is public and identical for every
+visitor sharing a URL, when you want the reuse to happen inside the app (so
+outer middleware still runs and invalidation stays in Rango's tag system).
 
 This middleware runs **inside** the worker/function. It is not itself a platform
-CDN cache. With `CFCacheStore` the response family can use Cloudflare's edge/KV
-tiers; with `VercelCacheStore` it uses Vercel Runtime Cache. The request still
-reaches Rango before the middleware can return a store hit.
+CDN cache. It works with every built-in store: with `CFCacheStore` the response
+family uses Cloudflare's Cache API (and KV when configured), with
+`VercelCacheStore` it uses Vercel Runtime Cache, and `MemorySegmentCacheStore`
+keeps responses in process memory. The request still reaches Rango before the
+middleware can return a store hit.
 
 ## Not this skill if…
 
@@ -27,9 +35,9 @@ reaches Rango before the middleware can return a store hit.
 ## Setup
 
 Document caching is a middleware. Add `createDocumentCacheMiddleware()` to the
-router with `.use()`. The cache store it reads from is the app-level store you
-configure on `createRouter({ cache })` (available on the request context as
-`requestCtx._cacheStore`), not a store passed to the middleware.
+router with `.use()`. It reads and writes the app-level store you configure on
+`createRouter({ cache })`; the store is not a middleware option. Without an app
+store, the middleware passes every request through.
 
 ```typescript
 import { createRouter } from "@rangojs/router";
@@ -39,7 +47,7 @@ import {
 } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRouter<AppBindings>({
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
   // App-level cache store. The document cache middleware uses this store's
@@ -53,13 +61,14 @@ router.use(
     debug: process.env.NODE_ENV === "development",
   }),
 );
-
-export default router;
 ```
 
+Middleware registered before it runs on every request, hits included; everything
+after it (and all route middleware) runs only on a miss.
+
 ## Route Opt-In with Cache-Control
 
-Routes opt-in to document caching by setting a `Cache-Control` response header
+Routes opt in to document caching by setting a `Cache-Control` response header
 with `s-maxage`. The middleware caches responses whose `Cache-Control` includes
 `s-maxage`; `stale-while-revalidate` enables background revalidation (SWR).
 
@@ -86,6 +95,21 @@ function BlogPostHandler(ctx) {
 // Dashboard sets no Cache-Control header, so it is never document-cached.
 ```
 
+A handler inside a `cache()` boundary or on a `ppr` route cannot write response
+headers (the write throws). Set the header from route middleware instead — it
+runs on every request that reaches the route:
+
+```typescript
+cache({ ttl: 60 }, () => [
+  path("/blog", BlogIndex, { name: "blog" }, () => [
+    middleware(async (ctx, next) => {
+      ctx.header("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+      await next();
+    }),
+  ]),
+]);
+```
+
 ## Document Cache Options
 
 `createDocumentCacheMiddleware(options?)` accepts:
@@ -95,10 +119,11 @@ createDocumentCacheMiddleware({
   // Skip specific paths (matched by pathname prefix)
   skipPaths: ["/api", "/admin"],
 
-  // Custom cache key generator
-  keyGenerator: (url) => url.pathname,
+  // Custom cache key base. Replaces host + pathname + search entirely, so
+  // include the host yourself when one deployment serves several domains.
+  keyGenerator: (url) => `${url.host}${url.pathname}`,
 
-  // Conditional caching, evaluated per request
+  // Conditional caching, evaluated per request (receives the middleware ctx)
   isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
 
   // Debug logging (HIT, MISS, STALE, REVALIDATED)
@@ -150,18 +175,26 @@ header or logs to identify an actual CDN hit.
 
 ## Cache Key Generation
 
-Default keys differentiate:
+The default key is the host, pathname, and sorted search string (internal
+`_rsc*` params removed, `cache.searchParams` filtering applied), followed by
+suffixes that separate response variants:
 
-- HTML requests: `{pathname}:html`
-- RSC partials: `{pathname}:{segmentHash}:rsc`
+- HTML document requests: `{host}{pathname}[?search]:html`
+- RSC requests (client navigations and full-document Flight fetches):
+  `{host}{pathname}[?search]:rsc`
+- Client navigations additionally add a hash of the segments the client already
+  has (`:{segmentHash}`), so navigations from pages with different layouts get
+  different cached payloads, and a `:fragments` marker when the client accepts
+  fragment envelopes.
 
-Segment hash ensures different cached responses for navigations from different source pages (with different layouts).
+A custom `keyGenerator(url)` replaces only the `{host}{pathname}[?search]` part;
+the variant suffixes are still appended.
 
 ## What Gets Cached
 
 - Full HTML responses (document requests)
 - RSC payloads (client navigation)
-- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
+- Only `GET` 200 responses whose `Cache-Control` includes `s-maxage`
 
 ## What's NOT Cached
 
@@ -169,7 +202,35 @@ Segment hash ensures different cached responses for navigations from different s
 - Loader requests (`_rsc_loader`)
 - Non-GET requests
 - Responses without an `s-maxage` `Cache-Control` directive
+- Responses whose `Cache-Control` also contains `private`, `no-store`, or an
+  unqualified `no-cache` (those win over `s-maxage` in a shared cache)
+- Responses carrying `Set-Cookie` (a per-client value must not be replayed to
+  everyone)
 - Non-200 responses
+- A 200 whose render reported an error: a component that threw after the
+  response started streaming, such as an async server component whose fetch
+  failed. The status is already 200, so the body carries the error (an error
+  row in the RSC payload, an errored Suspense boundary in the HTML). The write
+  is skipped and logged as `[DocumentCache] cache write`; the error goes to
+  `onError` as `cache-write` unless the router already reported that same
+  error during the render. The current request still gets the errored render,
+  the next request renders fresh, and on a stale refresh the stale entry keeps
+  serving.
+
+## Invalidation
+
+Entries expire by `s-maxage` (+ `stale-while-revalidate`). They are also tagged
+with the request's tag set, so `updateTag()`/`revalidateTag()` evict them:
+
+- a render-callable `cacheTag("...")` in any server component on the page;
+- tags of `cache()` segments, cached loaders, and `"use cache"` functions the
+  render read.
+
+Tags are snapshotted after the response body has fully streamed, so tags from
+Suspense-streamed content are included. A `Prerender()` route's build-time
+segments contribute no tags (only its live loaders can), so such an entry
+usually expires by TTL only.
+See `/caching` → "Tag-Based Invalidation".
 
 ## Complete Example
 
@@ -179,7 +240,7 @@ import { createRouter } from "@rangojs/router";
 import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRouter<AppBindings>({
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
   cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
@@ -192,7 +253,6 @@ router.use(
   }),
 );
 
-export default router;
 
 // urls.tsx
 import { urls } from "@rangojs/router";
@@ -225,14 +285,18 @@ function BlogPost(ctx) {
 }
 ```
 
+Note that `BlogPostLoader` output is frozen into the cached response along with
+everything else.
+
 ## Document Cache vs Segment Cache
 
-| Feature      | Document Cache             | Segment Cache         |
-| ------------ | -------------------------- | --------------------- |
-| Granularity  | Full response              | Individual segments   |
-| Opt-in       | `Cache-Control` `s-maxage` | `cache({ ttl, swr })` |
-| Use case     | Static pages               | Dynamic compositions  |
-| Key includes | URL + segment hash         | Route params          |
+| Feature      | Document Cache                        | Segment Cache (`cache()`)         |
+| ------------ | ------------------------------------- | --------------------------------- |
+| Granularity  | Full response                         | Individual segments               |
+| Opt-in       | `Cache-Control` `s-maxage`            | `cache({ ttl, swr })`             |
+| Loaders      | Frozen with the response              | Always run fresh                  |
+| Use case     | Static pages                          | Dynamic compositions              |
+| Key includes | host + URL + variant (+ segment hash) | host + pathname + params + search |
 
 Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.
 

package/skills/fonts/SKILL.md

@@ -6,7 +6,10 @@ argument-hint: [provider]
 
 # Fonts
 
-Load web fonts in the Document component with `<link rel="preload">` for optimal performance. Fonts are declared in `<head>` alongside your stylesheet.
+Three ways to load web fonts in a Rango app: a hosted provider (Google Fonts),
+self-hosted files in `public/`, or Fontsource packages bundled by Vite (the
+recommended default). Font links go in the Document `<head>` next to your
+stylesheet, which follows the `?url` + `precedence` pattern from `/css`.
 
 ## Google Fonts
 
@@ -15,7 +18,7 @@ Load web fonts in the Document component with `<link rel="preload">` for optimal
 "use client";
 
 import type { ReactNode } from "react";
-import { MetaTags } from "@rangojs/router/client";
+import { Html } from "@rangojs/router/client";
 import styles from "./index.css?url";
 
 export function Document({ children }: { children: ReactNode }) {
@@ -30,16 +33,17 @@ export function Document({ children }: { children: ReactNode }) {
           crossOrigin="anonymous"
         />
 
-        {/* Load font stylesheet */}
+        {/* Font stylesheet first, so app styles can override it */}
         <link
           href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
           rel="stylesheet"
+          precedence="default"
         />
 
         {/* App styles */}
         <link rel="preload" href={styles} as="style" />
-        <link rel="stylesheet" href={styles} />
-        <MetaTags />
+        <link rel="stylesheet" href={styles} precedence="default" />
+        <Html.Meta />
       </head>
       <body>{children}</body>
     </html>
@@ -60,6 +64,8 @@ Or with Tailwind (see `/tailwind`):
 
 ```css
 /* src/index.css */
+@import "tailwindcss";
+
 @theme {
   --font-sans: "Inter", sans-serif;
 }
@@ -92,7 +98,9 @@ body {
 }
 ```
 
-Preload the most critical weight in the Document:
+Preload the most critical weight in the Document (same imports as the Google
+Fonts example above). Font preloads need `crossOrigin` even for same-origin
+files, or the browser fetches the font twice:
 
 ```tsx
 export function Document({ children }: { children: ReactNode }) {
@@ -107,8 +115,8 @@ export function Document({ children }: { children: ReactNode }) {
           crossOrigin="anonymous"
         />
         <link rel="preload" href={styles} as="style" />
-        <link rel="stylesheet" href={styles} />
-        <MetaTags />
+        <link rel="stylesheet" href={styles} precedence="default" />
+        <Html.Meta />
       </head>
       <body>{children}</body>
     </html>

package/skills/handler-use/SKILL.md

@@ -6,7 +6,7 @@ argument-hint: "[handler]"
 
 # Handler-Attached `.use`
 
-A handler function (or branded `Static`/`Prerender`/`Passthrough` definition) can carry its own defaults via a `.use` callback that returns an array of `use` items (loader, middleware, parallel, intercept, layout, loading, etc.). The mount-site DSL (`path()`, `layout()`, `parallel()`, `intercept()`) merges those defaults with any explicit `use()` callback supplied at the registration site.
+A handler function (or branded `Static`/`Prerender`/`Passthrough` definition) can carry its own defaults via a `.use` callback that returns an array of `use` items (loader, middleware, parallel, intercept, layout, loading, etc.). The mount-site DSL (`path()`, `layout()`, `parallel()`, `intercept()`) merges those defaults with any explicit `use()` callback supplied at the registration site. Loader definitions from `createLoader()` accept a `.use` too, limited to `revalidate` and `cache` (see "Loaders" below).
 
 This lets handlers be **self-contained, reusable units** — a page brings its own loader, a layout brings its own middleware, a parallel slot brings its own data + skeleton — without forcing every caller to wire the same items at every mount site.
 
@@ -51,13 +51,16 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 
 `handler.use()` is the same callback shape regardless of where the handler runs, but the runtime validates that the items it returns are valid for the mount site. Driven by `MOUNT_SITE_ALLOWED_TYPES` in [resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts):
 
-| Mount site                                        | Allowed item types                                                                                                                                                                        |
-| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                            |
-| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                                                                 |
-| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                      |
-| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `transition` (conditional activation is config-only: `intercept(..., { when })`) |
-| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                                                                     |
+| Mount site                                        | Allowed item types                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()`                                          | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                                                                                                                                                                                                                                          |
+| `layout()`                                        | All of the above, plus `route` (nested `path()` items) and `include`                                                                                                                                                                                                                                                                                                                                    |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                                                                                                                                                                                                                                    |
+| `intercept()`                                     | `middleware`, `loader`, `loading`, `layout` (modal chrome, without its own `use()` items), `route`, `transition`. Conditional activation is config-only: `intercept(..., { when })`. Anything else throws with a pointer: `revalidate` goes on the intercept's loader (`loader(Def, () => [revalidate(...)])`), `errorBoundary`/`notFoundBoundary` on the enclosing layout, `cache` on the target route |
+| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                                                                                                                                                                                                                                                                                   |
+| `loader()` (a `createLoader()` definition)        | `revalidate`, `cache`                                                                                                                                                                                                                                                                                                                                                                                   |
+
+`route` is the item type a `path()` call produces.
 
 For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
 
@@ -68,7 +71,13 @@ handler.use() returned middleware() which is not valid inside parallel().
 Allowed types: revalidate, loader, loading, errorBoundary, notFoundBoundary, transition.
 ```
 
-The narrowest contract is `parallel()` — slots cannot bring their own middleware or layout; only data, loading, error/notFound boundaries, revalidation, and transitions.
+The narrowest contract for a handler is `parallel()` — slots cannot bring their own middleware or layout; only data, loading, error/notFound boundaries, revalidation, and transitions.
+
+This runtime check applies to items returned by `handler.use()`. Items in an explicit mount-site `use()` callback are constrained by the TypeScript use-item types (e.g. a `parallel()` callback is typed to parallel items), not by this runtime allow-list. `intercept()` is the exception: it checks its merged items, explicit `use()` and `handler.use()` together, against the same list at runtime (`validateInterceptUseItems`), and a rejected item throws with a pointer instead:
+
+```
+errorBoundary() is not valid inside intercept("@modal", "product") use() (including the handler's .use): put it on the enclosing layout or path; it handles the intercept's handler and loader errors.
+```
 
 ## Composition with explicit `use()`
 
@@ -281,7 +290,7 @@ AdminLayout.use = () => [
 
 ### Intercepts (`intercept()`)
 
-Intercept handlers can carry their own middleware chain, loaders, and even nested layouts/routes for the modal shell.
+Intercept handlers can carry their own middleware chain, loaders, `loading()`, and the modal chrome: a `layout(Chrome)` with no `use()` items of its own. Boundaries, `cache()` and `revalidate()` throw here (see the table above and [intercept](../intercept/SKILL.md)).
 
 ```typescript
 const QuickViewModal: Handler = async (ctx) => {
@@ -295,6 +304,30 @@ QuickViewModal.use = () => [
 ];
 ```
 
+### Loaders (`loader()`)
+
+A loader definition can carry its own cache and revalidation defaults. They are
+merged into every `loader(Def)` registration, before the explicit
+`loader(Def, () => [...])` items:
+
+```typescript
+import { cache, createLoader, revalidate } from "@rangojs/router";
+import * as CatalogActions from "./actions/catalog";
+
+export const CategoriesLoader = createLoader(async () => fetchCategories());
+CategoriesLoader.use = () => [
+  cache({ ttl: 300 }),
+  // Loaders re-run after every action by default. Re-run this one only for
+  // catalog actions; on navigation, undefined keeps the default.
+  revalidate((ctx) =>
+    ctx.isAction() ? ctx.isAction(CatalogActions) : undefined,
+  ),
+];
+
+// Mount sites get the cache + revalidation defaults with no extra wiring.
+layout(<ShopLayout />, () => [loader(CategoriesLoader) /* … */]);
+```
+
 ## `loading()` is a single-assignment item — scope it correctly
 
 Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loading`](../../src/route-definition/dsl-helpers.ts)).
@@ -310,7 +343,7 @@ Cart.use = () => [loader(CartLoader), loading(<CartSkeleton />)];
 const Notifs: Handler = async (ctx) => { /* … */ };
 Notifs.use = () => [loader(NotifsLoader), loading(<NotifsSkeleton />)];
 
-// ✅ @cart gets a custom skeleton; @notifs keeps its handler.use default.
+// @cart gets a custom skeleton; @notifs keeps its handler.use default.
 parallel({
   "@cart": {
     handler: Cart,
@@ -319,7 +352,7 @@ parallel({
   "@notifs": Notifs,
 });
 
-// ✅ Opt one slot out of streaming while siblings still stream the broadcast.
+// Opt one slot out of streaming while siblings still stream the broadcast.
 parallel(
   {
     "@cart": { handler: Cart, use: () => [loading(false)] },
@@ -333,7 +366,7 @@ Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-
 
 Other things to keep in mind about `loading()`:
 
-- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading: false` handling in [match-middleware/segment-resolution.ts](../../src/router/match-middleware/segment-resolution.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
+- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading === false` handling in [segment-resolution/fresh.ts](../../src/router/segment-resolution/fresh.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
 
 Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every mount site to stream by default. Use the slot descriptor's `use` for any per-slot intent at a `parallel()` call.
 
@@ -343,10 +376,13 @@ Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every
 - **Branded handlers** — `Static()`, `Prerender()`, and `Passthrough()` are positional constructors (not object-arg). Construct first, then attach `.use` to the returned definition:
 
   ```typescript
-  const ProductPage = Prerender(async (ctx) => {
-    const product = await fetchProduct(ctx.params.slug);
-    return <ProductView product={product} />;
-  });
+  const ProductPage = Prerender(
+    async () => [{ slug: "shoes" }, { slug: "jacket" }], // getParams
+    async (ctx) => {
+      const product = await fetchProduct(ctx.params.slug);
+      return <ProductView product={product} />;
+    },
+  );
   ProductPage.use = () => [loader(ProductLoader)];
   ```
 

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

@@ -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.