@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.bdaf10aa

package/src/browser/partial-update.ts

@@ -14,11 +14,38 @@ const addTransitionType: ((type: string) => void) | 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 } from "./intercept-utils.js";
+import {
+  hasActiveIntercept as hasActiveInterceptSlots,
+  isInterceptSegment,
+} from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
-import { debugLog } from "./logging.js";
-import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import {
+  debugLog,
+  isBrowserDebugEnabled,
+  IS_BROWSER_DEBUG,
+} from "./logging.js";
+import {
+  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
@@ -31,8 +58,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;
 }
 
 /**
@@ -68,7 +95,7 @@ export type UpdateMode =
       /** Source URL for intercept restore (popstate cache miss) */
       interceptSourceUrl?: string;
     }
-  | { type: "leave-intercept" }
+  | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
   | { type: "action"; interceptSourceUrl?: string };
 
@@ -84,35 +111,23 @@ export type PartialUpdater = (
   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
- */
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
-  const { store, client, onUpdate, renderSegments, version } = config;
+  const {
+    store,
+    client,
+    onUpdate,
+    renderSegments,
+    getVersion = () => undefined,
+  } = config;
 
-  /**
-   * Get current page's cached segments as an array
-   */
   function getCurrentCachedSegments(): ResolvedSegment[] {
     const currentKey = store.getHistoryKey();
     const cached = store.getCachedSegments(currentKey);
     return cached?.segments || [];
   }
 
-  /**
-   * Fetch partial update and trigger UI update
-   *
-   * @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,
@@ -124,86 +139,114 @@ export function createPartialUpdater(
     const segmentState = store.getSegmentState();
     const url = targetUrl || window.location.href;
 
-    // Capture history key at start for stale revalidation consistency check
     const historyKeyAtStart = store.getHistoryKey();
 
-    // Derive interceptSourceUrl from modes that carry it
-    const interceptSourceUrl =
-      mode.type === "stale-revalidation" ||
-      mode.type === "action" ||
-      mode.type === "navigate"
-        ? mode.interceptSourceUrl
-        : undefined;
+    const interceptSourceUrl = mode.interceptSourceUrl;
 
-    // When leaving intercept, filter out intercept-specific segments
     let segments: string[];
     if (mode.type === "leave-intercept") {
       const currentSegments = segmentIds ?? segmentState.currentSegmentIds;
       const currentCached = getCurrentCachedSegments();
       const interceptIds = new Set(
-        currentCached
-          .filter((s) => s.namespace?.startsWith("intercept:"))
-          .map((s) => s.id),
+        currentCached.filter(isInterceptSegment).map((s) => s.id),
       );
       segments = currentSegments.filter((id) => !interceptIds.has(id));
-      debugLog(
-        `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
-      );
+      if (IS_BROWSER_DEBUG) {
+        debugLog(
+          `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
+        );
+      }
     } else {
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // For intercept revalidation, use the intercept source URL as previousUrl
     const previousUrl =
-      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) {
-      debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+      mode.type === "leave-intercept"
+        ? segmentState.currentUrl || tx.currentUrl
+        : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+
+    if (IS_BROWSER_DEBUG) {
+      debugLog(`\n[Browser] >>> NAVIGATION`);
+      debugLog(`[Browser] From: ${previousUrl}`);
+      debugLog(`[Browser] To: ${url}`);
+      debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
+      if (interceptSourceUrl) {
+        debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+      }
     }
 
-    // Get cached segments for merging with server diff.
-    // When navigating with targetCacheSegments, use those for consistency.
-    // Otherwise fall back to current page's segments (for same-route revalidation).
     const targetCache =
-      mode.type === "navigate" ? mode.targetCacheSegments : undefined;
-    const cachedSegs =
-      targetCache && targetCache.length > 0
-        ? targetCache
-        : getCurrentCachedSegments();
+      mode.type === "navigate" && mode.targetCacheSegments?.length
+        ? mode.targetCacheSegments
+        : undefined;
+    const cachedSegs = targetCache ?? getCurrentCachedSegments();
+    const cachedSegsSource = targetCache ? "history-cache" : "current-page";
+    if (IS_BROWSER_DEBUG) {
+      debugLog(
+        `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+      );
+    }
 
-    // Fetch partial payload (no abort signal - RSC doesn't support it well)
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
     fetchResult = await client.fetchPartial({
       targetUrl: url,
       segmentIds: segments,
       previousUrl,
-      // Mark stale when explicitly requested OR when no segments are sent
-      // (action redirect sends empty segments for a fresh render).
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
-      version,
+      version: getVersion(),
+      routerId: store.getRouterId?.(),
     });
-    // Mark navigation as streaming (response received, now parsing RSC).
-    // Called after fetchPartial so pendingUrl stays set during the network wait,
-    // allowing useLinkStatus to show per-link pending indicators.
     const streamingToken = tx.startStreaming();
-    const { payload, streamComplete: rawStreamComplete } = fetchResult;
+    const {
+      payload,
+      streamComplete: rawStreamComplete,
+      fullyPrefetched,
+    } = fetchResult;
     debugLog("payload.metadata", payload.metadata);
 
-    const streamComplete = rawStreamComplete.then(() => {
-      streamingToken.end();
-    });
+    // 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;
+    }
 
-    // Handle server-side redirect with state
     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,
@@ -225,10 +268,11 @@ export function createPartialUpdater(
         return;
       }
 
-      debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
-      debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+      if (IS_BROWSER_DEBUG) {
+        debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
+        debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+      }
 
-      // If diff is empty, nothing changed on server side.
       if (!diff || diff.length === 0) {
         const matchedIds = matched || [];
         const cacheMap = new Map(cachedSegs.map((s) => [s.id, s]));
@@ -236,8 +280,7 @@ export function createPartialUpdater(
           .map((id: string) => cacheMap.get(id))
           .filter(Boolean) as ResolvedSegment[];
 
-        // When navigating with cached segments to a different route, render them.
-        if (mode.type === "navigate" && targetCache && targetCache.length > 0) {
+        if (mode.type === "navigate" && targetCache) {
           debugLog(
             "[Browser] No diff but navigating with cached segments - rendering target route",
           );
@@ -246,12 +289,18 @@ export function createPartialUpdater(
             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.
-          // Remove `handles` from metadata to prevent NavigationProvider from
-          // processing an empty handles stream, which would clear the cached breadcrumbs.
           const { handles: _unusedHandles, ...metadataWithoutHandles } =
             payload.metadata!;
           const cachedUpdate = {
@@ -260,12 +309,10 @@ export function createPartialUpdater(
               ...metadataWithoutHandles,
               cachedHandleData: mode.targetCacheHandleData,
             },
+            scroll: toScrollPayload(commitScroll),
           };
 
-          const cachedHasTransition = existingSegments.some(
-            (s) => s.transition,
-          );
-          if (cachedHasTransition) {
+          if (shouldStartViewTransition(existingSegments)) {
             startTransition(() => {
               if (addTransitionType) {
                 addTransitionType("navigation");
@@ -280,7 +327,6 @@ export function createPartialUpdater(
           return;
         }
 
-        // When leaving intercept, force re-render even with empty diff
         if (mode.type === "leave-intercept") {
           debugLog(
             "[Browser] Leaving intercept - forcing re-render to remove modal",
@@ -290,18 +336,21 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: leaveScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
+            scroll: toScrollPayload(leaveScroll),
           });
 
           debugLog("[Browser] Navigation complete (left intercept)");
           return;
         }
 
-        // Same route revalidation with no changes - skip UI update
         debugLog(
           "[Browser] No changes - all revalidations returned false, keeping existing UI",
         );
@@ -310,7 +359,6 @@ export function createPartialUpdater(
         return;
       }
 
-      // Reconcile server segments with cached segments (single source of truth)
       const matchedIds = matched || [];
       const actor: ReconcileActor =
         mode.type === "stale-revalidation" || mode.type === "action"
@@ -326,7 +374,6 @@ export function createPartialUpdater(
         insertMissingDiff: true,
       });
 
-      // HMR RESILIENCE: Check if we're missing any matched segments
       const reconciledIdSet = new Set(reconciled.segments.map((s) => s.id));
       const missingIds = matchedIds.filter(
         (id: string) => !reconciledIdSet.has(id),
@@ -348,13 +395,19 @@ export function createPartialUpdater(
           return;
         }
         if (mode.type === "action") {
+          // An action refetch that lands on missing segments (navigated away /
+          // consolidation / HMR) drops rather than refetch-all: the action flow
+          // is storeOnly / skipLoadingState, so a full refetch here would fight
+          // it. Keep the stale-but-consistent tree; log so the drop is visible.
+          debugLog(
+            `[Browser] Action refetch: ${missingCount} segments missing; dropping (stale-but-consistent tree kept).`,
+          );
           return;
         }
         console.warn(
           `[Browser] HMR detected: Missing ${missingCount} segments. Refetching all...`,
         );
 
-        // Refetch with empty segments = server sends everything
         return fetchPartialUpdate(url, [], true, signal, tx, mode);
       }
 
@@ -363,44 +416,59 @@ export function createPartialUpdater(
         return;
       }
 
-      // Rebuild tree on client (await for loader data resolution)
       const renderOptions = {
         isAction: mode.type === "action",
-        forceAwait: mode.type === "stale-revalidation",
+        // 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:
           reconciled.interceptSegments.length > 0
             ? reconciled.interceptSegments
             : undefined,
       };
-      const newTree = await (signal
-        ? Promise.race([
+      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),
-            new Promise<never>((_, reject) => {
-              if (signal.aborted) {
-                reject(new DOMException("Navigation aborted", "AbortError"));
-              }
-              signal.addEventListener("abort", () => {
-                reject(new DOMException("Navigation aborted", "AbortError"));
-              });
-            }),
-          ])
-        : renderSegments(reconciled.mainSegments, renderOptions));
-
-      // Final abort check before committing - another navigation may have started
+            abortPromise,
+          ]);
+        } finally {
+          if (onAbort) signal.removeEventListener("abort", onAbort);
+        }
+      } else {
+        newTree = await renderSegments(reconciled.mainSegments, renderOptions);
+      }
+
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
         return;
       }
 
-      // Check if this is an intercept response (any slot is active)
       const isInterceptResponse = hasActiveInterceptSlots(
         payload.metadata?.slots,
       );
 
-      // Track intercept context (only on navigation, not actions or stale revalidation)
-      // Use the authoritative source from mode/history state when restoring an
-      // intercept via popstate cache miss; fall back to the current URL for fresh
-      // intercept navigations.
       const effectiveInterceptSource =
         interceptSourceUrl || segmentState.currentUrl;
       if (mode.type !== "action" && mode.type !== "stale-revalidation") {
@@ -411,9 +479,6 @@ export function createPartialUpdater(
         }
       }
 
-      // Commit navigation - use server's matched as the authoritative segment ID list.
-      // reconciled.segments may be missing IDs (e.g., loader segments not in diff or cache)
-      // but the server's matched always includes all expected segment IDs.
       const allSegmentIds = matchedIds;
       const serverLocationState = payload.metadata?.locationState;
       const overrides: CommitOverrides | undefined = isInterceptResponse
@@ -426,9 +491,12 @@ export function createPartialUpdater(
         : serverLocationState
           ? { serverState: serverLocationState }
           : undefined;
-      tx.commit(allSegmentIds, reconciled.segments, overrides);
+      const { scroll: navScroll } = tx.commit(
+        allSegmentIds,
+        reconciled.segments,
+        overrides,
+      );
 
-      // For stale revalidation: verify history key hasn't changed before updating UI
       if (mode.type === "stale-revalidation") {
         const historyKeyNow = store.getHistoryKey();
         if (historyKeyNow !== historyKeyAtStart) {
@@ -441,8 +509,23 @@ export function createPartialUpdater(
 
       debugLog("[partial-update] updating document");
 
-      // Emit update to trigger React render
-      const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+      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);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
         startTransition(() => {
@@ -452,6 +535,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else if (hasTransition) {
@@ -462,19 +546,34 @@ export function createPartialUpdater(
           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,
         });
       }
 
       debugLog("[Browser] Navigation complete");
       return;
     } else {
-      // Full update (fallback)
       console.warn(`[Browser] Full update (fallback)`);
 
       const segments = payload.metadata?.segments || [];
@@ -494,18 +593,29 @@ export function createPartialUpdater(
       }
 
       const fullUpdateServerState = payload.metadata?.locationState;
-      if (fullUpdateServerState) {
-        tx.commit(segmentIds, segments, { serverState: fullUpdateServerState });
-      } else {
-        tx.commit(segmentIds, segments);
-      }
+      const { scroll: fullScroll } = fullUpdateServerState
+        ? tx.commit(segmentIds, segments, {
+            serverState: fullUpdateServerState,
+          })
+        : tx.commit(segmentIds, segments);
 
-      const fullHasTransition = segments.some(
-        (s: ResolvedSegment) => s.transition,
-      );
+      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");
@@ -513,16 +623,18 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (mode.type === "action") {
-        startTransition(async () => {
+        startTransition(() => {
           if (fullHasTransition && addTransitionType) {
             addTransitionType("action");
           }
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (fullHasTransition) {
@@ -533,12 +645,14 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: fullScrollPayload,
         });
       }