@timber-js/app 0.1.0

package/dist/client/index.js

@@ -0,0 +1,1218 @@
+import { t as TimberErrorBoundary } from "../_chunks/error-boundary-dj-WO5uq.js";
+import { i as setSsrData, n as clearSsrData, r as getSsrData, t as useCookie } from "../_chunks/use-cookie-8ZlA0rr3.js";
+import { t as getSearchParams$1 } from "../_chunks/registry-DUIpYD_x.js";
+import { createContext, createElement, useActionState as useActionState$1, useContext, useEffect, useMemo, useRef, useSyncExternalStore, useTransition } from "react";
+import { jsxDEV } from "react/jsx-dev-runtime";
+import { useQueryStates as useQueryStates$1 } from "nuqs";
+//#region src/client/link-navigate-interceptor.tsx
+var _jsxFileName$2 = "/Users/dsaewitz/y/timber-js-fresh/packages/timber-app/src/client/link-navigate-interceptor.tsx";
+/** Symbol used to store the onNavigate callback on anchor elements. */
+var ON_NAVIGATE_KEY = "__timberOnNavigate";
+/**
+* Client component rendered inside <Link> that attaches the onNavigate
+* callback to the closest <a> ancestor via a DOM property. The callback
+* is cleaned up on unmount.
+*
+* Renders no extra DOM — just a transparent wrapper.
+*/
+function LinkNavigateInterceptor({ onNavigate, children }) {
+	const ref = useRef(null);
+	useEffect(() => {
+		const anchor = ref.current?.closest("a");
+		if (!anchor) return;
+		anchor[ON_NAVIGATE_KEY] = onNavigate;
+		return () => {
+			delete anchor[ON_NAVIGATE_KEY];
+		};
+	}, [onNavigate]);
+	return /* @__PURE__ */ jsxDEV("span", {
+		ref,
+		style: { display: "contents" },
+		children
+	}, void 0, false, {
+		fileName: _jsxFileName$2,
+		lineNumber: 58,
+		columnNumber: 5
+	}, this);
+}
+//#endregion
+//#region src/client/use-link-status.ts
+/**
+* React context provided by <Link>. Holds the pending status
+* for that specific link's navigation.
+*/
+var LinkStatusContext = createContext({ pending: false });
+/**
+* Returns `{ pending: true }` while the nearest parent `<Link>` component's
+* navigation is in flight. Must be used inside a `<Link>` component's children.
+*
+* Unlike `useNavigationPending()` which is global, this hook is scoped to
+* the nearest parent `<Link>` — only the link the user clicked shows pending.
+*
+* ```tsx
+* 'use client'
+* import { Link, useLinkStatus } from '@timber/app/client'
+*
+* function Hint() {
+*   const { pending } = useLinkStatus()
+*   return <span className={pending ? 'opacity-50' : ''} />
+* }
+*
+* export function NavLink({ href, children }) {
+*   return (
+*     <Link href={href}>
+*       {children} <Hint />
+*     </Link>
+*   )
+* }
+* ```
+*/
+function useLinkStatus() {
+	return useContext(LinkStatusContext);
+}
+//#endregion
+//#region src/client/router-ref.ts
+var globalRouter = null;
+/**
+* Get the global router instance. Throws if called before bootstrap.
+* Used by client-side hooks (useNavigationPending, etc.)
+*/
+function getRouter() {
+	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
+	return globalRouter;
+}
+//#endregion
+//#region src/client/link-status-provider.tsx
+var _jsxFileName$1 = "/Users/dsaewitz/y/timber-js-fresh/packages/timber-app/src/client/link-status-provider.tsx";
+var NOT_PENDING = { pending: false };
+var IS_PENDING = { pending: true };
+/**
+* Client component that subscribes to the router's pending URL and provides
+* a scoped LinkStatusContext to children. Renders no extra DOM — just a
+* context provider around children.
+*/
+function LinkStatusProvider({ href, children }) {
+	const status = useSyncExternalStore((callback) => {
+		try {
+			return getRouter().onPendingChange(callback);
+		} catch {
+			return () => {};
+		}
+	}, () => {
+		try {
+			if (getRouter().getPendingUrl() === href) return IS_PENDING;
+			return NOT_PENDING;
+		} catch {
+			return NOT_PENDING;
+		}
+	}, () => NOT_PENDING);
+	return /* @__PURE__ */ jsxDEV(LinkStatusContext.Provider, {
+		value: status,
+		children
+	}, void 0, false, {
+		fileName: _jsxFileName$1,
+		lineNumber: 39,
+		columnNumber: 10
+	}, this);
+}
+//#endregion
+//#region src/client/link.tsx
+var _jsxFileName = "/Users/dsaewitz/y/timber-js-fresh/packages/timber-app/src/client/link.tsx";
+/**
+* Reject dangerous URL schemes that could execute script.
+* Security: design/13-security.md § Link scheme injection (test #9)
+*/
+var DANGEROUS_SCHEMES = /^\s*(javascript|data|vbscript):/i;
+function validateLinkHref(href) {
+	if (DANGEROUS_SCHEMES.test(href)) throw new Error(`<Link> received a dangerous href: "${href}". javascript:, data:, and vbscript: URLs are not allowed.`);
+}
+/** Returns true if the href is an internal path (not an external URL) */
+function isInternalHref(href) {
+	if (href.startsWith("/") || href.startsWith("#") || href.startsWith("?")) return true;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(href)) return false;
+	return true;
+}
+/**
+* Interpolate dynamic segments in a route pattern with actual values.
+* e.g. interpolateParams("/products/[id]", { id: "123" }) → "/products/123"
+*
+* Supports:
+* - [param]          → single segment
+* - [...param]       → catch-all (joined with /)
+* - [[...param]]     → optional catch-all (omitted if undefined/empty)
+*/
+function interpolateParams(pattern, params) {
+	return pattern.replace(/\[\[\.\.\.(\w+)\]\]|\[\.\.\.(\w+)\]|\[(\w+)\]/g, (_match, optionalCatchAll, catchAll, single) => {
+		if (optionalCatchAll) {
+			const value = params[optionalCatchAll];
+			if (value === void 0 || Array.isArray(value) && value.length === 0) return "";
+			return (Array.isArray(value) ? value : [value]).map(encodeURIComponent).join("/");
+		}
+		if (catchAll) {
+			const value = params[catchAll];
+			if (value === void 0) throw new Error(`<Link> missing required catch-all param "${catchAll}" for pattern "${pattern}".`);
+			const segments = Array.isArray(value) ? value : [value];
+			if (segments.length === 0) throw new Error(`<Link> catch-all param "${catchAll}" must have at least one segment for pattern "${pattern}".`);
+			return segments.map(encodeURIComponent).join("/");
+		}
+		const value = params[single];
+		if (value === void 0) throw new Error(`<Link> missing required param "${single}" for pattern "${pattern}".`);
+		if (Array.isArray(value)) throw new Error(`<Link> param "${single}" expected a string but received an array for pattern "${pattern}".`);
+		return encodeURIComponent(String(value));
+	}).replace(/\/+$/, "") || "/";
+}
+/**
+* Resolve the final href string from Link props.
+*
+* Handles:
+* - params interpolation into route patterns
+* - searchParams serialization via SearchParamsDefinition
+* - Validation that searchParams and inline query strings are exclusive
+*/
+function resolveHref(href, params, searchParams) {
+	let resolvedPath = href;
+	if (params) resolvedPath = interpolateParams(href, params);
+	if (searchParams) {
+		if (resolvedPath.includes("?")) throw new Error("<Link> received both a searchParams prop and a query string in href. These are mutually exclusive — use one or the other.");
+		const qs = searchParams.definition.serialize(searchParams.values);
+		if (qs) resolvedPath = `${resolvedPath}?${qs}`;
+	}
+	return resolvedPath;
+}
+/**
+* Build the HTML attributes for a Link. Separated from the component
+* for testability — the component just spreads these onto an <a>.
+*/
+function buildLinkProps(props) {
+	const resolvedHref = resolveHref(props.href, props.params, props.searchParams);
+	validateLinkHref(resolvedHref);
+	const output = { href: resolvedHref };
+	if (isInternalHref(resolvedHref)) {
+		output["data-timber-link"] = true;
+		if (props.prefetch) output["data-timber-prefetch"] = true;
+		if (props.scroll === false) output["data-timber-scroll"] = "false";
+	}
+	return output;
+}
+/**
+* Navigation link with progressive enhancement.
+*
+* Renders as a plain `<a>` tag — works without JavaScript. When the client
+* runtime is active, it intercepts clicks on links marked with
+* `data-timber-link` to perform RSC-based client navigation.
+*
+* Supports typed routes via codegen overloads. At runtime:
+* - `params` prop interpolates dynamic segments in the href pattern
+* - `searchParams` prop serializes query parameters via a SearchParamsDefinition
+*/
+function Link({ href, prefetch, scroll, params, searchParams, onNavigate, children, ...rest }) {
+	const linkProps = buildLinkProps({
+		href,
+		prefetch,
+		scroll,
+		params,
+		searchParams
+	});
+	const inner = /* @__PURE__ */ jsxDEV(LinkStatusProvider, {
+		href: linkProps.href,
+		children
+	}, void 0, false, {
+		fileName: _jsxFileName,
+		lineNumber: 299,
+		columnNumber: 17
+	}, this);
+	return /* @__PURE__ */ jsxDEV("a", {
+		...rest,
+		...linkProps,
+		children: onNavigate ? /* @__PURE__ */ jsxDEV(LinkNavigateInterceptor, {
+			onNavigate,
+			children: inner
+		}, void 0, false, {
+			fileName: _jsxFileName,
+			lineNumber: 304,
+			columnNumber: 9
+		}, this) : inner
+	}, void 0, false, {
+		fileName: _jsxFileName,
+		lineNumber: 302,
+		columnNumber: 5
+	}, this);
+}
+//#endregion
+//#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).
+	*
+	* This is a performance optimization only, NOT a security boundary.
+	* The server always runs all access.ts files regardless of the state tree.
+	*/
+	serializeStateTree() {
+		const segments = [];
+		if (this.root) collectSyncSegments(this.root, segments);
+		return { segments };
+	}
+};
+/** Recursively collect sync segment paths from the tree */
+function collectSyncSegments(node, out) {
+	if (!node.isAsync) out.push(node.segment);
+	for (const child of node.children.values()) collectSyncSegments(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 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.
+*
+* Scroll positions are stored in history.state (browser History API),
+* 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/use-params.ts
+var currentParams = {};
+/**
+* Set the current route params. Called by the framework internals
+* during navigation — not intended for direct use by app code.
+*
+* On the client, the segment router calls this on each navigation.
+* During SSR, params are also available via getSsrData().params
+* (ALS-backed), but setCurrentParams is still called for the
+* module-level fallback path.
+*/
+function setCurrentParams(params) {
+	currentParams = params;
+}
+function useParams(_route) {
+	const ssrData = getSsrData();
+	if (ssrData) return ssrData.params;
+	return currentParams;
+}
+//#endregion
+//#region src/client/router.ts
+/**
+* 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;
+	}
+};
+/**
+* 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;
+}
+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()}`;
+}
+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;
+	return headers;
+}
+/**
+* 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 {
+		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 {
+		return null;
+	}
+}
+/**
+* Extract route params from the X-Timber-Params response header.
+* Returns null if the header is missing or malformed.
+*
+* Used to populate useParams() 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 {
+		return null;
+	}
+}
+/**
+* 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) {
+	const rscUrl = appendRscParam(url);
+	const headers = buildRscHeaders(stateTree, currentUrl);
+	if (deps.decodeRsc) {
+		const fetchPromise = deps.fetch(rscUrl, {
+			headers,
+			redirect: "manual"
+		});
+		let headElements = null;
+		let segmentInfo = null;
+		let params = null;
+		const wrappedPromise = fetchPromise.then((response) => {
+			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);
+			headElements = extractHeadElements(response);
+			segmentInfo = extractSegmentInfo(response);
+			params = extractParams(response);
+			return response;
+		});
+		await wrappedPromise;
+		return {
+			payload: await deps.decodeRsc(wrappedPromise),
+			headElements,
+			segmentInfo,
+			params
+		};
+	}
+	const response = await deps.fetch(rscUrl, {
+		headers,
+		redirect: "manual"
+	});
+	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)
+	};
+}
+/**
+* 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();
+	let pending = false;
+	let pendingUrl = null;
+	const pendingListeners = /* @__PURE__ */ new Set();
+	function setPending(value, url) {
+		const newPendingUrl = value && url ? url : null;
+		if (pending === value && pendingUrl === newPendingUrl) return;
+		pending = value;
+		pendingUrl = newPendingUrl;
+		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) {
+		if (deps.renderRoot) deps.renderRoot(payload);
+	}
+	/** Update useParams() with route params from the server response. */
+	function updateParams(params) {
+		setCurrentParams(params ?? {});
+	}
+	/** 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();
+	}
+	async function navigate(url, options = {}) {
+		const scroll = options.scroll !== false;
+		const replace = options.replace === true;
+		const currentScrollY = deps.getScrollY();
+		deps.replaceState({
+			timber: true,
+			scrollY: currentScrollY
+		}, "", deps.getCurrentUrl());
+		setPending(true, url);
+		try {
+			let result = prefetchCache.consume(url);
+			if (result === void 0) {
+				const stateTree = segmentCache.serializeStateTree();
+				const rawCurrentUrl = deps.getCurrentUrl();
+				result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
+			}
+			if (replace) deps.replaceState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			else deps.pushState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			historyStack.push(url, {
+				payload: result.payload,
+				headElements: result.headElements,
+				params: result.params
+			});
+			updateSegmentCache(result.segmentInfo);
+			updateParams(result.params);
+			renderPayload(result.payload);
+			applyHead(result.headElements);
+			window.dispatchEvent(new Event("timber:navigation-end"));
+			afterPaint(() => {
+				if (scroll) deps.scrollTo(0, 0);
+				else deps.scrollTo(0, currentScrollY);
+				window.dispatchEvent(new Event("timber:scroll-restored"));
+			});
+		} catch (error) {
+			if (error instanceof RedirectError) {
+				setPending(false);
+				await navigate(error.redirectUrl, { replace: true });
+				return;
+			}
+			if (isAbortError(error)) return;
+			throw error;
+		} finally {
+			setPending(false);
+		}
+	}
+	async function refresh() {
+		const currentUrl = deps.getCurrentUrl();
+		setPending(true, currentUrl);
+		try {
+			const result = await fetchRscPayload(currentUrl, deps);
+			historyStack.push(currentUrl, {
+				payload: result.payload,
+				headElements: result.headElements,
+				params: result.params
+			});
+			updateSegmentCache(result.segmentInfo);
+			updateParams(result.params);
+			renderPayload(result.payload);
+			applyHead(result.headElements);
+		} finally {
+			setPending(false);
+		}
+	}
+	async function handlePopState(url, scrollY = 0) {
+		const entry = historyStack.get(url);
+		if (entry && entry.payload !== null) {
+			updateParams(entry.params);
+			renderPayload(entry.payload);
+			applyHead(entry.headElements);
+			afterPaint(() => {
+				deps.scrollTo(0, scrollY);
+				window.dispatchEvent(new Event("timber:scroll-restored"));
+			});
+		} else {
+			setPending(true, url);
+			try {
+				const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
+				updateSegmentCache(result.segmentInfo);
+				updateParams(result.params);
+				historyStack.push(url, {
+					payload: result.payload,
+					headElements: result.headElements,
+					params: result.params
+				});
+				renderPayload(result.payload);
+				applyHead(result.headElements);
+				afterPaint(() => {
+					deps.scrollTo(0, scrollY);
+					window.dispatchEvent(new Event("timber:scroll-restored"));
+				});
+			} finally {
+				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()).then((result) => {
+			prefetchCache.set(url, result);
+		}, () => {});
+	}
+	return {
+		navigate,
+		refresh,
+		handlePopState,
+		isPending: () => pending,
+		getPendingUrl: () => pendingUrl,
+		onPendingChange(listener) {
+			pendingListeners.add(listener);
+			return () => pendingListeners.delete(listener);
+		},
+		prefetch,
+		applyRevalidation(element, headElements) {
+			const currentUrl = deps.getCurrentUrl();
+			historyStack.push(currentUrl, {
+				payload: element,
+				headElements
+			});
+			renderPayload(element);
+			applyHead(headElements);
+		},
+		initSegmentCache: (segments) => updateSegmentCache(segments),
+		segmentCache,
+		prefetchCache,
+		historyStack
+	};
+}
+//#endregion
+//#region src/client/use-navigation-pending.ts
+/**
+* Returns true while an RSC navigation is in flight.
+*
+* The pending state is true from the moment the RSC fetch starts until
+* React reconciliation completes. This includes the fetch itself,
+* RSC stream parsing, and React tree reconciliation.
+*
+* It does NOT include Suspense streaming after the shell — only the
+* initial shell reconciliation.
+*
+* ```tsx
+* 'use client'
+* import { useNavigationPending } from '@timber/app/client'
+*
+* export function NavBar() {
+*   const isPending = useNavigationPending()
+*   return (
+*     <nav className={isPending ? 'opacity-50' : ''}>
+*       <Link href="/dashboard">Dashboard</Link>
+*     </nav>
+*   )
+* }
+* ```
+*/
+function useNavigationPending() {
+	return useSyncExternalStore((callback) => {
+		return getRouter().onPendingChange(callback);
+	}, () => {
+		try {
+			return getRouter().isPending();
+		} catch {
+			return false;
+		}
+	}, () => false);
+}
+//#endregion
+//#region src/client/use-router.ts
+/**
+* useRouter() — client-side hook for programmatic navigation.
+*
+* Returns a router instance with push, replace, refresh, back, forward,
+* and prefetch methods. Compatible with Next.js's `useRouter()` from
+* `next/navigation` (App Router).
+*
+* This wraps timber's internal RouterInstance in the Next.js-compatible
+* AppRouterInstance shape that ecosystem libraries expect.
+*/
+/** No-op router returned during SSR or before bootstrap. All methods are safe no-ops. */
+var SSR_NOOP_ROUTER = {
+	push() {},
+	replace() {},
+	refresh() {},
+	back() {},
+	forward() {},
+	prefetch() {}
+};
+/**
+* Get a router instance for programmatic navigation.
+*
+* Compatible with Next.js's `useRouter()` from `next/navigation`.
+*
+* Returns a no-op router during SSR or before the client router is bootstrapped,
+* so components that call useRouter() at the function level (e.g. TransitionLink)
+* do not crash during server-side rendering.
+*/
+function useRouter() {
+	let router;
+	try {
+		router = getRouter();
+	} catch {
+		return SSR_NOOP_ROUTER;
+	}
+	return {
+		push(href, options) {
+			router.navigate(href, { scroll: options?.scroll });
+		},
+		replace(href, options) {
+			router.navigate(href, {
+				scroll: options?.scroll,
+				replace: true
+			});
+		},
+		refresh() {
+			router.refresh();
+		},
+		back() {
+			window.history.back();
+		},
+		forward() {
+			window.history.forward();
+		},
+		prefetch(href) {
+			router.prefetch(href);
+		}
+	};
+}
+//#endregion
+//#region src/client/use-pathname.ts
+/**
+* usePathname() — client-side hook for reading the current pathname.
+*
+* Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
+* Updates when client-side navigation changes the URL.
+*
+* This is a thin wrapper over window.location.pathname, provided for
+* Next.js API compatibility (libraries like nuqs import usePathname
+* from next/navigation).
+*
+* During SSR, reads the request pathname from the SSR ALS context
+* (populated by ssr-entry.ts) instead of window.location.
+*/
+function getPathname() {
+	if (typeof window !== "undefined") return window.location.pathname;
+	return getSsrData()?.pathname ?? "/";
+}
+function getServerPathname() {
+	return getSsrData()?.pathname ?? "/";
+}
+function subscribe$1(callback) {
+	window.addEventListener("popstate", callback);
+	return () => window.removeEventListener("popstate", callback);
+}
+/**
+* Read the current URL pathname.
+*
+* Compatible with Next.js's `usePathname()` from `next/navigation`.
+*/
+function usePathname() {
+	return useSyncExternalStore(subscribe$1, getPathname, getServerPathname);
+}
+//#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.
+*/
+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);
+}
+var cachedSearch = "";
+var cachedParams = new URLSearchParams();
+function getSearchParams() {
+	const search = getSearch();
+	if (search !== cachedSearch) {
+		cachedSearch = search;
+		cachedParams = new URLSearchParams(search);
+	}
+	return cachedParams;
+}
+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
+//#region src/client/segment-context.ts
+/**
+* Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.
+*
+* Each layout in the segment tree is wrapped with a SegmentProvider that stores
+* the URL segments from root to the current layout level. The hooks read this
+* context to determine which child segments are active below the calling layout.
+*
+* The context value is intentionally minimal: just the segment path array and
+* parallel route keys. No internal cache details are exposed.
+*
+* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+*/
+var SegmentContext = createContext(null);
+/** Read the segment context. Returns null if no provider is above this component. */
+function useSegmentContext() {
+	return useContext(SegmentContext);
+}
+/**
+* Wraps each layout to provide segment position context.
+* Injected by rsc-entry.ts during element tree construction.
+*/
+function SegmentProvider({ segments, parallelRouteKeys, children }) {
+	const value = useMemo(() => ({
+		segments,
+		parallelRouteKeys
+	}), [segments.join("/"), parallelRouteKeys.join(",")]);
+	return createElement(SegmentContext.Provider, { value }, children);
+}
+//#endregion
+//#region src/client/use-selected-layout-segment.ts
+/**
+* useSelectedLayoutSegment / useSelectedLayoutSegments — client-side hooks
+* for reading the active segment(s) below the current layout.
+*
+* These hooks are used by navigation UIs to highlight active sections.
+* They match Next.js's API from next/navigation.
+*
+* How they work:
+* 1. Each layout is wrapped with a SegmentProvider that records its depth
+*    (the URL segments from root to that layout level).
+* 2. The hooks read the current URL pathname via usePathname().
+* 3. They compare the layout's segment depth against the full URL segments
+*    to determine which child segments are "selected" below.
+*
+* Example: For URL "/dashboard/settings/profile"
+* - Root layout (depth 0, segments: ['']): selected segment = "dashboard"
+* - Dashboard layout (depth 1, segments: ['', 'dashboard']): selected = "settings"
+* - Settings layout (depth 2, segments: ['', 'dashboard', 'settings']): selected = "profile"
+*
+* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+*/
+/**
+* Split a pathname into URL segments.
+* "/" → [""]
+* "/dashboard" → ["", "dashboard"]
+* "/dashboard/settings" → ["", "dashboard", "settings"]
+*/
+function pathnameToSegments(pathname) {
+	return pathname.split("/");
+}
+/**
+* Pure function: compute the selected child segment given a layout's segment
+* depth and the current URL pathname.
+*
+* @param contextSegments — segments from root to the calling layout, or null if no context
+* @param pathname — current URL pathname
+* @returns the active child segment one level below, or null if at the leaf
+*/
+function getSelectedSegment(contextSegments, pathname) {
+	const urlSegments = pathnameToSegments(pathname);
+	if (!contextSegments) return urlSegments[1] || null;
+	return urlSegments[contextSegments.length] || null;
+}
+/**
+* Pure function: compute all selected segments below a layout's depth.
+*
+* @param contextSegments — segments from root to the calling layout, or null if no context
+* @param pathname — current URL pathname
+* @returns all active segments below the layout
+*/
+function getSelectedSegments(contextSegments, pathname) {
+	const urlSegments = pathnameToSegments(pathname);
+	if (!contextSegments) return urlSegments.slice(1).filter(Boolean);
+	const depth = contextSegments.length;
+	return urlSegments.slice(depth).filter(Boolean);
+}
+/**
+* Returns the active child segment one level below the layout where this
+* hook is called. Returns `null` if the layout is the leaf (no child segment).
+*
+* Compatible with Next.js's `useSelectedLayoutSegment()` from `next/navigation`.
+*
+* @param parallelRouteKey — Optional parallel route key. Currently unused
+*   (parallel route segment tracking is not yet implemented). Accepted for
+*   API compatibility with Next.js.
+*/
+function useSelectedLayoutSegment(parallelRouteKey) {
+	const context = useSegmentContext();
+	const pathname = usePathname();
+	return getSelectedSegment(context?.segments ?? null, pathname);
+}
+/**
+* Returns all active segments below the layout where this hook is called.
+* Returns an empty array if the layout is the leaf (no child segments).
+*
+* Compatible with Next.js's `useSelectedLayoutSegments()` from `next/navigation`.
+*
+* @param parallelRouteKey — Optional parallel route key. Currently unused
+*   (parallel route segment tracking is not yet implemented). Accepted for
+*   API compatibility with Next.js.
+*/
+function useSelectedLayoutSegments(parallelRouteKey) {
+	const context = useSegmentContext();
+	const pathname = usePathname();
+	return getSelectedSegments(context?.segments ?? null, pathname);
+}
+//#endregion
+//#region src/client/form.tsx
+/**
+* Client-side form utilities for server actions.
+*
+* Exports a typed `useActionState` that understands the action builder's result shape.
+* Result is typed to:
+*   { data: T } | { validationErrors: Record<string, string[]> } | { serverError: { code, data? } } | null
+*
+* The action builder emits a function that satisfies both the direct call signature
+* and React's `(prevState, formData) => Promise<State>` contract.
+*
+* See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+*/
+/**
+* Typed wrapper around React 19's `useActionState` that understands
+* the timber action builder's result shape.
+*
+* @param action - A server action created with createActionClient or a raw 'use server' function.
+* @param initialState - Initial state, typically `null`. Pass `getFormFlash()` for no-JS
+*   progressive enhancement — the flash seeds the initial state so the form has a
+*   single source of truth for both with-JS and no-JS paths.
+* @param permalink - Optional permalink for progressive enhancement (no-JS fallback URL).
+*
+* @example
+* ```tsx
+* 'use client'
+* import { useActionState } from '@timber/app/client'
+* import { createTodo } from './actions'
+*
+* export function NewTodoForm({ flash }) {
+*   const [result, action, isPending] = useActionState(createTodo, flash)
+*   return (
+*     <form action={action}>
+*       <input name="title" />
+*       {result?.validationErrors?.title && <p>{result.validationErrors.title}</p>}
+*       <button disabled={isPending}>Add</button>
+*     </form>
+*   )
+* }
+* ```
+*/
+function useActionState(action, initialState, permalink) {
+	return useActionState$1(action, initialState, permalink);
+}
+/**
+* Hook for calling a server action imperatively (not via a form).
+* Returns [execute, isPending] where execute accepts the input directly.
+*
+* @example
+* ```tsx
+* const [deleteTodo, isPending] = useFormAction(deleteTodoAction)
+* <button onClick={() => deleteTodo({ id: todo.id })} disabled={isPending}>
+*   Delete
+* </button>
+* ```
+*/
+function useFormAction(action) {
+	const [isPending, startTransition] = useTransition();
+	const execute = (input) => {
+		return new Promise((resolve) => {
+			startTransition(async () => {
+				resolve(await action(input));
+			});
+		});
+	};
+	return [execute, isPending];
+}
+/**
+* Extract per-field and form-level errors from an ActionResult.
+*
+* Pure function (no internal hooks) — follows React naming convention
+* since it's used in render. Accepts the result from `useActionState`
+* or flash data from `getFormFlash()`.
+*
+* @example
+* ```tsx
+* const [result, action, isPending] = useActionState(createTodo, null)
+* const errors = useFormErrors(result)
+*
+* return (
+*   <form action={action}>
+*     <input name="title" />
+*     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
+*     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
+*   </form>
+* )
+* ```
+*/
+function useFormErrors(result) {
+	const empty = {
+		fieldErrors: {},
+		formErrors: [],
+		serverError: null,
+		hasErrors: false,
+		getFieldError: () => null
+	};
+	if (!result) return empty;
+	const validationErrors = result.validationErrors;
+	const serverError = result.serverError;
+	if (!validationErrors && !serverError) return empty;
+	const fieldErrors = {};
+	const formErrors = [];
+	if (validationErrors) for (const [key, messages] of Object.entries(validationErrors)) if (key === "_root") formErrors.push(...messages);
+	else fieldErrors[key] = messages;
+	const hasErrors = Object.keys(fieldErrors).length > 0 || formErrors.length > 0 || serverError != null;
+	return {
+		fieldErrors,
+		formErrors,
+		serverError: serverError ?? null,
+		hasErrors,
+		getFieldError(field) {
+			const errs = fieldErrors[field];
+			return errs && errs.length > 0 ? errs[0] : null;
+		}
+	};
+}
+//#endregion
+//#region src/client/use-query-states.ts
+/**
+* useQueryStates — client-side hook for URL-synced search params.
+*
+* Delegates to nuqs for URL synchronization, batching, React 19 transitions,
+* and throttled URL writes. Bridges timber's SearchParamCodec protocol to
+* nuqs-compatible parsers.
+*
+* Design doc: design/23-search-params.md §"Codec Bridge"
+*/
+/**
+* Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
+*
+* nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
+* timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
+*/
+function bridgeCodec(codec) {
+	return {
+		parse: (v) => codec.parse(v),
+		serialize: (v) => codec.serialize(v) ?? "",
+		defaultValue: codec.parse(void 0),
+		eq: (a, b) => codec.serialize(a) === codec.serialize(b)
+	};
+}
+/**
+* Bridge an entire codec map to nuqs-compatible parsers.
+*/
+function bridgeCodecs(codecs) {
+	const result = {};
+	for (const key of Object.keys(codecs)) result[key] = bridgeCodec(codecs[key]);
+	return result;
+}
+/**
+* Read and write typed search params from/to the URL.
+*
+* Delegates to nuqs internally. The timber nuqs adapter (auto-injected in
+* browser-entry.ts) handles RSC navigation on non-shallow updates.
+*
+* Usage:
+* ```ts
+* // Via a SearchParamsDefinition
+* const [params, setParams] = definition.useQueryStates()
+*
+* // Standalone with inline codecs
+* const [params, setParams] = useQueryStates({
+*   page: fromSchema(z.coerce.number().int().min(1).default(1)),
+* })
+* ```
+*/
+function useQueryStates(codecsOrRoute, _options, urlKeys) {
+	let codecs;
+	let resolvedUrlKeys = urlKeys;
+	if (typeof codecsOrRoute === "string") {
+		const definition = getSearchParams$1(codecsOrRoute);
+		if (!definition) throw new Error(`useQueryStates('${codecsOrRoute}'): no search params registered for this route. Either the route has no search-params.ts file, or it hasn't been loaded yet. For cross-route usage, import the definition explicitly.`);
+		codecs = definition.codecs;
+		resolvedUrlKeys = definition.urlKeys;
+	} else codecs = codecsOrRoute;
+	const bridged = bridgeCodecs(codecs);
+	const nuqsOptions = {};
+	if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
+	const [values, setValues] = useQueryStates$1(bridged, nuqsOptions);
+	const setParams = (partial, setOptions) => {
+		const nuqsSetOptions = {};
+		if (setOptions?.shallow !== void 0) nuqsSetOptions.shallow = setOptions.shallow;
+		if (setOptions?.scroll !== void 0) nuqsSetOptions.scroll = setOptions.scroll;
+		if (setOptions?.history !== void 0) nuqsSetOptions.history = setOptions.history;
+		setValues(partial, nuqsSetOptions);
+	};
+	return [values, setParams];
+}
+/**
+* Create a useQueryStates binding for a SearchParamsDefinition.
+* This is used internally by SearchParamsDefinition.useQueryStates().
+*/
+function bindUseQueryStates(definition) {
+	return (options) => {
+		return useQueryStates(definition.codecs, options, definition.urlKeys);
+	};
+}
+//#endregion
+export { HistoryStack, Link, LinkStatusContext, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getRouter, getSsrData, interpolateParams, resolveHref, setCurrentParams, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, useParams, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
+
+//# sourceMappingURL=index.js.map