@timber-js/app 0.1.23 → 0.1.25

package/src/client/router.ts

@@ -5,8 +5,8 @@ import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
 import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
-import { flushSync } from 'react-dom';
-import { setCurrentParams, notifyParamsListeners } from './use-params.js';
+import { setCurrentParams } from './use-params.js';
+import { setNavigationState } from './navigation-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -325,9 +325,26 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
-  /** Update useParams() with route params from the server response. */
-  function updateParams(params: Record<string, string | string[]> | null | undefined): void {
-    setCurrentParams(params ?? {});
+  /**
+   * Update navigation state (params + pathname) for the next render.
+   *
+   * Sets both the module-level fallback (for tests and SSR) and the
+   * navigation context state (read by renderRoot to wrap the element
+   * in NavigationProvider). The context update is atomic with the tree
+   * render — both are passed to reactRoot.render() in the same call.
+   */
+  function updateNavigationState(
+    params: Record<string, string | string[]> | null | undefined,
+    url: string
+  ): void {
+    const resolvedParams = params ?? {};
+    // Module-level fallback for tests (no NavigationProvider) and SSR
+    setCurrentParams(resolvedParams);
+    // Navigation context — read by renderRoot to wrap the RSC element
+    const pathname = url.startsWith('http')
+      ? new URL(url).pathname
+      : url.split('?')[0] || '/';
+    setNavigationState({ params: resolvedParams, pathname });
   }
 
   /** Apply head elements (title, meta tags) to the DOM if available. */
@@ -394,18 +411,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // header reflects the currently mounted segments.
       updateSegmentCache(result.segmentInfo);
 
-      // Update params, render the new tree, and notify params subscribers
-      // in a single synchronous flush. Without flushSync, renderPayload()
-      // (reactRoot.render) and notifyParamsListeners() are separate update
-      // mechanisms that React may commit in different frames — causing a
-      // flash where both the old and new active rows show simultaneously
-      // in preserved layouts (the new tree commits before the external
-      // store re-render deactivates the old row).
-      updateParams(result.params);
-      flushSync(() => {
-        renderPayload(result.payload);
-        notifyParamsListeners();
-      });
+      // Update navigation state (params + pathname) before rendering.
+      // The renderRoot callback reads this state and wraps the RSC element
+      // in NavigationProvider — so the context value and the element tree
+      // are passed to reactRoot.render() in the same call, making the
+      // update atomic. Preserved layouts see new params in the same render
+      // pass as the new tree, preventing the dual-active-row flash.
+      updateNavigationState(result.params, url);
+      renderPayload(result.payload);
 
       // Update document.title and <meta> tags with the new page's metadata
       applyHead(result.headElements);
@@ -465,12 +478,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Update segment cache with fresh segment info from full render
       updateSegmentCache(result.segmentInfo);
 
-      // Atomic update — see navigate() for rationale on flushSync.
-      updateParams(result.params);
-      flushSync(() => {
-        renderPayload(result.payload);
-        notifyParamsListeners();
-      });
+      // Atomic update — see navigate() for rationale on NavigationProvider.
+      updateNavigationState(result.params, currentUrl);
+      renderPayload(result.payload);
       applyHead(result.headElements);
     } finally {
       setPending(false);
@@ -485,11 +495,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip
-      updateParams(entry.params);
-      flushSync(() => {
-        renderPayload(entry.payload);
-        notifyParamsListeners();
-      });
+      updateNavigationState(entry.params, url);
+      renderPayload(entry.payload);
       applyHead(entry.headElements);
       afterPaint(() => {
         deps.scrollTo(0, scrollY);
@@ -505,16 +512,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         const stateTree = segmentCache.serializeStateTree();
         const result = await fetchRscPayload(url, deps, stateTree);
         updateSegmentCache(result.segmentInfo);
-        updateParams(result.params);
+        updateNavigationState(result.params, url);
         historyStack.push(url, {
           payload: result.payload,
           headElements: result.headElements,
           params: result.params,
         });
-        flushSync(() => {
-          renderPayload(result.payload);
-          notifyParamsListeners();
-        });
+        renderPayload(result.payload);
         applyHead(result.headElements);
         afterPaint(() => {
           deps.scrollTo(0, scrollY);

package/src/client/transition-root.tsx

@@ -0,0 +1,86 @@
+/**
+ * TransitionRoot — Wrapper component for transition-based rendering.
+ *
+ * Solves the "new boundary has no old content" problem for client-side
+ * navigation. When React renders a completely new Suspense boundary via
+ * root.render(), it shows the fallback immediately — root.render() is
+ * always an urgent update regardless of startTransition.
+ *
+ * TransitionRoot holds the current element in React state. Navigation
+ * updates call startTransition(() => setState(newElement)), which IS
+ * a transition update. React keeps the old committed tree visible while
+ * any new Suspense boundaries in the transition resolve.
+ *
+ * This is the client-side equivalent of deferSuspenseFor on the server:
+ * the old content stays visible until the new content is ready, avoiding
+ * flash-of-fallback during fast navigations.
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ */
+
+import { useState, startTransition, type ReactNode } from 'react';
+
+// ─── Module-level render function ────────────────────────────────
+
+/**
+ * Module-level reference to the state setter wrapped in startTransition.
+ * Set during TransitionRoot's render. This is safe because there is
+ * exactly one TransitionRoot per application (the document root).
+ */
+let _transitionRender: ((element: ReactNode) => void) | null = null;
+
+// ─── Component ───────────────────────────────────────────────────
+
+/**
+ * Root wrapper component that enables transition-based rendering.
+ *
+ * Renders no DOM elements — returns the current element directly.
+ * This means the DOM tree matches the server-rendered HTML during
+ * hydration (TransitionRoot is invisible to the DOM).
+ *
+ * Usage in browser-entry.ts:
+ *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
+ *   reactRoot = hydrateRoot(document, rootEl);
+ *
+ * Subsequent navigations:
+ *   transitionRender(newWrappedElement);
+ */
+export function TransitionRoot({ initial }: { initial: ReactNode }): ReactNode {
+  const [element, setElement] = useState<ReactNode>(initial);
+
+  // Update the module-level ref on every render so it always points
+  // to the current component instance's setState.
+  _transitionRender = (newElement: ReactNode) => {
+    startTransition(() => {
+      setElement(newElement);
+    });
+  };
+
+  return element;
+}
+
+// ─── Public API ──────────────────────────────────────────────────
+
+/**
+ * Trigger a transition render. React keeps the old committed tree
+ * visible while any new Suspense boundaries in the update resolve.
+ *
+ * This is the function called by the router's renderRoot callback
+ * instead of reactRoot.render() directly.
+ *
+ * Falls back to no-op if TransitionRoot hasn't mounted yet (shouldn't
+ * happen in practice — TransitionRoot mounts during hydration).
+ */
+export function transitionRender(element: ReactNode): void {
+  if (_transitionRender) {
+    _transitionRender(element);
+  }
+}
+
+/**
+ * Check if the TransitionRoot is mounted and ready for renders.
+ * Used by browser-entry.ts to guard against renders before hydration.
+ */
+export function isTransitionRootReady(): boolean {
+  return _transitionRender !== null;
+}

package/src/client/use-params.ts

@@ -18,10 +18,11 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
- * Reactivity: useParams() uses useSyncExternalStore so that components
- * in unchanged layouts (e.g., sidebar items) re-render atomically when
- * params change during client-side navigation. This matches the pattern
- * used by usePathname() and useSearchParams().
+ * Reactivity: On the client, useParams() reads from NavigationContext
+ * which is updated atomically with the RSC tree render. This replaces
+ * the previous useSyncExternalStore approach that suffered from a
+ * timing gap between tree render and store notification — causing
+ * preserved layout components to briefly show stale active state.
  *
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
@@ -29,18 +30,20 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
-import { useSyncExternalStore } from 'react';
 import type { Routes } from '#/index.js';
 import { getSsrData } from './ssr-data.js';
 import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
+import { useNavigationContext } from './navigation-context.js';
 
 // ---------------------------------------------------------------------------
-// Module-level subscribe/notify pattern — state lives in state.ts
+// Module-level subscribe/notify pattern — kept for backward compat and tests
 // ---------------------------------------------------------------------------
 
 /**
- * Subscribe to params changes. Called by useSyncExternalStore.
- * Exported for testing — not intended for direct use by app code.
+ * Subscribe to params changes.
+ * Retained for backward compatibility with tests that verify the
+ * subscribe/notify contract. On the client, useParams() reads from
+ * NavigationContext instead.
  */
 export function subscribe(callback: () => void): () => void {
   paramsListeners.add(callback);
@@ -48,51 +51,43 @@ export function subscribe(callback: () => void): () => void {
 }
 
 /**
- * Get the current params snapshot (client).
- * Exported for testing — not intended for direct use by app code.
+ * Get the current params snapshot (module-level fallback).
+ * Used by tests and by the hook when called outside a React component.
  */
 export function getSnapshot(): Record<string, string | string[]> {
   return currentParams;
 }
 
-/**
- * Get the server-side params snapshot (SSR).
- * Falls back to the module-level currentParams if no SSR context
- * is available (shouldn't happen, but defensive).
- */
-function getServerSnapshot(): Record<string, string | string[]> {
-  return getSsrData()?.params ?? currentParams;
-}
-
 // ---------------------------------------------------------------------------
 // Framework API — called by the segment router on each navigation
 // ---------------------------------------------------------------------------
 
 /**
- * Set the current route params WITHOUT notifying subscribers.
- * Called by the router before renderPayload() so that new components
- * in the RSC tree see the updated params via getSnapshot(), but
- * preserved layout components don't re-render prematurely with
- * {old tree, new params}.
+ * Set the current route params in the module-level store.
+ *
+ * Called by the router on each navigation. This updates the fallback
+ * snapshot used by tests and by the hook when called outside a React
+ * component (no NavigationContext available).
  *
- * After the React render commits, the router calls notifyParamsListeners()
- * to trigger re-renders in preserved layouts that read useParams().
+ * On the client, the primary reactivity path is NavigationContext —
+ * the router calls setNavigationState() then renderRoot() which wraps
+ * the element in NavigationProvider. setCurrentParams is still called
+ * for the module-level fallback.
  *
- * On the client, the segment router calls this on each navigation.
  * During SSR, params are also available via getSsrData().params
- * (ALS-backed), but setCurrentParams is still called for the
- * module-level fallback path.
+ * (ALS-backed).
  */
 export function setCurrentParams(params: Record<string, string | string[]>): void {
   _setCurrentParams(params);
 }
 
 /**
- * Notify all useSyncExternalStore subscribers that params have changed.
- * Called by the router AFTER renderPayload() so that preserved layout
- * components re-render only after the new tree is committed — producing
- * an atomic {new tree, new params} update instead of a stale
- * {old tree, new params} intermediate state.
+ * Notify all legacy subscribers that params have changed.
+ *
+ * Retained for backward compatibility with tests. On the client,
+ * the NavigationContext + renderRoot pattern replaces this — params
+ * update atomically with the tree render, so explicit notification
+ * is no longer needed.
  */
 export function notifyParamsListeners(): void {
   for (const listener of paramsListeners) {
@@ -110,9 +105,15 @@ export function notifyParamsListeners(): void {
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). This ensures params update
+ * atomically with the RSC tree — no timing gap.
+ *
  * During SSR, reads from the ALS-backed SSR data context to ensure
- * per-request isolation. On the client, subscribes to the module-level
- * params store via useSyncExternalStore.
+ * per-request isolation across concurrent requests with streaming Suspense.
+ *
+ * When called outside a React component (e.g., in test assertions),
+ * falls back to the module-level snapshot.
  *
  * @overload Typed — when a known route path is passed, returns the
  *   exact params shape from the generated Routes interface.
@@ -121,25 +122,20 @@ export function notifyParamsListeners(): void {
 export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
 export function useParams(route?: string): Record<string, string | string[]>;
 export function useParams(_route?: string): Record<string, string | string[]> {
-  // useSyncExternalStore handles both client and SSR:
-  // - Client: calls getSnapshot() → reads currentParams from state.ts
-  // - SSR: calls getServerSnapshot() → reads from ALS-backed getSsrData()
-  //
-  // We must always call the hook (Rules of Hooks — no conditional hook calls).
-  // React picks the right snapshot function based on the environment.
-  //
-  // When called outside a React component (e.g., in test assertions),
-  // useSyncExternalStore throws because there's no dispatcher. In that case,
-  // fall back to reading the snapshot directly.
+  // Try reading from NavigationContext (client-side, inside React tree).
+  // During SSR, no NavigationProvider is mounted, so this returns null.
+  // When called outside a React component, useContext throws — caught below.
   try {
-    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const navContext = useNavigationContext();
+    if (navContext !== null) {
+      return navContext.params;
+    }
   } catch {
-    // No React dispatcher available — return the best available snapshot.
-    // This path is hit when useParams() is called outside a component,
-    // e.g. in test assertions that verify the current params value.
-    // Use getServerSnapshot() because it checks the ALS-backed SSR context
-    // first (request-isolated), falling back to module-level currentParams
-    // only when no SSR context exists (client-side / tests).
-    return getServerSnapshot();
+    // No React dispatcher available (called outside a component).
+    // Fall through to module-level snapshot below.
   }
+
+  // SSR path: read from ALS-backed SSR data context.
+  // Falls back to module-level currentParams for tests.
+  return getSsrData()?.params ?? currentParams;
 }

package/src/client/use-pathname.ts

@@ -4,40 +4,47 @@
  * Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
  * Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.pathname, provided for
- * Next.js API compatibility (libraries like nuqs import usePathname
- * from next/navigation).
+ * On the client, reads from NavigationContext which is updated atomically
+ * with the RSC tree render. This replaces the previous useSyncExternalStore
+ * approach which only subscribed to popstate events — meaning usePathname()
+ * did NOT re-render on forward navigation (pushState). The context approach
+ * fixes this: pathname updates in the same render pass as the new tree.
  *
  * During SSR, reads the request pathname from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
+ *
+ * Compatible with Next.js's `usePathname()` from `next/navigation`.
  */
 
-import { useSyncExternalStore } from 'react';
 import { getSsrData } from './ssr-data.js';
-
-function getPathname(): string {
-  if (typeof window !== 'undefined') return window.location.pathname;
-  return getSsrData()?.pathname ?? '/';
-}
-
-function getServerPathname(): string {
-  return getSsrData()?.pathname ?? '/';
-}
-
-function subscribe(callback: () => void): () => void {
-  // Listen for popstate (back/forward) and timber's custom navigation events.
-  // pushState/replaceState don't fire popstate, but timber's router calls
-  // onPendingChange listeners after navigation — components re-render
-  // naturally via React's tree update from the new RSC payload.
-  window.addEventListener('popstate', callback);
-  return () => window.removeEventListener('popstate', callback);
-}
+import { useNavigationContext } from './navigation-context.js';
 
 /**
  * Read the current URL pathname.
  *
- * Compatible with Next.js's `usePathname()` from `next/navigation`.
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). During SSR, reads from the
+ * ALS-backed SSR data context. Falls back to window.location.pathname
+ * when called outside a React component (e.g., in tests).
  */
 export function usePathname(): string {
-  return useSyncExternalStore(subscribe, getPathname, getServerPathname);
+  // Try reading from NavigationContext (client-side, inside React tree).
+  // During SSR, no NavigationProvider is mounted, so this returns null.
+  try {
+    const navContext = useNavigationContext();
+    if (navContext !== null) {
+      return navContext.pathname;
+    }
+  } catch {
+    // No React dispatcher available (called outside a component).
+    // Fall through to SSR/fallback below.
+  }
+
+  // SSR path: read from ALS-backed SSR data context.
+  const ssrData = getSsrData();
+  if (ssrData) return ssrData.pathname ?? '/';
+
+  // Final fallback: window.location (tests, edge cases).
+  if (typeof window !== 'undefined') return window.location.pathname;
+  return '/';
 }

package/src/client/use-router.ts

@@ -7,9 +7,22 @@
  *
  * This wraps timber's internal RouterInstance in the Next.js-compatible
  * AppRouterInstance shape that ecosystem libraries expect.
+ *
+ * NOTE: Unlike Next.js, these methods do NOT wrap navigation in
+ * startTransition. In Next.js, router state is React state (useReducer)
+ * so startTransition defers the update and provides isPending tracking.
+ * In timber, navigation calls reactRoot.render() which is a root-level
+ * render — startTransition has no effect on root renders.
+ *
+ * Navigation state (params, pathname) is delivered atomically via
+ * NavigationContext embedded in the element tree passed to
+ * reactRoot.render(). See design/19-client-navigation.md §"NavigationContext".
+ *
+ * For loading UI during navigation, use:
+ * - useLinkStatus()          — per-link pending indicator (inside <Link>)
+ * - useNavigationPending()   — global navigation pending state
  */
 
-import { startTransition } from 'react';
 import { getRouterOrNull } from './router-ref.js';
 
 export interface AppRouterInstance {
@@ -54,14 +67,7 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      // Wrap in startTransition so React 19 tracks the async navigation.
-      // React 19's startTransition accepts async callbacks — it keeps
-      // isPending=true until the returned promise resolves. This means
-      // useTransition's isPending reflects the full RSC fetch + render
-      // lifecycle when wrapping router.push() in startTransition.
-      startTransition(async () => {
-        await router.navigate(href, { scroll: options?.scroll });
-      });
+      void router.navigate(href, { scroll: options?.scroll });
     },
     replace(href: string, options?: { scroll?: boolean }) {
       const router = getRouterOrNull();
@@ -71,9 +77,7 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      startTransition(async () => {
-        await router.navigate(href, { scroll: options?.scroll, replace: true });
-      });
+      void router.navigate(href, { scroll: options?.scroll, replace: true });
     },
     refresh() {
       const router = getRouterOrNull();
@@ -83,9 +87,7 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      startTransition(async () => {
-        await router.refresh();
-      });
+      void router.refresh();
     },
     back() {
       if (typeof window !== 'undefined') window.history.back();