@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/browser/rsc-router.tsx

@@ -8,6 +8,8 @@ import {
   generateHistoryKey,
 } from "./navigation-store.js";
 import { createEventController } from "./event-controller.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
@@ -21,12 +23,23 @@ import type {
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import { expandPayloadFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
+import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import {
+  setPrefetchConcurrency,
+  setPrefetchDecoder,
+} from "./prefetch/loader.js";
+import { setDefaultPrefetchStrategy } from "./prefetch/default-strategy.js";
+import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
   splitInterceptSegments,
 } from "./intercept-utils.js";
+import { createAppShellRef } from "./app-shell.js";
+import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { setActiveInterceptTargets } from "../client-urls/navigation.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -57,8 +70,11 @@ export interface InitBrowserAppOptions {
 
   /**
    * Enable global link interception for SPA navigation.
-   * When enabled, clicks on same-origin anchor elements are intercepted
-   * and handled via client-side navigation instead of full page loads.
+   * When enabled, clicks on eligible same-origin HTML anchor elements are intercepted
+   * and handled via client-side navigation instead of full page loads. Plain
+   * anchors inside the router basename also follow its default prefetch strategy
+   * after hydration. `data-prefetch="false"`/`"none"` opts out; `"true"` allows
+   * an application route with a common static-resource suffix.
    *
    * Links rendered with the Link component handle their own navigation
    * regardless of this setting.
@@ -111,15 +127,28 @@ export interface BrowserAppContext {
   initialTheme?: Theme;
   /** Whether connection warmup is enabled */
   warmupEnabled?: boolean;
+  /** Whether the hydrated tree should be wrapped in React.StrictMode */
+  strictMode?: boolean;
+  /** Whether plain-anchor click interception and delegated prefetch are enabled */
+  linkInterceptionEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
+  /**
+   * App-shell ref, read through on each render so renderSegments and the
+   * NavigationProvider see rootLayout/basename/version without closing over a
+   * stale snapshot. Set once from the initial payload and not swapped within a
+   * session: a cross-app navigation is a full document load (X-RSC-Reload), so
+   * the target app establishes its own shell on load. Theme, warmup, and
+   * prefetch TTL are document-lifetime too (see AppShell).
+   */
+  appShellRef?: import("./app-shell.js").AppShellRef;
 }
 
 // Module-level state for the initialized app
 let browserAppContext: BrowserAppContext | null = null;
 
 /**
- * Initialize the browser app. Must be called before rendering RSCRouter.
+ * Initialize the browser app. Must be called before rendering Rango.
  *
  * This function:
  * - Loads the initial RSC payload from the stream
@@ -139,10 +168,19 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
-  // Load initial payload from SSR-injected __FLIGHT_DATA__
+  bootLog("initBrowserApp start");
+  bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
+  // Shell-HIT documents carry replayed segments as VERBATIM stored fragments
+  // (segment-fragments.ts, issue #700); expand them through the browser
+  // deserializer BEFORE any consumer reads the segments (store seed,
+  // renderSegments, history cache). Non-HIT payloads have no envelopes and pay
+  // one field scan. The SSR resume pass ran the same expansion (ssr-root.tsx),
+  // so the hydrated tree matches the server-rendered one by construction.
+  await expandPayloadFragments(initialPayload, deps.createFromReadableStream);
+
   // Extract themeConfig and initialTheme from payload if not explicitly provided
   // This allows virtual entries to work without importing the router
   const effectiveThemeConfig =
@@ -153,8 +191,27 @@ export async function initBrowserApp(
   // Get initial segments and compute history key from current URL
   const initialSegments = (initialPayload.metadata?.segments ??
     []) as ResolvedSegment[];
+  if (IS_BROWSER_DEBUG) {
+    bootLog("initial payload decoded", {
+      version: initialPayload.metadata?.version,
+      routerId: initialPayload.metadata?.routerId,
+      segments: initialSegments.map((s) => s.id),
+      matched: initialPayload.metadata?.matched,
+    });
+  }
   const initialHistoryKey = generateHistoryKey(window.location.href);
 
+  // Resolve the state namespace before the store installs its BroadcastChannel
+  // listener. A streaming handle payload can delay hydration below; leaving the
+  // default name active during that wait would discard this router's messages.
+  const version = initialPayload.metadata?.version;
+  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
+
+  // Seed the intercept-target set for the initial location so the FIRST
+  // clientUrls navigation already declines intercepted targets (refreshed on
+  // every commit in partial-update.ts).
+  setActiveInterceptTargets(initialPayload.metadata?.interceptTargets);
+
   // Create navigation store with history-based caching
   const store = createNavigationStore({
     initialLocation: window.location,
@@ -164,6 +221,18 @@ export async function initBrowserApp(
     ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
   });
 
+  // Register the active store on the module-level handle and wire the
+  // jar-divergence observer before any getRangoState() read can detect a
+  // cross-tab/server rotation. There is no global store singleton, so this
+  // handle is the live reference.
+  registerNavigationStore(store);
+
+  // Seed router identity from the initial SSR payload so the first
+  // cross-app SPA navigation can detect the app switch.
+  if (initialPayload.metadata?.routerId) {
+    store.setRouterId?.(initialPayload.metadata.routerId);
+  }
+
   // Create event controller for reactive state management
   const eventController = createEventController({
     initialLocation: new URL(window.location.href),
@@ -179,11 +248,24 @@ export async function initBrowserApp(
   // This ensures useHandle returns correct data during hydration to avoid mismatch
   // The handles property is an async generator that yields on each push
   if (initialPayload.metadata?.handles) {
+    // This for-await consumes the handle generator to completion BEFORE
+    // hydrateRoot is called — on a streaming/PPR document the generator only
+    // ends when its stream side does, so the per-push logs below are the
+    // primary probe for "the document render is holding hydration".
+    bootLog("handles: consuming payload handle stream (pre-hydration await)");
     const handlesGenerator = initialPayload.metadata.handles;
     let lastHandleData: Record<string, Record<string, unknown[]>> = {};
+    let handlePushes = 0;
     for await (const handleData of handlesGenerator) {
       lastHandleData = handleData;
+      if (IS_BROWSER_DEBUG) {
+        handlePushes += 1;
+        bootLog(`handles: push #${handlePushes}`, {
+          segments: Object.keys(handleData),
+        });
+      }
     }
+    bootLog("handles: stream complete", { pushes: handlePushes });
     // Initialize event controller with initial handle state before hydration.
     eventController.setHandleData(
       lastHandleData,
@@ -193,31 +275,108 @@ export async function initBrowserApp(
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
     store.updateCacheHandleData(initialHistoryKey, lastHandleData);
+
+    // Late handle channel: pushes from streaming loader bodies that missed the
+    // handler barrier (ctx.handle() writes mid-body). Consumed NON-BLOCKING —
+    // hydration must not wait on loader bodies — and applied through the same
+    // controller/cache path as the initial snapshot, so useHandle readers
+    // re-render as meta/breadcrumbs stream in.
+    const lateGenerator = initialPayload.metadata?.handlesLate;
+    if (lateGenerator) {
+      void (async () => {
+        try {
+          // Never apply before React commits hydration — a pre-commit
+          // application mutates the state useHandle initializers read during
+          // the hydration render (mismatch). Yields buffer in the generator
+          // meanwhile; nothing is lost.
+          await hydrationCommitted;
+          for await (const rawLateData of lateGenerator) {
+            // Handles are async by design: a push(promise) value resolves
+            // whenever it resolves — only SSR'd handles are awaited server-
+            // side. The main document snapshot arrives server-resolved
+            // (resolvedHandleStream); this late channel is raw, so resolve
+            // deferred values here exactly like the nav lane's processHandles
+            // does before applying.
+            const lateData = await resolveDeferredHandleValues(rawLateData);
+            bootLog("handles: late push applied", {
+              segments: Object.keys(lateData),
+            });
+            eventController.setHandleData(
+              lateData,
+              initialPayload.metadata?.matched,
+            );
+            store.updateCacheHandleData(initialHistoryKey, lateData);
+          }
+        } catch (err) {
+          console.error("[rsc-router] Error consuming late handles:", err);
+        }
+      })();
+    }
+  } else {
+    bootLog("handles: none in payload");
   }
 
   // Create composable utilities
   const client = createNavigationClient(deps);
 
-  // Extract rootLayout and version from metadata for browser-side re-renders
-  const rootLayout = initialPayload.metadata?.rootLayout;
-  const version = initialPayload.metadata?.version;
+  // Capture the per-router app-shell. rootLayout, basename, and version live
+  // here and are read through the ref at call time rather than closed over.
+  // It is set once from the initial payload and not swapped within a session:
+  // a cross-app navigation is a full document load (X-RSC-Reload), so the
+  // target app establishes its own shell on load.
+  const appShellRef = createAppShellRef({
+    routerId: initialPayload.metadata?.routerId,
+    rootLayout: initialPayload.metadata?.rootLayout,
+    basename: initialPayload.metadata?.basename,
+    version,
+  });
 
-  // Initialize the localStorage state key for cache invalidation.
-  // Uses the build version so a new deploy automatically busts all cached prefetches.
-  initRangoState(version ?? "0");
+  setAppVersion(version);
 
-  // Initialize the in-memory prefetch cache TTL from server config.
-  // A value of 0 disables the cache; undefined falls back to the module default.
+  // Initialize the in-memory prefetch cache (TTL + max size) and the prefetch
+  // queue concurrency from server config. A TTL of 0 disables the cache;
+  // undefined values fall back to the module defaults.
   const prefetchCacheTTL = initialPayload.metadata?.prefetchCacheTTL;
-  if (prefetchCacheTTL !== undefined) {
-    initPrefetchCache(prefetchCacheTTL);
+  const prefetchCacheSize = initialPayload.metadata?.prefetchCacheSize;
+  if (prefetchCacheTTL !== undefined || prefetchCacheSize !== undefined) {
+    initPrefetchCache(prefetchCacheTTL, prefetchCacheSize);
+  }
+  const prefetchConcurrency = initialPayload.metadata?.prefetchConcurrency;
+  if (prefetchConcurrency !== undefined) {
+    setPrefetchConcurrency(prefetchConcurrency);
+  }
+  // Apply the router-wide default Link prefetch strategy. Undefined (older
+  // server payload) keeps the module's environment-aware default, which equals
+  // the server resolver's default by contract — see default-strategy.ts.
+  const defaultPrefetch = initialPayload.metadata?.defaultPrefetch;
+  if (defaultPrefetch !== undefined) {
+    setDefaultPrefetchStrategy(defaultPrefetch);
   }
 
-  // Create a bound renderSegments that includes rootLayout
+  // Wire the RSC decoder so prefetches decode eagerly and warm the route's
+  // client chunks (same createFromFetch the navigation client uses). Fragment
+  // envelopes (#700) expand BEFORE the decoded payload enters the prefetch
+  // cache, so cached entries only ever resolve to expanded segments; a
+  // fragment-decode failure rejects the entry's payload and rides the cache's
+  // existing eviction path.
+  setPrefetchDecoder(async (response) => {
+    const payload = await deps.createFromFetch<RscPayload>(response);
+    await expandPayloadFragments(payload, deps.createFromReadableStream);
+    return payload;
+  });
+
+  // Create a bound renderSegments that reads rootLayout through the shell ref.
+  // The shell is set once at init and not swapped within a session (a cross-app
+  // navigation is a full document load), so this always renders this app's
+  // Document; reading through the ref just avoids closing over a stale value.
   const renderSegments = (
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
-  ) => baseRenderSegments(segments, { ...options, rootLayout });
+  ) =>
+    baseRenderSegments(segments, {
+      ...options,
+      rootLayout: appShellRef.get().rootLayout,
+    });
 
   // Lazy reference for navigation bridge — the action bridge is created first
   // but may need to trigger SPA navigation for action redirects.
@@ -231,10 +390,15 @@ export async function initBrowserApp(
     deps,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
     onNavigate: (url, options) => {
       if (!navigateFn) {
-        window.location.href = url;
+        // Navigation bridge not wired yet: hard-navigate, but re-validate
+        // same-origin defensively so this init-window fallback cannot become an
+        // open redirect (the normal path validates inside the navigation bridge).
+        const safe = validateRedirectOrigin(url, window.location.origin);
+        if (safe) {
+          window.location.href = safe;
+        }
         return Promise.resolve();
       }
       return navigateFn(url, options);
@@ -249,7 +413,9 @@ export async function initBrowserApp(
     client,
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
-    version,
+    version: version,
+    defaultPrefetch,
+    basename: initialPayload.metadata?.basename,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -259,9 +425,17 @@ export async function initBrowserApp(
   if (linkInterception) {
     navigationBridge.registerLinkInterception();
   }
+  bootLog("bridges registered (action + navigation)");
 
   // Build initial tree with rootLayout
+  bootLog("building initial segment tree (renderSegments)");
   const initialTree = renderSegments(initialPayload.metadata!.segments);
+  if (IS_BROWSER_DEBUG && initialTree instanceof Promise) {
+    initialTree.then(
+      () => bootLog("initial segment tree settled"),
+      (err: unknown) => bootLog("initial segment tree rejected", { err }),
+    );
+  }
 
   // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
   // fire many rsc:update events in quick succession. Without debouncing,
@@ -294,11 +468,11 @@ export async function initBrowserApp(
         // full lifecycle (fetching + streaming, before commit) without
         // blocking on server actions.
         if (eventController.getState().isNavigating) {
-          console.log("[RSCRouter] HMR: Skipping — navigation in progress");
+          console.log("[Rango] HMR: Skipping — navigation in progress");
           return;
         }
 
-        console.log("[RSCRouter] HMR: Server update, refetching RSC");
+        console.log("[Rango] HMR: Server update, refetching RSC");
 
         const abort = new AbortController();
         hmrAbort = abort;
@@ -316,6 +490,7 @@ export async function initBrowserApp(
             segmentIds: [],
             previousUrl: store.getSegmentState().currentUrl,
             interceptSourceUrl: interceptSourceUrl || undefined,
+            routerId: store.getRouterId?.(),
             hmr: true,
             signal: abort.signal,
           });
@@ -329,6 +504,35 @@ export async function initBrowserApp(
             throw new Error("HMR refetch returned invalid payload");
           }
 
+          // Update version BEFORE rebuilding state so that
+          // clearHistoryCache() runs first, then the fresh segment
+          // cache entry we create below survives.
+          //
+          // Compare against the bridge's live version, not the init-time
+          // `version` const: after the first HMR bump the const is stale, so a
+          // later update with an unchanged version would otherwise re-clear the
+          // cache and re-broadcast across tabs/apps. The live read fires only
+          // on a genuine version change.
+          const newVersion = payload.metadata.version;
+          const currentVersion = navigationBridge.getVersion();
+          if (newVersion && newVersion !== currentVersion) {
+            console.log(
+              "[Rango] HMR: version changed",
+              currentVersion,
+              "→",
+              newVersion,
+              "clearing caches",
+            );
+            navigationBridge.updateVersion(newVersion);
+          }
+
+          // Apply only partial segment updates. A non-partial payload during
+          // HMR is transient: the worker route table is still rebuilding after
+          // the edit, so the URL momentarily resolves to not-found/catch-all.
+          // Skip it -- the debounced follow-up refetch returns the settled
+          // route's partial payload and renders it below. We never reload here:
+          // a paramless document GET would run the SSR path and surface the
+          // not-found page during that same transient.
           if (payload.metadata?.isPartial) {
             const segments = payload.metadata.segments || [];
             const matched = payload.metadata.matched || [];
@@ -368,10 +572,10 @@ export async function initBrowserApp(
 
           await streamComplete;
           handle.complete(new URL(window.location.href));
-          console.log("[RSCRouter] HMR: RSC stream complete");
+          console.log("[Rango] HMR: RSC stream complete");
         } catch (err) {
           if (abort.signal.aborted) return;
-          console.warn("[RSCRouter] HMR: Refetch failed, reloading page", err);
+          console.warn("[Rango] HMR: Refetch failed, reloading page", err);
           window.location.reload();
           return;
         } finally {
@@ -383,7 +587,7 @@ export async function initBrowserApp(
     });
   }
 
-  // Store context for RSCRouter component
+  // Store context for Rango component
   const context: BrowserAppContext = {
     store,
     eventController,
@@ -393,20 +597,40 @@ export async function initBrowserApp(
     themeConfig: effectiveThemeConfig,
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
+    strictMode: initialPayload.metadata?.strictMode ?? true,
+    linkInterceptionEnabled: linkInterception,
     version,
+    appShellRef,
   };
   browserAppContext = context;
 
+  bootLog("initBrowserApp complete -- handing off to hydrateRoot");
   return context;
 }
 
+// Once-flag so the hydration-commit boot log fires a single time (StrictMode
+// re-runs the root effect; the second flush is not a second hydration).
+let hydrationCommitLogged = false;
+
+// Hydration-commit barrier for the late handle channel. useHandle's useState
+// initializer reads the eventController's LIVE state during the hydration
+// render, so applying a late handle update BEFORE hydration commits changes
+// that state out from under React — the classic "external changing data"
+// hydration mismatch (seen when a loader's push lost the handler-barrier race
+// by milliseconds and its late yield landed mid-hydration). The root effect
+// below resolves this; the late consumer awaits it before applying anything.
+let resolveHydrationCommitted!: () => void;
+const hydrationCommitted: Promise<void> = new Promise((resolve) => {
+  resolveHydrationCommitted = resolve;
+});
+
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
 export function getBrowserAppContext(): BrowserAppContext {
   if (!browserAppContext) {
     throw new Error(
-      "RSCRouter: initBrowserApp() must be called before rendering RSCRouter",
+      "Rango: initBrowserApp() must be called before rendering Rango",
     );
   }
   return browserAppContext;
@@ -420,18 +644,18 @@ export function resetBrowserAppContext(): void {
 }
 
 /**
- * Props for the RSCRouter component
+ * Props for the Rango component
  */
-export interface RSCRouterProps {}
+export interface RangoProps {}
 
 /**
- * RSCRouter component - renders the RSC router with all internal wiring.
+ * Rango component - renders the RSC router with all internal wiring.
  *
  * Must be called after initBrowserApp() has completed.
  *
  * @example
  * ```tsx
- * import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "rsc-router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *
@@ -441,14 +665,14 @@ export interface RSCRouterProps {}
  *   hydrateRoot(
  *     document,
  *     <React.StrictMode>
- *       <RSCRouter />
+ *       <Rango />
  *     </React.StrictMode>
  *   );
  * }
  * main();
  * ```
  */
-export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
+export function Rango(_props: RangoProps): React.ReactElement {
   const {
     store,
     eventController,
@@ -459,6 +683,8 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
     initialTheme,
     warmupEnabled,
     version,
+    appShellRef,
+    linkInterceptionEnabled,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -466,7 +692,18 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
   // that does not depend on React internals like __reactFiber.
   React.useEffect(() => {
     document.documentElement.dataset.hydrated = "";
-  }, []);
+    const cleanupPrefetch = linkInterceptionEnabled
+      ? bridge.registerDelegatedPrefetch()
+      : undefined;
+    if (IS_BROWSER_DEBUG && !hydrationCommitLogged) {
+      hydrationCommitLogged = true;
+      bootLog("hydration commit (root effect flushed)");
+    }
+    // Release the late handle channel (see hydrationCommitted above).
+    // StrictMode double-invoke: resolving twice is a no-op.
+    resolveHydrationCommitted();
+    return cleanupPrefetch;
+  }, [bridge, linkInterceptionEnabled]);
 
   return (
     <NavigationProvider
@@ -478,6 +715,8 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       initialTheme={initialTheme}
       warmupEnabled={warmupEnabled}
       version={version}
+      basename={initialPayload.metadata?.basename}
+      appShellRef={appShellRef}
     />
   );
 }

package/src/browser/scroll-restoration.ts

@@ -8,7 +8,7 @@
  * - Supports hash link scrolling
  */
 
-import { debugLog } from "./logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Defers a callback to the next animation frame.
@@ -150,10 +150,12 @@ export function initScrollRestoration(options?: {
 
   window.addEventListener("pagehide", handlePageHide);
 
-  debugLog(
-    "[Scroll] Initialized, loaded positions:",
-    Object.keys(savedScrollPositions).length,
-  );
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      "[Scroll] Initialized, loaded positions:",
+      Object.keys(savedScrollPositions).length,
+    );
+  }
 
   return () => {
     cancelScrollRestorationPolling();
@@ -191,10 +193,15 @@ export function saveCurrentScrollPosition(): void {
 
 /**
  * Persist scroll positions to sessionStorage.
- * If the write fails due to quota exceeded, progressively evict the oldest
- * entries and retry until it succeeds or the store is empty.
+ * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
+ * entries ONCE and retry the write a single time; if that still fails, remove
+ * our storage key entirely so we don't block other sessionStorage consumers.
+ * This is a single evict-then-retry-then-clear ladder, not a loop.
+ *
+ * Exported so that single eviction/retry/clear ladder is unit-testable directly.
+ * The browser drives it from the `pagehide` handler.
  */
-function persistToSessionStorage(): void {
+export function persistToSessionStorage(): void {
   try {
     sessionStorage.setItem(
       SCROLL_STORAGE_KEY,
@@ -332,6 +339,8 @@ export function scrollToHash(): boolean {
  * Scroll to top of page
  */
 export function scrollToTop(): void {
+  if (typeof window === "undefined") return;
+  if (typeof window.scrollTo !== "function") return;
   window.scrollTo(0, 0);
 }
 
@@ -356,36 +365,44 @@ export function handleNavigationEnd(options: {
   scroll?: boolean;
   isStreaming?: () => boolean;
 }): void {
-  if (!initialized) {
-    return;
-  }
-
   const { restore = false, scroll = true, isStreaming } = options;
 
-  // Don't scroll if explicitly disabled
-  if (scroll === false) {
+  // Don't scroll if explicitly disabled or not in a browser
+  if (scroll === false || typeof window === "undefined") {
     return;
   }
 
-  // For back/forward (restore), try to restore saved position
-  if (restore) {
+  // Save/restore requires initialization (sessionStorage, history state).
+  // But basic scroll-to-top and hash scrolling work without it — this
+  // matters during cross-app navigation where ScrollRestoration unmounts
+  // and remounts, creating a brief window where initialized is false.
+  if (restore && initialized) {
     if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
       return;
     }
     // Fall through to hash or top if no saved position
   }
 
-  // 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.
-  deferToNextPaint(() => {
-    // Try hash scrolling first
-    if (scrollToHash()) {
-      return;
-    }
-
-    // Default: scroll to top
-    scrollToTop();
-  });
+  // scrollToHash / scrollToTop run synchronously here.
+  // handleNavigationEnd is invoked from NavigationProvider's
+  // useLayoutEffect (post-commit, pre-paint), so a sync scrollTo is
+  // captured by the upcoming paint AND by startViewTransition's snapshot.
+  // Deferring via rAF here pushed the call past the snapshot capture,
+  // making forward navigations wrapped in a layout/route view transition
+  // skip scroll-to-top — the live DOM scrolled but the captured snapshot
+  // was at the previous scroll position, so the user-facing page stayed
+  // visually clamped at the source page's scrollY (often the new tree's
+  // max scroll for tall→short navs). Y=0 / a hash element are robust
+  // 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.)
+  if (scrollToHash()) {
+    return;
+  }
+  scrollToTop();
 }
 
 /**