@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2a0dea97

package/src/rsc/loader-fetch.ts

@@ -168,8 +168,19 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
-          const rscStream =
-            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
 
           return createResponseWithMergedHeaders(rscStream, {
             headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -199,7 +210,16 @@ export async function handleLoaderFetch<TEnv>(
         name: err.name,
       },
     };
-    const rscStream = ctx.renderToReadableStream(errorPayload);
+    const rscStream = ctx.renderToReadableStream(errorPayload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    });
 
     return createResponseWithMergedHeaders(rscStream, {
       status: 500,

package/src/rsc/manifest-init.ts

@@ -31,7 +31,11 @@ export async function buildRouterTrieFromUrlpatterns(
 ): Promise<void> {
   const { generateManifestFull } =
     await import("../build/generate-manifest.js");
-  const generated = generateManifestFull(router.urlpatterns);
+  const generated = generateManifestFull(
+    router.urlpatterns,
+    undefined,
+    router.basename ? { urlPrefix: router.basename } : undefined,
+  );
   if (
     generated._routeAncestry &&
     Object.keys(generated._routeAncestry).length > 0

package/src/rsc/progressive-enhancement.ts

@@ -243,6 +243,8 @@ export async function handleProgressiveEnhancement<TEnv>(
     const payload: RscPayload = {
       metadata: {
         pathname: url.pathname,
+        routerId: ctx.router.id,
+        basename: ctx.router.basename,
         segments: match.segments,
         matched: match.matched,
         diff: match.diff,
@@ -257,7 +259,11 @@ export async function handleProgressiveEnhancement<TEnv>(
       formState: actionResult,
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
     // metricsStore=undefined is safe: the handler already stashed the early
     // SSR setup promise on request variables, so getSSRSetup returns it
     // without falling back to a fresh startSSRSetup.
@@ -342,6 +348,8 @@ async function renderPeErrorBoundary<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
@@ -356,7 +364,11 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   // metricsStore=undefined is safe: the handler already stashed the early
   // SSR setup promise on request variables, so getSSRSetup returns it
   // without falling back to a fresh startSSRSetup.

package/src/rsc/rsc-rendering.ts

@@ -54,6 +54,8 @@ export async function handleRscRendering<TEnv>(
       payload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
+          basename: ctx.router.basename,
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
@@ -75,6 +77,7 @@ export async function handleRscRendering<TEnv>(
       payload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: result.segments,
           matched: result.matched,
           diff: result.diff,
@@ -83,6 +86,7 @@ export async function handleRscRendering<TEnv>(
           slots: result.slots,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
         },
       };
     }
@@ -135,6 +139,8 @@ export async function handleRscRendering<TEnv>(
 
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
+          basename: ctx.router.basename,
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
@@ -143,6 +149,7 @@ export async function handleRscRendering<TEnv>(
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },
@@ -166,7 +173,11 @@ export async function handleRscRendering<TEnv>(
 
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   const rscSerializeDur = performance.now() - rscSerializeStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
   appendMetric(

package/src/rsc/server-action.ts

@@ -208,6 +208,7 @@ export async function executeServerAction<TEnv>(
       const payload: RscPayload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: errorResult.segments,
           isPartial: true,
           matched: errorResult.matched,
@@ -225,6 +226,9 @@ export async function executeServerAction<TEnv>(
 
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
       });
 
       return createResponseWithMergedHeaders(rscStream, {
@@ -314,6 +318,7 @@ export async function revalidateAfterAction<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
       segments: matchResult.segments,
       isPartial: true,
       matched: matchResult.matched,
@@ -330,6 +335,9 @@ export async function revalidateAfterAction<TEnv>(
   const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
   });
   const rscSerializeDur = performance.now() - renderStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.

package/src/rsc/ssr-setup.ts

@@ -77,7 +77,7 @@ export function getSSRSetup<TEnv>(
   url: URL,
   metricsStore: MetricsStore | undefined,
 ): Promise<SSRSetup> {
-  const early = _getRequestContext()?.var?.[SSR_SETUP_VAR] as
+  const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
     | Promise<SSRSetup>
     | undefined;
   if (early) return early;
@@ -98,7 +98,7 @@ export function getSSRSetup<TEnv>(
  * the isRscRequest decision in rsc-rendering.ts.
  *
  * Note: response/mime routes are excluded by the caller — this function
- * runs after previewMatch() classifies the route type.
+ * runs after classifyRequest() determines the request mode.
  */
 export function mayNeedSSR(request: Request, url: URL): boolean {
   if (

package/src/rsc/types.ts

@@ -19,6 +19,9 @@ export interface RscPayload {
   metadata?: {
     pathname: string;
     segments: ResolvedSegment[];
+    /** Router instance ID. When this changes between navigations, the client
+     *  discards cached segments and does a full tree replacement (app switch). */
+    routerId?: string;
     isPartial?: boolean;
     isError?: boolean;
     matched?: string[];
@@ -38,6 +41,8 @@ export interface RscPayload {
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */
     initialTheme?: Theme;
+    /** URL prefix for all routes (from createRouter({ basename })). */
+    basename?: string;
     /** Whether connection warmup is enabled */
     warmupEnabled?: boolean;
     /** Server-side redirect with optional state (for partial requests) */
@@ -63,7 +68,10 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown },
+    options?: {
+      temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
+    },
   ) => ReadableStream<Uint8Array>;
 
   /**

package/src/segment-content-promise.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Return a stable Promise wrapping `component`, memoized on `segment`.
+ *
+ * A fresh `Promise.resolve(component)` each render would suspend for one
+ * microtask and briefly commit the loading fallback inside Suspender — the
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
+ * the first observation. `component` is separate from `segment.component`
+ * so action renders can feed in the awaited value.
+ *
+ * @internal
+ */
+export function getMemoizedContentPromise(
+  segment: ResolvedSegment,
+  component: ReactNode,
+): Promise<ReactNode> {
+  if (component instanceof Promise) {
+    return component as Promise<ReactNode>;
+  }
+  if (
+    segment.contentPromise !== undefined &&
+    segment.contentSource === component
+  ) {
+    return segment.contentPromise;
+  }
+  const promise = Promise.resolve(component);
+  segment.contentPromise = promise;
+  segment.contentSource = component;
+  return promise;
+}

package/src/segment-system.tsx

@@ -2,11 +2,7 @@ import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import type {
-  ResolvedSegment,
-  LoaderDataResult,
-  RootLayoutProps,
-} from "./types.js";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { isLoaderDataResult } from "./types.js";
 import { invariant } from "./errors.js";
 import {
@@ -14,12 +10,103 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
+function restoreParallelLoaderMarkers(
+  segments: ResolvedSegment[],
+): ResolvedSegment[] {
+  const parallelLoadingByNamespace = new Map<string, ReactNode>();
+  let nextSegments: ResolvedSegment[] | null = null;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+
+    if (segment.type === "parallel") {
+      if (
+        segment.namespace &&
+        segment.loading !== undefined &&
+        segment.loading !== null &&
+        segment.loading !== false
+      ) {
+        parallelLoadingByNamespace.set(segment.namespace, segment.loading);
+      }
+      continue;
+    }
+
+    if (segment.type !== "loader" || segment.parallelLoading !== undefined) {
+      continue;
+    }
+
+    const parallelLoading = segment.namespace
+      ? parallelLoadingByNamespace.get(segment.namespace)
+      : undefined;
+    if (parallelLoading === undefined) {
+      continue;
+    }
+
+    if (!nextSegments) {
+      nextSegments = segments.slice();
+    }
+    nextSegments[i] = { ...segment, parallelLoading };
+  }
+
+  return nextSegments ?? segments;
+}
+
+function hasSameReferences(a: unknown[] | undefined, b: unknown[]): boolean {
+  if (!a || a.length !== b.length) {
+    return false;
+  }
+
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Memoize an aggregate Promise.all for a segment's owned loaders on the
+ * segment itself. Reusing the same aggregate across renders — invalidated
+ * only when an underlying loader.loaderData ref changes — keeps React's
+ * use() in "known fulfilled" state and prevents a fresh Promise.all from
+ * suspending (and briefly committing the Suspense fallback) on every
+ * partial update that doesn't actually change loader data.
+ */
+function memoizeLoaderPromise(
+  target: ResolvedSegment,
+  loaders: ResolvedSegment[],
+  sourcesKey: "layoutLoaderSources" | "parallelLoaderSources",
+): Promise<any[]> | any[] {
+  const sources = loaders.map((loader) => loader.loaderData);
+  if (
+    target.loaderDataPromise !== undefined &&
+    hasSameReferences(target[sourcesKey], sources)
+  ) {
+    return target.loaderDataPromise;
+  }
+  const promise: Promise<any[]> | any[] =
+    loaders.length > 0
+      ? Promise.all(
+          loaders.map((loader) =>
+            loader.loaderData instanceof Promise
+              ? loader.loaderData
+              : Promise.resolve(loader.loaderData),
+          ),
+        )
+      : Promise.resolve([]);
+  target.loaderDataPromise = promise;
+  target[sourcesKey] = sources;
+  return promise;
+}
+
 /**
  * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
  */
@@ -143,6 +230,10 @@ export async function renderSegments(
   } = options || {};
 
   const temporalLazyRefs: Promise<any>[] = [];
+  const normalizedSegments = restoreParallelLoaderMarkers(segments);
+  const normalizedInterceptSegments = interceptSegments
+    ? restoreParallelLoaderMarkers(interceptSegments)
+    : undefined;
 
   /**
    * Registers promises from lazy/async components for awaiting.
@@ -167,7 +258,7 @@ export async function renderSegments(
     );
   }
   // Separate segments by type, passing intercept segments for explicit injection
-  const tree = segmentTreeWalk(segments, interceptSegments);
+  const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
   // Render content segments as siblings
   let content: ReactNode = null;
   for (const node of tree) {
@@ -219,10 +310,7 @@ export async function renderSegments(
       loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
-            content:
-              resolvedComponent instanceof Promise
-                ? resolvedComponent
-                : Promise.resolve(resolvedComponent),
+            content: getMemoizedContentPromise(node.segment, resolvedComponent),
             fallback: loading,
             segmentId: id,
           })
@@ -246,16 +334,11 @@ export async function renderSegments(
 
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise =
-      loaderEntries.length > 0
-        ? Promise.all(
-            loaderEntries.map((loader) =>
-              loader.loaderData instanceof Promise
-                ? loader.loaderData
-                : Promise.resolve(loader.loaderData),
-            ),
-          )
-        : Promise.resolve([]);
+    const loaderDataPromise = memoizeLoaderPromise(
+      node.segment,
+      loaderEntries,
+      "layoutLoaderSources",
+    );
 
     // Use LoaderBoundary when loading is defined to maintain consistent tree structure
     // This ensures cached segments (which may not have loader segments) have the same
@@ -284,13 +367,71 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton - await loaders and render directly
-      const resolvedData = await loaderDataPromise;
+      // Has loaders but no loading skeleton.
+      // Split: parallel-owned loaders stream (their parallel has loading()),
+      // layout-owned loaders are awaited (they gate the layout content).
+      const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
+      const parallelOwnedLoaders = loaderEntries.filter(
+        (l) => !!l.parallelLoading,
+      );
+
+      // Await only layout-owned loaders
+      const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      const layoutLoaderDataPromise =
+        layoutLoaders.length > 0
+          ? Promise.all(
+              layoutLoaders.map((l) =>
+                l.loaderData instanceof Promise
+                  ? l.loaderData
+                  : Promise.resolve(l.loaderData),
+              ),
+            )
+          : Promise.resolve([]);
+      const resolvedData = await layoutLoaderDataPromise;
       const { loaderData, errorFallback } = resolveLoaderData(
         resolvedData,
-        loaderIds,
+        layoutLoaderIds,
       );
 
+      // Parallel-owned loaders: attach to their owning parallel segment
+      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
+      if (parallelOwnedLoaders.length > 0) {
+        const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
+
+        for (const loader of parallelOwnedLoaders) {
+          if (!loader.namespace) {
+            continue;
+          }
+          const existing = loadersByParallelNamespace.get(loader.namespace);
+          if (existing) {
+            existing.push(loader);
+          } else {
+            loadersByParallelNamespace.set(loader.namespace, [loader]);
+          }
+        }
+
+        for (const p of node.parallel) {
+          if (!p.loading || !p.namespace) {
+            continue;
+          }
+
+          const ownedLoaders = loadersByParallelNamespace.get(p.namespace);
+          if (!ownedLoaders || ownedLoaders.length === 0) {
+            continue;
+          }
+
+          p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const aggregated = memoizeLoaderPromise(
+            p,
+            ownedLoaders,
+            "parallelLoaderSources",
+          );
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            p.loaderDataPromise = await aggregated;
+          }
+        }
+      }
+
       content = createElement(OutletProvider, {
         key,
         content: outletContent,