@rangojs/router 0.16.0 → 0.18.0

package/skills/defer-hydration/SKILL.md

@@ -15,7 +15,7 @@ storefront homepage (shell HIT, production build, M-series laptop): a single
 was dead for ~11s. Fast paint, frozen page.
 
 The obvious fix — wrap the heavy subtree in `<Suspense>` so it hydrates later —
-trades the paint away: under shell capture that boundary postpones, and the
+can trade the paint away: when that boundary postpones under shell capture, the
 frozen prelude ships an empty `<main>`. This recipe gets both: the full body
 HTML in the prelude AND its hydration off the initial task, released on first
 idle at retry-lane priority.
@@ -28,11 +28,14 @@ idle at retry-lane priority.
 | interactive (menu click works)   | ~3.5s    | ~1.6s                            | ~1.6s                     |
 
 Measure your own page before and after — the win depends on how much of the
-hydration cost lives under the boundary (see "Verifying and measuring").
+hydration cost lives under the boundary (see "Verifying and measuring"). These
+numbers were measured before PPR captures baked handler output; see the next
+section for what that changed.
 
 ## The recipe
 
-~40 lines, plain React, no rango imports — copy it into your app:
+About 50 lines of plain React, no rango imports. Copy it into a client module in
+your app:
 
 ```tsx
 "use client";
@@ -101,23 +104,39 @@ inside hydrates after first idle.
 
 ## Why `fallback={children}` is load-bearing
 
-This is not a style choice; it is the half of the recipe that makes it
-PPR-compatible.
-
-Shell capture aborts on flight byte-quiet (`src/rsc/shell-capture.ts`,
-`FLIGHT_QUIET_HOPS`): once the Flight source has been byte-silent for the
-quiet window, the fizz render freezes. A big HTML subtree under _any_
-`<Suspense>` boundary cannot finish inside that window, so the boundary always
-postpones — boundary placement cannot fix it. Verified both ways: wrapping the
-client island from outside AND placing the boundary inside the island both
-baked `<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the
-frozen prelude.
-
-With the content as the fallback, the unavoidable postpone _becomes the
-delivery mechanism_: the shell bakes the fallback, and the fallback IS the
-body. In `/ppr` hole-doctrine terms, this is the PHYSICS class exploited
-deliberately — you cannot stop the boundary from becoming a hole, so you make
-the hole's baked fallback carry the real markup.
+This is not a style choice. The recipe was built when the shell capture
+postponed any big `<Suspense>` subtree: the capture froze on Flight byte-quiet
+(`FLIGHT_QUIET_HOPS` in `src/rsc/shell-capture.ts`) while the handler output
+was still rendering, so a boundary over the page body became a hole no matter
+where it sat. Verified both ways at the time: wrapping the client island from
+outside AND placing the boundary inside the island both baked
+`<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the frozen
+prelude. With the content as the fallback, the postpone became the delivery
+mechanism: the shell baked the fallback, and the fallback was the body.
+
+PPR captures now wait for the whole handler layer before freezing anything:
+the capture records the page's segments first (async server components
+rendered, every promise in the handler output settled) and renders its Flight
+payload from that record (`settleCaptureRecord` in `src/rsc/shell-capture.ts`).
+A boundary whose content is only handler output is therefore expected to bake
+its content as a completed boundary instead of postponing. What still
+postpones at capture is a boundary over live data: a loader without
+`ssr: false` read with `useLoader` under `loading()` or an inline
+`<Suspense>`, or a promise nested in an `ssr: false` loader's value. Run the
+prelude check in "Verifying and measuring" on your page rather than assuming
+either shape.
+
+`fallback={children}` stays the safe choice either way:
+
+- If the boundary still postpones (live data inside it), the fallback is what
+  the prelude shows, so it must be the content.
+- The sync-update trap below: a client render of the boundary shows the
+  fallback. With `fallback={children}` that is a visual no-op; with
+  `fallback={null}` it blanks the page.
+
+The hydration deferral does not depend on which shape you get: `HydrationGate`
+suspends during hydration, and React keeps the server DOM of the boundary in
+place until the gate releases.
 
 ## Why the client gate is free
 
@@ -163,13 +182,14 @@ release on interaction instead (see Variations).
 
 ## Known cost: the body rides twice (measure it, don't guess)
 
-On a shell HIT the gated subtree's HTML is in the response twice — once as the
-baked fallback in the prelude, once as the resumed hole content (the resume
-re-renders and re-ships it; there is no bake-through). Homepage measurement:
-234KB → 302KB gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth,
-not render-blocking — the visible prelude streams first — but it is real bytes
-on every document GET. Weigh it per page; on a small body the recipe may not
-pay for itself.
+When the boundary postpones at capture, a shell HIT carries the gated
+subtree's HTML twice — once as the baked fallback in the prelude, once as the
+resumed hole content (the resume re-renders and re-ships it; there is no
+bake-through). Homepage measurement (postponing boundary): 234KB → 302KB
+gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth, not
+render-blocking — the visible prelude streams first — but it is real bytes on
+every document GET. Weigh it per page; on a small body the recipe may not pay
+for itself. A boundary that bakes its content ships it once.
 
 ## Verifying and measuring
 
@@ -229,7 +249,8 @@ this exact space. The recipe survives that future; a primitive might not.
 
 ## Related
 
-- `/ppr` — the shell/hole mechanics this recipe rides on (hole doctrine:
-  PHYSICS class), and why the capture postpones any big Suspense subtree
-- `src/rsc/shell-capture.ts` — the byte-quiet capture window
-  (`FLIGHT_QUIET_HOPS`) that makes `fallback={children}` mandatory
+- `/ppr` — the shell/hole mechanics this recipe rides on: what bakes into the
+  shell, and which boundaries stay holes
+- `src/rsc/shell-capture.ts` — the record-first capture (`settleCaptureRecord`)
+  and the byte-quiet window (`FLIGHT_QUIET_HOPS`) that decide what the prelude
+  holds

package/skills/deployment-caching/SKILL.md

@@ -10,6 +10,9 @@ Start with one question: **does the request reach Rango before shared bytes are
 served?** That boundary decides whether middleware runs, whether loaders stay
 live, and which invalidation system owns the result.
 
+This skill is about where each cache sits relative to your deployment platform.
+To choose between the in-app layers themselves, start at `/cache-guide`.
+
 ## The execution matrix
 
 | Mechanism                         | Stored artifact                                 | Function/worker runs on a hit? |                                   Rango middleware on a hit? | What stays live?                     |
@@ -53,8 +56,11 @@ There are two shell producers:
 Both producers feed the same in-function serve path. Build-time shells are
 content-hashed modules in the server bundle, not CDN-served HTML files.
 
-`ppr.ttl`, `ppr.swr`, and `ppr.tags` govern that shell entry. They do **not**
-emit HTTP `Cache-Control` and do not configure a platform CDN.
+`ppr.ttl` and `ppr.swr` set the shell entry's lifetime, capped by the route
+`cache()` entry it was captured from (the shorter wins). Its tags are
+`ppr.tags` plus the tags its content recorded. A route `cache({ key })` or a
+store `keyGenerator` stores one shell per partition value. None of this emits
+HTTP `Cache-Control` or configures a platform CDN.
 
 ## Platform deployment shapes
 
@@ -173,4 +179,6 @@ provably public and shared.
 - `/document-cache` — store-backed complete-response middleware
 - `/vercel` — Vercel Build Output preset and Runtime Cache wiring
 - `/cloudflare` — Worker deployment and bindings
-- `/cache-guide` — function, loader, and segment cache selection
+- `/cache-guide` — choosing between the in-app cache layers
+- `/caching` — `cache()` segments, stores, and tag invalidation
+- `/use-cache` — function-level `"use cache"`

package/skills/document-cache/SKILL.md

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

package/skills/fonts/SKILL.md

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

package/skills/handler-use/SKILL.md

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