@rangojs/router 0.34.0 → 0.35.0

package/README.md

@@ -304,7 +304,7 @@ Loaders run in parallel with the handler and stream their results.
 into it. Without `loading()`, the segment has no skeleton, and the HTML
 normally arrives with the data already in place. To guarantee that a
 loader's data, head tags, or a real 404 are in the first HTML flush, register
-it with `loader(StockLoader, { ssr: false })`.
+it with `loader(StockLoader, { ssr: "await" })`.
 
 When a loader's data changes, every component that reads it updates too.
 Calling `load()` from `useLoader()` refetches it on the client, and

package/dist/bin/{chunk-4HHFQSDC.js → chunk-3CQXDX3A.js}

@@ -23,7 +23,7 @@ import * as React4 from "react";
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
 // src/rsc/shell-capture-constants.ts
-var PPR_LANE_HINT = 'Lane rule: only loader(Def, { ssr: false }) 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).';
+var PPR_LANE_HINT = '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).';
 
 // src/cache/cache-exec-scope.ts
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -52,8 +52,8 @@ var LOADER_BODY_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-bo
 var loaderBodyScopeALS = globalThis[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage2();
 function requestReadCaptureFix(what) {
   return {
-    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 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 under loading() or an inline <Suspense> (a live hole). A promise the handler passes or pushes does not help: the capture waits for it."
+    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: "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: "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.'
   };
 }
 var NON_CACHEABLE_READ = {
@@ -1149,7 +1149,7 @@ var RAW_COOKIES_READ = {
   verb: "called",
   fix: COOKIES_READ.fix
 };
-var 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>). 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).";
+var THEME_READ_FIX = 'On ppr and cache() routes, read the theme with useTheme() in a client 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).';
 var THEME_READ = {
   verb: "read",
   fix: {
@@ -1348,7 +1348,7 @@ function serializeRoute(route2, options, ordinals) {
   });
   const awaitedLoaderIndices = indicesWhere(
     route2.loaders,
-    ({ ssr }) => ssr === false
+    ({ ssr }) => ssr === "await"
   );
   const transition3 = serializeTransition(route2);
   return Object.freeze({

package/dist/bin/{client-urls-projection-4Q5EQDAL.js → client-urls-projection-2GBDM5YK.js}

@@ -10,7 +10,7 @@ import {
   refreshRecordedClientUrlProjections,
   resolveClientUrlsSource,
   scanForClientUrlModules
-} from "./chunk-4HHFQSDC.js";
+} from "./chunk-3CQXDX3A.js";
 import "./chunk-MWOHBDPM.js";
 import "./chunk-LD7UBHT4.js";
 export {

package/dist/bin/rango.js

@@ -229,7 +229,7 @@ ${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}
   }
   let discoverAndWriteRouteTypes;
   try {
-    const mod = await import("./runtime-discovery-2ZTYRZ3V.js");
+    const mod = await import("./runtime-discovery-PA3V3IFQ.js");
     discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
   } catch (err) {
     if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "MODULE_NOT_FOUND") {

package/dist/bin/{runtime-discovery-2ZTYRZ3V.js → runtime-discovery-PA3V3IFQ.js}

@@ -163,9 +163,9 @@ async function discoverAndWriteRouteTypes(opts) {
       "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc"
     );
   }
-  const { createTempRscServer } = await import("./temp-rsc-server-EUNKRFJD.js");
+  const { createTempRscServer } = await import("./temp-rsc-server-WDXEHDY7.js");
   const { createDiscoveryState } = await import("./state-ACD2MGKJ.js");
-  const { discoverClientUrlProjections } = await import("./client-urls-projection-4Q5EQDAL.js");
+  const { discoverClientUrlProjections } = await import("./client-urls-projection-2GBDM5YK.js");
   const {
     isFrameworkPlugin,
     pickForwardedRunnerConfig,

package/dist/bin/{temp-rsc-server-EUNKRFJD.js → temp-rsc-server-WDXEHDY7.js}

@@ -27,7 +27,7 @@ import {
   propertyKeyIs,
   recordClientUrlsModule,
   unwrapExpression
-} from "./chunk-4HHFQSDC.js";
+} from "./chunk-3CQXDX3A.js";
 import "./chunk-MWOHBDPM.js";
 import {
   codeMatchIndices,
@@ -47,7 +47,7 @@ var DEFAULT_ROUTER_VERSIONS_KEY = "*";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.34.0",
+  version: "0.35.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/dist/types/cache/shell-snapshot.d.ts

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

package/dist/types/cache/types.d.ts

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

package/dist/types/client-urls/server-projection.d.ts

@@ -28,7 +28,7 @@ export interface ClientUrlProjectionRoute {
     readonly options: ClientUrlProjectionOptions;
     readonly loaderIds: readonly string[];
     readonly hasLoading: boolean;
-    /** Indices into loaderIds of loaders declared loader(Def, { ssr: false });
+    /** Indices into loaderIds of loaders declared loader(Def, { ssr: "await" });
      *  materialization passes the option through to the server loader() so
      *  document renders await them before first flush. Absent (= none) in
      *  projections serialized before the option existed. */

package/dist/types/client-urls/types.d.ts

@@ -42,12 +42,12 @@ export interface ClientUrlLoaderRecord {
      */
     readonly revalidate: readonly (ShouldRevalidateFn<any, DefaultEnv> | HoistedRevalidateRef | boolean)[];
     /**
-     * loader(Def, { ssr: false }): document renders await this loader before
+     * loader(Def, { ssr: "await" }): document renders await this loader before
      * first flush (see {@link LoaderOptions}). Projected into the server tree,
      * where the per-isSSR entry stamping applies — client navigations stream
      * regardless.
      */
-    readonly ssr?: false;
+    readonly ssr?: "await";
     /**
      * loader(Def, { prefetch: false | "intent" }): a prefetch of the route, or
      * of an intercept's target from its source, defers this loader and the
@@ -109,10 +109,10 @@ export interface ClientUrlHelpers {
      * Attach a projected loader. The optional use callback may contain
      * revalidate() only: a per-loader predicate the server runs, as in urls().
      *
-     * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
-     * false }) — to await this loader before first flush on DOCUMENT requests
-     * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
-     * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+     * Pass `{ ssr: "await" }` to await this loader before first flush on
+     * DOCUMENT requests (see {@link LoaderOptions}): the opt-in for loaders
+     * whose data, handle pushes, or thrown notFound()/redirect() must be in the
+     * SSR'd HTML.
      * Per-loader: a streaming sibling keeps streaming. Under a `ppr` group
      * route the flag BAKES: the loader executes at shell capture and its
      * settled return freezes into the shell (nested promises stay live

package/dist/types/decode-loader-results.d.ts

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

package/dist/types/errors.d.ts

@@ -243,10 +243,10 @@ export declare class InvalidHandlerError extends Error {
  */
 export declare function invariant(condition: any, message: string): asserts condition;
 /**
- * Rejects a boolean-only DSL option that holds anything else (undefined
- * passes), as an invariant.
+ * Rejects a loader `ssr` option other than `"stream"` or `"await"`
+ * (undefined passes). clientUrls() inlines the same checks.
  */
-export declare function assertBooleanOption(value: unknown, option: string, effect: string): void;
+export declare function assertLoaderSsrOption(value: unknown, helper: string): void;
 /**
  * Rejects a `prefetch` DSL option that is neither a boolean nor `"intent"`
  * (undefined passes), as an invariant.

package/dist/types/handles/meta.d.ts

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

package/dist/types/loader-store.d.ts

@@ -28,6 +28,10 @@
  *     cancelled on resubscribe so a StrictMode / transition remount does not
  *     reclaim a bucket that is about to be reused, and is held until any
  *     in-flight load settles.
+ *   - Owned buckets (one reader's private refresh-group bucket,
+ *     `useLoader(L, { refreshGroup })` without a key) are sticky while that
+ *     reader is mounted and dropped like an ephemeral bucket once it leaves:
+ *     no other reader names the bucket, and a remount takes a new one.
  *
  * Each router's NavigationStore owns one (navigation-store.ts), and hooks reach
  * it through NavigationStoreContext: the router store is the single source of
@@ -79,6 +83,13 @@ export interface SubscribeOptions {
      * subscriber attaches, and from then on resets via `clearFamily`.
      */
     ephemeral?: boolean;
+    /**
+     * When true, the bucket belongs to this subscriber alone (a private
+     * refresh-group bucket, which no other reader names): it is reset by
+     * `clearFamily` while subscribed, and dropped after the subscriber leaves
+     * even when sticky. Read at unsubscribe, so pass it on every subscribe.
+     */
+    owned?: boolean;
     /**
      * Cross-loader refresh group name(s). Tags this bucket so `refreshGroups(name)`
      * can refresh it alongside buckets of other loaders. A bucket may be tagged
@@ -130,8 +141,8 @@ export declare class LoaderStore {
      * Subscribe to entry changes for `bucketKey`.
      * Returns an unsubscribe function. A sticky bucket's entry is kept around even
      * after the last subscriber leaves so that an in-flight `load()` can still
-     * commit if the consumer remounts. An ephemeral bucket is dropped once its
-     * last subscriber leaves (deferred, see maybeScheduleRefcountClear).
+     * commit if the consumer remounts. An ephemeral or owned bucket is dropped
+     * once its last subscriber leaves (deferred, see maybeScheduleRefcountClear).
      */
     subscribe(bucketKey: string, cb: () => void, options?: SubscribeOptions): () => void;
     private addToGroup;
@@ -149,14 +160,14 @@ export declare class LoaderStore {
      */
     refreshGroups(groups: string | string[]): Promise<void>;
     /**
-     * Schedule a deferred drop for an ad-hoc (never-sticky) bucket whose last
-     * subscriber just left. Deferred to a microtask so a StrictMode / transition
-     * remount that resubscribes in the same tick cancels it.
+     * Schedule a deferred drop for an ad-hoc (never-sticky) or owned bucket
+     * whose last subscriber just left. Deferred to a microtask so a StrictMode /
+     * transition remount that resubscribes in the same tick cancels it.
      */
     private maybeScheduleRefcountClear;
     /** Remove a bucket entry entirely and prune it from its family/group indexes. */
     private dropBucket;
-    /** Drop an ephemeral bucket that settled with no subscribers left. */
+    /** Drop an ephemeral or owned bucket that settled with no subscribers left. */
     private dropIfSettled;
     /**
      * Returns the current snapshot for `bucketKey`. Stable reference between
@@ -205,7 +216,8 @@ export declare class LoaderStore {
      * Reset a single bucket entry. Bumps `latestRequestId` so any in-flight
      * `load()` whose promise is still pending will fail its gate when it resolves
      * and be dropped — prevents pre-navigation loads from clobbering the new
-     * route's context. The entry itself is kept (sticky-bucket semantics).
+     * route's context. The entry itself is kept (sticky-bucket semantics),
+     * unless it was only waiting for that request to be dropped.
      */
     clear(bucketKey: string): void;
     /**
@@ -221,7 +233,7 @@ export declare class LoaderStore {
     /**
      * Register a still-streaming per-loader result for `loaderId`. No-op for a
      * settled Flight chunk (unwrapsSynchronously / "rejected"): the forceAwait
-     * and action lanes commit settled chunks, and a { ssr: false } loader is
+     * and action lanes commit settled chunks, and a { ssr: "await" } loader is
      * awaited before flush. Released as the stream settles, either way.
      */
     trackPendingStream(loaderId: string, stream: Promise<unknown>): void;

package/dist/types/outlet-context.d.ts

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

package/dist/types/route-definition/helpers-types.d.ts

@@ -221,14 +221,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/dist/types/router/loader-resolution.d.ts

@@ -44,7 +44,7 @@ export type LoaderErrorCallback = (error: unknown, context: {
  *   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.

package/dist/types/router/match-context.d.ts

@@ -112,6 +112,7 @@ import type { CacheScope } from "../cache/cache-scope.js";
 import type { EntryData, InterceptSelectorContext, MetricsStore } 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";
@@ -130,7 +131,10 @@ export interface MatchContext<TEnv = any> {
     heldBoundary?: string;
     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;
     matched: RouteMatchResult;
     manifestEntry: EntryData;
     entries: EntryData[];
@@ -169,6 +173,14 @@ export interface MatchContext<TEnv = any> {
 export declare function rendersLive(ctx: Pick<MatchContext, "isAction" | "stale">): boolean;
 /** This match as the input of a revalidating resolution pass (resolution-pass.ts). */
 export declare function resolutionPassInput<TEnv>(ctx: MatchContext<TEnv>): 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 declare function interceptPassInput<TEnv>(ctx: MatchContext<TEnv>): ResolutionPassInput<TEnv>;
 /**
  * Mutable state that flows through the pipeline
  */

package/dist/types/router/navigation-snapshot.d.ts

@@ -1,10 +1,27 @@
 import type { RouteMatchResult } from "./pattern-matching.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;
     clientSegmentIds: string[];

package/dist/types/router/segment-resolution/loader-cache.d.ts

@@ -56,14 +56,14 @@ import { type RequestContext } from "../../server/request-context.js";
 export declare function bindsLoaderCache(entries: readonly EntryData[]): boolean;
 /**
  * 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).
  */
 export declare function routeLoaderLanes(entries: readonly EntryData[]): ReadonlyMap<string, "live" | "bake">;
 /**
  * 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.
@@ -77,14 +77,14 @@ export declare function servesLoaderPin(loaderEntry: LoaderEntry, reqCtx?: Reque
  * 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 declare function loaderPins(entries: readonly EntryData[], reqCtx: RequestContext<any> | undefined): OwnedPushDelivery;
@@ -108,7 +108,7 @@ export declare function loaderPins(entries: readonly EntryData[], reqCtx: Reques
  * 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
@@ -130,7 +130,7 @@ export declare function loaderPins(entries: readonly EntryData[], reqCtx: Reques
  *   (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 declare function resolveLoaderData<TEnv>(loaderEntry: LoaderEntry, ctx: HandlerContext<any, TEnv>, pathname: string, bakeSegmentKey?: string | null): Promise<any>;

package/dist/types/router/types.d.ts

@@ -35,7 +35,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>(promise: Promise<T>, errorContext?: {
         segmentId?: string;

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -148,12 +148,12 @@ export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
  * (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

package/dist/types/server/context.d.ts

@@ -119,7 +119,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
@@ -129,7 +129,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,
@@ -491,7 +491,7 @@ export type { HelperContext };
  * parent pointer, handler) stays shared, which is correct and cheap.
  */
 export declare function getIsolatedLazyParent(captured: EntryData | null | undefined): EntryData | null;
-/** 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 declare function documentModeLoader(entry: LoaderEntry): LoaderEntry;
 /** loading(fallback, { ssr: false }): a document renders no fallback. */
 export declare function applyDocumentModeLoading(entry: EntryPropRender): void;

package/dist/types/server/request-context.d.ts

@@ -710,7 +710,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _handlerLoaderDeps?: Set<string>;
     /**
      * @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/dist/types/ssr/index.d.ts

@@ -171,7 +171,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

package/dist/types/ssr/ssr-root.d.ts

@@ -30,7 +30,7 @@ export interface RscPayload {
  * 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/dist/types/ssr-suspension-warning.d.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

package/dist/types/types/loader-types.d.ts

@@ -63,7 +63,7 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * 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
@@ -150,29 +150,29 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
 /**
  * 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
@@ -181,7 +181,7 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
  * 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
@@ -211,7 +211,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/dist/types/types/segments.d.ts

@@ -150,7 +150,7 @@ export interface ResolvedSegment {
     loaderData?: any;
     /**
      * 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).
@@ -170,7 +170,7 @@ export interface ResolvedSegment {
     loaderIds?: string[];
     /**
      * 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).
      */