@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/src/client/browser-entry/hydrate.ts

@@ -0,0 +1,187 @@
+/**
+ * Hydration — pre-hydration sequence and React root creation.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
+ * 2. No RSC payload: deferred root creation via installDeferredNavigation
+ *
+ * Pre-hydration ordering contract (MUST execute in this order):
+ *   1. initRouter()        — creates the global router so useRouter()
+ *                            works during render
+ *   2. setCurrentParams()  — populates 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
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import { createElement } from 'react';
+import { hydrateRoot, createRoot } from 'react-dom/client';
+import { getRouterOrNull, setCurrentParams } from '#client-internal';
+import {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from '../navigation-context.js';
+import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
+import { TimberNuqsAdapter } from '../nuqs-adapter.js';
+import { isPageUnloading } from '../unload-guard.js';
+import { NavigationRoot, installDeferredNavigation } from '../navigation-root.js';
+import type { TopLoaderConfig } from '../top-loader.js';
+
+import type { RscStreamResult } from './rsc-stream.js';
+
+let showHydrationError: ((error: unknown) => void) | null = null;
+let isHydrationError: ((error: unknown) => boolean) | null = null;
+let pendingHydrationErrors: unknown[] = [];
+
+// React 19 emits attribute-only hydration mismatches via console.error
+// with format substitution: console.error(fmt, link, diff). We must
+// intercept before hydrateRoot() to catch errors during initial hydration.
+const ATTR_MISMATCH_RE =
+  /A tree hydrated but some attributes of the server rendered HTML didn't match/;
+if (process.env.NODE_ENV !== 'production') {
+  const origConsoleError = console.error;
+  console.error = (...args: unknown[]) => {
+    origConsoleError.apply(console, args);
+    if (typeof args[0] === 'string' && ATTR_MISMATCH_RE.test(args[0])) {
+      const message = args
+        .slice(1)
+        .reduce<string>((s, arg) => s.replace('%s', String(arg)), args[0] as string);
+      queueOrShowHydrationError(new Error(message));
+    }
+  };
+  import('../../dev-tools/hydration-overlay.js').then((m) => {
+    showHydrationError = m.showHydrationError;
+    isHydrationError = m.isHydrationError;
+    for (const err of pendingHydrationErrors) {
+      if (m.isHydrationError(err)) m.showHydrationError(err);
+    }
+    pendingHydrationErrors = [];
+  });
+}
+
+function queueOrShowHydrationError(error: unknown): void {
+  if (showHydrationError && isHydrationError) {
+    if (isHydrationError(error)) showHydrationError(error);
+  } else {
+    pendingHydrationErrors.push(error);
+  }
+}
+
+interface HydrateOptions {
+  /** RSC stream result (null if no inlined payload) */
+  rscResult: RscStreamResult | null;
+  /** Runtime config from virtual:timber-config */
+  config: { topLoader?: TopLoaderConfig };
+}
+
+/**
+ * Run the pre-hydration sequence: read server-embedded params and
+ * set navigation state. Must be called AFTER initRouter().
+ */
+export function runPreHydration(): void {
+  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,
+      search: window.location.search,
+    });
+    delete (self as unknown as Record<string, unknown>).__timber_params;
+  } else {
+    setNavigationState({
+      params: {},
+      pathname: window.location.pathname,
+      search: window.location.search,
+    });
+  }
+}
+
+/**
+ * Hydrate the React tree or set up deferred root creation.
+ *
+ * When an RSC payload is available, wraps it with NavigationProvider +
+ * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
+ * document.
+ *
+ * When no RSC payload is available (JS-only client), sets up deferred
+ * navigation so the first client navigation creates the React root.
+ */
+export function hydrateApp({ rscResult, config }: HydrateOptions): void {
+  if (rscResult) {
+    const element = rscResult.element;
+
+    // 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 withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
+    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'
+        );
+      }
+    }
+
+    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) {
+        if (isPageUnloading()) return;
+        if (process.env.NODE_ENV === 'development') {
+          queueOrShowHydrationError(error);
+          console.debug('[timber] Hydration recoverable error:', error);
+        }
+      },
+    });
+  } else {
+    // No RSC payload available — defer React root creation until the
+    // 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,
+      });
+      const root = createRoot(document);
+      root.render(rootElement);
+    });
+  }
+}

package/src/client/browser-entry/index.ts

@@ -0,0 +1,111 @@
+/**
+ * Browser Entry — Client-side hydration and navigation bootstrap.
+ *
+ * This is the thin orchestrator that coordinates the bootstrap sequence.
+ * Each responsibility is extracted into a focused module:
+ *
+ *   action-dispatch.ts  — server action callServer callback
+ *   rsc-stream.ts       — __timber_f chunk handling + ReadableStream
+ *   router-init.ts      — createRouter + Navigation API setup
+ *   hydrate.ts          — pre-hydration sequence + hydrateRoot/createRoot
+ *   post-hydration.ts   — history stack, segment cache, popstate, scroll
+ *   hmr.ts              — dev-only HMR + error forwarding
+ *   scroll.ts           — getScrollY helper
+ *
+ * Bootstrap call order contract:
+ *
+ *   1. setupServerActions()      — register callServer (independent)
+ *   2. createRscPayloadStream()  — decode inlined RSC payload
+ *   3. createTimberRouter()      — create router + Navigation API
+ *   4. runPreHydration()         — set params + navigation state
+ *   5. hydrateApp()              — hydrateRoot or deferred createRoot
+ *   6. setupPostHydration()      — history stack, popstate, scroll
+ *   7. setupHmr()                — dev-only HMR wiring
+ *   8. timber-ready signal       — E2E test readiness indicator
+ *
+ * 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';
+// TIM-830: Populate the search-params registry eagerly so <Link> on the
+// client can serialize flat `Partial<T>` values synchronously during
+// render and click handlers. Side-effect-only import.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import 'virtual:timber-search-params-registry';
+// TIM-932: Populate the codec registry so Link's interpolateParams can
+// use codec.serialize() for URL construction. Side-effect-only import.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import schemaCodecs from 'virtual:timber-schema';
+import { setLinkCodecs } from '../../params/codec-registry.js';
+setLinkCodecs(schemaCodecs);
+
+import { setClientDeploymentId } from '../rsc-fetch.js';
+
+import { setupServerActions } from './action-dispatch.js';
+import { createRscPayloadStream } from './rsc-stream.js';
+import { createTimberRouter } from './router-init.js';
+import { runPreHydration, hydrateApp } from './hydrate.js';
+import { setupPostHydration } from './post-hydration.js';
+import { setupHmr } from './hmr.js';
+
+// ─── 1. Server Action Dispatch (independent) ────────────────────
+
+setupServerActions();
+
+// ─── 2–7. Bootstrap ─────────────────────────────────────────────
+
+function bootstrap(runtimeConfig: typeof config): void {
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (runtimeConfig 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';
+
+  // Step 2: Decode inlined RSC payload (may be null for JS-only clients)
+  const rscResult = createRscPayloadStream();
+
+  // Step 3: Create router + Navigation API integration
+  const { router, navApiController } = createTimberRouter({
+    initialElement: rscResult?.element ?? undefined,
+  });
+
+  // Step 4: Pre-hydration — set params + navigation state (MUST run after router init)
+  runPreHydration();
+
+  // Step 5: Hydrate or set up deferred root creation
+  hydrateApp({ rscResult, config: runtimeConfig });
+
+  // Step 6: Post-hydration wiring
+  setupPostHydration({
+    router,
+    navApiController,
+    initialElement: rscResult?.element ?? null,
+  });
+
+  // Step 7: HMR (dev-only, no-op in production)
+  setupHmr(router);
+}
+
+bootstrap(config);
+
+// ─── 8. Ready Signal ────────────────────────────────────────────
+
+// 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);

package/src/client/browser-entry/post-hydration.ts

@@ -0,0 +1,103 @@
+/**
+ * Post-Hydration Wiring — history stack, segment cache, popstate, scroll.
+ *
+ * Sets up everything that needs to happen after the React root exists:
+ * - Stores initial page in history stack for instant back navigation
+ * - Initializes scroll state for the initial entry
+ * - Populates segment cache from server-embedded metadata
+ * - Registers popstate handler for back/forward navigation
+ * - Sets up debounced scroll position saving
+ *
+ * See design/19-client-navigation.md §"History Stack"
+ */
+
+import type { RouterInstance } from '#client-internal';
+import { getNavigationState } from '../navigation-context.js';
+import type { NavigationApiController } from '../navigation-api.js';
+import { getScrollY } from './scroll.js';
+
+interface PostHydrationOptions {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+  /** Decoded RSC element from initial SSR (null if no RSC payload) */
+  initialElement: unknown;
+}
+
+/**
+ * Wire up post-hydration event handlers and state.
+ */
+export function setupPostHydration({
+  router,
+  navApiController,
+  initialElement,
+}: PostHydrationOptions): void {
+  // 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.
+  // Params were captured from the server-embedded __timber_params by
+  // runPreHydration() — without them on the entry, the cached replay on
+  // back-navigation would normalize params to {} and wipe every
+  // useSegmentParams() consumer on the initial page (TIM-1037).
+  router.historyStack.push(window.location.pathname + window.location.search, {
+    payload: initialElement,
+    params: getNavigationState().params,
+  });
+
+  // Initialize scroll state for the initial entry.
+  // When Navigation API is available, use per-entry state.
+  // Otherwise fall back to history.state.
+  if (navApiController) {
+    navApiController.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;
+  }
+
+  // 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 });
+}

package/src/client/browser-entry/router-init.ts

@@ -0,0 +1,287 @@
+/**
+ * Router Initialization — creates the timber router with all dependencies.
+ *
+ * Wires up RouterDeps (fetch, history, scroll, RSC decoding, render
+ * callbacks) and optionally sets up Navigation API integration.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+
+import { createElement } from 'react';
+import { createFromFetch } from '../../rsc-runtime/browser.js';
+import { createRouter, setGlobalRouter } from '#client-internal';
+import type { RouterDeps, RouterInstance } from '#client-internal';
+import type { NavigationState } from '#client-internal';
+import { TimberNuqsAdapter } from '../nuqs-adapter.js';
+import {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from '../navigation-context.js';
+import { transitionRender, navigateTransition } from '../navigation-root.js';
+import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from '../navigation-api.js';
+import { getScrollY, scrollToHashTarget } from './scroll.js';
+
+export interface RouterInitOptions {
+  initialElement?: unknown;
+}
+
+export interface RouterInitResult {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+}
+
+/**
+ * Create and register the global timber router.
+ *
+ * Must be called before hydrateRoot so `useRouter()` works during
+ * the initial render (methods lazily resolve the router at invocation,
+ * not render time, but initRouter must still run first).
+ */
+export function createTimberRouter(options?: RouterInitOptions): RouterInitResult {
+  // 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();
+
+  // Track the current unwrapped RSC payload. On partial navigation, the
+  // router re-wraps this same element with new NavigationProvider context
+  // so mounted SegmentOutlets are preserved (they pick up changes via
+  // SegmentUpdateContext, not from new children props).
+  // Initialized from the hydration element so partial nav works on the
+  // very first client navigation (before any wrapPayload call).
+  let currentPayload: unknown = options?.initialElement ?? null;
+
+  // ─── History API Patch ──────────────────────────────────────────
+  // Patch pushState/replaceState to detect external URL changes (nuqs
+  // shallow updates, replaceUrl, third-party libraries). When the router
+  // itself calls pushState/replaceState, it sets a flag so the patch
+  // skips the sync — the router already updates NavigationContext.
+  //
+  // On Navigation API browsers, the navigate event catches most URL
+  // changes. The patch is defense-in-depth and the primary mechanism
+  // for History API-only browsers (older Safari/Firefox).
+  const ROUTER_HISTORY_FLAG = Symbol.for('__timber_router_history_update');
+  const gFlags = globalThis as Record<symbol, boolean>;
+
+  const originalPushState = window.history.pushState.bind(window.history);
+  const originalReplaceState = window.history.replaceState.bind(window.history);
+
+  /**
+   * Sync NavigationContext.search after a shallow URL update. Called by
+   * the Navigation API shallow handler and the History API patch.
+   *
+   * @param search — the new search string. The Navigation API path passes
+   *   this from event.destination.url (window.location hasn't committed
+   *   yet when the navigate listener fires). The History API patch omits
+   *   it, reading window.location.search (already committed by the time
+   *   the patched pushState/replaceState returns).
+   *
+   * Bails when search is unchanged (scroll saves, no-ops, dual-fire).
+   * Re-wraps currentPayload with updated NavigationProvider and commits
+   * via transitionRender (startTransition — non-blocking).
+   */
+  function syncShallowSearch(search?: string): void {
+    const currentSearch = search ?? window.location.search;
+    const navState = getNavigationState();
+    if (currentSearch === navState.search) return;
+    if (!currentPayload) return;
+
+    const newNavState: NavigationState = {
+      params: navState.params,
+      pathname: navState.pathname,
+      search: currentSearch,
+    };
+    setNavigationState(newNavState);
+
+    const withNav = createElement(
+      NavigationProvider,
+      { value: newNavState },
+      currentPayload as React.ReactNode
+    );
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
+    transitionRender(wrapped);
+  }
+
+  window.history.pushState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalPushState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
+  window.history.replaceState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalReplaceState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
+  const deps: RouterDeps = {
+    fetch: (url, init) => window.fetch(url, init),
+    pushState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.pushState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
+    replaceState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.replaceState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
+    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,
+    scrollToHash: scrollToHashTarget,
+
+    decodeRsc: (fetchPromise: Promise<Response>) => {
+      return createFromFetch(fetchPromise);
+    },
+
+    // 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) => {
+      currentPayload = element;
+      const withNav = createElement(
+        NavigationProvider,
+        { value: navState },
+        element as React.ReactNode
+      );
+      const withUpdates = createElement(
+        SegmentUpdateContext.Provider,
+        { value: EMPTY_SEGMENT_UPDATES },
+        withNav
+      );
+      const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
+      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 { element, decodePromise } = await perform(
+          (
+            rawPayload: unknown,
+            navState: NavigationState,
+            segmentUpdates?: Map<string, unknown>
+          ) => {
+            currentPayload = rawPayload;
+            const withNav = createElement(
+              NavigationProvider,
+              { value: navState },
+              rawPayload as React.ReactNode
+            );
+            const withUpdates = createElement(
+              SegmentUpdateContext.Provider,
+              { value: (segmentUpdates ?? EMPTY_SEGMENT_UPDATES) as Map<string, React.ReactNode> },
+              withNav
+            );
+            return createElement(TimberNuqsAdapter, null, withUpdates);
+          }
+        );
+        return { element: element as React.ReactNode, decodePromise };
+      });
+    },
+
+    _getCurrentPayload: () => currentPayload,
+
+    // 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);
+      });
+    },
+  };
+
+  const 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.
+  let navApiController: NavigationApiController | null = null;
+  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);
+      },
+      onShallowNavigate: (destinationUrl: string) => {
+        const search = new URL(destinationUrl).search;
+        syncShallowSearch(search);
+      },
+    });
+
+    // 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);
+  }
+
+  return { router, navApiController };
+}