@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

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

@@ -0,0 +1,123 @@
+/**
+ * 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.ts';
+import type { NavigationApiController } from '../navigation-api.ts';
+import { getScrollY } from './scroll.ts';
+import type { ParamsSource } from '../../shared/payload-root.ts';
+import { locationSearch } from '../location-search.ts';
+
+interface PostHydrationOptions {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+  /** Decoded RSC element from initial SSR (null if no RSC payload) */
+  initialElement: unknown;
+  /** The params that payload published, from the same decode. */
+  initialParams: ParamsSource;
+}
+
+/**
+ * Wire up post-hydration event handlers and state.
+ */
+export function setupPostHydration({
+  router,
+  navApiController,
+  initialElement,
+  initialParams,
+}: PostHydrationOptions): void {
+  // 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;
+  const initialSegmentInfo = Array.isArray(timberSegments)
+    ? (timberSegments as import('../../shared/segment-info.ts').SegmentInfo[])
+    : null;
+  if (initialSegmentInfo) {
+    router.initSegmentCache(initialSegmentInfo);
+    delete (self as unknown as Record<string, unknown>).__timber_segments;
+  }
+
+  // Store the initial page in the history stack so back-button works
+  // after the first navigation. Include segmentInfo so the segment
+  // cache is restored correctly on popstate cached replay.
+  // Replaying this entry on a Back re-renders `initialElement` and republishes
+  // `initialParams`. Both came out of one split of one decoded payload root
+  // (rsc-stream.ts), so the entry cannot replay with another route's params —
+  // which is what a separately-seeded copy used to do (TIM-1037, TIM-1285).
+  router.historyStack.push(window.location.pathname + locationSearch(), {
+    payload: initialElement,
+    params: initialParams,
+    segmentInfo: initialSegmentInfo,
+  });
+
+  // Leave scrollRestoration = 'auto' so the browser natively restores
+  // scroll on reload, tab restore, and back-from-external-page — cases
+  // JS cannot reliably cover because 'manual' persists on the session
+  // history entry across reloads. For client navigations the router's
+  // restoreScrollAfterPaint() re-applies the saved position after React
+  // commits, writing last and winning over the browser's auto-restore.
+  // Explicitly set 'auto' to heal entries from previously-deployed builds
+  // that set 'manual'.
+  window.history.scrollRestoration = 'auto';
+
+  // Initialize scroll state for the initial entry. On reload the browser's
+  // native restoration may land before or after this runs; the debounced
+  // scroll listener below updates the entry state to the true position.
+  const initialScrollY = getScrollY();
+  if (navApiController) {
+    navApiController.saveScrollPosition(initialScrollY);
+  } else {
+    window.history.replaceState({ timber: true, scrollY: initialScrollY }, '');
+  }
+
+  // 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 + locationSearch(), 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,418 @@
+/**
+ * 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.ts';
+import { PayloadRoot } from '../params-context.ts';
+import { readPublishedParams, type ParamsSource } from '../../shared/payload-root.ts';
+import { createRouter, setGlobalRouter } from '#client-internal';
+import type { RouterDeps, RouterInstance } from '#client-internal';
+import type { NavigationState } from '#client-internal';
+import { TimberNuqsAdapter } from '../nuqs-adapter.tsx';
+import {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from '../navigation-context.ts';
+import { navigateTransition, type RenderOwner } from '../navigation-transition.ts';
+import type { NavigationRender } from '../navigation-root.tsx';
+import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.ts';
+import { SlotContentCacheContext, type SlotContentCache } from '../slot-content-cache-context.ts';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from '../navigation-api.ts';
+import { getScrollY, scrollToHashTarget } from './scroll.ts';
+import { locationSearch } from '../location-search.ts';
+import { stripRscCacheKey } from '../../shared/rsc-cache-key.ts';
+
+export interface RouterInitOptions {
+  /**
+   * The router's React root (`createReactRoot().render`). Every path that puts
+   * a page on screen renders through it — it is the synchronous transition
+   * around `root.render`, and the `publish` it takes runs on React's commit.
+   */
+  render: NavigationRender;
+  initialElement?: unknown;
+  /** The params the hydration payload published, beside `initialElement`. */
+  initialParams?: ParamsSource;
+  clientSegmentCache?: boolean;
+}
+
+export interface RouterInitResult {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+  /**
+   * The client's wrapper chain around a tree — the one every navigation
+   * renders through. Hydration builds its root with this too, so the
+   * hydrated tree and the first navigated tree cannot differ in shape
+   * (a type present on one and absent on the other remounts everything
+   * below it) and share the router's slot content cache.
+   */
+  renderTree: (
+    tree: unknown,
+    navState: NavigationState,
+    params: ParamsSource
+  ) => React.ReactElement;
+}
+
+/**
+ * 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 {
+  const { render } = options;
+
+  // 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;
+
+  // The params `currentPayload` is displayed with. Tracked beside it because
+  // the two render paths that do NOT receive a payload — a shallow search
+  // update and any re-wrap of the current tree — must republish the same
+  // record rather than dropping it. They are written together, in one place
+  // (`renderTree`), so they cannot come apart.
+  let currentParams: ParamsSource = options.initialParams ?? readPublishedParams(undefined);
+
+  // The slot content the client has committed, by segmentPath. Owned here so
+  // there is exactly one per router (never a module or globalThis singleton —
+  // SegmentOutlet also executes during SSR, where a process-wide Map would be
+  // shared across requests). Read by SegmentOutlet in render, written by it
+  // at commit only. See client/slot-content-cache-context.ts (TIM-1423).
+  const slotContentCache: SlotContentCache = new Map();
+
+  /**
+   * Build the client's wrapper chain around a tree. **The only place it is
+   * built.**
+   *
+   * Every render path goes through here — hydration (`hydrate.ts`) receives
+   * this function and builds its root with it, and a navigation, a shallow
+   * search update, a popstate replay and a revalidation all call this. That
+   * matters beyond tidiness: an element type present on one render and absent
+   * on the next changes the type at that position, so React unmounts and
+   * remounts everything below it, destroying the layout state partial
+   * navigation exists to preserve (caught by
+   * tests/e2e/segment-merge-navigation.test.ts when the params wrapper was
+   * conditional).
+   *
+   * `PayloadRoot` is *above* `currentPayload`, which on a partial navigation
+   * is the retained tree. That position is the whole design: it is the only
+   * provider a reader in a skipped layout can resolve to (TIM-1297).
+   *
+   * Pure — building the element does not make it the displayed one. Every
+   * caller pairs this with `publishTree` at the point the tree is actually
+   * handed to React, because a navigation builds its element before it is
+   * known to have won and a superseded one must leave `currentPayload`
+   * describing the route still on screen (TIM-1301).
+   */
+  function renderTree(
+    tree: unknown,
+    navState: NavigationState,
+    params: ParamsSource,
+    segmentUpdates?: Map<string, React.ReactNode>
+  ): React.ReactElement {
+    const withParams = createElement(PayloadRoot, { source: params }, tree as React.ReactNode);
+    const withNav = createElement(NavigationProvider, { value: navState }, withParams);
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: segmentUpdates ?? EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const withSlotCache = createElement(
+      SlotContentCacheContext.Provider,
+      { value: slotContentCache },
+      withUpdates
+    );
+    return createElement(TimberNuqsAdapter, null, withSlotCache);
+  }
+
+  /**
+   * Record the tree the client is now displaying, and the params published
+   * over it. Written together — the two paths that re-wrap without a fresh
+   * payload (a shallow search update, a partial navigation) read them back as
+   * a pair and would otherwise restore one route's tree with another's params.
+   */
+  function publishTree(tree: unknown, params: ParamsSource): void {
+    currentPayload = tree;
+    currentParams = params;
+  }
+
+  // Late-bound: syncShallowSearch is defined before createRouter, but only
+  // called after the router exists (from patched pushState/replaceState or
+  // the Navigation API handler, both of which fire from user code).
+  let router: RouterInstance | null = 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 hands it to
+   * React through the root's `render` (startTransition — non-blocking).
+   */
+  function syncShallowSearch(search?: string): void {
+    const currentSearch = search != null ? stripRscCacheKey(search) : locationSearch();
+    const navState = getNavigationState();
+    if (currentSearch === navState.search) return;
+    if (!currentPayload) return;
+
+    // A shallow search update does not re-render the tree from the server, so
+    // the params are unchanged — but they are the client's to publish now, and
+    // this path rebuilds the whole chain. Republishing `currentParams` is what
+    // keeps a `?q=` change from silently clearing the route's params
+    // (TIM-1285's failure mode, on a path that used to be exempt from it
+    // because the record lived inside the payload).
+    const newNavState: NavigationState = {
+      pathname: navState.pathname,
+      search: currentSearch,
+    };
+    setNavigationState(newNavState);
+
+    // A shallow search update displaces whatever React is rendering. If a
+    // handed-off tree is still suspended (e.g. a cached popstate replay whose
+    // client component is lazy-loading), this render replaces it and React
+    // will never commit it — so forgetOlderHandoffs never fires and
+    // hasUncommittedNav stays true forever, blocking runWhenIdle tasks.
+    //
+    // Deferred to a microtask so that when a child layout effect fires a
+    // pushState during the same commit (e.g. nuqs syncing on mount),
+    // forgetOlderHandoffs — which runs in the parent layout effect, i.e.
+    // synchronously before the microtask — clears pendingCommit first,
+    // and this settle is a no-op. A genuinely displaced suspended tree
+    // never fires forgetOlderHandoffs, so the microtask settles it
+    // (TIM-1480).
+    queueMicrotask(() => router?.settleHandoffs());
+
+    publishTree(currentPayload, currentParams);
+    render(renderTree(currentPayload, newNavState, currentParams), null);
+  }
+
+  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 = {
+    clientSegmentCache: options?.clientSegmentCache ?? false,
+    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 + locationSearch(),
+    getScrollY,
+    scrollToHash: scrollToHashTarget,
+
+    decodeRsc: (fetchPromise: Promise<Response>) => {
+      return createFromFetch(fetchPromise);
+    },
+
+    // Render a decoded RSC tree through the router's React root. Used for
+    // non-navigation renders (popstate cached replay, applyActionResult).
+    // Wraps with NavigationProvider + TimberNuqsAdapter.
+    //
+    // For navigation renders (navigate, refresh, popstate-with-fetch),
+    // navigateTransition is used instead — it hands the destination tree to
+    // React in a transition so the departing page stays visible.
+    //
+    // navState is passed explicitly by the router — no temporal coupling
+    // with getNavigationState().
+    renderRoot: (
+      element: unknown,
+      navState: NavigationState,
+      params: ParamsSource,
+      commit: () => void
+    ) => {
+      // These paths render what is already decided (a replay, a
+      // revalidation), but "decided" is not "on screen": the tree goes out in
+      // a transition React may hold. The publish — the router's and this
+      // module's record of the displayed tree — runs when React commits it,
+      // the same way a navigation's does (TIM-1301, TIM-1423).
+      render(renderTree(element, navState, params), () => {
+        publishTree(element, params);
+        commit();
+      });
+    },
+
+    // Hand a navigation's tree to React in a transition
+    // (navigation-transition.ts). The fetch runs outside any transition
+    // scope; only the render that hands the tree over is wrapped, and in a
+    // synchronous `startTransition`. Do NOT make this callback's caller an
+    // async React action — see the entanglement note in
+    // `navigateTransition` (TIM-1306, TIM-1307).
+    //
+    // 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.
+    //
+    // `_url` names the pending URL the router already published to its own
+    // pending store before calling here; the transition has no use for it.
+    navigateTransition: (_url: string, owner: RenderOwner, perform, onCommit) => {
+      return navigateTransition(
+        owner,
+        async () => {
+          // What wrapPayload built, held until the transition wins. The client's
+          // record of the displayed tree is navigation state like any other, so
+          // it rides the same commit as the segment cache rather than being
+          // written as a side effect of building the element (TIM-1301).
+          let displayed: { tree: unknown; params: ParamsSource } | null = null;
+          const { element, decodePromise, commit } = await perform(
+            (
+              rawPayload: unknown,
+              navState: NavigationState,
+              params: ParamsSource,
+              segmentUpdates?: Map<string, unknown>
+            ) => {
+              displayed = { tree: rawPayload, params };
+              return renderTree(
+                rawPayload,
+                navState,
+                params,
+                segmentUpdates as Map<string, React.ReactNode> | undefined
+              );
+            }
+          );
+          return {
+            element: element as React.ReactNode,
+            decodePromise,
+            commit: () => {
+              if (displayed) publishTree(displayed.tree, displayed.params);
+              commit();
+            },
+          };
+        },
+        render,
+        onCommit
+      );
+    },
+
+    _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);
+      });
+    },
+  };
+
+  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, departingUrl }) => {
+        await router.navigate(url, {
+          replace,
+          scroll,
+          _signal: signal,
+          _skipHistory: true,
+          _departingUrl: departingUrl,
+        });
+      },
+      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, renderTree };
+}