@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.35

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 { 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-TYEQJZ1-.js";
+import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-Dpq2XOKg.js";
+import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-BvW0TKDn.js";
+import { t as _registerUseCookieModule } from "../_chunks/define-cookie-w5GWm_bL.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();
@@ -324,13 +325,13 @@ 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 }) {
+function Link({ href, prefetch, scroll, segmentParams, searchParams, onNavigate, onClick: userOnClick, onMouseEnter: userOnMouseEnter, children, ...rest }) {
 	const { href: resolvedHref } = buildLinkProps({
 		href,
-		params,
+		params: segmentParams,
 		searchParams
 	});
 	const internal = isInternalHref(resolvedHref);
@@ -520,7 +521,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 +760,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 +836,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 +859,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 +889,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 +934,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 +957,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 +974,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 +1007,7 @@ function createRouter(deps) {
 					headElements: result.headElements,
 					params: result.params
 				});
-				return wrapPayload(merged);
+				return wrapPayload(merged, result.navState);
 			});
 			return headElements;
 		}
@@ -989,7 +1018,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 +1031,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 +1067,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 +1085,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 +1110,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 +1123,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 +1160,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 +1174,7 @@ function createRouter(deps) {
 				payload: merged,
 				headElements
 			});
-			renderPayload(merged);
+			renderPayload(merged, getNavigationState());
 			applyHead(headElements);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
@@ -1354,36 +1397,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 +1602,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, resolveHref, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useActionState, useCookie, useFormAction, useFormErrors, useLinkStatus, useNavigationPending, usePathname, useQueryStates, useRouter, useSearchParams, useSegmentContext, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateLinkHref };
 
 //# sourceMappingURL=index.js.map