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

package/skills/links/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse. Use when generating a link to a route by name instead of hardcoding a path, or a link breaks after routes move or get mounted elsewhere.
 argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 ---
 
@@ -38,6 +38,18 @@ export const shopPatterns = urls(({ path, layout }) => [
 - **`.name`** — local route, resolved within the current `include()` scope
 - **`name`** — global route, from the named-routes definition
 
+The include site decides which global names exist:
+
+| Include site                                       | App-wide names                                     |
+| -------------------------------------------------- | -------------------------------------------------- |
+| `include("/shop", shopPatterns)`                   | none from the child; use `.name` inside the module |
+| `include("/shop", shopPatterns, { name: "shop" })` | `shop.index`, `shop.product`, ...                  |
+| `include("/shop", shopPatterns, { name: "" })`     | `index`, `product`, ... at the parent scope        |
+
+Flatten only when those names are intentionally unique across the whole parent
+map. Private includes are useful for reusable modules and still support
+mount-aware dot-local reversal.
+
 ```typescript
 // Inside a handler within shopPatterns (mounted at /shop)
 path("/product/:slug", (ctx) => {
@@ -411,6 +423,30 @@ Don't edit the file by hand — re-run codegen when patterns change.
 }
 ```
 
+## Prefetch boundaries
+
+`Link` follows its `prefetch` prop or the router's `defaultPrefetch`; eligible
+plain anchors follow the router default. When a whole DOM section must never
+speculate, mark its container instead of repeating per-link opt-outs:
+
+```tsx
+<section data-prefetch-scope="none">
+  <Link to="/activity" prefetch="viewport">
+    Activity
+  </Link>
+  <a href="/export">Export</a>
+</section>
+```
+
+The scope is a hard opt-out for every descendant Link and plain anchor; `"false"`
+and `"none"` are equivalent. An explicit `prefetch` prop or
+`data-prefetch="true"` cannot override it, and navigation still works normally.
+Use `data-prefetch="false"` or `"none"` directly on a plain anchor when only that
+anchor is unsafe. Dynamic scope changes re-evaluate only descendant anchors and
+mounted viewport/render Links. Links share one document-level scope observer,
+not one observer per Link or container. Adding a scope cannot recall work already
+queued or in flight; removing it re-arms both Link types.
+
 ## When to use what
 
 | Context          | API                                                | Resolves                                  | Use for                                                          |

package/skills/loader/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loader
-description: Define data loaders for fetching data in routes with createLoader
-argument-hint: [loader]
+description: Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (ssr:false).
+argument-hint: "[loader]"
 ---
 
 # Data Loaders with loader()
@@ -11,6 +11,13 @@ Loaders fetch data on the server and stream it to the client. For mutations
 `/server-actions`. Loaders re-resolve after an action runs, so the typical
 flow is _action mutates → loader re-reads → UI updates_.
 
+## Not this skill if…
+
+- You want to mutate state — mutations are `"use server"` actions: see
+  `/server-actions`. Loaders read per-request live data.
+- You want to cache a function's return value — loaders are fresh every request
+  by default; caching one function is `"use cache"`: see `/use-cache`.
+
 ## Creating a Loader
 
 ```typescript
@@ -140,6 +147,11 @@ same memoized result — loaders never run twice per request.
 - The handler output depends on the loader data. If the route is inside
   `cache()`, the handler is cached with the loader result baked in —
   defeating the live data guarantee.
+- The same holds under a PPR shell capture (`/ppr`): handler consumption is
+  the BAKED lane — the loader executes at capture (identity reads permitted)
+  and the rendered value is a capture-time copy; `useLoader` client-side is
+  the live lane. One rule across `cache()`, `"use cache"`, and PPR: the
+  consumption-lane rule (`/rango` → Invariants).
 - Non-cacheable variable reads (`createVar({ cache: false })`) inside the
   handler still throw, even if the data came from a loader.
 - Prefer DSL `loader()` + client `useLoader()` for data that depends on
@@ -160,23 +172,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 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).                                                                  |
+| 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 \| handle)` | Reads middleware variables/context-vars — or READS a handle's collected data, after `await ctx.rendered()`.                                                                                    |
+| `use`          | `(loader \| handle) => T`       | Access another loader's data (Promise), or WRITE a handle: `ctx.use(Meta)({ title })` returns the push function — handler parity. Reads moved to `get`.                                        |
+| `rendered`     | `() => Promise<void>`           | **Experimental.** DSL loaders only — waits for all non-loader segments (including `loading()` streaming handlers) to settle before reading handle data. Not with `ssr: false` (cycle; throws). |
+| `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
 
@@ -430,7 +442,10 @@ 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.
+response starts streaming first and loader data fills in. (The one deliberate
+exception is per-loader: `loader(Def, { ssr: false })` awaits that
+loader before first flush on document renders — see "`ssr: false`"
+below.)
 
 ### See it: `debugPerformance`
 
@@ -648,6 +663,131 @@ function ProductPage() {
 }
 ```
 
+## Loader Authority: notFound() and redirect()
+
+A loader may **throw** `notFound()` and `redirect()` — data-dependent
+authority lives with the data, so every consumer of the loader inherits the
+signal instead of re-checking existence at each read site:
+
+```typescript
+import { createLoader, notFound, redirect } from "@rangojs/router";
+
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const moved = LEGACY_SLUGS[ctx.params.slug];
+  if (moved) throw redirect(`/shop/product/${moved}`);
+
+  // Existence check BEFORE the expensive fetch: a near-instant rejection
+  // usually wins the race to first flush (see the semantics below).
+  if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);
+
+  return getProduct(ctx.params.slug);
+});
+```
+
+Semantics by lane:
+
+| Signal       | Document load                                                                                                                                                                                                                                               | Client navigation                                 |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `ssr: false` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
+| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                         | Redirect envelope navigates to the target         |
+
+Session/auth gates belong in middleware (they are request-shaped, not
+data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
+"this slug moved / does not exist" belongs in the loader.
+
+## Writing Handles from Loaders (meta, breadcrumbs)
+
+Loader bodies can WRITE handles with handler parity — `ctx.use(Handle)`
+returns the push function, legal for the whole body, streaming loaders
+included. This is how data-derived page titles and breadcrumb trails live
+where the data lives:
+
+```typescript
+import { Meta, Breadcrumbs } from "./handles";
+
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const product = await getProduct(ctx.params.slug);
+
+  ctx.use(Meta)({ title: `${product.name} — Shop` });
+  const pushCrumb = ctx.use(Breadcrumbs);
+  pushCrumb({ label: "Shop", href: "/shop" });
+  pushCrumb({ label: product.name, href: `/shop/product/${product.slug}` });
+
+  return product;
+});
+```
+
+Delivery is async **by the race model**: pushes that settle before the handler
+barrier ride the SSR handle snapshot (in the SSR'd document — `<MetaTags />`,
+`useHandle` reads); later pushes stream to the client and apply post-hydration
+on document loads (`metadata.handlesLate`) or progressively on navigations.
+A push before your slow fetch usually beats the barrier; a push derived from
+the fetched data usually does not. When it MUST be in the document, use
+`ssr: false` below.
+
+Reads are the other direction and gated: `ctx.get(handle)` throws unless the
+loader first does `await ctx.rendered()` (DSL-registered loaders only —
+handler-invoked loaders cannot use `rendered()`, and a handler already
+awaiting the loader via `ctx.use()` makes it a detected deadlock).
+
+## `ssr: false` — Guarantee a Loader in the Document
+
+Streaming means nothing a slow loader produces is _guaranteed_ in the SSR'd
+HTML: its section SSRs as the fallback, a late handle push applies
+post-hydration, a late `notFound()` loses the status race. When the loader
+feeds something that must exist in the document — `<head>` meta via a handle,
+or a real 404 status — pass delivery options between the definition and the
+use callback:
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader, { ssr: false }, () => [cache({ ttl: 60 })]),
+  loader(RelatedLoader),   // untouched: still streams behind its boundary
+]),
+```
+
+The knob mirrors `loading(fallback, { ssr: false })` — SSR delivery is off
+for this loader, so nothing of it is left to stream in the document:
+document renders await this loader before first flush — data is settled
+(`useLoader` reads it synchronously, no fallback paints), handle pushes beat
+the barrier snapshot, and a thrown `notFound()` deterministically precedes
+Response construction (real 404, no warm-up race). Client navigations stream
+exactly as before. Scoped per LOADER: the flagged loader awaits only itself;
+siblings keep streaming.
+
+Delivery is in-place, not merely in-document. React's Fizz outlines any
+COMPLETED Suspense boundary over ~500 bytes to an end-of-stream
+`<div hidden>` + `$RC()` reveal once the shell saturates its 12800-byte
+`progressiveChunkSize` budget — the bytes are in the HTML, but not at their
+document position, and a consumer that doesn't execute scripts never sees
+them revealed. When the matched chain has a flagged loader, the document
+render raises the budget to `MAX_SAFE_INTEGER` automatically, so the awaited
+content renders where it belongs. Pin the budget yourself (in either
+direction) with `rango({ progressiveChunkSize })` in the Vite config — an
+explicit value disables the auto-raise. Boundaries hoisting stylesheets
+still outline; their reveal must wait for the CSS.
+
+The costs and constraints:
+
+- Every document load pays the flagged loader's latency before first byte.
+  That is the point — but keep flagged loaders fast, and flag loaders, not
+  routes.
+- A flagged loader must not `await ctx.rendered()` / `ctx.get(handle)` — the
+  document render awaits the loader before the render barrier resolves, so
+  that wait is a cycle by construction; it throws a deadlock error naming the
+  fix.
+- PPR capture is the BAKE lane for flagged loaders (`/ppr`): the capture
+  render awaits them too, and the settled result — handle pushes included —
+  freezes into the stored shell. Unflagged loaders stay masked as live
+  holes. The `progressiveChunkSize` auto-raise is live-document only;
+  captured shells outline per the explicit option or React's default.
+
+Also available in `clientUrls()` route groups (`/client-urls`), where the
+loader-heavy shape makes it most useful. `LoaderOptions` is exported from the
+package root.
+
 ## Fetchable Loaders
 
 By default, loaders only run during SSR and navigation. Pass `true` as the second
@@ -671,6 +811,16 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+> **No registration needed — and no worker-entry import.** A fetchable loader
+> does not have to be registered with `loader()` in the route DSL, and it does
+> not have to be imported by any server module. Importing it into the client
+> component that calls `useFetchLoader()` / `load()` is enough. Rango discovers
+> every `createLoader(fn, true)` at build time and registers it for the
+> `_rsc_loader` endpoint, so a loader reachable only through a client component
+> still resolves in production — on both the generated entry and a hand-written
+> worker entry (e.g. a Cloudflare `worker.rsc.tsx`). You do **not** need to
+> force-import the loader in your worker entry to make it resolve.
+
 ### Fetchable Loader with Middleware
 
 Pass an options object instead of `true` to attach per-loader middleware.

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define middleware for authentication, logging, and request processing in @rangojs/router
+description: Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.
 argument-hint: [middleware-name]
 ---
 
@@ -60,8 +60,12 @@ data itself.
 ### Revalidation Contracts with Middleware-Backed Trees
 
 Middleware can establish request-level context (`ctx.set`) for segments that
-execute in the current render pass. It does not change partial revalidation
-boundaries between handler/layout/parallel segments.
+execute in the current render pass. Because route middleware wraps **every**
+render pass — normal renders, post-action revalidation, PE re-renders — its
+variables are never stale: middleware is the safest `ctx.set` rung on the
+data-passing ladder (`/rango` → "Passing data down the tree"). But it does
+not change partial revalidation boundaries between handler/layout/parallel
+segments.
 
 For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.
@@ -193,6 +197,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.request; // Request object
   ctx.url; // Parsed URL
   ctx.params; // Route parameters
+  ctx.build; // in middleware: true only during Prerender + ppr build-shell capture (plain Prerender does not run middleware)
 
   // Access platform bindings (plain bindings from createRouter<TEnv>())
   ctx.env.DB; // D1Database
@@ -201,6 +206,9 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
+  // Opt the current request out of PPR shell lookup/capture.
+  ctx.dynamic();
+
   // Continue to next middleware/handler
   await next();
 
@@ -242,6 +250,35 @@ This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
 via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
 data; use Rango.Vars for app-wide middleware state.
 
+## Build-Time PPR Middleware
+
+Normal `Prerender` Flight payload collection does not run middleware: there is
+no request to wrap. The exception is `Prerender` + `ppr` build-shell capture.
+After the Flight payload exists, the shell producer replays global and route
+middleware for each generated URL before it captures HTML.
+
+In that build-shell pass:
+
+- `ctx.build === true`;
+- `ctx.waitUntil()` is inert;
+- `ctx.dynamic()` skips the baked shell for that URL;
+- context variables set by middleware are visible to the shell render.
+
+Use this to keep side effects predictable:
+
+```typescript
+export const commerceMiddleware: Middleware = async (ctx, next) => {
+  if (ctx.build) {
+    ctx.dynamic(); // leave this shell to runtime PPR
+    return next();
+  }
+
+  const session = await commerce.auth(ctx.request);
+  ctx.set("session", session);
+  return next();
+};
+```
+
 ## Redirect with State in Middleware
 
 ```typescript