@timber-js/app 0.1.29 → 0.1.30

package/dist/client/index.js

@@ -67,53 +67,104 @@ function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
 //#endregion
-//#region src/client/router-ref.ts
+//#region src/client/navigation-context.ts
 /**
-* Set the global router instance. Called once during bootstrap.
+* 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"
 */
-function setGlobalRouter(router) {
-	_setGlobalRouter(router);
+/**
+* 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;
 }
 /**
-* Get the global router instance. Throws if called before bootstrap.
-* Used by client-side hooks (useNavigationPending, etc.)
+* 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 getRouter() {
-	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
-	return globalRouter;
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
 }
 /**
-* Get the global router instance or null if not yet initialized.
-* Used by useRouter() methods to avoid silent failures — callers
-* can log a meaningful warning instead of silently no-oping.
+* 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 getRouterOrNull() {
-	return globalRouter;
+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 subscribes to the router's pending URL and provides
-* a scoped LinkStatusContext to children. Renders no extra DOM — just a
-* context provider around children.
+* Client component that reads the pending URL from NavigationContext 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 = useSyncExternalStore((callback) => {
-		try {
-			return getRouter().onPendingChange(callback);
-		} catch {
-			return () => {};
-		}
-	}, () => {
-		try {
-			if (getRouter().getPendingUrl() === href) return IS_PENDING;
-			return NOT_PENDING;
-		} catch {
-			return NOT_PENDING;
-		}
-	}, () => NOT_PENDING);
+	const status = useNavigationContext()?.pendingUrl === href ? IS_PENDING : NOT_PENDING;
 	return /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
 		value: status,
 		children
@@ -356,87 +407,6 @@ 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.
@@ -616,12 +586,21 @@ 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) {
@@ -631,22 +610,29 @@ 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) for the next render.
+	* Update navigation state (params + pathname + pendingUrl) 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) {
+	function updateNavigationState(params, url, navPendingUrl = null) {
 		const resolvedParams = params ?? {};
 		setCurrentParams(resolvedParams);
 		setNavigationState({
 			params: resolvedParams,
-			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
+			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/",
+			pendingUrl: navPendingUrl
 		});
 	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
@@ -823,15 +809,33 @@ function createRouter(deps) {
 * ```
 */
 function useNavigationPending() {
-	return useSyncExternalStore((callback) => {
-		return getRouter().onPendingChange(callback);
-	}, () => {
-		try {
-			return getRouter().isPending();
-		} catch {
-			return false;
-		}
-	}, () => false);
+	const navState = useNavigationContext();
+	if (!navState) return false;
+	return navState.pendingUrl !== null;
+}
+//#endregion
+//#region src/client/router-ref.ts
+/**
+* Set the global router instance. Called once during bootstrap.
+*/
+function setGlobalRouter(router) {
+	_setGlobalRouter(router);
+}
+/**
+* Get the global router instance. Throws if called before bootstrap.
+* Used by client-side hooks (useNavigationPending, etc.)
+*/
+function getRouter() {
+	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
+	return globalRouter;
+}
+/**
+* Get the global router instance or null if not yet initialized.
+* Used by useRouter() methods to avoid silent failures — callers
+* can log a meaningful warning instead of silently no-oping.
+*/
+function getRouterOrNull() {
+	return globalRouter;
 }
 //#endregion
 //#region src/client/use-router.ts