@rangojs/router 0.8.0 → 0.10.0

package/src/segment-system.tsx

@@ -179,6 +179,30 @@ function wrapDefaultOutletContent(
   return createViewTransitionBoundary(transition, content);
 }
 
+/**
+ * Per-loader stream map for read-site suspension. { ssr: false } loaders were
+ * awaited before flush (fresh.ts), so deliver the SETTLED result, not the
+ * settled promise: the read site decodes synchronously instead of use()ing a
+ * Flight chunk whose fulfilled-at-read-time status is a scheduling race the
+ * SSR-completeness contract must not depend on. Unflagged siblings keep the
+ * promise (deliberate streaming). Flagged ids are collected as input for the
+ * dev SSR-suspension diagnostic (ssr-suspension-warning.ts).
+ */
+async function buildLoaderStreams(loaders: ResolvedSegment[]): Promise<{
+  streams: Record<string, unknown>;
+  awaitedIds: string[] | undefined;
+}> {
+  const streams: Record<string, unknown> = {};
+  let awaitedIds: string[] | undefined;
+  for (const l of loaders) {
+    streams[l.loaderId!] = l.awaitBeforeFlush
+      ? await l.loaderData
+      : l.loaderData;
+    if (l.awaitBeforeFlush) (awaitedIds ??= []).push(l.loaderId!);
+  }
+  return { streams, awaitedIds };
+}
+
 /**
  * Render segments into a React tree with proper layout nesting
  *
@@ -477,6 +501,7 @@ export async function renderSegments(
       // microtask suspension is what makes SSR emit the loading() fallback
       // for content-suspending routes (segment-loader-promise.ts).
       let boundaryLoaderStreams: Record<string, unknown> | undefined;
+      let boundaryAwaitedLoaderIds: string[] | undefined;
       if (forceAwait || isAction) {
         const awaitStart = segDebug ? performance.now() : 0;
         boundaryLoaderData = await loaderDataPromise;
@@ -487,10 +512,10 @@ export async function renderSegments(
           });
         }
       } else if (loaderEntries.length > 0) {
-        boundaryLoaderStreams = {};
-        for (const l of loaderEntries) {
-          boundaryLoaderStreams[l.loaderId!] = l.loaderData;
-        }
+        ({
+          streams: boundaryLoaderStreams,
+          awaitedIds: boundaryAwaitedLoaderIds,
+        } = await buildLoaderStreams(loaderEntries));
         if (segDebug) {
           segDebugLog(
             `segment ${id}: per-loader streams via LoaderBoundary (read-site suspense)`,
@@ -503,6 +528,7 @@ export async function renderSegments(
         loaderDataPromise: boundaryLoaderData,
         loaderIds,
         loaderStreams: boundaryLoaderStreams,
+        awaitedLoaderIds: boundaryAwaitedLoaderIds,
         fallback: loading,
         outletKey: key,
         outletContent,
@@ -537,6 +563,7 @@ export async function renderSegments(
       let loaderData: Record<string, any> = {};
       let errorFallback: ReactNode = null;
       let loaderStreams: Record<string, unknown> | undefined;
+      let awaitedLoaderIds: string[] | undefined;
       if (forceAwait || isAction) {
         const layoutAwaitStart = segDebug ? performance.now() : 0;
         const resolvedData = await buildLoaderPromise(layoutLoaders);
@@ -560,10 +587,8 @@ export async function renderSegments(
           }
         }
       } else if (layoutLoaders.length > 0) {
-        loaderStreams = {};
-        for (const l of layoutLoaders) {
-          loaderStreams[l.loaderId!] = l.loaderData;
-        }
+        ({ streams: loaderStreams, awaitedIds: awaitedLoaderIds } =
+          await buildLoaderStreams(layoutLoaders));
         if (segDebug) {
           segDebugLog(
             `segment ${id}: layout loaders streaming to read sites (no loading())`,
@@ -599,12 +624,29 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+          // Parallel slots must NOT take the loaderStreams path.
+          // LoaderResolver skips use(aggregate) when streams are set, so
+          // the already-rendered slot handler commits immediately. That
+          // bakes a live-lane hole into the shell (semantic-matrix PPR3 /
+          // shell-cache slot-use: masked loaderData is what pins
+          // "srv badge pending...") and, on reuse, leaves a stale stream
+          // map that ignores the post-action aggregate (mini @cart).
+          // Flagged (ssr:false) delivery still holds: when every owned
+          // loader paid the pre-flush await, settle the aggregate so
+          // LoaderResolver decodes the array without a Flight-chunk use().
+          const settleParallelAggregate =
+            forceAwait ||
+            isAction ||
+            ownedLoaders.every((l) => l.awaitBeforeFlush === true);
+          if (settleParallelAggregate) {
             const parallelAwaitStart = segDebug ? performance.now() : 0;
-            p.loaderDataPromise = await aggregated;
+            p.loaderDataPromise =
+              aggregated instanceof Promise ? await aggregated : aggregated;
+            p.loaderStreams = undefined;
+            p.awaitedLoaderIds = undefined;
             if (segDebug) {
               segDebugLog(
-                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action/ssr:false)`,
                 {
                   loaderIds: p.loaderIds,
                   ms: Math.round(performance.now() - parallelAwaitStart),
@@ -613,9 +655,11 @@ export async function renderSegments(
             }
           } else {
             p.loaderDataPromise = aggregated;
+            p.loaderStreams = undefined;
+            p.awaitedLoaderIds = undefined;
             if (segDebug) {
               segDebugLog(
-                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                `segment ${id}: parallel ${p.id} loaders via aggregate (suspense)`,
                 { loaderIds: p.loaderIds },
               );
             }
@@ -630,6 +674,7 @@ export async function renderSegments(
         parallel: node.parallel,
         loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
         loaderStreams,
+        awaitedLoaderIds,
         pending: outletPending,
         children: errorFallback ?? nodeContent,
       });

package/src/server/context.ts

@@ -108,7 +108,7 @@ export type LoaderEntry = {
   cache?: EntryCacheConfig;
   /**
    * Document renders await this loader before segment resolution returns
-   * (loader(Def, { stream: "navigation" })), so its data, handle pushes, and
+   * (loader(Def, { ssr: false })), so its data, handle pushes, and
    * thrown notFound()/redirect() deterministically precede first flush.
    * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
    * per-isSSR (router/manifest.ts cache key), so the flag is already

package/src/server/request-context.ts

@@ -620,7 +620,7 @@ export interface RequestContext<
 
   /**
    * @internal Loader IDs ($$id) whose entries carry `awaitBeforeFlush`
-   * (loader(Def, { stream: "navigation" })): segment resolution awaits these
+   * (loader(Def, { ssr: false })): segment resolution awaits these
    * before returning, so the render barrier cannot resolve until they settle.
    * rendered() checks this set to fail fast — a flagged loader awaiting the
    * barrier is a guaranteed cycle, not a race. Registered by resolveLoaders

package/src/ssr/index.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { createSsrRootComponent } from "./ssr-root.js";
+import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
@@ -26,6 +26,7 @@ interface RenderToReadableStreamOptions {
   bootstrapModules?: string[];
   nonce?: string;
   formState?: unknown;
+  progressiveChunkSize?: number;
 }
 
 /**
@@ -43,6 +44,7 @@ interface PrerenderOptions {
   bootstrapScriptContent?: string;
   bootstrapModules?: string[];
   onError?: (error: unknown) => void;
+  progressiveChunkSize?: number;
 }
 
 /**
@@ -114,6 +116,14 @@ export interface SSRRenderOptions {
    * only (runtime captures own the search variants, seeded per key).
    */
   search?: string;
+
+  /**
+   * The live request's origin, seeding the SSR store location so
+   * origin-dependent markup (Link's data-external) agrees with the
+   * browser's window.location across hydration. Absent on the build-time
+   * prerender pass (host-agnostic bare captures).
+   */
+  origin?: string;
 }
 
 /**
@@ -160,6 +170,23 @@ export interface SSRDependencies<TEnv = unknown> {
    */
   headScripts?: HeadScriptsOption;
 
+  /**
+   * Fizz `progressiveChunkSize`, forwarded verbatim to renderToReadableStream
+   * (live SSR) and prerender (shell capture); resume() inherits the capture
+   * value from the postponed state. The generated virtual SSR entry threads
+   * the `rango({ progressiveChunkSize })` plugin option here (canonical docs
+   * on `RangoBaseOptions.progressiveChunkSize` in vite/plugin-types.ts).
+   *
+   * When UNSET, createSSRHandler auto-raises to Number.MAX_SAFE_INTEGER for
+   * document renders whose matched chain has a `loader(Def, { ssr: false })`
+   * entry (payload segments carry `awaitBeforeFlush`): the loader was awaited
+   * before first flush precisely so its content ships in-place, and React
+   * 19.2's Fizz would otherwise move any completed boundary over ~500 bytes
+   * to an end-of-stream `<div hidden>` + $RC reveal once the shell saturates
+   * the default 12800 budget. An explicit value disables the auto-raise.
+   */
+  progressiveChunkSize?: number;
+
   /**
    * prerender from react-dom/static.edge. Optional; required only by
    * {@link createShellCaptureHandler} for PPR shell capture.
@@ -363,6 +390,13 @@ interface ShellCaptureOptions {
    * the shell's own key. MUST equal the resume pass's seed for the same key.
    */
   search?: string;
+  /**
+   * The capture request's origin. Shell keys are host-scoped, so the resume
+   * pass's request agrees modulo protocol drift; seeding it keeps
+   * origin-dependent static markup (Link's data-external) identical across
+   * capture, resume, and browser hydration.
+   */
+  origin?: string;
 }
 
 /**
@@ -391,6 +425,8 @@ interface ShellResumeOptions {
    * postponed holes.
    */
   search?: string;
+  /** The HIT request's origin — same host as the capture's (key-scoped). */
+  origin?: string;
 }
 
 /**
@@ -472,7 +508,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState, streamMode, search } = options ?? {};
+    const { nonce, formState, streamMode, search, origin } = options ?? {};
 
     try {
       // Tee the stream:
@@ -480,9 +516,21 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // - rscStream2: For browser hydration (inject as __FLIGHT_DATA__)
       const [rscStream1, rscStream2] = rscStream.tee();
 
+      // Deserialization starts here (not lazily on SsrRoot's first render) so
+      // the auto-raise below can read payload metadata before the fizz call.
+      // The parallel no-op catch keeps a payload rejection off the
+      // unhandledRejection path if fizz errors before consuming the promise;
+      // SsrRoot's React.use() on the SAME promise still observes the rejection.
+      const payload = deserializeSsrPayload(
+        createFromReadableStream,
+        rscStream1,
+      );
+      payload.catch(() => {});
+
       const SsrRoot = createSsrRootComponent({
         createFromReadableStream,
         rscStream: rscStream1,
+        payload,
         nonce,
         // Live fizz seeds the request's RAW search. The shell capture pass
         // below and its resume twin seed the SHELL KEY's search instead
@@ -490,11 +538,24 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         // same key => same seed, so the resume tree matches the captured
         // tree while static-part search reads render what the key names.
         search,
+        origin,
       });
 
       // Get bootstrap script content
       const bootstrapScriptContent = await loadBootstrapScriptContent();
 
+      // ssr:false auto-raise (see SSRDependencies.progressiveChunkSize).
+      // Awaiting the payload here is latency-neutral: fizz cannot emit even
+      // <html> until this same promise settles. A rejection lands in the
+      // catch below — the same reportRenderError path a shell error takes.
+      let progressiveChunkSize = deps.progressiveChunkSize;
+      if (progressiveChunkSize === undefined) {
+        const resolved = await payload;
+        if (resolved.metadata?.segments?.some((s) => s.awaitBeforeFlush)) {
+          progressiveChunkSize = Number.MAX_SAFE_INTEGER;
+        }
+      }
+
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided
       // Pass nonce for CSP if provided. runWithPreinitNonce makes the same
@@ -505,6 +566,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
           formState,
           nonce,
+          ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
         }),
       );
 
@@ -594,6 +656,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
         // The shell key's own search: static-part search reads render what
         // the key names, and the resume pass seeds the identical string.
         search: opts.search,
+        origin: opts.origin,
       });
 
       // Bootstrap load raced against the deadline. A load that never resolves
@@ -627,6 +690,14 @@ export function createShellCaptureHandler<TEnv = unknown>(
       const prerenderPromise = prerender(<SsrRoot />, {
         signal: controller.signal,
         ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+        // Explicit option only — the ssr:false auto-raise is live-SSR scoped
+        // (RangoBaseOptions.progressiveChunkSize documents the contract); the
+        // capture handler starts prerender without deserializing the payload,
+        // so segment metadata is not read here. The captured value rides the
+        // postponed state into every later resume().
+        ...(deps.progressiveChunkSize !== undefined && {
+          progressiveChunkSize: deps.progressiveChunkSize,
+        }),
         // Abort is how capture WORKS: once the shell is quiet we abort() to
         // freeze the prelude and let the still-pending holes postpone. React
         // reports the abort reason for each pending boundary through onError.
@@ -767,7 +838,7 @@ export function createShellResumeHandler<TEnv = unknown>(
     rscStream: ReadableStream<Uint8Array>,
     opts: ShellResumeOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { postponed, nonce, search } = opts;
+    const { postponed, nonce, search, origin } = opts;
 
     try {
       if (postponed === null) {
@@ -800,6 +871,7 @@ export function createShellResumeHandler<TEnv = unknown>(
         // Same seed as the capture pass for this key: the resume tree must
         // match the captured tree above the holes, search reads included.
         search,
+        origin,
       });
 
       // EAGER injection (resume-only): the stored prelude — a complete document

package/src/ssr/ssr-root.tsx

@@ -70,13 +70,22 @@ function createSsrEventController(opts: {
    * names and both passes agree byte-for-byte.
    */
   search?: string;
+  /**
+   * Origin seeding the store location. Live fizz passes the request's real
+   * origin so origin-dependent markup (Link's data-external compares link
+   * origins against it) agrees with the browser's window.location; ppr
+   * capture/resume pass their request's origin (shell keys are host-scoped,
+   * so the two agree modulo protocol drift). Absent (build-time bare
+   * captures, tests) falls back to the historical internal host.
+   */
+  origin?: string;
   params?: Record<string, string>;
   handleData?: HandleData;
   matched?: string[];
 }): EventController {
   const location = new URL(
     `${opts.pathname}${opts.search ?? ""}`,
-    "http://localhost",
+    opts.origin ?? "http://localhost",
   );
   let params = opts.params ?? {};
   const rawMatched = opts.matched ?? [];
@@ -130,6 +139,37 @@ function createSsrEventController(opts: {
   };
 }
 
+/**
+ * Deserialize the Flight stream branch into the payload SsrRoot renders,
+ * fragment expansion included. Factored out of SsrRoot so createSSRHandler can
+ * create the promise BEFORE fizz starts and read metadata that must influence
+ * the fizz call itself (the ssr:false progressiveChunkSize auto-raise) —
+ * awaiting it there is latency-neutral because fizz cannot emit even <html>
+ * until this same promise settles.
+ */
+export function deserializeSsrPayload(
+  createFromReadableStream: CreateFromReadableStream,
+  rscStream: ReadableStream<Uint8Array>,
+): Promise<RscPayload> {
+  // Shell-HIT tails carry replayed segments as VERBATIM stored fragments
+  // (segment-fragments.ts, issue #700); expand them through this
+  // environment's deserializer before anything reads the segments. Every
+  // other payload (full render, capture, actions) has no envelopes and
+  // pays one field scan.
+  // Promise.resolve() adoption is load-bearing: some wirings (the build
+  // temp server's vendored Flight client) return a THENABLE Chunk whose
+  // .then returns undefined — chaining on it directly yields undefined.
+  return Promise.resolve(createFromReadableStream<RscPayload>(rscStream)).then(
+    async (resolvedPayload) => {
+      await expandSegmentFragments(
+        resolvedPayload.metadata?.segments,
+        createFromReadableStream,
+      );
+      return resolvedPayload;
+    },
+  );
+}
+
 /**
  * Options for {@link createSsrRootComponent}.
  */
@@ -138,6 +178,13 @@ export interface SsrRootOptions {
   createFromReadableStream: CreateFromReadableStream;
   /** The Flight stream branch to deserialize into the SSR VDOM. */
   rscStream: ReadableStream<Uint8Array>;
+  /**
+   * Pre-created payload promise (deserializeSsrPayload over the SAME
+   * rscStream). When present SsrRoot adopts it instead of deserializing
+   * lazily on first render — the stream can only be consumed once, so the
+   * caller that already started deserialization MUST pass the promise in.
+   */
+  payload?: Promise<RscPayload>;
   /** Nonce for CSP; propagated to NonceContext. */
   nonce?: string;
   /**
@@ -162,6 +209,11 @@ export interface SsrRootOptions {
    * the resume tree matches the captured tree above the postponed holes.
    */
   search?: string;
+  /**
+   * Origin seeding the SSR store location (see createSsrEventController):
+   * live fizz passes the request's origin; capture/resume pass theirs.
+   */
+  origin?: string;
 }
 
 /**
@@ -188,35 +240,26 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     nonce,
     onPayloadSettled,
     search,
+    origin,
   } = opts;
 
-  let payload: Promise<RscPayload> | undefined;
+  // onPayloadSettled fires AFTER fragment expansion (inside
+  // deserializeSsrPayload): the capture's fizz-readiness gate must include
+  // fragment module loads.
+  const adoptPayload = (p: Promise<RscPayload>): Promise<RscPayload> => {
+    if (onPayloadSettled) p.then(onPayloadSettled, onPayloadSettled);
+    return p;
+  };
+  let payload: Promise<RscPayload> | undefined =
+    opts.payload && adoptPayload(opts.payload);
   let handlesPromise: Promise<HandleData> | undefined;
   let ssrContextValue: NavigationStoreContextValue | undefined;
   let rootPromise: Promise<React.ReactNode> | undefined;
 
   return function SsrRoot() {
-    if (payload === undefined) {
-      // Shell-HIT tails carry replayed segments as VERBATIM stored fragments
-      // (segment-fragments.ts, issue #700); expand them through this
-      // environment's deserializer before anything reads the segments. Every
-      // other payload (full render, capture, actions) has no envelopes and
-      // pays one field scan. onPayloadSettled fires AFTER expansion: the
-      // capture's fizz-readiness gate must include fragment module loads.
-      // Promise.resolve() adoption is load-bearing: some wirings (the build
-      // temp server's vendored Flight client) return a THENABLE Chunk whose
-      // .then returns undefined — chaining on it directly yields undefined.
-      payload = Promise.resolve(
-        createFromReadableStream<RscPayload>(rscStream),
-      ).then(async (resolvedPayload) => {
-        await expandSegmentFragments(
-          resolvedPayload.metadata?.segments,
-          createFromReadableStream,
-        );
-        return resolvedPayload;
-      });
-      if (onPayloadSettled) payload.then(onPayloadSettled, onPayloadSettled);
-    }
+    payload ??= adoptPayload(
+      deserializeSsrPayload(createFromReadableStream, rscStream),
+    );
     const resolved = React.use(payload);
 
     const themeConfig = resolved.metadata?.themeConfig ?? null;
@@ -238,6 +281,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
       eventController: createSsrEventController({
         pathname,
         search,
+        origin,
         params: resolved.metadata?.params,
         handleData,
         matched: resolved.metadata?.matched,

package/src/ssr-suspension-warning.ts

@@ -0,0 +1,68 @@
+/**
+ * Dev-only diagnostic for the { ssr: false } SSR-completeness opt-in.
+ *
+ * A document render that awaits flagged loaders before first flush is usually
+ * expected to produce an SSR-complete boundary — but the await is scoped per
+ * LOADER (see LoaderOptions in types/loader-types.ts), so one unflagged read
+ * under the same Suspense boundary still suspends it and the boundary streams
+ * as its fallback, invisible without JS. That failure mode looks exactly like
+ * the flag not working; a consumer app burned hours on byte-level archaeology
+ * before the unflagged sibling read was identified. This warning names the
+ * culprit at the suspension site instead.
+ *
+ * Fires at most once per loader id per process, only during the SSR pass
+ * (`window` undefined), only in dev, and only when the render actually awaited
+ * flagged loaders (`awaitedLoaderIds`, stamped by segment resolution on
+ * document AND shell-capture renders — capture awaits the same flagged lane;
+ * its masked live-lane reads suspend by design and dedupe against the live
+ * render's warnings through the once-per-id set).
+ */
+
+const warned = new Set<string>();
+
+/** Thenable statuses `use()` unwraps without suspending: React's re-check
+ *  after `.then()` handles "fulfilled", and Flight chunks in the resolved_*
+ *  states initialize synchronously inside that same call. Anything else
+ *  (pending, blocked, an unstamped native promise) suspends at least once. */
+function unwrapsSynchronously(stream: Promise<unknown>): boolean {
+  const status = (stream as { status?: string }).status;
+  return (
+    status === "fulfilled" ||
+    status === "resolved_model" ||
+    status === "resolved_module"
+  );
+}
+
+export function warnAwaitedSsrSuspension(
+  loaderId: string,
+  awaitedLoaderIds: readonly string[] | undefined,
+  stream: Promise<unknown>,
+  isServer: boolean = typeof window === "undefined",
+): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (!isServer) return;
+  if (!awaitedLoaderIds || awaitedLoaderIds.length === 0) return;
+  if (unwrapsSynchronously(stream)) return;
+  if (warned.has(loaderId)) return;
+  warned.add(loaderId);
+
+  if (awaitedLoaderIds.includes(loaderId)) {
+    console.error(
+      `[rango] Loader "${loaderId}" is flagged { ssr: false } and was awaited ` +
+        `before first flush, but its useLoader read observed a still-pending ` +
+        `promise during SSR. If its Suspense fallback appears in the SSR'd HTML, ` +
+        `please report it to @rangojs/router with a reproduction.`,
+    );
+    return;
+  }
+
+  console.warn(
+    `[rango] The document render awaited { ssr: false } loader(s) ` +
+      `${JSON.stringify(awaitedLoaderIds)} before first flush, but ` +
+      `useLoader("${loaderId}") still suspended during SSR. "${loaderId}" is not ` +
+      `flagged, so the Suspense boundary above that read streams as its fallback ` +
+      `and the content under it stays hidden until JS runs. If the boundary must ` +
+      `be SSR-complete, flag "${loaderId}" with { ssr: false } too, or move its ` +
+      `read behind its own boundary. If it streams deliberately, ignore this.`,
+  );
+}

package/src/types/loader-types.ts

@@ -75,7 +75,7 @@ export type LoaderContext<
    * later ones stream to the client and apply post-hydration (document lane)
    * or progressively (navigation/action lanes). To guarantee a loader's
    * handles are in the SSR'd document, register it as
-   * `loader(Def, { stream: "navigation" })` so the document render awaits it
+   * `loader(Def, { ssr: false })` so the document render awaits it
    * (see {@link LoaderOptions}).
    *
    * @example
@@ -174,29 +174,35 @@ export type LoaderFn<
 > = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
 
 /**
- * Delivery mode for a DSL-registered loader: `loader(Def, { stream })`.
+ * SSR delivery for a DSL-registered loader: `loader(Def, { ssr })`.
  *
- * Default (omitted): the loader streams on every render. Its data, its
- * `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws may land
- * AFTER the document Response is constructed, so none of them are guaranteed to
- * be in the SSR'd HTML.
+ * Default (omitted / `true`): the loader streams on every render. Its data,
+ * its `ctx.use(Handle)` pushes, and any `notFound()`/`redirect()` it throws
+ * may land AFTER the document Response is constructed, so none of them are
+ * guaranteed to be in the SSR'd HTML.
  *
- * `"navigation"` narrows streaming to client navigations only: on a DOCUMENT
- * request the loader is awaited before first flush. `useLoader` still suspends,
- * but on an already-settled promise, so no fallback paints. This is the
- * SSR-completeness opt-in — the name is about WHERE streaming still applies, not
- * about disabling it. Choose it when the loader feeds something that must exist
- * in the document: `<head>` meta via a handle, or a real 404 status (an awaited
- * `notFound()` deterministically precedes Response construction, where the
- * streamed default only wins that race opportunistically). It does NOT change
- * PPR capture behavior: capture renders mask loaders and skip this await.
+ * `ssr: false` turns SSR streaming off for this loader — the same knob
+ * `loading(fallback, { ssr: false })` is for the fallback: on a DOCUMENT
+ * request the loader is awaited before first flush, so no fallback paints for
+ * it (`useLoader` still suspends, but on an already-settled promise). Client
+ * navigations keep streaming it. This is the SSR-completeness opt-in. Choose
+ * it when the loader feeds something that must exist in the document:
+ * `<head>` meta via a handle, or a real 404 status (an awaited `notFound()`
+ * deterministically precedes Response construction, where the streamed
+ * default only wins that race opportunistically). Under ppr it is also the
+ * BAKE lane: the loader executes at shell capture and its settled return is
+ * shell material (nested promises stay live holes) — see the ppr docs.
  *
- * Scoped per LOADER, not per segment: a baked loader alongside a deliberately
- * dynamic sibling awaits only itself, and the sibling keeps streaming behind its
- * `loading()`/Suspense boundary.
+ * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
+ * deliberately streaming sibling awaits only itself, and the sibling keeps
+ * streaming behind its `loading()`/Suspense boundary. Watch the scoping when
+ * the boundary must be SSR-complete: ONE unflagged read under it still
+ * suspends the whole boundary, which then streams as its fallback — looking
+ * exactly like the flag not working. In dev the router warns at the read
+ * site naming the unflagged loader (ssr-suspension-warning.ts).
  */
 export type LoaderOptions = {
-  stream?: "navigation";
+  ssr?: boolean;
 };
 
 /**

package/src/types/segments.ts

@@ -166,10 +166,27 @@ export interface ResolvedSegment {
   loaderId?: string; // For loaders: the loader $$id identifier
   _inherited?: boolean; // For inherited loaders: dedup marker for buildMatchResult
   loaderData?: any; // For loaders: the resolved data from loader execution
+  /**
+   * True when this loader was awaited before first flush
+   * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on
+   * document AND shell-capture renders — capture bakes flagged loaders and
+   * awaits the same lane. Feeds segment-system's settled-value delivery and
+   * the dev SSR suspension warning (ssr-suspension-warning.ts).
+   */
+  awaitBeforeFlush?: true;
   parallelLoading?: ReactNode; // For parallel-owned loaders: the parallel's loading fallback
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
+  /**
+   * Per-loader UNDECODED results for a layout/route stream map.
+   * Flagged (ssr:false) entries are settled values; unflagged siblings
+   * stay promises. Parallel slots do not use this channel — they pin
+   * loading() / live-lane holes via use(loaderDataPromise).
+   */
+  loaderStreams?: Record<string, unknown>;
+  /** $$ids of loaders this segment awaited before flush. Dev diagnostic. */
+  awaitedLoaderIds?: string[];
   // Error-specific fields
   error?: ErrorInfo; // For error segments: the error information
   // NotFound-specific fields