@rangojs/router 0.0.0-experimental.98 → 0.0.0-experimental.98914650

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:
@@ -606,6 +744,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 +783,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" }, () => [

package/skills/middleware/SKILL.md

@@ -10,9 +10,6 @@ Middleware runs before/after route handlers using the onion model.
 
 ## Execution Model
 
-Canonical semantics reference:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 There are two levels of middleware with different execution scopes:
 
 ### Global middleware (`router.use()`)
@@ -36,15 +33,22 @@ Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wra
 
 ```
 Request flow (with action):
-  global mw -> action executes -> route mw -> layout -> handler -> loaders
+  global mw -> action executes -> route mw -> render pass
 
 Request flow (no action):
-  global mw -> route mw -> layout -> handler -> loaders
+  global mw -> route mw -> render pass
 
 Progressive enhancement (no-JS form POST):
   global mw -> action executes -> route mw -> full page re-render
 ```
 
+The **render pass** resolves handler, layouts, parallels, and loaders together —
+it is not a handler-then-loaders sequence. Handler-first ordering is guaranteed
+only between a route handler and its child/orphan layouts and parallels (so
+`ctx.set` is visible); loaders run **concurrently** and stream their results, so
+their latency overlaps rendering rather than blocking it. See `/loader` →
+"Parallel and streaming".
+
 The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
 
 Revalidation is still partial. Route middleware wraps the render pass that
@@ -63,8 +67,10 @@ For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.
 
 ```typescript
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") ?? false;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   middleware(cartRenderMiddleware),
@@ -192,7 +198,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.env.DB; // D1Database
   ctx.env.KV; // KVNamespace
 
-  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
   // Continue to next middleware/handler
@@ -233,8 +239,8 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
 ```
 
 This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
-via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
-data; use RSCRouter.Vars for app-wide middleware state.
+via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use Rango.Vars for app-wide middleware state.
 
 ## Redirect with State in Middleware
 

package/skills/migrate-nextjs/SKILL.md

@@ -288,21 +288,40 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 Use `Passthrough()` whenever the Next.js route has `dynamicParams: true` (the
 default) or serves an open-ended param space. See `/prerender` for full API.
 
-### Revalidation: different model
+### Revalidation: two distinct axes
 
-Next.js uses path/tag-based cache invalidation (`revalidatePath`, `revalidateTag`)
-to bust cached responses. Rango does not currently have a direct equivalent.
+Next.js conflates two things under "revalidation." Rango separates them — and
+tag-based cache invalidation now maps directly.
 
-In Rango, separate these two concepts:
+**1. Cache invalidation (bust cached values) — direct equivalent.** Tag entries
+with `cache({ tags })` or, inside a `"use cache"` function, runtime
+`cacheTag(...tags)`. Then invalidate by tag:
 
-**Partial rendering revalidation** — `revalidate()` controls which segments
-(layouts, paths, loaders, parallels) should re-run during partial action
-re-rendering. This is about the segment tree, not cache invalidation:
+```typescript
+// Next.js                    Rango
+// revalidateTag("products")  →  await updateTag("products")  // in a server action: awaitable,
+//                                                            // read-your-own-writes (next render is fresh)
+//                            or  revalidateTag("products")    // in a route handler / webhook:
+//                                                            // background, non-blocking (hard-purge)
+```
+
+`updateTag` is awaitable and immediate; `revalidateTag` is fire-and-forget. Both
+hard-purge (the next read re-renders fresh); the only difference is awaitability —
+despite the Next.js name, `revalidateTag` here is NOT stale-while-revalidate.
+Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) index by tag. Next's
+`revalidatePath` has no path-based equivalent — tag the relevant entries instead.
+
+**2. Partial-render selection (which segments re-run after an action).** This is
+NOT cache invalidation — it is `revalidate()`, controlling which segments
+(layouts, paths, loaders, parallels) recompute during partial action
+re-rendering:
 
 ```typescript
+import { updateBlog } from "./actions/blog";
+
 // Re-run this layout when a blog action fires
 layout(BlogLayout, () => [
-  revalidate(({ actionId }) => actionId?.includes("updateBlog") ?? false),
+  revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
 ]);
 
@@ -323,15 +342,18 @@ cache({ ttl: 60, swr: 300 }, () => [
 ]);
 ```
 
-The key shift is:
+The two axes compose: `updateTag()` / `revalidateTag()` bust cached values;
+`revalidate()` selects which segments re-render and stream to the client after an
+action.
 
-- Next.js asks "which cached path or tag should I invalidate?"
-- Rango asks "which segments should re-run after this action?"
+When migrating:
 
-When migrating `revalidatePath()` / `revalidateTag()` usage, the Rango version
-usually is not a 1:1 API replacement. Instead, decide which layouts, routes,
-loaders, or parallels should recompute after an action and declare
-`revalidate()` at those segment boundaries.
+- `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
+  `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
+- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+  route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
+- To also force specific segments to re-render after the action (independent of
+  cache busting), attach a `revalidate()` rule at those segment boundaries.
 
 ## 4. Middleware
 
@@ -463,7 +485,7 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
-Next.js's `revalidatePath()` / `revalidateTag()` have no direct equivalent — Rango partially re-renders matched route segments (path/layout/parallel/intercept) and re-resolves their loaders, and you scope re-runs by attaching a `revalidate(({ actionId }) => ...)` rule to any segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads) and `/loader` for revalidation rule semantics.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data; `revalidateTag(tag)` is a background (non-blocking) hard-purge and is NOT read-your-own-writes, so reserve it for route handlers / webhooks (calling it from an action can leave that action's re-render stale). `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, to force specific matched segments (path/layout/parallel/intercept) and their loaders to re-render after an action, attach a `revalidate(({ actionId }) => ...)` rule to that segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
 
 ## 8. Metadata / Head
 

package/skills/mime-routes/SKILL.md

@@ -108,6 +108,33 @@ path.text("/api/data", () => "plain text version", { name: "dataText" }),
 Without an RSC primary, there is no `text/html` candidate — the Accept header
 picks among the response-type candidates directly.
 
+## Type Safety For Negotiated Paths
+
+`router.named-routes.gen.ts` validates route names, params, search, `href()`, and
+the `Rango.Path` type, but it does not carry response payload metadata. For MIME or
+response payload types, use one of these surfaces:
+
+- `RouteResponse<typeof patterns, "routeName">` for a specific response variant
+  by route name. This is the clearest option when several MIME variants share
+  one URL pattern.
+- `Rango.PathResponse<"/products/:id">` (ambient, no import) for global lookup by URL pattern or concrete path after the app
+  registers `typeof router.routeMap`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+`RegisteredRoutes` is what exposes the richer routeMap entries containing
+response payload metadata. Without it, URL-pattern response lookup has paths but
+no payloads, so response types resolve to `never`.
+
 ## How It Works
 
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.

package/skills/observability/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: observability
+description: Debug Rango request performance with debugPerformance, Server-Timing, structured telemetry, and tracing
+argument-hint:
+---
+
+# Observability
+
+Use this when you need to understand request latency, cache decisions,
+revalidation behavior, loader overlap, or production traces.
+
+Rango exposes two complementary observability surfaces:
+
+1. **Performance timeline** (`debugPerformance`) — per-request waterfall for
+   local or targeted debugging. It prints to the console and emits
+   `Server-Timing`.
+2. **Structured telemetry** (`telemetry`) — lifecycle events sent to a pluggable
+   sink for production monitoring, OpenTelemetry, or custom metrics.
+
+The essentials are below. The exported `TelemetryEvent` union type
+(`import type { TelemetryEvent } from "@rangojs/router"`) is the full event
+contract — every event kind and its fields are typed there.
+
+## Performance timeline
+
+Enable globally while debugging:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+});
+```
+
+Or enable for selected requests from middleware:
+
+```typescript
+middleware(async (ctx, next) => {
+  if (ctx.url.searchParams.has("debug")) {
+    ctx.debugPerformance();
+  }
+  await next();
+});
+```
+
+Call `ctx.debugPerformance()` before `await next()`. The request then prints a
+shared-axis waterfall and adds a `Server-Timing` header.
+
+Read the timeline as intervals:
+
+- `handler:total` is the whole router request.
+- `render:total` / `ssr-render-html` show the render pass.
+- `loader:*` rows should overlap render work. If a loader starts only after the
+  render bar, it is serialized latency.
+- Cache, route matching, middleware pre/post, RSC serialization, and SSR phases
+  appear as separate spans, so the slow phase is visible without guessing.
+
+## Structured telemetry
+
+Use telemetry when you want durable production events rather than a one-request
+debug waterfall.
+
+```typescript
+import { createRouter, createConsoleSink } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createConsoleSink(),
+});
+```
+
+For OpenTelemetry:
+
+```typescript
+import { createRouter, createOTelSink } from "@rangojs/router";
+import { trace } from "@opentelemetry/api";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: createOTelSink(trace.getTracer("my-app")),
+});
+```
+
+Custom sinks implement `emit(event)`:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  telemetry: {
+    emit(event) {
+      myMetrics.record(event);
+    },
+  },
+});
+```
+
+Events include `request.start/end/error`, `loader.start/end/error`,
+`handler.error`, `cache.decision`, and `revalidation.decision`.
+
+## Debugging revalidation and stale data
+
+When stale UI or unexpected partial renders are the question, use all three
+layers together:
+
+```typescript
+import { createConsoleSink, createRouter } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  debugPerformance: true,
+  telemetry: createConsoleSink(),
+});
+```
+
+Then inspect:
+
+- `revalidation.decision` telemetry to see which segment re-ran or skipped.
+- cache spans / `cache.decision` events to see hit, miss, stale, and background
+  revalidation behavior.
+- loader spans to confirm live loaders overlap the render rather than blocking
+  first paint.
+- the `Server-Timing` header to compare local logs with browser-network timing.
+
+## Zero-overhead defaults
+
+`debugPerformance` is off by default, and `telemetry` emits nothing unless a sink
+is configured. Per-request `ctx.debugPerformance()` lets you turn on the
+waterfall only for the route, user, or query param you are investigating.