@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/client/browser-entry.ts

@@ -28,14 +28,20 @@ import {
   createFromFetch,
   setServerCallback,
   encodeReply,
-} from '#/rsc-runtime/browser.js';
+} from '../rsc-runtime/browser.js';
 // Shared-state modules MUST be imported from @timber-js/app/client (the public
 // barrel) so they resolve to the same module instances as user code. In Vite dev,
 // user code imports @timber-js/app/client from dist/ via package.json exports.
 // If we used relative imports (./router-ref.js), Vite would load separate src/
 // copies with separate module-level state — e.g., globalRouter set here but
 // read as null from the dist/ copy used by useRouter().
-import { createRouter, setGlobalRouter, getRouter, setCurrentParams } from '@timber-js/app/client';
+import {
+  createRouter,
+  setGlobalRouter,
+  getRouter,
+  getRouterOrNull,
+  setCurrentParams,
+} from '@timber-js/app/client';
 import type { RouterDeps, RouterInstance } from '@timber-js/app/client';
 
 // Internal-only modules (no shared mutable state with user code) use relative
@@ -47,12 +53,35 @@ import {
   NavigationProvider,
   getNavigationState,
   setNavigationState,
+  type NavigationState,
 } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 // browser-links.ts removed — Link components own their click/hover handlers directly.
 // See LOCAL-340.
-import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
-import { isStaleClientReference, triggerStaleReload, clearStaleReloadFlag } from './stale-reload.js';
+import {
+  NavigationRoot,
+  transitionRender,
+  navigateTransition,
+  installDeferredNavigation,
+  setHardNavigating,
+} from './navigation-root.js';
+import {
+  isStaleClientReference,
+  isChunkLoadError,
+  triggerStaleReload,
+  clearStaleReloadFlag,
+} from './stale-reload.js';
+import {
+  setClientDeploymentId,
+  getClientDeploymentId,
+  DEPLOYMENT_ID_HEADER,
+  RELOAD_HEADER,
+} from './rsc-fetch.js';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from './navigation-api.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -81,14 +110,28 @@ setServerCallback(async (id: string, args: unknown[]) => {
   let hasRedirect = false;
   let headElementsJson: string | null = null;
 
+  // Build action request headers. Include deployment ID for version
+  // skew detection (TIM-446) — the server rejects stale actions gracefully.
+  const actionHeaders: Record<string, string> = {
+    'Accept': 'text/x-component',
+    'x-rsc-action': id,
+  };
+  const actionDeploymentId = getClientDeploymentId();
+  if (actionDeploymentId) {
+    actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+  }
+
   const response = fetch(window.location.href, {
     method: 'POST',
-    headers: {
-      'Accept': 'text/x-component',
-      'x-rsc-action': id,
-    },
+    headers: actionHeaders,
     body,
   }).then((res) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // trigger a full page load to pick up the new deployment.
+    if (res.headers.get(RELOAD_HEADER) === '1') {
+      window.location.reload();
+      throw new Error('Version skew detected — reloading page');
+    }
     hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
     hasRedirect = res.headers.get('X-Timber-Redirect') != null;
     headElementsJson = res.headers.get('X-Timber-Head');
@@ -115,7 +158,10 @@ setServerCallback(async (id: string, args: unknown[]) => {
       const router = getRouter();
       void router.navigate(wrapper._redirect);
     } catch {
-      // Router not yet initialized — fall back to full navigation
+      // Router not yet initialized — fall back to full navigation.
+      // Set hard-navigating flag to prevent Navigation API interception
+      // and React from rendering during page teardown. See TIM-626.
+      setHardNavigating(true);
       window.location.href = wrapper._redirect;
     }
     return undefined;
@@ -155,7 +201,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
  * Hydrates the server-rendered HTML with React, then initializes
  * client-side navigation for SPA transitions.
  */
-/** Read scroll position from window or scroll containers. */
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
 function getScrollY(): number {
   if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
@@ -163,74 +219,24 @@ function getScrollY(): number {
   for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
     if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
   }
-  // Auto-detect: if window isn't scrolled, check for overflow containers.
-  // Common pattern: layouts use a scrollable div (overflow-y: auto/scroll)
-  // inside a fixed-height parent (h-screen). In this case window.scrollY is
-  // always 0 and the real scroll position lives on the overflow container.
-  const container = findOverflowContainer();
-  if (container && container.scrollTop > 0) return container.scrollTop;
   return 0;
 }
 
-/**
- * Find the primary overflow scroll container in the document.
- *
- * Walks direct children of body and their immediate children looking for
- * an element with overflow-y: auto|scroll that is actually scrollable
- * (scrollHeight > clientHeight). Returns the first match, or null.
- *
- * This heuristic covers the common layout patterns:
- *   <body> → <root-layout> → <div class="overflow-y-auto">
- *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
- *
- * We limit depth to 3 to avoid expensive full-tree traversals while still
- * reaching nested layout scroll containers (e.g., parallel route layouts
- * inside a root layout's <main> element).
- *
- * DIVERGENCE FROM NEXT.JS: Next.js's ScrollAndFocusHandler scrolls only
- * document.documentElement.scrollTop — it does NOT handle overflow containers.
- * Layouts using h-screen + overflow-y-auto have the same scroll bug in Next.js.
- * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-3
- * traversal may miss deeply nested containers or match the wrong element.
- * See design/19-client-navigation.md §"Overflow Scroll Containers".
- */
-function findOverflowContainer(): HTMLElement | null {
-  const candidates: HTMLElement[] = [];
-  // Check body's descendants up to depth 3. Depth 3 covers the common case:
-  //   <body> → <root-layout-div> → <main> → <overflow-container>
-  // React context providers (SegmentProvider, NavigationProvider) don't add
-  // DOM elements, so depth 3 from body reaches nested layout scroll containers.
-  for (const child of document.body.children) {
-    candidates.push(child as HTMLElement);
-    for (const grandchild of child.children) {
-      candidates.push(grandchild as HTMLElement);
-      for (const greatGrandchild of grandchild.children) {
-        candidates.push(greatGrandchild as HTMLElement);
-      }
-    }
-  }
-  for (const el of candidates) {
-    if (!(el instanceof HTMLElement)) continue;
-    const style = getComputedStyle(el);
-    const overflowY = style.overflowY;
-    if (
-      (overflowY === 'auto' || overflowY === 'scroll') &&
-      el.scrollHeight > el.clientHeight
-    ) {
-      return el;
-    }
-  }
-  return null;
-}
-
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
-  // Take manual control of scroll restoration. React's render() on the
-  // document root resets scroll during DOM reconciliation, so the browser's
-  // native scroll restoration (scrollRestoration = 'auto') doesn't work —
-  // the browser restores scroll, then React's commit resets it to 0.
-  // We save/restore scroll positions explicitly in the history stack.
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (_config as Record<string, unknown>).deploymentId as string | null;
+  if (deploymentId) {
+    setClientDeploymentId(deploymentId);
+  }
+
+  // Take manual control of scroll restoration. Even though segment tree
+  // merging preserves shared layout DOM via cloneElement (so React doesn't
+  // reset scroll on those elements), the root-level reactRoot.render() with
+  // a new element tree can still cause scroll resets on the document during
+  // reconciliation. Manual control ensures consistent behavior.
   window.history.scrollRestoration = 'manual';
 
   // Hydrate the React tree from the RSC payload.
@@ -246,7 +252,13 @@ function bootstrap(runtimeConfig: typeof config): void {
   // For subsequent navigations, it's fetched from the server.
   type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
 
-  const timberChunks = (self as unknown as Record<string, FlightSegment[]>).__timber_f;
+  // __timber_f is initialized in <head> via flightInitScript() (see
+  // flight-scripts.ts). If it doesn't exist, skip Flight decoding
+  // entirely and fall through to the createRoot branch.
+  // Do NOT defensively create it here: that would cause
+  // createFromReadableStream to be called on an empty stream, producing
+  // a "Connection closed" error on hydration. See TIM-552.
+  const timberChunks = (self as unknown as Record<string, FlightSegment[] | undefined>).__timber_f;
 
   let _reactRoot: Root | null = null;
   let initialElement: unknown = null;
@@ -254,6 +266,12 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Assigned inside initRouter() which is called in both branches.
   let router!: RouterInstance;
 
+  // Navigation API controller — initialized when the API is available.
+  // Declared here (before the hydration if/else) because initRouter()
+  // is called from runPreHydration() inside both branches, and it
+  // assigns to this variable. Must be in scope before first use.
+  let navApiController: NavigationApiController | null = null;
+
   if (timberChunks) {
     const encoder = new TextEncoder();
 
@@ -318,6 +336,28 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Leaving the stream open is harmless: the page is being torn down.
     function onDOMContentLoaded(): void {
       if (isPageUnloading()) return;
+
+      // In dev mode, do NOT close the stream. React's RSC renderer
+      // includes debug owner/stack references ($1, $14, etc.) in the
+      // Flight payload that point to rows delivered through the debug
+      // channel, not the main Flight stream. The browser Flight client
+      // tracks these as pending chunks. Closing the stream with
+      // unresolved chunks triggers reportGlobalError("Connection closed")
+      // which kills the entire React tree.
+      //
+      // Leaving the stream open is harmless: React has already received
+      // all data rows and can hydrate fully. The pending debug chunks
+      // just remain unresolved (they're only used for React DevTools
+      // component stacks, not rendering).
+      //
+      // In production, debug rows are not emitted, so closing is safe.
+      if (process.env.NODE_ENV === 'development') {
+        // Mark as flushed so no more data is buffered, but don't close.
+        streamFlushed = true;
+        dataBuffer = undefined;
+        return;
+      }
+
       if (streamWriter && !streamFlushed) {
         streamWriter.close();
         streamFlushed = true;
@@ -329,49 +369,58 @@ function bootstrap(runtimeConfig: typeof config): void {
     if (document.readyState === 'loading') {
       document.addEventListener('DOMContentLoaded', onDOMContentLoaded, false);
     } else {
-      // DOM already parsed — close after a microtask to ensure
-      // any pending push() calls from inline scripts have executed.
-      setTimeout(onDOMContentLoaded);
+      // DOM already parsed. All inline RSC <script> tags have already
+      // executed and pushed their data into the buffer. The buffer was
+      // flushed into the stream during start() above.
+      //
+      // Close via queueMicrotask rather than setTimeout. setTimeout
+      // defers to the next macrotask, which can race with React's
+      // Flight client read loop — if React finishes reading all queued
+      // chunks and issues a reader.read() that pends, the stream is
+      // NOT closed yet (setTimeout hasn't fired), so React sees an
+      // open stream and waits. Then setTimeout fires and closes it.
+      // This works in theory but some React Flight builds interpret
+      // a mid-read close as "Connection closed" rather than clean EOF.
+      // queueMicrotask fires at the end of the current microtask
+      // checkpoint — after start() and createFromReadableStream
+      // initialization but before any macrotask, giving React a
+      // consistent close signal. See TIM-524.
+      queueMicrotask(onDOMContentLoaded);
     }
 
     const element = createFromReadableStream(rscPayload);
     initialElement = element;
 
-    // ── Initialize the navigation router BEFORE hydration ──────────────
-    // hydrateRoot() synchronously executes component render functions.
-    // Components that call useRouter() during render need the global
-    // router to be available, otherwise they get a stale no-op reference.
-    // The router must be initialized before hydration so useRouter() works.
-    // renderRoot uses transitionRender (no direct reactRoot dependency).
-    initRouter();
-
-    // ── Initialize navigation state BEFORE hydration ───────────────────
-    // Read server-embedded params and set navigation state so that
-    // useParams() and usePathname() return correct values during hydration.
-    // This must happen before hydrateRoot so the NavigationProvider
-    // wrapping the element has the right values on the initial render.
-    const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
-    if (earlyParams && typeof earlyParams === 'object') {
-      setCurrentParams(earlyParams as Record<string, string | string[]>);
-      setNavigationState({
-        params: earlyParams as Record<string, string | string[]>,
-        pathname: window.location.pathname,
-      });
-      delete (self as unknown as Record<string, unknown>).__timber_params;
-    } else {
-      setNavigationState({
-        params: {},
-        pathname: window.location.pathname,
-      });
-    }
+    // ── Pre-hydration bootstrap sequence ──────────────────────────────
+    //
+    // These steps MUST execute in this exact order before hydrateRoot():
+    //
+    //   1. initRouter()        — creates the global router so useRouter()
+    //                            works during render (methods lazily resolve
+    //                            the router at invocation, not render time,
+    //                            but initRouter must still run first)
+    //
+    //   2. setCurrentParams()  — populates module-level params snapshot so
+    //      + setNavigationState()  useSegmentParams() and usePathname()
+    //                            return correct values during hydration
+    //
+    //   3. hydrateRoot()       — synchronously executes component render
+    //                            functions that depend on steps 1-2
+    //
+    // Implicit prerequisite: the __timber_f RSC stream (ReadableStream
+    // above) must be wired up before hydrateRoot, because React starts
+    // consuming it synchronously during hydration.
+    //
+    // See design/19-client-navigation.md §"NavigationContext"
+    runPreHydration(element);
 
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
     // Wrap with NavigationProvider (for atomic useParams/usePathname),
-    // TimberNuqsAdapter (for nuqs context), and TransitionRoot (for
+    // TimberNuqsAdapter (for nuqs context), and NavigationRoot (for
     // transition-based rendering during client navigation).
     //
-    // TransitionRoot holds the element in React state and updates via
+    // NavigationRoot holds the element in React state and updates via
     // startTransition, so React keeps old UI visible while new Suspense
     // boundaries resolve during navigation. See design/05-streaming.md.
     const navState = getNavigationState();
@@ -381,7 +430,19 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, { initial: wrapped, topLoaderConfig: _config.topLoader });
+    const rootElement = createElement(NavigationRoot, {
+      initial: wrapped,
+      topLoaderConfig: _config.topLoader,
+    });
+
+    if (process.env.NODE_ENV !== 'production') {
+      if (!getRouterOrNull()) {
+        throw new Error(
+          '[timber] hydrateRoot called before initRouter() — bootstrap order violated'
+        );
+      }
+    }
+
     _reactRoot = hydrateRoot(document, rootElement, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these
@@ -401,42 +462,64 @@ function bootstrap(runtimeConfig: typeof config): void {
       },
     });
   } else {
-    // No RSC payload available (plugin hasn't inlined it yet) — create a
-    // non-hydrated root so client navigation can still render RSC payloads.
-    // The initial SSR HTML remains as-is; the first client navigation will
-    // replace it with a React-managed tree.
-    initRouter();
-    _reactRoot = createRoot(document);
+    // No RSC payload available — create a non-hydrated root so client
+    // navigation can still render RSC payloads. The initial SSR HTML
+    // remains as-is; the first client navigation will replace it with
+    // a React-managed tree.
+    runPreHydration(null);
+    // Defer React root creation until first client navigation (TIM-600).
+    //
+    // We must NOT call createRoot(document).render() here — that would take
+    // React ownership of the entire document and blank the SSR HTML.
+    // Instead, installDeferredNavigation sets up one-shot callbacks so the
+    // first navigateTransition/transitionRender call creates the root on
+    // `document` with the navigated content. After that initial render,
+    // NavigationRoot's real startTransition-based callbacks take over.
+    //
+    // This also fixes TIM-580 (navigation from SSR-only pages) because the
+    // deferred callbacks ensure NavigationRoot is mounted before the first
+    // navigation completes.
+    installDeferredNavigation((initial) => {
+      const rootElement = createElement(NavigationRoot, {
+        initial,
+        topLoaderConfig: _config.topLoader,
+      });
+      _reactRoot = createRoot(document);
+      _reactRoot.render(rootElement);
+    });
   }
 
   // ── Router initialization (hoisted above hydrateRoot) ────────────────
   // Extracted into a function so both the hydration and createRoot paths
   // can call it. Must run before hydrateRoot so useRouter() works during
   // the initial render. renderRoot uses transitionRender which is set
-  // by the TransitionRoot component during hydration.
+  // by the NavigationRoot component during hydration.
   function initRouter(): void {
+    // Feature-detect Navigation API. When available, the navigate event
+    // replaces popstate for back/forward and catches external navigations.
+    // See design/19-client-navigation.md §"Navigation API Integration"
+    const useNavApi = hasNavigationApi();
+
     const deps: RouterDeps = {
       fetch: (url, init) => window.fetch(url, init),
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
+      navigationApiActive: useNavApi,
       scrollTo: (x, y) => {
+        // Scroll the document viewport.
         window.scrollTo(x, y);
         document.documentElement.scrollTop = y;
         document.body.scrollTop = y;
-        // Also scroll any element explicitly marked as a scroll container.
+        // Scroll any element explicitly marked as a scroll container.
+        // With segment tree merging, shared layouts (sidebars, nav bars)
+        // are reconciled in place via cloneElement — React preserves their
+        // DOM and scroll state naturally. We no longer auto-detect overflow
+        // containers, which previously found the wrong element (e.g.,
+        // scrolling a sidebar instead of the main content area).
+        // Use `data-timber-scroll-restoration` to opt in specific containers.
         for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
           (el as HTMLElement).scrollTop = y;
         }
-        // Auto-detect overflow containers for layouts that scroll inside
-        // a fixed-height wrapper (e.g., h-screen + overflow-y-auto).
-        // In these layouts, window.scrollY is always 0 and the real scroll
-        // lives on the overflow container. Without this, forward navigation
-        // between pages that share a layout with parallel route slots won't
-        // scroll to top — the router's window.scrollTo(0,0) is a no-op.
-        const container = findOverflowContainer();
-        if (container) {
-          container.scrollTop = y;
-        }
       },
       getCurrentUrl: () => window.location.pathname + window.location.search,
       getScrollY,
@@ -464,15 +547,17 @@ function bootstrap(runtimeConfig: typeof config): void {
         }
       },
 
-      // Render decoded RSC tree via TransitionRoot's state-based mechanism.
+      // Render decoded RSC tree via NavigationRoot's state-based mechanism.
       // Used for non-navigation renders (popstate cached replay, applyRevalidation).
       // Wraps with NavigationProvider + TimberNuqsAdapter.
       //
       // For navigation renders (navigate, refresh, popstate-with-fetch),
       // navigateTransition is used instead — it wraps the entire navigation
       // in a React transition with useOptimistic for the pending URL.
-      renderRoot: (element: unknown) => {
-        const navState = getNavigationState();
+      //
+      // navState is passed explicitly by the router — no temporal coupling
+      // with getNavigationState().
+      renderRoot: (element: unknown, navState: NavigationState) => {
         const withNav = createElement(
           NavigationProvider,
           { value: navState },
@@ -488,13 +573,11 @@ function bootstrap(runtimeConfig: typeof config): void {
       // commits (atomic with the new tree + params).
       //
       // The perform callback receives a wrapPayload function that wraps the
-      // decoded RSC payload with NavigationProvider + NuqsAdapter — this must
-      // happen inside the transition so the NavigationProvider reads the
-      // UPDATED navigation state (set by the router inside perform).
+      // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+      // is passed explicitly by the router — no getNavigationState() needed.
       navigateTransition: (pendingUrl: string, perform) => {
         return navigateTransition(pendingUrl, async () => {
-          const payload = await perform((rawPayload: unknown) => {
-            const navState = getNavigationState();
+          const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
             const withNav = createElement(
               NavigationProvider,
               { value: navState },
@@ -522,6 +605,62 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     router = createRouter(deps);
     setGlobalRouter(router);
+
+    // Set up Navigation API integration after router is created.
+    // The navigate event listener delegates to router.navigate and
+    // router.handlePopState for external navigations and traversals.
+    if (useNavApi) {
+      navApiController = setupNavigationApi({
+        onExternalNavigate: async (url, { replace, signal, scroll }) => {
+          // Navigation intercepted by the Navigation API. Covers both
+          // Link <a> clicks (user-initiated) and external navigations.
+          // The Navigation API handles the URL update via intercept(),
+          // so pass _skipHistory to avoid double pushState.
+          await router.navigate(url, {
+            replace,
+            scroll,
+            _signal: signal,
+            _skipHistory: true,
+          });
+        },
+        onTraverse: async (url, scrollY, signal) => {
+          // Back/forward — delegate to the router's popstate handler.
+          await router.handlePopState(url, scrollY, signal);
+        },
+      });
+
+      // Wire the router-navigating flag into RouterDeps.
+      // This must be done after setupNavigationApi returns the controller.
+      deps.setRouterNavigating = (v) => navApiController!.setRouterNavigating(v);
+      deps.saveNavigationEntryScroll = (y) => navApiController!.saveScrollPosition(y);
+      deps.completeRouterNavigation = () => navApiController!.completeRouterNavigation();
+      deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
+    }
+  }
+
+  // ── Pre-hydration sequence ──────────────────────────────────────────
+  // Concentrates the ordering contract: initRouter → setParams/navState.
+  // Called before hydrateRoot in the hydration path. The createRoot path
+  // calls initRouter() directly (no params to read from server embed).
+  function runPreHydration(_element: unknown): void {
+    // Step 1: Initialize the router
+    initRouter();
+
+    // Step 2: Read server-embedded params and set navigation state
+    const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
+    if (earlyParams && typeof earlyParams === 'object') {
+      setCurrentParams(earlyParams as Record<string, string | string[]>);
+      setNavigationState({
+        params: earlyParams as Record<string, string | string[]>,
+        pathname: window.location.pathname,
+      });
+      delete (self as unknown as Record<string, unknown>).__timber_params;
+    } else {
+      setNavigationState({
+        params: {},
+        pathname: window.location.pathname,
+      });
+    }
   }
 
   // Store the initial page in the history stack so back-button works
@@ -532,9 +671,17 @@ function bootstrap(runtimeConfig: typeof config): void {
     headElements: null, // SSR already set the correct head
   });
 
-  // Initialize history.state with scrollY for the initial entry.
-  // This ensures back navigation to the initial page restores scroll correctly.
-  window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  // Initialize scroll state for the initial entry.
+  // When Navigation API is available, use per-entry state.
+  // Otherwise fall back to history.state.
+  // Note: navApiController is assigned inside initRouter() which runs
+  // synchronously before this point via runPreHydration().
+  const navApi = navApiController as NavigationApiController | null;
+  if (navApi) {
+    navApi.saveScrollPosition(0);
+  } else {
+    window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  }
 
   // Populate the segment cache from server-embedded segment metadata.
   // This enables state tree diffing from the very first client navigation.
@@ -566,28 +713,40 @@ function bootstrap(runtimeConfig: typeof config): void {
   }
 
   // Register popstate handler for back/forward navigation.
+  // When Navigation API is active, the navigate event covers traversals —
+  // popstate is a no-op. When unavailable, popstate handles back/forward.
+  //
   // Use pathname+search (not full href) to match the URL format used by
   // navigate() — Link hrefs are relative paths like "/scroll-test/page-a".
   // Read scrollY from history.state — the browser maintains per-entry state
   // so duplicate URLs in history each have their own scroll position.
   window.addEventListener('popstate', () => {
+    // Navigation API handles traversals via the navigate event.
+    if (navApiController) return;
+
     const state = window.history.state;
     const scrollY = state && typeof state.scrollY === 'number' ? state.scrollY : 0;
     void router.handlePopState(window.location.pathname + window.location.search, scrollY);
   });
 
-  // Keep history.state.scrollY up to date as the user scrolls.
+  // Keep scroll position up to date as the user scrolls.
   // This ensures that when the user presses back/forward, the departing
   // page's scroll position is already saved in its history entry.
-  // Debounced to avoid excessive replaceState calls during smooth scrolling.
+  // When Navigation API is available, uses per-entry state via
+  // navigation.updateCurrentEntry(). Otherwise falls back to history.state.
+  // Debounced to avoid excessive state updates during smooth scrolling.
   let scrollTimer: ReturnType<typeof setTimeout>;
   function saveScrollPosition(): void {
     clearTimeout(scrollTimer);
     scrollTimer = setTimeout(() => {
-      const state = window.history.state;
-      if (state && typeof state === 'object') {
-        // Use getScrollY to capture scroll from overflow containers too.
-        window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
+      const y = getScrollY();
+      if (navApiController) {
+        navApiController.saveScrollPosition(y);
+      } else {
+        const state = window.history.state;
+        if (state && typeof state === 'object') {
+          window.history.replaceState({ ...state, scrollY: y }, '');
+        }
       }
     }, 100);
   }
@@ -655,8 +814,21 @@ clearStaleReloadFlag();
 // If the payload references a module ID from a newer deployment, the error
 // surfaces as an unhandled rejection during React's render/hydration cycle.
 // This handler catches those errors and triggers a full page reload.
+//
+// Also catches chunk load failures (dynamic import of missing assets after
+// a deployment) — these surface as "Failed to fetch dynamically imported module"
+// or "Loading chunk <name> failed" errors. See TIM-446.
 window.addEventListener('unhandledrejection', (event) => {
-  if (isStaleClientReference(event.reason)) {
+  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// Also catch synchronous errors from chunk loads (some browsers throw
+// TypeError synchronously instead of via unhandled rejection).
+window.addEventListener('error', (event) => {
+  if (isChunkLoadError(event.error)) {
     event.preventDefault();
     triggerStaleReload();
   }