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

package/dist/client/index.js

@@ -1,21 +1,26 @@
 "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-MjmprTmO.js";
-import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-D5KaffOK.js";
-import { t as useCookie } from "../_chunks/use-cookie-DX-l1_5E.js";
-import { TimberErrorBoundary } from "./error-boundary.js";
-import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useMemo, useSyncExternalStore, useTransition } from "react";
+import { n as classifyUrlSegment } from "../_chunks/segment-classify-Byy425ng.js";
+import { t as getSearchParamsDefinition } from "../_chunks/registry-DbJPKoBp.js";
+import { n as getSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
+import { n as useSegmentParams, o as useNavigationContext } from "../_chunks/use-segment-params-D1CzlgBo.js";
+import { a as mergePreservedSearchParams, i as validateNavigationHref, n as isInternalHref } from "../_chunks/href-validation-CMc5JRls.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-CtmF-aPv.js";
+import { n as useSegmentContext } from "../_chunks/segment-context-ZDnXDkbz.js";
+import { t as getLinkCodec } from "../_chunks/codec-registry-oOUxugz3.js";
+import { r as usePendingNavigation } from "../_chunks/navigation-root-bUDZLw74.js";
+import { createContext, useActionState as useActionState$1, useContext, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#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
@@ -23,8 +28,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 }) {
@@ -40,203 +45,20 @@ 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: All shared mutable state uses globalThis via
-* Symbol.for keys. The RSC client bundler can duplicate this module
-* across chunks (browser-entry graph + client-reference graph). With
-* ESM output, each chunk gets its own module scope — module-level
-* variables would create separate singleton instances per chunk.
-* globalThis guarantees a single instance regardless of duplication.
-*
-* This workaround will be removed when Rolldown ships `format: 'app'`
-* (module registry format that deduplicates like webpack/Turbopack).
-* See design/27-chunking-strategy.md.
-*
-* See design/19-client-navigation.md §"NavigationContext"
-*/
-/**
-* 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.
-*
-* Context instances are stored on globalThis (NOT in module-level
-* variables) because the ESM bundler can duplicate this module across
-* chunks. Module-level variables would create separate instances per
-* chunk — the provider in TransitionRoot (index chunk) would use
-* context A while the consumer in LinkStatusProvider (shared chunk)
-* reads from context B. globalThis guarantees a single instance.
-*
-* See design/27-chunking-strategy.md §"Singleton Safety"
-*/
-var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
-var PENDING_CTX_KEY = Symbol.for("__timber_pending_nav_ctx");
-function getOrCreateContext() {
-	const existing = globalThis[NAV_CTX_KEY];
-	if (existing !== void 0) return existing;
-	if (typeof React.createContext === "function") {
-		const ctx = React.createContext(null);
-		globalThis[NAV_CTX_KEY] = ctx;
-		return ctx;
-	}
-}
-/**
-* 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.
-*
-* Stored on globalThis (like the context instances above) because the
-* router lives in one chunk while renderRoot lives in another. Module-
-* level variables would be separate per chunk.
-*/
-var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
-function _getNavStateStore() {
-	const g = globalThis;
-	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
-		params: {},
-		pathname: "/"
-	} };
-	return g[NAV_STATE_KEY];
-}
-function setNavigationState(state) {
-	_getNavStateStore().current = state;
-}
-function getNavigationState() {
-	return _getNavStateStore().current;
-}
-/**
-* Separate context for the in-flight navigation URL. Provided by
-* TransitionRoot (urgent useState), consumed by LinkStatusProvider
-* and useNavigationPending.
-*
-* Uses globalThis via Symbol.for for the same reason as NavigationContext
-* above — the bundler may duplicate this module across chunks, and module-
-* level variables would create separate context instances.
-*/
-function getOrCreatePendingContext() {
-	const existing = globalThis[PENDING_CTX_KEY];
-	if (existing !== void 0) return existing;
-	if (typeof React.createContext === "function") {
-		const ctx = React.createContext(null);
-		globalThis[PENDING_CTX_KEY] = ctx;
-		return ctx;
-	}
-}
-/**
-* Read the pending navigation URL from context.
-* Returns null during SSR (no provider) or in the RSC environment.
-*/
-function usePendingNavigationUrl() {
-	const ctx = getOrCreatePendingContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
-}
-//#endregion
-//#region src/client/link-status-provider.tsx
-var NOT_PENDING = { pending: false };
-var IS_PENDING = { pending: true };
-/**
-* 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.
-*/
-function LinkStatusProvider({ href, children }) {
-	const status = usePendingNavigationUrl() === href ? IS_PENDING : NOT_PENDING;
-	return /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
-		value: status,
-		children
-	});
-}
-//#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/link.tsx
+var LINK_PENDING = { isPending: true };
+var LINK_IDLE = { isPending: false };
 /**
-* Reject dangerous URL schemes that could execute script.
-* Security: design/13-security.md § Link scheme injection (test #9)
+* 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.
 */
-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;
+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}` : "";
 }
 /**
 * Interpolate dynamic segments in a route pattern with actual values.
@@ -247,25 +69,73 @@ 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).
+*
+* When schema codecs are registered (via virtual:timber-schema), uses
+* codec.serialize() for URL construction instead of plain String().
+*/
+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;
+			const codec = getLinkCodec(`[[...${seg.name}]]`);
+			if (codec) {
+				const serialized = codec.serialize(value);
+				if (!serialized) return null;
+				return serialized.split("/").map(encodeURIComponent).join("/");
+			}
 			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 codec = getLinkCodec(`[...${seg.name}]`);
+			if (codec) {
+				const serialized = codec.serialize(value);
+				if (!serialized) throw new Error(`<Link> catch-all param "${seg.name}" codec returned null for pattern "${pattern}".`);
+				return serialized.split("/").map(encodeURIComponent).join("/");
+			}
 			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}".`);
+			const codec = getLinkCodec(`[${seg.name}]`);
+			const str = codec ? codec.serialize(value) ?? String(value) : String(value);
+			const encoded = encodeURIComponent(str);
+			const prefix = seg.prefix ?? "";
+			const suffix = seg.suffix ?? "";
+			return prefix + encoded + suffix;
+		}
+	}
+}
+/**
+* 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.
@@ -275,13 +145,41 @@ 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);
-		if (qs) resolvedPath = `${resolvedPath}?${qs}`;
+		let definition;
+		let values;
+		if (isWrappedSearchParamsProp(searchParams)) {
+			definition = searchParams.definition;
+			values = searchParams.values;
+		} else {
+			definition = getSearchParamsDefinition(href);
+			values = searchParams;
+		}
+		if (definition) {
+			const qs = definition.serialize(values);
+			if (qs) resolvedPath = `${resolvedPath}?${qs}`;
+		} else {
+			const usp = new URLSearchParams();
+			for (const [key, val] of Object.entries(values)) {
+				if (val === void 0 || val === null) continue;
+				if (Array.isArray(val)) for (const item of val) usp.append(key, String(item));
+				else usp.set(key, String(val));
+			}
+			const qs = usp.toString();
+			if (qs) resolvedPath = `${resolvedPath}?${qs}`;
+		}
 	}
 	return resolvedPath;
 }
@@ -291,7 +189,7 @@ function resolveHref(href, params, searchParams) {
 */
 function buildLinkProps(props) {
 	const resolvedHref = resolveHref(props.href, props.params, props.searchParams);
-	validateLinkHref(resolvedHref);
+	validateNavigationHref(resolvedHref);
 	return { href: resolvedHref };
 }
 /**
@@ -323,17 +221,26 @@ function shouldInterceptClick(event, resolvedHref) {
 * 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, onClick: userOnClick, onMouseEnter: userOnMouseEnter, children, ...rest }) {
-	const { href: resolvedHref } = 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,
-		params,
+		params: segmentParams,
 		searchParams
 	});
-	const internal = isInternalHref(resolvedHref);
+	const [isPending, startTransition] = useTransition();
+	const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
+	const internal = isInternalHref(baseHref);
+	const resolvedHref = preserveSearchParams && internal ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
 	const handleClick = internal ? (event) => {
 		userOnClick?.(event);
 		if (!shouldInterceptClick(event, resolvedHref)) return;
@@ -349,828 +256,37 @@ function Link({ href, prefetch, scroll, params, searchParams, onNavigate, onClic
 		}
 		const router = getRouterOrNull();
 		if (!router) return;
+		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+		const resolved = new URL(navHref, window.location.href);
+		if (resolved.pathname === window.location.pathname && resolved.search === window.location.search && resolved.hash) return;
 		event.preventDefault();
 		const shouldScroll = scroll !== false;
-		router.navigate(resolvedHref, { scroll: shouldScroll });
+		const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
+		startTransition(async () => {
+			await router.navigate(absoluteHref, { scroll: shouldScroll });
+		});
 	} : userOnClick;
 	const handleMouseEnter = internal && prefetch ? (event) => {
 		userOnMouseEnter?.(event);
 		const router = getRouterOrNull();
-		if (router) router.prefetch(resolvedHref);
+		if (router) {
+			const prefetchHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+			const resolved = new URL(prefetchHref, window.location.href);
+			router.prefetch(resolved.pathname + resolved.search);
+		}
 	} : userOnMouseEnter;
 	return /* @__PURE__ */ jsx("a", {
 		...rest,
 		href: resolvedHref,
 		onClick: handleClick,
 		onMouseEnter: handleMouseEnter,
-		children: /* @__PURE__ */ jsx(LinkStatusProvider, {
-			href: resolvedHref,
+		children: /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
+			value: linkStatus,
 			children
 		})
 	});
-}
-//#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 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 });
-				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"));
-			});
-		} 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);
-			}
-		}
-	}
-	/**
-	* 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
-	};
-}
-//#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-js/app/client'
-*
-* export function NavBar() {
-*   const isPending = useNavigationPending()
-*   return (
-*     <nav className={isPending ? 'opacity-50' : ''}>
-*       <Link href="/dashboard">Dashboard</Link>
-*     </nav>
-*   )
-* }
-* ```
-*/
-function useNavigationPending() {
-	return usePendingNavigationUrl() !== null;
-}
-//#endregion
 //#region src/client/use-router.ts
 /**
 * useRouter() — client-side hook for programmatic navigation.
@@ -1194,7 +310,7 @@ function useNavigationPending() {
 *
 * 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.
@@ -1216,6 +332,7 @@ function useNavigationPending() {
 function useRouter() {
 	return {
 		push(href, options) {
+			validateNavigationHref(href);
 			const router = getRouterOrNull();
 			if (!router) {
 				if (process.env.NODE_ENV === "development") console.error("[timber] useRouter().push() called but router is not initialized. This is a bug — please report it.");
@@ -1224,6 +341,7 @@ function useRouter() {
 			router.navigate(href, { scroll: options?.scroll });
 		},
 		replace(href, options) {
+			validateNavigationHref(href);
 			const router = getRouterOrNull();
 			if (!router) {
 				if (process.env.NODE_ENV === "development") console.error("[timber] useRouter().replace() called but router is not initialized.");
@@ -1293,95 +411,38 @@ function usePathname() {
 	return "/";
 }
 //#endregion
-//#region src/client/use-search-params.ts
+//#region src/client/navigation-api.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"
+* Returns true if the Navigation API is available in the current environment.
+* Feature-detected at runtime — no polyfill.
 */
-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();
+function hasNavigationApi() {
+	return typeof window !== "undefined" && "navigation" in window && window.navigation != null;
 }
 /**
-* Read the current URL search params.
-*
-* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+* Get the Navigation API instance. Returns null if unavailable.
 */
-function useSearchParams() {
-	useSyncExternalStore(subscribe, getSearch, getServerSearch);
-	return typeof window !== "undefined" ? getSearchParams() : getServerSearchParams();
+function getNavigationApi() {
+	if (!hasNavigationApi()) return null;
+	return window.navigation;
 }
 //#endregion
-//#region src/client/segment-context.ts
+//#region src/client/shallow-url.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.
+* Shallow URL replacement — update the browser URL bar without triggering
+* RSC navigation, TopLoader, or any server round-trip.
 *
-* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+* Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+* which the navigate event handler intercepts with a no-op handler. Falls back
+* to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
 */
-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);
+function replaceUrl(url) {
+	const nav = getNavigationApi();
+	if (nav) nav.navigate(url, {
+		history: "replace",
+		info: { shallow: true }
+	});
+	else history.replaceState(history.state, "", url);
 }
 //#endregion
 //#region src/client/use-selected-layout-segment.ts
@@ -1514,7 +575,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).
@@ -1540,27 +607,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: [],
@@ -1589,6 +640,6 @@ 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 };
+export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, replaceUrl, resolveHref, useActionState, useFormAction, useLinkStatus, usePathname, usePendingNavigation, useRouter, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateNavigationHref as validateLinkHref };
 
 //# sourceMappingURL=index.js.map