fix: clear stale parallel slots on traversal in mergeElements

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

@@ -75,6 +75,14 @@ type ServerActionResult = {
 };
 
 type NavigationKind = "navigate" | "traverse" | "refresh";
+
+// Maps NavigationKind to the AppRouterAction type used by the reducer.
+// "refresh" is intentionally treated as "navigate" (merge, preserve absent slots).
+// Both call sites must stay in sync — update here if NavigationKind gains new values.
+function toActionType(kind: NavigationKind): "navigate" | "traverse" {
+  return kind === "traverse" ? "traverse" : "navigate";
+}
+
 type HistoryUpdateMode = "push" | "replace";
 type VisitedResponseCacheEntry = {
   params: Record<string, string | string[]>;
@@ -453,7 +461,7 @@ function dispatchBrowserTree(
   elements: AppElements,
   navigationSnapshot: ClientNavigationRenderSnapshot,
   renderId: number,
-  actionType: "navigate" | "replace",
+  actionType: "navigate" | "replace" | "traverse",
   routeId: string,
   rootLayoutTreePath: string | null,
   useTransitionMode: boolean,
@@ -484,7 +492,7 @@ async function renderNavigationPayload(
   navId: number,
   prePaintEffect: (() => void) | null = null,
   useTransition = true,
-  actionType: "navigate" | "replace" = "navigate",
+  actionType: "navigate" | "replace" | "traverse" = "navigate",
 ): Promise<void> {
   const renderId = ++nextNavigationRenderId;
   const committed = new Promise<void>((resolve) => {
@@ -783,6 +791,7 @@ async function main(): Promise<void> {
             navId,
             createNavigationCommitEffect(href, historyUpdateMode, cachedParams),
             isSameRoute,
+            toActionType(navigationKind),
           );
         } finally {
           // Always clear _snapshotPending so the outer catch does not
@@ -871,6 +880,7 @@ async function main(): Promise<void> {
           navId,
           createNavigationCommitEffect(href, historyUpdateMode, navParams),
           isSameRoute,
+          toActionType(navigationKind),
         );
       } finally {
         // Always clear _snapshotPending after renderNavigationPayload returns or

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

@@ -16,7 +16,7 @@ export type AppRouterAction = {
   renderId: number;
   rootLayoutTreePath: string | null;
   routeId: string;
-  type: "navigate" | "replace";
+  type: "navigate" | "replace" | "traverse";
 };
 
 export type PendingNavigationCommit = {
@@ -33,9 +33,10 @@ export type ClassifiedPendingNavigationCommit = {
 
 export function routerReducer(state: AppRouterState, action: AppRouterAction): AppRouterState {
   switch (action.type) {
+    case "traverse":
     case "navigate":
       return {
-        elements: mergeElements(state.elements, action.elements),
+        elements: mergeElements(state.elements, action.elements, action.type === "traverse"),
         navigationSnapshot: action.navigationSnapshot,
         renderId: action.renderId,
         rootLayoutTreePath: action.rootLayoutTreePath,
@@ -92,7 +93,7 @@ export async function createPendingNavigationCommit(options: {
   nextElements: Promise<AppElements>;
   navigationSnapshot: ClientNavigationRenderSnapshot;
   renderId: number;
-  type: "navigate" | "replace";
+  type: "navigate" | "replace" | "traverse";
 }): Promise<PendingNavigationCommit> {
   const elements = await options.nextElements;
   const metadata = readAppElementsMetadata(elements);
@@ -118,7 +119,7 @@ export async function resolveAndClassifyNavigationCommit(options: {
   nextElements: Promise<AppElements>;
   renderId: number;
   startedNavigationId: number;
-  type: "navigate" | "replace";
+  type: "navigate" | "replace" | "traverse";
 }): Promise<ClassifiedPendingNavigationCommit> {
   const pending = await createPendingNavigationCommit({
     currentState: options.currentState,

packages/vinext/src/shims/slot.tsx

@@ -22,7 +22,11 @@ export const ParallelSlotsContext = React.createContext<Readonly<
   Record<string, React.ReactNode>
 > | null>(null);
 
-export function mergeElements(prev: AppElements, next: AppElements): AppElements {
+export function mergeElements(
+  prev: AppElements,
+  next: AppElements,
+  clearAbsentSlots = false,
+): AppElements {
   const merged: Record<string, AppElementValue> = { ...prev, ...next };
   // On soft navigation, unmatched parallel slots preserve their previous subtree
   // instead of firing notFound(). Only hard navigation (full page load) should 404.
@@ -32,6 +36,18 @@ export function mergeElements(prev: AppElements, next: AppElements): AppElements
       merged[key] = prev[key];
     }
   }
+  // On traversal (browser back/forward), the server renders the full destination
+  // route tree. A slot absent from next means the destination route tree does not
+  // include it, so clear it rather than keeping the stale prev value. This only
+  // runs for traversals because soft forward navigations may omit parent layout
+  // slots that should be preserved.
+  if (clearAbsentSlots) {
+    for (const key of Object.keys(merged)) {
+      if (key.startsWith("slot:") && !Object.hasOwn(next, key)) {
+        delete merged[key];
+      }
+    }
+  }
   return merged;
 }
 

tests/app-browser-entry.test.ts

@@ -221,6 +221,46 @@ describe("app browser entry state helpers", () => {
     expect(shouldHardNavigate(null, "/")).toBe(false);
     expect(shouldHardNavigate("/", null)).toBe(false);
   });
+
+  it("clears stale parallel slots on traverse", () => {
+    const state = createState({
+      elements: createResolvedElements("route:/feed", "/", {
+        "slot:modal:/feed": React.createElement("div", null, "modal"),
+      }),
+    });
+    const nextElements = createResolvedElements("route:/feed", "/");
+
+    const nextState = routerReducer(state, {
+      elements: nextElements,
+      navigationSnapshot: createState().navigationSnapshot,
+      renderId: 1,
+      rootLayoutTreePath: "/",
+      routeId: "route:/feed",
+      type: "traverse",
+    });
+
+    expect(Object.hasOwn(nextState.elements, "slot:modal:/feed")).toBe(false);
+  });
+
+  it("preserves absent parallel slots on navigate", () => {
+    const state = createState({
+      elements: createResolvedElements("route:/feed", "/", {
+        "slot:modal:/feed": React.createElement("div", null, "modal"),
+      }),
+    });
+    const nextElements = createResolvedElements("route:/feed/comments", "/");
+
+    const nextState = routerReducer(state, {
+      elements: nextElements,
+      navigationSnapshot: createState().navigationSnapshot,
+      renderId: 1,
+      rootLayoutTreePath: "/",
+      routeId: "route:/feed/comments",
+      type: "navigate",
+    });
+
+    expect(Object.hasOwn(nextState.elements, "slot:modal:/feed")).toBe(true);
+  });
 });
 
 describe("mounted slot helpers", () => {

tests/slot.test.ts

@@ -277,6 +277,68 @@ describe("slot primitives", () => {
     expect(merged["slot:modal:/"]).toBe(UNMATCHED_SLOT);
   });
 
+  it("mergeElements clears stale slots absent from next when clearAbsentSlots is set", async () => {
+    const { mergeElements } = await import("../packages/vinext/src/shims/slot.js");
+
+    const merged = mergeElements(
+      {
+        "layout:/": React.createElement("div", null, "layout"),
+        "page:/feed": React.createElement("div", null, "feed"),
+        "slot:modal:/feed": React.createElement("div", null, "intercepted modal"),
+      },
+      {
+        "layout:/": React.createElement("div", null, "layout"),
+        "page:/feed": React.createElement("div", null, "feed"),
+      },
+      true,
+    );
+
+    expect(Object.hasOwn(merged, "slot:modal:/feed")).toBe(false);
+  });
+
+  it("mergeElements on traversal: UNMATCHED_SLOT in next is restored from prev and not cleared", async () => {
+    const { mergeElements, UNMATCHED_SLOT } = await import("../packages/vinext/src/shims/slot.js");
+
+    const realContent = React.createElement("div", null, "modal content");
+    const merged = mergeElements(
+      {
+        "layout:/": React.createElement("div", null, "layout"),
+        "page:/feed": React.createElement("div", null, "feed"),
+        "slot:modal:/feed": realContent,
+      },
+      {
+        "layout:/": React.createElement("div", null, "layout"),
+        "page:/feed": React.createElement("div", null, "feed"),
+        "slot:modal:/feed": UNMATCHED_SLOT,
+      },
+      true,
+    );
+
+    // The slot IS present in next (as UNMATCHED_SLOT), so clearAbsentSlots does not
+    // delete it. The UNMATCHED_SLOT preservation loop then restores the real prev
+    // content because prev had a non-sentinel value.
+    expect(Object.hasOwn(merged, "slot:modal:/feed")).toBe(true);
+    expect(merged["slot:modal:/feed"]).toBe(realContent);
+  });
+
+  it("mergeElements preserves absent slots when clearAbsentSlots is not set", async () => {
+    const { mergeElements } = await import("../packages/vinext/src/shims/slot.js");
+
+    const merged = mergeElements(
+      {
+        "layout:/": React.createElement("div", null, "layout"),
+        "page:/dashboard": React.createElement("div", null, "dashboard"),
+        "slot:team:/dashboard": React.createElement("div", null, "team panel"),
+      },
+      {
+        "page:/dashboard/settings": React.createElement("div", null, "settings"),
+      },
+    );
+
+    // Without clearAbsentSlots, absent slots survive (soft nav to child route)
+    expect(Object.hasOwn(merged, "slot:team:/dashboard")).toBe(true);
+  });
+
   it("Slot renders element from resolved context", async () => {
     const mod = await import("../packages/vinext/src/shims/slot.js");