@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

package/skills/document-cache/SKILL.md

@@ -10,73 +10,82 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 
 ## Setup
 
-Configure document cache in router:
+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.
 
 ```typescript
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import {
+  createDocumentCacheMiddleware,
+  CFCacheStore,
+} from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (_env, ctx) => ({
-    store: new CFCacheStore({ ctx: ctx! }),
+  // App-level cache store. The document cache middleware uses this store's
+  // getResponse/putResponse methods.
+  cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api", "/admin"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 
 export default router;
 ```
 
-## Route Opt-In with cache()
+## Route Opt-In with Cache-Control
 
-Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
+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).
 
 ```typescript
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, cache }) => [
-  // Cache full page for 5 min, serve stale for 1 hour
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    path("/blog", BlogIndex, { name: "blog" }),
-  ]),
-
-  // Long cache for individual posts
-  cache({ documentCache: { sMaxAge: 3600, swr: 86400 } }, () => [
-    path("/blog/:slug", BlogPost, { name: "blogPost" }),
-  ]),
-
-  // No cache for dashboard (no documentCache option)
-  path("/dashboard", Dashboard, { name: "dashboard" }),
-]);
+// Cache full page for 5 min, serve stale for 1 hour
+function BlogIndexHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndex />;
+}
+
+// Long cache for individual posts
+function BlogPostHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
+  return <BlogPost />;
+}
+
+// Dashboard sets no Cache-Control header, so it is never document-cached.
 ```
 
 ## Document Cache Options
 
-```typescript
-createRouter({
-  // ...
-  documentCache: (_env, ctx) => ({
-    // Cache store (required)
-    store: new CFCacheStore({ ctx: ctx! }),
+`createDocumentCacheMiddleware(options?)` accepts:
 
-    // Skip specific paths
-    skipPaths: ["/api", "/admin"],
+```typescript
+createDocumentCacheMiddleware({
+  // Skip specific paths (matched by pathname prefix)
+  skipPaths: ["/api", "/admin"],
 
-    // Custom cache key
-    keyGenerator: (url) => url.pathname,
+  // Custom cache key generator
+  keyGenerator: (url) => url.pathname,
 
-    // Conditional caching
-    isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+  // Conditional caching, evaluated per request
+  isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
 
-    // Debug logging
-    debug: true,
-  }),
+  // Debug logging (HIT, MISS, STALE, REVALIDATED)
+  debug: true,
 });
 ```
 
+The cache store is not a middleware option — it comes from the app-level
+`createRouter({ cache })` store.
+
 ## How It Works
 
 ```
@@ -89,7 +98,7 @@ Request → Check Cache
     ↓             ↓
   Fresh?      Run handler
     │             │
-   Yes → Return   Has documentCache?
+   Yes → Return   Has s-maxage?
     │             │
    No (stale)    Yes → Cache + Return
     │             │
@@ -120,13 +129,14 @@ Segment hash ensures different cached responses for navigations from different s
 
 - Full HTML responses (document requests)
 - RSC payloads (client navigation)
-- Only 200 OK responses with documentCache enabled
+- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
 
 ## What's NOT Cached
 
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
-- Routes without `documentCache` option
+- Non-GET requests
+- Responses without an `s-maxage` `Cache-Control` directive
 - Non-200 responses
 
 ## Complete Example
@@ -134,40 +144,53 @@ Segment hash ensures different cached responses for navigations from different s
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache";
+import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (_env, ctx) => ({
-    store: new CFCacheStore({ ctx: ctx! }),
+  cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 
 export default router;
 
 // urls.tsx
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout, cache, loader }) => [
-  // Blog with document caching
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    layout(<BlogLayout />, () => [
-      path("/blog", BlogIndex, { name: "blog" }),
-      path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
-        loader(BlogPostLoader),
-      ]),
+export const urlpatterns = urls(({ path, layout, loader }) => [
+  // Blog pages opt into document caching via Cache-Control headers set in
+  // their handlers (see BlogIndex / BlogPost below).
+  layout(<BlogLayout />, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+    path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+      loader(BlogPostLoader),
     ]),
   ]),
 
-  // Dashboard - no document cache (dynamic content)
+  // Dashboard sets no Cache-Control header, so it is never document-cached.
   layout(<DashboardLayout />, () => [
     path("/dashboard", Dashboard, { name: "dashboard" }),
   ]),
 ]);
+
+// Blog handlers set s-maxage to opt into the document cache.
+function BlogIndex(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndexPage />;
+}
+
+function BlogPost(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogPostPage />;
+}
 ```
 
 ## Document Cache vs Segment Cache
@@ -175,7 +198,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader }) => [
 | Feature      | Document Cache             | Segment Cache         |
 | ------------ | -------------------------- | --------------------- |
 | Granularity  | Full response              | Individual segments   |
-| Opt-in       | `documentCache` in cache() | `cache({ ttl, swr })` |
+| Opt-in       | `Cache-Control` `s-maxage` | `cache({ ttl, swr })` |
 | Use case     | Static pages               | Dynamic compositions  |
 | Key includes | URL + segment hash         | Route params          |
 

package/skills/handler-use/SKILL.md

@@ -40,7 +40,7 @@ ProductPage.use = () => [
   loading(<ProductSkeleton />),
   middleware(async (ctx, next) => {
     await next();
-    ctx.header("Cache-Control", "private, max-age=60");
+    ctx.headers.set("Cache-Control", "private, max-age=60");
   }),
 ];
 ```
@@ -297,7 +297,7 @@ QuickViewModal.use = () => [
 
 ## `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 `loadingFn`](../../src/route-definition/dsl-helpers.ts)).
+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)).
 
 For pages, layouts, and intercepts that's straightforward: explicit `loading()` at the mount site replaces any `loading()` from `handler.use`. The merge order is `handler.use → explicit`, so the explicit one is the last writer and wins.
 

package/skills/hooks/SKILL.md

@@ -89,8 +89,8 @@ import { useSegments } from "@rangojs/router/client";
 function Breadcrumbs() {
   const { path, segmentIds, location } = useSegments();
 
-  // path: ["/shop", "products", "123"]
-  // segmentIds: ["shop-layout", "products-route"]
+  // path: ["shop", "products", "123"] (split on "/", no leading slash on any element)
+  // segmentIds: ["L0", "L0L1", "L0L1R0"] (opaque internal short-codes, not route names)
   // location: URL object
 
   return <nav>{path.join(" > ")}</nav>;
@@ -190,6 +190,141 @@ function SearchResults() {
 }
 ```
 
+**Shared refetch behavior**:
+
+When the loader is registered on the route via `loader()`, a plain
+`load()` call (no options, or a trivially-defaulted GET with no
+`params` and no `body`) broadcasts its result to every component
+reading the same loader id. Layout, page, and parallel-slot reads
+all converge on the new value:
+
+```tsx
+// Layout button calls load() — the page read below sees the update too.
+function Layout() {
+  const { data, load } = useLoader(CartLoader);
+  return <button onClick={() => load()}>Refresh ({data.count})</button>;
+}
+function Page() {
+  const { data } = useLoader(CartLoader); // updates with the layout's load()
+  return <span>{data.count} items</span>;
+}
+```
+
+`isLoading` and `error` follow the same scope. `throwOnError: true`
+render-throws are scoped to the **originating** hook — sibling readers
+see the error in their `error` state but their boundaries are not
+triggered by someone else's failure. A successful follow-up `load()`
+clears the shared error.
+
+**`load()` calls that stay local** (no broadcast, per-hook state, same
+semantics as the old per-component `useState`):
+
+- `load({ params: { ... } })` — explicit params.
+- `load({ method: "POST", body })` — mutations.
+- Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
+  registered on the current route. Two unrelated components calling
+  `load()` on the same fetchable-but-unregistered loader keep
+  independent results.
+
+So the search/list pattern still works — two components calling
+`load({ params: { q } })` with different `q` values each keep their
+own result; they do not collapse to last-write-wins through a shared
+store.
+
+**Scoping refetch with a `key`**:
+
+Pass a `key` to partition the shared refresh store. Only hooks using the
+**same** `key` refresh together when one of them calls `load()`. This is a
+client-side refresh identity only — it never changes the request sent to the
+server, and is unrelated to the server `cache({ key })` option and to
+`revalidate()`.
+
+```tsx
+// Two independent dashboards using the same loader. Without a key, one
+// dashboard's load() would flip the other's spinner and value. With a key,
+// they refresh independently.
+function Dashboard({ id }: { id: string }) {
+  const { data, load } = useLoader(StatsLoader, { key: `dashboard:${id}` });
+  return <button onClick={() => load()}>Refresh {data.total}</button>;
+}
+```
+
+The `key` widens sharing in two ways the default cannot:
+
+- **Parameterized GETs share.** `useFetchLoader(SearchLoader, { key: q })`
+  with the same `q` in two components share one result and refresh together —
+  a keyed `load({ params: { q } })` broadcasts to the group instead of staying
+  local. (Mutations — non-GET or `body` — stay local even with a key.)
+- **Unregistered loaders share.** A `key` makes `useFetchLoader` of a loader
+  that is **not** registered on the route share too, letting unrelated
+  components opt into a common refresh group.
+
+Lifecycle: a keyed read of an unregistered loader is reference-counted — its
+shared value lives as long as at least one component using that key is mounted.
+A persistent component (e.g. a header) keeps the value across navigations; a
+route-scoped component's value is reclaimed when it unmounts. Registered-loader
+reads (keyed or not) reset on navigation from fresh route data, as before.
+
+**Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
+
+`key` groups readers of one loader. To refresh **different** loaders together,
+tag them with a shared `refreshGroup` name and trigger them with
+`useRefreshLoaders()`. The hook takes no argument; you pass the group(s) to the
+function it returns, so one `useRefreshLoaders()` can refresh different groups
+depending on context. A read may carry **several** tags — pass an array — and is
+refreshed when **any** of its groups is refreshed:
+
+```tsx
+function Profile() {
+  const { data } = useLoader(ProfileLoader, {
+    key: userId,
+    refreshGroup: "account",
+  });
+  return <span>{data.name}</span>;
+}
+function Orders() {
+  // Tagged into two groups: refreshed by "account" (the whole set) or the
+  // finer "orders" tag.
+  const { data } = useLoader(OrdersLoader, {
+    key: userId,
+    refreshGroup: ["account", "orders"],
+  });
+  return <span>{data.count} orders</span>;
+}
+function RefreshButtons() {
+  const refresh = useRefreshLoaders();
+  return (
+    <>
+      <button onClick={() => refresh("account")}>Refresh account</button>
+      <button onClick={() => refresh("orders")}>Refresh orders only</button>
+      <button onClick={() => refresh(["account", "orders"])}>
+        Refresh both
+      </button>
+    </>
+  );
+}
+```
+
+`refresh(groups)` accepts one name or an array and re-runs every currently-mounted
+member tagged with **any** of them, with a **plain GET** against the current route
+URL — no params, no body, no mutation methods, because a group spans loaders with
+different shapes. A member that sits in two of the requested groups is fetched
+once (members are unioned and deduped by read). It returns a promise that resolves
+when all members settle and **rejects with an `AggregateError`** if any fail;
+group refresh never render-throws, so handle failures at the await site
+(`await refresh("account").catch(...)`). Each failing member also exposes its
+error via its own read's `error`.
+
+Multiple tags give you granular vs. whole-set refresh from one place: a coarse
+tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
+subset. Sharing within a group is opt-in via `key`: members that share a `key`
+share one value (and one fetch); a grouped reader **without** a `key` gets its own
+private bucket, so a group refresh updates only that read and never leaks into
+unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+at once (one read tagged with multiple names, or different reads tagging the same
+keyed bucket with different names). Keep parameterized loaders on the single-loader
+`key` — a plain-GET group refresh sends no params.
+
 **Load options**:
 
 ```tsx
@@ -511,33 +646,81 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
 
-## Cache Hooks
+> **Hydration:** `.read()` returns `undefined` on the server but may return
+> a real value on the first client render (history state survives reload).
+> Do not call `.read()` directly during the initial render of a component;
+> call it from an event handler or inside a `useEffect` post-mount. For
+> reactive hydration-safe access, use `useLocationState()` instead.
+
+### .write() / .delete() (static, non-reactive)
 
-### useClientCache()
+Static counterparts to `.read()`. Both mutate the current history entry's
+`history.state` via `replaceState`, preserving any other keys (router
+bookkeeping, other location state slots). Both are client-only; they throw
+when called on the server.
 
-Manually control client-side navigation cache:
+Neither dispatches an event, so components reading via `useLocationState`
+will NOT re-render until the next navigation/popstate. Pair with `.read()`
+(or a fresh mount via back/forward/reload) instead.
 
 ```tsx
 "use client";
-import { useClientCache } from "@rangojs/router/client";
+import { ProductState } from "./state";
 
-function SaveButton() {
-  const { clear } = useClientCache();
+// Persisted across hard refresh and back/forward of this entry.
+ProductState.write({ name: "Widget", price: 9.99 });
+
+// Read later (or on next mount).
+const current = ProductState.read();
+
+// Manually clear the slot. Idempotent if it isn't set.
+ProductState.delete();
+```
 
+| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.write()`  | yes (replace this slot) | no                                | throws              |
+| `.delete()` | yes (remove this slot)  | no                                | throws              |
+
+## Cache Control
+
+### invalidateClientCache()
+
+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.
+
+```tsx
+"use client";
+import { invalidateClientCache } from "@rangojs/router";
+
+function SaveButton() {
   const handleSave = async () => {
     await fetch("/api/data", {
       method: "POST",
       body: JSON.stringify(data),
     });
 
-    // Invalidate cache after mutation
-    clear();
+    // Invalidate the client's caches after the mutation
+    invalidateClientCache();
   };
 
   return <button onClick={handleSave}>Save</button>;
 }
 ```
 
+A module-level subscription works the same way (no component needed):
+
+```ts
+import { invalidateClientCache } from "@rangojs/router";
+
+socket.on("catalog-updated", () => invalidateClientCache());
+```
+
 **Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.
 
 ## Outlet Components
@@ -696,7 +879,9 @@ function MountInfo() {
 
 ### useReverse(routes)
 
-Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse(".name", params?)`. Auto-fills params from `useParams()`; explicit params override.
+Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` — the leading dot is optional. Auto-fills params from `useParams()`; explicit params override.
+
+> Per-module `*.gen.ts` files are **CLI opt-in and not Vite-watched** — run `rango generate <urls-file>` (or wire it into `predev`) and re-run it whenever the module's routes change. See `/links` for the full generated-file setup and exposure-boundary rules.
 
 ```tsx
 "use client";
@@ -707,8 +892,8 @@ function BlogNav() {
   const reverse = useReverse(blogRoutes);
   return (
     <nav>
-      <Link to={reverse(".index")}>Blog</Link>
-      <Link to={reverse(".post", { postId: "hello" })}>Post</Link>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
     </nav>
   );
 }
@@ -718,21 +903,22 @@ See `/links` for the full URL generation guide. `ctx.reverse()` is server-only;
 
 ## 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                 | `ReadonlyURLSearchParams`                                          |
-| `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                                             |
-| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                                              |
-| `useHandle()`        | Accumulated handle data           | T (handle type)                                                    |
-| `useAction()`        | Server action state               | state, error, result                                               |
-| `useLocationState()` | History state (persists or flash) | T \| undefined                                                     |
-| `useClientCache()`   | Cache control                     | { clear }                                                          |
+| Hook                      | Purpose                                                        | Returns                                                            |
+| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`           | Current pathname                                               | `string`                                                           |
+| `useSearchParams()`       | URL search params                                              | `ReadonlyURLSearchParams`                                          |
+| `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`                                                             |