@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/dist/client/internal.js

@@ -0,0 +1,964 @@
+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-m9-cNEIw.js";
+import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-CpvjBqdu.js";
+import { TimberErrorBoundary } from "./error-boundary.js";
+import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-EsfQpS--.js";
+import { t as setHardNavigating } from "../_chunks/navigation-root-DoRTeBm5.js";
+import { a as getNavigationState, i as NavigationProvider, o as setNavigationState, t as setCurrentParams } from "../_chunks/use-segment-params-CtIAjqK0.js";
+import { cloneElement, isValidElement, useSyncExternalStore } from "react";
+//#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 = [];
+		if (this.root) collectSyncSegments(this.root, segments, mergeableFilter);
+		return { segments };
+	}
+};
+/** Recursively collect sync segment paths from the tree */
+function collectSyncSegments(node, out, mergeableFilter) {
+	if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) out.push(node.segment);
+	for (const child of node.children.values()) collectSyncSegments(child, out, mergeableFilter);
+}
+/**
+* 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 layouts = segments.length > 1 ? segments.slice(0, -1) : segments;
+	let root;
+	let parent;
+	for (const info of layouts) {
+		const node = {
+			segment: info.path,
+			payload: null,
+			isAsync: info.isAsync,
+			children: /* @__PURE__ */ new Map()
+		};
+		if (!root) root = node;
+		if (parent) parent.children.set(info.path, node);
+		parent = node;
+	}
+	return root;
+}
+/**
+* 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;
+	}
+};
+//#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.
+*
+* Supports two keying modes:
+* - **URL-keyed** (default): entries keyed by pathname + search.
+*   Used with the History API fallback.
+* - **Entry-key + URL**: when the Navigation API is available,
+*   entries can also be stored by Navigation entry key for
+*   disambiguation of duplicate URLs in the history stack.
+*   Falls back to URL lookup when entry key is not found.
+*
+* 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();
+	/** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
+	entryKeyMap = /* @__PURE__ */ new Map();
+	push(url, entry, entryKey) {
+		this.entries.set(url, entry);
+		if (entryKey) this.entryKeyMap.set(entryKey, entry);
+	}
+	/**
+	* Get an entry. When an entry key is provided (Navigation API),
+	* tries the entry-key map first for accurate disambiguation of
+	* duplicate URLs, then falls back to URL lookup.
+	*/
+	get(url, entryKey) {
+		if (entryKey) {
+			const byKey = this.entryKeyMap.get(entryKey);
+			if (byKey) return byKey;
+		}
+		return this.entries.get(url);
+	}
+	has(url) {
+		return this.entries.has(url);
+	}
+};
+//#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";
+/**
+* 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.
+*/
+function appendRscParam(url) {
+	return `${url}${url.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 head elements from the X-Timber-Head response header.
+* Returns null if the header is missing or malformed.
+*/
+function extractHeadElements(response) {
+	const header = response.headers.get("X-Timber-Head");
+	if (!header) return null;
+	try {
+		return JSON.parse(decodeURIComponent(header));
+	} catch {
+		warnMalformedHeader("X-Timber-Head", header);
+		return null;
+	}
+}
+/**
+* Extract segment metadata from the X-Timber-Segments response header.
+* Returns null if the header is missing or malformed.
+*
+* Format: JSON array of {path, isAsync} 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 via triggerStaleReload().
+* 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;
+	}
+};
+/**
+* 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).
+*
+* Also extracts head elements from the X-Timber-Head response header
+* so the client can update document.title and <meta> tags after navigation.
+*/
+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 headElements = null;
+		let segmentInfo = null;
+		let params = null;
+		let skippedSegments = null;
+		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);
+			headElements = extractHeadElements(response);
+			segmentInfo = extractSegmentInfo(response);
+			params = extractParams(response);
+			skippedSegments = extractSkippedSegments(response);
+			return response;
+		});
+		await wrappedPromise;
+		return {
+			payload: await deps.decodeRsc(wrappedPromise),
+			headElements,
+			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);
+	}
+	return {
+		payload: await response.text(),
+		headElements: extractHeadElements(response),
+		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();
+	const segmentElementCache = new SegmentElementCache();
+	let routerPhase = { phase: "idle" };
+	const pendingListeners = /* @__PURE__ */ new Set();
+	let currentNavAbort = null;
+	/**
+	* Create a new AbortController for a navigation, aborting any
+	* previous in-flight navigation. Optionally links to an external
+	* signal (e.g., from the Navigation API's NavigateEvent.signal).
+	*/
+	function createNavAbort(externalSignal) {
+		currentNavAbort?.abort();
+		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 (!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);
+	}
+	/**
+	* Merge a partial RSC payload with cached segment elements if segments
+	* were skipped, then cache segments from the (merged) payload.
+	* Returns the merged payload ready for rendering.
+	*/
+	function mergeAndCachePayload(payload, skippedSegments) {
+		let merged = payload;
+		if (skippedSegments && skippedSegments.length > 0) merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+		cacheSegmentElements(merged, segmentElementCache);
+		return merged;
+	}
+	/**
+	* 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 navState = {
+			params: resolvedParams,
+			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
+		};
+		setNavigationState(navState);
+		return navState;
+	}
+	/**
+	* Render a payload via navigateTransition (production) or renderRoot (tests).
+	* The perform callback should fetch data, update state, and return the
+	* FetchResult plus the NavigationState (so it can be passed explicitly
+	* to wrapPayload/renderRoot without temporal coupling).
+	*/
+	async function renderViaTransition(url, perform) {
+		if (deps.navigateTransition) {
+			let headElements = null;
+			await deps.navigateTransition(url, async (wrapPayload) => {
+				const result = await perform();
+				headElements = result.headElements;
+				const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+				historyStack.push(url, {
+					payload: merged,
+					headElements: result.headElements,
+					params: result.params
+				});
+				return wrapPayload(merged, result.navState);
+			});
+			return headElements;
+		}
+		const result = await perform();
+		const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+		historyStack.push(url, {
+			payload: merged,
+			headElements: result.headElements,
+			params: result.params
+		});
+		renderPayload(merged, result.navState);
+		return result.headElements;
+	}
+	/** Apply head elements (title, meta tags) to the DOM if available. */
+	function applyHead(elements) {
+		if (elements && deps.applyHead) deps.applyHead(elements);
+	}
+	/** 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"));
+		});
+	}
+	/**
+	* 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) {
+		const prefetched = prefetchCache.consume(url);
+		let result = prefetched ? {
+			payload: prefetched.payload,
+			headElements: prefetched.headElements,
+			segmentInfo: prefetched.segmentInfo ?? null,
+			params: prefetched.params ?? null,
+			skippedSegments: prefetched.skippedSegments ?? null
+		} : void 0;
+		if (result === void 0) {
+			const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+			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);
+		}
+		if (!options.skipHistory) {
+			deps.setRouterNavigating?.(true);
+			if (options.replace) deps.replaceState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			else deps.pushState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			deps.setRouterNavigating?.(false);
+		}
+		updateSegmentCache(result.segmentInfo);
+		const navState = updateNavigationState(result.params, url);
+		return {
+			...result,
+			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 navAbort = createNavAbort(externalSignal);
+		const currentScrollY = deps.getScrollY();
+		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
+		else deps.replaceState({
+			timber: true,
+			scrollY: currentScrollY
+		}, "", deps.getCurrentUrl());
+		let effectiveSkipHistory = skipHistory;
+		if (!skipHistory && deps.navigationNavigate) {
+			deps.setRouterNavigating?.(true);
+			deps.navigationNavigate(url, replace);
+			deps.setRouterNavigating?.(false);
+			effectiveSkipHistory = true;
+		}
+		setPending(true, url);
+		try {
+			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, {
+				replace,
+				signal: navAbort.signal,
+				skipHistory: effectiveSkipHistory
+			})));
+			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");
+				triggerStaleReload();
+				return new Promise(() => {});
+			}
+			if (error instanceof RedirectError) {
+				setPending(false);
+				deps.completeRouterNavigation?.();
+				await navigate(error.redirectUrl, { replace: true });
+				return;
+			}
+			if (error instanceof ServerErrorResponse) {
+				setHardNavigating(true);
+				window.location.href = error.url;
+				return new Promise(() => {});
+			}
+			if (isAbortError(error)) return;
+			throw error;
+		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
+			setPending(false);
+			deps.completeRouterNavigation?.();
+		}
+	}
+	async function refresh() {
+		const currentUrl = deps.getCurrentUrl();
+		const navAbort = createNavAbort();
+		setPending(true, currentUrl);
+		try {
+			applyHead(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);
+				return {
+					...result,
+					navState
+				};
+			}));
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
+		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
+			setPending(false);
+			deps.completeRouterNavigation?.();
+		}
+	}
+	async function handlePopState(url, scrollY = 0, externalSignal) {
+		const entry = historyStack.get(url);
+		if (entry && entry.payload !== null) {
+			const navState = updateNavigationState(entry.params, url);
+			renderPayload(entry.payload, navState);
+			applyHead(entry.headElements);
+			restoreScrollAfterPaint(scrollY);
+		} else {
+			const navAbort = createNavAbort(externalSignal);
+			setPending(true, url);
+			try {
+				applyHead(await renderViaTransition(url, async () => {
+					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()), void 0, navAbort.signal);
+					updateSegmentCache(result.segmentInfo);
+					const navState = updateNavigationState(result.params, url);
+					return {
+						...result,
+						navState
+					};
+				}));
+				restoreScrollAfterPaint(scrollY);
+			} catch (error) {
+				if (isAbortError(error)) return;
+				throw error;
+			} finally {
+				if (currentNavAbort === navAbort) currentNavAbort = null;
+				setPending(false);
+			}
+		}
+	}
+	/**
+	* Prefetch an RSC payload for a URL and store it in the prefetch cache.
+	* Called on hover of <Link prefetch> elements.
+	*/
+	function prefetch(url) {
+		if (prefetchCache.get(url) !== void 0) return;
+		if (historyStack.has(url)) return;
+		fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths())).then((result) => {
+			prefetchCache.set(url, result);
+		}, () => {});
+	}
+	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, headElements) {
+			const currentUrl = deps.getCurrentUrl();
+			const merged = mergeAndCachePayload(element, null);
+			historyStack.push(currentUrl, {
+				payload: merged,
+				headElements
+			});
+			renderPayload(merged, getNavigationState());
+			applyHead(headElements);
+		},
+		initSegmentCache: (segments) => updateSegmentCache(segments),
+		cacheElementTree: (element) => cacheSegmentElements(element, segmentElementCache),
+		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.
+*
+* This is a thin wrapper over window.location.search, provided for
+* Next.js API compatibility (libraries like nuqs import useSearchParams
+* from next/navigation).
+*
+* 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.
+*
+* All mutable state is delegated to client/state.ts for singleton guarantees.
+* See design/18-build-system.md §"Singleton State Registry"
+*/
+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();
+	if (search !== cachedSearch) {
+		const params = new URLSearchParams(search);
+		_setCachedSearch(search, params);
+		return params;
+	}
+	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();
+}
+//#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