@rangojs/router 0.0.0-experimental.138 → 0.0.0-experimental.139

package/skills/host-router/SKILL.md

@@ -33,6 +33,48 @@ export default {
 };
 ```
 
+## Deploying: Cloudflare vs node/vercel
+
+How a host router is _served_ depends on the preset, because the preset decides who owns the server entry.
+
+| Preset            | Who owns the entry          | What the host module exports                                                                                |
+| ----------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `cloudflare`      | You (your `worker.rsc.tsx`) | `export default { fetch(request, env, ctx) { return router.match(request, { env, ctx }); } }`               |
+| `node` / `vercel` | rango (generated RSC entry) | `export default router;` (the `HostRouter` instance itself), or a named `export const hostRouter`/`router`. |
+
+On `node`/`vercel`, rango generates the served RSC entry, so it needs the `HostRouter` **instance** to call `hostRouter.match()` for you. Export the instance, not a `{ fetch }` object:
+
+```typescript
+// src/worker.rsc.tsx  (node / vercel)
+import { createHostRouter } from "@rangojs/router/host";
+
+export const hostRouter = createHostRouter();
+hostRouter.host(["admin.*"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
+
+// Export the instance — the generated entry serves it via hostRouter.match().
+export default hostRouter;
+```
+
+Each sub-app exports a handler exactly as on Cloudflare (no change):
+
+```typescript
+// src/apps/admin/handler.ts
+import { router } from "./router.js";
+export default (request: Request, input: any) => router.fetch(request, input);
+```
+
+Selecting the host entry — a host app has several `createRouter()` sub-apps, so single-router auto-discovery can't pick one. Either let rango auto-detect the lone `createHostRouter()` file, or point at it explicitly:
+
+```typescript
+// vite.config.ts
+rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
+```
+
+On Vercel this is a single function running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model); `{ env, ctx }` (`process.env` + `{ waitUntil }`) is threaded unchanged to each matched sub-app's handler and `cache(env, ctx)` factory. See the `vercel` skill.
+
+Unmatched hosts on node/vercel: because rango owns the generated entry (you have no worker `try/catch`), it catches `NoRouteMatchError` and returns **404** by default — so you do **not** need a catch-all host route. If you want different behavior (a branded 404, a redirect, a default app), register a catch-all mount as the **last** route, e.g. `host(["**"]).lazy(() => import("./apps/site/handler.js"))` — it matches any host, so the built-in 404 only fires when nothing matched at all. (Note `fallback()` is for cookie-override errors, not general unmatched hosts.)
+
 ## Inline handlers (`.map`) vs lazy mounts (`.lazy`)
 
 A host pattern maps to one of two things, and you pick the method by intent:
@@ -134,17 +176,17 @@ router.fallback().map((request) => {
 });
 ```
 
-For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch:
+For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch. Use the `isNoRouteMatchError()` guard rather than a bare `instanceof`: a workspace with a duplicated `@rangojs/router` copy can throw the error with a different class identity, and `instanceof` would then turn the 404 into an opaque 500.
 
 ```typescript
-import { NoRouteMatchError } from "@rangojs/router/host";
+import { isNoRouteMatchError } from "@rangojs/router/host";
 
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     try {
       return await router.match(request, { env, ctx });
     } catch (err) {
-      if (err instanceof NoRouteMatchError) {
+      if (isNoRouteMatchError(err)) {
         return new Response("Not Found", { status: 404 });
       }
       throw err;

package/skills/layout/SKILL.md

@@ -147,12 +147,21 @@ A layout as a child of `path()` wraps the route content and can read
 data set by the route handler via `ctx.get()`. The handler always
 executes before its children.
 
-This handler-first guarantee applies to a single full render pass
-(initial render, prerender, or full HTML re-render). During partial
-action revalidation, only the segments that revalidate are recomputed.
-If an orphan layout depends on data established by an outer handler or
-layout, that outer segment must also revalidate, or the orphan must
-guard/reload the data independently.
+This is the recommended way to pass handler data downward, and it is
+safe under partial action revalidation with zero configuration: orphan
+layouts (and their parallels) belong to the route entry, and on an
+action the whole entry re-runs together by default — route segment,
+loaders, and `belongsToRoute` children all seed revalidate-true, with
+handler-first ordering preserved. Producer and consumer cannot desync
+unless you narrow one side with a predicate that returns a hard `false`
+(then put the same contract on both — see "Revalidation Contracts").
+
+Data from an **outer** handler or layout entry is the opposite case:
+outer entries do not revalidate on actions by default (parent-chain
+skip). If an orphan layout depends on data established above its own
+route entry, that outer segment must share a revalidation contract, or
+the orphan must guard/reload the data independently. See `/rango` →
+"Passing data down the tree" for the full safest-first ladder.
 
 ```typescript
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
@@ -191,7 +200,10 @@ orphan layouts to read them.
 
 ## Layout Revalidation
 
-Layouts don't revalidate by default. Control with `revalidate()`:
+Standalone `layout()` entries don't revalidate by default — on an action,
+parent-chain segments are skipped unless a `revalidate()` opts them in.
+(Orphan layouts inside a `path()` are the opposite: they ride along with
+the route entry by default.) Control with `revalidate()`:
 
 ```typescript
 layout(<ShopLayout />, () => [
@@ -218,8 +230,13 @@ their `ctx.set()` state.
 
 ### Revalidation Contracts
 
-For shared upstream data, define named revalidation functions and reuse
-them on both producer and consumer segments:
+Contracts are the tool for cross-entry sharing — the bottom rung of the
+data-passing ladder (`/rango` → "Passing data down the tree"). Before
+writing one, check whether the producer can move down a rung: into the
+consumer's own entry as an orphan layout, into middleware, or into a
+loader. When the data genuinely must flow from an outer entry, define
+named revalidation functions and reuse them on both producer and
+consumer segments:
 
 ```typescript
 // revalidation-contracts.ts

package/skills/middleware/SKILL.md

@@ -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.

package/skills/observability/SKILL.md

@@ -112,7 +112,29 @@ const router = createRouter({
 });
 ```
 
-Both factories return a `RouterTracingConfig` for the same `tracing` slot;
+On **Vercel Functions** (Node runtime), use `createVercelTracing` — a thin
+wrapper over `createOTelTracing` that reads the global OTel tracer
+`@vercel/otel`'s `registerOTel()` installs, so you do not call `trace.getTracer`
+yourself. Custom spans are Node-only (unsupported on the Edge runtime):
+
+```typescript
+// instrumentation.ts — install the provider, then export the tracing config.
+// Importing this module is what runs registerOTel() — a Rango/Vite app does not
+// auto-load instrumentation.ts like Next.js, so a standalone registerOTel() that
+// nothing imports is a silent no-op.
+import { registerOTel } from "@vercel/otel";
+import { createVercelTracing } from "@rangojs/router/vercel";
+registerOTel({ serviceName: "my-app" });
+export const tracing = createVercelTracing(); // { enabled, spans, tracerName, tracer }
+
+// router.tsx — importing `tracing` runs instrumentation.ts
+import { createRouter } from "@rangojs/router";
+import { tracing } from "./instrumentation.js";
+
+const router = createRouter({ document: Document, urls: urlpatterns, tracing });
+```
+
+These factories return a `RouterTracingConfig` for the same `tracing` slot;
 `telemetry` stays independent (events only, no phase spans). Phase spans:
 `rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
 `rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline

package/skills/parallel/SKILL.md

@@ -344,9 +344,17 @@ parallel(
 )
 ```
 
-Revalidating only the parallel does not re-run outer handlers/layouts.
-If the slot reads `ctx.get()` data established above it, opt the outer
-segment into revalidation as well.
+Where the slot sits decides its action default. A parallel under a
+`path()` (or one of its orphan layouts) belongs to the route entry and
+revalidates together with it on every action — handler-set data stays
+consistent with no configuration. A parallel under a standalone
+`layout()` entry follows the parent-chain default instead: skipped on
+actions unless a `revalidate()` opts it in.
+
+In either position, revalidating only the parallel does not re-run outer
+handlers/layouts. If the slot reads `ctx.get()` data established above
+it, opt the outer segment into revalidation as well (see `/rango` →
+"Passing data down the tree").
 
 A `revalidate()` callback may return a hard `boolean`, a soft
 `{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /

package/skills/rango/SKILL.md

@@ -59,22 +59,57 @@ appears, not up front.
 To decide where something can live: **does it define a URL? structure, stays in
 `urls()`. Does it modify a node? config, compose freely.**
 
+## Passing data down the tree
+
+Four ways to get per-request data to a segment below you, ordered safest-first.
+Reach for the next rung only when the one above doesn't fit — the higher rungs
+are immune to partial-revalidation staleness by construction.
+
+1. **A loader** (`loader()` + `useLoader()`). Loaders resolve fresh on every
+   pass — full renders, action revalidations, cache hits. Nothing to keep in
+   sync. If the data can be a loader, make it a loader.
+2. **Middleware `ctx.set()`**. Route middleware wraps every render pass,
+   including post-action revalidation and PE re-renders, so its variables are
+   never stale. Right for request-shaped context: auth, session, locale.
+3. **Handler `ctx.set()` to its own children** —
+   `path(handler, ..., () => [layout(...)])`. Orphan layouts and their
+   parallels belong to the route entry: on an action the whole entry re-runs
+   together by default (handler-first preserved), so the data stays consistent
+   with zero configuration. Right for data the page must compute anyway —
+   e.g. pagination, where the handler's search decides how many pages the
+   layout chrome renders. One rule: if you narrow the entry's revalidation
+   with a predicate that can return a hard `false`, put the same contract on
+   the entry's children too — a hard `false` on one side of a
+   producer/consumer pair desyncs it.
+4. **Cross-entry sharing** — an outer `layout()` entry feeding descendants.
+   Outer entries do NOT revalidate on actions by default (the revalidation
+   trace calls this `action:parent-chain-skip`), so this rung always requires
+   a shared revalidation contract: the same named `revalidate()` function on
+   the producer and every consumer. See `/layout` → "Revalidation Contracts".
+   Before writing one, check whether the producer can move down a rung.
+
+The failure mode this ladder prevents: a consumer re-runs, its producer
+doesn't, `ctx.get()` reads `undefined`, and fallback UI silently replaces good
+UI after an action. Rungs 1–3 make that unrepresentable; rung 4 makes it a
+stated, greppable contract.
+
 ## Pick a primitive
 
-| I need to…                            | Use                              | Skill                   |
-| ------------------------------------- | -------------------------------- | ----------------------- |
-| render data fresh every request       | `loader()` + `useLoader()`       | /loader                 |
-| cache a rendered subtree              | `cache()` on a segment           | /caching                |
-| cache one function/component's result | `"use cache"`                    | /use-cache              |
-| cache a loader's data                 | `loader(L, () => [cache()])`     | /loader, /caching       |
-| re-render a segment after an action   | `revalidate()`                   | /loader                 |
-| mutate                                | `"use server"` action            | /server-actions         |
-| debug a slow request                  | `debugPerformance` / telemetry   | /observability          |
-| share config across routes            | factory returning a helper array | /composability          |
-| compose a sub-app / module            | `include()`                      | /route                  |
-| modal / soft navigation               | `intercept()`                    | /intercept              |
-| pre-render a route at build time      | `Prerender(...)` wrapper         | /prerender              |
-| stream SSE / upgrade a WebSocket      | `path.stream()` / `path.any()`   | /streams-and-websockets |
+| I need to…                            | Use                                | Skill                   |
+| ------------------------------------- | ---------------------------------- | ----------------------- |
+| render data fresh every request       | `loader()` + `useLoader()`         | /loader                 |
+| cache a rendered subtree              | `cache()` on a segment             | /caching                |
+| cache one function/component's result | `"use cache"`                      | /use-cache              |
+| cache a loader's data                 | `loader(L, () => [cache()])`       | /loader, /caching       |
+| re-render a segment after an action   | `revalidate()`                     | /loader                 |
+| mutate                                | `"use server"` action              | /server-actions         |
+| debug a slow request                  | `debugPerformance` / telemetry     | /observability          |
+| share config across routes            | factory returning a helper array   | /composability          |
+| compose a sub-app / module            | `include()`                        | /route                  |
+| modal / soft navigation               | `intercept()`                      | /intercept              |
+| pre-render a route at build time      | `Prerender(...)` wrapper           | /prerender              |
+| feed live loaders from a cached shell | replayed handle + `ctx.rendered()` | /shell-manifest         |
+| stream SSE / upgrade a WebSocket      | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
 
@@ -185,6 +220,12 @@ resolve `dist/` outside `./vite`, and it may lag `src/`.
 
 Grouped by concern — read when you need to…
 
+**Positioning & evaluation**:
+
+| Skill         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `/comparison` | Compare Rango with Next.js, TanStack Start, and Waku fairly. |
+
 **Structure & routing** — shape URLs, layouts, navigation, and request processing:
 
 | Skill                     | Description                                                                |
@@ -206,15 +247,16 @@ Grouped by concern — read when you need to…
 
 **Data & caching** — fetch, mutate, and cache:
 
-| Skill             | Description                                                             |
-| ----------------- | ----------------------------------------------------------------------- |
-| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                   |
-| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation |
-| `/caching`        | Segment caching with memory or KV stores                                |
-| `/use-cache`      | Function-level caching with `"use cache"` directive                     |
-| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide |
-| `/document-cache` | Edge caching with Cache-Control headers                                 |
-| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)     |
+| Skill             | Description                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `/loader`         | Data loaders with `createLoader()` and `revalidate()`                                      |
+| `/server-actions` | Mutations with `"use server"`, useActionState, validation, revalidation                    |
+| `/caching`        | Segment caching with memory or KV stores                                                   |
+| `/use-cache`      | Function-level caching with `"use cache"` directive                                        |
+| `/cache-guide`    | When to use `cache()` vs `"use cache"` — differences and decision guide                    |
+| `/document-cache` | Edge caching with Cache-Control headers                                                    |
+| `/prerender`      | Pre-render route segments at build time (Passthrough live fallback)                        |
+| `/shell-manifest` | Replayed handles as cache metadata read by live loaders (frozen shell, batched live holes) |
 
 **Client & presentation** — build the client-side UX:
 
@@ -239,6 +281,12 @@ Grouped by concern — read when you need to…
 | `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
 | `/debug-manifest`  | Inspect route manifest structure                                         |
 
+**Deployment**:
+
+| Skill     | Description                                                                               |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `/vercel` | Deploy to Vercel Functions (`preset: "vercel"`), Runtime Cache, and `createVercelTracing` |
+
 **Testing**:
 
 | Skill      | Description                                                                                                                     |

package/skills/route/SKILL.md

@@ -154,6 +154,13 @@ first. Use `ctx.set(key, value)` to share data with children, who read it
 via `ctx.get(key)`. Caching wraps all segments together, so either all run
 or none do.
 
+This pattern is also safe under partial action revalidation: on an action,
+the route entry re-runs as a unit by default — route segment, loaders, and
+`belongsToRoute` children (orphan layouts, entry parallels) all seed
+revalidate-true, with handler-first ordering preserved. Handler-set data
+stays consistent with no configuration. See `/rango` → "Passing data down
+the tree" for the safest-first ladder.
+
 ### Typed context variables with createVar
 
 Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
@@ -240,9 +247,18 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 > decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
 > `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
 
-Handler-first guarantees apply within a single full render pass. For partial
-action revalidation, define named revalidation contracts and reuse them on both
-the producer route and the consumer child segments.
+With no `revalidate()` configured, an entry needs no contract: on an action
+the route handler and its children re-run together by default, so handler
+data stays consistent on its own. Contracts matter in two cases:
+
+1. **You narrow the entry's revalidation** with a predicate that can return a
+   hard `false` (e.g. bare `ctx.isAction(X)`). A hard `false` on one side of a
+   producer/consumer pair desyncs it — the child re-runs by default and reads
+   `undefined`, or vice versa. Put the same named contract on the route and
+   its dependent children so they narrow together.
+2. **The producer is an outer entry** (a standalone `layout()` above this
+   route). Outer entries skip action revalidation by default, so the shared
+   contract is mandatory — see `/layout` → "Revalidation Contracts".
 
 ```typescript
 // revalidation-contracts.ts

package/skills/router-setup/SKILL.md

@@ -505,6 +505,7 @@ const router = createRouter({
 ```typescript
 // On Cloudflare Workers, swap the tracing factory for native custom spans
 // (no @opentelemetry/api dependency); the telemetry slot is unchanged.
+// On Vercel (Node runtime) use createVercelTracing() from @rangojs/router/vercel.
 import { createCloudflareTracing } from "@rangojs/router/cloudflare";
 
 const router = createRouter({

package/skills/shell-manifest/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: shell-manifest
+description: Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices
+argument-hint:
+---
+
+# Shell Manifest — cache metadata for live loaders
+
+Use this when a cached or prerendered shell has dynamic holes, and the live
+data layer needs to know **what the shell actually contains** — which
+products, which slots, which keys. The frozen render describes itself
+through a handle; loaders (always live) read that description and fetch
+exactly the dynamic data the shell needs, in one batch.
+
+Canonical case: a prerendered product list where prices must stay live.
+
+## The problem this solves
+
+Any cached-shell-plus-live-holes design has a coordination gap: how does the
+live layer know what the holes need?
+
+- **Per-hole fetching** (each `<Price>` component fetching for itself) is the
+  N+1 default — N visible products, N queries.
+- **A loader that re-queries the list** ("current top products") drifts from
+  a stale shell — right prices attached to wrong products.
+
+The shell manifest closes the gap with a consistency guarantee: the loader
+reads the ids the shell _actually rendered_, replayed from the same stored
+artifact, so the holes can never desync from the shell and the query is
+batched.
+
+## The mechanism (three features composed)
+
+1. **Handles record data at render time.** The handler pushes to a handle
+   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on
+   the cache miss for `cache()`.
+2. **Replay on every hit.** Handle data is stored with the Flight payload
+   and replayed into the handle store on cache/prerender hits — handler code
+   does not re-run, but its pushes do.
+3. **Loaders read after the render barrier.** A DSL loader can
+   `await ctx.rendered()` (waits for all non-loader segments to settle —
+   fresh render or replay alike), then `ctx.use(Handle)` returns the
+   **collected** handle data.
+
+Loaders are live by default, so the read happens on every request even when
+the shell is a hit.
+
+## Canonical example: prerendered list, live prices
+
+```tsx
+// handles/rendered-products.ts
+import { createHandle } from "@rangojs/router";
+
+// TData = string (one push per product id), collected to a flat string[]
+export const RenderedProducts = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
+```
+
+```tsx
+// routes/products.tsx — the list is baked at build time; prices are not
+import { Prerender } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+import { Price } from "../components/price";
+
+export const ProductList = Prerender(
+  async () => [{ category: "espresso" }, { category: "filter" }],
+  async (ctx) => {
+    const products = await db.productsByCategory(ctx.params.category);
+    const track = ctx.use(RenderedProducts);
+    for (const p of products) track(p.id);
+    return (
+      <ul>
+        {products.map((p) => (
+          <li key={p.id}>
+            {p.name} <Price id={p.id} />
+          </li>
+        ))}
+      </ul>
+    );
+  },
+);
+```
+
+```ts
+// loaders/prices.ts — one batched query for exactly the rendered products
+import { createLoader } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+
+export const PriceLoader = createLoader(async (ctx) => {
+  "use server";
+  await ctx.rendered();
+  const ids = ctx.use(RenderedProducts);
+  return db.pricesFor(ids); // Map<string, number> keyed by product id
+});
+```
+
+```tsx
+// urls.tsx — wire the route and register the loader
+path("/products/:category", ProductList, { name: "products" }, () => [
+  loader(PriceLoader),
+]);
+```
+
+```tsx
+// components/price.tsx — live hole in the frozen shell
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import { PriceLoader } from "../loaders/prices";
+
+export function Price({ id }: { id: string }) {
+  const { data } = useLoader(PriceLoader);
+  return <span>{formatPrice(data[id])}</span>;
+}
+```
+
+Request flow on a hit: stored payload replays (handler never runs) → handle
+data lands in the store → render barrier resolves → `PriceLoader` reads the
+replayed ids → one query → prices stream into `<Price>` components.
+
+## Works with runtime cache() too
+
+`Prerender` is build-time caching; the replay mechanism is identical for the
+runtime segment cache. Wrap the route in `cache()` instead and the handler
+pushes on the miss, replays on every hit:
+
+```tsx
+cache({ ttl: 600, tags: ["products"] }, () => [
+  path("/products/:category", ProductList, { name: "products" }, () => [
+    loader(PriceLoader),
+  ]),
+]);
+```
+
+## Contract and gotchas
+
+- **The manifest is exactly as fresh as the shell.** Replayed handle data is
+  frozen with the payload. To change _which_ products render, invalidate the
+  shell (`updateTag("products")`, TTL expiry, rebuild) — never treat the
+  loader as the refresh path for the list itself. This is the point:
+  shell and holes cannot desync because they share one artifact.
+- **No request-scoped data in a manifest handle.** The handle data is baked
+  into a shared artifact — the same cross-user rule as any cached content.
+  Ids, slugs, slot names, variant keys: yes. Anything derived from
+  `cookies()`/`headers()`: no.
+- **`ctx.rendered()` is experimental and DSL-loaders-only.** It throws in
+  fetchable/standalone loader calls that run outside a route render.
+- **The reading loader serializes after the shell.** `await ctx.rendered()`
+  deliberately gives up loader/render parallelism — on a miss the loader
+  waits for segment resolution; on a hit (the common case for a cached
+  shell) replay is immediate and the wait is negligible. A
+  `debugPerformance` waterfall shows this loader after the render bar; for
+  this pattern that is the contract, not a regression.
+- **`ctx.use(Handle)` before `await ctx.rendered()` throws** in a loader,
+  with an error saying to await the barrier first.
+- **Deferred handle values are resolved before storage** (resolve-by-default),
+  so the manifest read always sees plain values, never promises.
+
+## Testing
+
+`runLoader` seeds the barrier and the collected handle value directly —
+matched by handle reference (the same seeding style as loader deps):
+
+```ts
+import { runLoader } from "@rangojs/router/testing";
+
+const prices = await runLoader(PriceLoader, {
+  rendered: true,
+  handles: [[RenderedProducts, ["widget-a", "widget-b"]]],
+  env: { DB: fakeDb },
+});
+```
+
+This tests the loader's post-barrier logic. The real
+push → store → replay → barrier wiring is covered at the e2e tier (dev +
+production), like every cache-path behavior.
+
+## Related
+
+- `/prerender` — `Prerender`/`Passthrough`, build flow, passthrough fallback
+- `/caching` — segment `cache()`, stores, tags
+- `/loader` — loader context, `ctx.rendered()`, streaming
+- `/hooks` — `useHandle` for reading handle data in client components
+- `/rango` → "Passing data down the tree" — this pattern is the frozen→live
+  counterpart of that ladder