@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/dist/client/internal.js

@@ -0,0 +1,938 @@
+import { t as bindUseQueryStates } from "../_chunks/use-query-states-DFvWd-EA.js";
+import { c as cachedSearchParams, i as _setCachedSearch, n as getSsrData, r as setSsrData, s as cachedSearch, t as clearSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
+import { a as setNavigationState, i as getNavigationState, o as useNavigationContext, r as NavigationProvider, t as setCurrentParams } from "../_chunks/use-segment-params-D1CzlgBo.js";
+import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-CtmF-aPv.js";
+import { TimberErrorBoundary } from "./error-boundary.js";
+import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-ZDnXDkbz.js";
+import { n as supersedeNavigationTransitions, t as setHardNavigating } from "../_chunks/navigation-root-bUDZLw74.js";
+//#region src/client/segment-cache.ts
+/**
+* Maintains the client-side segment tree representing currently mounted
+* layouts and pages. Used for navigation reconciliation — the router diffs
+* new routes against this tree to determine which segments to re-fetch.
+*/
+var SegmentCache = class {
+	root;
+	get(segment) {
+		if (segment === "/" || segment === this.root?.segment) return this.root;
+	}
+	set(segment, node) {
+		if (segment === "/" || !this.root) this.root = node;
+	}
+	clear() {
+		this.root = void 0;
+	}
+	/**
+	* Serialize the mounted segment tree for the X-Timber-State-Tree header.
+	* Only includes sync segments — async segments are excluded because the
+	* server must always re-render them (they may depend on request context).
+	*
+	* When mergeableFilter is provided, only segments whose paths are in the
+	* set are included. This ensures the server only skips segments that the
+	* client can actually merge (i.e., segments whose cached element tree
+	* contains an inner SegmentProvider the merger can splice into).
+	*
+	* This is a performance optimization only, NOT a security boundary.
+	* The server always runs all access.ts files regardless of the state tree.
+	*/
+	serializeStateTree(mergeableFilter) {
+		const segments = [];
+		const slots = [];
+		if (this.root) {
+			collectSyncSegments(this.root, segments, mergeableFilter);
+			collectSyncSlots(this.root, slots);
+		}
+		const tree = { segments };
+		if (slots.length > 0) tree.slots = slots;
+		return tree;
+	}
+};
+/** Recursively collect sync segment paths from the tree */
+function collectSyncSegments(node, out, mergeableFilter) {
+	if (!node.isRequestDependent && (!mergeableFilter || mergeableFilter.has(node.segment))) out.push(node.segment);
+	for (const child of node.children.values()) collectSyncSegments(child, out, mergeableFilter);
+}
+/** Recursively collect cacheable slot paths from the tree */
+function collectSyncSlots(node, out) {
+	if (node.slots) {
+		for (const slot of node.slots.values()) if (!slot.isRequestDependent && !slot.denied) out.push(slot.segment);
+	}
+	for (const child of node.children.values()) collectSyncSlots(child, out);
+}
+/**
+* Build a SegmentNode tree from flat segment metadata.
+*
+* Takes an ordered list of segment descriptors (root → leaf) from the
+* server's X-Timber-Segments header and constructs the hierarchical
+* tree structure that SegmentCache expects.
+*
+* Each segment is nested as a child of the previous one, forming a
+* linear chain from root to leaf. The leaf segment (page) is excluded
+* from the tree — pages are never cached across navigations.
+*/
+function buildSegmentTree(segments) {
+	if (segments.length === 0) return void 0;
+	const segmentEntries = [];
+	const slotEntries = [];
+	for (const info of segments) if (info.slot) slotEntries.push(info);
+	else segmentEntries.push(info);
+	let root;
+	let parent;
+	const nodeById = /* @__PURE__ */ new Map();
+	for (const info of segmentEntries) {
+		const id = info.segmentId ?? info.path;
+		const node = {
+			segment: id,
+			payload: null,
+			isRequestDependent: info.isRequestDependent,
+			children: /* @__PURE__ */ new Map()
+		};
+		nodeById.set(id, node);
+		if (!root) root = node;
+		if (parent) parent.children.set(id, node);
+		parent = node;
+	}
+	for (const slotInfo of slotEntries) {
+		const parentId = slotInfo.parentSegment;
+		const parentNode = parentId ? nodeById.get(parentId) : root;
+		if (!parentNode) continue;
+		const slotId = slotInfo.segmentId ?? slotInfo.path;
+		const slotNode = {
+			segment: slotId,
+			payload: null,
+			isRequestDependent: slotInfo.isRequestDependent,
+			children: /* @__PURE__ */ new Map(),
+			denied: slotInfo.denied
+		};
+		if (!parentNode.slots) parentNode.slots = /* @__PURE__ */ new Map();
+		parentNode.slots.set(slotId, slotNode);
+	}
+	return root;
+}
+/** Sentinel value for negative cache entries (URL is not a route). */
+var NEGATIVE_ENTRY = Object.freeze({ payload: null });
+/**
+* Short-lived cache for hover-triggered prefetches. Entries expire after
+* 30 seconds. When a link is clicked, the prefetched payload is consumed
+* (moved to the history stack) and removed from this cache.
+*
+* timber.js does NOT prefetch on viewport intersection — only explicit
+* hover on <Link prefetch> triggers a prefetch.
+*/
+var PrefetchCache = class PrefetchCache {
+	static TTL_MS = 3e4;
+	entries = /* @__PURE__ */ new Map();
+	set(url, result) {
+		this.entries.set(url, {
+			result,
+			expiresAt: Date.now() + PrefetchCache.TTL_MS
+		});
+	}
+	get(url) {
+		const entry = this.entries.get(url);
+		if (!entry) return void 0;
+		if (Date.now() >= entry.expiresAt) {
+			this.entries.delete(url);
+			return;
+		}
+		return entry.result;
+	}
+	/** Get and remove the entry (used when navigation consumes a prefetch) */
+	consume(url) {
+		const result = this.get(url);
+		if (result !== void 0) this.entries.delete(url);
+		return result;
+	}
+	/** Store a negative entry — the URL is not a route (non-RSC Content-Type). */
+	setNegative(url) {
+		this.set(url, NEGATIVE_ENTRY);
+	}
+	/** Check if the entry is a negative cache entry (URL is not a route). */
+	isNegative(url) {
+		return this.get(url) === NEGATIVE_ENTRY;
+	}
+};
+//#endregion
+//#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. 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 persist for the session duration (no expiry) and are cleared
+* when the tab is closed — matching browser back-button behavior.
+*/
+var HistoryStack = class {
+	entries = /* @__PURE__ */ new Map();
+	push(url, entry) {
+		this.entries.set(url, entry);
+	}
+	get(url) {
+		return this.entries.get(url);
+	}
+	has(url) {
+		return this.entries.has(url);
+	}
+};
+//#endregion
+//#region src/client/rsc-fetch.ts
+var RSC_CONTENT_TYPE = "text/x-component";
+/**
+* Generate a short random cache-busting ID (5 chars, a-z0-9).
+* Matches the format Next.js uses for _rsc params.
+*/
+function generateCacheBustId() {
+	const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+	let id = "";
+	for (let i = 0; i < 5; i++) id += chars[Math.random() * 36 | 0];
+	return id;
+}
+/**
+* Append a `_rsc=<id>` query parameter to the URL.
+* Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
+* for RSC navigation requests and signals that this is an RSC fetch.
+*
+* Strips any #fragment before appending — fragments are client-only and
+* fetch() discards them, so _rsc would land inside the hash and be lost.
+*/
+function appendRscParam(url) {
+	const hashIndex = url.indexOf("#");
+	const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+	return `${urlWithoutHash}${urlWithoutHash.includes("?") ? "&" : "?"}_rsc=${generateCacheBustId()}`;
+}
+/**
+* The client's deployment ID, set at bootstrap from the runtime config.
+* Sent with every RSC/action request for version skew detection.
+* Null in dev mode. See TIM-446.
+*/
+var clientDeploymentId = null;
+/** Header name used by the server to signal a version skew reload. */
+var RELOAD_HEADER = "X-Timber-Reload";
+/** Header name for the client's deployment ID. */
+var DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
+/**
+* Check if a response signals a version skew reload.
+* Triggers a full page reload if the server indicates the client is stale.
+*/
+function checkReloadSignal(response) {
+	return response.headers.get(RELOAD_HEADER) === "1";
+}
+function buildRscHeaders(stateTree, currentUrl) {
+	const headers = { Accept: RSC_CONTENT_TYPE };
+	if (stateTree) headers["X-Timber-State-Tree"] = JSON.stringify(stateTree);
+	if (currentUrl) headers["X-Timber-URL"] = currentUrl;
+	if (clientDeploymentId) headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+	return headers;
+}
+/** Dev-only warning for malformed framework headers. Tree-shaken in production. */
+function warnMalformedHeader(headerName, raw) {
+	if (process.env.NODE_ENV !== "production") {
+		const preview = raw.length > 200 ? raw.slice(0, 200) + "…" : raw;
+		console.warn(`[timber] Malformed ${headerName} header \u2014 JSON.parse failed. This indicates a framework bug or header corruption. Raw (first 200 chars): ${preview}`);
+	}
+}
+/**
+* Extract segment metadata from the X-Timber-Segments response header.
+* Returns null if the header is missing or malformed.
+*
+* Format: JSON array of {path, isRequestDependent} objects describing the rendered
+* segment chain from root to leaf. Used to populate the client-side
+* segment cache for state tree diffing on subsequent navigations.
+*/
+function extractSegmentInfo(response) {
+	const header = response.headers.get("X-Timber-Segments");
+	if (!header) return null;
+	try {
+		return JSON.parse(header);
+	} catch {
+		warnMalformedHeader("X-Timber-Segments", header);
+		return null;
+	}
+}
+/**
+* Extract skipped segment paths from the X-Timber-Skipped-Segments header.
+* Returns null if the header is missing or malformed.
+*
+* When the server skips sync layouts the client already has cached,
+* it sends this header listing the skipped segment paths (outermost first).
+* The client uses this to merge the partial payload with cached segments.
+*/
+function extractSkippedSegments(response) {
+	const header = response.headers.get("X-Timber-Skipped-Segments");
+	if (!header) return null;
+	try {
+		const parsed = JSON.parse(header);
+		return Array.isArray(parsed) ? parsed : null;
+	} catch {
+		warnMalformedHeader("X-Timber-Skipped-Segments", header);
+		return null;
+	}
+}
+/**
+* Extract route params from the X-Timber-Params response header.
+* Returns null if the header is missing or malformed.
+*
+* Used to populate useSegmentParams() after client-side navigation.
+*/
+function extractParams(response) {
+	const header = response.headers.get("X-Timber-Params");
+	if (!header) return null;
+	try {
+		return JSON.parse(header);
+	} catch {
+		warnMalformedHeader("X-Timber-Params", header);
+		return null;
+	}
+}
+/**
+* Thrown when an RSC payload response contains X-Timber-Redirect header.
+* Caught in navigate() to trigger a soft router navigation to the redirect target.
+*/
+var RedirectError = class extends Error {
+	redirectUrl;
+	constructor(url) {
+		super(`Server redirect to ${url}`);
+		this.redirectUrl = url;
+	}
+};
+/**
+* Thrown when the server signals a version skew (X-Timber-Reload header).
+* Caught in navigate() to trigger a full page reload.
+* See TIM-446.
+*/
+var VersionSkewError = class extends Error {
+	constructor() {
+		super("Version skew detected — server has been redeployed");
+	}
+};
+/**
+* Thrown when the server returns an error for an RSC payload request.
+* The server sends X-Timber-Error header and a JSON body instead of a
+* broken RSC stream for any RenderError (4xx or 5xx). Caught in
+* navigate() to trigger a hard navigation so the server can render
+* the error page as HTML.
+*
+* See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+*/
+var ServerErrorResponse = class extends Error {
+	status;
+	url;
+	constructor(status, url) {
+		super(`Server error ${status} during navigation to ${url}`);
+		this.status = status;
+		this.url = url;
+	}
+};
+/**
+* Thrown when the RSC fetch response has a Content-Type that is not
+* text/x-component — e.g., a static asset (image, CSS, JS) served
+* for a same-origin URL that isn't a route. The response body is
+* cancelled immediately (headers-only cost). Caught in navigate()
+* to trigger a hard navigation; caught in prefetch() to store a
+* negative cache entry so click hard-navigates without a second fetch.
+*
+* See TIM-1231.
+*/
+var NonRscResponse = class extends Error {
+	url;
+	constructor(url) {
+		super(`Non-RSC response for ${url}`);
+		this.url = url;
+	}
+};
+/**
+* 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).
+*/
+async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
+	const rscUrl = appendRscParam(url);
+	const headers = buildRscHeaders(stateTree, currentUrl);
+	if (deps.decodeRsc) {
+		const fetchPromise = deps.fetch(rscUrl, {
+			headers,
+			redirect: "manual",
+			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);
+			if (redirectLocation) throw new RedirectError(redirectLocation);
+			if (response.headers.get("X-Timber-Error") === "1") throw new ServerErrorResponse(response.status, url);
+			const contentType = response.headers.get("content-type");
+			if (!contentType || !contentType.split(";")[0].trim().includes("text/x-component")) {
+				response.body?.cancel();
+				throw new NonRscResponse(url);
+			}
+			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 payloadError = new Promise((_, reject) => {
+			Promise.resolve(payload).then(() => {}, reject);
+		});
+		payloadError.catch(() => {});
+		return {
+			payload,
+			decodePromise: Promise.race([streamDone, payloadError]),
+			segmentInfo,
+			params,
+			skippedSegments
+		};
+	}
+	const response = await deps.fetch(rscUrl, {
+		headers,
+		redirect: "manual",
+		signal
+	});
+	if (response.status >= 300 && response.status < 400) {
+		const location = response.headers.get("Location");
+		if (location) throw new RedirectError(location);
+	}
+	const fallbackContentType = response.headers.get("content-type");
+	if (!fallbackContentType || !fallbackContentType.split(";")[0].trim().includes("text/x-component")) {
+		response.body?.cancel();
+		throw new NonRscResponse(url);
+	}
+	return {
+		payload: await response.text(),
+		decodePromise: null,
+		segmentInfo: extractSegmentInfo(response),
+		params: extractParams(response),
+		skippedSegments: extractSkippedSegments(response)
+	};
+}
+//#endregion
+//#region src/client/router.ts
+/**
+* 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 createRouter(deps) {
+	const segmentCache = new SegmentCache();
+	const prefetchCache = new PrefetchCache();
+	const historyStack = new HistoryStack();
+	let routerPhase = { phase: "idle" };
+	const pendingListeners = /* @__PURE__ */ new Set();
+	let currentNavAbort = null;
+	/**
+	* Create a new AbortController 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.
+	* 2. Invalidate its render transition so a response that already
+	*    arrived can't commit a stale tree (NavigationRoot's transId guard).
+	* 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 createNavAbort(externalSignal) {
+		if (currentNavAbort) {
+			currentNavAbort.abort();
+			supersedeNavigationTransitions();
+			deps.completeRouterNavigation?.();
+		}
+		const controller = new AbortController();
+		currentNavAbort = controller;
+		if (externalSignal) if (externalSignal.aborted) controller.abort();
+		else externalSignal.addEventListener("abort", () => controller.abort(), { once: true });
+		return controller;
+	}
+	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);
+	}
+	/** Update the segment cache from server-provided segment metadata. */
+	function updateSegmentCache(segmentInfo) {
+		if (!deps.clientSegmentCache) return;
+		if (!segmentInfo || segmentInfo.length === 0) return;
+		const tree = buildSegmentTree(segmentInfo);
+		if (tree) segmentCache.set("/", tree);
+	}
+	/** Render a decoded RSC payload into the DOM if a renderer is available. */
+	function renderPayload(payload, navState) {
+		if (deps.renderRoot) deps.renderRoot(payload, navState);
+	}
+	/**
+	* Atomically update all navigation-owned state for a new page. Every
+	* code path that changes the "current page" must go through this
+	* function — making "forgot a field" impossible by construction.
+	*
+	* The three operations:
+	* 1. Segment cache — update from server-provided segment metadata
+	* 2. Navigation state — params + pathname for useSegmentParams/usePathname
+	* 3. History stack — store the payload for instant back/forward replay
+	*/
+	function commitNavigation(url, opts) {
+		if (opts.segmentInfo && opts.segmentInfo.length > 0) updateSegmentCache(opts.segmentInfo);
+		else if (opts.clearSegmentCacheOnEmpty) segmentCache.clear();
+		const navState = updateNavigationState(opts.params, url);
+		historyStack.push(url, {
+			payload: opts.payload,
+			params: navState.params,
+			segmentInfo: opts.segmentInfo
+		});
+		return navState;
+	}
+	/**
+	* Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+	* Consolidates the createNavAbort + 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 navAbort = createNavAbort(externalSignal);
+		setPending(true, url);
+		try {
+			await fn(navAbort);
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
+		} finally {
+			if (currentNavAbort === navAbort) {
+				currentNavAbort = null;
+				setPending(false);
+				deps.completeRouterNavigation?.();
+			}
+		}
+	}
+	/**
+	* Resolve thenable payloads in the test/fallback path (no navigateTransition).
+	* In production, React handles thenables from createFromFetch directly via
+	* Suspense. In tests, renderRoot is a plain mock that expects resolved values.
+	*/
+	async function resolveForFallback(payload) {
+		if (!deps.navigateTransition && payload != null && typeof payload === "object" && "then" in payload) return await payload;
+		return payload;
+	}
+	function isPartialNavigation(skippedSegments) {
+		return skippedSegments != null && skippedSegments.length > 0;
+	}
+	/**
+	* Build a segment updates map for partial navigation. Identifies the
+	* first non-skipped segment and maps it to the payload content.
+	*/
+	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.
+	*
+	* Sets the module-level fallback (for tests and SSR) and the
+	* globalThis bridge, then returns the NavigationState so callers
+	* can pass it explicitly to renderRoot/wrapPayload — eliminating
+	* temporal coupling with getNavigationState().
+	*/
+	function updateNavigationState(params, url) {
+		const resolvedParams = params ?? {};
+		setCurrentParams(resolvedParams);
+		const parsed = new URL(url, "http://localhost");
+		const navState = {
+			params: resolvedParams,
+			pathname: parsed.pathname || "/",
+			search: parsed.search
+		};
+		setNavigationState(navState);
+		return navState;
+	}
+	/**
+	* Render a payload via navigateTransition (production) or renderRoot (tests).
+	* The perform callback should fetch data, call commitNavigation, and return
+	* the FetchResult plus the NavigationState.
+	*
+	* State management (segmentCache, navState, historyStack) is handled by
+	* commitNavigation inside perform — this function only handles rendering.
+	*/
+	async function renderViaTransition(url, perform) {
+		if (deps.navigateTransition) {
+			await deps.navigateTransition(url, async (wrapPayload) => {
+				const result = await perform();
+				if (isPartialNavigation(result.skippedSegments)) {
+					const segmentUpdates = buildSegmentUpdates(result);
+					return {
+						element: wrapPayload(deps._getCurrentPayload?.() ?? result.payload, result.navState, segmentUpdates),
+						decodePromise: result.decodePromise
+					};
+				}
+				return {
+					element: wrapPayload(result.payload, result.navState),
+					decodePromise: result.decodePromise
+				};
+			});
+			return;
+		}
+		const result = await perform();
+		if (!isPartialNavigation(result.skippedSegments)) renderPayload(result.payload, result.navState);
+	}
+	/** Run a callback after the next paint (after React commit). */
+	function afterPaint(callback) {
+		if (deps.afterPaint) deps.afterPaint(callback);
+		else callback();
+	}
+	/**
+	* Schedule scroll restoration after the next paint and fire the
+	* scroll-restored event. Used by navigate, popstate, and refresh.
+	*/
+	function restoreScrollAfterPaint(scrollY) {
+		afterPaint(() => {
+			deps.scrollTo(0, scrollY);
+			window.dispatchEvent(new Event("timber:scroll-restored"));
+		});
+	}
+	/**
+	* Scroll to the element matching the URL #fragment after paint, falling
+	* back to scroll-to-top when no element matches (matching full-page-load
+	* behavior for an unknown fragment). Used by forward navigation to a
+	* hash-bearing URL (TIM-1035).
+	*/
+	function scrollToHashAfterPaint(hash) {
+		afterPaint(() => {
+			if (deps.scrollToHash?.(hash) !== true) deps.scrollTo(0, 0);
+			window.dispatchEvent(new Event("timber:scroll-restored"));
+		});
+	}
+	/**
+	* 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) {
+		if (prefetchCache.isNegative(url)) {
+			prefetchCache.consume(url);
+			throw new NonRscResponse(url);
+		}
+		const prefetched = prefetchCache.consume(url);
+		let result = prefetched ? {
+			payload: prefetched.payload,
+			decodePromise: null,
+			segmentInfo: prefetched.segmentInfo ?? null,
+			params: prefetched.params ?? null,
+			skippedSegments: prefetched.skippedSegments ?? null
+		} : void 0;
+		if (result === void 0) {
+			const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : void 0;
+			const rawDepartingUrl = options.departingUrl ?? deps.getCurrentUrl();
+			result = await fetchRscPayload(url, deps, stateTree, rawDepartingUrl.startsWith("http") ? new URL(rawDepartingUrl).pathname : new URL(rawDepartingUrl, "http://localhost").pathname, options.signal);
+		}
+		if (!options.skipHistory) {
+			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 payload = await resolveForFallback(result.payload);
+		const isPartial = isPartialNavigation(result.skippedSegments);
+		const hasSkippedSlots = result.segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
+		const navState = commitNavigation(url, {
+			payload: isPartial || hasSkippedSlots ? null : payload,
+			params: result.params,
+			segmentInfo: result.segmentInfo
+		});
+		return {
+			...result,
+			payload,
+			navState
+		};
+	}
+	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 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());
+		let effectiveSkipHistory = skipHistory;
+		await runNavigation(url, async (navAbort) => {
+			if (!effectiveSkipHistory && deps.navigationNavigate) {
+				deps.setRouterNavigating?.(true);
+				deps.navigationNavigate(url, replace);
+				deps.setRouterNavigating?.(false);
+				effectiveSkipHistory = true;
+			}
+			try {
+				await renderViaTransition(fetchUrl, () => performNavigationFetch(fetchUrl, {
+					replace,
+					commitUrl: url,
+					signal: navAbort.signal,
+					skipHistory: effectiveSkipHistory,
+					departingUrl
+				}));
+				window.dispatchEvent(new Event("timber:navigation-end"));
+				if (scroll && hash) scrollToHashAfterPaint(hash);
+				else restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+			} catch (error) {
+				if (error instanceof VersionSkewError) {
+					setHardNavigating(true);
+					window.location.reload();
+					await new Promise(() => {});
+				}
+				if (error instanceof RedirectError) {
+					if (currentNavAbort !== navAbort) return;
+					await navigate(error.redirectUrl, { replace: true });
+					return;
+				}
+				if (error instanceof ServerErrorResponse) {
+					setHardNavigating(true);
+					window.location.href = error.url;
+					await new Promise(() => {});
+				}
+				if (error instanceof NonRscResponse) {
+					setHardNavigating(true);
+					window.location.href = url;
+					await new Promise(() => {});
+				}
+				throw error;
+			}
+		}, externalSignal);
+	}
+	async function refresh() {
+		const currentUrl = deps.getCurrentUrl();
+		await runNavigation(currentUrl, async (navAbort) => {
+			await renderViaTransition(currentUrl, async () => {
+				const result = await fetchRscPayload(currentUrl, deps, void 0, void 0, navAbort.signal);
+				const payload = await resolveForFallback(result.payload);
+				const navState = commitNavigation(currentUrl, {
+					payload,
+					params: result.params,
+					segmentInfo: result.segmentInfo
+				});
+				return {
+					...result,
+					payload,
+					navState
+				};
+			});
+		});
+	}
+	async function handlePopState(url, scrollY = 0, externalSignal) {
+		const entry = historyStack.get(url);
+		if (entry && entry.payload !== null) await runNavigation(url, async () => {
+			const navState = commitNavigation(url, {
+				payload: entry.payload,
+				params: entry.params,
+				segmentInfo: entry.segmentInfo,
+				clearSegmentCacheOnEmpty: true
+			});
+			renderPayload(entry.payload, navState);
+			restoreScrollAfterPaint(scrollY);
+		}, externalSignal);
+		else await runNavigation(url, async (navAbort) => {
+			await renderViaTransition(url, async () => {
+				const result = await fetchRscPayload(url, deps, deps.clientSegmentCache ? segmentCache.serializeStateTree() : void 0, void 0, navAbort.signal);
+				const payload = await resolveForFallback(result.payload);
+				const navState = commitNavigation(url, {
+					payload,
+					params: result.params,
+					segmentInfo: result.segmentInfo
+				});
+				return {
+					...result,
+					payload,
+					navState
+				};
+			});
+			restoreScrollAfterPaint(scrollY);
+		}, externalSignal);
+	}
+	/**
+	* Prefetch an RSC payload for a URL and store it in the prefetch cache.
+	* Called on hover of <Link prefetch> elements.
+	*/
+	function prefetch(url) {
+		const hashIndex = url.indexOf("#");
+		const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+		if (prefetchCache.get(fetchUrl) !== void 0) return;
+		if (historyStack.has(fetchUrl)) return;
+		fetchRscPayload(fetchUrl, deps, deps.clientSegmentCache ? segmentCache.serializeStateTree() : void 0).then((result) => {
+			result.decodePromise?.catch(() => {});
+			prefetchCache.set(fetchUrl, result);
+		}, (error) => {
+			if (error instanceof NonRscResponse) {
+				prefetchCache.setNegative(fetchUrl);
+				return;
+			}
+		});
+	}
+	return {
+		navigate,
+		refresh,
+		handlePopState,
+		isPending: () => routerPhase.phase === "navigating",
+		getPendingUrl: () => routerPhase.phase === "navigating" ? routerPhase.targetUrl : null,
+		onPendingChange(listener) {
+			pendingListeners.add(listener);
+			return () => pendingListeners.delete(listener);
+		},
+		prefetch,
+		applyRevalidation(element) {
+			const currentUrl = deps.getCurrentUrl();
+			const existingEntry = historyStack.get(currentUrl);
+			renderPayload(element, commitNavigation(currentUrl, {
+				payload: element,
+				params: getNavigationState().params,
+				segmentInfo: existingEntry?.segmentInfo
+			}));
+		},
+		initSegmentCache: (segments) => updateSegmentCache(segments),
+		segmentCache,
+		prefetchCache,
+		historyStack
+	};
+}
+//#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.
+*
+* On the client, reads from NavigationContext which is updated atomically
+* with the RSC tree render 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.
+*
+* 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
+* local copy but do NOT affect the URL — use the router or nuqs for that.
+*
+* During SSR, reads the request search params from the SSR ALS context
+* (populated by ssr-entry.ts) instead of window.location.
+*
+* 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.
+*
+* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+*/
+function useSearchParams() {
+	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 };
+
+//# sourceMappingURL=internal.js.map