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

package/skills/host-router/SKILL.md

@@ -22,9 +22,9 @@ import { createHostRouter } from "@rangojs/router/host";
 
 const router = createHostRouter();
 
-router.host(["."]).map(() => import("./apps/main"));
-router.host(["admin.*"]).map(() => import("./apps/admin"));
-router.host(["api.*"]).map(() => import("./apps/api"));
+router.host(["."]).lazy(() => import("./apps/main"));
+router.host(["admin.*"]).lazy(() => import("./apps/admin"));
+router.host(["api.*"]).lazy(() => import("./apps/api"));
 
 export default {
   fetch(request: Request, env: Env, ctx: ExecutionContext) {
@@ -33,7 +33,31 @@ export default {
 };
 ```
 
-Each `.map()` receives either a direct handler `(request, input) => Response` or a lazy import `() => import(...)`. Lazy imports resolve a module with a `default` export that is either a handler function or another `HostRouter` (for nesting).
+## Inline handlers (`.map`) vs lazy mounts (`.lazy`)
+
+A host pattern maps to one of two things, and you pick the method by intent:
+
+| Method  | Argument                       | Use for                                                      |
+| ------- | ------------------------------ | ------------------------------------------------------------ |
+| `.map`  | `(request, input) => Response` | An inline request handler that produces a response directly. |
+| `.lazy` | `() => import("./sub-app")`    | A lazily-imported handler or nested host router (a sub-app). |
+
+```typescript
+// Lazy mount: the module's default export is a handler or a HostRouter.
+router.host(["admin.*"]).lazy(() => import("./apps/admin"));
+
+// Inline handler: returns a Response itself (sync or async).
+router.host(["health.*"]).map(() => new Response("ok"));
+router
+  .host(["echo.*"])
+  .map((request) => new Response(new URL(request.url).pathname));
+```
+
+Why two methods instead of one overloaded `.map()`:
+
+- **Build-time discovery** invokes only `.lazy()` mounts (to trigger each sub-app's `createRouter()` registration). Inline `.map()` handlers are never invoked during discovery, so they can't crash it or pollute its errors.
+- `.map(() => import("./sub-app"))` is a **type error** — a lazy import resolves to a module, not a `Response`. Use `.lazy()` for imports. (If the types are bypassed, e.g. from JS, a `.map()` handler that resolves to a module throws a clear `HostRouterError` at request time instead of returning the module.)
+- A lazy loader may declare an ignored parameter (`.lazy((_request?) => import("./x"))`); `.lazy()` accepts it because intent is explicit, not inferred from the signature.
 
 ## Pattern Syntax
 
@@ -42,7 +66,7 @@ Each `.map()` receives either a direct handler `(request, input) => Response` or
 | `.` or `*`        | Any apex domain (`example.com`)                |
 | `**`              | Any domain (apex + all subdomains)             |
 | `*.`              | Any single-level subdomain (`www.example.com`) |
-| `**. `            | Any multi-level subdomain (`a.b.example.com`)  |
+| `**.`             | Any multi-level subdomain (`a.b.example.com`)  |
 | `example.com`     | Exact domain                                   |
 | `*.com`           | Any apex `.com` domain                         |
 | `*.example.com`   | Single subdomain of `example.com`              |
@@ -65,8 +89,8 @@ const hosts = defineHosts({
   app: [".", "www.*"],
 });
 
-router.host(hosts.admin).map(() => import("./apps/admin"));
-router.host(hosts.app).map(() => import("./apps/main"));
+router.host(hosts.admin).lazy(() => import("./apps/admin"));
+router.host(hosts.app).lazy(() => import("./apps/main"));
 ```
 
 Returns a frozen object — keys are autocompleted by TypeScript.
@@ -88,7 +112,7 @@ router.use(async (request, input, next) => {
 router
   .host(["admin.*"])
   .use(requireAuth)
-  .map(() => import("./apps/admin"));
+  .lazy(() => import("./apps/admin"));
 ```
 
 Middleware signature: `(request: Request, input: RouterRequestInput, next: () => Promise<Response>) => Promise<Response>`
@@ -165,12 +189,26 @@ Logs pattern matching, route registration, and cookie override decisions to cons
 ## Testing
 
 ```typescript
-import { createTestRequest, testPattern } from "@rangojs/router/host/testing";
+import {
+  createTestRequest,
+  testPattern,
+  matchesHost,
+} from "@rangojs/router/host/testing";
 
-// Test pattern matching
+// Test pattern matching (host-only)
 testPattern("admin.*", "admin.example.com"); // true
 testPattern([".", "www.*"], "example.com"); // true
 
+// Path-based patterns need the third pathname arg (defaults to "/", so a
+// host-only pattern still works with two args):
+testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin"); // true
+
+// Or match a pattern against a real Request (hostname + pathname from the URL):
+matchesHost(
+  "**.workers.dev/admin",
+  new Request("https://foo.workers.dev/admin"),
+); // true
+
 // Create requests for integration tests
 const request = createTestRequest({
   host: "admin.example.com",
@@ -179,40 +217,62 @@ const request = createTestRequest({
 });
 
 // Test which route would match (without executing)
-router.test("admin.example.com"); // { pattern, handler } | null
+router.test("admin.example.com"); // { pattern, handler, kind } | null
 ```
 
 ## Error Types
 
 All errors extend `HostRouterError`:
 
-| Error                         | When                                        |
-| ----------------------------- | ------------------------------------------- |
-| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces |
-| `HostOverrideNotAllowedError` | Cookie override from disallowed host        |
-| `InvalidHostnameError`        | Cookie value isn't a valid hostname         |
-| `HostValidationError`         | Custom `validate` function threw            |
-| `NoRouteMatchError`           | No host pattern matched the request         |
-| `InvalidHandlerError`         | Handler is not a function                   |
+| Error                         | When                                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| `InvalidPatternError`         | Pattern is empty, non-string, or has spaces                                                       |
+| `HostOverrideNotAllowedError` | Cookie override from disallowed host                                                              |
+| `InvalidHostnameError`        | Cookie value isn't a valid hostname                                                               |
+| `HostValidationError`         | Custom `validate` function threw                                                                  |
+| `NoRouteMatchError`           | No host pattern matched the request                                                               |
+| `InvalidHandlerError`         | Handler is not a function, or a lazy mount resolved to a module without a usable `default` export |
+| `HostRouterError`             | A `.map()` inline handler resolved to a module namespace (a misused lazy import — use `.lazy()`)  |
 
 See the fallback section above for a `NoRouteMatchError` catch example.
 
 ## Nesting Host Routers
 
-A lazy handler can resolve to another `HostRouter`:
+A lazy mount can resolve to another `HostRouter`:
 
 ```typescript
 // apps/regional.ts
 import { createHostRouter } from "@rangojs/router/host";
 
 const regional = createHostRouter();
-regional.host(["us.*"]).map(() => import("./regions/us"));
-regional.host(["eu.*"]).map(() => import("./regions/eu"));
+regional.host(["us.*"]).lazy(() => import("./regions/us"));
+regional.host(["eu.*"]).lazy(() => import("./regions/eu"));
 
 export default regional;
 ```
 
 ```typescript
 // host-router.ts
-router.host(["**.regional.example.com"]).map(() => import("./apps/regional"));
+router.host(["**.regional.example.com"]).lazy(() => import("./apps/regional"));
 ```
+
+## Cross-app navigation is a full document load
+
+A client-side navigation that crosses an app boundary (e.g. a `<Link>` or
+intercepted `<a>` from the app at `/` into an app mounted at `/shop`) is a **hard
+document navigation**, not a soft in-tree swap. When the server sees a partial
+(SPA) request whose router id doesn't match the matched app, it returns
+`X-RSC-Reload` and the client does a real document navigation to the target.
+
+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
+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
+apps; each app owns its own document.
+
+**Within-app** navigation is unchanged — a normal soft SPA update (the document
+stays mounted). Only crossing an app boundary triggers the reload.

package/skills/intercept/SKILL.md

@@ -8,9 +8,6 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Basic Intercept
 
 ```typescript
@@ -26,7 +23,7 @@ function ShopLayout() {
   );
 }
 
-export const urlpatterns = urls(({ path, layout, intercept, loader }) => [
+export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) => [
   layout(<ShopLayout />, () => [
     // Intercept product detail - shows modal during soft navigation
     intercept(
@@ -110,8 +107,10 @@ Use named revalidation contracts on both the outer producer and the intercept
 consumer when they share `ctx.set()` data:
 
 ```typescript
-export const revalidateProductShell = ({ actionId }) =>
-  actionId?.includes("src/actions/product.ts#") ?? false;
+import * as ProductActions from "./actions/product";
+
+export const revalidateProductShell = (ctx) =>
+  ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns

package/skills/layout/SKILL.md

@@ -8,9 +8,6 @@ argument-hint: [component]
 
 Layouts wrap child routes and persist during navigation within their scope.
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Basic Layout
 
 ```typescript
@@ -205,8 +202,10 @@ layout(<ShopLayout />, () => [
 ])
 
 // Or revalidate based on conditions
+import * as CartActions from "./actions/cart";
+
 layout(<CartLayout />, () => [
-  revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+  revalidate((ctx) => ctx.isAction(CartActions) || undefined),
 
   path("/cart", CartPage, { name: "cart" }),
 ])
@@ -224,8 +223,9 @@ them on both producer and consumer segments:
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#addToCart") ?? false;
+import { addToCart } from "./actions/cart";
+
+export const revalidateCartData = (ctx) => ctx.isAction(addToCart) || undefined;
 ```
 
 ```typescript
@@ -245,9 +245,10 @@ You can also package them as importable handoff helpers:
 ```typescript
 // revalidation-contracts.ts
 import { revalidate } from "@rangojs/router";
+import * as AuthActions from "./actions/auth";
 
-export const revalidateAuthData = ({ actionId }) =>
-  actionId?.includes("src/actions/auth.ts#") ?? false;
+export const revalidateAuthData = (ctx) =>
+  ctx.isAction(AuthActions) || undefined;
 export const revalidateAuth = () => [revalidate(revalidateAuthData)];
 ```
 
@@ -265,6 +266,7 @@ layout(<ShellLayout />, () => [
 ```typescript
 import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
   return (
@@ -294,7 +296,7 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   }, () => [
     // Layout loaders
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
 
     // Parallel routes

package/skills/links/SKILL.md

@@ -13,7 +13,7 @@ argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 **On the client, two patterns:**
 
 1. **Receive URLs as props / loader data / action return.** The default. The server has the full route manifest and handler context — generate URLs there and hand strings to client components.
-2. **`useReverse(routes)`.** Import a generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse(".name", params?)`. Mount-aware via `useMount()`, auto-fills params from `useParams()`, fully typed from the imported map. Use this when a client component needs to generate URLs into a known module without round-tripping through the server.
+2. **`useReverse(routes)`.** Import a generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` (the leading dot is optional). Mount-aware via `useMount()`, auto-fills params from `useParams()`, fully typed from the imported map. Use this when a client component needs to generate URLs into a known module without round-tripping through the server.
 
 `ctx.reverse()` itself is **server-only** — it depends on the full route manifest and handler context. Client components never import or call it.
 
@@ -213,7 +213,17 @@ function GlobalNav() {
 }
 ```
 
-`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via the `Rango.Path` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+When wrapping `href()`, type the wrapper's path parameter as `Rango.Path` so it
+keeps the same generated-route validation. `Rango.Path` is ambient — no import,
+just like `Rango.Env` / `Rango.Vars`:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
 
 `href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
@@ -263,6 +273,8 @@ function MountInfo() {
 
 Hook that returns a typed local reverse function for a `routes` map imported from a generated `.gen.ts` next to a `urls()` module. The route map is the **exposure boundary** — `useReverse` only knows about names in that map, never the full app manifest.
 
+> **Which map?** `useReverse` accepts any routes map. Prefer the per-module `routes` (e.g. `urls/blog.gen.ts`): it gives **mount-aware** local `.name` reverse (auto-prefixes the `include()` mount) and only that module's names enter the client bundle. You _can_ instead pass `router.named-routes.gen.ts` (`NamedRoutes`) for **global** names (`blog.post`; the leading dot is optional) — it is a plain importable map and works on the client (it is **not** server-only) — but its paths are **absolute** while `useReverse` mount-prefixes, so it is correct only at the root mount (under a non-root mount it double-prefixes), and importing it pulls every route name and pattern in the app into the client bundle (a small names-to-paths map — not components or loaders), versus the per-module map which exposes only one module's names. So the per-module map is preferred for in-module links; the named-routes map is the escape hatch for global names.
+
 ```tsx
 "use client";
 import { Link, useReverse } from "@rangojs/router/client";
@@ -273,8 +285,8 @@ export function BlogNav() {
 
   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>
   );
 }
@@ -282,7 +294,7 @@ export function BlogNav() {
 
 ### How it resolves
 
-1. Strips the leading `.` and looks up the name in the imported `routes` map.
+1. Strips an optional leading `.` and looks up the name in the imported `routes` map.
 2. Joins the local pattern with the surrounding `useMount()` value — the include's URL pattern.
 3. Substitutes params: explicit params from the call, then auto-filled from `useParams()` for anything still unresolved (mount params like `:tenantId` flow in this way).
 4. Appends a query string if a search object is passed and the route has a `search` schema.
@@ -350,14 +362,14 @@ reverse(".search", {}, { q: "hello world", page: 2 });
 
 ### Errors
 
-- Unknown name: throws `Unknown local route: ".not-a-route"`.
+- Unknown name: throws `Unknown route: ".not-a-route"`.
 - Missing required param: throws `Missing param "postId" for route ".detail"`.
 
 Both happen synchronously during `reverse()` — wrap calls in try/catch (or an ErrorBoundary if the throw happens during render) when you need to surface them as UI.
 
-### Names are dot-only on the client
+### The leading dot is optional
 
-`useReverse` accepts only `.name` (and dotted variants like `.nested.index`). There is no global namespace on the client — the import IS the scope. To link into a different module, import that module's `routes`:
+`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. To link into a different module, import that module's `routes`:
 
 ```tsx
 import { routes as blogRoutes } from "../urls/blog.gen.js";
@@ -368,8 +380,8 @@ function CrossNav() {
   const shop = useReverse(shopRoutes);
   return (
     <nav>
-      <Link to={blog(".index")}>Blog</Link>
-      <Link to={shop(".cart")}>Cart</Link>
+      <Link to={blog("index")}>Blog</Link>
+      <Link to={shop("cart")}>Cart</Link>
     </nav>
   );
 }

package/skills/loader/SKILL.md

@@ -91,6 +91,20 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+> **Client refresh `key` vs. server `cache({ key })` vs. `revalidate()`.** Three
+> different "what refreshes" knobs that are easy to confuse:
+>
+> - `useLoader(Loader, { key })` / `useFetchLoader(Loader, { key })` — a
+>   **client** refresh identity. It groups which mounted reads of one loader
+>   refresh together when one calls `load()`. It never touches the server
+>   request. For refreshing **different** loaders together, tag them with
+>   `{ refreshGroup }` (one name or several) and call `useRefreshLoaders()(name)`
+>   (plain GET only). See the hooks skill ("Scoping refetch with a `key`" and
+>   "Refreshing multiple loaders together").
+> - `cache({ key })` — a **server** cache identity (storage hit/miss/ttl/swr).
+> - `revalidate()` — which **server** segments/loaders recompute during
+>   navigation and action refreshes.
+
 DSL loaders are the **live data layer** — they resolve fresh on every
 request, even when the route is inside a `cache()` boundary. The router
 excludes them from the segment cache at storage time and re-resolves them
@@ -146,23 +160,23 @@ Loaders receive the same context shape as route handlers.
 
 ### Full field surface
 
-| Field          | Type                           | Notes                                                                                               |
-| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
-| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                 |
-| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                        |
-| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                 |
-| `url`          | `URL`                          | Parsed request URL.                                                                                 |
-| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                     |
-| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                |
-| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                   |
-| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                 |
-| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                     |
-| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
-| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data.      |
-| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.               |
-| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                      |
-| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                     |
-| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).              |
+| Field          | Type                           | Notes                                                                                                                                                   |
+| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                                                                     |
+| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                                                                            |
+| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                                                                     |
+| `url`          | `URL`                          | Parsed request URL.                                                                                                                                     |
+| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                                                                         |
+| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                                                                    |
+| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                                                                       |
+| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                     |
+| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                                                                         |
+| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`).                                                     |
+| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. |
+| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                   |
+| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                          |
+| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                                                                         |
+| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                  |
 
 ### Example
 
@@ -185,7 +199,7 @@ export const ProductLoader = createLoader(async (ctx) => {
   // Request headers
   const auth = ctx.request.headers.get("Authorization");
 
-  // Variables set by middleware (from RSCRouter.Vars augmentation)
+  // Variables set by middleware (from Rango.Vars augmentation)
   const user = ctx.get("user");
 
   // Type-checked URLs for payloads. `.name` resolves within the current
@@ -235,6 +249,8 @@ export const OrderLoader = createLoader(async (ctx) => {
 Add caching or revalidation to specific loaders:
 
 ```typescript
+import * as CartActions from "./actions/cart";
+
 path("/product/:slug", ProductPage, { name: "product" }, () => [
   // Cached loader
   loader(ProductLoader, () => [cache({ ttl: 300 })]),
@@ -244,15 +260,23 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
     revalidate(() => false), // Never revalidate
   ]),
 
-  // Loader that revalidates after cart actions
+  // Loader that revalidates after cart actions (defer otherwise — keeps the
+  // permissive loader defaults for navigation and other actions intact)
   loader(CartLoader, () => [
-    revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
   ]),
 ]);
 ```
 
 ### `revalidate()` return shapes
 
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether a segment (here, a loader) re-runs and streams to the
+> client on a navigation or action — never whether a cached value is stale. The
+> cache decides hit/miss/ttl/swr independently and never reads `revalidate()`.
+> Caching a loader is a separate, opt-in step (`loader(Fn, () => [cache({...})])`).
+> See `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
 A `revalidate(fn)` callback can return one of four shapes. The chain
 processes revalidators in order; each call's return controls how the
 chain continues:
@@ -282,6 +306,58 @@ revalidate(() => null); // explicit defer
 If every revalidator on a segment defers, the segment-type default
 (e.g. params-changed for routes, `false` for parallels) is used.
 
+#### `|| undefined` (defer) vs `?? false` (hard) — pick deliberately
+
+A boolean return — including `false` — is a **hard** decision: it short-circuits
+the chain and overrides the segment default. `undefined` **defers** to the
+running suggestion / segment default. They are not interchangeable:
+
+```typescript
+// Defer: "revalidate on match, otherwise let the default/downstream decide."
+revalidate(({ actionId }) => actionId?.includes("Cart") || undefined);
+
+// Hard: "revalidate ONLY on match, suppress everything else."
+revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
+```
+
+This matters most for loaders, whose defaults are permissive: a loader defaults
+to revalidating on **any** action (`POST`) and on **param/search changes**
+during navigation. So `?? false` on a loader silently suppresses both — the
+loader will not refetch when you navigate to a different `:id`. Use
+`|| undefined` when you want to _add_ a revalidation signal on top of the
+sensible defaults, and reserve `?? false` for the rare case where you genuinely
+want the loader to refetch on nothing but your matched action.
+
+When **composing multiple revalidators** on one segment (see below), defer is
+mandatory: the first hard `?? false` ends the chain and the later contracts
+never run.
+
+#### Matching actions: `ctx.isAction()`
+
+To revalidate after specific server actions, match them by **reference** with
+`ctx.isAction()` rather than hand-written `actionId` substrings. A rename or
+moved file then becomes a type error instead of silently failing to match:
+
+```typescript
+import { addToCart, removeFromCart } from "../actions/cart";
+import * as CartActions from "../actions/cart";
+
+loader(CartLoader, () => [
+  revalidate((ctx) => ctx.isAction(addToCart) || undefined), // one action
+]);
+revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
+revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+```
+
+`isAction()` is a method on the revalidate predicate's **context argument** —
+there is no standalone `isAction` import; you always reach it through the callback
+parameter (`revalidate((ctx) => ctx.isAction(...))`). It returns a raw boolean, so
+pair it with `|| undefined` for the usual "revalidate on match, else defer"
+intent. It returns `false` on plain navigation and on non-matches, and resolves
+the reference the same way the router derives `actionId` (`$id` in production,
+`$$id` in dev), so it matches in both modes. The raw `actionId` string stays
+available on the same context as an escape hatch.
+
 ### Revalidation Contracts for Loader Dependencies
 
 If a loader reads `ctx.get()` data produced by an outer handler/layout, share
@@ -289,8 +365,12 @@ the same named revalidation contract across producer and consumer segments.
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateAccountScope = ({ actionId }) =>
-  actionId?.includes("src/actions/account.ts#") ?? false;
+import * as AccountActions from "./actions/account";
+
+// Match by reference with ctx.isAction() (rename-safe), and defer (|| undefined)
+// so these contracts compose — a hard `false` would short-circuit the rest.
+export const revalidateAccountScope = (ctx) =>
+  ctx.isAction(AccountActions) || undefined;
 
 layout(AccountLayout, () => [
   revalidate(revalidateAccountScope), // producer reruns
@@ -333,6 +413,64 @@ follows the same rule: at build time, loaders are skipped entirely (there is no
 real request context), and at runtime the worker resolves them fresh against
 the live database.
 
+### Parallel and streaming — latency overlaps first paint
+
+Loaders do not block the page. As the render pass begins — the pass that route
+middleware wraps, so loaders run right after middleware, not in a later
+phase — every matched loader is kicked off **concurrently** (their promises start in the
+same tick), and each result is **streamed** to the client as its own RSC Flight
+chunk rather than awaited up front. Pair a loader with `loading()` (or a
+client `<Suspense>`) and the shell paints immediately while the data streams in.
+
+This is why **"cached UI still pays full data latency" is the wrong intuition**:
+on a `cache()` hit the UI segments stream instantly from cache while the live
+loaders resolve fresh **in parallel** — data latency _overlaps_ first paint
+instead of being added on top of it. (Without a `loading()` / `<Suspense>`
+boundary a parallel loader blocks its parent, so add one to keep the overlap.)
+
+If you come from a framework where the loader is a blocking step that runs
+before the response is built, this is the shift to internalize: here the
+response starts streaming first and loader data fills in.
+
+### See it: `debugPerformance`
+
+Turn on the per-request performance timeline early — it is the fastest way to
+confirm loaders overlap rather than serialize, and to find the real bottleneck
+locally instead of guessing:
+
+```typescript
+const router = createRouter({ document: Document, debugPerformance: true });
+```
+
+Or enable it per-request from middleware (e.g. only when `?debug` is present) by
+calling `ctx.debugPerformance()` **before** `await next()`. Each HTML request
+then prints a shared-axis waterfall (and emits a `Server-Timing` header):
+
+```
+[RSC Perf] GET /product/widget (24.53ms)
+start      dur  span                          timeline
+ 0.08ms  3.20ms  route-matching               |#####...................................|
+ 3.40ms  8.70ms  ssr-render-html              |.....##############.....................|
+ 3.42ms 11.90ms  loader:…#ProductLoader       |.....###################................|
+ 3.45ms 11.40ms  loader:…#ReviewsLoader        |.....##################.................|
+ 0.00ms 24.53ms  handler:total                |########################################|
+```
+
+How to read it:
+
+- **Humans:** scan the `#` bars on the shared axis. Bars that start at the same
+  offset and run side by side are executing **in parallel** — loaders should
+  overlap `ssr-render-html` / `render:total`, not sit alone to the right of
+  everything. A lone `loader:*` bar past the render bar is serialized latency to
+  chase. `handler:total` is the whole request; `render:total` is the render pass.
+- **LLMs / programmatic:** read each row as `{ start, dur, label }`. A loader
+  overlaps paint when its `[start, start+dur]` interval intersects
+  `render:total` / `ssr-render-html`. Flag a regression when a `loader:*`
+  interval is **disjoint from and starts after** `render:total`, or when its
+  `dur` approaches `handler:total` — that loader is on the critical path instead
+  of overlapping it. Two `loader:*` rows with near-equal `start` confirm
+  parallel execution.
+
 ### Opting a Loader into Caching
 
 To cache a specific loader's data, attach a `cache()` child:
@@ -423,6 +561,8 @@ entirely (no read, no write).
 ### Per-Loader Store Override
 
 ```typescript
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+
 const hotStore = new MemorySegmentCacheStore({ defaults: { ttl: 10 } });
 
 loader(PricingLoader, () => [
@@ -606,6 +746,13 @@ export const FileUploadLoader = createLoader(async (ctx) => {
 
 Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
 
+> **Refetch sharing**: when the loader is registered on the route via
+> `loader()`, a plain `load()` call (no `params`, no `body`) broadcasts
+> the new value to every component reading the same loader id —
+> `useLoader` reads in layouts, pages, and parallel slots all converge.
+> Calls with `params` or a non-GET method stay local to the call site.
+> See `/hooks` → "Shared refetch behavior" for the full contract.
+
 ## Complete Example
 
 ```typescript
@@ -638,10 +785,12 @@ export const CartLoader = createLoader(async (ctx) => {
 });
 
 // urls.tsx — register loaders in the DSL
+import * as CartActions from "./actions/cart";
+
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
 
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [