@rangojs/router 0.22.1 → 0.24.0

package/src/rsc/rewrite-passes.ts

@@ -0,0 +1,203 @@
+/**
+ * The pass loop that honors `throw rewrite()` (route-definition/rewrite.ts):
+ * one catch around the global middleware chain moves the same request
+ * context to the target (server/request-context.ts rebaseRequestContext) and
+ * runs the request again from the top, as a direct visit to the target
+ * would run it. Shared by the request handler (rsc/handler.ts) and the
+ * dispatch testing primitive, so the two cannot drift.
+ */
+
+import { RewriteLoopError } from "../errors.js";
+import {
+  describeRewriteTarget,
+  isRewrite,
+  rewriteNotSupported,
+  type Rewrite,
+} from "../route-definition/rewrite.js";
+import { prefixBasename } from "../router/basename.js";
+import { createReverseFunction } from "../router/handler-context.js";
+import { stripInternalParams } from "../router/internal-params.js";
+import {
+  rebaseRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
+import { recordRewriteHop } from "../server/rewrite-trail.js";
+
+/** Response header naming the route path a rewritten request rendered. */
+export const REWRITE_HEADER = "x-rango-rewrite";
+
+/**
+ * Resolve a rewrite's target against the router's route map (global names,
+ * no param auto-fill, as middleware `ctx.reverse`) and the request origin.
+ * A path is basename-prefixed like `redirect()` and must stay under the
+ * basename once normalized (`/../admin` cannot step out of it). The
+ * target's own `_rsc*` params are dropped: only the visitor's transport
+ * params carry over. Throws for an unknown name, a missing param, another
+ * origin or a path outside the basename.
+ */
+export function resolveRewriteTarget(
+  rewrite: Rewrite,
+  routeMap: Record<string, string>,
+  base: URL,
+  basename?: string,
+): URL {
+  const { target } = rewrite;
+  const path =
+    "path" in target
+      ? prefixBasename(target.path, basename)
+      : // `{}`, not undefined: a route with params then throws for the
+        // missing ones instead of resolving to its raw pattern.
+        createReverseFunction(routeMap)(
+          target.name,
+          target.params ?? {},
+          target.search,
+        );
+  const resolved = stripInternalParams(new URL(path, base.origin));
+  if (resolved.origin !== base.origin) {
+    throw new TypeError(
+      `${describeRewriteTarget(target)} must name a path in this app, not another origin.`,
+    );
+  }
+  if (
+    basename &&
+    resolved.pathname !== basename &&
+    !resolved.pathname.startsWith(basename + "/")
+  ) {
+    throw new TypeError(
+      `${describeRewriteTarget(target)} resolves to ${resolved.pathname}, outside the router's basename ${basename}.`,
+    );
+  }
+  resolved.hash = "";
+  return resolved;
+}
+
+/**
+ * The raw URL of a rewritten pass: the target's path and search plus the
+ * visitor's internal `_rsc*` transport params, so a navigation stays a
+ * navigation (same segments, version, partial flag).
+ */
+function rewriteTransportUrl(target: URL, visitorRaw: URL): URL {
+  const raw = new URL(target);
+  visitorRaw.searchParams.forEach((value, key) => {
+    if (key.startsWith("_rsc")) raw.searchParams.append(key, value);
+  });
+  return raw;
+}
+
+/** The next pass of a rewritten request. */
+export interface RewritePass {
+  request: Request;
+  /** The pass's raw URL, `_rsc*` params included. */
+  url: URL;
+  /** The target's clean URL. */
+  target: URL;
+  hops: number;
+}
+
+/**
+ * Move the request context to `rewrite`'s target for the next pass: check
+ * that this request can be rewritten, resolve the target, count the hop,
+ * then rebase the context. Throws the site error for a mutation or a loader
+ * fetch, a resolution error, and RewriteLoopError.
+ */
+export function applyRewrite(
+  rewrite: Rewrite,
+  passRequest: Request,
+  reqCtx: RequestContext<any>,
+  routeMap: Record<string, string>,
+  basename: string | undefined,
+): RewritePass {
+  // A loader fetch first: `load()` with a body is a POST, and its refusal
+  // is the loader fetch's.
+  if (reqCtx.originalUrl.searchParams.has("_rsc_loader")) {
+    throw rewriteNotSupported(rewrite, "loader-fetch");
+  }
+  if (passRequest.method !== "GET" && passRequest.method !== "HEAD") {
+    throw rewriteNotSupported(rewrite, "mutation");
+  }
+  const target = resolveRewriteTarget(rewrite, routeMap, reqCtx.url, basename);
+  const hops = recordRewriteHop(reqCtx, reqCtx.url, target);
+  const url = rewriteTransportUrl(target, reqCtx.originalUrl);
+  const request = new Request(url, passRequest);
+  rebaseRequestContext(reqCtx, request, url);
+  return { request, url, target, hops };
+}
+
+/** The response to a rewrite loop. */
+export function loopDetectedResponse(): Response {
+  return new Response("Loop Detected", {
+    status: 508,
+    headers: { "content-type": "text/plain;charset=utf-8" },
+  });
+}
+
+export interface RewritePassesOptions {
+  reqCtx: RequestContext<any>;
+  /** The visitor's request and raw URL: the first pass. */
+  request: Request;
+  url: URL;
+  routeMap: () => Record<string, string>;
+  basename: string | undefined;
+  /** One pass: the global chain matched on `url`'s path around the core handler. */
+  runPass: (request: Request, url: URL) => Promise<Response>;
+  /** After a hop moved the context to its target. */
+  onHop?: (pass: RewritePass) => void;
+  /** Report a rewrite the request cannot take (onError, phase "routing"). */
+  report: (error: unknown, at: { request: Request; url: URL }) => void;
+  /**
+   * The response for a refused rewrite other than a loop (a loader fetch's
+   * error response); undefined rethrows the error.
+   */
+  refuse?: (error: unknown, rewrite: Rewrite) => Response | undefined;
+}
+
+export interface RewritePassesResult {
+  response: Response;
+  /** The pathname the final pass rendered, when a rewrite took the request there. */
+  rewrittenTo?: string;
+}
+
+/**
+ * Run the request pass by pass until one produces a response. A `Rewrite`
+ * that unwinds a pass moves the context to its target and runs the next;
+ * a loop answers 508; a rewrite the request cannot take is reported and
+ * becomes `refuse`'s response, or is thrown.
+ */
+export async function runRewritePasses(
+  opts: RewritePassesOptions,
+): Promise<RewritePassesResult> {
+  let request = opts.request;
+  let url = opts.url;
+  let rewrittenTo: string | undefined;
+  for (;;) {
+    let rewrite: Rewrite;
+    try {
+      return { response: await opts.runPass(request, url), rewrittenTo };
+    } catch (error) {
+      if (!isRewrite(error)) throw error;
+      rewrite = error;
+    }
+    let pass: RewritePass;
+    try {
+      pass = applyRewrite(
+        rewrite,
+        request,
+        opts.reqCtx,
+        opts.routeMap(),
+        opts.basename,
+      );
+    } catch (error) {
+      opts.report(error, { request, url });
+      if (error instanceof RewriteLoopError) {
+        return { response: loopDetectedResponse() };
+      }
+      const refused = opts.refuse?.(error, rewrite);
+      if (refused) return { response: refused };
+      throw error;
+    }
+    request = pass.request;
+    url = pass.url;
+    rewrittenTo = pass.target.pathname;
+    opts.onHop?.(pass);
+  }
+}

package/src/rsc/rsc-rendering.ts

@@ -51,7 +51,7 @@ import {
 import type { HandlerContext } from "./handler-context.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
-import { buildFullPayload } from "./full-payload.js";
+import { buildFullPayload, renderedLocation } from "./full-payload.js";
 import {
   capShellWindow,
   lastStoredCaptureSeq,
@@ -94,6 +94,7 @@ import {
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import {
   isWarmReplace,
   noteWarmShellEvent,
@@ -302,7 +303,10 @@ type PreparedRender =
   | {
       kind: "payload";
       payload: RscPayload;
-      /** The response depends on the source page: an intercept targets the route. */
+      /**
+       * The response depends on the source page: an intercept targets the
+       * route, or it carries deferred units (`prefetch: false`).
+       */
       sourceScoped: boolean;
       pprReplayStatus?: PprReplayStatus;
       /** The key a navigation-only heal capture stores under, when one is needed. */
@@ -831,11 +835,17 @@ function* preparePayloadPlan<TEnv>(
       };
     }
 
+    // What a prefetch defers depends on what the source page holds: a page
+    // that holds the segment gets it rendered. Adopted from another page, a
+    // deferring payload held the click on a fill for content a plain click
+    // showed at once, and ran held work again.
+    const deferring = result.segments.some((s) => s.deferred);
+    if (deferring) reqCtx._payloadDeferred = true;
     return {
       kind: "payload",
       payload: {
         metadata: {
-          pathname: url.pathname,
+          pathname: renderedLocation(reqCtx, url).pathname,
           // routerId is serialized on every payload (including within-session
           // ones) so the frontend can read the current app/router identity. It
           // always equals the current app's id: a cross-app navigation is
@@ -860,7 +870,7 @@ function* preparePayloadPlan<TEnv>(
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       },
-      sourceScoped: result.interceptTargeted === true,
+      sourceScoped: result.interceptTargeted === true || deferring,
       pprReplayStatus,
       healKey,
     };
@@ -1200,16 +1210,34 @@ function renderPreparedRscResponse<TEnv>(
     rscHeaders["x-rsc-prefetch-scope"] = "source";
   }
   // Enable browser HTTP caching for prefetch responses only.
-  // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
-  // a source-agnostic response (see sourceScoped above), and a configured
-  // cache-control value (false disables caching).
-  const isPrefetch = requestHeaders(request).has("X-Rango-Prefetch");
-  if (isPrefetch && isPartial && !sourceScoped) {
+  // Requires a prefetch request (X-Rango-Prefetch, sent by Link prefetch
+  // fetch), a source-agnostic response (see sourceScoped above), and a
+  // configured cache-control value (false disables caching).
+  if (reqCtx._requestKind === "prefetch" && isPartial && !sourceScoped) {
     const cc = ctx.router.prefetchCacheControl;
     if (cc) {
       rscHeaders["cache-control"] = cc;
     }
   }
+  // prefetch: false (docs/design/prefetch-false.md, R7). A response that
+  // carries deferred units answers one page's prefetch, and a fill is the
+  // second half of one adoption: neither is reused by a shared cache or the
+  // document cache (which also refuses a payload marked `_payloadDeferred`),
+  // whatever Cache-Control the route set. A route with no flag keeps its
+  // headers.
+  if (
+    reqCtx._payloadDeferred ||
+    (isPartial && reqCtx._requestKind === "fill")
+  ) {
+    rscHeaders["cache-control"] = NOT_REUSED;
+  }
+  // The browser may still keep the body, and answers from it without asking
+  // while it reloads a document for back/forward. A navigation is the same
+  // URL as its prefetch: the header that tells them apart keeps the deferring
+  // body from answering one.
+  if (reqCtx._payloadDeferred) {
+    rscHeaders.vary += `, ${PREFETCH_HEADER}`;
+  }
 
   const isFlightResponse = isRscRequest(request, url, isPartial);
   const stageTracking = {
@@ -1694,6 +1722,21 @@ function publishTailTiming(
 
 const PENDING = Symbol("pending");
 
+/**
+ * Cache-Control of a response that is not to be reused: one that carries
+ * deferred units (`prefetch: false`), and a fill. `private` keeps it out of
+ * shared caches; `no-cache` makes the browser ask again, and with no
+ * validator on the response that is a full request. The browser may keep the
+ * body all the same (Chromium does) and answers from it, without asking,
+ * while it reloads a document for back/forward. That is harmless: the client
+ * completes any payload that carries deferred work, wherever it came from.
+ * Not `no-store`:
+ * Chromium reports a `no-store` fetch whose body is read through a stream
+ * as canceled (net::ERR_ABORTED in DevTools, and Playwright's
+ * response.finished() never settles), though every byte arrived.
+ */
+const NOT_REUSED = "private, no-cache";
+
 /**
  * Whether `value` is not a promise, or a promise that has already settled:
  * racing it against an already-resolved promise, a settled one's reaction is
@@ -1824,6 +1867,8 @@ function serveShellHit(
       payload.metadata.initialTheme = entry.initialTheme as
         | import("../theme/types.js").Theme
         | undefined;
+      // Same for the location: the capture rendered the target's.
+      payload.metadata.pathname = url.pathname;
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).

package/src/rsc/shell-capture.ts

@@ -73,6 +73,7 @@ import {
 } from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import { requestHeaders } from "../server/request-headers.js";
+import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import type {
   CachedEntryData,
   ShellCacheEntry,
@@ -1448,7 +1449,7 @@ function createNavigationCaptureRequest(request: Request, url: URL): Request {
   headers.set("accept", "text/html");
   for (const name of [
     "rsc-action",
-    "x-rango-prefetch",
+    PREFETCH_HEADER,
     "x-rango-state",
     "x-rsc-hmr",
     "x-rsc-router-client-path",

package/src/rsc/ssr-setup.ts

@@ -22,6 +22,7 @@ import {
   RSC_WIRE_MIME,
 } from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { renderedLocation } from "./full-payload.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
 
@@ -38,6 +39,8 @@ export const SSR_SETUP_VAR = "__ssrSetup";
  * lazily so stores created after kickoff are still captured). Without a
  * getter the promises run bare — no `.then()` microtasks, no
  * `performance.now()` calls — keeping the non-debug hot path lean.
+ * `ssrModule` reuses a load already started (a rewritten request's earlier
+ * pass).
  */
 export function startSSRSetup<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -45,16 +48,17 @@ export function startSSRSetup<TEnv>(
   env: TEnv,
   url: URL,
   getMetricsStore?: () => MetricsStore | undefined,
+  ssrModule?: Promise<SSRModule>,
 ): Promise<SSRSetup> {
   if (!getMetricsStore) {
     return Promise.all([
-      ctx.loadSSRModule(),
+      ssrModule ?? ctx.loadSSRModule(),
       ctx.resolveStreamMode(request, env, url),
     ]);
   }
   const start = performance.now();
   return Promise.all([
-    ctx.loadSSRModule().then((mod) => {
+    (ssrModule ?? ctx.loadSSRModule()).then((mod) => {
       appendMetric(
         getMetricsStore(),
         "ssr:module-load",
@@ -110,7 +114,9 @@ export function createSsrHtmlStage<TEnv>(
       options.url,
       options.metricsStore,
     );
-    const renderErrors = _getRequestContext()?._renderErrors;
+    const reqCtx = _getRequestContext();
+    const renderErrors = reqCtx?._renderErrors;
+    const location = renderedLocation(reqCtx, options.url);
     return {
       render: () =>
         // search: the LIVE request's query string, threaded out-of-band into
@@ -121,11 +127,11 @@ export function createSsrHtmlStage<TEnv>(
         ssrModule.renderHTML(flight.stream, {
           ...options.render,
           streamMode,
-          search: options.url.search,
+          search: location.search,
           // origin: same out-of-band channel — seeds the SSR store location
           // so origin-dependent markup (Link's data-external) agrees with the
           // browser's window.location across hydration.
-          origin: options.url.origin,
+          origin: location.origin,
           // A component that throws inside a Suspense boundary leaves an
           // errored boundary in a completed document; the document cache
           // reads the list before storing it.

package/src/segment-loader-promise.ts

@@ -1,5 +1,6 @@
 import type { ResolvedSegment } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
+import { asStream } from "./browser/defer.js";
 
 /**
  * Browser: a boundary is handed the settled value. React treats a promise as
@@ -7,7 +8,13 @@ import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
  * promise it has not read, in a render that cannot wait, shows its fallback.
  * So a cache entry records its array once the aggregate fulfils and later
  * calls return that same array; until then (and when it rejects) they return
- * the promise. A boundary with no loaders gets one shared empty array.
+ * the promise. A boundary with no loaders gets one shared empty array. An
+ * aggregate whose sources are all streams that have fulfilled (React's
+ * `status` on the thenable, which Flight sets itself; a plain value is not a
+ * stream, whatever fields it carries) is known on its first
+ * call and is the array from the start: the sources of a page whose entry was
+ * rewritten without a render (browser/partial-update.ts fillHoles) are
+ * first aggregated by the next navigation that keeps them.
  *
  * Server: a fresh promise per call, so Suspense emits the fallback in the
  * streamed HTML. A shared resolved promise would carry React's `.status`
@@ -22,10 +29,10 @@ const IS_BROWSER = typeof window !== "undefined";
 
 interface LoaderCacheEntry {
   sources: any[];
-  // Resolves to the same array it records in `value`; a rejection passes
-  // through untouched.
-  promise: Promise<any[]>;
-  value?: any[];
+  // The aggregate while it is pending (a rejection passes through untouched),
+  // then the array it fulfilled with. The array from the start for sources
+  // that have all fulfilled.
+  result: Promise<any[]> | any[];
 }
 
 // Cap the per-key entries array. A stable first-ref (e.g. a layout loader whose
@@ -91,13 +98,7 @@ export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
       }
     }
   }
-  return Promise.all(
-    loaders.map((loader) =>
-      loader.loaderData instanceof Promise
-        ? loader.loaderData
-        : Promise.resolve(loader.loaderData),
-    ),
-  );
+  return Promise.all(loaders.map((loader) => asStream(loader.loaderData)));
 }
 
 function isObjectLike(value: unknown): value is object {
@@ -131,17 +132,19 @@ export function getMemoizedLoaderPromise(
   if (entries) {
     for (const entry of entries) {
       if (hasSameReferences(entry.sources, sources)) {
-        return entry.value ?? entry.promise;
+        return entry.result;
       }
     }
   }
 
-  const newEntry = { sources } as LoaderCacheEntry;
-  const promise = buildLoaderPromise(loaders).then((values) => {
-    newEntry.value = values;
-    return values;
-  });
-  newEntry.promise = promise;
+  const newEntry: LoaderCacheEntry = { sources, result: [] };
+  newEntry.result = sources.every(
+    (source) =>
+      source instanceof Promise &&
+      (source as { status?: string }).status === "fulfilled",
+  )
+    ? sources.map((source) => source.value)
+    : buildLoaderPromise(loaders).then((values) => (newEntry.result = values));
   if (entries) {
     // Bound the array: drop the oldest entry before appending when at the cap.
     if (entries.length >= MAX_ENTRIES_PER_KEY) {
@@ -153,5 +156,5 @@ export function getMemoizedLoaderPromise(
   } else {
     primitiveLoaderCache.set(first, [newEntry]);
   }
-  return promise;
+  return newEntry.result;
 }

package/src/segment-system.tsx

@@ -9,6 +9,8 @@ import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
+import { isRenderableLoading } from "./types/boundaries.js";
+import { isPlaceholder } from "./types/segments.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
@@ -23,6 +25,7 @@ import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
 import { getBoundaryContent } from "./segment-boundary-content.js";
+import { asStream } from "./browser/defer.js";
 import {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
@@ -61,15 +64,6 @@ function segDebugLog(msg: string, details?: Record<string, unknown>): void {
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
-// A loading skeleton is renderable only when it is a real ReactNode value.
-// `false` is treated as "not renderable" here. This is the three-term gate;
-// the distinct two-term gate at the LoaderBoundary site deliberately treats
-// `false` as "create a boundary without a RouteContentWrapper"
-// (tree-structure.md), so it must NOT use this helper.
-function isRenderableLoading(loading: ReactNode): boolean {
-  return loading !== undefined && loading !== null && loading !== false;
-}
-
 // Exported for unit testing the no-parallel fast path (D6); internal otherwise.
 export function restoreParallelLoaderMarkers(
   segments: ResolvedSegment[],
@@ -264,32 +258,61 @@ function wrapDefaultOutletContent(
  * reader sits above every boundary, so the throw is a Fizz shell error (500).
  * `settledFallback` is that node; the caller plants it and, for a redirect,
  * replaces the whole page (an ancestor reading the loader would still throw).
+ *
+ * `settle` is the forceAwait/action lane of a loader set that holds a
+ * deferred loader (`prefetch: false`, see hasDeferred): every other loader is
+ * settled like a flagged one, so the commit stays whole for them, and the
+ * deferred one keeps its hole for the read site to suspend on. A settled
+ * error with no boundary is left to the read site there, where the aggregate
+ * lane it replaces would have thrown it.
  */
-async function buildLoaderStreams(loaders: ResolvedSegment[]): Promise<{
+async function buildLoaderStreams(
+  loaders: ResolvedSegment[],
+  settle?: boolean,
+): Promise<{
   streams: Record<string, unknown>;
   awaitedIds: string[] | undefined;
   settledFallback: ReactNode | undefined;
 }> {
   const streams: Record<string, unknown> = {};
   let awaitedIds: string[] | undefined;
-  let awaitedValues: unknown[] | undefined;
+  let settledIds: string[] | undefined;
+  let settledValues: unknown[] | undefined;
   for (const l of loaders) {
-    if (l.awaitBeforeFlush) {
+    if (l.awaitBeforeFlush || (settle && !isPlaceholder(l))) {
       const value = await l.loaderData;
       streams[l.loaderId!] = value;
-      (awaitedIds ??= []).push(l.loaderId!);
-      (awaitedValues ??= []).push(value);
+      if (l.awaitBeforeFlush) (awaitedIds ??= []).push(l.loaderId!);
+      (settledIds ??= []).push(l.loaderId!);
+      (settledValues ??= []).push(value);
     } else {
       streams[l.loaderId!] = l.loaderData;
     }
   }
-  const settledFallback = awaitedIds
-    ? (decodeLoaderResults(awaitedValues!, awaitedIds).errorFallback ??
-      undefined)
-    : undefined;
+  let settledFallback: ReactNode | undefined;
+  if (settledIds) {
+    try {
+      settledFallback =
+        decodeLoaderResults(settledValues!, settledIds).errorFallback ??
+        undefined;
+    } catch (error) {
+      if (!settle) throw error;
+    }
+  }
   return { streams, awaitedIds, settledFallback };
 }
 
+/**
+ * A loader set that holds a deferred loader (`prefetch: false`): its
+ * `loaderData` is a hole (browser/defer.ts) the browser resolves when the
+ * fill request lands (browser/partial-update.ts fillHoles), so no lane may
+ * await the set as a whole. The
+ * tree build would wait for a request that is only sent once it returns.
+ */
+function hasDeferred(loaders: ResolvedSegment[]): boolean {
+  return loaders.some(isPlaceholder);
+}
+
 function isLoaderRedirectNode(node: ReactNode): boolean {
   return isValidElement(node) && node.type === LoaderRedirect;
 }
@@ -354,6 +377,11 @@ export async function renderSegments(
     rootLayout: RootLayout,
     transitionGatedOff,
   } = options || {};
+  // forceAwait and action lanes settle loader data before the commit, except
+  // a set that holds a deferred loader (hasDeferred).
+  const settleLoaders = !!(forceAwait || isAction);
+  const settleAll = (loaders: ResolvedSegment[]): boolean =>
+    settleLoaders && !hasDeferred(loaders);
 
   const segDebug = INTERNAL_RANGO_DEBUG;
   const segDebugStart = segDebug ? performance.now() : 0;
@@ -484,6 +512,8 @@ export async function renderSegments(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
     );
 
+    // A deferred unit's component is a hole (browser/defer.ts), never a
+    // Promise: the awaits below pass it through.
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
       const componentAwaitStart = segDebug ? performance.now() : 0;
@@ -540,7 +570,11 @@ export async function renderSegments(
           componentTypeof: typeof c,
         });
       }
-      nodeContent = registerLazyRef(resolvedComponent);
+      // A hole here is read by React itself (browser/defer.ts asStream).
+      const streamed = asStream(resolvedComponent) as ReactNode;
+      nodeContent = isPlaceholder(node.segment)
+        ? streamed
+        : registerLazyRef(streamed);
     }
 
     // Wrap with <ViewTransition> if transition config exists (React 19.3+ / experimental).
@@ -614,7 +648,7 @@ export async function renderSegments(
       // for content-suspending routes (segment-loader-promise.ts).
       let boundaryLoaderStreams: Record<string, unknown> | undefined;
       let boundaryAwaitedLoaderIds: string[] | undefined;
-      if (forceAwait || isAction) {
+      if (settleAll(loaderEntries)) {
         const awaitStart = segDebug ? performance.now() : 0;
         boundaryLoaderData =
           loaderDataPromise instanceof Promise
@@ -632,7 +666,7 @@ export async function renderSegments(
           streams: boundaryLoaderStreams,
           awaitedIds: boundaryAwaitedLoaderIds,
           settledFallback,
-        } = await buildLoaderStreams(loaderEntries));
+        } = await buildLoaderStreams(loaderEntries, settleLoaders));
         if (settledFallback !== undefined) {
           if (isLoaderRedirectNode(settledFallback)) {
             content = settledFallback;
@@ -698,7 +732,7 @@ export async function renderSegments(
       let errorFallback: ReactNode = null;
       let loaderStreams: Record<string, unknown> | undefined;
       let awaitedLoaderIds: string[] | undefined;
-      if (forceAwait || isAction) {
+      if (settleAll(layoutLoaders)) {
         const layoutAwaitStart = segDebug ? performance.now() : 0;
         const resolvedData = await buildLoaderPromise(layoutLoaders);
         if (segDebug) {
@@ -726,7 +760,7 @@ export async function renderSegments(
           streams: loaderStreams,
           awaitedIds: awaitedLoaderIds,
           settledFallback,
-        } = await buildLoaderStreams(layoutLoaders));
+        } = await buildLoaderStreams(layoutLoaders, settleLoaders));
         if (settledFallback !== undefined) {
           if (isLoaderRedirectNode(settledFallback)) {
             content = settledFallback;
@@ -780,9 +814,9 @@ export async function renderSegments(
           // 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);
+            (settleLoaders ||
+              ownedLoaders.every((l) => l.awaitBeforeFlush === true)) &&
+            !hasDeferred(ownedLoaders);
           if (settleParallelAggregate) {
             const parallelAwaitStart = segDebug ? performance.now() : 0;
             p.loaderDataPromise =