@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/client/internal.js

@@ -0,0 +1,792 @@
+import { t as SingleflightTimeoutError } from "../_chunks/singleflight-BeVMMKi0.js";
+import { a as routerUrlKey, c as prefetchScopeOf, i as parseRouterUrl, n as createNavigationCommitter, o as PrefetchCache, r as isPartialNavigation, s as SegmentCache } from "../_chunks/status-page-marker-BRX9Ib-d.js";
+import { c as cachedSearchParams, s as cachedSearch, t as _setCachedSearch } from "../_chunks/state-BhNGPsdi.js";
+import { a as setGlobalRouter, i as getRouterOrNull, r as getRouter } from "../_chunks/navigation-root-BQfo1-kG.js";
+import { n as registerSsrDataProvider, t as getSsrData } from "../_chunks/ssr-data-nA3I70_n.js";
+import { i as useNavigationContext, n as useSegmentContext, r as NavigationProvider, t as SegmentProvider } from "../_chunks/segment-context-xtPUGfdq.js";
+import { a as createSpaExits, c as NonRscResponse, d as readPublishedParams, i as createScrollEffects, l as fetchRscPayload, n as TimberErrorBoundary, o as recordSkew, r as createNavigationRecovery, s as isClientStale, u as readPayloadTree } from "../_chunks/error-boundary-DsNScGRM.js";
+import { t as bindUseQueryStates } from "../_chunks/use-query-states-I3JMng6J.js";
+//#region src/client/history.ts
+/**
+* Session-lived history stack keyed by URL. Enables instant back/forward
+* navigation without a server roundtrip.
+*
+* On forward navigation, the new page's payload is pushed onto the stack.
+* On popstate, the cached payload is replayed instantly.
+*
+* Entries are keyed by pathname + search in the browser's own spelling
+* (`routerUrlKey`), whatever spelling a caller passes: an entry stored by
+* `navigate('/café')` is found by a traversal that reads `/caf%C3%A9` off
+* the address bar, and `/a?` is `/a` (TIM-1541). Used with the History API
+* fallback and the Navigation API.
+*
+* Scroll positions are stored in history.state or Navigation API entry
+* state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+*
+* Entries have no expiry, but only the 50 most recently used URLs are kept
+* by default. Traversing to an evicted entry fetches a fresh payload.
+*/
+var HistoryStack = class {
+	entries = /* @__PURE__ */ new Map();
+	maxEntries;
+	constructor({ maxEntries = 50 } = {}) {
+		if (!Number.isInteger(maxEntries) || maxEntries < 1) throw new RangeError("HistoryStack maxEntries must be a positive integer");
+		this.maxEntries = maxEntries;
+	}
+	push(url, entry) {
+		url = routerUrlKey(url);
+		this.entries.delete(url);
+		this.entries.set(url, entry);
+		if (this.entries.size > this.maxEntries) {
+			const oldest = this.entries.keys().next();
+			if (!oldest.done) this.entries.delete(oldest.value);
+		}
+	}
+	get(url) {
+		url = routerUrlKey(url);
+		const entry = this.entries.get(url);
+		if (entry) {
+			this.entries.delete(url);
+			this.entries.set(url, entry);
+		}
+		return entry;
+	}
+	/** Presence checks (such as hover prefetch probes) do not promote entries. */
+	has(url) {
+		return this.entries.has(routerUrlKey(url));
+	}
+	/**
+	* Evict every entry (TIM-1476). Called after a server action that
+	* revalidated data — history entries are equally stale since they replay
+	* on back/forward without a server check. Clearing forces a fresh fetch on
+	* the next traversal.
+	*
+	* The current page's entry goes too. Nothing reads it for anything but a
+	* replay: the segment metadata a revalidation needs is the committer's
+	* record of the current page, not this stack's (TIM-1541).
+	*/
+	clear() {
+		this.entries.clear();
+	}
+};
+//#endregion
+//#region src/client/navigation-transition.ts
+/**
+* Create a fresh RenderOwner. Exported so tests that call
+* `navigateTransition` directly can construct one without a router.
+*/
+function createRenderOwner(kind) {
+	let resolveDisplaced;
+	const displaced = new Promise((r) => {
+		resolveDisplaced = r;
+	});
+	const owner = {
+		kind,
+		fetchAbort: new AbortController(),
+		handedOff: false,
+		outcome: null,
+		displaced,
+		settle(outcome) {
+			if (owner.outcome === null) owner.outcome = outcome;
+			else if (outcome === "superseded" && owner.outcome === "committed") owner.outcome = "superseded";
+			if (outcome !== "committed") resolveDisplaced();
+		}
+	};
+	return owner;
+}
+//#endregion
+//#region src/client/router-lifecycle.ts
+/**
+* Navigation Lifecycle — who owns the router, and when a fetch may be cut.
+*
+* One navigation at a time owns the router. This module holds that ownership
+* as a single `RenderOwner` slot, the rule for taking it (`createNavOwner`
+* supersedes), the wrapper every navigation runs inside (`runNavigation`),
+* and the pending store that `TopLoader` and `usePendingNavigation()`
+* subscribe to.
+*
+* TIM-1481: replaced the transition counter, the `handedOffNavAborts` set,
+* and the `AbortController`-as-owner pattern with `RenderOwner`. Supersession
+* is "take the slot": settle the previous owner and abort its fetch unless
+* handed off.
+*
+* See design/19-client-navigation.md §"How Pending State Works".
+*/
+/**
+* Check if an error is an abort error (connection closed / fetch aborted).
+* Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
+*/
+function isAbortError(error) {
+	if (error instanceof DOMException && error.name === "AbortError") return true;
+	if (error instanceof Error && error.name === "AbortError") return true;
+	return false;
+}
+function createNavigationLifecycle(deps) {
+	let current = null;
+	let pendingCommit = null;
+	let routerPhase = { phase: "idle" };
+	const pendingListeners = /* @__PURE__ */ new Set();
+	let navigationSeq = 0;
+	let idleTask = null;
+	/**
+	* Whether a handed-off tree has not yet committed. Derived from the slot:
+	* true when `current` is handed off but not yet settled.
+	*/
+	function hasUncommittedNav() {
+		return pendingCommit !== null || current !== null && current.handedOff && current.outcome === null;
+	}
+	/**
+	* Cancel a navigation's RSC fetch — unless its tree is the one on screen.
+	*
+	* THE only place a navigation controller is aborted. Every path that gives
+	* up on a navigation calls this, so the "is this tree displayed?" question
+	* is asked once rather than at each site. A new abort path is a call to
+	* this, not a copy of `controller.abort()`.
+	*
+	* See design/19-client-navigation.md §"A navigation that reached React
+	* keeps its stream".
+	*/
+	function abortUnlessHandedOff(owner) {
+		if (owner.handedOff) return;
+		owner.fetchAbort.abort();
+	}
+	/**
+	* Create a new RenderOwner for a navigation, superseding any previous
+	* in-flight navigation. Optionally links to an external signal (e.g.,
+	* from the Navigation API's NavigateEvent.signal).
+	*
+	* Superseding is one operation with three parts:
+	* 1. Abort the previous navigation's fetch — UNLESS its tree is the one on
+	*    screen, in which case tearing the stream down would error the page the
+	*    user is currently looking at. See `RenderOwner.handedOff`.
+	* 2. Settle the previous owner as 'superseded' so its transition detects
+	*    it lost and never hands a stale tree to React. This replaces both
+	*    `supersedeNavigationTransitions()` and the transition counter bump.
+	* 3. Resolve its Navigation API deferred — the superseded navigation's
+	*    finally block is staleness-guarded (see TIM-1034) and no longer
+	*    cleans up after itself, so the browser's native loading state for
+	*    the dead navigation is cleared here.
+	*/
+	function createNavOwner(kind, externalSignal) {
+		if (current) {
+			abortUnlessHandedOff(current);
+			current.settle("superseded");
+			deps.completeRouterNavigation?.();
+		}
+		if (pendingCommit) {
+			pendingCommit.settle("superseded");
+			pendingCommit = null;
+		}
+		navigationSeq += 1;
+		const owner = createRenderOwner(kind);
+		current = owner;
+		if (externalSignal) {
+			if (externalSignal.aborted) abortUnlessHandedOff(owner);
+			else externalSignal.addEventListener("abort", () => abortUnlessHandedOff(owner), { once: true });
+		}
+		return owner;
+	}
+	function setPending(value, url) {
+		const next = value && url ? {
+			phase: "navigating",
+			targetUrl: url
+		} : { phase: "idle" };
+		if (routerPhase.phase === next.phase && (routerPhase.phase === "idle" || routerPhase.phase === "navigating" && next.phase === "navigating" && routerPhase.targetUrl === next.targetUrl)) return;
+		routerPhase = next;
+		for (const listener of pendingListeners) listener(value);
+	}
+	/**
+	* Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+	* Consolidates the createNavOwner + 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 owner = createNavOwner("navigation", externalSignal);
+		setPending(true, url);
+		try {
+			await fn(owner);
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
+		} finally {
+			if (current === owner) {
+				current = null;
+				setPending(false);
+				deps.completeRouterNavigation?.();
+				flushIdleTask();
+			}
+		}
+	}
+	function flushIdleTask() {
+		if (routerPhase.phase !== "idle" || hasUncommittedNav() || !idleTask) return;
+		const task = idleTask;
+		idleTask = null;
+		task();
+	}
+	return {
+		currentOwner: () => current,
+		createNavOwner,
+		runNavigation,
+		markHandedOff(owner) {
+			if (current !== owner) return;
+			owner.handedOff = true;
+			pendingCommit = owner;
+		},
+		forgetOlderHandoffs(owner) {
+			owner.settle("committed");
+			if (pendingCommit === owner) pendingCommit = null;
+			flushIdleTask();
+		},
+		placeRevalidationOwner(owner) {
+			current = owner;
+		},
+		isPending: () => routerPhase.phase === "navigating",
+		getPendingUrl: () => routerPhase.phase === "navigating" ? routerPhase.targetUrl : null,
+		onPendingChange(listener) {
+			pendingListeners.add(listener);
+			return () => pendingListeners.delete(listener);
+		},
+		epoch() {
+			return {
+				seq: navigationSeq,
+				idle: routerPhase.phase === "idle" && !hasUncommittedNav()
+			};
+		},
+		isEpochCurrent(e) {
+			return e.idle && routerPhase.phase === "idle" && !hasUncommittedNav() && navigationSeq === e.seq;
+		},
+		runWhenIdle(task) {
+			if (routerPhase.phase === "idle" && !hasUncommittedNav()) {
+				task();
+				return;
+			}
+			idleTask = task;
+		},
+		settleHandoffs() {
+			if (pendingCommit) {
+				pendingCommit.settle("superseded");
+				pendingCommit = null;
+			}
+			if (current !== null && current.handedOff && current.outcome === null) current.settle("superseded");
+			flushIdleTask();
+		}
+	};
+}
+//#endregion
+//#region src/client/router-pipeline.ts
+/**
+* Navigation Pipeline — URL in, tree in React's hands.
+*
+* Everything between "the user asked for this URL" and "React is holding the
+* destination's tree": consult the prefetch cache or fetch, prepare the commit
+* that makes the page current, and hand the result over inside a transition.
+*
+* `router.ts` keeps the *operations* — `navigate`, `refresh`, `handlePopState`,
+* `prefetch`, `applyActionResult` — and each of them is a call into here. The
+* split is the same one `router-effects.ts` and `router-lifecycle.ts` made
+* (design/18-build-system.md §"No file >500 lines").
+*
+* See design/19-client-navigation.md §"Partial Rendering" and §"Prefetching".
+*/
+/**
+* Race a promise against an abort signal. The promise continues regardless —
+* only the *await* gives up. Used so a click superseded by a newer navigation
+* stops waiting for a shared prefetch flight without aborting the flight
+* itself (TIM-1438).
+*/
+function raceAbort(promise, signal) {
+	if (!signal) return promise;
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return Promise.race([promise, new Promise((_, reject) => {
+		signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+	})]);
+}
+/**
+* Normalize a departing URL to the pathname the server is told about.
+*
+* This is the value sent as `X-Timber-URL` *and* the source half of the
+* prefetch cache key — one function so a prefetch and the click that consumes
+* it can never disagree about what "where we came from" means (TIM-1265). The
+* query is dropped deliberately: it would land in the `_rsc` digest, which is
+* logged (TIM-1268), and nothing downstream reads it — slot-skip resolution
+* and interception scope both compare pathnames.
+*
+* Absolute inputs parse against the base and ignore it, so one call handles
+* both `location.href` and a bare pathname.
+*/
+function departingPathname(raw) {
+	return parseRouterUrl(raw).pathname;
+}
+/**
+* The prefetch cache key for a destination.
+*
+* Both halves of the cache are keyed through here — the hover that writes an
+* entry (`router.ts`'s `prefetch()`) and the click that consumes it
+* (`performNavigationFetch` below) — so the two cannot disagree about what
+* identifies a payload. That is the whole point of the key: `from` scopes it
+* to the page the link was on (TIM-1265) and `scope` to the tree that was
+* mounted (TIM-1282), and an entry written under one reading of either would
+* simply never be found under the other, silently costing every prefetch.
+*
+* `departingPathname` is applied here rather than by callers for the same
+* reason: it is also what goes out as `X-Timber-URL`, so the key and the
+* request describe the same departure point.
+*/
+function prefetchKeyFor(url, departingUrl, stateTree) {
+	return {
+		url,
+		from: departingPathname(departingUrl),
+		scope: prefetchScopeOf(stateTree)
+	};
+}
+/**
+* Build a segment updates map for partial navigation. Identifies the
+* first non-skipped segment and maps it to the payload content.
+*/
+function buildSegmentUpdates(result, payload) {
+	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, payload);
+			break;
+		}
+	}
+	return updates;
+}
+/**
+* Inspect a decode rejection for version skew before handing the promise on,
+* without changing what the consumer sees.
+*
+* The decode rejects independently of the fetch, and not every consumer
+* awaits it — NavigationRoot drops it outright when the transition has been
+* superseded. A stale client reference arriving that way is still evidence
+* the bundle is superseded, so record it here where every consumer is fed
+* from, rather than at each place that might drop it (TIM-1275).
+*/
+function observeSkew(decodePromise) {
+	decodePromise?.catch((error) => void recordSkew(error));
+	return decodePromise;
+}
+function createNavigationPipeline({ deps, prefetchCache, currentStateTree, prepareNavigation, isSegmentReuseSuppressed, restoreSegmentReuse, markHandedOff, forgetOlderHandoffs }) {
+	/**
+	* Hand a payload to React via navigateTransition. The perform callback should fetch data, prepare the commit, and return the
+	* FetchResult plus the NavigationState and the commit thunk.
+	*
+	* The thunk is handed *through* to NavigationRoot rather than called here:
+	* state management (segment cache, history stack, address bar) has to happen on
+	* the far side of the supersession check, which only NavigationRoot can
+	* make (TIM-1301).
+	*/
+	async function renderViaTransition(url, owner, types, perform, onCommit) {
+		const handOff = () => markHandedOff(owner);
+		const commitAndForget = (commit) => () => {
+			forgetOlderHandoffs(owner);
+			commit();
+		};
+		await deps.navigateTransition(url, owner, types, async (wrapPayload) => {
+			const result = await perform();
+			const params = await result.params;
+			const payload = await result.payload;
+			if (isPartialNavigation(result.skippedSegments)) {
+				const segmentUpdates = buildSegmentUpdates(result, payload);
+				const element = wrapPayload(deps._getCurrentPayload?.() ?? payload, result.navState, params, segmentUpdates);
+				handOff();
+				return {
+					element,
+					decodePromise: observeSkew(result.decodePromise),
+					commit: commitAndForget(result.commit)
+				};
+			}
+			const element = wrapPayload(payload, result.navState, params);
+			handOff();
+			return {
+				element,
+				decodePromise: observeSkew(result.decodePromise),
+				commit: commitAndForget(result.commit)
+			};
+		}, onCommit);
+	}
+	/**
+	* Fetch (or take from the prefetch cache) a navigation's payload and
+	* prepare — without publishing — the commit that makes it current.
+	*/
+	async function performNavigationFetch(url, options) {
+		const stateTree = currentStateTree();
+		let reuseSuppressedAtFetch = isSegmentReuseSuppressed();
+		const cacheKey = prefetchKeyFor(url, options.departingUrl ?? deps.getCurrentUrl(), stateTree);
+		const currentUrl = cacheKey.from;
+		if (prefetchCache.isNegative(cacheKey)) {
+			prefetchCache.consume(cacheKey);
+			throw new NonRscResponse(url);
+		}
+		const prefetched = prefetchCache.consume(cacheKey);
+		let result = prefetched ? {
+			payload: prefetched.payload,
+			params: prefetched.params ?? readPublishedParams(void 0),
+			decodePromise: prefetched.decodePromise ?? null,
+			segmentInfo: prefetched.segmentInfo ?? null,
+			skippedSegments: prefetched.skippedSegments ?? null
+		} : void 0;
+		if (result === void 0) {
+			const inflight = prefetchCache.joinInflight(cacheKey);
+			if (inflight) {
+				const genBefore = prefetchCache.getEvictionGen();
+				try {
+					const outcome = await raceAbort(inflight, options.signal);
+					if (prefetchCache.getEvictionGen() !== genBefore || outcome.startGen !== genBefore) {} else if (outcome.kind === "non-route") throw new NonRscResponse(url);
+					else {
+						prefetchCache.consume(cacheKey);
+						result = {
+							payload: outcome.result.payload,
+							params: outcome.result.params ?? readPublishedParams(void 0),
+							decodePromise: outcome.result.decodePromise ?? null,
+							segmentInfo: outcome.result.segmentInfo ?? null,
+							skippedSegments: outcome.result.skippedSegments ?? null
+						};
+					}
+				} catch (error) {
+					if (error instanceof DOMException && error.name === "AbortError") throw error;
+					if (options.signal?.aborted) throw options.signal.reason;
+					if (error instanceof SingleflightTimeoutError || error instanceof TypeError) {} else throw error;
+				}
+			}
+		}
+		if (result === void 0) {
+			reuseSuppressedAtFetch = isSegmentReuseSuppressed();
+			const freshStateTree = currentStateTree();
+			result = await fetchRscPayload(url, deps, freshStateTree, currentUrl, options.signal);
+		}
+		const commitHistoryUrl = () => {
+			if (options.skipHistory) return;
+			const commitUrl = options.commitUrl ?? url;
+			deps.setRouterNavigating?.(true);
+			if (options.replace) deps.replaceState({
+				timber: true,
+				scrollY: 0
+			}, "", commitUrl);
+			else deps.pushState({
+				timber: true,
+				scrollY: 0
+			}, "", commitUrl);
+			deps.setRouterNavigating?.(false);
+		};
+		const params = await result.params;
+		const { navState, commit } = prepareNavigation(url, {
+			payload: result.payload,
+			params,
+			segmentInfo: result.segmentInfo,
+			skippedSegments: result.skippedSegments
+		});
+		if (reuseSuppressedAtFetch) restoreSegmentReuse();
+		return {
+			...result,
+			params,
+			navState,
+			commit: () => {
+				commitHistoryUrl();
+				commit();
+				window.dispatchEvent(new Event("timber:navigation-end"));
+			}
+		};
+	}
+	return {
+		performNavigationFetch,
+		renderViaTransition
+	};
+}
+//#endregion
+//#region src/client/router.ts
+/**
+* Create a router instance. In production, called once at app hydration
+* with real browser APIs. In tests, called with mock dependencies.
+*/
+function createRouter(deps) {
+	const segmentCache = new SegmentCache();
+	const prefetchCache = new PrefetchCache();
+	const historyStack = new HistoryStack();
+	const { prepareNavigation, currentStateTree, committedSegmentInfo, isSegmentReuseSuppressed, restoreSegmentReuse } = createNavigationCommitter({
+		segmentCache,
+		historyStack,
+		clientSegmentCache: () => deps.clientSegmentCache
+	});
+	const lifecycle = createNavigationLifecycle(deps);
+	const { currentOwner, createNavOwner, runNavigation, markHandedOff, forgetOlderHandoffs, isPending, getPendingUrl, onPendingChange } = lifecycle;
+	const { performNavigationFetch, renderViaTransition } = createNavigationPipeline({
+		deps,
+		prefetchCache,
+		currentStateTree,
+		prepareNavigation,
+		isSegmentReuseSuppressed,
+		restoreSegmentReuse,
+		markHandedOff,
+		forgetOlderHandoffs
+	});
+	const { restoreScrollAfterPaint, scrollToHashAfterPaint } = createScrollEffects(deps);
+	const { leaveSpaIfOwned, leaveSpaSuperseding } = createSpaExits({
+		currentOwner,
+		supersede: () => void createNavOwner("navigation")
+	});
+	const recoverFromNavigationError = createNavigationRecovery({
+		currentOwner,
+		leaveSpaIfOwned,
+		navigate: (url, types) => navigate(url, {
+			replace: true,
+			_renderTypes: types
+		})
+	});
+	async function navigate(url, options = {}) {
+		const scroll = options.scroll !== false;
+		const replace = options.replace === true;
+		const externalSignal = options._signal;
+		const skipHistory = options._skipHistory === true;
+		const types = options._renderTypes ?? ["navigation-forward", ...options.transitionTypes ?? []];
+		const hashIndex = url.indexOf("#");
+		const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+		const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+		const departingUrl = options._departingUrl ?? deps.getCurrentUrl();
+		const currentScrollY = deps.getScrollY();
+		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
+		else deps.replaceState({
+			timber: true,
+			scrollY: currentScrollY
+		}, "", deps.getCurrentUrl());
+		if (isClientStale()) await leaveSpaSuperseding(url, departingUrl);
+		let effectiveSkipHistory = skipHistory;
+		await runNavigation(url, async (owner) => {
+			if (!effectiveSkipHistory && deps.navigationNavigate) {
+				deps.setRouterNavigating?.(true);
+				deps.navigationNavigate(url, replace);
+				deps.setRouterNavigating?.(false);
+				effectiveSkipHistory = true;
+			}
+			try {
+				await renderViaTransition(fetchUrl, owner, types, () => performNavigationFetch(fetchUrl, {
+					replace,
+					commitUrl: url,
+					signal: owner.fetchAbort.signal,
+					skipHistory: effectiveSkipHistory,
+					departingUrl
+				}), options.onCommit);
+				if (scroll && hash) scrollToHashAfterPaint(hash);
+				else restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+			} catch (error) {
+				if (await recoverFromNavigationError(error, owner, url, departingUrl, types)) return;
+				throw error;
+			}
+		}, externalSignal);
+	}
+	/**
+	* Fetch a URL's RSC payload, commit it, and render — the pipeline shared by
+	* refresh() and an uncached back/forward traversal. Both can be the path
+	* that discovers a version skew, and both recover the same way (TIM-1275).
+	*
+	* Not `performNavigationFetch`: neither caller consults the prefetch cache
+	* (there is no link to have hovered) and neither moves the address bar (the
+	* browser is already where it is going), so the fetch is a plain one.
+	*/
+	async function fetchCommitAndRender(url, type, opts = {}) {
+		await runNavigation(url, async (owner) => {
+			try {
+				await renderViaTransition(url, owner, [type], async () => {
+					const result = await fetchRscPayload(url, deps, opts.stateTree, void 0, owner.fetchAbort.signal);
+					const params = await result.params;
+					const { navState, commit } = prepareNavigation(url, {
+						payload: result.payload,
+						params,
+						segmentInfo: result.segmentInfo,
+						skippedSegments: result.skippedSegments
+					});
+					return {
+						...result,
+						params,
+						navState,
+						commit
+					};
+				}, opts.onCommit);
+			} catch (error) {
+				if (await recoverFromNavigationError(error, owner, url, url, [type])) return;
+				throw error;
+			}
+			if (opts.scrollY !== void 0) restoreScrollAfterPaint(opts.scrollY);
+		}, opts.externalSignal);
+	}
+	async function refresh(options = {}) {
+		const currentUrl = deps.getCurrentUrl();
+		if (isClientStale()) await leaveSpaSuperseding(currentUrl, currentUrl);
+		await fetchCommitAndRender(currentUrl, options.transitionType ?? "refresh", { onCommit: options.onCommit });
+	}
+	async function handlePopState(url, scrollY = 0, externalSignal, direction = "navigation-traverse") {
+		if (isClientStale()) await leaveSpaSuperseding(url, url);
+		const entry = historyStack.get(url);
+		if (entry && entry.payload !== null) await runNavigation(url, async (owner) => {
+			await renderViaTransition(url, owner, [direction], async () => {
+				const { navState, commit } = prepareNavigation(url, {
+					payload: entry.payload,
+					params: entry.params,
+					segmentInfo: entry.segmentInfo,
+					clearSegmentCacheOnEmpty: true
+				});
+				return {
+					payload: entry.payload,
+					params: entry.params,
+					navState,
+					commit,
+					decodePromise: null,
+					segmentInfo: entry.segmentInfo ?? null,
+					skippedSegments: null
+				};
+			});
+			restoreScrollAfterPaint(scrollY);
+		}, externalSignal);
+		else await fetchCommitAndRender(url, direction, {
+			stateTree: currentStateTree(),
+			scrollY,
+			externalSignal
+		});
+	}
+	/**
+	* Prefetch an RSC payload for a URL and store it in the prefetch cache.
+	* Called on hover of <Link prefetch> elements.
+	*
+	* Concurrent hovers and a click during the round-trip coalesce via the
+	* singleflight inside PrefetchCache (TIM-1438).
+	*/
+	function prefetch(url) {
+		if (isClientStale()) return;
+		const hashIndex = url.indexOf("#");
+		const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+		const stateTree = currentStateTree();
+		const cacheKey = prefetchKeyFor(fetchUrl, deps.getCurrentUrl(), stateTree);
+		const from = cacheKey.from;
+		if (prefetchCache.has(cacheKey)) return;
+		prefetchCache.fetchOrCoalesce(cacheKey, (signal) => fetchRscPayload(fetchUrl, deps, stateTree, from, signal), (err) => err instanceof NonRscResponse).then((outcome) => {
+			if (outcome.kind === "ready") outcome.result.decodePromise?.catch((error) => void recordSkew(error));
+		}, (error) => {
+			recordSkew(error);
+		});
+	}
+	return {
+		navigate,
+		refresh,
+		handlePopState,
+		isPending,
+		getPendingUrl,
+		onPendingChange,
+		prefetch,
+		epoch: () => lifecycle.epoch(),
+		isEpochCurrent: (epoch) => lifecycle.isEpochCurrent(epoch),
+		async applyActionResult(epoch, tree) {
+			if (!lifecycle.isEpochCurrent(epoch)) return false;
+			if (tree === void 0) {
+				let outcomeResolve;
+				const outcomePromise = new Promise((r) => outcomeResolve = r);
+				const [, outcome] = await Promise.all([refresh({
+					transitionType: "revalidate",
+					onCommit: outcomeResolve
+				}).catch(() => {}), outcomePromise]);
+				return outcome === "committed";
+			}
+			const currentUrl = deps.getCurrentUrl();
+			const payloadTree = readPayloadTree(tree);
+			const params = readPublishedParams(tree);
+			const segmentInfo = committedSegmentInfo();
+			let outcomeResolve;
+			const outcomePromise = new Promise((r) => outcomeResolve = r);
+			const owner = createRenderOwner("revalidation");
+			lifecycle.placeRevalidationOwner(owner);
+			const [, outcome] = await Promise.all([renderViaTransition(currentUrl, owner, ["revalidate"], async () => {
+				const { navState, commit } = prepareNavigation(currentUrl, {
+					payload: payloadTree,
+					params,
+					segmentInfo
+				});
+				return {
+					payload: payloadTree,
+					params,
+					navState,
+					commit,
+					decodePromise: null,
+					segmentInfo,
+					skippedSegments: null
+				};
+			}, outcomeResolve).catch(() => {}), outcomePromise]);
+			return outcome === "committed";
+		},
+		runWhenIdle: (task) => lifecycle.runWhenIdle(task),
+		settleHandoffs: () => lifecycle.settleHandoffs(),
+		suppressSegmentReuse() {
+			segmentCache.invalidateReuse();
+		},
+		evictStaleCaches() {
+			prefetchCache.clearReady();
+			historyStack.clear();
+		},
+		hydrate(page) {
+			const { navState, commit } = prepareNavigation(deps.getCurrentUrl(), {
+				payload: page.payload,
+				params: page.params,
+				segmentInfo: page.segmentInfo
+			});
+			commit();
+			return navState;
+		},
+		segmentCache,
+		prefetchCache
+	};
+}
+//#endregion
+//#region src/client/use-search-params.ts
+/**
+* useSearchParams() — client-side hook for reading URL search params.
+*
+* Returns a read-only URLSearchParams instance reflecting the current
+* URL's query string. Updates when client-side navigation changes the URL.
+*
+* One unconditional read of NavigationContext, on every side (TIM-1425):
+*
+* - In the browser, the provider is updated atomically with the RSC tree
+*   during full navigations, AND by syncShallowSearch() for shallow URL
+*   updates (nuqs shallow: true, replaceUrl, or any external
+*   pushState/replaceState that changes the query string). See router-init.ts.
+* - During SSR, the wrapper chain mounts the same provider carrying the
+*   request's RAW query string (TIM-1424), so repeated keys
+*   (`?tag=a&tag=b`) survive — the collapsed record the ALS context holds
+*   cannot represent them.
+* - In the RSC environment, this module is never evaluated — the shims plugin
+*   resolves next/navigation to navigation-rsc.ts (TIM-1420).
+*
+* Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
+* URLSearchParams. Mutation methods (set, delete, append) work on the
+* local copy but do NOT affect the URL — use the router or nuqs for that.
+*
+* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+*/
+function getSearchParams(search) {
+	if (search !== cachedSearch) {
+		const params = new URLSearchParams(search);
+		_setCachedSearch(search, params);
+		return params;
+	}
+	return cachedSearchParams;
+}
+/**
+* Read the current URL search params.
+*
+* Throws when no NavigationProvider is above the caller.
+*
+* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+*/
+function useSearchParams() {
+	const nav = useNavigationContext();
+	if (nav === null) throw new Error("[timber] useSearchParams() was called outside the timber app tree (no NavigationProvider found). In tests, render the component inside the timber providers.");
+	if (typeof window === "undefined" || getSsrData()) return new URLSearchParams(nav.search);
+	return getSearchParams(nav.search);
+}
+//#endregion
+export { HistoryStack, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, createRouter, getRouter, getRouterOrNull, getSsrData, registerSsrDataProvider, setGlobalRouter, useSearchParams, useSegmentContext };
+
+//# sourceMappingURL=internal.js.map