@rangojs/router 0.24.3 → 0.25.0

package/src/browser/scroll-restoration.ts

@@ -75,7 +75,8 @@ let customGetKey: GetScrollKeyFunction | null = null;
 /**
  * Scroll key of the entry on screen. At popstate history.state already belongs
  * to the destination, so this is the only way to save the page being left
- * under its own key (see handleTraversalStart).
+ * under its own key (see handleTraversalStart). A traversal moves it when its
+ * restore commits (handleNavigationEnd), not at its event.
  */
 let displayedKey: string | null = null;
 
@@ -283,10 +284,12 @@ export function cancelScrollRestorationPolling(): void {
  *
  * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
  * @param options.isStreaming - Function to check if streaming is in progress
+ * @param options.committed - React has committed the restored tree (a layout effect)
  */
 export function restoreScrollPosition(options?: {
   retryIfStreaming?: boolean;
   isStreaming?: () => boolean;
+  committed?: boolean;
 }): boolean {
   // Clear any pending polling
   cancelScrollRestorationPolling();
@@ -298,6 +301,11 @@ export function restoreScrollPosition(options?: {
     return false;
   }
 
+  // Once React committed the restored tree, scroll now, so a view
+  // transition's new snapshot is taken at the restored position, while the
+  // page still streams too.
+  if (options?.committed) window.scrollTo(0, savedY);
+
   // If streaming, poll until streaming ends then scroll to saved position
   if (options?.retryIfStreaming && options?.isStreaming?.()) {
     const startTime = Date.now();
@@ -319,9 +327,8 @@ export function restoreScrollPosition(options?: {
     return true;
   }
 
-  // Not streaming — scroll after React commits and browser paints.
-  // startTransition defers the DOM commit, so scrolling synchronously
-  // would be overwritten when React replaces the content.
+  // Not streaming: scroll (again) on the next frame, for layout that settles
+  // after the commit and for a caller that ran before it.
   deferToNextPaint(() => {
     window.scrollTo(0, savedY);
     debugLog("[Scroll] Restored position:", savedY, "for key:", key);
@@ -374,18 +381,18 @@ export function handleNavigationStart(): void {
 
 /**
  * Handle scroll for a back/forward traversal, at popstate before anything
- * renders: save the page being left under ITS key (history has already moved,
- * so saveCurrentScrollPosition would use the destination's key) and track the
- * destination as the displayed entry.
+ * renders: save the page on screen under ITS key (history has already moved,
+ * so saveCurrentScrollPosition would use the destination's key). A second
+ * traversal before the first one's restore commits (a rapid double Back, a
+ * deferred animated restore) saves the page still on screen, never an entry
+ * it did not show.
  */
 export function handleTraversalStart(): void {
   if (!initialized) return;
-  const leftKey = displayedKey;
-  trackDisplayedEntry();
   // A key shared with the destination (a getKey that collapses entries, e.g.
   // by pathname) keeps the destination's saved position.
-  if (leftKey !== null && leftKey !== displayedKey) {
-    saveScrollPosition(leftKey, window.scrollY);
+  if (displayedKey !== null && displayedKey !== getScrollKey()) {
+    saveScrollPosition(displayedKey, window.scrollY);
   }
 }
 
@@ -394,13 +401,15 @@ export function handleTraversalStart(): void {
  * @param options.restore - If true, restore saved position (for popstate)
  * @param options.scroll - If false, don't scroll at all
  * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
+ * @param options.committed - Called after React committed the new tree
  */
 export function handleNavigationEnd(options: {
   restore?: boolean;
   scroll?: boolean;
   isStreaming?: () => boolean;
+  committed?: boolean;
 }): void {
-  const { restore = false, scroll = true, isStreaming } = options;
+  const { restore = false, scroll = true, isStreaming, committed } = options;
 
   // Don't scroll if explicitly disabled or not in a browser
   if (scroll === false || typeof window === "undefined") {
@@ -412,11 +421,17 @@ export function handleNavigationEnd(options: {
   // matters during cross-app navigation where ScrollRestoration unmounts
   // and remounts, creating a brief window where initialized is false.
   if (restore) {
-    if (
-      initialized &&
-      restoreScrollPosition({ retryIfStreaming: true, isStreaming })
-    ) {
-      return;
+    if (initialized) {
+      trackDisplayedEntry();
+      if (
+        restoreScrollPosition({
+          retryIfStreaming: true,
+          isStreaming,
+          committed,
+        })
+      ) {
+        return;
+      }
     }
     // An "auto" entry (no <Html.ScrollRestoration>, or created before it mounted)
     // is restored by the browser. A scrollTo here races that restore, and
@@ -438,9 +453,8 @@ export function handleNavigationEnd(options: {
   // against unmeasured layout, so sync scroll is correct here even
   // before the new tree's scrollHeight settles.
   //
-  // (The restore branch above keeps deferToNextPaint because savedY
-  // depends on the new tree's max scroll; sync scrollTo against an
-  // unmeasured DOM would clamp savedY to whatever the old/zero max was.)
+  // (The restore branch above also scrolls again on the next frame: savedY
+  // depends on the new tree's max scroll, which can grow after the commit.)
   if (scrollToHash()) {
     return;
   }

package/src/browser/segment-reconciler.ts

@@ -1,9 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
-import {
-  mergeSegmentLoaders,
-  needsLoaderMerge,
-  insertMissingDiffSegments,
-} from "./merge-segment-loaders.js";
+import { insertMissingDiffSegments } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
 import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
@@ -11,15 +7,17 @@ import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 /**
  * Determines the merging behavior for segment reconciliation.
  *
- * - 'action': From server-action-bridge's own merge. Always merges loaders,
- *   always preserves cached loading (even undefined), never clears cached
- *   segment loading.
- * - 'navigation': From partial-update during normal navigation. Does NOT merge
- *   loaders, preserves cached loading only when defined, clears truthy loading
- *   on cached segments not in server diff.
+ * - 'action': From server-action-bridge's own merge. Always preserves cached
+ *   loading (even undefined), never clears cached segment loading.
+ * - 'navigation': From partial-update during normal navigation. Preserves
+ *   cached loading only when defined, clears truthy loading on cached
+ *   segments not in server diff.
  * - 'stale-revalidation': From partial-update during stale revalidation or
- *   action-triggered refetch. Merges loaders, always preserves cached loading
- *   (same as action), clears truthy loading on cached segments not in server diff.
+ *   action-triggered refetch. Always preserves cached loading (same as
+ *   action), clears truthy loading on cached segments not in server diff.
+ *
+ * No actor merges loader data: a loader the server skipped, an intercept's
+ * included, is its own cached segment in `matched`.
  */
 export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
 
@@ -64,11 +62,6 @@ export interface ReconcileResult {
  *   (not undefined). When cached is undefined, lets server value through
  *   because we're building a new tree.
  *
- * Loader merging:
- * - action/stale-revalidation: Merges partial loader data when server returns
- *   fewer loaders than cached (revalidation only updated some loaders).
- * - navigation: Does not merge (full navigation fetches complete data).
- *
  * Cached segment handling (segments in matched but not in server response):
  * - action: Returns cached segment as-is (preserve tree structure).
  * - navigation/stale-revalidation: Clears truthy loading to undefined
@@ -77,7 +70,6 @@ export interface ReconcileResult {
  */
 export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const { actor, matched, diff, insertMissingDiff } = input;
-  const shouldMergeLoaders = actor !== "navigation";
   const context = actor === "action" ? "action-bridge" : "partial-update";
 
   // Build lookup maps from arrays
@@ -119,16 +111,6 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 
       if (fromServer) {
         const inDiff = diffSet.has(segId);
-        // Merge partial loader data when server returns fewer loaders than cached
-        if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
-          if (IS_BROWSER_DEBUG) {
-            debugLog(
-              `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
-            );
-          }
-          return mergeSegmentLoaders(fromServer, fromCache);
-        }
-
         // Preserve cached structural properties to maintain consistent React tree.
         // Changing these between renders alters the element nesting
         // (with/without RouteContentWrapper, MountContextProvider, etc.),

package/src/browser/server-action-bridge.ts

@@ -3,8 +3,10 @@ import type {
   ServerActionBridgeConfig,
   RscPayload,
   ResolvedSegment,
+  NavigationUpdate,
+  UpdateSubscriber,
 } from "./types.js";
-import { createPartialUpdater } from "./partial-update.js";
+import { addTransitionType, createPartialUpdater } from "./partial-update.js";
 import { enterActionFence, exitActionFence } from "./action-fence.js";
 import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
@@ -39,6 +41,7 @@ import {
 import { mergeLocationState } from "./history-state.js";
 import { stampLocationState } from "./react/location-state-shared.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
+import { revalidationErrorOf } from "../decode-loader-results.js";
 import { getAppVersion } from "./app-version.js";
 import {
   decideCommitGatedOff,
@@ -99,6 +102,24 @@ function applyActionLocationState(
   }
 }
 
+/**
+ * An action's commit: urgent when transition({ when }) gated it off, like
+ * every gated-off commit, else a transition tagged `action` (#1165).
+ */
+function commitAction(
+  onUpdate: UpdateSubscriber,
+  update: NavigationUpdate,
+  gatedOff: boolean,
+): void {
+  if (gatedOff) onUpdate(update);
+  else
+    startTransition(() => {
+      addTransitionType?.("action");
+      update.inTransition = true;
+      onUpdate(update);
+    });
+}
+
 /**
  * Create a server action bridge for handling RSC server actions
  *
@@ -173,6 +194,7 @@ export function createServerActionBridge(
    * Refetch current route via a navigation transaction.
    * Encapsulates the repeated pattern of creating a navTx + fetchPartialUpdate
    * used by navigated-away, hmr-missing, and consolidation-needed scenarios.
+   * Resolves with the error of a loader that threw on the refetch.
    */
   async function refetchRoute(opts?: {
     segments?: string[];
@@ -180,7 +202,7 @@ export function createServerActionBridge(
     actionId?: string;
     /** transition({ when }) `action` fields for the refetch commit. */
     action?: TransitionWhenActionInput;
-  }): Promise<void> {
+  }): Promise<Error | undefined> {
     const src = opts?.interceptSourceUrl ?? null;
     const navTx = createNavigationTransaction(
       store,
@@ -189,7 +211,7 @@ export function createServerActionBridge(
       { replace: true, skipLoadingState: true },
     );
     try {
-      await fetchPartialUpdate(
+      return await fetchPartialUpdate(
         window.location.href,
         opts?.segments ?? [],
         false,
@@ -302,6 +324,11 @@ export function createServerActionBridge(
       if (rid) {
         url.searchParams.set("_rsc_rid", rid);
       }
+      // The page's rewrite target: the server diffs the re-render against it.
+      const rewriteTarget = store.getHistoryEntryMemory()?.rewriteTarget;
+      if (rewriteTarget) {
+        url.searchParams.set("_rsc_rt", rewriteTarget);
+      }
 
       // Encode arguments
       const encodedBody = await deps.encodeReply(args, { temporaryReferences });
@@ -618,12 +645,13 @@ export function createServerActionBridge(
         );
         store.rememberDisplayedEntry();
 
-        // Update UI with error boundary: urgent when transition({ when })
-        // gated it off, like every gated-off commit.
-        const errorUpdate = { root: errorTree, metadata: metadata! };
+        // Update UI with error boundary.
         if (process.env.NODE_ENV !== "production") auditTreeCause("action");
-        if (errorGatedOff) onUpdate(errorUpdate);
-        else startTransition(() => onUpdate(errorUpdate));
+        commitAction(
+          onUpdate,
+          { root: errorTree, metadata: metadata! },
+          errorGatedOff,
+        );
 
         // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
@@ -677,6 +705,8 @@ export function createServerActionBridge(
       const fullSegments = reconciled.segments;
 
       const returnData = returnValue?.data;
+      // A loader that threw while it re-ran: reported, not thrown.
+      let revalidationError: Error | undefined;
 
       if (returnValue && !returnValue.ok) {
         handle.fail(returnValue.data);
@@ -754,7 +784,7 @@ export function createServerActionBridge(
           // route. Invalidation is deferred to finalizeAction(); here we only
           // trigger the revalidation refetch (suppressed on keep).
           if (!keepCache) {
-            await refetchRoute({
+            revalidationError = await refetchRoute({
               interceptSourceUrl: store.getInterceptSourceUrl(),
               actionId: id,
               action: whenAction,
@@ -771,7 +801,7 @@ export function createServerActionBridge(
           // resolving last must discharge a directive-free sibling's repair.
           // See the keep row in docs/design/rango-state-cookie.md (the all-keep
           // edge, and the benign re-mark-stale-after-refetch end-state delta).
-          await refetchRoute({
+          revalidationError = await refetchRoute({
             interceptSourceUrl,
             actionId: id,
             action: whenAction,
@@ -794,7 +824,7 @@ export function createServerActionBridge(
           handle.clearConsolidation();
 
           // Ungated on keepCache, same as hmr-missing above (see the keep row).
-          await refetchRoute({
+          revalidationError = await refetchRoute({
             segments: segmentsToSend,
             interceptSourceUrl,
             actionId: id,
@@ -824,6 +854,9 @@ export function createServerActionBridge(
               currentHandleData,
             );
           }
+          // Not rendered: the sibling's refetch reruns these loaders and
+          // reports its own. Resolve when the metadata lands, without waiting
+          // for this answer's loader chunks.
           break;
         }
 
@@ -854,6 +887,7 @@ export function createServerActionBridge(
                 ? reconciled.interceptSegments
                 : undefined,
           });
+          revalidationError = await revalidationErrorOf(segments);
 
           // Re-check if user navigated away (could happen during async renderSegments)
           if (window.location.pathname !== actionStartPathname) {
@@ -891,12 +925,14 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
-          store.rememberDisplayedEntry(metadata?.routeName);
+          store.rememberDisplayedEntry(metadata);
 
-          const actionUpdate = { root: newTree, metadata: metadata! };
           if (process.env.NODE_ENV !== "production") auditTreeCause("action");
-          if (gatedOff) onUpdate(actionUpdate);
-          else startTransition(() => onUpdate(actionUpdate));
+          commitAction(
+            onUpdate,
+            { root: newTree, metadata: metadata! },
+            gatedOff,
+          );
           // Invalidation deferred to finalizeAction() (runs after this caches
           // the fresh segments), suppressed when the action called
           // keepClientCache().
@@ -904,7 +940,7 @@ export function createServerActionBridge(
         }
       }
 
-      handle.complete(returnData);
+      handle.complete(returnData, revalidationError);
       return returnData;
     } catch (error) {
       // What the call rejects with (a revalidation render that threw, a

package/src/browser/types.ts

@@ -36,6 +36,11 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
  */
 export interface RscMetadata {
   pathname: string;
+  /**
+   * Path and search of the URL the route rendered, when middleware rewrote
+   * the request there. Kept per history entry and sent back as `_rsc_rt`.
+   */
+  rewriteTarget?: string;
   segments: ResolvedSegment[];
   /** Router instance ID — the current app's identity. A mismatch with the
    *  client's id (sent as _rsc_rid) is detected server-side and answered with
@@ -248,6 +253,13 @@ export interface TrackedActionState {
 
   /** Result data from the action (preserved after completion) */
   result: unknown | null;
+
+  /**
+   * The error of a loader that threw while it re-ran after this successful
+   * action (the first, when several did). The loader also throws at its
+   * useLoader read, where the nearest error boundary catches it.
+   */
+  revalidationError: unknown | null;
 }
 
 /**
@@ -292,13 +304,24 @@ export interface SegmentState {
   currentSegmentIds: string[];
 }
 
+/**
+ * What a committed payload says about the page it shows, remembered per
+ * history entry (NavigationStore.rememberDisplayedEntry).
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface ShownEntry {
+  readonly routeName?: string;
+  readonly rewriteTarget?: string;
+}
+
 /**
  * What the router remembers about one history entry for transition({ when })
- * (NavigationStore.rememberDisplayedEntry).
+ * and the requests made from it (NavigationStore.rememberDisplayedEntry).
  *
  * @internal This type is an implementation detail and may change without notice.
  */
-export interface HistoryEntryMemory {
+export interface HistoryEntryMemory extends ShownEntry {
   readonly routeName: string | undefined;
   /** The entry's `history.state` as last recorded. */
   readonly state: unknown;
@@ -326,6 +349,12 @@ export interface NavigationUpdate {
     /** Function to check if streaming is in progress */
     isStreaming?: () => boolean;
   };
+  /**
+   * Handed to React inside startTransition (commitInTransition, an action's
+   * commit, a cached back/forward's): NavigationProvider joins the route
+   * state that arrives while React holds it to its commit.
+   */
+  inTransition?: true;
 }
 
 /**
@@ -587,12 +616,12 @@ export interface NavigationStore {
   /**
    * Per-history-entry memory for transition({ when }) sources: record the
    * entry on screen (keyed by its `history.state.key`) with its current
-   * `history.state` and, when given, its route name (kept from the last
-   * record otherwise; every push/replace creates a new key, so a stale name
-   * never carries to another entry). Called after every commit, restore and
-   * state merge.
+   * `history.state` and, when `shown` is given, its route name and rewrite
+   * target (both kept from the last record otherwise; every push/replace
+   * creates a new key, so a stale record never carries to another entry).
+   * Called after every commit, restore and state merge.
    */
-  rememberDisplayedEntry(routeName?: string): void;
+  rememberDisplayedEntry(shown?: ShownEntry): void;
   /**
    * The memory of the entry on screen, or of `entryKey`. At popstate
    * history.state already belongs to the destination, so back/forward reads
@@ -683,6 +712,8 @@ export interface FetchPartialOptions {
   targetUrl: string;
   segmentIds: string[];
   previousUrl: string;
+  /** The page's RscMetadata.rewriteTarget, sent as `_rsc_rt`. */
+  rewriteTarget?: string;
   signal?: AbortSignal;
   /** If true, this is a stale cache revalidation request - server should force revalidators */
   staleRevalidation?: boolean;
@@ -772,7 +803,8 @@ export interface ServerActionBridgeConfig {
 export interface NavigationBridge {
   navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
   refresh(): Promise<void>;
-  handlePopstate(): Promise<void>;
+  /** `event`: the popstate event; a traversal the browser animated itself (hasUAVisualTransition) is not animated again. */
+  handlePopstate(event?: PopStateEvent): Promise<void>;
   registerLinkInterception(): () => void;
   registerDelegatedPrefetch(): () => void;
   /** Current RSC version (live, reflects the latest updateVersion). */

package/src/build/generate-manifest.ts

@@ -16,7 +16,11 @@ import {
   RangoContext,
   runWithPrefixes,
 } from "../server/context.js";
-import type { EntryData, TrackedInclude } from "../server/context.js";
+import type {
+  EntryData,
+  IncludeScopePosition,
+  TrackedInclude,
+} from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
@@ -179,6 +183,7 @@ async function buildPrefixTreeNode(
   routeSearchSchemas?: Record<string, Record<string, string>>,
   routerId?: string,
   validateTransitionWhen?: boolean,
+  position?: IncludeScopePosition,
 ): Promise<PrefixTreeNode> {
   // Resolve an async include provider (`() => import("./routes")`) so its routes
   // are walked into the build-time manifest/types/href. Runtime matching still
@@ -222,6 +227,10 @@ async function buildPrefixTreeNode(
         mountIndex,
         ...(routerId ? { routerId } : {}),
         trackedIncludes, // Enable nested include tracking
+        // The same position runtime expansion runs this include at
+        // (lazy-includes.ts), so nested hidden names agree across realms.
+        scopePath: position?.scopePath,
+        hiddenScopePath: position?.hiddenScopePath,
       },
       () => {
         const helpers = createRouteHelpers();
@@ -304,6 +313,7 @@ async function buildPrefixTreeNode(
         routeSearchSchemas,
         routerId,
         validateTransitionWhen,
+        include,
       ),
     );
 
@@ -505,6 +515,7 @@ export async function generateManifestFull<TEnv>(
       routeSearchSchemas,
       options?.routerId,
       options?.validateTransitionWhen,
+      include,
     ),
   );
 

package/src/build/route-types/codegen.ts

@@ -48,7 +48,11 @@ export function generatePerModuleTypesSource(
     }
     deduped.set(name, { pattern, params, search });
   }
-  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  // Locale pinned: the machine's default locale reorders names (Czech sorts
+  // "ch" after "h"), and generated files must be identical on every machine.
+  const sorted = [...deduped.entries()].sort(([a], [b]) =>
+    a.localeCompare(b, "en"),
+  );
   const body = sorted
     .map(([name, { pattern, params, search }]) => {
       const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
@@ -69,7 +73,7 @@ export function generateRouteTypesSource(
 ): string {
   const entries = Object.entries(routeManifest)
     .filter(([name]) => !isAutoGeneratedRouteName(name))
-    .sort(([a], [b]) => a.localeCompare(b));
+    .sort(([a], [b]) => a.localeCompare(b, "en"));
 
   const filteredSearchSchemas = searchSchemas
     ? Object.fromEntries(