@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/dist/client/error-boundary.js

@@ -1,128 +1,4 @@
 "use client";
 "use client";
-import { n as getSsrData } from "../_chunks/ssr-data-MjmprTmO.js";
-import { Component, createElement } from "react";
-//#region src/client/error-boundary.tsx
-/**
-* Framework-injected React error boundary.
-*
-* Catches errors thrown by children and renders a fallback component
-* with the appropriate props based on error type:
-*   - DenySignal (4xx) → { status, dangerouslyPassData }
-*   - RenderError (5xx) → { error, digest, reset }
-*   - Unhandled error → { error, digest: null, reset }
-*
-* The `status` prop controls which errors this boundary catches:
-*   - Specific code (e.g. 403) → only that status
-*   - Category (400) → any 4xx
-*   - Category (500) → any 5xx
-*   - Omitted → catches everything (error.tsx behavior)
-*
-* See design/10-error-handling.md §"Status-Code Files"
-*/
-var _isUnloading = false;
-if (typeof window !== "undefined") {
-	window.addEventListener("beforeunload", () => {
-		_isUnloading = true;
-	});
-	window.addEventListener("pagehide", () => {
-		_isUnloading = true;
-	});
-}
-var TimberErrorBoundary = class extends Component {
-	constructor(props) {
-		super(props);
-		this.state = {
-			hasError: false,
-			error: null
-		};
-	}
-	static getDerivedStateFromError(error) {
-		if (_isUnloading) return {
-			hasError: false,
-			error: null
-		};
-		return {
-			hasError: true,
-			error
-		};
-	}
-	componentDidUpdate(prevProps) {
-		if (this.state.hasError && prevProps.children !== this.props.children) this.setState({
-			hasError: false,
-			error: null
-		});
-	}
-	/** Reset the error state so children re-render. */
-	reset = () => {
-		this.setState({
-			hasError: false,
-			error: null
-		});
-	};
-	render() {
-		if (!this.state.hasError || !this.state.error) return this.props.children;
-		const error = this.state.error;
-		const parsed = parseDigest(error);
-		if (parsed?.type === "redirect") throw error;
-		if (this.props.status != null) {
-			const errorStatus = getErrorStatus(parsed, error);
-			if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) throw error;
-		}
-		if (parsed?.type === "deny" && this.props.isSlotBoundary) {
-			const ssrData = getSsrData();
-			if (ssrData?._navContext) ssrData._navContext._denyHandledByBoundary = true;
-		}
-		if (parsed?.type === "deny") return createElement(this.props.fallbackComponent, {
-			status: parsed.status,
-			dangerouslyPassData: parsed.data
-		});
-		const digest = parsed?.type === "render-error" ? {
-			code: parsed.code,
-			data: parsed.data
-		} : null;
-		return createElement(this.props.fallbackComponent, {
-			error,
-			digest,
-			reset: this.reset
-		});
-	}
-};
-/**
-* Parse the structured digest from the error.
-* React sets `error.digest` from the string returned by RSC's onError.
-*/
-function parseDigest(error) {
-	const raw = error.digest;
-	if (typeof raw !== "string") return null;
-	try {
-		const parsed = JSON.parse(raw);
-		if (parsed && typeof parsed === "object" && typeof parsed.type === "string") return parsed;
-	} catch {}
-	return null;
-}
-/**
-* Extract the HTTP status code from a parsed digest or error message.
-* Falls back to message pattern matching for errors without a digest.
-*/
-function getErrorStatus(parsed, error) {
-	if (parsed?.type === "deny") return parsed.status;
-	if (parsed?.type === "render-error") return parsed.status;
-	if (parsed?.type === "redirect") return parsed.status;
-	const match = error.message.match(/^Access denied with status (\d+)$/);
-	if (match) return parseInt(match[1], 10);
-	return 500;
-}
-/**
-* Check whether an error's status matches the boundary's status filter.
-* Category markers (400, 500) match any status in that range.
-*/
-function statusMatches(boundaryStatus, errorStatus) {
-	if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;
-	if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;
-	return boundaryStatus === errorStatus;
-}
-//#endregion
+import { t as TimberErrorBoundary } from "../_chunks/error-boundary-BAN3751q.js";
 export { TimberErrorBoundary };
-
-//# sourceMappingURL=error-boundary.js.map

package/dist/client/index.d.ts

@@ -1,9 +1,10 @@
 export type { JsonSerializable, RenderErrorDigest } from './types';
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
+export { mergePreservedSearchParams } from '#/shared/merge-search-params.js';
 export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
 export type { OnNavigateHandler, OnNavigateEvent } from './link';
 export { createRouter } from './router';
-export type { RouterInstance, NavigationOptions, RouterDeps, RscDecoder, RootRenderer, } from './router';
+export type { RouterInstance, NavigationOptions, RouterDeps, RouterPhase, RscDecoder, RootRenderer, } from './router';
 export { useNavigationPending } from './use-navigation-pending';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
@@ -21,7 +22,7 @@ export { HistoryStack } from './history';
 export type { HistoryEntry } from './history';
 export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
-export { useParams, setCurrentParams } from './use-params';
+export { useSegmentParams, setCurrentParams } from './use-params';
 export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
 export type { NavigationState } from './navigation-context';
 export { useQueryStates, bindUseQueryStates } from './use-query-states';

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAChF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGvF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClG,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGtE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAChG,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAChF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAGpG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClG,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAUtE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC"}

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 useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-C6byCyZU.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-BAN3751q.js";
+import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-BvW0TKDn.js";
+import { t as _registerUseCookieModule } from "../_chunks/define-cookie-BmKbSyp0.js";
+import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -46,7 +47,7 @@ function useLinkStatus() {
 *
 * 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(),
+* 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.
@@ -107,7 +108,7 @@ function getOrCreateContext() {
 /**
 * Read the navigation context. Returns null during SSR (no provider)
 * or in the RSC environment (no context available).
-* Internal — used by useParams() and usePathname().
+* Internal — used by useSegmentParams() and usePathname().
 */
 function useNavigationContext() {
 	const ctx = getOrCreateContext();
@@ -225,6 +226,18 @@ function getRouterOrNull() {
 //#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 +337,16 @@ 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 resolvedHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : baseHref;
 	const internal = isInternalHref(resolvedHref);
 	const handleClick = internal ? (event) => {
 		userOnClick?.(event);
@@ -351,12 +365,16 @@ 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;
+		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,
@@ -520,7 +538,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 +777,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 +853,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 +876,16 @@ 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");
+	}
+};
+/**
 * 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,6 +906,7 @@ 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);
 			headElements = extractHeadElements(response);
@@ -904,23 +951,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 +974,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 +991,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 +1024,7 @@ function createRouter(deps) {
 					headElements: result.headElements,
 					params: result.params
 				});
-				return wrapPayload(merged);
+				return wrapPayload(merged, result.navState);
 			});
 			return headElements;
 		}
@@ -989,7 +1035,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 +1048,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 +1084,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,12 +1102,13 @@ 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-C0ValzG7.js");
+				triggerStaleReload();
+				return new Promise(() => {});
+			}
 			if (error instanceof RedirectError) {
 				setPending(false);
 				await navigate(error.redirectUrl, { replace: true });
@@ -1067,8 +1127,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 +1140,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 +1177,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 +1191,7 @@ function createRouter(deps) {
 				payload: merged,
 				headElements
 			});
-			renderPayload(merged);
+			renderPayload(merged, getNavigationState());
 			applyHead(headElements);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
@@ -1354,36 +1414,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 +1619,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