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

package/src/browser/partial-update.ts

@@ -20,24 +20,23 @@ import {
 } 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";
 
-/** Build a scroll payload from the commit's scroll option */
 function toScrollPayload(
   scroll: boolean | undefined,
 ): NonNullable<NavigationUpdate["scroll"]> {
   return { enabled: scroll !== false ? scroll : false };
 }
 
-/**
- * Whether to wrap an update in startViewTransition.
- *
- * Intercept-driven updates only mutate the parallel slot — the main outlet
- * shows the same content — so transitions on the underlying main segments
- * shouldn't fire (otherwise their elements get hoisted above the modal).
- */
 function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
   let hasIntercept = false;
   let hasTransition = false;
@@ -61,13 +60,6 @@ export interface PartialUpdateConfig {
   ) => Promise<ReactNode> | ReactNode;
   /** RSC version getter — returns the current version (may change after HMR) */
   getVersion?: () => string | undefined;
-  /**
-   * Replace the active app-shell when a cross-app navigation is detected.
-   * Called before the full-update tree replacement renders, so the new
-   * payload's rootLayout, basename, and version are picked up. Theme,
-   * warmup, and prefetch TTL are not part of the shell — see AppShell.
-   */
-  applyAppShell?: (next: import("./app-shell.js").AppShell) => void;
 }
 
 /**
@@ -119,15 +111,6 @@ 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 {
@@ -137,24 +120,14 @@ export function createPartialUpdater(
     onUpdate,
     renderSegments,
     getVersion = () => undefined,
-    applyAppShell,
   } = 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,
@@ -166,117 +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();
 
     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.
-    // For leave-intercept, tx.currentUrl captures window.location.href at tx
-    // creation, which on popstate is already the destination URL and would
-    // tell the server "from == to". segmentState.currentUrl still points at
-    // the URL the cached segments render (the intercept URL), which is the
-    // correct "from" for the server's diff computation.
     const previousUrl =
       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) {
-      debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+    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?.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(", ")})`,
-    );
+    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: 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();
-    });
-
-    // Detect app switch: if routerId changed, the navigation crossed into
-    // a different router (e.g., via host router path mount). Downgrade
-    // partial to full so the entire tree is replaced without reconciliation
-    // against stale segments from the previous app, and replace the app
-    // shell (rootLayout, basename, version) so the target app's document
-    // and router config take effect instead of remaining captured from the
-    // initial load. Theme, warmup, and prefetch TTL are intentionally
-    // document-lifetime (see AppShell doc); a new document navigation
-    // applies them.
-    if (payload.metadata?.routerId) {
-      const prevRouterId = store.getRouterId?.();
-      if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
-        debugLog(
-          `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
-        );
-        payload.metadata.isPartial = false;
-        applyAppShell?.({
-          routerId: payload.metadata.routerId,
-          rootLayout: payload.metadata.rootLayout,
-          basename: payload.metadata.basename,
-          version: payload.metadata.version,
-        });
-      }
-      store.setRouterId?.(payload.metadata.routerId);
+    // 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,
@@ -298,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]));
@@ -309,7 +280,6 @@ 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) {
           debugLog(
             "[Browser] No diff but navigating with cached segments - rendering target route",
@@ -324,10 +294,6 @@ export function createPartialUpdater(
             existingSegments,
           );
 
-          // tx.commit() cached the source page's handleData because
-          // eventController hasn't been updated yet. Overwrite with the
-          // correct cached handleData to prevent cache corruption on
-          // subsequent navigations to this same URL.
           if (mode.targetCacheHandleData) {
             store.updateCacheHandleData(
               store.getHistoryKey(),
@@ -335,10 +301,6 @@ export function createPartialUpdater(
             );
           }
 
-          // 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 = {
@@ -365,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",
@@ -390,7 +351,6 @@ export function createPartialUpdater(
           return;
         }
 
-        // Same route revalidation with no changes - skip UI update
         debugLog(
           "[Browser] No changes - all revalidations returned false, keeping existing UI",
         );
@@ -399,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"
@@ -415,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),
@@ -437,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);
       }
 
@@ -452,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") {
@@ -500,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
@@ -521,7 +497,6 @@ export function createPartialUpdater(
         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) {
@@ -534,9 +509,22 @@ export function createPartialUpdater(
 
       debugLog("[partial-update] updating document");
 
-      // Emit update to trigger React render.
-      // Scroll info is included so NavigationProvider applies it after React commits.
       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") {
@@ -562,6 +550,20 @@ export function createPartialUpdater(
           });
         });
       } 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!,
@@ -572,7 +574,6 @@ export function createPartialUpdater(
       debugLog("[Browser] Navigation complete");
       return;
     } else {
-      // Full update (fallback)
       console.warn(`[Browser] Full update (fallback)`);
 
       const segments = payload.metadata?.segments || [];
@@ -603,6 +604,18 @@ export function createPartialUpdater(
 
       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");
@@ -614,7 +627,7 @@ export function createPartialUpdater(
           });
         });
       } else if (mode.type === "action") {
-        startTransition(async () => {
+        startTransition(() => {
           if (fullHasTransition && addTransitionType) {
             addTransitionType("action");
           }