@timber-js/app 0.2.0-alpha.123 → 0.2.0-alpha.125

package/dist/client/internal.js

@@ -1,11 +1,11 @@
 import { t as bindUseQueryStates } from "../_chunks/use-query-states-C9G6LP0F.js";
 import { c as cachedSearchParams, i as _setCachedSearch, n as getSsrData, r as setSsrData, s as cachedSearch, t as clearSsrData } from "../_chunks/ssr-data-DVX8S7vj.js";
-import { a as setNavigationState, i as getNavigationState, r as NavigationProvider, t as setCurrentParams } from "../_chunks/use-segment-params-Du7u25cK.js";
+import { a as setNavigationState, i as getNavigationState, o as useNavigationContext, r as NavigationProvider, t as setCurrentParams } from "../_chunks/use-segment-params-ByGqwUuO.js";
 import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-B2-2kIIC.js";
 import { TimberErrorBoundary } from "./error-boundary.js";
 import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-Bg0pFbLT.js";
-import { t as setHardNavigating } from "../_chunks/navigation-root-Ds_hDtRW.js";
-import { cloneElement, isValidElement, useSyncExternalStore } from "react";
+import { t as setHardNavigating } from "../_chunks/navigation-root-CeNTCxzS.js";
+import { r as triggerStaleReload, t as isStaleClientReference } from "../_chunks/stale-reload-CCqb62Z3.js";
 //#region src/client/segment-cache.ts
 /**
 * Maintains the client-side segment tree representing currently mounted
@@ -64,14 +64,15 @@ function buildSegmentTree(segments) {
 	let root;
 	let parent;
 	for (const info of layouts) {
+		const id = info.segmentId ?? info.path;
 		const node = {
-			segment: info.path,
+			segment: id,
 			payload: null,
 			isAsync: info.isAsync,
 			children: /* @__PURE__ */ new Map()
 		};
 		if (!root) root = node;
-		if (parent) parent.children.set(info.path, node);
+		if (parent) parent.children.set(id, node);
 		parent = node;
 	}
 	return root;
@@ -157,217 +158,6 @@ var HistoryStack = class {
 	}
 };
 //#endregion
-//#region src/client/segment-merger.ts
-/**
-* Segment Merger — client-side tree merging for partial RSC payloads.
-*
-* When the server skips rendering sync layouts (because the client already
-* has them cached), the RSC payload is missing outer segment wrappers.
-* This module reconstructs the full element tree by splicing the partial
-* payload into cached segment subtrees.
-*
-* The approach:
-* 1. After each full RSC payload render, walk the decoded element tree
-*    and cache each segment's subtree (identified by SegmentProvider boundaries)
-* 2. When a partial payload arrives, wrap it with cached segment elements
-*    using React.cloneElement to preserve component identity
-*
-* React.cloneElement preserves the element's `type` — React sees the same
-* component at the same tree position and reconciles (preserving state)
-* rather than remounting. This is how layout state survives navigations.
-*
-* Design docs: 19-client-navigation.md §"Navigation Reconciliation"
-* Security: access.ts runs on the server regardless of skipping — this
-*           is a performance optimization only. See 13-security.md.
-*/
-/**
-* Cache of React element subtrees per segment path.
-* Updated after each navigation with the full decoded RSC element tree.
-*/
-var SegmentElementCache = class {
-	entries = /* @__PURE__ */ new Map();
-	get(segmentPath) {
-		return this.entries.get(segmentPath);
-	}
-	set(segmentPath, entry) {
-		this.entries.set(segmentPath, entry);
-	}
-	has(segmentPath) {
-		return this.entries.has(segmentPath);
-	}
-	clear() {
-		this.entries.clear();
-	}
-	get size() {
-		return this.entries.size;
-	}
-	/**
-	* Get the set of segment paths that are safe for the server to skip.
-	* Only segments with an inner SegmentProvider (hasMergeableChild) are
-	* included — the merger can only replace inner SegmentProviders, not
-	* pages embedded in layout output. Used to filter the state tree.
-	*
-	* Returns an empty set if the element cache is empty (no elements
-	* cached yet). This is the safe default — an empty set means no
-	* segments pass the filter, so the state tree is empty and the server
-	* does a full render. The element cache is populated lazily after the
-	* first SPA navigation (RSC-decoded elements from hydration are
-	* thenables that can't be walked until React resolves them).
-	*/
-	getMergeablePaths() {
-		const paths = /* @__PURE__ */ new Set();
-		for (const [, entry] of this.entries) if (entry.hasMergeableChild) paths.add(entry.segmentPath);
-		return paths;
-	}
-};
-/**
-* Check if a React element is a SegmentProvider by looking for the
-* `segments` prop (an array of path segments). This is the only
-* component that receives this prop shape.
-*/
-function isSegmentProvider(element) {
-	if (!isValidElement(element)) return false;
-	const props = element.props;
-	return Array.isArray(props.segments);
-}
-/**
-* Extract the segment path from a SegmentProvider element.
-*
-* Uses the `segmentId` prop if available (set by the server for route groups
-* to distinguish siblings that share the same urlPath). Falls back to
-* reconstructing from the `segments` array prop.
-*/
-function getSegmentPath(element) {
-	const props = element.props;
-	if (props.segmentId) return props.segmentId;
-	const filtered = props.segments.filter(Boolean);
-	return filtered.length === 0 ? "/" : "/" + filtered.join("/");
-}
-/**
-* Walk a React element tree and extract all SegmentProvider boundaries.
-* Returns an ordered list of segment entries from outermost to innermost.
-*
-* This only finds SegmentProviders along the main children path — it does
-* not descend into parallel routes/slots (those are separate subtrees).
-*/
-function extractSegments(element) {
-	const segments = [];
-	walkForSegments(element, segments);
-	for (let i = 0; i < segments.length; i++) segments[i].hasMergeableChild = i < segments.length - 1;
-	return segments;
-}
-function walkForSegments(node, out) {
-	if (!isValidElement(node)) return;
-	const el = node;
-	const props = el.props;
-	if (isSegmentProvider(node)) {
-		out.push({
-			segmentPath: getSegmentPath(el),
-			element: el,
-			hasMergeableChild: false
-		});
-		walkChildren(props.children, out);
-		return;
-	}
-	walkChildren(props.children, out);
-}
-function walkChildren(children, out) {
-	if (children == null) return;
-	if (Array.isArray(children)) for (const child of children) walkForSegments(child, out);
-	else walkForSegments(children, out);
-}
-/**
-* Cache all segment subtrees from a fully-rendered RSC element tree.
-* Call this after every full RSC payload render (navigate, refresh, hydration).
-*/
-function cacheSegmentElements(element, cache) {
-	const segments = extractSegments(element);
-	for (const entry of segments) cache.set(entry.segmentPath, entry);
-}
-function findSegmentProviderPath(node, targetPath) {
-	const children = node.props.children;
-	if (children == null) return null;
-	if (Array.isArray(children)) for (let i = 0; i < children.length; i++) {
-		const child = children[i];
-		if (!isValidElement(child)) continue;
-		if (isSegmentProvider(child)) {
-			if (!targetPath || getSegmentPath(child) === targetPath) return [{
-				element: node,
-				childIndex: i
-			}];
-		}
-		const deeper = findSegmentProviderPath(child, targetPath);
-		if (deeper) return [{
-			element: node,
-			childIndex: i
-		}, ...deeper];
-	}
-	else if (isValidElement(children)) {
-		if (isSegmentProvider(children)) {
-			if (!targetPath || getSegmentPath(children) === targetPath) return [{
-				element: node,
-				childIndex: -1
-			}];
-		}
-		const deeper = findSegmentProviderPath(children, targetPath);
-		if (deeper) return [{
-			element: node,
-			childIndex: -1
-		}, ...deeper];
-	}
-	return null;
-}
-/**
-* Replace a nested SegmentProvider within a cached element tree with
-* new content. Uses cloneElement along the path to produce a new tree
-* with preserved component identity at every level except the replaced node.
-*
-* @param cachedElement The cached SegmentProvider element for this segment
-* @param newInnerContent The new React element to splice in at the inner segment position
-* @param innerSegmentPath The path of the inner segment to replace (optional — replaces first found)
-* @returns New element tree with the inner segment replaced
-*/
-function replaceInnerSegment(cachedElement, newInnerContent, innerSegmentPath) {
-	const path = findSegmentProviderPath(cachedElement, innerSegmentPath);
-	if (!path || path.length === 0) return cachedElement;
-	let replacement = newInnerContent;
-	for (let i = path.length - 1; i >= 0; i--) {
-		const { element, childIndex } = path[i];
-		if (childIndex === -1) replacement = cloneElement(element, {}, replacement);
-		else {
-			const newChildren = [...element.props.children];
-			newChildren[childIndex] = replacement;
-			replacement = cloneElement(element, {}, ...newChildren);
-		}
-	}
-	return replacement;
-}
-/**
-* Merge a partial RSC payload with cached segment elements.
-*
-* When the server skips segments, the partial payload starts from the
-* first non-skipped segment. This function wraps it with cached elements
-* for the skipped segments, producing a full tree that React can
-* reconcile with the mounted tree (preserving layout state).
-*
-* @param partialPayload The RSC payload element (may be partial)
-* @param skippedSegments Ordered list of segment paths that were skipped (outermost first)
-* @param cache The segment element cache
-* @returns The merged full element tree, or the partial payload if merging isn't possible
-*/
-function mergeSegmentTree(partialPayload, skippedSegments, cache) {
-	if (!isValidElement(partialPayload)) return partialPayload;
-	if (skippedSegments.length === 0) return partialPayload;
-	let result = partialPayload;
-	for (let i = skippedSegments.length - 1; i >= 0; i--) {
-		const segmentPath = skippedSegments[i];
-		const cached = cache.get(segmentPath);
-		if (!cached) return partialPayload;
-		result = replaceInnerSegment(cached.element, result);
-	}
-	return result;
-}
-//#endregion
 //#region src/client/rsc-fetch.ts
 var RSC_CONTENT_TYPE = "text/x-component";
 /**
@@ -526,6 +316,46 @@ var ServerErrorResponse = class extends Error {
 	}
 };
 /**
+* Wrap a response body stream to track when it's fully consumed.
+* Returns a new body that passes all chunks through unchanged, plus
+* a `done` promise that resolves when the last chunk is read (or
+* rejects if the stream errors).
+*
+* Used to keep React transitions open for the full RSC stream
+* duration — createFromFetch's thenable resolves on shell arrival,
+* but we need stream completion for useOptimistic pending state.
+*/
+function trackStreamCompletion(body) {
+	let resolveDone;
+	let rejectDone;
+	const done = new Promise((res, rej) => {
+		resolveDone = res;
+		rejectDone = rej;
+	});
+	const reader = body.getReader();
+	return {
+		body: new ReadableStream({
+			async pull(controller) {
+				try {
+					const result = await reader.read();
+					if (result.done) {
+						controller.close();
+						resolveDone();
+					} else controller.enqueue(result.value);
+				} catch (error) {
+					controller.error(error);
+					rejectDone(error);
+				}
+			},
+			cancel(reason) {
+				reader.cancel(reason);
+				resolveDone();
+			}
+		}),
+		done
+	};
+}
+/**
 * Fetch an RSC payload from the server. If a decodeRsc function is provided,
 * the response is decoded into a React element tree via createFromFetch.
 * Otherwise, the raw response text is returned (test mode).
@@ -546,6 +376,7 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 		let segmentInfo = null;
 		let params = null;
 		let skippedSegments = null;
+		let streamDone = Promise.resolve();
 		const wrappedPromise = fetchPromise.then((response) => {
 			if (checkReloadSignal(response)) throw new VersionSkewError();
 			const redirectLocation = response.headers.get("X-Timber-Redirect") || (response.status >= 300 && response.status < 400 ? response.headers.get("Location") : null);
@@ -555,15 +386,26 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 			segmentInfo = extractSegmentInfo(response);
 			params = extractParams(response);
 			skippedSegments = extractSkippedSegments(response);
+			if (response.body) {
+				const tracked = trackStreamCompletion(response.body);
+				streamDone = tracked.done;
+				streamDone.catch(() => {});
+				return new Response(tracked.body, {
+					headers: response.headers,
+					status: response.status
+				});
+			}
 			return response;
 		});
 		await wrappedPromise;
 		const payload = deps.decodeRsc(wrappedPromise);
-		const decodePromise = Promise.resolve(payload).then(() => void 0);
-		decodePromise.catch(() => {});
+		const payloadError = new Promise((_, reject) => {
+			Promise.resolve(payload).then(() => {}, reject);
+		});
+		payloadError.catch(() => {});
 		return {
 			payload,
-			decodePromise,
+			decodePromise: Promise.race([streamDone, payloadError]),
 			headElements,
 			segmentInfo,
 			params,
@@ -603,9 +445,7 @@ function createRouter(deps) {
 	const segmentCache = new SegmentCache();
 	const prefetchCache = new PrefetchCache();
 	const historyStack = new HistoryStack();
-	const segmentElementCache = new SegmentElementCache();
 	let routerPhase = { phase: "idle" };
-	let navigationId = 0;
 	const pendingListeners = /* @__PURE__ */ new Set();
 	let currentNavAbort = null;
 	/**
@@ -640,31 +480,24 @@ function createRouter(deps) {
 	function renderPayload(payload, navState) {
 		if (deps.renderRoot) deps.renderRoot(payload, navState);
 	}
-	/**
-	* Merge a partial RSC payload with cached segment elements if segments
-	* were skipped. Returns the merged payload ready for rendering.
-	*
-	* Segment element caching is deferred to after paint by the caller
-	* so it doesn't block the render path.
-	*/
-	async function mergePayload(payload, skippedSegments) {
-		if (skippedSegments && skippedSegments.length > 0) return mergeSegmentTree(payload != null && typeof payload === "object" && "then" in payload ? await payload : payload, skippedSegments, segmentElementCache);
-		return payload;
+	function isPartialNavigation(skippedSegments) {
+		return skippedSegments != null && skippedSegments.length > 0;
 	}
 	/**
-	* Schedule segment element caching after paint. Resolves thenable
-	* payloads first since tree walking requires resolved React elements.
-	* Guards against stale writes: if a newer navigation started before
-	* this callback fires, the cache write is skipped.
+	* Build a segment updates map for partial navigation. Identifies the
+	* first non-skipped segment and maps it to the payload content.
 	*/
-	function deferSegmentCaching(payload) {
-		const capturedNavId = navigationId;
-		afterPaint(async () => {
-			if (capturedNavId !== navigationId) return;
-			const resolved = payload != null && typeof payload === "object" && "then" in payload ? await payload : payload;
-			if (capturedNavId !== navigationId) return;
-			cacheSegmentElements(resolved, segmentElementCache);
-		});
+	function buildSegmentUpdates(result) {
+		const skipped = new Set(result.skippedSegments);
+		const segmentInfo = result.segmentInfo;
+		const updates = /* @__PURE__ */ new Map();
+		if (segmentInfo) {
+			for (const info of segmentInfo) if (!skipped.has(info.segmentId ?? info.path)) {
+				updates.set(info.segmentId ?? info.path, result.payload);
+				break;
+			}
+		}
+		return updates;
 	}
 	/**
 	* Update navigation state (params + pathname) for the next render.
@@ -677,9 +510,11 @@ function createRouter(deps) {
 	function updateNavigationState(params, url) {
 		const resolvedParams = params ?? {};
 		setCurrentParams(resolvedParams);
+		const parsed = new URL(url, "http://localhost");
 		const navState = {
 			params: resolvedParams,
-			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
+			pathname: parsed.pathname || "/",
+			search: parsed.search
 		};
 		setNavigationState(navState);
 		return navState;
@@ -687,34 +522,51 @@ function createRouter(deps) {
 	async function renderViaTransition(url, perform) {
 		if (deps.navigateTransition) {
 			let headElements = null;
-			let decodePromise = null;
 			await deps.navigateTransition(url, async (wrapPayload) => {
 				const result = await perform();
 				headElements = result.headElements;
-				decodePromise = result.decodePromise;
-				const merged = await mergePayload(result.payload, result.skippedSegments);
+				if (isPartialNavigation(result.skippedSegments)) {
+					const segmentUpdates = buildSegmentUpdates(result);
+					historyStack.push(url, {
+						payload: null,
+						headElements: result.headElements,
+						params: result.params
+					});
+					return {
+						element: wrapPayload(deps._getCurrentPayload?.() ?? result.payload, result.navState, segmentUpdates),
+						decodePromise: result.decodePromise
+					};
+				}
 				historyStack.push(url, {
-					payload: merged,
+					payload: result.payload,
 					headElements: result.headElements,
 					params: result.params
 				});
-				deferSegmentCaching(merged);
-				return wrapPayload(merged, result.navState);
+				return {
+					element: wrapPayload(result.payload, result.navState),
+					decodePromise: result.decodePromise
+				};
 			});
 			return {
 				headElements,
-				decodePromise
+				decodePromise: null
 			};
 		}
 		const result = await perform();
-		const merged = await mergePayload(result.payload, result.skippedSegments);
-		historyStack.push(url, {
-			payload: merged,
+		if (isPartialNavigation(result.skippedSegments)) historyStack.push(url, {
+			payload: null,
 			headElements: result.headElements,
 			params: result.params
 		});
-		deferSegmentCaching(merged);
-		renderPayload(merged, result.navState);
+		else {
+			const payload = result.payload != null && typeof result.payload === "object" && "then" in result.payload ? await result.payload : result.payload;
+			historyStack.push(url, {
+				payload,
+				headElements: result.headElements,
+				params: result.params
+			});
+			renderPayload(payload, result.navState);
+		}
 		return {
 			headElements: result.headElements,
 			decodePromise: result.decodePromise
@@ -754,7 +606,7 @@ function createRouter(deps) {
 			skippedSegments: prefetched.skippedSegments ?? null
 		} : void 0;
 		if (result === void 0) {
-			const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+			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, options.signal);
 		}
@@ -782,7 +634,6 @@ function createRouter(deps) {
 		const replace = options.replace === true;
 		const externalSignal = options._signal;
 		const skipHistory = options._skipHistory === true;
-		navigationId++;
 		const navAbort = createNavAbort(externalSignal);
 		const currentScrollY = deps.getScrollY();
 		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
@@ -799,19 +650,18 @@ function createRouter(deps) {
 		}
 		setPending(true, url);
 		try {
-			const { headElements, decodePromise } = await renderViaTransition(url, () => performNavigationFetch(url, {
+			const { headElements } = await renderViaTransition(url, () => performNavigationFetch(url, {
 				replace,
 				signal: navAbort.signal,
 				skipHistory: effectiveSkipHistory
 			}));
-			if (decodePromise) await decodePromise;
 			applyHead(headElements);
 			window.dispatchEvent(new Event("timber:navigation-end"));
 			restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 		} catch (error) {
 			if (error instanceof VersionSkewError) {
 				setHardNavigating(true);
-				const { triggerStaleReload } = await import("../_chunks/stale-reload-BN2kcE06.js");
+				const { triggerStaleReload } = await import("../_chunks/stale-reload-CCqb62Z3.js").then((n) => n.n);
 				triggerStaleReload();
 				return new Promise(() => {});
 			}
@@ -826,6 +676,11 @@ function createRouter(deps) {
 				window.location.href = error.url;
 				return new Promise(() => {});
 			}
+			if (isStaleClientReference(error)) {
+				setHardNavigating(true);
+				triggerStaleReload();
+				return new Promise(() => {});
+			}
 			if (isAbortError(error)) return;
 			throw error;
 		} finally {
@@ -836,11 +691,10 @@ function createRouter(deps) {
 	}
 	async function refresh() {
 		const currentUrl = deps.getCurrentUrl();
-		navigationId++;
 		const navAbort = createNavAbort();
 		setPending(true, currentUrl);
 		try {
-			const { headElements, decodePromise } = await renderViaTransition(currentUrl, async () => {
+			const { headElements } = 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);
@@ -849,9 +703,13 @@ function createRouter(deps) {
 					navState
 				};
 			});
-			if (decodePromise) await decodePromise;
 			applyHead(headElements);
 		} catch (error) {
+			if (isStaleClientReference(error)) {
+				setHardNavigating(true);
+				triggerStaleReload();
+				return new Promise(() => {});
+			}
 			if (isAbortError(error)) return;
 			throw error;
 		} finally {
@@ -861,7 +719,6 @@ function createRouter(deps) {
 		}
 	}
 	async function handlePopState(url, scrollY = 0, externalSignal) {
-		navigationId++;
 		const entry = historyStack.get(url);
 		if (entry && entry.payload !== null) {
 			const navState = updateNavigationState(entry.params, url);
@@ -872,8 +729,8 @@ function createRouter(deps) {
 			const navAbort = createNavAbort(externalSignal);
 			setPending(true, url);
 			try {
-				const { headElements, decodePromise } = await renderViaTransition(url, async () => {
-					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()), void 0, navAbort.signal);
+				const { headElements } = 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 {
@@ -881,10 +738,14 @@ function createRouter(deps) {
 						navState
 					};
 				});
-				if (decodePromise) await decodePromise;
 				applyHead(headElements);
 				restoreScrollAfterPaint(scrollY);
 			} catch (error) {
+				if (isStaleClientReference(error)) {
+					setHardNavigating(true);
+					triggerStaleReload();
+					return new Promise(() => {});
+				}
 				if (isAbortError(error)) return;
 				throw error;
 			} finally {
@@ -900,7 +761,8 @@ function createRouter(deps) {
 	function prefetch(url) {
 		if (prefetchCache.get(url) !== void 0) return;
 		if (historyStack.has(url)) return;
-		fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths())).then((result) => {
+		fetchRscPayload(url, deps, segmentCache.serializeStateTree()).then((result) => {
+			result.decodePromise?.catch(() => {});
 			prefetchCache.set(url, result);
 		}, () => {});
 	}
@@ -921,12 +783,10 @@ function createRouter(deps) {
 				payload: element,
 				headElements
 			});
-			deferSegmentCaching(element);
 			renderPayload(element, getNavigationState());
 			applyHead(headElements);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
-		cacheElementTree: (element) => cacheSegmentElements(element, segmentElementCache),
 		segmentCache,
 		prefetchCache,
 		historyStack
@@ -940,9 +800,12 @@ function createRouter(deps) {
 * Returns a read-only URLSearchParams instance reflecting the current
 * URL's query string. Updates when client-side navigation changes the URL.
 *
-* This is a thin wrapper over window.location.search, provided for
-* Next.js API compatibility (libraries like nuqs import useSearchParams
-* 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 read window.location.search directly — causing React to
+* detect external store tearing during transitions and fall back to
+* synchronous rendering (renderRootSync instead of renderRootConcurrent),
+* blocking the main thread and freezing animations.
 *
 * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
 * URLSearchParams. Mutation methods (set, delete, append) work on the
@@ -951,28 +814,9 @@ function createRouter(deps) {
 * During SSR, reads the request search params from the SSR ALS context
 * (populated by ssr-entry.ts) instead of window.location.
 *
-* All mutable state is delegated to client/state.ts for singleton guarantees.
-* See design/18-build-system.md §"Singleton State Registry"
+* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
 */
-function getSearch() {
-	if (typeof window !== "undefined") return window.location.search;
-	const data = getSsrData();
-	if (!data) return "";
-	const str = new URLSearchParams(data.searchParams).toString();
-	return str ? `?${str}` : "";
-}
-function getServerSearch() {
-	const data = getSsrData();
-	if (!data) return "";
-	const str = new URLSearchParams(data.searchParams).toString();
-	return str ? `?${str}` : "";
-}
-function subscribe(callback) {
-	window.addEventListener("popstate", callback);
-	return () => window.removeEventListener("popstate", callback);
-}
-function getSearchParams() {
-	const search = getSearch();
+function getSearchParams(search) {
 	if (search !== cachedSearch) {
 		const params = new URLSearchParams(search);
 		_setCachedSearch(search, params);
@@ -980,18 +824,20 @@ function getSearchParams() {
 	}
 	return cachedSearchParams;
 }
-function getServerSearchParams() {
-	const data = getSsrData();
-	return data ? new URLSearchParams(data.searchParams) : new URLSearchParams();
-}
 /**
 * Read the current URL search params.
 *
 * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
 */
 function useSearchParams() {
-	useSyncExternalStore(subscribe, getSearch, getServerSearch);
-	return typeof window !== "undefined" ? getSearchParams() : getServerSearchParams();
+	try {
+		const navContext = useNavigationContext();
+		if (navContext !== null) return getSearchParams(navContext.search);
+	} catch {}
+	const ssrData = getSsrData();
+	if (ssrData) return new URLSearchParams(ssrData.searchParams);
+	if (typeof window !== "undefined") return getSearchParams(window.location.search);
+	return new URLSearchParams();
 }
 //#endregion
 export { HistoryStack, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, clearSsrData, createRouter, getNavigationState, getRouter, getRouterOrNull, getSsrData, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useSearchParams, useSegmentContext };