@rangojs/router 0.0.0-experimental.ede38110 → 0.0.0-experimental.f2d1a2f1

package/src/router/match-api.ts

@@ -22,10 +22,10 @@ import { collectRouteMiddleware } from "./middleware.js";
 import { traverseBack } from "./pattern-matching.js";
 import { DefaultErrorFallback } from "../default-error-boundary.js";
 import {
-  EntryData,
-  LoaderEntry,
+  type EntryData,
+  type LoaderEntry,
   getContext,
-  InterceptSelectorContext,
+  type InterceptSelectorContext,
 } from "../server/context";
 import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";

package/src/router/middleware-types.ts

@@ -14,6 +14,7 @@ import type {
 import type { ScopedReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Get variable function type
@@ -57,28 +58,7 @@ export interface CookieOptions {
 export interface MiddlewareContext<
   TEnv = any,
   TParams = Record<string, string>,
-> {
-  /** Original request */
-  request: Request;
-
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-
-  /** URL pathname */
-  pathname: string;
-
-  /** URL search params */
-  searchParams: URLSearchParams;
-
-  /** Platform bindings (Cloudflare, etc.) */
-  env: TEnv;
-
+> extends RequestScope<TEnv> {
   /** URL params extracted from route/middleware pattern */
   params: TParams;
 

package/src/router/middleware.ts

@@ -10,6 +10,8 @@
  */
 
 import { contextGet, contextSet } from "../context-var.js";
+import { safeDecodeURIComponent } from "./url-params.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import type {
   CollectedMiddleware,
   MiddlewareCollectableEntry,
@@ -22,6 +24,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
 import { stripInternalParams } from "./handler-context.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -112,7 +115,12 @@ function escapeRegex(str: string): string {
 }
 
 /**
- * Extract params from a pathname using a pattern's regex and param names
+ * Extract params from a pathname using a pattern's regex and param names.
+ *
+ * Values are URL-decoded so apps see the raw string (e.g. "ivo@example.com")
+ * instead of the percent-encoded form ("ivo%40example.com"). This matches the
+ * contract assumed by ctx.reverse (which re-encodes) and aligns with
+ * Express/React Router/Fastify/Koa.
  */
 export function extractParams(
   pathname: string,
@@ -124,7 +132,7 @@ export function extractParams(
 
   const params: Record<string, string> = {};
   for (let i = 0; i < paramNames.length; i++) {
-    params[paramNames[i]] = match[i + 1] || "";
+    params[paramNames[i]] = safeDecodeURIComponent(match[i + 1] || "");
   }
   return params;
 }
@@ -179,14 +187,22 @@ export function createMiddlewareContext<TEnv>(
     return responseHolder.response;
   };
 
+  // Capture reqCtx once: the request-scoped platform fields
+  // (originalUrl, executionContext, waitUntil) are immutable per request,
+  // so snapshotting beats re-reading ALS on every access. The lazy getters
+  // below (routeName, theme, setTheme) stay lazy because those can change
+  // during `await next()`.
+  const reqCtx = _getRequestContext();
   return {
     request,
     url,
-    originalUrl: new URL(request.url),
+    originalUrl: reqCtx?.originalUrl ?? new URL(request.url),
     pathname: url.pathname,
     searchParams: url.searchParams,
     env: env as MiddlewareContext<TEnv>["env"],
     params,
+    executionContext: reqCtx?.executionContext,
+    waitUntil: reqCtx ? reqCtx.waitUntil.bind(reqCtx) : fireAndForgetWaitUntil,
     // Getter: re-derives from request context on each access so that global
     // middleware sees the matched route name after await next().
     get routeName(): MiddlewareContext<TEnv>["routeName"] {
@@ -360,6 +376,11 @@ export async function executeMiddleware<TEnv>(
         });
       }
 
+      if (isWebSocketUpgradeResponse(response)) {
+        responseHolder.response = response;
+        return response;
+      }
+
       // Clone response with merged headers (mutable for post-next() modifications)
       responseHolder.response = new Response(response.body, {
         status: response.status,
@@ -451,6 +472,10 @@ export async function executeMiddleware<TEnv>(
     // RequestContext stub headers (from ctx.setCookie) into the
     // returned Response so they are not lost.
     if (result instanceof Response) {
+      if (isWebSocketUpgradeResponse(result)) {
+        responseHolder.response = result;
+        return result;
+      }
       const mergedHeaders = new Headers(result.headers);
       stubResponse.headers.forEach((value, name) => {
         if (name.toLowerCase() === "set-cookie") {
@@ -527,8 +552,11 @@ export async function executeMiddleware<TEnv>(
   // last merge point (e.g. cookies().set() called after await next()).
   // The reqCtx stub may have already been partially merged during finalHandler
   // or early-return paths; only append *new* Set-Cookie entries to avoid dupes.
+  //
+  // Skip for upgrade responses: upgrade headers are semantically immutable and
+  // set-cookie on an upgrade is not meaningful.
   const reqCtx = _getRequestContext();
-  if (reqCtx) {
+  if (reqCtx && !isWebSocketUpgradeResponse(finalResponse)) {
     const stubCookies = reqCtx.res.headers.getSetCookie();
     if (stubCookies.length > 0) {
       const existingCookies = new Set(finalResponse.headers.getSetCookie());

package/src/router/pattern-matching.ts

@@ -7,6 +7,7 @@
 import type { RouteEntry, TrailingSlashMode } from "../types";
 import type { EntryData } from "../server/context";
 import { debugLog, isRouterDebugEnabled } from "./logging.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 /**
  * Parsed segment info
@@ -82,6 +83,13 @@ export interface CompiledPattern {
   paramNames: string[];
   optionalParams: Set<string>;
   hasTrailingSlash: boolean;
+  /**
+   * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
+   * Validated against the **decoded** param value after regex extraction so
+   * a URL like `/en%20GB` still matches `:lang(en GB)` — matching the trie
+   * path's behavior (trie-matching.ts:validateAndBuild).
+   */
+  constraints?: Record<string, string[]>;
 }
 
 // Module-level cache for compiled patterns. Route patterns are a finite set
@@ -142,6 +150,7 @@ export function compilePattern(pattern: string): CompiledPattern {
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
   const optionalParams = new Set<string>();
+  let constraints: Record<string, string[]> | undefined;
 
   let regexPattern = "";
 
@@ -152,11 +161,14 @@ export function compilePattern(pattern: string): CompiledPattern {
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
       const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
-      const valuePattern = segment.constraint
-        ? `(${segment.constraint.map(escapeRegex).join("|")})`
-        : segment.suffix
-          ? "([^/]+?)"
-          : "([^/]+)";
+      // Constrained params capture anything here; the allowed values are
+      // checked post-decode in findMatch so URL-encoded constraint values
+      // (e.g. `:lang(en GB)` via `/en%20GB`) still match.
+      const valuePattern = segment.suffix ? "([^/]+?)" : "([^/]+)";
+
+      if (segment.constraint) {
+        (constraints ??= {})[segment.value] = segment.constraint;
+      }
 
       if (segment.optional) {
         optionalParams.add(segment.value);
@@ -186,9 +198,33 @@ export function compilePattern(pattern: string): CompiledPattern {
     paramNames,
     optionalParams,
     hasTrailingSlash,
+    ...(constraints ? { constraints } : {}),
   };
 }
 
+/**
+ * Validate decoded params against a compiled pattern's constraints.
+ * Returns false if any constrained param has a non-empty value not in the
+ * allowed list (empty-string = absent optional, which is allowed).
+ */
+function satisfiesConstraints(
+  params: Record<string, string>,
+  constraints: Record<string, string[]> | undefined,
+): boolean {
+  if (!constraints) return true;
+  for (const name in constraints) {
+    const value = params[name];
+    if (
+      value !== undefined &&
+      value !== "" &&
+      !constraints[name].includes(value)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * Escape special regex characters in a string
  */
@@ -392,8 +428,13 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, optionalParams, hasTrailingSlash } =
-        getCompiledPattern(fullPattern);
+      const {
+        regex,
+        paramNames,
+        optionalParams,
+        hasTrailingSlash,
+        constraints,
+      } = getCompiledPattern(fullPattern);
 
       // Get trailing slash mode for this route (per-route config or pattern-based)
       const trailingSlashMode: TrailingSlashMode | undefined =
@@ -412,9 +453,15 @@ export function findMatch<TEnv>(
       if (match) {
         const params: Record<string, string> = {};
         paramNames.forEach((name, index) => {
-          params[name] = match[index + 1] ?? "";
+          params[name] = safeDecodeURIComponent(match[index + 1] ?? "");
         });
 
+        // Validate constraints against decoded values; a failure falls
+        // through to the next route so other patterns can still match.
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
+
         if (effectiveDebug) {
           debugLog("findMatch", "matched route", {
             routeKey,
@@ -467,9 +514,13 @@ export function findMatch<TEnv>(
       if (altMatch) {
         const params: Record<string, string> = {};
         paramNames.forEach((name, index) => {
-          params[name] = altMatch[index + 1] ?? "";
+          params[name] = safeDecodeURIComponent(altMatch[index + 1] ?? "");
         });
 
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
+
         // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
           // Match without redirect

package/src/router/trie-matching.ts

@@ -6,6 +6,7 @@
  */
 
 import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -173,20 +174,25 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues
+  // Build named params by zipping leaf.pa with positional paramValues.
+  // Params are URL-decoded at this boundary so ctx.params holds the values
+  // apps expect (matching Express/React Router) and round-trip cleanly
+  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
-      params[leaf.pa[i]] = paramValues[i];
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
     }
   }
 
   // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
-    params[(leaf as TrieLeaf & { pn: string }).pn] = wildcardValue;
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints
+  // Validate constraints against decoded values so constraint lists can be
+  // written in decoded form (e.g. ["en-GB", "en US"]).
   if (leaf.cv) {
     for (const paramName in leaf.cv) {
       const allowed = leaf.cv[paramName]!;

package/src/router/url-params.ts

@@ -0,0 +1,49 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+// encodeURIComponent over-encodes for path segments. After running it,
+// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
+// keeps human-readable characters that are legal in a path segment.
+// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
+// encoded.
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}

package/src/router.ts

@@ -22,8 +22,7 @@ import type { UrlPatterns } from "./urls.js";
 import type { UrlBuilder } from "./urls/pattern-types.js";
 import { urls } from "./urls.js";
 import {
-  EntryData,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
   RSCRouterContext,
   type MetricsStore,

package/src/rsc/handler.ts

@@ -31,6 +31,7 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import {
   handleResponseRoute,
   type ResponseRouteMatch,
@@ -56,6 +57,7 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
 import {
@@ -352,7 +354,7 @@ export function createRSCHandler<
     // Resolve cache store configuration
     // Priority: options.cache (handler override) > router.cache (router default)
     // Store is enabled only if: config provided, enabled, and no ?__no_cache query param
-    let cacheStore = undefined;
+    let cacheStore: SegmentCacheStore | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
       const cacheConfig =
@@ -533,7 +535,9 @@ export function createRSCHandler<
       }
 
       const fullTiming = timingParts.join(", ");
-      if (fullTiming) response.headers.set("Server-Timing", fullTiming);
+      if (fullTiming && !isWebSocketUpgradeResponse(response)) {
+        response.headers.set("Server-Timing", fullTiming);
+      }
 
       return response;
     });
@@ -804,7 +808,7 @@ export function createRSCHandler<
         );
       }
       const response = responseOutcome.result;
-      if (plan.negotiated) {
+      if (plan.negotiated && !isWebSocketUpgradeResponse(response)) {
         response.headers.append("Vary", "Accept");
       }
       return response;
@@ -1014,7 +1018,7 @@ export function createRSCHandler<
             nonce,
           );
         }
-        if (negotiated) {
+        if (negotiated && !isWebSocketUpgradeResponse(response)) {
           response.headers.append("Vary", "Accept");
         }
         return response;

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/progressive-enhancement.ts

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

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;
@@ -78,10 +80,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 +101,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 +207,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

@@ -204,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

@@ -213,6 +213,7 @@ export async function executeServerAction<TEnv>(
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
           version: ctx.version,
@@ -323,6 +324,7 @@ export async function revalidateAfterAction<TEnv>(
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,