@rangojs/router 0.8.0 → 0.9.0

package/skills/loader/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loader
-description: Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (stream:"navigation").
+description: Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, client components need reactive server data, a loader should throw notFound()/redirect(), set page meta/breadcrumbs from loader data (handle writes), or loader data must be guaranteed in the SSR'd document (ssr:false).
 argument-hint: "[loader]"
 ---
 
@@ -172,23 +172,23 @@ Loaders receive the same context shape as route handlers.
 
 ### 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`                           | Parsed request URL.                                                                                                                                                                                      |
-| `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`          | `TEnv`                          | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                                                                      |
-| `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 `stream: "navigation"` (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`      | `ScopedReverseFunction`         | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                                                                   |
+| 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`                           | Parsed request URL.                                                                                                                                                                            |
+| `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`          | `TEnv`                          | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                                                                                                            |
+| `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`      | `ScopedReverseFunction`         | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                                                         |
 
 ### Example
 
@@ -443,8 +443,8 @@ 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, { stream: "navigation" })` awaits that
-loader before first flush on document renders — see "`stream: "navigation"`"
+exception is per-loader: `loader(Def, { ssr: false })` awaits that
+loader before first flush on document renders — see "`ssr: false`"
 below.)
 
 ### See it: `debugPerformance`
@@ -687,10 +687,10 @@ export const ProductLoader = createLoader(async (ctx) => {
 
 Semantics by lane:
 
-| Signal       | Document load                                                                                                                                                                                                                                                         | 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. `stream: "navigation"` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
-| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                                   | Redirect envelope navigates to the target         |
+| Signal       | Document load                                                                                                                                                                                                                                               | 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. | 404 UI swaps in, URL preserved, payload stays 200 |
+| `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                         | Redirect envelope navigates to the target         |
 
 Session/auth gates belong in middleware (they are request-shaped, not
 data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
@@ -725,14 +725,14 @@ barrier ride the SSR handle snapshot (in the SSR'd document — `<MetaTags />`,
 on document loads (`metadata.handlesLate`) or progressively on navigations.
 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
-`stream: "navigation"` below.
+`ssr: false` below.
 
 Reads are the other direction and gated: `ctx.get(handle)` throws unless the
 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).
 
-## `stream: "navigation"` — Guarantee a Loader in the Document
+## `ssr: false` — 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
@@ -743,12 +743,13 @@ use callback:
 
 ```typescript
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { stream: "navigation" }, () => [cache({ ttl: 60 })]),
+  loader(ProductLoader, { ssr: false }, () => [cache({ ttl: 60 })]),
   loader(RelatedLoader),   // untouched: still streams behind its boundary
 ]),
 ```
 
-The name says WHERE streaming still applies, not that it is disabled:
+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` reads it synchronously, no fallback paints), handle pushes beat
 the barrier snapshot, and a thrown `notFound()` deterministically precedes

package/skills/migrate-nextjs/SKILL.md

@@ -726,7 +726,7 @@ const HomePage: Handler<"home"> = (ctx) => {
 
 `generateMetadata({ params })` — DATA-derived, document-blocking metadata —
 maps to a Meta push from the LOADER that owns the data, plus
-`{ stream: "navigation" }` for the blocking-until-in-head part:
+`{ ssr: false }` for the blocking-until-in-head part:
 
 ```typescript
 // Next.js: export async function generateMetadata({ params }) {
@@ -744,7 +744,7 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader, { stream: "navigation" }),
+  loader(ProductLoader, { ssr: false }),
 ]);
 ```
 
@@ -843,7 +843,7 @@ See `/theme` for full API including system detection and cookie persistence.
 10. [ ] Convert loading/error files to `loading()` / `errorBoundary()`
 11. [ ] Migrate API routes to `path.json()` / `path.text()`
 12. [ ] Update metadata to use `Meta` handle + `<MetaTags />` in document head
-        (`generateMetadata` → loader push + `{ stream: "navigation" }`)
+        (`generateMetadata` → loader push + `{ ssr: false }`)
 13. [ ] Replace `next-themes` with `theme: true` in createRouter (see `/theme`)
 14. [ ] Map rendering-mode segment config: `revalidate = N` → `cache({ ttl })`,
         `force-static` → `Static()`/`Prerender()`, `experimental_ppr` → the

package/skills/migrate-react-router/component-migration.md

@@ -134,7 +134,7 @@ const HomePage: Handler<"home"> = (ctx) => {
 
 RR's data-derived `meta({ data })` maps to the same push from the LOADER that
 owns the data — `ctx.use(Meta)({ title: data.name })` in the loader body, with
-`loader(Def, { stream: "navigation" })` when the title must be in the SSR'd
+`loader(Def, { ssr: false })` when the title must be in the SSR'd
 head. See `/loader` → "Writing Handles from Loaders".
 
 Add `<MetaTags />` in the Document component's `<head>`:

package/skills/migrate-react-router/data-and-actions.md

@@ -46,7 +46,7 @@ Use it only when you need capabilities beyond what the handler provides:
   document loads, never an HTTP 302 — pre-stream 302s move to middleware)
 - **`meta({ data })` / `handle` exports** — data-derived page metadata becomes
   a handle push from the loader body (`ctx.use(Meta)({ title: data.name })`),
-  with `loader(L, { stream: "navigation" })` when it must be in the SSR'd head
+  with `loader(L, { ssr: false })` when it must be in the SSR'd head
 
 If the React Router loader just fetches data for its page component AND the
 component can become a server component, merge it into the handler. If the

package/skills/migrate-react-router/route-mapping.md

@@ -135,7 +135,7 @@ The loader-shaped variant is equally valid — and closer to the RR module when
 the loader carried authority. A `createLoader()` body can throw `notFound()`
 for the missing product AND push the data-derived meta itself
 (`ctx.use(Meta)({ title: product.name })`); register it with
-`loader(ProductLoader, { stream: "navigation" })` when the 404 status and
+`loader(ProductLoader, { ssr: false })` when the 404 status and
 title must be in the document deterministically. See `/loader` → "Loader
 Authority" and "Writing Handles from Loaders". (One RR habit that does NOT
 carry over: a loader `throw redirect()` is a client-side navigate on document

package/skills/parallel/SKILL.md

@@ -136,7 +136,7 @@ naturally.
 > the baked lane under `cache()`/PPR — just to reach a `ctx.use(Meta)` call.
 > The loader can now push `Meta` itself (`/loader` → "Writing Handles from
 > Loaders"), keeping the data on the live lane; add
-> `loader(Def, { stream: "navigation" })` when the meta must be in the SSR'd
+> `loader(Def, { ssr: false })` when the meta must be in the SSR'd
 > head. Keep the `@meta` slot for metadata that is NOT loader-derived
 > (templates, static descriptions, structured data with independent inputs).
 

package/skills/ppr/SKILL.md

@@ -669,7 +669,7 @@ LOADER-pushed Meta is different: loaders are masked at capture, so the push
 happens at request time and applies client-side (`metadata.handlesLate`) — it
 is never in the cached shell's head, by construction.
 
-One flag to know about here: `loader(Def, { stream: "navigation" })` (the
+One flag to know about here: `loader(Def, { ssr: false })` (the
 document-render await, `/loader`) is **inert under PPR** — capture renders
 mask loaders and skip the await, and a shell HIT flushes the stored prelude
 before loaders resolve. Flagging a loader on a `ppr` route does not bake it

package/skills/rango/SKILL.md

@@ -95,26 +95,26 @@ stated, greppable contract.
 
 ## Pick a primitive
 
-| I need to…                              | Use                                   | Skill                   |
-| --------------------------------------- | ------------------------------------- | ----------------------- |
-| render data fresh every request         | `loader()` + `useLoader()`            | /loader                 |
-| cache a rendered subtree                | `cache()` on a segment                | /caching                |
-| cache one function/component's result   | `"use cache"`                         | /use-cache              |
-| cache a loader's data                   | `loader(L, () => [cache()])`          | /loader, /caching       |
-| re-render a segment after an action     | `revalidate()`                        | /loader                 |
-| mutate                                  | `"use server"` action                 | /server-actions         |
-| debug a slow request                    | `debugPerformance` / telemetry        | /observability          |
-| share config across routes              | factory returning a helper array      | /composability          |
-| compose a sub-app / module              | `include()`                           | /route                  |
-| modal / soft navigation                 | `intercept()`                         | /intercept              |
-| 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, { stream: "navigation" })` | /loader                 |
-| pre-render a route at build time        | `Prerender(...)` wrapper              | /prerender              |
-| feed live loaders from a cached shell   | replayed handle + `ctx.rendered()`    | /shell-manifest         |
-| cache the HTML shell, keep loaders live | `ppr` path option                     | /ppr                    |
-| choose in-function vs CDN caching       | deployment cache boundary             | /deployment-caching     |
-| stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`        | /streams-and-websockets |
+| I need to…                              | Use                                | Skill                   |
+| --------------------------------------- | ---------------------------------- | ----------------------- |
+| render data fresh every request         | `loader()` + `useLoader()`         | /loader                 |
+| cache a rendered subtree                | `cache()` on a segment             | /caching                |
+| cache one function/component's result   | `"use cache"`                      | /use-cache              |
+| cache a loader's data                   | `loader(L, () => [cache()])`       | /loader, /caching       |
+| re-render a segment after an action     | `revalidate()`                     | /loader                 |
+| mutate                                  | `"use server"` action              | /server-actions         |
+| debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
+| share config across routes              | factory returning a helper array   | /composability          |
+| compose a sub-app / module              | `include()`                        | /route                  |
+| modal / soft navigation                 | `intercept()`                      | /intercept              |
+| 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                 |
+| pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
+| feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
+| cache the HTML shell, keep loaders live | `ppr` path option                  | /ppr                    |
+| choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
+| stream SSE / upgrade a WebSocket        | `path.stream()` / `path.any()`     | /streams-and-websockets |
 
 ## Invariants
 

package/skills/router-setup/SKILL.md

@@ -375,7 +375,7 @@ Handler and no-match cases set HTTP 404 status. A LOADER-thrown `notFound()`
 on a document load always streams the resolved not-found UI, but the 404
 STATUS is opportunistic — real only when the rejection settles before the
 document Response is constructed (loaders stream). Register the loader as
-`loader(Def, { stream: "navigation" })` to make the 404 status deterministic;
+`loader(Def, { ssr: false })` to make the 404 status deterministic;
 on client navigations the 404 UI swaps in with the URL preserved (payload
 stays 200 — the client owns presentation there). See `/loader` → "Loader
 Authority".

package/skills/scripts/SKILL.md

@@ -106,7 +106,7 @@ 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, { stream: "navigation" })` so the
+> to the document, register it `loader(Def, { ssr: false })` so the
 > document render awaits the push; otherwise push from a handler (or use an
 > `async` config, which stays reactive).
 

package/skills/shell-manifest/SKILL.md

@@ -151,7 +151,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
-  `{ stream: "navigation" }` (the document render awaits the loader before
+  `{ ssr: false }` (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/src/browser/react/Link.tsx

@@ -167,17 +167,28 @@ export interface LinkProps extends Omit<
 }
 
 /**
- * Check if URL is external (different origin)
+ * Check if URL is external (different origin). `origin` is resolved by the
+ * component from the navigation store location so SSR and browser agree —
+ * reading window here made every absolute-URL Link a hydration mismatch:
+ * on the server the ReferenceError was swallowed by the malformed-URL catch
+ * and the SSR HTML never carried data-external, then the browser evaluated
+ * the same link as external.
  */
-function isExternalUrl(href: string): boolean {
+function isExternalUrl(href: string, origin: string | undefined): boolean {
   // Protocol-relative URLs
   if (href.startsWith("//")) return true;
 
   // Absolute URLs
   if (href.startsWith("http://") || href.startsWith("https://")) {
+    // No known origin (no provider and no window): treat as internal — the
+    // pre-fix behavior for that configuration, and stable across hydration
+    // because both sides resolve the same store origin when a provider
+    // exists (the real-app case).
+    if (!origin) return false;
     try {
-      return new URL(href).origin !== window.location.origin;
+      return new URL(href).origin !== origin;
     } catch {
+      // Genuinely malformed absolute URL.
       return false;
     }
   }
@@ -225,7 +236,19 @@ export const Link: ForwardRefExoticComponent<
   ref,
 ) {
   const ctx = useContext(NavigationStoreContext);
-  const isExternal = isExternalUrl(to);
+  // Origin from the store location — the same both-sides source
+  // useSearchParams seeds from (SSR: the live request's URL; browser:
+  // window.location), so data-external agrees across hydration. Origin is
+  // immutable per document, so the inline getState() read cannot tear.
+  // window is the provider-less browser fallback (tests, portals outside
+  // the app root); provider-less SSR has no origin and keeps links internal.
+  const storeLocation = ctx?.eventController.getState().location as
+    | URL
+    | undefined;
+  const origin =
+    storeLocation?.origin ??
+    (typeof window !== "undefined" ? window.location.origin : undefined);
+  const isExternal = isExternalUrl(to, origin);
 
   // Auto-prefix with basename for app-local paths.
   // Skip if external, already prefixed, or not a root-relative path.

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

@@ -137,7 +137,7 @@ interface LoaderItem extends ItemBase {
   readonly type: "loader";
   readonly definition: LoaderDefinition<any, any>;
   readonly revalidate: readonly ClientRevalidateFn[];
-  readonly stream?: "navigation";
+  readonly ssr?: false;
 }
 
 interface RevalidateItem extends ItemBase {
@@ -380,9 +380,14 @@ function createHelpers(): ClientUrlHelpers {
     const options =
       typeof optionsOrUse === "function" ? undefined : optionsOrUse;
     const use = typeof optionsOrUse === "function" ? optionsOrUse : maybeUse;
-    if (options?.stream !== undefined && options.stream !== "navigation") {
+    if ((options as { stream?: unknown } | undefined)?.stream !== undefined) {
       throw new Error(
-        `clientUrls() loader() stream must be "navigation" (got ${JSON.stringify(options.stream)}). Omit it to stream on every render.`,
+        "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.",
+      );
+    }
+    if (options?.ssr !== undefined && typeof options.ssr !== "boolean") {
+      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.`,
       );
     }
     const items = use ? runUse(use, "loader use") : [];
@@ -397,9 +402,7 @@ function createHelpers(): ClientUrlHelpers {
             item.type === "revalidate",
         )
         .map((item) => item.fn),
-      ...(options?.stream === "navigation"
-        ? { stream: "navigation" as const }
-        : {}),
+      ...(options?.ssr === false ? { ssr: false as const } : {}),
     });
   };
 
@@ -505,9 +508,9 @@ function createHelpers(): ClientUrlHelpers {
     for (const item of items) {
       // Intercept loaders run on soft navigations only — a document-render
       // await can never apply, so accepting the flag would be silently inert.
-      if (item.type === "loader" && item.stream !== undefined) {
+      if (item.type === "loader" && item.ssr !== undefined) {
         throw new Error(
-          'clientUrls() intercept() loaders cannot use stream: "navigation" — intercepts render on client navigations only',
+          "clientUrls() intercept() loaders cannot use ssr: false — intercepts render on client navigations only",
         );
       }
     }
@@ -557,7 +560,7 @@ function applyConfig(
         Object.freeze({
           loader: item.definition,
           revalidate: Object.freeze([...item.revalidate]),
-          ...(item.stream ? { stream: item.stream } : {}),
+          ...(item.ssr === false ? { ssr: false as const } : {}),
         }),
       );
     } else if (item.type === "loading") {

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

@@ -89,10 +89,10 @@ export interface ClientUrlProjectionRoute {
   readonly options: ClientUrlProjectionOptions;
   readonly loaderIds: readonly string[];
   readonly hasLoading: boolean;
-  /** Indices into loaderIds of loaders declared loader(Def, { stream:
-   *  "navigation" }); materialization passes the option through to the server
-   *  loader() so document renders await them before first flush. Absent (=
-   *  none) in projections serialized before stream support. */
+  /** Indices into loaderIds of loaders declared loader(Def, { ssr: false });
+   *  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. */
   readonly awaitedLoaderIndices?: readonly number[];
   /** Data-only transition config (no `when` — server-tree only); absent in
    *  projections serialized before transition support. */
@@ -274,7 +274,7 @@ function serializeRoute(route: ClientUrlRouteRecord): ClientUrlProjectionRoute {
   });
 
   const awaitedLoaderIndices = route.loaders
-    .map(({ stream }, index) => (stream === "navigation" ? index : -1))
+    .map(({ ssr }, index) => (ssr === false ? index : -1))
     .filter((index) => index >= 0);
 
   const transition = serializeTransition(route);
@@ -526,7 +526,7 @@ function materializeRouteItems(
               loader(
                 createLoaderStub(id),
                 route.awaitedLoaderIndices?.includes(loaderIndex)
-                  ? { stream: "navigation" }
+                  ? { ssr: false }
                   : undefined,
                 () => [revalidate(makeClientDecisionRevalidate(id))],
               ),

package/src/client-urls/types.ts

@@ -87,12 +87,12 @@ export interface ClientUrlLoaderRecord {
   /** Client-run per-loader revalidation predicates; empty = locked defaults. */
   readonly revalidate: readonly ClientRevalidateFn[];
   /**
-   * loader(Def, { stream: "navigation" }): 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.
+   * loader(Def, { ssr: false }): 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 stream?: "navigation";
+  readonly ssr?: false;
 }
 
 /**
@@ -141,13 +141,14 @@ export interface ClientUrlHelpers {
    * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
    * the function) is sent with the revalidation request.
    *
-   * Pass `{ stream: "navigation" }` 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 dynamic 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 holes).
+   * 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.
+   * 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
+   * holes).
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,

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

@@ -807,8 +807,12 @@ const loader: RouteHelpers<any, any>["loader"] = (
     "loader() received two use() callbacks. Pass loader(Def, options, use) or loader(Def, use).",
   );
   invariant(
-    optionsGiven?.stream === undefined || optionsGiven.stream === "navigation",
-    `loader() stream must be "navigation" (got ${JSON.stringify(optionsGiven?.stream)}). Omit it to stream on every render.`,
+    (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.",
+  );
+  invariant(
+    optionsGiven?.ssr === undefined || typeof optionsGiven.ssr === "boolean",
+    `loader() ssr must be a boolean (got ${JSON.stringify(optionsGiven?.ssr)}). Omit it (or pass true) to stream on every render.`,
   );
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
@@ -820,7 +824,7 @@ const loader: RouteHelpers<any, any>["loader"] = (
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
-    ...(optionsGiven?.stream === "navigation" && ctx.isSSR
+    ...(optionsGiven?.ssr === false && ctx.isSSR
       ? { awaitBeforeFlush: true as const }
       : {}),
   };

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

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

package/src/router/loader-resolution.ts

@@ -572,7 +572,7 @@ function createLoaderExecutor<TEnv>(
         }
 
         // awaitBeforeFlush cycle: segment resolution awaits this loader
-        // (loader(Def, { stream: "navigation" })), the barrier awaits segment
+        // (loader(Def, { ssr: false })), 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
@@ -581,10 +581,10 @@ function createLoaderExecutor<TEnv>(
         if (reqCtx._awaitBeforeFlushLoaderIds?.has(currentLoaderId)) {
           throw new Error(
             `Deadlock: loader "${currentLoaderId}" is registered with ` +
-              `stream: "navigation", so the document render awaits it before ` +
+              `ssr: false, 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 ` +
-              `stream: "navigation" on this loader or move the handle read to ` +
+              `ssr: false on this loader or move the handle read to ` +
               `a component.`,
           );
         }

package/src/router/segment-resolution/fresh.ts

@@ -104,7 +104,7 @@ export async function resolveLoaders<TEnv>(
   const errorContext = buildLoaderErrorContext(ctx);
 
   if (emitStreaming) {
-    // awaitBeforeFlush (loader(Def, { stream: "navigation" })): document
+    // awaitBeforeFlush (loader(Def, { ssr: false })): document
     // renders await these loaders before returning, so their data is settled,
     // their handle pushes beat the barrier snapshot, and a thrown notFound()'s
     // status write deterministically precedes Response construction. The ids
@@ -148,7 +148,7 @@ export async function resolveLoaders<TEnv>(
               loaderEntry,
               ctx,
               ctx.pathname,
-              // The bake key rides for flagged loaders too: stream:"navigation"
+              // The bake key rides for flagged loaders too: ssr:false
               // bakes at capture regardless of the entry's loading() lane
               // (loader-cache.ts capture branch) and its HIT-tail seed
               // overlay needs the same key.

package/src/router/segment-resolution/loader-cache.ts

@@ -159,7 +159,7 @@ export function resolveLoaderData<TEnv>(
   if (isShellCaptureActive(reqCtx)) {
     // Capture lane, per LOADER (not per entry):
     //
-    // - `stream: "navigation"` (awaitBeforeFlush) — the BAKE lane. The flag's
+    // - `ssr: false` (awaitBeforeFlush) — the BAKE lane. The flag's
     //   document promise is "this loader's data is in the HTML before first
     //   flush"; under ppr the pre-flush HTML IS the frozen prelude, so the
     //   loader executes at capture and its SETTLED return bakes into the

package/src/router/segment-resolution/loader-mask.ts

@@ -44,7 +44,7 @@ export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
  * Entry-level lane input for an entry's loaders under PPR (the loading()
  * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
- * is per LOADER in loader-cache.ts: a `stream: "navigation"`
+ * is per LOADER in loader-cache.ts: an `ssr: false`
  * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
  * flag's document promise ("data in the HTML before first flush") maps to
  * the frozen prelude — while every other loader is LIVE (masked at capture,