@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/dist/client/index.js

@@ -1,9 +1,10 @@
 "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 __exportAll } from "../_chunks/chunk-DYhsFzuS.js";
+import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-wEXY2JQB.js";
+import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-CyaM1mrD.js";
+import { a as _setCachedSearch, c as cachedSearch, d as globalRouter, i as setSsrData, l as cachedSearchParams, n as clearSsrData, o as _setCurrentParams, r as getSsrData, s as _setGlobalRouter, t as TimberErrorBoundary, u as currentParams } from "../_chunks/error-boundary-DpZJBCqh.js";
+import { t as _registerUseCookieModule } from "../_chunks/define-cookie-BWr_52kY.js";
+import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useEffect, useRef, useState, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -40,165 +41,6 @@ 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.
@@ -223,8 +65,62 @@ function getRouterOrNull() {
 	return globalRouter;
 }
 //#endregion
+//#region src/client/link-pending-store.ts
+var LINK_PENDING_KEY = Symbol.for("__timber_link_pending");
+/** Status object indicating link is pending — shared reference */
+var PENDING_LINK_STATUS = { pending: true };
+/** Status object indicating link is idle — shared reference */
+var IDLE_LINK_STATUS = { pending: false };
+function getStore() {
+	const g = globalThis;
+	if (!g[LINK_PENDING_KEY]) g[LINK_PENDING_KEY] = {
+		current: null,
+		navId: 0
+	};
+	return g[LINK_PENDING_KEY];
+}
+/**
+* Register the link instance that initiated the current navigation.
+*
+* Called from <Link>'s click handler before router.navigate().
+* - Resets the previous pending link to IDLE (urgent update, immediate)
+* - Does NOT set the new link to PENDING here — the Link's click handler
+*   calls setLinkStatus(PENDING) directly for the eager show
+* - Increments the navId counter for stale-clear protection
+*
+* Pass `null` to clear (e.g., for programmatic navigations).
+*/
+function setLinkForCurrentNavigation(link) {
+	const store = getStore();
+	const prev = store.current;
+	if (prev && prev !== link) prev.setLinkStatus(IDLE_LINK_STATUS);
+	store.current = link;
+	store.navId++;
+}
+/**
+* Unmount a link instance from navigation tracking. Called when a Link
+* component unmounts while it is the current navigation link. Prevents
+* calling setState on an unmounted component.
+*/
+function unmountLinkForCurrentNavigation(link) {
+	const store = getStore();
+	if (store.current === link) store.current = null;
+}
+//#endregion
 //#region src/client/link.tsx
 /**
+* 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 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}` : "";
+}
+/**
 * Reject dangerous URL schemes that could execute script.
 * Security: design/13-security.md § Link scheme injection (test #9)
 */
@@ -324,15 +220,26 @@ function shouldInterceptClick(event, resolvedHref) {
 * its own click handling.
 *
 * Supports typed routes via codegen overloads. At runtime:
-* - `params` prop interpolates dynamic segments in the href pattern
+* - `segmentParams` prop interpolates dynamic segments in the href pattern
 * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
 */
-function Link({ href, prefetch, scroll, params, searchParams, onNavigate, onClick: userOnClick, onMouseEnter: userOnMouseEnter, children, ...rest }) {
-	const { href: resolvedHref } = buildLinkProps({
+function Link({ href, prefetch, scroll, segmentParams, searchParams, preserveSearchParams, onNavigate, onClick: userOnClick, onMouseEnter: userOnMouseEnter, children, ...rest }) {
+	const { href: baseHref } = buildLinkProps({
 		href,
-		params,
+		params: segmentParams,
 		searchParams
 	});
+	const [linkStatus, setLinkStatus] = useState(IDLE_LINK_STATUS);
+	const linkInstanceRef = useRef(null);
+	if (!linkInstanceRef.current) linkInstanceRef.current = { setLinkStatus };
+	else linkInstanceRef.current.setLinkStatus = setLinkStatus;
+	useEffect(() => {
+		const instance = linkInstanceRef.current;
+		return () => {
+			if (instance) unmountLinkForCurrentNavigation(instance);
+		};
+	}, []);
+	const resolvedHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
 	const internal = isInternalHref(resolvedHref);
 	const handleClick = internal ? (event) => {
 		userOnClick?.(event);
@@ -351,20 +258,26 @@ function Link({ href, prefetch, scroll, params, searchParams, onNavigate, onClic
 		if (!router) return;
 		event.preventDefault();
 		const shouldScroll = scroll !== false;
-		router.navigate(resolvedHref, { scroll: shouldScroll });
+		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+		setLinkStatus(PENDING_LINK_STATUS);
+		setLinkForCurrentNavigation(linkInstanceRef.current);
+		router.navigate(navHref, { 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;
+			router.prefetch(prefetchHref);
+		}
 	} : 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
 		})
 	});
@@ -501,6 +414,150 @@ var HistoryStack = class {
 	}
 };
 //#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 useSegmentParams() 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 useNavigationPending (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 useSegmentParams() 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 useNavigationPending
+* and TopLoader. Per-link pending state uses useOptimistic instead
+* (see link-pending-store.ts).
+*
+* 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/use-params.ts
 /**
 * Set the current route params in the module-level store.
@@ -520,7 +577,7 @@ var HistoryStack = class {
 function setCurrentParams(params) {
 	_setCurrentParams(params);
 }
-function useParams(_route) {
+function useSegmentParams(_route) {
 	try {
 		const navContext = useNavigationContext();
 		if (navContext !== null) return navContext.params;
@@ -759,10 +816,28 @@ function generateCacheBustId() {
 function appendRscParam(url) {
 	return `${url}${url.includes("?") ? "&" : "?"}_rsc=${generateCacheBustId()}`;
 }
+/**
+* The client's deployment ID, set at bootstrap from the runtime config.
+* Sent with every RSC/action request for version skew detection.
+* Null in dev mode. See TIM-446.
+*/
+var clientDeploymentId = null;
+/** Header name used by the server to signal a version skew reload. */
+var RELOAD_HEADER = "X-Timber-Reload";
+/** Header name for the client's deployment ID. */
+var DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
+/**
+* Check if a response signals a version skew reload.
+* Triggers a full page reload if the server indicates the client is stale.
+*/
+function checkReloadSignal(response) {
+	return response.headers.get(RELOAD_HEADER) === "1";
+}
 function buildRscHeaders(stateTree, currentUrl) {
 	const headers = { Accept: RSC_CONTENT_TYPE };
 	if (stateTree) headers["X-Timber-State-Tree"] = JSON.stringify(stateTree);
 	if (currentUrl) headers["X-Timber-URL"] = currentUrl;
+	if (clientDeploymentId) headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
 	return headers;
 }
 /**
@@ -817,7 +892,7 @@ function extractSkippedSegments(response) {
 * 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.
+* Used to populate useSegmentParams() after client-side navigation.
 */
 function extractParams(response) {
 	const header = response.headers.get("X-Timber-Params");
@@ -840,6 +915,33 @@ var RedirectError = class extends Error {
 	}
 };
 /**
+* Thrown when the server signals a version skew (X-Timber-Reload header).
+* Caught in navigate() to trigger a full page reload via triggerStaleReload().
+* See TIM-446.
+*/
+var VersionSkewError = class extends Error {
+	constructor() {
+		super("Version skew detected — server has been redeployed");
+	}
+};
+/**
+* Thrown when the server returns a 5xx error for an RSC payload request.
+* The server sends X-Timber-Error header and a JSON body instead of a
+* broken RSC stream. Caught in navigate() to trigger a hard navigation
+* so the server can render the error page as HTML.
+*
+* See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+*/
+var ServerErrorResponse = class extends Error {
+	status;
+	url;
+	constructor(status, url) {
+		super(`Server error ${status} during navigation to ${url}`);
+		this.status = status;
+		this.url = url;
+	}
+};
+/**
 * Fetch an RSC payload from the server. If a decodeRsc function is provided,
 * the response is decoded into a React element tree via createFromFetch.
 * Otherwise, the raw response text is returned (test mode).
@@ -860,8 +962,10 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 		let params = null;
 		let skippedSegments = null;
 		const wrappedPromise = fetchPromise.then((response) => {
+			if (checkReloadSignal(response)) throw new VersionSkewError();
 			const redirectLocation = response.headers.get("X-Timber-Redirect") || (response.status >= 300 && response.status < 400 ? response.headers.get("Location") : null);
 			if (redirectLocation) throw new RedirectError(redirectLocation);
+			if (response.headers.get("X-Timber-Error") === "1" && response.status >= 500) throw new ServerErrorResponse(response.status, url);
 			headElements = extractHeadElements(response);
 			segmentInfo = extractSegmentInfo(response);
 			params = extractParams(response);
@@ -904,23 +1008,20 @@ function isAbortError(error) {
 	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;
+	let routerPhase = { phase: "idle" };
 	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;
+		const next = value && url ? {
+			phase: "navigating",
+			targetUrl: url
+		} : { phase: "idle" };
+		if (routerPhase.phase === next.phase && (routerPhase.phase === "idle" || routerPhase.phase === "navigating" && next.phase === "navigating" && routerPhase.targetUrl === next.targetUrl)) return;
+		routerPhase = next;
 		for (const listener of pendingListeners) listener(value);
 	}
 	/** Update the segment cache from server-provided segment metadata. */
@@ -930,8 +1031,8 @@ function createRouter(deps) {
 		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);
+	function renderPayload(payload, navState) {
+		if (deps.renderRoot) deps.renderRoot(payload, navState);
 	}
 	/**
 	* Merge a partial RSC payload with cached segment elements if segments
@@ -947,24 +1048,26 @@ function createRouter(deps) {
 	/**
 	* 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.
+	* Sets the module-level fallback (for tests and SSR) and the
+	* globalThis bridge, then returns the NavigationState so callers
+	* can pass it explicitly to renderRoot/wrapPayload — eliminating
+	* temporal coupling with getNavigationState().
 	*/
 	function updateNavigationState(params, url) {
 		const resolvedParams = params ?? {};
 		setCurrentParams(resolvedParams);
-		setNavigationState({
+		const navState = {
 			params: resolvedParams,
 			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
-		});
+		};
+		setNavigationState(navState);
+		return navState;
 	}
 	/**
 	* Render a payload via navigateTransition (production) or renderRoot (tests).
-	* The perform callback should fetch data, update state, and return the payload.
-	* In production, the entire callback runs inside a React transition with
-	* useOptimistic for the pending URL. In tests, the payload is rendered directly.
+	* The perform callback should fetch data, update state, and return the
+	* FetchResult plus the NavigationState (so it can be passed explicitly
+	* to wrapPayload/renderRoot without temporal coupling).
 	*/
 	async function renderViaTransition(url, perform) {
 		if (deps.navigateTransition) {
@@ -978,7 +1081,7 @@ function createRouter(deps) {
 					headElements: result.headElements,
 					params: result.params
 				});
-				return wrapPayload(merged);
+				return wrapPayload(merged, result.navState);
 			});
 			return headElements;
 		}
@@ -989,7 +1092,7 @@ function createRouter(deps) {
 			headElements: result.headElements,
 			params: result.params
 		});
-		renderPayload(merged);
+		renderPayload(merged, result.navState);
 		return result.headElements;
 	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
@@ -1002,6 +1105,16 @@ function createRouter(deps) {
 		else callback();
 	}
 	/**
+	* Schedule scroll restoration after the next paint and fire the
+	* scroll-restored event. Used by navigate, popstate, and refresh.
+	*/
+	function restoreScrollAfterPaint(scrollY) {
+		afterPaint(() => {
+			deps.scrollTo(0, scrollY);
+			window.dispatchEvent(new Event("timber:scroll-restored"));
+		});
+	}
+	/**
 	* Core navigation logic shared between the transition and fallback paths.
 	* Fetches the RSC payload, updates all state, and returns the result.
 	*/
@@ -1028,8 +1141,11 @@ function createRouter(deps) {
 			scrollY: 0
 		}, "", url);
 		updateSegmentCache(result.segmentInfo);
-		updateNavigationState(result.params, url);
-		return result;
+		const navState = updateNavigationState(result.params, url);
+		return {
+			...result,
+			navState
+		};
 	}
 	async function navigate(url, options = {}) {
 		const scroll = options.scroll !== false;
@@ -1043,17 +1159,22 @@ function createRouter(deps) {
 		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"));
-			});
+			restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 		} catch (error) {
+			if (error instanceof VersionSkewError) {
+				const { triggerStaleReload } = await import("../_chunks/stale-reload-BSSym1MJ.js");
+				triggerStaleReload();
+				return new Promise(() => {});
+			}
 			if (error instanceof RedirectError) {
 				setPending(false);
 				await navigate(error.redirectUrl, { replace: true });
 				return;
 			}
+			if (error instanceof ServerErrorResponse) {
+				window.location.href = error.url;
+				return new Promise(() => {});
+			}
 			if (isAbortError(error)) return;
 			throw error;
 		} finally {
@@ -1067,8 +1188,11 @@ function createRouter(deps) {
 			applyHead(await renderViaTransition(currentUrl, async () => {
 				const result = await fetchRscPayload(currentUrl, deps);
 				updateSegmentCache(result.segmentInfo);
-				updateNavigationState(result.params, currentUrl);
-				return result;
+				const navState = updateNavigationState(result.params, currentUrl);
+				return {
+					...result,
+					navState
+				};
 			}));
 		} finally {
 			setPending(false);
@@ -1077,26 +1201,23 @@ function createRouter(deps) {
 	async function handlePopState(url, scrollY = 0) {
 		const entry = historyStack.get(url);
 		if (entry && entry.payload !== null) {
-			updateNavigationState(entry.params, url);
-			renderPayload(entry.payload);
+			const navState = updateNavigationState(entry.params, url);
+			renderPayload(entry.payload, navState);
 			applyHead(entry.headElements);
-			afterPaint(() => {
-				deps.scrollTo(0, scrollY);
-				window.dispatchEvent(new Event("timber:scroll-restored"));
-			});
+			restoreScrollAfterPaint(scrollY);
 		} 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;
+					const navState = updateNavigationState(result.params, url);
+					return {
+						...result,
+						navState
+					};
 				}));
-				afterPaint(() => {
-					deps.scrollTo(0, scrollY);
-					window.dispatchEvent(new Event("timber:scroll-restored"));
-				});
+				restoreScrollAfterPaint(scrollY);
 			} finally {
 				setPending(false);
 			}
@@ -1117,8 +1238,8 @@ function createRouter(deps) {
 		navigate,
 		refresh,
 		handlePopState,
-		isPending: () => pending,
-		getPendingUrl: () => pendingUrl,
+		isPending: () => routerPhase.phase === "navigating",
+		getPendingUrl: () => routerPhase.phase === "navigating" ? routerPhase.targetUrl : null,
 		onPendingChange(listener) {
 			pendingListeners.add(listener);
 			return () => pendingListeners.delete(listener);
@@ -1131,7 +1252,7 @@ function createRouter(deps) {
 				payload: merged,
 				headElements
 			});
-			renderPayload(merged);
+			renderPayload(merged, getNavigationState());
 			applyHead(headElements);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
@@ -1354,36 +1475,6 @@ function useSearchParams() {
 	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
@@ -1589,6 +1680,96 @@ 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({ 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();
+}
+/**
+* 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);
+	const setCookie = (newValue, options) => {
+		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);
+//#endregion
+export { HistoryStack, Link, LinkStatusContext, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, buildLinkProps, clearSsrData, createRouter, getNavigationState, getRouter, getSsrData, interpolateParams, mergePreservedSearchParams, resolveHref, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
 
 //# sourceMappingURL=index.js.map