fix(app-router): promote default slot persistence through route state (#1229)

* fix(app-router): promote default slot persistence through route state

Default and unmatched parallel slots were still inferred from AppElements transport markers. That made soft navigation persistence depend on wire shape instead of planner-owned route state, which breaks the #726 invariant that AppElementsWire is transport only.

Thread slot binding metadata through AppElements, browser state, and the navigation planner. The commit boundary now preserves previous slot content and binding proof only when target route-state marks the slot default or unmatched and the visible state proves a mounted/default value exists.

Tests cover the new planner contract, metadata validation, route wiring, mergeElements behavior, and browser commit lifecycle for default and unmatched slot targets.

* fix(app-router): align intercepted slot binding metadata

Intercepted slot payloads could render active modal content while their route-state metadata still described the slot as default. The browser planner could then preserve the previous default slot for an ID that the fresh payload should replace, breaking intercepted navigations in app-router E2E.

Derive slot IDs through one helper for both metadata and rendering, assert graph/wire ID divergence, and compute binding state from the same resolved override default export used by the render path. Move the app hydration marker to the committed root layout effect so E2E link clicks wait for a hydrated tree.

* fix(app-router): harden slot binding preservation

Review follow-up for #726-CORE-14. Centralize AppElements slot binding normalization so duplicate slot ids and stale owner layout ids fail at the wire boundary instead of creating quiet last-write-wins behavior.

Alias planner slot binding snapshots to the AppElements binding shape, share slot id ordering helpers, document the no-proof compatibility law, and add negative planner/wire tests plus a browser-visible soft navigation E2E. Refs #726.

* fix(app-router): align slot binding proof with rendering

* docs(app-router): clarify slot preservation invariants

Author: NathanDrake2406

packages/vinext/src/global.d.ts

@@ -41,8 +41,9 @@ declare global {
     __VINEXT_ROOT__: Root | undefined;
 
     /**
-     * High-resolution timestamp recorded after client hydration completes.
-     * Used by instrumentation-client compatibility tests.
+     * High-resolution timestamp recorded after client hydration is usable.
+     * Pages Router writes after hydrateRoot() returns; App Router writes after
+     * the first committed tree attaches browser router state.
      */
     __VINEXT_HYDRATED_AT: number | undefined;
 

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

@@ -508,6 +508,7 @@ function BrowserRoot({
     renderId: 0,
     rootLayoutTreePath: initialMetadata.rootLayoutTreePath,
     routeId: initialMetadata.routeId,
+    slotBindings: initialMetadata.slotBindings,
     visibleCommitVersion: 0,
   });
   const treeState = isRouterStatePromise(treeStateValue) ? use(treeStateValue) : treeStateValue;
@@ -532,6 +533,11 @@ function BrowserRoot({
       stateRef,
     );
     browserRouterStateHasEverCommitted = true;
+    // App Router uses this timestamp as first committed tree readiness: the
+    // browser router state is attached and link/router interactions can safely
+    // observe the committed tree. It is intentionally later than hydrateRoot()
+    // returning.
+    window.__VINEXT_HYDRATED_AT = performance.now();
     return () => {
       detach();
       setMountedSlotsHeader(null);
@@ -1000,7 +1006,6 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
     options: hydrateRootOptions,
     startTransition,
   });
-  window.__VINEXT_HYDRATED_AT = performance.now();
 
   // Exposed so the navigation shim's `router.refresh()` can invalidate the
   // entire client navigation cache (visited-response + prefetch) before

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

@@ -4,6 +4,7 @@ import {
   getMountedSlotIds,
   getMountedSlotIdsHeader,
   type AppElements,
+  type AppElementsSlotBinding,
   type LayoutFlags,
 } from "./app-elements.js";
 import { createRscRequestHeaders } from "./app-rsc-cache-busting.js";
@@ -65,6 +66,7 @@ export type AppRouterState = {
   navigationSnapshot: ClientNavigationRenderSnapshot;
   rootLayoutTreePath: string | null;
   routeId: string;
+  slotBindings: readonly AppElementsSlotBinding[];
   visibleCommitVersion: number;
 };
 
@@ -79,6 +81,7 @@ export type AppRouterAction = {
   renderId: number;
   rootLayoutTreePath: string | null;
   routeId: string;
+  slotBindings: readonly AppElementsSlotBinding[];
   type: "navigate" | "replace" | "traverse";
 };
 
@@ -95,6 +98,7 @@ type DispatchPendingNavigationCommitDispositionDecision = {
   disposition: "dispatch";
   preserveAbsentSlots: boolean;
   preserveElementIds: readonly string[];
+  preservePreviousSlotIds: readonly string[];
   trace: NavigationTrace;
 };
 type NonDispatchPendingNavigationCommitDispositionDecision = {
@@ -290,6 +294,7 @@ function createVisibleRouteSnapshot(state: AppRouterState): RouteSnapshotV0 {
     mountedParallelSlots: createMountedParallelSlotSnapshots(state.elements),
     rootBoundaryId: state.rootLayoutTreePath,
     routeId: state.routeId,
+    slotBindings: state.slotBindings,
   };
 }
 
@@ -304,6 +309,7 @@ function createPendingRouteSnapshot(pending: PendingNavigationCommit): RouteSnap
     mountedParallelSlots: createMountedParallelSlotSnapshots(pending.action.elements),
     rootBoundaryId: pending.rootLayoutTreePath,
     routeId: pending.routeId,
+    slotBindings: pending.action.slotBindings,
   };
 }
 
@@ -374,6 +380,7 @@ function mapNavigationDecisionToPendingDisposition(
         disposition: "dispatch",
         preserveAbsentSlots: decision.proposal.preserveAbsentSlots,
         preserveElementIds: decision.proposal.preserveElementIds,
+        preservePreviousSlotIds: decision.proposal.preservePreviousSlotIds,
         trace: decision.trace,
       };
     case "hardNavigate":
@@ -413,6 +420,7 @@ export async function createPendingNavigationCommit(options: {
       interceptionContext: metadata.interceptionContext,
       layoutIds: metadata.layoutIds,
       layoutFlags: metadata.layoutFlags,
+      slotBindings: metadata.slotBindings,
       navigationSnapshot: options.navigationSnapshot,
       operation: createOperationRecord({
         id: options.renderId,

packages/vinext/src/server/app-browser-visible-commit.ts

@@ -1,6 +1,10 @@
 import type { ClientNavigationRenderSnapshot } from "vinext/shims/navigation";
 import { mergeElements } from "vinext/shims/slot";
-import type { AppElements } from "./app-elements.js";
+import {
+  normalizeAppElementsSlotBindings,
+  type AppElements,
+  type AppElementsSlotBinding,
+} from "./app-elements.js";
 import {
   createPendingNavigationCommit,
   resolvePendingNavigationCommitDispositionDecision,
@@ -25,6 +29,7 @@ type VisibleCommitDecision = {
   disposition: "commit";
   preserveAbsentSlots: boolean;
   preserveElementIds: readonly string[];
+  preservePreviousSlotIds: readonly string[];
   trace: NavigationTrace;
 };
 type HardNavigateCommitDecision = {
@@ -104,6 +109,36 @@ function commitVisibleRouterState(
   };
 }
 
+function mergeSlotBindings(
+  previousBindings: readonly AppElementsSlotBinding[],
+  nextBindings: readonly AppElementsSlotBinding[],
+  layoutIds: readonly string[],
+  preservePreviousSlotIds: readonly string[],
+): readonly AppElementsSlotBinding[] {
+  if (preservePreviousSlotIds.length === 0) return nextBindings;
+
+  const preservedSlotIds = new Set(preservePreviousSlotIds);
+  const previousBindingsBySlotId = new Map<string, AppElementsSlotBinding>();
+  for (const binding of previousBindings) {
+    if (!preservedSlotIds.has(binding.slotId)) continue;
+    previousBindingsBySlotId.set(binding.slotId, binding);
+  }
+
+  const mergedBindings: AppElementsSlotBinding[] = [];
+  const seenSlotIds = new Set<string>();
+  for (const binding of nextBindings) {
+    const previousBinding = previousBindingsBySlotId.get(binding.slotId);
+    mergedBindings.push(previousBinding ?? binding);
+    seenSlotIds.add(binding.slotId);
+  }
+  for (const slotId of preservePreviousSlotIds) {
+    if (seenSlotIds.has(slotId)) continue;
+    const previousBinding = previousBindingsBySlotId.get(slotId);
+    if (previousBinding) mergedBindings.push(previousBinding);
+  }
+  return normalizeAppElementsSlotBindings(mergedBindings, { layoutIds });
+}
+
 function reduceApprovedVisibleCommitState(
   state: AppRouterState,
   commit: ApprovedVisibleCommit,
@@ -119,6 +154,7 @@ function reduceApprovedVisibleCommitState(
             clearAbsentSlots: action.type === "traverse",
             preserveAbsentSlots: commit.decision.preserveAbsentSlots,
             preserveElementIds: commit.decision.preserveElementIds,
+            preservePreviousSlotIds: commit.decision.preservePreviousSlotIds,
           }),
           interceptionContext: action.interceptionContext,
           layoutFlags: mergeLayoutFlags(
@@ -132,6 +168,12 @@ function reduceApprovedVisibleCommitState(
           renderId: action.renderId,
           rootLayoutTreePath: action.rootLayoutTreePath,
           routeId: action.routeId,
+          slotBindings: mergeSlotBindings(
+            state.slotBindings,
+            action.slotBindings,
+            action.layoutIds,
+            commit.decision.preservePreviousSlotIds,
+          ),
         },
         action.operation,
       );
@@ -148,6 +190,7 @@ function reduceApprovedVisibleCommitState(
           renderId: action.renderId,
           rootLayoutTreePath: action.rootLayoutTreePath,
           routeId: action.routeId,
+          slotBindings: action.slotBindings,
         },
         action.operation,
       );
@@ -177,6 +220,7 @@ function resolvePendingNavigationCommitDecision(options: {
         decision.trace,
         decision.preserveElementIds,
         decision.preserveAbsentSlots,
+        decision.preservePreviousSlotIds,
       );
     default: {
       const _exhaustive: never = decision;
@@ -189,11 +233,13 @@ function createVisibleCommitDecision(
   trace: NavigationTrace = createNavigationTrace(NavigationTraceReasonCodes.commitCurrent),
   preserveElementIds: readonly string[] = [],
   preserveAbsentSlots: boolean = false,
+  preservePreviousSlotIds: readonly string[] = [],
 ): VisibleCommitDecision {
   return {
     disposition: "commit",
     preserveAbsentSlots,
     preserveElementIds: [...preserveElementIds],
+    preservePreviousSlotIds: [...preservePreviousSlotIds],
     trace,
   };
 }