@ecopages/react-router 0.2.0-alpha.4 → 0.2.0-alpha.7

package/src/router.ts

@@ -20,15 +20,28 @@ import {
 	type ReactNode,
 	type ComponentType,
 	type FC,
+	type RefObject,
 } from 'react';
 import { type EcoRouterOptions, DEFAULT_OPTIONS } from './types.ts';
 import { RouterContext } from './context.ts';
-import { type PageState, getInterceptDecision, loadPageModule, shouldInterceptClick } from './navigation.ts';
+import {
+	type PageState,
+	fetchPageDocument,
+	getInterceptDecision,
+	loadPageModuleFromDocument,
+	shouldInterceptClick,
+} from './navigation.ts';
 import { morphHead } from './head-morpher.ts';
 import { applyViewTransitionNames } from './view-transition-utils.ts';
 import { manageScroll } from './manage-scroll.ts';
 import { saveScrollPositions, restoreScrollPositions } from './scroll-persist.ts';
 import type { EcoInjectedMeta } from '@ecopages/core';
+import { getEcoNavigationRuntime, type EcoNavigationTransaction } from '@ecopages/core/router/navigation-coordinator';
+import {
+	getAnchorFromNavigationEvent,
+	recoverPendingNavigationHref,
+	type EcoPendingNavigationIntent,
+} from '@ecopages/core/router/link-intent';
 
 type PageContextValue = PageState | null;
 
@@ -36,8 +49,21 @@ const PageContext = createContext<PageContextValue>(null);
 
 const PersistLayoutsContext = createContext<boolean>(false);
 
-function getLayoutFromPage(Page: ComponentType<unknown>): ComponentType | undefined {
-	const config = (Page as ComponentType & { config?: { layout?: ComponentType } }).config;
+type LayoutComponent = ComponentType<Record<string, unknown>>;
+
+/**
+ * Reads the optional layout assigned to a page component.
+ *
+ * The router recreates the server-rendered tree on the client, so it needs to
+ * recover the layout reference from page config before rendering `PageContent`.
+ * The returned type is widened to a generic record-based component because
+ * layouts may receive serialized `locals` during hydration.
+ *
+ * @param Page - Hydrated page component.
+ * @returns Configured layout component when present.
+ */
+function getLayoutFromPage(Page: ComponentType<unknown>): LayoutComponent | undefined {
+	const config = (Page as ComponentType & { config?: { layout?: LayoutComponent } }).config;
 	return config?.layout;
 }
 
@@ -62,17 +88,24 @@ export interface EcoRouterProps {
  *
  * Stored on window to persist across module reloads during HMR/SPA navigation.
  */
-function getLayoutCache(): Map<string, ComponentType> {
+function getLayoutCache(): Map<string, LayoutComponent> {
 	if (typeof window === 'undefined') {
 		return new Map();
 	}
-	const win = window as typeof window & { __ecoLayoutCache?: Map<string, ComponentType> };
+	const win = window as typeof window & { __ecoLayoutCache?: Map<string, LayoutComponent> };
 	if (!win.__ecoLayoutCache) {
 		win.__ecoLayoutCache = new Map();
 	}
 	return win.__ecoLayoutCache;
 }
 
+/**
+ * Normalizes a layout cache key so logically identical layouts reuse the same
+ * persistent instance across SPA navigations and HMR cycles.
+ *
+ * @param value - Raw layout identifier, display name, or injected module id.
+ * @returns Stable cache key.
+ */
 function normalizeLayoutKey(value: string): string {
 	const trimmed = value.trim();
 	if (!trimmed) return 'layout';
@@ -96,7 +129,9 @@ export function clearLayoutCache(): void {
  * Renders the current page with its layout.
  *
  * Must be a child of {@link EcoRouter}. When `persistLayouts` is enabled,
- * shared layouts remain mounted across navigations.
+ * shared layouts remain mounted across navigations. When the server serialized
+ * request `locals` for hydration, the same `locals` object is passed to the
+ * layout on the client so the hydrated tree matches SSR.
  *
  * @example
  * ```tsx
@@ -119,6 +154,7 @@ export const PageContent: FC = () => {
 	const { Component: Page, props } = pageContext;
 	const Layout = getLayoutFromPage(Page);
 	const pageElement = createElement(Page, props);
+	const layoutProps = props?.locals ? { locals: props.locals } : null;
 
 	if (!Layout) {
 		return pageElement;
@@ -126,7 +162,7 @@ export const PageContent: FC = () => {
 
 	if (persistLayouts) {
 		const layoutCache = getLayoutCache();
-		const layoutConfig = (Layout as ComponentType & { config?: { __eco?: EcoInjectedMeta } }).config;
+		const layoutConfig = (Layout as LayoutComponent & { config?: { __eco?: EcoInjectedMeta } }).config;
 		const layoutKeyRaw = layoutConfig?.__eco?.id || Layout.displayName || Layout.name || 'layout';
 		const layoutKey = normalizeLayoutKey(layoutKeyRaw);
 
@@ -135,10 +171,10 @@ export const PageContent: FC = () => {
 		}
 		const CachedLayout = layoutCache.get(layoutKey)!;
 
-		return createElement(CachedLayout, { key: layoutKey }, pageElement);
+		return createElement(CachedLayout, { key: layoutKey, ...(layoutProps ?? {}) }, pageElement);
 	}
 
-	return createElement(Layout, null, pageElement);
+	return createElement(Layout, layoutProps, pageElement);
 };
 
 function createDeferred<T>() {
@@ -149,27 +185,65 @@ function createDeferred<T>() {
 	return { promise, resolve };
 }
 
-function useHmrReload(navigate: (url: string) => Promise<void>) {
+type PendingRender = {
+	navigationId: number;
+	page: PageState;
+	resolve: () => void;
+};
+
+function useNavigationCoordinator(
+	navigate: (
+		url: string,
+		options?: { isPopState?: boolean; pushHistory?: boolean; skipViewTransition?: boolean },
+	) => Promise<void>,
+	activeNavigationRef: RefObject<EcoNavigationTransaction | null>,
+	isNavigatingRef: RefObject<boolean>,
+	runtimeActiveRef: RefObject<boolean>,
+) {
 	useEffect(() => {
 		if (typeof window === 'undefined') return;
-		if (import.meta.env?.MODE === 'production' || import.meta.env?.PROD) return;
 
-		const windowWithHmr = window as typeof window & {
-			__ecopages_reload_current_page__?: (options?: { clearCache?: boolean }) => Promise<void>;
-		};
+		const navigationRuntime = getEcoNavigationRuntime(window);
+		let unregisterRuntime: (() => void) | null = null;
+		const unregister = navigationRuntime.register({
+			owner: 'react-router',
+			navigate: async (request) => {
+				await navigate(request.href, {
+					isPopState: request.direction === 'back',
+					pushHistory: request.direction === 'forward',
+					skipViewTransition: request.source === 'browser-router',
+				});
+				return true;
+			},
+			reloadCurrentPage: async (request) => {
+				if (activeNavigationRef.current || isNavigatingRef.current) {
+					return;
+				}
 
-		windowWithHmr.__ecopages_reload_current_page__ = async (options?: { clearCache?: boolean }) => {
-			if (options?.clearCache) {
-				clearLayoutCache();
-			}
-			const currentUrl = window.location.pathname + window.location.search;
-			await navigate(currentUrl);
-		};
+				if (request?.clearCache) {
+					clearLayoutCache();
+				}
 
+				const currentUrl = window.location.pathname + window.location.search;
+				await navigate(currentUrl);
+			},
+			cleanupBeforeHandoff: async () => {
+				runtimeActiveRef.current = false;
+				unregisterRuntime?.();
+				unregisterRuntime = null;
+				window.__ECO_PAGES__?.react?.cleanupPageRoot?.();
+			},
+		});
+		unregisterRuntime = unregister;
+		navigationRuntime.claimOwnership('react-router');
+		runtimeActiveRef.current = true;
 		return () => {
-			windowWithHmr.__ecopages_reload_current_page__ = undefined;
+			runtimeActiveRef.current = false;
+			navigationRuntime.releaseOwnership('react-router');
+			unregisterRuntime?.();
+			unregisterRuntime = null;
 		};
-	}, [navigate]);
+	}, [activeNavigationRef, isNavigatingRef, navigate, runtimeActiveRef]);
 }
 
 /**
@@ -207,11 +281,20 @@ export const EcoRouter: FC<EcoRouterProps> = ({ page, pageProps, options: userOp
 	const options = useMemo(() => ({ ...DEFAULT_OPTIONS, ...userOptions }), [userOptions]);
 	const [currentPage, setCurrentPage] = useState<PageState>({ Component: page, props: pageProps });
 	const [isNavigating, setIsNavigating] = useState(false);
-	const [pendingPage, setPendingPage] = useState<PageState | null>(null);
-	const renderDfd = useRef<{ promise: Promise<void>; resolve: () => void } | null>(null);
+	const pendingRenderRef = useRef<PendingRender | null>(null);
+	const activeNavigationRef = useRef<EcoNavigationTransaction | null>(null);
+	const isNavigatingRef = useRef(false);
+	const runtimeActiveRef = useRef(true);
+	const pendingPointerNavigationRef = useRef<EcoPendingNavigationIntent | null>(null);
+	const pendingHoverNavigationRef = useRef<EcoPendingNavigationIntent | null>(null);
+	const queuedNavigationHrefRef = useRef<string | null>(null);
 	const pendingScrollRestoreRef = useRef<{ url: string; isPopState: boolean } | null>(null);
 	const previousUrlRef = useRef<string>(typeof window !== 'undefined' ? window.location.href : '');
 
+	useEffect(() => {
+		isNavigatingRef.current = isNavigating;
+	}, [isNavigating]);
+
 	useEffect(() => {
 		setCurrentPage({ Component: page, props: pageProps });
 	}, [page, pageProps]);
@@ -221,12 +304,25 @@ export const EcoRouter: FC<EcoRouterProps> = ({ page, pageProps, options: userOp
 	}, [currentPage]);
 
 	useEffect(() => {
-		if (pendingPage && currentPage.Component === pendingPage.Component && renderDfd.current) {
-			renderDfd.current.resolve();
-			renderDfd.current = null;
-			setPendingPage(null);
+		const pendingRender = pendingRenderRef.current;
+		if (
+			pendingRender &&
+			currentPage.Component === pendingRender.page.Component &&
+			currentPage.props === pendingRender.page.props
+		) {
+			pendingRender.resolve();
+			pendingRenderRef.current = null;
 		}
-	}, [currentPage, pendingPage]);
+	}, [currentPage]);
+
+	useEffect(() => {
+		return () => {
+			activeNavigationRef.current?.cancel();
+			pendingRenderRef.current?.resolve();
+			pendingRenderRef.current = null;
+			queuedNavigationHrefRef.current = null;
+		};
+	}, []);
 
 	useEffect(() => {
 		if (typeof window === 'undefined') return;
@@ -250,55 +346,263 @@ export const EcoRouter: FC<EcoRouterProps> = ({ page, pageProps, options: userOp
 	}, [currentPage, options.scrollBehavior, options.smoothScroll]);
 
 	const navigate = useCallback(
-		async (url: string, isPopState = false) => {
-			setIsNavigating(true);
-			const result = await loadPageModule(url);
-
-			if (result) {
-				const { Component, props, doc, finalPath } = result;
-				const nextPage = { Component, props };
-				const cleanupHead = await morphHead(doc);
-				applyViewTransitionNames();
-
-				if (finalPath !== url) {
-					window.history.replaceState(null, '', finalPath);
+		async (
+			url: string,
+			navigationOptions: { isPopState?: boolean; pushHistory?: boolean; skipViewTransition?: boolean } = {},
+		) => {
+			const { isPopState = false, pushHistory = false, skipViewTransition = false } = navigationOptions;
+			const navigationRuntime = getEcoNavigationRuntime(window);
+			const navigation = navigationRuntime.beginNavigationTransaction();
+			activeNavigationRef.current = navigation;
+			const navigationId = navigation.id;
+			const isStale = () => !navigation.isCurrent();
+			const commitPageData = (moduleUrl: string, props: Record<string, unknown>) => {
+				window.__ECO_PAGES__ = window.__ECO_PAGES__ || {};
+				window.__ECO_PAGES__.page = {
+					module: moduleUrl,
+					props,
+				};
+			};
+			let navigationCommitPromise: Promise<void> | null = null;
+
+			try {
+				setIsNavigating(true);
+				const fetchedPage = await fetchPageDocument(url, { signal: navigation.signal });
+
+				if (isStale()) return;
+
+				if (!fetchedPage) {
+					window.location.href = url;
+					return;
 				}
 
-				saveScrollPositions();
-				pendingScrollRestoreRef.current = { url, isPopState };
+				const result = await loadPageModuleFromDocument(fetchedPage.doc, fetchedPage.finalPath);
 
-				if (options.viewTransitions && document.startViewTransition) {
-					renderDfd.current = createDeferred<void>();
-					setPendingPage(nextPage);
+				if (isStale()) return;
+
+				if (result) {
+					const { Component, props, doc, finalPath, moduleUrl } = result;
+					const nextPage = { Component, props };
+					const cleanupHead = await morphHead(doc);
+
+					if (isStale()) {
+						cleanupHead();
+						return;
+					}
+
+					applyViewTransitionNames();
+
+					if (pushHistory) {
+						window.history.pushState(null, '', finalPath);
+					} else if (finalPath !== url) {
+						window.history.replaceState(null, '', finalPath);
+					}
 
-					document.startViewTransition(async () => {
-						startTransition(() => {
-							setCurrentPage(nextPage);
+					saveScrollPositions();
+					pendingScrollRestoreRef.current = { url, isPopState };
+
+					if (!skipViewTransition && options.viewTransitions && document.startViewTransition) {
+						pendingRenderRef.current?.resolve();
+						const renderDfd = createDeferred<void>();
+						pendingRenderRef.current = {
+							navigationId,
+							page: nextPage,
+							resolve: renderDfd.resolve,
+						};
+
+						navigationCommitPromise = new Promise<void>((resolve) => {
+							document.startViewTransition(async () => {
+								try {
+									if (isStale()) {
+										if (pendingRenderRef.current?.navigationId === navigationId) {
+											pendingRenderRef.current.resolve();
+											pendingRenderRef.current = null;
+										}
+										cleanupHead();
+										return;
+									}
+									startTransition(() => {
+										commitPageData(moduleUrl, props);
+										setCurrentPage(nextPage);
+									});
+									await renderDfd.promise;
+									if (isStale()) {
+										return;
+									}
+									cleanupHead();
+									applyViewTransitionNames();
+								} finally {
+									resolve();
+								}
+							});
 						});
-						await renderDfd.current?.promise;
+						await navigationCommitPromise;
+					} else {
+						commitPageData(moduleUrl, props);
+						setCurrentPage(nextPage);
 						cleanupHead();
 						applyViewTransitionNames();
-					});
+					}
 				} else {
-					setCurrentPage(nextPage);
-					cleanupHead();
-					applyViewTransitionNames();
+					if (isStale()) return;
+
+					const handled = await navigationRuntime.requestHandoff({
+						href: url,
+						finalHref: fetchedPage.finalPath,
+						direction: isPopState ? 'back' : pushHistory ? 'forward' : 'replace',
+						source: 'react-router',
+						targetOwner: 'browser-router',
+						document: fetchedPage.doc,
+						html: fetchedPage.html,
+						isStaleSourceNavigation: isStale,
+					});
+
+					if (!handled) {
+						window.location.assign(fetchedPage.finalPath);
+					}
 				}
-			} else {
-				if (options.debug) {
-					console.error('[EcoRouter] Falling back to full page navigation:', url);
+				if (!isStale()) {
+					setIsNavigating(false);
+				}
+			} finally {
+				const shouldReplayQueuedNavigation = activeNavigationRef.current?.id === navigationId;
+				const queuedNavigationHref = shouldReplayQueuedNavigation ? queuedNavigationHrefRef.current : null;
+				navigation.complete();
+				if (activeNavigationRef.current?.id === navigationId) {
+					activeNavigationRef.current = null;
+				}
+
+				if (
+					queuedNavigationHref &&
+					queuedNavigationHref !== window.location.pathname + window.location.search
+				) {
+					queuedNavigationHrefRef.current = null;
+
+					if (runtimeActiveRef.current) {
+						void navigate(queuedNavigationHref, { pushHistory: true });
+					} else {
+						// React may finish after control has already moved to another runtime.
+						// In that case replay the queued click through the shared coordinator
+						// so the newest navigation still lands on its intended owner.
+						void navigationRuntime
+							.requestNavigation({
+								href: queuedNavigationHref,
+								direction: 'forward',
+								source: 'react-router',
+							})
+							.then((handled) => {
+								if (!handled) {
+									window.location.assign(queuedNavigationHref);
+								}
+							});
+					}
 				}
-				window.location.href = url;
 			}
-			setIsNavigating(false);
 		},
-		[options.viewTransitions, options.debug],
+		[options.viewTransitions],
 	);
 
 	useEffect(() => {
+		const getLinkFromEvent = (event: MouseEvent | PointerEvent) =>
+			getAnchorFromNavigationEvent(event, options.linkSelector);
+
+		const getRecoveredPointerHref = () => {
+			const href = recoverPendingNavigationHref(
+				pendingPointerNavigationRef.current,
+				!!activeNavigationRef.current || isNavigatingRef.current,
+				performance.now(),
+			);
+
+			if (!href) {
+				pendingPointerNavigationRef.current = null;
+			}
+
+			return href;
+		};
+
+		const getRecoveredHoverHref = () => {
+			const href = recoverPendingNavigationHref(
+				pendingHoverNavigationRef.current,
+				!!activeNavigationRef.current || isNavigatingRef.current,
+				performance.now(),
+			);
+
+			if (!href) {
+				pendingHoverNavigationRef.current = null;
+			}
+
+			return href;
+		};
+
+		const handleHoverIntent = (event: MouseEvent | PointerEvent) => {
+			if (!runtimeActiveRef.current) {
+				return;
+			}
+
+			const link = getLinkFromEvent(event);
+			if (!link) {
+				return;
+			}
+
+			const decision = getInterceptDecision(event, link, options);
+			if (!decision.shouldIntercept) {
+				return;
+			}
+
+			pendingHoverNavigationRef.current = {
+				href: link.getAttribute('href')!,
+				timestamp: performance.now(),
+			};
+			queuedNavigationHrefRef.current = link.getAttribute('href')!;
+		};
+
+		const handlePointerDown = (event: PointerEvent) => {
+			if (!runtimeActiveRef.current) {
+				pendingPointerNavigationRef.current = null;
+				return;
+			}
+
+			const link = getLinkFromEvent(event);
+			if (!link) {
+				pendingPointerNavigationRef.current = null;
+				return;
+			}
+
+			const decision = getInterceptDecision(event as unknown as MouseEvent, link, options);
+			pendingPointerNavigationRef.current = decision.shouldIntercept
+				? {
+						href: link.getAttribute('href')!,
+						timestamp: performance.now(),
+					}
+				: null;
+
+			if (decision.shouldIntercept && (activeNavigationRef.current || isNavigatingRef.current)) {
+				queuedNavigationHrefRef.current = link.getAttribute('href')!;
+			}
+		};
+
 		const handleClick = (event: MouseEvent) => {
-			const link = (event.target as Element).closest(options.linkSelector) as HTMLAnchorElement | null;
-			if (!link) return;
+			if (!runtimeActiveRef.current) {
+				pendingPointerNavigationRef.current = null;
+				pendingHoverNavigationRef.current = null;
+				return;
+			}
+
+			const link = getLinkFromEvent(event);
+			if (!link) {
+				const recoveredHref = getRecoveredPointerHref() ?? getRecoveredHoverHref();
+				pendingPointerNavigationRef.current = null;
+				pendingHoverNavigationRef.current = null;
+				if (!recoveredHref) {
+					return;
+				}
+
+				event.preventDefault();
+				queuedNavigationHrefRef.current = null;
+				const recoveredUrl = new URL(recoveredHref, window.location.origin);
+				navigate(recoveredUrl.pathname + recoveredUrl.search, { pushHistory: true });
+				return;
+			}
 			if (!shouldInterceptClick(event, link, options)) {
 				if (options.debug) {
 					const decision = getInterceptDecision(event, link, options);
@@ -306,10 +610,15 @@ export const EcoRouter: FC<EcoRouterProps> = ({ page, pageProps, options: userOp
 						console.debug('[EcoRouter] Not intercepting link click:', decision.reason, link.href);
 					}
 				}
+				pendingPointerNavigationRef.current = null;
+				pendingHoverNavigationRef.current = null;
 				return;
 			}
 
+			pendingPointerNavigationRef.current = null;
+			pendingHoverNavigationRef.current = null;
 			event.preventDefault();
+			queuedNavigationHrefRef.current = null;
 			const href = link.getAttribute('href')!;
 			const url = new URL(href, window.location.origin);
 
@@ -317,24 +626,37 @@ export const EcoRouter: FC<EcoRouterProps> = ({ page, pageProps, options: userOp
 				console.debug('[EcoRouter] Intercepting navigation:', url.pathname + url.search);
 			}
 
-			window.history.pushState(null, '', url.href);
-			navigate(url.pathname + url.search);
+			navigate(url.pathname + url.search, { pushHistory: true });
 		};
 
 		const handlePopState = () => {
-			navigate(window.location.pathname + window.location.search, true);
+			if (!runtimeActiveRef.current) {
+				return;
+			}
+
+			navigate(window.location.pathname + window.location.search, { isPopState: true });
 		};
 
-		document.addEventListener('click', handleClick);
+		document.addEventListener('mouseover', handleHoverIntent, true);
+		document.addEventListener('pointerover', handleHoverIntent, true);
+		document.addEventListener('mousemove', handleHoverIntent, true);
+		document.addEventListener('pointermove', handleHoverIntent, true);
+		document.addEventListener('pointerdown', handlePointerDown, true);
+		document.addEventListener('click', handleClick, true);
 		window.addEventListener('popstate', handlePopState);
 
 		return () => {
-			document.removeEventListener('click', handleClick);
+			document.removeEventListener('mouseover', handleHoverIntent, true);
+			document.removeEventListener('pointerover', handleHoverIntent, true);
+			document.removeEventListener('mousemove', handleHoverIntent, true);
+			document.removeEventListener('pointermove', handleHoverIntent, true);
+			document.removeEventListener('pointerdown', handlePointerDown, true);
+			document.removeEventListener('click', handleClick, true);
 			window.removeEventListener('popstate', handlePopState);
 		};
-	}, [navigate, options]);
+	}, [navigate, options, runtimeActiveRef]);
 
-	useHmrReload(navigate);
+	useNavigationCoordinator(navigate, activeNavigationRef, isNavigatingRef, runtimeActiveRef);
 
 	return createElement(
 		RouterContext.Provider,