Fix parallel slot persistence and cache variants

packages/vinext/src/entries/app-rsc-entry.ts

@@ -538,7 +538,21 @@ function __isrCacheKey(pathname, suffix) {
   return prefix + ":__hash:" + __isrFnv1a64(normalized) + ":" + suffix;
 }
 function __isrHtmlKey(pathname) { return __isrCacheKey(pathname, "html"); }
-function __isrRscKey(pathname) { return __isrCacheKey(pathname, "rsc"); }
+function __isrRscKey(pathname, mountedSlotsHeader) {
+  if (!mountedSlotsHeader) return __isrCacheKey(pathname, "rsc");
+  return __isrCacheKey(pathname, "rsc:" + __isrFnv1a64(mountedSlotsHeader));
+}
+function __normalizeMountedSlotsHeader(raw) {
+  if (!raw) return null;
+  const normalized = Array.from(
+    new Set(
+      raw
+        .split(/\\s+/)
+        .filter(Boolean),
+    ),
+  ).sort().join(" ");
+  return normalized || null;
+}
 function __isrRouteKey(pathname) { return __isrCacheKey(pathname, "route"); }
 // Verbose cache logging — opt in with NEXT_PRIVATE_DEBUG_CACHE=1.
 // Matches the env var Next.js uses for its own cache debug output so operators
@@ -911,7 +925,7 @@ function findIntercept(pathname) {
   return null;
 }
 
-async function buildPageElements(route, params, routePath, opts, searchParams) {
+async function buildPageElements(route, params, routePath, opts, searchParams, isRscRequest, request) {
   const PageComponent = route.page?.default;
   if (!PageComponent) {
     const _noExportRouteId = "route:" + routePath;
@@ -1024,9 +1038,18 @@ async function buildPageElements(route, params, routePath, opts, searchParams) {
     // dynamic, and this avoids false positives from React internals.
     if (hasSearchParams) markDynamicUsage();
   }
+  const __mountedSlotsHeader = __normalizeMountedSlotsHeader(
+    request?.headers?.get("x-vinext-mounted-slots"),
+  );
+  const mountedSlotIds = __mountedSlotsHeader
+    ? new Set(__mountedSlotsHeader.split(" "))
+    : null;
+
   return __buildAppPageElements({
     element: createElement(PageComponent, pageProps),
     globalErrorModule: ${globalErrorVar ? globalErrorVar : "null"},
+    isRscRequest,
+    mountedSlotIds,
     makeThenableParams,
     matchedParams: params,
     resolvedMetadata,
@@ -1778,6 +1801,8 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
           cleanPathname,
           undefined,
           url.searchParams,
+          isRscRequest,
+          request,
         );
       } else {
         const _actionRouteId = "route:" + cleanPathname;
@@ -2099,6 +2124,9 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
 
   // force-dynamic: set no-store Cache-Control
   const isForceDynamic = dynamicConfig === "force-dynamic";
+  const __mountedSlotsHeader = __normalizeMountedSlotsHeader(
+    request.headers.get("x-vinext-mounted-slots"),
+  );
 
   // ── ISR cache read (production only) ─────────────────────────────────────
   // Read from cache BEFORE generateStaticParams and all rendering work.
@@ -2132,6 +2160,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
       isrHtmlKey: __isrHtmlKey,
       isrRscKey: __isrRscKey,
       isrSet: __isrSet,
+      mountedSlotsHeader: __mountedSlotsHeader,
       revalidateSeconds,
       renderFreshPageForCache: async function() {
         // Re-render the page to produce fresh HTML + RSC data for the cache
@@ -2146,12 +2175,17 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
         return _runWithUnifiedCtx(__revalUCtx, async () => {
           _ensureFetchPatch();
           setNavigationContext({ pathname: cleanPathname, searchParams: new URLSearchParams(), params });
+          // Slot context (X-Vinext-Mounted-Slots) is inherited from the
+          // triggering request so the regen result is cached under the
+          // correct slot-variant key.
           const __revalElement = await buildPageElements(
             route,
             params,
             cleanPathname,
             undefined,
             new URLSearchParams(),
+            isRscRequest,
+            request,
           );
           const __revalOnError = createRscOnErrorHandler(request, cleanPathname, route.pattern);
           const __revalRscStream = renderToReadableStream(__revalElement, { onError: __revalOnError });
@@ -2208,6 +2242,8 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
         cleanPathname,
         interceptOpts,
         interceptSearchParams,
+        isRscRequest,
+        request,
       );
     },
     cleanPathname,
@@ -2260,7 +2296,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
 
   const __pageBuildResult = await __buildAppPageElement({
     buildPageElement() {
-      return buildPageElements(route, params, cleanPathname, interceptOpts, url.searchParams);
+      return buildPageElements(route, params, cleanPathname, interceptOpts, url.searchParams, isRscRequest, request);
     },
     renderErrorBoundaryPage(buildErr) {
       return renderErrorBoundaryPage(route, buildErr, isRscRequest, request, params, _scriptNonce);
@@ -2357,6 +2393,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
       return PageComponent({ params: _asyncLayoutParams, searchParams: _asyncSearchParams });
     },
     revalidateSeconds,
+    mountedSlotsHeader: __mountedSlotsHeader,
     renderErrorBoundaryResponse(renderErr) {
       return renderErrorBoundaryPage(route, renderErr, isRscRequest, request, params, _scriptNonce);
     },

packages/vinext/src/server/app-browser-entry.ts

@@ -35,6 +35,7 @@ import {
   restoreRscResponse,
   setClientParams,
   snapshotRscResponse,
+  setMountedSlotsHeader,
   setNavigationContext,
   toRscUrl,
   type CachedRscResponse,
@@ -47,6 +48,7 @@ import {
   getVinextBrowserGlobal,
 } from "./app-browser-stream.js";
 import {
+  getMountedSlotIdsHeader,
   normalizeAppElements,
   readAppElementsMetadata,
   type AppElements,
@@ -218,13 +220,19 @@ function evictVisitedResponseCacheIfNeeded(): void {
 
 function getVisitedResponse(
   rscUrl: string,
+  mountedSlotsHeader: string | null,
   navigationKind: NavigationKind,
 ): VisitedResponseCacheEntry | null {
   const cached = visitedResponseCache.get(rscUrl);
   if (!cached) {
     return null;
   }
 
+  if ((cached.response.mountedSlotsHeader ?? null) !== mountedSlotsHeader) {
+    visitedResponseCache.delete(rscUrl);
+    return null;
+  }
+
   if (navigationKind === "refresh") {
     return null;
   }
@@ -411,9 +419,14 @@ function BrowserRoot({
       if (browserRouterStateRef === stateRef) {
         browserRouterStateRef = null;
       }
+      setMountedSlotsHeader(null);
     };
   }, [dispatchTreeState]);
 
+  useLayoutEffect(() => {
+    setMountedSlotsHeader(getMountedSlotIdsHeader(stateRef.current.elements));
+  }, [treeState.elements]);
+
   const committedTree = createElement(
     NavigationCommitSignal,
     { renderId: treeState.renderId },
@@ -737,7 +750,9 @@ async function main(): Promise<void> {
       const isSameRoute =
         stripBasePath(url.pathname, __basePath) ===
         stripBasePath(window.location.pathname, __basePath);
-      const cachedRoute = getVisitedResponse(rscUrl, navigationKind);
+      const elementsAtNavStart = getBrowserRouterState().elements;
+      const mountedSlotsHeader = getMountedSlotIdsHeader(elementsAtNavStart);
+      const cachedRoute = getVisitedResponse(rscUrl, mountedSlotsHeader, navigationKind);
       if (cachedRoute) {
         // Check stale-navigation before and after createFromFetch. The pre-check
         // avoids wasted parse work; the post-check catches supersessions that
@@ -777,19 +792,26 @@ async function main(): Promise<void> {
         return;
       }
 
+      // Continue using the slot state captured at navigation start for fetches
+      // and prefetch compatibility decisions.
+
       let navResponse: Response | undefined;
       let navResponseUrl: string | null = null;
       if (navigationKind !== "refresh") {
-        const prefetchedResponse = consumePrefetchResponse(rscUrl);
+        const prefetchedResponse = consumePrefetchResponse(rscUrl, mountedSlotsHeader);
         if (prefetchedResponse) {
           navResponse = restoreRscResponse(prefetchedResponse, false);
           navResponseUrl = prefetchedResponse.url;
         }
       }
 
       if (!navResponse) {
+        const rscFetchHeaders: Record<string, string> = { Accept: "text/x-component" };
+        if (mountedSlotsHeader) {
+          rscFetchHeaders["X-Vinext-Mounted-Slots"] = mountedSlotsHeader;
+        }
         navResponse = await fetch(rscUrl, {
-          headers: { Accept: "text/x-component" },
+          headers: rscFetchHeaders,
           credentials: "include",
         });
       }

packages/vinext/src/server/app-elements.ts

@@ -17,6 +17,31 @@ export type AppElementsMetadata = {
   rootLayoutTreePath: string | null;
 };
 
+export function normalizeMountedSlotsHeader(header: string | null | undefined): string | null {
+  if (!header) {
+    return null;
+  }
+
+  const slotIds = Array.from(new Set(header.split(/\s+/).filter(Boolean))).sort();
+
+  return slotIds.length > 0 ? slotIds.join(" ") : null;
+}
+
+export function getMountedSlotIds(elements: AppElements): string[] {
+  return Object.keys(elements)
+    .filter((key) => {
+      const value = elements[key];
+      return (
+        key.startsWith("slot:") && value !== null && value !== undefined && value !== UNMATCHED_SLOT
+      );
+    })
+    .sort();
+}
+
+export function getMountedSlotIdsHeader(elements: AppElements): string | null {
+  return normalizeMountedSlotsHeader(getMountedSlotIds(elements).join(" "));
+}
+
 export function normalizeAppElements(elements: AppWireElements): AppElements {
   let needsNormalization = false;
   for (const [key, value] of Object.entries(elements)) {

packages/vinext/src/server/app-page-cache.ts

@@ -20,6 +20,7 @@ export type AppPageCacheRenderResult = {
 export type BuildAppPageCachedResponseOptions = {
   cacheState: "HIT" | "STALE";
   isRscRequest: boolean;
+  mountedSlotsHeader?: string | null;
   revalidateSeconds: number;
 };
 
@@ -30,8 +31,9 @@ export type ReadAppPageCacheResponseOptions = {
   isrDebug?: AppPageDebugLogger;
   isrGet: AppPageCacheGetter;
   isrHtmlKey: (pathname: string) => string;
-  isrRscKey: (pathname: string) => string;
+  isrRscKey: (pathname: string, mountedSlotsHeader?: string | null) => string;
   isrSet: AppPageCacheSetter;
+  mountedSlotsHeader?: string | null;
   revalidateSeconds: number;
   renderFreshPageForCache: () => Promise<AppPageCacheRenderResult>;
   scheduleBackgroundRegeneration: AppPageBackgroundRegenerator;
@@ -43,7 +45,7 @@ export type FinalizeAppPageHtmlCacheResponseOptions = {
   getPageTags: () => string[];
   isrDebug?: AppPageDebugLogger;
   isrHtmlKey: (pathname: string) => string;
-  isrRscKey: (pathname: string) => string;
+  isrRscKey: (pathname: string, mountedSlotsHeader?: string | null) => string;
   isrSet: AppPageCacheSetter;
   revalidateSeconds: number;
   waitUntil?: (promise: Promise<void>) => void;
@@ -56,8 +58,9 @@ export type ScheduleAppPageRscCacheWriteOptions = {
   dynamicUsedDuringBuild: boolean;
   getPageTags: () => string[];
   isrDebug?: AppPageDebugLogger;
-  isrRscKey: (pathname: string) => string;
+  isrRscKey: (pathname: string, mountedSlotsHeader?: string | null) => string;
   isrSet: AppPageCacheSetter;
+  mountedSlotsHeader?: string | null;
   revalidateSeconds: number;
   waitUntil?: (promise: Promise<void>) => void;
 };
@@ -95,12 +98,17 @@ export function buildAppPageCachedResponse(
       return null;
     }
 
+    const rscHeaders: Record<string, string> = {
+      "Content-Type": "text/x-component; charset=utf-8",
+      ...headers,
+    };
+    if (options.mountedSlotsHeader) {
+      rscHeaders["X-Vinext-Mounted-Slots"] = options.mountedSlotsHeader;
+    }
+
     return new Response(cachedValue.rscData, {
       status,
-      headers: {
-        "Content-Type": "text/x-component; charset=utf-8",
-        ...headers,
-      },
+      headers: rscHeaders,
     });
   }
 
@@ -121,7 +129,7 @@ export async function readAppPageCacheResponse(
   options: ReadAppPageCacheResponseOptions,
 ): Promise<Response | null> {
   const isrKey = options.isRscRequest
-    ? options.isrRscKey(options.cleanPathname)
+    ? options.isrRscKey(options.cleanPathname, options.mountedSlotsHeader)
     : options.isrHtmlKey(options.cleanPathname);
 
   try {
@@ -132,6 +140,7 @@ export async function readAppPageCacheResponse(
       const hitResponse = buildAppPageCachedResponse(cachedValue, {
         cacheState: "HIT",
         isRscRequest: options.isRscRequest,
+        mountedSlotsHeader: options.mountedSlotsHeader,
         revalidateSeconds: options.revalidateSeconds,
       });
 
@@ -151,29 +160,43 @@ export async function readAppPageCacheResponse(
       // Preserve the legacy behavior from the inline generator: stale entries
       // still trigger background regeneration even if this request cannot use
       // the stale payload and will fall through to a fresh render.
+      // Dedup key is pathname-only: if multiple slot variants are stale
+      // concurrently, only one regen runs. Other variants refresh on
+      // their next STALE read.
       options.scheduleBackgroundRegeneration(options.cleanPathname, async () => {
         const revalidatedPage = await options.renderFreshPageForCache();
-
-        await Promise.all([
+        const writes = [
           options.isrSet(
-            options.isrHtmlKey(options.cleanPathname),
-            buildAppPageCacheValue(revalidatedPage.html, undefined, 200),
-            options.revalidateSeconds,
-            revalidatedPage.tags,
-          ),
-          options.isrSet(
-            options.isrRscKey(options.cleanPathname),
+            options.isrRscKey(options.cleanPathname, options.mountedSlotsHeader),
             buildAppPageCacheValue("", revalidatedPage.rscData, 200),
             options.revalidateSeconds,
             revalidatedPage.tags,
           ),
-        ]);
+        ];
+
+        if (!options.isRscRequest) {
+          // HTML cache is slot-state-independent (canonical), so only refresh it
+          // during HTML-triggered regens. RSC-triggered regens only update the
+          // requesting client's RSC slot variant; a stale HTML cache entry will
+          // be regenerated independently by the next full-page HTML request.
+          writes.push(
+            options.isrSet(
+              options.isrHtmlKey(options.cleanPathname),
+              buildAppPageCacheValue(revalidatedPage.html, undefined, 200),
+              options.revalidateSeconds,
+              revalidatedPage.tags,
+            ),
+          );
+        }
+
+        await Promise.all(writes);
         options.isrDebug?.("regen complete", options.cleanPathname);
       });
 
       const staleResponse = buildAppPageCachedResponse(cachedValue, {
         cacheState: "STALE",
         isRscRequest: options.isRscRequest,
+        mountedSlotsHeader: options.mountedSlotsHeader,
         revalidateSeconds: options.revalidateSeconds,
       });
 
@@ -209,7 +232,7 @@ export function finalizeAppPageHtmlCacheResponse(
 
   const [streamForClient, streamForCache] = response.body.tee();
   const htmlKey = options.isrHtmlKey(options.cleanPathname);
-  const rscKey = options.isrRscKey(options.cleanPathname);
+  const rscKey = options.isrRscKey(options.cleanPathname, null);
 
   const cachePromise = (async () => {
     try {
@@ -272,7 +295,7 @@ export function scheduleAppPageRscCacheWrite(
     return false;
   }
 
-  const rscKey = options.isrRscKey(options.cleanPathname);
+  const rscKey = options.isrRscKey(options.cleanPathname, options.mountedSlotsHeader);
   const cachePromise = (async () => {
     try {
       const rscData = await capturedRscDataPromise;