@rangojs/router 0.34.0 → 0.35.0

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

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

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

@@ -323,14 +323,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   return <div>{data.name}</div>;
    * }
    * ```
-   * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
-   * false }) — to await this loader before first flush on DOCUMENT requests
-   * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
-   * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+   * Pass `{ ssr: "await" }` to await this loader before first flush on
+   * DOCUMENT requests (see {@link LoaderOptions}): the opt-in for loaders
+   * whose data, handle pushes, or thrown notFound()/redirect() must be in the
+   * SSR'd HTML.
    * Per-loader: a streaming sibling in the same segment keeps streaming.
    *
    * ```typescript
-   * loader(ProductLoader, { ssr: false }, () => [cache()]),
+   * loader(ProductLoader, { ssr: "await" }, () => [cache()]),
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *

package/src/router/loader-resolution.ts

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

package/src/router/match-api.ts

@@ -203,6 +203,7 @@ export async function createMatchContextForFull<TEnv>(
     prevUrl: cleanUrl,
     prevParams: {},
     prevMatch: null,
+    interceptPrev: { url: cleanUrl, params: {} },
     matched,
     manifestEntry: snapshot.manifestEntry,
     entries: snapshot.entries,
@@ -520,6 +521,7 @@ export async function createMatchContextForPartial<TEnv>(
     prevUrl: nav.prevUrl,
     prevParams: nav.prevParams,
     prevMatch: nav.prevMatch,
+    interceptPrev: nav.interceptPrev,
     matched,
     manifestEntry: snapshot.manifestEntry,
     entries: snapshot.entries,

package/src/router/match-context.ts

@@ -116,6 +116,7 @@ import type {
 } from "../server/context.js";
 import type { HandlerContext, ResolvedSegment } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { PrevPage } from "./navigation-snapshot.js";
 import type { InterceptResult } from "./router-context.js";
 import type { ResolutionPassInput } from "./segment-resolution/resolution-pass.js";
 import type { ActionContext } from "./types.js";
@@ -139,10 +140,13 @@ export interface MatchContext<TEnv = any> {
   /** NavigationSnapshot.heldBoundary: the walk stops above it. */
   heldBoundary?: string;
 
-  // Previous navigation state
+  // Previous navigation state: see NavigationSnapshot.
   prevUrl: URL;
   prevParams: Record<string, string>;
+  /** The match of the page left: the intercept's URL while one is open. */
   prevMatch: RouteMatchResult | null;
+  /** The page an open intercept's slot was rendered for. */
+  interceptPrev: PrevPage;
 
   // Current route match
   matched: RouteMatchResult;
@@ -225,6 +229,23 @@ export function resolutionPassInput<TEnv>(
   };
 }
 
+/**
+ * This match as the input of the pass that resolves its intercept's slot: its
+ * held segments compare with the intercept's own URL (`interceptPrev`), not
+ * with the source page under it. From /item/2 over /list/1, a link to /item/1
+ * compared with the source's params would read as param-equal and keep item
+ * 2's slot.
+ */
+export function interceptPassInput<TEnv>(
+  ctx: MatchContext<TEnv>,
+): ResolutionPassInput<TEnv> {
+  return {
+    ...resolutionPassInput(ctx),
+    prevUrl: ctx.interceptPrev.url,
+    prevParams: ctx.interceptPrev.params,
+  };
+}
+
 /**
  * Mutable state that flows through the pipeline
  */

package/src/router/match-middleware/cache-lookup.ts

@@ -49,6 +49,7 @@ import {
   type MatchPipelineState,
 } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
+import type { PrevPage } from "../navigation-snapshot.js";
 import { freshPassInput } from "../segment-resolution/resolution-pass.js";
 import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
@@ -336,7 +337,12 @@ function storedEntrySends<TEnv>(
   router: RouterContext<TEnv>,
 ): (segment: ResolvedSegment) => boolean | Promise<boolean> {
   if (ctx.isFullMatch) return () => true;
-  const paramsChanged = !paramsEqual(ctx.matched.params, ctx.prevParams);
+  // An intercept variant's slot compares with the intercept's own page, the
+  // page under it with the source (MatchContext.interceptPrev).
+  const pagePrev: PrevPage = { url: ctx.prevUrl, params: ctx.prevParams };
+  const slotPrev = ctx.interceptPrev;
+  const pageParamsChanged = !paramsEqual(ctx.matched.params, pagePrev.params);
+  const slotParamsChanged = !paramsEqual(ctx.matched.params, slotPrev.params);
   const resendRouteSegments = replaceable && (ctx.isAction || ctx.stale);
   const entryRevalidateMap =
     ctx.clientSegmentSet.size > 0
@@ -345,11 +351,11 @@ function storedEntrySends<TEnv>(
   // A keep that hangs on the source's params is right for the pages with
   // the same params only: scope a prefetch of the answer to them, as a
   // predicate that compared every param would (#1331).
-  const heldForSource = (): false => {
+  const heldForSource = (prevParams: Record<string, string>): false => {
     markSourceHeld(
       ctx.handlerContext as InternalHandlerContext<any, TEnv>,
-      readsOfAllParams(ctx.prevParams),
-      { params: ctx.prevParams, routeName: undefined },
+      readsOfAllParams(prevParams),
+      { params: prevParams, routeName: undefined },
     );
     return false;
   };
@@ -362,23 +368,26 @@ function storedEntrySends<TEnv>(
       ctx.clientSegmentSet,
     );
     if (fill !== undefined) return fill;
+    const ofSlot = isInterceptSegment(segment);
+    const prev = ofSlot ? slotPrev : pagePrev;
+    const paramsChanged = ofSlot ? slotParamsChanged : pageParamsChanged;
     if (segment.type === "route" || segment.belongsToRoute === true) {
       if (paramsChanged || resendRouteSegments) return true;
       // Kept on equal params, whatever the search: a source with other
       // params is sent it.
-      return heldForSource();
+      return heldForSource(prev.params);
     }
     const revalidate = entryRevalidateMap?.get(segment.id)?.revalidate;
     if (!revalidate?.length) return false;
     // Kept on equal params: from another source the rules run and may send
     // it.
-    if (!paramsChanged) return heldForSource();
+    if (!paramsChanged) return heldForSource(prev.params);
     return router.evaluateRevalidation({
       segment,
-      prevParams: ctx.prevParams,
+      prevParams: prev.params,
       getPrevSegment: null,
       request: ctx.request,
-      prevUrl: ctx.prevUrl,
+      prevUrl: prev.url,
       nextUrl: ctx.url,
       revalidations: revalidate.map((fn, i) => ({
         name: `revalidate${i}`,

package/src/router/match-middleware/intercept-resolution.ts

@@ -103,7 +103,7 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { resolutionPassInput } from "../match-context.js";
+import { interceptPassInput } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog } from "../logging.js";
@@ -176,7 +176,7 @@ export function withInterceptResolution<TEnv>(
     const Store = ctx.Store;
     const interceptSegments = await Store.run(() =>
       resolveInterceptEntry(
-        resolutionPassInput(ctx),
+        interceptPassInput(ctx),
         ctx.interceptResult!.intercept,
         ctx.interceptResult!.entry,
         true, // belongsToRoute
@@ -232,7 +232,7 @@ async function handleCacheHitIntercept<TEnv>(
   const loaderSegments = resolveInterceptLoadersOnly
     ? await ctx.Store.run(() =>
         resolveInterceptLoadersOnly(
-          resolutionPassInput(ctx),
+          interceptPassInput(ctx),
           ctx.interceptResult!.intercept,
           ctx.interceptResult!.entry,
           true, // belongsToRoute

package/src/router/navigation-snapshot.ts

@@ -3,12 +3,30 @@ import { requestHeaders } from "../server/request-headers.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import { WIRE } from "../wire-params.js";
 
+/** A page held segments were rendered for: what their revalidation compares with. */
+export interface PrevPage {
+  url: URL;
+  params: Record<string, string>;
+}
+
 export interface NavigationSnapshot {
+  /**
+   * `prevUrl` and `prevParams`: the page the held page segments were rendered
+   * for. That is the page left, or the source page while an intercept is open
+   * (`hasInterceptSource`).
+   */
   prevUrl: URL;
   /** The visitor's URL of the page left, when `prevUrl` is its rewrite target. */
   prevVisitorUrl: URL | null;
   prevParams: Record<string, string>;
+  /** The match of the page left: the intercept's URL while one is open. */
   prevMatch: RouteMatchResult | null;
+  /**
+   * The page an open intercept's slot was rendered for: the intercept's own
+   * URL (match-context.ts interceptPassInput). Equals `prevUrl`/`prevParams`
+   * when the request names no intercept source.
+   */
+  interceptPrev: PrevPage;
 
   interceptContextUrl: URL;
   interceptContextMatch: RouteMatchResult | null;
@@ -176,29 +194,40 @@ export async function resolveNavigation(
   }
   // An intercept's request diffs from its source, which _rsc_rt does not name.
   const shown = interceptSourceUrl ? null : getShownRouteUrl(url);
-  const prevUrl = shown ?? visitor;
+  const left = shown ?? visitor;
 
   let interceptContextUrl: URL;
   try {
     interceptContextUrl = interceptSourceUrl
       ? withoutHash(new URL(interceptSourceUrl, url.origin))
-      : prevUrl;
+      : left;
   } catch {
-    interceptContextUrl = prevUrl;
+    interceptContextUrl = left;
   }
 
-  const prevMatch = await deps.findMatch(prevUrl.pathname);
-  const prevParams = prevMatch?.params || {};
+  const prevMatch = await deps.findMatch(left.pathname);
   const interceptContextMatch = interceptSourceUrl
     ? await deps.findMatch(interceptContextUrl.pathname)
     : prevMatch;
+  const interceptPrev: PrevPage = {
+    url: left,
+    params: prevMatch?.params || {},
+  };
+  // The page under an open intercept was rendered for the source, with its
+  // search, not for the intercept's URL.
+  const prev: PrevPage = interceptSourceUrl
+    ? {
+        url: formSearch(new URL(interceptContextUrl)),
+        params: interceptContextMatch?.params || {},
+      }
+    : interceptPrev;
 
   const isSameRouteNavigation = !!(
     interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
   );
 
   const hasInterceptSource = !!interceptSourceUrl;
-  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : prevUrl;
+  const effectiveFromUrl = hasInterceptSource ? interceptContextUrl : left;
   const effectiveFromMatch = hasInterceptSource
     ? interceptContextMatch
     : prevMatch;
@@ -212,10 +241,11 @@ export async function resolveNavigation(
   const clientSegmentSet = new Set(clientSegmentIds);
 
   return {
-    prevUrl,
+    prevUrl: prev.url,
     prevVisitorUrl: shown && visitor,
-    prevParams,
+    prevParams: prev.params,
     prevMatch,
+    interceptPrev,
     interceptContextUrl,
     interceptContextMatch,
     clientSegmentIds,
@@ -240,6 +270,7 @@ export function createNavigationSnapshot(
     prevVisitorUrl: null,
     prevParams: {},
     prevMatch: null,
+    interceptPrev: { url: defaultUrl, params: {} },
     interceptContextUrl: defaultUrl,
     interceptContextMatch: null,
     clientSegmentIds: [],

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