@rangojs/router 0.9.0 → 0.10.0

package/skills/loader/SKILL.md

@@ -757,6 +757,18 @@ Response construction (real 404, no warm-up race). Client navigations stream
 exactly as before. Scoped per LOADER: the flagged loader awaits only itself;
 siblings keep streaming.
 
+Delivery is in-place, not merely in-document. React's Fizz outlines any
+COMPLETED Suspense boundary over ~500 bytes to an end-of-stream
+`<div hidden>` + `$RC()` reveal once the shell saturates its 12800-byte
+`progressiveChunkSize` budget — the bytes are in the HTML, but not at their
+document position, and a consumer that doesn't execute scripts never sees
+them revealed. When the matched chain has a flagged loader, the document
+render raises the budget to `MAX_SAFE_INTEGER` automatically, so the awaited
+content renders where it belongs. Pin the budget yourself (in either
+direction) with `rango({ progressiveChunkSize })` in the Vite config — an
+explicit value disables the auto-raise. Boundaries hoisting stylesheets
+still outline; their reveal must wait for the CSS.
+
 The costs and constraints:
 
 - Every document load pays the flagged loader's latency before first byte.
@@ -766,8 +778,11 @@ The costs and constraints:
   document render awaits the loader before the render barrier resolves, so
   that wait is a cycle by construction; it throws a deadlock error naming the
   fix.
-- PPR capture renders mask loaders and skip the await — the flag does not
-  bake anything into a shell (`/ppr`).
+- PPR capture is the BAKE lane for flagged loaders (`/ppr`): the capture
+  render awaits them too, and the settled result — handle pushes included —
+  freezes into the stored shell. Unflagged loaders stay masked as live
+  holes. The `progressiveChunkSize` auto-raise is live-document only;
+  captured shells outline per the explicit option or React's default.
 
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful. `LoaderOptions` is exported from the

package/src/browser/merge-segment-loaders.ts

@@ -45,6 +45,10 @@ export function mergeSegmentLoaders(
     }),
     // Keep all loader IDs from cache
     loaderIds: fromCache.loaderIds,
+    // The rebuilt aggregate is the source of truth. Cached per-loader
+    // streams would make LoaderResolver ignore loaderDataPromise.
+    loaderStreams: undefined,
+    awaitedLoaderIds: undefined,
   };
 }
 

package/src/client.tsx

@@ -49,6 +49,8 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
     <LoaderBoundary
       loaderDataPromise={segment.loaderDataPromise!}
       loaderIds={segment.loaderIds!}
+      loaderStreams={segment.loaderStreams}
+      awaitedLoaderIds={segment.awaitedLoaderIds}
       fallback={segment.loading}
       outletKey={segment.id + "-loader"}
       outletContent={null}

package/src/outlet-context.ts

@@ -18,6 +18,15 @@ export interface OutletContextValue {
    * the resolved `loaderData` record.
    */
   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
+   * it to warn when a read still suspends during SSR on a render that awaited
+   * flagged loaders (ssr-suspension-warning.ts). Present only on streaming
+   * lanes with flagged loaders (document and shell-capture renders); absent
+   * on forceAwait/action lanes.
+   */
+  awaitedLoaderIds?: readonly string[];
   parent?: OutletContextValue | null;
   /** Loading component for Suspense fallback (from segment's loading() definition) */
   loading?: ReactNode;

package/src/outlet-provider.tsx

@@ -13,6 +13,7 @@ export function OutletProvider({
   segment,
   loaderData,
   loaderStreams,
+  awaitedLoaderIds,
   pending = false,
   children,
 }: {
@@ -21,6 +22,7 @@ export function OutletProvider({
   segment?: ResolvedSegment;
   loaderData?: Record<string, any>;
   loaderStreams?: Record<string, unknown>;
+  awaitedLoaderIds?: readonly string[];
   pending?: boolean;
   children: ReactNode;
 }): ReactNode {
@@ -34,6 +36,7 @@ export function OutletProvider({
       segment,
       loaderData,
       loaderStreams,
+      awaitedLoaderIds,
       pending,
       parent: parentContext,
       loading: segment?.loading,
@@ -44,6 +47,7 @@ export function OutletProvider({
       segment,
       loaderData,
       loaderStreams,
+      awaitedLoaderIds,
       pending,
       parentContext,
     ],

package/src/route-content-wrapper.tsx

@@ -129,6 +129,9 @@ export interface LoaderBoundaryProps {
    * the children; useLoader suspends per loader at the read site.
    */
   loaderStreams?: Record<string, unknown>;
+  /** Dev-diagnostic input for the SSR suspension warning — see
+   *  OutletContextValue.awaitedLoaderIds. Rides the streams lane only. */
+  awaitedLoaderIds?: readonly string[];
   fallback?: ReactNode;
   outletKey: string;
   outletContent: ReactNode;
@@ -141,6 +144,7 @@ export function LoaderBoundary({
   loaderDataPromise,
   loaderIds,
   loaderStreams,
+  awaitedLoaderIds,
   fallback,
   outletKey,
   outletContent,
@@ -154,6 +158,7 @@ export function LoaderBoundary({
         loaderDataPromise={loaderDataPromise}
         loaderIds={loaderIds}
         loaderStreams={loaderStreams}
+        awaitedLoaderIds={awaitedLoaderIds}
         outletKey={outletKey}
         outletContent={outletContent}
         segment={segment}
@@ -187,6 +192,7 @@ function LoaderResolver({
   loaderDataPromise,
   loaderIds,
   loaderStreams,
+  awaitedLoaderIds,
   outletKey,
   outletContent,
   segment,
@@ -201,6 +207,7 @@ function LoaderResolver({
         segment={segment}
         parallel={parallel}
         loaderStreams={loaderStreams}
+        awaitedLoaderIds={awaitedLoaderIds}
       >
         {children}
       </OutletProvider>

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

@@ -11,6 +11,7 @@ import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type LoaderEntry,
 } from "../../server/context";
 import type {
   HandlerContext,
@@ -45,6 +46,37 @@ import {
   latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
+/**
+ * Register flagged loader $$ids on the request context and return their
+ * indices. Must run BEFORE kickoff: rendered() checks the set to fail
+ * fast on the barrier cycle (resolution awaits the loader, the barrier
+ * awaits resolution).
+ */
+function registerAwaitBeforeFlushIds(loaderEntries: LoaderEntry[]): number[] {
+  const awaitedIndices: number[] = [];
+  for (let i = 0; i < loaderEntries.length; i++) {
+    if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
+  }
+  if (awaitedIndices.length > 0) {
+    const reqCtx = _getRequestContext();
+    if (reqCtx) {
+      reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
+      for (const i of awaitedIndices) {
+        reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
+      }
+    }
+  }
+  return awaitedIndices;
+}
+
+function stampAwaitBeforeFlush(
+  loaderEntry: LoaderEntry,
+): { awaitBeforeFlush: true } | Record<string, never> {
+  return loaderEntry.awaitBeforeFlush === true
+    ? { awaitBeforeFlush: true as const }
+    : {};
+}
+
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -112,23 +144,12 @@ export async function resolveLoaders<TEnv>(
     // the set to fail fast on the barrier cycle (segment resolution awaits the
     // loader, the barrier awaits segment resolution, rendered() awaits the
     // barrier), and the loader body can call rendered() before the await below
-    // is reached. Skipped during shell capture: LIVE-lane loaders are masked
-    // with never-resolving promises there (loader-mask.ts) and would hang.
-    const awaitedIndices: number[] = [];
-    if (!isShellCaptureActive()) {
-      for (let i = 0; i < loaderEntries.length; i++) {
-        if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
-      }
-    }
-    if (awaitedIndices.length > 0) {
-      const reqCtx = _getRequestContext();
-      if (reqCtx) {
-        reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
-        for (const i of awaitedIndices) {
-          reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
-        }
-      }
-    }
+    // is reached.
+    //
+    // Shell-capture renders await too: flagged loaders BAKE at capture
+    // (loader-mask masks only LIVE-lane loaders). Capture must await them so
+    // bake-lane handle pushes land in the prelude.
+    const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
 
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
@@ -142,6 +163,10 @@ export async function resolveLoaders<TEnv>(
         component: null,
         params: ctx.params,
         loaderId: loader.$$id,
+        // Stamped on document AND capture renders: segment-system's
+        // value-delivery await and the dev SSR-suspension diagnostic both
+        // key off it.
+        ...stampAwaitBeforeFlush(loaderEntry),
         loaderData: deps.wrapLoaderPromise(
           runInsideLoaderScope(() =>
             resolveLoaderData(
@@ -188,6 +213,11 @@ export async function resolveLoaders<TEnv>(
   // collapsing the whole entry and discarding successful sibling data, and
   // (2) leave the other in-flight raw promises without a .catch, producing
   // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  //
+  // Flagged loaders still get awaitBeforeFlush stamped: auto-raise and
+  // settled-value delivery key off the field, and this path already paid
+  // the pre-flush await.
+  registerAwaitBeforeFlushIds(loaderEntries);
   const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
@@ -224,6 +254,7 @@ export async function resolveLoaders<TEnv>(
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
+      ...stampAwaitBeforeFlush(loaderEntry),
       loaderData: pending.wrapped,
       belongsToRoute,
     };

package/src/router.ts

@@ -1167,11 +1167,16 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+        const requestedDiscoveryEpoch = request.headers.get(
+          DEV_DISCOVERY_PROBE_HEADER,
+        );
         if (
           devDiscoveryEpoch !== undefined &&
-          request.headers.get(DEV_DISCOVERY_PROBE_HEADER) ===
-            String(devDiscoveryEpoch)
+          requestedDiscoveryEpoch !== null
         ) {
+          // A stale generation must still answer as a probe. Rendering the app
+          // on an epoch mismatch makes the readiness loop overlap full renders
+          // with workerd reloads and can exhaust the dev server heap.
           return new Response(null, {
             headers: {
               [DEV_DISCOVERY_EPOCH_HEADER]: String(devDiscoveryEpoch),

package/src/rsc/handler.ts

@@ -45,7 +45,7 @@ import {
   handleResponseRoute,
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
-import { generateNonce, nonce as nonceToken } from "./nonce.js";
+import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
 import { VERSION } from "@rangojs/router:version";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
@@ -456,12 +456,12 @@ export function createRSCHandler<
       }
     }
 
-    // Resolve nonce if provider is set
+    // Resolve nonce if provider is set. false/"" normalize to undefined —
+    // the per-request opt-out (resolveProviderNonce).
     const nonceStart = performance.now();
     let nonce: string | undefined;
     if (nonceProvider) {
-      const result = await nonceProvider(request, env);
-      nonce = result === true ? generateNonce() : result;
+      nonce = resolveProviderNonce(await nonceProvider(request, env));
     }
     const nonceDur = performance.now() - nonceStart;
 

package/src/rsc/nonce.ts

@@ -25,6 +25,22 @@ import { createVar } from "../context-var.js";
  */
 export const nonce: ContextVar<string> = createVar<string>();
 
+/**
+ * Normalize a NonceProvider return value to the nonce the request runs with.
+ * `true` auto-generates; `false` and the empty string are the per-request
+ * opt-out and normalize to undefined — without this, a falsy string would be
+ * threaded as-is into the render: never written to the token (`if (nonce)`)
+ * yet still `!== undefined` for the ppr shell gate (rsc-rendering.ts
+ * activeNonce), pinning a ppr route to axis 1 with no way to opt a request
+ * out while keeping the provider for the rest of the app.
+ */
+export function resolveProviderNonce(
+  result: string | boolean,
+): string | undefined {
+  if (result === true) return generateNonce();
+  return result === false || result === "" ? undefined : result;
+}
+
 /**
  * Generate a cryptographic nonce for CSP.
  * Returns a 16-byte random value encoded as base64.

package/src/rsc/shell-capture.ts

@@ -45,7 +45,10 @@ import {
   maskNestedContainerThenables,
   type MaskReport,
 } from "../router/segment-resolution/mask-nested.js";
-import { isInsideLoaderScope } from "../server/context.js";
+import {
+  getCurrentLoaderBodyId,
+  isInsideLoaderScope,
+} from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import type {
   ShellCacheEntry,
@@ -1503,6 +1506,15 @@ export function deriveShellCaptureContext(
   //    applied ONLY at the captureHandles cache-write call site — every other
   //    getDataForSegment consumer (the render-barrier snapshot, prerender)
   //    sees every push.
+  //    EXCEPTION — bake-lane { ssr: false } loaders: they execute at capture
+  //    and never re-run on a HIT, so neither exclusion rationale applies. The
+  //    capture awaits them (fresh.ts), their pushes are in the captured HTML
+  //    (<head> title/meta, useHandle echoes), and the stored snapshot MUST
+  //    carry the same values or HIT hydration mismatches against its own
+  //    prelude (server text present, client handle empty). Only their
+  //    settled, thenable-free pushes qualify — a deferred (thenable) push or
+  //    one with masked nested promises keeps the exclusion so the handle
+  //    encode cannot stall on a never-resolving mask.
   const handleLiveness = {
     holes: false,
     pendingPushes: 0,
@@ -1518,11 +1530,13 @@ export function deriveShellCaptureContext(
     const pushedInLoaderScope = isInsideLoaderScope();
     // Single walk: the mask reports whether it masked any nested thenable
     // (the liveness declaration) while building the capture copy.
+    let maskedNestedThenable = false;
     const maskWithLiveness = (v: unknown): unknown => {
       const report: MaskReport = { thenable: false };
       const masked = maskNestedContainerThenables(v, undefined, report);
-      if (!pushedInLoaderScope && report.thenable) {
-        handleLiveness.holes = true;
+      if (report.thenable) {
+        maskedNestedThenable = true;
+        if (!pushedInLoaderScope) handleLiveness.holes = true;
       }
       return masked;
     };
@@ -1534,11 +1548,30 @@ export function deriveShellCaptureContext(
         value.then(settle, settle);
       }
       masked = value.then(maskWithLiveness);
+      // Deferred (thenable) loader pushes always keep the exclusion — the
+      // bake-lane carve-out below is for settled values only.
+      if (pushedInLoaderScope) {
+        loaderScopedPushValues.add(masked as object);
+      }
     } else {
       masked = maskWithLiveness(value);
-    }
-    if (pushedInLoaderScope && typeof masked === "object" && masked !== null) {
-      loaderScopedPushValues.add(masked);
+      if (
+        pushedInLoaderScope &&
+        typeof masked === "object" &&
+        masked !== null
+      ) {
+        // Bake-lane { ssr: false } loader pushes are shell material (see the
+        // funnel comment above): keep them IN the stored snapshot when
+        // settled and thenable-free; everything else stays excluded.
+        const bodyLoaderId = getCurrentLoaderBodyId();
+        const baked =
+          bodyLoaderId !== undefined &&
+          !maskedNestedThenable &&
+          derivedCtx._awaitBeforeFlushLoaderIds?.has(bodyLoaderId) === true;
+        if (!baked) {
+          loaderScopedPushValues.add(masked);
+        }
+      }
     }
     rawCapturePush(handleName, segmentId, masked);
   };

package/src/rsc/types.ts

@@ -276,12 +276,16 @@ export interface HandlerCacheConfig {
 
 /**
  * Nonce provider function type.
- * Can return a nonce string, or true to auto-generate one.
+ * Return a nonce string to use verbatim, `true` to auto-generate one, or
+ * `false` (or an empty string) to serve THIS request without a nonce — the
+ * per-request opt-out for apps that nonce globally but declare `ppr` on some
+ * routes: a shell is shared per host+URL and can never bake a per-request
+ * nonce, so a ppr route only captures when its requests opt out here.
  */
 export type NonceProvider<TEnv = unknown> = (
   request: Request,
   env: TEnv,
-) => string | true | Promise<string | true>;
+) => string | boolean | Promise<string | boolean>;
 
 /**
  * Options for creating an RSC handler

package/src/segment-system.tsx

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

package/src/ssr/index.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { createSsrRootComponent } from "./ssr-root.js";
+import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
@@ -26,6 +26,7 @@ interface RenderToReadableStreamOptions {
   bootstrapModules?: string[];
   nonce?: string;
   formState?: unknown;
+  progressiveChunkSize?: number;
 }
 
 /**
@@ -43,6 +44,7 @@ interface PrerenderOptions {
   bootstrapScriptContent?: string;
   bootstrapModules?: string[];
   onError?: (error: unknown) => void;
+  progressiveChunkSize?: number;
 }
 
 /**
@@ -168,6 +170,23 @@ export interface SSRDependencies<TEnv = unknown> {
    */
   headScripts?: HeadScriptsOption;
 
+  /**
+   * Fizz `progressiveChunkSize`, forwarded verbatim to renderToReadableStream
+   * (live SSR) and prerender (shell capture); resume() inherits the capture
+   * value from the postponed state. The generated virtual SSR entry threads
+   * the `rango({ progressiveChunkSize })` plugin option here (canonical docs
+   * on `RangoBaseOptions.progressiveChunkSize` in vite/plugin-types.ts).
+   *
+   * When UNSET, createSSRHandler auto-raises to Number.MAX_SAFE_INTEGER for
+   * document renders whose matched chain has a `loader(Def, { ssr: false })`
+   * entry (payload segments carry `awaitBeforeFlush`): the loader was awaited
+   * before first flush precisely so its content ships in-place, and React
+   * 19.2's Fizz would otherwise move any completed boundary over ~500 bytes
+   * to an end-of-stream `<div hidden>` + $RC reveal once the shell saturates
+   * the default 12800 budget. An explicit value disables the auto-raise.
+   */
+  progressiveChunkSize?: number;
+
   /**
    * prerender from react-dom/static.edge. Optional; required only by
    * {@link createShellCaptureHandler} for PPR shell capture.
@@ -497,9 +516,21 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // - rscStream2: For browser hydration (inject as __FLIGHT_DATA__)
       const [rscStream1, rscStream2] = rscStream.tee();
 
+      // Deserialization starts here (not lazily on SsrRoot's first render) so
+      // the auto-raise below can read payload metadata before the fizz call.
+      // The parallel no-op catch keeps a payload rejection off the
+      // unhandledRejection path if fizz errors before consuming the promise;
+      // SsrRoot's React.use() on the SAME promise still observes the rejection.
+      const payload = deserializeSsrPayload(
+        createFromReadableStream,
+        rscStream1,
+      );
+      payload.catch(() => {});
+
       const SsrRoot = createSsrRootComponent({
         createFromReadableStream,
         rscStream: rscStream1,
+        payload,
         nonce,
         // Live fizz seeds the request's RAW search. The shell capture pass
         // below and its resume twin seed the SHELL KEY's search instead
@@ -513,6 +544,18 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Get bootstrap script content
       const bootstrapScriptContent = await loadBootstrapScriptContent();
 
+      // ssr:false auto-raise (see SSRDependencies.progressiveChunkSize).
+      // Awaiting the payload here is latency-neutral: fizz cannot emit even
+      // <html> until this same promise settles. A rejection lands in the
+      // catch below — the same reportRenderError path a shell error takes.
+      let progressiveChunkSize = deps.progressiveChunkSize;
+      if (progressiveChunkSize === undefined) {
+        const resolved = await payload;
+        if (resolved.metadata?.segments?.some((s) => s.awaitBeforeFlush)) {
+          progressiveChunkSize = Number.MAX_SAFE_INTEGER;
+        }
+      }
+
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided
       // Pass nonce for CSP if provided. runWithPreinitNonce makes the same
@@ -523,6 +566,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
           formState,
           nonce,
+          ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
         }),
       );
 
@@ -646,6 +690,14 @@ export function createShellCaptureHandler<TEnv = unknown>(
       const prerenderPromise = prerender(<SsrRoot />, {
         signal: controller.signal,
         ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+        // Explicit option only — the ssr:false auto-raise is live-SSR scoped
+        // (RangoBaseOptions.progressiveChunkSize documents the contract); the
+        // capture handler starts prerender without deserializing the payload,
+        // so segment metadata is not read here. The captured value rides the
+        // postponed state into every later resume().
+        ...(deps.progressiveChunkSize !== undefined && {
+          progressiveChunkSize: deps.progressiveChunkSize,
+        }),
         // Abort is how capture WORKS: once the shell is quiet we abort() to
         // freeze the prelude and let the still-pending holes postpone. React
         // reports the abort reason for each pending boundary through onError.