@rangojs/router 0.0.0-experimental.d5d3070a → 0.0.0-experimental.d68257e5

package/src/segment-system.tsx

@@ -8,14 +8,38 @@ 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";
 import { getMemoizedContentPromise } from "./segment-content-promise.js";
 import {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
 
+/**
+ * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
+ * sides now, environment-tagged: `[Browser][segments]` lines up with the
+ * `[Browser][boot]` sequence around hydrateRoot; `[Server][segments]` exposes
+ * the SSR/RSC tree-build stalls (blocking loader awaits during fizz are what
+ * dominate MISS TTFB) that used to be invisible because the logs were
+ * window-gated. Server lines have no request correlation — segment-system is
+ * shared client code and cannot import request-context (node:async_hooks
+ * would enter the browser bundle) — so on a busy server, correlate by
+ * timestamp + segment ids.
+ */
+function segDebugLog(msg: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const env = typeof window === "object" ? "[Browser]" : "[Server]";
+  const prefix = `${env}[segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}
+
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
@@ -90,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
@@ -208,9 +235,21 @@ export async function renderSegments(
     isAction,
     interceptSegments,
     forceAwait,
+    outletPending = false,
     rootLayout: RootLayout,
   } = options || {};
 
+  const segDebug = INTERNAL_RANGO_DEBUG;
+  const segDebugStart = segDebug ? performance.now() : 0;
+  if (segDebug) {
+    segDebugLog("renderSegments start", {
+      segments: segments.map((s) => `${s.id}:${s.type}`),
+      isAction: !!isAction,
+      forceAwait: !!forceAwait,
+      intercepts: interceptSegments?.length ?? 0,
+    });
+  }
+
   const temporalLazyRefs: Promise<any>[] = [];
   const normalizedSegments = restoreParallelLoaderMarkers(segments);
   const normalizedInterceptSegments = interceptSegments
@@ -271,6 +310,7 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
+    const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
@@ -313,17 +353,63 @@ export async function renderSegments(
 
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
+      const componentAwaitStart = segDebug ? performance.now() : 0;
       resolvedComponent = await component;
+      if (segDebug) {
+        segDebugLog(`segment ${id}: component awaited (action)`, {
+          ms: Math.round(performance.now() - componentAwaitStart),
+        });
+      }
     }
 
-    let nodeContent: ReactNode = isRenderableLoading(loading)
-      ? createElement(RouteContentWrapper, {
-          key: `suspense-loading-${id}`,
-          content: getMemoizedContentPromise(resolvedComponent),
-          fallback: loading,
-          segmentId: id,
-        })
-      : registerLazyRef(resolvedComponent);
+    let nodeContent: ReactNode = null;
+    if (isRenderableLoading(loading)) {
+      // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
+      // loading() route with the route content ALREADY resolved, so its
+      // RouteContentWrapper Suspender does not suspend for a microtask and flash
+      // the loading() fallback on a NORMAL (non-transition) commit. The router
+      // data is known-ready on these paths, so awaiting the content here is free.
+      // The wrapper tree is unchanged (RouteContentWrapper is still created with
+      // the same key/fallback) — only the `content` prop is a resolved node
+      // instead of a pending promise, which Suspender renders synchronously. This
+      // mirrors the forceAwait loaderData unwrap above; a CLIENT component that
+      // suspends on mount inside the content still reveals a fallback (it is not
+      // pre-resolved).
+      const contentPromise = getMemoizedContentPromise(resolvedComponent);
+      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      if (forceAwait) {
+        const contentAwaitStart = segDebug ? performance.now() : 0;
+        loadingContent = await contentPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
+            ms: Math.round(performance.now() - contentAwaitStart),
+          });
+        }
+      }
+      nodeContent = createElement(RouteContentWrapper, {
+        key: `suspense-loading-${id}`,
+        content: loadingContent,
+        fallback: loading,
+        segmentId: id,
+      });
+    } else {
+      // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. A segment in the no-loading()
+      // branch whose component decodes as a Promise/lazy gets registered into
+      // temporalLazyRefs and awaited before commit (see below) — which on builds
+      // where the segment component arrives deferred defeats client-nav streaming.
+      if (INTERNAL_RANGO_DEBUG && typeof window === "object") {
+        const c = resolvedComponent as unknown;
+        console.log("[VT-DIAG] renderSegments no-loading-branch segment", {
+          id,
+          type: node.segment.type,
+          componentIsPromise: c instanceof Promise,
+          componentIsLazy:
+            c != null && typeof c === "object" && "_payload" in c,
+          componentTypeof: typeof c,
+        });
+      }
+      nodeContent = registerLazyRef(resolvedComponent);
+    }
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
@@ -367,13 +453,69 @@ 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;
+      let boundaryAwaitedLoaderIds: string[] | undefined;
+      if (forceAwait || isAction) {
+        const awaitStart = segDebug ? performance.now() : 0;
+        boundaryLoaderData = await loaderDataPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
+            loaderIds,
+            ms: Math.round(performance.now() - awaitStart),
+          });
+        }
+      } else if (loaderEntries.length > 0) {
+        boundaryLoaderStreams = {};
+        for (const l of loaderEntries) {
+          // { 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).
+          boundaryLoaderStreams[l.loaderId!] = l.awaitBeforeFlush
+            ? await l.loaderData
+            : l.loaderData;
+          if (l.awaitBeforeFlush) {
+            (boundaryAwaitedLoaderIds ??= []).push(l.loaderId!);
+          }
+        }
+        if (segDebug) {
+          segDebugLog(
+            `segment ${id}: per-loader streams via LoaderBoundary (read-site suspense)`,
+            { loaderIds },
+          );
+        }
+      }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
-        loaderDataPromise:
-          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderDataPromise: boundaryLoaderData,
         loaderIds,
+        loaderStreams: boundaryLoaderStreams,
+        awaitedLoaderIds: boundaryAwaitedLoaderIds,
         fallback: loading,
         outletKey: key,
         outletContent,
@@ -387,6 +529,7 @@ export async function renderSegments(
         content: outletContent,
         segment: node.segment,
         parallel: node.parallel,
+        pending: outletPending,
         children: nodeContent,
       });
     } else {
@@ -396,11 +539,59 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
-      const resolvedData = await buildLoaderPromise(layoutLoaders);
-      const { loaderData, errorFallback } = decodeLoaderResults(
-        resolvedData,
-        layoutLoaderIds,
-      );
+      // 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;
+      let awaitedLoaderIds: string[] | 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) {
+          // Same settled-value delivery for { ssr: false } as the
+          // LoaderBoundary branch above — see that comment.
+          loaderStreams[l.loaderId!] = l.awaitBeforeFlush
+            ? await l.loaderData
+            : l.loaderData;
+          if (l.awaitBeforeFlush) {
+            (awaitedLoaderIds ??= []).push(l.loaderId!);
+          }
+        }
+        if (segDebug) {
+          segDebugLog(
+            `segment ${id}: layout loaders streaming to read sites (no loading())`,
+            { loaderIds: layoutLoaderIds },
+          );
+        }
+      }
 
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
@@ -429,10 +620,27 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          p.loaderDataPromise =
-            (forceAwait || isAction) && aggregated instanceof Promise
-              ? await aggregated
-              : aggregated;
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            const parallelAwaitStart = segDebug ? performance.now() : 0;
+            p.loaderDataPromise = await aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                {
+                  loaderIds: p.loaderIds,
+                  ms: Math.round(performance.now() - parallelAwaitStart),
+                },
+              );
+            }
+          } else {
+            p.loaderDataPromise = aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                { loaderIds: p.loaderIds },
+              );
+            }
+          }
         }
       }
 
@@ -442,6 +650,9 @@ export async function renderSegments(
         segment: node.segment,
         parallel: node.parallel,
         loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
+        loaderStreams,
+        awaitedLoaderIds,
+        pending: outletPending,
         children: errorFallback ?? nodeContent,
       });
     }
@@ -456,13 +667,40 @@ export async function renderSegments(
         children: content,
       });
     }
+
+    if (segDebug) {
+      segDebugLog(`segment ${id} built`, {
+        type: node.segment.type,
+        ms: Math.round(performance.now() - segNodeStart),
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
   }
 
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {
     children: content,
   });
   if (typeof window === "object") {
+    // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. If this await dominates the
+    // navigation time, a deferred/lazy segment component is being fully resolved
+    // before commit, which defeats client-nav streaming. The await itself is
+    // functional (it preloads lazy chunk refs); only the timing log is gated.
+    const vtDebug = INTERNAL_RANGO_DEBUG && temporalLazyRefs.length > 0;
+    const vtDebugStart = vtDebug ? performance.now() : 0;
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments awaiting temporalLazyRefs", {
+        count: temporalLazyRefs.length,
+      });
+    }
     await Promise.allSettled(temporalLazyRefs);
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments temporalLazyRefs settled", {
+        count: temporalLazyRefs.length,
+        ms: Math.round(performance.now() - vtDebugStart),
+      });
+    }
   }
 
   let result: ReactNode = errorBoundaryWrapped;
@@ -473,6 +711,12 @@ export async function renderSegments(
     });
   }
 
+  if (segDebug) {
+    segDebugLog("renderSegments complete", {
+      ms: Math.round(performance.now() - segDebugStart),
+    });
+  }
+
   return result;
 }