@rangojs/router 0.34.1 → 0.35.0

package/skills/breadcrumbs/SKILL.md

@@ -102,11 +102,11 @@ Two pushes from one segment accumulate in push order (`Shop › product`).
 Delivery follows the loader race model: a push that beats the handler barrier
 is in the SSR'd document; a push after a slow fetch streams and applies
 client-side (`useHandle` re-renders when it lands). To guarantee document
-delivery, register the loader as `loader(Def, { ssr: false })` —
+delivery, register the loader as `loader(Def, { ssr: "await" })` —
 see `/loader` → "Writing Handles from Loaders". On a `ppr` route the race is
-decided at capture: a loader without `ssr: false` never runs there, so its
+decided at capture: a loader without `ssr: "await"` never runs there, so its
 crumb is not in the shell and applies client-side on every HIT; with
-`ssr: false` the crumb bakes into the shell (`/ppr` → "On a shell HIT").
+`ssr: "await"` the crumb bakes into the shell (`/ppr` → "On a shell HIT").
 Under `cache()` loader crumbs are not stored with the cached segments; the
 loader re-pushes them on every hit, so they appear once even without an `href`.
 A loader with its own `cache()` keeps its crumbs on its own hits too: they are
@@ -147,7 +147,7 @@ in a `ppr` shell it is stored resolved: the cache write, or the shell capture
 (within `ppr.captureTimeout`), waits for a `content` promise and for a
 `.defer()` slot (below), and every HIT replays the crumb as it was resolved
 then, without running the handler. For per-request crumb content, push it
-from a loader without `ssr: false` (see "Pushing from Loaders").
+from a loader without `ssr: "await"` (see "Pushing from Loaders").
 
 ### Deferred content (decide now, resolve from a deep component)
 
@@ -211,7 +211,7 @@ swap in — no blank, no pending entry. The hold-then-swap is deliberate: a hand
 undefined, the entry is simply dropped. Use `.defer()` only when even
 `label`/`href` are unknown at handler time AND the producer is a component,
 not a loader — a loader-produced crumb pushes directly from the loader body
-(add `{ ssr: false }` if it must be in the SSR'd document), and if
+(add `{ ssr: "await" }` if it must be in the SSR'd document), and if
 you know `label`/`href` and only the `content` is async, push a concrete item
 with a `Promise` `content` field instead (the `content` field is a nested
 promise you resolve with `use()` in your component; no `.defer()` needed).

package/skills/cache-guide/SKILL.md

@@ -38,7 +38,7 @@ Quick rules:
   CDN caching (`/deployment-caching`).
 - A value that must be fresh on **every** request → a loader (never cached
   unless you opt in), read with `useLoader()`; on a `ppr` route, keep it off
-  `ssr: false`. A handler inside a `cache()` or `ppr` boundary that awaits
+  `ssr: "await"`. A handler inside a `cache()` or `ppr` boundary that awaits
   `ctx.use(Loader)` renders the value it got on the miss, and every hit
   replays that output.
 
@@ -161,7 +161,7 @@ The `ppr` shell capture has its own, stricter guard: `cookies()`, `headers()`,
 `ctx.request.headers`, a theme read, a `{ cache: false }` variable read, and
 `ctx.dynamic()` refuse the
 capture anywhere it waits — handlers, promises they pass or push, async server
-components, `ssr: false` loaders, and loaders a handler awaits (no loader
+components, `ssr: "await"` loaders, and loaders a handler awaits (no loader
 exemption there). The route then serves uncached; see `/ppr`.
 
 ### Cross-deploy safety: version-segmented store keys
@@ -490,7 +490,7 @@ So `"use cache: short"` (60s) inside `cache({ ttl: 600 })` yields ~600s freshnes
 on hits, **not** 60s. This is not a bug: setting `cache({ ttl: 600 })` declares
 "this subtree may be ~600s stale." **If a value must be fresher than its
 enclosing segment, put it in a loader** read with `useLoader()` (without
-`ssr: false` on a `ppr` route). `debugPerformance` prints cache hits per
+`ssr: "await"` on a `ppr` route). `debugPerformance` prints cache hits per
 layer, so the actual per-request behavior is observable.
 
 Keys and tags cross the nesting too:
@@ -643,7 +643,7 @@ This means `cache()` gives you cached UI + fresh data by default, where the
 data is read outside the cached output: `useLoader()` in a client component.
 A handler inside the boundary that awaits `ctx.use(Loader)` renders the value
 it got on the miss, and every hit replays that output. On a `ppr` route an
-`ssr: false` loader is the other exception: it bakes into the shell (`/ppr`).
+`ssr: "await"` loader is the other exception: it bakes into the shell (`/ppr`).
 To also cache a loader's data, explicitly opt in with
 `loader(Fn, () => [cache({...})])`.
 That entry is keyed by loader, host, path and params, not by the route's

package/skills/caching/SKILL.md

@@ -707,7 +707,7 @@ times out, or whose snapshot is truncated or corrupt (also evicted), cannot
 replay the captured segment record, so it degrades: the entry is replaced and
 recaptured and the page reloads once into a cache-miss render (`/ppr`). The
 snapshot holds only what a HIT reads: every HIT replays the handler layer from
-the captured segment record and serves an `ssr: false` loader's baked
+the captured segment record and serves an `ssr: "await"` loader's baked
 container, so no `"use cache"` or loader `cache()` item is stored in it. A
 live hole, and any loader that runs on the HIT, reads those from the store
 under their own ttl/swr and tags.

package/skills/catalog.json

@@ -41,7 +41,7 @@
     },
     {
       "name": "client-urls",
-      "description": "Define client-component route groups with clientUrls() in a \"use client\" module — no handlers, useLoader at read sites, server-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a \"use client\" file work.",
+      "description": "Define client-component route groups with clientUrls() in a \"use client\" module — no handlers, useLoader at read sites, server-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:\"await\" SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a \"use client\" file work.",
       "argumentHint": "[setup]",
       "path": "skills/client-urls/SKILL.md"
     },
@@ -143,7 +143,7 @@
     },
     {
       "name": "loader",
-      "description": "Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, must be settled in the SSR'd document (ssr:false), or must stay out of link prefetches (prefetch:false).",
+      "description": "Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, must be settled in the SSR'd document (ssr:\"await\"), or must stay out of link prefetches (prefetch:false).",
       "argumentHint": "[loader]",
       "path": "skills/loader/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-urls
-description: Define client-component route groups with clientUrls() in a "use client" module — no handlers, useLoader at read sites, server-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a "use client" file work.
+description: Define client-component route groups with clientUrls() in a "use client" module — no handlers, useLoader at read sites, server-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:"await" SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a "use client" file work.
 argument-hint: "[setup]"
 ---
 
@@ -132,7 +132,7 @@ flow into the generated route map, so `href()`, `ctx.reverse()` and
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see `/ppr` → The loader lane rule); no response variants. Use callback may contain `loader()`, `loading()`, `transition()` |
 | `layout()`     | `layout(Component, () => [...])` — children are required and must contain at least one `path()`; may also hold `loader()`, `loading()`, `intercept()`, nested `layout()`                         |
-| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false, prefetch: false \| "intent" }, use?)` — see below                                                                                              |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: "await", prefetch: false \| "intent" }, use?)` — see below                                                                                            |
 | `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait                                            |
 | `revalidate()` | Valid **inside a loader() use callback only**; runs on the server (the build hoists it out of the `"use client"` module)                                                                         |
 | `transition()` | Inside a `path()` use callback only (at most one). ViewTransition config plus a browser-run `when` predicate (see `/view-transitions`); same-route navs in a group already hold without it       |
@@ -185,11 +185,11 @@ export default clientUrls(({ path }) => [
 ]);
 ```
 
-| Component mounted by | Its `.use` may return                          |
-| -------------------- | ---------------------------------------------- |
-| `path()`             | `loader()`, `loading()`, `transition()`        |
-| `layout()`           | `loader()`, `loading()`                        |
-| `intercept()`        | `loader()` (without `ssr: false`), `loading()` |
+| Component mounted by | Its `.use` may return                            |
+| -------------------- | ------------------------------------------------ |
+| `path()`             | `loader()`, `loading()`, `transition()`          |
+| `layout()`           | `loader()`, `loading()`                          |
+| `intercept()`        | `loader()` (without `ssr: "await"`), `loading()` |
 
 - **Merge order is the server's.** The component's items come first and the
   mount site's own items second: an explicit `loading()` or `transition()`
@@ -511,7 +511,7 @@ The next action or navigation that reruns the loader replaces the message.
 
 A failure returned as data is an ordinary value, so whatever stores the
 loader's value stores it too: a `cache()` on the loader serves it for its TTL,
-a `ppr` shell bakes an `ssr: false` loader's value, and a prerender stores it
+a `ppr` shell bakes an `ssr: "await"` loader's value, and a prerender stores it
 at build time. A thrown error is never stored (a stale entry keeps serving).
 To cache the expensive part, cache the call the loader makes (`"use cache"` on
 that function: a call that throws stores nothing) and turn the throw into
@@ -545,7 +545,7 @@ export const ProductLoader = createLoader(async (ctx) => {
 On a document load, `notFound()` streams the resolved not-found UI in the
 envelope and _opportunistically_ sets a real 404 status — the status write only
 wins if the rejection settles before the document Response is constructed (a
-fast, pre-fetch existence check usually wins; see `ssr: false` below
+fast, pre-fetch existence check usually wins; see `ssr: "await"` below
 for the deterministic version). On navigations the 404 UI swaps in with the
 URL preserved. A loader `redirect()` is always a client-side navigate — there
 is no document-lane 302 from loaders; pre-stream redirect authority belongs to
@@ -557,10 +557,10 @@ push. Reads moved to `ctx.get(handle)`, gated behind `await ctx.rendered()`.
 Delivery follows the race model: pushes that settle before the handler barrier
 ride the SSR handle snapshot; later ones stream and apply post-hydration
 (document loads) or progressively (navigations). On a `ppr` shell HIT a loader
-without `ssr: false` never ran during the capture, so its pushes are never in
+without `ssr: "await"` never ran during the capture, so its pushes are never in
 the shell and always apply client-side. See `/loader` for the full contract.
 
-## `ssr: false` — the SSR-completeness opt-in
+## `ssr: "await"` — the SSR-completeness opt-in
 
 By default every loader streams on every render, so nothing a slow loader
 produces is _guaranteed_ to be in the SSR'd HTML — data SSRs as the Suspense
@@ -570,7 +570,7 @@ document — `<head>` meta via a handle, or a real 404 status — flag it:
 
 ```ts
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { ssr: false }, () => [
+  loader(ProductLoader, { ssr: "await" }, () => [
     revalidate(({ currentParams, nextParams, defaultShouldRevalidate }) =>
       currentParams.slug !== nextParams.slug ? defaultShouldRevalidate : false,
     ),
@@ -579,9 +579,9 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]),
 ```
 
-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 settled — no fallback
+The value says what the server render does with the loader: `"stream"` (the
+default) streams it, `"await"` awaits it. Document renders await a flagged
+loader before first flush (data settled — no fallback
 paints; handle pushes beat the barrier snapshot; a thrown `notFound()` is a
 deterministic real 404, no warm-up race); client navigations stream exactly as
 before. Scoped per loader — the flagged loader awaits only itself, siblings
@@ -613,12 +613,12 @@ Pinned end to end by dev + production e2e in the router repository.
 ships its fallback and swaps the content in with a script, which a browser
 without JavaScript never runs. That includes a client component a loader's
 answer draws under an inline `<Suspense>`: a fast loader's answer usually
-makes the first flush, and `ssr: false` guarantees the loader's data does. It
+makes the first flush, and `ssr: "await"` guarantees the loader's data does. It
 does not cover the client component's module: the first document a build's
 fresh server renders can still be waiting for it. The dev server matches a
 build here: when the shell is ready, it waits for the client components the
 payload has named and that are still loading, and for nothing else. On a
-document with an `ssr: false` loader, a part React finishes a moment after the
+document with an `ssr: "await"` loader, a part React finishes a moment after the
 shell, such as a `useActionState` form (React suspends it once to encode its
 action), is in the first flush too: the router gives React up to three more
 turns before it, and none when the document is already complete.
@@ -665,7 +665,7 @@ rest of the destination; otherwise it is held. A same-route click
   prefetch of the intercept's target defers it, and the click opens the
   modal at once with one fill for it; a hover's runs a loader marked
   `"intent"`.
-- With `ssr: false` on a `ppr` group route the flag works as on a server
+- With `ssr: "await"` on a `ppr` group route the flag works as on a server
   route: deferred unless the prefetch serves the loader from a pin of a
   document-captured shell (`/ppr` → "`prefetch: false` on a `ppr` route").
 - Test it with `serveShellRequest` in the Flight project: mount the module
@@ -726,7 +726,7 @@ a hard load of the target URL renders the full route.
   matches) never renders as a group route: the server ships the competing
   routes with the group.
 - **Two parallel loaders with equal latency look "SSR'd" together.** Loaders
-  kick off in parallel, so awaiting one (`ssr: false`) gives
+  kick off in parallel, so awaiting one (`ssr: "await"`) gives
   same-or-faster siblings time to settle coincidentally. Do not read "it was
   in the HTML once" as a guarantee — only the flagged loader is guaranteed.
 - **Hook semantics shift inside a group.** `usePathname` is ABSOLUTE (mount
@@ -786,7 +786,7 @@ The router repository (not shipped in this package) carries a canonical
 consumer at `tests/vite-rsc-demo/src/urls/client-shop.client.tsx`: layout +
 index + product routes, param-sensitive predicates, action-scoped cart
 revalidation, loader-thrown `notFound()`/`redirect()`, loader-written
-Meta/Breadcrumbs, viewport prefetch on cards, and the `ssr: false`
+Meta/Breadcrumbs, viewport prefetch on cards, and the `ssr: "await"`
 fixtures — with e2e suites next to it pinning each contract in dev and
 production. The sections above are self-contained; the app is corroboration,
 not required reading.

package/skills/comparison/references/framework-comparison.md

@@ -638,17 +638,17 @@ this resource-aware policy layer.
 
 `createLoader(fn)` / `loader()` define **live-by-default** data units: they are
 excluded from an enclosing segment cache and resolve on every request unless the
-loader itself explicitly opts into `cache()`. A loader without `ssr: false` may
+loader itself explicitly opts into `cache()`. A loader without `ssr: "await"` may
 safely read `cookies()`, `headers()`, request context, and `env` because its
 execution is outside the cached shell; a loader with its own `cache()` must put
 those reads in its `key()`, or its miss fails and stores nothing. On a `ppr`
-route an `ssr: false` loader bakes into the shell, so an identity read there
+route an `ssr: "await"` loader bakes into the shell, so an identity read there
 refuses the capture. Loaders run in parallel, stream independently under
 `loading()` boundaries, compose server-side via `ctx.use(OtherLoader)`, and
 carry route-level authority: they can throw `notFound()`/`redirect()`, WRITE
 handles (`ctx.use(Meta)({ title })` — data-derived page metadata pushed from the
 data's producer), read handle data after the render settles (`ctx.get(handle)`
-behind `await ctx.rendered()`), and opt into `loader(Def, { ssr: false })` so a
+behind `await ctx.rendered()`), and opt into `loader(Def, { ssr: "await" })` so a
 document render awaits them before first flush (deterministic SSR'd data, meta,
 and 404 status). Reads happen through `useLoader` in a client component
 (including its SSR pass) or `useFetchLoader` for standalone client fetches.
@@ -715,12 +715,12 @@ that no loader-before-render has:
 
 - it is the **cache-safety escape hatch** — the only place request-coupled reads
   are allowed inside a cache scope, because it is the part guaranteed to re-run
-  (a loader without `ssr: false` and without its own unkeyed `cache()`);
+  (a loader without `ssr: "await"` and without its own unkeyed `cache()`);
 - it is **standalone and composable**, not route-coupled — one `createLoader()`
   read by many segments, composed via `ctx.use`, or exposed as a fetchable endpoint;
 - it **streams as a hole, not a gate** — concurrent, Suspense-resolved under
   `loading()`, so the shell never blocks on it (and gating is a deliberate
-  per-loader opt-in — `{ ssr: false }` awaits ONE loader on document
+  per-loader opt-in — `{ ssr: "await" }` awaits ONE loader on document
   renders while the rest keep streaming — not the model's default);
 - it is **client-addressable and refreshable** independent of navigation (`key`,
   `refreshGroup`, `useRefreshLoaders`), behaving like a built-in, server-defined
@@ -798,7 +798,7 @@ shell.
 
 This is where the taint and loader designs meet. Loaders are the sanctioned
 dynamic holes: they run outside the enclosing segment cache and may read the
-current request (except, on a `ppr` route, an `ssr: false` loader or a loader a
+current request (except, on a `ppr` route, an `ssr: "await"` loader or a loader a
 handler awaits, which the capture runs and refuses on such a read), while the
 shared shell remains protected. Next.js also isolates runtime APIs from ordinary
 `"use cache"`, and React's optional taint APIs protect values at the

package/skills/defer-hydration/SKILL.md

@@ -121,8 +121,8 @@ 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
+`ssr: "await"` read with `useLoader` under `loading()` or an inline
+`<Suspense>`, or a promise nested in an `ssr: "await"` loader's value. Run the
 prelude check in "Verifying and measuring" on your page rather than assuming
 either shape.
 

package/skills/handler-use/SKILL.md

@@ -417,11 +417,11 @@ The composition rules are this skill's: the component's items first, the
 mount site's explicit items second, `loading()` and `transition()` last-wins,
 loaders accumulate. What differs:
 
-| Mount site in `clientUrls()` | The component's `.use` may return          |
-| ---------------------------- | ------------------------------------------ |
-| `path()`                     | `loader`, `loading`, `transition`          |
-| `layout()`                   | `loader`, `loading`                        |
-| `intercept()`                | `loader` (without `ssr: false`), `loading` |
+| Mount site in `clientUrls()` | The component's `.use` may return            |
+| ---------------------------- | -------------------------------------------- |
+| `path()`                     | `loader`, `loading`, `transition`            |
+| `layout()`                   | `loader`, `loading`                          |
+| `intercept()`                | `loader` (without `ssr: "await"`), `loading` |
 
 - No `route`, `layout`, `intercept` or `include` items: a group's routes and
   its generated types come from the builder's own items.

package/skills/hooks/data.md

@@ -28,7 +28,7 @@ boundary (or the route's `loading()`) — it does NOT render with
 `isLoading: true`. Put a boundary above every read whose loader can be slow;
 `isLoading` covers later refetches (`load()`, key/group refreshes). Once the
 component renders, `data` is present. (On document loads a loader registered
-with `{ ssr: false }` is already settled at first paint, so its
+with `{ ssr: "await" }` is already settled at first paint, so its
 reads never suspend there — see `/loader`.)
 
 **`isLoading` covers navigations and `load()` only.** When a server action

package/skills/hooks/handle-and-actions.md

@@ -33,9 +33,9 @@ const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
 Writers: handlers AND loader bodies — `ctx.use(Handle)` returns the push
 function in each (middleware has no handle APIs). Loader pushes follow a delivery race (settle before
 the handler barrier → in the SSR'd document; later → applied client-side), and
-`loader(Def, { ssr: false })` makes them deterministic in the
-document. On a `ppr` shell HIT, a loader without `ssr: false` never ran during
-the capture, so its pushes always apply client-side; with `ssr: false` they
+`loader(Def, { ssr: "await" })` makes them deterministic in the
+document. On a `ppr` shell HIT, a loader without `ssr: "await"` never ran during
+the capture, so its pushes always apply client-side; with `ssr: "await"` they
 bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.
 
@@ -46,12 +46,12 @@ belongs to the segment that pushed it and reaches `useHandle` when that push
 settles. The page never waits for a handle, and a handle never shows the next
 page's values over the page being left:
 
-| Case                                                                                                                                       | What `useHandle` returns                                                                                                                                                                                                                                                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Document load                                                                                                                              | The values the HTML was rendered from. `push(promise)` and `.defer()` are awaited during SSR, so the document ships the resolved value. On a `ppr` shell HIT that holds for the handlers' and the `ssr: false` loaders' pushes, which the shell baked; a live-lane loader's push arrives right after hydration (see `/ppr`). |
-| Navigation to a page that commits at once (a cold click that mounts new segments)                                                          | The destination's values, in the page's commit; the page's effects read them                                                                                                                                                                                                                                                 |
-| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land right after the page's commit: without view transitions in the same task, before paint; with view transitions when the transition's `ready` resolves                                                                                                            |
-| `push(promise)` or `.defer()` on a client navigation                                                                                       | The previous value, then the new one when the promise resolves, possibly well after the page                                                                                                                                                                                                                                 |
+| Case                                                                                                                                       | What `useHandle` returns                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Document load                                                                                                                              | The values the HTML was rendered from. `push(promise)` and `.defer()` are awaited during SSR, so the document ships the resolved value. On a `ppr` shell HIT that holds for the handlers' and the `ssr: "await"` loaders' pushes, which the shell baked; a live-lane loader's push arrives right after hydration (see `/ppr`). |
+| Navigation to a page that commits at once (a cold click that mounts new segments)                                                          | The destination's values, in the page's commit; the page's effects read them                                                                                                                                                                                                                                                   |
+| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land right after the page's commit: without view transitions in the same task, before paint; with view transitions when the transition's `ready` resolves                                                                                                              |
+| `push(promise)` or `.defer()` on a client navigation                                                                                       | The previous value, then the new one when the promise resolves, possibly well after the page                                                                                                                                                                                                                                   |
 
 You never see a pending value, a blank, or the destination's title over the old
 page. A crumb whose `content` is a promise read with `use()` in `<Suspense>`

package/skills/loader/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loader
-description: Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, must be settled in the SSR'd document (ssr:false), or must stay out of link prefetches (prefetch:false).
+description: Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, must be settled in the SSR'd document (ssr:"await"), or must stay out of link prefetches (prefetch:false).
 argument-hint: "[loader]"
 ---
 
@@ -8,7 +8,7 @@ argument-hint: "[loader]"
 
 A loader is a server function created with `createLoader()` and registered on a
 route segment with `loader()`. It runs fresh on every request (on a `ppr` route,
-one registered with `ssr: false` is baked into the shell instead), streams its
+one registered with `ssr: "await"` is baked into the shell instead), streams its
 result to the client, and client components read it with `useLoader()`. This
 skill covers defining, registering, consuming, revalidating, caching, and
 client-fetching loaders.
@@ -130,15 +130,15 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 DSL loaders are the **live data layer**: they resolve fresh on every request,
 even when the route is inside a `cache()` boundary, so `cache()` gives you
 cached UI + fresh data by default. See "Loaders: The Live Data Layer" below.
-The exception is a `ppr` route's `ssr: false` loader: it bakes into the shell,
+The exception is a `ppr` route's `ssr: "await"` loader: it bakes into the shell,
 and a shell HIT runs it only when its return carries promises.
 
 ### Cache safety
 
-A DSL loader without `ssr: false` can read `createVar({ cache: false })`
+A DSL loader without `ssr: "await"` can read `createVar({ cache: false })`
 variables: it runs on every request, `cache()` and PPR shell HITs included, so
 the read guard is bypassed for it. On a `ppr` route the capture runs an
-`ssr: false` loader, and a loader a handler awaits, and bakes their values into
+`ssr: "await"` loader, and a loader a handler awaits, and bakes their values into
 the shell: a `cookies()`, `headers()`, `ctx.request.headers` or
 `{ cache: false }` read there refuses the capture, so the route keeps
 rendering without a shell (warned once per key).
@@ -191,7 +191,7 @@ the tree).
 - The same holds under a PPR shell capture (`/ppr`): handler consumption is the
   BAKED lane — the loader executes at capture and the rendered value is a
   capture-time copy served on every HIT (a HIT never runs the handler);
-  `useLoader` of a loader without `ssr: false` is the live lane (an `ssr: false`
+  `useLoader` of a loader without `ssr: "await"` is the live lane (an `ssr: "await"`
   loader is the bake lane however it is read). Unlike `cache()`, an identity
   read inside that loader (`cookies()`, `headers()`, `ctx.request.headers`, a
   `{ cache: false }` variable) refuses the capture, so the route stays
@@ -226,26 +226,26 @@ never sends it (see `/hooks` `state.md`, "State on a document response").
 
 ### 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`                           | Request URL with internal `_rsc*` transport params stripped. Use this for application logic.                                                                                                   |
-| `originalUrl`      | `URL`                           | Request URL with every param intact, including `_rsc*`. Only for debugging or custom cache keying.                                                                                             |
-| `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`              | `any`                           | Bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.). `createLoader` types it as `any`; annotate or cast at the use site.                                                              |
-| `waitUntil`        | `(fn: () => Promise<void>)`     | Run work after the response is sent. Takes a function, not a promise. Delegates to Cloudflare's `waitUntil`; fire-and-forget with error logging elsewhere.                                     |
-| `executionContext` | `ExecutionContext \| undefined` | Raw Cloudflare `ExecutionContext` for libraries that need it; `undefined` off Cloudflare. Prefer `waitUntil`.                                                                                  |
-| `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`          | `AutofillAwareReverseFunction`  | Generate type-checked URLs from route names (same scoped semantics as route handlers; params the matched route carries are optional).                                                          |
+| 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`                           | Request URL with internal `_rsc*` transport params stripped. Use this for application logic.                                                                                                     |
+| `originalUrl`      | `URL`                           | Request URL with every param intact, including `_rsc*`. Only for debugging or custom cache keying.                                                                                               |
+| `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`              | `any`                           | Bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.). `createLoader` types it as `any`; annotate or cast at the use site.                                                                |
+| `waitUntil`        | `(fn: () => Promise<void>)`     | Run work after the response is sent. Takes a function, not a promise. Delegates to Cloudflare's `waitUntil`; fire-and-forget with error logging elsewhere.                                       |
+| `executionContext` | `ExecutionContext \| undefined` | Raw Cloudflare `ExecutionContext` for libraries that need it; `undefined` off Cloudflare. Prefer `waitUntil`.                                                                                    |
+| `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: "await"` (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`          | `AutofillAwareReverseFunction`  | Generate type-checked URLs from route names (same scoped semantics as route handlers; params the matched route carries are optional).                                                            |
 
 ### Example
 
@@ -556,14 +556,14 @@ served from cache. Route-level `cache()` caches rendered segments but never
 loader data: loaders are excluded when the segments are stored and re-resolved
 when they are served. Caching a loader's own data is a separate opt-in (see
 "Opting a Loader into Caching"). A `ppr` shell does store some loader data: an
-`ssr: false` loader's settled data bakes into the shell, and a HIT runs that
-loader only when its return carries promises (see "`ssr: false`" below and
+`ssr: "await"` loader's settled data bakes into the shell, and a HIT runs that
+loader only when its return carries promises (see "`ssr: "await"`" below and
 `/ppr`).
 
 Pre-rendering follows the same rule: the build-time Flight payload skips
 loaders (there is no real request context), and at runtime the worker resolves
 them fresh against the live database. The exception is a `Prerender` + `ppr`
-route: its build-time shell capture runs `ssr: false` loaders and bakes their
+route: its build-time shell capture runs `ssr: "await"` loaders and bakes their
 settled data into the shell, like a runtime capture.
 
 ### Parallel and streaming — latency overlaps first paint
@@ -584,9 +584,9 @@ 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. (The one deliberate
-exception is per-loader: `loader(Def, { ssr: false })` awaits that
+exception is per-loader: `loader(Def, { ssr: "await" })` awaits that
 loader before first flush on document renders other than a `ppr` shell HIT,
-where the shell flushes first — see "`ssr: false`" below.)
+where the shell flushes first — see "`ssr: "await"`" below.)
 
 ### See it: `debugPerformance`
 
@@ -693,7 +693,7 @@ rejects) skips the whole entry, as above. Entries written
 before handles were recorded replay none until they are rewritten (expiry or
 SWR revalidation).
 
-On a `ppr` route the shell keeps a copy of an `ssr: false` loader's pushes
+On a `ppr` route the shell keeps a copy of an `ssr: "await"` loader's pushes
 too, a pushed promise resolved (#1182). The two never disagree on the page:
 where a replay of the shell serves the loader's data from the shell, the
 shell's copy is the one shown and the entry only adds a push whose value
@@ -1005,12 +1005,12 @@ export const ProductLoader = createLoader(async (ctx) => {
 
 Semantics by lane:
 
-| Signal       | Document load, read inside `<Suspense>` or under `loading()`                                                                                                                                                                                                | Document load, read outside any `<Suspense>`                                                                                          | 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. | A real 404; the browser renders the not-found UI with the layouts kept (the recovery document, below)                                 | 404 UI swaps in, URL preserved, payload stays 200 |
-| `redirect()` | 200 document, then a client-side replace to the target                                                                                                                                                                                                      | A real 3xx (the redirect's own status) with `Location`; with `state`, the recovery document (200), then the client replace carries it | Redirect envelope navigates to the target         |
+| Signal       | Document load, read inside `<Suspense>` or under `loading()`                                                                                                                                                                                                  | Document load, read outside any `<Suspense>`                                                                                          | 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: "await"` (below) makes it deterministic. | A real 404; the browser renders the not-found UI with the layouts kept (the recovery document, below)                                 | 404 UI swaps in, URL preserved, payload stays 200 |
+| `redirect()` | 200 document, then a client-side replace to the target                                                                                                                                                                                                        | A real 3xx (the redirect's own status) with `Location`; with `state`, the recovery document (200), then the client replace carries it | Redirect envelope navigates to the target         |
 
-With `loader(Def, { ssr: false })` the result is settled BEFORE the document
+With `loader(Def, { ssr: "await" })` the result is settled BEFORE the document
 flushes, so both signals are resolved server-side while the tree is built:
 `redirect()` replaces the whole page with the redirect carrier (still a 200
 document, the client replaces to the target on hydration) and `notFound()`
@@ -1102,7 +1102,7 @@ on document loads (`metadata.handlesLate`) or progressively on navigations.
 Handle values land on their own channel and never hold the page, so an effect that needs a late push keys on the handle value, not the URL (see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design)).
 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. A loader with its own `cache()` keeps its pushes on a hit —
+`ssr: "await"` below. A loader with its own `cache()` keeps its pushes on a hit —
 they are replayed from the entry (see "Opting a Loader into Caching"). On a
 `ppr` route the race does not apply to a document served from its shell:
 there every push a loader makes on that request applies post-hydration (see
@@ -1115,8 +1115,8 @@ handler reserved with `.defer()` instead (`/breadcrumbs`, "Deferred content").
 
 Under `cache()`, loader pushes are not stored with the cached segments: the
 loader re-runs on every hit and its live push is the only copy. (`ppr` keeps
-the pushes of an `ssr: false` loader, and of the loaders it awaits, in the
-shell, a pushed promise resolved, and a promise-free `ssr: false` loader does
+the pushes of an `ssr: "await"` loader, and of the loaders it awaits, in the
+shell, a pushed promise resolved, and a promise-free `ssr: "await"` loader does
 not run on a shell HIT — see `/ppr`.)
 
 Reads are the other direction and gated: `ctx.get(handle)` throws unless the
@@ -1124,7 +1124,7 @@ 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
+## `ssr: "await"` — 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
@@ -1135,7 +1135,7 @@ use callback:
 
 ```typescript
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { ssr: false }, () => [cache({ ttl: 60 })]),
+  loader(ProductLoader, { ssr: "await" }, () => [cache({ ttl: 60 })]),
   loader(RelatedLoader),   // untouched: still streams behind its boundary
 ]),
 ```
@@ -1143,9 +1143,14 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 The options object is typed as `LoaderOptions`
 (`import type { LoaderOptions } from "@rangojs/router"`).
 
-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`
+The value says what the server render does with the loader: `"stream"` (the
+default, the same as leaving `ssr` out) streams it behind its boundary;
+`"await"` awaits it in the renders that produce HTML — the document render and
+a `ppr` shell capture (at runtime, or at build time on a `Prerender` + `ppr`
+route). (`loading(fallback, { ssr: false })` is a different option: there
+`false` means the fallback is not server-rendered.)
+
+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
@@ -1212,7 +1217,7 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ```
 
 (`prefetch` sits beside `ssr` in `LoaderOptions`; combine them as
-`{ ssr: false, prefetch: false }` if you need both.)
+`{ ssr: "await", prefetch: false }` if you need both.)
 
 | Request                                                      | unflagged  | `prefetch: false`        | `prefetch: "intent"`     |
 | ------------------------------------------------------------ | ---------- | ------------------------ | ------------------------ |
@@ -1404,7 +1409,7 @@ The limits:
   `intercept()` defers nothing. Each intercept loader also runs its own
   `revalidate()`, so an action from the modal re-runs only those that say so
   (see `/intercept`).
-- **`ppr` and `ssr: false`.** On a `ppr` route an `ssr: false` loader is the
+- **`ppr` and `ssr: "await"`.** On a `ppr` route an `ssr: "await"` loader is the
   bake lane. A prefetch that replays a shell a document request captured
   serves it from its pin: it is not deferred, does not run, and the click
   sends nothing. Every other prefetch (a navigation-only shell, a cold page,