@rangojs/router 0.0.0-experimental.6fe6a3cc → 0.0.0-experimental.78a48627

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.6fe6a3cc",
+  version: "0.0.0-experimental.78a48627",
   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.6fe6a3cc",
+  "version": "0.0.0-experimental.78a48627",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/browser/navigation-bridge.ts

@@ -472,6 +472,7 @@ export function createNavigationBridge(
               cachedHandleData,
               params: cachedParams,
             },
+            scroll: { restore: true, isStreaming },
           };
           const hasTransition = cachedSegments.some((s) => s.transition);
           if (hasTransition) {
@@ -485,9 +486,6 @@ export function createNavigationBridge(
             onUpdate(popstateUpdate);
           }
 
-          // Restore scroll position for back/forward navigation
-          handleNavigationEnd({ restore: true, isStreaming });
-
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");

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

@@ -246,7 +246,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.
@@ -260,6 +263,10 @@ export function createPartialUpdater(
               ...metadataWithoutHandles,
               cachedHandleData: mode.targetCacheHandleData,
             },
+            scroll:
+              commitScroll !== false
+                ? { enabled: commitScroll }
+                : { enabled: false },
           };
 
           const cachedHasTransition = existingSegments.some(
@@ -290,11 +297,18 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: leaveScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
+            scroll:
+              leaveScroll !== false
+                ? { enabled: leaveScroll }
+                : { enabled: false },
           });
 
           debugLog("[Browser] Navigation complete (left intercept)");
@@ -426,7 +440,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") {
@@ -441,8 +459,13 @@ export function createPartialUpdater(
 
       debugLog("[partial-update] updating document");
 
-      // Emit update to trigger React render
+      // Emit update to trigger React render.
+      // Scroll info is included so NavigationProvider applies it after React commits.
       const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+      const scrollPayload =
+        navScroll !== false
+          ? { enabled: navScroll }
+          : { enabled: false as const };
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
         startTransition(() => {
@@ -452,6 +475,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else if (hasTransition) {
@@ -462,12 +486,14 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: scrollPayload,
         });
       }
 
@@ -494,15 +520,19 @@ 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 fullScrollPayload =
+        fullScroll !== false
+          ? { enabled: fullScroll }
+          : { enabled: false as const };
 
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
@@ -513,6 +543,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (mode.type === "action") {
@@ -523,6 +554,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (fullHasTransition) {
@@ -533,12 +565,14 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: fullScrollPayload,
         });
       }
 

package/src/browser/react/NavigationProvider.tsx

@@ -3,8 +3,10 @@
 import React, {
   useState,
   useEffect,
+  useLayoutEffect,
   useCallback,
   useMemo,
+  useRef,
   use,
   type ReactNode,
 } from "react";
@@ -25,6 +27,7 @@ import { ThemeProvider } from "../../theme/ThemeProvider.js";
 import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
+import { handleNavigationEnd } from "../scroll-restoration.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -301,9 +304,33 @@ export function NavigationProvider({
     return unsub;
   }, [eventController]);
 
+  // Pending scroll action to apply after React commits
+  const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
+
+  // Apply scroll after React commits the new content to the DOM
+  useLayoutEffect(() => {
+    const scrollAction = pendingScrollRef.current;
+    if (!scrollAction) return;
+    pendingScrollRef.current = undefined;
+
+    if (scrollAction.enabled === false) return;
+
+    handleNavigationEnd({
+      restore: scrollAction.restore,
+      scroll: scrollAction.enabled,
+      isStreaming: scrollAction.isStreaming,
+    });
+  });
+
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
+      // Capture scroll intent — it will be applied in useLayoutEffect
+      // after React commits this state update to the DOM.
+      if (update.scroll) {
+        pendingScrollRef.current = update.scroll;
+      }
+
       setPayload({
         root: update.root,
         metadata: update.metadata,

package/src/browser/scroll-restoration.ts

@@ -288,7 +288,11 @@ export function restoreScrollPosition(options?: {
   // 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.
-  requestAnimationFrame(() => {
+  const defer =
+    typeof requestAnimationFrame === "function"
+      ? requestAnimationFrame
+      : (fn: () => void) => setTimeout(fn, 0);
+  defer(() => {
     window.scrollTo(0, savedY);
     debugLog("[Scroll] Restored position:", savedY, "for key:", key);
   });
@@ -366,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();
+  });
 }
 
 /**

package/src/browser/types.ts

@@ -215,6 +215,15 @@ export interface SegmentState {
 export interface NavigationUpdate {
   root: ReactNode | Promise<ReactNode>;
   metadata: RscMetadata;
+  /** Scroll behavior to apply after React commits this update */
+  scroll?: {
+    /** For back/forward: restore saved position */
+    restore?: boolean;
+    /** Set to false to disable scrolling entirely */
+    enabled?: boolean;
+    /** Function to check if streaming is in progress */
+    isStreaming?: () => boolean;
+  };
 }
 
 /**

package/src/route-map-builder.ts

@@ -199,7 +199,13 @@ export function registerRouterManifestLoader(
 }
 
 export async function ensureRouterManifest(routerId: string): Promise<void> {
-  if (perRouterManifestMap.has(routerId)) return;
+  // Check both manifest AND trie. The virtual module's setRouterManifest()
+  // pre-sets the manifest at startup, but the per-router trie is only
+  // available from the lazy loader. Without this, the lazy loader never
+  // runs and findMatch falls back to the global merged trie — which
+  // contains routes from ALL routers and breaks multi-router setups.
+  if (perRouterManifestMap.has(routerId) && perRouterTrieMap.has(routerId))
+    return;
   const loader = routerManifestLoaders.get(routerId);
   if (loader) {
     const mod = await loader();

package/src/router/find-match.ts

@@ -52,8 +52,10 @@ export function createFindMatch<TEnv = any>(
       : undefined;
 
     // Phase 1: Try trie match (O(path_length))
-    // Prefer per-router trie (isolated) over global trie (merged).
-    const routeTrie = getRouterTrie(deps.routerId) ?? getRouteTrie();
+    // Only use the per-router trie. The global trie merges routes from ALL
+    // routers and must not be used — in multi-router setups (host routing)
+    // overlapping paths like "/" would match the wrong app's route.
+    const routeTrie = getRouterTrie(deps.routerId);
     if (routeTrie) {
       const trieStart = performance.now();
       const trieResult = tryTrieMatch(routeTrie, pathname);

package/src/router/intercept-resolution.ts

@@ -188,6 +188,7 @@ export async function resolveInterceptEntry<TEnv>(
           context,
           actionContext,
           stale,
+          traceSource: "intercept-loader",
         });
 
         if (!shouldRevalidate) {
@@ -355,6 +356,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
         context,
         actionContext,
         stale,
+        traceSource: "intercept-loader",
       });
 
       if (!shouldRevalidate) {

package/src/router/lazy-includes.ts

@@ -14,6 +14,7 @@ export interface LazyEvalDeps<TEnv = any> {
   mergedRouteMap: Record<string, string>;
   nextMountIndex: () => number;
   getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
+  routerId?: string;
 }
 
 // Detect lazy includes in handler result and create placeholder entries
@@ -200,6 +201,7 @@ export function evaluateLazyEntry<TEnv = any>(
       trailingSlash: entry.trailingSlash,
       handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
       mountIndex: deps.nextMountIndex(),
+      routerId: deps.routerId,
       // Lazy evaluation fields
       lazy: true,
       lazyPatterns: lazyInclude.patterns,

package/src/router/logging.ts

@@ -12,7 +12,10 @@ export interface RevalidationTraceEntry {
     | "cache-hit"
     | "loader"
     | "parallel"
-    | "orphan-layout";
+    | "orphan-layout"
+    | "route-handler"
+    | "layout-handler"
+    | "intercept-loader";
   defaultShouldRevalidate: boolean;
   finalShouldRevalidate: boolean;
   reason: string;

package/src/router/manifest.ts

@@ -65,7 +65,9 @@ export async function loadManifest(
   const mountIndex = entry.mountIndex;
 
   // Check module-level cache (persists across requests within same isolate)
-  const cacheKey = `${VERSION}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
+  // Include routerId so multi-router setups (host routing) don't share cached
+  // EntryData across routers with overlapping mountIndex + routeKey combinations.
+  const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
   const cached = manifestModuleCache.get(cacheKey);
   if (cached) {
     const cacheStart = performance.now();

package/src/router/router-context.ts

@@ -189,7 +189,10 @@ export interface RouterContext<TEnv = any> {
       | "cache-hit"
       | "loader"
       | "parallel"
-      | "orphan-layout";
+      | "orphan-layout"
+      | "route-handler"
+      | "layout-handler"
+      | "intercept-loader";
   }) => Promise<boolean>;
 
   // Request context

package/src/router/segment-resolution/revalidation.ts

@@ -608,6 +608,8 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         context,
         actionContext,
         stale,
+        traceSource:
+          entry.type === "route" ? "route-handler" : "layout-handler",
       });
       emitRevalidationDecision(
         entry.shortCode,

package/src/router.ts

@@ -560,6 +560,7 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
   function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -751,6 +752,7 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -770,6 +772,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -813,6 +816,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,

package/src/types/route-entry.ts

@@ -55,6 +55,13 @@ export interface RouteEntry<TEnv = any> {
     | Promise<() => Array<AllUseItems>>;
   mountIndex: number;
 
+  /**
+   * Router ID that owns this entry. Used to namespace the manifest cache
+   * so multi-router setups (host routing) don't share cached EntryData
+   * across routers with overlapping mountIndex + routeKey combinations.
+   */
+  routerId?: string;
+
   /**
    * Route keys in this entry that have pre-render handlers.
    * Used by the non-trie match path to set the `pr` flag.