@rangojs/router 0.5.2 → 0.6.0

package/src/router.ts

@@ -3,6 +3,11 @@ import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
+import {
+  isClientUrlPatterns,
+  isClientUrlReference,
+} from "./client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "./client-urls/types.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
 import {
@@ -100,6 +105,7 @@ import type {
   Rango,
   RangoInternal,
   RouterRequestInput,
+  UrlPatternMount,
 } from "./router/router-interfaces.js";
 
 // Extracted closure functions
@@ -330,6 +336,7 @@ export function createRouter<TEnv = any>(
 
   // Store reference to urlpatterns for runtime manifest generation
   let storedUrlPatterns: UrlPatterns<TEnv, any> | null = null;
+  const urlpatternMounts: UrlPatternMount<TEnv>[] = [];
 
   // Global middleware storage
   const globalMiddleware: MiddlewareEntry<TEnv>[] = [];
@@ -572,6 +579,13 @@ export function createRouter<TEnv = any>(
             }
           }
         : undefined,
+      // notFound() resolution deps: the streamed envelope carries the
+      // server-rendered not-found UI, mirroring the consumption lane's
+      // boundary resolution (segment-resolution/helpers.ts).
+      {
+        findNearestNotFoundBoundary,
+        notFoundComponent: notFound,
+      },
     );
 
     // Emit loader.end after the promise settles (fire-and-forget)
@@ -756,7 +770,30 @@ export function createRouter<TEnv = any>(
     id: routerId,
     basename,
 
-    routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
+    routes(
+      patternsOrBuilder:
+        | UrlPatterns<TEnv>
+        | UrlBuilder<TEnv>
+        | ClientUrlPatterns,
+    ): any {
+      // Pure-client mounting shorthand: a clientUrls() definition passed
+      // directly NORMALIZES to a root include in the canonical urls() tree —
+      // exactly `include("/", definition, { name: "" })`, keeping local route
+      // names bare and local patterns app-absolute. This is sugar over the
+      // ONE composition model, not a second registration path: it rides the
+      // same lazy include materialization, so no ordering, one-definition, or
+      // deferral rules exist. Prefixing, wrapping RSC layouts, and middleware
+      // scope still come from mounting through include() in urls() yourself.
+      if (
+        isClientUrlPatterns(patternsOrBuilder) ||
+        isClientUrlReference(patternsOrBuilder)
+      ) {
+        const clientSource = patternsOrBuilder as ClientUrlPatterns;
+        patternsOrBuilder = urls(({ include }) => [
+          include("/", clientSource, { name: "" }),
+        ]) as UrlPatterns<TEnv>;
+      }
+
       // Wrap builder functions in urls() automatically
       const urlPatterns: UrlPatterns<TEnv> =
         typeof patternsOrBuilder === "function"
@@ -766,6 +803,10 @@ export function createRouter<TEnv = any>(
       // Store reference for runtime manifest generation
       storedUrlPatterns = urlPatterns;
       const currentMountIndex = mountIndex++;
+      urlpatternMounts.push({
+        patterns: urlPatterns,
+        mountIndex: currentMountIndex,
+      });
 
       // Create manifest and patterns maps for route registration
       const manifest = new Map<string, EntryData>();
@@ -1095,6 +1136,10 @@ export function createRouter<TEnv = any>(
       return storedUrlPatterns ?? undefined;
     },
 
+    get __urlpatternMounts() {
+      return urlpatternMounts;
+    },
+
     // Expose source file for per-router type generation
     __sourceFile,
 

package/src/rsc/full-payload.ts

@@ -44,11 +44,17 @@ export function buildFullPayload(
       resolvedIds: m.resolvedIds,
       params: m.params,
       isPartial: false,
+      interceptTargets: m.interceptTargets,
       rootLayout: ctx.router.rootLayout,
       // Full render: resolve deferred handle values server-side so SSR markup and
       // the first sync useHandle read see resolved values. Partial payloads
       // (rsc-rendering.ts) keep streaming (handleStore.stream()).
       handles: resolvedHandleStream(handleStore),
+      // Post-handler-barrier pushes (streaming loader ctx.handle() writes)
+      // stream here; the client applies them after hydration. Instantly
+      // complete when the loader lane is idle — including PPR shell capture,
+      // where masked loaders never run.
+      handlesLate: handleStore.streamLate(),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       prefetchCacheSize: ctx.router.prefetchCacheSize,

package/src/rsc/handler.ts

@@ -7,7 +7,6 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
-import { createElement } from "react";
 import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
@@ -50,7 +49,10 @@ import { generateNonce, nonce as nonceToken } from "./nonce.js";
 import { VERSION } from "@rangojs/router:version";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
-import { invokeOnError } from "../router/error-handling.js";
+import {
+  invokeOnError,
+  resolveDefaultNotFound,
+} from "../router/error-handling.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -1309,11 +1311,12 @@ export function createRSCHandler<
             handledByBoundary: true,
           });
 
-          const notFoundOption = router.notFound;
-          const notFoundComponent =
-            typeof notFoundOption === "function"
-              ? notFoundOption({ pathname: url.pathname })
-              : (notFoundOption ?? createElement("h1", null, "Not Found"));
+          // No boundary to consult: an unmatched route has no entry chain, so
+          // this always lands on the router option or the shared default.
+          const notFoundComponent = resolveDefaultNotFound(
+            router.notFound,
+            url.pathname,
+          );
 
           const notFoundSegment = {
             id: "notFound",

package/src/rsc/loader-fetch.ts

@@ -12,7 +12,7 @@
  */
 
 import { getLoaderLazy } from "../server/loader-registry.js";
-import { DataNotFoundError } from "../errors.js";
+import { isDataNotFoundError } from "../errors.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
 import { getRequestContext } from "../server/request-context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -289,7 +289,7 @@ export async function handleLoaderFetch<TEnv>(
     // so it does not match the branch above. Map it to a 404 before the generic
     // 500 coercion so a no-middleware fetchable loader's notFound() is honored
     // (the with-middleware path resolves it through the notFoundBoundary).
-    if (error instanceof DataNotFoundError) {
+    if (isDataNotFoundError(error)) {
       return finalizeResponse(
         createResponseWithMergedHeaders(null, { status: 404 }),
       );

package/src/rsc/manifest-init.ts

@@ -1,8 +1,8 @@
 /**
  * Router Manifest Initialization
  *
- * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
- * where the manifest exists but the trie needs rebuilding.
+ * Builds a fresh route trie from every registered URL-pattern mount for
+ * dev/HMR scenarios where the manifest exists but the trie needs rebuilding.
  */
 
 import {
@@ -13,11 +13,12 @@ import {
   setRouterTrie,
   setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
+import { mergeFullManifests } from "../build/merge-full-manifests.js";
 
 /**
- * Build a fresh route trie from router.urlpatterns and store it in the
- * per-router cache. Also sets the per-router manifest and merges into
- * the global manifest for reverse()/href().
+ * Build a fresh route trie from the router's URL-pattern mounts and store it in
+ * the per-router cache. Also sets the per-router manifest and merges into the
+ * global manifest for reverse()/href().
  *
  * Called when manifest data may exist but the per-router trie is missing,
  * which happens in dev mode after HMR: the virtual module sets the manifest
@@ -30,10 +31,28 @@ export async function buildRouterTrieFromUrlpatterns(
 ): Promise<void> {
   const { generateManifestFull } =
     await import("../build/generate-manifest.js");
-  const generated = await generateManifestFull(router.urlpatterns, undefined, {
-    routerId: router.id,
-    ...(router.basename ? { urlPrefix: router.basename } : {}),
-  });
+  const mounts =
+    router.__urlpatternMounts ??
+    (router.urlpatterns
+      ? [{ patterns: router.urlpatterns, mountIndex: undefined }]
+      : []);
+  // mount.mountIndex mirrors the live router's per-mount counter partitioning
+  // (context.ts getShortCode `M{i}` prefixes), so entries generated here carry
+  // the same shortCodes as runtime registration. Build discovery
+  // (discover-routers.ts / runtime-discovery.ts) numbers mounts GLOBALLY across
+  // routers instead — that divergence is invisible: shortCodes never leave
+  // their realm, and route names (the trie keys) carry no mount index (unnamed
+  // routes are `$path_*`, see path-helper.ts).
+  const mountManifests = [];
+  for (const mount of mounts) {
+    mountManifests.push(
+      await generateManifestFull(mount.patterns, mount.mountIndex, {
+        routerId: router.id,
+        ...(router.basename ? { urlPrefix: router.basename } : {}),
+      }),
+    );
+  }
+  const generated = mergeFullManifests(mountManifests);
   // Build the trie through the SAME shared helper the production discovery uses
   // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
   // serialized trie cannot drift. buildPerRouterTrie returns null when there

package/src/rsc/rsc-rendering.ts

@@ -57,6 +57,7 @@ import {
   SHELL_STATUS_HEADER,
   resolvePprConfig,
   buildShellKey,
+  shellSearchSeed,
   isValidShellHit,
   hasIntactShellPayload,
   base64ToBytes,
@@ -153,12 +154,14 @@ function buildNavigationShellKey(
 function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
+  searchSeed: string,
   pprConfig: ResolvedPprConfig,
   store: SegmentCacheStore<any>,
   navigationOnly?: true,
 ): ShellCaptureDescriptor {
   return {
     key,
+    searchSeed,
     buildVersion: ctx.version,
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
@@ -512,7 +515,13 @@ function* shellServePlan<TEnv>(
   ) {
     return { kind: "pass" };
   }
-  const descriptor = createShellCaptureDescriptor(ctx, key, pprConfig, store);
+  const descriptor = createShellCaptureDescriptor(
+    ctx,
+    key,
+    shellSearchSeed(url, reqCtx._searchParamsFilter),
+    pprConfig,
+    store,
+  );
 
   if (
     cached &&
@@ -699,6 +708,7 @@ function* preparePayloadPlan<TEnv>(
           params: result.params,
           isPartial: true,
           slots: result.slots,
+          interceptTargets: result.interceptTargets,
           handles: handleStore.stream(),
           version: ctx.version,
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
@@ -993,6 +1003,7 @@ function scheduleNavigationShellCapture<TEnv>(
       ctx,
       partialCaptureKey ??
         buildNavigationShellKey(url, reqCtx._searchParamsFilter),
+      shellSearchSeed(url, reqCtx._searchParamsFilter),
       pprConfig,
       store,
       true,
@@ -1510,6 +1521,9 @@ function serveShellHit(
       ssrModule.resumeShellHTML!(rscStream, {
         postponed: entry.postponed,
         nonce: undefined,
+        // The shell key's own search — identical to the capture seed for
+        // this key, so the resume tree matches the captured tree.
+        search: shellSearchSeed(url, reqCtx._searchParamsFilter),
       }),
     );
   };

package/src/rsc/shell-capture.ts

@@ -907,6 +907,15 @@ export function gateFlightForCapture(
  */
 export interface ShellCaptureDescriptor {
   key: string;
+  /**
+   * The key's search portion (shellSearchSeed: `?`-prefixed sorted search,
+   * cache.searchParams filter applied, or ""). Seeds the capture render's SSR
+   * store so static-part `useSearchParams` reads bake markup consistent with
+   * the shell's own key; the resume pass derives the identical string from
+   * the HIT request. Computed next to the key so the two cannot drift.
+   * Omitted (build-time bare-pathname captures) = search-less, same as "".
+   */
+  searchSeed?: string;
   /**
    * The RSC handler's build version (HandlerContext.version), stamped into the
    * stored entry as ShellCacheEntry.buildVersion — the serve-side
@@ -1753,6 +1762,9 @@ async function captureAndStoreShell(
         captureShellHTML(gate.stream, {
           quiesce,
           maxWaitMs: capture.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS,
+          // The shell key's own search seeds the capture render's store —
+          // static-part search reads bake what the key names.
+          search: capture.searchSeed,
         }),
       );
     } catch (error) {

package/src/rsc/shell-serve.ts

@@ -129,9 +129,22 @@ export function resolvePprConfig(
  * and lookup makes every shell request a permanent miss.
  */
 export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
+  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
+}
+
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
   const sorted = sortedSearchString(url.searchParams, filter);
-  const searchSuffix = sorted ? `?${sorted}` : "";
-  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+  return sorted ? `?${sorted}` : "";
 }
 
 /**

package/src/rsc/ssr-setup.ts

@@ -111,7 +111,16 @@ export function createSsrHtmlStage<TEnv>(
     );
     return {
       render: () =>
-        ssrModule.renderHTML(flight.stream, { ...options.render, streamMode }),
+        // search: the LIVE request's query string, threaded out-of-band into
+        // the SSR pass so useSearchParams sees real values during document
+        // renders. Deliberately not payload metadata: cached/prerendered
+        // payloads replay captured metadata, and search is not route
+        // identity — it must always come from the request being served.
+        ssrModule.renderHTML(flight.stream, {
+          ...options.render,
+          streamMode,
+          search: options.url.search,
+        }),
       ...(options.init && { init: options.init }),
     };
   };

package/src/rsc/types.ts

@@ -35,10 +35,27 @@ export interface RscPayload {
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable from this location as a
+     * navigation origin (see MatchResult.interceptTargets). The browser-local
+     * clientUrls matcher declines optimistic presentation for these.
+     */
+    interceptTargets?: string[];
     /** Root layout component for browser-side re-renders (client component reference) */
     rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
     /** Handle data accumulated across route segments (async generator that yields on each push) */
     handles?: AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late handle channel: full-state updates for pushes landing
+     * AFTER the handler barrier (streaming loader bodies writing handles
+     * mid-body). `handles` above is drained to completion in blocking
+     * positions (SSR seed, pre-hydration), so late pushes need this separate
+     * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+     * Empty/instantly-complete when no auxiliary-lane work is pending at the
+     * handler barrier. Full payloads only — partial payloads' `handles`
+     * generator streams to full settle already.
+     */
+    handlesLate?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
     /** Cloudflare dev worker generation used for stale-document convergence. */
@@ -158,6 +175,18 @@ export interface SSRRenderOptions {
    * - `"allReady"` — await `stream.allReady` before returning.
    */
   streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /**
+   * The live request's query string (`url.search`, `?`-prefixed or empty).
+   * Seeds the SSR navigation store so `useSearchParams` (and
+   * `useNavigation().location`) carry real values during document renders.
+   * Out-of-band by design — never payload metadata, which cached/prerendered
+   * payloads replay; search is not route identity. The build-time prerender
+   * pass passes none — build shells capture bare pathnames and serve
+   * search-less requests only (runtime ppr captures seed the shell key's
+   * search; see ShellCaptureOptions.search in the SSR entry).
+   */
+  search?: string;
 }
 
 /**
@@ -179,7 +208,7 @@ export interface SSRModule {
    */
   captureShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { quiesce: Promise<void>; maxWaitMs?: number },
+    options: { quiesce: Promise<void>; maxWaitMs?: number; search?: string },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
   /**
@@ -192,7 +221,7 @@ export interface SSRModule {
    */
   resumeShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { postponed: string | null; nonce?: string },
+    options: { postponed: string | null; nonce?: string; search?: string },
   ) => Promise<ReadableStream<Uint8Array>>;
 }
 

package/src/segment-system.tsx

@@ -8,6 +8,7 @@ import { invariant } from "./errors.js";
 import {
   RouteContentWrapper,
   LoaderBoundary,
+  StreamedLoaderErrorBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
@@ -113,6 +114,9 @@ export interface RenderSegmentsOptions {
    */
   forceAwait?: boolean;
 
+  /** Seeded descendant client-route pending state for testing. */
+  outletPending?: boolean;
+
   /**
    * Intercept segments to inject into the tree.
    * These are parallel segments from intercept routes that need to be
@@ -231,6 +235,7 @@ export async function renderSegments(
     isAction,
     interceptSegments,
     forceAwait,
+    outletPending = false,
     rootLayout: RootLayout,
   } = options || {};
 
@@ -448,9 +453,30 @@ export async function renderSegments(
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
 
+    // Loader-bearing segments get the router-owned error boundary around
+    // their children so a read-site loader error renders its errorBoundary()
+    // fallback (LOADER_ERROR_FALLBACK marker on the thrown error) instead of
+    // escaping to app boundaries. Wrapped UNCONDITIONALLY on loader presence
+    // — streams and forceAwait lanes must produce the same tree shape or
+    // lane changes remount the subtree (docs/tree-structure.md).
+    if (loaderEntries.length > 0) {
+      nodeContent = createElement(StreamedLoaderErrorBoundary, {
+        children: nodeContent,
+      });
+    }
+
     if (loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      // SPIKE (streaming useLoader): per-loader streams for the boundary's
+      // readers. MUST come from the individual loader refs — splitting the
+      // aggregate client-side is wrong (Promise.all resolves at the slowest
+      // loader, erasing per-loader timing; measured 400ms data held to a
+      // 2000ms sibling). Zero-loader boundaries pass NO streams so the
+      // resolver keeps the fresh-promise resolve-above suspension — that
+      // microtask suspension is what makes SSR emit the loading() fallback
+      // for content-suspending routes (segment-loader-promise.ts).
+      let boundaryLoaderStreams: Record<string, unknown> | undefined;
       if (forceAwait || isAction) {
         const awaitStart = segDebug ? performance.now() : 0;
         boundaryLoaderData = await loaderDataPromise;
@@ -460,16 +486,23 @@ export async function renderSegments(
             ms: Math.round(performance.now() - awaitStart),
           });
         }
-      } else if (segDebug) {
-        segDebugLog(
-          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
-          { loaderIds },
-        );
+      } else if (loaderEntries.length > 0) {
+        boundaryLoaderStreams = {};
+        for (const l of loaderEntries) {
+          boundaryLoaderStreams[l.loaderId!] = l.loaderData;
+        }
+        if (segDebug) {
+          segDebugLog(
+            `segment ${id}: per-loader streams via LoaderBoundary (read-site suspense)`,
+            { loaderIds },
+          );
+        }
       }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
         loaderDataPromise: boundaryLoaderData,
         loaderIds,
+        loaderStreams: boundaryLoaderStreams,
         fallback: loading,
         outletKey: key,
         outletContent,
@@ -483,6 +516,7 @@ export async function renderSegments(
         content: outletContent,
         segment: node.segment,
         parallel: node.parallel,
+        pending: outletPending,
         children: nodeContent,
       });
     } else {
@@ -492,29 +526,50 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
-      // No loading() on this segment, so its loader data cannot stream behind
-      // a Suspense fallback — the tree build BLOCKS here until the data
-      // arrives. On the initial document this await runs before hydrateRoot.
-      const layoutAwaitStart = segDebug ? performance.now() : 0;
-      const resolvedData = await buildLoaderPromise(layoutLoaders);
-      if (segDebug) {
-        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
-          loaderIds: layoutLoaderIds,
-          ms: Math.round(performance.now() - layoutAwaitStart),
-        });
-      }
-      const decodeStart = segDebug ? performance.now() : 0;
-      const { loaderData, errorFallback } = decodeLoaderResults(
-        resolvedData,
-        layoutLoaderIds,
-      );
-      if (segDebug) {
-        const decodeMs = Math.round(performance.now() - decodeStart);
-        if (decodeMs > 0) {
-          segDebugLog(`segment ${id}: loader results decoded`, {
-            ms: decodeMs,
+      // SPIKE (streaming useLoader): a segment without loading() used to BLOCK
+      // the tree build here (await buildLoaderPromise) so its data was always
+      // resolved before render. Streaming lanes now skip the await and pass
+      // per-loader UNDECODED results (possibly pending promises) through
+      // OutletProvider.loaderStreams — useLoader suspends at the read site to
+      // the nearest CONSUMER Suspense boundary. forceAwait (popstate, stale
+      // revalidation, fully-prefetched) and action lanes keep the blocking
+      // await so those commits stay whole with no fallback flash.
+      let loaderData: Record<string, any> = {};
+      let errorFallback: ReactNode = null;
+      let loaderStreams: Record<string, unknown> | undefined;
+      if (forceAwait || isAction) {
+        const layoutAwaitStart = segDebug ? performance.now() : 0;
+        const resolvedData = await buildLoaderPromise(layoutLoaders);
+        if (segDebug) {
+          segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+            loaderIds: layoutLoaderIds,
+            ms: Math.round(performance.now() - layoutAwaitStart),
           });
         }
+        const decodeStart = segDebug ? performance.now() : 0;
+        ({ loaderData, errorFallback } = decodeLoaderResults(
+          resolvedData,
+          layoutLoaderIds,
+        ));
+        if (segDebug) {
+          const decodeMs = Math.round(performance.now() - decodeStart);
+          if (decodeMs > 0) {
+            segDebugLog(`segment ${id}: loader results decoded`, {
+              ms: decodeMs,
+            });
+          }
+        }
+      } else if (layoutLoaders.length > 0) {
+        loaderStreams = {};
+        for (const l of layoutLoaders) {
+          loaderStreams[l.loaderId!] = l.loaderData;
+        }
+        if (segDebug) {
+          segDebugLog(
+            `segment ${id}: layout loaders streaming to read sites (no loading())`,
+            { loaderIds: layoutLoaderIds },
+          );
+        }
       }
 
       if (parallelOwnedLoaders.length > 0) {
@@ -574,6 +629,8 @@ export async function renderSegments(
         segment: node.segment,
         parallel: node.parallel,
         loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
+        loaderStreams,
+        pending: outletPending,
         children: errorFallback ?? nodeContent,
       });
     }

package/src/server/context.ts

@@ -106,6 +106,16 @@ export type LoaderEntry = {
   revalidate: ShouldRevalidateFn<any, any>[];
   /** Cache config for this specific loader (loaders are NOT cached by default) */
   cache?: EntryCacheConfig;
+  /**
+   * Document renders await this loader before segment resolution returns
+   * (loader(Def, { stream: "navigation" })), so its data, handle pushes, and
+   * thrown notFound()/redirect() deterministically precede first flush.
+   * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
+   * per-isSSR (router/manifest.ts cache key), so the flag is already
+   * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+   * appears on navigation-lane entries.
+   */
+  awaitBeforeFlush?: true;
 };
 
 /**