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

package/src/client/browser-entry.ts

@@ -1,846 +0,0 @@
-/**
- * Browser Entry — Client-side hydration and navigation bootstrap.
- *
- * This is a real TypeScript file, not codegen. It initializes the
- * client navigation runtime: segment router, prefetch cache, and
- * history stack.
- *
- * Hydration works by:
- * 1. Decoding the RSC payload embedded in the initial HTML response
- *    via createFromReadableStream from @vitejs/plugin-rsc/browser
- * 2. Hydrating the decoded React tree via hydrateRoot
- * 3. Setting up client-side navigation for subsequent page transitions
- *
- * After hydration, the browser entry:
- * - Link click handling is per-component (Link's onClick), not global delegation
- * - Listens for popstate events for back/forward navigation
- *
- * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
- */
-
-// @ts-expect-error — virtual module provided by timber-entries plugin
-import config from 'virtual:timber-config';
-
-import { createElement } from 'react';
-import { hydrateRoot, createRoot, type Root } from 'react-dom/client';
-import {
-  createFromReadableStream,
-  createFromFetch,
-  setServerCallback,
-  encodeReply,
-} 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,
-  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
-// imports — they don't need singleton behavior across module graphs.
-import { applyHeadElements } from './head.js';
-import { TimberNuqsAdapter } from './nuqs-adapter.js';
-import { isPageUnloading } from './unload-guard.js';
-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 {
-  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 ──────────────────────────────────────
-
-/**
- * Register the callServer callback for server action dispatch.
- *
- * When React encounters a server reference (from `'use server'` modules),
- * it calls `callServer(id, args)` to dispatch the action to the server.
- * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
- * set by `setServerCallback`.
- *
- * The callback:
- * 1. Serializes args via `encodeReply` (RSC wire format)
- * 2. POSTs to the current URL with `Accept: text/x-component`
- * 3. Decodes the RSC response stream
- *
- * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
- */
-setServerCallback(async (id: string, args: unknown[]) => {
-  const body = await encodeReply(args);
-
-  // Track the X-Timber-Revalidation header from the response.
-  // We intercept the fetch promise to read headers before createFromFetch
-  // consumes the body stream.
-  let hasRevalidation = false;
-  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: 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');
-    return res;
-  });
-
-  let decoded: unknown;
-  try {
-    decoded = await createFromFetch(response);
-  } catch (error) {
-    if (isStaleClientReference(error)) {
-      triggerStaleReload();
-      // Return a never-resolving promise to prevent further processing
-      return new Promise(() => {});
-    }
-    throw error;
-  }
-
-  // Handle redirect — server encoded the redirect location in the RSC stream
-  // instead of returning HTTP 302. Perform a client-side SPA navigation.
-  if (hasRedirect) {
-    const wrapper = decoded as { _redirect: string; _status: number };
-    try {
-      const router = getRouter();
-      void router.navigate(wrapper._redirect);
-    } catch {
-      // 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;
-  }
-
-  if (hasRevalidation) {
-    // Piggybacked response: wrapper object { _action, _tree }
-    // Apply the revalidated tree directly — no separate router.refresh() needed.
-    const wrapper = decoded as { _action: unknown; _tree: unknown };
-    try {
-      const router = getRouter();
-      const headElements = headElementsJson ? JSON.parse(headElementsJson) : null;
-      router.applyRevalidation(wrapper._tree, headElements);
-    } catch {
-      // Router not yet initialized — fall through
-    }
-    return wrapper._action;
-  }
-
-  // No piggybacked revalidation — refresh to pick up any mutations.
-  // This covers actions that don't call revalidatePath().
-  try {
-    const router = getRouter();
-    void router.refresh();
-  } catch {
-    // Router not yet initialized (rare edge case during bootstrap)
-  }
-
-  return decoded;
-});
-
-// ─── Bootstrap ───────────────────────────────────────────────────
-
-/**
- * Bootstrap the client-side runtime.
- *
- * Hydrates the server-rendered HTML with React, then initializes
- * client-side navigation for SPA transitions.
- */
-/**
- * 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;
-  }
-  for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
-    if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
-  }
-  return 0;
-}
-
-function bootstrap(runtimeConfig: typeof config): void {
-  const _config = runtimeConfig;
-
-  // 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.
-  //
-  // The RSC payload is embedded in the HTML as progressive inline script
-  // tags that call self.__timber_f.push([type, data]) as RSC chunks arrive.
-  // Typed tuples: [0] = bootstrap signal, [1, string] = Flight data chunk.
-  //
-  // We set up a ReadableStream fed by those push() calls so
-  // createFromReadableStream can decode the Flight protocol progressively.
-  //
-  // For the initial page load, the RSC payload is inlined in the HTML.
-  // For subsequent navigations, it's fetched from the server.
-  type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
-
-  // __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;
-  // Declared here so it's accessible after the if/else hydration block.
-  // 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();
-
-    // Buffer to hold string data until the stream writer is ready.
-    // Scripts that execute before hydration starts push data here.
-    let dataBuffer: string[] | undefined = [];
-    let streamWriter: ReadableStreamDefaultController<Uint8Array> | null = null;
-    let streamFlushed = false;
-
-    /** Process a typed tuple from __timber_f. */
-    function handleSegment(seg: FlightSegment): void {
-      if (seg[0] === 0) {
-        // Bootstrap signal — initialize buffer (already done above)
-        if (!dataBuffer) dataBuffer = [];
-      } else if (seg[0] === 1) {
-        // Flight data chunk
-        if (streamWriter) {
-          streamWriter.enqueue(encoder.encode(seg[1]));
-        } else if (dataBuffer) {
-          dataBuffer.push(seg[1]);
-        }
-      }
-    }
-
-    // Process any chunks that arrived before this script executed.
-    for (const seg of timberChunks) {
-      handleSegment(seg);
-    }
-    // Clear the array to release memory.
-    timberChunks.length = 0;
-
-    // Patch push() so subsequent script tags feed data in real time.
-    (timberChunks as unknown as { push: (seg: FlightSegment) => void }).push = handleSegment;
-
-    const rscPayload = new ReadableStream<Uint8Array>({
-      start(controller) {
-        streamWriter = controller;
-        // Flush buffered data into the stream.
-        if (dataBuffer) {
-          for (const data of dataBuffer) {
-            controller.enqueue(encoder.encode(data));
-          }
-          dataBuffer = undefined;
-        }
-        // If DOM already loaded (non-streaming or fast page), close now.
-        if (streamFlushed) {
-          controller.close();
-        }
-      },
-    });
-
-    // Close the stream when the document finishes loading.
-    // DOMContentLoaded fires after the HTML parser has processed all
-    // inline scripts (including streamed Suspense replacements and
-    // RSC data), so all push() calls have completed by this point.
-    //
-    // If the page is unloading (user refreshed or navigated away),
-    // do NOT close the stream. When the connection drops mid-stream,
-    // DOMContentLoaded fires because the parser finishes. Closing an
-    // incomplete RSC stream causes React's Flight client to throw
-    // "Connection closed." — a jarring error on a page being replaced.
-    // 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;
-        dataBuffer = undefined;
-      }
-      streamFlushed = true;
-    }
-
-    if (document.readyState === 'loading') {
-      document.addEventListener('DOMContentLoaded', onDOMContentLoaded, false);
-    } else {
-      // 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;
-
-    // ── 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 NavigationRoot (for
-    // transition-based rendering during client navigation).
-    //
-    // 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();
-    const withNav = createElement(
-      NavigationProvider,
-      { value: navState },
-      element as React.ReactNode
-    );
-    const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    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
-      // (wrapStreamWithErrorHandling closes the stream cleanly after
-      // the shell is flushed). React replays the error during hydration
-      // but the server HTML is already correct — no recovery needed.
-      onRecoverableError(error: unknown) {
-        // Suppress errors during page unload (refresh/navigate away).
-        // The aborted stream causes incomplete HTML which React flags
-        // as a recoverable error — but the page is being replaced.
-        if (isPageUnloading()) return;
-        // Only log in dev — in production these are expected for
-        // deny() inside Suspense and streaming error boundaries.
-        if (process.env.NODE_ENV === 'development') {
-          console.debug('[timber] Hydration recoverable error:', error);
-        }
-      },
-    });
-  } else {
-    // 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 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;
-        // 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;
-        }
-      },
-      getCurrentUrl: () => window.location.pathname + window.location.search,
-      getScrollY,
-
-      // Decode RSC Flight stream using createFromFetch.
-      // createFromFetch takes a Promise<Response> and progressively
-      // parses the RSC stream as chunks arrive.
-      //
-      // Wrapped with stale client reference detection: if the server
-      // has been redeployed with new bundles, the RSC payload may
-      // reference module IDs that don't exist in the old client bundle.
-      // We catch "Could not find the module" errors and trigger a full
-      // page reload so the browser fetches the new bundle.
-      decodeRsc: async (fetchPromise: Promise<Response>) => {
-        try {
-          return await createFromFetch(fetchPromise);
-        } catch (error) {
-          if (isStaleClientReference(error)) {
-            triggerStaleReload();
-            // Return a never-resolving promise to prevent further processing
-            // while the page is reloading.
-            return new Promise(() => {});
-          }
-          throw error;
-        }
-      },
-
-      // 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.
-      //
-      // navState is passed explicitly by the router — no temporal coupling
-      // with getNavigationState().
-      renderRoot: (element: unknown, navState: NavigationState) => {
-        const withNav = createElement(
-          NavigationProvider,
-          { value: navState },
-          element as React.ReactNode
-        );
-        const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-        transitionRender(wrapped);
-      },
-
-      // Run a navigation inside a React transition with optimistic pending URL.
-      // The entire fetch + state update runs inside startTransition. useOptimistic
-      // shows the pending URL immediately and reverts to null when the transition
-      // commits (atomic with the new tree + params).
-      //
-      // The perform callback receives a wrapPayload function that wraps the
-      // 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, navState: NavigationState) => {
-            const withNav = createElement(
-              NavigationProvider,
-              { value: navState },
-              rawPayload as React.ReactNode
-            );
-            return createElement(TimberNuqsAdapter, null, withNav);
-          });
-          return payload as React.ReactNode;
-        });
-      },
-
-      // Schedule a callback after the next paint so scroll operations
-      // happen after React commits the new content to the DOM.
-      // Double-rAF ensures the browser has painted the new frame.
-      afterPaint: (callback: () => void) => {
-        requestAnimationFrame(() => {
-          requestAnimationFrame(callback);
-        });
-      },
-
-      // Apply resolved head elements (title, meta tags) to the DOM after
-      // SPA navigation. See design/16-metadata.md.
-      applyHead: applyHeadElements,
-    };
-
-    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
-  // after the first navigation. We store the decoded RSC element so
-  // back navigation can replay it instantly without a server fetch.
-  router.historyStack.push(window.location.pathname + window.location.search, {
-    payload: initialElement,
-    headElements: null, // SSR already set the correct head
-  });
-
-  // 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.
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const timberSegments = (self as unknown as Record<string, unknown>).__timber_segments;
-  if (Array.isArray(timberSegments)) {
-    router.initSegmentCache(timberSegments);
-    delete (self as unknown as Record<string, unknown>).__timber_segments;
-  }
-
-  // NOTE: We do NOT cache segment elements from the initial RSC payload here.
-  // The decoded element from createFromReadableStream is a thenable/lazy
-  // element that React resolves during render — the segment walker can't
-  // traverse it. The element cache is populated lazily after the first SPA
-  // navigation (via mergeAndCachePayload in renderViaTransition), when
-  // the decoded payload is a fully resolved React element tree.
-
-  // Note: __timber_params is read before hydrateRoot (see above) so that
-  // NavigationProvider has correct values during hydration. If the hydration
-  // path was skipped (no RSC payload), populate the fallback here.
-  const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (lateTimberParams && typeof lateTimberParams === 'object') {
-    setCurrentParams(lateTimberParams as Record<string, string | string[]>);
-    setNavigationState({
-      params: lateTimberParams as Record<string, string | string[]>,
-      pathname: window.location.pathname,
-    });
-    delete (self as unknown as Record<string, unknown>).__timber_params;
-  }
-
-  // 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 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.
-  // 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 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);
-  }
-  window.addEventListener('scroll', saveScrollPosition, { passive: true });
-
-  // Link click and hover prefetch are handled per-component by Link's
-  // onClick and onMouseEnter handlers. No global delegation needed.
-  // See LOCAL-340.
-
-  // Dev-only: Listen for RSC module invalidation events from @vitejs/plugin-rsc.
-  // When a server component is edited, the RSC plugin sends an "rsc:update"
-  // event. We trigger a router.refresh() to re-fetch the RSC payload with
-  // the updated server code. This avoids a full page reload while still
-  // picking up server-side changes.
-  // See design/21-dev-server.md §"HMR Wiring"
-  // Vite injects import.meta.hot in dev mode. Cast to access it without
-  // requiring vite/client types in the package tsconfig.
-  const hot = (
-    import.meta as unknown as {
-      hot?: {
-        on(event: string, cb: (...args: unknown[]) => void): void;
-        send(event: string, data: unknown): void;
-      };
-    }
-  ).hot;
-  if (hot) {
-    hot.on('rsc:update', () => {
-      void router.refresh();
-    });
-
-    // Listen for dev warnings forwarded from the server via WebSocket.
-    // See dev-warnings.ts — emitOnce() sends these via server.hot.send().
-    hot.on('timber:dev-warning', (data: unknown) => {
-      const warning = data as { level: string; message: string };
-      if (warning.level === 'error') {
-        console.error(warning.message);
-      } else {
-        console.warn(warning.message);
-      }
-    });
-
-    // Listen for server console logs forwarded via WebSocket.
-    // Replays them in the browser console with a [SERVER] prefix
-    // so developers can see server output without switching to the terminal.
-    // See plugins/dev-logs.ts.
-    setupServerLogReplay(hot);
-
-    // Forward uncaught client errors to the server for the dev overlay.
-    // The server source-maps the stack and sends it back via Vite's
-    // error overlay protocol. See dev-server.ts §client error listener.
-    setupClientErrorForwarding(hot);
-  }
-}
-
-bootstrap(config);
-
-// Clear the stale reload flag on successful bootstrap. If the page
-// loaded and bootstrapped without hitting a stale reference error,
-// the loop guard should reset so the next stale error gets a fresh
-// reload attempt.
-clearStaleReloadFlag();
-
-// Global error handler for stale client reference errors during hydration.
-// The initial RSC payload is decoded lazily by React via createFromReadableStream.
-// 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) || 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();
-  }
-});
-
-// Signal that the client runtime has been initialized.
-// Used by E2E tests to wait for hydration before interacting.
-// We append a <meta name="timber-ready"> tag rather than setting a
-// data attribute on <html>. Since React owns the entire document
-// via hydrateRoot(document, ...), mutating <html> attributes causes
-// hydration mismatch warnings. Dynamically-added <meta> tags don't
-// conflict because React doesn't reconcile them.
-const readyMeta = document.createElement('meta');
-readyMeta.name = 'timber-ready';
-document.head.appendChild(readyMeta);