@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.eb0645d3

package/src/rsc/helpers.ts

@@ -8,9 +8,49 @@ import {
   _getRequestContext,
   getLocationState,
 } from "../server/request-context.js";
+import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 
+/**
+ * Copy stub headers from the request context onto a target Headers instance:
+ * append Set-Cookie entries, set everything else only if absent. Header
+ * mutation failures are swallowed so the same logic works against Response
+ * headers that may be immutable (e.g. Cloudflare protocol-switch responses).
+ */
+function applyStubHeaders(target: Headers, stub: Headers): void {
+  stub.forEach((value, name) => {
+    try {
+      if (name.toLowerCase() === "set-cookie") {
+        target.append(name, value);
+      } else if (!target.has(name)) {
+        target.set(name, value);
+      }
+    } catch {
+      // Headers immutable — skip.
+    }
+  });
+}
+
+/**
+ * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
+ * iteration prevents re-entrant registrations from double-firing and matches
+ * the contract that each callback runs at most once per request.
+ */
+function drainOnResponseCallbacks(
+  ctx: RequestContext,
+  response: Response,
+): Response {
+  const callbacks = ctx._onResponseCallbacks;
+  if (callbacks.length === 0) return response;
+  ctx._onResponseCallbacks = [];
+  let result = response;
+  for (const callback of callbacks) {
+    result = callback(result) ?? result;
+  }
+  return result;
+}
+
 /**
  * Check if a request body has content to decode
  */
@@ -39,40 +79,23 @@ export function createResponseWithMergedHeaders(
     return new Response(body, init);
   }
 
-  // Merge headers from stub response into the new response.
-  // Delete Set-Cookie from the stub after consuming so that downstream
-  // merge points (e.g. executeMiddleware) do not duplicate them.
+  // Delete Set-Cookie from the stub after consuming so downstream merge
+  // points (e.g. executeMiddleware) don't duplicate them.
   const mergedHeaders = new Headers(init.headers);
-  ctx.res.headers.forEach((value, name) => {
-    if (name.toLowerCase() === "set-cookie") {
-      mergedHeaders.append(name, value);
-    } else if (!mergedHeaders.has(name)) {
-      // Only set if not already present in init.headers
-      mergedHeaders.set(name, value);
-    }
-  });
+  applyStubHeaders(mergedHeaders, ctx.res.headers);
   ctx.res.headers.delete("set-cookie");
 
-  // Use ctx.res.status if it was set (e.g., 404 for notFound, 500 for error)
-  // Otherwise use the status from init
+  // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
+  // notFound, 500 for error). Default ctx.res.status is 200.
   const status = ctx.res.status !== 200 ? ctx.res.status : init.status;
 
-  let response = new Response(body, {
+  const response = new Response(body, {
     ...init,
     status,
     headers: mergedHeaders,
   });
 
-  // Run onResponse callbacks - each can inspect/modify the response.
-  // Drain the array so that downstream callers (e.g. finalizeResponse)
-  // do not re-execute the same callbacks on this response.
-  const callbacks = ctx._onResponseCallbacks;
-  ctx._onResponseCallbacks = [];
-  for (const callback of callbacks) {
-    response = callback(response) ?? response;
-  }
-
-  return response;
+  return drainOnResponseCallbacks(ctx, response);
 }
 
 /**
@@ -175,24 +198,29 @@ export function buildRouteMiddlewareEntries<TEnv>(
 }
 
 /**
- * Run onResponse callbacks on an existing Response.
- *
- * Used for code paths that bypass createResponseWithMergedHeaders(), such as
- * middleware short-circuits where the Response is already constructed but
- * ctx.onResponse() callbacks still need to fire.
+ * Merge stub headers from the request context onto an existing Response in
+ * place, then drain onResponse callbacks. Used when a Response cannot flow
+ * through `new Response()` — status 101 is outside the constructor's
+ * 200-599 range, and the Cloudflare-specific `webSocket` property would be
+ * lost on reconstruction.
  */
-export function finalizeResponse(response: Response): Response {
+export function mergeStubHeadersAndFinalize(response: Response): Response {
   const ctx = _getRequestContext();
-  if (!ctx || ctx._onResponseCallbacks.length === 0) {
-    return response;
-  }
+  if (!ctx) return response;
 
-  // Drain the array so callbacks run at most once per request.
-  const callbacks = ctx._onResponseCallbacks;
-  ctx._onResponseCallbacks = [];
-  let result = response;
-  for (const callback of callbacks) {
-    result = callback(result) ?? result;
-  }
-  return result;
+  applyStubHeaders(response.headers, ctx.res.headers);
+  ctx.res.headers.delete("set-cookie");
+
+  return drainOnResponseCallbacks(ctx, response);
+}
+
+/**
+ * Run onResponse callbacks on an existing Response. Used by code paths that
+ * bypass createResponseWithMergedHeaders (e.g. middleware short-circuits)
+ * but still need ctx.onResponse() callbacks to fire.
+ */
+export function finalizeResponse(response: Response): Response {
+  const ctx = _getRequestContext();
+  if (!ctx) return response;
+  return drainOnResponseCallbacks(ctx, response);
 }

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,9 +243,12 @@ 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,
+        params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
@@ -257,7 +260,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,9 +349,12 @@ 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,
+      params: errorResult.params,
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,
@@ -356,7 +366,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/response-route-handler.ts

@@ -26,7 +26,9 @@ import {
   finalizeResponse,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
+  mergeStubHeadersAndFinalize,
 } from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -96,6 +98,12 @@ export async function handleResponseRoute<TEnv>(
     // so that stub headers (cookies, custom headers set via ctx.header()) are included.
     // Use Headers (not Record<string, string>) to preserve duplicate entries like Set-Cookie.
     const rewrapResponse = (result: Response) => {
+      // 204/205/304 are NOT short-circuited — they're valid for the Response
+      // constructor and must honor ctx.setStatus() overrides. Only upgrade
+      // responses (status 101 / `webSocket` property) bypass reconstruction.
+      if (isWebSocketUpgradeResponse(result)) {
+        return mergeStubHeadersAndFinalize(result);
+      }
       const headers = new Headers();
       result.headers.forEach((value, key) => {
         if (key.toLowerCase() === "set-cookie") {
@@ -196,7 +204,9 @@ export async function handleResponseRoute<TEnv>(
   // Wrap callHandler to append Vary: Accept on content-negotiated responses
   const callHandlerWithVary = async () => {
     const response = await callHandler();
-    if (preview.negotiated) {
+    if (preview.negotiated && !isWebSocketUpgradeResponse(response)) {
+      // Skip Vary on upgrade responses: headers are semantically immutable
+      // on some runtimes, and Vary is meaningless for a 101 response.
       response.headers.append("Vary", "Accept");
     }
     return response;

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,
@@ -136,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,
@@ -168,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(
@@ -195,6 +204,13 @@ export async function handleRscRendering<TEnv>(
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
     };
+    // Tell the client's prefetch cache to scope this response to its source
+    // URL (instead of the default source-agnostic wildcard). Intercept
+    // responses depend on the source page matching an intercept rule, so
+    // they must not be reused for navigations from other sources.
+    if (hasInterceptSlots) {
+      rscHeaders["x-rsc-prefetch-scope"] = "source";
+    }
     // Enable browser HTTP caching for prefetch responses only.
     // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
     // non-intercept context (intercept responses depend on source page),

package/src/rsc/server-action.ts

@@ -208,10 +208,12 @@ export async function executeServerAction<TEnv>(
       const payload: RscPayload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: errorResult.segments,
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
           version: ctx.version,
@@ -225,6 +227,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,10 +319,12 @@ export async function revalidateAfterAction<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
       segments: matchResult.segments,
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,
@@ -330,6 +337,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,67 @@
+import type { ReactNode } from "react";
+
+/**
+ * Stable Promise wrappers keyed on the component itself. Objects (React
+ * elements, functions, lazy payloads) land in a WeakMap so entries GC when
+ * the underlying component is released; primitives (string, number, boolean,
+ * null) land in a Map so memoization still applies to text-/null-backed
+ * segments like those in partial-update flows. Keeping this cache outside
+ * the segment eliminates preservation fields on ResolvedSegment — it survives
+ * reconciliation naturally because the component ref is what's stable.
+ *
+ * Browser-only. On the server each SSR render needs a fresh pending promise
+ * so Suspense can emit the loading fallback HTML before content streams. A
+ * shared already-resolved promise has `.status === "fulfilled"` attached by
+ * React on its first observation — subsequent `use()` calls return
+ * synchronously without suspending, so the Suspense fallback never makes it
+ * into the initial HTML. Route-definition components share refs across
+ * requests, so a global cache would leak tracked state between renders.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+const objectContentCache = IS_BROWSER
+  ? new WeakMap<object, Promise<ReactNode>>()
+  : null;
+const primitiveContentCache = IS_BROWSER
+  ? new Map<unknown, Promise<ReactNode>>()
+  : null;
+
+/**
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
+ *
+ * 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.
+ *
+ * @internal
+ */
+export function getMemoizedContentPromise(
+  component: ReactNode,
+): Promise<ReactNode> {
+  if (component instanceof Promise) {
+    return component as Promise<ReactNode>;
+  }
+
+  if (!objectContentCache || !primitiveContentCache) {
+    return Promise.resolve(component);
+  }
+
+  if (component !== null && typeof component === "object") {
+    const cached = objectContentCache.get(component);
+    if (cached) {
+      return cached;
+    }
+    const promise = Promise.resolve(component);
+    objectContentCache.set(component, promise);
+    return promise;
+  }
+
+  const cached = primitiveContentCache.get(component);
+  if (cached) {
+    return cached;
+  }
+  const promise = Promise.resolve(component);
+  primitiveContentCache.set(component, promise);
+  return promise;
+}

package/src/segment-loader-promise.ts

@@ -0,0 +1,122 @@
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Cache of aggregate Promise.all results keyed on the first loader's
+ * `loaderData` reference. Each entry holds the source refs it was built from
+ * plus the resulting Promise/array; lookup scans entries for the matching
+ * source array (typically a single entry, since distinct loader groups rarely
+ * share a first source). Object first-refs live in a WeakMap (auto-GC);
+ * primitive first-refs (strings/numbers/booleans/null) live in a Map so
+ * loaders that resolve to primitive data are memoized too — bounded in
+ * practice by the application's loader set.
+ *
+ * Keying externally means reconciliation's fresh segment objects no longer
+ * drop memoization — the cache survives as long as the underlying loader
+ * segments do, and GC collects entries when those loaders are released
+ * (object keys only).
+ *
+ * Browser-only. On the server each SSR render needs a fresh Promise so
+ * Suspense can actually suspend and emit the loading fallback HTML before
+ * content streams. A shared already-resolved promise has `.status` attached
+ * by React on first `use()`; subsequent observations return synchronously
+ * and skip the fallback. The zero-loader case is especially prone because
+ * every empty-loader site would otherwise share one promise across requests.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+
+interface LoaderCacheEntry {
+  sources: any[];
+  promise: Promise<any[]> | any[];
+}
+
+const objectLoaderCache = IS_BROWSER
+  ? new WeakMap<object, LoaderCacheEntry[]>()
+  : null;
+const primitiveLoaderCache = IS_BROWSER
+  ? new Map<unknown, LoaderCacheEntry[]>()
+  : null;
+
+// In the browser, a single shared empty aggregate is safe (and desirable) —
+// reusing the same resolved promise keeps React's `use()` in a known-fulfilled
+// state across renders. On the server it would leak `.status = "fulfilled"`
+// across requests and skip the Suspense fallback, so we rebuild on each call.
+const SHARED_EMPTY_LOADER_PROMISE: Promise<any[]> | null = IS_BROWSER
+  ? Promise.resolve([])
+  : null;
+
+function hasSameReferences(a: any[], b: any[]): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
+  if (loaders.length === 0) {
+    return Promise.resolve([]);
+  }
+  return Promise.all(
+    loaders.map((loader) =>
+      loader.loaderData instanceof Promise
+        ? loader.loaderData
+        : Promise.resolve(loader.loaderData),
+    ),
+  );
+}
+
+function isObjectLike(value: unknown): value is object {
+  return (
+    value !== null && (typeof value === "object" || typeof value === "function")
+  );
+}
+
+/**
+ * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
+ * same aggregate across renders — invalidated only when any 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.
+ *
+ * @internal
+ */
+export function getMemoizedLoaderPromise(
+  loaders: ResolvedSegment[],
+): Promise<any[]> | any[] {
+  if (loaders.length === 0) {
+    return SHARED_EMPTY_LOADER_PROMISE ?? buildLoaderPromise(loaders);
+  }
+  if (!objectLoaderCache || !primitiveLoaderCache) {
+    return buildLoaderPromise(loaders);
+  }
+
+  const sources = loaders.map((loader) => loader.loaderData);
+  const first = sources[0];
+  const entries = isObjectLike(first)
+    ? objectLoaderCache.get(first)
+    : primitiveLoaderCache.get(first);
+
+  if (entries) {
+    for (const entry of entries) {
+      if (hasSameReferences(entry.sources, sources)) {
+        return entry.promise;
+      }
+    }
+  }
+
+  const promise = buildLoaderPromise(loaders);
+  const newEntry: LoaderCacheEntry = { sources, promise };
+  if (entries) {
+    entries.push(newEntry);
+  } else if (isObjectLike(first)) {
+    objectLoaderCache.set(first, [newEntry]);
+  } else {
+    primitiveLoaderCache.set(first, [newEntry]);
+  }
+  return promise;
+}