@rangojs/router 0.0.0-experimental.dfa55db4 → 0.0.0-experimental.e16b7c00

package/src/rsc/progressive-enhancement.ts

@@ -248,6 +248,8 @@ export async function handleProgressiveEnhancement<TEnv>(
         segments: match.segments,
         matched: match.matched,
         diff: match.diff,
+        resolvedIds: match.resolvedIds,
+        params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
@@ -353,6 +355,8 @@ async function renderPeErrorBoundary<TEnv>(
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
+      resolvedIds: errorResult.resolvedIds,
+      params: errorResult.params,
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,

package/src/rsc/response-route-handler.ts

@@ -11,7 +11,8 @@ import { requireRequestContext } from "../server/request-context.js";
 import { contextGet } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { traverseBack } from "../router/pattern-matching.js";
-import { createCacheScope } from "../cache/cache-scope.js";
+import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
+import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
   createReverseFunction,
@@ -26,7 +27,9 @@ import {
   finalizeResponse,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
+  mergeStubHeadersAndFinalize,
 } from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -78,10 +81,13 @@ export async function handleResponseRoute<TEnv>(
     env,
     searchParams: cleanUrl.searchParams,
     url: cleanUrl,
+    originalUrl: reqCtx.originalUrl,
     pathname: url.pathname,
     reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     header: (name: string, value: string) => reqCtx.header(name, value),
+    waitUntil: reqCtx.waitUntil.bind(reqCtx),
+    executionContext: reqCtx.executionContext,
     _responseType: preview.responseType,
   };
   // Brand with taint symbol so "use cache" detects it as request-scoped
@@ -96,6 +102,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") {
@@ -110,13 +122,15 @@ export async function handleResponseRoute<TEnv>(
       });
     };
 
-    // JSON response routes: wrap in { data } / { error } envelope
-    if (preview.responseType === "json") {
-      try {
-        const result = await (preview.handler as Function)(responseHandlerCtx);
-        if (result instanceof Response) {
-          return rewrapResponse(result);
-        }
+    try {
+      const result = await (preview.handler as Function)(responseHandlerCtx);
+
+      if (result instanceof Response) {
+        return rewrapResponse(result);
+      }
+
+      // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
+      if (preview.responseType === "json") {
         return createResponseWithMergedHeaders(
           JSON.stringify({ data: result }),
           {
@@ -124,10 +138,28 @@ export async function handleResponseRoute<TEnv>(
             headers: { "content-type": "application/json;charset=utf-8" },
           },
         );
-      } catch (error) {
-        handlerCtx.callOnError(error, "handler", errorCtx);
-        const isDev = process.env.NODE_ENV !== "production";
-        const status = error instanceof RouterError ? error.status : 500;
+      }
+
+      // Object.hasOwn (not truthiness) so prototype names like "toString" are not
+      // matched; image/stream/any are absent and fall through to the throw.
+      if (Object.hasOwn(RESPONSE_TYPE_MIME, preview.responseType)) {
+        return createResponseWithMergedHeaders(String(result), {
+          status: 200,
+          headers: {
+            "content-type": `${RESPONSE_TYPE_MIME[preview.responseType]};charset=utf-8`,
+          },
+        });
+      }
+
+      throw new Error(
+        `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
+      );
+    } catch (error) {
+      handlerCtx.callOnError(error, "handler", errorCtx);
+      const isDev = process.env.NODE_ENV !== "production";
+      const status = error instanceof RouterError ? error.status : 500;
+
+      if (preview.responseType === "json") {
         return createResponseWithMergedHeaders(
           JSON.stringify({
             error: createResponseErrorPayload(error, isDev),
@@ -138,48 +170,7 @@ export async function handleResponseRoute<TEnv>(
           },
         );
       }
-    }
-
-    // Non-JSON response routes: catch errors and return plain Response
-    try {
-      const result = await (preview.handler as Function)(responseHandlerCtx);
-
-      if (result instanceof Response) {
-        return rewrapResponse(result);
-      }
 
-      // Auto-wrap based on response type tag
-      switch (preview.responseType) {
-        case "text":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "text/plain;charset=utf-8" },
-          });
-        case "html":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "text/html;charset=utf-8" },
-          });
-        case "xml":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "application/xml;charset=utf-8" },
-          });
-        case "md":
-          return createResponseWithMergedHeaders(String(result), {
-            status: 200,
-            headers: { "content-type": "text/markdown;charset=utf-8" },
-          });
-        default:
-          // image, stream, any -- must return Response
-          throw new Error(
-            `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
-          );
-      }
-    } catch (error) {
-      handlerCtx.callOnError(error, "handler", errorCtx);
-      const isDev = process.env.NODE_ENV !== "production";
-      const status = error instanceof RouterError ? error.status : 500;
       const message =
         error instanceof RouterError
           ? error.message
@@ -196,7 +187,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;
@@ -262,6 +255,11 @@ export async function handleResponseRoute<TEnv>(
           }
         }
 
+        // Resolve cache tags for this document entry (static or dynamic),
+        // while request context is available. Passed to putResponse so the
+        // entry is tag-invalidatable.
+        const responseTags = resolveCacheTags(cacheScope.config, reqCtx);
+
         // Save pre-handler callbacks (registered by app-level middleware
         // before we reach the cache block) and clear the live array.
         // createResponseWithMergedHeaders (inside the handler) eagerly
@@ -303,6 +301,7 @@ export async function handleResponseRoute<TEnv>(
                     fresh.clone(),
                     cacheScope!.ttl,
                     cacheScope!.swr,
+                    responseTags,
                   );
                 }
               } catch (error) {
@@ -331,6 +330,7 @@ export async function handleResponseRoute<TEnv>(
                 response.clone(),
                 cacheScope!.ttl,
                 cacheScope!.swr,
+                responseTags,
               );
             } catch (error) {
               console.error(`[ResponseCache] Cache write failed:`, error);

package/src/rsc/rsc-rendering.ts

@@ -13,8 +13,9 @@ import {
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { appendMetric } from "../router/metrics.js";
-import { getSSRSetup } from "./ssr-setup.js";
+import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
+import type { MatchResult } from "../types.js";
 import {
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
@@ -35,6 +36,28 @@ export async function handleRscRendering<TEnv>(
   let payload: RscPayload;
   let hasInterceptSlots = false;
 
+  // Shared by the partial-fallback and full-render paths. The partial-success
+  // payload below is intentionally different (omits rootLayout/theme, adds slots).
+  const buildFullPayload = (m: MatchResult): RscPayload => ({
+    metadata: {
+      pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: m.segments,
+      matched: m.matched,
+      diff: m.diff,
+      resolvedIds: m.resolvedIds,
+      params: m.params,
+      isPartial: false,
+      rootLayout: ctx.router.rootLayout,
+      handles: handleStore.stream(),
+      version: ctx.version,
+      prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      themeConfig: ctx.router.themeConfig,
+      initialTheme: reqCtx.theme,
+    },
+  });
+
   if (isPartial) {
     // Partial render (navigation)
     const result = await ctx.router.matchPartial(request, { env });
@@ -51,24 +74,7 @@ export async function handleRscRendering<TEnv>(
         return createSimpleRedirectResponse(match.redirect);
       }
 
-      payload = {
-        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(),
-          version: ctx.version,
-          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
-          themeConfig: ctx.router.themeConfig,
-          initialTheme: reqCtx.theme,
-        },
-      };
+      payload = buildFullPayload(match);
     } else {
       setRequestContextParams(result.params, result.routeName);
 
@@ -81,6 +87,7 @@ export async function handleRscRendering<TEnv>(
           segments: result.segments,
           matched: result.matched,
           diff: result.diff,
+          resolvedIds: result.resolvedIds,
           params: result.params,
           isPartial: true,
           slots: result.slots,
@@ -133,27 +140,7 @@ export async function handleRscRendering<TEnv>(
         { headers: { "Content-Type": "application/json" } },
       );
     } else {
-      payload = {
-        // Initial SSR can reconstruct the tree from segments + rootLayout,
-        // so we omit root to avoid sending the same structure twice.
-
-        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(),
-          version: ctx.version,
-          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
-          themeConfig: ctx.router.themeConfig,
-          initialTheme: reqCtx.theme,
-        },
-      };
+      payload = buildFullPayload(match);
     }
   }
 
@@ -187,23 +174,20 @@ export async function handleRscRendering<TEnv>(
     rscSerializeDur,
   );
 
-  // Determine if this is an RSC request or HTML request.
-  // Partial requests (_rsc_partial) are always RSC -- they come from client-side
-  // navigation or prefetch fetch(). We cannot rely on Accept alone since some
-  // browsers may send Accept: text/html for non-HTML requests.
-  const isRscRequest =
-    isPartial ||
-    (!request.headers.get("accept")?.includes("text/html") &&
-      !url.searchParams.has("__html")) ||
-    url.searchParams.has("__rsc");
-
-  if (isRscRequest) {
+  if (isRscRequest(request, url, isPartial)) {
     const renderDur = performance.now() - renderStart;
     appendMetric(metricsStore, "render:total", renderStart, renderDur);
     const rscHeaders: Record<string, string> = {
       "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/runtime-warnings.ts

@@ -8,6 +8,7 @@ import {
   createResponseWithMergedHeaders,
   carryOverRedirectHeaders,
 } from "./helpers.js";
+import { isRedirectResponse } from "../response-utils.js";
 
 // W3 -----------------------------------------------------------------------
 
@@ -18,16 +19,14 @@ import {
  */
 export function extractRedirectResponse(value: unknown): Response | null {
   if (!(value instanceof Response)) return null;
-  const location = value.headers.get("Location");
-  if (value.status >= 300 && value.status < 400 && location) {
-    const redirect = createResponseWithMergedHeaders(null, {
-      status: value.status,
-      headers: { Location: location },
-    });
-    carryOverRedirectHeaders(value, redirect);
-    return redirect;
-  }
-  return null;
+  if (!isRedirectResponse(value)) return null;
+  const location = value.headers.get("Location")!;
+  const redirect = createResponseWithMergedHeaders(null, {
+    status: value.status,
+    headers: { Location: location },
+  });
+  carryOverRedirectHeaders(value, redirect);
+  return redirect;
 }
 
 /**

package/src/rsc/server-action.ts

@@ -27,7 +27,7 @@ import {
   hasBodyContent,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
-  carryOverRedirectHeaders,
+  interceptRedirectForPartial,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
@@ -111,49 +111,25 @@ export async function executeServerAction<TEnv>(
     loadedAction = await ctx.loadServerAction(actionId);
     const data = await loadedAction!.apply(null, args);
 
-    // Intercept redirect responses from actions. Without this, the redirect
-    // Response would be serialized as the action returnValue (which fails)
-    // and the revalidation step would run unnecessarily.
+    // Intercept redirect Responses: serializing one as the action returnValue
+    // would fail, and revalidation would run needlessly.
     if (data instanceof Response) {
-      const redirectUrl = data.headers.get("Location");
-      const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(data, redirect);
-        return redirect;
-      }
+      const intercepted = interceptRedirectForPartial(
+        data,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
     }
 
     returnValue = { ok: true, data };
   } catch (error) {
     // Handle thrown redirect (e.g., throw redirect('/path'))
     if (error instanceof Response) {
-      const redirectUrl = error.headers.get("Location");
-      const isRedirect =
-        error.status >= 300 && error.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(error, redirect);
-        return redirect;
-      }
+      const intercepted = interceptRedirectForPartial(
+        error,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
 
       // Non-redirect Response thrown from action — this will be treated
       // as a regular error and routed to the error boundary. Warn in dev
@@ -213,6 +189,8 @@ export async function executeServerAction<TEnv>(
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          resolvedIds: errorResult.resolvedIds,
+          params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
           version: ctx.version,
@@ -323,6 +301,8 @@ export async function revalidateAfterAction<TEnv>(
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      resolvedIds: matchResult.resolvedIds,
+      params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,

package/src/rsc/ssr-setup.ts

@@ -126,3 +126,19 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
 
   return true;
 }
+
+// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
+// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
+// Accept header as needing SSR; this treats it as RSC).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    (!request.headers.get("accept")?.includes("text/html") &&
+      !url.searchParams.has("__html")) ||
+    url.searchParams.has("__rsc")
+  );
+}

package/src/rsc/types.ts

@@ -7,7 +7,7 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
@@ -26,6 +26,12 @@ export interface RscPayload {
     isError?: boolean;
     matched?: string[];
     diff?: string[];
+    /**
+     * All segment ids re-resolved on the server, including null-component
+     * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+     * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+     */
+    resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;
@@ -179,7 +185,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouterInternal<TEnv, TRoutes>;
+  router: RangoInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.

package/src/search-params.ts

@@ -81,11 +81,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
 // ============================================================================
 
 /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
-type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
-  ? keyof RSCRouter.GeneratedRouteMap extends never
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
     ? Record<string, string>
-    : RSCRouter.GeneratedRouteMap
-  : RSCRouter.RegisteredRoutes;
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Extract the resolved search params type for a named route.

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;
+}