@rangojs/router 0.34.0 → 0.35.0

package/dist/types/urls/path-helper-types.d.ts

@@ -153,10 +153,10 @@ export type PathHelpers<TEnv> = {
     /**
      * Attach a data loader to the current route/layout.
      *
-     * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
-     * false }) — to await this loader before first flush on DOCUMENT requests
-     * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
-     * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+     * Pass `{ ssr: "await" }` to await this loader before first flush on
+     * DOCUMENT requests (see {@link LoaderOptions}): the opt-in for loaders
+     * whose data, handle pushes, or thrown notFound()/redirect() must be in the
+     * SSR'd HTML.
      * Per-loader: a streaming sibling keeps streaming. Under a `ppr` route the
      * flag BAKES: the loader executes at shell capture and its settled return
      * freezes into the shell (nested promises stay live holes) — the pre-flush

package/dist/types/urls/pattern-types.d.ts

@@ -61,7 +61,7 @@ export interface PartialPrerenderProps {
      * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
      * data snapshot: the bake-lane loader records. The doc record (the handler
      * layer every HIT replays) is exempt. A document HIT is served only from an
-     * entry that holds a pin for every `ssr: false` loader its HTML baked, so
+     * entry that holds a pin for every `ssr: "await"` loader its HTML baked, so
      * over the cap no document shell is stored: documents render in full
      * (MISS), and client navigations still replay the handler layer and run
      * those loaders fresh. Reported once per key. Defaults to 8 MiB. The whole

package/dist/types/vite/plugin-types.d.ts

@@ -166,7 +166,7 @@ interface RangoBaseOptions {
      * which is why React outlines by default.
      *
      * When UNSET, document renders and PPR shell captures whose matched chain
-     * has a `loader(Def, { ssr: false })` entry auto-raise to MAX_SAFE_INTEGER —
+     * has a `loader(Def, { ssr: "await" })` entry auto-raise to MAX_SAFE_INTEGER —
      * the loader was awaited before first flush precisely so its content ships
      * in-place, and outlining the boundary it feeds would defeat that. A shell
      * HIT inherits the captured value, so it matches the live render. Setting

package/dist/vite/index.js

@@ -4604,7 +4604,7 @@ function routerKeyPrefix(routerId2) {
 
 // src/rsc/shell-capture-constants.ts
 var SHELL_CAPTURE_MAX_WAIT_MS = 15e3;
-var PPR_LANE_HINT = 'Lane rule: only loader(Def, { ssr: false }) executes at capture and bakes its non-promise data; every other loader is live (masked at capture, fresh per request) and needs loading() or an inline <Suspense> above its reader. See the /ppr skill, "The loader lane rule" (node_modules/@rangojs/router/skills/ppr/SKILL.md).';
+var PPR_LANE_HINT = 'Lane rule: only loader(Def, { ssr: "await" }) executes at capture and bakes its non-promise data; every other loader is live (masked at capture, fresh per request) and needs loading() or an inline <Suspense> above its reader. See the /ppr skill, "The loader lane rule" (node_modules/@rangojs/router/skills/ppr/SKILL.md).';
 
 // src/cache/cache-exec-scope.ts
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -4633,8 +4633,8 @@ var LOADER_BODY_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-bo
 var loaderBodyScopeALS = globalThis[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage2();
 function requestReadCaptureFix(what) {
   return {
-    capture: `The captured shell is served to every user of this URL, so request-scoped data read here would leak one user's ${what} to others. Read it inside a loader without ssr: false and consume it with useLoader, e.g. createLoader(async () => getUser(cookies().get("session")?.value)). ${PPR_LANE_HINT}`,
-    warning: "Read it in a loader without ssr: false and consume it with useLoader under loading() or an inline <Suspense> (a live hole). A promise the handler passes or pushes does not help: the capture waits for it."
+    capture: `The captured shell is served to every user of this URL, so request-scoped data read here would leak one user's ${what} to others. Read it inside a loader without ssr: "await" and consume it with useLoader, e.g. createLoader(async () => getUser(cookies().get("session")?.value)). ${PPR_LANE_HINT}`,
+    warning: 'Read it in a loader without ssr: "await" and consume it with useLoader under loading() or an inline <Suspense> (a live hole). A promise the handler passes or pushes does not help: the capture waits for it.'
   };
 }
 var NON_CACHEABLE_READ = {
@@ -6074,7 +6074,7 @@ var RAW_COOKIES_READ = {
   verb: "called",
   fix: COOKIES_READ.fix
 };
-var THEME_READ_FIX = "On ppr and cache() routes, read the theme with useTheme() in a client component, or in a live loader (no ssr: false) with cookies().get(<storageKey>). The <html> theme class needs neither: the theme script sets it before paint. See the /theme skill (node_modules/@rangojs/router/skills/theme/SKILL.md).";
+var THEME_READ_FIX = 'On ppr and cache() routes, read the theme with useTheme() in a client component, or in a live loader (no ssr: "await") with cookies().get(<storageKey>). The <html> theme class needs neither: the theme script sets it before paint. See the /theme skill (node_modules/@rangojs/router/skills/theme/SKILL.md).';
 var THEME_READ = {
   verb: "read",
   fix: {
@@ -6289,7 +6289,7 @@ function serializeRoute(route2, options, ordinals) {
   });
   const awaitedLoaderIndices = indicesWhere(
     route2.loaders,
-    ({ ssr }) => ssr === false
+    ({ ssr }) => ssr === "await"
   );
   const transition3 = serializeTransition(route2);
   return Object.freeze({
@@ -7344,7 +7344,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.34.0",
+  version: "0.35.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -14567,7 +14567,7 @@ async function runShellPrerenderPhase(s, builder, versionsTable) {
       injectRSCPayload: htmlStream.injectRSCPayload,
       headScripts: "preinit",
       // Build-captured shells honor the explicit outlining budget, or the
-      // ssr:false auto-raise without one (createShellCaptureHandler): the
+      // ssr: "await" auto-raise without one (createShellCaptureHandler): the
       // capture value rides the postponed state into every runtime resume().
       ...s.opts?.progressiveChunkSize !== void 0 && {
         progressiveChunkSize: s.opts.progressiveChunkSize

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/app-structure/e-commerce.md

@@ -379,7 +379,7 @@ product) and the pages render entirely from loaders, mount the shop as a
 `clientUrls()` group, `include("/shop", shopUrls, { name: "shop" })`:
 navigations inside it render at the click, and each loader's `revalidate()`
 holds its data across them. A group has no handlers, so a `ppr` group route
-holds its client components' HTML and its `ssr: false` loaders' data, and
+holds its client components' HTML and its `ssr: "await"` loaders' data, and
 every other loader is a hole; handler output baked from a tagged
 `"use cache"` read, as in the catalog above, needs `urls()` routes. The router
 repository's `tests/vite-rsc-demo/src/urls/client-shop.client.tsx` is a full

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
@@ -261,7 +261,10 @@ tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
 subset. Sharing within a group is opt-in via `key`: members that share a `key`
 share one value (and one fetch); a grouped reader **without** a `key` gets its own
 private bucket, so a group refresh updates only that read and never leaks into
-unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+unrelated unkeyed reads of the same loader. That private bucket lives as long as
+its read is mounted, and a hidden React `<Activity>` counts as unmounted: when it
+shows again, the read is back on the route's data until the next refresh. To keep
+a refreshed value across an `<Activity>` hide, give the read a `key`. A bucket may belong to several groups
 at once (one read tagged with multiple names, or different reads tagging the same
 keyed bucket with different names). Keep parameterized loaders on the single-loader
 `key` — a plain-GET group refresh sends no params.

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>`