@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/dist/client/index.js

@@ -1,48 +1,29 @@
 "use client";
-import { a as _setCurrentParams, c as cachedSearchParams, i as _setCachedSearch, l as currentParams, n as getSsrData, o as _setGlobalRouter, r as setSsrData, s as cachedSearch, t as clearSsrData, u as globalRouter } from "../_chunks/ssr-data-DLnbYpj1.js";
-import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-DAhgj8Gx.js";
-import { t as useCookie } from "../_chunks/use-cookie-dDbpCTx-.js";
-import { TimberErrorBoundary } from "./error-boundary.js";
-import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useEffect, useMemo, useRef, useSyncExternalStore, useTransition } from "react";
+import { r as __exportAll } from "../_chunks/chunk-BYIpzuS7.js";
+import { n as classifyUrlSegment } from "../_chunks/segment-classify-BjfuctV2.js";
+import { t as getSearchParamsDefinition } from "../_chunks/registry-I2ss-lvy.js";
+import { n as fromSchema } from "../_chunks/schema-bridge-Cxu4l-7p.js";
+import { t as _registerUseSegmentParams } from "../_chunks/define-CfBPoJb0.js";
+import { n as assertValidCookieName, t as mergePreservedSearchParams } from "../_chunks/merge-search-params-BphMdht_.js";
+import { r as _registerUseCookieModule, t as _registerFromSchema } from "../_chunks/define-cookie-BjpIt4UC.js";
+import { n as getSsrData } from "../_chunks/ssr-data-B4CdH7rE.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-h3-UaCQv.js";
+import { n as useSegmentContext } from "../_chunks/segment-context-Dx_OizxD.js";
+import { i as unmountLinkForCurrentNavigation, n as LINK_IDLE, r as setLinkForCurrentNavigation } from "../_chunks/navigation-root-BCYczjml.js";
+import { c as usePendingNavigationUrl, n as useSegmentParams, s as useNavigationContext } from "../_chunks/use-segment-params-BkpKAQ7D.js";
+import { createContext, useActionState as useActionState$1, useContext, useEffect, useOptimistic, useRef, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
-//#region 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__ */ jsx("span", {
-		ref,
-		style: { display: "contents" },
-		children
-	});
-}
-//#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 });
+var LinkStatusContext = createContext({ isPending: false });
 /**
-* Returns `{ pending: true }` while the nearest parent `<Link>` component's
+* Returns `{ isPending: 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
+* Unlike `usePendingNavigation()` which is global, this hook is scoped to
 * the nearest parent `<Link>` — only the link the user clicked shows pending.
 *
 * ```tsx
@@ -50,8 +31,8 @@ var LinkStatusContext = createContext({ pending: false });
 * import { Link, useLinkStatus } from '@timber-js/app/client'
 *
 * function Hint() {
-*   const { pending } = useLinkStatus()
-*   return <span className={pending ? 'opacity-50' : ''} />
+*   const { isPending } = useLinkStatus()
+*   return <span className={isPending ? 'opacity-50' : ''} />
 * }
 *
 * export function NavLink({ href, children }) {
@@ -66,135 +47,35 @@ var LinkStatusContext = createContext({ pending: false });
 function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
-//#endregion
-//#region src/client/navigation-context.ts
 /**
-* NavigationContext — React context for navigation state.
-*
-* Holds the current route params and pathname, updated atomically
-* with the RSC tree on each navigation. This replaces the previous
-* useSyncExternalStore approach for useParams() and usePathname(),
-* which suffered from a timing gap: the new tree could commit before
-* the external store re-renders fired, causing a frame where both
-* old and new active states were visible simultaneously.
-*
-* By wrapping the RSC payload element in NavigationProvider inside
-* renderRoot(), the context value and the element tree are passed to
-* reactRoot.render() in the same call — atomic by construction.
-* All consumers (useParams, usePathname) see the new values in the
-* same render pass as the new tree.
-*
-* During SSR, no NavigationProvider is mounted. Hooks fall back to
-* the ALS-backed getSsrData() for per-request isolation.
-*
-* IMPORTANT: createContext and useContext are NOT available in the RSC
-* environment (React Server Components use a stripped-down React).
-* The context is lazily initialized on first access, and all functions
-* that depend on these APIs are safe to call from any environment —
-* they return null or no-op when the APIs aren't available.
-*
-* Singleton guarantee: With the simplified chunking strategy (LOCAL-337),
-* this module lives in exactly one client chunk. The previous globalThis +
-* Symbol.for workaround for cross-chunk duplication is no longer needed.
-* See design/27-chunking-strategy.md.
-*
-* See design/19-client-navigation.md §"NavigationContext"
+* Store metadata from Link's onClick for the next navigate event.
+* Called synchronously in the click handler — the navigate event
+* fires synchronously after onClick returns.
 */
+function setNavLinkMetadata(metadata) {}
+//#endregion
+//#region src/client/navigation-api.ts
 /**
-* The context is created lazily to avoid calling createContext at module
-* level. In the RSC environment, React.createContext doesn't exist —
-* calling it at import time would crash the server.
-*/
-var _navCtx;
-var _pendingNavCtx;
-function getOrCreateContext() {
-	if (_navCtx !== void 0) return _navCtx;
-	if (typeof React.createContext === "function") {
-		_navCtx = React.createContext(null);
-		return _navCtx;
-	}
-}
-/**
-* Read the navigation context. Returns null during SSR (no provider)
-* or in the RSC environment (no context available).
-* Internal — used by useParams() and usePathname().
-*/
-function useNavigationContext() {
-	const ctx = getOrCreateContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
-}
-/**
-* Wraps children with NavigationContext.Provider.
-*
-* Used in browser-entry.ts renderRoot to wrap the RSC payload element
-* so that navigation state updates atomically with the tree render.
-*/
-function NavigationProvider({ value, children }) {
-	const ctx = getOrCreateContext();
-	if (!ctx) return children;
-	return createElement(ctx.Provider, { value }, children);
-}
-/**
-* Navigation state communicated between the router and renderRoot.
-*
-* The router calls setNavigationState() before renderRoot(). The
-* renderRoot callback reads via getNavigationState() to create the
-* NavigationProvider with the correct params/pathname.
-*
-* This is NOT used by hooks directly — hooks read from React context.
-*/
-var _navState = {
-	params: {},
-	pathname: "/"
-};
-function setNavigationState(state) {
-	_navState = state;
-}
-function getNavigationState() {
-	return _navState;
-}
-/**
-* Separate context for the in-flight navigation URL. Provided by
-* TransitionRoot (urgent useState), consumed by LinkStatusProvider
-* and useNavigationPending.
-*/
-function getOrCreatePendingContext() {
-	if (_pendingNavCtx !== void 0) return _pendingNavCtx;
-	if (typeof React.createContext === "function") {
-		_pendingNavCtx = React.createContext(null);
-		return _pendingNavCtx;
-	}
-}
-/**
-* Read the pending navigation URL from context.
-* Returns null during SSR (no provider) or in the RSC environment.
+* Returns true if the Navigation API is available in the current environment.
+* Feature-detected at runtime — no polyfill.
 */
-function usePendingNavigationUrl() {
-	const ctx = getOrCreatePendingContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
+function hasNavigationApi() {
+	return typeof window !== "undefined" && "navigation" in window && window.navigation != null;
 }
 //#endregion
-//#region src/client/link-status-provider.tsx
-var NOT_PENDING = { pending: false };
-var IS_PENDING = { pending: true };
+//#region src/client/link.tsx
 /**
-* Client component that reads the pending URL from PendingNavigationContext
-* and provides a scoped LinkStatusContext to children. Renders no extra DOM —
-* just a context provider around children.
+* Read the current URL's search string without requiring a React hook.
+* On the client, reads window.location.search. During SSR, reads from
+* the request context (getSsrData). Returns empty string if unavailable.
 */
-function LinkStatusProvider({ href, children }) {
-	const status = usePendingNavigationUrl() === href ? IS_PENDING : NOT_PENDING;
-	return /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
-		value: status,
-		children
-	});
+function getCurrentSearch() {
+	if (typeof window !== "undefined") return window.location.search;
+	const data = getSsrData();
+	if (!data) return "";
+	const str = new URLSearchParams(data.searchParams).toString();
+	return str ? `?${str}` : "";
 }
-//#endregion
-//#region src/client/link.tsx
 /**
 * Reject dangerous URL schemes that could execute script.
 * Security: design/13-security.md § Link scheme injection (test #9)
@@ -218,25 +99,53 @@ function isInternalHref(href) {
 * - [...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 "";
+/**
+* Parse a route pattern's path portion into classified segments.
+* Exported for testing. Uses the shared character-based classifier.
+*/
+function parseSegments(pattern) {
+	return pattern.split("/").filter(Boolean).map(classifyUrlSegment);
+}
+/**
+* Resolve a single classified segment into its string representation.
+* Returns null for optional catch-all with no value (filtered out before join).
+*/
+function resolveSegment(seg, params, pattern) {
+	switch (seg.kind) {
+		case "static": return seg.value;
+		case "optional-catch-all": {
+			const value = params[seg.name];
+			if (value === void 0 || Array.isArray(value) && value.length === 0) return null;
 			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}".`);
+		case "catch-all": {
+			const value = params[seg.name];
+			if (value === void 0) throw new Error(`<Link> missing required catch-all param "${seg.name}" 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}".`);
+			if (segments.length === 0) throw new Error(`<Link> catch-all param "${seg.name}" 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(/\/+$/, "") || "/";
+		case "dynamic": {
+			const value = params[seg.name];
+			if (value === void 0) throw new Error(`<Link> missing required param "${seg.name}" for pattern "${pattern}".`);
+			if (Array.isArray(value)) throw new Error(`<Link> param "${seg.name}" expected a string but received an array for pattern "${pattern}".`);
+			return encodeURIComponent(String(value));
+		}
+	}
+}
+/**
+* Split a URL pattern into the path portion and any trailing ?query/#hash suffix.
+* Uses URL parsing for correctness rather than manual index arithmetic.
+*/
+function splitPatternSuffix(pattern) {
+	if (!pattern.includes("?") && !pattern.includes("#")) return [pattern, ""];
+	const url = new URL(pattern, "http://x");
+	const suffix = url.search + url.hash;
+	return [pattern.slice(0, pattern.length - suffix.length), suffix];
+}
+function interpolateParams(pattern, params) {
+	const [pathPart, suffix] = splitPatternSuffix(pattern);
+	return ("/" + parseSegments(pathPart).map((seg) => resolveSegment(seg, params, pattern)).filter((s) => s !== null).join("/") || "/") + suffix;
 }
 /**
 * Resolve the final href string from Link props.
@@ -246,12 +155,30 @@ function interpolateParams(pattern, params) {
 * - searchParams serialization via SearchParamsDefinition
 * - Validation that searchParams and inline query strings are exclusive
 */
+/**
+* Runtime discriminator: treat `searchParams` as the legacy wrapped shape
+* only when it literally has a `definition` key. Everything else is the
+* flat `Partial<T>` values shape (TIM-830).
+*/
+function isWrappedSearchParamsProp(sp) {
+	return "definition" in sp;
+}
 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);
+		let definition;
+		let values;
+		if (isWrappedSearchParamsProp(searchParams)) {
+			definition = searchParams.definition;
+			values = searchParams.values;
+		} else {
+			definition = getSearchParamsDefinition(href);
+			values = searchParams;
+			if (!definition) throw new Error(`<Link> received a flat searchParams object for href "${href}", but no SearchParamsDefinition is registered for that route. Either the route does not export \`searchParams\` from its \`params.ts\`/\`page.tsx\`, or the search-params registry module was not loaded. For external or computed hrefs, pass the legacy \`{ definition, values }\` shape instead.`);
+		}
+		const qs = definition.serialize(values);
 		if (qs) resolvedPath = `${resolvedPath}?${qs}`;
 	}
 	return resolvedPath;
@@ -263,820 +190,114 @@ function resolveHref(href, params, searchParams) {
 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;
+	return { href: resolvedHref };
+}
+/**
+* Should this click be intercepted for SPA navigation?
+*
+* Returns false (pass through to browser) when:
+* - Modified keys are held (Ctrl, Meta, Shift, Alt) — open in new tab
+* - The click is not the primary button
+* - The event was already prevented by a parent handler
+* - The link has target="_blank" or similar
+* - The link has a download attribute
+* - The href is external
+*/
+function shouldInterceptClick(event, resolvedHref) {
+	if (event.button !== 0) return false;
+	if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+	if (event.defaultPrevented) return false;
+	const anchor = event.currentTarget;
+	if (anchor.target && anchor.target !== "_self") return false;
+	if (anchor.hasAttribute("download")) return false;
+	if (!isInternalHref(resolvedHref)) return false;
+	return true;
 }
 /**
 * 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.
+* runtime is active, the Link's onClick handler triggers RSC-based client
+* navigation via the router. No global event delegation — each Link owns
+* its own click handling.
 *
-* Supports typed routes via codegen overloads. At runtime:
-* - `params` prop interpolates dynamic segments in the href pattern
+* Supports typed routes via the Routes interface (populated by codegen).
+* At runtime:
+* - `segmentParams` prop interpolates dynamic segments in the href pattern
 * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
+*
+* Typed via the LinkFunction callable interface. The base call signature
+* forbids segmentParams; per-route signatures are added by codegen via
+* interface merging. See TIM-624.
 */
-function Link({ href, prefetch, scroll, params, searchParams, onNavigate, children, ...rest }) {
-	const linkProps = buildLinkProps({
+var Link = function LinkImpl(props) {
+	const { href, prefetch, scroll, segmentParams, searchParams, preserveSearchParams, onNavigate, onClick: userOnClick, onMouseEnter: userOnMouseEnter, children, ...rest } = props;
+	const { href: baseHref } = buildLinkProps({
 		href,
-		prefetch,
-		scroll,
-		params,
+		params: segmentParams,
 		searchParams
 	});
-	const inner = /* @__PURE__ */ jsx(LinkStatusProvider, {
-		href: linkProps.href,
-		children
-	});
-	return /* @__PURE__ */ jsx("a", {
-		...rest,
-		...linkProps,
-		children: onNavigate ? /* @__PURE__ */ jsx(LinkNavigateInterceptor, {
-			onNavigate,
-			children: inner
-		}) : inner
-	});
-}
-//#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).
-	*
-	* 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.
-*
-* 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
-/**
-* Set the current route params in the module-level store.
-*
-* Called by the router on each navigation. This updates the fallback
-* snapshot used by tests and by the hook when called outside a React
-* component (no NavigationContext available).
-*
-* On the client, the primary reactivity path is NavigationContext —
-* the router calls setNavigationState() then renderRoot() which wraps
-* the element in NavigationProvider. setCurrentParams is still called
-* for the module-level fallback.
-*
-* During SSR, params are also available via getSsrData().params
-* (ALS-backed).
-*/
-function setCurrentParams(params) {
-	_setCurrentParams(params);
-}
-function useParams(_route) {
-	try {
-		const navContext = useNavigationContext();
-		if (navContext !== null) return navContext.params;
-	} catch {}
-	return getSsrData()?.params ?? currentParams;
-}
-//#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()}`;
-}
-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 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 {
-		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;
-	}
-}
-/**
-* 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;
-	}
-};
-/**
-* 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;
-		let skippedSegments = 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);
-			skippedSegments = extractSkippedSegments(response);
-			return response;
-		});
-		await wrappedPromise;
-		return {
-			payload: await deps.decodeRsc(wrappedPromise),
-			headElements,
-			segmentInfo,
-			params,
-			skippedSegments
+	const [linkStatus, setIsPending] = useOptimistic(LINK_IDLE);
+	const linkInstanceRef = useRef(null);
+	if (!linkInstanceRef.current) linkInstanceRef.current = { setIsPending };
+	else linkInstanceRef.current.setIsPending = setIsPending;
+	useEffect(() => {
+		const instance = linkInstanceRef.current;
+		return () => {
+			if (instance) unmountLinkForCurrentNavigation(instance);
 		};
-	}
-	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),
-		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;
-}
-/**
-* Create a router instance. In production, called once at app hydration
-* with real browser APIs. In tests, called with mock dependencies.
-*/
-function createRouter(deps) {
-	const segmentCache = new SegmentCache();
-	const prefetchCache = new PrefetchCache();
-	const historyStack = new HistoryStack();
-	const segmentElementCache = new SegmentElementCache();
-	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);
-	}
-	/**
-	* 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 both the module-level fallback (for tests and SSR) and the
-	* navigation context state (read by renderRoot to wrap the element
-	* in NavigationProvider). The context update is atomic with the tree
-	* render — both are passed to reactRoot.render() in the same call.
-	*/
-	function updateNavigationState(params, url) {
-		const resolvedParams = params ?? {};
-		setCurrentParams(resolvedParams);
-		setNavigationState({
-			params: resolvedParams,
-			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
-		});
-	}
-	/**
-	* Render a payload via navigateTransition (production) or renderRoot (tests).
-	* The perform callback should fetch data, update state, and return the payload.
-	* In production, the entire callback runs inside a React transition with
-	* useOptimistic for the pending URL. In tests, the payload is rendered directly.
-	*/
-	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);
-			});
-			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);
-		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();
-	}
-	/**
-	* 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);
-		}
-		if (options.replace) deps.replaceState({
-			timber: true,
-			scrollY: 0
-		}, "", url);
-		else deps.pushState({
-			timber: true,
-			scrollY: 0
-		}, "", url);
-		updateSegmentCache(result.segmentInfo);
-		updateNavigationState(result.params, url);
-		return result;
-	}
-	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 {
-			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, { replace })));
-			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 });
+	}, []);
+	const resolvedHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
+	const internal = isInternalHref(resolvedHref);
+	const handleClick = internal ? (event) => {
+		userOnClick?.(event);
+		if (!shouldInterceptClick(event, resolvedHref)) return;
+		if (onNavigate) {
+			let prevented = false;
+			onNavigate({ preventDefault: () => {
+				prevented = true;
+			} });
+			if (prevented) {
+				event.preventDefault();
 				return;
 			}
-			if (isAbortError(error)) return;
-			throw error;
-		} finally {
-			setPending(false);
-		}
-	}
-	async function refresh() {
-		const currentUrl = deps.getCurrentUrl();
-		setPending(true, currentUrl);
-		try {
-			applyHead(await renderViaTransition(currentUrl, async () => {
-				const result = await fetchRscPayload(currentUrl, deps);
-				updateSegmentCache(result.segmentInfo);
-				updateNavigationState(result.params, currentUrl);
-				return result;
-			}));
-		} finally {
-			setPending(false);
 		}
-	}
-	async function handlePopState(url, scrollY = 0) {
-		const entry = historyStack.get(url);
-		if (entry && entry.payload !== null) {
-			updateNavigationState(entry.params, url);
-			renderPayload(entry.payload);
-			applyHead(entry.headElements);
-			afterPaint(() => {
-				deps.scrollTo(0, scrollY);
-				window.dispatchEvent(new Event("timber:scroll-restored"));
+		const router = getRouterOrNull();
+		if (!router) return;
+		const shouldScroll = scroll !== false;
+		setLinkForCurrentNavigation(linkInstanceRef.current);
+		if (hasNavigationApi()) {
+			setNavLinkMetadata({
+				scroll: shouldScroll,
+				linkInstance: linkInstanceRef.current
 			});
-		} else {
-			setPending(true, url);
-			try {
-				applyHead(await renderViaTransition(url, async () => {
-					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()));
-					updateSegmentCache(result.segmentInfo);
-					updateNavigationState(result.params, url);
-					return result;
-				}));
-				afterPaint(() => {
-					deps.scrollTo(0, scrollY);
-					window.dispatchEvent(new Event("timber:scroll-restored"));
-				});
-			} finally {
-				setPending(false);
-			}
+			return;
 		}
-	}
-	/**
-	* 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: () => pending,
-		getPendingUrl: () => pendingUrl,
-		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);
-			applyHead(headElements);
-		},
-		initSegmentCache: (segments) => updateSegmentCache(segments),
-		cacheElementTree: (element) => cacheSegmentElements(element, segmentElementCache),
-		segmentCache,
-		prefetchCache,
-		historyStack
-	};
-}
+		event.preventDefault();
+		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+		router.navigate(navHref, { scroll: shouldScroll });
+	} : userOnClick;
+	const handleMouseEnter = internal && prefetch ? (event) => {
+		userOnMouseEnter?.(event);
+		const router = getRouterOrNull();
+		if (router) {
+			const prefetchHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+			router.prefetch(prefetchHref);
+		}
+	} : userOnMouseEnter;
+	return /* @__PURE__ */ jsx("a", {
+		...rest,
+		href: resolvedHref,
+		onClick: handleClick,
+		onMouseEnter: handleMouseEnter,
+		children: /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
+			value: linkStatus,
+			children
+		})
+	});
+};
 //#endregion
-//#region src/client/use-navigation-pending.ts
+//#region src/client/use-pending-navigation.ts
 /**
 * Returns true while an RSC navigation is in flight.
 *
@@ -1089,10 +310,10 @@ function createRouter(deps) {
 *
 * ```tsx
 * 'use client'
-* import { useNavigationPending } from '@timber-js/app/client'
+* import { usePendingNavigation } from '@timber-js/app/client'
 *
 * export function NavBar() {
-*   const isPending = useNavigationPending()
+*   const isPending = usePendingNavigation()
 *   return (
 *     <nav className={isPending ? 'opacity-50' : ''}>
 *       <Link href="/dashboard">Dashboard</Link>
@@ -1101,34 +322,10 @@ function createRouter(deps) {
 * }
 * ```
 */
-function useNavigationPending() {
+function usePendingNavigation() {
 	return usePendingNavigationUrl() !== null;
 }
 //#endregion
-//#region src/client/router-ref.ts
-/**
-* Set the global router instance. Called once during bootstrap.
-*/
-function setGlobalRouter(router) {
-	_setGlobalRouter(router);
-}
-/**
-* 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;
-}
-/**
-* Get the global router instance or null if not yet initialized.
-* Used by useRouter() methods to avoid silent failures — callers
-* can log a meaningful warning instead of silently no-oping.
-*/
-function getRouterOrNull() {
-	return globalRouter;
-}
-//#endregion
 //#region src/client/use-router.ts
 /**
 * useRouter() — client-side hook for programmatic navigation.
@@ -1152,7 +349,7 @@ function getRouterOrNull() {
 *
 * For loading UI during navigation, use:
 * - useLinkStatus()          — per-link pending indicator (inside <Link>)
-* - useNavigationPending()   — global navigation pending state
+* - usePendingNavigation()   — global navigation pending state
 */
 /**
 * Get a router instance for programmatic navigation.
@@ -1251,97 +448,6 @@ function usePathname() {
 	return "/";
 }
 //#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
-//#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, segmentId: _segmentId, 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
@@ -1472,7 +578,13 @@ function useSelectedLayoutSegments(parallelRouteKey) {
 * ```
 */
 function useActionState(action, initialState, permalink) {
-	return useActionState$1(action, initialState, permalink);
+	const [result, formAction, isPending] = useActionState$1(action, initialState, permalink);
+	return [
+		result,
+		formAction,
+		isPending,
+		deriveFormErrors(result)
+	];
 }
 /**
 * Hook for calling a server action imperatively (not via a form).
@@ -1498,27 +610,11 @@ function useFormAction(action) {
 	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>
-* )
-* ```
+* Derive FormErrorsResult from an action result.
+* Used internally by useActionState 4th tuple element.
+* @internal — exported for test access only.
 */
-function useFormErrors(result) {
+function deriveFormErrors(result) {
 	const empty = {
 		fieldErrors: {},
 		formErrors: [],
@@ -1547,6 +643,113 @@ function useFormErrors(result) {
 	};
 }
 //#endregion
-export { HistoryStack, Link, LinkStatusContext, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getNavigationState, getRouter, getSsrData, interpolateParams, resolveHref, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, useParams, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
+//#region src/client/use-cookie.ts
+/**
+* useCookie — reactive client-side cookie hook.
+*
+* Uses useSyncExternalStore for SSR-safe, reactive cookie access.
+* All components reading the same cookie name re-render on change.
+* No cross-tab sync (intentional — see design/29-cookies.md).
+*
+* See design/29-cookies.md §"useCookie(name) Hook"
+*/
+var use_cookie_exports = /* @__PURE__ */ __exportAll({
+	notifyCookieChange: () => notifyCookieChange,
+	useCookie: () => useCookie
+});
+/** Per-name subscriber sets. */
+var listeners = /* @__PURE__ */ new Map();
+/** Parse a cookie name from document.cookie. */
+function getCookieValue(name) {
+	if (typeof document === "undefined") return void 0;
+	const match = document.cookie.match(new RegExp("(?:^|;\\s*)" + name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\s*=\\s*([^;]*)"));
+	return match ? decodeURIComponent(match[1]) : void 0;
+}
+/** Serialize options into a cookie string suffix. */
+function serializeOptions(options) {
+	if (!options) return "; Path=/; SameSite=Lax";
+	const parts = [];
+	parts.push(`Path=${options.path ?? "/"}`);
+	if (options.domain) parts.push(`Domain=${options.domain}`);
+	if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
+	if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+	const sameSite = options.sameSite ?? "lax";
+	parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
+	if (options.secure) parts.push("Secure");
+	return "; " + parts.join("; ");
+}
+/** Notify all subscribers for a given cookie name. */
+function notify(name) {
+	const subs = listeners.get(name);
+	if (subs) for (const fn of subs) fn();
+}
+/**
+* Notify useCookie subscribers that a cookie value changed.
+* Called by defineCookie's imperative client .set()/.delete() methods
+* so mounted useCookie() consumers re-render.
+*
+* @internal — framework use only
+*/
+function notifyCookieChange(name) {
+	notify(name);
+}
+/**
+* Reactive hook for reading/writing a client-side cookie.
+*
+* Returns `[value, setCookie, deleteCookie]`:
+* - `value`: current cookie value (string | undefined)
+* - `setCookie`: sets the cookie and triggers re-renders
+* - `deleteCookie`: deletes the cookie and triggers re-renders
+*
+* @param name - Cookie name.
+* @param defaultOptions - Default options for setCookie calls.
+*/
+function useCookie(name, defaultOptions) {
+	const subscribe = (callback) => {
+		let subs = listeners.get(name);
+		if (!subs) {
+			subs = /* @__PURE__ */ new Set();
+			listeners.set(name, subs);
+		}
+		subs.add(callback);
+		return () => {
+			subs.delete(callback);
+			if (subs.size === 0) listeners.delete(name);
+		};
+	};
+	const getSnapshot = () => getCookieValue(name);
+	const getServerSnapshot = () => getSsrData()?.cookies.get(name);
+	const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+	assertValidCookieName(name);
+	const setCookie = (newValue, options) => {
+		if (typeof newValue !== "string") throw new Error(`[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n  '@timber-js/app/cookies' and call its useCookie() hook instead.`);
+		const merged = {
+			...defaultOptions,
+			...options
+		};
+		document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
+		notify(name);
+	};
+	const deleteCookie = () => {
+		const path = defaultOptions?.path ?? "/";
+		const domain = defaultOptions?.domain;
+		let cookieStr = `${name}=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=${path}`;
+		if (domain) cookieStr += `; Domain=${domain}`;
+		document.cookie = cookieStr;
+		notify(name);
+	};
+	return [
+		value,
+		setCookie,
+		deleteCookie
+	];
+}
+//#endregion
+//#region src/client/index.ts
+_registerUseCookieModule(use_cookie_exports);
+_registerFromSchema(fromSchema);
+_registerUseSegmentParams(useSegmentParams);
+//#endregion
+export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, resolveHref, useActionState, useFormAction, useLinkStatus, usePathname, usePendingNavigation, useRouter, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
 
 //# sourceMappingURL=index.js.map