@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/browser/navigation-client.ts

@@ -11,6 +11,12 @@ import {
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.js";
+import { getRangoState } from "./rango-state.js";
+import {
+  extractRscHeaderUrl,
+  emptyResponse,
+  teeWithCompletion,
+} from "./response-adapter.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -84,7 +90,6 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
-
       if (tx) {
         browserDebugLog(tx, "fetching", {
           path: `${fetchUrl.pathname}${fetchUrl.search}`,
@@ -101,6 +106,7 @@ export function createNavigationClient(
       const responsePromise = fetch(fetchUrl, {
         headers: {
           "X-RSC-Router-Client-Path": previousUrl,
+          "X-Rango-State": getRangoState(),
           ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
@@ -110,25 +116,18 @@ export function createNavigationClient(
         signal,
       }).then((response) => {
         // Check for version mismatch - server wants us to reload
-        const reloadUrl = response.headers.get("X-RSC-Reload");
-        if (reloadUrl) {
-          // Validate origin to prevent open redirect via crafted headers
-          try {
-            const target = new URL(reloadUrl, window.location.origin);
-            if (target.origin !== window.location.origin) {
-              throw new Error(
-                `X-RSC-Reload blocked: origin mismatch (${target.origin})`,
-              );
-            }
-          } catch (e) {
-            console.error("[rango]", e);
-            return response;
-          }
+        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+        if (reload === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
+        }
+        if (reload) {
           if (tx) {
-            browserDebugLog(tx, "version mismatch, reloading", { reloadUrl });
+            browserDebugLog(tx, "version mismatch, reloading", {
+              reloadUrl: reload.url,
+            });
           }
-          window.location.href = reloadUrl;
-          // Return a never-resolving promise to prevent further processing
+          window.location.href = reload.url;
           return new Promise<Response>(() => {});
         }
 
@@ -136,56 +135,29 @@ export function createNavigationClient(
         // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
         // to a URL rendering full HTML). Throw ServerRedirect so the
         // navigation bridge catches it and re-navigates with _skipCache.
-        const redirectUrl = response.headers.get("X-RSC-Redirect");
-        if (redirectUrl) {
-          if (tx) {
-            browserDebugLog(tx, "server redirect", { redirectUrl });
-          }
+        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+        if (redirect === "blocked") {
           resolveStreamComplete();
-          throw new ServerRedirect(redirectUrl, undefined);
+          return emptyResponse();
         }
-
-        if (!response.body) {
-          // No body means stream is already complete
+        if (redirect) {
+          if (tx) {
+            browserDebugLog(tx, "server redirect", {
+              redirectUrl: redirect.url,
+            });
+          }
           resolveStreamComplete();
-          return response;
+          throw new ServerRedirect(redirect.url, undefined);
         }
 
-        // Tee the stream: one for RSC runtime, one for tracking completion
-        const [rscStream, trackingStream] = response.body.tee();
-
-        // Consume the tracking stream to detect when it closes
-        (async () => {
-          const reader = trackingStream.getReader();
-
-          // Cancel tracking if navigation is aborted
-          const onAbort = reader.cancel.bind(reader);
-          signal?.addEventListener("abort", onAbort, { once: true });
-
-          try {
-            while (true) {
-              const { done } = await reader.read();
-              if (done) break;
-            }
-          } finally {
-            signal?.removeEventListener("abort", onAbort);
-            reader.releaseLock();
-            if (tx) {
-              browserDebugLog(tx, "stream complete");
-            }
+        return teeWithCompletion(
+          response,
+          () => {
+            if (tx) browserDebugLog(tx, "stream complete");
             resolveStreamComplete();
-          }
-        })().catch((error) => {
-          console.error("[Browser] Error reading tracking stream:", error);
-          resolveStreamComplete();
-        });
-
-        // Return response with the RSC stream
-        return new Response(rscStream, {
-          headers: response.headers,
-          status: response.status,
-          statusText: response.statusText,
-        });
+          },
+          signal,
+        );
       });
 
       try {

package/src/browser/navigation-store.ts

@@ -12,6 +12,7 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -320,6 +321,7 @@ export function createNavigationStore(
    */
   function clearCacheInternal(): void {
     historyCache.length = 0;
+    clearPrefetchCache();
   }
 
   /**
@@ -329,13 +331,13 @@ export function createNavigationStore(
     for (let i = 0; i < historyCache.length; i++) {
       historyCache[i][2] = true;
     }
+    clearPrefetchCache();
   }
 
   /**
    * Clear the history cache and broadcast to other tabs
    */
   function clearCacheAndBroadcast(): void {
-    console.log("[Browser] Clearing cache and broadcasting to other tabs");
     clearCacheInternal();
     broadcastInvalidation();
   }
@@ -344,9 +346,6 @@ export function createNavigationStore(
    * Mark cache as stale and broadcast to other tabs
    */
   function markStaleAndBroadcast(): void {
-    console.log(
-      "[Browser] Marking cache as stale and broadcasting to other tabs",
-    );
     markCacheAsStaleInternal();
     broadcastInvalidation();
   }
@@ -369,14 +368,6 @@ export function createNavigationStore(
         path: currentPath,
         segmentIds: currentSegmentIds,
       });
-      console.log(
-        "[Browser] Broadcast sent for path:",
-        currentPath,
-        "segments:",
-        currentSegmentIds.join(", "),
-      );
-    } else {
-      console.warn("[Browser] No BroadcastChannel available");
     }
   }
 
@@ -401,34 +392,21 @@ export function createNavigationStore(
             return;
           }
 
-          console.log(
-            "[Browser] Cache marked stale by another tab, shared segments:",
-            mutatedSegmentIds
-              .filter((id) => currentSegmentIds.includes(id))
-              .join(", "),
-          );
           markCacheAsStaleInternal();
 
           // Auto-refresh if enabled and callback is registered
           if (crossTabAutoRefresh && crossTabRefreshCallback) {
             // If idle, refresh immediately. If loading, wait for idle then refresh.
             if (navState.state === "idle") {
-              console.log("[Browser] Cross-tab refresh triggered (idle)");
               crossTabRefreshCallback();
             } else if (!pendingCrossTabRefresh) {
               // Only queue one refresh, ignore subsequent events while loading
               pendingCrossTabRefresh = true;
-              console.log(
-                "[Browser] Navigation in progress, deferring cross-tab refresh",
-              );
               // Subscribe to state changes, refresh when idle
               const listener: StateListener = () => {
                 if (navState.state === "idle") {
                   stateListeners.delete(listener);
                   pendingCrossTabRefresh = false;
-                  console.log(
-                    "[Browser] Cross-tab refresh triggered (deferred)",
-                  );
                   crossTabRefreshCallback?.();
                 }
               };
@@ -652,14 +630,7 @@ export function createNavigationStore(
      * Called after server actions to indicate data may be outdated
      */
     markCacheAsStale(): void {
-      for (let i = 0; i < historyCache.length; i++) {
-        historyCache[i][2] = true;
-      }
-      console.log(
-        "[Browser] Marked",
-        historyCache.length,
-        "cache entries as stale",
-      );
+      markCacheAsStaleInternal();
     },
 
     /**

package/src/browser/navigation-transaction.ts

@@ -0,0 +1,295 @@
+import type {
+  NavigateOptions,
+  NavigationStore,
+  ResolvedSegment,
+  StreamingToken,
+} from "./types.js";
+import { generateHistoryKey } from "./navigation-store.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
+import type { EventController, NavigationHandle } from "./event-controller.js";
+import { debugLog } from "./logging.js";
+import { buildHistoryState } from "./history-state.js";
+
+// Re-export for consumers that import from navigation-transaction
+export { resolveNavigationState } from "./history-state.js";
+
+/** Check if a history state object contains location state keys. */
+function hasLocationState(state: unknown): boolean {
+  if (!state || typeof state !== "object") return false;
+  return (
+    "state" in state ||
+    Object.keys(state).some((k) => k.startsWith("__rsc_ls_"))
+  );
+}
+
+// Polyfill Symbol.dispose for Safari and older browsers
+if (typeof Symbol.dispose === "undefined") {
+  (Symbol as any).dispose = Symbol("Symbol.dispose");
+}
+
+/**
+ * Options for committing a navigation transaction
+ */
+interface CommitOptions {
+  url: string;
+  segmentIds: string[];
+  segments: ResolvedSegment[];
+  replace?: boolean;
+  scroll?: boolean;
+  /** User-provided state to store in history.state */
+  state?: unknown;
+  /** If true, only update store without changing URL/history (for server actions) */
+  storeOnly?: boolean;
+  /** If true, this is an intercept route - store in history.state for popstate handling */
+  intercept?: boolean;
+  /** Source URL where the intercept was triggered from (stored in history.state) */
+  interceptSourceUrl?: string;
+  /** If true, only update cache without touching store or history (for background stale revalidation) */
+  cacheOnly?: boolean;
+  /** Server-set location state to merge into history.pushState */
+  serverState?: Record<string, unknown>;
+}
+
+/**
+ * Options that can override the pre-configured commit settings
+ */
+interface BoundCommitOverrides {
+  /** Override scroll behavior (e.g., disable for intercepts) */
+  scroll?: boolean;
+  /** Override replace behavior (e.g., force replace for intercepts) */
+  replace?: boolean;
+  /** Override user-provided state */
+  state?: unknown;
+  /** Mark this as an intercept route */
+  intercept?: boolean;
+  /** Source URL where intercept was triggered from */
+  interceptSourceUrl?: string;
+  /** If true, only update cache (for stale revalidation) */
+  cacheOnly?: boolean;
+  /** Server-set location state to merge into history.pushState */
+  serverState?: Record<string, unknown>;
+}
+
+/**
+ * Bound transaction with pre-configured commit options (without segmentIds/segments)
+ */
+export interface BoundTransaction {
+  readonly currentUrl: string;
+  /** Start streaming and get a token to end it when the stream completes */
+  startStreaming(): StreamingToken;
+  commit(
+    segmentIds: string[],
+    segments: ResolvedSegment[],
+    overrides?: BoundCommitOverrides,
+  ): void;
+}
+
+/**
+ * Navigation transaction for managing state during navigation
+ * Uses the event controller handle for lifecycle management
+ */
+interface NavigationTransaction extends Disposable {
+  commit(options: CommitOptions): void;
+  with(
+    options: Omit<CommitOptions, "segmentIds" | "segments">,
+  ): BoundTransaction;
+  /** The navigation handle from the event controller */
+  handle: NavigationHandle;
+}
+
+/**
+ * Creates a navigation transaction that coordinates with the event controller.
+ * Handles loading state transitions and cleanup on completion/abort.
+ */
+export function createNavigationTransaction(
+  store: NavigationStore,
+  eventController: EventController,
+  url: string,
+  options?: NavigateOptions & { skipLoadingState?: boolean },
+): NavigationTransaction {
+  let committed = false;
+  const currentUrl = window.location.href;
+
+  // Start navigation in event controller (this sets loading state)
+  const handle = eventController.startNavigation(url, options);
+
+  /**
+   * Commit the navigation - updates store and URL atomically
+   */
+  function commit(opts: CommitOptions): void {
+    committed = true;
+
+    const {
+      url,
+      segmentIds,
+      segments,
+      replace,
+      scroll,
+      storeOnly,
+      intercept,
+      interceptSourceUrl,
+      cacheOnly,
+      serverState,
+    } = opts;
+
+    const parsedUrl = new URL(url, window.location.origin);
+
+    // Generate history key from URL (with intercept suffix for separate caching)
+    const historyKey = generateHistoryKey(url, { intercept });
+
+    // For cache-only commits (stale revalidation), only update cache and return
+    // Don't touch store state or history - user may have navigated elsewhere
+    if (cacheOnly) {
+      const currentHandleData = eventController.getHandleState().data;
+      store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
+      // Complete the navigation handle so currentNavigation is cleared.
+      // Without this, the entry lingers and weakens state-machine invariants.
+      handle.complete(parsedUrl);
+      debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
+      return;
+    }
+
+    // Save current scroll position before navigating
+    handleNavigationStart();
+
+    // Update segment state atomically
+    store.setSegmentIds(segmentIds);
+    store.setCurrentUrl(url);
+    store.setPath(parsedUrl.pathname);
+
+    store.setHistoryKey(historyKey);
+
+    // Cache segments with current handleData for this history entry
+    const currentHandleData = eventController.getHandleState().data;
+    store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
+
+    // For server actions, skip URL/history updates but still complete navigation
+    if (storeOnly) {
+      debugLog("[Browser] Store updated (action)");
+      // Complete navigation to clear loading state
+      handle.complete(parsedUrl);
+      return;
+    }
+
+    // Build history state - include user state, intercept info, and server-set state
+    const historyState = buildHistoryState(
+      opts.state,
+      { intercept, sourceUrl: interceptSourceUrl },
+      serverState,
+    );
+
+    // Snapshot old state before pushState/replaceState overwrites it.
+    // Used to detect when location state is being cleared.
+    const oldState = window.history.state;
+
+    // Update browser URL
+    if (replace) {
+      window.history.replaceState(historyState, "", url);
+    } else {
+      window.history.pushState(historyState, "", url);
+    }
+    // Ensure new history entry has a scroll restoration key
+    ensureHistoryKey();
+
+    // Notify location state hooks when either old or new state carries
+    // location state. This covers both "set new state" and "clear old state"
+    // for same-page navigations where components don't remount.
+    if (hasLocationState(oldState) || hasLocationState(historyState)) {
+      window.dispatchEvent(new Event("__rsc_locationstate"));
+    }
+
+    // Complete the navigation in event controller (sets idle state, updates location)
+    handle.complete(parsedUrl);
+
+    // Handle scroll after navigation
+    handleNavigationEnd({ scroll });
+
+    debugLog(
+      "[Browser] Navigation committed, historyKey:",
+      historyKey,
+      intercept ? "(intercept)" : "",
+    );
+  }
+
+  return {
+    handle,
+    commit,
+
+    /**
+     * Create a bound transaction with pre-configured URL options
+     * segmentIds and segments provided at commit time (after they're resolved)
+     */
+    with(
+      opts: Omit<CommitOptions, "segmentIds" | "segments">,
+    ): BoundTransaction {
+      return {
+        get currentUrl() {
+          return currentUrl;
+        },
+        startStreaming() {
+          return handle.startStreaming();
+        },
+        commit: (
+          segmentIds: string[],
+          segments: ResolvedSegment[],
+          overrides?: BoundCommitOverrides,
+        ) => {
+          // Allow overrides to disable scroll (e.g., for intercepts)
+          const finalScroll =
+            overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
+          // Allow overrides to force replace (e.g., for intercepts)
+          const finalReplace =
+            overrides?.replace !== undefined ? overrides.replace : opts.replace;
+          // Intercept info: overrides take precedence, fallback to opts
+          const intercept =
+            overrides?.intercept !== undefined
+              ? overrides.intercept
+              : opts.intercept;
+          const interceptSourceUrl =
+            overrides?.interceptSourceUrl !== undefined
+              ? overrides.interceptSourceUrl
+              : opts.interceptSourceUrl;
+          // Cache-only mode: overrides take precedence, fallback to opts
+          const cacheOnly =
+            overrides?.cacheOnly !== undefined
+              ? overrides.cacheOnly
+              : opts.cacheOnly;
+          // User state: overrides take precedence, fallback to opts
+          const state =
+            overrides?.state !== undefined ? overrides.state : opts.state;
+          // Server-set location state: only from overrides (set by partial-update)
+          const serverState = overrides?.serverState;
+          commit({
+            ...opts,
+            segmentIds,
+            segments,
+            scroll: finalScroll,
+            replace: finalReplace,
+            state,
+            intercept,
+            interceptSourceUrl,
+            cacheOnly,
+            serverState,
+          });
+        },
+      };
+    },
+
+    [Symbol.dispose]() {
+      // Superseded: another navigation took over.
+      if (handle.signal.aborted) {
+        return;
+      }
+
+      // Failed (not committed): keep the target URL -- the error UI owns it.
+      // Just reset the event controller to idle.
+      if (!committed) {
+        handle[Symbol.dispose]();
+      }
+    },
+  };
+}