@rangojs/router 0.34.1 → 0.35.0

package/skills/prerender/SKILL.md

@@ -21,7 +21,7 @@ The handler code and its imports are removed from the production bundle.
 ## Not this skill if…
 
 - You want a cached HTML shell captured at runtime, with holes staying live
-  per request (loaders without `ssr: false` run per request; `ssr: false`
+  per request (loaders without `ssr: "await"` run per request; `ssr: "await"`
   loaders bake) — see `/ppr`.
 - You want runtime segment caching with TTL/SWR — that is the `cache()` DSL:
   see `/caching`. Prerender is the same cache filled at build time.
@@ -355,12 +355,12 @@ own shell identity and is captured at runtime. The runtime shell store is read
 first, so a runtime capture supersedes the baked entry once it exists.
 
 Handle values behave as on any `ppr` shell (`/ppr` → "Handles on a shell
-HIT"): a value an `ssr: false` loader pushes settled is in the shell's HTML and
+HIT"): a value an `ssr: "await"` loader pushes settled is in the shell's HTML and
 in the data a HIT hydrates with, and one it pushes as a promise arrives after
 hydration. The prerendered payload holds only the handler's pushes (loaders
 never run at build), so the shell entry keeps the loader pushes its HTML
 rendered, on a build-baked shell and on one captured at runtime alike. A shell
-stored by router 0.21 or earlier lacks them, and a promise-free `ssr: false`
+stored by router 0.21 or earlier lacks them, and a promise-free `ssr: "await"`
 loader's settled push fails hydration on its HITs until the shell is replaced
 (#1057).
 
@@ -384,7 +384,7 @@ entry STILL serves and a runtime recapture is scheduled that upgrades it in plac
 `Prerender` handler is evicted from the production bundle, that recapture never
 re-runs the handler — it replays the same build-time segments and only refreshes
 what the capture reads again: `cache()`-scoped data baked into the shell, and
-the data of `ssr: false` loaders, which run at every capture. **If the shell
+the data of `ssr: "await"` loaders, which run at every capture. **If the shell
 bakes neither, `ttl` has nothing to refresh** — reach for `updateTag` (or a
 redeploy) instead of a shorter `ttl`.
 
@@ -661,7 +661,7 @@ Passthrough entries are logged distinctly:
 Loaders on pre-rendered routes run at request time. They are bundled normally
 and need `cache()` for caching. Do not use build-only APIs in loaders.
 
-The exception is an `ssr: false` loader on a `Prerender` + `ppr` route: the
+The exception is an `ssr: "await"` loader on a `Prerender` + `ppr` route: the
 build-time shell capture runs it and bakes its settled data into the shell,
 and a shell HIT runs it only when its return carries promises (`/ppr` → "The
 bake lane"). The Flight payload collection itself still skips loaders.

package/skills/rango/SKILL.md

@@ -27,7 +27,7 @@ with the shape, then pick a primitive.
   **stream**, so data latency overlaps first paint instead of blocking it (a
   cache hit streams UI instantly while loaders resolve fresh alongside). Opt into
   caching explicitly. See `/loader` → "Parallel and streaming". The one
-  exception is a `ppr` route's `ssr: false` loader: it bakes into the shell
+  exception is a `ppr` route's `ssr: "await"` loader: it bakes into the shell
   and runs on a shell HIT only when its return carries promises (`/ppr`).
 - **One identity, one store** — loaders, handles, cached fns, and actions are all
   `path#export`; all caches share one store. Entries expire by TTL/SWR, and are
@@ -71,7 +71,7 @@ are immune to partial-revalidation staleness by construction.
 
 1. **A loader** (`loader()` + `useLoader()`). Loaders resolve fresh on every
    pass — full renders, action revalidations, cache hits, PPR shell HITs (on a
-   `ppr` route, keep it off `ssr: false`, which bakes it into the shell).
+   `ppr` route, keep it off `ssr: "await"`, which bakes it into the shell).
    Nothing to keep in sync. If the data can be a loader, make it a loader.
 2. **Middleware `ctx.set()`**. Route middleware wraps every render pass,
    including post-action revalidation and PE re-renders, so its variables are
@@ -117,7 +117,7 @@ stated, greppable contract.
 | modal / soft navigation                 | `intercept()`                      | /intercept              |
 | route group of client components        | `clientUrls()` in `"use client"`   | /client-urls            |
 | set meta/breadcrumbs from loader data   | `ctx.use(Handle)` in the loader    | /loader                 |
-| guarantee loader output in the SSR HTML | `loader(L, { ssr: false })`        | /loader                 |
+| guarantee loader output in the SSR HTML | `loader(L, { ssr: "await" })`      | /loader                 |
 | pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
 | make a route ready before traffic       | `router.prerender({ env })(url)`   | /prerender              |
 | feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
@@ -130,7 +130,7 @@ stated, greppable contract.
 - `path()`/`include()` are always visible in `urls()`; config helpers are extractable.
 - **Cache decides freshness; `revalidate()` decides client-update.** Orthogonal; compose.
 - Loaders resolve fresh every request (even inside `cache()`) and never run twice/request.
-  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 runs on a shell HIT only when its return carries promises.
 - **The consumption-lane rule.** For every shared artifact (`cache()`,
   `"use cache"`, the PPR shell): server-side handler consumption
@@ -143,14 +143,14 @@ stated, greppable contract.
   `loader()` binding, or the cached function itself) and REFUSE a PPR capture: the route serves uncached until
   the read moves to a live loader. Client-side consumption
   (`useLoader` in a `"use client"` component) is the LIVE lane. DSL
-  `loader()` segments follow their PPR lane (only `ssr: false` bakes; see
+  `loader()` segments follow their PPR lane (only `ssr: "await"` bakes; see
   `/ppr` → The loader lane rule).
 - **A PPR shell HIT never runs a handler.** Everything a handler produces
   (promises it passes under `<Suspense>`, async server components, handle
   pushes, loaders it awaits) is shell material, as under `cache()`; a HIT
-  runs middleware and live loaders only (an `ssr: false` loader runs there
+  runs middleware and live loaders only (an `ssr: "await"` loader runs there
   only when its return carries promises). Live data belongs in a loader without
-  `ssr: false`, read with `useLoader` under `loading()` or an inline
+  `ssr: "await"`, read with `useLoader` under `loading()` or an inline
   `<Suspense>`.
 - Inside `"use cache"`: `cookies()`/`headers()`/`ctx.request.headers` and `ctx` side-effects
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`

package/skills/route/SKILL.md

@@ -482,7 +482,7 @@ loader re-runs on every hit — but a `"use cache"` function a loader calls is
 not, and neither is a loader bound with its own `cache()` without a `key()` (any
 `key()` switches the check off, so it must include the value; `/loader` → "Cache
 Key"). On a `ppr` route the exemption does not cover a loader the shell capture
-waits for (`ssr: false`, or awaited by a handler via `ctx.use()`): the read
+waits for (`ssr: "await"`, or awaited by a handler via `ctx.use()`): the read
 refuses the capture. Cacheable vars (the default) can be read freely inside
 cache scopes. See `/cache-guide` → "Context Variable Cache Safety".
 

package/skills/router-setup/SKILL.md

@@ -254,7 +254,7 @@ Notes:
   them.
 - `progressiveChunkSize` sets React's Fizz `progressiveChunkSize` for document
   renders and PPR shell capture. Unset, documents whose route has a
-  `loader(Def, { ssr: false })` raise it automatically so that content stays
+  `loader(Def, { ssr: "await" })` raise it automatically so that content stays
   in place; see `/loader`.
 - `encryptionKey` is the key that encrypts inline server-action bound
   arguments: base64-encoded 32 bytes (`openssl rand -base64 32`). Pass it as
@@ -504,7 +504,7 @@ When `notFound()` is thrown, the router uses the first of:
 Handler-thrown and no-match 404s always set HTTP status 404. A loader-thrown
 `notFound()` on a document request always renders the not-found UI, but the
 404 status is set only if the loader rejects before the document Response is
-constructed (loaders stream). Register the loader as `loader(Def, { ssr: false })` to
+constructed (loaders stream). Register the loader as `loader(Def, { ssr: "await" })` to
 make the 404 status deterministic. On client navigations the 404 UI swaps in
 with the URL preserved and the payload stays 200. See `/loader` → "Loader
 Authority".

package/skills/scripts/SKILL.md

@@ -112,11 +112,11 @@ during navigation.
 > settles before the handler barrier. A push that lands after a slow fetch
 > arrives post-hydration — and for an inline/ordered script the frozen set
 > means it is silently dropped. If a loader must contribute an inline script
-> to the document, register it `loader(Def, { ssr: false })` so the
+> to the document, register it `loader(Def, { ssr: "await" })` so the
 > document render awaits the push; otherwise push from a handler (or use an
 > `async` config, which stays reactive). On a `ppr` route a loader without
-> `ssr: false` never runs during the shell capture, so its inline/ordered
-> script is dropped on every shell HIT; with `ssr: false` the push bakes into
+> `ssr: "await"` never runs during the shell capture, so its inline/ordered
+> script is dropped on every shell HIT; with `ssr: "await"` the push bakes into
 > the shell.
 
 **Nonce caveat for soft-nav async.** The "nonce is applied automatically" claim

package/skills/shell-manifest/SKILL.md

@@ -9,7 +9,7 @@ argument-hint:
 Use this when a cached or prerendered shell has dynamic holes, and the live
 data layer needs to know **what the shell actually contains** — which
 products, which slots, which keys. The frozen render describes itself
-through a handle; live loaders (no `ssr: false`) read that description and
+through a handle; live loaders (no `ssr: "await"`) read that description and
 fetch exactly the dynamic data the shell needs, in one batch.
 
 Canonical case: a prerendered product list where prices must stay live.
@@ -36,7 +36,7 @@ batched.
    cache miss for `cache()`. (Loader bodies can push handles too — see `/loader`
    — but a live loader's push is request-time and is NOT part of the replayed
    artifact; a manifest handle must be pushed by the code that gets frozen with
-   the shell. An `ssr: false` loader on a `ppr` route is the exception: its
+   the shell. An `ssr: "await"` loader on a `ppr` route is the exception: its
    settled pushes are recorded with the shell. On a HIT, one whose return has no
    promises does not run (unless the capture marked it to run), so the recorded
    pushes are what the page shows; one whose return carries promises runs on
@@ -157,7 +157,7 @@ cache({ ttl: 600, tags: ["products"] }, () => [
   fetchable/standalone loader calls that run outside a route render, in
   handler-invoked loaders (a handler already awaiting the loader via
   `ctx.use()` is a detected deadlock), and in loaders registered with
-  `{ ssr: false }` (the document render awaits the loader before
+  `{ ssr: "await" }` (the document render awaits the loader before
   the barrier — a cycle by construction; see `/loader`).
 - **The reading loader serializes after the shell.** `await ctx.rendered()`
   deliberately gives up loader/render parallelism — on a miss the loader

package/skills/testing/serve-shell-request.md

@@ -250,7 +250,7 @@ Vitest runs no Vite id transform, so give each router an explicit `id` when a te
 | `hydration` | What the document hydrates with (`metadata.handles`, read to its end before hydration starts). For a `partial` request, the last state it streamed. |
 | `late`      | The states that arrived on the late channel (`metadata.handlesLate`), in order. Each replaces the client's handle data after hydration. Often `[]`. |
 
-On a HIT the client hydrates with exactly what the shell was rendered from, so `hydration` is also what the shell's HTML holds (the handlers' pushes and the `ssr: false` loaders', a pushed promise resolved), and whatever this request's loaders push, replace or drop is in `late` (see `/ppr`, "Handles on a shell HIT"):
+On a HIT the client hydrates with exactly what the shell was rendered from, so `hydration` is also what the shell's HTML holds (the handlers' pushes and the `ssr: "await"` loaders', a pushed promise resolved), and whatever this request's loaders push, replace or drop is in `late` (see `/ppr`, "Handles on a shell HIT"):
 
 ```ts
 // The handler pushed ctx.use(Notes)("from-handler"); a live loader pushes

package/skills/theme/SKILL.md

@@ -141,10 +141,10 @@ Read the theme where it is per request instead:
   visitor with no stored theme sees the default, and one with a stored theme
   sees it after hydration. Any other render, a 404 included, starts at the
   visitor's own theme.
-- A live loader (no `ssr: false`). Loaders do not get `ctx.theme` or
+- A live loader (no `ssr: "await"`). Loaders do not get `ctx.theme` or
   `ctx.setTheme`; read the cookie directly. A live loader runs on every
   request, HITs included, and on a `ppr` route needs `loading()` or an inline
-  `<Suspense>` above its reader. A bake-lane loader (`ssr: false`) runs at
+  `<Suspense>` above its reader. A bake-lane loader (`ssr: "await"`) runs at
   capture, where this `cookies()` read refuses the capture, and so does a
   loader a handler awaits with `ctx.use()`.
 

package/skills/typesafety/env-and-bindings.md

@@ -118,9 +118,9 @@ marks a specific write as non-cacheable even if the var itself is cacheable.
 "Least cacheable wins" — if either says `cache: false`, the value throws on
 read inside `cache()` or `"use cache"`. On a `ppr` route the read also throws
 anywhere the shell capture waits for it (a handler, a promise it passes or
-pushes, an async server component, an `ssr: false` loader, a loader a handler
+pushes, an async server component, an `ssr: "await"` loader, a loader a handler
 awaits) and refuses the capture: the route keeps rendering without a shell,
-and a warning fires once per key. A loader without `ssr: false` that no
+and a warning fires once per key. A loader without `ssr: "await"` that no
 handler awaits may read it, unless it is bound with its own `cache()` and no
 `key()`: that miss fails, since the entry is shared (`/loader` → "Cache
 Key").

package/skills/use-cache/SKILL.md

@@ -655,7 +655,7 @@ this isolate's invalidations are caught; ttl+swr bounds the rest.
 
 Inside a `ppr` shell, a `"use cache"` value that renders as shell material is
 pinned at capture time for the life of that shell (see `/ppr` → Pitfalls). A
-hole's own read (in a loader without `ssr: false` under `loading()` or an
+hole's own read (in a loader without `ssr: "await"` under `loading()` or an
 inline `<Suspense>`) always returns the store's current entry, never the
 shell's copy, even when a loader the capture ran read the same entry.
 

package/skills/ux-architecture/SKILL.md

@@ -53,10 +53,10 @@ hand, is a router bug: report it.
 
 ### 2.1 A server urls() page or a clientUrls() group?
 
-| Pick                                   | When                                                                                                                                                                                                                                                                                    | What you get                                                                                                                                                                                                                                                                                                                                                                                               |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A server `urls()` route with a handler | Pages people mostly reach by a document load (marketing, docs, articles, landing pages). Pages built from server components you don't want to ship as client code. Routes that need `cache()`, `Prerender()`, `parallel()`, `middleware()` or an `errorBoundary()` on the route itself. | The handler renders on the server, and `cache()` or a prerender can store its output. A click with no prefetch waits for the server before the page changes; a prefetched click does not.                                                                                                                                                                                                                  |
-| A `clientUrls()` group                 | An area where people move a lot inside one layout: dashboards, admin, settings, tabs, filters, master and detail. Pages that are client components anyway.                                                                                                                              | The browser matches the group, so a click to another route of the group renders the destination at once, before the server answers. Param and search changes on one route reconcile and hold. There are no handlers: every read is a `useLoader` under its own boundary. A document load is still rendered on the server, and `loader(Def, { ssr: false })` puts a loader's data and handles in that HTML. |
+| Pick                                   | When                                                                                                                                                                                                                                                                                    | What you get                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A server `urls()` route with a handler | Pages people mostly reach by a document load (marketing, docs, articles, landing pages). Pages built from server components you don't want to ship as client code. Routes that need `cache()`, `Prerender()`, `parallel()`, `middleware()` or an `errorBoundary()` on the route itself. | The handler renders on the server, and `cache()` or a prerender can store its output. A click with no prefetch waits for the server before the page changes; a prefetched click does not.                                                                                                                                                                                                                    |
+| A `clientUrls()` group                 | An area where people move a lot inside one layout: dashboards, admin, settings, tabs, filters, master and detail. Pages that are client components anyway.                                                                                                                              | The browser matches the group, so a click to another route of the group renders the destination at once, before the server answers. Param and search changes on one route reconcile and hold. There are no handlers: every read is a `useLoader` under its own boundary. A document load is still rendered on the server, and `loader(Def, { ssr: "await" })` puts a loader's data and handles in that HTML. |
 
 Two limits of a group decide some cases:
 
@@ -436,7 +436,7 @@ The rule: **prefetch broadly, and flag what is expensive.**
   `ctx.use(Breadcrumbs)({ label, href })`. This is how a group, which has no
   handlers, sets them (`/breadcrumbs`, "Pushing from Loaders").
 - Read them in chrome with `useHandle(Breadcrumbs)`, in a layout that stays.
-- `loader(Def, { ssr: false })` puts its pushes in the document's HTML (a
+- `loader(Def, { ssr: "await" })` puts its pushes in the document's HTML (a
   title for search engines, a real 404 from `notFound()`). The document waits
   for that loader; flag only the one that needs it.
 - A loader an action skips keeps its title and crumbs
@@ -633,7 +633,7 @@ export default clientUrls(({ path, layout, loader, revalidate }) => [
       loader(ProductsLoader, () => [revalidate(bySearch)]),
     ]),
     path("/product/:slug", ProductPage, { name: "product" }, () => [
-      loader(ProductLoader, { ssr: false }, () => [revalidate(bySlug)]),
+      loader(ProductLoader, { ssr: "await" }, () => [revalidate(bySlug)]),
       loader(RelatedLoader, () => [revalidate(bySlug)]),
       loader(ReviewsLoader, { prefetch: false }, () => [revalidate(bySlug)]),
     ]),
@@ -647,7 +647,7 @@ Why each placement:
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Catalog and product in one group                       | A card click renders the product page at the click; the filters and tabs are same-route navigations that hold.                                                                                                                                                                            |
 | `CartLoader` on the server layout, ternary predicate   | Held on every navigation (a server layout loader's default), re-run only after a cart action. It survives entering and leaving the group. The badge updates in the add-to-cart response itself.                                                                                           |
-| `ProductLoader` with `ssr: false`                      | The product's title and a real 404 for an unknown slug are in the document's HTML. Client navigations still stream it.                                                                                                                                                                    |
+| `ProductLoader` with `ssr: "await"`                    | The product's title and a real 404 for an unknown slug are in the document's HTML. Client navigations still stream it.                                                                                                                                                                    |
 | `bySlug` on the product loaders                        | Product to product re-runs them; a tab switch and an add to cart hold them. One action, three outcomes: the badge refreshes, product and related keep their data (`client-shop-cart.test.ts`).                                                                                            |
 | `ReviewsLoader` flagged `prefetch: false`              | Every visible card prefetches; reviews are the expensive, rarely read part. The click still shows the product at once and the reviews fill behind their own boundary. A prefetch from another product page (the related links) still runs it: only a segment new to the page is deferred. |
 | One `<Suspense>` per section                           | A slow product loader fills its section without holding the related list, and the other way round (the demo's product loader takes 2 s).                                                                                                                                                  |

package/src/cache/shell-snapshot.ts

@@ -5,7 +5,7 @@
  * that must agree with them byte for byte. The handler layer's part of that
  * payload is the capture's own doc segment record: the capture writes it
  * first, renders its prelude from it, and every HIT replays it (no handler
- * runs on a HIT). The loader layer's part is the bake-lane (`ssr: false`)
+ * runs on a HIT). The loader layer's part is the bake-lane (`ssr: "await"`)
  * loader pins: a promise-free bake-lane loader is served from its pin and
  * does not run; one whose return carries promises (`holes`), or whose pushes
  * the record could not keep (`runs`), runs on the HIT. See

package/src/cache/types.ts

@@ -841,7 +841,7 @@ export type SegmentHandleData = Record<string, unknown[]>;
 /**
  * segmentId -> handleName -> the owning loader id of each recorded value, by
  * index (null: not owned). Only a PPR shell capture writes owners: the
- * settled pushes of the loader bodies it ran (an `ssr: false` loader's own,
+ * settled pushes of the loader bodies it ran (an `ssr: "await"` loader's own,
  * the loaders it awaits, and its own cache() replays), which the record keeps
  * because the prelude rendered them. A restore of the record
  * (handle-snapshot.ts restoreHandles) keeps an owner's value where the

package/src/client-urls/client-urls.ts

@@ -141,7 +141,7 @@ interface LoaderItem extends ItemBase {
   readonly type: "loader";
   readonly definition: LoaderDefinition<any, any>;
   readonly revalidate: ClientUrlLoaderRecord["revalidate"];
-  readonly ssr?: false;
+  readonly ssr?: "await";
   readonly prefetch?: PrefetchFlag;
 }
 
@@ -348,14 +348,21 @@ export const loader: ClientUrlHelpers["loader"] = (
   const use = typeof optionsOrUse === "function" ? optionsOrUse : maybeUse;
   if ((options as { stream?: unknown } | undefined)?.stream !== undefined) {
     throw new Error(
-      "clientUrls() loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
+      'clientUrls() loader() stream was replaced: use loader(Def, { ssr: "await" }) to await the loader before first flush on document requests.',
     );
   }
-  // Inline, not errors.ts assertBooleanOption: this module is in the
-  // client router chunk, where the helper costs 20 B gzip.
-  if (options?.ssr !== undefined && typeof options.ssr !== "boolean") {
+  // Inline, not errors.ts assertLoaderSsrOption: this module is in the
+  // client router chunk, where the helper costs bytes on every page.
+  if (
+    options?.ssr !== undefined &&
+    options.ssr !== "stream" &&
+    options.ssr !== "await"
+  ) {
     throw new Error(
-      `clientUrls() loader() ssr must be a boolean (got ${JSON.stringify(options.ssr)}). Omit it (or pass true) to stream on every render.`,
+      process.env.NODE_ENV !== "production" &&
+        (options.ssr as unknown) === false
+        ? 'clientUrls() loader() ssr: false was replaced: use loader(Def, { ssr: "await" }) to await the loader before first flush on document requests.'
+        : `clientUrls() loader() ssr must be "stream" or "await" (got ${JSON.stringify(options.ssr)}). Omit it (or pass "stream") to stream on every render.`,
     );
   }
   if (
@@ -380,7 +387,7 @@ export const loader: ClientUrlHelpers["loader"] = (
           item.type === "revalidate",
       )
       .map((item) => item.fn),
-    ...(options?.ssr === false ? { ssr: false as const } : {}),
+    ...(options?.ssr === "await" ? { ssr: "await" as const } : {}),
     ...(isPrefetchFlag(options?.prefetch)
       ? { prefetch: options.prefetch }
       : {}),
@@ -580,7 +587,7 @@ function createHelpers(): ClientUrlHelpers {
       // await can never apply, so accepting the flag would be silently inert.
       if (item.type === "loader" && item.ssr !== undefined) {
         throw new Error(
-          "clientUrls() intercept() loaders cannot use ssr: false — intercepts render on client navigations only",
+          'clientUrls() intercept() loaders cannot use ssr: "await" — intercepts render on client navigations only',
         );
       }
     }
@@ -633,7 +640,7 @@ function applyConfig(
         Object.freeze({
           loader: item.definition,
           revalidate: Object.freeze([...item.revalidate]),
-          ...(item.ssr === false ? { ssr: false as const } : {}),
+          ...(item.ssr === "await" ? { ssr: "await" as const } : {}),
           ...(item.prefetch !== undefined ? { prefetch: item.prefetch } : {}),
         }),
       );

package/src/client-urls/server-projection.ts

@@ -103,7 +103,7 @@ export interface ClientUrlProjectionRoute {
   readonly options: ClientUrlProjectionOptions;
   readonly loaderIds: readonly string[];
   readonly hasLoading: boolean;
-  /** Indices into loaderIds of loaders declared loader(Def, { ssr: false });
+  /** Indices into loaderIds of loaders declared loader(Def, { ssr: "await" });
    *  materialization passes the option through to the server loader() so
    *  document renders await them before first flush. Absent (= none) in
    *  projections serialized before the option existed. */
@@ -348,7 +348,7 @@ function serializeRoute(
 
   const awaitedLoaderIndices = indicesWhere(
     route.loaders,
-    ({ ssr }) => ssr === false,
+    ({ ssr }) => ssr === "await",
   );
 
   const transition = serializeTransition(route);
@@ -832,7 +832,7 @@ function materializeRouteItems(
   };
 
   // The loader() items of a route's or an intercept's projected loaders: each
-  // stub with its `ssr: false` and `prefetch` flags and its revalidate()
+  // stub with its `ssr: "await"` and `prefetch` flags and its revalidate()
   // predicates.
   const materializeLoaders = (owner: ProjectedLoaders) =>
     owner.projected.loaderIds.map((id, loaderIndex) => {
@@ -841,7 +841,7 @@ function materializeRouteItems(
         createLoaderStub(id),
         {
           ...(owner.projected.awaitedLoaderIndices?.includes(loaderIndex) && {
-            ssr: false,
+            ssr: "await" as const,
           }),
           ...(owner.projected.deferrableLoaderIndices?.includes(
             loaderIndex,

package/src/client-urls/types.ts

@@ -79,12 +79,12 @@ export interface ClientUrlLoaderRecord {
     | boolean
   )[];
   /**
-   * loader(Def, { ssr: false }): document renders await this loader before
+   * loader(Def, { ssr: "await" }): document renders await this loader before
    * first flush (see {@link LoaderOptions}). Projected into the server tree,
    * where the per-isSSR entry stamping applies — client navigations stream
    * regardless.
    */
-  readonly ssr?: false;
+  readonly ssr?: "await";
   /**
    * loader(Def, { prefetch: false | "intent" }): a prefetch of the route, or
    * of an intercept's target from its source, defers this loader and the
@@ -160,10 +160,10 @@ export interface ClientUrlHelpers {
    * Attach a projected loader. The optional use callback may contain
    * revalidate() only: a per-loader predicate the server runs, as in urls().
    *
-   * 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` group
    * route the flag BAKES: the loader executes at shell capture and its
    * settled return freezes into the shell (nested promises stay live

package/src/decode-loader-results.ts

@@ -26,7 +26,7 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * decodeLoaderResults runs during the tree build on settled results, where a
  * throw would collapse the whole payload — it routes signals through the
  * errorFallback slot instead (same visual: the slot replaces the children
- * under OutletProvider). The document lane's `{ ssr: false }` results take
+ * under OutletProvider). The document lane's `{ ssr: "await" }` results take
  * this route (segment-system buildLoaderStreams): they are settled before the
  * tree is built, and the read-site throw would land in the Fizz shell with no
  * boundary to absorb it.

package/src/errors.ts

@@ -406,17 +406,17 @@ export function invariant(condition: any, message: string): asserts condition {
 }
 
 /**
- * Rejects a boolean-only DSL option that holds anything else (undefined
- * passes), as an invariant.
+ * Rejects a loader `ssr` option other than `"stream"` or `"await"`
+ * (undefined passes). clientUrls() inlines the same checks.
  */
-export function assertBooleanOption(
-  value: unknown,
-  option: string,
-  effect: string,
-): void {
+export function assertLoaderSsrOption(value: unknown, helper: string): void {
+  invariant(
+    value !== false,
+    `${helper} ssr: false was replaced: use loader(Def, { ssr: "await" }) to await the loader before first flush on document requests.`,
+  );
   invariant(
-    value === undefined || typeof value === "boolean",
-    `${option} must be a boolean (got ${JSON.stringify(value)}). Omit it (or pass true) to ${effect}.`,
+    value === undefined || value === "stream" || value === "await",
+    `${helper} ssr must be "stream" or "await" (got ${JSON.stringify(value)}). Omit it (or pass "stream") to stream on every render.`,
   );
 }
 

package/src/handles/meta.ts

@@ -232,9 +232,9 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * title-templating identically to synchronous descriptors. A descriptor that
  * resolves to `null`/`undefined` (or rejects) is dropped.
  *
- * On a ppr route, a descriptor a handler or an `ssr: false` loader pushes,
+ * On a ppr route, a descriptor a handler or an `ssr: "await"` loader pushes,
  * promise or not, is in the shell's `<head>` on every HIT (#1182). One a
- * loader without `ssr: false` pushes is live: on a HIT it arrives after
+ * loader without `ssr: "await"` pushes is live: on a HIT it arrives after
  * hydration.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<

package/src/loader-store.ts

@@ -575,7 +575,7 @@ export class LoaderStore {
   /**
    * Register a still-streaming per-loader result for `loaderId`. No-op for a
    * settled Flight chunk (unwrapsSynchronously / "rejected"): the forceAwait
-   * and action lanes commit settled chunks, and a { ssr: false } loader is
+   * and action lanes commit settled chunks, and a { ssr: "await" } loader is
    * awaited before flush. Released as the stream settles, either way.
    */
   trackPendingStream(loaderId: string, stream: Promise<unknown>): void {

package/src/outlet-context.ts

@@ -20,7 +20,7 @@ export interface OutletContextValue {
   loaderStreams?: Record<string, unknown>;
   /**
    * Loader $$ids on this segment that the render awaited before first flush
-   * (loader(Def, { ssr: false })). Dev-diagnostic input only: useLoader uses
+   * (loader(Def, { ssr: "await" })). Dev-diagnostic input only: useLoader uses
    * it to warn when a read still suspends during SSR on a render that awaited
    * flagged loaders (ssr-suspension-warning.ts). Present only where a
    * segment carries flagged loaders (document and shell-capture renders, and

package/src/route-definition/dsl-helpers.ts

@@ -26,7 +26,7 @@ import {
   type LoaderEntry,
 } from "../server/context";
 import {
-  assertBooleanOption,
+  assertLoaderSsrOption,
   assertPrefetchOption,
   invariant,
 } from "../errors";
@@ -920,13 +920,9 @@ const loader: RouteHelpers<any, any>["loader"] = (
   );
   invariant(
     (optionsGiven as { stream?: unknown } | undefined)?.stream === undefined,
-    "loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
-  );
-  assertBooleanOption(
-    optionsGiven?.ssr,
-    "loader() ssr",
-    "stream on every render",
+    'loader() stream was replaced: use loader(Def, { ssr: "await" }) to await the loader before first flush on document requests.',
   );
+  assertLoaderSsrOption(optionsGiven?.ssr, "loader()");
   assertPrefetchOption(
     optionsGiven?.prefetch,
     "loader() prefetch",
@@ -942,7 +938,7 @@ const loader: RouteHelpers<any, any>["loader"] = (
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
-    ...(optionsGiven?.ssr === false && { bake: true as const }),
+    ...(optionsGiven?.ssr === "await" && { bake: true as const }),
     ...(isPrefetchFlag(optionsGiven?.prefetch) && {
       prefetch: optionsGiven.prefetch,
     }),

package/src/route-definition/helpers-types.ts

@@ -323,14 +323,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   return <div>{data.name}</div>;
    * }
    * ```
-   * 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 in the same segment keeps streaming.
    *
    * ```typescript
-   * loader(ProductLoader, { ssr: false }, () => [cache()]),
+   * loader(ProductLoader, { ssr: "await" }, () => [cache()]),
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *

package/src/router/loader-resolution.ts

@@ -160,7 +160,7 @@ function pushHandleValue(
  *   This has a simplified signature for internal use - the caller (typically
  *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
  *   OnErrorCallback with complete request context (request, url, env, etc.).
- * @param useDefaultErrorBoundary - An `ssr: false` loader on a document or
+ * @param useDefaultErrorBoundary - An `ssr: "await"` loader on a document or
  *   capture render: an error with no declared boundary gets
  *   `DefaultErrorFallback` (it would otherwise reject the tree), and every
  *   error answers 500.
@@ -758,7 +758,7 @@ function createLoaderExecutor<TEnv>(
         }
 
         // awaitBeforeFlush cycle: segment resolution awaits this loader
-        // (loader(Def, { ssr: false })), the barrier awaits segment
+        // (loader(Def, { ssr: "await" })), the barrier awaits segment
         // resolution, and rendered() awaits the barrier — waiting here can
         // never complete. Fail fast with the cause instead of hanging the
         // document render. Only document renders populate the set (the flag is
@@ -767,10 +767,10 @@ function createLoaderExecutor<TEnv>(
         if (reqCtx._awaitBeforeFlushLoaderIds?.has(currentLoaderId)) {
           throw new Error(
             `Deadlock: loader "${currentLoaderId}" is registered with ` +
-              `ssr: false, so the document render awaits it before ` +
+              `ssr: "await", so the document render awaits it before ` +
               `the render barrier resolves — ctx.rendered() (and the ` +
               `ctx.get(handle) read it gates) can never settle here. Drop ` +
-              `ssr: false on this loader or move the handle read to ` +
+              `ssr: "await" on this loader or move the handle read to ` +
               `a component.`,
           );
         }