npm - @rangojs/router - Versions diffs - 0.9.0 → 0.10.1 - Mend

@rangojs/router 0.9.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (68) hide show

package/AGENTS.md +1 -1
package/LICENSE +21 -0
package/README.md +17 -15
package/dist/types/cache/cf/cf-cache-constants.d.ts +1 -1
package/dist/types/cache/cf/cf-cache-store.d.ts +1 -1
package/dist/types/outlet-context.d.ts +9 -0
package/dist/types/outlet-provider.d.ts +2 -1
package/dist/types/route-content-wrapper.d.ts +4 -1
package/dist/types/rsc/nonce.d.ts +10 -0
package/dist/types/rsc/shell-capture-constants.d.ts +1 -1
package/dist/types/rsc/types.d.ts +6 -2
package/dist/types/ssr/index.d.ts +18 -0
package/dist/types/ssr/ssr-root.d.ts +16 -0
package/dist/types/ssr-suspension-warning.d.ts +20 -0
package/dist/types/types/loader-types.d.ts +5 -1
package/dist/types/types/segments.d.ts +17 -0
package/dist/types/vite/discovery/state.d.ts +6 -0
package/dist/types/vite/plugin-types.d.ts +27 -0
package/dist/types/vite/plugins/virtual-entries.d.ts +1 -1
package/dist/types/vite/utils/shared-utils.d.ts +1 -0
package/dist/vite/index.js +56 -26
package/package.json +26 -26
package/skills/bundle-analysis/SKILL.md +1 -1
package/skills/loader/SKILL.md +17 -2
package/skills/testing/SKILL.md +1 -1
package/skills/testing/bindings.md +1 -1
package/skills/testing/cache-prerender.md +1 -1
package/skills/testing/client-components.md +1 -1
package/skills/testing/e2e-parity.md +1 -1
package/skills/testing/flight.md +1 -1
package/skills/testing/handles.md +1 -1
package/skills/testing/loader.md +1 -1
package/skills/testing/middleware.md +1 -1
package/skills/testing/render-handler.md +1 -1
package/skills/testing/response-routes.md +1 -1
package/skills/testing/reverse-and-types.md +1 -1
package/skills/testing/server-actions.md +1 -1
package/skills/testing/server-tree.md +1 -1
package/skills/testing/setup.md +1 -1
package/src/browser/merge-segment-loaders.ts +4 -0
package/src/cache/cache-runtime.ts +2 -2
package/src/cache/cf/cf-cache-constants.ts +1 -1
package/src/cache/cf/cf-cache-store.ts +1 -1
package/src/client.tsx +2 -0
package/src/outlet-context.ts +9 -0
package/src/outlet-provider.tsx +4 -0
package/src/route-content-wrapper.tsx +7 -0
package/src/router/segment-resolution/fresh.ts +48 -17
package/src/router.ts +7 -2
package/src/rsc/handler.ts +4 -4
package/src/rsc/nonce.ts +16 -0
package/src/rsc/shell-capture-constants.ts +1 -1
package/src/rsc/shell-capture.ts +41 -8
package/src/rsc/types.ts +6 -2
package/src/segment-system.tsx +57 -12
package/src/ssr/index.tsx +53 -1
package/src/ssr/ssr-root.tsx +50 -22
package/src/ssr-suspension-warning.ts +68 -0
package/src/types/loader-types.ts +5 -1
package/src/types/segments.ts +17 -0
package/src/use-loader.tsx +24 -1
package/src/vite/discovery/shell-prerender-phase.ts +5 -0
package/src/vite/discovery/state.ts +6 -0
package/src/vite/plugin-types.ts +28 -0
package/src/vite/plugins/virtual-entries.ts +26 -3
package/src/vite/rango.ts +3 -0
package/src/vite/router-discovery.ts +31 -19
package/src/vite/utils/shared-utils.ts +8 -2

package/src/rsc/shell-capture.ts CHANGED Viewed

@@ -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,
@@ -378,7 +381,7 @@ function warnNullCaptureOnce(key: string): void {
       "a <Suspense> above the consuming component.\n" +
       'See the /ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md), "The hole ' +
       'doctrine" and "The layout-with-loaders playbook", or the design docs: ' +
-      "https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/design/ppr-shell-resume.md",
+      "https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/design/ppr-shell-resume.md",
   );
 }
@@ -1046,7 +1049,7 @@ export function scheduleShellCapture(
       // Hard-capped: SHELL_CAPTURE_MAX_WAIT_MS arms only inside
       // captureShellHTML, AFTER the capture's router.match() — a handler
       // wedged on a never-settling upstream await has no deadline in force
-      // and would strand the stampede guard and the queue slot (autobarn
+      // and would strand the stampede guard and the queue slot (production
       // pilot). The cap rejects, riding the existing catch: backoff +
       // reportCacheError + token-guarded release. The abandoned attempt keeps
       // running until its context dies; nothing awaits it.
@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.

package/src/ssr/ssr-root.tsx CHANGED Viewed

@@ -139,6 +139,37 @@ function createSsrEventController(opts: {
   };
 }
+/**
+ * Deserialize the Flight stream branch into the payload SsrRoot renders,
+ * fragment expansion included. Factored out of SsrRoot so createSSRHandler can
+ * create the promise BEFORE fizz starts and read metadata that must influence
+ * the fizz call itself (the ssr:false progressiveChunkSize auto-raise) —
+ * awaiting it there is latency-neutral because fizz cannot emit even <html>
+ * until this same promise settles.
+ */
+export function deserializeSsrPayload(
+  createFromReadableStream: CreateFromReadableStream,
+  rscStream: ReadableStream<Uint8Array>,
+): Promise<RscPayload> {
+  // Shell-HIT tails carry replayed segments as VERBATIM stored fragments
+  // (segment-fragments.ts, issue #700); expand them through this
+  // environment's deserializer before anything reads the segments. Every
+  // other payload (full render, capture, actions) has no envelopes and
+  // pays one field scan.
+  // Promise.resolve() adoption is load-bearing: some wirings (the build
+  // temp server's vendored Flight client) return a THENABLE Chunk whose
+  // .then returns undefined — chaining on it directly yields undefined.
+  return Promise.resolve(createFromReadableStream<RscPayload>(rscStream)).then(
+    async (resolvedPayload) => {
+      await expandSegmentFragments(
+        resolvedPayload.metadata?.segments,
+        createFromReadableStream,
+      );
+      return resolvedPayload;
+    },
+  );
+}
 /**
  * Options for {@link createSsrRootComponent}.
  */
@@ -147,6 +178,13 @@ export interface SsrRootOptions {
   createFromReadableStream: CreateFromReadableStream;
   /** The Flight stream branch to deserialize into the SSR VDOM. */
   rscStream: ReadableStream<Uint8Array>;
+  /**
+   * Pre-created payload promise (deserializeSsrPayload over the SAME
+   * rscStream). When present SsrRoot adopts it instead of deserializing
+   * lazily on first render — the stream can only be consumed once, so the
+   * caller that already started deserialization MUST pass the promise in.
+   */
+  payload?: Promise<RscPayload>;
   /** Nonce for CSP; propagated to NonceContext. */
   nonce?: string;
   /**
@@ -205,33 +243,23 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     origin,
   } = opts;
-  let payload: Promise<RscPayload> | undefined;
+  // onPayloadSettled fires AFTER fragment expansion (inside
+  // deserializeSsrPayload): the capture's fizz-readiness gate must include
+  // fragment module loads.
+  const adoptPayload = (p: Promise<RscPayload>): Promise<RscPayload> => {
+    if (onPayloadSettled) p.then(onPayloadSettled, onPayloadSettled);
+    return p;
+  };
+  let payload: Promise<RscPayload> | undefined =
+    opts.payload && adoptPayload(opts.payload);
   let handlesPromise: Promise<HandleData> | undefined;
   let ssrContextValue: NavigationStoreContextValue | undefined;
   let rootPromise: Promise<React.ReactNode> | undefined;
   return function SsrRoot() {
-    if (payload === undefined) {
-      // Shell-HIT tails carry replayed segments as VERBATIM stored fragments
-      // (segment-fragments.ts, issue #700); expand them through this
-      // environment's deserializer before anything reads the segments. Every
-      // other payload (full render, capture, actions) has no envelopes and
-      // pays one field scan. onPayloadSettled fires AFTER expansion: the
-      // capture's fizz-readiness gate must include fragment module loads.
-      // Promise.resolve() adoption is load-bearing: some wirings (the build
-      // temp server's vendored Flight client) return a THENABLE Chunk whose
-      // .then returns undefined — chaining on it directly yields undefined.
-      payload = Promise.resolve(
-        createFromReadableStream<RscPayload>(rscStream),
-      ).then(async (resolvedPayload) => {
-        await expandSegmentFragments(
-          resolvedPayload.metadata?.segments,
-          createFromReadableStream,
-        );
-        return resolvedPayload;
-      });
-      if (onPayloadSettled) payload.then(onPayloadSettled, onPayloadSettled);
-    }
+    payload ??= adoptPayload(
+      deserializeSsrPayload(createFromReadableStream, rscStream),
+    );
     const resolved = React.use(payload);
     const themeConfig = resolved.metadata?.themeConfig ?? null;

package/src/ssr-suspension-warning.ts ADDED Viewed

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

package/src/types/loader-types.ts CHANGED Viewed

@@ -195,7 +195,11 @@ export type LoaderFn<
  *
  * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
  * deliberately streaming sibling awaits only itself, and the sibling keeps
- * streaming behind its `loading()`/Suspense boundary.
+ * streaming behind its `loading()`/Suspense boundary. Watch the scoping when
+ * the boundary must be SSR-complete: ONE unflagged read under it still
+ * suspends the whole boundary, which then streams as its fallback — looking
+ * exactly like the flag not working. In dev the router warns at the read
+ * site naming the unflagged loader (ssr-suspension-warning.ts).
  */
 export type LoaderOptions = {
   ssr?: boolean;

package/src/types/segments.ts CHANGED Viewed

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

package/src/use-loader.tsx CHANGED Viewed

@@ -15,6 +15,7 @@ import {
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import { loaderStore, type LoaderEntry } from "./loader-store.js";
 import { decodeLoaderEntry } from "./decode-loader-results.js";
+import { warnAwaitedSsrSuspension } from "./ssr-suspension-warning.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 function isShareableGet(options: LoadOptions | undefined): boolean {
@@ -64,11 +65,18 @@ function lookupLoaderStreams(
 function extractContentLoaderData(
   node: ReactNode,
   loaderId: string,
+  awaitedAcc?: string[],
 ): LoaderLookup {
   if (!isValidElement(node)) return NOT_FOUND;
   const props = node.props as Record<string, any> | undefined;
   if (!props) return NOT_FOUND;
+  // Collect BEFORE the lookups so ids on the element that owns the stream
+  // entry count for the SSR suspension diagnostic.
+  if (awaitedAcc && Array.isArray(props.awaitedLoaderIds)) {
+    awaitedAcc.push(...props.awaitedLoaderIds);
+  }
   // Direct OutletProvider with loaderData
   if (props.loaderData && loaderId in props.loaderData) {
     return { value: props.loaderData[loaderId] };
@@ -93,7 +101,9 @@ function extractContentLoaderData(
     }
   }
-  if (props.children) return extractContentLoaderData(props.children, loaderId);
+  if (props.children) {
+    return extractContentLoaderData(props.children, loaderId, awaitedAcc);
+  }
   return NOT_FOUND;
 }
@@ -136,9 +146,14 @@ function useLoaderInternal<T>(
     contextData: T | undefined;
     hasContextData: boolean;
     pendingStream?: Promise<unknown>;
+    /** { ssr: false } loader ids seen on the chain up to (and including) the
+     *  level that owned the read — input for the dev SSR suspension warning. */
+    awaitedLoaderIds?: string[];
   } => {
+    const awaited: string[] = [];
     let current: OutletContextValue | null | undefined = context;
     while (current) {
+      if (current.awaitedLoaderIds) awaited.push(...current.awaitedLoaderIds);
       if (current.loaderData && loader.$$id in current.loaderData) {
         return {
           contextData: current.loaderData[loader.$$id] as T,
@@ -152,6 +167,7 @@ function useLoaderInternal<T>(
             contextData: undefined,
             hasContextData: true,
             pendingStream: streamed.stream,
+            awaitedLoaderIds: awaited,
           };
         }
         return { contextData: streamed.value as T, hasContextData: true };
@@ -159,6 +175,7 @@ function useLoaderInternal<T>(
       const contentData = extractContentLoaderData(
         current.content,
         loader.$$id,
+        awaited,
       );
       if (contentData !== NOT_FOUND) {
         if ("stream" in contentData) {
@@ -166,6 +183,7 @@ function useLoaderInternal<T>(
             contextData: undefined,
             hasContextData: true,
             pendingStream: contentData.stream,
+            awaitedLoaderIds: awaited,
           };
         }
         return { contextData: contentData.value as T, hasContextData: true };
@@ -184,6 +202,11 @@ function useLoaderInternal<T>(
   const { hasContextData } = walk;
   let contextData = walk.contextData;
   if (walk.pendingStream) {
+    warnAwaitedSsrSuspension(
+      loader.$$id,
+      walk.awaitedLoaderIds,
+      walk.pendingStream,
+    );
     contextData = decodeLoaderEntry(use(walk.pendingStream)) as T;
   }

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

@@ -196,6 +196,11 @@ export async function runShellPrerenderPhase(
       prerender: reactDomStatic.prerender ?? reactDomStatic.default?.prerender,
       injectRSCPayload: htmlStream.injectRSCPayload,
       headScripts: "preinit",
+      // Build-captured shells must honor the explicit outlining budget: the
+      // capture value rides the postponed state into every runtime resume().
+      ...(s.opts?.progressiveChunkSize !== undefined && {
+        progressiveChunkSize: s.opts.progressiveChunkSize,
+      }),
       loadBootstrapScriptContent: async () => bootstrapContent,
     });