@rangojs/router 0.34.1 → 0.35.0

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

@@ -261,7 +261,7 @@ function chainLoaderEntries(entry: EntryData): readonly LoaderEntry[] {
 
 /**
  * The lane of each loader the matched chain `entries` registers: "live" (no
- * `ssr: false`) or "bake". A loader registered on both is "live". A PPR
+ * `ssr: "await"`) or "bake". A loader registered on both is "live". A PPR
  * capture credits a push to the first registered loader around it when that
  * one is live (shell-capture.ts deriveShellCaptureContext).
  */
@@ -302,7 +302,7 @@ function servedPins(
 
 /**
  * This request serves `loaderEntry` from a pin (servedPins), so its body does
- * not decide the value: resolveLoaderData serves a pin to an `ssr: false`
+ * not decide the value: resolveLoaderData serves a pin to an `ssr: "await"`
  * registration only. A prefetch does not defer such a loader
  * (prefetch-deferral.ts defersLoader): nothing would run, and the pin is the
  * value the document shows.
@@ -325,14 +325,14 @@ export function servesLoaderPin(
  * only and the store asks while loader bodies run.
  *
  * Each side applies its own lane to the pin. The value is per registration
- * (resolveLoaderData: an `ssr: false` registration is served its pin). The
- * pushes are per loader: one the route also registers without `ssr: false`
+ * (resolveLoaderData: an `ssr: "await"` registration is served its pin). The
+ * pushes are per loader: one the route also registers without `ssr: "await"`
  * is a hole whatever its other registration's pin says, because the capture
  * credited its pushes to the live registration's run (routeLoaderLanes).
  *
  * A dependency the route does not register has no pin of its own, and the
  * record does not name the loader that ran it at capture: its copies stand
- * only while every `ssr: false` loader is pinned (exact when the pins are
+ * only while every `ssr: "await"` loader is pinned (exact when the pins are
  * all there or all gone).
  */
 export function loaderPins(
@@ -482,7 +482,7 @@ function recordOwnerKey(cachedLoaderId: string): () => string {
  * never run under a shell capture), so the lane is decided here, per LOADER,
  * never by the entry's loading():
  *
- * - BAKE lane: `loader(Def, { ssr: false })` (LoaderEntry `bake`: the
+ * - BAKE lane: `loader(Def, { ssr: "await" })` (LoaderEntry `bake`: the
  *   caller passes a `bakeSegmentKey` for it on document and navigation
  *   evaluations alike; a capture, a document evaluation, also has
  *   awaitBeforeFlush). The loader EXECUTES at capture (the
@@ -504,7 +504,7 @@ function recordOwnerKey(cachedLoaderId: string): () => string {
  *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an
  *   inline Suspense — then streams fresh per request. A masked read with NO
  *   boundary above it root-postpones and the <body> sanity gate refuses the
- *   shell (eternal-MISS warning). A route whose loaders are ALL `ssr: false`
+ *   shell (eternal-MISS warning). A route whose loaders are ALL `ssr: "await"`
  *   needs no loading(): nothing masks.
  */
 export function resolveLoaderData<TEnv>(
@@ -540,7 +540,7 @@ export function resolveLoaderData<TEnv>(
     return createMaskedLoaderPromise();
   }
 
-  // `bake`: the pin is the `ssr: false` registration's. The caller's key is
+  // `bake`: the pin is the `ssr: "await"` registration's. The caller's key is
   // passed for an unflagged loader of an entry without loading() too.
   if (bakeSegmentKey && loaderEntry.bake) {
     const recorded = servedPins(reqCtx)?.get(loaderEntry.loader.$$id);

package/src/router/segment-resolution/prefetch-deferral.ts

@@ -283,7 +283,7 @@ function collectDeferrable(
     for (const loaderEntry of entry.loader ?? []) {
       const own = counts(loaderEntry.prefetch);
       if (!own && behind.length === 0) continue;
-      // An ssr: false loader on a ppr route is in scope too: whether this
+      // An ssr: "await" loader on a ppr route is in scope too: whether this
       // request serves it from a shell pin is per request (defersLoader).
       loaders.set(loaderEntry, own ? true : behind);
     }

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

@@ -472,7 +472,7 @@ export async function resolveOwnerLoaders<TEnv>(
           loaderEntry,
           ctx,
           ctx.pathname,
-          // The bake key rides for flagged loaders too (`bake`): ssr: false
+          // The bake key rides for flagged loaders too (`bake`): ssr: "await"
           // bakes at capture regardless of the entry's loading() lane
           // (loader-cache.ts capture branch), its HIT-tail seed overlay needs
           // the same key, and on a navigation it pins exactly as on the
@@ -510,7 +510,7 @@ export async function resolveOwnerLoaders<TEnv>(
     ? buildLoaderErrorContext(ctx)
     : { ...buildLoaderErrorContext(ctx), isPartial: true };
 
-  // FRESH: awaitBeforeFlush (loader(Def, { ssr: false })). A document render
+  // FRESH: awaitBeforeFlush (loader(Def, { ssr: "await" })). A document render
   // awaits 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 must
@@ -554,7 +554,7 @@ export async function resolveOwnerLoaders<TEnv>(
       registerDeferredLoader(ctx, loader.$$id, shortCode, () =>
         kickoff(loaderEntry, segmentId),
       );
-      // A ppr shell record this request restored keeps an ssr: false
+      // A ppr shell record this request restored keeps an ssr: "await"
       // loader's pushes as copies that wait for its run (loaderPins "hole").
       // No run is made here: drop them, the fill sends the run's pushes.
       _getRequestContext()?._handleStore?.settleLoaderRun(loader.$$id);

package/src/router/types.ts

@@ -58,7 +58,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
       env?: TEnv;
       isPartial?: boolean;
     },
-    /** An `ssr: false` loader on a document or capture render. */
+    /** An `ssr: "await"` loader on a document or capture render. */
     useDefaultErrorBoundary?: boolean,
   ) => Promise<LoaderDataResult<T>>;
   trackHandler: <T>(

package/src/rsc/shell-capture-constants.ts

@@ -210,12 +210,12 @@ export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
  * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
  * result): `identity` (a request-scoped read: cookies(), headers(), the
  * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
- * `loader` (a `{ ssr: false }` loader rejected, settled with
+ * `loader` (a `{ ssr: "await" }` loader rejected, settled with
  * redirect()/notFound(), or a promise it pushed rejected),
  * `no-record` (no doc record: the route's cache() refused the write, or the
  * handler output failed), `handles` (a pushed
  * handle value did not finish encoding), `size` (over the store's value
- * limit, or `ssr: false` loader pins over `ppr.maxSnapshotBytes`: a
+ * limit, or `ssr: "await"` loader pins over `ppr.maxSnapshotBytes`: a
  * navigation-only entry was stored in place of the document shell),
  * `record-expired` (the route cache() record
  * the capture wrote ran out first), `invalidated` (a tag of the shell was
@@ -241,7 +241,7 @@ export type ShellCaptureRefusal =
  * rule: resolveLoaderData (router/segment-resolution/loader-cache.ts).
  */
 export const PPR_LANE_HINT: string =
-  "Lane rule: only loader(Def, { ssr: false }) executes at capture and bakes its " +
+  'Lane rule: only loader(Def, { ssr: "await" }) executes at capture and bakes its ' +
   "non-promise data; every other loader is live (masked at capture, fresh per " +
   "request) and needs loading() or an inline <Suspense> above its reader. See the " +
   '/ppr skill, "The loader lane rule" (node_modules/@rangojs/router/skills/ppr/SKILL.md).';

package/src/rsc/shell-capture.ts

@@ -391,15 +391,15 @@ function warnNullCaptureOnce(
       (cause
         ? `Cause: ${cause}. Every capture waits for the handler layer to finish and ` +
           'bakes it; make the slow part cheaper (cache() or "use cache"), raise ' +
-          "ppr.captureTimeout, or move it into a live loader (no ssr: false) read under " +
+          'ppr.captureTimeout, or move it into a live loader (no ssr: "await") read under ' +
           "loading() or an inline <Suspense>.\n"
         : "Causes, told apart by whether the route ever flips to HIT:\n" +
           "  1. Cold-start warmup (dev module transform, or a cold worker): the capture raced " +
           "an unfinished shell render. This SELF-HEALS — the route flips to HIT once a later " +
           "request warms the modules.\n" +
           "  2. Something suspends above <body> with no Suspense boundary and never settles " +
-          "within the capture window: a live loader (no ssr: false) read without loading() or " +
-          "an inline <Suspense>, or a loader(Def, { ssr: false }) or top-level push (e.g. Meta) " +
+          'within the capture window: a live loader (no ssr: "await") read without loading() or ' +
+          'an inline <Suspense>, or a loader(Def, { ssr: "await" }) or top-level push (e.g. Meta) ' +
           "slower than ppr.captureTimeout. The boundary belongs to the entry or component " +
           "that owns the data.\n") +
       (pendingStacks && pendingStacks.length > 0
@@ -565,8 +565,8 @@ function warnSnapshotOverCapOnce(
     key,
     () =>
       `[rango] Shell capture for "${key}" recorded ${snapshotBytes} bytes of ` +
-      `ssr: false loader pins, over the ${capBytes}-byte cap: the document ` +
-      "shell was not stored; raise maxSnapshotBytes or shrink the ssr: false " +
+      `ssr: "await" loader pins, over the ${capBytes}-byte cap: the document ` +
+      'shell was not stored; raise maxSnapshotBytes or shrink the ssr: "await" ' +
       "data. Documents of this route are a MISS until then; client " +
       "navigations still replay its handler layer.",
   );
@@ -599,9 +599,9 @@ function warnBakeCostOnce(key: string, source: string, ms: number): void {
       "of the route and occupies the per-isolate capture queue; the served " +
       "response never shows it. To keep it baked but cheap, wrap the work in " +
       'cache() or "use cache"; to make it per-request, load it in a live ' +
-      "loader (no ssr: false) read under loading() or an inline <Suspense>; for " +
-      "a loader(Def, { ssr: false }), return the slow part as a nested promise " +
-      "or drop ssr: false. " +
+      'loader (no ssr: "await") read under loading() or an inline <Suspense>; for ' +
+      'a loader(Def, { ssr: "await" }), return the slow part as a nested promise ' +
+      'or drop ssr: "await". ' +
       PPR_LANE_HINT,
   );
 }
@@ -1747,7 +1747,7 @@ export async function settleCaptureRecord(
       capture.key,
       `${describeLoaderPromisePush(rejected)} rejected during capture; a ` +
         "failed value must not bake into the shared shell. Catch it and push " +
-        "a fallback, or push it from a loader without ssr: false.",
+        'a fallback, or push it from a loader without ssr: "await".',
       PPR_LANE_HINT,
     );
     return { kind: "refused", refusal: "loader" };
@@ -2209,7 +2209,7 @@ export function deriveShellCaptureContext(
   //    cache() record's restore (handle-snapshot.ts restoreHandles) lands
   //    here too: a value it restores as a placeholder keeps that loader as
   //    owner, so a HIT restores it as that loader's (pushRestored).
-  //  - DSL-LOADER pushes. Only bake-lane { ssr: false } loaders and the
+  //  - DSL-LOADER pushes. Only bake-lane { ssr: "await" } loaders and the
   //    loaders they await via ctx.use execute at capture (live loaders are
   //    masked), their pushes are in the captured HTML (<head> title/meta,
   //    useHandle echoes), and a HIT does not run a promise-free bake-lane
@@ -2547,7 +2547,7 @@ async function captureAndStoreShell(
           warnCaptureRefusedOnce(
             capture.key,
             `the loader for segment "${segmentKey}" rejected during capture; its error UI must not bake into the shared shell. ` +
-              "Fix the loader, or drop its ssr: false to move it to the live lane.",
+              'Fix the loader, or drop its ssr: "await" to move it to the live lane.',
             PPR_LANE_HINT,
           );
           return refuse(stats, "loader");
@@ -2564,7 +2564,7 @@ async function captureAndStoreShell(
           warnCaptureRefusedOnce(
             capture.key,
             `the loader for segment "${segmentKey}" settled with redirect()/notFound() during capture; a request-specific signal must not bake into the shared shell. ` +
-              "Drop its ssr: false to move it to the live lane, or move the decision into middleware.",
+              'Drop its ssr: "await" to move it to the live lane, or move the decision into middleware.',
             PPR_LANE_HINT,
           );
           return refuse(stats, "loader");

package/src/segment-system.tsx

@@ -294,7 +294,7 @@ function wrapDefaultOutletContent(
 }
 
 /**
- * Per-loader stream map for read-site suspension. { ssr: false } loaders were
+ * Per-loader stream map for read-site suspension. { ssr: "await" } loaders were
  * awaited before flush (resolveOwnerLoaders), 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
@@ -844,7 +844,7 @@ export async function renderSegments(
           // 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
+          // Flagged (ssr: "await") 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 = settlesLoaders(
@@ -860,7 +860,7 @@ export async function renderSegments(
             p.awaitedLoaderIds = undefined;
             if (segDebug) {
               segDebugLog(
-                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action/ssr:false)`,
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action/ssr: "await")`,
                 {
                   loaderIds: p.loaderIds,
                   ms: Math.round(performance.now() - parallelAwaitStart),

package/src/server/context.ts

@@ -154,7 +154,7 @@ export type LoaderEntry = {
   cache?: EntryCacheConfig;
   /**
    * Document renders await this loader before segment resolution returns
-   * (loader(Def, { ssr: false })), so its data, handle pushes, and
+   * (loader(Def, { ssr: "await" })), 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
@@ -164,7 +164,7 @@ export type LoaderEntry = {
    */
   awaitBeforeFlush?: true;
   /**
-   * loader(Def, { ssr: false }) on every DSL evaluation, document and
+   * loader(Def, { ssr: "await" }) on every DSL evaluation, document and
    * navigation: the loader's PPR bake lane (loader-cache.ts
    * resolveLoaderData). The bake/seed key rides on it, so a client
    * navigation's shell replay pins exactly the loaders a document HIT pins,
@@ -913,7 +913,7 @@ export function getIsolatedLazyParent(
  * called from both.
  */
 
-/** loader(Def, { ssr: false }): a document awaits it before the first flush. */
+/** loader(Def, { ssr: "await" }): a document awaits it before the first flush. */
 export function documentModeLoader(entry: LoaderEntry): LoaderEntry {
   return entry.bake ? { ...entry, awaitBeforeFlush: true } : entry;
 }
@@ -1213,11 +1213,11 @@ export function requestReadCaptureFix(
     capture:
       `The captured shell is served to every user of this URL, so ` +
       `request-scoped data read here would leak one user's ${what} to ` +
-      `others. Read it inside a loader without ssr: false and consume it ` +
+      `others. Read it inside a loader without ssr: "await" and consume it ` +
       `with useLoader, e.g. createLoader(async () => ` +
       `getUser(cookies().get("session")?.value)). ${PPR_LANE_HINT}`,
     warning:
-      "Read it in a loader without ssr: false and consume it with useLoader " +
+      'Read it in a loader without ssr: "await" and consume it with useLoader ' +
       "under loading() or an inline <Suspense> (a live hole). A promise the " +
       "handler passes or pushes does not help: the capture waits for it.",
   };

package/src/server/cookie-store.ts

@@ -195,7 +195,7 @@ export function guardRequestHeaders(request: Request): Request {
 /** The fix for a theme read that a cache() boundary or a ppr capture refuses. */
 const THEME_READ_FIX =
   "On ppr and cache() routes, read the theme with useTheme() in a client " +
-  "component, or in a live loader (no ssr: false) with cookies().get(<storageKey>). " +
+  'component, or in a live loader (no ssr: "await") with cookies().get(<storageKey>). ' +
   "The <html> theme class needs neither: the theme script sets it before paint. " +
   "See the /theme skill (node_modules/@rangojs/router/skills/theme/SKILL.md).";
 

package/src/server/request-context.ts

@@ -863,7 +863,7 @@ export interface RequestContext<
 
   /**
    * @internal Loader IDs ($$id) whose entries carry `awaitBeforeFlush`
-   * (loader(Def, { ssr: false })): segment resolution awaits these
+   * (loader(Def, { ssr: "await" })): 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 resolveOwnerLoaders

package/src/ssr/index.tsx

@@ -232,7 +232,7 @@ export interface SSRDependencies<TEnv = unknown> {
    *
    * When UNSET, createSSRHandler and createShellCaptureHandler auto-raise to
    * Number.MAX_SAFE_INTEGER for document renders and shell captures whose
-   * matched chain has a `loader(Def, { ssr: false })` entry (payload segments
+   * matched chain has a `loader(Def, { ssr: "await" })` 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
@@ -441,7 +441,7 @@ function trackDocumentClientLoads<T>(decode: () => T): {
 const SSR_FALSE_FIRST_FLUSH_TURNS = 3;
 
 /**
- * True when the matched chain has a `loader(Def, { ssr: false })` entry: its
+ * True when the matched chain has a `loader(Def, { ssr: "await" })` entry: its
  * payload segments carry `awaitBeforeFlush` (resolveOwnerLoaders).
  */
 function hasAwaitBeforeFlush(payload: {
@@ -453,7 +453,7 @@ function hasAwaitBeforeFlush(payload: {
 /**
  * The progressiveChunkSize renderHTML and captureShellHTML pass to Fizz (see
  * SSRDependencies.progressiveChunkSize): the explicit option, else the
- * ssr:false auto-raise.
+ * ssr: "await" auto-raise.
  */
 function documentChunkSize(
   explicit: number | undefined,
@@ -463,7 +463,7 @@ function documentChunkSize(
 }
 
 /**
- * ssr: false documents only: before the first flush, give Fizz the turns a
+ * ssr: "await" documents only: before the first flush, give Fizz the turns a
  * task waiting on an already-settling thenable needs, so a boundary that
  * waits on nothing else completes in place (#1138).
  *
@@ -953,7 +953,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
 
       const bootstrap = await resolveBootstrap(deps);
 
-      // ssr:false auto-raise (see SSRDependencies.progressiveChunkSize).
+      // ssr: "await" 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.
@@ -1149,7 +1149,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
         origin: opts.origin,
       });
 
-      // ssr:false auto-raise (SSRDependencies.progressiveChunkSize); resume()
+      // ssr: "await" auto-raise (SSRDependencies.progressiveChunkSize); resume()
       // inherits it from the postponed state. A rejected or late payload
       // skips it and fails or degrades below as before.
       const awaitsBeforeFlush = await Promise.race([

package/src/ssr/ssr-root.tsx

@@ -150,7 +150,7 @@ function createSsrEventController(opts: {
  * Deserialize the Flight stream branch into the payload SsrRoot renders,
  * fragment expansion included. Factored out of SsrRoot so createSSRHandler and
  * createShellCaptureHandler can create the promise BEFORE fizz starts and read
- * metadata that must influence the fizz call itself (the ssr:false
+ * metadata that must influence the fizz call itself (the ssr: "await"
  * progressiveChunkSize auto-raise) — awaiting it there is latency-neutral
  * because fizz cannot emit even <html> until this same promise settles.
  */

package/src/ssr-suspension-warning.ts

@@ -1,5 +1,5 @@
 /**
- * Dev-only diagnostic for the { ssr: false } SSR-completeness opt-in.
+ * Dev-only diagnostic for the { ssr: "await" } 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
@@ -37,7 +37,7 @@ export function warnAwaitedSsrSuspension(
 
   if (awaitedLoaderIds.includes(loaderId)) {
     console.error(
-      `[rango] Loader "${loaderId}" is flagged { ssr: false } and was awaited ` +
+      `[rango] Loader "${loaderId}" is flagged { ssr: "await" } 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.`,
@@ -46,12 +46,12 @@ export function warnAwaitedSsrSuspension(
   }
 
   console.warn(
-    `[rango] The document render awaited { ssr: false } loader(s) ` +
+    `[rango] The document render awaited { ssr: "await" } 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 ` +
+      `be SSR-complete, flag "${loaderId}" with { ssr: "await" } 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, { ssr: false })` so the document render awaits it
+   * `loader(Def, { ssr: "await" })` so the document render awaits it
    * (see {@link LoaderOptions}).
    *
    * @example
@@ -175,29 +175,29 @@ export type LoaderFn<
 /**
  * SSR delivery for a DSL-registered loader: `loader(Def, { ssr })`.
  *
- * 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.
+ * Default (omitted / `"stream"`): 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.
  *
- * `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
+ * `ssr: "await"` makes the server renders that produce HTML await this
+ * loader: 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); a ppr shell capture, at runtime or at build time
+ * for a Prerender + ppr route, awaits it too. 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), and so are its handle
  * pushes, a pushed promise or `.defer()` included: the capture awaits it and
  * every HIT serves the value it settled to (#1182). A pushed promise that
  * rejects, or misses `ppr.captureTimeout`, keeps the route on MISS. A value
- * that must stay per request belongs to a loader without `ssr: false` — see
+ * that must stay per request belongs to a loader without `ssr: "await"` — see
  * the ppr docs.
  *
- * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
+ * Scoped per LOADER, not per segment: an `ssr: "await"` 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
@@ -206,7 +206,7 @@ export type LoaderFn<
  * site naming the unflagged loader (ssr-suspension-warning.ts).
  */
 export type LoaderOptions = {
-  ssr?: boolean;
+  ssr?: "stream" | "await";
   /**
    * `prefetch: false` keeps this loader out of every `<Link>` prefetch: a
    * prefetch (a partial request with `X-Rango-Prefetch`) does not execute
@@ -236,7 +236,7 @@ export type LoaderOptions = {
    * Limits: a handler that awaits the loader with `ctx.use()` makes it run in
    * the prefetch anyway; the loader cannot call `ctx.rendered()` (it throws
    * on every request); on a `ppr` route the flag is ignored for an
-   * `ssr: false` loader (the bake lane), with a dev warning. In the fill
+   * `ssr: "await"` loader (the bake lane), with a dev warning. In the fill
    * request only deferred work and middleware run, so values a held handler
    * would have set with `ctx.set()` are not visible.
    */

package/src/types/segments.ts

@@ -164,7 +164,7 @@ export interface ResolvedSegment {
   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 resolveOwnerLoaders on
+   * (loader(Def, { ssr: "await" })). Stamped by resolveOwnerLoaders 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).
@@ -185,7 +185,7 @@ export interface ResolvedSegment {
   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
+   * Flagged (ssr: "await") entries are settled values; unflagged siblings
    * stay promises. Parallel slots do not use this channel — they pin
    * loading() / live-lane holes via use(loaderDataPromise).
    */

package/src/urls/path-helper-types.ts

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

package/src/urls/pattern-types.ts

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

package/src/vite/discovery/shell-prerender-phase.ts

@@ -188,7 +188,7 @@ export async function runShellPrerenderPhase(
       injectRSCPayload: htmlStream.injectRSCPayload,
       headScripts: "preinit",
       // Build-captured shells honor the explicit outlining budget, or the
-      // ssr:false auto-raise without one (createShellCaptureHandler): the
+      // ssr: "await" auto-raise without one (createShellCaptureHandler): the
       // capture value rides the postponed state into every runtime resume().
       ...(s.opts?.progressiveChunkSize !== undefined && {
         progressiveChunkSize: s.opts.progressiveChunkSize,

package/src/vite/plugin-types.ts

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