@timber-js/app 0.1.30 → 0.1.31

package/dist/client/index.js

@@ -67,104 +67,55 @@ function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
 //#endregion
-//#region src/client/navigation-context.ts
+//#region src/client/pending-navigation-context.ts
 /**
-* NavigationContext — React context for navigation state.
+* PendingNavigationContext — React context for the in-flight navigation URL.
 *
-* Holds the current route params and pathname, updated atomically
-* with the RSC tree on each navigation. This replaces the previous
-* useSyncExternalStore approach for useParams() and usePathname(),
-* which suffered from a timing gap: the new tree could commit before
-* the external store re-renders fired, causing a frame where both
-* old and new active states were visible simultaneously.
-*
-* By wrapping the RSC payload element in NavigationProvider inside
-* renderRoot(), the context value and the element tree are passed to
-* reactRoot.render() in the same call — atomic by construction.
-* All consumers (useParams, usePathname) see the new values in the
-* same render pass as the new tree.
+* Provided by TransitionRoot. The value is the URL being navigated to,
+* or null when idle. Used by:
+* - LinkStatusProvider to show per-link pending spinners
+* - useNavigationPending to return a global pending boolean
 *
-* During SSR, no NavigationProvider is mounted. Hooks fall back to
-* the ALS-backed getSsrData() for per-request isolation.
+* The pending URL is set as an URGENT update (shows immediately) and
+* cleared inside startTransition (commits atomically with the new tree).
+* This ensures pending state appears instantly on navigation start and
+* disappears in the same React commit as the new params/tree.
 *
-* IMPORTANT: createContext and useContext are NOT available in the RSC
-* environment (React Server Components use a stripped-down React).
-* The context is lazily initialized on first access, and all functions
-* that depend on these APIs are safe to call from any environment —
-* they return null or no-op when the APIs aren't available.
+* Separate from NavigationContext (which holds params + pathname) because
+* the pending URL is managed as React state in TransitionRoot, while
+* params/pathname are set via module-level state read by renderRoot.
+* Both contexts commit together in the same transition.
 *
 * See design/19-client-navigation.md §"NavigationContext"
 */
-/**
-* The context is created lazily to avoid calling createContext at module
-* level. In the RSC environment, React.createContext doesn't exist —
-* calling it at import time would crash the server.
-*/
-var _context;
-function getOrCreateContext() {
-	if (_context !== void 0) return _context;
-	if (typeof React.createContext === "function") _context = React.createContext(null);
-	return _context;
+var _context$1;
+function getOrCreateContext$1() {
+	if (_context$1 !== void 0) return _context$1;
+	if (typeof React.createContext === "function") _context$1 = React.createContext(null);
+	return _context$1;
 }
 /**
-* Read the navigation context. Returns null during SSR (no provider)
-* or in the RSC environment (no context available).
-* Internal — used by useParams() and usePathname().
+* Read the pending navigation URL from context.
+* Returns null during SSR (no provider) or in the RSC environment.
+* Internal — used by LinkStatusProvider and useNavigationPending.
 */
-function useNavigationContext() {
-	const ctx = getOrCreateContext();
+function usePendingNavigationUrl() {
+	const ctx = getOrCreateContext$1();
 	if (!ctx) return null;
 	if (typeof React.useContext !== "function") return null;
 	return React.useContext(ctx);
 }
-/**
-* Wraps children with NavigationContext.Provider.
-*
-* Used in browser-entry.ts renderRoot to wrap the RSC payload element
-* so that navigation state updates atomically with the tree render.
-*/
-function NavigationProvider({ value, children }) {
-	const ctx = getOrCreateContext();
-	if (!ctx) return children;
-	return createElement(ctx.Provider, { value }, children);
-}
-/**
-* Module-level navigation state. Updated by the router before calling
-* renderRoot(). The renderRoot callback reads this to create the
-* NavigationProvider with the correct values.
-*
-* This is NOT used by hooks directly — hooks read from React context.
-* This exists only as a communication channel between the router
-* (which knows the new nav state) and renderRoot (which wraps the element).
-*/
-var _currentNavState = {
-	params: {},
-	pathname: "/",
-	pendingUrl: null
-};
-function setNavigationState(state) {
-	_currentNavState = state;
-}
-function getNavigationState() {
-	return _currentNavState;
-}
 //#endregion
 //#region src/client/link-status-provider.tsx
 var NOT_PENDING = { pending: false };
 var IS_PENDING = { pending: true };
 /**
-* Client component that reads the pending URL from NavigationContext and
-* provides a scoped LinkStatusContext to children. Renders no extra DOM —
+* Client component that reads the pending URL from PendingNavigationContext
+* and provides a scoped LinkStatusContext to children. Renders no extra DOM —
 * just a context provider around children.
-*
-* Because pendingUrl lives in NavigationContext alongside params and pathname,
-* all three update in the same React commit via renderRoot(). This eliminates
-* the two-commit timing gap that existed when pendingUrl was read via
-* useSyncExternalStore (external module-level state) while params came from
-* NavigationContext (React context).
 */
 function LinkStatusProvider({ href, children }) {
-	const status = useNavigationContext()?.pendingUrl === href ? IS_PENDING : NOT_PENDING;
+	const status = usePendingNavigationUrl() === href ? IS_PENDING : NOT_PENDING;
 	return /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
 		value: status,
 		children
@@ -407,6 +358,87 @@ var HistoryStack = class {
 	}
 };
 //#endregion
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current route params and pathname, updated atomically
+* with the RSC tree on each navigation. This replaces the previous
+* useSyncExternalStore approach for useParams() and usePathname(),
+* which suffered from a timing gap: the new tree could commit before
+* the external store re-renders fired, causing a frame where both
+* old and new active states were visible simultaneously.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (useParams, usePathname) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*/
+var _context;
+function getOrCreateContext() {
+	if (_context !== void 0) return _context;
+	if (typeof React.createContext === "function") _context = React.createContext(null);
+	return _context;
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by useParams() and usePathname().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Module-level navigation state. Updated by the router before calling
+* renderRoot(). The renderRoot callback reads this to create the
+* NavigationProvider with the correct values.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+* This exists only as a communication channel between the router
+* (which knows the new nav state) and renderRoot (which wraps the element).
+*/
+var _currentNavState = {
+	params: {},
+	pathname: "/"
+};
+function setNavigationState(state) {
+	_currentNavState = state;
+}
+function getNavigationState() {
+	return _currentNavState;
+}
+//#endregion
 //#region src/client/use-params.ts
 /**
 * Set the current route params in the module-level store.
@@ -586,21 +618,12 @@ function createRouter(deps) {
 	let pending = false;
 	let pendingUrl = null;
 	const pendingListeners = /* @__PURE__ */ new Set();
-	/** Last rendered payload — used to re-render at navigation start with pendingUrl set. */
-	let lastRenderedPayload = null;
 	function setPending(value, url) {
 		const newPendingUrl = value && url ? url : null;
 		if (pending === value && pendingUrl === newPendingUrl) return;
 		pending = value;
 		pendingUrl = newPendingUrl;
 		for (const listener of pendingListeners) listener(value);
-		if (value && lastRenderedPayload !== null) {
-			setNavigationState({
-				...getNavigationState(),
-				pendingUrl: newPendingUrl
-			});
-			renderPayload(lastRenderedPayload);
-		}
 	}
 	/** Update the segment cache from server-provided segment metadata. */
 	function updateSegmentCache(segmentInfo) {
@@ -610,31 +633,44 @@ function createRouter(deps) {
 	}
 	/** Render a decoded RSC payload into the DOM if a renderer is available. */
 	function renderPayload(payload) {
-		lastRenderedPayload = payload;
 		if (deps.renderRoot) deps.renderRoot(payload);
 	}
 	/**
-	* Update navigation state (params + pathname + pendingUrl) for the next render.
+	* 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.
-	*
-	* pendingUrl is included so that LinkStatusProvider (which reads from
-	* NavigationContext) sees the pending state change in the same React
-	* commit as params/pathname — preventing the gap where the spinner
-	* disappears before the active state updates.
 	*/
-	function updateNavigationState(params, url, navPendingUrl = null) {
+	function updateNavigationState(params, url) {
 		const resolvedParams = params ?? {};
 		setCurrentParams(resolvedParams);
 		setNavigationState({
 			params: resolvedParams,
-			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/",
-			pendingUrl: navPendingUrl
+			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
 		});
 	}
+	/**
+	* Render a payload via navigateTransition (production) or renderRoot (tests).
+	* The perform callback should fetch data, update state, and return the payload.
+	* In production, the entire callback runs inside a React transition with
+	* useOptimistic for the pending URL. In tests, the payload is rendered directly.
+	*/
+	async function renderViaTransition(pendingUrl, perform) {
+		if (deps.navigateTransition) {
+			let headElements = null;
+			await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
+				const result = await perform();
+				headElements = result.headElements;
+				return wrapPayload(result.payload);
+			});
+			return headElements;
+		}
+		const result = await perform();
+		renderPayload(result.payload);
+		return result.headElements;
+	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
 	function applyHead(elements) {
 		if (elements && deps.applyHead) deps.applyHead(elements);
@@ -644,6 +680,40 @@ function createRouter(deps) {
 		if (deps.afterPaint) deps.afterPaint(callback);
 		else callback();
 	}
+	/**
+	* Core navigation logic shared between the transition and fallback paths.
+	* Fetches the RSC payload, updates all state, and returns the result.
+	*/
+	async function performNavigationFetch(url, options) {
+		const prefetched = prefetchCache.consume(url);
+		let result = prefetched ? {
+			payload: prefetched.payload,
+			headElements: prefetched.headElements,
+			segmentInfo: prefetched.segmentInfo ?? null,
+			params: prefetched.params ?? null
+		} : void 0;
+		if (result === void 0) {
+			const stateTree = segmentCache.serializeStateTree();
+			const rawCurrentUrl = deps.getCurrentUrl();
+			result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
+		}
+		if (options.replace) deps.replaceState({
+			timber: true,
+			scrollY: 0
+		}, "", url);
+		else deps.pushState({
+			timber: true,
+			scrollY: 0
+		}, "", url);
+		historyStack.push(url, {
+			payload: result.payload,
+			headElements: result.headElements,
+			params: result.params
+		});
+		updateSegmentCache(result.segmentInfo);
+		updateNavigationState(result.params, url);
+		return result;
+	}
 	async function navigate(url, options = {}) {
 		const scroll = options.scroll !== false;
 		const replace = options.replace === true;
@@ -654,29 +724,7 @@ function createRouter(deps) {
 		}, "", deps.getCurrentUrl());
 		setPending(true, url);
 		try {
-			let result = prefetchCache.consume(url);
-			if (result === void 0) {
-				const stateTree = segmentCache.serializeStateTree();
-				const rawCurrentUrl = deps.getCurrentUrl();
-				result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
-			}
-			if (replace) deps.replaceState({
-				timber: true,
-				scrollY: 0
-			}, "", url);
-			else deps.pushState({
-				timber: true,
-				scrollY: 0
-			}, "", url);
-			historyStack.push(url, {
-				payload: result.payload,
-				headElements: result.headElements,
-				params: result.params
-			});
-			updateSegmentCache(result.segmentInfo);
-			updateNavigationState(result.params, url);
-			renderPayload(result.payload);
-			applyHead(result.headElements);
+			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, { replace })));
 			window.dispatchEvent(new Event("timber:navigation-end"));
 			afterPaint(() => {
 				if (scroll) deps.scrollTo(0, 0);
@@ -699,16 +747,17 @@ function createRouter(deps) {
 		const currentUrl = deps.getCurrentUrl();
 		setPending(true, currentUrl);
 		try {
-			const result = await fetchRscPayload(currentUrl, deps);
-			historyStack.push(currentUrl, {
-				payload: result.payload,
-				headElements: result.headElements,
-				params: result.params
-			});
-			updateSegmentCache(result.segmentInfo);
-			updateNavigationState(result.params, currentUrl);
-			renderPayload(result.payload);
-			applyHead(result.headElements);
+			applyHead(await renderViaTransition(currentUrl, async () => {
+				const result = await fetchRscPayload(currentUrl, deps);
+				historyStack.push(currentUrl, {
+					payload: result.payload,
+					headElements: result.headElements,
+					params: result.params
+				});
+				updateSegmentCache(result.segmentInfo);
+				updateNavigationState(result.params, currentUrl);
+				return result;
+			}));
 		} finally {
 			setPending(false);
 		}
@@ -726,16 +775,17 @@ function createRouter(deps) {
 		} else {
 			setPending(true, url);
 			try {
-				const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
-				updateSegmentCache(result.segmentInfo);
-				updateNavigationState(result.params, url);
-				historyStack.push(url, {
-					payload: result.payload,
-					headElements: result.headElements,
-					params: result.params
-				});
-				renderPayload(result.payload);
-				applyHead(result.headElements);
+				applyHead(await renderViaTransition(url, async () => {
+					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
+					updateSegmentCache(result.segmentInfo);
+					updateNavigationState(result.params, url);
+					historyStack.push(url, {
+						payload: result.payload,
+						headElements: result.headElements,
+						params: result.params
+					});
+					return result;
+				}));
 				afterPaint(() => {
 					deps.scrollTo(0, scrollY);
 					window.dispatchEvent(new Event("timber:scroll-restored"));
@@ -809,9 +859,7 @@ function createRouter(deps) {
 * ```
 */
 function useNavigationPending() {
-	const navState = useNavigationContext();
-	if (!navState) return false;
-	return navState.pendingUrl !== null;
+	return usePendingNavigationUrl() !== null;
 }
 //#endregion
 //#region src/client/router-ref.ts