@timber-js/app 0.2.0-alpha.165 → 0.2.0-alpha.167

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

@@ -38,9 +38,25 @@ export function setupPostHydration({
   // 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).
+  // 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('../segment-cache').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.
   router.historyStack.push(window.location.pathname + window.location.search, {
     payload: initialElement,
     params: getNavigationState().params,
+    segmentInfo: initialSegmentInfo,
   });
 
   // Initialize scroll state for the initial entry.
@@ -52,15 +68,6 @@ export function setupPostHydration({
     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.

package/src/client/history.ts

@@ -1,6 +1,8 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
+import type { SegmentInfo } from './segment-cache';
+
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface HistoryEntry {
@@ -13,6 +15,15 @@ export interface HistoryEntry {
    * and revalidation overwrites preserve the current state (TIM-1037).
    */
   params?: Record<string, string | string[]> | null;
+  /**
+   * Segment metadata for this page's route. Restored into the segment cache
+   * on popstate cached replay so the next forward navigation computes a
+   * correct state tree. Without this, the segment cache retains the
+   * *previous* page's segments after back-button, causing the server to
+   * skip segments that aren't mounted — and the partial payload targets
+   * a non-existent outlet.
+   */
+  segmentInfo?: SegmentInfo[] | null;
 }
 
 // ─── History Stack ───────────────────────────────────────────────

package/src/client/router.ts

@@ -306,6 +306,89 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Atomically update all navigation-owned state for a new page. Every
+   * code path that changes the "current page" must go through this
+   * function — making "forgot a field" impossible by construction.
+   *
+   * The three operations:
+   * 1. Segment cache — update from server-provided segment metadata
+   * 2. Navigation state — params + pathname for useSegmentParams/usePathname
+   * 3. History stack — store the payload for instant back/forward replay
+   */
+  function commitNavigation(
+    url: string,
+    opts: {
+      payload: unknown;
+      params?: Record<string, string | string[]> | null;
+      segmentInfo?: SegmentInfo[] | null;
+      /** When true, clear the segment cache if segmentInfo is empty
+       *  (popstate replay for entries without layout metadata). */
+      clearSegmentCacheOnEmpty?: boolean;
+    }
+  ): NavigationState {
+    if (opts.segmentInfo && opts.segmentInfo.length > 0) {
+      updateSegmentCache(opts.segmentInfo);
+    } else if (opts.clearSegmentCacheOnEmpty) {
+      segmentCache.clear();
+    }
+
+    const navState = updateNavigationState(opts.params, url);
+
+    historyStack.push(url, {
+      payload: opts.payload,
+      params: navState.params,
+      segmentInfo: opts.segmentInfo,
+    });
+
+    return navState;
+  }
+
+  /**
+   * Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+   * Consolidates the createNavAbort + setPending + staleness-guarded
+   * finally that was duplicated across navigate, refresh, and both
+   * handlePopState paths. AbortErrors are swallowed (not application
+   * errors); all other errors propagate to the caller.
+   */
+  async function runNavigation(
+    url: string,
+    fn: (navAbort: AbortController) => Promise<void>,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
+    const navAbort = createNavAbort(externalSignal);
+    setPending(true, url);
+    try {
+      await fn(navAbort);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      throw error;
+    } finally {
+      if (currentNavAbort === navAbort) {
+        currentNavAbort = null;
+        setPending(false);
+        deps.completeRouterNavigation?.();
+      }
+    }
+  }
+
+  /**
+   * Resolve thenable payloads in the test/fallback path (no navigateTransition).
+   * In production, React handles thenables from createFromFetch directly via
+   * Suspense. In tests, renderRoot is a plain mock that expects resolved values.
+   */
+  async function resolveForFallback(payload: unknown): Promise<unknown> {
+    if (
+      !deps.navigateTransition &&
+      payload != null &&
+      typeof payload === 'object' &&
+      'then' in payload
+    ) {
+      return await (payload as PromiseLike<unknown>);
+    }
+    return payload;
+  }
+
   function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {
     return skippedSegments != null && skippedSegments.length > 0;
   }
@@ -357,9 +440,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /**
    * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, update state, and return the
-   * FetchResult plus the NavigationState (so it can be passed explicitly
-   * to wrapPayload/renderRoot without temporal coupling).
+   * The perform callback should fetch data, call commitNavigation, and return
+   * the FetchResult plus the NavigationState.
+   *
+   * State management (segmentCache, navState, historyStack) is handled by
+   * commitNavigation inside perform — this function only handles rendering.
    */
   async function renderViaTransition(
     url: string,
@@ -372,11 +457,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         if (isPartialNavigation(result.skippedSegments)) {
           const segmentUpdates = buildSegmentUpdates(result);
 
-          historyStack.push(url, {
-            payload: null,
-            params: result.params,
-          });
-
           // Re-wrap the CURRENT element with new context values.
           // SegmentOutlets read updates from SegmentUpdateContext;
           // NavigationProvider gets new params/pathname.
@@ -389,10 +469,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         }
 
         // Full navigation — empty updates, render the new tree.
-        historyStack.push(url, {
-          payload: result.payload,
-          params: result.params,
-        });
         const element = wrapPayload(result.payload, result.navState);
         return { element, decodePromise: result.decodePromise };
       });
@@ -400,24 +476,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    if (isPartialNavigation(result.skippedSegments)) {
-      historyStack.push(url, {
-        payload: null,
-        params: result.params,
-      });
-    } else {
-      // Resolve thenables before storing/rendering in the fallback path
-      // (tests without navigateTransition). In production, React handles
-      // thenables via Suspense; in tests, renderRoot expects resolved values.
-      const payload =
-        result.payload != null && typeof result.payload === 'object' && 'then' in result.payload
-          ? await (result.payload as PromiseLike<unknown>)
-          : result.payload;
-      historyStack.push(url, {
-        payload,
-        params: result.params,
-      });
-      renderPayload(payload, result.navState);
+    if (!isPartialNavigation(result.skippedSegments)) {
+      renderPayload(result.payload, result.navState);
     }
   }
 
@@ -505,18 +565,21 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.setRouterNavigating?.(false);
     }
 
-    // NOTE: History push is deferred — the merged payload (after segment
-    // merging in renderViaTransition) is stored by the caller, not here.
-    // Storing result.payload here would record the partial (pre-merge)
-    // RSC tree, causing handlePopState to replay an incomplete tree.
-
-    // Update the segment cache with the new route's segment tree.
-    updateSegmentCache(result.segmentInfo);
-
-    // Update navigation state and capture it for explicit passing.
-    const navState = updateNavigationState(result.params, url);
+    // Resolve thenable payloads in the test path so popstate replay
+    // and renderPayload receive plain values (see resolveForFallback).
+    const payload = await resolveForFallback(result.payload);
+
+    // Atomically update all navigation state via commitNavigation.
+    // Partial navigations store null payload — the partial RSC tree
+    // can't be replayed standalone; popstate will fetch fresh.
+    const isPartial = isPartialNavigation(result.skippedSegments);
+    const navState = commitNavigation(url, {
+      payload: isPartial ? null : payload,
+      params: result.params,
+      segmentInfo: result.segmentInfo,
+    });
 
-    return { ...result, navState };
+    return { ...result, payload, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -534,10 +597,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
     const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
 
-    // Create an abort controller for this navigation. Links to the external
-    // signal (Navigation API's event.signal) when provided.
-    const navAbort = createNavAbort(externalSignal);
-
     // Capture the departing page's scroll position for scroll={false} preservation.
     const currentScrollY = deps.getScrollY();
 
@@ -549,114 +608,69 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
     }
 
-    // When Navigation API is active, initiate the navigation via
-    // navigation.navigate() BEFORE the fetch. Unlike history.pushState()
-    // which commits the URL synchronously (so Chrome sees it as "done"),
-    // navigation.navigate() fires the navigate event before committing.
-    // Our handler intercepts with a deferred promise, and Chrome shows
-    // its native loading indicator until completeRouterNavigation()
-    // resolves it in the finally block (same time as TopLoader clears).
     let effectiveSkipHistory = skipHistory;
-    if (!skipHistory && deps.navigationNavigate) {
-      deps.setRouterNavigating?.(true);
-      deps.navigationNavigate(url, replace);
-      deps.setRouterNavigating?.(false);
-      effectiveSkipHistory = true;
-    }
 
-    setPending(true, url);
-
-    try {
-      await renderViaTransition(fetchUrl, () =>
-        performNavigationFetch(fetchUrl, {
-          replace,
-          commitUrl: url,
-          signal: navAbort.signal,
-          skipHistory: effectiveSkipHistory,
-        })
-      );
+    await runNavigation(
+      url,
+      async (navAbort) => {
+        // When Navigation API is active, initiate the navigation via
+        // navigation.navigate() BEFORE the fetch. Must happen after
+        // createNavAbort supersedes the previous navigation (done by
+        // runNavigation) so the old deferred is resolved first.
+        if (!effectiveSkipHistory && deps.navigationNavigate) {
+          deps.setRouterNavigating?.(true);
+          deps.navigationNavigate(url, replace);
+          deps.setRouterNavigating?.(false);
+          effectiveSkipHistory = true;
+        }
 
-      // Notify nuqs adapter (and any other listeners) that navigation completed.
-      window.dispatchEvent(new Event('timber:navigation-end'));
+        try {
+          await renderViaTransition(fetchUrl, () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: navAbort.signal,
+              skipHistory: effectiveSkipHistory,
+            })
+          );
 
-      // Scroll-to-top on forward navigation, scroll to the #fragment target
-      // when the URL has one, or restore captured position for scroll={false}.
-      // React's render() on the document root can reset scroll during DOM
-      // reconciliation, so all scroll must be actively managed.
-      if (scroll && hash) {
-        scrollToHashAfterPaint(hash);
-      } else {
-        restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
-      }
-    } catch (error) {
-      // Version skew — server has been redeployed. Full page reload
-      // so the browser fetches the new bundle. See TIM-446.
-      if (error instanceof VersionSkewError) {
-        setHardNavigating(true);
-        window.location.reload();
-        return new Promise(() => {}) as never;
-      }
-      // Server-side redirect during RSC fetch → soft router navigation.
-      // The redirect navigate will push/replace its own URL.
-      if (error instanceof RedirectError) {
-        // Drop the redirect if a newer navigation superseded this one
-        // while the redirect response was in flight — the newer
-        // navigation wins, same as the stale-transition guard.
-        if (currentNavAbort !== navAbort) return;
-        // The recursive navigate() supersedes this one via createNavAbort,
-        // which also resolves this navigation's Navigation API deferred.
-        await navigate(error.redirectUrl, { replace: true });
-        return;
-      }
-      // Server 5xx error — hard-navigate so the server renders the
-      // error page as HTML. See design/10-error-handling.md
-      // §"Error Page Rendering for Client Navigation".
-      //
-      // Set hard-navigating flag BEFORE setting window.location.href:
-      // 1. Prevents Navigation API from intercepting → infinite loop
-      // 2. Causes NavigationRoot to throw unresolvedThenable → prevents
-      //    React from rendering children during page teardown (avoids
-      //    "Rendered more hooks" crashes). See TIM-626.
-      if (error instanceof ServerErrorResponse) {
-        setHardNavigating(true);
-        window.location.href = error.url;
-        return new Promise(() => {}) as never;
-      }
-      // Abort errors are not application errors — swallow silently.
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      // Staleness guard (TIM-1034): only clean up when this navigation
-      // still owns the abort controller. When a newer navigation
-      // superseded this one, createNavAbort() already replaced
-      // currentNavAbort — running setPending(false) /
-      // completeRouterNavigation() here would clear the NEWER
-      // navigation's pending state and resolve its Navigation API
-      // deferred. The superseding navigation resolved OUR deferred in
-      // createNavAbort().
-      if (currentNavAbort === navAbort) {
-        // Clear the abort controller so we don't abort a completed
-        // navigation when the next one starts. In dev mode, the RSC body
-        // stream stays open after data arrives (React's Flight client
-        // waits for debug rows). Aborting a "completed" navigation kills
-        // the open stream reader → "BodyStreamBuffer was aborted".
-        currentNavAbort = null;
-        setPending(false);
-        // Resolve the Navigation API deferred — clears the browser's
-        // native loading state (tab spinner) at the same time as the
-        // TopLoader.
-        deps.completeRouterNavigation?.();
-      }
-    }
+          // Notify nuqs adapter (and any other listeners) that navigation completed.
+          window.dispatchEvent(new Event('timber:navigation-end'));
+
+          // Scroll-to-top on forward navigation, scroll to the #fragment target
+          // when the URL has one, or restore captured position for scroll={false}.
+          if (scroll && hash) {
+            scrollToHashAfterPaint(hash);
+          } else {
+            restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+          }
+        } catch (error) {
+          if (error instanceof VersionSkewError) {
+            setHardNavigating(true);
+            window.location.reload();
+            await new Promise(() => {});
+          }
+          if (error instanceof RedirectError) {
+            if (currentNavAbort !== navAbort) return;
+            await navigate(error.redirectUrl, { replace: true });
+            return;
+          }
+          if (error instanceof ServerErrorResponse) {
+            setHardNavigating(true);
+            window.location.href = error.url;
+            await new Promise(() => {});
+          }
+          throw error;
+        }
+      },
+      externalSignal
+    );
   }
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
-    const navAbort = createNavAbort();
-
-    setPending(true, currentUrl);
 
-    try {
+    await runNavigation(currentUrl, async (navAbort) => {
       await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(
@@ -666,22 +680,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           undefined,
           navAbort.signal
         );
-        // History push handled by renderViaTransition (stores merged payload)
-        updateSegmentCache(result.segmentInfo);
-        const navState = updateNavigationState(result.params, currentUrl);
-        return { ...result, navState };
+        const payload = await resolveForFallback(result.payload);
+        const navState = commitNavigation(currentUrl, {
+          payload,
+          params: result.params,
+          segmentInfo: result.segmentInfo,
+        });
+        return { ...result, payload, navState };
       });
-    } catch (error) {
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      // Staleness guard (TIM-1034) — see navigate()'s finally block.
-      if (currentNavAbort === navAbort) {
-        currentNavAbort = null;
-        setPending(false);
-        deps.completeRouterNavigation?.();
-      }
-    }
+    });
   }
 
   async function handlePopState(
@@ -697,47 +704,51 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip.
       //
-      // A forward navigation may still be in flight (back pressed while a
-      // slow RSC fetch was pending). createNavAbort() supersedes it: aborts
-      // its fetch and invalidates its render transition so the stale
-      // forward payload can't commit over this replay (TIM-1022). The
-      // replay itself is synchronous — nothing to abort later — so the
-      // controller is cleared immediately, and any pending state left by
-      // the superseded navigation is reset.
-      createNavAbort(externalSignal);
-      currentNavAbort = null;
-      setPending(false);
-      const navState = updateNavigationState(entry.params, url);
-      renderPayload(entry.payload, navState);
-      restoreScrollAfterPaint(scrollY);
+      // runNavigation supersedes any in-flight forward navigation (TIM-1022):
+      // aborts its fetch and invalidates its render transition so the stale
+      // forward payload can't commit over this replay. The replay itself is
+      // synchronous — the fn resolves immediately.
+      await runNavigation(
+        url,
+        async () => {
+          // clearSegmentCacheOnEmpty: popstate to an entry without layout
+          // metadata (e.g., initial SSR page) clears the cache so the next
+          // forward navigation gets a full render.
+          const navState = commitNavigation(url, {
+            payload: entry.payload,
+            params: entry.params,
+            segmentInfo: entry.segmentInfo,
+            clearSegmentCacheOnEmpty: true,
+          });
+          renderPayload(entry.payload, navState);
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
       // (its payload is null since it was rendered via SSR, not RSC fetch)
       // or when the entry doesn't exist at all.
-      const navAbort = createNavAbort(externalSignal);
-      setPending(true, url);
-      try {
-        await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree();
-          const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
-          updateSegmentCache(result.segmentInfo);
-          const navState = updateNavigationState(result.params, url);
-          // History push handled by renderViaTransition (stores merged payload)
-          return { ...result, navState };
-        });
+      await runNavigation(
+        url,
+        async (navAbort) => {
+          await renderViaTransition(url, async () => {
+            const stateTree = segmentCache.serializeStateTree();
+            const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
+            const payload = await resolveForFallback(result.payload);
+            const navState = commitNavigation(url, {
+              payload,
+              params: result.params,
+              segmentInfo: result.segmentInfo,
+            });
+            return { ...result, payload, navState };
+          });
 
-        restoreScrollAfterPaint(scrollY);
-      } catch (error) {
-        if (isAbortError(error)) return;
-        throw error;
-      } finally {
-        // Staleness guard (TIM-1034) — see navigate()'s finally block.
-        if (currentNavAbort === navAbort) {
-          currentNavAbort = null;
-          setPending(false);
-        }
-      }
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     }
   }
 
@@ -783,21 +794,16 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload —
       // same as refresh() but without a server fetch.
-      // Revalidation payloads are already resolved (no Flight thenable),
-      // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
 
-      // Revalidation doesn't change params/pathname — preserve current state.
-      // DO NOT call updateNavigationState(null, ...) here: that normalizes
-      // params to {}, clearing dynamic route params on every action response.
-      const navState = getNavigationState();
-
-      // Keep params on the overwritten entry — dropping them would make
-      // away-and-back navigation replay this page with params normalized
-      // to {} (TIM-1037).
-      historyStack.push(currentUrl, {
+      // Preserve existing segmentInfo so away-and-back navigation replays
+      // with a correct segment cache (TIM-1037). Preserve current params
+      // so dynamic route params aren't cleared to {}.
+      const existingEntry = historyStack.get(currentUrl);
+      const navState = commitNavigation(currentUrl, {
         payload: element,
-        params: navState.params,
+        params: getNavigationState().params,
+        segmentInfo: existingEntry?.segmentInfo,
       });
       renderPayload(element, navState);
     },