@timber-js/app 0.1.23 → 0.1.25

package/dist/client/index.js

@@ -1,11 +1,10 @@
 "use client";
-import { a as _setCurrentParams, c as cachedSearchParams, d as paramsListeners, i as _setCachedSearch, l as currentParams, n as getSsrData, o as _setGlobalRouter, r as setSsrData, s as cachedSearch, t as clearSsrData, u as globalRouter } from "../_chunks/ssr-data-B2yikEEB.js";
+import { a as _setCurrentParams, c as cachedSearchParams, i as _setCachedSearch, l as currentParams, n as getSsrData, o as _setGlobalRouter, r as setSsrData, s as cachedSearch, t as clearSsrData, u as globalRouter } from "../_chunks/ssr-data-DLnbYpj1.js";
 import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-DAhgj8Gx.js";
-import { t as useCookie } from "../_chunks/use-cookie-D5aS4slY.js";
+import { t as useCookie } from "../_chunks/use-cookie-dDbpCTx-.js";
 import { TimberErrorBoundary } from "./error-boundary.js";
-import { createContext, createElement, startTransition, useActionState as useActionState$1, useContext, useEffect, useMemo, useRef, useSyncExternalStore, useTransition } from "react";
+import React, { createContext, createElement, useActionState as useActionState$1, useContext, useEffect, useMemo, useRef, useSyncExternalStore, useTransition } from "react";
 import { jsxDEV } from "react/jsx-dev-runtime";
-import { flushSync } from "react-dom";
 //#region src/client/link-navigate-interceptor.tsx
 var _jsxFileName$2 = "/Users/dsaewitz/y/timber-js-fresh/packages/timber-app/src/client/link-navigate-interceptor.tsx";
 /** Symbol used to store the onNavigate callback on anchor elements. */
@@ -380,94 +379,112 @@ var HistoryStack = class {
 	}
 };
 //#endregion
-//#region src/client/use-params.ts
+//#region src/client/navigation-context.ts
 /**
-* useParams() — client-side hook for accessing route params.
-*
-* Returns the dynamic route parameters for the current URL.
-* When called with a route pattern argument, TypeScript narrows
-* the return type to the exact params shape for that route.
-*
-* Two layers of type narrowing work together:
-* 1. The generic overload here uses the Routes interface directly —
-*    `useParams<R>()` returns `Routes[R]['params']`.
-* 2. Build-time codegen generates per-route string-literal overloads
-*    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).
-*
-* When the Routes interface is empty (no codegen yet), the generic
-* overload has `keyof Routes = never`, so only the fallback matches.
-*
-* During SSR, params are read from the ALS-backed SSR data context
-* (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().
-*
-* All mutable state is delegated to client/state.ts for singleton guarantees.
-* See design/18-build-system.md §"Singleton State Registry"
-*
-* Design doc: design/09-typescript.md §"Typed Routes"
+* 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"
 */
 /**
-* Subscribe to params changes. Called by useSyncExternalStore.
-* Exported for testing — not intended for direct use by app code.
+* 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.
 */
-function subscribe$2(callback) {
-	paramsListeners.add(callback);
-	return () => paramsListeners.delete(callback);
+var _context;
+function getOrCreateContext() {
+	if (_context !== void 0) return _context;
+	if (typeof React.createContext === "function") _context = React.createContext(null);
+	return _context;
 }
 /**
-* Get the current params snapshot (client).
-* Exported for testing — not intended for direct use by app code.
+* 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 getSnapshot() {
-	return currentParams;
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
 }
 /**
-* 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).
+* 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 getServerSnapshot() {
-	return getSsrData()?.params ?? currentParams;
+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 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).
 */
 function setCurrentParams(params) {
 	_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.
-*/
-function notifyParamsListeners() {
-	for (const listener of paramsListeners) listener();
-}
 function useParams(_route) {
 	try {
-		return useSyncExternalStore(subscribe$2, getSnapshot, getServerSnapshot);
-	} catch {
-		return getServerSnapshot();
-	}
+		const navContext = useNavigationContext();
+		if (navContext !== null) return navContext.params;
+	} catch {}
+	return getSsrData()?.params ?? currentParams;
 }
 //#endregion
 //#region src/client/router.ts
@@ -639,9 +656,21 @@ function createRouter(deps) {
 	function renderPayload(payload) {
 		if (deps.renderRoot) deps.renderRoot(payload);
 	}
-	/** Update useParams() with route params from the server response. */
-	function updateParams(params) {
-		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, url) {
+		const resolvedParams = params ?? {};
+		setCurrentParams(resolvedParams);
+		setNavigationState({
+			params: resolvedParams,
+			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
+		});
 	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
 	function applyHead(elements) {
@@ -682,11 +711,8 @@ function createRouter(deps) {
 				params: result.params
 			});
 			updateSegmentCache(result.segmentInfo);
-			updateParams(result.params);
-			flushSync(() => {
-				renderPayload(result.payload);
-				notifyParamsListeners();
-			});
+			updateNavigationState(result.params, url);
+			renderPayload(result.payload);
 			applyHead(result.headElements);
 			window.dispatchEvent(new Event("timber:navigation-end"));
 			afterPaint(() => {
@@ -717,11 +743,8 @@ function createRouter(deps) {
 				params: result.params
 			});
 			updateSegmentCache(result.segmentInfo);
-			updateParams(result.params);
-			flushSync(() => {
-				renderPayload(result.payload);
-				notifyParamsListeners();
-			});
+			updateNavigationState(result.params, currentUrl);
+			renderPayload(result.payload);
 			applyHead(result.headElements);
 		} finally {
 			setPending(false);
@@ -730,11 +753,8 @@ function createRouter(deps) {
 	async function handlePopState(url, scrollY = 0) {
 		const entry = historyStack.get(url);
 		if (entry && entry.payload !== null) {
-			updateParams(entry.params);
-			flushSync(() => {
-				renderPayload(entry.payload);
-				notifyParamsListeners();
-			});
+			updateNavigationState(entry.params, url);
+			renderPayload(entry.payload);
 			applyHead(entry.headElements);
 			afterPaint(() => {
 				deps.scrollTo(0, scrollY);
@@ -745,16 +765,13 @@ function createRouter(deps) {
 			try {
 				const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
 				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);
@@ -850,6 +867,20 @@ function useNavigationPending() {
 *
 * 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
 */
 /**
 * Get a router instance for programmatic navigation.
@@ -876,9 +907,7 @@ function useRouter() {
 				if (process.env.NODE_ENV === "development") console.error("[timber] useRouter().push() called but router is not initialized. This is a bug — please report it.");
 				return;
 			}
-			startTransition(async () => {
-				await router.navigate(href, { scroll: options?.scroll });
-			});
+			router.navigate(href, { scroll: options?.scroll });
 		},
 		replace(href, options) {
 			const router = getRouterOrNull();
@@ -886,11 +915,9 @@ function useRouter() {
 				if (process.env.NODE_ENV === "development") console.error("[timber] useRouter().replace() called but router is not initialized.");
 				return;
 			}
-			startTransition(async () => {
-				await router.navigate(href, {
-					scroll: options?.scroll,
-					replace: true
-				});
+			router.navigate(href, {
+				scroll: options?.scroll,
+				replace: true
 			});
 		},
 		refresh() {
@@ -899,9 +926,7 @@ function useRouter() {
 				if (process.env.NODE_ENV === "development") console.error("[timber] useRouter().refresh() called but router is not initialized.");
 				return;
 			}
-			startTransition(async () => {
-				await router.refresh();
-			});
+			router.refresh();
 		},
 		back() {
 			if (typeof window !== "undefined") window.history.back();
@@ -924,31 +949,34 @@ function useRouter() {
 * 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`.
 */
-function getPathname() {
-	if (typeof window !== "undefined") return window.location.pathname;
-	return getSsrData()?.pathname ?? "/";
-}
-function getServerPathname() {
-	return getSsrData()?.pathname ?? "/";
-}
-function subscribe$1(callback) {
-	window.addEventListener("popstate", callback);
-	return () => window.removeEventListener("popstate", callback);
-}
 /**
 * 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).
 */
 function usePathname() {
-	return useSyncExternalStore(subscribe$1, getPathname, getServerPathname);
+	try {
+		const navContext = useNavigationContext();
+		if (navContext !== null) return navContext.pathname;
+	} catch {}
+	const ssrData = getSsrData();
+	if (ssrData) return ssrData.pathname ?? "/";
+	if (typeof window !== "undefined") return window.location.pathname;
+	return "/";
 }
 //#endregion
 //#region src/client/use-search-params.ts
@@ -1247,6 +1275,6 @@ function useFormErrors(result) {
 	};
 }
 //#endregion
-export { HistoryStack, Link, LinkStatusContext, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getRouter, getSsrData, interpolateParams, resolveHref, setCurrentParams, setGlobalRouter, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, useParams, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
+export { HistoryStack, Link, LinkStatusContext, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getNavigationState, getRouter, getSsrData, interpolateParams, resolveHref, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, useParams, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
 
 //# sourceMappingURL=index.js.map