@rangojs/router 0.0.0-experimental.42 → 0.0.0-experimental.4518794d

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.42",
+  version: "0.0.0-experimental.4518794d",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.42",
+  "version": "0.0.0-experimental.4518794d",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/browser/navigation-bridge.ts

@@ -461,6 +461,10 @@ export function createNavigationBridge(
           }
           eventController.setParams(cachedParams);
 
+          // Scroll to top immediately to avoid flicker from the previous
+          // page's scroll position while React paints the cached content.
+          window.scrollTo(0, 0);
+
           const popstateUpdate = {
             root,
             metadata: {
@@ -485,16 +489,8 @@ export function createNavigationBridge(
             onUpdate(popstateUpdate);
           }
 
-          // Restore scroll position for back/forward navigation.
-          // Defer to next frame so React has committed the cached content to
-          // the DOM before we measure scrollHeight and restore scroll position.
-          const defer =
-            typeof requestAnimationFrame === "function"
-              ? requestAnimationFrame
-              : (fn: () => void) => setTimeout(fn, 0);
-          defer(() => {
-            handleNavigationEnd({ restore: true, isStreaming });
-          });
+          // Restore the actual saved scroll position after React paints.
+          handleNavigationEnd({ restore: true, isStreaming });
 
           // SWR: If stale, trigger background revalidation
           if (isStale) {

package/src/browser/navigation-transaction.ts

@@ -7,7 +7,6 @@ import type {
 import { generateHistoryKey } from "./navigation-store.js";
 import {
   handleNavigationStart,
-  handleNavigationEnd,
   ensureHistoryKey,
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
@@ -81,11 +80,12 @@ export interface BoundTransaction {
   readonly currentUrl: string;
   /** Start streaming and get a token to end it when the stream completes */
   startStreaming(): StreamingToken;
+  /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
   commit(
     segmentIds: string[],
     segments: ResolvedSegment[],
     overrides?: BoundCommitOverrides,
-  ): void;
+  ): { scroll?: boolean };
 }
 
 /**
@@ -93,7 +93,7 @@ export interface BoundTransaction {
  * Uses the event controller handle for lifecycle management
  */
 interface NavigationTransaction extends Disposable {
-  commit(options: CommitOptions): void;
+  commit(options: CommitOptions): { scroll?: boolean };
   with(
     options: Omit<CommitOptions, "segmentIds" | "segments">,
   ): BoundTransaction;
@@ -120,7 +120,7 @@ export function createNavigationTransaction(
   /**
    * Commit the navigation - updates store and URL atomically
    */
-  function commit(opts: CommitOptions): void {
+  function commit(opts: CommitOptions): { scroll?: boolean } {
     committed = true;
 
     const {
@@ -150,7 +150,7 @@ export function createNavigationTransaction(
       // Without this, the entry lingers and weakens state-machine invariants.
       handle.complete(parsedUrl);
       debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
-      return;
+      return { scroll: false };
     }
 
     // Save current scroll position before navigating
@@ -172,7 +172,7 @@ export function createNavigationTransaction(
       debugLog("[Browser] Store updated (action)");
       // Complete navigation to clear loading state
       handle.complete(parsedUrl);
-      return;
+      return { scroll: false };
     }
 
     // Build history state - include user state, intercept info, and server-set state
@@ -205,14 +205,16 @@ export function createNavigationTransaction(
     // Complete the navigation in event controller (sets idle state, updates location)
     handle.complete(parsedUrl);
 
-    // Handle scroll after navigation
-    handleNavigationEnd({ scroll });
+    // NOTE: Scroll is NOT handled here. The caller (partial-update.ts) handles
+    // scroll AFTER onUpdate() so React has the new content before we scroll.
 
     debugLog(
       "[Browser] Navigation committed, historyKey:",
       historyKey,
       intercept ? "(intercept)" : "",
     );
+
+    return { scroll };
   }
 
   return {
@@ -263,7 +265,7 @@ export function createNavigationTransaction(
             overrides?.state !== undefined ? overrides.state : opts.state;
           // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
-          commit({
+          return commit({
             ...opts,
             segmentIds,
             segments,

package/src/browser/partial-update.ts

@@ -19,6 +19,7 @@ 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 { handleNavigationEnd } from "./scroll-restoration.js";
 
 /**
  * Configuration for creating a partial updater
@@ -246,7 +247,10 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: commitScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
@@ -276,6 +280,7 @@ export function createPartialUpdater(
             onUpdate(cachedUpdate);
           }
 
+          handleNavigationEnd({ scroll: commitScroll });
           debugLog("[Browser] Navigation complete (rendered from cache)");
           return;
         }
@@ -290,13 +295,17 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: leaveScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
           });
 
+          handleNavigationEnd({ scroll: leaveScroll });
           debugLog("[Browser] Navigation complete (left intercept)");
           return;
         }
@@ -426,7 +435,11 @@ 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") {
@@ -471,6 +484,9 @@ export function createPartialUpdater(
         });
       }
 
+      // Scroll after onUpdate so React has the new content before we scroll
+      handleNavigationEnd({ scroll: navScroll });
+
       debugLog("[Browser] Navigation complete");
       return;
     } else {
@@ -494,11 +510,11 @@ 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,
@@ -542,6 +558,7 @@ export function createPartialUpdater(
         });
       }
 
+      handleNavigationEnd({ scroll: fullScroll });
       return;
     }
   }

package/src/browser/scroll-restoration.ts

@@ -370,13 +370,21 @@ export function handleNavigationEnd(options: {
     // Fall through to hash or top if no saved position
   }
 
-  // Try hash scrolling first
-  if (scrollToHash()) {
-    return;
-  }
+  // Defer hash and scroll-to-top to after React paints the new content,
+  // so the user doesn't see the current page jump before the new route appears.
+  const defer =
+    typeof requestAnimationFrame === "function"
+      ? requestAnimationFrame
+      : (fn: () => void) => setTimeout(fn, 0);
+  defer(() => {
+    // Try hash scrolling first
+    if (scrollToHash()) {
+      return;
+    }
 
-  // Default: scroll to top
-  scrollToTop();
+    // Default: scroll to top
+    scrollToTop();
+  });
 }
 
 /**