@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/browser/partial-update.ts

@@ -5,15 +5,43 @@ import type {
   ResolvedSegment,
 } from "./types.js";
 import type { ReactNode } from "react";
+import * as React from "react";
 import { startTransition } from "react";
+
+// addTransitionType is only available in React experimental
+const addTransitionType: ((type: string) => void) | undefined =
+  "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 import type { RenderSegmentsOptions } from "../segment-system.js";
+import { reconcileSegments } from "./segment-reconciler.js";
+import type { ReconcileActor } from "./segment-reconciler.js";
+import {
+  hasActiveIntercept as hasActiveInterceptSlots,
+  isInterceptSegment,
+} from "./intercept-utils.js";
+import type { BoundTransaction } from "./navigation-transaction.js";
+import { ServerRedirect } from "../errors.js";
+import { debugLog, isBrowserDebugEnabled } from "./logging.js";
 import {
-  mergeSegmentLoaders,
-  needsLoaderMerge,
-  insertMissingDiffSegments,
-} from "./merge-segment-loaders.js";
-import { assertSegmentStructure } from "./segment-structure-assert.js";
-import type { BoundTransaction } from "./navigation-bridge.js";
+  validateRedirectOrigin,
+  validateExternalRedirect,
+} from "./validate-redirect-origin.js";
+import type { NavigationUpdate } from "./types.js";
+
+function toScrollPayload(
+  scroll: boolean | undefined,
+): NonNullable<NavigationUpdate["scroll"]> {
+  return { enabled: scroll !== false ? scroll : false };
+}
+
+function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
+  let hasIntercept = false;
+  let hasTransition = false;
+  for (const s of segments) {
+    if (isInterceptSegment(s)) hasIntercept = true;
+    else if (s.transition) hasTransition = true;
+  }
+  return !hasIntercept && hasTransition;
+}
 
 /**
  * Configuration for creating a partial updater
@@ -26,8 +54,8 @@ export interface PartialUpdateConfig {
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
-  /** RSC version received from server (from initial payload metadata) */
-  version?: string;
+  /** RSC version getter — returns the current version (may change after HMR) */
+  getVersion?: () => string | undefined;
 }
 
 /**
@@ -42,12 +70,30 @@ export interface CommitOverrides {
   intercept?: boolean;
   /** Source URL where intercept was triggered from */
   interceptSourceUrl?: string;
+  /** Server-set location state to merge into history.pushState */
+  serverState?: Record<string, unknown>;
 }
 
 /**
- * Commit context passed to partial updater for URL updates
- * Transaction encapsulates all store mutations for atomic commit
+ * Discriminated update mode for partial updates.
  */
+export type UpdateMode =
+  | {
+      type: "navigate";
+      /** Cached segments for the target URL. When provided, these are used to build
+       * the segment map instead of the current page's segments. This ensures consistency
+       * when we send cached segment IDs to the server - if the server returns empty diff,
+       * we use the same segments we told the server we have. */
+      targetCacheSegments?: ResolvedSegment[];
+      /** Cached handle data for the target URL. When server returns empty diff and we're
+       * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
+      targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
+      /** Source URL for intercept restore (popstate cache miss) */
+      interceptSourceUrl?: string;
+    }
+  | { type: "leave-intercept"; interceptSourceUrl?: string }
+  | { type: "stale-revalidation"; interceptSourceUrl?: string }
+  | { type: "action"; interceptSourceUrl?: string };
 
 /**
  * Type for the fetchPartialUpdate function
@@ -57,320 +103,268 @@ export type PartialUpdater = (
   segmentIds: string[] | undefined,
   isRetry: boolean,
   signal: AbortSignal | undefined,
-  type: BoundTransaction,
-  options?: {
-    isAction?: boolean;
-    staleRevalidation?: boolean;
-    interceptSourceUrl?: string;
-    /** Cached segments for the target URL. When provided, these are used to build
-     * the segment map instead of the current page's segments. This ensures consistency
-     * when we send cached segment IDs to the server - if the server returns empty diff,
-     * we use the same segments we told the server we have. */
-    targetCacheSegments?: ResolvedSegment[];
-    /** Cached handle data for the target URL. When server returns empty diff and we're
-     * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
-    targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
-    /** When true, we're leaving an intercept state - don't use current segment IDs
-     * as fallback and force a fresh render from server */
-    leavingIntercept?: boolean;
-  },
-) => Promise<Promise<void>>;
+  tx: BoundTransaction,
+  mode?: UpdateMode,
+) => Promise<void>;
 
-/**
- * Create a partial updater for fetching and applying RSC partial updates
- *
- * This function is shared between navigation-bridge and server-action-bridge
- * to handle partial RSC updates with HMR resilience.
- *
- * @param config - Partial update configuration
- * @returns fetchPartialUpdate function
- *
- * @example
- * ```typescript
- * const fetchPartialUpdate = createPartialUpdater({
- *   store,
- *   client,
- *   onUpdate: (update) => store.emit(update),
- *   renderSegments,
- * });
- *
- * await fetchPartialUpdate('/new-page');
- * ```
- */
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
-  const { store, client, onUpdate, renderSegments, version } = config;
-
-  /**
-   * Build a lookup map from current page's cached segments
-   */
-  function getCurrentSegmentMap(): Map<string, ResolvedSegment> {
+  const {
+    store,
+    client,
+    onUpdate,
+    renderSegments,
+    getVersion = () => undefined,
+  } = config;
+
+  function getCurrentCachedSegments(): ResolvedSegment[] {
     const currentKey = store.getHistoryKey();
     const cached = store.getCachedSegments(currentKey);
-    const cachedSegments = cached?.segments || [];
-    const map = new Map<string, ResolvedSegment>();
-    cachedSegments.forEach((s) => map.set(s.id, s));
-    return map;
+    return cached?.segments || [];
   }
 
-  /**
-   * Fetch partial update and trigger UI update
-   * Returns a promise that resolves when the RSC stream is fully consumed
-   *
-   * @param tx - Transaction for committing segment state (required)
-   * @param signal - AbortSignal to check if navigation is stale (not for aborting fetch)
-   */
   async function fetchPartialUpdate(
     targetUrl: string,
     segmentIds: string[] | undefined,
     isRetry: boolean,
     signal: AbortSignal | undefined,
     tx: BoundTransaction,
-    options?: {
-      isAction?: boolean;
-      staleRevalidation?: boolean;
-      interceptSourceUrl?: string;
-      targetCacheSegments?: ResolvedSegment[];
-      targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
-      leavingIntercept?: boolean;
-    },
-  ): Promise<Promise<void>> {
-    const {
-      isAction = false,
-      staleRevalidation = false,
-      interceptSourceUrl,
-      targetCacheSegments,
-      targetCacheHandleData,
-      leavingIntercept = false,
-    } = options || {};
+    mode: UpdateMode = { type: "navigate" },
+  ): Promise<void> {
     const segmentState = store.getSegmentState();
     const url = targetUrl || window.location.href;
 
-    // Capture history key at start for stale revalidation consistency check
     const historyKeyAtStart = store.getHistoryKey();
 
-    // When leaving intercept, don't send current segment IDs - we need fresh non-intercept segments
-    // Filter out intercept-related segments (parallel slots like @modal) from current segments
+    const interceptSourceUrl = mode.interceptSourceUrl;
+
     let segments: string[];
-    if (leavingIntercept) {
-      // When leaving intercept, only send segments that aren't intercept-specific
-      // The server will return the non-intercept version of the route
+    if (mode.type === "leave-intercept") {
       const currentSegments = segmentIds ?? segmentState.currentSegmentIds;
-      // Filter out intercept-specific parallel slots (containing ".@") so the
-      // server resolves the base route instead of the modal overlay.
-      segments = currentSegments.filter((id) => !id.includes(".@"));
-      console.log(
+      const currentCached = getCurrentCachedSegments();
+      const interceptIds = new Set(
+        currentCached.filter(isInterceptSegment).map((s) => s.id),
+      );
+      segments = currentSegments.filter((id) => !interceptIds.has(id));
+      debugLog(
         `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
       );
     } else {
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // For intercept revalidation, use the intercept source URL as previousUrl
-    // This tells the server the route should be treated as an intercept
     const previousUrl =
-      interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
-
-    console.log(`\n[Browser] >>> NAVIGATION`);
-    console.log(`[Browser] From: ${previousUrl}`);
-    console.log(`[Browser] To: ${url}`);
-    console.log(`[Browser] Segments to send: ${segments.join(", ")}`);
+      mode.type === "leave-intercept"
+        ? segmentState.currentUrl || tx.currentUrl
+        : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+
+    debugLog(`\n[Browser] >>> NAVIGATION`);
+    debugLog(`[Browser] From: ${previousUrl}`);
+    debugLog(`[Browser] To: ${url}`);
+    debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
     if (interceptSourceUrl) {
-      console.log(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+      debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
     }
 
-    // Build segment map for merging with server diff.
-    // When targetCacheSegments is provided (navigating to a cached route), use those
-    // to ensure consistency - we use the same segments we told the server we have.
-    // Otherwise fall back to current page's segments (for same-route revalidation).
-    let currentSegmentMap: Map<string, ResolvedSegment>;
-    if (targetCacheSegments && targetCacheSegments.length > 0) {
-      currentSegmentMap = new Map();
-      targetCacheSegments.forEach((s) => currentSegmentMap.set(s.id, s));
-    } else {
-      currentSegmentMap = getCurrentSegmentMap();
-    }
-    // Mark navigation as streaming (response received, now parsing RSC)
-    // The token is ended when the stream completes
+    const targetCache =
+      mode.type === "navigate" && mode.targetCacheSegments?.length
+        ? mode.targetCacheSegments
+        : undefined;
+    const cachedSegs = targetCache ?? getCurrentCachedSegments();
+    const cachedSegsSource = targetCache ? "history-cache" : "current-page";
+    debugLog(
+      `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+    );
+
+    let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
+    fetchResult = await client.fetchPartial({
+      targetUrl: url,
+      segmentIds: segments,
+      previousUrl,
+      staleRevalidation:
+        mode.type === "stale-revalidation" || segments.length === 0,
+      version: getVersion(),
+      routerId: store.getRouterId?.(),
+    });
     const streamingToken = tx.startStreaming();
-    // Fetch partial payload (no abort signal - RSC doesn't support it well)
-    const { payload, streamComplete: rawStreamComplete } =
-      await client.fetchPartial({
-        targetUrl: url,
-        segmentIds: segments,
-        previousUrl,
-        staleRevalidation,
-        version,
-      });
-    console.log("payload.metadata", payload.metadata);
+    const {
+      payload,
+      streamComplete: rawStreamComplete,
+      fullyPrefetched,
+    } = fetchResult;
+    debugLog("payload.metadata", payload.metadata);
+
+    // Side effect only: end the streaming token once the stream settles.
+    // The wrapped promise was never read as a value; only the .end() matters.
+    // The .catch keeps an unhandled rejection from leaking if the stream errors.
+    rawStreamComplete.then(() => streamingToken.end()).catch(() => {});
+
+    const currentRouterId = store.getRouterId?.();
+    if (
+      payload.metadata?.routerId &&
+      currentRouterId &&
+      payload.metadata.routerId !== currentRouterId
+    ) {
+      console.error(
+        `[rango] Partial response router id "${payload.metadata.routerId}" does not ` +
+          `match this client ("${currentRouterId}"); discarding it and reloading to re-sync.`,
+      );
+      window.location.href = url;
+      return;
+    }
 
-    const streamComplete = rawStreamComplete.then(() => {
-      streamingToken.end();
-    });
+    if (payload.metadata?.redirect) {
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale redirect (aborted)");
+        return;
+      }
+      // Explicit off-host redirect (redirect(url, { external: true })):
+      // hard-navigate, but still scheme-validate (http/https only). external
+      // waives the same-origin check the app opted out of, NOT scheme safety, so
+      // a forged payload carrying a javascript:/data: URL cannot script via
+      // location.assign.
+      if (payload.metadata.redirect.external) {
+        const externalUrl = validateExternalRedirect(
+          payload.metadata.redirect.url,
+          window.location.origin,
+        );
+        if (!externalUrl) {
+          debugLog("[Browser] Ignoring blocked external redirect payload");
+          return;
+        }
+        debugLog("[Browser] External redirect (hard navigation)");
+        window.location.assign(externalUrl);
+        return;
+      }
+      const redirectUrl = validateRedirectOrigin(
+        payload.metadata.redirect.url,
+        window.location.origin,
+      );
+      if (!redirectUrl) {
+        debugLog("[Browser] Ignoring blocked redirect payload");
+        return;
+      }
+      const serverState = payload.metadata.locationState;
+      throw new ServerRedirect(redirectUrl, serverState);
+    }
 
     if (payload.metadata?.isPartial) {
       const { segments: newSegments, matched, diff } = payload.metadata;
 
       // Check if this navigation is stale (a newer one started)
       if (signal?.aborted) {
-        console.log(`[Browser] Ignoring stale navigation (aborted)`);
-        return streamComplete;
+        debugLog("[Browser] Ignoring stale navigation (aborted)");
+        return;
       }
 
-      console.log(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
-      console.log(`[Browser] Diff: ${diff?.join(", ")}`);
-
-      // Create lookup for new segments from server
-      const newSegmentMap = new Map<string, ResolvedSegment>();
-      (newSegments || []).forEach((s: ResolvedSegment) =>
-        newSegmentMap.set(s.id, s),
-      );
+      debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
+      debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
 
-      // If diff is empty, nothing changed on server side.
-      // However, if we're navigating with targetCacheSegments (to a different route),
-      // we still need to render those segments since the UI is showing the old route.
       if (!diff || diff.length === 0) {
         const matchedIds = matched || [];
+        const cacheMap = new Map(cachedSegs.map((s) => [s.id, s]));
         const existingSegments = matchedIds
-          .map((id: string) => currentSegmentMap.get(id))
+          .map((id: string) => cacheMap.get(id))
           .filter(Boolean) as ResolvedSegment[];
 
-        // When navigating with cached segments to a different route, render them.
-        // targetCacheSegments being provided means we're navigating to a cached route.
-        if (targetCacheSegments && targetCacheSegments.length > 0) {
-          console.log(
-            `[Browser] No diff but navigating with cached segments - rendering target route`,
+        if (mode.type === "navigate" && targetCache) {
+          debugLog(
+            "[Browser] No diff but navigating with cached segments - rendering target route",
           );
 
           const newTree = await renderSegments(existingSegments, {
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: commitScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
+
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
 
-          // Include cachedHandleData in metadata so NavigationProvider can restore
-          // breadcrumbs and other handle data from cache.
-          // IMPORTANT: Remove `handles` from metadata to prevent NavigationProvider from
-          // processing an empty handles stream, which would clear the cached breadcrumbs.
-          // When rendering from cache with empty diff, we want to use cachedHandleData instead.
           const { handles: _unusedHandles, ...metadataWithoutHandles } =
             payload.metadata!;
-          onUpdate({
+          const cachedUpdate = {
             root: newTree,
             metadata: {
               ...metadataWithoutHandles,
-              cachedHandleData: targetCacheHandleData,
+              cachedHandleData: mode.targetCacheHandleData,
             },
-          });
+            scroll: toScrollPayload(commitScroll),
+          };
 
-          console.log(`[Browser] Navigation complete (rendered from cache)\n`);
-          return streamComplete;
+          if (shouldStartViewTransition(existingSegments)) {
+            startTransition(() => {
+              if (addTransitionType) {
+                addTransitionType("navigation");
+              }
+              onUpdate(cachedUpdate);
+            });
+          } else {
+            onUpdate(cachedUpdate);
+          }
+
+          debugLog("[Browser] Navigation complete (rendered from cache)");
+          return;
         }
 
-        // When leaving intercept, force re-render even with empty diff
-        // The matched segments are the non-intercept segments, which we need to render
-        // to remove the modal from the UI
-        if (leavingIntercept) {
-          console.log(
-            `[Browser] Leaving intercept - forcing re-render to remove modal`,
+        if (mode.type === "leave-intercept") {
+          debugLog(
+            "[Browser] Leaving intercept - forcing re-render to remove modal",
           );
 
           const newTree = await renderSegments(existingSegments, {
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: leaveScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
+            scroll: toScrollPayload(leaveScroll),
           });
 
-          console.log(`[Browser] Navigation complete (left intercept)\n`);
-          return streamComplete;
+          debugLog("[Browser] Navigation complete (left intercept)");
+          return;
         }
 
-        // Same route revalidation with no changes - skip UI update
-        console.log(
-          `[Browser] No changes - all revalidations returned false, keeping existing UI`,
+        debugLog(
+          "[Browser] No changes - all revalidations returned false, keeping existing UI",
         );
         tx.commit(matchedIds, existingSegments);
-        console.log(`[Browser] Navigation complete (no re-render)\n`);
-        return streamComplete;
+        debugLog("[Browser] Navigation complete (no re-render)");
+        return;
       }
 
-      // Build full segment list by merging:
-      // - New/changed segments from server response (diff)
-      // - Unchanged segments from current page's cache
       const matchedIds = matched || [];
-      console.log(`[Browser] matchedIds: ${matchedIds.join(", ")}`);
-      console.log(
-        `[Browser] currentSegmentMap keys: ${[...currentSegmentMap.keys()].join(", ")}`,
-      );
-      console.log(
-        `[Browser] newSegmentMap keys: ${[...newSegmentMap.keys()].join(", ")}`,
-        newSegmentMap,
-      );
-
-      // First pass: build segments from matched IDs
-      const matchedIdSet = new Set(matchedIds);
-      const allSegments = matchedIds
-        .map((id: string) => {
-          // First check server response (new/updated segments)
-          const fromServer = newSegmentMap.get(id);
-          if (fromServer) {
-            // For partial revalidation (stale or action), merge server's new loader data
-            // with cached loader data when server returns fewer loaders than cached
-            const fromCache = currentSegmentMap.get(id);
-            // Dev-mode assertion: warn if tree structure would change
-            if (fromCache) {
-              assertSegmentStructure(fromCache, fromServer, "partial-update");
-            }
-            if (
-              (staleRevalidation || isAction) &&
-              needsLoaderMerge(fromServer, fromCache)
-            ) {
-              return mergeSegmentLoaders(fromServer, fromCache);
-            }
-            // When server returns component: null for a layout segment, it means
-            // "this segment doesn't need re-rendering" - preserve the cached component
-            // to maintain the outlet chain and prevent React tree changes
-            if (
-              fromServer.component === null &&
-              fromServer.type === "layout" &&
-              fromCache?.component != null
-            ) {
-              console.log(
-                `[Browser] Preserving cached component for layout ${id} (server returned null)`,
-              );
-              return { ...fromServer, component: fromCache.component };
-            }
-            return fromServer;
-          }
-          // Fall back to current page's cached segments
-          const fromCache = currentSegmentMap.get(id);
-          if (!fromCache) {
-            console.warn(`[Browser] Missing segment: ${id}`);
-            return fromCache;
-          }
-          // Clear loading for cached segments to prevent suspense - server decided
-          // this segment doesn't need re-rendering, so show content as-is
-          if (fromCache.loading !== undefined) {
-            return { ...fromCache, loading: undefined };
-          }
-          return fromCache;
-        })
-        .filter(Boolean) as ResolvedSegment[];
-
-      // Insert diff segments not in matchedIds (e.g., loader segments from consolidation fetch)
-      insertMissingDiffSegments(allSegments, diff, matchedIdSet, newSegmentMap);
+      const actor: ReconcileActor =
+        mode.type === "stale-revalidation" || mode.type === "action"
+          ? "stale-revalidation"
+          : "navigation";
+
+      const reconciled = reconcileSegments({
+        actor,
+        matched: matchedIds,
+        diff: diff || [],
+        serverSegments: newSegments || [],
+        cachedSegments: cachedSegs,
+        insertMissingDiff: true,
+      });
 
-      // HMR RESILIENCE: Check if we're missing any matched segments
-      // Note: allSegments may include additional diff segments, so we check matchedIds specifically
-      const allSegmentIdSet = new Set(allSegments.map((s) => s.id));
+      const reconciledIdSet = new Set(reconciled.segments.map((s) => s.id));
       const missingIds = matchedIds.filter(
-        (id: string) => !allSegmentIdSet.has(id),
+        (id: string) => !reconciledIdSet.has(id),
       );
 
       if (missingIds.length > 0) {
@@ -383,213 +377,267 @@ export function createPartialUpdater(
           );
         }
         if (signal?.aborted) {
-          console.log(
-            `[Browser] Ignoring stale navigation (aborted during HMR retry)`,
+          debugLog(
+            "[Browser] Ignoring stale navigation (aborted during HMR retry)",
           );
-          return streamComplete;
+          return;
         }
-        if (isAction) {
-          return streamComplete;
+        if (mode.type === "action") {
+          return;
         }
         console.warn(
           `[Browser] HMR detected: Missing ${missingCount} segments. Refetching all...`,
         );
 
-        // Refetch with empty segments = server sends everything
-        return fetchPartialUpdate(url, [], true, signal, tx, { isAction });
+        return fetchPartialUpdate(url, [], true, signal, tx, mode);
       }
 
-      // INTERCEPT HANDLING: Separate intercept segments for explicit injection
-      // Intercept segments have namespace starting with "intercept:" or ID containing .@
-      // This makes the flow clearer and easier to debug
-      const isInterceptSegment = (s: ResolvedSegment) =>
-        s.namespace?.startsWith("intercept:") ||
-        (s.type === "parallel" && s.id.includes(".@"));
-
-      const interceptSegments = allSegments.filter(isInterceptSegment);
-      const mainSegments = allSegments.filter((s) => !isInterceptSegment(s));
-
       if (signal?.aborted) {
-        console.log(
-          `[Browser] Ignoring stale navigation (aborted before render)`,
-        );
-        return streamComplete;
+        debugLog("[Browser] Ignoring stale navigation (aborted before render)");
+        return;
       }
 
-      // Rebuild tree on client (await for loader data resolution)
-      // Race against abort signal to allow cancellation during loader awaiting
-      // Pass intercept segments separately for explicit handling
-      // For stale revalidation, use forceAwait to ensure no loading fallbacks
       const renderOptions = {
-        isAction,
-        forceAwait: staleRevalidation,
+        isAction: mode.type === "action",
+        // forceAwait unwraps the ROUTER loader promises during render so they
+        // land without a loading()/fallback frame. A fully-prefetched nav has
+        // its router data already resolved (the prefetch stream drained), so
+        // awaiting it here is free and lets us commit NORMALLY (not in a
+        // transition) below — a normal commit still shows fallbacks for any
+        // CLIENT component that suspends on mount, which a transition would
+        // wrongly suppress by holding the old UI until that suspense settles.
+        forceAwait: mode.type === "stale-revalidation" || fullyPrefetched,
         interceptSegments:
-          interceptSegments.length > 0 ? interceptSegments : undefined,
+          reconciled.interceptSegments.length > 0
+            ? reconciled.interceptSegments
+            : undefined,
       };
-      const newTree = await (signal
-        ? Promise.race([
-            renderSegments(mainSegments, renderOptions),
-            new Promise<never>((_, reject) => {
-              if (signal.aborted) {
-                reject(new DOMException("Navigation aborted", "AbortError"));
-              }
-              signal.addEventListener("abort", () => {
-                reject(new DOMException("Navigation aborted", "AbortError"));
-              });
-            }),
-          ])
-        : renderSegments(mainSegments, renderOptions));
-
-      // Final abort check before committing - another navigation may have started
-      if (signal?.aborted) {
-        console.log(
-          `[Browser] Ignoring stale navigation (aborted before commit)`,
-        );
-        return streamComplete;
+      let newTree: Awaited<ReturnType<typeof renderSegments>>;
+      if (signal) {
+        // Race render against abort. Store the abort handler and register it
+        // { once:true } so a non-aborted render (which wins the race) can
+        // remove it in finally — otherwise the listener stays attached and the
+        // rejecting promise never settles. Mirrors teeWithCompletion in
+        // browser/response-adapter.ts.
+        let onAbort: (() => void) | undefined;
+        const abortPromise = new Promise<never>((_, reject) => {
+          if (signal.aborted) {
+            reject(new DOMException("Navigation aborted", "AbortError"));
+            return;
+          }
+          onAbort = () =>
+            reject(new DOMException("Navigation aborted", "AbortError"));
+          signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+          newTree = await Promise.race([
+            renderSegments(reconciled.mainSegments, renderOptions),
+            abortPromise,
+          ]);
+        } finally {
+          if (onAbort) signal.removeEventListener("abort", onAbort);
+        }
+      } else {
+        newTree = await renderSegments(reconciled.mainSegments, renderOptions);
       }
 
-      // Check if this is an intercept response (any slot is active)
-      // If so, disable scroll to keep the current scroll position
-      const hasActiveIntercept = payload.metadata?.slots
-        ? Object.values(payload.metadata.slots).some((slot) => slot.active)
-        : false;
-
-      // BUG FIX: When navigating with cached target segments but receiving an intercept response,
-      // the background segments should come from the SOURCE page (where we navigated from),
-      // not the TARGET cache. This happens when:
-      // 1. User visits /product/xxx (detail page) - cached under key "/product/xxx"
-      // 2. User navigates back to /
-      // 3. User clicks product link → cache hit for "/product/xxx" (detail page)
-      // 4. But server returns intercept response (modal with index background)
-      // 5. Without this fix: background uses detail page segments (wrong!)
-      // 6. With this fix: rebuild currentSegmentMap from source page
-      if (hasActiveIntercept && targetCacheSegments) {
-        console.log(
-          `[Browser] Intercept response with target cache - rebuilding segment map from source page`,
-        );
-        currentSegmentMap = getCurrentSegmentMap();
+      if (signal?.aborted) {
+        debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
+        return;
       }
 
-      // Track intercept context for action revalidation (only on navigation, not actions or stale revalidation)
-      if (!isAction && !staleRevalidation) {
-        if (hasActiveIntercept) {
-          // Save the source URL for action revalidation to maintain intercept context
-          store.setInterceptSourceUrl(segmentState.currentUrl);
+      const isInterceptResponse = hasActiveInterceptSlots(
+        payload.metadata?.slots,
+      );
+
+      const effectiveInterceptSource =
+        interceptSourceUrl || segmentState.currentUrl;
+      if (mode.type !== "action" && mode.type !== "stale-revalidation") {
+        if (isInterceptResponse) {
+          store.setInterceptSourceUrl(effectiveInterceptSource);
         } else {
-          // Clear intercept context when navigating to a non-intercept route
           store.setInterceptSourceUrl(null);
         }
       }
 
-      // Commit navigation - transaction handles all store mutations atomically
-      // For intercept responses: disable scroll, mark as intercept, include source URL
-      // Use allSegmentIds (derived from allSegments) instead of matchedIds because
-      // we may have added diff segments (like loader segments) not in the matched array
-      const allSegmentIds = allSegments.map((s) => s.id);
-      tx.commit(
+      const allSegmentIds = matchedIds;
+      const serverLocationState = payload.metadata?.locationState;
+      const overrides: CommitOverrides | undefined = isInterceptResponse
+        ? {
+            scroll: false,
+            intercept: true,
+            interceptSourceUrl: effectiveInterceptSource,
+            ...(serverLocationState && { serverState: serverLocationState }),
+          }
+        : serverLocationState
+          ? { serverState: serverLocationState }
+          : undefined;
+      const { scroll: navScroll } = tx.commit(
         allSegmentIds,
-        allSegments,
-        hasActiveIntercept
-          ? {
-              scroll: false,
-              intercept: true,
-              interceptSourceUrl: segmentState.currentUrl,
-            }
-          : undefined,
+        reconciled.segments,
+        overrides,
       );
 
-      // For stale revalidation: verify history key hasn't changed before updating UI
-      // If user navigated away, skip UI update to avoid corrupting current view
-      if (staleRevalidation) {
+      if (mode.type === "stale-revalidation") {
         const historyKeyNow = store.getHistoryKey();
         if (historyKeyNow !== historyKeyAtStart) {
-          console.log(
+          debugLog(
             `[Browser] Stale revalidation: history key changed (${historyKeyAtStart} -> ${historyKeyNow}), skipping UI update`,
           );
-          return streamComplete;
+          return;
         }
       }
 
-      console.log("[partial-update] updating document");
+      debugLog("[partial-update] updating document");
+
+      const hasTransition = shouldStartViewTransition(reconciled.segments);
+      // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Reports which reconciled
+      // segment still carries a transition after the server-side when-gate, and
+      // whether the commit will be held in a startTransition. If `withTransition`
+      // lists an ancestor (layout/root) id rather than the gated leaf, an ungated
+      // ancestor transition is holding the subtree (missing loading() fallback).
+      if (isBrowserDebugEnabled()) {
+        debugLog("[VT-DIAG] commit", {
+          mode: mode.type,
+          hasTransition,
+          withTransition: reconciled.segments
+            .filter((s) => s.transition)
+            .map((s) => s.id),
+          all: reconciled.segments.map((s) => s.id),
+        });
+      }
+      const scrollPayload = toScrollPayload(navScroll);
 
-      // Emit update to trigger React render
-      // For stale revalidation: wait for stream to complete (loaders resolved), then update
-      // For actions: wrap in startTransition to avoid UI flickering
-      if (isAction || staleRevalidation) {
+      if (mode.type === "action" || mode.type === "stale-revalidation") {
+        startTransition(() => {
+          if (hasTransition && addTransitionType) {
+            addTransitionType("action");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+            scroll: scrollPayload,
+          });
+        });
+      } else if (hasTransition) {
         startTransition(() => {
+          if (addTransitionType) {
+            addTransitionType("navigation");
+          }
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else {
+        // Normal commit (cold/partial nav AND fully-prefetched nav). For a
+        // fully-prefetched nav, renderOptions.forceAwait (above) unwrapped the
+        // already-resolved ROUTER loader data AND route content during render, so
+        // the new tree carries it inline with no loading()/fallback frame — yet we
+        // still commit NORMALLY here rather than in a transition. A transition
+        // holds the OLD UI until ALL suspense in the new tree settles, including a
+        // CLIENT component that starts its own data request only when mounted
+        // (post-commit) under a persistent boundary; that would retain the
+        // previous page indefinitely with no feedback. A normal commit lets such
+        // client-initiated suspense reveal a fallback (correct) while the router
+        // data — genuinely ready — never flashes. Cold/partial navs
+        // (fullyPrefetched=false) do not forceAwait, so they stream their
+        // fallbacks. Explicit transition() routes keep the broader content-hold
+        // via the hasTransition branch above (the documented opt-in).
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: scrollPayload,
         });
       }
 
-      console.log(`[Browser] Navigation complete\n`);
-      return streamComplete;
+      debugLog("[Browser] Navigation complete");
+      return;
     } else {
-      // Full update (fallback)
-      // Use client-side renderSegments instead of payload.root to ensure
-      // consistent component references with action revalidation.
-      // Server-rendered RSC tree has different component references than
-      // client-created tree, which causes React to remount LoaderBoundary
-      // when actions trigger revalidation.
       console.warn(`[Browser] Full update (fallback)`);
 
       const segments = payload.metadata?.segments || [];
 
-      // Check if this navigation is stale (a newer one started)
       if (signal?.aborted) {
-        console.log(`[Browser] Ignoring stale navigation (aborted)`);
-        return streamComplete;
+        debugLog("[Browser] Ignoring stale navigation (aborted)");
+        return;
       }
 
       const segmentIds = segments.map((s: ResolvedSegment) => s.id);
 
-      // Render on client for consistent component references
       const newTree = await renderSegments(segments);
 
-      // Final abort check before committing - another navigation may have started
       if (signal?.aborted) {
-        console.log(
-          `[Browser] Ignoring stale navigation (aborted before commit)`,
-        );
-        return streamComplete;
+        debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
+        return;
       }
 
-      // Commit navigation - transaction handles all store mutations atomically
-      tx.commit(segmentIds, segments);
+      const fullUpdateServerState = payload.metadata?.locationState;
+      const { scroll: fullScroll } = fullUpdateServerState
+        ? tx.commit(segmentIds, segments, {
+            serverState: fullUpdateServerState,
+          })
+        : tx.commit(segmentIds, segments);
 
-      // Emit update to trigger React render
-      // For stale revalidation: wait for stream to complete, then update
-      // For actions: wrap in startTransition to avoid UI flickering
-      if (staleRevalidation) {
+      const fullHasTransition = shouldStartViewTransition(segments);
+      const fullScrollPayload = toScrollPayload(fullScroll);
+
+      if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
+        // Mirror the partial branch's history-key staleness guard (above): the
+        // await above is a real async suspension, so the user may have navigated
+        // away while this background revalidation was draining. Dropping a late
+        // full-update here prevents it from clobbering the freshly committed UI
+        // of the page the user moved to.
+        const historyKeyNow = store.getHistoryKey();
+        if (historyKeyNow !== historyKeyAtStart) {
+          debugLog(
+            `[Browser] Stale revalidation (full update): history key changed (${historyKeyAtStart} -> ${historyKeyNow}), skipping UI update`,
+          );
+          return;
+        }
+        startTransition(() => {
+          if (fullHasTransition && addTransitionType) {
+            addTransitionType("action");
+          }
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+            scroll: fullScrollPayload,
+          });
+        });
+      } else if (mode.type === "action") {
         startTransition(() => {
+          if (fullHasTransition && addTransitionType) {
+            addTransitionType("action");
+          }
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
-      } else if (isAction) {
-        startTransition(async () => {
+      } else if (fullHasTransition) {
+        startTransition(() => {
+          if (addTransitionType) {
+            addTransitionType("navigation");
+          }
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: fullScrollPayload,
         });
       }
 
-      return streamComplete;
+      return;
     }
   }