@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/dist/client/index.js

@@ -1,9 +1,11 @@
 "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 { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
+import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-DAhgj8Gx.js";
+import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-hzuJ048X.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-D9hzsveV.js";
+import { t as _registerUseCookieModule } from "../_chunks/define-cookie-B5mewxwM.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,13 +42,85 @@ function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
 //#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-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;
+}
+/**
+* Store metadata from Link's onClick for the next navigate event.
+* Called synchronously in the click handler — the navigate event
+* fires synchronously after onClick returns.
+*/
+function setNavLinkMetadata(metadata) {}
+//#endregion
 //#region src/client/navigation-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(),
+* 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.
@@ -87,8 +161,8 @@ function useLinkStatus() {
 * 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)
+* chunk — the provider in NavigationRoot (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"
@@ -107,7 +181,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();
@@ -156,8 +230,9 @@ function getNavigationState() {
 }
 /**
 * Separate context for the in-flight navigation URL. Provided by
-* TransitionRoot (urgent useState), consumed by LinkStatusProvider
-* and useNavigationPending.
+* NavigationRoot (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-
@@ -183,48 +258,90 @@ function usePendingNavigationUrl() {
 	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
-	});
-}
+//#region src/client/top-loader.tsx
+/**
+* TopLoader — Built-in progress bar for client navigations.
+*
+* Shows an animated progress bar at the top of the viewport while an RSC
+* navigation is in flight. Injected automatically by the framework into
+* NavigationRoot — users never render this component directly.
+*
+* Configuration is via timber.config.ts `topLoader` key. Enabled by default.
+* Users who want a fully custom progress indicator disable the built-in one
+* (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+*
+* Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+* width over ~30s using ease-out timing. When navigation completes, the bar
+* snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+*
+* Phase transitions are derived synchronously during render (React's
+* getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+* The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+*
+* When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+* stays invisible during the delay period. If navigation finishes before the
+* delay, the bar was never visible so the finish transition is also invisible.
+*
+* See design/19-client-navigation.md §"useNavigationPending()"
+* See LOCAL-336 for design decisions.
+*/
 //#endregion
-//#region src/client/router-ref.ts
+//#region src/client/navigation-root.tsx
 /**
-* Set the global router instance. Called once during bootstrap.
+* Module-level flag indicating a hard (MPA) navigation is in progress.
+*
+* When true:
+* - NavigationRoot throws an unresolved thenable to suspend forever,
+*   preventing React from rendering children during page teardown
+*   (avoids "Rendered more hooks" crashes).
+* - The Navigation API handler skips interception, letting the browser
+*   perform a full page load (prevents infinite loops where
+*   window.location.href → navigate event → router.navigate → 500 →
+*   window.location.href → ...).
+*
+* Uses globalThis for singleton guarantee across chunks (same pattern
+* as NavigationContext). See design/19-client-navigation.md §"Singleton
+* Guarantee via globalThis".
 */
-function setGlobalRouter(router) {
-	_setGlobalRouter(router);
+var HARD_NAV_KEY = Symbol.for("__timber_hard_navigating");
+function getHardNavStore() {
+	const g = globalThis;
+	if (!g[HARD_NAV_KEY]) g[HARD_NAV_KEY] = { value: false };
+	return g[HARD_NAV_KEY];
 }
 /**
-* Get the global router instance. Throws if called before bootstrap.
-* Used by client-side hooks (useNavigationPending, etc.)
+* Set the hard-navigating flag. Call this BEFORE setting
+* window.location.href or window.location.reload() to prevent:
+* 1. React from rendering children during page teardown
+* 2. Navigation API from intercepting the hard navigation
 */
-function getRouter() {
-	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
-	return globalRouter;
+function setHardNavigating(value) {
+	getHardNavStore().value = value;
 }
+//#endregion
+//#region src/client/navigation-api.ts
 /**
-* 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.
+* Returns true if the Navigation API is available in the current environment.
+* Feature-detected at runtime — no polyfill.
 */
-function getRouterOrNull() {
-	return globalRouter;
+function hasNavigationApi() {
+	return typeof window !== "undefined" && "navigation" in window && window.navigation != 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)
 */
@@ -247,25 +364,53 @@ function isInternalHref(href) {
 * - [...param]       → catch-all (joined with /)
 * - [[...param]]     → optional catch-all (omitted if undefined/empty)
 */
-function interpolateParams(pattern, params) {
-	return pattern.replace(/\[\[\.\.\.(\w+)\]\]|\[\.\.\.(\w+)\]|\[(\w+)\]/g, (_match, optionalCatchAll, catchAll, single) => {
-		if (optionalCatchAll) {
-			const value = params[optionalCatchAll];
-			if (value === void 0 || Array.isArray(value) && value.length === 0) return "";
+/**
+* Parse a route pattern's path portion into classified segments.
+* Exported for testing. Uses the shared character-based classifier.
+*/
+function parseSegments(pattern) {
+	return pattern.split("/").filter(Boolean).map(classifyUrlSegment);
+}
+/**
+* Resolve a single classified segment into its string representation.
+* Returns null for optional catch-all with no value (filtered out before join).
+*/
+function resolveSegment(seg, params, pattern) {
+	switch (seg.kind) {
+		case "static": return seg.value;
+		case "optional-catch-all": {
+			const value = params[seg.name];
+			if (value === void 0 || Array.isArray(value) && value.length === 0) return null;
 			return (Array.isArray(value) ? value : [value]).map(encodeURIComponent).join("/");
 		}
-		if (catchAll) {
-			const value = params[catchAll];
-			if (value === void 0) throw new Error(`<Link> missing required catch-all param "${catchAll}" for pattern "${pattern}".`);
+		case "catch-all": {
+			const value = params[seg.name];
+			if (value === void 0) throw new Error(`<Link> missing required catch-all param "${seg.name}" for pattern "${pattern}".`);
 			const segments = Array.isArray(value) ? value : [value];
-			if (segments.length === 0) throw new Error(`<Link> catch-all param "${catchAll}" must have at least one segment for pattern "${pattern}".`);
+			if (segments.length === 0) throw new Error(`<Link> catch-all param "${seg.name}" must have at least one segment for pattern "${pattern}".`);
 			return segments.map(encodeURIComponent).join("/");
 		}
-		const value = params[single];
-		if (value === void 0) throw new Error(`<Link> missing required param "${single}" for pattern "${pattern}".`);
-		if (Array.isArray(value)) throw new Error(`<Link> param "${single}" expected a string but received an array for pattern "${pattern}".`);
-		return encodeURIComponent(String(value));
-	}).replace(/\/+$/, "") || "/";
+		case "dynamic": {
+			const value = params[seg.name];
+			if (value === void 0) throw new Error(`<Link> missing required param "${seg.name}" for pattern "${pattern}".`);
+			if (Array.isArray(value)) throw new Error(`<Link> param "${seg.name}" expected a string but received an array for pattern "${pattern}".`);
+			return encodeURIComponent(String(value));
+		}
+	}
+}
+/**
+* Split a URL pattern into the path portion and any trailing ?query/#hash suffix.
+* Uses URL parsing for correctness rather than manual index arithmetic.
+*/
+function splitPatternSuffix(pattern) {
+	if (!pattern.includes("?") && !pattern.includes("#")) return [pattern, ""];
+	const url = new URL(pattern, "http://x");
+	const suffix = url.search + url.hash;
+	return [pattern.slice(0, pattern.length - suffix.length), suffix];
+}
+function interpolateParams(pattern, params) {
+	const [pathPart, suffix] = splitPatternSuffix(pattern);
+	return ("/" + parseSegments(pathPart).map((seg) => resolveSegment(seg, params, pattern)).filter((s) => s !== null).join("/") || "/") + suffix;
 }
 /**
 * Resolve the final href string from Link props.
@@ -323,16 +468,33 @@ 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 [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);
@@ -349,26 +511,39 @@ function Link({ href, prefetch, scroll, params, searchParams, onNavigate, onClic
 		}
 		const router = getRouterOrNull();
 		if (!router) return;
-		event.preventDefault();
 		const shouldScroll = scroll !== false;
-		router.navigate(resolvedHref, { scroll: shouldScroll });
+		setLinkStatus(PENDING_LINK_STATUS);
+		setLinkForCurrentNavigation(linkInstanceRef.current);
+		if (hasNavigationApi()) {
+			setNavLinkMetadata({
+				scroll: shouldScroll,
+				linkInstance: linkInstanceRef.current
+			});
+			return;
+		}
+		event.preventDefault();
+		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
+		router.navigate(navHref, { scroll: shouldScroll });
 	} : userOnClick;
 	const handleMouseEnter = internal && prefetch ? (event) => {
 		userOnMouseEnter?.(event);
 		const router = getRouterOrNull();
-		if (router) 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
 		})
 	});
-}
+};
 //#endregion
 //#region src/client/segment-cache.ts
 /**
@@ -482,18 +657,38 @@ var PrefetchCache = class PrefetchCache {
 * 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.
+* Supports two keying modes:
+* - **URL-keyed** (default): entries keyed by pathname + search.
+*   Used with the History API fallback.
+* - **Entry-key + URL**: when the Navigation API is available,
+*   entries can also be stored by Navigation entry key for
+*   disambiguation of duplicate URLs in the history stack.
+*   Falls back to URL lookup when entry key is not found.
+*
+* Scroll positions are stored in history.state or Navigation API entry
+* state, 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) {
+	/** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
+	entryKeyMap = /* @__PURE__ */ new Map();
+	push(url, entry, entryKey) {
 		this.entries.set(url, entry);
+		if (entryKey) this.entryKeyMap.set(entryKey, entry);
 	}
-	get(url) {
+	/**
+	* Get an entry. When an entry key is provided (Navigation API),
+	* tries the entry-key map first for accurate disambiguation of
+	* duplicate URLs, then falls back to URL lookup.
+	*/
+	get(url, entryKey) {
+		if (entryKey) {
+			const byKey = this.entryKeyMap.get(entryKey);
+			if (byKey) return byKey;
+		}
 		return this.entries.get(url);
 	}
 	has(url) {
@@ -520,7 +715,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 +954,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 +1030,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 +1053,34 @@ 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 an error for an RSC payload request.
+* The server sends X-Timber-Error header and a JSON body instead of a
+* broken RSC stream for any RenderError (4xx or 5xx). 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).
@@ -847,21 +1088,24 @@ var RedirectError = class extends Error {
 * 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) {
+async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 	const rscUrl = appendRscParam(url);
 	const headers = buildRscHeaders(stateTree, currentUrl);
 	if (deps.decodeRsc) {
 		const fetchPromise = deps.fetch(rscUrl, {
 			headers,
-			redirect: "manual"
+			redirect: "manual",
+			signal
 		});
 		let headElements = null;
 		let segmentInfo = null;
 		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") throw new ServerErrorResponse(response.status, url);
 			headElements = extractHeadElements(response);
 			segmentInfo = extractSegmentInfo(response);
 			params = extractParams(response);
@@ -879,7 +1123,8 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 	}
 	const response = await deps.fetch(rscUrl, {
 		headers,
-		redirect: "manual"
+		redirect: "manual",
+		signal
 	});
 	if (response.status >= 300 && response.status < 400) {
 		const location = response.headers.get("Location");
@@ -904,23 +1149,34 @@ 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();
+	let currentNavAbort = null;
+	/**
+	* Create a new AbortController for a navigation, aborting any
+	* previous in-flight navigation. Optionally links to an external
+	* signal (e.g., from the Navigation API's NavigateEvent.signal).
+	*/
+	function createNavAbort(externalSignal) {
+		currentNavAbort?.abort();
+		const controller = new AbortController();
+		currentNavAbort = controller;
+		if (externalSignal) if (externalSignal.aborted) controller.abort();
+		else externalSignal.addEventListener("abort", () => controller.abort(), { once: true });
+		return controller;
+	}
 	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 +1186,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 +1203,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 +1236,7 @@ function createRouter(deps) {
 					headElements: result.headElements,
 					params: result.params
 				});
-				return wrapPayload(merged);
+				return wrapPayload(merged, result.navState);
 			});
 			return headElements;
 		}
@@ -989,7 +1247,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 +1260,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.
 	*/
@@ -1017,87 +1285,130 @@ function createRouter(deps) {
 		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);
+			result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname, options.signal);
+		}
+		if (!options.skipHistory) {
+			deps.setRouterNavigating?.(true);
+			if (options.replace) deps.replaceState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			else deps.pushState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			deps.setRouterNavigating?.(false);
 		}
-		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;
+		const navState = updateNavigationState(result.params, url);
+		return {
+			...result,
+			navState
+		};
 	}
 	async function navigate(url, options = {}) {
 		const scroll = options.scroll !== false;
 		const replace = options.replace === true;
+		const externalSignal = options._signal;
+		const skipHistory = options._skipHistory === true;
+		const navAbort = createNavAbort(externalSignal);
 		const currentScrollY = deps.getScrollY();
-		deps.replaceState({
+		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
+		else deps.replaceState({
 			timber: true,
 			scrollY: currentScrollY
 		}, "", deps.getCurrentUrl());
+		let effectiveSkipHistory = skipHistory;
+		if (!skipHistory && deps.navigationNavigate) {
+			deps.setRouterNavigating?.(true);
+			deps.navigationNavigate(url, replace);
+			deps.setRouterNavigating?.(false);
+			effectiveSkipHistory = true;
+		}
 		setPending(true, url);
 		try {
-			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, { replace })));
+			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, {
+				replace,
+				signal: navAbort.signal,
+				skipHistory: effectiveSkipHistory
+			})));
 			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) {
+				setHardNavigating(true);
+				const { triggerStaleReload } = await import("../_chunks/stale-reload-BLUC_Pl_.js");
+				triggerStaleReload();
+				return new Promise(() => {});
+			}
 			if (error instanceof RedirectError) {
 				setPending(false);
+				deps.completeRouterNavigation?.();
 				await navigate(error.redirectUrl, { replace: true });
 				return;
 			}
+			if (error instanceof ServerErrorResponse) {
+				setHardNavigating(true);
+				window.location.href = error.url;
+				return new Promise(() => {});
+			}
 			if (isAbortError(error)) return;
 			throw error;
 		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
 			setPending(false);
+			deps.completeRouterNavigation?.();
 		}
 	}
 	async function refresh() {
 		const currentUrl = deps.getCurrentUrl();
+		const navAbort = createNavAbort();
 		setPending(true, currentUrl);
 		try {
 			applyHead(await renderViaTransition(currentUrl, async () => {
-				const result = await fetchRscPayload(currentUrl, deps);
+				const result = await fetchRscPayload(currentUrl, deps, void 0, void 0, navAbort.signal);
 				updateSegmentCache(result.segmentInfo);
-				updateNavigationState(result.params, currentUrl);
-				return result;
+				const navState = updateNavigationState(result.params, currentUrl);
+				return {
+					...result,
+					navState
+				};
 			}));
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
 		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
 			setPending(false);
+			deps.completeRouterNavigation?.();
 		}
 	}
-	async function handlePopState(url, scrollY = 0) {
+	async function handlePopState(url, scrollY = 0, externalSignal) {
 		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 {
+			const navAbort = createNavAbort(externalSignal);
 			setPending(true, url);
 			try {
 				applyHead(await renderViaTransition(url, async () => {
-					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()));
+					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()), void 0, navAbort.signal);
 					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);
+			} catch (error) {
+				if (isAbortError(error)) return;
+				throw error;
 			} finally {
+				if (currentNavAbort === navAbort) currentNavAbort = null;
 				setPending(false);
 			}
 		}
@@ -1117,8 +1428,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 +1442,7 @@ function createRouter(deps) {
 				payload: merged,
 				headElements
 			});
-			renderPayload(merged);
+			renderPayload(merged, getNavigationState());
 			applyHead(headElements);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
@@ -1354,36 +1665,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 +1870,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, getRouterOrNull, 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