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

package/dist/client/history.d.ts

@@ -1,3 +1,4 @@
+import type { SegmentInfo } from './segment-cache';
 export interface HistoryEntry {
     /** The complete segment tree payload at the time of navigation */
     payload: unknown;
@@ -8,6 +9,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;
 }
 /**
  * Session-lived history stack keyed by URL. Enables instant back/forward

package/dist/client/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/client/history.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACnD;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmC;IAElD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAI5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI1C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAG1B"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/client/history.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAClD;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CACpC;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmC;IAElD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAI5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI1C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAG1B"}

package/dist/client/internal.js

@@ -1,4 +1,4 @@
-import { t as bindUseQueryStates } from "../_chunks/use-query-states-CbeQmext.js";
+import { t as bindUseQueryStates } from "../_chunks/use-query-states-DFvWd-EA.js";
 import { c as cachedSearchParams, i as _setCachedSearch, n as getSsrData, r as setSsrData, s as cachedSearch, t as clearSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
 import { a as setNavigationState, i as getNavigationState, o as useNavigationContext, r as NavigationProvider, t as setCurrentParams } from "../_chunks/use-segment-params-D1CzlgBo.js";
 import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-CtmF-aPv.js";
@@ -458,6 +458,59 @@ function createRouter(deps) {
 	function renderPayload(payload, navState) {
 		if (deps.renderRoot) deps.renderRoot(payload, navState);
 	}
+	/**
+	* 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, opts) {
+		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, fn, externalSignal) {
+		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) {
+		if (!deps.navigateTransition && payload != null && typeof payload === "object" && "then" in payload) return await payload;
+		return payload;
+	}
 	function isPartialNavigation(skippedSegments) {
 		return skippedSegments != null && skippedSegments.length > 0;
 	}
@@ -499,9 +552,11 @@ function createRouter(deps) {
 	}
 	/**
 	* 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, perform) {
 		if (deps.navigateTransition) {
@@ -509,19 +564,11 @@ function createRouter(deps) {
 				const result = await perform();
 				if (isPartialNavigation(result.skippedSegments)) {
 					const segmentUpdates = buildSegmentUpdates(result);
-					historyStack.push(url, {
-						payload: null,
-						params: result.params
-					});
 					return {
 						element: wrapPayload(deps._getCurrentPayload?.() ?? result.payload, result.navState, segmentUpdates),
 						decodePromise: result.decodePromise
 					};
 				}
-				historyStack.push(url, {
-					payload: result.payload,
-					params: result.params
-				});
 				return {
 					element: wrapPayload(result.payload, result.navState),
 					decodePromise: result.decodePromise
@@ -530,18 +577,7 @@ function createRouter(deps) {
 			return;
 		}
 		const result = await perform();
-		if (isPartialNavigation(result.skippedSegments)) historyStack.push(url, {
-			payload: null,
-			params: result.params
-		});
-		else {
-			const payload = result.payload != null && typeof result.payload === "object" && "then" in result.payload ? await result.payload : result.payload;
-			historyStack.push(url, {
-				payload,
-				params: result.params
-			});
-			renderPayload(payload, result.navState);
-		}
+		if (!isPartialNavigation(result.skippedSegments)) renderPayload(result.payload, result.navState);
 	}
 	/** Run a callback after the next paint (after React commit). */
 	function afterPaint(callback) {
@@ -601,10 +637,15 @@ function createRouter(deps) {
 			}, "", commitUrl);
 			deps.setRouterNavigating?.(false);
 		}
-		updateSegmentCache(result.segmentInfo);
-		const navState = updateNavigationState(result.params, url);
+		const payload = await resolveForFallback(result.payload);
+		const navState = commitNavigation(url, {
+			payload: isPartialNavigation(result.skippedSegments) ? null : payload,
+			params: result.params,
+			segmentInfo: result.segmentInfo
+		});
 		return {
 			...result,
+			payload,
 			navState
 		};
 	}
@@ -616,7 +657,6 @@ function createRouter(deps) {
 		const hashIndex = url.indexOf("#");
 		const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
 		const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
-		const navAbort = createNavAbort(externalSignal);
 		const currentScrollY = deps.getScrollY();
 		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
 		else deps.replaceState({
@@ -624,107 +664,91 @@ function createRouter(deps) {
 			scrollY: currentScrollY
 		}, "", deps.getCurrentUrl());
 		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
-			}));
-			window.dispatchEvent(new Event("timber:navigation-end"));
-			if (scroll && hash) scrollToHashAfterPaint(hash);
-			else restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
-		} catch (error) {
-			if (error instanceof VersionSkewError) {
-				setHardNavigating(true);
-				window.location.reload();
-				return new Promise(() => {});
-			}
-			if (error instanceof RedirectError) {
-				if (currentNavAbort !== navAbort) return;
-				await navigate(error.redirectUrl, { replace: true });
-				return;
+		await runNavigation(url, async (navAbort) => {
+			if (!effectiveSkipHistory && deps.navigationNavigate) {
+				deps.setRouterNavigating?.(true);
+				deps.navigationNavigate(url, replace);
+				deps.setRouterNavigating?.(false);
+				effectiveSkipHistory = true;
 			}
-			if (error instanceof ServerErrorResponse) {
-				setHardNavigating(true);
-				window.location.href = error.url;
-				return new Promise(() => {});
-			}
-			if (isAbortError(error)) return;
-			throw error;
-		} finally {
-			if (currentNavAbort === navAbort) {
-				currentNavAbort = null;
-				setPending(false);
-				deps.completeRouterNavigation?.();
+			try {
+				await renderViaTransition(fetchUrl, () => performNavigationFetch(fetchUrl, {
+					replace,
+					commitUrl: url,
+					signal: navAbort.signal,
+					skipHistory: effectiveSkipHistory
+				}));
+				window.dispatchEvent(new Event("timber:navigation-end"));
+				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() {
 		const currentUrl = deps.getCurrentUrl();
-		const navAbort = createNavAbort();
-		setPending(true, currentUrl);
-		try {
+		await runNavigation(currentUrl, async (navAbort) => {
 			await renderViaTransition(currentUrl, async () => {
 				const result = await fetchRscPayload(currentUrl, deps, void 0, void 0, navAbort.signal);
-				updateSegmentCache(result.segmentInfo);
-				const navState = updateNavigationState(result.params, currentUrl);
+				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 {
-			if (currentNavAbort === navAbort) {
-				currentNavAbort = null;
-				setPending(false);
-				deps.completeRouterNavigation?.();
-			}
-		}
+		});
 	}
 	async function handlePopState(url, scrollY = 0, externalSignal) {
 		const entry = historyStack.get(url);
-		if (entry && entry.payload !== null) {
-			createNavAbort(externalSignal);
-			currentNavAbort = null;
-			setPending(false);
-			const navState = updateNavigationState(entry.params, url);
+		if (entry && entry.payload !== null) await runNavigation(url, async () => {
+			const navState = commitNavigation(url, {
+				payload: entry.payload,
+				params: entry.params,
+				segmentInfo: entry.segmentInfo,
+				clearSegmentCacheOnEmpty: true
+			});
 			renderPayload(entry.payload, navState);
 			restoreScrollAfterPaint(scrollY);
-		} else {
-			const navAbort = createNavAbort(externalSignal);
-			setPending(true, url);
-			try {
-				await renderViaTransition(url, async () => {
-					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(), void 0, navAbort.signal);
-					updateSegmentCache(result.segmentInfo);
-					const navState = updateNavigationState(result.params, url);
-					return {
-						...result,
-						navState
-					};
+		}, externalSignal);
+		else await runNavigation(url, async (navAbort) => {
+			await renderViaTransition(url, async () => {
+				const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(), void 0, navAbort.signal);
+				const payload = await resolveForFallback(result.payload);
+				const navState = commitNavigation(url, {
+					payload,
+					params: result.params,
+					segmentInfo: result.segmentInfo
 				});
-				restoreScrollAfterPaint(scrollY);
-			} catch (error) {
-				if (isAbortError(error)) return;
-				throw error;
-			} finally {
-				if (currentNavAbort === navAbort) {
-					currentNavAbort = null;
-					setPending(false);
-				}
-			}
-		}
+				return {
+					...result,
+					payload,
+					navState
+				};
+			});
+			restoreScrollAfterPaint(scrollY);
+		}, externalSignal);
 	}
 	/**
 	* Prefetch an RSC payload for a URL and store it in the prefetch cache.
@@ -753,12 +777,12 @@ function createRouter(deps) {
 		prefetch,
 		applyRevalidation(element) {
 			const currentUrl = deps.getCurrentUrl();
-			const navState = getNavigationState();
-			historyStack.push(currentUrl, {
+			const existingEntry = historyStack.get(currentUrl);
+			renderPayload(element, commitNavigation(currentUrl, {
 				payload: element,
-				params: navState.params
-			});
-			renderPayload(element, navState);
+				params: getNavigationState().params,
+				segmentInfo: existingEntry?.segmentInfo
+			}));
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
 		segmentCache,